* doc/autoconf.texi (autoheader Invocation): Mention that the
[autoconf/tsuna.git] / doc / autoconf.texi
blob4da7c3f96e3b0fe109fb0d1e73553a67fb5625a7
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 C and C++::          C and C++ portability pitfalls
266 * Manual Configuration::        Selecting features that can't be guessed
267 * Site Configuration::          Local defaults for @command{configure}
268 * Running configure Scripts::   How to use the Autoconf output
269 * config.status Invocation::    Recreating a configuration
270 * Obsolete Constructs::         Kept for backward compatibility
271 * Using Autotest::              Creating portable test suites
272 * FAQ::                         Frequent Autoconf Questions, with answers
273 * History::                     History of Autoconf
274 * Copying This Manual::         How to make copies of this manual
275 * Indices::                     Indices of symbols, concepts, etc.
277 @detailmenu
278  --- The Detailed Node Listing ---
280 The @acronym{GNU} Build System
282 * Automake::                    Escaping Makefile hell
283 * Gnulib::                      The @acronym{GNU} portability library
284 * Libtool::                     Building libraries portably
285 * Pointers::                    More info on the @acronym{GNU} build system
287 Making @command{configure} Scripts
289 * Writing configure.ac::        What to put in an Autoconf input file
290 * autoscan Invocation::         Semi-automatic @file{configure.ac} writing
291 * ifnames Invocation::          Listing the conditionals in source code
292 * autoconf Invocation::         How to create configuration scripts
293 * autoreconf Invocation::       Remaking multiple @command{configure} scripts
295 Writing @file{configure.ac}
297 * Shell Script Compiler::       Autoconf as solution of a problem
298 * Autoconf Language::           Programming in Autoconf
299 * configure.ac Layout::         Standard organization of @file{configure.ac}
301 Initialization and Output Files
303 * Initializing configure::      Option processing etc.
304 * Notices::                     Copyright, version numbers in @command{configure}
305 * Input::                       Where Autoconf should find files
306 * Output::                      Outputting results from the configuration
307 * Configuration Actions::       Preparing the output based on results
308 * Configuration Files::         Creating output files
309 * Makefile Substitutions::      Using output variables in @file{Makefile}s
310 * Configuration Headers::       Creating a configuration header file
311 * Configuration Commands::      Running arbitrary instantiation commands
312 * Configuration Links::         Links depending on the configuration
313 * Subdirectories::              Configuring independent packages together
314 * Default Prefix::              Changing the default installation prefix
316 Substitutions in Makefiles
318 * Preset Output Variables::     Output variables that are always set
319 * Installation Directory Variables::  Other preset output variables
320 * Build Directories::           Supporting multiple concurrent compiles
321 * Automatic Remaking::          Makefile rules for configuring
323 Configuration Header Files
325 * Header Templates::            Input for the configuration headers
326 * autoheader Invocation::       How to create configuration templates
327 * Autoheader Macros::           How to specify CPP templates
329 Existing Tests
331 * Common Behavior::             Macros' standard schemes
332 * Alternative Programs::        Selecting between alternative programs
333 * Files::                       Checking for the existence of files
334 * Libraries::                   Library archives that might be missing
335 * Library Functions::           C library functions that might be missing
336 * Header Files::                Header files that might be missing
337 * Declarations::                Declarations that may be missing
338 * Structures::                  Structures or members that might be missing
339 * Types::                       Types that might be missing
340 * Compilers and Preprocessors::  Checking for compiling programs
341 * System Services::             Operating system services
342 * Posix Variants::              Special kludges for specific Posix variants
343 * Erlang Libraries::            Checking for the existence of Erlang libraries
345 Common Behavior
347 * Standard Symbols::            Symbols defined by the macros
348 * Default Includes::            Includes used by the generic macros
350 Alternative Programs
352 * Particular Programs::         Special handling to find certain programs
353 * Generic Programs::            How to find other programs
355 Library Functions
357 * Function Portability::        Pitfalls with usual functions
358 * Particular Functions::        Special handling to find certain functions
359 * Generic Functions::           How to find other functions
361 Header Files
363 * Header Portability::          Collected knowledge on common headers
364 * Particular Headers::          Special handling to find certain headers
365 * Generic Headers::             How to find other headers
367 Declarations
369 * Particular Declarations::     Macros to check for certain declarations
370 * Generic Declarations::        How to find other declarations
372 Structures
374 * Particular Structures::       Macros to check for certain structure members
375 * Generic Structures::          How to find other structure members
377 Types
379 * Particular Types::            Special handling to find certain types
380 * Generic Types::               How to find other types
382 Compilers and Preprocessors
384 * Specific Compiler Characteristics::  Some portability issues
385 * Generic Compiler Characteristics::  Language independent tests and features
386 * C Compiler::                  Checking its characteristics
387 * C++ Compiler::                Likewise
388 * Objective C Compiler::        Likewise
389 * Erlang Compiler and Interpreter::  Likewise
390 * Fortran Compiler::            Likewise
392 Writing Tests
394 * Language Choice::             Selecting which language to use for testing
395 * Writing Test Programs::       Forging source files for compilers
396 * Running the Preprocessor::    Detecting preprocessor symbols
397 * Running the Compiler::        Detecting language or header features
398 * Running the Linker::          Detecting library features
399 * Runtime::                     Testing for runtime features
400 * Systemology::                 A zoology of operating systems
401 * Multiple Cases::              Tests for several possible values
403 Writing Test Programs
405 * Guidelines::                  General rules for writing test programs
406 * Test Functions::              Avoiding pitfalls in test programs
407 * Generating Sources::          Source program boilerplate
409 Results of Tests
411 * Defining Symbols::            Defining C preprocessor symbols
412 * Setting Output Variables::    Replacing variables in output files
413 * Special Chars in Variables::  Characters to beware of in variables
414 * Caching Results::             Speeding up subsequent @command{configure} runs
415 * Printing Messages::           Notifying @command{configure} users
417 Caching Results
419 * Cache Variable Names::        Shell variables used in caches
420 * Cache Files::                 Files @command{configure} uses for caching
421 * Cache Checkpointing::         Loading and saving the cache file
423 Programming in M4
425 * M4 Quotation::                Protecting macros from unwanted expansion
426 * Using autom4te::              The Autoconf executables backbone
427 * Programming in M4sugar::      Convenient pure M4 macros
428 * Programming in M4sh::         Common shell Constructs
429 * File Descriptor Macros::      File descriptor macros for input and output
431 M4 Quotation
433 * Active Characters::           Characters that change the behavior of M4
434 * One Macro Call::              Quotation and one macro call
435 * Quotation and Nested Macros::  Macros calling macros
436 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
437 * Quadrigraphs::                Another way to escape special characters
438 * Quotation Rule Of Thumb::     One parenthesis, one quote
440 Using @command{autom4te}
442 * autom4te Invocation::         A @acronym{GNU} M4 wrapper
443 * Customizing autom4te::        Customizing the Autoconf package
445 Programming in M4sugar
447 * Redefined M4 Macros::         M4 builtins changed in M4sugar
448 * Looping constructs::          Iteration in M4
449 * Evaluation Macros::           More quotation and evaluation control
450 * Text processing Macros::      String manipulation in M4
451 * Forbidden Patterns::          Catching unexpanded macros
453 Writing Autoconf Macros
455 * Macro Definitions::           Basic format of an Autoconf macro
456 * Macro Names::                 What to call your new macros
457 * Reporting Messages::          Notifying @command{autoconf} users
458 * Dependencies Between Macros::  What to do when macros depend on other macros
459 * Obsoleting Macros::           Warning about old ways of doing things
460 * Coding Style::                Writing Autoconf macros @`a la Autoconf
462 Dependencies Between Macros
464 * Prerequisite Macros::         Ensuring required information
465 * Suggested Ordering::          Warning about possible ordering problems
466 * One-Shot Macros::             Ensuring a macro is called only once
468 Portable Shell Programming
470 * Shellology::                  A zoology of shells
471 * Here-Documents::              Quirks and tricks
472 * File Descriptors::            FDs and redirections
473 * File System Conventions::     File names
474 * Shell Substitutions::         Variable and command expansions
475 * Assignments::                 Varying side effects of assignments
476 * Parentheses::                 Parentheses in shell scripts
477 * Slashes::                     Slashes in shell scripts
478 * Special Shell Variables::     Variables you should not change
479 * Limitations of Builtins::     Portable use of not so portable /bin/sh
480 * Limitations of Usual Tools::  Portable use of portable tools
481 * Limitations of Make::         Portable Makefiles
483 Portable C and C++ Programming
485 * Varieties of Unportability::  How to make your programs unportable
486 * Integer Overflow::            When integers get too large
487 * Null Pointers::               Properties of null pointers
488 * Buffer Overruns::             Subscript errors and the like
489 * Floating Point Portability::  Portable floating-point arithmetic
490 * Exiting Portably::            Exiting and the exit status
492 Manual Configuration
494 * Specifying Names::            Specifying the system type
495 * Canonicalizing::              Getting the canonical system type
496 * Using System Type::           What to do with the system type
498 Site Configuration
500 * Help Formatting::             Customizing @samp{configure --help}
501 * External Software::           Working with other optional software
502 * Package Options::             Selecting optional features
503 * Pretty Help Strings::         Formatting help string
504 * Site Details::                Configuring site details
505 * Transforming Names::          Changing program names when installing
506 * Site Defaults::               Giving @command{configure} local defaults
508 Transforming Program Names When Installing
510 * Transformation Options::      @command{configure} options to transform names
511 * Transformation Examples::     Sample uses of transforming names
512 * Transformation Rules::        @file{Makefile} uses of transforming names
514 Running @command{configure} Scripts
516 * Basic Installation::          Instructions for typical cases
517 * Compilers and Options::       Selecting compilers and optimization
518 * Multiple Architectures::      Compiling for multiple architectures at once
519 * Installation Names::          Installing in different directories
520 * Optional Features::           Selecting optional features
521 * System Type::                 Specifying the system type
522 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
523 * Defining Variables::          Specifying the compiler etc.
524 * configure Invocation::        Changing how @command{configure} runs
526 Obsolete Constructs
528 * Obsolete config.status Use::  Different calling convention
529 * acconfig.h::                  Additional entries in @file{config.h.in}
530 * autoupdate Invocation::       Automatic update of @file{configure.ac}
531 * Obsolete Macros::             Backward compatibility macros
532 * Autoconf 1::                  Tips for upgrading your files
533 * Autoconf 2.13::               Some fresher tips
535 Upgrading From Version 1
537 * Changed File Names::          Files you might rename
538 * Changed Makefiles::           New things to put in @file{Makefile.in}
539 * Changed Macros::              Macro calls you might replace
540 * Changed Results::             Changes in how to check test results
541 * Changed Macro Writing::       Better ways to write your own macros
543 Upgrading From Version 2.13
545 * Changed Quotation::           Broken code which used to work
546 * New Macros::                  Interaction with foreign macros
547 * Hosts and Cross-Compilation::  Bugward compatibility kludges
548 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
549 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
551 Generating Test Suites with Autotest
553 * Using an Autotest Test Suite::  Autotest and the user
554 * Writing testsuite.at::        Autotest macros
555 * testsuite Invocation::        Running @command{testsuite} scripts
556 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
558 Using an Autotest Test Suite
560 * testsuite Scripts::           The concepts of Autotest
561 * Autotest Logs::               Their contents
563 Frequent Autoconf Questions, with answers
565 * Distributing::                Distributing @command{configure} scripts
566 * Why GNU m4::                  Why not use the standard M4?
567 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
568 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
569 * Defining Directories::        Passing @code{datadir} to program
570 * autom4te.cache::              What is it?  Can I remove it?
571 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
573 History of Autoconf
575 * Genesis::                     Prehistory and naming of @command{configure}
576 * Exodus::                      The plagues of M4 and Perl
577 * Leviticus::                   The priestly code of portability arrives
578 * Numbers::                     Growth and contributors
579 * Deuteronomy::                 Approaching the promises of easy configuration
581 Copying This Manual
583 * GNU Free Documentation License::  License for copying this manual
585 Indices
587 * Environment Variable Index::  Index of environment variables used
588 * Output Variable Index::       Index of variables set in output files
589 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
590 * Autoconf Macro Index::        Index of Autoconf macros
591 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
592 * Autotest Macro Index::        Index of Autotest macros
593 * Program & Function Index::    Index of those with portability problems
594 * Concept Index::               General index
596 @end detailmenu
597 @end menu
599 @c ============================================================= Introduction.
601 @node Introduction
602 @chapter Introduction
603 @cindex Introduction
605 @flushright
606 A physicist, an engineer, and a computer scientist were discussing the
607 nature of God.  ``Surely a Physicist,'' said the physicist, ``because
608 early in the Creation, God made Light; and you know, Maxwell's
609 equations, the dual nature of electromagnetic waves, the relativistic
610 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
611 before making Light, God split the Chaos into Land and Water; it takes a
612 hell of an engineer to handle that big amount of mud, and orderly
613 separation of solids from liquids@dots{}'' The computer scientist
614 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
616 ---Anonymous
617 @end flushright
618 @c (via Franc,ois Pinard)
620 Autoconf is a tool for producing shell scripts that automatically
621 configure software source code packages to adapt to many kinds of
622 Posix-like systems.  The configuration scripts produced by Autoconf
623 are independent of Autoconf when they are run, so their users do not
624 need to have Autoconf.
626 The configuration scripts produced by Autoconf require no manual user
627 intervention when run; they do not normally even need an argument
628 specifying the system type.  Instead, they individually test for the
629 presence of each feature that the software package they are for might need.
630 (Before each check, they print a one-line message stating what they are
631 checking for, so the user doesn't get too bored while waiting for the
632 script to finish.)  As a result, they deal well with systems that are
633 hybrids or customized from the more common Posix variants.  There is
634 no need to maintain files that list the features supported by each
635 release of each variant of Posix.
637 For each software package that Autoconf is used with, it creates a
638 configuration script from a template file that lists the system features
639 that the package needs or can use.  After the shell code to recognize
640 and respond to a system feature has been written, Autoconf allows it to
641 be shared by many software packages that can use (or need) that feature.
642 If it later turns out that the shell code needs adjustment for some
643 reason, it needs to be changed in only one place; all of the
644 configuration scripts can be regenerated automatically to take advantage
645 of the updated code.
647 The Metaconfig package is similar in purpose to Autoconf, but the
648 scripts it produces require manual user intervention, which is quite
649 inconvenient when configuring large source trees.  Unlike Metaconfig
650 scripts, Autoconf scripts can support cross-compiling, if some care is
651 taken in writing them.
653 Autoconf does not solve all problems related to making portable
654 software packages---for a more complete solution, it should be used in
655 concert with other @acronym{GNU} build tools like Automake and
656 Libtool.  These other tools take on jobs like the creation of a
657 portable, recursive @file{Makefile} with all of the standard targets,
658 linking of shared libraries, and so on.  @xref{The GNU Build System},
659 for more information.
661 Autoconf imposes some restrictions on the names of macros used with
662 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
664 Autoconf requires @acronym{GNU} M4 in order to generate the scripts.  It uses
665 features that some versions of M4, including @acronym{GNU} M4 1.3,
666 do not have.  You should use version 1.4.3 or later of @acronym{GNU} M4.
668 @xref{Autoconf 1}, for information about upgrading from version 1.
669 @xref{History}, for the story of Autoconf's development.  @xref{FAQ},
670 for answers to some common questions about Autoconf.
672 See the @uref{http://www.gnu.org/software/autoconf/,
673 Autoconf web page} for up-to-date information, details on the mailing
674 lists, pointers to a list of known bugs, etc.
676 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
677 list}.  Past suggestions are
678 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
680 Mail bug reports to @email{bug-autoconf@@gnu.org, the
681 Autoconf Bugs mailing list}.  Past bug reports are
682 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
684 If possible, first check that your bug is
685 not already solved in current development versions, and that it has not
686 been reported yet.  Be sure to include all the needed information and a
687 short @file{configure.ac} that demonstrates the problem.
689 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
690 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
691 Summary} for details.  Patches relative to the
692 current @acronym{CVS} version can be sent for review to the
693 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
694 Past patches are
695 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
697 Because of its mission, the Autoconf package itself
698 includes only a set of often-used
699 macros that have already demonstrated their usefulness.  Nevertheless,
700 if you wish to share your macros, or find existing ones, see the
701 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
702 Archive}, which is kindly run by @email{simons@@cryp.to,
703 Peter Simons}.
706 @c ================================================= The GNU Build System
708 @node The GNU Build System
709 @chapter The @acronym{GNU} Build System
710 @cindex GNU build system
712 Autoconf solves an important problem---reliable discovery of
713 system-specific build and runtime information---but this is only one
714 piece of the puzzle for the development of portable software.  To this
715 end, the @acronym{GNU} project has developed a suite of integrated
716 utilities to finish the job Autoconf started: the @acronym{GNU} build
717 system, whose most important components are Autoconf, Automake, and
718 Libtool.  In this chapter, we introduce you to those tools, point you
719 to sources of more information, and try to convince you to use the
720 entire @acronym{GNU} build system for your software.
722 @menu
723 * Automake::                    Escaping Makefile hell
724 * Gnulib::                      The @acronym{GNU} portability library
725 * Libtool::                     Building libraries portably
726 * Pointers::                    More info on the @acronym{GNU} build system
727 @end menu
729 @node Automake
730 @section Automake
732 The ubiquity of @command{make} means that a @file{Makefile} is almost the
733 only viable way to distribute automatic build rules for software, but
734 one quickly runs into @command{make}'s numerous limitations.  Its lack of
735 support for automatic dependency tracking, recursive builds in
736 subdirectories, reliable timestamps (e.g., for network file systems), and
737 so on, mean that developers must painfully (and often incorrectly)
738 reinvent the wheel for each project.  Portability is non-trivial, thanks
739 to the quirks of @command{make} on many systems.  On top of all this is the
740 manual labor required to implement the many standard targets that users
741 have come to expect (@code{make install}, @code{make distclean},
742 @code{make uninstall}, etc.).  Since you are, of course, using Autoconf,
743 you also have to insert repetitive code in your @code{Makefile.in} to
744 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
745 provided by @command{configure}.  Into this mess steps @dfn{Automake}.
746 @cindex Automake
748 Automake allows you to specify your build needs in a @code{Makefile.am}
749 file with a vastly simpler and more powerful syntax than that of a plain
750 @code{Makefile}, and then generates a portable @code{Makefile.in} for
751 use with Autoconf.  For example, the @code{Makefile.am} to build and
752 install a simple ``Hello world'' program might look like:
754 @example
755 bin_PROGRAMS = hello
756 hello_SOURCES = hello.c
757 @end example
759 @noindent
760 The resulting @code{Makefile.in} (~400 lines) automatically supports all
761 the standard targets, the substitutions provided by Autoconf, automatic
762 dependency tracking, @code{VPATH} building, and so on.  @command{make} will
763 build the @code{hello} program, and @code{make install} will install it
764 in @file{/usr/local/bin} (or whatever prefix was given to
765 @command{configure}, if not @file{/usr/local}).
767 The benefits of Automake increase for larger packages (especially ones
768 with subdirectories), but even for small programs the added convenience
769 and portability can be substantial.  And that's not all@enddots{}
771 @node Gnulib
772 @section Gnulib
774 @acronym{GNU} software has a well-deserved reputation for running on
775 many different types of systems.  While our primary goal is to write
776 software for the @acronym{GNU} system, many users and developers have
777 been introduced to us through the systems that they were already using.
779 @cindex Gnulib
780 Gnulib is a central location for common @acronym{GNU} code, intended to
781 be shared among free software packages.  Its components are typically
782 shared at the source level, rather than being a library that gets built,
783 installed, and linked against.  The idea is to copy files from Gnulib
784 into your own source tree.  There is no distribution tarball; developers
785 should just grab source modules from the repository.  The source files
786 are available online, under various licenses, mostly @acronym{GNU}
787 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
789 Gnulib modules typically contain C source code along with Autoconf
790 macros used to configure the source code.  For example, the Gnulib
791 @code{stdbool} module implements a @file{stdbool.h} header that nearly
792 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
793 This module contains a source file for the replacement header, along
794 with an Autoconf macro that arranges to use the replacement header on
795 old-fashioned systems.
797 @node Libtool
798 @section Libtool
800 Very often, one wants to build not only programs, but libraries, so that
801 other programs can benefit from the fruits of your labor.  Ideally, one
802 would like to produce @emph{shared} (dynamically linked) libraries,
803 which can be used by multiple programs without duplication on disk or in
804 memory and can be updated independently of the linked programs.
805 Producing shared libraries portably, however, is the stuff of
806 nightmares---each system has its own incompatible tools, compiler flags,
807 and magic incantations.  Fortunately, @acronym{GNU} provides a solution:
808 @dfn{Libtool}.
809 @cindex Libtool
811 Libtool handles all the requirements of building shared libraries for
812 you, and at this time seems to be the @emph{only} way to do so with any
813 portability.  It also handles many other headaches, such as: the
814 interaction of @code{Makefile} rules with the variable suffixes of
815 shared libraries, linking reliably with shared libraries before they are
816 installed by the superuser, and supplying a consistent versioning system
817 (so that different versions of a library can be installed or upgraded
818 without breaking binary compatibility).  Although Libtool, like
819 Autoconf, can be used without Automake, it is most simply utilized in
820 conjunction with Automake---there, Libtool is used automatically
821 whenever shared libraries are needed, and you need not know its syntax.
823 @node Pointers
824 @section Pointers
826 Developers who are used to the simplicity of @command{make} for small
827 projects on a single system might be daunted at the prospect of
828 learning to use Automake and Autoconf.  As your software is
829 distributed to more and more users, however, you will otherwise
830 quickly find yourself putting lots of effort into reinventing the
831 services that the @acronym{GNU} build tools provide, and making the
832 same mistakes that they once made and overcame.  (Besides, since
833 you're already learning Autoconf, Automake will be a piece of cake.)
835 There are a number of places that you can go to for more information on
836 the @acronym{GNU} build tools.
838 @itemize @minus
840 @item Web
842 The home pages for
843 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
844 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
845 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
846 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
848 @item Automake Manual
850 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
851 information on Automake.
853 @item Books
855 The book @cite{@acronym{GNU} Autoconf, Automake and
856 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
857 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor.  SAMS (originally
858 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
859 build environment.  You can also find
860 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
862 @end itemize
864 @c ================================================= Making configure Scripts.
866 @node Making configure Scripts
867 @chapter Making @command{configure} Scripts
868 @cindex @file{aclocal.m4}
869 @cindex @command{configure}
871 The configuration scripts that Autoconf produces are by convention
872 called @command{configure}.  When run, @command{configure} creates several
873 files, replacing configuration parameters in them with appropriate
874 values.  The files that @command{configure} creates are:
876 @itemize @minus
877 @item
878 one or more @file{Makefile} files, usually one in each subdirectory of the
879 package (@pxref{Makefile Substitutions});
881 @item
882 optionally, a C header file, the name of which is configurable,
883 containing @code{#define} directives (@pxref{Configuration Headers});
885 @item
886 a shell script called @file{config.status} that, when run, will recreate
887 the files listed above (@pxref{config.status Invocation});
889 @item
890 an optional shell script normally called @file{config.cache}
891 (created when using @samp{configure --config-cache}) that
892 saves the results of running many of the tests (@pxref{Cache Files});
894 @item
895 a file called @file{config.log} containing any messages produced by
896 compilers, to help debugging if @command{configure} makes a mistake.
897 @end itemize
899 @cindex @file{configure.in}
900 @cindex @file{configure.ac}
901 To create a @command{configure} script with Autoconf, you need to write an
902 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
903 @command{autoconf} on it.  If you write your own feature tests to
904 supplement those that come with Autoconf, you might also write files
905 called @file{aclocal.m4} and @file{acsite.m4}.  If you use a C header
906 file to contain @code{#define} directives, you might also run
907 @command{autoheader}, and you will distribute the generated file
908 @file{config.h.in} with the package.
910 Here is a diagram showing how the files that can be used in
911 configuration are produced.  Programs that are executed are suffixed by
912 @samp{*}.  Optional files are enclosed in square brackets (@samp{[]}).
913 @command{autoconf} and @command{autoheader} also read the installed Autoconf
914 macro files (by reading @file{autoconf.m4}).
916 @noindent
917 Files used in preparing a software package for distribution:
918 @example
919 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
921 @group
922 configure.ac --.
923                |   .------> autoconf* -----> configure
924 [aclocal.m4] --+---+
925                |   `-----> [autoheader*] --> [config.h.in]
926 [acsite.m4] ---'
927 @end group
929 Makefile.in -------------------------------> Makefile.in
930 @end example
932 @noindent
933 Files used in configuring a software package:
934 @example
935 @group
936                        .-------------> [config.cache]
937 configure* ------------+-------------> config.log
938                        |
939 [config.h.in] -.       v            .-> [config.h] -.
940                +--> config.status* -+               +--> make*
941 Makefile.in ---'                    `-> Makefile ---'
942 @end group
943 @end example
945 @menu
946 * Writing configure.ac::        What to put in an Autoconf input file
947 * autoscan Invocation::         Semi-automatic @file{configure.ac} writing
948 * ifnames Invocation::          Listing the conditionals in source code
949 * autoconf Invocation::         How to create configuration scripts
950 * autoreconf Invocation::       Remaking multiple @command{configure} scripts
951 @end menu
953 @node Writing configure.ac
954 @section Writing @file{configure.ac}
956 To produce a @command{configure} script for a software package, create a
957 file called @file{configure.ac} that contains invocations of the
958 Autoconf macros that test the system features your package needs or can
959 use.  Autoconf macros already exist to check for many features; see
960 @ref{Existing Tests}, for their descriptions.  For most other features,
961 you can use Autoconf template macros to produce custom checks; see
962 @ref{Writing Tests}, for information about them.  For especially tricky
963 or specialized features, @file{configure.ac} might need to contain some
964 hand-crafted shell commands; see @ref{Portable Shell}.  The
965 @command{autoscan} program can give you a good start in writing
966 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
968 Previous versions of Autoconf promoted the name @file{configure.in},
969 which is somewhat ambiguous (the tool needed to process this file is not
970 described by its extension), and introduces a slight confusion with
971 @file{config.h.in} and so on (for which @samp{.in} means ``to be
972 processed by @command{configure}'').  Using @file{configure.ac} is now
973 preferred.
975 @menu
976 * Shell Script Compiler::       Autoconf as solution of a problem
977 * Autoconf Language::           Programming in Autoconf
978 * configure.ac Layout::         Standard organization of @file{configure.ac}
979 @end menu
981 @node Shell Script Compiler
982 @subsection A Shell Script Compiler
984 Just as for any other computer language, in order to properly program
985 @file{configure.ac} in Autoconf you must understand @emph{what} problem
986 the language tries to address and @emph{how} it does so.
988 The problem Autoconf addresses is that the world is a mess.  After all,
989 you are using Autoconf in order to have your package compile easily on
990 all sorts of different systems, some of them being extremely hostile.
991 Autoconf itself bears the price for these differences: @command{configure}
992 must run on all those systems, and thus @command{configure} must limit itself
993 to their lowest common denominator of features.
995 Naturally, you might then think of shell scripts; who needs
996 @command{autoconf}?  A set of properly written shell functions is enough to
997 make it easy to write @command{configure} scripts by hand.  Sigh!
998 Unfortunately, shell functions do not belong to the least common
999 denominator; therefore, where you would like to define a function and
1000 use it ten times, you would instead need to copy its body ten times.
1002 So, what is really needed is some kind of compiler, @command{autoconf},
1003 that takes an Autoconf program, @file{configure.ac}, and transforms it
1004 into a portable shell script, @command{configure}.
1006 How does @command{autoconf} perform this task?
1008 There are two obvious possibilities: creating a brand new language or
1009 extending an existing one.  The former option is very attractive: all
1010 sorts of optimizations could easily be implemented in the compiler and
1011 many rigorous checks could be performed on the Autoconf program
1012 (e.g., rejecting any non-portable construct).  Alternatively, you can
1013 extend an existing language, such as the @code{sh} (Bourne shell)
1014 language.
1016 Autoconf does the latter: it is a layer on top of @code{sh}.  It was
1017 therefore most convenient to implement @command{autoconf} as a macro
1018 expander: a program that repeatedly performs @dfn{macro expansions} on
1019 text input, replacing macro calls with macro bodies and producing a pure
1020 @code{sh} script in the end.  Instead of implementing a dedicated
1021 Autoconf macro expander, it is natural to use an existing
1022 general-purpose macro language, such as M4, and implement the extensions
1023 as a set of M4 macros.
1026 @node Autoconf Language
1027 @subsection The Autoconf Language
1028 @cindex quotation
1030 The Autoconf language is very different from many other computer
1031 languages because it treats actual code the same as plain text.  Whereas
1032 in C, for instance, data and instructions have very different syntactic
1033 status, in Autoconf their status is rigorously the same.  Therefore, we
1034 need a means to distinguish literal strings from text to be expanded:
1035 quotation.
1037 When calling macros that take arguments, there must not be any white
1038 space between the macro name and the open parenthesis.  Arguments should
1039 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1040 separated by commas.  Any leading blanks or newlines in arguments are ignored,
1041 unless they are quoted.  You should always quote an argument that
1042 might contain a macro name, comma, parenthesis, or a leading blank or
1043 newline.  This rule applies recursively for every macro
1044 call, including macros called from other macros.
1046 For instance:
1048 @example
1049 AC_CHECK_HEADER([stdio.h],
1050                 [AC_DEFINE([HAVE_STDIO_H], [1],
1051                    [Define to 1 if you have <stdio.h>.])],
1052                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1053 @end example
1055 @noindent
1056 is quoted properly.  You may safely simplify its quotation to:
1058 @example
1059 AC_CHECK_HEADER([stdio.h],
1060                 [AC_DEFINE([HAVE_STDIO_H], 1,
1061                    [Define to 1 if you have <stdio.h>.])],
1062                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1063 @end example
1065 @noindent
1066 because @samp{1} cannot contain a macro call.  Here, the argument of
1067 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1068 interpreted as an argument separator.  Also, @samp{AC_CHECK_HEADER}'s
1069 second and third arguments must be quoted, since those arguments contain
1070 macro calls.  The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1071 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1072 if you unwisely defined a macro with a name like @samp{Define} or
1073 @samp{stdio} then they would need quoting.  Cautious Autoconf users
1074 would keep the quotes, but many Autoconf users find such precautions
1075 annoying, and would rewrite the example as follows:
1077 @example
1078 AC_CHECK_HEADER(stdio.h,
1079                 [AC_DEFINE(HAVE_STDIO_H, 1,
1080                    [Define to 1 if you have <stdio.h>.])],
1081                 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1082 @end example
1084 @noindent
1085 This is safe, so long as you adopt good naming conventions and do not
1086 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1087 @samp{h}.  Though it is also safe here to omit the quotes around
1088 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1089 message strings are more likely to inadvertently contain commas.
1091 The following example is wrong and dangerous, as it is underquoted:
1093 @example
1094 AC_CHECK_HEADER(stdio.h,
1095                 AC_DEFINE(HAVE_STDIO_H, 1,
1096                    Define to 1 if you have <stdio.h>.),
1097                 AC_MSG_ERROR([Sorry, can't do anything for you]))
1098 @end example
1100 In other cases, you may have to use text that also resembles a macro
1101 call.  You must quote that text even when it is not passed as a macro
1102 argument:
1104 @example
1105 echo "Hard rock was here!  --[AC_DC]"
1106 @end example
1108 @noindent
1109 which will result in
1111 @example
1112 echo "Hard rock was here!  --AC_DC"
1113 @end example
1115 @noindent
1116 When you use the same text in a macro argument, you must therefore have
1117 an extra quotation level (since one is stripped away by the macro
1118 substitution).  In general, then, it is a good idea to @emph{use double
1119 quoting for all literal string arguments}:
1121 @example
1122 AC_MSG_WARN([[AC_DC stinks  --Iron Maiden]])
1123 @end example
1125 You are now able to understand one of the constructs of Autoconf that
1126 has been continually misunderstood@dots{}  The rule of thumb is that
1127 @emph{whenever you expect macro expansion, expect quote expansion};
1128 i.e., expect one level of quotes to be lost.  For instance:
1130 @example
1131 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1132 @end example
1134 @noindent
1135 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1136 @samp{char b[10];} and will be expanded once, which results in
1137 @samp{char b10;}.  (There was an idiom common in Autoconf's past to
1138 address this issue via the M4 @code{changequote} primitive, but do not
1139 use it!)  Let's take a closer look: the author meant the first argument
1140 to be understood as a literal, and therefore it must be quoted twice:
1142 @example
1143 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1144 @end example
1146 @noindent
1147 Voil@`a, you actually produce @samp{char b[10];} this time!
1149 On the other hand, descriptions (e.g., the last parameter of
1150 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1151 are subject to line breaking, for example---and should not be double quoted.
1152 Even if these descriptions are short and are not actually broken, double
1153 quoting them yields weird results.
1155 Some macros take optional arguments, which this documentation represents
1156 as @ovar{arg} (not to be confused with the quote characters).  You may
1157 just leave them empty, or use @samp{[]} to make the emptiness of the
1158 argument explicit, or you may simply omit the trailing commas.  The
1159 three lines below are equivalent:
1161 @example
1162 AC_CHECK_HEADERS([stdio.h], [], [], [])
1163 AC_CHECK_HEADERS([stdio.h],,,)
1164 AC_CHECK_HEADERS([stdio.h])
1165 @end example
1167 It is best to put each macro call on its own line in
1168 @file{configure.ac}.  Most of the macros don't add extra newlines; they
1169 rely on the newline after the macro call to terminate the commands.
1170 This approach makes the generated @command{configure} script a little
1171 easier to read by not inserting lots of blank lines.  It is generally
1172 safe to set shell variables on the same line as a macro call, because
1173 the shell allows assignments without intervening newlines.
1175 You can include comments in @file{configure.ac} files by starting them
1176 with the @samp{#}.  For example, it is helpful to begin
1177 @file{configure.ac} files with a line like this:
1179 @example
1180 # Process this file with autoconf to produce a configure script.
1181 @end example
1183 @node configure.ac Layout
1184 @subsection Standard @file{configure.ac} Layout
1186 The order in which @file{configure.ac} calls the Autoconf macros is not
1187 important, with a few exceptions.  Every @file{configure.ac} must
1188 contain a call to @code{AC_INIT} before the checks, and a call to
1189 @code{AC_OUTPUT} at the end (@pxref{Output}).  Additionally, some macros
1190 rely on other macros having been called first, because they check
1191 previously set values of some variables to decide what to do.  These
1192 macros are noted in the individual descriptions (@pxref{Existing
1193 Tests}), and they also warn you when @command{configure} is created if they
1194 are called out of order.
1196 To encourage consistency, here is a suggested order for calling the
1197 Autoconf macros.  Generally speaking, the things near the end of this
1198 list are those that could depend on things earlier in it.  For example,
1199 library functions could be affected by types and libraries.
1201 @display
1202 @group
1203 Autoconf requirements
1204 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1205 information on the package
1206 checks for programs
1207 checks for libraries
1208 checks for header files
1209 checks for types
1210 checks for structures
1211 checks for compiler characteristics
1212 checks for library functions
1213 checks for system services
1214 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1215 @code{AC_OUTPUT}
1216 @end group
1217 @end display
1220 @node autoscan Invocation
1221 @section Using @command{autoscan} to Create @file{configure.ac}
1222 @cindex @command{autoscan}
1224 The @command{autoscan} program can help you create and/or maintain a
1225 @file{configure.ac} file for a software package.  @command{autoscan}
1226 examines source files in the directory tree rooted at a directory given
1227 as a command line argument, or the current directory if none is given.
1228 It searches the source files for common portability problems and creates
1229 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1230 for that package, and checks a possibly existing @file{configure.ac} for
1231 completeness.
1233 When using @command{autoscan} to create a @file{configure.ac}, you
1234 should manually examine @file{configure.scan} before renaming it to
1235 @file{configure.ac}; it will probably need some adjustments.
1236 Occasionally, @command{autoscan} outputs a macro in the wrong order
1237 relative to another macro, so that @command{autoconf} produces a warning;
1238 you need to move such macros manually.  Also, if you want the package to
1239 use a configuration header file, you must add a call to
1240 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}).  You might
1241 also have to change or add some @code{#if} directives to your program in
1242 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1243 information about a program that can help with that job).
1245 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1246 consider adding its suggestions.  The file @file{autoscan.log} will
1247 contain detailed information on why a macro is requested.
1249 @command{autoscan} uses several data files (installed along with Autoconf)
1250 to determine which macros to output when it finds particular symbols in
1251 a package's source files.  These data files all have the same format:
1252 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1253 output if that symbol is encountered.  Lines starting with @samp{#} are
1254 comments.
1256 @command{autoscan} accepts the following options:
1258 @table @option
1259 @item --help
1260 @itemx -h
1261 Print a summary of the command line options and exit.
1263 @item --version
1264 @itemx -V
1265 Print the version number of Autoconf and exit.
1267 @item --verbose
1268 @itemx -v
1269 Print the names of the files it examines and the potentially interesting
1270 symbols it finds in them.  This output can be voluminous.
1272 @item --include=@var{dir}
1273 @itemx -I @var{dir}
1274 Append @var{dir} to the include path.  Multiple invocations accumulate.
1276 @item --prepend-include=@var{dir}
1277 @item -B @var{dir}
1278 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1279 @end table
1281 @node ifnames Invocation
1282 @section Using @command{ifnames} to List Conditionals
1283 @cindex @command{ifnames}
1285 @command{ifnames} can help you write @file{configure.ac} for a software
1286 package.  It prints the identifiers that the package already uses in C
1287 preprocessor conditionals.  If a package has already been set up to have
1288 some portability, @command{ifnames} can thus help you figure out what its
1289 @command{configure} needs to check for.  It may help fill in some gaps in a
1290 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1291 Invocation}).
1293 @command{ifnames} scans all of the C source files named on the command line
1294 (or the standard input, if none are given) and writes to the standard
1295 output a sorted list of all the identifiers that appear in those files
1296 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1297 directives.  It prints each identifier on a line, followed by a
1298 space-separated list of the files in which that identifier occurs.
1300 @noindent
1301 @command{ifnames} accepts the following options:
1303 @table @option
1304 @item --help
1305 @itemx -h
1306 Print a summary of the command line options and exit.
1308 @item --version
1309 @itemx -V
1310 Print the version number of Autoconf and exit.
1311 @end table
1313 @node autoconf Invocation
1314 @section Using @command{autoconf} to Create @command{configure}
1315 @cindex @command{autoconf}
1317 To create @command{configure} from @file{configure.ac}, run the
1318 @command{autoconf} program with no arguments.  @command{autoconf} processes
1319 @file{configure.ac} with the M4 macro processor, using the
1320 Autoconf macros.  If you give @command{autoconf} an argument, it reads that
1321 file instead of @file{configure.ac} and writes the configuration script
1322 to the standard output instead of to @command{configure}.  If you give
1323 @command{autoconf} the argument @option{-}, it reads from the standard
1324 input instead of @file{configure.ac} and writes the configuration script
1325 to the standard output.
1327 The Autoconf macros are defined in several files.  Some of the files are
1328 distributed with Autoconf; @command{autoconf} reads them first.  Then it
1329 looks for the optional file @file{acsite.m4} in the directory that
1330 contains the distributed Autoconf macro files, and for the optional file
1331 @file{aclocal.m4} in the current directory.  Those files can contain
1332 your site's or the package's own Autoconf macro definitions
1333 (@pxref{Writing Autoconf Macros}, for more information).  If a macro is
1334 defined in more than one of the files that @command{autoconf} reads, the
1335 last definition it reads overrides the earlier ones.
1337 @command{autoconf} accepts the following options:
1339 @table @option
1340 @item --help
1341 @itemx -h
1342 Print a summary of the command line options and exit.
1344 @item --version
1345 @itemx -V
1346 Print the version number of Autoconf and exit.
1348 @item --verbose
1349 @itemx -v
1350 Report processing steps.
1352 @item --debug
1353 @itemx -d
1354 Don't remove the temporary files.
1356 @item --force
1357 @itemx -f
1358 Remake @file{configure} even if newer than its input files.
1360 @item --include=@var{dir}
1361 @itemx -I @var{dir}
1362 Append @var{dir} to the include path.  Multiple invocations accumulate.
1364 @item --prepend-include=@var{dir}
1365 @item -B @var{dir}
1366 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1368 @item --output=@var{file}
1369 @itemx -o @var{file}
1370 Save output (script or trace) to @var{file}.  The file @option{-} stands
1371 for the standard output.
1373 @item --warnings=@var{category}
1374 @itemx -W @var{category}
1375 @evindex WARNINGS
1376 Report the warnings related to @var{category} (which can actually be a
1377 comma separated list).  @xref{Reporting Messages}, macro
1378 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
1379 values include:
1381 @table @samp
1382 @item all
1383 report all the warnings
1385 @item none
1386 report none
1388 @item error
1389 treats warnings as errors
1391 @item no-@var{category}
1392 disable warnings falling into @var{category}
1393 @end table
1395 Warnings about @samp{syntax} are enabled by default, and the environment
1396 variable @env{WARNINGS}, a comma separated list of categories, is
1397 honored as well.  Passing @option{-W @var{category}} will actually behave as if
1398 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1399 you want to disable the defaults and @env{WARNINGS}, but (for example)
1400 enable the warnings about obsolete constructs, you would use @option{-W
1401 none,obsolete}.
1403 @cindex Back trace
1404 @cindex Macro invocation stack
1405 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1406 displays a back trace for errors, but not for warnings; if you want
1407 them, just pass @option{-W error}.  @xref{autom4te Invocation}, for some
1408 examples.
1410 @item --trace=@var{macro}[:@var{format}]
1411 @itemx -t @var{macro}[:@var{format}]
1412 Do not create the @command{configure} script, but list the calls to
1413 @var{macro} according to the @var{format}.  Multiple @option{--trace}
1414 arguments can be used to list several macros.  Multiple @option{--trace}
1415 arguments for a single macro are not cumulative; instead, you should
1416 just make @var{format} as long as needed.
1418 The @var{format} is a regular string, with newlines if desired, and
1419 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}; see
1420 @ref{autom4te Invocation}, for details on the @var{format}.
1422 @item --initialization
1423 @itemx -i
1424 By default, @option{--trace} does not trace the initialization of the
1425 Autoconf macros (typically the @code{AC_DEFUN} definitions).  This
1426 results in a noticeable speedup, but can be disabled by this option.
1427 @end table
1430 It is often necessary to check the content of a @file{configure.ac}
1431 file, but parsing it yourself is extremely fragile and error-prone.  It
1432 is suggested that you rely upon @option{--trace} to scan
1433 @file{configure.ac}.  For instance, to find the list of variables that
1434 are substituted, use:
1436 @example
1437 @group
1438 $ @kbd{autoconf -t AC_SUBST}
1439 configure.ac:2:AC_SUBST:ECHO_C
1440 configure.ac:2:AC_SUBST:ECHO_N
1441 configure.ac:2:AC_SUBST:ECHO_T
1442 @i{More traces deleted}
1443 @end group
1444 @end example
1446 @noindent
1447 The example below highlights the difference between @samp{$@@},
1448 @samp{$*}, and @samp{$%}.
1450 @example
1451 @group
1452 $ @kbd{cat configure.ac}
1453 AC_DEFINE(This, is, [an
1454 [example]])
1455 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1456 *: $*
1457 %: $%'
1458 @@: [This],[is],[an
1459 [example]]
1460 *: This,is,an
1461 [example]
1462 %: This:is:an [example]
1463 @end group
1464 @end example
1466 @noindent
1467 The @var{format} gives you a lot of freedom:
1469 @example
1470 @group
1471 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1472 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1473 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1474 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1475 @i{More traces deleted}
1476 @end group
1477 @end example
1479 @noindent
1480 A long @var{separator} can be used to improve the readability of complex
1481 structures, and to ease their parsing (for instance when no single
1482 character is suitable as a separator):
1484 @example
1485 @group
1486 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1487 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1488 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1489 AUTOMAKE|:::::|automake|:::::|$missing_dir
1490 @i{More traces deleted}
1491 @end group
1492 @end example
1494 @node autoreconf Invocation
1495 @section Using @command{autoreconf} to Update @command{configure} Scripts
1496 @cindex @command{autoreconf}
1498 Installing the various components of the @acronym{GNU} Build System can be
1499 tedious: running @command{autopoint} for Gettext, @command{automake} for
1500 @file{Makefile.in} etc.@: in each directory.  It may be needed either
1501 because some tools such as @command{automake} have been updated on your
1502 system, or because some of the sources such as @file{configure.ac} have
1503 been updated, or finally, simply in order to install the @acronym{GNU} Build
1504 System in a fresh tree.
1506 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1507 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1508 @command{autopoint} (when appropriate) repeatedly to update the
1509 @acronym{GNU} Build System in the specified directories and their
1510 subdirectories (@pxref{Subdirectories}).  By default, it only remakes
1511 those files that are older than their sources.
1513 If you install a new version of some tool, you can make
1514 @command{autoreconf} remake @emph{all} of the files by giving it the
1515 @option{--force} option.
1517 @xref{Automatic Remaking}, for @file{Makefile} rules to automatically
1518 remake @command{configure} scripts when their source files change.  That
1519 method handles the timestamps of configuration header templates
1520 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1521 @option{--localdir=@var{dir}}.
1523 @cindex Gettext
1524 @cindex @command{autopoint}
1525 Gettext supplies the @command{autopoint} command to add translation
1526 infrastructure to a source package.  If you use @command{autopoint},
1527 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1528 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}.  @xref{autopoint
1529 Invocation, , Invoking the @code{autopoint} Program, gettext, GNU
1530 @code{gettext} utilities}, for further details.
1532 @noindent
1533 @command{autoreconf} accepts the following options:
1535 @table @option
1536 @item --help
1537 @itemx -h
1538 Print a summary of the command line options and exit.
1540 @item --version
1541 @itemx -V
1542 Print the version number of Autoconf and exit.
1544 @item --verbose
1545 Print the name of each directory @command{autoreconf} examines and the
1546 commands it runs.  If given two or more times, pass @option{--verbose}
1547 to subordinate tools that support it.
1549 @item --debug
1550 @itemx -d
1551 Don't remove the temporary files.
1553 @item --force
1554 @itemx -f
1555 Remake even @file{configure} scripts and configuration headers that are
1556 newer than their input files (@file{configure.ac} and, if present,
1557 @file{aclocal.m4}).
1559 @item --install
1560 @itemx -i
1561 Install the missing auxiliary files in the package.  By default, files
1562 are copied; this can be changed with @option{--symlink}.
1564 If deemed appropriate, this option triggers calls to
1565 @samp{automake --add-missing},
1566 @samp{libtoolize}, @samp{autopoint}, etc.
1568 @item --no-recursive
1569 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1570 macro @code{AC_CONFIG_SUBDIRS}).
1572 @item --symlink
1573 @itemx -s
1574 When used with @option{--install}, install symbolic links to the missing
1575 auxiliary files instead of copying them.
1577 @item --make
1578 @itemx -m
1579 When the directories were configured, update the configuration by
1580 running @samp{./config.status --recheck && ./config.status}, and then
1581 run @samp{make}.
1583 @item --include=@var{dir}
1584 @itemx -I @var{dir}
1585 Append @var{dir} to the include path.  Multiple invocations accumulate.
1586 Passed on to @command{autoconf} and @command{autoheader} internally.
1588 @item --prepend-include=@var{dir}
1589 @item -B @var{dir}
1590 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
1591 Passed on to @command{autoconf} and @command{autoheader} internally.
1593 @item --warnings=@var{category}
1594 @itemx -W @var{category}
1595 @evindex WARNINGS
1596 Report the warnings related to @var{category} (which can actually be a
1597 comma separated list).
1599 @table @samp
1600 @item cross
1601 related to cross compilation issues.
1603 @item obsolete
1604 report the uses of obsolete constructs.
1606 @item portability
1607 portability issues
1609 @item syntax
1610 dubious syntactic constructs.
1612 @item all
1613 report all the warnings
1615 @item none
1616 report none
1618 @item error
1619 treats warnings as errors
1621 @item no-@var{category}
1622 disable warnings falling into @var{category}
1623 @end table
1625 Warnings about @samp{syntax} are enabled by default, and the environment
1626 variable @env{WARNINGS}, a comma separated list of categories, is
1627 honored as well.  Passing @option{-W @var{category}} will actually behave as if
1628 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}.  If
1629 you want to disable the defaults and @env{WARNINGS}, but (for example)
1630 enable the warnings about obsolete constructs, you would use @option{-W
1631 none,obsolete}.
1632 @end table
1634 If you want @command{autoreconf} to pass flags that are not listed here
1635 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your Makefile.am.
1637 @c ========================================= Initialization and Output Files.
1639 @node Setup
1640 @chapter Initialization and Output Files
1642 Autoconf-generated @command{configure} scripts need some information about
1643 how to initialize, such as how to find the package's source files and
1644 about the output files to produce.  The following sections describe the
1645 initialization and the creation of output files.
1647 @menu
1648 * Initializing configure::      Option processing etc.
1649 * Notices::                     Copyright, version numbers in @command{configure}
1650 * Input::                       Where Autoconf should find files
1651 * Output::                      Outputting results from the configuration
1652 * Configuration Actions::       Preparing the output based on results
1653 * Configuration Files::         Creating output files
1654 * Makefile Substitutions::      Using output variables in @file{Makefile}s
1655 * Configuration Headers::       Creating a configuration header file
1656 * Configuration Commands::      Running arbitrary instantiation commands
1657 * Configuration Links::         Links depending on the configuration
1658 * Subdirectories::              Configuring independent packages together
1659 * Default Prefix::              Changing the default installation prefix
1660 @end menu
1662 @node Initializing configure
1663 @section Initializing @command{configure}
1665 Every @command{configure} script must call @code{AC_INIT} before doing
1666 anything else.  The only other required macro is @code{AC_OUTPUT}
1667 (@pxref{Output}).
1669 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1670 @acindex{INIT}
1671 Process any command-line arguments and perform various initializations
1672 and verifications.
1674 Set the name of the @var{package} and its @var{version}.  These are
1675 typically used in @option{--version} support, including that of
1676 @command{configure}.  The optional argument @var{bug-report} should be
1677 the email to which users should send bug reports.  The package
1678 @var{tarname} differs from @var{package}: the latter designates the full
1679 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1680 distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
1681 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1682 other than alphanumerics and underscores are changed to @samp{-}.
1684 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1685 there should not be any shell computation, but they can be computed by
1688 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1689 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1690 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1692 @table @asis
1693 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1694 @acindex{PACKAGE_NAME}
1695 @ovindex PACKAGE_NAME
1696 @cvindex PACKAGE_NAME
1697 Exactly @var{package}.
1699 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1700 @acindex{PACKAGE_TARNAME}
1701 @ovindex PACKAGE_TARNAME
1702 @cvindex PACKAGE_TARNAME
1703 Exactly @var{tarname}.
1705 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1706 @acindex{PACKAGE_VERSION}
1707 @ovindex PACKAGE_VERSION
1708 @cvindex PACKAGE_VERSION
1709 Exactly @var{version}.
1711 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1712 @acindex{PACKAGE_STRING}
1713 @ovindex PACKAGE_STRING
1714 @cvindex PACKAGE_STRING
1715 Exactly @samp{@var{package} @var{version}}.
1717 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1718 @acindex{PACKAGE_BUGREPORT}
1719 @ovindex PACKAGE_BUGREPORT
1720 @cvindex PACKAGE_BUGREPORT
1721 Exactly @var{bug-report}.
1722 @end table
1723 @end defmac
1726 @node Notices
1727 @section Notices in @command{configure}
1728 @cindex Notices in @command{configure}
1730 The following macros manage version numbers for @command{configure}
1731 scripts.  Using them is optional.
1733 @c FIXME: AC_PREREQ should not be here
1734 @defmac AC_PREREQ (@var{version})
1735 @acindex{PREREQ}
1736 @cindex Version
1737 Ensure that a recent enough version of Autoconf is being used.  If the
1738 version of Autoconf being used to create @command{configure} is
1739 earlier than @var{version}, print an error message to the standard
1740 error output and exit with failure (exit status is 63).  For example:
1742 @example
1743 AC_PREREQ([@value{VERSION}])
1744 @end example
1746 This macro is the only macro that may be used before @code{AC_INIT}, but
1747 for consistency, you are invited not to do so.
1748 @end defmac
1750 @defmac AC_COPYRIGHT (@var{copyright-notice})
1751 @acindex{COPYRIGHT}
1752 @cindex Copyright Notice
1753 State that, in addition to the Free Software Foundation's copyright on
1754 the Autoconf macros, parts of your @command{configure} are covered by the
1755 @var{copyright-notice}.
1757 The @var{copyright-notice} will show up in both the head of
1758 @command{configure} and in @samp{configure --version}.
1759 @end defmac
1762 @defmac AC_REVISION (@var{revision-info})
1763 @acindex{REVISION}
1764 @cindex Revision
1765 Copy revision stamp @var{revision-info} into the @command{configure}
1766 script, with any dollar signs or double-quotes removed.  This macro lets
1767 you put a revision stamp from @file{configure.ac} into @command{configure}
1768 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1769 @command{configure}.  That way, you can determine easily which revision of
1770 @file{configure.ac} a particular @command{configure} corresponds to.
1772 For example, this line in @file{configure.ac}:
1774 @c The asis prevents RCS from changing the example in the manual.
1775 @example
1776 AC_REVISION([$@asis{Revision: 1.30 }$])
1777 @end example
1779 @noindent
1780 produces this in @command{configure}:
1782 @example
1783 #!/bin/sh
1784 # From configure.ac Revision: 1.30
1785 @end example
1786 @end defmac
1789 @node Input
1790 @section Finding @command{configure} Input
1793 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1794 @acindex{CONFIG_SRCDIR}
1795 @var{unique-file-in-source-dir} is some file that is in the package's
1796 source directory; @command{configure} checks for this file's existence to
1797 make sure that the directory that it is told contains the source code in
1798 fact does.  Occasionally people accidentally specify the wrong directory
1799 with @option{--srcdir}; this is a safety check.  @xref{configure
1800 Invocation}, for more information.
1801 @end defmac
1804 @c FIXME: Remove definitively once --install explained.
1806 @c Small packages may store all their macros in @code{aclocal.m4}.  As the
1807 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1808 @c to split the macros in several files.  In this case, Autoconf must be
1809 @c told which files to load, and in which order.
1811 @c @defmac AC_INCLUDE (@var{file}@dots{})
1812 @c @acindex{INCLUDE}
1813 @c @c FIXME: There is no longer shell globbing.
1814 @c Read the macro definitions that appear in the listed files.  A list of
1815 @c space-separated file names or shell globbing patterns is expected.  The
1816 @c files will be read in the order they're listed.
1818 @c Because the order of definition of macros is important (only the last
1819 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1820 @c loads @file{acsite.m4} and @file{aclocal.m4}.  Note that
1821 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1822 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1823 @c the latter case, non-macro lines from included files may end up in the
1824 @c @file{configure} script, whereas in the former case, they'd be discarded
1825 @c just like any text that appear before @code{AC_INIT}.
1826 @c @end defmac
1828 Packages that do manual configuration or use the @command{install} program
1829 might need to tell @command{configure} where to find some other shell
1830 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1831 it looks are correct for most cases.
1833 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1834 @acindex{CONFIG_AUX_DIR}
1835 Use the auxiliary build tools (e.g., @file{install-sh},
1836 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1837 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1838 These are auxiliary files used in configuration.  @var{dir} can be
1839 either absolute or relative to @file{@var{srcdir}}.  The default is
1840 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1841 @file{@var{srcdir}/../..}, whichever is the first that contains
1842 @file{install-sh}.  The other files are not checked for, so that using
1843 @code{AC_PROG_INSTALL} does not automatically require distributing the
1844 other auxiliary files.  It checks for @file{install.sh} also, but that
1845 name is obsolete because some @code{make} have a rule that creates
1846 @file{install} from it if there is no @file{Makefile}.
1848 The auxiliary directory is commonly named @file{build-aux}.
1849 If you need portability to @acronym{DOS} variants, do not name the
1850 auxiliary directory @file{aux}.  @xref{File System Conventions}.
1851 @end defmac
1853 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1854 @acindex{REQUIRE_AUX_FILE}
1855 Declares that @var{file} is expected in the directory defined above.  In
1856 Autoconf proper, this macro does nothing: its sole purpose is to be
1857 traced by third-party tools to produce a list of expected auxiliary
1858 files.  For instance it is called by macros like @code{AC_PROG_INSTALL}
1859 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1860 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1861 @end defmac
1863 Similarly, packages that use @command{aclocal} should declare where
1864 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1866 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1867 @acindex{CONFIG_MACRO_DIR}
1868 Future versions of @command{autopoint}, @command{libtoolize},
1869 @command{aclocal} and @command{autoreconf} will use directory
1870 @var{dir} as the location of additional local Autoconf macros.  Be
1871 sure to call this macro directly from @file{configure.ac} so that
1872 tools that install macros for @command{aclocal} can find the
1873 declaration before @option{--trace} can be called safely.
1874 @end defmac
1877 @node Output
1878 @section Outputting Files
1879 @cindex Outputting files
1881 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1882 calling @code{AC_OUTPUT}.  That is the macro that generates and runs
1883 @file{config.status}, which will create the @file{Makefile}s and any
1884 other files resulting from configuration.  This is the only required
1885 macro besides @code{AC_INIT} (@pxref{Input}).
1887 @defmac AC_OUTPUT
1888 @acindex{OUTPUT}
1889 @cindex Instantiation
1890 Generate @file{config.status} and launch it.  Call this macro once, at
1891 the end of @file{configure.ac}.
1893 @file{config.status} will perform all the configuration actions: all the
1894 output files (see @ref{Configuration Files}, macro
1895 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1896 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1897 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1898 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1899 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1900 are honored.
1902 The location of your @code{AC_OUTPUT} invocation is the exact point
1903 where configuration actions are taken: any code afterwards will be
1904 executed by @code{configure} once @command{config.status} was run.  If
1905 you want to bind actions to @command{config.status} itself
1906 (independently of whether @command{configure} is being run), see
1907 @ref{Configuration Commands, , Running Arbitrary Configuration
1908 Commands}.
1909 @end defmac
1911 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1912 @xref{Obsolete Macros}, for a description of the arguments that
1913 @code{AC_OUTPUT} used to support.
1916 If you run @command{make} in subdirectories, you should run it using the
1917 @code{make} variable @code{MAKE}.  Most versions of @command{make} set
1918 @code{MAKE} to the name of the @command{make} program plus any options it
1919 was given.  (But many do not include in it the values of any variables
1920 set on the command line, so those are not passed on automatically.)
1921 Some old versions of @command{make} do not set this variable.  The
1922 following macro allows you to use it even with those versions.
1924 @defmac AC_PROG_MAKE_SET
1925 @acindex{PROG_MAKE_SET}
1926 @ovindex SET_MAKE
1927 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1928 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1929 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1930 @code{$(MAKE)}, such as @samp{MAKE=make}.  Calls @code{AC_SUBST} for
1931 @code{SET_MAKE}.
1932 @end defmac
1934 If you use this macro, place a line like this in each @file{Makefile.in}
1935 that runs @code{MAKE} on other directories:
1937 @example
1938 @@SET_MAKE@@
1939 @end example
1943 @node Configuration Actions
1944 @section Performing Configuration Actions
1945 @cindex Configuration actions
1947 @file{configure} is designed so that it appears to do everything itself,
1948 but there is actually a hidden slave: @file{config.status}.
1949 @file{configure} is in charge of examining your system, but it is
1950 @file{config.status} that actually takes the proper actions based on the
1951 results of @file{configure}.  The most typical task of
1952 @file{config.status} is to @emph{instantiate} files.
1954 This section describes the common behavior of the four standard
1955 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1956 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}.  They all
1957 have this prototype:
1959 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1960 @c awful.
1961 @example
1962 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1963 @end example
1965 @noindent
1966 where the arguments are:
1968 @table @var
1969 @item @var{tag}@dots{}
1970 A blank-or-newline-separated list of tags, which are typically the names of
1971 the files to instantiate.
1973 You are encouraged to use literals as @var{tags}.  In particular, you
1974 should avoid
1976 @example
1977 @dots{} && my_foos="$my_foos fooo"
1978 @dots{} && my_foos="$my_foos foooo"
1979 AC_CONFIG_FOOS([$my_foos])
1980 @end example
1982 @noindent
1983 and use this instead:
1985 @example
1986 @dots{} && AC_CONFIG_FOOS([fooo])
1987 @dots{} && AC_CONFIG_FOOS([foooo])
1988 @end example
1990 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
1991 special @var{tag}s: they may have the form @samp{@var{output}} or
1992 @samp{@var{output}:@var{inputs}}.  The file @var{output} is instantiated
1993 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
1995 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
1996 for example, asks for
1997 the creation of @file{Makefile} that will be the expansion of the
1998 output variables in the concatenation of @file{boiler/top.mk} and
1999 @file{boiler/bot.mk}.
2001 The special value @samp{-} might be used to denote the standard output
2002 when used in @var{output}, or the standard input when used in the
2003 @var{inputs}.  You most probably don't need to use this in
2004 @file{configure.ac}, but it is convenient when using the command line
2005 interface of @file{./config.status}, see @ref{config.status Invocation},
2006 for more details.
2008 The @var{inputs} may be absolute or relative file names.  In the latter
2009 case they are first looked for in the build tree, and then in the source
2010 tree.
2012 @item commands
2013 Shell commands output literally into @file{config.status}, and
2014 associated with a tag that the user can use to tell @file{config.status}
2015 which the commands to run.  The commands are run each time a @var{tag}
2016 request is given to @file{config.status}, typically each time the file
2017 @file{@var{tag}} is created.
2019 The variables set during the execution of @command{configure} are
2020 @emph{not} available here: you first need to set them via the
2021 @var{init-cmds}.  Nonetheless the following variables are precomputed:
2023 @table @code
2024 @item srcdir
2025 The name of the top source directory, assuming that the working
2026 directory is the top build directory.  This
2027 is what @command{configure}'s option @option{--srcdir} sets.
2029 @item ac_top_srcdir
2030 The name of the top source directory, assuming that the working
2031 directory is the current build directory.
2034 @item ac_top_build_prefix
2035 The name of the top build directory, assuming that the working
2036 directory is the current build directory.
2037 It can be empty, or else ends with a slash, so that you may concatenate
2040 @item ac_srcdir
2041 The name of the corresponding source directory, assuming that the
2042 working directory is the current build directory.
2043 @end table
2045 @noindent
2046 The @dfn{current} directory refers to the directory (or
2047 pseudo-directory) containing the input part of @var{tags}.  For
2048 instance, running
2050 @example
2051 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2052 @end example
2054 @noindent
2055  with @option{--srcdir=../package} produces the following values:
2057 @example
2058 # Argument of --srcdir
2059 srcdir='../package'
2060 # Reversing deep/dir
2061 ac_top_build_prefix='../../'
2062 # Concatenation of $ac_top_build_prefix and srcdir
2063 ac_top_srcdir='../../../package'
2064 # Concatenation of $ac_top_srcdir and deep/dir
2065 ac_srcdir='../../../package/deep/dir'
2066 @end example
2068 @noindent
2069 independently of @samp{in/in.in}.
2071 @item init-cmds
2072 Shell commands output @emph{unquoted} near the beginning of
2073 @file{config.status}, and executed each time @file{config.status} runs
2074 (regardless of the tag).  Because they are unquoted, for example,
2075 @samp{$var} will be output as the value of @code{var}.  @var{init-cmds}
2076 is typically used by @file{configure} to give @file{config.status} some
2077 variables it needs to run the @var{commands}.
2079 You should be extremely cautious in your variable names: all the
2080 @var{init-cmds} share the same name space and may overwrite each other
2081 in unpredictable ways.  Sorry@enddots{}
2082 @end table
2084 All these macros can be called multiple times, with different
2085 @var{tag}s, of course!
2088 @node Configuration Files
2089 @section Creating Configuration Files
2090 @cindex Creating configuration files
2091 @cindex Configuration file creation
2093 Be sure to read the previous section, @ref{Configuration Actions}.
2095 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2096 @acindex{CONFIG_FILES}
2097 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2098 file (by default @file{@var{file}.in}), substituting the output variable
2099 values.
2100 @c Before we used to have this feature, which was later rejected
2101 @c because it complicates the write of Makefiles:
2102 @c If the file would be unchanged, it is left untouched, to preserve
2103 @c timestamp.
2104 This macro is one of the instantiating macros; see @ref{Configuration
2105 Actions}.  @xref{Makefile Substitutions}, for more information on using
2106 output variables.  @xref{Setting Output Variables}, for more information
2107 on creating them.  This macro creates the directory that the file is in
2108 if it doesn't exist.  Usually, @file{Makefile}s are created this way,
2109 but other files, such as @file{.gdbinit}, can be specified as well.
2111 Typical calls to @code{AC_CONFIG_FILES} look like this:
2113 @example
2114 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2115 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2116 @end example
2118 You can override an input file name by appending to @var{file} a
2119 colon-separated list of input files.  Examples:
2121 @example
2122 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2123                 [lib/Makefile:boiler/lib.mk])
2124 @end example
2126 @noindent
2127 Doing this allows you to keep your file names acceptable to
2128 @acronym{DOS} variants, or
2129 to prepend and/or append boilerplate to the file.
2130 @end defmac
2134 @node Makefile Substitutions
2135 @section Substitutions in Makefiles
2136 @cindex Substitutions in makefiles
2137 @cindex Makefile substitutions
2139 Each subdirectory in a distribution that contains something to be
2140 compiled or installed should come with a file @file{Makefile.in}, from
2141 which @command{configure} will create a @file{Makefile} in that directory.
2142 To create a @file{Makefile}, @command{configure} performs a simple variable
2143 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2144 @file{Makefile.in} with the value that @command{configure} has determined
2145 for that variable.  Variables that are substituted into output files in
2146 this way are called @dfn{output variables}.  They are ordinary shell
2147 variables that are set in @command{configure}.  To make @command{configure}
2148 substitute a particular variable into the output files, the macro
2149 @code{AC_SUBST} must be called with that variable name as an argument.
2150 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2151 left unchanged.  @xref{Setting Output Variables}, for more information
2152 on creating output variables with @code{AC_SUBST}.
2154 A software package that uses a @command{configure} script should be
2155 distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
2156 way, the user has to properly configure the package for the local system
2157 before compiling it.
2159 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2160 @acronym{GNU} Coding Standards}, for more information on what to put in
2161 @file{Makefile}s.
2163 @menu
2164 * Preset Output Variables::     Output variables that are always set
2165 * Installation Directory Variables::  Other preset output variables
2166 * Build Directories::           Supporting multiple concurrent compiles
2167 * Automatic Remaking::          Makefile rules for configuring
2168 @end menu
2170 @node Preset Output Variables
2171 @subsection Preset Output Variables
2172 @cindex Output variables
2174 Some output variables are preset by the Autoconf macros.  Some of the
2175 Autoconf macros set additional output variables, which are mentioned in
2176 the descriptions for those macros.  @xref{Output Variable Index}, for a
2177 complete list of output variables.  @xref{Installation Directory
2178 Variables}, for the list of the preset ones related to installation
2179 directories.  Below are listed the other preset ones.  They all are
2180 precious variables (@pxref{Setting Output Variables},
2181 @code{AC_ARG_VAR}).
2183 @c Just say no to ASCII sorting!  We're humans, not computers.
2184 @c These variables are listed as they would be in a dictionary:
2185 @c actor
2186 @c Actress
2187 @c actress
2189 @defvar CFLAGS
2190 @ovindex CFLAGS
2191 Debugging and optimization options for the C compiler.  If it is not set
2192 in the environment when @command{configure} runs, the default value is set
2193 when you call @code{AC_PROG_CC} (or empty if you don't).  @command{configure}
2194 uses this variable when compiling programs to test for C features.
2195 @end defvar
2197 @defvar configure_input
2198 @ovindex configure_input
2199 A comment saying that the file was generated automatically by
2200 @command{configure} and giving the name of the input file.
2201 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2202 of every @file{Makefile} it creates.  For other files, you should
2203 reference this variable in a comment at the top of each input file.  For
2204 example, an input shell script should begin like this:
2206 @example
2207 #!/bin/sh
2208 # @@configure_input@@
2209 @end example
2211 @noindent
2212 The presence of that line also reminds people editing the file that it
2213 needs to be processed by @command{configure} in order to be used.
2214 @end defvar
2216 @defvar CPPFLAGS
2217 @ovindex CPPFLAGS
2218 Header file search directory (@option{-I@var{dir}}) and any other
2219 miscellaneous options for the C and C++ preprocessors and compilers.  If
2220 it is not set in the environment when @command{configure} runs, the default
2221 value is empty.  @command{configure} uses this variable when compiling or
2222 preprocessing programs to test for C and C++ features.
2223 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2224 might run into.
2225 @end defvar
2227 @defvar CXXFLAGS
2228 @ovindex CXXFLAGS
2229 Debugging and optimization options for the C++ compiler.  If it is not
2230 set in the environment when @command{configure} runs, the default value is
2231 set when you call @code{AC_PROG_CXX} (or empty if you don't).
2232 @command{configure} uses this variable when compiling programs to test for
2233 C++ features.
2234 @end defvar
2236 @defvar DEFS
2237 @ovindex DEFS
2238 @option{-D} options to pass to the C compiler.  If @code{AC_CONFIG_HEADERS}
2239 is called, @command{configure} replaces @samp{@@DEFS@@} with
2240 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}).  This
2241 variable is not defined while @command{configure} is performing its tests,
2242 only when creating the output files.  @xref{Setting Output Variables}, for
2243 how to check the results of previous tests.
2244 @end defvar
2246 @defvar ECHO_C
2247 @defvarx ECHO_N
2248 @defvarx ECHO_T
2249 @ovindex ECHO_C
2250 @ovindex ECHO_N
2251 @ovindex ECHO_T
2252 How does one suppress the trailing newline from @command{echo} for
2253 question-answer message pairs?  These variables provide a way:
2255 @example
2256 echo $ECHO_N "And the winner is... $ECHO_C"
2257 sleep 100000000000
2258 echo "$@{ECHO_T@}dead."
2259 @end example
2261 @noindent
2262 Some old and uncommon @command{echo} implementations offer no means to
2263 achieve this, in which case @code{ECHO_T} is set to tab.  You might not
2264 want to use it.
2265 @end defvar
2267 @defvar ERLCFLAGS
2268 @ovindex ERLCFLAGS
2269 Debugging and optimization options for the Erlang compiler.  If it is not set
2270 in the environment when @command{configure} runs, the default value is empty.
2271 @command{configure} uses this variable when compiling programs to test for
2272 Erlang features.
2273 @end defvar
2275 @defvar FCFLAGS
2276 @ovindex FCFLAGS
2277 Debugging and optimization options for the Fortran compiler.  If it
2278 is not set in the environment when @command{configure} runs, the default
2279 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2280 @command{configure} uses this variable when compiling programs to test for
2281 Fortran features.
2282 @end defvar
2284 @defvar FFLAGS
2285 @ovindex FFLAGS
2286 Debugging and optimization options for the Fortran 77 compiler.  If it
2287 is not set in the environment when @command{configure} runs, the default
2288 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2289 @command{configure} uses this variable when compiling programs to test for
2290 Fortran 77 features.
2291 @end defvar
2293 @defvar LDFLAGS
2294 @ovindex LDFLAGS
2295 Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
2296 options for the linker.  Don't use this variable to pass library names
2297 (@option{-l}) to the linker, use @code{LIBS} instead.  If it is not set
2298 in the environment when @command{configure} runs, the default value is empty.
2299 @command{configure} uses this variable when linking programs to test for
2300 C, C++, and Fortran features.
2301 @end defvar
2303 @defvar LIBS
2304 @ovindex LIBS
2305 @option{-l} options to pass to the linker.  The default value is empty,
2306 but some Autoconf macros may prepend extra libraries to this variable if
2307 those libraries are found and provide necessary functions, see
2308 @ref{Libraries}.  @command{configure} uses this variable when linking
2309 programs to test for C, C++, and Fortran features.
2310 @end defvar
2312 @defvar OBJCFLAGS
2313 @ovindex OBJCFLAGS
2314 Debugging and optimization options for the Objective C compiler.  If it is
2315 not set in the environment when @command{configure} runs, the default value
2316 is set when you call @code{AC_PROG_OBJC} (or empty if you don't).
2317 @command{configure} uses this variable when compiling programs to test for
2318 Objective C features.
2319 @end defvar
2321 @defvar builddir
2322 @ovindex builddir
2323 Rigorously equal to @samp{.}.  Added for symmetry only.
2324 @end defvar
2326 @defvar abs_builddir
2327 @ovindex abs_builddir
2328 Absolute name of @code{builddir}.
2329 @end defvar
2331 @defvar top_builddir
2332 @ovindex top_builddir
2333 The relative name of the top level of the current build tree.  In the
2334 top-level directory, this is the same as @code{builddir}.
2335 @end defvar
2337 @defvar abs_top_builddir
2338 @ovindex abs_top_builddir
2339 Absolute name of @code{top_builddir}.
2340 @end defvar
2342 @defvar srcdir
2343 @ovindex srcdir
2344 The relative name of the directory that contains the source code for
2345 that @file{Makefile}.
2346 @end defvar
2348 @defvar abs_srcdir
2349 @ovindex abs_srcdir
2350 Absolute name of @code{srcdir}.
2351 @end defvar
2353 @defvar top_srcdir
2354 @ovindex top_srcdir
2355 The relative name of the top-level source code directory for the
2356 package.  In the top-level directory, this is the same as @code{srcdir}.
2357 @end defvar
2359 @defvar abs_top_srcdir
2360 @ovindex abs_top_srcdir
2361 Absolute name of @code{top_srcdir}.
2362 @end defvar
2364 @node Installation Directory Variables
2365 @subsection Installation Directory Variables
2366 @cindex Installation directories
2367 @cindex Directories, installation
2369 The following variables specify the directories where the package will
2370 be installed, see @ref{Directory Variables, , Variables for
2371 Installation Directories, standards, The @acronym{GNU} Coding
2372 Standards}, for more information.  See the end of this section for
2373 details on when and how to use these variables.
2375 @defvar bindir
2376 @ovindex bindir
2377 The directory for installing executables that users run.
2378 @end defvar
2380 @defvar datadir
2381 @ovindex datadir
2382 The directory for installing idiosyncratic read-only
2383 architecture-independent data.
2384 @end defvar
2386 @defvar datarootdir
2387 @ovindex datarootdir
2388 The root of the directory tree for read-only architecture-independent
2389 data files.
2390 @end defvar
2392 @defvar docdir
2393 @ovindex docdir
2394 The directory for installing documentation files (other than Info and
2395 man).
2396 @end defvar
2398 @defvar dvidir
2399 @ovindex dvidir
2400 The directory for installing documentation files in DVI format.
2401 @end defvar
2403 @defvar exec_prefix
2404 @ovindex exec_prefix
2405 The installation prefix for architecture-dependent files.  By default
2406 it's the same as @var{prefix}.  You should avoid installing anything
2407 directly to @var{exec_prefix}.  However, the default value for
2408 directories containing architecture-dependent files should be relative
2409 to @var{exec_prefix}.
2410 @end defvar
2412 @defvar htmldir
2413 @ovindex htmldir
2414 The directory for installing HTML documentation.
2415 @end defvar
2417 @defvar includedir
2418 @ovindex includedir
2419 The directory for installing C header files.
2420 @end defvar
2422 @defvar infodir
2423 @ovindex infodir
2424 The directory for installing documentation in Info format.
2425 @end defvar
2427 @defvar libdir
2428 @ovindex libdir
2429 The directory for installing object code libraries.
2430 @end defvar
2432 @defvar libexecdir
2433 @ovindex libexecdir
2434 The directory for installing executables that other programs run.
2435 @end defvar
2437 @defvar localedir
2438 @ovindex localedir
2439 The directory for installing locale-dependent but
2440 architecture-independent data, such as message catalogs.  This directory
2441 usually has a subdirectory per locale.
2442 @end defvar
2444 @defvar localstatedir
2445 @ovindex localstatedir
2446 The directory for installing modifiable single-machine data.
2447 @end defvar
2449 @defvar mandir
2450 @ovindex mandir
2451 The top-level directory for installing documentation in man format.
2452 @end defvar
2454 @defvar oldincludedir
2455 @ovindex oldincludedir
2456 The directory for installing C header files for non-GCC compilers.
2457 @end defvar
2459 @defvar pdfdir
2460 @ovindex pdfdir
2461 The directory for installing PDF documentation.
2462 @end defvar
2464 @defvar prefix
2465 @ovindex prefix
2466 The common installation prefix for all files.  If @var{exec_prefix}
2467 is defined to a different value, @var{prefix} is used only for
2468 architecture-independent files.
2469 @end defvar
2471 @defvar psdir
2472 @ovindex psdir
2473 The directory for installing PostScript documentation.
2474 @end defvar
2476 @defvar sbindir
2477 @ovindex sbindir
2478 The directory for installing executables that system
2479 administrators run.
2480 @end defvar
2482 @defvar sharedstatedir
2483 @ovindex sharedstatedir
2484 The directory for installing modifiable architecture-independent data.
2485 @end defvar
2487 @defvar sysconfdir
2488 @ovindex sysconfdir
2489 The directory for installing read-only single-machine data.
2490 @end defvar
2493 Most of these variables have values that rely on @code{prefix} or
2494 @code{exec_prefix}.  It is deliberate that the directory output
2495 variables keep them unexpanded: typically @samp{@@datarootdir@@} will be
2496 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2497 @samp{@@datadir@@} will be replaced by @samp{$@{datarootdir@}}.
2499 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2500 the user runs:
2502 @table @samp
2503 @item make
2504 she can still specify a different prefix from the one specified to
2505 @command{configure}, in which case, if needed, the package shall hard
2506 code dependencies corresponding to the make-specified prefix.
2508 @item make install
2509 she can specify a different installation location, in which case the
2510 package @emph{must} still depend on the location which was compiled in
2511 (i.e., never recompile when @samp{make install} is run).  This is an
2512 extremely important feature, as many people may decide to install all
2513 the files of a package grouped together, and then install links from
2514 the final locations to there.
2515 @end table
2517 In order to support these features, it is essential that
2518 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2519 depend upon the current value of @code{prefix}.
2521 A corollary is that you should not use these variables except in
2522 Makefiles.  For instance, instead of trying to evaluate @code{datadir}
2523 in @file{configure} and hard-coding it in Makefiles using
2524 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2525 you should add
2526 @option{-DDATADIR='$(datadir)'} to your Makefile's definition of
2527 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2529 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2530 @code{datadir} and friends in your shell scripts and other files, rather
2531 let @command{make} manage their replacement.  For instance Autoconf
2532 ships templates of its shell scripts ending with @samp{.in}, and uses a
2533 Makefile snippet similar to:
2535 @example
2536 @group
2537 edit = sed \
2538         -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2539         -e 's|@@prefix[@@]|$(prefix)|g'
2540 @end group
2542 @group
2543 autoconf: Makefile $(srcdir)/autoconf.in
2544         rm -f autoconf autoconf.tmp
2545         $(edit) $(srcdir)/autoconf.in >autoconf.tmp
2546         chmod +x autoconf.tmp
2547         mv autoconf.tmp autoconf
2548 @end group
2550 @group
2551 autoheader: Makefile $(srcdir)/autoheader.in
2552         rm -f autoheader autoheader.tmp
2553         $(edit) $(srcdir)/autoconf.in >autoheader.tmp
2554         chmod +x autoheader.tmp
2555         mv autoheader.tmp autoheader
2556 @end group
2557 @end example
2559 Some details are noteworthy:
2561 @table @samp
2562 @item @@datadir[@@]
2563 The brackets prevent @command{configure} from replacing
2564 @samp{@@datadir@@} in the Sed expression itself.
2565 Brackets are preferable to a backslash here, since
2566 Posix says @samp{\@@} is not portable.
2568 @item $(pkgdatadir)
2569 Don't use @samp{@@pkgdatadir@@}!  Use the matching makefile variable
2570 instead.
2572 @item ,
2573 Don't use @samp{/} in the Sed expression(s) since most likely the
2574 variables you use, such as @samp{$(pkgdatadir)}, will contain
2575 some.
2577 @item Dependency on @file{Makefile}
2578 Since @code{edit} uses values that depend on the configuration specific
2579 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2580 the output depends on @file{Makefile}, not @file{configure.ac}.
2582 @item Separated dependencies and Single Suffix Rules
2583 You can't use them!  The above snippet cannot be (portably) rewritten
2586 @example
2587 autoconf autoheader: Makefile
2588 @group
2589 .in:
2590         rm -f $@@ $@@.tmp
2591         $(edit) $< >$@@.tmp
2592         chmod +x $@@.tmp
2593         mv $@@.tmp $@@
2594 @end group
2595 @end example
2597 @xref{Limitations of Make}, for details.
2599 @item @samp{$(srcdir)}
2600 Be sure to specify the name of the source directory,
2601 otherwise the package won't support separated builds.
2602 @end table
2604 For the more specific installation of Erlang libraries, the following variables
2605 are defined:
2607 @defvar ERLANG_INSTALL_LIB_DIR
2608 @ovindex ERLANG_INSTALL_LIB_DIR
2609 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2610 The common parent directory of Erlang library installation directories.
2611 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2612 macro in @file{configure.ac}.
2613 @end defvar
2615 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2616 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2617 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2618 The installation directory for Erlang library @var{library}.
2619 This variable is set by calling the
2620 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2621 macro in @file{configure.ac}.
2622 @end defvar
2624 @xref{Erlang Libraries}, for details.
2627 @node Build Directories
2628 @subsection Build Directories
2629 @cindex Build directories
2630 @cindex Directories, build
2632 You can support compiling a software package for several architectures
2633 simultaneously from the same copy of the source code.  The object files
2634 for each architecture are kept in their own directory.
2636 To support doing this, @command{make} uses the @code{VPATH} variable to
2637 find the files that are in the source directory.  @acronym{GNU} Make
2638 and most other recent @command{make} programs can do this.  Older
2639 @command{make} programs do not support @code{VPATH}; when using them, the
2640 source code must be in the same directory as the object files.
2642 To support @code{VPATH}, each @file{Makefile.in} should contain two
2643 lines that look like:
2645 @example
2646 srcdir = @@srcdir@@
2647 VPATH = @@srcdir@@
2648 @end example
2650 Do not set @code{VPATH} to the value of another variable, for example
2651 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2652 variable substitutions on the value of @code{VPATH}.
2654 @command{configure} substitutes the correct value for @code{srcdir} when
2655 it produces @file{Makefile}.
2657 Do not use the @code{make} variable @code{$<}, which expands to the
2658 file name of the file in the source directory (found with @code{VPATH}),
2659 except in implicit rules.  (An implicit rule is one such as @samp{.c.o},
2660 which tells how to create a @file{.o} file from a @file{.c} file.)  Some
2661 versions of @command{make} do not set @code{$<} in explicit rules; they
2662 expand it to an empty value.
2664 Instead, @file{Makefile} command lines should always refer to source
2665 files by prefixing them with @samp{$(srcdir)/}.  For example:
2667 @example
2668 time.info: time.texinfo
2669         $(MAKEINFO) $(srcdir)/time.texinfo
2670 @end example
2672 @node Automatic Remaking
2673 @subsection Automatic Remaking
2674 @cindex Automatic remaking
2675 @cindex Remaking automatically
2677 You can put rules like the following in the top-level @file{Makefile.in}
2678 for a package to automatically update the configuration information when
2679 you change the configuration files.  This example includes all of the
2680 optional files, such as @file{aclocal.m4} and those related to
2681 configuration header files.  Omit from the @file{Makefile.in} rules for
2682 any of these files that your package does not use.
2684 The @samp{$(srcdir)/} prefix is included because of limitations in the
2685 @code{VPATH} mechanism.
2687 The @file{stamp-} files are necessary because the timestamps of
2688 @file{config.h.in} and @file{config.h} will not be changed if remaking
2689 them does not change their contents.  This feature avoids unnecessary
2690 recompilation.  You should include the file @file{stamp-h.in} your
2691 package's distribution, so @command{make} will consider
2692 @file{config.h.in} up to date.  Don't use @command{touch}
2693 (@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
2694 @command{date} would cause needless differences, hence @acronym{CVS}
2695 conflicts, etc.).
2697 @example
2698 @group
2699 $(srcdir)/configure: configure.ac aclocal.m4
2700         cd $(srcdir) && autoconf
2702 # autoheader might not change config.h.in, so touch a stamp file.
2703 $(srcdir)/config.h.in: stamp-h.in
2704 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2705         cd $(srcdir) && autoheader
2706         echo timestamp > $(srcdir)/stamp-h.in
2708 config.h: stamp-h
2709 stamp-h: config.h.in config.status
2710         ./config.status
2712 Makefile: Makefile.in config.status
2713         ./config.status
2715 config.status: configure
2716         ./config.status --recheck
2717 @end group
2718 @end example
2720 @noindent
2721 (Be careful if you copy these lines directly into your Makefile, as you
2722 will need to convert the indented lines to start with the tab character.)
2724 In addition, you should use
2726 @example
2727 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2728 @end example
2730 @noindent
2731 so @file{config.status} will ensure that @file{config.h} is considered up to
2732 date.  @xref{Output}, for more information about @code{AC_OUTPUT}.
2734 @xref{config.status Invocation}, for more examples of handling
2735 configuration-related dependencies.
2737 @node Configuration Headers
2738 @section Configuration Header Files
2739 @cindex Configuration Header
2740 @cindex @file{config.h}
2742 When a package contains more than a few tests that define C preprocessor
2743 symbols, the command lines to pass @option{-D} options to the compiler
2744 can get quite long.  This causes two problems.  One is that the
2745 @command{make} output is hard to visually scan for errors.  More
2746 seriously, the command lines can exceed the length limits of some
2747 operating systems.  As an alternative to passing @option{-D} options to
2748 the compiler, @command{configure} scripts can create a C header file
2749 containing @samp{#define} directives.  The @code{AC_CONFIG_HEADERS}
2750 macro selects this kind of output.  Though it can be called anywhere
2751 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2752 it right after @code{AC_INIT}.
2754 The package should @samp{#include} the configuration header file before
2755 any other header files, to prevent inconsistencies in declarations (for
2756 example, if it redefines @code{const}).
2758 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2759 option (or @option{-I..}; whichever directory contains @file{config.h}).
2760 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2761 the directory of the currently read file, i.e., the source directory, not
2762 the build directory.
2764 With the appropriate @option{-I} option, you can use
2765 @samp{#include <config.h>}.  Actually, it's a good habit to use it,
2766 because in the rare case when the source directory contains another
2767 @file{config.h}, the build directory should be searched first.
2770 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2771 @acindex{CONFIG_HEADERS}
2772 @cvindex HAVE_CONFIG_H
2773 This macro is one of the instantiating macros; see @ref{Configuration
2774 Actions}.  Make @code{AC_OUTPUT} create the file(s) in the
2775 blank-or-newline-separated list @var{header} containing C preprocessor
2776 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2777 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2778 The usual name for @var{header} is @file{config.h}.
2780 If @var{header} already exists and its contents are identical to what
2781 @code{AC_OUTPUT} would put in it, it is left alone.  Doing this allows
2782 making some changes in the configuration without needlessly causing
2783 object files that depend on the header file to be recompiled.
2785 Usually the input file is named @file{@var{header}.in}; however, you can
2786 override the input file name by appending to @var{header} a
2787 colon-separated list of input files.  Examples:
2789 @example
2790 AC_CONFIG_HEADERS([config.h:config.hin])
2791 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2792 @end example
2794 @noindent
2795 Doing this allows you to keep your file names acceptable to
2796 @acronym{DOS} variants, or
2797 to prepend and/or append boilerplate to the file.
2798 @end defmac
2800 @defmac AH_HEADER
2801 @ahindex{HEADER}
2802 This macro is defined as the name of the first declared config header
2803 and undefined if no config headers have been declared up to this point.
2804 A third-party macro may, for example, require use of a config header
2805 without invoking AC_CONFIG_HEADERS twice, like this:
2807 @example
2808 AC_CONFIG_COMMANDS_PRE(
2809         [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2810 @end example
2812 @end defmac
2814 @xref{Configuration Actions}, for more details on @var{header}.
2816 @menu
2817 * Header Templates::            Input for the configuration headers
2818 * autoheader Invocation::       How to create configuration templates
2819 * Autoheader Macros::           How to specify CPP templates
2820 @end menu
2822 @node Header Templates
2823 @subsection Configuration Header Templates
2824 @cindex Configuration Header Template
2825 @cindex Header templates
2826 @cindex @file{config.h.in}
2828 Your distribution should contain a template file that looks as you want
2829 the final header file to look, including comments, with @code{#undef}
2830 statements which are used as hooks.  For example, suppose your
2831 @file{configure.ac} makes these calls:
2833 @example
2834 AC_CONFIG_HEADERS([conf.h])
2835 AC_CHECK_HEADERS([unistd.h])
2836 @end example
2838 @noindent
2839 Then you could have code like the following in @file{conf.h.in}.  On
2840 systems that have @file{unistd.h}, @command{configure} will @samp{#define}
2841 @samp{HAVE_UNISTD_H} to 1.  On other systems, the whole line will be
2842 commented out (in case the system predefines that symbol).
2844 @example
2845 @group
2846 /* Define as 1 if you have unistd.h.  */
2847 #undef HAVE_UNISTD_H
2848 @end group
2849 @end example
2851 Pay attention that @samp{#undef} is in the first column, and there is
2852 nothing after @samp{HAVE_UNISTD_H}, not even white space.  You can
2853 then decode the configuration header using the preprocessor directives:
2855 @example
2856 @group
2857 #include <conf.h>
2859 #if HAVE_UNISTD_H
2860 # include <unistd.h>
2861 #else
2862 /* We are in trouble.  */
2863 #endif
2864 @end group
2865 @end example
2867 The use of old form templates, with @samp{#define} instead of
2868 @samp{#undef} is strongly discouraged.  Similarly with old templates
2869 with comments on the same line as the @samp{#undef}.  Anyway, putting
2870 comments in preprocessor macros has never been a good idea.
2872 Since it is a tedious task to keep a template header up to date, you may
2873 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
2876 @node autoheader Invocation
2877 @subsection Using @command{autoheader} to Create @file{config.h.in}
2878 @cindex @command{autoheader}
2880 The @command{autoheader} program can create a template file of C
2881 @samp{#define} statements for @command{configure} to use.  If
2882 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
2883 @command{autoheader} creates @file{@var{file}.in}; if multiple file
2884 arguments are given, the first one is used.  Otherwise,
2885 @command{autoheader} creates @file{config.h.in}.
2887 In order to do its job, @command{autoheader} needs you to document all
2888 of the symbols that you might use; i.e., there must be at least one
2889 @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} call with a third
2890 argument for each symbol (@pxref{Defining Symbols}).  An additional
2891 constraint is that the first argument of @code{AC_DEFINE}
2892 or @code{AC_DEFINE_UNQUOTED} must be a
2893 literal.  Note that all symbols defined by Autoconf's builtin tests are
2894 already documented properly; you only need to document those that you
2895 define yourself.
2897 You might wonder why @command{autoheader} is needed: after all, why
2898 would @command{configure} need to ``patch'' a @file{config.h.in} to
2899 produce a @file{config.h} instead of just creating @file{config.h} from
2900 scratch?  Well, when everything rocks, the answer is just that we are
2901 wasting our time maintaining @command{autoheader}: generating
2902 @file{config.h} directly is all that is needed.  When things go wrong,
2903 however, you'll be thankful for the existence of @command{autoheader}.
2905 The fact that the symbols are documented is important in order to
2906 @emph{check} that @file{config.h} makes sense.  The fact that there is a
2907 well-defined list of symbols that should be @code{#define}'d (or not) is
2908 also important for people who are porting packages to environments where
2909 @command{configure} cannot be run: they just have to @emph{fill in the
2910 blanks}.
2912 But let's come back to the point: @command{autoheader}'s invocation@dots{}
2914 If you give @command{autoheader} an argument, it uses that file instead
2915 of @file{configure.ac} and writes the header file to the standard output
2916 instead of to @file{config.h.in}.  If you give @command{autoheader} an
2917 argument of @option{-}, it reads the standard input instead of
2918 @file{configure.ac} and writes the header file to the standard output.
2920 @command{autoheader} accepts the following options:
2922 @table @option
2923 @item --help
2924 @itemx -h
2925 Print a summary of the command line options and exit.
2927 @item --version
2928 @itemx -V
2929 Print the version number of Autoconf and exit.
2931 @item --verbose
2932 @itemx -v
2933 Report processing steps.
2935 @item --debug
2936 @itemx -d
2937 Don't remove the temporary files.
2939 @item --force
2940 @itemx -f
2941 Remake the template file even if newer than its input files.
2943 @item --include=@var{dir}
2944 @itemx -I @var{dir}
2945 Append @var{dir} to the include path.  Multiple invocations accumulate.
2947 @item --prepend-include=@var{dir}
2948 @item -B @var{dir}
2949 Prepend @var{dir} to the include path.  Multiple invocations accumulate.
2951 @item --warnings=@var{category}
2952 @itemx -W @var{category}
2953 @evindex WARNINGS
2954 Report the warnings related to @var{category} (which can actually be a
2955 comma separated list).  Current categories include:
2957 @table @samp
2958 @item obsolete
2959 report the uses of obsolete constructs
2961 @item all
2962 report all the warnings
2964 @item none
2965 report none
2967 @item error
2968 treats warnings as errors
2970 @item no-@var{category}
2971 disable warnings falling into @var{category}
2972 @end table
2974 @end table
2978 @node Autoheader Macros
2979 @subsection Autoheader Macros
2980 @cindex Autoheader macros
2982 @command{autoheader} scans @file{configure.ac} and figures out which C
2983 preprocessor symbols it might define.  It knows how to generate
2984 templates for symbols defined by @code{AC_CHECK_HEADERS},
2985 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
2986 symbol, you must define a template for it.  If there are missing
2987 templates, @command{autoheader} fails with an error message.
2989 The simplest way to create a template for a @var{symbol} is to supply
2990 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
2991 @ref{Defining Symbols}.  You may also use one of the following macros.
2993 @defmac AH_VERBATIM (@var{key}, @var{template})
2994 @ahindex{VERBATIM}
2995 Tell @command{autoheader} to include the @var{template} as-is in the header
2996 template file.  This @var{template} is associated with the @var{key},
2997 which is used to sort all the different templates and guarantee their
2998 uniqueness.  It should be a symbol that can be @code{AC_DEFINE}'d.
3000 For example:
3002 @example
3003 AH_VERBATIM([_GNU_SOURCE],
3004 [/* Enable GNU extensions on systems that have them.  */
3005 #ifndef _GNU_SOURCE
3006 # define _GNU_SOURCE
3007 #endif])
3008 @end example
3009 @end defmac
3012 @defmac AH_TEMPLATE (@var{key}, @var{description})
3013 @ahindex{TEMPLATE}
3014 Tell @command{autoheader} to generate a template for @var{key}.  This macro
3015 generates standard templates just like @code{AC_DEFINE} when a
3016 @var{description} is given.
3018 For example:
3020 @example
3021 AH_TEMPLATE([CRAY_STACKSEG_END],
3022             [Define to one of _getb67, GETB67, getb67
3023              for Cray-2 and Cray-YMP systems.  This
3024              function is required for alloca.c support
3025              on those systems.])
3026 @end example
3028 @noindent
3029 will generate the following template, with the description properly
3030 justified.
3032 @example
3033 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3034    Cray-YMP systems.  This function is required for alloca.c
3035    support on those systems.  */
3036 #undef CRAY_STACKSEG_END
3037 @end example
3038 @end defmac
3041 @defmac AH_TOP (@var{text})
3042 @ahindex{TOP}
3043 Include @var{text} at the top of the header template file.
3044 @end defmac
3047 @defmac AH_BOTTOM (@var{text})
3048 @ahindex{BOTTOM}
3049 Include @var{text} at the bottom of the header template file.
3050 @end defmac
3053 @node Configuration Commands
3054 @section Running Arbitrary Configuration Commands
3055 @cindex Configuration commands
3056 @cindex Commands for configuration
3058 You can execute arbitrary commands before, during, and after
3059 @file{config.status} is run.  The three following macros accumulate the
3060 commands to run when they are called multiple times.
3061 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3062 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3064 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3065 @acindex{CONFIG_COMMANDS}
3066 Specify additional shell commands to run at the end of
3067 @file{config.status}, and shell commands to initialize any variables
3068 from @command{configure}.  Associate the commands with @var{tag}.
3069 Since typically the @var{cmds} create a file, @var{tag} should
3070 naturally be the name of that file.  If needed, the directory hosting
3071 @var{tag} is created.  This macro is one of the instantiating macros;
3072 see @ref{Configuration Actions}.
3074 Here is an unrealistic example:
3075 @example
3076 fubar=42
3077 AC_CONFIG_COMMANDS([fubar],
3078                    [echo this is extra $fubar, and so on.],
3079                    [fubar=$fubar])
3080 @end example
3082 Here is a better one:
3083 @example
3084 AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
3085 @end example
3086 @end defmac
3088 The following two macros look similar, but in fact they are not of the same
3089 breed: they are executed directly by @file{configure}, so you cannot use
3090 @file{config.status} to re-run them.
3092 @c Yet it is good to leave them here.  The user sees them together and
3093 @c decides which best fits their needs.
3095 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3096 @acindex{CONFIG_COMMANDS_PRE}
3097 Execute the @var{cmds} right before creating @file{config.status}.
3099 This macro presents the last opportunity to call @code{AC_SUBST},
3100 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3101 @end defmac
3103 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3104 @acindex{CONFIG_COMMANDS_POST}
3105 Execute the @var{cmds} right after creating @file{config.status}.
3106 @end defmac
3111 @node Configuration Links
3112 @section Creating Configuration Links
3113 @cindex Configuration links
3114 @cindex Links for configuration
3116 You may find it convenient to create links whose destinations depend upon
3117 results of tests.  One can use @code{AC_CONFIG_COMMANDS} but the
3118 creation of relative symbolic links can be delicate when the package is
3119 built in a directory different from the source directory.
3121 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3122 @acindex{CONFIG_LINKS}
3123 @cindex Links
3124 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3125 the corresponding link name @var{dest}.  Makes a symbolic link if
3126 possible, otherwise a hard link if possible, otherwise a copy.  The
3127 @var{dest} and @var{source} names should be relative to the top level
3128 source or build directory.  This macro is one of the instantiating
3129 macros; see @ref{Configuration Actions}.
3131 For example, this call:
3133 @example
3134 AC_CONFIG_LINKS([host.h:config/$machine.h
3135                 object.h:config/$obj_format.h])
3136 @end example
3138 @noindent
3139 creates in the current directory @file{host.h} as a link to
3140 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3141 link to @file{@var{srcdir}/config/$obj_format.h}.
3143 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3144 impossible for @samp{config.status} to guess the links to establish.
3146 One can then run:
3147 @example
3148 ./config.status host.h object.h
3149 @end example
3150 @noindent
3151 to create the links.
3152 @end defmac
3156 @node Subdirectories
3157 @section Configuring Other Packages in Subdirectories
3158 @cindex Configure subdirectories
3159 @cindex Subdirectory configure
3161 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3162 @file{Makefile}s in subdirectories.  However, @command{configure} scripts
3163 that control more than one independent package can use
3164 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3165 packages in subdirectories.
3167 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3168 @acindex{CONFIG_SUBDIRS}
3169 @ovindex subdirs
3170 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3171 @var{dir} in the given blank-or-newline-separated list.  Each @var{dir} should
3172 be a literal, i.e., please do not use:
3174 @example
3175 if test "$package_foo_enabled" = yes; then
3176   $my_subdirs="$my_subdirs foo"
3178 AC_CONFIG_SUBDIRS([$my_subdirs])
3179 @end example
3181 @noindent
3182 because this prevents @samp{./configure --help=recursive} from
3183 displaying the options of the package @code{foo}.  Rather, you should
3184 write:
3186 @example
3187 if test "$package_foo_enabled" = yes; then
3188   AC_CONFIG_SUBDIRS([foo])
3190 @end example
3192 If a given @var{dir} is not found, an error is reported: if the
3193 subdirectory is optional, write:
3195 @example
3196 if test -d $srcdir/foo; then
3197   AC_CONFIG_SUBDIRS([foo])
3199 @end example
3201 @c NB: Yes, below we mean configure.in, not configure.ac.
3202 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3203 of @command{configure}.  This is for packages that might use a
3204 non-Autoconf script @command{Configure}, which can't be called through a
3205 wrapper @command{configure} since it would be the same file on
3206 case-insensitive file systems.  Likewise, if a @var{dir} contains
3207 @file{configure.in} but no @command{configure}, the Cygnus
3208 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3210 The subdirectory @command{configure} scripts are given the same command
3211 line options that were given to this @command{configure} script, with minor
3212 changes if needed, which include:
3214 @itemize @minus
3215 @item
3216 adjusting a relative name for the cache file;
3218 @item
3219 adjusting a relative name for the source directory;
3221 @item
3222 propagating the current value of @code{$prefix}, including if it was
3223 defaulted, and if the default values of the top level and of the subdirectory
3224 @file{configure} differ.
3225 @end itemize
3227 This macro also sets the output variable @code{subdirs} to the list of
3228 directories @samp{@var{dir} @dots{}}.  @file{Makefile} rules can use
3229 this variable to determine which subdirectories to recurse into.
3231 This macro may be called multiple times.
3232 @end defmac
3234 @node Default Prefix
3235 @section Default Prefix
3236 @cindex Install prefix
3237 @cindex Prefix for install
3239 By default, @command{configure} sets the prefix for files it installs to
3240 @file{/usr/local}.  The user of @command{configure} can select a different
3241 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3242 There are two ways to change the default: when creating
3243 @command{configure}, and when running it.
3245 Some software packages might want to install in a directory other than
3246 @file{/usr/local} by default.  To accomplish that, use the
3247 @code{AC_PREFIX_DEFAULT} macro.
3249 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3250 @acindex{PREFIX_DEFAULT}
3251 Set the default installation prefix to @var{prefix} instead of
3252 @file{/usr/local}.
3253 @end defmac
3255 It may be convenient for users to have @command{configure} guess the
3256 installation prefix from the location of a related program that they
3257 have already installed.  If you wish to do that, you can call
3258 @code{AC_PREFIX_PROGRAM}.
3260 @defmac AC_PREFIX_PROGRAM (@var{program})
3261 @acindex{PREFIX_PROGRAM}
3262 If the user did not specify an installation prefix (using the
3263 @option{--prefix} option), guess a value for it by looking for
3264 @var{program} in @env{PATH}, the way the shell does.  If @var{program}
3265 is found, set the prefix to the parent of the directory containing
3266 @var{program}, else default the prefix as described above
3267 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}).  For example, if
3268 @var{program} is @code{gcc} and the @env{PATH} contains
3269 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3270 @end defmac
3274 @c ======================================================== Existing tests
3276 @node Existing Tests
3277 @chapter Existing Tests
3279 These macros test for particular system features that packages might
3280 need or want to use.  If you need to test for a kind of feature that
3281 none of these macros check for, you can probably do it by calling
3282 primitive test macros with appropriate arguments (@pxref{Writing
3283 Tests}).
3285 These tests print messages telling the user which feature they're
3286 checking for, and what they find.  They cache their results for future
3287 @command{configure} runs (@pxref{Caching Results}).
3289 Some of these macros set output variables.  @xref{Makefile
3290 Substitutions}, for how to get their values.  The phrase ``define
3291 @var{name}'' is used below as a shorthand to mean ``define C
3292 preprocessor symbol @var{name} to the value 1''.  @xref{Defining
3293 Symbols}, for how to get those symbol definitions into your program.
3295 @menu
3296 * Common Behavior::             Macros' standard schemes
3297 * Alternative Programs::        Selecting between alternative programs
3298 * Files::                       Checking for the existence of files
3299 * Libraries::                   Library archives that might be missing
3300 * Library Functions::           C library functions that might be missing
3301 * Header Files::                Header files that might be missing
3302 * Declarations::                Declarations that may be missing
3303 * Structures::                  Structures or members that might be missing
3304 * Types::                       Types that might be missing
3305 * Compilers and Preprocessors::  Checking for compiling programs
3306 * System Services::             Operating system services
3307 * Posix Variants::              Special kludges for specific Posix variants
3308 * Erlang Libraries::            Checking for the existence of Erlang libraries
3309 @end menu
3311 @node Common Behavior
3312 @section Common Behavior
3313 @cindex Common autoconf behavior
3315 Much effort has been expended to make Autoconf easy to learn.  The most
3316 obvious way to reach this goal is simply to enforce standard interfaces
3317 and behaviors, avoiding exceptions as much as possible.  Because of
3318 history and inertia, unfortunately, there are still too many exceptions
3319 in Autoconf; nevertheless, this section describes some of the common
3320 rules.
3322 @menu
3323 * Standard Symbols::            Symbols defined by the macros
3324 * Default Includes::            Includes used by the generic macros
3325 @end menu
3327 @node Standard Symbols
3328 @subsection Standard Symbols
3329 @cindex Standard symbols
3331 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3332 their test transform their @var{argument}s to a standard alphabet.
3333 First, @var{argument} is converted to upper case and any asterisks
3334 (@samp{*}) are each converted to @samp{P}.  Any remaining characters
3335 that are not alphanumeric are converted to underscores.
3337 For instance,
3339 @example
3340 AC_CHECK_TYPES([struct $Expensive*])
3341 @end example
3343 @noindent
3344 will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3345 succeeds.
3348 @node Default Includes
3349 @subsection Default Includes
3350 @cindex Default includes
3351 @cindex Includes, default
3353 Several tests depend upon a set of header files.  Since these headers
3354 are not universally available, tests actually have to provide a set of
3355 protected includes, such as:
3357 @example
3358 @group
3359 #if TIME_WITH_SYS_TIME
3360 # include <sys/time.h>
3361 # include <time.h>
3362 #else
3363 # if HAVE_SYS_TIME_H
3364 #  include <sys/time.h>
3365 # else
3366 #  include <time.h>
3367 # endif
3368 #endif
3369 @end group
3370 @end example
3372 @noindent
3373 Unless you know exactly what you are doing, you should avoid using
3374 unconditional includes, and check the existence of the headers you
3375 include beforehand (@pxref{Header Files}).
3377 Most generic macros use the following macro to provide the default set
3378 of includes:
3380 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3381 @acindex{INCLUDES_DEFAULT}
3382 Expand to @var{include-directives} if defined, otherwise to:
3384 @example
3385 @group
3386 #include <stdio.h>
3387 #if HAVE_SYS_TYPES_H
3388 # include <sys/types.h>
3389 #endif
3390 #if HAVE_SYS_STAT_H
3391 # include <sys/stat.h>
3392 #endif
3393 #if STDC_HEADERS
3394 # include <stdlib.h>
3395 # include <stddef.h>
3396 #else
3397 # if HAVE_STDLIB_H
3398 #  include <stdlib.h>
3399 # endif
3400 #endif
3401 #if HAVE_STRING_H
3402 # if !STDC_HEADERS && HAVE_MEMORY_H
3403 #  include <memory.h>
3404 # endif
3405 # include <string.h>
3406 #endif
3407 #if HAVE_STRINGS_H
3408 # include <strings.h>
3409 #endif
3410 #if HAVE_INTTYPES_H
3411 # include <inttypes.h>
3412 #endif
3413 #if HAVE_STDINT_H
3414 # include <stdint.h>
3415 #endif
3416 #if HAVE_UNISTD_H
3417 # include <unistd.h>
3418 #endif
3419 @end group
3420 @end example
3422 If the default includes are used, then check for the presence of these
3423 headers and their compatibility, i.e., you don't need to run
3424 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3426 These headers are checked for in the same order as they are included.
3427 For instance, on some systems @file{string.h} and @file{strings.h} both
3428 exist, but conflict.  Then @code{HAVE_STRING_H} will be defined, but
3429 @code{HAVE_STRINGS_H} won't.
3430 @end defmac
3432 @node Alternative Programs
3433 @section Alternative Programs
3434 @cindex Programs, checking
3436 These macros check for the presence or behavior of particular programs.
3437 They are used to choose between several alternative programs and to
3438 decide what to do once one has been chosen.  If there is no macro
3439 specifically defined to check for a program you need, and you don't need
3440 to check for any special properties of it, then you can use one of the
3441 general program-check macros.
3443 @menu
3444 * Particular Programs::         Special handling to find certain programs
3445 * Generic Programs::            How to find other programs
3446 @end menu
3448 @node Particular Programs
3449 @subsection Particular Program Checks
3451 These macros check for particular programs---whether they exist, and
3452 in some cases whether they support certain features.
3454 @defmac AC_PROG_AWK
3455 @acindex{PROG_AWK}
3456 @ovindex AWK
3457 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3458 order, and set output variable @code{AWK} to the first one that is found.
3459 It tries @code{gawk} first because that is reported to be the
3460 best implementation.
3461 @end defmac
3463 @defmac AC_PROG_GREP
3464 @acindex{PROG_GREP}
3465 @ovindex GREP
3466 Look for the best available @code{grep} or @code{ggrep} that accepts the
3467 longest input lines possible, and that supports multiple @option{-e} options.
3468 Set the output variable @code{GREP} to whatever is chosen.
3469 @xref{Limitations of Usual Tools}, for more information about
3470 portability problems with the @command{grep} command family.
3471 @end defmac
3473 @defmac AC_PROG_EGREP
3474 @acindex{PROG_EGREP}
3475 @ovindex EGREP
3476 Check whether @code{$GREP -E} works, or else look for the best available
3477 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3478 Set the output variable @code{EGREP} to whatever is chosen.
3479 @end defmac
3481 @defmac AC_PROG_FGREP
3482 @acindex{PROG_FGREP}
3483 @ovindex FGREP
3484 Check whether @code{$GREP -F} works, or else look for the best available
3485 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3486 Set the output variable @code{FGREP} to whatever is chosen.
3487 @end defmac
3489 @defmac AC_PROG_INSTALL
3490 @acindex{PROG_INSTALL}
3491 @ovindex INSTALL
3492 @ovindex INSTALL_PROGRAM
3493 @ovindex INSTALL_DATA
3494 @ovindex INSTALL_SCRIPT
3495 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3496 @command{install} program, if one is found in the current @env{PATH}.
3497 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3498 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3499 default directories) to determine @var{dir} (@pxref{Output}).  Also set
3500 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3501 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3503 This macro screens out various instances of @command{install} known not to
3504 work.  It prefers to find a C program rather than a shell script, for
3505 speed.  Instead of @file{install-sh}, it can also use @file{install.sh},
3506 but that name is obsolete because some @command{make} programs have a rule
3507 that creates @file{install} from it if there is no @file{Makefile}.
3509 Autoconf comes with a copy of @file{install-sh} that you can use.  If
3510 you use @code{AC_PROG_INSTALL}, you must include either
3511 @file{install-sh} or @file{install.sh} in your distribution, or
3512 @command{configure} will produce an error message saying it can't find
3513 them---even if the system you're on has a good @command{install} program.
3514 This check is a safety measure to prevent you from accidentally leaving
3515 that file out, which would prevent your package from installing on
3516 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3518 If you need to use your own installation program because it has features
3519 not found in standard @command{install} programs, there is no reason to use
3520 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3521 @file{Makefile.in} files.
3522 @end defmac
3524 @defmac AC_PROG_MKDIR_P
3525 @acindex{AC_PROG_MKDIR_P}
3526 @ovindex MKDIR_P
3527 Set output variable @code{MKDIR_P} to a program that ensures that for
3528 each argument, a directory named by this argument exists, creating it
3529 and its parent directories if needed.  The program is checked to make
3530 sure that it is thread-safe (@pxref{Limitations of Usual Tools}).
3532 This macro uses the @samp{mkdir -p} command if possible.  Otherwise, it
3533 falls back on invoking @command{install-sh} with the @option{-d} option,
3534 so your package should
3535 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3536 A @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3537 won't be thread-safe, so if you want to support parallel installs from
3538 different packages into the same directory you need to make sure you
3539 have an up-to-date @file{install-sh}.  In particular, be careful about
3540 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3542 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3543 in M4sh}), but it sets an output variable intended for use in other
3544 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3545 @command{configure}.  Also, @code{AS_MKDIR_P} does not accept options,
3546 but if you are willing to assume Posix 1003.2-1992 or later, a
3547 @code{MKDIR_P} can use the @option{-m} option, e.g., a makefile might
3548 invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible directory.
3549 @end defmac
3551 @defmac AC_PROG_LEX
3552 @acindex{PROG_LEX}
3553 @ovindex LEX
3554 @ovindex LEXLIB
3555 @cvindex YYTEXT_POINTER
3556 @ovindex LEX_OUTPUT_ROOT
3557 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3558 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3559 place.  Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3560 @option{-ll}.
3562 Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3563 of a @samp{char []}.  Also set output variable @code{LEX_OUTPUT_ROOT} to
3564 the base of the file name that the lexer generates; usually
3565 @file{lex.yy}, but sometimes something else.  These results vary
3566 according to whether @code{lex} or @code{flex} is being used.
3568 You are encouraged to use Flex in your sources, since it is both more
3569 pleasant to use than plain Lex and the C source it produces is portable.
3570 In order to ensure portability, however, you must either provide a
3571 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3572 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3573 statement in the scanner's source.  Once this done, the scanner is
3574 portable (unless @emph{you} felt free to use nonportable constructs) and
3575 does not depend on any library.  In this case, and in this case only, it
3576 is suggested that you use this Autoconf snippet:
3578 @example
3579 AC_PROG_LEX
3580 if test "$LEX" != flex; then
3581   LEX="$SHELL $missing_dir/missing flex"
3582   AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3583   AC_SUBST([LEXLIB], [''])
3585 @end example
3587 The shell script @command{missing} can be found in the Automake
3588 distribution.
3590 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3591 (indirectly) this macro twice, which will cause an annoying but benign
3592 ``@code{AC_PROG_LEX} invoked multiple times'' warning.  Future versions
3593 of Automake will fix this issue; meanwhile, just ignore this message.
3595 As part of running the test, this macro may delete any file in the
3596 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3597 @end defmac
3599 @defmac AC_PROG_LN_S
3600 @acindex{PROG_LN_S}
3601 @ovindex LN_S
3602 If @samp{ln -s} works on the current file system (the operating system
3603 and file system support symbolic links), set the output variable
3604 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3605 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3607 If you make a link in a directory other than the current directory, its
3608 meaning depends on whether @samp{ln} or @samp{ln -s} is used.  To safely
3609 create links using @samp{$(LN_S)}, either find out which form is used
3610 and adjust the arguments, or always invoke @code{ln} in the directory
3611 where the link is to be created.
3613 In other words, it does not work to do:
3614 @example
3615 $(LN_S) foo /x/bar
3616 @end example
3618 Instead, do:
3620 @example
3621 (cd /x && $(LN_S) foo bar)
3622 @end example
3623 @end defmac
3625 @defmac AC_PROG_RANLIB
3626 @acindex{PROG_RANLIB}
3627 @ovindex RANLIB
3628 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3629 is found, and otherwise to @samp{:} (do nothing).
3630 @end defmac
3632 @defmac AC_PROG_SED
3633 @acindex{PROG_SED}
3634 @ovindex SED
3635 Set output variable @code{SED} to a Sed implementation that conforms to
3636 Posix and does not have arbitrary length limits.  Report an error if no
3637 acceptable Sed is found.  @xref{Limitations of Usual Tools}, for more
3638 information about portability problems with Sed.
3639 @end defmac
3641 @defmac AC_PROG_YACC
3642 @acindex{PROG_YACC}
3643 @ovindex YACC
3644 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3645 -y}.  Otherwise, if @code{byacc} is found, set @code{YACC} to
3646 @samp{byacc}.  Otherwise set @code{YACC} to @samp{yacc}.
3647 @end defmac
3649 @node Generic Programs
3650 @subsection Generic Program and File Checks
3652 These macros are used to find programs not covered by the ``particular''
3653 test macros.  If you need to check the behavior of a program as well as
3654 find out whether it is present, you have to write your own test for it
3655 (@pxref{Writing Tests}).  By default, these macros use the environment
3656 variable @env{PATH}.  If you need to check for a program that might not
3657 be in the user's @env{PATH}, you can pass a modified path to use
3658 instead, like this:
3660 @example
3661 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3662              [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3663 @end example
3665 You are strongly encouraged to declare the @var{variable} passed to
3666 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3667 @code{AC_ARG_VAR}, for more details.
3669 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path},  @ovar{reject})
3670 @acindex{CHECK_PROG}
3671 Check whether program @var{prog-to-check-for} exists in @env{PATH}.  If
3672 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3673 @var{value-if-not-found}, if given.  Always pass over @var{reject} (an
3674 absolute file name) even if it is the first found in the search path; in
3675 that case, set @var{variable} using the absolute file name of the
3676 @var{prog-to-check-for} found that is not @var{reject}.  If
3677 @var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
3678 @var{variable}.
3679 @end defmac
3681 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3682 @acindex{CHECK_PROGS}
3683 Check for each program in the blank-separated list
3684 @var{progs-to-check-for} existing in the @env{PATH}.  If one is found, set
3685 @var{variable} to the name of that program.  Otherwise, continue
3686 checking the next program in the list.  If none of the programs in the
3687 list are found, set @var{variable} to @var{value-if-not-found}; if
3688 @var{value-if-not-found} is not specified, the value of @var{variable}
3689 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3690 @end defmac
3692 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3693 @acindex{CHECK_TARGET_TOOL}
3694 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3695 with a prefix of the target type as determined by
3696 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3697 If the tool cannot be found with a prefix, and if the build and target
3698 types are equal, then it is also searched for without a prefix.
3700 As noted in @ref{Specifying Names, , Specifying the system type}, the
3701 target is rarely specified, because most of the time it is the same
3702 as the host: it is the type of system for which any compiler tools in
3703 the package will produce code.  What this macro will look for is,
3704 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3705 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3706 will use to produce objects, archives or executables}.
3707 @end defmac
3709 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3710 @acindex{CHECK_TOOL}
3711 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3712 with a prefix of the host type as determined by
3713 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3714 For example, if the user runs @samp{configure --host=i386-gnu}, then
3715 this call:
3716 @example
3717 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3718 @end example
3719 @noindent
3720 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3721 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3722 @env{PATH}, or to @samp{:} if neither program exists.
3724 In the future, when cross-compiling this macro will @emph{only}
3725 accept program names that are prefixed with the host type.
3726 For more information, see @ref{Specifying Names, , Specifying the
3727 system type}.
3728 @end defmac
3730 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3731 @acindex{CHECK_TARGET_TOOLS}
3732 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3733 @var{progs-to-check-for} are checked with a prefix of the target type as
3734 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3735 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3736 prefix, and if the build and target types are equal, then the first one
3737 without a prefix is used.  If a tool is found, set @var{variable} to
3738 the name of that program.  If none of the tools in the list are found,
3739 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3740 is not specified, the value of @var{variable} is not changed.  Calls
3741 @code{AC_SUBST} for @var{variable}.
3742 @end defmac
3744 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3745 @acindex{CHECK_TOOLS}
3746 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3747 @var{progs-to-check-for} are checked with a prefix of the host type as
3748 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3749 (@pxref{Canonicalizing}).  If none of the tools can be found with a
3750 prefix, then the first one without a prefix is used.  If a tool is found,
3751 set @var{variable} to the name of that program.  If none of the tools in
3752 the list are found, set @var{variable} to @var{value-if-not-found}; if
3753 @var{value-if-not-found} is not specified, the value of @var{variable}
3754 is not changed.  Calls @code{AC_SUBST} for @var{variable}.
3756 In the future, when cross-compiling this macro will @emph{not}
3757 accept program names that are not prefixed with the host type.
3758 @end defmac
3760 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3761 @acindex{PATH_PROG}
3762 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3763 name of @var{prog-to-check-for} if found.
3764 @end defmac
3766 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3767 @acindex{PATH_PROGS}
3768 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3769 are found, set @var{variable} to the absolute name of the program
3770 found.
3771 @end defmac
3773 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3774 @acindex{PATH_TARGET_TOOL}
3775 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3776 name of the program if it is found.
3777 @end defmac
3779 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3780 @acindex{PATH_TOOL}
3781 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3782 name of the program if it is found.
3784 In the future, when cross-compiling this macro will @emph{not}
3785 accept program names that are not prefixed with the host type.
3786 @end defmac
3789 @node Files
3790 @section Files
3791 @cindex File, checking
3793 You might also need to check for the existence of files.  Before using
3794 these macros, ask yourself whether a runtime test might not be a better
3795 solution.  Be aware that, like most Autoconf macros, they test a feature
3796 of the host machine, and therefore, they die when cross-compiling.
3798 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3799 @acindex{CHECK_FILE}
3800 Check whether file @var{file} exists on the native system.  If it is
3801 found, execute @var{action-if-found}, otherwise do
3802 @var{action-if-not-found}, if given.
3803 @end defmac
3805 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3806 @acindex{CHECK_FILES}
3807 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3808 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3809 for each file found.
3810 @end defmac
3813 @node Libraries
3814 @section Library Files
3815 @cindex Library, checking
3817 The following macros check for the presence of certain C, C++, or Fortran
3818 library archive files.
3820 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3821 @acindex{CHECK_LIB}
3822 Test whether the library @var{library} is available by trying to link
3823 a test program that calls function @var{function} with the library.
3824 @var{function} should be a function provided by the library.
3825 Use the base
3826 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3827 the @var{library} argument.
3829 @var{action-if-found} is a list of shell commands to run if the link
3830 with the library succeeds; @var{action-if-not-found} is a list of shell
3831 commands to run if the link fails.  If @var{action-if-found} is not
3832 specified, the default action will prepend @option{-l@var{library}} to
3833 @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3834 capitals).  This macro is intended to support building @code{LIBS} in
3835 a right-to-left (least-dependent to most-dependent) fashion such that
3836 library dependencies are satisfied as a natural side-effect of
3837 consecutive tests.  Some linkers are very sensitive to library ordering
3838 so the order in which @code{LIBS} is generated is important to reliable
3839 detection of libraries.
3841 If linking with @var{library} results in unresolved symbols that would
3842 be resolved by linking with additional libraries, give those libraries
3843 as the @var{other-libraries} argument, separated by spaces:
3844 e.g., @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
3845 that @var{library} is present, because linking the test program will
3846 always fail with unresolved symbols.  The @var{other-libraries} argument
3847 should be limited to cases where it is desirable to test for one library
3848 in the presence of another that is not already in @code{LIBS}.
3850 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
3851 in some common cases.  Many standard functions like @code{gethostbyname}
3852 appear the standard C library on some hosts, and in special libraries
3853 like @code{nsl} on other hosts.  On some hosts the special libraries
3854 contain variant implementations that you may not want to use.  These
3855 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
3856 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
3857 @end defmac
3860 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3861 @acindex{SEARCH_LIBS}
3862 Search for a library defining @var{function} if it's not already
3863 available.  This equates to calling
3864 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
3865 no libraries, then for each library listed in @var{search-libs}.
3867 Add @option{-l@var{library}} to @code{LIBS} for the first library found
3868 to contain @var{function}, and run @var{action-if-found}.  If the
3869 function is not found, run @var{action-if-not-found}.
3871 If linking with @var{library} results in unresolved symbols that would
3872 be resolved by linking with additional libraries, give those libraries
3873 as the @var{other-libraries} argument, separated by spaces:
3874 e.g., @option{-lXt -lX11}.  Otherwise, this macro will fail to detect
3875 that @var{function} is present, because linking the test program will
3876 always fail with unresolved symbols.
3877 @end defmac
3881 @node Library Functions
3882 @section Library Functions
3884 The following macros check for particular C library functions.
3885 If there is no macro specifically defined to check for a function you need,
3886 and you don't need to check for any special properties of
3887 it, then you can use one of the general function-check macros.
3889 @menu
3890 * Function Portability::        Pitfalls with usual functions
3891 * Particular Functions::        Special handling to find certain functions
3892 * Generic Functions::           How to find other functions
3893 @end menu
3895 @node Function Portability
3896 @subsection Portability of C Functions
3897 @cindex Portability of C functions
3898 @cindex C function portability
3900 Most usual functions can either be missing, or be buggy, or be limited
3901 on some architectures.  This section tries to make an inventory of these
3902 portability issues.  By definition, this list will always require
3903 additions.  Please help us keeping it as complete as possible.
3905 @table @asis
3906 @item @code{exit}
3907 @c @fuindex exit
3908 @prindex @code{exit}
3909 On ancient hosts, @code{exit} returned @code{int}.
3910 This is because @code{exit} predates @code{void}, and there was a long
3911 tradition of it returning @code{int}.
3913 On more-modern hosts, the problem more likely is that @code{exit} is not
3914 declared, due to C++ problems of some sort or another.  For this reason
3915 we suggest that test programs not invoke @code{exit}, but return from
3916 @code{main} instead.
3918 @item @code{free}
3919 @c @fuindex free
3920 @prindex @code{free}
3921 The C standard says a call @code{free (NULL)} does nothing, but
3922 some old systems don't support this (e.g., NextStep).
3924 @item @code{isinf}
3925 @itemx @code{isnan}
3926 @c @fuindex isinf
3927 @c @fuindex isnan
3928 @prindex @code{isinf}
3929 @prindex @code{isnan}
3930 The C99 standard says that @code{isinf} and @code{isnan} are
3931 macros.  On some systems just macros are available (e.g., HP-UX), on
3932 some systems both macros and functions (e.g., glibc 2.3.2), and on some
3933 systems only functions (e.g., IRIX 6 and Solaris 9).  In some cases
3934 these functions are declared in nonstandard headers like
3935 @code{<sunmath.h>} and defined in non-default libraries like
3936 @option{-lm} or @option{-lsunmath}.
3938 The C99 @code{isinf} and @code{isnan} macros work correctly with
3939 @code{long double} arguments, but pre-C99 systems that use functions
3940 typically assume @code{double} arguments.  On such a system,
3941 @code{isinf} incorrectly returns true for a finite @code{long double}
3942 argument that is outside the range of @code{double}.
3944 To work around this porting mess, you can use code like the following.
3946 @smallexample
3947 #include <math.h>
3949 #ifndef isnan
3950 # define isnan(x) \
3951     (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
3952      : sizeof (x) == sizeof (double) ? isnan_d (x) \
3953      : isnan_f (x))
3954 static inline int isnan_f  (float       x) @{ return x != x; @}
3955 static inline int isnan_d  (double      x) @{ return x != x; @}
3956 static inline int isnan_ld (long double x) @{ return x != x; @}
3957 #endif
3959 #ifndef isinf
3960 # define isinf(x) \
3961     (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
3962      : sizeof (x) == sizeof (double) ? isinf_d (x) \
3963      : isinf_f (x))
3964 static inline int isinf_f  (float       x) @{ return isnan (x - x); @}
3965 static inline int isinf_d  (double      x) @{ return isnan (x - x); @}
3966 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
3967 #endif
3968 @end smallexample
3970 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
3971 compilers that lack the @code{inline} keyword.  Some optimizing
3972 compilers mishandle these definitions, but systems with that bug
3973 typically have missing or broken @code{isnan} functions anyway, so it's
3974 probably not worth worrying about.
3976 @item @code{malloc}
3977 @c @fuindex malloc
3978 @prindex @code{malloc}
3979 The C standard says a call @code{malloc (0)} is implementation
3980 dependent.  It may either return @code{NULL} (e.g., OSF 4) or
3981 non-@code{NULL} (e.g., @acronym{GNU} C Library).  @code{AC_FUNC_MALLOC}
3982 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
3984 @item @code{putenv}
3985 @c @fuindex putenv
3986 @prindex @code{putenv}
3987 Posix prefers @code{setenv} to @code{putenv}; among other things,
3988 @code{putenv} is not required of all Posix implementations, but
3989 @code{setenv} is.
3991 Posix specifies that @code{putenv} puts the given string directly in
3992 @code{environ}, but some systems make a copy of it instead (e.g.,
3993 glibc 2.0, or @acronym{BSD}).  And when a copy is made, @code{unsetenv} might
3994 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
3996 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
3997 environment, but this is not standard usage and it dumps core
3998 on some systems (e.g., AIX).
4000 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4001 environment, rather than inserting it with an empty value.
4003 @item @code{realloc}
4004 @c @fuindex realloc
4005 @prindex @code{realloc}
4006 The C standard says a call @code{realloc (NULL, size)} is equivalent
4007 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4008 NextStep).
4010 @item @code{signal} handler
4011 @c @fuindex signal
4012 @prindex @code{signal}
4013 Normally @code{signal} takes a handler function with a return type of
4014 @code{void}, but some old systems required @code{int} instead.  Any
4015 actual @code{int} value returned is not used; this is only a
4016 difference in the function prototype demanded.
4018 All systems we know of in current use return @code{void}.  The
4019 @code{int} was to support K&R C, where of course @code{void} is not
4020 available.  @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4021 used to establish the correct type in all cases.
4023 @item @code{snprintf}
4024 @c @fuindex snprintf
4025 @prindex @code{snprintf}
4026 @c @fuindex vsnprintf
4027 @prindex @code{vsnprintf}
4028 The C99 standard says that if the output array isn't big enough
4029 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4030 truncate the output and return the number of bytes that ought to have
4031 been produced.  Some older systems return the truncated length (e.g.,
4032 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4033 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4034 length without truncation (e.g., 32-bit Solaris 7).  Also, some buggy
4035 older systems ignore the length and overrun the buffer (e.g., 64-bit
4036 Solaris 7).
4038 @item @code{sprintf}
4039 @c @fuindex sprintf
4040 @prindex @code{sprintf}
4041 @c @fuindex vsprintf
4042 @prindex @code{vsprintf}
4043 The C standard says @code{sprintf} and @code{vsprintf} return the
4044 number of bytes written, but on some ancient systems (SunOS 4 for
4045 instance) they return the buffer pointer instead.
4047 @item @code{sscanf}
4048 @c @fuindex sscanf
4049 @prindex @code{sscanf}
4050 On various old systems, e.g., HP-UX 9, @code{sscanf} requires that its
4051 input string be writable (though it doesn't actually change it).  This
4052 can be a problem when using @command{gcc} since it normally puts
4053 constant strings in read-only memory
4054 (@pxref{Incompatibilities, Incompatibilities of GCC, , gcc, Using and
4055 Porting the @acronym{GNU} Compiler Collection}).  Apparently in some cases even
4056 having format strings read-only can be a problem.
4058 @item @code{strerror_r}
4059 @c @fuindex strerror_r
4060 @prindex @code{strerror_r}
4061 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4062 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4063 different version returning a @code{char *}.  @code{AC_FUNC_STRERROR_R}
4064 can detect which is in use (@pxref{Particular Functions}).
4066 @item @code{strnlen}
4067 @c @fuindex strnlen
4068 @prindex @code{strnlen}
4069 @acronym{AIX} 4.3 provides a broken version which produces the
4070 following results:
4072 @example
4073 strnlen ("foobar", 0) = 0
4074 strnlen ("foobar", 1) = 3
4075 strnlen ("foobar", 2) = 2
4076 strnlen ("foobar", 3) = 1
4077 strnlen ("foobar", 4) = 0
4078 strnlen ("foobar", 5) = 6
4079 strnlen ("foobar", 6) = 6
4080 strnlen ("foobar", 7) = 6
4081 strnlen ("foobar", 8) = 6
4082 strnlen ("foobar", 9) = 6
4083 @end example
4085 @item @code{sysconf}
4086 @c @fuindex sysconf
4087 @prindex @code{sysconf}
4088 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
4089 9) have @code{_SC_PAGE_SIZE} instead.  This can be tested with
4090 @code{#ifdef}.
4092 @item @code{unlink}
4093 @c @fuindex unlink
4094 @prindex @code{unlink}
4095 The Posix spec says that @code{unlink} causes the given file to be
4096 removed only after there are no more open file handles for it.  Some
4097 non-Posix hosts have trouble with this requirement, though,
4098 and some @acronym{DOS} variants even corrupt the file system.
4100 @item @code{unsetenv}
4101 @c @fuindex unsetenv
4102 @prindex @code{unsetenv}
4103 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4104 can be removed with a call @code{putenv ("FOO=")}, as described under
4105 @code{putenv} above.
4107 @item @code{va_copy}
4108 @c @fuindex va_copy
4109 @prindex @code{va_copy}
4110 The C99 standard provides @code{va_copy} for copying
4111 @code{va_list} variables.  It may be available in older environments
4112 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4113 pre-C99 mode).  These can be tested with @code{#ifdef}.  A fallback to
4114 @code{memcpy (&dst, &src, sizeof (va_list))} will give maximum
4115 portability.
4117 @item @code{va_list}
4118 @c @fuindex va_list
4119 @prindex @code{va_list}
4120 @code{va_list} is not necessarily just a pointer.  It can be a
4121 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4122 not portable.  Or it can be an array (e.g., @command{gcc} in some
4123 PowerPC configurations), which means as a function parameter it can be
4124 effectively call-by-reference and library routines might modify the
4125 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4126 2.1).
4128 @item Signed @code{>>}
4129 Normally the C @code{>>} right shift of a signed type replicates the
4130 high bit, giving a so-called ``arithmetic'' shift.  But care should be
4131 taken since Standard C doesn't require that behavior.  On those
4132 few processors without a native arithmetic shift (for instance Cray
4133 vector systems) zero bits may be shifted in, the same as a shift of an
4134 unsigned type.
4136 @item Integer @code{/}
4137 C divides signed integers by truncating their quotient toward zero,
4138 yielding the same result as Fortran.  However, before C99 the standard
4139 allowed C implementations to take the floor or ceiling of the quotient
4140 in some cases.  Hardly any implementations took advantage of this
4141 freedom, though, and it's probably not worth worrying about this issue
4142 nowadays.
4143 @end table
4146 @node Particular Functions
4147 @subsection Particular Function Checks
4148 @cindex Function, checking
4150 These macros check for particular C functions---whether they exist, and
4151 in some cases how they respond when given certain arguments.
4153 @defmac AC_FUNC_ALLOCA
4154 @acindex{FUNC_ALLOCA}
4155 @cvindex C_ALLOCA
4156 @cvindex HAVE_ALLOCA_H
4157 @ovindex ALLOCA
4158 @c @fuindex alloca
4159 @prindex @code{alloca}
4160 @hdrindex{alloca.h}
4161 Check how to get @code{alloca}.  Tries to get a builtin version by
4162 checking for @file{alloca.h} or the predefined C preprocessor macros
4163 @code{__GNUC__} and @code{_AIX}.  If this macro finds @file{alloca.h},
4164 it defines @code{HAVE_ALLOCA_H}.
4166 If those attempts fail, it looks for the function in the standard C
4167 library.  If any of those methods succeed, it defines
4168 @code{HAVE_ALLOCA}.  Otherwise, it sets the output variable
4169 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4170 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4171 garbage collect).  This variable is separate from @code{LIBOBJS} so
4172 multiple programs can share the value of @code{ALLOCA} without needing
4173 to create an actual library, in case only some of them use the code in
4174 @code{LIBOBJS}.  The @samp{$@{LIBOBJDIR@}} prefix serves the same
4175 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4177 This macro does not try to get @code{alloca} from the System V R3
4178 @file{libPW} or the System V R4 @file{libucb} because those libraries
4179 contain some incompatible functions that cause trouble.  Some versions
4180 do not even contain @code{alloca} or contain a buggy version.  If you
4181 still want to use their @code{alloca}, use @code{ar} to extract
4182 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4184 Source files that use @code{alloca} should start with a piece of code
4185 like the following, to declare it properly.
4187 @example
4188 @group
4189 #if HAVE_ALLOCA_H
4190 # include <alloca.h>
4191 #elif defined __GNUC__
4192 # define alloca __builtin_alloca
4193 #elif defined _AIX
4194 # define alloca __alloca
4195 #elif defined _MSC_VER
4196 # include <malloc.h>
4197 # define alloca _alloca
4198 #else
4199 # include <stddef.h>
4200 # ifdef  __cplusplus
4201 extern "C"
4202 # endif
4203 void *alloca (size_t);
4204 #endif
4205 @end group
4206 @end example
4207 @end defmac
4209 @defmac AC_FUNC_CHOWN
4210 @acindex{FUNC_CHOWN}
4211 @c @fuindex chown
4212 @prindex @code{chown}
4213 If the @code{chown} function is available and works (in particular, it
4214 should accept @option{-1} for @code{uid} and @code{gid}), define
4215 @code{HAVE_CHOWN}.
4216 @end defmac
4219 @defmac AC_FUNC_CLOSEDIR_VOID
4220 @acindex{FUNC_CLOSEDIR_VOID}
4221 @cvindex CLOSEDIR_VOID
4222 @c @fuindex closedir
4223 @prindex @code{closedir}
4224 If the @code{closedir} function does not return a meaningful value,
4225 define @code{CLOSEDIR_VOID}.  Otherwise, callers ought to check its
4226 return value for an error indicator.
4228 Currently this test is implemented by running a test program.  When
4229 cross compiling the pessimistic assumption that @code{closedir} does not
4230 return a meaningful value is made.
4231 @end defmac
4233 @defmac AC_FUNC_ERROR_AT_LINE
4234 @acindex{FUNC_ERROR_AT_LINE}
4235 @c @fuindex error_at_line
4236 @prindex @code{error_at_line}
4237 If the @code{error_at_line} function is not found, require an
4238 @code{AC_LIBOBJ} replacement of @samp{error}.
4239 @end defmac
4241 @defmac AC_FUNC_FNMATCH
4242 @acindex{FUNC_FNMATCH}
4243 @c @fuindex fnmatch
4244 @prindex @code{fnmatch}
4245 If the @code{fnmatch} function conforms to Posix, define
4246 @code{HAVE_FNMATCH}.  Detect common implementation bugs, for example,
4247 the bugs in Solaris 2.4.
4249 Note that for historical reasons, contrary to the other specific
4250 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4251 broken/missing @code{fnmatch}.  See @code{AC_REPLACE_FNMATCH} below.
4252 @end defmac
4254 @defmac AC_FUNC_FNMATCH_GNU
4255 @acindex{FUNC_FNMATCH_GNU}
4256 @c @fuindex fnmatch
4257 @prindex @code{fnmatch}
4258 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4259 whether @code{fnmatch} supports @acronym{GNU} extensions.  Detect common
4260 implementation bugs, for example, the bugs in the @acronym{GNU} C
4261 Library 2.1.
4262 @end defmac
4264 @defmac AC_FUNC_FORK
4265 @acindex{FUNC_FORK}
4266 @cvindex HAVE_VFORK_H
4267 @cvindex HAVE_WORKING_FORK
4268 @cvindex HAVE_WORKING_VFORK
4269 @cvindex vfork
4270 @c @fuindex fork
4271 @prindex @code{fork}
4272 @c @fuindex vfork
4273 @prindex @code{vfork}
4274 @hdrindex{vfork.h}
4275 This macro checks for the @code{fork} and @code{vfork} functions.  If a
4276 working @code{fork} is found, define @code{HAVE_WORKING_FORK}.  This macro
4277 checks whether @code{fork} is just a stub by trying to run it.
4279 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}.  If a working
4280 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}.  Otherwise,
4281 define @code{vfork} to be @code{fork} for backward compatibility with
4282 previous versions of @command{autoconf}.  This macro checks for several known
4283 errors in implementations of @code{vfork} and considers the system to not
4284 have a working @code{vfork} if it detects any of them.  It is not considered
4285 to be an implementation error if a child's invocation of @code{signal}
4286 modifies the parent's signal handler, since child processes rarely change
4287 their signal handlers.
4289 Since this macro defines @code{vfork} only for backward compatibility with
4290 previous versions of @command{autoconf} you're encouraged to define it
4291 yourself in new code:
4292 @example
4293 @group
4294 #if !HAVE_WORKING_VFORK
4295 # define vfork fork
4296 #endif
4297 @end group
4298 @end example
4299 @end defmac
4301 @defmac AC_FUNC_FSEEKO
4302 @acindex{FUNC_FSEEKO}
4303 @cvindex _LARGEFILE_SOURCE
4304 @c @fuindex fseeko
4305 @prindex @code{fseeko}
4306 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4307 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4308 visible on some systems (e.g., glibc 2.2).  Otherwise linkage problems
4309 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4310 largefile-sensitive systems where @code{off_t} does not default to a
4311 64bit entity.
4312 @end defmac
4314 @defmac AC_FUNC_GETGROUPS
4315 @acindex{FUNC_GETGROUPS}
4316 @ovindex GETGROUPS_LIBS
4317 @c @fuindex getgroups
4318 @prindex @code{getgroups}
4319 If the @code{getgroups} function is available and works (unlike on
4320 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4321 @code{HAVE_GETGROUPS}.  Set @code{GETGROUPS_LIBS} to any libraries
4322 needed to get that function.  This macro runs @code{AC_TYPE_GETGROUPS}.
4323 @end defmac
4325 @defmac AC_FUNC_GETLOADAVG
4326 @acindex{FUNC_GETLOADAVG}
4327 @cvindex SVR4
4328 @cvindex DGUX
4329 @cvindex UMAX
4330 @cvindex UMAX4_3
4331 @cvindex HAVE_NLIST_H
4332 @cvindex NLIST_NAME_UNION
4333 @cvindex GETLODAVG_PRIVILEGED
4334 @cvindex NEED_SETGID
4335 @cvindex C_GETLOADAVG
4336 @ovindex LIBOBJS
4337 @ovindex NEED_SETGID
4338 @ovindex KMEM_GROUP
4339 @ovindex GETLOADAVG_LIBS
4340 @c @fuindex getloadavg
4341 @prindex @code{getloadavg}
4342 Check how to get the system load averages.  To perform its tests
4343 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4344 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4345 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4347 If the system has the @code{getloadavg} function, define
4348 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4349 necessary to get that function.  Also add @code{GETLOADAVG_LIBS} to
4350 @code{LIBS}.  Otherwise, require an @code{AC_LIBOBJ} replacement for
4351 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4352 possibly define several other C preprocessor macros and output
4353 variables:
4355 @enumerate
4356 @item
4357 Define @code{C_GETLOADAVG}.
4359 @item
4360 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4361 those systems.
4363 @item
4364 @hdrindex{nlist.h}
4365 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4367 @item
4368 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4369 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}.  The obsolete symbol
4370 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4372 @item
4373 Programs may need to be installed setgid (or setuid) for
4374 @code{getloadavg} to work.  In this case, define
4375 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4376 to @samp{true} (and otherwise to @samp{false}), and set
4377 @code{KMEM_GROUP} to the name of the group that should own the installed
4378 program.
4379 @end enumerate
4380 @end defmac
4382 @defmac AC_FUNC_GETMNTENT
4383 @acindex{FUNC_GETMNTENT}
4384 @cvindex HAVE_GETMNTENT
4385 @c @fuindex getmntent
4386 @prindex @code{getmntent}
4387 Check for @code{getmntent} in the standard C library, and then in the
4388 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4389 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively.  Then, if
4390 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4391 @end defmac
4393 @defmac AC_FUNC_GETPGRP
4394 @acindex{FUNC_GETPGRP}
4395 @cvindex GETPGRP_VOID
4396 @c @fuindex getpgid
4397 @c @fuindex getpgrp
4398 @prindex @code{getpgid}
4399 @prindex @code{getpgrp}
4400 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4401 @code{getpgrp}; this is the Posix behavior.  On older @acronym{BSD}
4402 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4403 behaves like Posix's @code{getpgid}.
4405 @example
4406 #if GETPGRP_VOID
4407   pid = getpgrp ();
4408 #else
4409   pid = getpgrp (0);
4410 #endif
4411 @end example
4413 This macro does not check whether
4414 @code{getpgrp} exists at all; if you need to work in that situation,
4415 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4416 @end defmac
4418 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4419 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4420 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4421 @c @fuindex lstat
4422 @prindex @code{lstat}
4423 If @file{link} is a symbolic link, then @code{lstat} should treat
4424 @file{link/} the same as @file{link/.}.  However, many older
4425 @code{lstat} implementations incorrectly ignore trailing slashes.
4427 It is safe to assume that if @code{lstat} incorrectly ignores
4428 trailing slashes, then other symbolic-link-aware functions like
4429 @code{unlink} also incorrectly ignore trailing slashes.
4431 If @code{lstat} behaves properly, define
4432 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4433 @code{AC_LIBOBJ} replacement of @code{lstat}.
4434 @end defmac
4436 @defmac AC_FUNC_MALLOC
4437 @acindex{FUNC_MALLOC}
4438 @cvindex HAVE_MALLOC
4439 @cvindex malloc
4440 @c @fuindex malloc
4441 @prindex @code{malloc}
4442 If the @code{malloc} function is compatible with the @acronym{GNU} C
4443 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4444 pointer), define @code{HAVE_MALLOC} to 1.  Otherwise define
4445 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4446 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4447 native @code{malloc} is not used in the main project.
4449 Typically, the replacement file @file{malloc.c} should look like (note
4450 the @samp{#undef malloc}):
4452 @verbatim
4453 #if HAVE_CONFIG_H
4454 # include <config.h>
4455 #endif
4456 #undef malloc
4458 #include <sys/types.h>
4460 void *malloc ();
4462 /* Allocate an N-byte block of memory from the heap.
4463    If N is zero, allocate a 1-byte block.  */
4465 void *
4466 rpl_malloc (size_t n)
4468   if (n == 0)
4469     n = 1;
4470   return malloc (n);
4472 @end verbatim
4473 @end defmac
4475 @defmac AC_FUNC_MEMCMP
4476 @acindex{FUNC_MEMCMP}
4477 @ovindex LIBOBJS
4478 @c @fuindex memcmp
4479 @prindex @code{memcmp}
4480 If the @code{memcmp} function is not available, or does not work on
4481 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4482 bytes or more and with at least one buffer not starting on a 4-byte
4483 boundary (such as the one on NeXT x86 OpenStep), require an
4484 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4485 @end defmac
4487 @defmac AC_FUNC_MBRTOWC
4488 @acindex{FUNC_MBRTOWC}
4489 @cvindex HAVE_MBRTOWC
4490 @c @fuindex mbrtowc
4491 @prindex @code{mbrtowc}
4492 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4493 type @code{mbstate_t} are properly declared.
4494 @end defmac
4496 @defmac AC_FUNC_MKTIME
4497 @acindex{FUNC_MKTIME}
4498 @ovindex LIBOBJS
4499 @c @fuindex mktime
4500 @prindex @code{mktime}
4501 If the @code{mktime} function is not available, or does not work
4502 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4503 For the purposes of this test, @code{mktime} should conform to the
4504 Posix standard and should be the inverse of
4505 @code{localtime}.
4506 @end defmac
4508 @defmac AC_FUNC_MMAP
4509 @acindex{FUNC_MMAP}
4510 @cvindex HAVE_MMAP
4511 @c @fuindex mmap
4512 @prindex @code{mmap}
4513 If the @code{mmap} function exists and works correctly, define
4514 @code{HAVE_MMAP}.  Only checks private fixed mapping of already-mapped
4515 memory.
4516 @end defmac
4518 @defmac AC_FUNC_OBSTACK
4519 @acindex{FUNC_OBSTACK}
4520 @cvindex HAVE_OBSTACK
4521 @cindex obstack
4522 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4523 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4524 @end defmac
4526 @defmac AC_FUNC_REALLOC
4527 @acindex{FUNC_REALLOC}
4528 @cvindex HAVE_REALLOC
4529 @cvindex realloc
4530 @c @fuindex realloc
4531 @prindex @code{realloc}
4532 If the @code{realloc} function is compatible with the @acronym{GNU} C
4533 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4534 valid pointer), define @code{HAVE_REALLOC} to 1.  Otherwise define
4535 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4536 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4537 the native @code{realloc} is not used in the main project.  See
4538 @code{AC_FUNC_MALLOC} for details.
4539 @end defmac
4541 @defmac AC_FUNC_SELECT_ARGTYPES
4542 @acindex{FUNC_SELECT_ARGTYPES}
4543 @cvindex SELECT_TYPE_ARG1
4544 @cvindex SELECT_TYPE_ARG234
4545 @cvindex SELECT_TYPE_ARG5
4546 @c @fuindex select
4547 @prindex @code{select}
4548 Determines the correct type to be passed for each of the
4549 @code{select} function's arguments, and defines those types
4550 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4551 @code{SELECT_TYPE_ARG5} respectively.  @code{SELECT_TYPE_ARG1} defaults
4552 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4553 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4554 @end defmac
4556 @defmac AC_FUNC_SETPGRP
4557 @acindex{FUNC_SETPGRP}
4558 @cvindex SETPGRP_VOID
4559 @c @fuindex setpgrp
4560 @prindex @code{setpgrp}
4561 If @code{setpgrp} takes no argument (the Posix version), define
4562 @code{SETPGRP_VOID}.  Otherwise, it is the @acronym{BSD} version, which takes
4563 two process IDs as arguments.  This macro does not check whether
4564 @code{setpgrp} exists at all; if you need to work in that situation,
4565 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4566 @end defmac
4568 @defmac AC_FUNC_STAT
4569 @defmacx AC_FUNC_LSTAT
4570 @acindex{FUNC_STAT}
4571 @acindex{FUNC_LSTAT}
4572 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4573 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4574 @c @fuindex stat
4575 @prindex @code{stat}
4576 @c @fuindex lstat
4577 @prindex @code{lstat}
4578 Determine whether @code{stat} or @code{lstat} have the bug that it
4579 succeeds when given the zero-length file name as argument.  The @code{stat}
4580 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4581 this.
4583 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4584 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4585 replacement of it.
4586 @end defmac
4588 @defmac AC_FUNC_SETVBUF_REVERSED
4589 @acindex{FUNC_SETVBUF_REVERSED}
4590 @cvindex SETVBUF_REVERSED
4591 @c @fuindex setvbuf
4592 @prindex @code{setvbuf}
4593 If @code{setvbuf} takes the buffering type as its second argument and
4594 the buffer pointer as the third, instead of the other way around, define
4595 @code{SETVBUF_REVERSED}.
4596 @end defmac
4598 @defmac AC_FUNC_STRCOLL
4599 @acindex{FUNC_STRCOLL}
4600 @cvindex HAVE_STRCOLL
4601 @c @fuindex strcoll
4602 @prindex @code{strcoll}
4603 If the @code{strcoll} function exists and works correctly, define
4604 @code{HAVE_STRCOLL}.  This does a bit more than
4605 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4606 definitions of @code{strcoll} that should not be used.
4607 @end defmac
4609 @defmac AC_FUNC_STRERROR_R
4610 @acindex{FUNC_STRERROR_R}
4611 @cvindex HAVE_STRERROR_R
4612 @cvindex HAVE_DECL_STRERROR_R
4613 @cvindex STRERROR_R_CHAR_P
4614 @c @fuindex strerror_r
4615 @prindex @code{strerror_r}
4616 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4617 it is declared, define @code{HAVE_DECL_STRERROR_R}.  If it returns a
4618 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4619 returns an @code{int} error number.  The Thread-Safe Functions option of
4620 Posix requires @code{strerror_r} to return @code{int}, but
4621 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4622 Library) return a @code{char *} value that is not necessarily equal to
4623 the buffer argument.
4624 @end defmac
4626 @defmac AC_FUNC_STRFTIME
4627 @acindex{FUNC_STRFTIME}
4628 @cvindex HAVE_STRFTIME
4629 @c @fuindex strftime
4630 @prindex @code{strftime}
4631 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4632 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4633 @end defmac
4635 @defmac AC_FUNC_STRTOD
4636 @acindex{FUNC_STRTOD}
4637 @ovindex POW_LIB
4638 @c @fuindex strtod
4639 @prindex @code{strtod}
4640 If the @code{strtod} function does not exist or doesn't work correctly,
4641 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}.  In this case,
4642 because @file{strtod.c} is likely to need @samp{pow}, set the output
4643 variable @code{POW_LIB} to the extra library needed.
4644 @end defmac
4646 @defmac AC_FUNC_STRTOLD
4647 @acindex{FUNC_STRTOLD}
4648 @prindex @code{strtold}
4649 If the @code{strtold} function exists and conforms to C99, define
4650 @code{HAVE_STRTOLD}.
4651 @end defmac
4653 @defmac AC_FUNC_STRNLEN
4654 @acindex{FUNC_STRNLEN}
4655 @cvindex HAVE_STRNLEN
4656 @c @fuindex strnlen
4657 @prindex @code{strnlen}
4658 If the @code{strnlen} function is not available, or is buggy (like the one
4659 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4660 @end defmac
4662 @defmac AC_FUNC_UTIME_NULL
4663 @acindex{FUNC_UTIME_NULL}
4664 @cvindex HAVE_UTIME_NULL
4665 @c @fuindex utime
4666 @prindex @code{utime}
4667 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4668 the present, define @code{HAVE_UTIME_NULL}.
4669 @end defmac
4671 @defmac AC_FUNC_VPRINTF
4672 @acindex{FUNC_VPRINTF}
4673 @cvindex HAVE_VPRINTF
4674 @cvindex HAVE_DOPRNT
4675 @c @fuindex vprintf
4676 @prindex @code{vprintf}
4677 If @code{vprintf} is found, define @code{HAVE_VPRINTF}.  Otherwise, if
4678 @code{_doprnt} is found, define @code{HAVE_DOPRNT}.  (If @code{vprintf}
4679 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4680 are also available.)
4681 @end defmac
4683 @defmac AC_REPLACE_FNMATCH
4684 @acindex{REPLACE_FNMATCH}
4685 @c @fuindex fnmatch
4686 @prindex @code{fnmatch}
4687 @hdrindex{fnmatch.h}
4688 If the @code{fnmatch} function does not conform to Posix (see
4689 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4691 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4692 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4693 copy of the source code of @acronym{GNU} @code{fnmatch}.  If necessary,
4694 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4695 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4696 included in place of the system @code{<fnmatch.h>}.
4697 @end defmac
4701 @node Generic Functions
4702 @subsection Generic Function Checks
4704 These macros are used to find functions not covered by the ``particular''
4705 test macros.  If the functions might be in libraries other than the
4706 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4707 If you need to check the behavior of a function as well as find out
4708 whether it is present, you have to write your own test for
4709 it (@pxref{Writing Tests}).
4711 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4712 @acindex{CHECK_FUNC}
4713 If C function @var{function} is available, run shell commands
4714 @var{action-if-found}, otherwise @var{action-if-not-found}.  If you just
4715 want to define a symbol if the function is available, consider using
4716 @code{AC_CHECK_FUNCS} instead.  This macro checks for functions with C
4717 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4718 standardized than C++.  (@pxref{Language Choice}, for more information
4719 about selecting the language for checks.)
4720 @end defmac
4722 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4723 @acindex{CHECK_FUNCS}
4724 @cvindex HAVE_@var{function}
4725 For each @var{function} enumerated in the blank-or-newline-separated argument
4726 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4727 If @var{action-if-found} is given, it is additional shell code to
4728 execute when one of the functions is found.  You can give it a value of
4729 @samp{break} to break out of the loop on the first match.  If
4730 @var{action-if-not-found} is given, it is executed when one of the
4731 functions is not found.
4732 @end defmac
4734 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4735 @acindex{CHECK_FUNCS_ONCE}
4736 @cvindex HAVE_@var{function}
4737 For each @var{function} enumerated in the blank-or-newline-separated argument
4738 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4739 This is a once-only variant of @code{AC_CHECK_FUNCS}.  It generates the
4740 checking code at most once, so that @command{configure} is smaller and
4741 faster; but the checks cannot be conditionalized and are always done once,
4742 early during the @command{configure} run.
4743 @end defmac
4745 @sp 1
4747 Autoconf follows a philosophy that was formed over the years by those
4748 who have struggled for portability: isolate the portability issues in
4749 specific files, and then program as if you were in a Posix
4750 environment.  Some functions may be missing or unfixable, and your
4751 package must be ready to replace them.
4753 Suitable replacements for many such problem functions are available from
4754 Gnulib (@pxref{Gnulib}).
4756 @defmac AC_LIBOBJ (@var{function})
4757 @acindex{LIBOBJ}
4758 @ovindex LIBOBJS
4759 Specify that @samp{@var{function}.c} must be included in the executables
4760 to replace a missing or broken implementation of @var{function}.
4762 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4763 variable @code{LIBOBJS} if it is not already in, and calls
4764 @code{AC_LIBSOURCE} for @samp{@var{function}.c}.  You should not
4765 directly change @code{LIBOBJS}, since this is not traceable.
4766 @end defmac
4768 @defmac AC_LIBSOURCE (@var{file})
4769 @acindex{LIBSOURCE}
4770 Specify that @var{file} might be needed to compile the project.  If you
4771 need to know what files might be needed by a @file{configure.ac}, you
4772 should trace @code{AC_LIBSOURCE}.  @var{file} must be a literal.
4774 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4775 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}.  In
4776 that case, since shell variables cannot be traced statically, you must
4777 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4778 might cause @code{AC_LIBOBJ} to need.  For example, if you want to pass
4779 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4780 @code{"foo"} or @code{"bar"}, you should do:
4782 @example
4783 AC_LIBSOURCE([foo.c])
4784 AC_LIBSOURCE([bar.c])
4785 AC_LIBOBJ([$foo_or_bar])
4786 @end example
4788 @noindent
4789 There is usually a way to avoid this, however, and you are encouraged to
4790 simply call @code{AC_LIBOBJ} with literal arguments.
4792 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4793 slightly different semantics: the old macro took the function name,
4794 e.g., @code{foo}, as its argument rather than the file name.
4795 @end defmac
4797 @defmac AC_LIBSOURCES (@var{files})
4798 @acindex{LIBSOURCES}
4799 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
4800 comma-separated M4 list.  Thus, the above example might be rewritten:
4802 @example
4803 AC_LIBSOURCES([foo.c, bar.c])
4804 AC_LIBOBJ([$foo_or_bar])
4805 @end example
4806 @end defmac
4808 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
4809 @acindex{CONFIG_LIBOBJ_DIR}
4810 Specify that @code{AC_LIBOBJ} replacement files are to be found in
4811 @var{directory}, a name relative to the top level of the
4812 source tree.  The replacement directory defaults to @file{.}, the top
4813 level directory, and the most typical value is @file{lib}, corresponding
4814 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
4816 @command{configure} might need to know the replacement directory for the
4817 following reasons: (i) some checks use the replacement files, (ii) some
4818 macros bypass broken system headers by installing links to the
4819 replacement headers (iii) when used in conjunction with Automake,
4820 within each @file{Makefile}, @var{directory} is used as a relative path
4821 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
4822 @code{LTLIBOBJS}, etc.
4823 @end defmac
4825 @sp 1
4827 It is common to merely check for the existence of a function, and ask
4828 for its @code{AC_LIBOBJ} replacement if missing.  The following macro is
4829 a convenient shorthand.
4831 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
4832 @acindex{REPLACE_FUNCS}
4833 @ovindex LIBOBJS
4834 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
4835 @var{action-if-not-found}.  You can declare your replacement function by
4836 enclosing the prototype in @samp{#if !HAVE_@var{function}}.  If the
4837 system has the function, it probably declares it in a header file you
4838 should be including, so you shouldn't redeclare it lest your declaration
4839 conflict.
4840 @end defmac
4842 @node Header Files
4843 @section Header Files
4844 @cindex Header, checking
4846 The following macros check for the presence of certain C header files.
4847 If there is no macro specifically defined to check for a header file you need,
4848 and you don't need to check for any special properties of
4849 it, then you can use one of the general header-file check macros.
4851 @menu
4852 * Header Portability::          Collected knowledge on common headers
4853 * Particular Headers::          Special handling to find certain headers
4854 * Generic Headers::             How to find other headers
4855 @end menu
4857 @node Header Portability
4858 @subsection Portability of Headers
4859 @cindex Portability of headers
4860 @cindex Header portability
4862 This section tries to collect knowledge about common headers, and the
4863 problems they cause.  By definition, this list will always require
4864 additions.  Please help us keeping it as complete as possible.
4866 @table @asis
4868 @item @file{limits.h}
4869 C99 says that @file{limits.h} defines @code{LLONG_MIN},
4870 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
4871 environments (e.g., default GCC 4.0.2 + glibc 2.4) do not define them.
4873 @item @file{inttypes.h} vs.@: @file{stdint.h}
4874 @hdrindex{inttypes.h}
4875 @hdrindex{stdint.h}
4876 The C99 standard says that @file{inttypes.h} includes
4877 @file{stdint.h}, so there's no need to include @file{stdint.h}
4878 separately in a standard environment.  Some implementations have
4879 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
4880 know of any implementation that has @file{stdint.h} but not
4881 @file{inttypes.h}.
4883 @item @file{linux/irda.h}
4884 @hdrindex{linux/irda.h}
4885 It requires @file{linux/types.h} and @file{sys/socket.h}.
4887 @item @file{linux/random.h}
4888 @hdrindex{linux/random.h}
4889 It requires @file{linux/types.h}.
4891 @item @file{net/if.h}
4892 @hdrindex{net/if.h}
4893 On Darwin, this file requires that @file{sys/socket.h} be included
4894 beforehand.  One should run:
4896 @example
4897 AC_CHECK_HEADERS([sys/socket.h])
4898 AC_CHECK_HEADERS([net/if.h], [], [],
4899 [#include <stdio.h>
4900 #if STDC_HEADERS
4901 # include <stdlib.h>
4902 # include <stddef.h>
4903 #else
4904 # if HAVE_STDLIB_H
4905 #  include <stdlib.h>
4906 # endif
4907 #endif
4908 #if HAVE_SYS_SOCKET_H
4909 # include <sys/socket.h>
4910 #endif
4912 @end example
4914 @item @file{netinet/if_ether.h}
4915 @hdrindex{netinet/if_ether.h}
4916 On Darwin, this file requires that @file{stdio.h} and
4917 @file{sys/socket.h} be included beforehand.  One should run:
4919 @example
4920 AC_CHECK_HEADERS([sys/socket.h])
4921 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
4922 [#include <stdio.h>
4923 #if STDC_HEADERS
4924 # include <stdlib.h>
4925 # include <stddef.h>
4926 #else
4927 # if HAVE_STDLIB_H
4928 #  include <stdlib.h>
4929 # endif
4930 #endif
4931 #if HAVE_SYS_SOCKET_H
4932 # include <sys/socket.h>
4933 #endif
4935 @end example
4937 @item @file{stdint.h}
4938 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
4940 @item @file{stdlib.h}
4941 @hdrindex{stdlib.h}
4942 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
4944 @item @file{sys/mount.h}
4945 @hdrindex{sys/mount.h}
4946 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
4947 @file{sys/params.h} is a prerequisite.
4949 @item @file{sys/ptem.h}
4950 @hdrindex{sys/ptem.h}
4951 On Solaris 8, @file{sys/stream.h} is a prerequisite.
4953 @item @file{sys/socket.h}
4954 @hdrindex{sys/socket.h}
4955 On Darwin, @file{stdlib.h} is a prerequisite.
4957 @item @file{sys/ucred.h}
4958 @hdrindex{sys/ucred.h}
4959 On HP Tru64 5.1, @file{sys/types.h} is a prerequisite.
4961 @item @file{X11/extensions/scrnsaver.h}
4962 @hdrindex{X11/extensions/scrnsaver.h}
4963 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
4964 so required that you might not even consider looking for it.
4966 @example
4967 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
4968 [[#include <X11/Xlib.h>
4970 @end example
4971 @end table
4974 @node Particular Headers
4975 @subsection Particular Header Checks
4977 These macros check for particular system header files---whether they
4978 exist, and in some cases whether they declare certain symbols.
4980 @defmac AC_HEADER_ASSERT
4981 @acindex{HEADER_ASSERT}
4982 @cvindex NDEBUG
4983 @hdrindex{assert.h}
4984 Check whether to enable assertions in the style of @file{assert.h}.
4985 Assertions are enabled by default, but the user can override this by
4986 invoking @command{configure} with the @option{--disable-assert} option.
4987 @end defmac
4989 @defmac AC_HEADER_DIRENT
4990 @acindex{HEADER_DIRENT}
4991 @cvindex HAVE_DIRENT_H
4992 @cvindex HAVE_NDIR_H
4993 @cvindex HAVE_SYS_DIR_H
4994 @cvindex HAVE_SYS_NDIR_H
4995 @hdrindex{dirent.h}
4996 @hdrindex{sys/ndir.h}
4997 @hdrindex{sys/dir.h}
4998 @hdrindex{ndir.h}
4999 Check for the following header files.  For the first one that is
5000 found and defines @samp{DIR}, define the listed C preprocessor macro:
5002 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5003 @item @file{dirent.h}   @tab @code{HAVE_DIRENT_H}
5004 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5005 @item @file{sys/dir.h}  @tab @code{HAVE_SYS_DIR_H}
5006 @item @file{ndir.h}     @tab @code{HAVE_NDIR_H}
5007 @end multitable
5009 The directory-library declarations in your source code should look
5010 something like the following:
5012 @example
5013 @group
5014 #include <sys/types.h>
5015 #ifdef HAVE_DIRENT_H
5016 # include <dirent.h>
5017 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5018 #else
5019 # define dirent direct
5020 # define NAMLEN(dirent) ((dirent)->d_namlen)
5021 # if HAVE_SYS_NDIR_H
5022 #  include <sys/ndir.h>
5023 # endif
5024 # if HAVE_SYS_DIR_H
5025 #  include <sys/dir.h>
5026 # endif
5027 # if HAVE_NDIR_H
5028 #  include <ndir.h>
5029 # endif
5030 #endif
5031 @end group
5032 @end example
5034 Using the above declarations, the program would declare variables to be
5035 of type @code{struct dirent}, not @code{struct direct}, and would access
5036 the length of a directory entry name by passing a pointer to a
5037 @code{struct dirent} to the @code{NAMLEN} macro.
5039 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5041 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5042 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5043 @end defmac
5045 @defmac AC_HEADER_MAJOR
5046 @acindex{HEADER_MAJOR}
5047 @cvindex MAJOR_IN_MKDEV
5048 @cvindex MAJOR_IN_SYSMACROS
5049 @hdrindex{sys/mkdev.h}
5050 @hdrindex{sys/sysmacros.h}
5051 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5052 @code{makedev}, but @file{sys/mkdev.h} does, define
5053 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5054 @code{MAJOR_IN_SYSMACROS}.
5055 @end defmac
5057 @defmac AC_HEADER_RESOLV
5058 @acindex{HEADER_RESOLV}
5059 @cvindex HAVE_RESOLV_H
5060 @hdrindex{resolv.h}
5061 Checks for header @file{resolv.h}, checking for prerequisites first.
5062 To properly use @file{resolv.h}, your code should contain something like
5063 the following:
5065 @verbatim
5066 #if HAVE_SYS_TYPES_H
5067 #  include <sys/types.h>
5068 #endif
5069 #ifdef HAVE_NETINET_IN_H
5070 #  include <netinet/in.h>   /* inet_ functions / structs */
5071 #endif
5072 #ifdef HAVE_ARPA_NAMESER_H
5073 #  include <arpa/nameser.h> /* DNS HEADER struct */
5074 #endif
5075 #ifdef HAVE_NETDB_H
5076 #  include <netdb.h>
5077 #endif
5078 #include <resolv.h>
5079 @end verbatim
5080 @end defmac
5082 @defmac AC_HEADER_STAT
5083 @acindex{HEADER_STAT}
5084 @cvindex STAT_MACROS_BROKEN
5085 @hdrindex{sys/stat.h}
5086 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5087 @file{sys/stat.h} do not work properly (returning false positives),
5088 define @code{STAT_MACROS_BROKEN}.  This is the case on Tektronix UTekV,
5089 Amdahl UTS and Motorola System V/88.
5090 @end defmac
5092 @defmac AC_HEADER_STDBOOL
5093 @acindex{HEADER_STDBOOL}
5094 @cvindex HAVE_STDBOOL_H
5095 @cvindex HAVE__BOOL
5096 @hdrindex{stdbool.h}
5097 @hdrindex{system.h}
5098 If @file{stdbool.h} exists and conforms to C99, define
5099 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5100 @code{HAVE__BOOL} to 1.  To fulfill the C99 requirements, your
5101 @file{system.h} could contain the following code:
5103 @verbatim
5104 #if HAVE_STDBOOL_H
5105 # include <stdbool.h>
5106 #else
5107 # if ! HAVE__BOOL
5108 #  ifdef __cplusplus
5109 typedef bool _Bool;
5110 #  else
5111 #   define _Bool signed char
5112 #  endif
5113 # endif
5114 # define bool _Bool
5115 # define false 0
5116 # define true 1
5117 # define __bool_true_false_are_defined 1
5118 #endif
5119 @end verbatim
5121 Alternatively you can use the @samp{stdbool} package of Gnulib
5122 (@pxref{Gnulib}); it packages the above code into a replacement header
5123 and contains a few other bells and whistles.
5125 @end defmac
5128 @defmac AC_HEADER_STDC
5129 @acindex{HEADER_STDC}
5130 @cvindex STDC_HEADERS
5131 @hdrindex{stdlib.h}
5132 @hdrindex{stdarg.h}
5133 @hdrindex{string.h}
5134 @hdrindex{float.h}
5135 @hdrindex{ctype.h}
5136 Define @code{STDC_HEADERS} if the system has C header files
5137 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5138 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5139 @file{string.h}, and @file{float.h}; if the system has those, it
5140 probably has the rest of the C89 header files.  This macro also
5141 checks whether @file{string.h} declares @code{memchr} (and thus
5142 presumably the other @code{mem} functions), whether @file{stdlib.h}
5143 declare @code{free} (and thus presumably @code{malloc} and other related
5144 functions), and whether the @file{ctype.h} macros work on characters
5145 with the high bit set, as the C standard requires.
5147 Nowadays this macro is becoming obsolete.  However, if you use it, your
5148 code can refer to @code{STDC_HEADERS} instead of @code{__STDC__} to
5149 determine whether the system has conforming header files (and probably C
5150 library functions).  This is useful if you worry about portability
5151 to ancient systems that lack C89 header files.
5153 @hdrindex{string.h}
5154 @hdrindex{strings.h}
5155 Nowadays @file{string.h} is part of the C standard and declares functions like
5156 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5157 @acronym{BSD} functions like @code{bcopy}; but
5158 historically, string functions were a major sticking point in this area.
5159 If you worry about portability to ancient systems without standard
5160 headers, there is so much variation
5161 that it is probably easier to declare the functions you use than to
5162 figure out exactly what the system header files declare.  Some ancient systems
5163 contain a mix of functions from the C standard and from @acronym{BSD}; some are
5164 mostly standard but lack @samp{memmove}; some define the
5165 @acronym{BSD} functions as macros in @file{string.h} or
5166 @file{strings.h}; some have only the @acronym{BSD} functions but
5167 @file{string.h}; some declare the memory functions in @file{memory.h},
5168 some in @file{string.h}; etc.  It is probably sufficient to check for
5169 one string function and one memory function; if the library has the
5170 standard versions of those then it probably has most of the others.
5171 If you put the following in @file{configure.ac}:
5173 @example
5174 AC_HEADER_STDC
5175 AC_CHECK_FUNCS([strchr memcpy])
5176 @end example
5178 @noindent
5179 then, in your code, you can use declarations like this:
5181 @example
5182 @group
5183 #if STDC_HEADERS
5184 # include <string.h>
5185 #else
5186 # if !HAVE_STRCHR
5187 #  define strchr index
5188 #  define strrchr rindex
5189 # endif
5190 char *strchr (), *strrchr ();
5191 # if !HAVE_MEMCPY
5192 #  define memcpy(d, s, n) bcopy ((s), (d), (n))
5193 #  define memmove(d, s, n) bcopy ((s), (d), (n))
5194 # endif
5195 #endif
5196 @end group
5197 @end example
5199 @noindent
5200 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5201 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
5202 suffice; you must provide an implementation of each function.  An easy
5203 way to incorporate your implementations only when needed (since the ones
5204 in system C libraries may be hand optimized) is to, taking @code{memchr}
5205 for example, put it in @file{memchr.c} and use
5206 @samp{AC_REPLACE_FUNCS([memchr])}.
5207 @end defmac
5209 @defmac AC_HEADER_SYS_WAIT
5210 @acindex{HEADER_SYS_WAIT}
5211 @cvindex HAVE_SYS_WAIT_H
5212 @hdrindex{sys/wait.h}
5213 If @file{sys/wait.h} exists and is compatible with Posix, define
5214 @code{HAVE_SYS_WAIT_H}.  Incompatibility can occur if @file{sys/wait.h}
5215 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5216 of @code{int} to store a status value.  If @file{sys/wait.h} is not
5217 Posix compatible, then instead of including it, define the
5218 Posix macros with their usual interpretations.  Here is an
5219 example:
5221 @example
5222 @group
5223 #include <sys/types.h>
5224 #if HAVE_SYS_WAIT_H
5225 # include <sys/wait.h>
5226 #endif
5227 #ifndef WEXITSTATUS
5228 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5229 #endif
5230 #ifndef WIFEXITED
5231 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5232 #endif
5233 @end group
5234 @end example
5235 @end defmac
5237 @cvindex _POSIX_VERSION
5238 @hdrindex{unistd.h}
5239 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5240 Posix systems.  If there is no @file{unistd.h}, it is definitely
5241 not a Posix system.  However, some non-Posix systems do
5242 have @file{unistd.h}.
5244 The way to check whether the system supports Posix is:
5246 @example
5247 @group
5248 #if HAVE_UNISTD_H
5249 # include <sys/types.h>
5250 # include <unistd.h>
5251 #endif
5253 #ifdef _POSIX_VERSION
5254 /* Code for Posix systems.  */
5255 #endif
5256 @end group
5257 @end example
5259 @defmac AC_HEADER_TIME
5260 @acindex{HEADER_TIME}
5261 @cvindex TIME_WITH_SYS_TIME
5262 @hdrindex{time.h}
5263 @hdrindex{sys/time.h}
5264 If a program may include both @file{time.h} and @file{sys/time.h},
5265 define @code{TIME_WITH_SYS_TIME}.  On some older systems,
5266 @file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
5267 protected against multiple inclusion, so programs should not explicitly
5268 include both files.  This macro is useful in programs that use, for
5269 example, @code{struct timeval} as well as
5270 @code{struct tm}.  It is best used in conjunction with
5271 @code{HAVE_SYS_TIME_H}, which can be checked for using
5272 @code{AC_CHECK_HEADERS([sys/time.h])}.
5274 @example
5275 @group
5276 #if TIME_WITH_SYS_TIME
5277 # include <sys/time.h>
5278 # include <time.h>
5279 #else
5280 # if HAVE_SYS_TIME_H
5281 #  include <sys/time.h>
5282 # else
5283 #  include <time.h>
5284 # endif
5285 #endif
5286 @end group
5287 @end example
5288 @end defmac
5291 @defmac AC_HEADER_TIOCGWINSZ
5292 @acindex{HEADER_TIOCGWINSZ}
5293 @cvindex GWINSZ_IN_SYS_IOCTL
5294 @hdrindex{sys/ioctl.h}
5295 @hdrindex{termios.h}
5296 @c FIXME: I need clarifications from Jim.
5297 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5298 define @code{GWINSZ_IN_SYS_IOCTL}.  Otherwise @code{TIOCGWINSZ} can be
5299 found in @file{<termios.h>}.
5301 Use:
5303 @example
5304 @group
5305 #if HAVE_TERMIOS_H
5306 # include <termios.h>
5307 #endif
5309 #if GWINSZ_IN_SYS_IOCTL
5310 # include <sys/ioctl.h>
5311 #endif
5312 @end group
5313 @end example
5314 @end defmac
5316 @node Generic Headers
5317 @subsection Generic Header Checks
5319 These macros are used to find system header files not covered by the
5320 ``particular'' test macros.  If you need to check the contents of a header
5321 as well as find out whether it is present, you have to write your own
5322 test for it (@pxref{Writing Tests}).
5324 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5325 @acindex{CHECK_HEADER}
5326 If the system header file @var{header-file} is compilable, execute shell
5327 commands @var{action-if-found}, otherwise execute
5328 @var{action-if-not-found}.  If you just want to define a symbol if the
5329 header file is available, consider using @code{AC_CHECK_HEADERS}
5330 instead.
5332 For compatibility issues with older versions of Autoconf, please read
5333 below.
5334 @end defmac
5336 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5337 @acindex{CHECK_HEADERS}
5338 @cvindex HAVE_@var{header}
5339 For each given system header file @var{header-file} in the
5340 blank-separated argument list that exists, define
5341 @code{HAVE_@var{header-file}} (in all capitals).  If @var{action-if-found}
5342 is given, it is additional shell code to execute when one of the header
5343 files is found.  You can give it a value of @samp{break} to break out of
5344 the loop on the first match.  If @var{action-if-not-found} is given, it
5345 is executed when one of the header files is not found.
5347 For compatibility issues with older versions of Autoconf, please read
5348 below.
5349 @end defmac
5351 Previous versions of Autoconf merely checked whether the header was
5352 accepted by the preprocessor.  This was changed because the old test was
5353 inappropriate for typical uses.  Headers are typically used to compile,
5354 not merely to preprocess, and the old behavior sometimes accepted
5355 headers that clashed at compile-time.  If you need to check whether a
5356 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5357 (@pxref{Running the Preprocessor}).
5359 This scheme, which improves the robustness of the test, also requires
5360 that you make sure that headers that must be included before the
5361 @var{header-file} be part of the @var{includes}, (@pxref{Default
5362 Includes}).  If looking for @file{bar.h}, which requires that
5363 @file{foo.h} be included before if it exists, we suggest the following
5364 scheme:
5366 @verbatim
5367 AC_CHECK_HEADERS([foo.h])
5368 AC_CHECK_HEADERS([bar.h], [], [],
5369 [#if HAVE_FOO_H
5370 # include <foo.h>
5371 # endif
5373 @end verbatim
5375 The following variant generates smaller, faster @command{configure}
5376 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5378 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5379 @acindex{CHECK_HEADERS_ONCE}
5380 @cvindex HAVE_@var{header}
5381 For each given system header file @var{header-file} in the
5382 blank-separated argument list that exists, define
5383 @code{HAVE_@var{header-file}} (in all capitals).
5384 This is a once-only variant of @code{AC_CHECK_HEADERS}.  It generates the
5385 checking code at most once, so that @command{configure} is smaller and
5386 faster; but the checks cannot be conditionalized and are always done once,
5387 early during the @command{configure} run.
5388 @end defmac
5390 @node Declarations
5391 @section Declarations
5392 @cindex Declaration, checking
5394 The following macros check for the declaration of variables and
5395 functions.  If there is no macro specifically defined to check for a
5396 symbol you need, then you can use the general macros (@pxref{Generic
5397 Declarations}) or, for more complex tests, you may use
5398 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5400 @menu
5401 * Particular Declarations::     Macros to check for certain declarations
5402 * Generic Declarations::        How to find other declarations
5403 @end menu
5405 @node Particular Declarations
5406 @subsection Particular Declaration Checks
5408 There are no specific macros for declarations.
5410 @node Generic Declarations
5411 @subsection Generic Declaration Checks
5413 These macros are used to find declarations not covered by the ``particular''
5414 test macros.
5416 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5417 @acindex{CHECK_DECL}
5418 If @var{symbol} (a function or a variable) is not declared in
5419 @var{includes} and a declaration is needed, run the shell commands
5420 @var{action-if-not-found}, otherwise @var{action-if-found}.  If no
5421 @var{includes} are specified, the default includes are used
5422 (@pxref{Default Includes}).
5424 This macro actually tests whether it is valid to use @var{symbol} as an
5425 r-value, not if it is really declared, because it is much safer to avoid
5426 introducing extra declarations when they are not needed.
5427 @end defmac
5429 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5430 @acindex{CHECK_DECLS}
5431 @cvindex HAVE_DECL_@var{symbol}
5432 For each of the @var{symbols} (@emph{comma}-separated list), define
5433 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5434 @var{symbol} is declared, otherwise to @samp{0}.  If
5435 @var{action-if-not-found} is given, it is additional shell code to
5436 execute when one of the function declarations is needed, otherwise
5437 @var{action-if-found} is executed.
5439 This macro uses an m4 list as first argument:
5440 @example
5441 AC_CHECK_DECLS([strdup])
5442 AC_CHECK_DECLS([strlen])
5443 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5444 @end example
5446 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5447 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5448 of leaving @code{HAVE_DECL_@var{symbol}} undeclared.  When you are
5449 @emph{sure} that the check was performed, use
5450 @code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
5452 @example
5453 #if !HAVE_DECL_SYMBOL
5454 extern char *symbol;
5455 #endif
5456 @end example
5458 @noindent
5459 If the test may have not been performed, however, because it is safer
5460 @emph{not} to declare a symbol than to use a declaration that conflicts
5461 with the system's one, you should use:
5463 @example
5464 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5465 void *malloc (size_t *s);
5466 #endif
5467 @end example
5469 @noindent
5470 You fall into the second category only in extreme situations: either
5471 your files may be used without being configured, or they are used during
5472 the configuration.  In most cases the traditional approach is enough.
5473 @end defmac
5475 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5476 @acindex{CHECK_DECLS_ONCE}
5477 @cvindex HAVE_DECL_@var{symbol}
5478 For each of the @var{symbols} (@emph{comma}-separated list), define
5479 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5480 @var{symbol} is declared in the default include files, otherwise to
5481 @samp{0}.  This is a once-only variant of @code{AC_CHECK_DECLS}.  It
5482 generates the checking code at most once, so that @command{configure} is
5483 smaller and faster; but the checks cannot be conditionalized and are
5484 always done once, early during the @command{configure} run.
5485 @end defmac
5488 @node Structures
5489 @section Structures
5490 @cindex Structure, checking
5492 The following macros check for the presence of certain members in C
5493 structures.  If there is no macro specifically defined to check for a
5494 member you need, then you can use the general structure-member macros
5495 (@pxref{Generic Structures}) or, for more complex tests, you may use
5496 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5498 @menu
5499 * Particular Structures::       Macros to check for certain structure members
5500 * Generic Structures::          How to find other structure members
5501 @end menu
5503 @node Particular Structures
5504 @subsection Particular Structure Checks
5506 The following macros check for certain structures or structure members.
5508 @defmac AC_STRUCT_DIRENT_D_INO
5509 @acindex{STRUCT_DIRENT_D_INO}
5510 @cvindex HAVE_STRUCT_DIRENT_D_INO
5511 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5512 Headers}).  Then, if @code{struct dirent} contains a @code{d_ino}
5513 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5515 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5516 @code{d_ino}, not whether its contents are always reliable.
5517 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5518 though modern systems hide this detail from the user and never return
5519 zero @code{d_ino} values.
5520 @end defmac
5522 @defmac AC_STRUCT_DIRENT_D_TYPE
5523 @acindex{STRUCT_DIRENT_D_TYPE}
5524 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5525 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5526 Headers}).  Then, if @code{struct dirent} contains a @code{d_type}
5527 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5528 @end defmac
5530 @defmac AC_STRUCT_ST_BLKSIZE
5531 @acindex{STRUCT_ST_BLKSIZE}
5532 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5533 @cvindex HAVE_ST_BLKSIZE
5534 If @code{struct stat} contains an @code{st_blksize} member, define
5535 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}.  The former name,
5536 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5537 the future.  This macro is obsoleted, and should be replaced by
5539 @example
5540 AC_CHECK_MEMBERS([struct stat.st_blksize])
5541 @end example
5542 @end defmac
5544 @defmac AC_STRUCT_ST_BLOCKS
5545 @acindex{STRUCT_ST_BLOCKS}
5546 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5547 @cvindex HAVE_ST_BLOCKS
5548 @ovindex LIBOBJS
5549 If @code{struct stat} contains an @code{st_blocks} member, define
5550 @code{HAVE_STRUCT_STAT_ST_BLOCKS}.  Otherwise, require an
5551 @code{AC_LIBOBJ} replacement of @samp{fileblocks}.  The former name,
5552 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5553 future.
5554 @end defmac
5556 @defmac AC_STRUCT_ST_RDEV
5557 @acindex{STRUCT_ST_RDEV}
5558 @cvindex HAVE_ST_RDEV
5559 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5560 If @code{struct stat} contains an @code{st_rdev} member, define
5561 @code{HAVE_STRUCT_STAT_ST_RDEV}.  The former name for this macro,
5562 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5563 in the future.  Actually, even the new macro is obsolete and should be
5564 replaced by:
5565 @example
5566 AC_CHECK_MEMBERS([struct stat.st_rdev])
5567 @end example
5568 @end defmac
5570 @defmac AC_STRUCT_TM
5571 @acindex{STRUCT_TM}
5572 @cvindex TM_IN_SYS_TIME
5573 @hdrindex{time.h}
5574 @hdrindex{sys/time.h}
5575 If @file{time.h} does not define @code{struct tm}, define
5576 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5577 had better define @code{struct tm}.
5578 @end defmac
5580 @defmac AC_STRUCT_TIMEZONE
5581 @acindex{STRUCT_TIMEZONE}
5582 @cvindex HAVE_TM_ZONE
5583 @cvindex HAVE_TZNAME
5584 Figure out how to get the current timezone.  If @code{struct tm} has a
5585 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5586 obsoleted @code{HAVE_TM_ZONE}).  Otherwise, if the external array
5587 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5588 define @code{HAVE_DECL_TZNAME}.
5589 @end defmac
5591 @node Generic Structures
5592 @subsection Generic Structure Checks
5594 These macros are used to find structure members not covered by the
5595 ``particular'' test macros.
5597 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5598 @acindex{CHECK_MEMBER}
5599 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5600 If no @var{includes} are specified, the default includes are used
5601 (@pxref{Default Includes}).
5603 @example
5604 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5605                 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5606                 [#include <pwd.h>])
5607 @end example
5609 You can use this macro for sub-members:
5611 @example
5612 AC_CHECK_MEMBER(struct top.middle.bot)
5613 @end example
5614 @end defmac
5616 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5617 @acindex{CHECK_MEMBERS}
5618 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5619 @var{members} using the previous macro.  When @var{member} belongs to
5620 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5621 capitals, with spaces and dots replaced by underscores).  If
5622 @var{action-if-found} is given, it is executed for each of the found
5623 members.  If @var{action-if-not-found} is given, it is executed for each
5624 of the members that could not be found.
5626 This macro uses m4 lists:
5627 @example
5628 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5629 @end example
5630 @end defmac
5633 @node Types
5634 @section Types
5635 @cindex Types
5636 @cindex C types
5638 The following macros check for C types, either builtin or typedefs.  If
5639 there is no macro specifically defined to check for a type you need, and
5640 you don't need to check for any special properties of it, then you can
5641 use a general type-check macro.
5643 @menu
5644 * Particular Types::            Special handling to find certain types
5645 * Generic Types::               How to find other types
5646 @end menu
5648 @node Particular Types
5649 @subsection Particular Type Checks
5651 @hdrindex{sys/types.h}
5652 @hdrindex{stdlib.h}
5653 @hdrindex{stdint.h}
5654 @hdrindex{inttypes.h}
5655 These macros check for particular C types in @file{sys/types.h},
5656 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5657 exist.
5659 The Gnulib @code{stdint} module is an alternate way to define many of
5660 these symbols; it is useful if you prefer your code to assume a
5661 C99-or-better environment.  @xref{Gnulib}.
5663 @defmac AC_TYPE_GETGROUPS
5664 @acindex{TYPE_GETGROUPS}
5665 @cvindex GETGROUPS_T
5666 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5667 is the base type of the array argument to @code{getgroups}.
5668 @end defmac
5670 @defmac AC_TYPE_INT8_T
5671 @acindex{TYPE_INT8_T}
5672 @cvindex HAVE_INT8_T
5673 @cvindex int8_t
5674 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5675 define @code{HAVE_INT8_T}.  Otherwise, define @code{int8_t} to a signed
5676 integer type that is exactly 8 bits wide and that uses two's complement
5677 representation, if such a type exists.
5678 @end defmac
5680 @defmac AC_TYPE_INT16_T
5681 @acindex{TYPE_INT16_T}
5682 @cvindex HAVE_INT16_T
5683 @cvindex int16_t
5684 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5685 @end defmac
5687 @defmac AC_TYPE_INT32_T
5688 @acindex{TYPE_INT32_T}
5689 @cvindex HAVE_INT32_T
5690 @cvindex int32_t
5691 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5692 @end defmac
5694 @defmac AC_TYPE_INT64_T
5695 @acindex{TYPE_INT64_T}
5696 @cvindex HAVE_INT64_T
5697 @cvindex int64_t
5698 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5699 @end defmac
5701 @defmac AC_TYPE_INTMAX_T
5702 @acindex{TYPE_INTMAX_T}
5703 @cvindex HAVE_INTMAX_T
5704 @cvindex intmax_t
5705 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5706 define @code{HAVE_INTMAX_T}.  Otherwise, define @code{intmax_t} to the
5707 widest signed integer type.
5708 @end defmac
5710 @defmac AC_TYPE_INTPTR_T
5711 @acindex{TYPE_INTPTR_T}
5712 @cvindex HAVE_INTPTR_T
5713 @cvindex intptr_t
5714 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5715 define @code{HAVE_INTPTR_T}.  Otherwise, define @code{intptr_t} to a
5716 signed integer type wide enough to hold a pointer, if such a type
5717 exists.
5718 @end defmac
5720 @defmac AC_TYPE_LONG_DOUBLE
5721 @acindex{TYPE_LONG_DOUBLE}
5722 @cvindex HAVE_LONG_DOUBLE
5723 If the C compiler supports a working @code{long double} type, define
5724 @code{HAVE_LONG_DOUBLE}.  The @code{long double} type might have the
5725 same range and precision as @code{double}.
5726 @end defmac
5728 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5729 @acindex{TYPE_LONG_DOUBLE_WIDER}
5730 @cvindex HAVE_LONG_DOUBLE_WIDER
5731 If the C compiler supports a working @code{long double} type with more
5732 range or precision than the @code{double} type, define
5733 @code{HAVE_LONG_DOUBLE_WIDER}.
5734 @end defmac
5736 @defmac AC_TYPE_LONG_LONG_INT
5737 @acindex{TYPE_LONG_LONG_INT}
5738 @cvindex HAVE_LONG_LONG_INT
5739 If the C compiler supports a working @code{long long int} type, define
5740 @code{HAVE_LONG_LONG_INT}.
5741 @end defmac
5743 @defmac AC_TYPE_MBSTATE_T
5744 @acindex{TYPE_MBSTATE_T}
5745 @cvindex mbstate_t
5746 @hdrindex{wchar.h}
5747 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5748 @code{mbstate_t} type.  Also, define @code{mbstate_t} to be a type if
5749 @code{<wchar.h>} does not declare it.
5750 @end defmac
5752 @defmac AC_TYPE_MODE_T
5753 @acindex{TYPE_MODE_T}
5754 @cvindex mode_t
5755 Define @code{mode_t} to a suitable type, if standard headers do not
5756 define it.
5757 @end defmac
5759 @defmac AC_TYPE_OFF_T
5760 @acindex{TYPE_OFF_T}
5761 @cvindex off_t
5762 Define @code{off_t} to a suitable type, if standard headers do not
5763 define it.
5764 @end defmac
5766 @defmac AC_TYPE_PID_T
5767 @acindex{TYPE_PID_T}
5768 @cvindex pid_t
5769 Define @code{pid_t} to a suitable type, if standard headers do not
5770 define it.
5771 @end defmac
5773 @defmac AC_TYPE_SIGNAL
5774 @acindex{TYPE_SIGNAL}
5775 @cvindex RETSIGTYPE
5776 @hdrindex{signal.h}
5777 If @file{signal.h} declares @code{signal} as returning a pointer to a
5778 function returning @code{void}, define @code{RETSIGTYPE} to be
5779 @code{void}; otherwise, define it to be @code{int}.
5781 Define signal handlers as returning type @code{RETSIGTYPE}:
5783 @example
5784 @group
5785 RETSIGTYPE
5786 hup_handler ()
5788 @dots{}
5790 @end group
5791 @end example
5792 @end defmac
5794 @defmac AC_TYPE_SIZE_T
5795 @acindex{TYPE_SIZE_T}
5796 @cvindex size_t
5797 Define @code{size_t} to a suitable type, if standard headers do not
5798 define it.
5799 @end defmac
5801 @defmac AC_TYPE_SSIZE_T
5802 @acindex{TYPE_SSIZE_T}
5803 @cvindex ssize_t
5804 Define @code{ssize_t} to a suitable type, if standard headers do not
5805 define it.
5806 @end defmac
5808 @defmac AC_TYPE_UID_T
5809 @acindex{TYPE_UID_T}
5810 @cvindex uid_t
5811 @cvindex gid_t
5812 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
5813 headers do not define them.
5814 @end defmac
5816 @defmac AC_TYPE_UINT8_T
5817 @acindex{TYPE_UINT8_T}
5818 @cvindex HAVE_UINT8_T
5819 @cvindex uint8_t
5820 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
5821 define @code{HAVE_UINT8_T}.  Otherwise, define @code{uint8_t} to an
5822 unsigned integer type that is exactly 8 bits wide, if such a type
5823 exists.
5824 @end defmac
5826 @defmac AC_TYPE_UINT16_T
5827 @acindex{TYPE_UINT16_T}
5828 @cvindex HAVE_UINT16_T
5829 @cvindex uint16_t
5830 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
5831 @end defmac
5833 @defmac AC_TYPE_UINT32_T
5834 @acindex{TYPE_UINT32_T}
5835 @cvindex HAVE_UINT32_T
5836 @cvindex uint32_t
5837 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
5838 @end defmac
5840 @defmac AC_TYPE_UINT64_T
5841 @acindex{TYPE_UINT64_T}
5842 @cvindex HAVE_UINT64_T
5843 @cvindex uint64_t
5844 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
5845 @end defmac
5847 @defmac AC_TYPE_UINTMAX_T
5848 @acindex{TYPE_UINTMAX_T}
5849 @cvindex HAVE_UINTMAX_T
5850 @cvindex uintmax_t
5851 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
5852 define @code{HAVE_UINTMAX_T}.  Otherwise, define @code{uintmax_t} to the
5853 widest unsigned integer type.
5854 @end defmac
5856 @defmac AC_TYPE_UINTPTR_T
5857 @acindex{TYPE_UINTPTR_T}
5858 @cvindex HAVE_UINTPTR_T
5859 @cvindex uintptr_t
5860 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
5861 define @code{HAVE_UINTPTR_T}.  Otherwise, define @code{uintptr_t} to an
5862 unsigned integer type wide enough to hold a pointer, if such a type
5863 exists.
5864 @end defmac
5866 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
5867 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
5868 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
5869 If the C compiler supports a working @code{unsigned long long int} type,
5870 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
5871 @end defmac
5873 @node Generic Types
5874 @subsection Generic Type Checks
5876 These macros are used to check for types not covered by the ``particular''
5877 test macros.
5879 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5880 @acindex{CHECK_TYPE}
5881 Check whether @var{type} is defined.  It may be a compiler builtin type
5882 or defined by the @var{includes} (@pxref{Default Includes}).
5883 @end defmac
5886 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5887 @acindex{CHECK_TYPES}
5888 For each @var{type} of the @var{types} that is defined, define
5889 @code{HAVE_@var{type}} (in all capitals).  If no @var{includes} are
5890 specified, the default includes are used (@pxref{Default Includes}).  If
5891 @var{action-if-found} is given, it is additional shell code to execute
5892 when one of the types is found.  If @var{action-if-not-found} is given,
5893 it is executed when one of the types is not found.
5895 This macro uses m4 lists:
5896 @example
5897 AC_CHECK_TYPES([ptrdiff_t])
5898 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
5899 @end example
5901 @end defmac
5903 Autoconf, up to 2.13, used to provide to another version of
5904 @code{AC_CHECK_TYPE}, broken by design.  In order to keep backward
5905 compatibility, a simple heuristics, quite safe but not totally, is
5906 implemented.  In case of doubt, read the documentation of the former
5907 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
5910 @node Compilers and Preprocessors
5911 @section Compilers and Preprocessors
5912 @cindex Compilers
5913 @cindex Preprocessors
5915 @ovindex EXEEXT
5916 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
5917 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
5918 the output of the compiler, typically to the empty string if
5919 Posix and @samp{.exe} if a @acronym{DOS} variant.  It can be overridden
5920 by passing the argument @samp{ac_cv_exeext=@var{ext}} to
5921 @command{configure}.
5923 @ovindex OBJEXT
5924 They also define the output variable @code{OBJEXT} based on the
5925 output of the compiler, after @file{.c} files have been excluded, typically
5926 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
5928 If the compiler being used does not produce executables, the tests fail.  If
5929 the executables can't be run, and cross-compilation is not enabled, they
5930 fail too.  @xref{Manual Configuration}, for more on support for cross
5931 compiling.
5933 @menu
5934 * Specific Compiler Characteristics::  Some portability issues
5935 * Generic Compiler Characteristics::  Language independent tests and features
5936 * C Compiler::                  Checking its characteristics
5937 * C++ Compiler::                Likewise
5938 * Objective C Compiler::        Likewise
5939 * Erlang Compiler and Interpreter::  Likewise
5940 * Fortran Compiler::            Likewise
5941 @end menu
5943 @node Specific Compiler Characteristics
5944 @subsection Specific Compiler Characteristics
5946 Some compilers exhibit different behaviors.
5948 @table @asis
5949 @item Static/Dynamic Expressions
5950 Autoconf relies on a trick to extract one bit of information from the C
5951 compiler: using negative array sizes.  For instance the following
5952 excerpt of a C source demonstrates how to test whether @samp{int}s are 4
5953 bytes wide:
5955 @example
5957 main (void)
5959   static int test_array [sizeof (int) == 4 ? 1 : -1];
5960   test_array [0] = 0;
5961   return 0;
5963 @end example
5965 @noindent
5966 To our knowledge, there is a single compiler that does not support this
5967 trick: the HP C compilers (the real one, not only the ``bundled'') on
5968 HP-UX 11.00.  They incorrectly reject the above program with the diagnostic
5969 ``Variable-length arrays cannot have static storage.''
5970 This bug comes from HP compilers' mishandling of @code{sizeof (int)},
5971 not from the @code{? 1 : -1}, and
5972 Autoconf works around this problem by casting @code{sizeof (int)} to
5973 @code{long int} before comparing it.
5974 @end table
5976 @node Generic Compiler Characteristics
5977 @subsection Generic Compiler Characteristics
5979 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
5980 @acindex{CHECK_SIZEOF}
5981 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
5982 size in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
5983 of 0.  If no @var{includes} are specified, the default includes are used
5984 (@pxref{Default Includes}).  If you provide @var{include}, be sure to
5985 include @file{stdio.h} which is required for this macro to run.
5987 This macro now works even when cross-compiling.  The @var{unused}
5988 argument was used when cross-compiling.
5990 For example, the call
5992 @example
5993 AC_CHECK_SIZEOF([int *])
5994 @end example
5996 @noindent
5997 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
5998 @end defmac
6000 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6001 @acindex{CHECK_ALIGNOF}
6002 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6003 alignment in bytes of @var{type}.  If @samp{type} is unknown, it gets a size
6004 of 0.  If no @var{includes} are specified, the default includes are used
6005 (@pxref{Default Includes}).  If you provide @var{include}, be sure to
6006 include @file{stddef.h} and @file{stdio.h} which are required for this
6007 macro to work correctly.
6008 @end defmac
6010 @defmac AC_LANG_WERROR
6011 @acindex{LANG_WERROR}
6012 Normally Autoconf ignores warnings generated by the compiler, linker, and
6013 preprocessor.  If this macro is used, warnings will be treated as fatal
6014 errors instead for the current language.  This macro is useful when the
6015 results of configuration will be used where warnings are unacceptable; for
6016 instance, if parts of a program are built with the GCC @option{-Werror}
6017 option.  If the whole program will be built using @option{-Werror} it is
6018 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6019 etc.).
6020 @end defmac
6022 @node C Compiler
6023 @subsection C Compiler Characteristics
6025 The following macros provide ways to find and exercise a C Compiler.
6026 There are a few constructs that ought to be avoided, but do not deserve
6027 being checked for, since they can easily be worked around.
6029 @table @asis
6030 @item Don't use lines containing solitary backslashes
6031 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20,
6032 11.00, and 11i).  When given the following source:
6034 @example
6035 #ifdef __STDC__
6037 * A comment with backslash-newlines in it.  %@{ %@} *\
6040 char str[] = "\\
6041 " A string with backslash-newlines in it %@{ %@} \\
6043 char apostrophe = '\\
6047 #endif
6048 @end example
6050 @noindent
6051 the compiler incorrectly fails with the diagnostics ``Non-terminating
6052 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6053 Removing the lines with solitary backslashes solves the problem.
6055 @item Don't compile several files at once if output matters to you
6056 Some compilers, such as the HP's, reports the name of the file it is
6057 compiling @emph{when} they are several.  For instance:
6059 @example
6060 $ @kbd{cc a.c b.c}
6061 a.c:
6062 b.c:
6063 @end example
6065 @noindent
6066 This can cause problems if you observe the output of the compiler to
6067 detect failures.  Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6068 b.o} solves the issue.
6070 @item Don't rely on @code{#error} failing
6071 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6072 simply emits a diagnostic and continues, exiting successfully.  So,
6073 instead of an error directive like @code{#error "Unsupported word size"}
6074 it is more portable to use an invalid directive like @code{#Unsupported
6075 word size} in Autoconf tests.  In ordinary source code, @code{#error} is
6076 OK, since installers with inadequate compilers like @sc{irix} can simply
6077 examine these compilers' diagnostic output.
6079 @item Don't rely on correct @code{#line} support
6080 On Solaris 8, @command{c89} (Sun WorkShop 6 update 2 C 5.3 Patch
6081 111679-08 2002/05/09)) diagnoses @code{#line} directives whose line
6082 numbers are greater than 32767.  In addition, nothing in Posix
6083 makes this invalid.  That is why Autoconf stopped issuing
6084 @code{#line} directives.
6085 @end table
6087 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6088 @acindex{PROG_CC}
6089 @ovindex CC
6090 @ovindex CFLAGS
6091 Determine a C compiler to use.  If @code{CC} is not already set in the
6092 environment, check for @code{gcc} and @code{cc}, then for other C
6093 compilers.  Set output variable @code{CC} to the name of the compiler
6094 found.
6096 This macro may, however, be invoked with an optional first argument
6097 which, if specified, must be a blank-separated list of C compilers to
6098 search for.  This just gives the user an opportunity to specify an
6099 alternative search list for the C compiler.  For example, if you didn't
6100 like the default order, then you could invoke @code{AC_PROG_CC} like
6101 this:
6103 @example
6104 AC_PROG_CC([gcc cl cc])
6105 @end example
6107 If the C compiler does not handle function prototypes correctly by
6108 default, try to add an option to output variable @code{CC} to make it
6109 so.  This macro tries various options that select standard-conformance
6110 modes on various systems.
6112 After calling this macro you can check whether the C compiler has been
6113 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6114 variable
6115 @code{ac_cv_prog_cc_c89} is set to @samp{no}.  See also
6116 @code{AC_C_PROTOTYPES} below.
6118 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6119 @samp{yes}.  If output variable @code{CFLAGS} was not already set, set
6120 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6121 where GCC does not accept @option{-g}), or @option{-g} for other compilers.
6122 @end defmac
6124 @defmac AC_PROG_CC_C_O
6125 @acindex{PROG_CC_C_O}
6126 @cvindex NO_MINUS_C_MINUS_O
6127 If the C compiler does not accept the @option{-c} and @option{-o} options
6128 simultaneously, define @code{NO_MINUS_C_MINUS_O}.  This macro actually
6129 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6130 the first @code{cc} in the path.  The test fails if one fails.  This
6131 macro was created for @acronym{GNU} Make to choose the default C compilation
6132 rule.
6133 @end defmac
6136 @defmac AC_PROG_CPP
6137 @acindex{PROG_CPP}
6138 @ovindex CPP
6139 Set output variable @code{CPP} to a command that runs the
6140 C preprocessor.  If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6141 It is only portable to run @code{CPP} on files with a @file{.c}
6142 extension.
6144 Some preprocessors don't indicate missing include files by the error
6145 status.  For such preprocessors an internal variable is set that causes
6146 other macros to check the standard error from the preprocessor and
6147 consider the test failed if any warnings have been reported.
6148 For most preprocessors, though, warnings do not cause include-file
6149 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6150 @end defmac
6152 @defmac AC_PROG_CPP_WERROR
6153 @acindex{PROG_CPP_WERROR}
6154 @ovindex CPP
6155 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6156 preprocessor as errors even if the preprocessor exit status indicates
6157 success.  This is useful for avoiding headers that generate mandatory
6158 warnings, such as deprecation notices.
6159 @end defmac
6162 The following macros check for C compiler or machine architecture
6163 features.  To check for characteristics not listed here, use
6164 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6165 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6167 @defmac AC_PROG_CC_STDC
6168 @acindex{PROG_CC_STDC}
6169 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6170 C99), try to add an option to output variable @code{CC} to make it work.
6171 If the compiler does not support C99, fall back to supporting
6172 @acronym{ANSI} C89 (@acronym{ISO} C90).
6174 After calling this macro you can check whether the C compiler has been
6175 set to accept Standard C; if not, the shell variable
6176 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6177 @end defmac
6179 @defmac AC_PROG_CC_C89
6180 @acindex{PROG_CC_C89}
6181 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6182 default, try to add an option to output variable @code{CC} to make it
6183 so.  This macro tries various options that select @acronym{ANSI} C89 on
6184 some system or another.  It considers the compiler to be in
6185 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6187 After calling this macro you can check whether the C compiler has been
6188 set to accept @acronym{ANSI} C89; if not, the shell variable
6189 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6191 This macro is called automatically by @code{AC_PROG_CC}.
6192 @end defmac
6194 @defmac AC_PROG_CC_C99
6195 @acindex{PROG_CC_C99}
6196 If the C compiler is not in C99 mode by default, try to add an
6197 option to output variable @code{CC} to make it so.  This macro tries
6198 various options that select C99 on some system or another.  It
6199 considers the compiler to be in C99 mode if it handles @code{_Bool},
6200 flexible arrays, @code{inline}, @code{long long int}, mixed code and
6201 declarations, named initialization of structs, @code{restrict}, varargs
6202 macros, variable declarations in @code{for} loops and variable length
6203 arrays.
6205 After calling this macro you can check whether the C compiler has been
6206 set to accept C99; if not, the shell variable
6207 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6208 @end defmac
6210 @defmac AC_C_BACKSLASH_A
6211 @acindex{HAVE_C_BACKSLASH_A}
6212 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6213 @samp{\a}.
6214 @end defmac
6216 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
6217 @acindex{C_BIGENDIAN}
6218 @cvindex WORDS_BIGENDIAN
6219 @cindex Endianness
6220 If words are stored with the most significant byte first (like Motorola
6221 and SPARC CPUs), execute @var{action-if-true}.  If words are stored with
6222 the least significant byte first (like Intel and VAX CPUs), execute
6223 @var{action-if-false}.
6225 This macro runs a test-case if endianness cannot be determined from the
6226 system header files.  When cross-compiling, the test-case is not run but
6227 grep'ed for some magic values.  @var{action-if-unknown} is executed if
6228 the latter case fails to determine the byte sex of the host system.
6230 The default for @var{action-if-true} is to define
6231 @samp{WORDS_BIGENDIAN}.  The default for @var{action-if-false} is to do
6232 nothing.  And finally, the default for @var{action-if-unknown} is to
6233 abort configure and tell the installer which variable he should preset
6234 to bypass this test.
6235 @end defmac
6237 @defmac AC_C_CONST
6238 @acindex{C_CONST}
6239 @cvindex const
6240 If the C compiler does not fully support the @code{const} keyword,
6241 define @code{const} to be empty.  Some C compilers that do
6242 not define @code{__STDC__} do support @code{const}; some compilers that
6243 define @code{__STDC__} do not completely support @code{const}.  Programs
6244 can simply use @code{const} as if every C compiler supported it; for
6245 those that don't, the @file{Makefile} or configuration header file will
6246 define it as empty.
6248 Occasionally installers use a C++ compiler to compile C code, typically
6249 because they lack a C compiler.  This causes problems with @code{const},
6250 because C and C++ treat @code{const} differently.  For example:
6252 @example
6253 const int foo;
6254 @end example
6256 @noindent
6257 is valid in C but not in C++.  These differences unfortunately cannot be
6258 papered over by defining @code{const} to be empty.
6260 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6261 as this generally yields better results in practice.  However, using a
6262 C++ compiler to compile C code is not recommended or supported, and
6263 installers who run into trouble in this area should get a C compiler
6264 like GCC to compile their C code.
6265 @end defmac
6267 @defmac AC_C_RESTRICT
6268 @acindex{C_RESTRICT}
6269 @cvindex restrict
6270 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6271 If it recognizes only a variant spelling (@code{__restrict},
6272 @code{__restrict__}, or @code{_Restrict}), then define
6273 @code{restrict} to that.
6274 Otherwise, define @code{restrict} to be empty.
6275 Thus, programs may simply use @code{restrict} as if every C compiler
6276 supported it; for those that do not, the @file{Makefile}
6277 or configuration header defines it away.
6279 Although support in C++ for the @code{restrict} keyword is not
6280 required, several C++ compilers do accept the keyword.
6281 This macro works for them, too.
6282 @end defmac
6284 @defmac AC_C_VOLATILE
6285 @acindex{C_VOLATILE}
6286 @cvindex volatile
6287 If the C compiler does not understand the keyword @code{volatile},
6288 define @code{volatile} to be empty.  Programs can simply use
6289 @code{volatile} as if every C compiler supported it; for those that do
6290 not, the @file{Makefile} or configuration header will define it as
6291 empty.
6293 If the correctness of your program depends on the semantics of
6294 @code{volatile}, simply defining it to be empty does, in a sense, break
6295 your code.  However, given that the compiler does not support
6296 @code{volatile}, you are at its mercy anyway.  At least your
6297 program will compile, when it wouldn't before.
6299 In general, the @code{volatile} keyword is a standard C feature, so
6300 you might expect that @code{volatile} is available only when
6301 @code{__STDC__} is defined.  However, Ultrix 4.3's native compiler does
6302 support volatile, but does not define @code{__STDC__}.
6303 @end defmac
6305 @defmac AC_C_INLINE
6306 @acindex{C_INLINE}
6307 @cvindex inline
6308 If the C compiler supports the keyword @code{inline}, do nothing.
6309 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6310 if it accepts one of those, otherwise define @code{inline} to be empty.
6311 @end defmac
6313 @defmac AC_C_CHAR_UNSIGNED
6314 @acindex{C_CHAR_UNSIGNED}
6315 @cvindex __CHAR_UNSIGNED__
6316 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6317 unless the C compiler predefines it.
6318 @end defmac
6320 @defmac AC_C_STRINGIZE
6321 @acindex{C_STRINGIZE}
6322 @cvindex HAVE_STRINGIZE
6323 If the C preprocessor supports the stringizing operator, define
6324 @code{HAVE_STRINGIZE}.  The stringizing operator is @samp{#} and is
6325 found in macros such as this:
6327 @example
6328 #define x(y) #y
6329 @end example
6330 @end defmac
6332 @defmac AC_C_TYPEOF
6333 @acindex{C_TYPEOF}
6334 @cvindex HAVE_TYPEOF
6335 @cvindex typeof
6336 If the C compiler supports GCC's @code{typeof} syntax either directly or
6337 through a different spelling of the keyword (e.g., @code{__typeof__}),
6338 define @code{HAVE_TYPEOF}.  If the support is available only through a
6339 different spelling, define @code{typeof} to that spelling.
6340 @end defmac
6342 @defmac AC_C_PROTOTYPES
6343 @acindex{C_PROTOTYPES}
6344 @cvindex PROTOTYPES
6345 @cvindex __PROTOTYPES
6346 @cvindex PARAMS
6347 If function prototypes are understood by the compiler (as determined by
6348 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6349 Defining @code{__PROTOTYPES} is for the benefit of
6350 header files that cannot use macros that infringe on user name space.
6351 @end defmac
6353 @defmac AC_PROG_GCC_TRADITIONAL
6354 @acindex{PROG_GCC_TRADITIONAL}
6355 @ovindex CC
6356 Add @option{-traditional} to output variable @code{CC} if using the
6357 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6358 @option{-traditional}.  That usually happens when the fixed header files
6359 have not been installed on an old system.  Since recent versions of the
6360 @acronym{GNU} C compiler fix the header files automatically when installed,
6361 this macro is becoming obsolete.
6362 @end defmac
6365 @node C++ Compiler
6366 @subsection C++ Compiler Characteristics
6369 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6370 @acindex{PROG_CXX}
6371 @ovindex CXX
6372 @ovindex CXXFLAGS
6373 Determine a C++ compiler to use.  Check whether the environment variable
6374 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6375 variable @code{CXX} to its value.
6377 Otherwise, if the macro is invoked without an argument, then search for
6378 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6379 then other names).  If none of those checks succeed, then as a last
6380 resort set @code{CXX} to @code{g++}.
6382 This macro may, however, be invoked with an optional first argument
6383 which, if specified, must be a blank-separated list of C++ compilers to
6384 search for.  This just gives the user an opportunity to specify an
6385 alternative search list for the C++ compiler.  For example, if you
6386 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6387 like this:
6389 @example
6390 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6391 @end example
6393 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6394 @samp{yes}.  If output variable @code{CXXFLAGS} was not already set, set
6395 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6396 systems where G++ does not accept @option{-g}), or @option{-g} for other
6397 compilers.
6398 @end defmac
6400 @defmac AC_PROG_CXXCPP
6401 @acindex{PROG_CXXCPP}
6402 @ovindex CXXCPP
6403 Set output variable @code{CXXCPP} to a command that runs the C++
6404 preprocessor.  If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6405 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6406 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6408 Some preprocessors don't indicate missing include files by the error
6409 status.  For such preprocessors an internal variable is set that causes
6410 other macros to check the standard error from the preprocessor and
6411 consider the test failed if any warnings have been reported.  However,
6412 it is not known whether such broken preprocessors exist for C++.
6413 @end defmac
6415 @defmac AC_PROG_CXX_C_O
6416 @acindex{PROG_CXX_C_O}
6417 @cvindex CXX_NO_MINUS_C_MINUS_O
6418 Test whether the C++ compiler accepts the options @option{-c} and
6419 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6420 if it does not.
6421 @end defmac
6424 @node Objective C Compiler
6425 @subsection Objective C Compiler Characteristics
6428 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6429 @acindex{PROG_OBJC}
6430 @ovindex OBJC
6431 @ovindex OBJCFLAGS
6432 Determine an Objective C compiler to use.  If @code{OBJC} is not already
6433 set in the environment, check for Objective C compilers.  Set output
6434 variable @code{OBJC} to the name of the compiler found.
6436 This macro may, however, be invoked with an optional first argument
6437 which, if specified, must be a blank-separated list of Objective C compilers to
6438 search for.  This just gives the user an opportunity to specify an
6439 alternative search list for the Objective C compiler.  For example, if you
6440 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6441 like this:
6443 @example
6444 AC_PROG_OBJC([gcc objcc objc])
6445 @end example
6447 If using the @acronym{GNU} Objective C compiler, set shell variable
6448 @code{GOBJC} to @samp{yes}.  If output variable @code{OBJCFLAGS} was not
6449 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6450 compiler (@option{-O2} on systems where @command{gcc} does not accept
6451 @option{-g}), or @option{-g} for other compilers.
6452 @end defmac
6454 @defmac AC_PROG_OBJCCPP
6455 @acindex{PROG_OBJCCPP}
6456 @ovindex OBJCCPP
6457 Set output variable @code{OBJCCPP} to a command that runs the Objective C
6458 preprocessor.  If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6459 @end defmac
6462 @node Erlang Compiler and Interpreter
6463 @subsection Erlang Compiler and Interpreter Characteristics
6464 @cindex Erlang
6466 Autoconf defines the following macros for determining paths to the essential
6467 Erlang/OTP programs:
6469 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6470 @acindex{ERLANG_PATH_ERLC}
6471 @ovindex ERLC
6472 @ovindex ERLCFLAGS
6473 Determine an Erlang compiler to use.  If @code{ERLC} is not already set in the
6474 environment, check for @command{erlc}.  Set output variable @code{ERLC} to the
6475 complete path of the compiler command found.  In addition, if @code{ERLCFLAGS}
6476 is not set in the environment, set it to an empty value.
6478 The two optional arguments have the same meaning as the two last arguments of
6479 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program.  For
6480 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6481 directory:
6483 @example
6484 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6485 @end example
6486 @end defmac
6488 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6489 @acindex{ERLANG_NEED_ERLC}
6490 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6491 error message and exits the @command{configure} script if the @command{erlc}
6492 program is not found.
6493 @end defmac
6495 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6496 @acindex{ERLANG_PATH_ERL}
6497 @ovindex ERL
6498 Determine an Erlang interpreter to use.  If @code{ERL} is not already set in the
6499 environment, check for @command{erl}.  Set output variable @code{ERL} to the
6500 complete path of the interpreter command found.
6502 The two optional arguments have the same meaning as the two last arguments of
6503 macro @code{AC_PROG_PATH} for looking for the @command{erl} program.  For
6504 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6505 directory:
6507 @example
6508 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6509 @end example
6510 @end defmac
6512 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6513 @acindex{ERLANG_NEED_ERL}
6514 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6515 error message and exits the @command{configure} script if the @command{erl}
6516 program is not found.
6517 @end defmac
6520 @node Fortran Compiler
6521 @subsection Fortran Compiler Characteristics
6522 @cindex Fortran
6523 @cindex F77
6525 The Autoconf Fortran support is divided into two categories: legacy
6526 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6527 The former are intended for traditional Fortran 77 code, and have output
6528 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}.  The latter
6529 are for newer programs that can (or must) compile under the newer
6530 Fortran standards, and have output variables like @code{FC},
6531 @code{FCFLAGS}, and @code{FCLIBS}.
6533 Except for two new macros @code{AC_FC_SRCEXT} and
6534 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6535 behave almost identically, and so they are documented together in this
6536 section.
6539 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6540 @acindex{PROG_F77}
6541 @ovindex F77
6542 @ovindex FFLAGS
6543 Determine a Fortran 77 compiler to use.  If @code{F77} is not already
6544 set in the environment, then check for @code{g77} and @code{f77}, and
6545 then some other names.  Set the output variable @code{F77} to the name
6546 of the compiler found.
6548 This macro may, however, be invoked with an optional first argument
6549 which, if specified, must be a blank-separated list of Fortran 77
6550 compilers to search for.  This just gives the user an opportunity to
6551 specify an alternative search list for the Fortran 77 compiler.  For
6552 example, if you didn't like the default order, then you could invoke
6553 @code{AC_PROG_F77} like this:
6555 @example
6556 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6557 @end example
6559 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6560 @code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
6561 If the output variable @code{FFLAGS} was not already set in the
6562 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6563 where @code{g77} does not accept @option{-g}).  Otherwise, set
6564 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6565 @end defmac
6567 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6568 @acindex{PROG_FC}
6569 @ovindex FC
6570 @ovindex FCFLAGS
6571 Determine a Fortran compiler to use.  If @code{FC} is not already set in
6572 the environment, then @code{dialect} is a hint to indicate what Fortran
6573 dialect to search for; the default is to search for the newest available
6574 dialect.  Set the output variable @code{FC} to the name of the compiler
6575 found.
6577 By default, newer dialects are preferred over older dialects, but if
6578 @code{dialect} is specified then older dialects are preferred starting
6579 with the specified dialect.  @code{dialect} can currently be one of
6580 Fortran 77, Fortran 90, or Fortran 95.  However, this is only a hint of
6581 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6582 and no attempt is made to guarantee that a particular language standard
6583 is actually supported.  Thus, it is preferable that you avoid the
6584 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6585 the latest Fortran standard.
6587 This macro may, alternatively, be invoked with an optional first argument
6588 which, if specified, must be a blank-separated list of Fortran
6589 compilers to search for, just as in @code{AC_PROG_F77}.
6591 If the output variable @code{FCFLAGS} was not already set in the
6592 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6593 @option{-O2} where @code{g77} does not accept @option{-g}).  Otherwise,
6594 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6595 @end defmac
6597 @defmac AC_PROG_F77_C_O
6598 @defmacx AC_PROG_FC_C_O
6599 @acindex{PROG_F77_C_O}
6600 @acindex{PROG_FC_C_O}
6601 @cvindex F77_NO_MINUS_C_MINUS_O
6602 @cvindex FC_NO_MINUS_C_MINUS_O
6603 Test whether the Fortran compiler accepts the options @option{-c} and
6604 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6605 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6606 @end defmac
6608 The following macros check for Fortran compiler characteristics.
6609 To check for characteristics not listed here, use
6610 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6611 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6612 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6613 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6616 @defmac AC_F77_LIBRARY_LDFLAGS
6617 @defmacx AC_FC_LIBRARY_LDFLAGS
6618 @acindex{F77_LIBRARY_LDFLAGS}
6619 @ovindex FLIBS
6620 @acindex{FC_LIBRARY_LDFLAGS}
6621 @ovindex FCLIBS
6622 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6623 @dfn{Fortran intrinsic and runtime libraries} that are required to
6624 successfully link a Fortran program or shared library.  The output
6625 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6626 should be included after @code{LIBS} when linking).
6628 This macro is intended to be used in those situations when it is
6629 necessary to mix, e.g., C++ and Fortran source code in a single
6630 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6631 automake, @acronym{GNU} Automake}).
6633 For example, if object files from a C++ and Fortran compiler must be
6634 linked together, then the C++ compiler/linker must be used for linking
6635 (since special C++-ish things need to happen at link time like calling
6636 global constructors, instantiating templates, enabling exception
6637 support, etc.).
6639 However, the Fortran intrinsic and runtime libraries must be linked in
6640 as well, but the C++ compiler/linker doesn't know by default how to add
6641 these Fortran 77 libraries.  Hence, this macro was created to determine
6642 these Fortran libraries.
6644 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6645 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} will probably also be necessary to
6646 link C/C++ with Fortran; see below.
6647 @end defmac
6649 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6650 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6651 @acindex{F77_DUMMY_MAIN}
6652 @cvindex F77_DUMMY_MAIN
6653 With many compilers, the Fortran libraries detected by
6654 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6655 their own @code{main} entry function that initializes things like
6656 Fortran I/O, and which then calls a user-provided entry function named
6657 (say) @code{MAIN__} to run the user's program.  The
6658 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6659 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6660 this interaction.
6662 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6663 one prefers to provide one's own @code{main} and skip the Fortran
6664 library initializations.  In this case, however, one may still need to
6665 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6666 on some systems.  @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6667 detects whether any such routine is @emph{required} for linking, and
6668 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6669 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6670 was found, and @code{none} when no such dummy main is needed.
6672 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6673 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6674 @emph{if} it is required.  @var{action-if-not-found} defaults to
6675 exiting with an error.
6677 In order to link with Fortran routines, the user's C/C++ program should
6678 then include the following code to define the dummy main if it is
6679 needed:
6681 @example
6682 #ifdef F77_DUMMY_MAIN
6683 #  ifdef __cplusplus
6684      extern "C"
6685 #  endif
6686    int F77_DUMMY_MAIN() @{ return 1; @}
6687 #endif
6688 @end example
6690 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6692 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6693 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6694 explicitly unless one wants to change the default actions.
6695 @end defmac
6697 @defmac AC_F77_MAIN
6698 @defmacx AC_FC_MAIN
6699 @acindex{F77_MAIN}
6700 @cvindex F77_MAIN
6701 @acindex{FC_MAIN}
6702 @cvindex FC_MAIN
6703 As discussed above, many Fortran libraries allow you to provide an entry
6704 point called (say) @code{MAIN__} instead of the usual @code{main}, which
6705 is then called by a @code{main} function in the Fortran libraries that
6706 initializes things like Fortran I/O@.  The
6707 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
6708 @emph{possible} to utilize such an alternate main function, and defines
6709 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function.  (If no
6710 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
6711 simply defined to @code{main}.)
6713 Thus, when calling Fortran routines from C that perform things like I/O,
6714 one should use this macro and name the "main" function
6715 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
6716 @end defmac
6718 @defmac AC_F77_WRAPPERS
6719 @defmacx AC_FC_WRAPPERS
6720 @acindex{F77_WRAPPERS}
6721 @cvindex F77_FUNC
6722 @cvindex F77_FUNC_
6723 @acindex{FC_WRAPPERS}
6724 @cvindex FC_FUNC
6725 @cvindex FC_FUNC_
6726 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
6727 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
6728 mangle the names of C/C++ identifiers, and identifiers with underscores,
6729 respectively, so that they match the name-mangling scheme used by the
6730 Fortran compiler.
6732 Fortran is case-insensitive, and in order to achieve this the Fortran
6733 compiler converts all identifiers into a canonical case and format.  To
6734 call a Fortran subroutine from C or to write a C function that is
6735 callable from Fortran, the C program must explicitly use identifiers in
6736 the format expected by the Fortran compiler.  In order to do this, one
6737 simply wraps all C identifiers in one of the macros provided by
6738 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}.  For example, suppose
6739 you have the following Fortran 77 subroutine:
6741 @example
6742       subroutine foobar (x, y)
6743       double precision x, y
6744       y = 3.14159 * x
6745       return
6746       end
6747 @end example
6749 You would then declare its prototype in C or C++ as:
6751 @example
6752 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
6753 #ifdef __cplusplus
6754 extern "C"  /* prevent C++ name mangling */
6755 #endif
6756 void FOOBAR_F77(double *x, double *y);
6757 @end example
6759 Note that we pass both the lowercase and uppercase versions of the
6760 function name to @code{F77_FUNC} so that it can select the right one.
6761 Note also that all parameters to Fortran 77 routines are passed as
6762 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
6763 Automake}).
6765 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6767 Although Autoconf tries to be intelligent about detecting the
6768 name-mangling scheme of the Fortran compiler, there may be Fortran
6769 compilers that it doesn't support yet.  In this case, the above code
6770 will generate a compile-time error, but some other behavior
6771 (e.g., disabling Fortran-related features) can be induced by checking
6772 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
6774 Now, to call that routine from a C program, we would do something like:
6776 @example
6778     double x = 2.7183, y;
6779     FOOBAR_F77 (&x, &y);
6781 @end example
6783 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
6784 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
6785 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments).  This is
6786 because some Fortran compilers mangle names differently if they contain
6787 an underscore.
6788 @end defmac
6790 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
6791 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
6792 @acindex{F77_FUNC}
6793 @acindex{FC_FUNC}
6794 Given an identifier @var{name}, set the shell variable @var{shellvar} to
6795 hold the mangled version @var{name} according to the rules of the
6796 Fortran linker (see also @code{AC_F77_WRAPPERS} or
6797 @code{AC_FC_WRAPPERS}).  @var{shellvar} is optional; if it is not
6798 supplied, the shell variable will be simply @var{name}.  The purpose of
6799 this macro is to give the caller a way to access the name-mangling
6800 information other than through the C preprocessor as above, for example,
6801 to call Fortran routines from some language other than C/C++.
6802 @end defmac
6804 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
6805 @acindex{FC_SRCEXT}
6806 By default, the @code{FC} macros perform their tests using a @file{.f}
6807 extension for source-code files.  Some compilers, however, only enable
6808 newer language features for appropriately named files, e.g., Fortran 90
6809 features only for @file{.f90} files.  On the other hand, some other
6810 compilers expect all source files to end in @file{.f} and require
6811 special flags to support other file name extensions.  The
6812 @code{AC_FC_SRCEXT} macro deals with both of these issues.
6814 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
6815 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
6816 contain the dot).  If any special compiler flags are needed for this, it
6817 stores them in the output variable @code{FCFLAGS_}@var{ext}.  This
6818 extension and these flags are then used for all subsequent @code{FC} tests
6819 (until @code{AC_FC_SRCEXT} is called again).
6821 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
6822 @file{.f90} extension in future tests, and it would set a
6823 @code{FCFLAGS_f90} output variable with any extra flags that are needed
6824 to compile such files.
6826 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
6827 @code{FCFLAGS}, for two reasons based on the limitations of some
6828 compilers.  First, only one @code{FCFLAGS_}@var{ext} can be used at a
6829 time, so files with different extensions must be compiled separately.
6830 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
6831 the source-code file name when compiling.  So, continuing the example
6832 above, you might compile a @file{foo.f90} file in your Makefile with the
6833 command:
6835 @example
6836 foo.o: foo.f90
6837      $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) foo.f90
6838 @end example
6840 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
6841 extension, it calls @var{action-if-success} (defaults to nothing).  If
6842 it fails, and cannot find a way to make the @code{FC} compiler accept such
6843 files, it calls @var{action-if-failure} (defaults to exiting with an
6844 error message).
6846 @end defmac
6848 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
6849 @acindex{FC_FREEFORM}
6851 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
6852 (@code{$FC}) allows free-format source code (as opposed to the older
6853 fixed-format style from Fortran 77).  If necessary, it may add some
6854 additional flags to @code{FCFLAGS}.
6856 This macro is most important if you are using the default @file{.f}
6857 extension, since many compilers interpret this extension as indicating
6858 fixed-format source unless an additional flag is supplied.  If you
6859 specify a different extension with @code{AC_FC_SRCEXT}, such as
6860 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} will ordinarily
6861 succeed without modifying @code{FCFLAGS}.
6863 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
6864 calls @var{action-if-success} (defaults to nothing).  If it fails, it
6865 calls @var{action-if-failure} (defaults to exiting with an error
6866 message).
6867 @end defmac
6869 @node System Services
6870 @section System Services
6872 The following macros check for operating system services or capabilities.
6874 @defmac AC_PATH_X
6875 @acindex{PATH_X}
6876 @evindex XMKMF
6877 @cindex X Window System
6878 Try to locate the X Window System include files and libraries.  If the
6879 user gave the command line options @option{--x-includes=@var{dir}} and
6880 @option{--x-libraries=@var{dir}}, use those directories.
6882 If either or both were not given, get the missing values by running
6883 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
6884 environment variable) on a trivial @file{Imakefile} and examining the
6885 @file{Makefile} that it produces.  Setting @code{XMKMF} to @samp{false}
6886 will disable this method.
6888 If this method fails to find the X Window System, @command{configure}
6889 will look for the files in several directories where they often reside.
6890 If either method is successful, set the shell variables
6891 @code{x_includes} and @code{x_libraries} to their locations, unless they
6892 are in directories the compiler searches by default.
6894 If both methods fail, or the user gave the command line option
6895 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
6896 otherwise set it to the empty string.
6897 @end defmac
6899 @defmac AC_PATH_XTRA
6900 @acindex{PATH_XTRA}
6901 @ovindex X_CFLAGS
6902 @ovindex X_LIBS
6903 @ovindex X_EXTRA_LIBS
6904 @ovindex X_PRE_LIBS
6905 @cvindex X_DISPLAY_MISSING
6906 An enhanced version of @code{AC_PATH_X}.  It adds the C compiler flags
6907 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
6908 to @code{X_LIBS}.  Define @code{X_DISPLAY_MISSING} if X is not
6909 available.
6911 This macro also checks for special libraries that some systems need in
6912 order to compile X programs.  It adds any that the system needs to
6913 output variable @code{X_EXTRA_LIBS}.  And it checks for special X11R6
6914 libraries that need to be linked with before @option{-lX11}, and adds
6915 any found to the output variable @code{X_PRE_LIBS}.
6917 @c This is an incomplete kludge.  Make a real way to do it.
6918 @c If you need to check for other X functions or libraries yourself, then
6919 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
6920 @c @code{LIBS} temporarily, like this: (FIXME - add example)
6921 @end defmac
6923 @defmac AC_SYS_INTERPRETER
6924 @acindex{SYS_INTERPRETER}
6925 Check whether the system supports starting scripts with a line of the
6926 form @samp{#!/bin/sh} to select the interpreter to use for the script.
6927 After running this macro, shell code in @file{configure.ac} can check
6928 the shell variable @code{interpval}; it will be set to @samp{yes}
6929 if the system supports @samp{#!}, @samp{no} if not.
6930 @end defmac
6932 @defmac AC_SYS_LARGEFILE
6933 @acindex{SYS_LARGEFILE}
6934 @cvindex _FILE_OFFSET_BITS
6935 @cvindex _LARGE_FILES
6936 @ovindex CC
6937 @cindex Large file support
6938 @cindex LFS
6939 Arrange for
6940 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
6941 large-file support}.  On some hosts, one must use special compiler
6942 options to build programs that can access large files.  Append any such
6943 options to the output variable @code{CC}.  Define
6944 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
6946 Large-file support can be disabled by configuring with the
6947 @option{--disable-largefile} option.
6949 If you use this macro, check that your program works even when
6950 @code{off_t} is wider than @code{long int}, since this is common when
6951 large-file support is enabled.  For example, it is not correct to print
6952 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
6953 (long int) X)}.
6955 The LFS introduced the @code{fseeko} and @code{ftello} functions to
6956 replace their C counterparts @code{fseek} and @code{ftell} that do not
6957 use @code{off_t}.  Take care to use @code{AC_FUNC_FSEEKO} to make their
6958 prototypes available when using them and large-file support is
6959 enabled.
6960 @end defmac
6962 @defmac AC_SYS_LONG_FILE_NAMES
6963 @acindex{SYS_LONG_FILE_NAMES}
6964 @cvindex HAVE_LONG_FILE_NAMES
6965 If the system supports file names longer than 14 characters, define
6966 @code{HAVE_LONG_FILE_NAMES}.
6967 @end defmac
6969 @defmac AC_SYS_POSIX_TERMIOS
6970 @acindex{SYS_POSIX_TERMIOS}
6971 @cindex Posix termios headers
6972 @cindex termios Posix headers
6973 Check to see if the Posix termios headers and functions are available on the
6974 system.  If so, set the shell variable @code{ac_cv_sys_posix_termios} to
6975 @samp{yes}.  If not, set the variable to @samp{no}.
6976 @end defmac
6978 @node Posix Variants
6979 @section Posix Variants
6981 The following macros check for certain operating systems that need
6982 special treatment for some programs, due to exceptional oddities in
6983 their header files or libraries.  These macros are warts; they will be
6984 replaced by a more systematic approach, based on the functions they make
6985 available or the environments they provide.
6987 @defmac AC_AIX
6988 @acindex{AIX}
6989 @cvindex _ALL_SOURCE
6990 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
6991 Allows the use of some @acronym{BSD}
6992 functions.  Should be called before any macros that run the C compiler.
6993 @end defmac
6995 @defmac AC_GNU_SOURCE
6996 @acindex{GNU_SOURCE}
6997 @cvindex _GNU_SOURCE
6998 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
6999 Allows the use of some @acronym{GNU} functions.  Should be called
7000 before any macros that run the C compiler.
7001 @end defmac
7003 @defmac AC_ISC_POSIX
7004 @acindex{ISC_POSIX}
7005 @ovindex LIBS
7006 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7007 variable @code{LIBS} if necessary for Posix facilities.  Call this
7008 after @code{AC_PROG_CC} and before any other macros that use Posix
7009 interfaces.  @sc{interactive} Unix is no longer sold, and Sun says that
7010 they will drop support for it on 2006-07-23, so this macro is becoming
7011 obsolescent.
7012 @end defmac
7014 @defmac AC_MINIX
7015 @acindex{MINIX}
7016 @cvindex _MINIX
7017 @cvindex _POSIX_SOURCE
7018 @cvindex _POSIX_1_SOURCE
7019 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7020 @code{_POSIX_1_SOURCE} to be 2.  This allows the use of Posix
7021 facilities.  Should be called before any macros that run the C compiler.
7022 @end defmac
7024 @defmac AC_USE_SYSTEM_EXTENSIONS
7025 @acindex{USE_SYSTEM_EXTENSIONS}
7026 @cvindex _ALL_SOURCE
7027 @cvindex _GNU_SOURCE
7028 @cvindex _MINIX
7029 @cvindex _POSIX_1_SOURCE
7030 @cvindex _POSIX_PTHREAD_SEMANTICS
7031 @cvindex _POSIX_SOURCE
7032 @cvindex __EXTENSIONS__
7033 If possible, enable extensions to Posix on hosts that normally disable
7034 the extensions, typically due to standards-conformance namespace issues.
7035 This may involve defining @code{__EXTENSIONS__} and
7036 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.  This
7037 macro also has the combined effects of @code{AC_GNU_SOURCE},
7038 @code{AC_AIX}, and @code{AC_MINIX}.
7039 @end defmac
7042 @node Erlang Libraries
7043 @section Erlang Libraries
7044 @cindex Erlang, Library, checking
7046 The following macros check for an installation of Erlang/OTP, and for the
7047 presence of certain Erlang libraries.  All those macros require the
7048 configuration of an Erlang interpreter and an Erlang compiler
7049 (@pxref{Erlang Compiler and Interpreter}).
7051 @defmac AC_ERLANG_SUBST_ROOT_DIR
7052 @acindex{ERLANG_SUBST_ROOT_DIR}
7053 @ovindex ERLANG_ROOT_DIR
7055 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7056 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7057 function).  The result of this test is cached if caching is enabled when running
7058 @command{configure}.
7059 @end defmac
7061 @defmac AC_ERLANG_SUBST_LIB_DIR
7062 @acindex{ERLANG_SUBST_LIB_DIR}
7063 @ovindex ERLANG_LIB_DIR
7065 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7066 directory of Erlang/OTP (as returned by Erlang's
7067 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7068 Erlang/OTP library.  The result of this test is cached if caching is enabled
7069 when running @command{configure}.
7070 @end defmac
7072 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7073 @acindex{ERLANG_CHECK_LIB}
7074 @ovindex ERLANG_LIB_DIR_@var{library}
7076 Test whether the Erlang/OTP library @var{library} is installed by calling
7077 Erlang's @code{code:lib_dir/1} function.  The result of this test is cached if
7078 caching is enabled when running @command{configure}.  @var{action-if-found} is a
7079 list of shell commands to run if the library is installed;
7080 @var{action-if-not-found} is a list of shell commands to run if it is not.
7081 Additionally, if the library is installed, the output variable
7082 @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the library
7083 installation directory.  For example, to check if library @code{stdlib} is
7084 installed:
7086 @example
7087 AC_ERLANG_CHECK_LIB([stdlib],
7088   [echo "stdlib is installed in $ERLANG_LIB_DIR_stdlib"],
7089   [AC_MSG_ERROR([stdlib was not found!])])
7090 @end example
7091 @end defmac
7093 In addition to the above macros, which test installed Erlang libraries, the
7094 following macros determine the paths to the directories into which newly built
7095 Erlang libraries are to be installed:
7097 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7098 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7099 @ovindex ERLANG_INSTALL_LIB_DIR
7101 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7102 which every built Erlang library should be installed in a separate subdirectory.
7103 If this variable is not set in the environment when @command{configure} runs,
7104 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7105 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7106 @end defmac
7108 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7109 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7110 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7112 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7113 directory into which the built Erlang library @var{library} version
7114 @var{version} should be installed.  If this variable is not set in the
7115 environment when @command{configure} runs, its default value is
7116 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7117 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7118 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7119 @end defmac
7125 @c ========================================================= Writing Tests
7127 @node Writing Tests
7128 @chapter Writing Tests
7130 If the existing feature tests don't do something you need, you have to
7131 write new ones.  These macros are the building blocks.  They provide
7132 ways for other macros to check whether various kinds of features are
7133 available and report the results.
7135 This chapter contains some suggestions and some of the reasons why the
7136 existing tests are written the way they are.  You can also learn a lot
7137 about how to write Autoconf tests by looking at the existing ones.  If
7138 something goes wrong in one or more of the Autoconf tests, this
7139 information can help you understand the assumptions behind them, which
7140 might help you figure out how to best solve the problem.
7142 These macros check the output of the compiler system of the current
7143 language (@pxref{Language Choice}).  They do not cache the results of
7144 their tests for future use (@pxref{Caching Results}), because they don't
7145 know enough about the information they are checking for to generate a
7146 cache variable name.  They also do not print any messages, for the same
7147 reason.  The checks for particular kinds of features call these macros
7148 and do cache their results and print messages about what they're
7149 checking for.
7151 When you write a feature test that could be applicable to more than one
7152 software package, the best thing to do is encapsulate it in a new macro.
7153 @xref{Writing Autoconf Macros}, for how to do that.
7155 @menu
7156 * Language Choice::             Selecting which language to use for testing
7157 * Writing Test Programs::       Forging source files for compilers
7158 * Running the Preprocessor::    Detecting preprocessor symbols
7159 * Running the Compiler::        Detecting language or header features
7160 * Running the Linker::          Detecting library features
7161 * Runtime::                     Testing for runtime features
7162 * Systemology::                 A zoology of operating systems
7163 * Multiple Cases::              Tests for several possible values
7164 @end menu
7166 @node Language Choice
7167 @section Language Choice
7168 @cindex Language
7170 Autoconf-generated @command{configure} scripts check for the C compiler and
7171 its features by default.  Packages that use other programming languages
7172 (maybe more than one, e.g., C and C++) need to test features of the
7173 compilers for the respective languages.  The following macros determine
7174 which programming language is used in the subsequent tests in
7175 @file{configure.ac}.
7177 @defmac AC_LANG (@var{language})
7178 Do compilation tests using the compiler, preprocessor, and file
7179 extensions for the specified @var{language}.
7181 Supported languages are:
7183 @table @samp
7184 @item C
7185 Do compilation tests using @code{CC} and @code{CPP} and use extension
7186 @file{.c} for test programs.  Use compilation flags: @code{CPPFLAGS} with
7187 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7189 @item C++
7190 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7191 extension @file{.C} for test programs.  Use compilation flags:
7192 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
7193 @code{CXXFLAGS} with @code{CXX}.
7195 @item Fortran 77
7196 Do compilation tests using @code{F77} and use extension @file{.f} for
7197 test programs.  Use compilation flags: @code{FFLAGS}.
7199 @item Fortran
7200 Do compilation tests using @code{FC} and use extension @file{.f} (or
7201 whatever has been set by @code{AC_FC_SRCEXT}) for test programs.  Use
7202 compilation flags: @code{FCFLAGS}.
7204 @item Erlang
7205 @ovindex ERLC
7206 @ovindex ERL
7207 @ovindex ERLCFLAGS
7208 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7209 @file{.erl} for test Erlang modules.  Use compilation flags: @code{ERLCFLAGS}.
7211 @item Objective C
7212 Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use
7213 extension @file{.m} for test programs.  Use compilation flags:
7214 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7215 @code{OBJCFLAGS} with @code{OBJC}.
7216 @end table
7217 @end defmac
7219 @defmac AC_LANG_PUSH (@var{language})
7220 @acindex{LANG_PUSH}
7221 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7222 then select the @var{language}.  Use this macro and @code{AC_LANG_POP}
7223 in macros that need to temporarily switch to a particular language.
7224 @end defmac
7226 @defmac AC_LANG_POP (@ovar{language})
7227 @acindex{LANG_POP}
7228 Select the language that is saved on the top of the stack, as set by
7229 @code{AC_LANG_PUSH}, and remove it from the stack.
7231 If given, @var{language} specifies the language we just @emph{quit}.  It
7232 is a good idea to specify it when it's known (which should be the
7233 case@dots{}), since Autoconf will detect inconsistencies.
7235 @example
7236 AC_LANG_PUSH([Fortran 77])
7237 # Perform some tests on Fortran 77.
7238 # @dots{}
7239 AC_LANG_POP([Fortran 77])
7240 @end example
7241 @end defmac
7243 @defmac AC_LANG_ASSERT (@var{language})
7244 @acindex{LANG_ASSERT} Check statically that the current language is
7245 @var{language}.  You should use this in your language specific macros
7246 to avoid that they be called with an inappropriate language.
7248 This macro runs only at @command{autoconf} time, and incurs no cost at
7249 @command{configure} time.  Sadly enough and because Autoconf is a two
7250 layer language @footnote{Because M4 is not aware of Sh code,
7251 especially conditionals, some optimizations that look nice statically
7252 may produce incorrect results at runtime.}, the macros
7253 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7254 therefore as much as possible you ought to avoid using them to wrap
7255 your code, rather, require from the user to run the macro with a
7256 correct current language, and check it with @code{AC_LANG_ASSERT}.
7257 And anyway, that may help the user understand she is running a Fortran
7258 macro while expecting a result about her Fortran 77 compiler@dots{}
7259 @end defmac
7262 @defmac AC_REQUIRE_CPP
7263 @acindex{REQUIRE_CPP}
7264 Ensure that whichever preprocessor would currently be used for tests has
7265 been found.  Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7266 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7267 depending on which language is current.
7268 @end defmac
7271 @node Writing Test Programs
7272 @section Writing Test Programs
7274 Autoconf tests follow a common scheme: feed some program with some
7275 input, and most of the time, feed a compiler with some source file.
7276 This section is dedicated to these source samples.
7278 @menu
7279 * Guidelines::                  General rules for writing test programs
7280 * Test Functions::              Avoiding pitfalls in test programs
7281 * Generating Sources::          Source program boilerplate
7282 @end menu
7284 @node Guidelines
7285 @subsection Guidelines for Test Programs
7287 The most important rule to follow when writing testing samples is:
7289 @center @emph{Look for realism.}
7291 This motto means that testing samples must be written with the same
7292 strictness as real programs are written.  In particular, you should
7293 avoid ``shortcuts'' and simplifications.
7295 Don't just play with the preprocessor if you want to prepare a
7296 compilation.  For instance, using @command{cpp} to check whether a header is
7297 functional might let your @command{configure} accept a header which will
7298 cause some @emph{compiler} error.  Do not hesitate checking header with
7299 other headers included before, especially required headers.
7301 Make sure the symbols you use are properly defined, i.e., refrain for
7302 simply declaring a function yourself instead of including the proper
7303 header.
7305 Test programs should not write to standard output.  They
7306 should exit with status 0 if the test succeeds, and with status 1
7307 otherwise, so that success
7308 can be distinguished easily from a core dump or other failure;
7309 segmentation violations and other failures produce a nonzero exit
7310 status.  Unless you arrange for @code{exit} to be declared, test
7311 programs should @code{return}, not @code{exit}, from @code{main},
7312 because on many systems @code{exit} is not declared by default.
7314 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7315 preprocessor macros defined by tests that have already run.  For
7316 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7317 @file{configure.ac} you can have a test program that includes
7318 @file{stdbool.h} conditionally:
7320 @example
7321 @group
7322 #if HAVE_STDBOOL_H
7323 # include <stdbool.h>
7324 #endif
7325 @end group
7326 @end example
7328 If a test program needs to use or create a data file, give it a name
7329 that starts with @file{conftest}, such as @file{conftest.data}.  The
7330 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7331 after running test programs and if the script is interrupted.
7333 @node Test Functions
7334 @subsection Test Functions
7336 These days it's safe to assume support for function prototypes
7337 (introduced in C89).
7339 Functions that test programs declare should also be conditionalized for
7340 C++, which requires @samp{extern "C"} prototypes.  Make sure to not
7341 include any header files containing clashing prototypes.
7343 @example
7344 #ifdef __cplusplus
7345 extern "C"
7346 #endif
7347 void *valloc (size_t);
7348 @end example
7350 If a test program calls a function with invalid parameters (just to see
7351 whether it exists), organize the program to ensure that it never invokes
7352 that function.  You can do this by calling it in another function that is
7353 never invoked.  You can't do it by putting it after a call to
7354 @code{exit}, because GCC version 2 knows that @code{exit} never returns
7355 and optimizes out any code that follows it in the same block.
7357 If you include any header files, be sure to call the functions
7358 relevant to them with the correct number of arguments, even if they are
7359 just 0, to avoid compilation errors due to prototypes.  GCC version 2
7360 has internal prototypes for several functions that it automatically
7361 inlines; for example, @code{memcpy}.  To avoid errors when checking for
7362 them, either pass them the correct number of arguments or redeclare them
7363 with a different return type (such as @code{char}).
7366 @node Generating Sources
7367 @subsection Generating Sources
7369 Autoconf provides a set of macros that can be used to generate test
7370 source files.  They are written to be language generic, i.e., they
7371 actually depend on the current language (@pxref{Language Choice}) to
7372 ``format'' the output properly.
7375 @defmac AC_LANG_CONFTEST (@var{source})
7376 @acindex{LANG_CONFTEST}
7377 Save the @var{source} text in the current test source file:
7378 @file{conftest.@var{extension}} where the @var{extension} depends on the
7379 current language.
7381 Note that the @var{source} is evaluated exactly once, like regular
7382 Autoconf macro arguments, and therefore (i) you may pass a macro
7383 invocation, (ii) if not, be sure to double quote if needed.
7384 @end defmac
7386 @defmac AC_LANG_SOURCE (@var{source})
7387 @acindex{LANG_SOURCE}
7388 Expands into the @var{source}, with the definition of
7389 all the @code{AC_DEFINE} performed so far.
7390 @end defmac
7392 For instance executing (observe the double quotation!):
7394 @example
7395 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7396 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7397   [Greetings string.])
7398 AC_LANG(C)
7399 AC_LANG_CONFTEST(
7400    [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7401 gcc -E -dD -o - conftest.c
7402 @end example
7404 @noindent
7405 results in:
7407 @example
7408 @dots{}
7409 # 1 "conftest.c"
7411 #define PACKAGE_NAME "Hello"
7412 #define PACKAGE_TARNAME "hello"
7413 #define PACKAGE_VERSION "1.0"
7414 #define PACKAGE_STRING "Hello 1.0"
7415 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7416 #define HELLO_WORLD "Hello, World\n"
7418 const char hw[] = "Hello, World\n";
7419 @end example
7421 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7422 are not automatically translated into constants in the source code by this
7423 macro.
7425 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7426 @acindex{LANG_PROGRAM}
7427 Expands into a source file which consists of the @var{prologue}, and
7428 then @var{body} as body of the main function (e.g., @code{main} in
7429 C).  Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7430 available.
7431 @end defmac
7433 For instance:
7435 @example
7436 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7437 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7438   [Greetings string.])
7439 AC_LANG_CONFTEST(
7440 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7441                  [[fputs (hw, stdout);]])])
7442 gcc -E -dD -o - conftest.c
7443 @end example
7445 @noindent
7446 results in:
7448 @example
7449 @dots{}
7450 # 1 "conftest.c"
7452 #define PACKAGE_NAME "Hello"
7453 #define PACKAGE_TARNAME "hello"
7454 #define PACKAGE_VERSION "1.0"
7455 #define PACKAGE_STRING "Hello 1.0"
7456 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7457 #define HELLO_WORLD "Hello, World\n"
7459 const char hw[] = "Hello, World\n";
7461 main ()
7463 fputs (hw, stdout);
7464   ;
7465   return 0;
7467 @end example
7469 In Erlang tests, the created source file is that of an Erlang module called
7470 @code{conftest} (@file{conftest.erl}).  This module defines and exports at least
7471 one @code{start/0} function, which is called to perform the test.  The
7472 @var{prologue} is optional code that is inserted between the module header and
7473 the @code{start/0} function definition.  @var{body} is the body of the
7474 @code{start/0} function without the final period (@pxref{Runtime}, about
7475 constraints on this function's behaviour).
7477 For instance:
7479 @example
7480 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7481 AC_LANG(Erlang)
7482 AC_LANG_CONFTEST(
7483 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7484                  [[io:format("~s~n", [?HELLO_WORLD])]])])
7485 cat conftest.erl
7486 @end example
7488 @noindent
7489 results in:
7491 @example
7492 -module(conftest).
7493 -export([start/0]).
7494 -define(HELLO_WORLD, "Hello, world!").
7495 start() ->
7496 io:format("~s~n", [?HELLO_WORLD])
7498 @end example
7500 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7501 @acindex{LANG_CALL}
7502 Expands into a source file which consists of the @var{prologue}, and
7503 then a call to the @var{function} as body of the main function (e.g.,
7504 @code{main} in C).  Since it uses @code{AC_LANG_PROGRAM}, the feature
7505 of the latter are available.
7507 This function will probably be replaced in the future by a version
7508 which would enable specifying the arguments.  The use of this macro is
7509 not encouraged, as it violates strongly the typing system.
7511 This macro cannot be used for Erlang tests.
7512 @end defmac
7514 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7515 @acindex{LANG_FUNC_LINK_TRY}
7516 Expands into a source file which uses the @var{function} in the body of
7517 the main function (e.g., @code{main} in C).  Since it uses
7518 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7520 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7521 It is considered to be severely broken, and in the future will be
7522 removed in favor of actual function calls (with properly typed
7523 arguments).
7525 This macro cannot be used for Erlang tests.
7526 @end defmac
7528 @node Running the Preprocessor
7529 @section Running the Preprocessor
7531 Sometimes one might need to run the preprocessor on some source file.
7532 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7533 your project, not merely run the preprocessor on it; therefore you
7534 certainly want to run the compiler, not the preprocessor.  Resist the
7535 temptation of following the easiest path.
7537 Nevertheless, if you need to run the preprocessor, then use
7538 @code{AC_PREPROC_IFELSE}.
7540 The macros described in this section cannot be used for tests in Erlang or
7541 Fortran, since those languages require no preprocessor.
7543 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7544 @acindex{PREPROC_IFELSE}
7545 Run the preprocessor of the current language (@pxref{Language Choice})
7546 on the @var{input}, run the shell commands @var{action-if-true} on
7547 success, @var{action-if-false} otherwise.  The @var{input} can be made
7548 by @code{AC_LANG_PROGRAM} and friends.
7550 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7551 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7552 preprocessors.
7554 It is customary to report unexpected failures with
7555 @code{AC_MSG_FAILURE}.
7556 @end defmac
7558 For instance:
7560 @example
7561 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7562 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7563   [Greetings string.])
7564 AC_PREPROC_IFELSE(
7565    [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7566                     [[fputs (hw, stdout);]])],
7567    [AC_MSG_RESULT([OK])],
7568    [AC_MSG_FAILURE([unexpected preprocessor failure])])
7569 @end example
7571 @noindent
7572 results in:
7574 @example
7575 checking for gcc... gcc
7576 checking for C compiler default output file name... a.out
7577 checking whether the C compiler works... yes
7578 checking whether we are cross compiling... no
7579 checking for suffix of executables...
7580 checking for suffix of object files... o
7581 checking whether we are using the GNU C compiler... yes
7582 checking whether gcc accepts -g... yes
7583 checking for gcc option to accept ISO C89... none needed
7584 checking how to run the C preprocessor... gcc -E
7586 @end example
7588 @sp 1
7590 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7591 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7592 it impossible to use it to elaborate sources.  You are encouraged to
7593 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7594 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7595 to run the @emph{preprocessor} and not the compiler?
7597 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7598 @acindex{EGREP_HEADER}
7599 If the output of running the preprocessor on the system header file
7600 @var{header-file} matches the extended regular expression
7601 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7602 execute @var{action-if-not-found}.
7603 @end defmac
7605 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7606 @acindex{EGREP_CPP}
7607 @var{program} is the text of a C or C++ program, on which shell
7608 variable, back quote, and backslash substitutions are performed.  If the
7609 output of running the preprocessor on @var{program} matches the
7610 extended regular expression @var{pattern}, execute shell commands
7611 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7612 @end defmac
7616 @node Running the Compiler
7617 @section Running the Compiler
7619 To check for a syntax feature of the current language's (@pxref{Language
7620 Choice}) compiler, such as whether it recognizes a certain keyword, or
7621 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7622 to compile a small program that uses that feature.
7624 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7625 @acindex{COMPILE_IFELSE}
7626 Run the compiler and compilation flags of the current language
7627 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7628 @var{action-if-true} on success, @var{action-if-false} otherwise.  The
7629 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7631 It is customary to report unexpected failures with
7632 @code{AC_MSG_FAILURE}.  This macro does not try to link; use
7633 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7634 Linker}).
7635 @end defmac
7637 @ovindex ERL
7638 For tests in Erlang, the @var{input} must be the source code of a module named
7639 @code{conftest}.  @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7640 file that can be interpreted by the Erlang virtual machine (@code{ERL}).  It is
7641 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7642 that the Erlang module has the right name.
7644 @node Running the Linker
7645 @section Running the Linker
7647 To check for a library, a function, or a global variable, Autoconf
7648 @command{configure} scripts try to compile and link a small program that
7649 uses it.  This is unlike Metaconfig, which by default uses @code{nm} or
7650 @code{ar} on the C library to try to figure out which functions are
7651 available.  Trying to link with the function is usually a more reliable
7652 approach because it avoids dealing with the variations in the options
7653 and output formats of @code{nm} and @code{ar} and in the location of the
7654 standard libraries.  It also allows configuring for cross-compilation or
7655 checking a function's runtime behavior if needed.  On the other hand,
7656 it can be slower than scanning the libraries once, but accuracy is more
7657 important than speed.
7659 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7660 functions and global variables.  It is also used by @code{AC_CHECK_LIB}
7661 to check for libraries (@pxref{Libraries}), by adding the library being
7662 checked for to @code{LIBS} temporarily and trying to link a small
7663 program.
7666 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7667 @acindex{LINK_IFELSE}
7668 Run the compiler (and compilation flags) and the linker of the current
7669 language (@pxref{Language Choice}) on the @var{input}, run the shell
7670 commands @var{action-if-true} on success, @var{action-if-false}
7671 otherwise.  The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7672 friends.
7674 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7675 current compilation flags.
7677 It is customary to report unexpected failures with
7678 @code{AC_MSG_FAILURE}.  This macro does not try to execute the program;
7679 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
7680 @end defmac
7682 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
7683 programs are interpreted and do not require linking.
7687 @node Runtime
7688 @section Checking Runtime Behavior
7690 Sometimes you need to find out how a system performs at runtime, such
7691 as whether a given function has a certain capability or bug.  If you
7692 can, make such checks when your program runs instead of when it is
7693 configured.  You can check for things like the machine's endianness when
7694 your program initializes itself.
7696 If you really need to test for a runtime behavior while configuring,
7697 you can write a test program to determine the result, and compile and
7698 run it using @code{AC_RUN_IFELSE}.  Avoid running test programs if
7699 possible, because this prevents people from configuring your package for
7700 cross-compiling.
7702 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
7703 @acindex{RUN_IFELSE}
7704 If @var{program} compiles and links successfully and returns an exit
7705 status of 0 when executed, run shell commands @var{action-if-true}.
7706 Otherwise, run shell commands @var{action-if-false}.
7708 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7709 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7710 compilation flags of the current language (@pxref{Language Choice}).
7712 If the compiler being used does not produce executables that run on the
7713 system where @command{configure} is being run, then the test program is
7714 not run.  If the optional shell commands @var{action-if-cross-compiling}
7715 are given, they are run instead.  Otherwise, @command{configure} prints
7716 an error message and exits.
7718 In the @var{action-if-false} section, the failing exit status is
7719 available in the shell variable @samp{$?}.  This exit status might be
7720 that of a failed compilation, or it might be that of a failed program
7721 execution.
7723 It is customary to report unexpected failures with
7724 @code{AC_MSG_FAILURE}.
7725 @end defmac
7727 Try to provide a pessimistic default value to use when cross-compiling
7728 makes runtime tests impossible.  You do this by passing the optional
7729 last argument to @code{AC_RUN_IFELSE}.  @command{autoconf} prints a
7730 warning message when creating @command{configure} each time it
7731 encounters a call to @code{AC_RUN_IFELSE} with no
7732 @var{action-if-cross-compiling} argument given.  You may ignore the
7733 warning, though users will not be able to configure your package for
7734 cross-compiling.  A few of the macros distributed with Autoconf produce
7735 this warning message.
7737 To configure for cross-compiling you can also choose a value for those
7738 parameters based on the canonical system name (@pxref{Manual
7739 Configuration}).  Alternatively, set up a test results cache file with
7740 the correct values for the host system (@pxref{Caching Results}).
7742 @ovindex cross_compiling
7743 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
7744 in other macros, including a few of the ones that come with Autoconf,
7745 you can test whether the shell variable @code{cross_compiling} is set to
7746 @samp{yes}, and then use an alternate method to get the results instead
7747 of calling the macros.
7749 A C or C++ runtime test should be portable.
7750 @xref{Portable C and C++}.
7752 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
7753 function: the given status code is used to determine the success of the test
7754 (status is @code{0}) or its failure (status is different than @code{0}), as
7755 explained above.  It must be noted that data output through the standard output
7756 (e.g. using @code{io:format/2}) may be truncated when halting the VM.
7757 Therefore, if a test must output configuration information, it is recommended
7758 to create and to output data into the temporary file named @file{conftest.out},
7759 using the functions of module @code{file}.  The @code{conftest.out} file is
7760 automatically deleted by the @code{AC_RUN_IFELSE} macro.  For instance, a
7761 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
7763 @example
7764 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
7765 AC_ERLANG_NEED_ERL
7766 AC_LANG(Erlang)
7767 AC_RUN_IFELSE(
7768   [AC_LANG_PROGRAM([], [dnl
7769     file:write_file("conftest.out", code:lib_dir()),
7770     halt(0)])],
7771   [echo "code:lib_dir() returned: `cat conftest.out`"],
7772   [AC_MSG_FAILURE([test Erlang program execution failed])])
7773 @end example
7776 @node Systemology
7777 @section Systemology
7778 @cindex Systemology
7780 This section aims at presenting some systems and pointers to
7781 documentation.  It may help you addressing particular problems reported
7782 by users.
7784 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
7785 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
7786 operating system}.
7788 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
7789 contains a table correlating the features of various Posix-conforming
7790 systems.  @uref{http://www.levenez.com/unix/, Unix History} is a
7791 simplified diagram of how many Unix systems were derived from each
7792 other.
7794 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
7795 provides some variants of traditional implementations of Unix utilities.
7797 @table @asis
7798 @item Darwin
7799 @cindex Darwin
7800 Darwin is also known as Mac OS X@.  Beware that the file system @emph{can} be
7801 case-preserving, but case insensitive.  This can cause nasty problems,
7802 since for instance the installation attempt for a package having an
7803 @file{INSTALL} file can result in @samp{make install} report that
7804 nothing was to be done!
7806 That's all dependent on whether the file system is a UFS (case
7807 sensitive) or HFS+ (case preserving).  By default Apple wants you to
7808 install the OS on HFS+.  Unfortunately, there are some pieces of
7809 software which really need to be built on UFS@.  We may want to rebuild
7810 Darwin to have both UFS and HFS+ available (and put the /local/build
7811 tree on the UFS).
7813 @item @acronym{QNX} 4.25
7814 @cindex @acronym{QNX} 4.25
7815 @c FIXME: Please, if you feel like writing something more precise,
7816 @c it'd be great.  In particular, I can't understand the difference with
7817 @c QNX Neutrino.
7818 @acronym{QNX} is a realtime operating system running on Intel architecture
7819 meant to be scalable from the small embedded systems to the hundred
7820 processor super-computer.  It claims to be Posix certified.  More
7821 information is available on the
7822 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
7824 @item Tru64
7825 @cindex Tru64
7826 @uref{http://h30097.www3.hp.com/@/docs/,
7827 Documentation of several versions of Tru64} is available in different
7828 formats.
7830 @item Unix version 7
7831 @cindex Unix version 7
7832 @cindex V7
7833 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
7834 time-sharing system'' but we use the more-common name ``Unix version 7''.
7835 Documentation is available in the
7836 @uref{http://plan9.bell-labs.com/7thEdMan/, Unix Seventh Edition Manual}.
7837 Previous versions of Unix are called ``Unix version 6'', etc., but
7838 they were not as widely used.
7839 @end table
7842 @node Multiple Cases
7843 @section Multiple Cases
7845 Some operations are accomplished in several possible ways, depending on
7846 the OS variant.  Checking for them essentially requires a ``case
7847 statement''.  Autoconf does not directly provide one; however, it is
7848 easy to simulate by using a shell variable to keep track of whether a
7849 way to perform the operation has been found yet.
7851 Here is an example that uses the shell variable @code{fstype} to keep
7852 track of whether the remaining cases need to be checked.
7854 @example
7855 @group
7856 AC_MSG_CHECKING([how to get file system type])
7857 fstype=no
7858 # The order of these tests is important.
7859 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
7860 #include <sys/fstyp.h>]])],
7861                   [AC_DEFINE([FSTYPE_STATVFS], [1],
7862                      [Define if statvfs exists.])
7863                    fstype=SVR4])
7864 if test $fstype = no; then
7865   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7866 #include <sys/fstyp.h>]])],
7867                   [AC_DEFINE([FSTYPE_USG_STATFS], [1],
7868                      [Define if USG statfs.])
7869                    fstype=SVR3])
7871 if test $fstype = no; then
7872   AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7873 #include <sys/vmount.h>]])]),
7874                   [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
7875                      [Define if AIX statfs.])
7876                    fstype=AIX])
7878 # (more cases omitted here)
7879 AC_MSG_RESULT([$fstype])
7880 @end group
7881 @end example
7883 @c ====================================================== Results of Tests.
7885 @node Results
7886 @chapter Results of Tests
7888 Once @command{configure} has determined whether a feature exists, what can
7889 it do to record that information?  There are four sorts of things it can
7890 do: define a C preprocessor symbol, set a variable in the output files,
7891 save the result in a cache file for future @command{configure} runs, and
7892 print a message letting the user know the result of the test.
7894 @menu
7895 * Defining Symbols::            Defining C preprocessor symbols
7896 * Setting Output Variables::    Replacing variables in output files
7897 * Special Chars in Variables::  Characters to beware of in variables
7898 * Caching Results::             Speeding up subsequent @command{configure} runs
7899 * Printing Messages::           Notifying @command{configure} users
7900 @end menu
7902 @node Defining Symbols
7903 @section Defining C Preprocessor Symbols
7905 A common action to take in response to a feature test is to define a C
7906 preprocessor symbol indicating the results of the test.  That is done by
7907 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
7909 By default, @code{AC_OUTPUT} places the symbols defined by these macros
7910 into the output variable @code{DEFS}, which contains an option
7911 @option{-D@var{symbol}=@var{value}} for each symbol defined.  Unlike in
7912 Autoconf version 1, there is no variable @code{DEFS} defined while
7913 @command{configure} is running.  To check whether Autoconf macros have
7914 already defined a certain C preprocessor symbol, test the value of the
7915 appropriate cache variable, as in this example:
7917 @example
7918 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
7919                           [Define if vprintf exists.])])
7920 if test "$ac_cv_func_vprintf" != yes; then
7921   AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
7922                             [Define if _doprnt exists.])])
7924 @end example
7926 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
7927 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
7928 correct values into @code{#define} statements in a template file.
7929 @xref{Configuration Headers}, for more information about this kind of
7930 output.
7932 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
7933 @defmacx AC_DEFINE (@var{variable})
7934 @acindex{DEFINE}
7935 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
7936 @var{value} should not contain literal newlines, and if you are not
7937 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
7938 characters, as @command{make} tends to eat them.  To use a shell variable,
7939 use @code{AC_DEFINE_UNQUOTED} instead.
7940 @var{description} is only useful if you are using
7941 @code{AC_CONFIG_HEADERS}.  In this case, @var{description} is put into
7942 the generated @file{config.h.in} as the comment before the macro define.
7943 The following example defines the C preprocessor variable
7944 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
7946 @example
7947 AC_DEFINE([EQUATION], ["$a > $b"],
7948   [Equation string.])
7949 @end example
7951 If neither @var{value} nor @var{description} are given, then
7952 @var{value} defaults to 1 instead of to the empty string.  This is for
7953 backwards compatibility with older versions of Autoconf, but this usage
7954 is obsolescent and may be withdrawn in future versions of Autoconf.
7956 If the @var{variable} is a literal string, it is passed to
7957 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
7958 @end defmac
7960 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
7961 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
7962 @acindex{DEFINE_UNQUOTED}
7963 Like @code{AC_DEFINE}, but three shell expansions are
7964 performed---once---on @var{variable} and @var{value}: variable expansion
7965 (@samp{$}), command substitution (@samp{`}), and backslash escaping
7966 (@samp{\}).  Single and double quote characters in the value have no
7967 special meaning.  Use this macro instead of @code{AC_DEFINE} when
7968 @var{variable} or @var{value} is a shell variable.  Examples:
7970 @example
7971 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
7972   [Configuration machine file.])
7973 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
7974   [getgroups return type.])
7975 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
7976   [Translated header name.])
7977 @end example
7978 @end defmac
7980 Due to a syntactical bizarreness of the Bourne shell, do not use
7981 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
7982 calls from other macro calls or shell code; that can cause syntax errors
7983 in the resulting @command{configure} script.  Use either blanks or
7984 newlines.  That is, do this:
7986 @example
7987 AC_CHECK_HEADER([elf.h],
7988   [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
7989 @end example
7991 @noindent
7992 or this:
7994 @example
7995 AC_CHECK_HEADER([elf.h],
7996   [AC_DEFINE([SVR4], [1], [System V Release 4])
7997    LIBS="-lelf $LIBS"])
7998 @end example
8000 @noindent
8001 instead of this:
8003 @example
8004 AC_CHECK_HEADER([elf.h],
8005   [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8006 @end example
8008 @node Setting Output Variables
8009 @section Setting Output Variables
8010 @cindex Output variables
8012 Another way to record the results of tests is to set @dfn{output
8013 variables}, which are shell variables whose values are substituted into
8014 files that @command{configure} outputs.  The two macros below create new
8015 output variables.  @xref{Preset Output Variables}, for a list of output
8016 variables that are always available.
8018 @defmac AC_SUBST (@var{variable}, @ovar{value})
8019 @acindex{SUBST}
8020 Create an output variable from a shell variable.  Make @code{AC_OUTPUT}
8021 substitute the variable @var{variable} into output files (typically one
8022 or more @file{Makefile}s).  This means that @code{AC_OUTPUT} will
8023 replace instances of @samp{@@@var{variable}@@} in input files with the
8024 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8025 is called.  The value can contain newlines.
8026 The substituted value is not rescanned for more output variables;
8027 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8028 literally into the output file.  (The algorithm uses the special marker
8029 @code{|#_!!_#|} internally, so the substituted value cannot contain
8030 @code{|#_!!_#|}.)
8032 If @var{value} is given, in addition assign it to @var{variable}.
8034 The string @var{variable} is passed to @code{m4_pattern_allow}
8035 (@pxref{Forbidden Patterns}).
8036 @end defmac
8038 @defmac AC_SUBST_FILE (@var{variable})
8039 @acindex{SUBST_FILE}
8040 Another way to create an output variable from a shell variable.  Make
8041 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8042 named by shell variable @var{variable} into output files.  This means
8043 that @code{AC_OUTPUT} will replace instances of
8044 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8045 with the contents of the file that the shell variable @var{variable}
8046 names when @code{AC_OUTPUT} is called.  Set the variable to
8047 @file{/dev/null} for cases that do not have a file to insert.
8048 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8049 line by itself, optionally surrounded by spaces and tabs.  The
8050 substitution replaces the whole line, including the spaces, tabs, and
8051 the terminating newline.
8053 This macro is useful for inserting @file{Makefile} fragments containing
8054 special dependencies or other @code{make} directives for particular host
8055 or target types into @file{Makefile}s.  For example, @file{configure.ac}
8056 could contain:
8058 @example
8059 AC_SUBST_FILE([host_frag])
8060 host_frag=$srcdir/conf/sun4.mh
8061 @end example
8063 @noindent
8064 and then a @file{Makefile.in} could contain:
8066 @example
8067 @@host_frag@@
8068 @end example
8070 The string @var{variable} is passed to @code{m4_pattern_allow}
8071 (@pxref{Forbidden Patterns}).
8072 @end defmac
8074 @cindex Previous Variable
8075 @cindex Variable, Precious
8076 Running @command{configure} in varying environments can be extremely
8077 dangerous.  If for instance the user runs @samp{CC=bizarre-cc
8078 ./configure}, then the cache, @file{config.h}, and many other output
8079 files will depend upon @command{bizarre-cc} being the C compiler.  If
8080 for some reason the user runs @command{./configure} again, or if it is
8081 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8082 and @pxref{config.status Invocation}), then the configuration can be
8083 inconsistent, composed of results depending upon two different
8084 compilers.
8086 Environment variables that affect this situation, such as @samp{CC}
8087 above, are called @dfn{precious variables}, and can be declared as such
8088 by @code{AC_ARG_VAR}.
8090 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8091 @acindex{ARG_VAR}
8092 Declare @var{variable} is a precious variable, and include its
8093 @var{description} in the variable section of @samp{./configure --help}.
8095 Being precious means that
8096 @itemize @minus
8097 @item
8098 @var{variable} is @code{AC_SUBST}'d.
8100 @item
8101 The value of @var{variable} when @command{configure} was launched is
8102 saved in the cache, including if it was not specified on the command
8103 line but via the environment.  Indeed, while @command{configure} can
8104 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8105 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8106 which, unfortunately, is what most users do.
8108 We emphasize that it is the @emph{initial} value of @var{variable} which
8109 is saved, not that found during the execution of @command{configure}.
8110 Indeed, specifying @samp{./configure FOO=foo} and letting
8111 @samp{./configure} guess that @code{FOO} is @code{foo} can be two very
8112 different runs.
8114 @item
8115 @var{variable} is checked for consistency between two
8116 @command{configure} runs.  For instance:
8118 @example
8119 $ @kbd{./configure --silent --config-cache}
8120 $ @kbd{CC=cc ./configure --silent --config-cache}
8121 configure: error: `CC' was not set in the previous run
8122 configure: error: changes in the environment can compromise \
8123 the build
8124 configure: error: run `make distclean' and/or \
8125 `rm config.cache' and start over
8126 @end example
8128 @noindent
8129 and similarly if the variable is unset, or if its content is changed.
8132 @item
8133 @var{variable} is kept during automatic reconfiguration
8134 (@pxref{config.status Invocation}) as if it had been passed as a command
8135 line argument, including when no cache is used:
8137 @example
8138 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8139 $ @kbd{./config.status --recheck}
8140 running /bin/sh ./configure undeclared_var=raboof --silent \
8141   CC=/usr/bin/cc  --no-create --no-recursion
8142 @end example
8143 @end itemize
8144 @end defmac
8146 @node Special Chars in Variables
8147 @section Special Characters in Output Variables
8148 @cindex Output variables, special characters in
8150 Many output variables are intended to be evaluated both by
8151 @command{make} and by the shell.  Some characters are expanded
8152 differently in these two contexts, so to avoid confusion these
8153 variables' values should not contain any of the following characters:
8155 @example
8156 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8157 @end example
8159 Also, these variables' values should neither contain newlines, nor start
8160 with @samp{~}, nor contain white space or @samp{:} immediately followed
8161 by @samp{~}.  The values can contain nonempty sequences of white space
8162 characters like tabs and spaces, but each such sequence might
8163 arbitrarily be replaced by a single space during substitution.
8165 These restrictions apply both to the values that @command{configure}
8166 computes, and to the values set directly by the user.  For example, the
8167 following invocations of @command{configure} are problematic, since they
8168 attempt to use special characters within @code{CPPFLAGS}:
8170 @example
8171 CPPFLAGS='-DOUCH="&\"#$*?"' ./configure
8173 ./configure CPPFLAGS='-DOUCH="&\"#$*?"'
8174 @end example
8176 @node Caching Results
8177 @section Caching Results
8178 @cindex Cache
8180 To avoid checking for the same features repeatedly in various
8181 @command{configure} scripts (or in repeated runs of one script),
8182 @command{configure} can optionally save the results of many checks in a
8183 @dfn{cache file} (@pxref{Cache Files}).  If a @command{configure} script
8184 runs with caching enabled and finds a cache file, it reads the results
8185 of previous runs from the cache and avoids rerunning those checks.  As a
8186 result, @command{configure} can then run much faster than if it had to
8187 perform all of the checks every time.
8189 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8190 @acindex{CACHE_VAL}
8191 Ensure that the results of the check identified by @var{cache-id} are
8192 available.  If the results of the check were in the cache file that was
8193 read, and @command{configure} was not given the @option{--quiet} or
8194 @option{--silent} option, print a message saying that the result was
8195 cached; otherwise, run the shell commands @var{commands-to-set-it}.  If
8196 the shell commands are run to determine the value, the value will be
8197 saved in the cache file just before @command{configure} creates its output
8198 files.  @xref{Cache Variable Names}, for how to choose the name of the
8199 @var{cache-id} variable.
8201 The @var{commands-to-set-it} @emph{must have no side effects} except for
8202 setting the variable @var{cache-id}, see below.
8203 @end defmac
8205 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8206 @acindex{CACHE_CHECK}
8207 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8208 messages.  This macro provides a convenient shorthand for the most
8209 common way to use these macros.  It calls @code{AC_MSG_CHECKING} for
8210 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8211 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8213 The @var{commands-to-set-it} @emph{must have no side effects} except for
8214 setting the variable @var{cache-id}, see below.
8215 @end defmac
8217 It is very common to find buggy macros using @code{AC_CACHE_VAL} or
8218 @code{AC_CACHE_CHECK}, because people are tempted to call
8219 @code{AC_DEFINE} in the @var{commands-to-set-it}.  Instead, the code that
8220 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8221 @code{AC_DEFINE}, by examining the value of the cache variable.  For
8222 instance, the following macro is broken:
8224 @example
8225 @group
8226 AC_DEFUN([AC_SHELL_TRUE],
8227 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8228                 [ac_cv_shell_true_works=no
8229                  (true) 2>/dev/null && ac_cv_shell_true_works=yes
8230                  if test "$ac_cv_shell_true_works" = yes; then
8231                    AC_DEFINE([TRUE_WORKS], [1],
8232                              [Define if `true(1)' works properly.])
8233                  fi])
8235 @end group
8236 @end example
8238 @noindent
8239 This fails if the cache is enabled: the second time this macro is run,
8240 @code{TRUE_WORKS} @emph{will not be defined}.  The proper implementation
8243 @example
8244 @group
8245 AC_DEFUN([AC_SHELL_TRUE],
8246 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8247                 [ac_cv_shell_true_works=no
8248                  (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8249  if test "$ac_cv_shell_true_works" = yes; then
8250    AC_DEFINE([TRUE_WORKS], [1],
8251              [Define if `true(1)' works properly.])
8252  fi
8254 @end group
8255 @end example
8257 Also, @var{commands-to-set-it} should not print any messages, for
8258 example with @code{AC_MSG_CHECKING}; do that before calling
8259 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8260 the results of the check are retrieved from the cache or determined by
8261 running the shell commands.
8263 @menu
8264 * Cache Variable Names::        Shell variables used in caches
8265 * Cache Files::                 Files @command{configure} uses for caching
8266 * Cache Checkpointing::         Loading and saving the cache file
8267 @end menu
8269 @node Cache Variable Names
8270 @subsection Cache Variable Names
8271 @cindex Cache variable
8273 The names of cache variables should have the following format:
8275 @example
8276 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8277 @end example
8279 @noindent
8280 for example, @samp{ac_cv_header_stat_broken} or
8281 @samp{ac_cv_prog_gcc_traditional}.  The parts of the variable name are:
8283 @table @asis
8284 @item @var{package-prefix}
8285 An abbreviation for your package or organization; the same prefix you
8286 begin local Autoconf macros with, except lowercase by convention.
8287 For cache values used by the distributed Autoconf macros, this value is
8288 @samp{ac}.
8290 @item @code{_cv_}
8291 Indicates that this shell variable is a cache value.  This string
8292 @emph{must} be present in the variable name, including the leading
8293 underscore.
8295 @item @var{value-type}
8296 A convention for classifying cache values, to produce a rational naming
8297 system.  The values used in Autoconf are listed in @ref{Macro Names}.
8299 @item @var{specific-value}
8300 Which member of the class of cache values this test applies to.
8301 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8302 output variable (@samp{INSTALL}).
8304 @item @var{additional-options}
8305 Any particular behavior of the specific member that this test applies to.
8306 For example, @samp{broken} or @samp{set}.  This part of the name may
8307 be omitted if it does not apply.
8308 @end table
8310 The values assigned to cache variables may not contain newlines.
8311 Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
8312 names of files or functions; so this is not an important restriction.
8314 @node Cache Files
8315 @subsection Cache Files
8317 A cache file is a shell script that caches the results of configure
8318 tests run on one system so they can be shared between configure scripts
8319 and configure runs.  It is not useful on other systems.  If its contents
8320 are invalid for some reason, the user may delete or edit it.
8322 By default, @command{configure} uses no cache file,
8323 to avoid problems caused by accidental
8324 use of stale cache files.
8326 To enable caching, @command{configure} accepts @option{--config-cache} (or
8327 @option{-C}) to cache results in the file @file{config.cache}.
8328 Alternatively, @option{--cache-file=@var{file}} specifies that
8329 @var{file} be the cache file.  The cache file is created if it does not
8330 exist already.  When @command{configure} calls @command{configure} scripts in
8331 subdirectories, it uses the @option{--cache-file} argument so that they
8332 share the same cache.  @xref{Subdirectories}, for information on
8333 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8335 @file{config.status} only pays attention to the cache file if it is
8336 given the @option{--recheck} option, which makes it rerun
8337 @command{configure}.
8339 It is wrong to try to distribute cache files for particular system types.
8340 There is too much room for error in doing that, and too much
8341 administrative overhead in maintaining them.  For any features that
8342 can't be guessed automatically, use the standard method of the canonical
8343 system type and linking files (@pxref{Manual Configuration}).
8345 The site initialization script can specify a site-wide cache file to
8346 use, instead of the usual per-program cache.  In this case, the cache
8347 file will gradually accumulate information whenever someone runs a new
8348 @command{configure} script.  (Running @command{configure} merges the new cache
8349 results with the existing cache file.)  This may cause problems,
8350 however, if the system configuration (e.g., the installed libraries or
8351 compilers) changes and the stale cache file is not deleted.
8353 @node Cache Checkpointing
8354 @subsection Cache Checkpointing
8356 If your configure script, or a macro called from @file{configure.ac}, happens
8357 to abort the configure process, it may be useful to checkpoint the cache
8358 a few times at key points using @code{AC_CACHE_SAVE}.  Doing so will
8359 reduce the amount of time it takes to re-run the configure script with
8360 (hopefully) the error that caused the previous abort corrected.
8362 @c FIXME: Do we really want to document this guy?
8363 @defmac AC_CACHE_LOAD
8364 @acindex{CACHE_LOAD}
8365 Loads values from existing cache file, or creates a new cache file if a
8366 cache file is not found.  Called automatically from @code{AC_INIT}.
8367 @end defmac
8369 @defmac AC_CACHE_SAVE
8370 @acindex{CACHE_SAVE}
8371 Flushes all cached values to the cache file.  Called automatically from
8372 @code{AC_OUTPUT}, but it can be quite useful to call
8373 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8374 @end defmac
8376 For instance:
8378 @example
8379 @r{ @dots{} AC_INIT, etc. @dots{}}
8380 @group
8381 # Checks for programs.
8382 AC_PROG_CC
8383 AC_PROG_GCC_TRADITIONAL
8384 @r{ @dots{} more program checks @dots{}}
8385 AC_CACHE_SAVE
8386 @end group
8388 @group
8389 # Checks for libraries.
8390 AC_CHECK_LIB([nsl], [gethostbyname])
8391 AC_CHECK_LIB([socket], [connect])
8392 @r{ @dots{} more lib checks @dots{}}
8393 AC_CACHE_SAVE
8394 @end group
8396 @group
8397 # Might abort@dots{}
8398 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8399 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8400 @end group
8401 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8402 @end example
8404 @node Printing Messages
8405 @section Printing Messages
8406 @cindex Messages, from @command{configure}
8408 @command{configure} scripts need to give users running them several kinds
8409 of information.  The following macros print messages in ways appropriate
8410 for each kind.  The arguments to all of them get enclosed in shell
8411 double quotes, so the shell performs variable and back-quote
8412 substitution on them.
8414 These macros are all wrappers around the @command{echo} shell command,
8415 and will direct output to the appropriate file descriptor (@pxref{File
8416 Descriptor Macros}).
8417 @command{configure} scripts should rarely need to run @command{echo} directly
8418 to print messages for the user.  Using these macros makes it easy to
8419 change how and when each kind of message is printed; such changes need
8420 only be made to the macro definitions and all the callers will change
8421 automatically.
8423 To diagnose static issues, i.e., when @command{autoconf} is run, see
8424 @ref{Reporting Messages}.
8426 @defmac AC_MSG_CHECKING (@var{feature-description})
8427 @acindex{MSG_CHECKING}
8428 Notify the user that @command{configure} is checking for a particular
8429 feature.  This macro prints a message that starts with @samp{checking }
8430 and ends with @samp{...} and no newline.  It must be followed by a call
8431 to @code{AC_MSG_RESULT} to print the result of the check and the
8432 newline.  The @var{feature-description} should be something like
8433 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8434 c89}.
8436 This macro prints nothing if @command{configure} is run with the
8437 @option{--quiet} or @option{--silent} option.
8438 @end defmac
8440 @defmac AC_MSG_RESULT (@var{result-description})
8441 @acindex{MSG_RESULT}
8442 Notify the user of the results of a check.  @var{result-description} is
8443 almost always the value of the cache variable for the check, typically
8444 @samp{yes}, @samp{no}, or a file name.  This macro should follow a call
8445 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8446 the completion of the message printed by the call to
8447 @code{AC_MSG_CHECKING}.
8449 This macro prints nothing if @command{configure} is run with the
8450 @option{--quiet} or @option{--silent} option.
8451 @end defmac
8453 @defmac AC_MSG_NOTICE (@var{message})
8454 @acindex{MSG_NOTICE}
8455 Deliver the @var{message} to the user.  It is useful mainly to print a
8456 general description of the overall purpose of a group of feature checks,
8457 e.g.,
8459 @example
8460 AC_MSG_NOTICE([checking if stack overflow is detectable])
8461 @end example
8463 This macro prints nothing if @command{configure} is run with the
8464 @option{--quiet} or @option{--silent} option.
8465 @end defmac
8467 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8468 @acindex{MSG_ERROR}
8469 Notify the user of an error that prevents @command{configure} from
8470 completing.  This macro prints an error message to the standard error
8471 output and exits @command{configure} with @var{exit-status} (1 by default).
8472 @var{error-description} should be something like @samp{invalid value
8473 $HOME for \$HOME}.
8475 The @var{error-description} should start with a lower-case letter, and
8476 ``cannot'' is preferred to ``can't''.
8477 @end defmac
8479 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8480 @acindex{MSG_FAILURE}
8481 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8482 prevents @command{configure} from completing @emph{and} that additional
8483 details are provided in @file{config.log}.  This is typically used when
8484 abnormal results are found during a compilation.
8485 @end defmac
8487 @defmac AC_MSG_WARN (@var{problem-description})
8488 @acindex{MSG_WARN}
8489 Notify the @command{configure} user of a possible problem.  This macro
8490 prints the message to the standard error output; @command{configure}
8491 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8492 provide a default (back-up) behavior for the situations they warn about.
8493 @var{problem-description} should be something like @samp{ln -s seems to
8494 make hard links}.
8495 @end defmac
8499 @c ====================================================== Programming in M4.
8501 @node Programming in M4
8502 @chapter Programming in M4
8503 @cindex M4
8505 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8506 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8507 provides macros dedicated to shell script generation.
8509 As of this version of Autoconf, these two layers are still experimental,
8510 and their interface might change in the future.  As a matter of fact,
8511 @emph{anything that is not documented must not be used}.
8513 @menu
8514 * M4 Quotation::                Protecting macros from unwanted expansion
8515 * Using autom4te::              The Autoconf executables backbone
8516 * Programming in M4sugar::      Convenient pure M4 macros
8517 * Programming in M4sh::         Common shell Constructs
8518 * File Descriptor Macros::      File descriptor macros for input and output
8519 @end menu
8521 @node M4 Quotation
8522 @section M4 Quotation
8523 @cindex M4 quotation
8524 @cindex quotation
8526 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8527 @c prevented `expansion' of $1.  Unless it refers to the expansion
8528 @c of the value of $1?  Anyway, we need a rewrite here@enddots{}
8530 The most common problem with existing macros is an improper quotation.
8531 This section, which users of Autoconf can skip, but which macro writers
8532 @emph{must} read, first justifies the quotation scheme that was chosen
8533 for Autoconf and then ends with a rule of thumb.  Understanding the
8534 former helps one to follow the latter.
8536 @menu
8537 * Active Characters::           Characters that change the behavior of M4
8538 * One Macro Call::              Quotation and one macro call
8539 * Quotation and Nested Macros::  Macros calling macros
8540 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
8541 * Quadrigraphs::                Another way to escape special characters
8542 * Quotation Rule Of Thumb::     One parenthesis, one quote
8543 @end menu
8545 @node Active Characters
8546 @subsection Active Characters
8548 To fully understand where proper quotation is important, you first need
8549 to know what the special characters are in Autoconf: @samp{#} introduces
8550 a comment inside which no macro expansion is performed, @samp{,}
8551 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8552 and finally @samp{(} and @samp{)} (which M4 tries to match by
8553 pairs).
8555 In order to understand the delicate case of macro calls, we first have
8556 to present some obvious failures.  Below they are ``obvious-ified'',
8557 but when you find them in real life, they are usually in disguise.
8559 Comments, introduced by a hash and running up to the newline, are opaque
8560 tokens to the top level: active characters are turned off, and there is
8561 no macro expansion:
8563 @example
8564 # define([def], ine)
8565 @result{}# define([def], ine)
8566 @end example
8568 Each time there can be a macro expansion, there is a quotation
8569 expansion, i.e., one level of quotes is stripped:
8571 @example
8572 int tab[10];
8573 @result{}int tab10;
8574 [int tab[10];]
8575 @result{}int tab[10];
8576 @end example
8578 Without this in mind, the reader will try hopelessly to use her macro
8579 @code{array}:
8581 @example
8582 define([array], [int tab[10];])
8583 array
8584 @result{}int tab10;
8585 [array]
8586 @result{}array
8587 @end example
8589 @noindent
8590 How can you correctly output the intended results@footnote{Using
8591 @code{defn}.}?
8594 @node One Macro Call
8595 @subsection One Macro Call
8597 Let's proceed on the interaction between active characters and macros
8598 with this small macro, which just returns its first argument:
8600 @example
8601 define([car], [$1])
8602 @end example
8604 @noindent
8605 The two pairs of quotes above are not part of the arguments of
8606 @code{define}; rather, they are understood by the top level when it
8607 tries to find the arguments of @code{define}.  Therefore, assuming
8608 @code{car} is not already defined, it is equivalent to write:
8610 @example
8611 define(car, $1)
8612 @end example
8614 @noindent
8615 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8616 quotes, it is bad practice for Autoconf macros which must both be more
8617 robust and also advocate perfect style.
8619 At the top level, there are only two possibilities: either you
8620 quote or you don't:
8622 @example
8623 car(foo, bar, baz)
8624 @result{}foo
8625 [car(foo, bar, baz)]
8626 @result{}car(foo, bar, baz)
8627 @end example
8629 Let's pay attention to the special characters:
8631 @example
8632 car(#)
8633 @error{}EOF in argument list
8634 @end example
8636 The closing parenthesis is hidden in the comment; with a hypothetical
8637 quoting, the top level understood it this way:
8639 @example
8640 car([#)]
8641 @end example
8643 @noindent
8644 Proper quotation, of course, fixes the problem:
8646 @example
8647 car([#])
8648 @result{}#
8649 @end example
8651 Here are more examples:
8653 @example
8654 car(foo, bar)
8655 @result{}foo
8656 car([foo, bar])
8657 @result{}foo, bar
8658 car((foo, bar))
8659 @result{}(foo, bar)
8660 car([(foo], [bar)])
8661 @result{}(foo
8662 define([a], [b])
8663 @result{}
8664 car(a)
8665 @result{}b
8666 car([a])
8667 @result{}b
8668 car([[a]])
8669 @result{}a
8670 car([[[a]]])
8671 @result{}[a]
8672 @end example
8674 With this in mind, we can explore the cases where macros invoke
8675 macros@enddots{}
8678 @node Quotation and Nested Macros
8679 @subsection Quotation and Nested Macros
8681 The examples below use the following macros:
8683 @example
8684 define([car], [$1])
8685 define([active], [ACT, IVE])
8686 define([array], [int tab[10]])
8687 @end example
8689 Each additional embedded macro call introduces other possible
8690 interesting quotations:
8692 @example
8693 car(active)
8694 @result{}ACT
8695 car([active])
8696 @result{}ACT, IVE
8697 car([[active]])
8698 @result{}active
8699 @end example
8701 In the first case, the top level looks for the arguments of @code{car},
8702 and finds @samp{active}.  Because M4 evaluates its arguments
8703 before applying the macro, @samp{active} is expanded, which results in:
8705 @example
8706 car(ACT, IVE)
8707 @result{}ACT
8708 @end example
8710 @noindent
8711 In the second case, the top level gives @samp{active} as first and only
8712 argument of @code{car}, which results in:
8714 @example
8715 active
8716 @result{}ACT, IVE
8717 @end example
8719 @noindent
8720 i.e., the argument is evaluated @emph{after} the macro that invokes it.
8721 In the third case, @code{car} receives @samp{[active]}, which results in:
8723 @example
8724 [active]
8725 @result{}active
8726 @end example
8728 @noindent
8729 exactly as we already saw above.
8731 The example above, applied to a more realistic example, gives:
8733 @example
8734 car(int tab[10];)
8735 @result{}int tab10;
8736 car([int tab[10];])
8737 @result{}int tab10;
8738 car([[int tab[10];]])
8739 @result{}int tab[10];
8740 @end example
8742 @noindent
8743 Huh?  The first case is easily understood, but why is the second wrong,
8744 and the third right?  To understand that, you must know that after
8745 M4 expands a macro, the resulting text is immediately subjected
8746 to macro expansion and quote removal.  This means that the quote removal
8747 occurs twice---first before the argument is passed to the @code{car}
8748 macro, and second after the @code{car} macro expands to the first
8749 argument.
8751 As the author of the Autoconf macro @code{car}, you then consider it to
8752 be incorrect that your users have to double-quote the arguments of
8753 @code{car}, so you ``fix'' your macro.  Let's call it @code{qar} for
8754 quoted car:
8756 @example
8757 define([qar], [[$1]])
8758 @end example
8760 @noindent
8761 and check that @code{qar} is properly fixed:
8763 @example
8764 qar([int tab[10];])
8765 @result{}int tab[10];
8766 @end example
8768 @noindent
8769 Ahhh!  That's much better.
8771 But note what you've done: now that the arguments are literal strings,
8772 if the user wants to use the results of expansions as arguments, she has
8773 to use an @emph{unquoted} macro call:
8775 @example
8776 qar(active)
8777 @result{}ACT
8778 @end example
8780 @noindent
8781 where she wanted to reproduce what she used to do with @code{car}:
8783 @example
8784 car([active])
8785 @result{}ACT, IVE
8786 @end example
8788 @noindent
8789 Worse yet: she wants to use a macro that produces a set of @code{cpp}
8790 macros:
8792 @example
8793 define([my_includes], [#include <stdio.h>])
8794 car([my_includes])
8795 @result{}#include <stdio.h>
8796 qar(my_includes)
8797 @error{}EOF in argument list
8798 @end example
8800 This macro, @code{qar}, because it double quotes its arguments, forces
8801 its users to leave their macro calls unquoted, which is dangerous.
8802 Commas and other active symbols are interpreted by M4 before
8803 they are given to the macro, often not in the way the users expect.
8804 Also, because @code{qar} behaves differently from the other macros,
8805 it's an exception that should be avoided in Autoconf.
8807 @node Changequote is Evil
8808 @subsection @code{changequote} is Evil
8809 @cindex @code{changequote}
8811 The temptation is often high to bypass proper quotation, in particular
8812 when it's late at night.  Then, many experienced Autoconf hackers
8813 finally surrender to the dark side of the force and use the ultimate
8814 weapon: @code{changequote}.
8816 The M4 builtin @code{changequote} belongs to a set of primitives that
8817 allow one to adjust the syntax of the language to adjust it to one's
8818 needs.  For instance, by default M4 uses @samp{`} and @samp{'} as
8819 quotes, but in the context of shell programming (and actually of most
8820 programming languages), that's about the worst choice one can make:
8821 because of strings and back-quoted expressions in shell code (such as
8822 @samp{'this'} and @samp{`that`}), because of literal characters in usual
8823 programming languages (as in @samp{'0'}), there are many unbalanced
8824 @samp{`} and @samp{'}.  Proper M4 quotation then becomes a nightmare, if
8825 not impossible.  In order to make M4 useful in such a context, its
8826 designers have equipped it with @code{changequote}, which makes it
8827 possible to choose another pair of quotes.  M4sugar, M4sh, Autoconf, and
8828 Autotest all have chosen to use @samp{[} and @samp{]}.  Not especially
8829 because they are unlikely characters, but @emph{because they are
8830 characters unlikely to be unbalanced}.
8832 There are other magic primitives, such as @code{changecom} to specify
8833 what syntactic forms are comments (it is common to see
8834 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
8835 @code{changeword} and @code{changesyntax} to change other syntactic
8836 details (such as the character to denote the @var{n}th argument, @samp{$} by
8837 default, the parenthesis around arguments, etc.).
8839 These primitives are really meant to make M4 more useful for specific
8840 domains: they should be considered like command line options:
8841 @option{--quotes}, @option{--comments}, @option{--words}, and
8842 @option{--syntax}.  Nevertheless, they are implemented as M4 builtins, as
8843 it makes M4 libraries self contained (no need for additional options).
8845 There lies the problem@enddots{}
8847 @sp 1
8849 The problem is that it is then tempting to use them in the middle of an
8850 M4 script, as opposed to its initialization.  This, if not carefully
8851 thought out, can lead to disastrous effects: @emph{you are changing the
8852 language in the middle of the execution}.  Changing and restoring the
8853 syntax is often not enough: if you happened to invoke macros in between,
8854 these macros will be lost, as the current syntax will probably not be
8855 the one they were implemented with.
8857 @c FIXME: I've been looking for a short, real case example, but I
8858 @c lost them all :(
8861 @node Quadrigraphs
8862 @subsection Quadrigraphs
8863 @cindex quadrigraphs
8864 @cindex @samp{@@S|@@}
8865 @cindex @samp{@@&t@@}
8866 @c Info cannot handle `:' in index entries.
8867 @c @cindex @samp{@@<:@@}
8868 @c @cindex @samp{@@:>@@}
8869 @c @cindex @samp{@@%:@@}
8871 When writing an Autoconf macro you may occasionally need to generate
8872 special characters that are difficult to express with the standard
8873 Autoconf quoting rules.  For example, you may need to output the regular
8874 expression @samp{[^[]}, which matches any character other than @samp{[}.
8875 This expression contains unbalanced brackets so it cannot be put easily
8876 into an M4 macro.
8878 You can work around this problem by using one of the following
8879 @dfn{quadrigraphs}:
8881 @table @samp
8882 @item @@<:@@
8883 @samp{[}
8884 @item @@:>@@
8885 @samp{]}
8886 @item @@S|@@
8887 @samp{$}
8888 @item @@%:@@
8889 @samp{#}
8890 @item @@&t@@
8891 Expands to nothing.
8892 @end table
8894 Quadrigraphs are replaced at a late stage of the translation process,
8895 after @command{m4} is run, so they do not get in the way of M4 quoting.
8896 For example, the string @samp{^@@<:@@}, independently of its quotation,
8897 will appear as @samp{^[} in the output.
8899 The empty quadrigraph can be used:
8901 @itemize @minus
8902 @item to mark trailing spaces explicitly
8904 Trailing spaces are smashed by @command{autom4te}.  This is a feature.
8906 @item to produce other quadrigraphs
8908 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
8910 @item to escape @emph{occurrences} of forbidden patterns
8912 For instance you might want to mention @code{AC_FOO} in a comment, while
8913 still being sure that @command{autom4te} will still catch unexpanded
8914 @samp{AC_*}.  Then write @samp{AC@@&t@@_FOO}.
8915 @end itemize
8917 The name @samp{@@&t@@} was suggested by Paul Eggert:
8919 @quotation
8920 I should give some credit to the @samp{@@&t@@} pun.  The @samp{&} is my
8921 own invention, but the @samp{t} came from the source code of the
8922 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
8923 and which used @samp{mt} to denote the empty string.  In C, it would
8924 have looked like something like:
8926 @example
8927 char const mt[] = "";
8928 @end example
8930 @noindent
8931 but of course the source code was written in Algol 68.
8933 I don't know where he got @samp{mt} from: it could have been his own
8934 invention, and I suppose it could have been a common pun around the
8935 Cambridge University computer lab at the time.
8936 @end quotation
8938 @node Quotation Rule Of Thumb
8939 @subsection Quotation Rule Of Thumb
8941 To conclude, the quotation rule of thumb is:
8943 @center @emph{One pair of quotes per pair of parentheses.}
8945 Never over-quote, never under-quote, in particular in the definition of
8946 macros.  In the few places where the macros need to use brackets
8947 (usually in C program text or regular expressions), properly quote
8948 @emph{the arguments}!
8950 It is common to read Autoconf programs with snippets like:
8952 @example
8953 AC_TRY_LINK(
8954 changequote(<<, >>)dnl
8955 <<#include <time.h>
8956 #ifndef tzname /* For SGI.  */
8957 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
8958 #endif>>,
8959 changequote([, ])dnl
8960 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
8961 @end example
8963 @noindent
8964 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
8965 double quoting, so you just need:
8967 @example
8968 AC_TRY_LINK(
8969 [#include <time.h>
8970 #ifndef tzname /* For SGI.  */
8971 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
8972 #endif],
8973             [atoi (*tzname);],
8974             [ac_cv_var_tzname=yes],
8975             [ac_cv_var_tzname=no])
8976 @end example
8978 @noindent
8979 The M4-fluent reader will note that these two examples are rigorously
8980 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
8981 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
8982 quotes are not part of the arguments!
8984 Simplified, the example above is just doing this:
8986 @example
8987 changequote(<<, >>)dnl
8988 <<[]>>
8989 changequote([, ])dnl
8990 @end example
8992 @noindent
8993 instead of simply:
8995 @example
8996 [[]]
8997 @end example
8999 With macros that do not double quote their arguments (which is the
9000 rule), double-quote the (risky) literals:
9002 @example
9003 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9004 [[#include <time.h>
9005 #ifndef tzname /* For SGI.  */
9006 extern char *tzname[]; /* RS6000 and others reject char **tzname.  */
9007 #endif]],
9008                                 [atoi (*tzname);])],
9009                [ac_cv_var_tzname=yes],
9010                [ac_cv_var_tzname=no])
9011 @end example
9013 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9014 should be using @code{AC_LINK_IFELSE} instead.
9016 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9017 where quoting does not suffice.
9019 When you create a @command{configure} script using newly written macros,
9020 examine it carefully to check whether you need to add more quotes in
9021 your macros.  If one or more words have disappeared in the M4
9022 output, you need more quotes.  When in doubt, quote.
9024 However, it's also possible to put on too many layers of quotes.  If
9025 this happens, the resulting @command{configure} script may contain
9026 unexpanded macros.  The @command{autoconf} program checks for this problem
9027 by looking for the string @samp{AC_} in @file{configure}.  However, this
9028 heuristic does not work in general: for example, it does not catch
9029 overquoting in @code{AC_DEFINE} descriptions.
9032 @c ---------------------------------------- Using autom4te
9034 @node Using autom4te
9035 @section Using @command{autom4te}
9037 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9038 to Autoconf per se, heavily rely on M4.  All these different uses
9039 revealed common needs factored into a layer over @command{m4}:
9040 @command{autom4te}@footnote{
9042 Yet another great name from Lars J. Aas.
9046 @command{autom4te} is a preprocessor that is like @command{m4}.
9047 It supports M4 extensions designed for use in tools like Autoconf.
9049 @menu
9050 * autom4te Invocation::         A @acronym{GNU} M4 wrapper
9051 * Customizing autom4te::        Customizing the Autoconf package
9052 @end menu
9054 @node autom4te Invocation
9055 @subsection Invoking @command{autom4te}
9057 The command line arguments are modeled after M4's:
9059 @example
9060 autom4te @var{options} @var{files}
9061 @end example
9063 @noindent
9064 where the @var{files} are directly passed to @command{m4}.  In addition
9065 to the regular expansion, it handles the replacement of the quadrigraphs
9066 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9067 output.  It supports an extended syntax for the @var{files}:
9069 @table @file
9070 @item @var{file}.m4f
9071 This file is an M4 frozen file.  Note that @emph{all the previous files
9072 are ignored}.  See the option @option{--melt} for the rationale.
9074 @item @var{file}?
9075 If found in the library path, the @var{file} is included for expansion,
9076 otherwise it is ignored instead of triggering a failure.
9077 @end table
9079 @sp 1
9081 Of course, it supports the Autoconf common subset of options:
9083 @table @option
9084 @item --help
9085 @itemx -h
9086 Print a summary of the command line options and exit.
9088 @item --version
9089 @itemx -V
9090 Print the version number of Autoconf and exit.
9092 @item --verbose
9093 @itemx -v
9094 Report processing steps.
9096 @item --debug
9097 @itemx -d
9098 Don't remove the temporary files and be even more verbose.
9100 @item --include=@var{dir}
9101 @itemx -I @var{dir}
9102 Also look for input files in @var{dir}.  Multiple invocations
9103 accumulate.
9105 @item --output=@var{file}
9106 @itemx -o @var{file}
9107 Save output (script or trace) to @var{file}.  The file @option{-} stands
9108 for the standard output.
9109 @end table
9111 @sp 1
9113 As an extension of @command{m4}, it includes the following options:
9115 @table @option
9116 @item --warnings=@var{category}
9117 @itemx -W @var{category}
9118 @evindex WARNINGS
9119 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9120 Report the warnings related to @var{category} (which can actually be a
9121 comma separated list).  @xref{Reporting Messages}, macro
9122 @code{AC_DIAGNOSE}, for a comprehensive list of categories.  Special
9123 values include:
9125 @table @samp
9126 @item all
9127 report all the warnings
9129 @item none
9130 report none
9132 @item error
9133 treats warnings as errors
9135 @item no-@var{category}
9136 disable warnings falling into @var{category}
9137 @end table
9139 Warnings about @samp{syntax} are enabled by default, and the environment
9140 variable @env{WARNINGS}, a comma separated list of categories, is
9141 honored.  @command{autom4te -W @var{category}} will actually
9142 behave as if you had run:
9144 @example
9145 autom4te --warnings=syntax,$WARNINGS,@var{category}
9146 @end example
9148 @noindent
9149 For example, if you want to disable @command{autom4te}'s defaults and
9150 @env{WARNINGS}, but enable the warnings about obsolete
9151 constructs, you would use @option{-W none,obsolete}.
9153 @cindex Back trace
9154 @cindex Macro invocation stack
9155 @command{autom4te} displays a back trace for errors, but not for
9156 warnings; if you want them, just pass @option{-W error}.
9158 @item --melt
9159 @itemx -m
9160 Do not use frozen files.  Any argument @code{@var{file}.m4f} will be
9161 replaced with @code{@var{file}.m4}.  This helps tracing the macros which
9162 are executed only when the files are frozen, typically
9163 @code{m4_define}.  For instance, running:
9165 @example
9166 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9167 @end example
9169 @noindent
9170 is roughly equivalent to running:
9172 @example
9173 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9174 @end example
9176 @noindent
9177 while
9179 @example
9180 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9181 @end example
9183 @noindent
9184 is equivalent to:
9186 @example
9187 m4 --reload-state=4.m4f input.m4
9188 @end example
9190 @item --freeze
9191 @itemx -f
9192 Produce a frozen state file.  @command{autom4te} freezing is stricter
9193 than M4's: it must produce no warnings, and no output other than empty
9194 lines (a line with white space is @emph{not} empty) and comments
9195 (starting with @samp{#}).  Please, note that contrary to @command{m4},
9196 this options takes no argument:
9198 @example
9199 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9200 @end example
9202 @noindent
9203 corresponds to
9205 @example
9206 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9207 @end example
9209 @item --mode=@var{octal-mode}
9210 @itemx -m @var{octal-mode}
9211 Set the mode of the non-traces output to @var{octal-mode}; by default
9212 @samp{0666}.
9213 @end table
9215 @sp 1
9217 @cindex @file{autom4te.cache}
9218 As another additional feature over @command{m4}, @command{autom4te}
9219 caches its results.  @acronym{GNU} M4 is able to produce a regular
9220 output and traces at the same time.  Traces are heavily used in the
9221 @acronym{GNU} Build System: @command{autoheader} uses them to build
9222 @file{config.h.in}, @command{autoreconf} to determine what
9223 @acronym{GNU} Build System components are used, @command{automake} to
9224 ``parse'' @file{configure.ac} etc.  To save the long runs of
9225 @command{m4}, traces are cached while performing regular expansion,
9226 and conversely.  This cache is (actually, the caches are) stored in
9227 the directory @file{autom4te.cache}.  @emph{It can safely be removed}
9228 at any moment (especially if for some reason @command{autom4te}
9229 considers it is trashed).
9231 @table @option
9232 @item --cache=@var{directory}
9233 @itemx -C @var{directory}
9234 Specify the name of the directory where the result should be cached.
9235 Passing an empty value disables caching.  Be sure to pass a relative
9236 file name, as for the time being, global caches are not supported.
9238 @item --no-cache
9239 Don't cache the results.
9241 @item --force
9242 @itemx -f
9243 If a cache is used, consider it obsolete (but update it anyway).
9244 @end table
9246 @sp 1
9248 Because traces are so important to the @acronym{GNU} Build System,
9249 @command{autom4te} provides high level tracing features as compared to
9250 M4, and helps exploiting the cache:
9252 @table @option
9253 @item --trace=@var{macro}[:@var{format}]
9254 @itemx -t @var{macro}[:@var{format}]
9255 Trace the invocations of @var{macro} according to the @var{format}.
9256 Multiple @option{--trace} arguments can be used to list several macros.
9257 Multiple @option{--trace} arguments for a single macro are not
9258 cumulative; instead, you should just make @var{format} as long as
9259 needed.
9261 The @var{format} is a regular string, with newlines if desired, and
9262 several special escape codes.  It defaults to @samp{$f:$l:$n:$%}.  It can
9263 use the following special escapes:
9265 @table @samp
9266 @item $$
9267 The character @samp{$}.
9269 @item $f
9270 The file name from which @var{macro} is called.
9272 @item $l
9273 The line number from which @var{macro} is called.
9275 @item $d
9276 The depth of the @var{macro} call.  This is an M4 technical detail that
9277 you probably don't want to know about.
9279 @item $n
9280 The name of the @var{macro}.
9282 @item $@var{num}
9283 The @var{num}th argument of the call to @var{macro}.
9285 @item $@@
9286 @itemx $@var{sep}@@
9287 @itemx $@{@var{separator}@}@@
9288 All the arguments passed to @var{macro}, separated by the character
9289 @var{sep} or the string @var{separator} (@samp{,} by default).  Each
9290 argument is quoted, i.e., enclosed in a pair of square brackets.
9292 @item $*
9293 @itemx $@var{sep}*
9294 @itemx $@{@var{separator}@}*
9295 As above, but the arguments are not quoted.
9297 @item $%
9298 @itemx $@var{sep}%
9299 @itemx $@{@var{separator}@}%
9300 As above, but the arguments are not quoted, all new line characters in
9301 the arguments are smashed, and the default separator is @samp{:}.
9303 The escape @samp{$%} produces single-line trace outputs (unless you put
9304 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9305 not.
9306 @end table
9308 @xref{autoconf Invocation}, for examples of trace uses.
9310 @item --preselect=@var{macro}
9311 @itemx -p @var{macro}
9312 Cache the traces of @var{macro}, but do not enable traces.  This is
9313 especially important to save CPU cycles in the future.  For instance,
9314 when invoked, @command{autoconf} preselects all the macros that
9315 @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
9316 trace, so that running @command{m4} is not needed to trace them: the
9317 cache suffices.  This results in a huge speed-up.
9318 @end table
9320 @sp 1
9322 @cindex Autom4te Library
9323 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9324 libraries}.  They consists in a powerful yet extremely simple feature:
9325 sets of combined command line arguments:
9327 @table @option
9328 @item --language=@var{language}
9329 @itemx -l @var{language}
9330 Use the @var{language} Autom4te library.  Current languages include:
9332 @table @code
9333 @item M4sugar
9334 create M4sugar output.
9336 @item M4sh
9337 create M4sh executable shell scripts.
9339 @item Autotest
9340 create Autotest executable test suites.
9342 @item Autoconf-without-aclocal-m4
9343 create Autoconf executable configure scripts without
9344 reading @file{aclocal.m4}.
9346 @item Autoconf
9347 create Autoconf executable configure scripts.  This language inherits
9348 all the characteristics of @code{Autoconf-without-aclocal-m4} and will
9349 additionally read @file{aclocal.m4}.
9350 @end table
9352 @item --prepend-include=@var{dir}
9353 @item -B @var{dir}
9354 Prepend directory @var{dir} to the search path.  This is used to include
9355 the language-specific files before any third-party macros.
9357 @end table
9359 @cindex @file{autom4te.cfg}
9360 As an example, if Autoconf is installed in its default location,
9361 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9362 strictly equivalent to the command:
9364 @example
9365 autom4te --prepend-include /usr/local/share/autoconf \
9366   m4sugar/m4sugar.m4f --warnings syntax foo.m4
9367 @end example
9369 @noindent
9370 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9371 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9372 foo.m4}, i.e.:
9374 @example
9375 autom4te --prepend-include /usr/local/share/autoconf \
9376   m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9377 @end example
9379 @noindent
9380 The definition of the languages is stored in @file{autom4te.cfg}.
9382 @node Customizing autom4te
9383 @subsection Customizing @command{autom4te}
9385 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9386 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9387 as found in the directory from which @command{autom4te} is run).  The
9388 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9389 then @file{./.autom4te.cfg}, and finally the command line arguments.
9391 In these text files, comments are introduced with @code{#}, and empty
9392 lines are ignored.  Customization is performed on a per-language basis,
9393 wrapped in between a @samp{begin-language: "@var{language}"},
9394 @samp{end-language: "@var{language}"} pair.
9396 Customizing a language stands for appending options (@pxref{autom4te
9397 Invocation}) to the current definition of the language.  Options, and
9398 more generally arguments, are introduced by @samp{args:
9399 @var{arguments}}.  You may use the traditional shell syntax to quote the
9400 @var{arguments}.
9402 As an example, to disable Autoconf caches (@file{autom4te.cache})
9403 globally, include the following lines in @file{~/.autom4te.cfg}:
9405 @verbatim
9406 ## ------------------ ##
9407 ## User Preferences.  ##
9408 ## ------------------ ##
9410 begin-language: "Autoconf-without-aclocal-m4"
9411 args: --no-cache
9412 end-language: "Autoconf-without-aclocal-m4"
9413 @end verbatim
9416 @node Programming in M4sugar
9417 @section Programming in M4sugar
9419 @cindex M4sugar
9420 M4 by itself provides only a small, but sufficient, set of all-purpose
9421 macros.  M4sugar introduces additional generic macros.  Its name was
9422 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9423 M4sugar''.
9425 @menu
9426 * Redefined M4 Macros::         M4 builtins changed in M4sugar
9427 * Looping constructs::          Iteration in M4
9428 * Evaluation Macros::           More quotation and evaluation control
9429 * Text processing Macros::      String manipulation in M4
9430 * Forbidden Patterns::          Catching unexpanded macros
9431 @end menu
9433 @node Redefined M4 Macros
9434 @subsection Redefined M4 Macros
9436 @msindex{builtin}
9437 @msindex{decr}
9438 @msindex{define}
9439 @msindex{dumpdef}
9440 @msindex{errprint}
9441 @msindex{esyscmd}
9442 @msindex{eval}
9443 @msindex{format}
9444 @msindex{ifdef}
9445 @msindex{incr}
9446 @msindex{index}
9447 @msindex{indir}
9448 @msindex{len}
9449 @msindex{maketemp}
9450 @msindex{pushdef}
9451 @msindex{shift}
9452 @msindex{substr}
9453 @msindex{syscmd}
9454 @msindex{sysval}
9455 @msindex{translit}
9456 @msindex{undefine}
9457 With a few exceptions, all the M4 native macros are moved in the
9458 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9459 @code{m4_define} etc.
9461 Some M4 macros are redefined, and are slightly incompatible with their
9462 native equivalent.
9464 @defmac dnl
9465 @msindex{dnl}
9466 This macro kept its original name: no @code{m4_dnl} is defined.
9467 @end defmac
9469 @defmac m4_defn (@var{macro})
9470 @msindex{defn}
9471 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9472 defined.  See @code{m4_undefine}.
9473 @end defmac
9475 @defmac m4_exit (@var{exit-status})
9476 @msindex{exit}
9477 This macro corresponds to @code{m4exit}.
9478 @end defmac
9480 @defmac m4_if (@var{comment})
9481 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9482 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9483 @msindex{if}
9484 This macro corresponds to @code{ifelse}.
9485 @end defmac
9487 @defmac m4_include (@var{file})
9488 @defmacx m4_sinclude (@var{file})
9489 @msindex{include}
9490 @msindex{sinclude}
9491 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9492 @end defmac
9494 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9495 @msindex{bpatsubst}
9496 This macro corresponds to @code{patsubst}.  The name @code{m4_patsubst}
9497 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9498 provide extended regular expression syntax via @code{epatsubst}.
9499 @end defmac
9501 @defmac m4_popdef (@var{macro})
9502 @msindex{popdef}
9503 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9504 defined.  See @code{m4_undefine}.
9505 @end defmac
9507 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9508 @msindex{bregexp}
9509 This macro corresponds to @code{regexp}.  The name @code{m4_regexp}
9510 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9511 provide extended regular expression syntax via @code{eregexp}.
9512 @end defmac
9514 @defmac m4_wrap (@var{text})
9515 @msindex{wrap}
9516 This macro corresponds to @code{m4wrap}.
9518 You are encouraged to end @var{text} with @samp{[]}, so that there are
9519 no risks that two consecutive invocations of @code{m4_wrap} result in an
9520 unexpected pasting of tokens, as in
9522 @example
9523 m4_define([foo], [Foo])
9524 m4_define([bar], [Bar])
9525 m4_define([foobar], [FOOBAR])
9526 m4_wrap([bar])
9527 m4_wrap([foo])
9528 @result{}FOOBAR
9529 @end example
9530 @end defmac
9532 @defmac m4_undefine (@var{macro})
9533 @msindex{undefine}
9534 Contrary to the M4 builtin, this macro fails if @var{macro} is not
9535 defined.  Use
9537 @example
9538 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9539 @end example
9541 @noindent
9542 to recover the behavior of the builtin.
9543 @end defmac
9547 @node Looping constructs
9548 @subsection Looping constructs
9550 The following macros implement loops in M4.
9552 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9553 @msindex{for}
9554 Loop over the numeric values between @var{first} and @var{last}
9555 including bounds by increments of @var{step}.  For each iteration,
9556 expand @var{expression} with the numeric value assigned to @var{var}.
9557 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9558 on the order of the limits.  If given, @var{step} has to match this
9559 order.
9560 @end defmac
9562 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9563 @msindex{foreach}
9564 Loop over the comma-separated m4 list @var{list}, assigning each value
9565 to @var{var}, and expand @var{expression}.  The following example will
9566 output two lines:
9568 @example
9569 m4_foreach([myvar], [[foo], [bar, baz]],
9570            [echo myvar
9573 @end example
9574 @end defmac
9576 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9577 @msindex{foreach_w}
9578 Loop over the whitespace-separated list @var{list}, assigning each value
9579 to @var{var}, and expand @var{expression}.
9581 The deprecated macro @code{AC_FOREACH} is an alias of
9582 @code{m4_foreach_w}.
9583 @end defmac
9587 @node Evaluation Macros
9588 @subsection Evaluation Macros
9590 The following macros give some control over the order of the evaluation
9591 by adding or removing levels of quotes.  They are meant for hard-core M4
9592 programmers.
9594 @defmac m4_dquote (@var{arg1}, @dots{})
9595 @msindex{dquote}
9596 Return the arguments as a quoted list of quoted arguments.
9597 @end defmac
9599 @defmac m4_quote (@var{arg1}, @dots{})
9600 @msindex{quote}
9601 Return the arguments as a single entity, i.e., wrap them into a pair of
9602 quotes.
9603 @end defmac
9605 The following example aims at emphasizing the difference between (i), not
9606 using these macros, (ii), using @code{m4_quote}, and (iii), using
9607 @code{m4_dquote}.
9609 @example
9610 $ @kbd{cat example.m4}
9611 # Overquote, so that quotes are visible.
9612 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9613 m4_divert(0)dnl
9614 show(a, b)
9615 show(m4_quote(a, b))
9616 show(m4_dquote(a, b))
9617 $ @kbd{autom4te -l m4sugar example.m4}
9618 $1 = a, $@@ = [a],[b]
9619 $1 = a,b, $@@ = [a,b]
9620 $1 = [a],[b], $@@ = [[a],[b]]
9621 @end example
9625 @node Text processing Macros
9626 @subsection Text processing Macros
9628 The following macros may be used to manipulate strings in M4.
9629 They are not intended for casual use.
9631 @defmac m4_re_escape (@var{string})
9632 @msindex{re_escape}
9633 Backslash-escape all characters in @var{string} that are active in
9634 regexps.
9635 @end defmac
9637 @defmac m4_tolower (@var{string})
9638 @defmacx m4_toupper (@var{string})
9639 @msindex{tolower}
9640 @msindex{toupper}
9641 Return @var{string} with letters converted to upper or lower case,
9642 respectively.
9643 @end defmac
9645 @defmac m4_split (@var{string}, @ovar{regexp})
9646 @msindex{split}
9647 Split @var{string} into an M4 list of elements quoted by @samp{[} and
9648 @samp{]}, while keeping white space at the beginning and at the end.
9649 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
9650 If @var{string} is empty, the result is an empty list.
9651 @end defmac
9653 @defmac m4_normalize (@var{string})
9654 @msindex{normalize}
9655 Remove leading and trailing spaces and tabs, sequences of
9656 backslash-then-newline, and replace multiple spaces and tabs with a
9657 single space.
9658 @end defmac
9660 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
9661 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
9662 @msindex{append}
9663 @msindex{append_uniq}
9664 Redefine @var{macro-name} to its former contents with @var{separator}
9665 and @var{string} added at the end.  If @var{macro-name} was undefined
9666 before (but not if it was defined but empty), then no @var{separator} is
9667 added.  @code{m4_append} can be used to grow strings, and
9668 @code{m4_append_uniq} to grow strings without duplicating substrings.
9669 @end defmac
9673 @node Forbidden Patterns
9674 @subsection Forbidden Patterns
9675 @cindex Forbidden patterns
9676 @cindex Patterns, forbidden
9678 M4sugar provides a means to define suspicious patterns, patterns
9679 describing tokens which should not be found in the output.  For
9680 instance, if an Autoconf @file{configure} script includes tokens such as
9681 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
9682 wrong (typically a macro was not evaluated because of overquotation).
9684 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
9686 @defmac m4_pattern_forbid (@var{pattern})
9687 @msindex{pattern_forbid}
9688 Declare that no token matching @var{pattern} must be found in the output.
9689 Comments are not checked; this can be a problem if, for instance, you
9690 have some macro left unexpanded after an @samp{#include}.  No consensus
9691 is currently found in the Autoconf community, as some people consider it
9692 should be valid to name macros in comments (which doesn't make sense to
9693 the author of this documentation, as @samp{#}-comments should document
9694 the output, not the input, documented by @samp{dnl} comments).
9695 @end defmac
9697 Of course, you might encounter exceptions to these generic rules, for
9698 instance you might have to refer to @samp{$m4_flags}.
9700 @defmac m4_pattern_allow (@var{pattern})
9701 @msindex{pattern_allow}
9702 Any token matching @var{pattern} is allowed, including if it matches an
9703 @code{m4_pattern_forbid} pattern.
9704 @end defmac
9706 @node Programming in M4sh
9707 @section Programming in M4sh
9709 @c FIXME: Eventually will become a chapter, as it is not related to
9710 @c programming in M4 per se.
9712 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
9713 scripts.  This name was coined by Lars J. Aas, who notes that,
9714 according to the Webster's Revised Unabridged Dictionary (1913):
9716 @quotation
9717 Mash \Mash\, n.  [Akin to G. meisch, maisch, meische, maische, mash,
9718 wash, and prob.@: to AS. miscian to mix.  See ``Mix''.]
9720 @enumerate 1
9721 @item
9722 A mass of mixed ingredients reduced to a soft pulpy state by beating or
9723 pressure@enddots{}
9725 @item
9726 A mixture of meal or bran and water fed to animals.
9728 @item
9729 A mess; trouble.  [Obs.] --Beau.@: & Fl.
9730 @end enumerate
9731 @end quotation
9734 For the time being, it is not mature enough to be widely used.
9736 M4sh provides portable alternatives for some common shell constructs
9737 that unfortunately are not portable in practice.
9739 @c Deprecated, to be replaced by a better API
9740 @ignore
9741 @defmac AS_BASENAME (@var{file-name})
9742 @asindex{BASENAME}
9743 Output the non-directory portion of @var{file-name}.  For example,
9744 if @code{$file} is @samp{/one/two/three}, the command
9745 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
9746 @end defmac
9747 @end ignore
9749 @defmac AS_BOURNE_COMPATIBLE
9750 @asindex{BOURNE_COMPATIBLE}
9751 Set up the shell to be more compatible with the Bourne shell as
9752 standardized by Posix, if possible.  This may involve setting
9753 environment variables, or setting options, or similar
9754 implementation-specific actions.
9755 @end defmac
9757 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
9758 @asindex{CASE}
9759 Expand into a shell @samp{case} statement, where @var{word} is matched
9760 against one or more patterns.  @var{if-matched} is run if the
9761 corresponding pattern matched @var{word}, else @var{default} is run.
9762 @end defmac
9764 @defmac AS_DIRNAME (@var{file-name})
9765 @asindex{DIRNAME}
9766 Output the directory portion of @var{file-name}.  For example,
9767 if @code{$file} is @samp{/one/two/three}, the command
9768 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
9769 @end defmac
9771 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
9772 @asindex{IF}
9773 Run shell code @var{test1}.  If @var{test1} exits with a zero status then
9774 run shell code @var{run-if-true1}, else examine further tests.  If no test
9775 exits with a zero status, run shell code @var{run-if-false}, with
9776 simplifications if either @var{run-if-true1} or @var{run-if-false1}
9777 is empty.  For example,
9779 @example
9780 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
9781       [test "$foo" != no], [HANDLE_FOO([maybe])],
9782       [echo foo not specified])
9783 @end example
9785 @noindent
9786 will make sure any @code{AC_REQUIRE}'s macros of @code{HANDLE_FOO} will
9787 be expanded before the first test.
9788 @end defmac
9790 @defmac AS_MKDIR_P (@var{file-name})
9791 @asindex{MKDIR_P}
9792 Make the directory @var{file-name}, including intervening directories
9793 as necessary.  This is equivalent to @samp{mkdir -p @var{file-name}},
9794 except that it is portable to older versions of @command{mkdir} that
9795 lack support for the @option{-p} option.  Also, @code{AS_MKDIR_P}
9796 succeeds if @var{file-name} is a symbolic link to an existing directory,
9797 even though Posix is unclear whether @samp{mkdir -p} should
9798 succeed in that case.  If creation of @var{file-name} fails, exit the
9799 script.
9801 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
9802 @end defmac
9804 @defmac AS_SHELL_SANITIZE
9805 @asindex{SHELL_SANITIZE}
9806 Initialize the shell suitably for @code{configure} scripts.  This has
9807 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
9808 environment variables for predictable results from configuration tests.
9809 For example, it sets @env{LC_ALL} to change to the default C locale.
9810 @xref{Special Shell Variables}.
9811 @end defmac
9813 @defmac AS_TR_CPP (@var{expression})
9814 @asindex{TR_CPP}
9815 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
9816 For example:
9818 @example
9819 $ type="char *"
9820 $ echo "#define AS_TR_CPP([HAVE_$type]) 1"
9821 #define HAVE_CHAR_P 1
9822 @end example
9823 @end defmac
9825 @defmac AS_TR_SH (@var{expression})
9826 @asindex{TR_SH}
9827 Transform @var{expression} into a valid shell variable name.  For example:
9829 @example
9830 $ header="sys/some file.h"
9831 $ AS_TR_SH([HAVE_$header])=yes
9832 $ if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
9833 Have it!
9834 @end example
9835 @end defmac
9837 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
9838 @asindex{SET_CATFILE}
9839 Set the shell variable @var{var} to @var{dir}/@var{file}, but
9840 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
9841 @var{file} is absolute, etc.).
9842 @end defmac
9845 @node File Descriptor Macros
9846 @section File Descriptor Macros
9847 @cindex input
9848 @cindex standard input
9849 @cindex file descriptors
9850 @cindex descriptors
9851 @cindex low-level output
9852 @cindex output, low-level
9854 The following macros define file descriptors used to output messages
9855 (or input values) from @file{configure} scripts.
9856 For example:
9858 @example
9859 echo "$wombats found" >&AS_MESSAGE_LOG_FD
9860 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
9861 read kangaroos <&AS_ORIGINAL_STDIN_FD`
9862 @end example
9864 @noindent
9865 However doing so is seldom needed, because Autoconf provides higher
9866 level macros as described below.
9868 @defmac AS_MESSAGE_FD
9869 @asindex{MESSAGE_FD}
9870 The file descriptor for @samp{checking for...}  messages and results.
9871 Normally this directs messages to the standard output, however when
9872 @command{configure} is run with the @option{-q} option, messages sent to
9873 @code{AS_MESSAGE_FD} will be discarded.
9875 If you want to display some messages, consider using one of the printing
9876 macros (@pxref{Printing Messages}) instead.  Copies of messages output
9877 via these macros will additionally be recorded in @file{config.log}.
9878 @end defmac
9880 @defmac AS_MESSAGE_LOG_FD
9881 @asindex{MESSAGE_LOG_FD}
9883 The file descriptor for messages logged to @file{config.log}.  Macros
9884 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
9885 Compiler}), redirect all output to this descriptor.  You may want to do
9886 so if you develop such a low-level macro.
9887 @end defmac
9889 @defmac AS_ORIGINAL_STDIN_FD
9890 @asindex{ORIGINAL_STDIN_FD}
9891 The file descriptor for the original standard input.
9893 When @command{configure} runs, it may accidentally execute an
9894 interactive command that has the same name as the non-interactive meant
9895 to be used or checked.  If the standard input was the terminal, such
9896 interactive programs would cause @command{configure} to stop, pending
9897 some user input.  Therefore @command{configure} redirects its standard
9898 input from @file{/dev/null} during its initialization.  This is not
9899 normally a problem, since @command{configure} normally does not need
9900 user input.
9902 In the extreme case where your @file{configure} script really needs to
9903 obtain some values from the original standard input, you can read them
9904 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
9905 @end defmac
9908 @c =================================================== Writing Autoconf Macros.
9910 @node Writing Autoconf Macros
9911 @chapter Writing Autoconf Macros
9913 When you write a feature test that could be applicable to more than one
9914 software package, the best thing to do is encapsulate it in a new macro.
9915 Here are some instructions and guidelines for writing Autoconf macros.
9917 @menu
9918 * Macro Definitions::           Basic format of an Autoconf macro
9919 * Macro Names::                 What to call your new macros
9920 * Reporting Messages::          Notifying @command{autoconf} users
9921 * Dependencies Between Macros::  What to do when macros depend on other macros
9922 * Obsoleting Macros::           Warning about old ways of doing things
9923 * Coding Style::                Writing Autoconf macros @`a la Autoconf
9924 @end menu
9926 @node Macro Definitions
9927 @section Macro Definitions
9929 @acindex{DEFUN}
9930 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
9931 similar to the M4 builtin @code{m4_define} macro.  In addition to
9932 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
9933 constrain the order in which macros are called (@pxref{Prerequisite
9934 Macros}).
9936 An Autoconf macro definition looks like this:
9938 @example
9939 AC_DEFUN(@var{macro-name}, @var{macro-body})
9940 @end example
9942 You can refer to any arguments passed to the macro as @samp{$1},
9943 @samp{$2}, etc.  @xref{Definitions, , How to define new macros, m4.info,
9944 @acronym{GNU} m4}, for more complete information on writing M4 macros.
9946 Be sure to properly quote both the @var{macro-body} @emph{and} the
9947 @var{macro-name} to avoid any problems if the macro happens to have
9948 been previously defined.
9950 Each macro should have a header comment that gives its prototype, and a
9951 brief description.  When arguments have default values, display them in
9952 the prototype.  For example:
9954 @example
9955 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
9956 # --------------------------------------
9957 m4_define([AC_MSG_ERROR],
9958   [@{ AS_MESSAGE([error: $1], [2])
9959      exit m4_default([$2], [1]); @}])
9960 @end example
9962 Comments about the macro should be left in the header comment.  Most
9963 other comments will make their way into @file{configure}, so just keep
9964 using @samp{#} to introduce comments.
9966 @cindex @code{dnl}
9967 If you have some very special comments about pure M4 code, comments
9968 that make no sense in @file{configure} and in the header comment, then
9969 use the builtin @code{dnl}: it causes M4 to discard the text
9970 through the next newline.
9972 Keep in mind that @code{dnl} is rarely needed to introduce comments;
9973 @code{dnl} is more useful to get rid of the newlines following macros
9974 that produce no output, such as @code{AC_REQUIRE}.
9977 @node Macro Names
9978 @section Macro Names
9980 All of the Autoconf macros have all-uppercase names starting with
9981 @samp{AC_} to prevent them from accidentally conflicting with other
9982 text.  All shell variables that they use for internal purposes have
9983 mostly-lowercase names starting with @samp{ac_}.  To ensure that your
9984 macros don't conflict with present or future Autoconf macros, you should
9985 prefix your own macro names and any shell variables they use with some
9986 other sequence.  Possibilities include your initials, or an abbreviation
9987 for the name of your organization or software package.
9989 Most of the Autoconf macros' names follow a structured naming convention
9990 that indicates the kind of feature check by the name.  The macro names
9991 consist of several words, separated by underscores, going from most
9992 general to most specific.  The names of their cache variables use the
9993 same convention (@pxref{Cache Variable Names}, for more information on
9994 them).
9996 The first word of the name after @samp{AC_} usually tells the category
9997 of the feature being tested.  Here are the categories used in Autoconf for
9998 specific test macros, the kind of macro that you are more likely to
9999 write.  They are also used for cache variables, in all-lowercase.  Use
10000 them where applicable; where they're not, invent your own categories.
10002 @table @code
10003 @item C
10004 C language builtin features.
10005 @item DECL
10006 Declarations of C variables in header files.
10007 @item FUNC
10008 Functions in libraries.
10009 @item GROUP
10010 Posix group owners of files.
10011 @item HEADER
10012 Header files.
10013 @item LIB
10014 C libraries.
10015 @item PATH
10016 Absolute names of files, including programs.
10017 @item PROG
10018 The base names of programs.
10019 @item MEMBER
10020 Members of aggregates.
10021 @item SYS
10022 Operating system features.
10023 @item TYPE
10024 C builtin or declared types.
10025 @item VAR
10026 C variables in libraries.
10027 @end table
10029 After the category comes the name of the particular feature being
10030 tested.  Any further words in the macro name indicate particular aspects
10031 of the feature.  For example, @code{AC_FUNC_UTIME_NULL} checks the
10032 behavior of the @code{utime} function when called with a @code{NULL}
10033 pointer.
10035 An internal macro should have a name that starts with an underscore;
10036 Autoconf internals should therefore start with @samp{_AC_}.
10037 Additionally, a macro that is an internal subroutine of another macro
10038 should have a name that starts with an underscore and the name of that
10039 other macro, followed by one or more words saying what the internal
10040 macro does.  For example, @code{AC_PATH_X} has internal macros
10041 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10043 @node Reporting Messages
10044 @section Reporting Messages
10045 @cindex Messages, from @command{autoconf}
10047 When macros statically diagnose abnormal situations, benign or fatal,
10048 they should report them using these macros.  For dynamic issues, i.e.,
10049 when @command{configure} is run, see @ref{Printing Messages}.
10051 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10052 @acindex{DIAGNOSE}
10053 Report @var{message} as a warning (or as an error if requested by the
10054 user) if warnings of the @var{category} are turned on.  You are
10055 encouraged to use standard categories, which currently include:
10057 @table @samp
10058 @item all
10059 messages that don't fall into one of the following categories.  Use of an
10060 empty @var{category} is equivalent.
10062 @item cross
10063 related to cross compilation issues.
10065 @item obsolete
10066 use of an obsolete construct.
10068 @item syntax
10069 dubious syntactic constructs, incorrectly ordered macro calls.
10070 @end table
10071 @end defmac
10073 @defmac AC_WARNING (@var{message})
10074 @acindex{WARNING}
10075 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10076 strongly encouraged to use a finer grained category.
10077 @end defmac
10079 @defmac AC_FATAL (@var{message})
10080 @acindex{FATAL}
10081 Report a severe error @var{message}, and have @command{autoconf} die.
10082 @end defmac
10084 When the user runs @samp{autoconf -W error}, warnings from
10085 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10086 @ref{autoconf Invocation}.
10088 @node Dependencies Between Macros
10089 @section Dependencies Between Macros
10090 @cindex Dependencies between macros
10092 Some Autoconf macros depend on other macros having been called first in
10093 order to work correctly.  Autoconf provides a way to ensure that certain
10094 macros are called if needed and a way to warn the user if macros are
10095 called in an order that might cause incorrect operation.
10097 @menu
10098 * Prerequisite Macros::         Ensuring required information
10099 * Suggested Ordering::          Warning about possible ordering problems
10100 * One-Shot Macros::             Ensuring a macro is called only once
10101 @end menu
10103 @node Prerequisite Macros
10104 @subsection Prerequisite Macros
10105 @cindex Prerequisite macros
10106 @cindex Macros, prerequisites
10108 A macro that you write might need to use values that have previously
10109 been computed by other macros.  For example, @code{AC_DECL_YYTEXT}
10110 examines the output of @code{flex} or @code{lex}, so it depends on
10111 @code{AC_PROG_LEX} having been called first to set the shell variable
10112 @code{LEX}.
10114 Rather than forcing the user of the macros to keep track of the
10115 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10116 it automatically.  @code{AC_REQUIRE} can ensure that a macro is only
10117 called if it is needed, and only called once.
10119 @defmac AC_REQUIRE (@var{macro-name})
10120 @acindex{REQUIRE}
10121 If the M4 macro @var{macro-name} has not already been called, call it
10122 (without any arguments).  Make sure to quote @var{macro-name} with
10123 square brackets.  @var{macro-name} must have been defined using
10124 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10125 that it has been called.
10127 @code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
10128 must not be called from the top level.
10129 @end defmac
10131 @code{AC_REQUIRE} is often misunderstood.  It really implements
10132 dependencies between macros in the sense that if one macro depends upon
10133 another, the latter will be expanded @emph{before} the body of the
10134 former.  To be more precise, the required macro will be expanded before
10135 the outermost @code{AC_DEFUN}'d macro in the current expansion stack.
10136 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10137 @code{FOO}.  For instance, this definition of macros:
10139 @example
10140 @group
10141 AC_DEFUN([TRAVOLTA],
10142 [test "$body_temperature_in_celsius" -gt "38" &&
10143   dance_floor=occupied])
10144 AC_DEFUN([NEWTON_JOHN],
10145 [test "$hair_style" = "curly" &&
10146   dance_floor=occupied])
10147 @end group
10149 @group
10150 AC_DEFUN([RESERVE_DANCE_FLOOR],
10151 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10152   AC_REQUIRE([TRAVOLTA])
10153   AC_REQUIRE([NEWTON_JOHN])
10154 fi])
10155 @end group
10156 @end example
10158 @noindent
10159 with this @file{configure.ac}
10161 @example
10162 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10163 RESERVE_DANCE_FLOOR
10164 if test "$dance_floor" = occupied; then
10165   AC_MSG_ERROR([cannot pick up here, let's move])
10167 @end example
10169 @noindent
10170 will not leave you with a better chance to meet a kindred soul at
10171 other times than Saturday night since it expands into:
10173 @example
10174 @group
10175 test "$body_temperature_in_Celsius" -gt "38" &&
10176   dance_floor=occupied
10177 test "$hair_style" = "curly" &&
10178   dance_floor=occupied
10180 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10184 @end group
10185 @end example
10187 This behavior was chosen on purpose: (i) it prevents messages in
10188 required macros from interrupting the messages in the requiring macros;
10189 (ii) it avoids bad surprises when shell conditionals are used, as in:
10191 @example
10192 @group
10193 if @dots{}; then
10194   AC_REQUIRE([SOME_CHECK])
10196 @dots{}
10197 SOME_CHECK
10198 @end group
10199 @end example
10201 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10202 enforce expansion of required macros outside of shell conditional
10203 constructs.  You are furthermore encouraged to put all @code{AC_REQUIRE}s
10204 at the beginning of a macro.  You can use @code{dnl} to avoid the empty
10205 lines they leave.
10207 @node Suggested Ordering
10208 @subsection Suggested Ordering
10209 @cindex Macros, ordering
10210 @cindex Ordering macros
10212 Some macros should be run before another macro if both are called, but
10213 neither @emph{requires} that the other be called.  For example, a macro
10214 that changes the behavior of the C compiler should be called before any
10215 macros that run the C compiler.  Many of these dependencies are noted in
10216 the documentation.
10218 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10219 with this kind of dependency appear out of order in a
10220 @file{configure.ac} file.  The warning occurs when creating
10221 @command{configure} from @file{configure.ac}, not when running
10222 @command{configure}.
10224 For example, @code{AC_PROG_CPP} checks whether the C compiler
10225 can run the C preprocessor when given the @option{-E} option.  It should
10226 therefore be called after any macros that change which C compiler is
10227 being used, such as @code{AC_PROG_CC}.  So @code{AC_PROG_CC} contains:
10229 @example
10230 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10231 @end example
10233 @noindent
10234 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10235 when @code{AC_PROG_CC} is called.
10237 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10238 @acindex{BEFORE}
10239 Make M4 print a warning message to the standard error output if
10240 @var{called-macro-name} has already been called.  @var{this-macro-name}
10241 should be the name of the macro that is calling @code{AC_BEFORE}.  The
10242 macro @var{called-macro-name} must have been defined using
10243 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10244 that it has been called.
10245 @end defmac
10247 @node One-Shot Macros
10248 @subsection One-Shot Macros
10249 @cindex One-shot macros
10250 @cindex Macros, called once
10252 Some macros should be called only once, either because calling them
10253 multiple time is unsafe, or because it is bad style.  For instance
10254 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10255 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10256 sense to run these expensive checks more than once.  Such one-shot
10257 macros can be defined using @code{AC_DEFUN_ONCE}.
10259 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10260 @acindex{DEFUN_ONCE}
10262 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10263 Definitions}), and emit a warning any time the macro is called more than
10264 once.
10265 @end defmac
10267 Obviously it is not sensible to evaluate a macro defined by
10268 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}, most of the
10269 times you will want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10270 Macros}).
10272 @node Obsoleting Macros
10273 @section Obsoleting Macros
10274 @cindex Obsoleting macros
10275 @cindex Macros, obsoleting
10277 Configuration and portability technology has evolved over the years.
10278 Often better ways of solving a particular problem are developed, or
10279 ad-hoc approaches are systematized.  This process has occurred in many
10280 parts of Autoconf.  One result is that some of the macros are now
10281 considered @dfn{obsolete}; they still work, but are no longer considered
10282 the best thing to do, hence they should be replaced with more modern
10283 macros.  Ideally, @command{autoupdate} should replace the old macro calls
10284 with their modern implementation.
10286 Autoconf provides a simple means to obsolete a macro.
10288 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10289 @auindex{DEFUN}
10290 Define @var{old-macro} as @var{implementation}.  The only difference
10291 with @code{AC_DEFUN} is that the user will be warned that
10292 @var{old-macro} is now obsolete.
10294 If she then uses @command{autoupdate}, the call to @var{old-macro} will be
10295 replaced by the modern @var{implementation}.  @var{message} should
10296 include information on what to do after running @command{autoupdate};
10297 @command{autoupdate} will print it as a warning, and include it
10298 in the updated @file{configure.ac} file.
10300 The details of this macro are hairy: if @command{autoconf} encounters an
10301 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10302 as usual.  However, when @command{autoupdate} is run, only M4 and M4sugar
10303 macros will be expanded here, while all other macros are disabled and will
10304 appear literally in the updated @file{configure.ac}.
10305 @end defmac
10307 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10308 @auindex{ALIAS}
10309 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10310 with the same parameters.  This happens for example if the macro was renamed.
10311 @end defmac
10313 @node Coding Style
10314 @section Coding Style
10315 @cindex Coding style
10317 The Autoconf macros follow a strict coding style.  You are encouraged to
10318 follow this style, especially if you intend to distribute your macro,
10319 either by contributing it to Autoconf itself, or via other means.
10321 The first requirement is to pay great attention to the quotation.  For
10322 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10324 Do not try to invent new interfaces.  It is likely that there is a macro
10325 in Autoconf that resembles the macro you are defining: try to stick to
10326 this existing interface (order of arguments, default values, etc.).  We
10327 @emph{are} conscious that some of these interfaces are not perfect;
10328 nevertheless, when harmless, homogeneity should be preferred over
10329 creativity.
10331 Be careful about clashes both between M4 symbols and between shell
10332 variables.
10334 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10335 you are unlikely to generate conflicts.  Nevertheless, when you need to
10336 set a special value, @emph{avoid using a regular macro name}; rather,
10337 use an ``impossible'' name.  For instance, up to version 2.13, the macro
10338 @code{AC_SUBST} used to remember what @var{symbol}s were already defined
10339 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10340 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10341 impossible to @samp{AC_SUBST(FILE)}!  In this case,
10342 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10343 have been used (yes, with the parentheses).
10344 @c or better yet, high-level macros such as @code{m4_expand_once}
10346 No Autoconf macro should ever enter the user-variable name space; i.e.,
10347 except for the variables that are the actual result of running the
10348 macro, all shell variables should start with @code{ac_}.  In
10349 addition, small macros or any macro that is likely to be embedded in
10350 other macros should be careful not to use obvious names.
10352 @cindex @code{dnl}
10353 Do not use @code{dnl} to introduce comments: most of the comments you
10354 are likely to write are either header comments which are not output
10355 anyway, or comments that should make their way into @file{configure}.
10356 There are exceptional cases where you do want to comment special M4
10357 constructs, in which case @code{dnl} is right, but keep in mind that it
10358 is unlikely.
10360 M4 ignores the leading blanks and newlines before each argument.
10361 Use this feature to
10362 indent in such a way that arguments are (more or less) aligned with the
10363 opening parenthesis of the macro being called.  For instance, instead of
10365 @example
10366 AC_CACHE_CHECK(for EMX OS/2 environment,
10367 ac_cv_emxos2,
10368 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10369 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10370 @end example
10372 @noindent
10373 write
10375 @example
10376 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10377 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10378                    [ac_cv_emxos2=yes],
10379                    [ac_cv_emxos2=no])])
10380 @end example
10382 @noindent
10383 or even
10385 @example
10386 AC_CACHE_CHECK([for EMX OS/2 environment],
10387                [ac_cv_emxos2],
10388                [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10389                                                    [return __EMX__;])],
10390                                   [ac_cv_emxos2=yes],
10391                                   [ac_cv_emxos2=no])])
10392 @end example
10394 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10395 cross-compiling, provide a pessimistic value (typically @samp{no}).
10397 Feel free to use various tricks to prevent auxiliary tools, such as
10398 syntax-highlighting editors, from behaving improperly.  For instance,
10399 instead of:
10401 @example
10402 m4_bpatsubst([$1], [$"])
10403 @end example
10405 @noindent
10408 @example
10409 m4_bpatsubst([$1], [$""])
10410 @end example
10412 @noindent
10413 so that Emacsen do not open an endless ``string'' at the first quote.
10414 For the same reasons, avoid:
10416 @example
10417 test $[#] != 0
10418 @end example
10420 @noindent
10421 and use:
10423 @example
10424 test $[@@%:@@] != 0
10425 @end example
10427 @noindent
10428 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10429 breaking the bracket-matching highlighting from Emacsen.  Note the
10430 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc.  Do
10431 not escape when it is unnecessary.  Common examples of useless quotation
10432 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10433 etc.  If you add portability issues to the picture, you'll prefer
10434 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10435 better than hacking Autoconf @code{:-)}.
10437 When using @command{sed}, don't use @option{-e} except for indenting
10438 purposes.  With the @code{s} and @code{y} commands, the preferred
10439 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10440 or replacement, in which case you should use @samp{|}, or optionally
10441 @samp{,} if you know the pattern and replacement cannot contain a file
10442 name.  If none of these characters will do, choose a printable character
10443 that cannot appear in the pattern or replacement.  Characters from the
10444 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10445 replacement might contain a file name, since they have special meaning
10446 to the shell and are less likely to occur in file names.
10448 @xref{Macro Definitions}, for details on how to define a macro.  If a
10449 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10450 of an @code{AC_REQUIRE} directive, and macros required by other macros
10451 inside arguments will not need to be expanded before this macro, then
10452 use @code{m4_define}.  In case of doubt, use @code{AC_DEFUN}.
10453 All the @code{AC_REQUIRE} statements should be at the beginning of the
10454 macro, @code{dnl}'ed.
10456 You should not rely on the number of arguments: instead of checking
10457 whether an argument is missing, test that it is not empty.  It provides
10458 both a simpler and a more predictable interface to the user, and saves
10459 room for further arguments.
10461 Unless the macro is short, try to leave the closing @samp{])} at the
10462 beginning of a line, followed by a comment that repeats the name of the
10463 macro being defined.  This introduces an additional newline in
10464 @command{configure}; normally, that is not a problem, but if you want to
10465 remove it you can use @samp{[]dnl} on the last line.  You can similarly
10466 use @samp{[]dnl} after a macro call to remove its newline.  @samp{[]dnl}
10467 is recommended instead of @samp{dnl} to ensure that M4 does not
10468 interpret the @samp{dnl} as being attached to the preceding text or
10469 macro output.  For example, instead of:
10471 @example
10472 AC_DEFUN([AC_PATH_X],
10473 [AC_MSG_CHECKING([for X])
10474 AC_REQUIRE_CPP()
10475 @r{# @dots{}omitted@dots{}}
10476   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10477 fi])
10478 @end example
10480 @noindent
10481 you would write:
10483 @example
10484 AC_DEFUN([AC_PATH_X],
10485 [AC_REQUIRE_CPP()[]dnl
10486 AC_MSG_CHECKING([for X])
10487 @r{# @dots{}omitted@dots{}}
10488   AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10489 fi[]dnl
10490 ])# AC_PATH_X
10491 @end example
10493 If the macro is long, try to split it into logical chunks.  Typically,
10494 macros that check for a bug in a function and prepare its
10495 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10496 this setup.  Do not hesitate to introduce auxiliary macros to factor
10497 your code.
10499 In order to highlight the recommended coding style, here is a macro
10500 written the old way:
10502 @example
10503 dnl Check for EMX on OS/2.
10504 dnl _AC_EMXOS2
10505 AC_DEFUN(_AC_EMXOS2,
10506 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10507 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10508 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10509 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10510 @end example
10512 @noindent
10513 and the new way:
10515 @example
10516 # _AC_EMXOS2
10517 # ----------
10518 # Check for EMX on OS/2.
10519 m4_define([_AC_EMXOS2],
10520 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10521 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10522                    [ac_cv_emxos2=yes],
10523                    [ac_cv_emxos2=no])])
10524 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10525 ])# _AC_EMXOS2
10526 @end example
10531 @c ============================================= Portable Shell Programming
10533 @node Portable Shell
10534 @chapter Portable Shell Programming
10535 @cindex Portable shell programming
10537 When writing your own checks, there are some shell-script programming
10538 techniques you should avoid in order to make your code portable.  The
10539 Bourne shell and upward-compatible shells like the Korn shell and Bash
10540 have evolved over the years, but to prevent trouble, do not take
10541 advantage of features that were added after Unix version 7, circa
10542 1977 (@pxref{Systemology}).
10544 You should not use shell functions, aliases, negated character
10545 classes, or other features that are not found in all Bourne-compatible
10546 shells; restrict yourself to the lowest common denominator.  Even
10547 @code{unset} is not supported by all shells!
10549 Some old systems have quite
10550 small limits on the length of the @samp{#!} line; for instance, 32
10551 bytes (not including the newline) on SunOS 4.
10552 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10553 required a single space between the @samp{#!} and the @samp{/}, but
10554 these are no longer of practical concern.
10556 The set of external programs you should run in a @command{configure} script
10557 is fairly small.  @xref{Utilities in Makefiles, , Utilities in
10558 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list.  This
10559 restriction allows users to start out with a fairly small set of
10560 programs and build the rest, avoiding too many interdependencies between
10561 packages.
10563 Some of these external utilities have a portable subset of features; see
10564 @ref{Limitations of Usual Tools}.
10566 There are other sources of documentation about shells.  The
10567 specification for the Posix
10568 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10569 Command Language}, though more generous than the restrictive shell
10570 subset described above, is fairly portable nowadays.  Also please see
10571 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10573 @menu
10574 * Shellology::                  A zoology of shells
10575 * Here-Documents::              Quirks and tricks
10576 * File Descriptors::            FDs and redirections
10577 * File System Conventions::     File names
10578 * Shell Substitutions::         Variable and command expansions
10579 * Assignments::                 Varying side effects of assignments
10580 * Parentheses::                 Parentheses in shell scripts
10581 * Slashes::                     Slashes in shell scripts
10582 * Special Shell Variables::     Variables you should not change
10583 * Limitations of Builtins::     Portable use of not so portable /bin/sh
10584 * Limitations of Usual Tools::  Portable use of portable tools
10585 * Limitations of Make::         Portable Makefiles
10586 @end menu
10588 @node Shellology
10589 @section Shellology
10590 @cindex Shellology
10592 There are several families of shells, most prominently the Bourne family
10593 and the C shell family which are deeply incompatible.  If you want to
10594 write portable shell scripts, avoid members of the C shell family.  The
10595 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10596 Shell difference FAQ} includes a small history of Posix shells, and a
10597 comparison between several of them.
10599 Below we describe some of the members of the Bourne shell family.
10601 @table @asis
10602 @item Ash
10603 @cindex Ash
10604 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10605 systems as a light-weight Bourne-compatible shell.  Ash 0.2 has some
10606 bugs that are fixed in the 0.3.x series, but portable shell scripts
10607 should work around them, since version 0.2 is still shipped with many
10608 @acronym{GNU}/Linux distributions.
10610 To be compatible with Ash 0.2:
10612 @itemize @minus
10613 @item
10614 don't use @samp{$?} after expanding empty or unset variables,
10615 or at the start of an @command{eval}:
10617 @example
10618 foo=
10619 false
10620 $foo
10621 echo "Do not use it: $?"
10622 false
10623 eval 'echo "Do not use it: $?"'
10624 @end example
10626 @item
10627 don't use command substitution within variable expansion:
10629 @example
10630 cat $@{FOO=`bar`@}
10631 @end example
10633 @item
10634 beware that single builtin substitutions are not performed by a
10635 subshell, hence their effect applies to the current shell!  @xref{Shell
10636 Substitutions}, item ``Command Substitution''.
10637 @end itemize
10639 @item Bash
10640 @cindex Bash
10641 To detect whether you are running Bash, test whether
10642 @code{BASH_VERSION} is set.  To require
10643 Posix compatibility, run @samp{set -o posix}.  @xref{Bash POSIX
10644 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
10645 Manual}, for details.
10647 @item Bash 2.05 and later
10648 @cindex Bash 2.05 and later
10649 Versions 2.05 and later of Bash use a different format for the
10650 output of the @command{set} builtin, designed to make evaluating its
10651 output easier.  However, this output is not compatible with earlier
10652 versions of Bash (or with many other shells, probably).  So if
10653 you use Bash 2.05 or higher to execute @command{configure},
10654 you'll need to use Bash 2.05 for all other build tasks as well.
10656 @item Ksh
10657 @cindex Ksh
10658 @cindex Korn shell
10659 @prindex @samp{ksh}
10660 @prindex @samp{ksh88}
10661 @prindex @samp{ksh93}
10662 The Korn shell is compatible with the Bourne family and it mostly
10663 conforms to Posix.  It has two major variants commonly
10664 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
10665 release.  It is usually called @command{ksh}, but is called @command{sh}
10666 on some hosts if you set your path appropriately.
10668 Solaris systems have three variants:
10669 @prindex @command{/usr/bin/ksh} on Solaris
10670 @command{/usr/bin/ksh} is @samp{ksh88}; it is
10671 standard on Solaris 2.0 and later.
10672 @prindex @command{/usr/xpg4/bin/sh} on Solaris
10673 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
10674 @samp{ksh88}; it is standard on Solaris 9 and later.
10675 @prindex @command{/usr/dt/bin/dtksh} on Solaris
10676 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
10677 Variants that are not standard may be parts of optional
10678 packages.  There is no extra charge for these packages, but they are
10679 not part of a minimal OS install and therefore some installations may
10680 not have it.
10682 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
10683 is also available as @command{/usr/bin/posix/sh}.  If the environment
10684 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
10685 the standard shell conform to Posix.
10687 @item Pdksh
10688 @prindex @samp{pdksh}
10689 A public-domain clone of the Korn shell called @command{pdksh} is widely
10690 available: it has most of the @samp{ksh88} features along with a few of
10691 its own.  It will usually set @code{KSH_VERSION}, except if invoked as
10692 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
10693 Posix compatibility by running @samp{set -o posix}.  Unfortunately, with
10694 @command{pdksh} 5.2.14 (the latest stable version as of February 2006)
10695 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
10696 at least one respect:
10698 @example
10699 $ echo "`echo \"hello\"`"
10700 hello
10701 $ set -o posix
10702 $ echo "`echo \"hello\"`"
10703 "hello"
10704 @end example
10706 The last line of output contains spurious quotes.  This is yet another
10707 reason why portable shell code should not contain
10708 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
10709 Substitutions}).
10711 @item Zsh
10712 @cindex Zsh
10713 To detect whether you are running @command{zsh}, test whether
10714 @code{ZSH_VERSION} is set.  By default @command{zsh} is @emph{not}
10715 compatible with the Bourne shell: you must execute @samp{emulate sh},
10716 and for @command{zsh} versions before 3.1.6-dev-18 you must also
10717 set @code{NULLCMD} to @samp{:}.  @xref{Compatibility, , Compatibility,
10718 zsh, The Z Shell Manual}, for details.
10720 The default Mac OS X @command{sh} was originally Zsh; it was changed to
10721 Bash in Mac OS X 10.2.
10722 @end table
10724 The following discussion between Russ Allbery and Robert Lipe is worth
10725 reading:
10727 @noindent
10728 Russ Allbery:
10730 @quotation
10731 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
10732 leads to a permanent deadlock.  Vendors don't want to break users'
10733 existing shell scripts, and there are some corner cases in the Bourne
10734 shell that are not completely compatible with a Posix shell.  Thus,
10735 vendors who have taken this route will @emph{never} (OK@dots{}``never say
10736 never'') replace the Bourne shell (as @command{/bin/sh}) with a
10737 Posix shell.
10738 @end quotation
10740 @noindent
10741 Robert Lipe:
10743 @quotation
10744 This is exactly the problem.  While most (at least most System V's) do
10745 have a Bourne shell that accepts shell functions most vendor
10746 @command{/bin/sh} programs are not the Posix shell.
10748 So while most modern systems do have a shell @emph{somewhere} that meets the
10749 Posix standard, the challenge is to find it.
10750 @end quotation
10752 @node Here-Documents
10753 @section Here-Documents
10754 @cindex Here documents
10755 @cindex Shell here documents
10757 Don't rely on @samp{\} being preserved just because it has no special
10758 meaning together with the next symbol.  In the native @command{sh}
10759 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
10760 unquoted delimiter.  As a general rule, if @samp{\\} expands to @samp{\}
10761 use @samp{\\} to get @samp{\}.
10763 With Open@acronym{BSD} 2.7's @command{sh}
10765 @example
10766 @group
10767 $ @kbd{cat <<EOF
10768 > \" \\
10769 > EOF}
10770 " \
10771 @end group
10772 @end example
10774 @noindent
10775 and with Bash:
10777 @example
10778 @group
10779 bash-2.04$ @kbd{cat <<EOF
10780 > \" \\
10781 > EOF}
10782 \" \
10783 @end group
10784 @end example
10787 Many older shells (including the Bourne shell) implement here-documents
10788 inefficiently.  And some shells mishandle large here-documents: for example,
10789 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
10790 derived from Korn shell version M-12/28/93d, mishandle braced variable
10791 expansion @code{$@{var@}} that crosses a 1024- or 4096-byte buffer boundary
10792 within a here-document.  If the closing brace does not lie on the boundary,
10793 the failure is silent and the variable expansion will be empty, otherwise
10794 the shell will report a bad substitution.  This bug can usually be worked
10795 around by omitting the braces: @code{$var}.
10797 Some shells can be extremely inefficient when there are a lot of
10798 here-documents inside a single statement.  For instance if your
10799 @file{configure.ac} includes something like:
10801 @example
10802 @group
10803 if <cross_compiling>; then
10804   assume this and that
10805 else
10806   check this
10807   check that
10808   check something else
10809   @dots{}
10810   on and on forever
10811   @dots{}
10813 @end group
10814 @end example
10816 A shell parses the whole @code{if}/@code{fi} construct, creating
10817 temporary files for each here document in it.  Some shells create links
10818 for such here-documents on every @code{fork}, so that the clean-up code
10819 they had installed correctly removes them.  It is creating the links
10820 that can take the shell forever.
10822 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
10823 @code{if}/@code{fi} constructs, would improve the performance
10824 significantly.  Anyway, this kind of construct is not exactly the
10825 typical use of Autoconf.  In fact, it's even not recommended, because M4
10826 macros can't look into shell conditionals, so we may fail to expand a
10827 macro when it was expanded before in a conditional path, and the
10828 condition turned out to be false at runtime, and we end up not
10829 executing the macro at all.
10831 @node File Descriptors
10832 @section File Descriptors
10833 @cindex Descriptors
10834 @cindex File descriptors
10835 @cindex Shell file descriptors
10837 Some file descriptors shall not be used, since some systems, admittedly
10838 arcane, use them for special purpose:
10840 @display
10841 3 --- some systems may open it to @samp{/dev/tty}.
10842 4 --- used on the Kubota Titan.
10843 @end display
10845 Don't redirect the same file descriptor several times, as you are doomed
10846 to failure under Ultrix.
10848 @example
10849 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
10850 UWS V4.4 (Rev. 11)
10851 $ @kbd{eval 'echo matter >fullness' >void}
10852 illegal io
10853 $ @kbd{eval '(echo matter >fullness)' >void}
10854 illegal io
10855 $ @kbd{(eval '(echo matter >fullness)') >void}
10856 Ambiguous output redirect.
10857 @end example
10859 @noindent
10860 In each case the expected result is of course @file{fullness} containing
10861 @samp{matter} and @file{void} being empty.
10863 Don't try to redirect the standard error of a command substitution: it
10864 must be done @emph{inside} the command substitution: when running
10865 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
10866 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
10868 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
10869 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
10871 Most shells, if not all (including Bash, Zsh, Ash), output traces on
10872 stderr, even for sub-shells.  This might result in undesirable content
10873 if you meant to capture the standard-error output of the inner command:
10875 @example
10876 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
10877 $ @kbd{cat stderr}
10878 + eval echo foo >&2
10879 + echo foo
10881 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
10882 $ @kbd{cat stderr}
10883 + eval 'echo foo >&2'
10884 ++ echo foo
10886 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
10887 @i{# Traces on startup files deleted here.}
10888 $ @kbd{cat stderr}
10889 +zsh:1> eval echo foo >&2
10890 +zsh:1> echo foo
10892 @end example
10894 @noindent
10895 You'll appreciate the various levels of detail@enddots{}
10897 One workaround is to grep out uninteresting lines, hoping not to remove
10898 good ones@enddots{}
10900 Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
10901 bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
10903 Don't rely on open file descriptors being open in child processes.  In
10904 @command{ksh}, file descriptors above 2 which are opened using
10905 @samp{exec n>file} are closed by a subsequent @samp{exec} (such as
10906 that involved in the fork-and-exec which runs a program or script).
10907 Thus, using sh, we have:
10908 @example
10909 $ cat ./descrips
10910 #!/bin/sh -
10911 echo hello >&5
10912 $ exec 5>t
10913 $ ./descrips
10914 $ cat t
10915 hello
10917 @end example
10918 But using ksh:
10919 @example
10920 $ exec 5>t
10921 $ ./descrips
10922 hello
10923 $ cat t
10925 @end example
10926 Within the process which runs the @samp{descrips} script, file
10927 descriptor number 5 is closed.
10929 @node File System Conventions
10930 @section File System Conventions
10931 @cindex File system conventions
10933 Autoconf uses shell-script processing extensively, so the file names
10934 that it processes should not contain characters that are special to the
10935 shell.  Special characters include space, tab, newline, @sc{nul}, and
10936 the following:
10938 @example
10939 " # $ & ' ( ) * ; < = > ? [ \ ` |
10940 @end example
10942 Also, file names should not begin with @samp{~} or @samp{-}, and should
10943 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
10944 immediately after @samp{:}.
10946 These restrictions apply not only to the files that you distribute, but
10947 also to the absolute file names of your source, build, and destination
10948 directories.
10950 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
10951 they should be avoided.
10953 Posix lets implementations treat leading @file{//} specially, but
10954 requires leading @file{///} and beyond to be equivalent to @file{/}.
10955 Most Unix variants treat @file{//} like @file{/}.  However, some treat
10956 @file{//} as a ``super-root'' that can provide access to files that are
10957 not otherwise reachable from @file{/}.  The super-root tradition began
10958 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
10959 has revived it.
10961 While @command{autoconf} and friends will usually be run on some Posix
10962 variety, it can and will be used on other systems, most notably @acronym{DOS}
10963 variants.  This impacts several assumptions regarding file names.
10965 @noindent
10966 For example, the following code:
10968 @example
10969 case $foo_dir in
10970   /*) # Absolute
10971      ;;
10972   *)
10973      foo_dir=$dots$foo_dir ;;
10974 esac
10975 @end example
10977 @noindent
10978 will fail to properly detect absolute file names on those systems, because
10979 they can use a drivespec, and will usually use a backslash as directory
10980 separator.  If you want to be portable to @acronym{DOS} variants (at the
10981 price of rejecting valid but oddball Posix file names like @file{a:\b}),
10982 you can check for absolute file names like this:
10984 @example
10985 case $foo_dir in
10986   [\\/]* | ?:[\\/]* ) # Absolute
10987      ;;
10988   *)
10989      foo_dir=$dots$foo_dir ;;
10990 esac
10991 @end example
10993 @noindent
10994 Make sure you quote the brackets if appropriate and keep the backslash as
10995 first character (@pxref{Limitations of Builtins}).
10997 Also, because the colon is used as part of a drivespec, these systems don't
10998 use it as path separator.  When creating or accessing paths, you can use the
10999 @code{PATH_SEPARATOR} output variable instead.  @command{configure} sets this
11000 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
11002 File names need extra care as well.  While @acronym{DOS} variants
11003 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP}) will
11004 usually be able to handle long file names properly, there are still
11005 limitations that can seriously break packages.  Several of these issues
11006 can be easily detected by the
11007 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11008 package.
11010 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11011 indicate where they apply: @sc{sfn} means the issues are only relevant to
11012 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11013 variants, while @sc{lfn} identifies problems that exist even under
11014 Microsoft Windows variants.
11016 @table @asis
11017 @item No multiple dots (@sc{sfn})
11018 @acronym{DOS} cannot handle multiple dots in file names.  This is an especially
11019 important thing to remember when building a portable configure script,
11020 as @command{autoconf} uses a .in suffix for template files.
11022 This is perfectly OK on Posix variants:
11024 @example
11025 AC_CONFIG_HEADERS([config.h])
11026 AC_CONFIG_FILES([source.c foo.bar])
11027 AC_OUTPUT
11028 @end example
11030 @noindent
11031 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11032 @samp{source.c.in} and @samp{foo.bar.in}.  To make your package more portable
11033 to @acronym{DOS}-based environments, you should use this instead:
11035 @example
11036 AC_CONFIG_HEADERS([config.h:config.hin])
11037 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11038 AC_OUTPUT
11039 @end example
11041 @item No leading dot (@sc{sfn})
11042 @acronym{DOS} cannot handle file names that start with a dot.  This is usually
11043 not a very important issue for @command{autoconf}.
11045 @item Case insensitivity (@sc{lfn})
11046 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11047 file called @samp{INSTALL} and a directory called @samp{install}.  This
11048 also affects @command{make}; if there's a file called @samp{INSTALL} in
11049 the directory, @samp{make install} will do nothing (unless the
11050 @samp{install} target is marked as PHONY).
11052 @item The 8+3 limit (@sc{sfn})
11053 Because the @acronym{DOS} file system only stores the first 8 characters of
11054 the file name and the first 3 of the extension, those must be unique.
11055 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11056 @file{foobar-prettybird.c} all resolve to the same file name
11057 (@file{FOOBAR-P.C}).  The same goes for @file{foo.bar} and
11058 @file{foo.bartender}.
11060 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11061 uses numeric
11062 tails in the short version of file names to make them unique.  However, a
11063 registry setting can turn this behavior off.  While this makes it
11064 possible to share file trees containing long file names between @sc{sfn}
11065 and @sc{lfn} environments, it also means the above problem applies there
11066 as well.
11068 @item Invalid characters (@sc{lfn})
11069 Some characters are invalid in @acronym{DOS} file names, and should therefore
11070 be avoided.  In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11071 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11072 In a @sc{sfn} environment, other characters are also invalid.  These
11073 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11075 @item Invalid names (@sc{lfn})
11076 Some @acronym{DOS} file names are reserved, and cause problems if you
11077 try to use files with those names.  These names include @file{CON},
11078 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11079 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11080 File names are case insensitive, so even names like
11081 @file{aux/config.guess} are disallowed.
11083 @end table
11085 @node Shell Substitutions
11086 @section Shell Substitutions
11087 @cindex Shell substitutions
11089 Contrary to a persistent urban legend, the Bourne shell does not
11090 systematically split variables and back-quoted expressions, in particular
11091 on the right-hand side of assignments and in the argument of @code{case}.
11092 For instance, the following code:
11094 @example
11095 case "$given_srcdir" in
11096 .)  top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11097 *)  top_srcdir="$dots$given_srcdir" ;;
11098 esac
11099 @end example
11101 @noindent
11102 is more readable when written as:
11104 @example
11105 case $given_srcdir in
11106 .)  top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11107 *)  top_srcdir=$dots$given_srcdir ;;
11108 esac
11109 @end example
11111 @noindent
11112 and in fact it is even @emph{more} portable: in the first case of the
11113 first attempt, the computation of @code{top_srcdir} is not portable,
11114 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11115 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11116 the same way.  There is just no portable way to use double-quoted
11117 strings inside double-quoted back-quoted expressions (pfew!).
11119 @table @code
11120 @item $@@
11121 @cindex @samp{"$@@"}
11122 One of the most famous shell-portability issues is related to
11123 @samp{"$@@"}.  When there are no positional arguments, Posix says
11124 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11125 original Unix version 7 Bourne shell treated it as equivalent to
11126 @samp{""} instead, and this behavior survives in later implementations
11127 like Digital Unix 5.0.
11129 The traditional way to work around this portability problem is to use
11130 @samp{$@{1+"$@@"@}}.  Unfortunately this method does not work with
11131 Zsh (3.x and 4.x), which is used on Mac OS X@.  When emulating
11132 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11134 @example
11135 zsh $ @kbd{emulate sh}
11136 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11137 Hello World
11139 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11140 Hello
11141 World
11143 @end example
11145 @noindent
11146 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11147 @samp{"$@@"} because of the portability problems mentioned above.
11148 One workaround relies on Zsh's ``global aliases'' to convert
11149 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11151 @example
11152 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11153 @end example
11155 A more conservative workaround is to avoid @samp{"$@@"} if it is
11156 possible that there may be no positional arguments.  For example,
11157 instead of:
11159 @example
11160 cat conftest.c "$@@"
11161 @end example
11163 you can use this instead:
11165 @example
11166 case $# in
11167 0) cat conftest.c;;
11168 *) cat conftest.c "$@@";;
11169 esac
11170 @end example
11173 @item $@{10@}
11174 @cindex positional parameters
11175 The 10th, 11th, @dots{} positional parameters can be accessed only after
11176 a @code{shift}.  The 7th Edition shell reported an error if given
11177 @code{$@{10@}}, and
11178 Solaris 10 @command{/bin/sh} still acts that way:
11180 @example
11181 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11182 $ @kbd{echo $@{10@}}
11183 bad substitution
11184 @end example
11186 @item $@{@var{var}:-@var{value}@}
11187 @c Info cannot handle `:' in index entries.
11188 @c @cindex $@{@var{var}:-@var{value}@}
11189 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11190 colon for any shell substitution, and complain and die.
11192 @item $@{@var{var}=@var{literal}@}
11193 @cindex $@{@var{var}=@var{literal}@}
11194 Be sure to quote:
11196 @example
11197 : $@{var='Some words'@}
11198 @end example
11200 @noindent
11201 otherwise some shells, such as on Digital Unix V 5.0, will die because
11202 of a ``bad substitution''.
11204 @sp 1
11206 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11207 of this.  Imagine you need set a variable to a string containing
11208 @samp{@}}.  This @samp{@}} character confuses Solaris @command{/bin/sh}
11209 when the affected variable was already set.  This bug can be exercised
11210 by running:
11212 @example
11213 $ @kbd{unset foo}
11214 $ @kbd{foo=$@{foo='@}'@}}
11215 $ @kbd{echo $foo}
11217 $ @kbd{foo=$@{foo='@}'   # no error; this hints to what the bug is}
11218 $ @kbd{echo $foo}
11220 $ @kbd{foo=$@{foo='@}'@}}
11221 $ @kbd{echo $foo}
11222 @}@}
11223  ^ ugh!
11224 @end example
11226 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11227 though it is enclosed in single quotes.  The problem doesn't happen
11228 using double quotes.
11230 @item $@{@var{var}=@var{expanded-value}@}
11231 @cindex $@{@var{var}=@var{expanded-value}@}
11232 On Ultrix,
11233 running
11235 @example
11236 default="yu,yaa"
11237 : $@{var="$default"@}
11238 @end example
11240 @noindent
11241 will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11242 each char will be set.  You won't observe the phenomenon using a simple
11243 @samp{echo $var} since apparently the shell resets the 8th bit when it
11244 expands $var.  Here are two means to make this shell confess its sins:
11246 @example
11247 $ @kbd{cat -v <<EOF
11248 $var
11249 EOF}
11250 @end example
11252 @noindent
11255 @example
11256 $ @kbd{set | grep '^var=' | cat -v}
11257 @end example
11259 One classic incarnation of this bug is:
11261 @example
11262 default="a b c"
11263 : $@{list="$default"@}
11264 for c in $list; do
11265   echo $c
11266 done
11267 @end example
11269 @noindent
11270 You'll get @samp{a b c} on a single line.  Why?  Because there are no
11271 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11272 bit set, hence no IFS splitting is performed!!!
11274 One piece of good news is that Ultrix works fine with @samp{:
11275 $@{list=$default@}}; i.e., if you @emph{don't} quote.  The bad news is
11276 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11277 @var{default}!
11279 The portable way out consists in using a double assignment, to switch
11280 the 8th bit twice on Ultrix:
11282 @example
11283 list=$@{list="$default"@}
11284 @end example
11286 @noindent
11287 @dots{}but beware of the @samp{@}} bug from Solaris (see above).  For safety,
11288 use:
11290 @example
11291 test "$@{var+set@}" = set || var=@var{@{value@}}
11292 @end example
11295 @item `@var{commands}`
11296 @cindex `@var{commands}`
11297 @cindex Command Substitution
11298 Posix requires shells to trim all trailing newlines from command
11299 output before substituting it, so assignments like
11300 @samp{dir=`echo "$file" | tr a A`} will not work as expected if
11301 @samp{$file} ends in a newline.
11303 While in general it makes no sense, do not substitute a single builtin
11304 with side effects, because Ash 0.2, trying to optimize, does not fork a
11305 subshell to perform the command.
11307 For instance, if you wanted to check that @command{cd} is silent, do not
11308 use @samp{test -z "`cd /`"} because the following can happen:
11310 @example
11311 $ @kbd{pwd}
11312 /tmp
11313 $ @kbd{test -z "`cd /`" && pwd}
11315 @end example
11317 @noindent
11318 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11320 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11321 command substitution of a native program, if the end of the substution
11322 is not aligned with the end of the double quote.  This may be worked
11323 around by inserting another pair of quotes:
11325 @example
11326 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11327 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11328 - broken differ: char 4, line 1
11329 @end example
11332 @item $(@var{commands})
11333 @cindex $(@var{commands})
11334 This construct is meant to replace @samp{`@var{commands}`},
11335 and it has most of the problems listed under @code{`@var{commands}`}.
11337 This construct can be
11338 nested while this is impossible to do portably with back quotes.
11339 Unfortunately it is not yet universally supported.  Most notably, even recent
11340 releases of Solaris don't support it:
11342 @example
11343 $ @kbd{showrev -c /bin/sh | grep version}
11344 Command version: SunOS 5.10 Generic January 2005
11345 $ @kbd{echo $(echo blah)}
11346 syntax error: `(' unexpected
11347 @end example
11349 @noindent
11350 nor does @sc{irix} 6.5's Bourne shell:
11351 @example
11352 $ @kbd{uname -a}
11353 IRIX firebird-image 6.5 07151432 IP22
11354 $ @kbd{echo $(echo blah)}
11355 $(echo blah)
11356 @end example
11358 If you do use @samp{$(@var{commands})}, make sure that the commands
11359 do not start with a parenthesis, as that would cause confusion with
11360 a different notation @samp{$((@var{expression}))} that in modern
11361 shells is an arithmetic expression not a command.  To avoid the
11362 confusion, insert a space between the two opening parentheses.
11364 Avoid @var{commands} that contain unbalanced parentheses in
11365 here-documents, comments, or case statement patterns, as many shells
11366 mishandle them.  For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11367 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11369 @example
11370 echo $(case x in x) echo hello;; esac)
11371 @end example
11373 @item ^
11374 @cindex ^ quoting
11375 Always quote @samp{^}, otherwise traditional shells such as
11376 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11378 @end table
11381 @node Assignments
11382 @section Assignments
11383 @cindex Shell assignments
11385 When setting several variables in a row, be aware that the order of the
11386 evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
11387 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11388 You must use
11389 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11391 Don't rely on the following to find @file{subdir/program}:
11393 @example
11394 PATH=subdir$PATH_SEPARATOR$PATH program
11395 @end example
11397 @noindent
11398 as this does not work with Zsh 3.0.6.  Use something like this
11399 instead:
11401 @example
11402 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11403 @end example
11405 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11406 the status and propagates that of the last statement:
11408 @example
11409 $ @kbd{false || foo=bar; echo $?}
11411 $ @kbd{false || foo=`:`; echo $?}
11413 @end example
11415 @noindent
11416 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11417 to 0 in any case:
11419 @example
11420 $ @kbd{foo=`exit 1`; echo $?}
11422 @end example
11424 To assign default values, follow this algorithm:
11426 @enumerate
11427 @item
11428 If the default value is a literal and does not contain any closing
11429 brace, use:
11431 @example
11432 : $@{var='my literal'@}
11433 @end example
11435 @item
11436 If the default value contains no closing brace, has to be expanded, and
11437 the variable being initialized will never be IFS-split (i.e., it's not a
11438 list), then use:
11440 @example
11441 : $@{var="$default"@}
11442 @end example
11444 @item
11445 If the default value contains no closing brace, has to be expanded, and
11446 the variable being initialized will be IFS-split (i.e., it's a list),
11447 then use:
11449 @example
11450 var=$@{var="$default"@}
11451 @end example
11453 @item
11454 If the default value contains a closing brace, then use:
11456 @example
11457 test "$@{var+set@}" = set || var='$@{indirection@}'
11458 @end example
11459 @end enumerate
11461 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11462 doubt, just use the latter.  @xref{Shell Substitutions}, items
11463 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11464 for the rationale.
11466 @node Parentheses
11467 @section Parentheses in Shell Scripts
11468 @cindex Shell parentheses
11470 Beware of two opening parentheses in a row, as some shell
11471 implementations mishandle them.  For example, @samp{pdksh} 5.2.14
11472 misparses the following code:
11474 @example
11475 if ((true) || false); then
11476   echo ok
11478 @end example
11480 @noindent
11481 To work around this problem, insert a space between the two opening
11482 parentheses.  There is a similar problem and workaround with
11483 @samp{$((}; see @ref{Shell Substitutions}.
11485 Posix requires support for @code{case} patterns with opening
11486 parentheses like this:
11488 @example
11489 case $file_name in
11490 (*.c) echo "C source code";;
11491 esac
11492 @end example
11494 @noindent
11495 but the @code{(} in this example is not portable to many older Bourne
11496 shell implementations.  It can be omitted safely.
11498 @node Slashes
11499 @section Slashes in Shell Scripts
11500 @cindex Shell slashes
11502 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11503 arguments that contain two trailing slashes:
11505 @example
11506 $ echo / // /// //// .// //.
11507 / / // /// ./ //.
11508 $ x=//
11509 $ eval "echo \$x"
11511 $ set -x
11512 $ echo abc | tr -t ab //
11513 + echo abc
11514 + tr -t ab /
11516 @end example
11518 However, our understanding is that patches are available, so perhaps
11519 it's not worth worrying about working around this horrendous bug.
11521 @node Special Shell Variables
11522 @section Special Shell Variables
11523 @cindex Shell variables
11524 @cindex Special shell variables
11526 Some shell variables should not be used, since they can have a deep
11527 influence on the behavior of the shell.  In order to recover a sane
11528 behavior from the shell, some variables should be unset, but
11529 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11530 fallback value is needed.
11532 As a general rule, shell variable names containing a lower-case letter
11533 are safe; you can define and use these variables without worrying about
11534 their effect on the underlying system, and without worrying about
11535 whether the shell will change them unexpectedly.  (The exception is the
11536 shell variable @code{status}, as described below.)
11538 Here is a list of names that are known to cause trouble.  This list is
11539 not exhaustive, but you should be safe if you avoid the name
11540 @code{status} and names containing only upper-case letters and
11541 underscores.
11543 @c Alphabetical order, case insensitive, `A' before `a'.
11544 @table @code
11545 @item _
11546 Many shells reserve @samp{$_} for various purposes, e.g., the name of
11547 the last command executed.
11549 @item BIN_SH
11550 @evindex BIN_SH
11551 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11552 the standard shell conform to Posix.
11553 Autoconf-generated scripts export this variable when they start up.
11555 @item CDPATH
11556 @evindex CDPATH
11557 When this variable is set it specifies a list of directories to search
11558 when invoking @code{cd} with a relative file name.  Posix
11559 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
11560 is used successfully, @code{cd} prints the resulting absolute
11561 file name.  Unfortunately this output can break idioms like
11562 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
11563 Also, many shells do not conform to this part of Posix; for
11564 example, @command{zsh} prints the result only if a directory name
11565 other than @file{.} was chosen from @env{CDPATH}.
11567 In practice the shells that have this problem also support
11568 @command{unset}, so you can work around the problem as follows:
11570 @example
11571 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
11572 @end example
11574 Autoconf-generated scripts automatically unset @env{CDPATH} if
11575 possible, so you need not worry about this problem in those scripts.
11577 @item DUALCASE
11578 @evindex DUALCASE
11579 In the MKS shell, case statements and file name generation are
11580 case-insensitive unless @env{DUALCASE} is nonzero.
11581 Autoconf-generated scripts export this variable when they start up.
11583 @item ENV
11584 @itemx MAIL
11585 @itemx MAILPATH
11586 @itemx PS1
11587 @itemx PS2
11588 @itemx PS4
11589 @evindex ENV
11590 @evindex MAIL
11591 @evindex MAILPATH
11592 @evindex PS1
11593 @evindex PS2
11594 @evindex PS4
11595 These variables should not matter for shell scripts, since they are
11596 supposed to affect only interactive shells.  However, at least one
11597 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
11598 whether it is interactive, which means that (for example) a @env{PS1}
11599 with a side effect can unexpectedly modify @samp{$?}.  To work around
11600 this bug, Autoconf-generated scripts do something like this:
11602 @example
11603 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
11604 PS1='$ '
11605 PS2='> '
11606 PS4='+ '
11607 @end example
11609 @item IFS
11610 @evindex IFS
11611 Long ago, shell scripts inherited @env{IFS} from the environment,
11612 but this caused many problems so modern shells ignore any environment
11613 settings for @env{IFS}.
11615 Don't set the first character of @code{IFS} to backslash.  Indeed,
11616 Bourne shells use the first character (backslash) when joining the
11617 components in @samp{"$@@"} and some shells then re-interpret (!)@: the
11618 backslash escapes, so you can end up with backspace and other strange
11619 characters.
11621 The proper value for @code{IFS} (in regular code, not when performing
11622 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}.  The first character is
11623 especially important, as it is used to join the arguments in @samp{$*};
11624 however, note that traditional shells, but also bash-2.04, fail to adhere
11625 to this and join with a space anyway.
11627 @item LANG
11628 @itemx LC_ALL
11629 @itemx LC_COLLATE
11630 @itemx LC_CTYPE
11631 @itemx LC_MESSAGES
11632 @itemx LC_MONETARY
11633 @itemx LC_NUMERIC
11634 @itemx LC_TIME
11635 @evindex LANG
11636 @evindex LC_ALL
11637 @evindex LC_COLLATE
11638 @evindex LC_CTYPE
11639 @evindex LC_MESSAGES
11640 @evindex LC_MONETARY
11641 @evindex LC_NUMERIC
11642 @evindex LC_TIME
11644 Autoconf-generated scripts normally set all these variables to
11645 @samp{C} because so much configuration code assumes the C locale and
11646 Posix requires that locale environment variables be set to
11647 @samp{C} if the C locale is desired.  However, some older, nonstandard
11648 systems (notably @acronym{SCO}) break if locale environment variables
11649 are set to @samp{C}, so when running on these systems
11650 Autoconf-generated scripts unset the variables instead.
11652 @item LANGUAGE
11653 @evindex LANGUAGE
11655 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
11656 extension that overrides @env{LC_ALL} in some cases, so
11657 Autoconf-generated scripts set it too.
11659 @item LC_ADDRESS
11660 @itemx LC_IDENTIFICATION
11661 @itemx LC_MEASUREMENT
11662 @itemx LC_NAME
11663 @itemx LC_PAPER
11664 @itemx LC_TELEPHONE
11665 @evindex LC_ADDRESS
11666 @evindex LC_IDENTIFICATION
11667 @evindex LC_MEASUREMENT
11668 @evindex LC_NAME
11669 @evindex LC_PAPER
11670 @evindex LC_TELEPHONE
11672 These locale environment variables are @acronym{GNU} extensions.  They
11673 are treated like their Posix brethren (@env{LC_COLLATE},
11674 etc.)@: as described above.
11676 @item LINENO
11677 Most modern shells provide the current line number in @code{LINENO}.
11678 Its value is the line number of the beginning of the current command.
11679 Autoconf attempts to execute @command{configure} with a modern shell.
11680 If no such shell is available, it attempts to implement @code{LINENO}
11681 with a Sed prepass that replaces each instance of the string
11682 @code{$LINENO} (not followed by an alphanumeric character) with the
11683 line's number.
11685 You should not rely on @code{LINENO} within @command{eval}, as the
11686 behavior differs in practice.  Also, the possibility of the Sed
11687 prepass means that you should not rely on @code{$LINENO} when quoted,
11688 when in here-documents, or when in long commands that cross line
11689 boundaries.  Subshells should be OK, though.  In the following
11690 example, lines 1, 6, and 9 are portable, but the other instances of
11691 @code{LINENO} are not:
11693 @example
11694 @group
11695 $ @kbd{cat lineno}
11696 echo 1. $LINENO
11697 cat <<EOF
11698 3. $LINENO
11699 4. $LINENO
11701 ( echo 6. $LINENO )
11702 eval 'echo 7. $LINENO'
11703 echo 8. '$LINENO'
11704 echo 9. $LINENO '
11705 10.' $LINENO
11706 @end group
11707 @group
11708 $ @kbd{bash-2.05 lineno}
11709 1. 1
11710 3. 2
11711 4. 2
11712 6. 6
11713 7. 1
11714 8. $LINENO
11715 9. 9
11716 10. 9
11717 @end group
11718 @group
11719 $ @kbd{zsh-3.0.6 lineno}
11720 1. 1
11721 3. 2
11722 4. 2
11723 6. 6
11724 7. 7
11725 8. $LINENO
11726 9. 9
11727 10. 9
11728 @end group
11729 @group
11730 $ @kbd{pdksh-5.2.14 lineno}
11731 1. 1
11732 3. 2
11733 4. 2
11734 6. 6
11735 7. 0
11736 8. $LINENO
11737 9. 9
11738 10. 9
11739 @end group
11740 @group
11741 $ @kbd{sed '=' <lineno |}
11742 > @kbd{  sed '}
11743 > @kbd{    N}
11744 > @kbd{    s,$,-,}
11745 > @kbd{    t loop}
11746 > @kbd{    :loop}
11747 > @kbd{    s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
11748 > @kbd{    t loop}
11749 > @kbd{    s,-$,,}
11750 > @kbd{    s,^[0-9]*\n,,}
11751 > @kbd{  ' |}
11752 > @kbd{  sh}
11753 1. 1
11754 3. 3
11755 4. 4
11756 6. 6
11757 7. 7
11758 8. 8
11759 9. 9
11760 10. 10
11761 @end group
11762 @end example
11764 @item NULLCMD
11765 @evindex NULLCMD
11766 When executing the command @samp{>foo}, @command{zsh} executes
11767 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
11768 compatibility mode and the @command{zsh} version is newer
11769 than 3.1.6-dev-18.  If you are using an older @command{zsh}
11770 and forget to set @env{NULLCMD},
11771 your script might be suspended waiting for data on its standard input.
11773 @item PATH_SEPARATOR
11774 @evindex PATH_SEPARATOR
11775 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
11776 variable can be set to either @samp{:} or @samp{;} to control the path
11777 separator Bash uses to set up certain environment variables (such as
11778 @env{PATH}).  You can set this variable to @samp{;} if you want
11779 @command{configure} to use @samp{;} as a separator; this might be useful
11780 if you plan to use non-Posix shells to execute files.  @xref{File System
11781 Conventions}, for more information about @code{PATH_SEPARATOR}.
11783 @item PWD
11784 @evindex PWD
11785 Posix 1003.1-2001 requires that @command{cd} and
11786 @command{pwd} must update the @env{PWD} environment variable to point
11787 to the logical name of the current directory, but traditional shells
11788 do not support this.  This can cause confusion if one shell instance
11789 maintains @env{PWD} but a subsidiary and different shell does not know
11790 about @env{PWD} and executes @command{cd}; in this case @env{PWD} will
11791 point to the wrong directory.  Use @samp{`pwd`} rather than
11792 @samp{$PWD}.
11794 @item RANDOM
11795 Many shells provide @code{RANDOM}, a variable that returns a different
11796 integer each time it is used.  Most of the time, its value does not
11797 change when it is not used, but on @sc{irix} 6.5 the value changes all
11798 the time.  This can be observed by using @command{set}.  It is common
11799 practice to use @code{$RANDOM} as part of a file name, but code
11800 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
11802 @item status
11803 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
11804 hence read-only.  Do not use it.
11805 @end table
11807 @node Limitations of Builtins
11808 @section Limitations of Shell Builtins
11809 @cindex Shell builtins
11810 @cindex Limitations of shell builtins
11812 No, no, we are serious: some shells do have limitations!  :)
11814 You should always keep in mind that any builtin or command may support
11815 options, and therefore have a very different behavior with arguments
11816 starting with a dash.  For instance, the innocent @samp{echo "$word"}
11817 can give unexpected results when @code{word} starts with a dash.  It is
11818 often possible to avoid this problem using @samp{echo "x$word"}, taking
11819 the @samp{x} into account later in the pipe.
11821 @table @asis
11822 @item @command{.}
11823 @prindex @command{.}
11824 Use @command{.} only with regular files (use @samp{test -f}).  Bash
11825 2.03, for instance, chokes on @samp{. /dev/null}.  Also, remember that
11826 @command{.} uses @env{PATH} if its argument contains no slashes, so if
11827 you want to use @command{.} on a file @file{foo} in the current
11828 directory, you must use @samp{. ./foo}.
11830 @item @command{!}
11831 @prindex @command{!}
11832 The Unix version 7 shell did not support
11833 negating the exit status of commands with @command{!}, and this feature
11834 is still absent from more modern shells (e.g., Solaris @command{/bin/sh}).
11835 Shell code like this:
11837 @example
11838 if ! cmp file1 file2 >/dev/null 2>&1; then
11839   echo files differ or trouble
11841 @end example
11843 is therefore not portable in practice.  Typically it is easy to rewrite
11844 such code, e.g.:
11846 @example
11847 cmp file1 file2 >/dev/null 2>&1 ||
11848   echo files differ or trouble
11849 @end example
11851 More generally, one can always rewrite @samp{! @var{command}} as:
11853 @example
11854 if @var{command}; then (exit 1); else :; fi
11855 @end example
11857 @item @command{break}
11858 @c ------------------
11859 @prindex @command{break}
11860 The use of @samp{break 2} etc.@: is safe.
11863 @item @command{case}
11864 @c -----------------
11865 @prindex @command{case}
11866 You don't need to quote the argument; no splitting is performed.
11868 You don't need the final @samp{;;}, but you should use it.
11870 Because of a bug in its @code{fnmatch}, Bash fails to properly
11871 handle backslashes in character classes:
11873 @example
11874 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
11875 bash-2.02$
11876 @end example
11878 @noindent
11879 This is extremely unfortunate, since you are likely to use this code to
11880 handle Posix or @sc{ms-dos} absolute file names.  To work around this
11881 bug, always put the backslash first:
11883 @example
11884 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
11886 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
11888 @end example
11890 Many Bourne shells cannot handle closing brackets in character classes
11891 correctly.
11893 Some shells also have problems with backslash escaping in case you do not want
11894 to match the backslash: both a backslash and the escaped character match this
11895 pattern.  To work around this, specify the character class in a variable, so
11896 that quote removal does not apply afterwards, and the special characters don't
11897 have to be backslash-escaped:
11899 @example
11900 $ @kbd{case '\' in [\<]) echo OK;; esac}
11902 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
11904 @end example
11906 Even with this, Solaris @command{ksh} matches a backslash if the set
11907 contains any
11908 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
11910 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
11911 a closing parenthesis if not specified in a character class:
11913 @example
11914 $ @kbd{case foo in *\)*) echo fail ;; esac}
11915 fail
11916 $ @kbd{case foo in *')'*) echo fail ;; esac}
11917 fail
11918 @end example
11920 Some shells, such as Ash 0.3.8, are confused by an empty
11921 @code{case}/@code{esac}:
11923 @example
11924 ash-0.3.8 $ @kbd{case foo in esac;}
11925 @error{}Syntax error: ";" unexpected (expecting ")")
11926 @end example
11928 Many shells still do not support parenthesized cases, which is a pity
11929 for those of us using tools that rely on balanced parentheses.  For
11930 instance, Solaris @command{/bin/sh}:
11932 @example
11933 $ @kbd{case foo in (foo) echo foo;; esac}
11934 @error{}syntax error: `(' unexpected
11935 @end example
11938 @item @command{cd}
11939 @c ---------------
11940 @prindex @command{cd}
11941 Posix 1003.1-2001 requires that @command{cd} must support
11942 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
11943 with @option{-L} being the default.  However, traditional shells do
11944 not support these options, and their @command{cd} command has the
11945 @option{-P} behavior.
11947 Portable scripts should assume neither option is supported, and should
11948 assume neither behavior is the default.  This can be a bit tricky,
11949 since the Posix default behavior means that, for example,
11950 @samp{ls ..} and @samp{cd ..} may refer to different directories if
11951 the current logical directory is a symbolic link.  It is safe to use
11952 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
11953 Also, Autoconf-generated scripts check for this problem when computing
11954 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
11955 so it is safe to @command{cd} to these variables.
11957 Also please see the discussion of the @command{pwd} command.
11960 @item @command{echo}
11961 @c -----------------
11962 @prindex @command{echo}
11963 The simple @command{echo} is probably the most surprising source of
11964 portability troubles.  It is not possible to use @samp{echo} portably
11965 unless both options and escape sequences are omitted.  New applications
11966 which are not aiming at portability should use @samp{printf} instead of
11967 @samp{echo}.
11969 Don't expect any option.  @xref{Preset Output Variables}, @code{ECHO_N}
11970 etc.@: for a means to simulate @option{-n}.
11972 Do not use backslashes in the arguments, as there is no consensus on
11973 their handling.  On @samp{echo '\n' | wc -l}, the @command{sh} of
11974 Digital Unix 4.0 and @acronym{MIPS RISC/OS} 4.52, answer 2, but the Solaris
11975 @command{/bin/sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
11976 Please note that the problem is truly @command{echo}: all the shells
11977 understand @samp{'\n'} as the string composed of a backslash and an
11978 @samp{n}.
11980 Because of these problems, do not pass a string containing arbitrary
11981 characters to @command{echo}.  For example, @samp{echo "$foo"} is safe
11982 if you know that @var{foo}'s value cannot contain backslashes and cannot
11983 start with @samp{-}, but otherwise you should use a here-document like
11984 this:
11986 @example
11987 cat <<EOF
11988 $foo
11990 @end example
11993 @item @command{eval}
11994 @c -----------------
11995 @prindex @command{eval}
11996 The @command{eval} command is useful in limited circumstances, e.g.,
11997 using commands like @samp{eval table_$key=\$value} and @samp{eval
11998 value=table_$key} to simulate a hash table when the key is known to be
11999 alphanumeric.  However, @command{eval} is tricky to use on arbitrary
12000 arguments, even when it is implemented correctly.
12002 It is obviously unwise to use @samp{eval $cmd} if the string value of
12003 @samp{cmd} was derived from an untrustworthy source.  But even if the
12004 string value is valid, @samp{eval $cmd} might not work as intended,
12005 since it causes field splitting and file name expansion to occur twice,
12006 once for the @command{eval} and once for the command itself.  It is
12007 therefore safer to use @samp{eval "$cmd"}.  For example, if @var{cmd}
12008 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12009 equivalent of @samp{cat test;.c} if there happens to be a file named
12010 @file{test;.c} in the current directory; and this in turn will
12011 mistakenly attempt to invoke @command{cat} on the file @file{test} and
12012 then execute the command @command{.c}.  To avoid this problem, use
12013 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12015 However, suppose that you want to output the text of the evaluated
12016 command just before executing it.  Assuming the previous example,
12017 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12018 this output doesn't show the user that @samp{test;.c} is the actual name
12019 of the copied file.  Conversely, @samp{eval "echo Executing: $cmd"} will
12020 work on this example, but it will fail with @samp{cmd='cat foo >bar'},
12021 since it will mistakenly replace the contents of @file{bar} by the
12022 string @samp{cat foo}.  No simple, general, and portable solution to
12023 this problem is known.
12025 You should also be wary of common bugs in @command{eval} implementations.
12026 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12027 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12028 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12029 @samp{$?} is 0, so they exhibit behavior like this:
12031 @example
12032 $ false; eval 'echo $?'
12034 @end example
12036 The correct behavior here is to output a nonzero value,
12037 but portable scripts should not rely on this.
12039 You should not rely on @code{LINENO} within @command{eval}.
12040 @xref{Special Shell Variables}.
12042 @item @command{exit}
12043 @c -----------------
12044 @prindex @command{exit}
12045 The default value of @command{exit} is supposed to be @code{$?};
12046 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12047 perform @samp{exit 0}.
12049 @example
12050 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12051 fail
12052 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12053 fail
12054 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12055 bash-2.04$
12056 @end example
12058 Using @samp{exit $?} restores the expected behavior.
12060 Some shell scripts, such as those generated by @command{autoconf}, use a
12061 trap to clean up before exiting.  If the last shell command exited with
12062 nonzero status, the trap also exits with nonzero status so that the
12063 invoker can tell that an error occurred.
12065 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12066 trap ignores the @code{exit} command's argument.  In these shells, a trap
12067 cannot determine whether it was invoked by plain @code{exit} or by
12068 @code{exit 1}.  Instead of calling @code{exit} directly, use the
12069 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12072 @item @command{export}
12073 @c -------------------
12074 @prindex @command{export}
12075 The builtin @command{export} dubs a shell variable @dfn{environment
12076 variable}.  Each update of exported variables corresponds to an update
12077 of the environment variables.  Conversely, each environment variable
12078 received by the shell when it is launched should be imported as a shell
12079 variable marked as exported.
12081 Alas, many shells, such as Solaris @command{/bin/sh},
12082 @sc{irix} 6.3, @sc{irix} 5.2,
12083 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12084 @command{export} the environment variables they receive.  As a result,
12085 two variables coexist: the environment variable and the shell
12086 variable.  The following code demonstrates this failure:
12088 @example
12089 #!/bin/sh
12090 echo $FOO
12091 FOO=bar
12092 echo $FOO
12093 exec /bin/sh $0
12094 @end example
12096 @noindent
12097 when run with @samp{FOO=foo} in the environment, these shells will print
12098 alternately @samp{foo} and @samp{bar}, although it should only print
12099 @samp{foo} and then a sequence of @samp{bar}s.
12101 Therefore you should @command{export} again each environment variable
12102 that you update.
12105 @item @command{false}
12106 @c ------------------
12107 @prindex @command{false}
12108 Don't expect @command{false} to exit with status 1: in native
12109 Solaris it exits with status 255.
12112 @item @command{for}
12113 @c ----------------
12114 @prindex @command{for}
12115 To loop over positional arguments, use:
12117 @example
12118 for arg
12120   echo "$arg"
12121 done
12122 @end example
12124 @noindent
12125 You may @emph{not} leave the @code{do} on the same line as @code{for},
12126 since some shells improperly grok:
12128 @example
12129 for arg; do
12130   echo "$arg"
12131 done
12132 @end example
12134 If you want to explicitly refer to the positional arguments, given the
12135 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12137 @example
12138 for arg in $@{1+"$@@"@}; do
12139   echo "$arg"
12140 done
12141 @end example
12143 @noindent
12144 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12145 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12146 item @samp{$@@}, for more.
12149 @item @command{if}
12150 @c ---------------
12151 @prindex @command{if}
12152 Using @samp{!} is not portable.  Instead of:
12154 @example
12155 if ! cmp -s file file.new; then
12156   mv file.new file
12158 @end example
12160 @noindent
12161 use:
12163 @example
12164 if cmp -s file file.new; then :; else
12165   mv file.new file
12167 @end example
12169 There are shells that do not reset the exit status from an @command{if}:
12171 @example
12172 $ @kbd{if (exit 42); then true; fi; echo $?}
12174 @end example
12176 @noindent
12177 whereas a proper shell should have printed @samp{0}.  This is especially
12178 bad in Makefiles since it produces false failures.  This is why properly
12179 written Makefiles, such as Automake's, have such hairy constructs:
12181 @example
12182 if test -f "$file"; then
12183   install "$file" "$dest"
12184 else
12185   :
12187 @end example
12190 @item @command{printf}
12191 @c ------------------
12192 @prindex @command{printf}
12193 A format string starting with a @samp{-} can cause problems.
12194 Bash (e.g., 2.05b) will interpret it as an options string and
12195 give an error.  And @samp{--} to mark the end of options is not good
12196 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which will take that
12197 literally as the format string.  Putting the @samp{-} in a @samp{%c}
12198 or @samp{%s} is probably the easiest way to avoid doubt,
12200 @example
12201 printf %s -foo
12202 @end example
12205 @item @command{read}
12206 @c ------------------
12207 @prindex @command{read}
12208 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12211 @item @command{pwd}
12212 @c ----------------
12213 @prindex @command{pwd}
12214 With modern shells, plain @command{pwd} outputs a ``logical''
12215 directory name, some of whose components may be symbolic links.  These
12216 directory names are in contrast to ``physical'' directory names, whose
12217 components are all directories.
12219 Posix 1003.1-2001 requires that @command{pwd} must support
12220 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12221 with @option{-L} being the default.  However, traditional shells do
12222 not support these options, and their @command{pwd} command has the
12223 @option{-P} behavior.
12225 Portable scripts should assume neither option is supported, and should
12226 assume neither behavior is the default.  Also, on many hosts
12227 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12228 does not require this behavior and portable scripts should not rely on
12231 Typically it's best to use plain @command{pwd}.  On modern hosts this
12232 outputs logical directory names, which have the following advantages:
12234 @itemize @bullet
12235 @item
12236 Logical names are what the user specified.
12237 @item
12238 Physical names may not be portable from one installation
12239 host to another due to network file system gymnastics.
12240 @item
12241 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12242 some parent directory, but plain @command{pwd} cannot fail for this
12243 reason.
12244 @end itemize
12246 Also please see the discussion of the @command{cd} command.
12249 @item @command{set}
12250 @c ----------------
12251 @prindex @command{set}
12252 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12253 any options) does not sort its output.
12255 The @command{set} builtin faces the usual problem with arguments starting with a
12256 dash.  Modern shells such as Bash or Zsh understand @option{--} to specify
12257 the end of the options (any argument after @option{--} is a parameter,
12258 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12259 10 @command{/bin/sh}) simply stop option
12260 processing as soon as a non-option argument is found.  Therefore, use
12261 @samp{dummy} or simply @samp{x} to end the option processing, and use
12262 @command{shift} to pop it out:
12264 @example
12265 set x $my_list; shift
12266 @end example
12268 Avoid @samp{set -}, e.g., @samp{set - $my_list}.  Posix no
12269 longer requires support for this command, and in traditional shells
12270 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12271 makes scripts harder to debug.
12273 Some nonstandard shells do not recognize more than one option
12274 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line).  It is
12275 better to combine them:
12277 @example
12278 set -ex
12279 @end example
12281 The @acronym{BSD} shell has had several problems with the @option{-e}
12282 option, partly because @acronym{BSD} @command{make} traditionally used
12283 @option{-e} even though this was incompatible with Posix
12284 (@pxref{Limitations of Make}).  Older versions of the @acronym{BSD}
12285 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12286 @samp{case} when @option{-e} was in effect, causing the shell to exit
12287 unexpectedly in some cases.  This was particularly a problem with
12288 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12289 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12290 wrapper works around the bug.
12292 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12293 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12294 @samp{&&} fails inside a compound statement.  For example:
12296 @example
12297 #! /bin/sh
12298 set -e
12299 foo=''
12300 test -n "$foo" && exit 1
12301 echo one
12302 if :; then
12303   test -n "$foo" && exit 1
12305 echo two
12306 @end example
12308 @noindent
12309 does not print @samp{two}.  One workaround is to use @samp{if test -n
12310 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12311 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12314 @item @command{shift}
12315 @c ------------------
12316 @prindex @command{shift}
12317 Not only is @command{shift}ing a bad idea when there is nothing left to
12318 shift, but in addition it is not portable: the shell of @acronym{MIPS
12319 RISC/OS} 4.52 refuses to do it.
12321 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12322 and it is also absent in many pre-Posix shells.
12325 @item @command{source}
12326 @c -------------------
12327 @prindex @command{source}
12328 This command is not portable, as Posix does not require it; use
12329 @command{.} instead.
12332 @item @command{test}
12333 @c -----------------
12334 @prindex @command{test}
12335 The @code{test} program is the way to perform many file and string
12336 tests.  It is often invoked by the alternate name @samp{[}, but using
12337 that name in Autoconf code is asking for trouble since it is an M4 quote
12338 character.
12340 If you need to make multiple checks using @code{test}, combine them with
12341 the shell operators @samp{&&} and @samp{||} instead of using the
12342 @code{test} operators @option{-a} and @option{-o}.  On System V, the
12343 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12344 operators; consequently, Posix does not specify them, so using them
12345 is nonportable.  If you combine @samp{&&} and @samp{||} in the same
12346 statement, keep in mind that they have equal precedence.
12348 It is safe to use @samp{!} as a @command{test} operator.  For example,
12349 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12350 -d foo; @dots{}} is not.
12353 @item @command{test} (files)
12354 @c -------------------------
12355 To enable @command{configure} scripts to support cross-compilation, they
12356 shouldn't do anything that tests features of the build system instead of
12357 the host system.  But occasionally you may find it necessary to check
12358 whether some arbitrary file exists.  To do so, use @samp{test -f} or
12359 @samp{test -r}.  Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12360 have it.  Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12361 lacks it.  To test for symbolic links on systems that have them, use
12362 @samp{test -h} rather than @samp{test -L}; either form conforms to
12363 Posix 1003.1-2001, but older shells like Solaris 8
12364 @code{/bin/sh} support only @option{-h}.
12366 @item @command{test} (strings)
12367 @c ---------------------------
12368 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12369 start with a dash, since @code{test} might interpret its argument as an
12370 option (e.g., @samp{@var{string} = "-n"}).
12372 Contrary to a common belief, @samp{test -n @var{string}} and
12373 @samp{test -z @var{string}} @strong{are} portable.  Nevertheless many
12374 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12375 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12376 @var{string} looks like an operator:
12378 @example
12379 $ @kbd{test -n =}
12380 test: argument expected
12381 @end example
12383 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12384 "x@var{string}" != x} instead.
12386 It is common to find variations of the following idiom:
12388 @example
12389 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12390   @var{action}
12391 @end example
12393 @noindent
12394 to take an action when a token matches a given pattern.  Such constructs
12395 should always be avoided by using:
12397 @example
12398 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12399   @var{action}
12400 @end example
12402 @noindent
12403 Use @code{case} where possible since it is faster, being a shell builtin:
12406 @example
12407 case $ac_feature in
12408   *[!-a-zA-Z0-9_]*) @var{action};;
12409 esac
12410 @end example
12412 Alas, negated character classes are probably not portable, although no
12413 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12414 (when in interactive mode, @command{zsh} is confused by the
12415 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12416 @samp{!}).  Many shells do not support the alternative syntax
12417 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12419 One solution can be:
12421 @example
12422 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12423   @var{action}
12424 @end example
12426 @noindent
12427 or better yet
12429 @example
12430 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12431   @var{action}
12432 @end example
12434 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12435 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12436 @samp{@var{foo}} contains backslashes.
12439 @item @command{trap}
12440 @c -----------------
12441 @prindex @command{trap}
12442 It is safe to trap at least the signals 1, 2, 13, and 15.  You can also
12443 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12444 explicit @command{exit}, or the end of the script).
12446 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12447 specified signals to their default values, but many common shells (e.g.,
12448 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12449 ``command'' named @command{-} when the specified conditions arise.
12450 There is no portable workaround, except for @samp{trap - 0}, for which
12451 @samp{trap '' 0} is a portable substitute.
12453 Although Posix is not absolutely clear on this point, it is widely
12454 admitted that when entering the trap @samp{$?} should be set to the exit
12455 status of the last command run before the trap.  The ambiguity can be
12456 summarized as: ``when the trap is launched by an @command{exit}, what is
12457 the @emph{last} command run: that before @command{exit}, or
12458 @command{exit} itself?''
12460 Bash considers @command{exit} to be the last command, while Zsh and
12461 Solaris @command{/bin/sh} consider that when the trap is run it is
12462 @emph{still} in the @command{exit}, hence it is the previous exit status
12463 that the trap receives:
12465 @example
12466 $ @kbd{cat trap.sh}
12467 trap 'echo $?' 0
12468 (exit 42); exit 0
12469 $ @kbd{zsh trap.sh}
12471 $ @kbd{bash trap.sh}
12473 @end example
12475 The portable solution is then simple: when you want to @samp{exit 42},
12476 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12477 set the exit status to 42 for Zsh, and the second to trigger the trap
12478 and pass 42 as exit status for Bash.
12480 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12481 reset to 0 by empty lines if the code is inside @command{trap}.
12483 @example
12484 $ @kbd{trap 'false}
12486 echo $?' 0
12487 $ @kbd{exit}
12489 @end example
12491 @noindent
12492 Fortunately, this bug only affects @command{trap}.
12494 @item @command{true}
12495 @c -----------------
12496 @prindex @command{true}
12497 @c Info cannot handle `:' in index entries.
12498 @c @prindex @command{:}
12499 Don't worry: as far as we know @command{true} is portable.
12500 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12501 portable shell community tends to prefer using @command{:}.  This has a
12502 funny side effect: when asked whether @command{false} is more portable
12503 than @command{true} Alexandre Oliva answered:
12505 @quotation
12506 In a sense, yes, because if it doesn't exist, the shell will produce an
12507 exit status of failure, which is correct for @command{false}, but not
12508 for @command{true}.
12509 @end quotation
12512 @item @command{unset}
12513 @c ------------------
12514 @prindex @command{unset}
12515 You cannot assume the support of @command{unset}.  Nevertheless, because
12516 it is extremely useful to disable embarrassing variables such as
12517 @code{PS1}, you can test for its existence and use
12518 it @emph{provided} you give a neutralizing value when @command{unset} is
12519 not supported:
12521 @example
12522 if (unset FOO) >/dev/null 2>&1; then
12523   unset=unset
12524 else
12525   unset=false
12527 $unset PS1 || PS1='$ '
12528 @end example
12530 @xref{Special Shell Variables}, for some neutralizing values.  Also, see
12531 @ref{Limitations of Builtins}, documentation of @command{export}, for
12532 the case of environment variables.
12533 @end table
12535 @node Limitations of Usual Tools
12536 @section Limitations of Usual Tools
12537 @cindex Limitations of usual tools
12539 The small set of tools you can expect to find on any machine can still
12540 include some limitations you should be aware of.
12542 @table @asis
12543 @item Awk
12544 @c ----------------
12545 @prindex Awk
12546 Don't leave white space before the opening parenthesis in a user function call.
12547 Posix does not allow this and @acronym{GNU} Awk rejects it:
12549 @example
12550 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
12551         BEGIN @{ die () @}'}
12552 gawk: cmd. line:2:         BEGIN @{ die () @}
12553 gawk: cmd. line:2:                      ^ parse error
12554 $ @kbd{gawk 'function die () @{ print "Aaaaarg!"  @}
12555         BEGIN @{ die() @}'}
12556 Aaaaarg!
12557 @end example
12559 If you want your program to be deterministic, don't depend on @code{for}
12560 on arrays:
12562 @example
12563 $ @kbd{cat for.awk}
12564 END @{
12565   arr["foo"] = 1
12566   arr["bar"] = 1
12567   for (i in arr)
12568     print i
12570 $ @kbd{gawk -f for.awk </dev/null}
12573 $ @kbd{nawk -f for.awk </dev/null}
12576 @end example
12578 Some Awk implementations, such as HP-UX 11.0's native one, mishandle anchors:
12580 @example
12581 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
12582 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
12584 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
12585 xfoo
12586 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
12588 @end example
12590 @noindent
12591 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
12592 or use a simple test to reject such implementations.
12594 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the the
12595 length of regular expressions and literal strings in an Awk program.
12597 Traditional Awk implementations derived from Unix version 7, such as
12598 Solaris @command{/bin/awk}, have many limitations and do not
12599 conform to Posix.  Nowadays @code{AC_PROG_AWK} (@pxref{Particular
12600 Programs}) will find you an Awk that doesn't have these problems, but if
12601 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
12602 address them.
12604 Traditional Awk does not support multidimensional arrays or user-defined
12605 functions.
12607 Traditional Awk does not support the @option{-v} option.  You can use
12608 assignments after the program instead, e.g., @command{$AWK '@{print v
12609 $1@}' v=x}; however, don't forget that such assignments are not
12610 evaluated until they are encountered (e.g., after any @code{BEGIN}
12611 action).
12613 Traditional Awk does not support the keywords @code{delete} or @code{do}.
12615 Traditional Awk does not support the expressions
12616 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
12617 or @code{@var{a}^=@var{b}}.
12619 Traditional Awk does not support the predefined @code{CONVFMT} variable.
12621 Traditional Awk supports only the predefined functions @code{exp},
12622 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
12623 @code{sqrt}, and @code{substr}.
12625 Traditional Awk @code{getline} is not at all compatible with Posix;
12626 avoid it.
12628 Traditional Awk @code{split} supports only two arguments.
12630 Traditional Awk has a limit of 99
12631 fields in a record.  You may be able to circumvent this problem by using
12632 @code{split}.
12635 @item @command{basename}
12636 @c ---------------------
12637 @prindex @command{basename}
12638 Not all hosts have a working @command{basename}.
12639 You can use @command{expr} instead.
12641 @c AS_BASENAME is to be replaced by a better API.
12642 @ignore
12643 Not all hosts have a working @command{basename}, and you should instead
12644 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
12645 @command{expr} if you need to strip a suffix.  For example:
12647 @example
12648 a=`basename "$aname"`       # This is not portable.
12649 a=`AS_BASENAME(["$aname"])` # This is more portable.
12651 # This is not portable.
12652 c=`basename "$cname" .c`
12654 # This is more portable.
12655 c=`AS_BASENAME(["$cname"])`
12656 case $c in
12657 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
12658 esac
12659 @end example
12660 @end ignore
12663 @item @command{cat}
12664 @c ----------------
12665 @prindex @command{cat}
12666 Don't rely on any option.
12669 @item @command{cc}
12670 @c ---------------
12671 @prindex @command{cc}
12672 The command @samp{cc -c foo.c} traditionally produces an object file
12673 named @file{foo.o}.  Most compilers allow @option{-c} to be combined
12674 with @option{-o} to specify a different object file name, but
12675 Posix does not require this combination and a few compilers
12676 lack support for it.  @xref{C Compiler}, for how @acronym{GNU} Make
12677 tests for this feature with @code{AC_PROG_CC_C_O}.
12679 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
12680 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
12682 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
12683 assemble.  @samp{cc -c foo.S} will appear to succeed, but in fact does
12684 nothing.
12686 The default executable, produced by @samp{cc foo.c}, can be
12688 @itemize
12689 @item @file{a.out} --- usual Posix convention.
12690 @item @file{b.out} --- i960 compilers (including @command{gcc}).
12691 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
12692 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
12693 @item @file{foo.exe} --- various MS-DOS compilers.
12694 @end itemize
12696 The C compiler's traditional name is @command{cc}, but other names like
12697 @command{gcc} are common.  Posix 1003.1-2001 specifies the
12698 name @command{c99}, but older Posix editions specified
12699 @command{c89} and anyway these standard names are rarely used in
12700 practice.  Typically the C compiler is invoked from makefiles that use
12701 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
12702 compiler name.
12705 @item @command{chmod}
12706 @c ------------------
12707 @prindex @command{chmod}
12708 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
12709 instead, for two reasons.  First, plain @option{-w} does not necessarily
12710 make the file unwritable, since it does not affect mode bits that
12711 correspond to bits in the file mode creation mask.  Second,
12712 Posix says that the @option{-w} might be interpreted as an
12713 implementation-specific option, not as a mode; Posix suggests
12714 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
12715 @samp{--} does not work on some older hosts.
12718 @item @command{cmp}
12719 @c ----------------
12720 @prindex @command{cmp}
12721 @command{cmp} performs a raw data comparison of two files, while
12722 @command{diff} compares two text files.  Therefore, if you might compare
12723 DOS files, even if only checking whether two files are different, use
12724 @command{diff} to avoid spurious differences due to differences of
12725 newline encoding.
12728 @item @command{cp}
12729 @c ---------------
12730 @prindex @command{cp}
12731 Avoid the @option{-r} option, since its behavior is not specified by
12732 Posix.  Use @option{-R} instead.  On @acronym{GNU} hosts the two options
12733 are equivalent, but on Solaris hosts (for example) @command{cp -r}
12734 reads from pipes instead of replicating them.
12736 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
12737 trailing slashes at the end of nonexistent destination directories.  To
12738 avoid this problem, omit the trailing slashes.  For example, use
12739 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
12740 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
12742 @c This is thanks to Ian.
12743 SunOS 4 @command{cp} does not support @option{-f}, although its
12744 @command{mv} does.  It's possible to deduce why @command{mv} and
12745 @command{cp} are different with respect to @option{-f}.  @command{mv}
12746 prompts by default before overwriting a read-only file.  @command{cp}
12747 does not.  Therefore, @command{mv} requires a @option{-f} option, but
12748 @command{cp} does not.  @command{mv} and @command{cp} behave differently
12749 with respect to read-only files because the simplest form of
12750 @command{cp} cannot overwrite a read-only file, but the simplest form of
12751 @command{mv} can.  This is because @command{cp} opens the target for
12752 write access, whereas @command{mv} simply calls @code{link} (or, in
12753 newer systems, @code{rename}).
12754 @c Ian said: ``I don't think -p or -r are portable''!!! How can you live
12755 @c without -r???
12757 @cindex timestamp resolution
12758 Traditionally, file timestamps had 1-second resolution, and @samp{cp
12759 -p} copied the timestamps exactly.  However, many modern file systems
12760 have timestamps with 1-nanosecond resolution.  Unfortunately, @samp{cp
12761 -p} implementations truncate timestamps when copying files, so this
12762 can result in the destination file appearing to be older than the
12763 source.  The exact amount of truncation depends on the resolution of
12764 the system calls that @command{cp} uses; traditionally this was
12765 @code{utime}, which has 1-second resolution, but some newer
12766 @command{cp} implementations use @code{utimes}, which has
12767 1-microsecond resolution.  These newer implementations include @acronym{GNU}
12768 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
12769 later.  Unfortunately as of January 2006 there is still no system
12770 call to set time stamps to the full nanosecond resolution.
12772 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
12773 ownerships.  But whether it actually does copy ownerships or not is a
12774 system dependent policy decision implemented by the kernel.  If the
12775 kernel allows it then it happens.  If the kernel does not allow it then
12776 it does not happen.  It is not something @command{cp} itself has control
12777 over.
12779 In Unix System V any user can chown files to any other user, and System
12780 V also has a non-sticky @file{/tmp}.  That probably derives from the
12781 heritage of System V in a business environment without hostile users.
12782 @acronym{BSD} changed this
12783 to be a more secure model where only root can @command{chown} files and
12784 a sticky @file{/tmp} is used.  That undoubtedly derives from the heritage
12785 of @acronym{BSD} in a campus environment.
12787 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
12788 can be configured to allow a System V style @command{chown}.  On the
12789 other hand, @acronym{HP-UX} follows System V, but can
12790 be configured to use the modern security model and disallow
12791 @command{chown}.  Since it is an administrator-configurable parameter
12792 you can't use the name of the kernel as an indicator of the behavior.
12796 @item @command{date}
12797 @c -----------------
12798 @prindex @command{date}
12799 Some versions of @command{date} do not recognize special % directives,
12800 and unfortunately, instead of complaining, they just pass them through,
12801 and exit with success:
12803 @example
12804 $ @kbd{uname -a}
12805 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
12806 $ @kbd{date "+%s"}
12808 @end example
12811 @item @command{diff}
12812 @c -----------------
12813 @prindex @command{diff}
12814 Option @option{-u} is nonportable.
12816 Some implementations, such as Tru64's, fail when comparing to
12817 @file{/dev/null}.  Use an empty file instead.
12820 @item @command{dirname}
12821 @c --------------------
12822 @prindex @command{dirname}
12823 Not all hosts have a working @command{dirname}, and you should instead
12824 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}).  For example:
12826 @example
12827 dir=`dirname "$file"`       # This is not portable.
12828 dir=`AS_DIRNAME(["$file"])` # This is more portable.
12829 @end example
12832 @item @command{egrep}
12833 @c ------------------
12834 @prindex @command{egrep}
12835 Posix 1003.1-2001 no longer requires @command{egrep},
12836 but many older hosts do not yet support the Posix
12837 replacement @code{grep -E}.  Also, some traditional implementations do
12838 not work on long input lines.  To work around these problems, invoke
12839 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
12841 Portable extended regular expressions should use @samp{\} only to escape
12842 characters in the string @samp{$()*+.?[\^@{|}.  For example, @samp{\@}}
12843 is not portable, even though it typically matches @samp{@}}.
12845 The empty alternative is not portable.  Use @samp{?} instead.  For
12846 instance with Digital Unix v5.0:
12848 @example
12849 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
12850 |foo
12851 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
12852 bar|
12853 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
12855 |bar
12856 @end example
12858 @command{$EGREP} also suffers the limitations of @command{grep}.
12860 @item @command{expr}
12861 @c -----------------
12862 @prindex @command{expr}
12863 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
12864 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
12865 misinterpreting @var{word}.
12867 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
12869 @item @command{expr} (@samp{|})
12870 @prindex @command{expr} (@samp{|})
12871 You can use @samp{|}.  Although Posix does require that @samp{expr
12872 ''} return the empty string, it does not specify the result when you
12873 @samp{|} together the empty string (or zero) with the empty string.  For
12874 example:
12876 @example
12877 expr '' \| ''
12878 @end example
12880 Posix 1003.2-1992 returns the empty string
12881 for this case, but traditional Unix returns @samp{0} (Solaris is
12882 one such example).  In Posix 1003.1-2001, the specification was
12883 changed to match traditional Unix's behavior (which is
12884 bizarre, but it's too late to fix this).  Please note that the same
12885 problem does arise when the empty string results from a computation,
12886 as in:
12888 @example
12889 expr bar : foo \| foo : bar
12890 @end example
12892 @noindent
12893 Avoid this portability problem by avoiding the empty string.
12896 @item @command{expr} (@samp{:})
12897 @c ----------------------------
12898 @prindex @command{expr}
12899 Portable @command{expr} regular expressions should use @samp{\} to
12900 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
12901 For example, alternation, @samp{\|}, is common but Posix does not
12902 require its support, so it should be avoided in portable scripts.
12903 Similarly, @samp{\+} and @samp{\?} should be avoided.
12905 Portable @command{expr} regular expressions should not begin with
12906 @samp{^}.  Patterns are automatically anchored so leading @samp{^} is
12907 not needed anyway.
12909 The Posix standard is ambiguous as to whether
12910 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
12911 In practice, it outputs the empty string on most platforms, but portable
12912 scripts should not assume this.  For instance, the @acronym{QNX} 4.25 native
12913 @command{expr} returns @samp{0}.
12915 One might think that a way to get a uniform behavior would be to use
12916 the empty string as a default value:
12918 @example
12919 expr a : '\(b\)' \| ''
12920 @end example
12922 @noindent
12923 Unfortunately this behaves exactly as the original expression; see the
12924 @samp{@command{expr} (@samp{|})} entry for more information.
12926 Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
12927 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
12928 @command{expr} to fail if the matched substring is longer than 120
12929 bytes.  In this case, you might want to fall back on @samp{echo|sed} if
12930 @command{expr} fails.
12932 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
12933 some cases.  For example, the command
12934 @example
12935 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
12936 @end example
12938 @noindent
12939 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
12940 This particular case can be worked around by substituting @samp{[^--]}
12941 for @samp{[^-]}.
12943 Don't leave, there is some more!
12945 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
12946 the empty string, has a funny behavior in its exit status: it's always 1
12947 when parentheses are used!
12949 @example
12950 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
12951 0: 1
12952 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
12953 1: 0
12955 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
12956 1: a
12957 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
12958 1: 0
12959 @end example
12961 @noindent
12962 In practice this can be a big problem if you are ready to catch failures
12963 of @command{expr} programs with some other method (such as using
12964 @command{sed}), since you may get twice the result.  For instance
12966 @example
12967 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
12968 @end example
12970 @noindent
12971 will output @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25.  A
12972 simple workaround consists in testing @command{expr} and use a variable
12973 set to @command{expr} or to @command{false} according to the result.
12975 Tru64 @command{expr} incorrectly treats the result as a number, if it
12976 can be interpreted that way:
12978 @example
12979 $ @kbd{expr 00001 : '.*\(...\)'}
12981 @end example
12984 @item @command{fgrep}
12985 @c ------------------
12986 @prindex @command{fgrep}
12987 Posix 1003.1-2001 no longer requires @command{fgrep},
12988 but many older hosts do not yet support the Posix
12989 replacement @code{grep -F}.  Also, some traditional implementations do
12990 not work on long input lines.  To work around these problems, invoke
12991 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
12994 @item @command{find}
12995 @c -----------------
12996 @prindex @command{find}
12997 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
12998 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
12999 commands do not understand it.
13001 The replacement of @samp{@{@}} is guaranteed only if the argument is
13002 exactly @emph{@{@}}, not if it's only a part of an argument.  For
13003 instance on DU, and HP-UX 10.20 and HP-UX 11:
13005 @example
13006 $ @kbd{touch foo}
13007 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13008 @{@}-@{@}
13009 @end example
13011 @noindent
13012 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13015 @item @command{grep}
13016 @c -----------------
13017 @prindex @command{grep}
13018 Portable scripts can rely on the @command{grep} options @option{-c},
13019 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13020 options.  For example, don't use @option{-w}, as Posix does not require
13021 it and Irix 6.5.16m's @command{grep} does not support it.  Also,
13022 portable scripts should not combine @option{-c} with @option{-l},
13023 as Posix does not allow this.
13025 Some of the options required by Posix are not portable in practice.
13026 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13027 implementations (e.g., Solaris) do not support @option{-q}.
13028 Don't use @samp{grep -s} to suppress output either, because Posix
13029 says @option{-s} does not suppress output, only some error messages;
13030 also, the @option{-s} option of traditional @command{grep} behaved
13031 like @option{-q} does in most modern implementations.  Instead,
13032 redirect the standard output and standard error (in case the file
13033 doesn't exist) of @code{grep} to @file{/dev/null}.  Check the exit
13034 status of @code{grep} to determine whether it found a match.
13036 Some traditional @command{grep} implementations do not work on long
13037 input lines.  On AIX the default @code{grep} silently truncates long
13038 lines on the input before matching.
13040 Also, many implementations do not support multiple regexps
13041 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13042 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT).  To
13043 work around these problems, invoke @code{AC_PROG_GREP} and then use
13044 @code{$GREP}.
13046 Another possible workaround for the multiple @option{-e} problem is to
13047 separate the patterns by newlines, for example:
13049 @example
13050 grep 'foo
13051 bar' in.txt
13052 @end example
13054 @noindent
13055 except that this will fail with traditional @command{grep}
13056 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13058 Traditional @command{grep} implementations (e.g., Solaris) do not
13059 support the @option{-E} or @option{-F} options.  To work around these
13060 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13061 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}.  Even if you are
13062 willing to require support for Posix @command{grep}, your script should
13063 not use both @option{-E} and @option{-F}, since Posix does not allow
13064 this combination.
13066 Portable @command{grep} regular expressions should use @samp{\} only to
13067 escape characters in the string @samp{$()*.0123456789[\^@{@}}.  For example,
13068 alternation, @samp{\|}, is common but Posix does not require its
13069 support in basic regular expressions, so it should be avoided in
13070 portable scripts.  Solaris @command{grep} does not support it.
13071 Similarly, @samp{\+} and @samp{\?} should be avoided.
13074 @item @command{join}
13075 @c -----------------
13076 @prindex @command{join}
13077 Solaris 8 @command{join} has bugs when the second operand is standard
13078 input, and when standard input is a pipe.  For example, the following
13079 shell script causes Solaris 8 @command{join} to loop forever:
13081 @example
13082 cat >file <<'EOF'
13083 1 x
13084 2 y
13086 cat file | join file -
13087 @end example
13089 Use @samp{join - file} instead.
13092 @item @command{ln}
13093 @c ---------------
13094 @prindex @command{ln}
13095 @cindex Symbolic links
13096 Don't rely on @command{ln} having a @option{-f} option.  Symbolic links
13097 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13099 For versions of the @acronym{DJGPP} before 2.04,
13100 @command{ln} emulates symbolic links
13101 to executables by generating a stub that in turn calls the real
13102 program.  This feature also works with nonexistent files like in the
13103 Posix spec.  So @samp{ln -s file link} will generate @file{link.exe},
13104 which will attempt to call @file{file.exe} if run.  But this feature only
13105 works for executables, so @samp{cp -p} is used instead for these
13106 systems.  @acronym{DJGPP} versions 2.04 and later have full support
13107 for symbolic links.
13110 @item @command{ls}
13111 @c ---------------
13112 @prindex @command{ls}
13113 @cindex Listing directories
13114 The portable options are @option{-acdilrtu}.  Modern practice is for
13115 @option{-l} to output both owner and group, but traditional
13116 @command{ls} omits the group.
13118 @c From Bruce Lilly:
13120 @c # telnet dim
13121 @c [...]
13122 @c   Unix System V (TWG-TCP/IP) (dim.blilly.com)
13123 @c [...]
13124 @c $ mkdir foo
13125 @c $ cd foo
13126 @c $ /bin/ls a.exe 2>/dev/null
13127 @c a.exe not found
13128 @c $ what /bin/ls
13129 @c /bin/ls:
13130 @c           fndcmd:fndcmd.sl 1.68
13131 @c $ uname -a
13132 @c Unix dim SYSTEM5 3.51m mc68k
13134 @c It's an AT&T 3B1.  See http://www.faqs.org/faqs/3b1-faq/ or any
13135 @c mirror of the 3B1 FAQ.  It's actually SVR2.2.
13136 Modern practice is for all diagnostics to go to standard error, but
13137 traditional @samp{ls foo} prints the message @samp{foo not found} to
13138 standard output if @file{foo} does not exist.  Be careful when writing
13139 shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
13140 traditional @command{ls} this is equivalent to @samp{sources="*.c not
13141 found"} if there are no @samp{.c} files.
13144 @item @command{mkdir}
13145 @c ------------------
13146 @prindex @command{mkdir}
13147 @cindex Making directories
13148 None of @command{mkdir}'s options are portable to older systems.  Instead of
13149 @samp{mkdir -p @var{file-name}}, you should use use
13150 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13151 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13153 Posix does not clearly specify whether @samp{mkdir -p foo}
13154 should succeed when @file{foo} is a symbolic link to an already-existing
13155 directory.  The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13156 succeeds, but Solaris @command{mkdir} fails.
13158 Not all @code{mkdir -p} implementations are thread-safe.  When it is not
13159 and you call @code{mkdir -p a/b} and @code{mkdir -p a/c} at the same
13160 time, both will detect that @file{a/} is missing, one will create
13161 @file{a/}, then the other will try to create @file{a/} and die with a
13162 @code{File exists} error.  At least Solaris 10, Net@acronym{BSD} 1.6, and Open@acronym{BSD}
13163 3.4 have an unsafe @code{mkdir -p}.  The @acronym{GNU} Core Utilities
13164 (since @samp{fileutils}
13165 version 4.0c), Free@acronym{BSD} 5.0, and Net@acronym{BSD}-current are
13166 known to have a
13167 race-free @code{mkdir -p}.  This possible race is harmful in parallel
13168 builds when several @file{Makefile} rules call @code{mkdir -p} to
13169 construct directories.  You may use
13170 @code{install-sh -d} as a safe replacement, provided this script is
13171 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13172 OK, but copies from older versions are not thread-safe either.
13175 @item @command{mktemp}
13176 @c -------------------
13177 @prindex @command{mktemp}
13178 @cindex Creating temporary files
13179 Shell scripts can use temporary files safely with @command{mktemp}, but
13180 it does not exist on all systems.  A portable way to create a safe
13181 temporary file name is to create a temporary directory with mode 700 and
13182 use a file inside this directory.  Both methods prevent attackers from
13183 gaining control, though @command{mktemp} is far less likely to fail
13184 gratuitously under attack.
13186 Here is sample code to create a new temporary directory safely:
13188 @example
13189 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13190 # Use mktemp if possible; otherwise fall back on mkdir,
13191 # with $RANDOM to make collisions less likely.
13192 : $@{TMPDIR=/tmp@}
13194   tmp=`
13195     (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13196   ` &&
13197   test -n "$tmp" && test -d "$tmp"
13198 @} || @{
13199   tmp=$TMPDIR/foo$$-$RANDOM
13200   (umask 077 && mkdir "$tmp")
13201 @} || exit $?
13202 @end example
13205 @item @command{mv}
13206 @c ---------------
13207 @prindex @command{mv}
13208 @cindex Moving open files
13209 The only portable options are @option{-f} and @option{-i}.
13211 Moving individual files between file systems is portable (it was in Unix
13212 version 6),
13213 but it is not always atomic: when doing @samp{mv new existing}, there's
13214 a critical section where neither the old nor the new version of
13215 @file{existing} actually exists.
13217 On some systems moving files from @file{/tmp} can sometimes cause
13218 undesirable (but perfectly valid) warnings, even if you created these
13219 files.  This is because @file{/tmp} belongs to a group that ordinary
13220 users are not members of, and files created in @file{/tmp} inherit
13221 @file{/tmp}'s group.  When the file is copied, @command{mv} issues
13222 a diagnostic without failing:
13224 @smallexample
13225 $ @kbd{touch /tmp/foo}
13226 $ @kbd{mv /tmp/foo .}
13227 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13228 $ @kbd{echo $?}
13230 $ @kbd{ls foo}
13232 @end smallexample
13234 @noindent
13235 This annoying behavior conforms to Posix, unfortunately.
13237 Moving directories across mount points is not portable, use @command{cp}
13238 and @command{rm}.
13240 Moving/Deleting open files isn't portable.  The following can't be done
13241 on @acronym{DOS} variants:
13243 @example
13244 exec > foo
13245 mv foo bar
13246 @end example
13248 @noindent
13249 nor can
13251 @example
13252 exec > foo
13253 rm -f foo
13254 @end example
13257 @item @command{od}
13258 @c ---------------
13259 @prindex @command{od}
13261 In Mac OS X 10.3, @command{od} does not support the
13262 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13263 @option{-t}, or the @acronym{XSI} option @option{-s}.  The only
13264 supported Posix option is @option{-v}, and the only supported
13265 @acronym{XSI} options are those in @option{-bcdox}.  The BSD
13266 @command{hexdump} program can be used instead.
13268 This problem no longer exists in Mac OS X 10.4.3.
13271 @item @command{sed}
13272 @c ----------------
13273 @prindex @command{sed}
13274 Patterns should not include the separator (unless escaped), even as part
13275 of a character class.  In conformance with Posix, the Cray
13276 @command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13278 Avoid empty patterns within parentheses (i.e., @samp{\(\)}).  Posix does
13279 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13280 them.
13282 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13284 Sed scripts should not use branch labels longer than 8 characters and
13285 should not contain comments.  HP-UX sed has a limit of 99 commands
13286 (not counting @samp{:} commands) and
13287 48 labels, which can not be circumvented by using more than one script
13288 file.  It can execute up to 19 reads with the @samp{r} command per cycle.
13289 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13290 about 6000 bytes for the internal representation of commands.
13292 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13293 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13294 @samp{;} as a command:
13296 @example
13297 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13298 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13299 @end example
13301 Input should not have unreasonably long lines, since some @command{sed}
13302 implementations have an input buffer limited to 4000 bytes.
13304 Portable @command{sed} regular expressions should use @samp{\} only to escape
13305 characters in the string @samp{$()*.0123456789[\^n@{@}}.  For example,
13306 alternation, @samp{\|}, is common but Posix does not require its
13307 support, so it should be avoided in portable scripts.  Solaris
13308 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13309 deletes only lines that contain the literal string @samp{a|b}.
13310 Similarly, @samp{\+} and @samp{\?} should be avoided.
13312 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13314 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
13315 quite portable to modern hosts, but is not supported by some older
13316 @command{sed} implementations like SVR3.
13318 Some @command{sed} implementations, e.g., Solaris,
13319 restrict the special role of the asterisk to one-character regular expressions.
13320 This may lead to unexpected behavior:
13322 @example
13323 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13324 x2x4
13325 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13327 @end example
13329 The @option{-e} option is portable.
13330 Some people prefer to use it:
13332 @example
13333 sed -e '@var{command-1}' \
13334     -e '@var{command-2}'
13335 @end example
13337 @noindent
13338 as opposed to the equivalent:
13340 @example
13341 sed '
13342   @var{command-1}
13343   @var{command-2}
13345 @end example
13347 @noindent
13348 The following usage is sometimes equivalent:
13350 @example
13351 sed '@var{command-1};@var{command-2}'
13352 @end example
13354 but Posix says that this use of a semicolon has undefined effect if
13355 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13356 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13357 should use semicolon only with simple scripts that do not use these
13358 verbs.
13360 Commands inside @{ @} brackets are further restricted.  Posix says that
13361 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13362 each command must be followed immediately by a newline, without any
13363 intervening blanks or semicolons.  The closing bracket must be alone on
13364 a line, other than white space preceding or following it.
13366 Contrary to yet another urban legend, you may portably use @samp{&} in
13367 the replacement part of the @code{s} command to mean ``what was
13368 matched''.  All descendants of Unix version 7 @command{sed}
13369 (at least; we
13370 don't have first hand experience with older @command{sed}s) have
13371 supported it.
13373 Posix requires that you must not have any white space between
13374 @samp{!} and the following command.  It is OK to have blanks between
13375 the address and the @samp{!}.  For instance, on Solaris:
13377 @example
13378 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13379 @error{}Unrecognized command: /bar/ ! p
13380 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13381 @error{}Unrecognized command: /bar/! p
13382 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13384 @end example
13386 Posix also says that you should not combine @samp{!} and @samp{;}.  If
13387 you use @samp{!}, it is best to put it on a command that is delimited by
13388 newlines rather than @samp{;}.
13390 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13391 @samp{w} commands be followed by exactly one space before their argument.
13392 On the other hand, no white space is allowed between @samp{:} and the
13393 subsequent label name.
13395 @item @command{sed} (@samp{t})
13396 @c ---------------------------
13397 @prindex @command{sed} (@samp{t})
13398 Some old systems have @command{sed} that ``forget'' to reset their
13399 @samp{t} flag when starting a new cycle.  For instance on @acronym{MIPS
13400 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13401 script (the line numbers are not actual part of the texts):
13403 @example
13404 s/keep me/kept/g  # a
13405 t end             # b
13406 s/.*/deleted/g    # c
13407 :end              # d
13408 @end example
13410 @noindent
13413 @example
13414 delete me         # 1
13415 delete me         # 2
13416 keep me           # 3
13417 delete me         # 4
13418 @end example
13420 @noindent
13421 you get
13423 @example
13424 deleted
13425 delete me
13426 kept
13427 deleted
13428 @end example
13430 @noindent
13431 instead of
13433 @example
13434 deleted
13435 deleted
13436 kept
13437 deleted
13438 @end example
13440 Why?  When processing line 1, (c) matches, therefore sets the @samp{t}
13441 flag, and the output is produced.  When processing
13442 line 2, the @samp{t} flag is still set (this is the bug).  Command (a)
13443 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13444 flag when a substitution fails.  Command (b) sees that the flag is set,
13445 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13446 instead of @samp{deleted}.  When processing line (3), @samp{t} is clear,
13447 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13448 Finally, since the flag is clear, line 4 is processed properly.
13450 There are two things one should remember about @samp{t} in @command{sed}.
13451 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13452 succeeded, not only the immediately preceding substitution.  Therefore,
13453 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13454 line, to reset the @samp{t} flag where needed.
13456 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13457 cycle.
13459 One portable implementation of the script above is:
13461 @example
13462 t clear
13463 :clear
13464 s/keep me/kept/g
13465 t end
13466 s/.*/deleted/g
13467 :end
13468 @end example
13470 @item @command{touch}
13471 @c ------------------
13472 @prindex @command{touch}
13473 @cindex timestamp resolution
13474 If you specify the desired timestamp (e.g., with the @option{-r}
13475 option), @command{touch} typically uses the @code{utime} or
13476 @code{utimes} system call, which can result in the same kind of
13477 timestamp truncation problems that @samp{cp -p} has.
13479 On some old @acronym{BSD} systems, @command{touch} or any command that
13480 results in an empty file does not update the timestamps, so use a
13481 command like @command{echo} as a workaround.
13483 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
13484 fails to work on SunOS 4.1.3 when the empty file is on an
13485 @acronym{NFS}-mounted 4.2 volume.
13487 @end table
13490 @node Limitations of Make
13491 @section Limitations of Make
13492 @prindex @command{make}
13493 @cindex Limitations of @command{make}
13495 @command{make} itself suffers a great number of limitations, only a few
13496 of which are listed here.  First of all, remember that since commands
13497 are executed by the shell, all its weaknesses are inherited@enddots{}
13499 @table @asis
13501 @item @code{$<}
13502 Posix says that the @samp{$<} construct in makefiles can be
13503 used only in inference rules and in the @samp{.DEFAULT} rule; its
13504 meaning in ordinary rules is unspecified.  Solaris @command{make}
13505 for instance will replace it with the empty string.  Open@acronym{BSD} (3.0 and
13506 later) @command{make} will diagnose these uses and error out.
13508 @item Command execution
13509 Since 1992 Posix has required that @command{make} must invoke
13510 each command with the equivalent of a @samp{sh -c} subshell.  However,
13511 many @command{make} implementations, including @acronym{BSD} make through 2004,
13512 use @samp{sh -e -c} instead, and the @option{-e} option causes the
13513 subshell to exit immediately if a subsidiary simple-command fails.  For
13514 example, the command @samp{touch T; rm -f U} will always attempt to
13515 remove @file{U} with Posix make, but incompatible
13516 @command{make} implementations skip the @command{rm} if the
13517 @command{touch} fails.  One way to work around this is to reword the
13518 affected simple-commands so that they always succeed, e.g., @samp{touch
13519 T || :; rm -f U}.
13520 However, even this approach can run into common bugs in BSD
13521 implementations of the @option{-e} option of @command{sh} and
13522 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
13523 about porting to buggy BSD shells it may be simpler to migrate
13524 complicated @command{make} actions into separate scripts.
13526 @item Leading underscore in macro names
13527 Some @command{make}s don't support leading underscores in macro names,
13528 such as on NEWS-OS 4.2R.
13530 @example
13531 $ @kbd{cat Makefile}
13532 _am_include = #
13533 _am_quote =
13534 all:; @@echo this is test
13535 $ @kbd{make}
13536 Make: Must be a separator on rules line 2.  Stop.
13537 $ @kbd{cat Makefile2}
13538 am_include = #
13539 am_quote =
13540 all:; @@echo this is test
13541 $ @kbd{make -f Makefile2}
13542 this is test
13543 @end example
13545 @item Trailing backslash in macro
13546 @c  This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
13547 @c  but another hppa hpux 10.20 didn't have it.  Bob Proulx
13548 @c  <bob@proulx.com> thinks it was in hpux 8.0 too.
13549 On some versions of HP-UX, @command{make} will read multiple newlines
13550 following a backslash, continuing to the next non-empty line.  For
13551 example,
13553 @example
13554 FOO = one \
13556 BAR = two
13558 test:
13559         : FOO is "$(FOO)"
13560         : BAR is "$(BAR)"
13561 @end example
13563 @noindent
13564 shows @code{FOO} equal to @code{one BAR = two}.  Other @command{make}s
13565 sensibly let a backslash continue only to the immediately following
13566 line.
13568 @item Escaped newline in comments
13570 According to Posix, @file{Makefile} comments start with @code{#}
13571 and continue until an unescaped newline is reached.
13573 @example
13574 % @kbd{cat Makefile}
13575 # A = foo \
13576       bar \
13577       baz
13579 all:
13580         @@echo ok
13581 % @kbd{make}   # GNU make
13583 @end example
13585 @noindent
13586 However in Real World this is not always the case.  Some implementations
13587 discards anything from @code{#} up to the end of line, ignoring any
13588 trailing backslash.
13590 @example
13591 % @kbd{pmake}  # BSD make
13592 "Makefile", line 3: Need an operator
13593 Fatal errors encountered -- cannot continue
13594 @end example
13596 @noindent
13597 Therefore, if you want to comment out a multi-line definition, prefix each
13598 line with @code{#}, not only the first.
13600 @example
13601 # A = foo \
13602 #     bar \
13603 #     baz
13604 @end example
13606 @item Long lines.
13608 OSF/1 4.0d's @command{make} cannot process @file{Makefile}s with lines
13609 longer than 38912 bytes.  It exits with a @code{Line too long}
13610 diagnostic.  A later version, Tru64 5.1's @command{make} has been
13611 reported to crash with lines around 20 kB.
13613 @item @code{make macro=value} and sub-@command{make}s.
13615 A command-line variable definition such as @code{foo=bar} overrides any
13616 definition of @code{foo} in the @file{Makefile}.  Some @command{make}
13617 implementations (such as @acronym{GNU} @command{make}) will propagate this
13618 override to sub-invocations of @command{make}.  Some other implementation
13619 will not pass the substitution along to sub-@command{make}s.
13621 @example
13622 % @kbd{cat Makefile}
13623 foo = foo
13624 one:
13625         @@echo $(foo)
13626         $(MAKE) two
13627 two:
13628         @@echo $(foo)
13629 % @kbd{make foo=bar}            # GNU make 3.79.1
13631 make two
13632 make[1]: Entering directory `/home/adl'
13634 make[1]: Leaving directory `/home/adl'
13635 % @kbd{pmake foo=bar}           # BSD make
13637 pmake two
13639 @end example
13641 You have a few possibilities if you do want the @code{foo=bar} override
13642 to propagate to sub-@command{make}s.  One is to use the @option{-e}
13643 option, which causes all environment variables to have precedence over
13644 the @file{Makefile} macro definitions, and declare foo as an environment
13645 variable:
13647 @example
13648 % @kbd{env foo=bar make -e}
13649 @end example
13651 The @option{-e} option is propagated to sub-@command{make}s automatically,
13652 and since the environment is inherited between @command{make}
13653 invocations, the @code{foo} macro will be overridden in
13654 sub-@code{make}s as expected.
13656 This syntax (@code{foo=bar make -e}) is portable only when used
13657 outside of a @file{Makefile}, for instance from a script or from the
13658 command line.  When run inside a @command{make} rule, @acronym{GNU}
13659 @command{make} 3.80 and prior versions forget to propagate the
13660 @option{-e} option to sub-@command{make}s.
13662 Moreover, using @option{-e} could have unexpected side-effects if your
13663 environment contains some other macros usually defined by the
13664 Makefile.  (See also the note about @code{make -e} and @code{SHELL}
13665 below.)
13667 Another way to propagate overrides to sub-@command{make}s is to do it
13668 manually, from your @file{Makefile}:
13670 @example
13671 foo = foo
13672 one:
13673         @@echo $(foo)
13674         $(MAKE) foo=$(foo) two
13675 two:
13676         @@echo $(foo)
13677 @end example
13679 You need to foresee all macros that a user might want to override if
13680 you do that.
13682 @item The @code{SHELL} macro
13683 @cindex @code{SHELL} and @command{make}
13684 @cindex @command{make} and @code{SHELL}
13686 Posix-compliant @command{make}s internally use the @code{$(SHELL)}
13687 macro to spawn shell processes and execute @file{Makefile} rules.  This
13688 is a builtin macro supplied by @command{make}, but it can be modified
13689 from the @file{Makefile} or a command-line argument.
13691 Not all @command{make}s will define this @code{SHELL} macro.  OSF/Tru64
13692 @command{make} is an example; this implementation will always use
13693 @code{/bin/sh}.  So it's a good idea to always define @code{SHELL} in
13694 your @file{Makefile}s.  If you use Autoconf, do
13696 @example
13697 SHELL = @@SHELL@@
13698 @end example
13700 Do not force @code{SHELL = /bin/sh} because that is not correct
13701 everywhere.  For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
13702 its @acronym{GNU} @code{make} port sees such a setting it enters a special
13703 emulation mode where features like pipes and redirections are emulated
13704 on top of DOS's @command{command.com}.  Unfortunately this emulation is
13705 incomplete; for instance it does not handle command substitutions.
13706 On @acronym{DJGPP} @code{SHELL} should point to Bash.
13708 Posix-compliant @command{make}s should never acquire the value of
13709 $(SHELL) from the environment, even when @code{make -e} is used
13710 (otherwise, think about what would happen to your rules if
13711 @code{SHELL=/bin/tcsh}).
13713 However not all @command{make} implementations will make this exception.
13714 For instance it's not surprising that OSF/Tru64 @command{make} doesn't
13715 protect @code{SHELL}, since it doesn't use it.
13717 @example
13718 % @kbd{cat Makefile}
13719 SHELL = /bin/sh
13720 FOO = foo
13721 all:
13722         @@echo $(SHELL)
13723         @@echo $(FOO)
13724 % @kbd{env SHELL=/bin/tcsh FOO=bar make -e}   # OSF1 V4.0 Make
13725 /bin/tcsh
13727 % @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e}  # GNU make
13728 /bin/sh
13730 @end example
13732 @item Comments in rules
13733 @cindex Comments in @file{Makefile} rules
13734 @cindex @file{Makefile} rules and comments
13736 Never put comments in a rule.
13738 Some @command{make} treat anything starting with a tab as a command for
13739 the current rule, even if the tab is immediately followed by a @code{#}.
13740 The @command{make} from Tru64 Unix V5.1 is one of them.  The following
13741 @file{Makefile} will run @code{# foo} through the shell.
13743 @example
13744 all:
13745         # foo
13746 @end example
13748 @item The @file{obj/} subdirectory.
13749 @cindex @file{obj/}, subdirectory
13750 @cindex @acronym{BSD} @command{make} and @file{obj/}
13752 Never name one of your subdirectories @file{obj/} if you don't like
13753 surprises.
13755 If an @file{obj/} directory exists, @acronym{BSD} @command{make} will enter it
13756 before reading @file{Makefile}.  Hence the @file{Makefile} in the
13757 current directory will not be read.
13759 @example
13760 % @kbd{cat Makefile}
13761 all:
13762         echo Hello
13763 % @kbd{cat obj/Makefile}
13764 all:
13765         echo World
13766 % @kbd{make}      # GNU make
13767 echo Hello
13768 Hello
13769 % @kbd{pmake}     # BSD make
13770 echo World
13771 World
13772 @end example
13774 @item @code{make -k}
13775 @cindex @code{make -k}
13777 Do not rely on the exit status of @code{make -k}.  Some implementations
13778 reflect whether they encountered an error in their exit status; other
13779 implementations always succeed.
13781 @example
13782 % @kbd{cat Makefile}
13783 all:
13784         false
13785 % @kbd{make -k; echo exit status: $?}    # GNU make
13786 false
13787 make: *** [all] Error 1
13788 exit status: 2
13789 % @kbd{pmake -k; echo exit status: $?}   # BSD make
13790 false
13791 *** Error code 1 (continuing)
13792 exit status: 0
13793 @end example
13795 @item @code{VPATH}
13796 @cindex @code{VPATH}
13798 There is no @code{VPATH} support specified in Posix.  Many
13799 @command{make}s have a form of @code{VPATH} support, but its
13800 implementation is not consistent amongst @command{make}s.
13802 Maybe the best suggestion to give to people who need the @code{VPATH}
13803 feature is to choose a @command{make} implementation and stick to it.
13804 Since the resulting @file{Makefile}s are not portable anyway, better
13805 choose a portable @command{make} (hint, hint).
13807 Here are a couple of known issues with some @code{VPATH}
13808 implementations.
13810 @table @asis
13812 @item @code{VPATH} and double-colon rules
13813 @cindex @code{VPATH} and double-colon rules
13814 @cindex double-colon rules and @code{VPATH}
13816 Any assignment to @code{VPATH} causes Sun @command{make} to only execute
13817 the first set of double-colon rules.  (This comment has been here since
13818 1994 and the context has been lost.  It's probably about SunOS 4.  If
13819 you can reproduce this, please send us a test case for illustration.)
13821 @item @code{$<} not supported in explicit rules
13822 @cindex explicit rules, @code{$<}, and @code{VPATH}
13823 @cindex @code{$<}, explicit rules, and @code{VPATH}
13824 @cindex @code{VPATH}, explicit rules, and @code{$<}
13826 As said elsewhere, using @code{$<} in explicit rules is not portable.
13827 The prerequisite file must be named explicitly in the rule.  If you want
13828 to find the prerequisite via a @code{VPATH} search, you have to code the
13829 whole thing manually.  For instance, using the following pattern:
13831 @example
13832 VPATH = ../pkg/src
13833 f.c: if.c
13834         cp `test -f if.c || echo $(VPATH)/`if.c f.c
13835 @end example
13837 @item Automatic rule rewriting
13838 @cindex @code{VPATH} and automatic rule rewriting
13839 @cindex automatic rule rewriting and @code{VPATH}
13841 Some @command{make} implementations, such as SunOS 4 @command{make} or
13842 OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
13843 rewrite all their occurrences in the rule appropriately.
13845 For instance
13847 @example
13848 VPATH = ../pkg/src
13849 f.c: if.c
13850         cp if.c f.c
13851 @end example
13853 @noindent
13854 would execute @code{cp ../pkg/src/if.c f.c} if @file{if.c} was
13855 found in @file{../pkg/src}.  That sounds great.
13857 However, for the sake of other @command{make} implementations, we can't
13858 rely on this, and we have to search @code{VPATH} manually:
13860 @smallexample
13861 VPATH = ../pkg/src
13862 f.c: if.c
13863         cp `test -f if.c || echo $(VPATH)/`if.c f.c
13864 @end smallexample
13866 @noindent
13867 However the "prerequisite rewriting" still applies here.  So if
13868 @file{if.c} is in @file{../pkg/src}, SunOS 4 @command{make} and OSF1/Tru64
13869 @command{make} will execute
13871 @smallexample
13872 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
13873 @end smallexample
13875 @noindent
13876 which reduces to
13878 @example
13879 cp if.c f.c
13880 @end example
13882 @noindent
13883 and thus fails.  Oops.
13885 One workaround is to make sure that @file{if.c} never appears as a plain word
13886 in the rule.  For instance these three rules would be safe.
13888 @smallexample
13889 VPATH = ../pkg/src
13890 f.c: if.c
13891         cp `test -f ./if.c || echo $(VPATH)/`if.c f.c
13892 g.c: ig.c
13893         cp `test -f 'ig.c' || echo $(VPATH)/`ig.c g.c
13894 h.c: ih.c
13895         cp `test -f "ih.c" || echo $(VPATH)/`ih.c h.c
13896 @end smallexample
13898 Things get worse when your prerequisites are in a macro.
13900 @example
13901 VPATH = ../pkg/src
13902 HEADERS = f.h g.h h.h
13903 install-HEADERS: $(HEADERS)
13904         for i in $(HEADERS); do \
13905           $(INSTALL) -m 644 \
13906             `test -f $$i || echo $(VPATH)/`$$i \
13907             $(DESTDIR)$(includedir)/$$i; \
13908         done
13909 @end example
13911 The above @code{install-HEADERS} rule is not SunOS-4-proof because @code{for
13912 i in $(HEADERS);} will be expanded as @code{for i in f.h g.h h.h;}
13913 where @code{f.h} and @code{g.h} are plain words and are hence
13914 subject to @code{VPATH} adjustments.
13916 If the three files are in @file{../pkg/src}, the rule is run as:
13918 @example
13919 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
13920   install -m 644 \
13921      `test -f $i || echo ../pkg/src/`$i \
13922      /usr/local/include/$i; \
13923 done
13924 @end example
13926 where the two first @command{install} calls will fail.  For instance,
13927 consider the @code{f.h} installation:
13929 @example
13930 install -m 644 \
13931   `test -f ../pkg/src/f.h || \
13932     echo ../pkg/src/ \
13933   `../pkg/src/f.h \
13934   /usr/local/include/../pkg/src/f.h;
13935 @end example
13936 @noindent
13937 It reduces to:
13939 @example
13940 install -m 644 \
13941   ../pkg/src/f.h \
13942   /usr/local/include/../pkg/src/f.h;
13943 @end example
13945 Note that the manual @code{VPATH} search did not cause any problems here;
13946 however this command installs @file{f.h} in an incorrect directory.
13948 Trying to quote @code{$(HEADERS)} in some way, as we did for
13949 @code{foo.c} a few @file{Makefile}s ago, does not help:
13951 @example
13952 install-HEADERS: $(HEADERS)
13953         headers='$(HEADERS)'; \
13954         for i in $$headers; do \
13955           $(INSTALL) -m 644 \
13956             `test -f $$i || echo $(VPATH)/`$$i \
13957             $(DESTDIR)$(includedir)/$$i; \
13958         done
13959 @end example
13961 Now, @code{headers='$(HEADERS)'} macroexpands to:
13963 @example
13964 headers='f.h g.h h.h'
13965 @end example
13967 @noindent
13968 but @code{g.h} is still a plain word.  (As an aside, the idiom
13969 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
13970 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
13971 syntax error on @code{for i in;}.)
13973 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
13974 @example
13975 VPATH = ../pkg/src
13976 HEADERS = f.h g.h h.h
13977 install-HEADERS: $(HEADERS)
13978         headers='$(HEADERS)'; \
13979         for i in $$headers; do \
13980           i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
13981           $(INSTALL) -m 644 \
13982             `test -f $$i || echo $(VPATH)/`$$i \
13983             $(DESTDIR)$(includedir)/$$i; \
13984         done
13985 @end example
13987 Automake does something similar.  However the above hack works only if
13988 the files listed in @code{HEADERS} are in the current directory or a
13989 subdirectory; they should not be in an enclosing directory.  If we had
13990 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
13991 build with OSF1/Tru64 @command{make}.  The reason is that not only does
13992 OSF1/Tru64 @command{make} rewrite dependencies, but it also simplifies
13993 them.  Hence @code{../f.h} will become @code{../pkg/f.h} instead of
13994 @code{../pkg/src/../f.h}.  This obviously defeats any attempt to strip
13995 a leading @file{../pkg/src/} component.
13997 The following example makes the behavior of OSF1/Tru64 @command{make}
13998 more apparent.
13999 @example
14000 % cat Makefile
14001 VPATH = sub
14002 all: ../foo
14003         echo ../foo
14004 % ls
14005 Makefile foo
14006 % make
14007 echo foo
14009 @end example
14010 @noindent
14011 Dependency @file{../foo} was found in @file{sub/../foo}, but OSF1/Tru64
14012 @command{make} simplified it as @file{foo}.  (Note that the @file{sub/}
14013 directory does not even exist, this just means that the simplification
14014 occurred before the file was checked for.)
14016 For the record here is how SunOS 4 @command{make} behaves on this
14017 very same example.
14018 @smallexample
14019 % make
14020 make: Fatal error: Don't know how to make target `../foo'
14021 % mkdir sub
14022 % make
14023 echo sub/../foo
14024 sub/../foo
14025 @end smallexample
14028 @item OSF/Tru64 @command{make} creates prerequisite directories magically
14029 @cindex @code{VPATH} and prerequisite directories
14030 @cindex prerequisite directories and @code{VPATH}
14032 When a prerequisite is a sub-directory of @code{VPATH}, Tru64
14033 @command{make} will create it in the current directory.
14035 @example
14036 % @kbd{mkdir -p foo/bar build}
14037 % @kbd{cd build}
14038 % @kbd{cat >Makefile <<END
14039 VPATH = ..
14040 all: foo/bar
14041 END}
14042 % @kbd{make}
14043 mkdir foo
14044 mkdir foo/bar
14045 @end example
14047 This can yield unexpected results if a rule uses a manual @code{VPATH}
14048 search as presented before.
14050 @example
14051 VPATH = ..
14052 all : foo/bar
14053         command `test -d foo/bar || echo ../`foo/bar
14054 @end example
14056 The above @command{command} will be run on the empty @file{foo/bar}
14057 directory that was created in the current directory.
14059 @item target lookup
14060 @cindex @code{VPATH}, resolving target pathnames
14062 @acronym{GNU} @command{make} uses a rather complex algorithm to decide when it
14063 should use files found via a @code{VPATH} search.  @xref{Search
14064 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14065 Manual}.
14067 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14068 file name found during the @code{VPATH} search for this target, and
14069 builds the file locally using the file name given in the @file{Makefile}.
14070 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14071 file name found during the @code{VPATH} search.
14073 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14074 easier to describe: the file name found during the @code{VPATH} search
14075 will be used whether the target needs to be rebuilt or not.  Therefore
14076 new files are created locally, but existing files are updated at their
14077 @code{VPATH} location.
14079 Open@acronym{BSD} and Free@acronym{BSD} @command{make}s, however, will
14080 never perform a
14081 @code{VPATH} search for a dependency which has an explicit rule.
14082 This is extremely annoying.
14084 When attempting a @code{VPATH} build for an autoconfiscated package
14085 (e.g., @code{mkdir build && cd build && ../configure}), this means the
14086 @acronym{GNU}
14087 @command{make} will build everything locally in the @file{build}
14088 directory, while @acronym{BSD} @command{make} will build new files locally and
14089 update existing files in the source directory.
14091 @example
14092 % @kbd{cat Makefile}
14093 VPATH = ..
14094 all: foo.x bar.x
14095 foo.x bar.x: newer.x
14096         @@echo Building $@@
14097 % @kbd{touch ../bar.x}
14098 % @kbd{touch ../newer.x}
14099 % @kbd{make}        # GNU make
14100 Building foo.x
14101 Building bar.x
14102 % @kbd{pmake}       # NetBSD make
14103 Building foo.x
14104 Building ../bar.x
14105 % @kbd{fmake}       # FreeBSD make, OpenBSD make
14106 Building foo.x
14107 Building bar.x
14108 % @kbd{tmake}       # Tru64 make
14109 Building foo.x
14110 Building bar.x
14111 % @kbd{touch ../bar.x}
14112 % @kbd{make}        # GNU make
14113 Building foo.x
14114 % @kbd{pmake}       # NetBSD make
14115 Building foo.x
14116 % @kbd{fmake}       # FreeBSD make, OpenBSD make
14117 Building foo.x
14118 Building bar.x
14119 % @kbd{tmake}       # Tru64 make
14120 Building foo.x
14121 Building bar.x
14122 @end example
14124 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14125 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14126 @command{make} always
14127 update @file{bar.x}, even when @file{../bar.x} is up to date.
14129 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14130 decided to ignore a @code{VPATH} file name (e.g., it ignored
14131 @file{../bar.x} in the above example) it will continue to ignore it when
14132 the target occurs as a prerequisite of another rule.
14134 The following example shows that @acronym{GNU} @command{make} does not look up
14135 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14136 because it ignored the @code{VPATH} result of @file{bar.x} while running
14137 the @code{bar.x: newer.x} rule.
14139 @example
14140 % @kbd{cat Makefile}
14141 VPATH = ..
14142 all: bar.y
14143 bar.x: newer.x
14144         @@echo Building $@@
14145 .SUFFIXES: .x .y
14146 .x.y:
14147         cp $< $@@
14148 % @kbd{touch ../bar.x}
14149 % @kbd{touch ../newer.x}
14150 % @kbd{make}        # GNU make
14151 Building bar.x
14152 cp bar.x bar.y
14153 cp: cannot stat `bar.x': No such file or directory
14154 make: *** [bar.y] Error 1
14155 % @kbd{pmake}       # NetBSD make
14156 Building ../bar.x
14157 cp ../bar.x bar.y
14158 % @kbd{rm bar.y}
14159 % @kbd{fmake}       # FreeBSD make, OpenBSD make
14160 echo Building bar.x
14161 cp bar.x bar.y
14162 cp: cannot stat `bar.x': No such file or directory
14163 *** Error code 1
14164 % @kbd{tmake}       # Tru64 make
14165 Building bar.x
14166 cp: bar.x: No such file or directory
14167 *** Exit 1
14168 @end example
14170 Note that if you drop away the command from the @code{bar.x: newer.x}
14171 rule, @acronym{GNU} @command{make} will magically start to work: it
14172 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14173 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14174 uses.  Tru64 will also work, but Free@acronym{BSD} and Open@acronym{BSD}
14175 still don't.
14177 @example
14178 % @kbd{cat Makefile}
14179 VPATH = ..
14180 all: bar.y
14181 bar.x: newer.x
14182 .SUFFIXES: .x .y
14183 .x.y:
14184         cp $< $@@
14185 % @kbd{touch ../bar.x}
14186 % @kbd{touch ../newer.x}
14187 % @kbd{make}        # GNU make
14188 cp ../bar.x bar.y
14189 % @kbd{rm bar.y}
14190 % @kbd{pmake}       # NetBSD make
14191 cp ../bar.x bar.y
14192 % @kbd{rm bar.y}
14193 % @kbd{fmake}       # FreeBSD make, OpenBSD make
14194 cp bar.x bar.y
14195 cp: cannot stat `bar.x': No such file or directory
14196 *** Error code 1
14197 % @kbd{tmake}       # Tru64 make
14198 cp ../bar.x bar.y
14199 @end example
14201 It seems the sole solution that would please every @command{make}
14202 implementation is to never rely on @code{VPATH} searches for targets.
14203 In other words, @code{VPATH} should be reserved to unbuilt sources.
14205 @end table
14206 @c end item about VPATH
14208 @item Single Suffix Rules and Separated Dependencies
14209 @cindex Single Suffix Inference Rule
14210 @cindex Rule, Single Suffix Inference
14211 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14212 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14213 (@samp{.from:}).
14215 @cindex Separated Dependencies
14216 @dfn{Separated dependencies} simply refers to listing the prerequisite
14217 of a target, without defining a rule.  Usually one can list on the one
14218 hand side, the rules, and on the other hand side, the dependencies.
14220 Solaris @command{make} does not support separated dependencies for
14221 targets defined by single suffix rules:
14223 @example
14224 $ @kbd{cat Makefile}
14225 .SUFFIXES: .in
14226 foo: foo.in
14227 .in:
14228         cp $< $@@
14229 $ @kbd{touch foo.in}
14230 $ @kbd{make}
14231 $ @kbd{ls}
14232 Makefile  foo.in
14233 @end example
14235 @noindent
14236 while @acronym{GNU} Make does:
14238 @example
14239 $ @kbd{gmake}
14240 cp foo.in foo
14241 $ @kbd{ls}
14242 Makefile  foo       foo.in
14243 @end example
14245 Note it works without the @samp{foo: foo.in} dependency.
14247 @example
14248 $ @kbd{cat Makefile}
14249 .SUFFIXES: .in
14250 .in:
14251         cp $< $@@
14252 $ @kbd{make foo}
14253 cp foo.in foo
14254 @end example
14256 @noindent
14257 and it works with double suffix inference rules:
14259 @example
14260 $ @kbd{cat Makefile}
14261 foo.out: foo.in
14262 .SUFFIXES: .in .out
14263 .in.out:
14264         cp $< $@@
14265 $ @kbd{make}
14266 cp foo.in foo.out
14267 @end example
14269 As a result, in such a case, you have to write target rules.
14271 @item Timestamp Resolution
14272 @cindex timestamp resolution
14273 Traditionally, file timestamps had 1-second resolution, and
14274 @command{make} used those timestamps to determine whether one file was
14275 newer than the other.  However, many modern file systems have
14276 timestamps with 1-nanosecond resolution.  Some @command{make}
14277 implementations look at the entire timestamp; others ignore the
14278 fractional part, which can lead to incorrect results.  Normally this
14279 is not a problem, but in some extreme cases you may need to use tricks
14280 like @samp{sleep 1} to work around timestamp truncation bugs.
14282 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14283 file timestamps to their full resolutions (@pxref{Limitations of Usual
14284 Tools}).  Hence you should be wary of rules like this:
14286 @example
14287 dest: src
14288         cp -p src dest
14289 @end example
14291 as @file{dest} will often appear to be older than @file{src} after the
14292 timestamp is truncated, and this can cause @command{make} to do
14293 needless rework the next time it is invoked.  To work around this
14294 problem, you can use a timestamp file, e.g.:
14296 @example
14297 dest-stamp: src
14298         cp -p src dest
14299         date >dest-stamp
14300 @end example
14302 @end table
14307 @c ======================================== Portable C and C++ Programming
14309 @node Portable C and C++
14310 @chapter Portable C and C++ Programming
14311 @cindex Portable C and C++ programming
14313 C and C++ programs often use low-level features of the underlying
14314 system, and therefore are often more difficult to make portable to other
14315 platforms.
14317 Several standards have been developed to help make your programs more
14318 portable.  If you write programs with these standards in mind, you can
14319 have greater confidence that your programs will work on a wide variety
14320 of systems.  @xref{Standards, , Language Standards Supported by GCC,
14321 gcc, Using the GNU Compiler Collection (GCC)}, for a list of C-related
14322 standards.  Many programs also assume the
14323 @uref{http://www.opengroup.org/susv3, Posix standard}.
14325 Some old code is written to be portable to K&R C, which predates any C
14326 standard.  K&R C compilers are no longer of practical interest, though,
14327 and the rest of section assumes at least C89, the first C standard.
14329 Program portability is a huge topic, and this section can only briefly
14330 introduce common pitfalls.  @xref{System Portability, , Portability
14331 between System Types, standards, @acronym{GNU} Coding Standards}, for
14332 more information.
14334 @menu
14335 * Varieties of Unportability::  How to make your programs unportable
14336 * Integer Overflow::            When integers get too large
14337 * Null Pointers::               Properties of null pointers
14338 * Buffer Overruns::             Subscript errors and the like
14339 * Floating Point Portability::  Portable floating-point arithmetic
14340 * Exiting Portably::            Exiting and the exit status
14341 @end menu
14343 @node Varieties of Unportability
14344 @section Varieties of Unportability
14345 @cindex portability
14347 Autoconf tests and ordinary programs often need to test what is allowed
14348 on a system, and therefore they may need to deliberately exceed the
14349 boundaries of what the standards allow, if only to see whether an
14350 optional feature is present.  When you write such a program, you should
14351 keep in mind the difference between constraints, unspecified behavior,
14352 and undefined behavior.
14354 In C, a @dfn{constraint} is a rule that the compiler must enforce.  An
14355 example constraint is that C programs must not declare a bit-field with
14356 negative width.  Tests can therefore reliably assume that programs with
14357 negative-width bit-fields will be rejected by a compiler that conforms
14358 to the standard.
14360 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14361 multiple possibilities.  For example, the order of evaluation of
14362 function arguments is unspecified.  Some unspecified behavior is
14363 @dfn{implementation-defined}, i.e., documented by the implementation,
14364 but since Autoconf tests cannot read the documentation they cannot
14365 distinguish between implementation-defined and other unspecified
14366 behavior.  It is common for Autoconf tests to probe implementations to
14367 determine otherwise-unspecified behavior.
14369 @dfn{Undefined behavior} is invalid behavior, where the standard allows
14370 the implementation to do anything it pleases.  For example,
14371 dereferencing a null pointer leads to undefined behavior.  If possible,
14372 test programs should avoid undefined behavior, since a program with
14373 undefined behavior might succeed on a test that should fail.
14375 The above rules apply to programs that are intended to conform to the
14376 standard.  However, strictly-conforming programs are quite rare, since
14377 the standards are so limiting.  A major goal of Autoconf is to support
14378 programs that use implementation features not described by the standard,
14379 and it is fairly common for test programs to violate the above rules, if
14380 the programs work well enough in practice.
14382 @node Integer Overflow
14383 @section Integer Overflow
14384 @cindex overflow, arithmetic
14386 In C, signed integer overflow leads to undefined behavior.  However,
14387 many programs and Autoconf tests assume that signed integer overflow after
14388 addition, subtraction, or multiplication silently
14389 wraps around modulo a power of two, using two's complement arithmetic,
14390 so long as you cast the resulting value
14391 to an integer type or store it into an integer variable.  Such programs
14392 are portable to the vast majority of modern platforms.  However, signed
14393 integer division is not always harmless: for example, on CPUs of the
14394 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
14395 which by default terminates the program.
14397 GCC users might consider using the
14398 @option{-ftrapv} option if they are worried about porting their code to
14399 the rare platforms where signed integer overflow does not wrap around
14400 after addition, subtraction, or multiplication.
14402 Unsigned integer overflow reliably wraps around modulo the word size.
14403 This is guaranteed by the C standard and is portable in practice.
14405 @node Null Pointers
14406 @section Properties of Null Pointers
14407 @cindex null pointers
14409 Most modern hosts reliably fail when you attempt to dereference a null
14410 pointer.
14412 On almost all modern hosts, null pointers use an all-bits-zero internal
14413 representation, so you can reliably use @code{memset} with 0 to set all
14414 the pointers in an array to null values.
14416 If @code{p} is a null pointer to an object type, the C expression
14417 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
14418 the standard says that it has undefined behavior.
14420 @node Buffer Overruns
14421 @section Buffer Overruns and Subscript Errors
14422 @cindex buffer overruns
14424 Buffer overruns and subscript errors are the most common dangerous
14425 errors in C programs.  They result in undefined behavior because storing
14426 outside an array typically modifies storage that is used by some other
14427 object, and most modern systems lack runtime checks to catch these
14428 errors.  Programs should not rely on buffer overruns being caught.
14430 There is one exception to the usual rule that a portable program cannot
14431 address outside an array.  In C, it is valid to compute the address just
14432 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
14433 so long as you do not dereference the resulting pointer.  But it is not
14434 valid to compute the address just before an object, e.g., @code{&a[-1]};
14435 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}.  On
14436 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
14437 reliable in general, and it is usually easy enough to avoid the
14438 potential portability problem, e.g., by allocating an extra unused array
14439 element at the start or end.
14441 @uref{http://valgrind.org/, Valgrind} can catch many overruns.  GCC
14442 users might also consider using the @option{-fmudflap} option to catch
14443 overruns.
14445 Buffer overruns are usually caused by off-by-one errors, but there are
14446 more subtle ways to get them.
14448 Using @code{int} values to index into an array or compute array sizes
14449 will cause problems on typical 64-bit hosts where an array index might
14450 be @math{2^31} or larger.
14452 If you add or multiply two numbers to calculate an array size, e.g.,
14453 @code{malloc (x * sizeof y + z)}, havoc will ensue if the addition or
14454 multiplication overflows.
14456 Many implementations of the @code{alloca} function silently misbehave
14457 and can generate buffer overflows if given sizes that are too large.
14458 The size limits are implementation dependent, but are at least 4000
14459 bytes on all platforms that we know about.
14461 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
14462 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
14463 portable code should not use them unless the inputs are known to be
14464 within certain limits.  The time-related functions can overflow their
14465 buffers if given time stamps out of range (e.g., a year less than -999
14466 or greater than 9999).  Time-related buffer overflows cannot happen with
14467 recent-enough versions of the GNU C library, but are possible with other
14468 implementations.  The @code{gets} function is the worst, since it almost
14469 invariably overflows its buffer when presented with an input line larger
14470 than the buffer.
14472 @node Floating Point Portability
14473 @section Floating Point Portability
14474 @cindex floating point
14476 Almost all modern systems use IEEE-754 floating point, and it is safe to
14477 assume IEEE-754 in most portable code these days.  For more information,
14478 please see David Goldberg's classic paper
14479 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
14480 Scientist Should Know About Floating-Point Arithmetic}.
14482 @node Exiting Portably
14483 @section Exiting Portably
14484 @cindex exiting portably
14486 A C or C++ program can exit with status @var{N} by returning
14487 @var{N} from the @code{main} function.  Portable programs are supposed
14488 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
14489 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
14490 fail by exiting with status 1, and test programs that assume Posix can
14491 fail by exiting with status values from 1 through 255.  Programs on
14492 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
14493 status when @code{main} returned nonzero, but ancient systems like these
14494 are no longer of practical concern.
14496 A program can also exit with status @var{N} by passing @var{N} to the
14497 @code{exit} function, and a program can fail by calling the @code{abort}
14498 function.  If a program is specialized to just some platforms, it can fail
14499 by calling functions specific to those platforms, e.g., @code{_exit}
14500 (Posix) and @code{_Exit} (C99).  However, like other functions, an exit
14501 function should be declared, typically by including a header.  For
14502 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
14503 either directly or via the default includes (@pxref{Default Includes}).
14505 A program can fail due to undefined behavior such as dereferencing a null
14506 pointer, but this is not recommended as undefined behavior allows an
14507 implementation to do whatever it pleases and this includes exiting
14508 successfully.
14511 @c ================================================== Manual Configuration
14513 @node Manual Configuration
14514 @chapter Manual Configuration
14516 A few kinds of features can't be guessed automatically by running test
14517 programs.  For example, the details of the object-file format, or
14518 special options that need to be passed to the compiler or linker.  You
14519 can check for such features using ad-hoc means, such as having
14520 @command{configure} check the output of the @code{uname} program, or
14521 looking for libraries that are unique to particular systems.  However,
14522 Autoconf provides a uniform method for handling unguessable features.
14524 @menu
14525 * Specifying Names::            Specifying the system type
14526 * Canonicalizing::              Getting the canonical system type
14527 * Using System Type::           What to do with the system type
14528 @end menu
14530 @node Specifying Names
14531 @section Specifying the System Type
14532 @cindex System type
14534 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
14535 @command{configure} scripts can make decisions based on a canonical name
14536 for the system type, which has the form:
14537 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
14538 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
14540 @command{configure} can usually guess the canonical name for the type of
14541 system it's running on.  To do so it runs a script called
14542 @command{config.guess}, which infers the name using the @code{uname}
14543 command or symbols predefined by the C preprocessor.
14545 Alternately, the user can specify the system type with command line
14546 arguments to @command{configure}.  Doing so is necessary when
14547 cross-compiling.  In the most complex case of cross-compiling, three
14548 system types are involved.  The options to specify them are:
14550 @table @option
14551 @item --build=@var{build-type}
14552 the type of system on which the package is being configured and
14553 compiled.  It defaults to the result of running @command{config.guess}.
14555 @item --host=@var{host-type}
14556 the type of system on which the package will run.  By default it is the
14557 same as the build machine.  Specifying it enables the cross-compilation
14558 mode.
14560 @item --target=@var{target-type}
14561 the type of system for which any compiler tools in the package will
14562 produce code (rarely needed).  By default, it is the same as host.
14563 @end table
14565 If you mean to override the result of @command{config.guess}, use
14566 @option{--build}, not @option{--host}, since the latter enables
14567 cross-compilation.  For historical reasons, passing @option{--host} also
14568 changes the build type.  Therefore, whenever you specify @option{--host},
14569 be sure to specify @option{--build} too; this will be fixed in the
14570 future.  So, to enter cross-compilation mode, use a command like this
14572 @example
14573 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
14574 @end example
14576 @noindent
14577 Note that if you do not specify @option{--host}, @command{configure} will
14578 fail if it can't run the code generated by the specified compiler.  For
14579 example, configuring as follows will fail:
14581 @example
14582 ./configure CC=m68k-coff-gcc
14583 @end example
14585 In the future, when cross-compiling Autoconf will @emph{not}
14586 accept tools (compilers, linkers, assemblers) whose name is not
14587 prefixed with the host type.  The only case when this may be
14588 useful is when you really are not cross-compiling, but only
14589 building for a least-common-denominator architecture: an example
14590 is building for @code{i386-pc-linux-gnu} while running on an
14591 @code{i686-pc-linux-gnu} architecture.  In this case, some particular
14592 pairs might be similar enough to let you get away with the system
14593 compilers, but in general the compiler might make bogus assumptions
14594 on the host: if you know what you are doing, please create symbolic
14595 links from the host compiler to the build compiler.
14597 @cindex @command{config.sub}
14598 @command{configure} recognizes short aliases for many system types; for
14599 example, @samp{decstation} can be used instead of
14600 @samp{mips-dec-ultrix4.2}.  @command{configure} runs a script called
14601 @command{config.sub} to canonicalize system type aliases.
14603 This section deliberately omits the description of the obsolete
14604 interface; see @ref{Hosts and Cross-Compilation}.
14607 @node Canonicalizing
14608 @section Getting the Canonical System Type
14609 @cindex System type
14610 @cindex Canonical system type
14612 The following macros make the system type available to @command{configure}
14613 scripts.
14615 @ovindex build_alias
14616 @ovindex host_alias
14617 @ovindex target_alias
14619 The variables @samp{build_alias}, @samp{host_alias}, and
14620 @samp{target_alias} are always exactly the arguments of @option{--build},
14621 @option{--host}, and @option{--target}; in particular, they are left empty
14622 if the user did not use them, even if the corresponding
14623 @code{AC_CANONICAL} macro was run.  Any configure script may use these
14624 variables anywhere.  These are the variables that should be used when in
14625 interaction with the user.
14627 If you need to recognize some special environments based on their system
14628 type, run the following macros to get canonical system names.  These
14629 variables are not set before the macro call.
14631 If you use these macros, you must distribute @command{config.guess} and
14632 @command{config.sub} along with your source code.  @xref{Output}, for
14633 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
14634 to control in which directory @command{configure} looks for those scripts.
14637 @defmac AC_CANONICAL_BUILD
14638 @acindex{CANONICAL_BUILD}
14639 @ovindex build
14640 @ovindex build_cpu
14641 @ovindex build_vendor
14642 @ovindex build_os
14643 Compute the canonical build-system type variable, @code{build}, and its
14644 three individual parts @code{build_cpu}, @code{build_vendor}, and
14645 @code{build_os}.
14647 If @option{--build} was specified, then @code{build} is the
14648 canonicalization of @code{build_alias} by @command{config.sub},
14649 otherwise it is determined by the shell script @command{config.guess}.
14650 @end defmac
14652 @defmac AC_CANONICAL_HOST
14653 @acindex{CANONICAL_HOST}
14654 @ovindex host
14655 @ovindex host_cpu
14656 @ovindex host_vendor
14657 @ovindex host_os
14658 Compute the canonical host-system type variable, @code{host}, and its
14659 three individual parts @code{host_cpu}, @code{host_vendor}, and
14660 @code{host_os}.
14662 If @option{--host} was specified, then @code{host} is the
14663 canonicalization of @code{host_alias} by @command{config.sub},
14664 otherwise it defaults to @code{build}.
14665 @end defmac
14667 @defmac AC_CANONICAL_TARGET
14668 @acindex{CANONICAL_TARGET}
14669 @ovindex target
14670 @ovindex target_cpu
14671 @ovindex target_vendor
14672 @ovindex target_os
14673 Compute the canonical target-system type variable, @code{target}, and its
14674 three individual parts @code{target_cpu}, @code{target_vendor}, and
14675 @code{target_os}.
14677 If @option{--target} was specified, then @code{target} is the
14678 canonicalization of @code{target_alias} by @command{config.sub},
14679 otherwise it defaults to @code{host}.
14680 @end defmac
14682 Note that there can be artifacts due to the backward compatibility
14683 code.  See @xref{Hosts and Cross-Compilation}, for more.
14685 @node Using System Type
14686 @section Using the System Type
14688 In @file{configure.ac} the system type is generally used by one or more
14689 @code{case} statements to select system-specifics.  Shell wildcards can
14690 be used to match a group of system types.
14692 For example, an extra assembler code object file could be chosen, giving
14693 access to a CPU cycle counter register.  @code{$(CYCLE_OBJ)} in the
14694 following would be used in a @file{Makefile} to add the object to a
14695 program or library.
14697 @example
14698 case $host in
14699   alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
14700   i?86-*-*)   CYCLE_OBJ=rdtsc.o ;;
14701   *)          CYCLE_OBJ= ;;
14702 esac
14703 AC_SUBST([CYCLE_OBJ])
14704 @end example
14706 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
14707 to select variant source files, for example optimized code for some
14708 CPUs.  The configured CPU type doesn't always indicate exact CPU types,
14709 so some runtime capability checks may be necessary too.
14711 @example
14712 case $host in
14713   alpha*-*-*)   AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
14714   powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
14715   *-*-*)        AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
14716 esac
14717 @end example
14719 The host system type can also be used to find cross-compilation tools
14720 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
14722 The above examples all show @samp{$host}, since this is where the code
14723 is going to run.  Only rarely is it necessary to test @samp{$build}
14724 (which is where the build is being done).
14726 Whenever you're tempted to use @samp{$host} it's worth considering
14727 whether some sort of probe would be better.  New system types come along
14728 periodically or previously missing features are added.  Well-written
14729 probes can adapt themselves to such things, but hard-coded lists of
14730 names won't.  Here are some guidelines,
14732 @itemize @bullet
14733 @item
14734 Availability of libraries and library functions should always be checked
14735 by probing.
14736 @item
14737 Variant behavior of system calls is best identified with runtime tests
14738 if possible, but bug workarounds or obscure difficulties might have to
14739 be driven from @samp{$host}.
14740 @item
14741 Assembler code is inevitably highly CPU-specific and is best selected
14742 according to @samp{$host_cpu}.
14743 @item
14744 Assembler variations like underscore prefix on globals or ELF versus
14745 COFF type directives are however best determined by probing, perhaps
14746 even examining the compiler output.
14747 @end itemize
14749 @samp{$target} is for use by a package creating a compiler or similar.
14750 For ordinary packages it's meaningless and should not be used.  It
14751 indicates what the created compiler should generate code for, if it can
14752 cross-compile.  @samp{$target} generally selects various hard-coded CPU
14753 and system conventions, since usually the compiler or tools under
14754 construction will themselves determine how the target will work.
14757 @c ===================================================== Site Configuration.
14759 @node Site Configuration
14760 @chapter Site Configuration
14762 @command{configure} scripts support several kinds of local configuration
14763 decisions.  There are ways for users to specify where external software
14764 packages are, include or exclude optional features, install programs
14765 under modified names, and set default values for @command{configure}
14766 options.
14768 @menu
14769 * Help Formatting::             Customizing @samp{configure --help}
14770 * External Software::           Working with other optional software
14771 * Package Options::             Selecting optional features
14772 * Pretty Help Strings::         Formatting help string
14773 * Site Details::                Configuring site details
14774 * Transforming Names::          Changing program names when installing
14775 * Site Defaults::               Giving @command{configure} local defaults
14776 @end menu
14778 @node Help Formatting
14779 @section Controlling Help Output
14781 Users will consult @samp{configure --help} to learn of configuration
14782 decisions specific to your package.  By default, @command{configure}
14783 breaks this output into sections for each type of option; within each
14784 section, help strings appear in the order @file{configure.ac} defines
14785 them:
14787 @example
14788 Optional Features:
14789   @dots{}
14790   --enable-bar            include bar
14792 Optional Packages:
14793   @dots{}
14794   --with-foo              use foo
14795 @end example
14797 @defmac AC_PRESERVE_HELP_ORDER
14798 @acindex{PRESERVE_HELP_ORDER}
14800 Request an alternate @option{--help} format, in which options of all
14801 types appear together, in the order defined.  Call this macro before any
14802 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
14804 @example
14805 Optional Features and Packages:
14806   @dots{}
14807   --enable-bar            include bar
14808   --with-foo              use foo
14809 @end example
14811 @end defmac
14813 @node External Software
14814 @section Working With External Software
14815 @cindex External software
14817 Some packages require, or can optionally use, other software packages
14818 that are already installed.  The user can give @command{configure}
14819 command line options to specify which such external software to use.
14820 The options have one of these forms:
14822 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
14823 @c awful.
14824 @example
14825 --with-@var{package}[=@var{arg}]
14826 --without-@var{package}
14827 @end example
14829 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
14830 instead of some other linker.  @option{--with-x} means work with The X
14831 Window System.
14833 The user can give an argument by following the package name with
14834 @samp{=} and the argument.  Giving an argument of @samp{no} is for
14835 packages that are used by default; it says to @emph{not} use the
14836 package.  An argument that is neither @samp{yes} nor @samp{no} could
14837 include a name or number of a version of the other package, to specify
14838 more precisely which other package this program is supposed to work
14839 with.  If no argument is given, it defaults to @samp{yes}.
14840 @option{--without-@var{package}} is equivalent to
14841 @option{--with-@var{package}=no}.
14843 @command{configure} scripts do not complain about
14844 @option{--with-@var{package}} options that they do not support.  This
14845 behavior permits configuring a source tree containing multiple packages
14846 with a top-level @command{configure} script when the packages support
14847 different options, without spurious error messages about options that
14848 some of the packages support.  An unfortunate side effect is that option
14849 spelling errors are not diagnosed.  No better approach to this problem
14850 has been suggested so far.
14852 For each external software package that may be used, @file{configure.ac}
14853 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
14854 user asked to use it.  Whether each package is used or not by default,
14855 and which arguments are valid, is up to you.
14857 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
14858 @acindex{ARG_WITH}
14859 If the user gave @command{configure} the option @option{--with-@var{package}}
14860 or @option{--without-@var{package}}, run shell commands
14861 @var{action-if-given}.  If neither option was given, run shell commands
14862 @var{action-if-not-given}.  The name @var{package} indicates another
14863 software package that this program should work with.  It should consist
14864 only of alphanumeric characters and dashes.
14866 The option's argument is available to the shell commands
14867 @var{action-if-given} in the shell variable @code{withval}, which is
14868 actually just the value of the shell variable @code{with_@var{package}},
14869 with any @option{-} characters changed into @samp{_}.  You may use that
14870 variable instead, if you wish.
14872 The argument @var{help-string} is a description of the option that
14873 looks like this:
14874 @example
14875   --with-readline         support fancy command line editing
14876 @end example
14878 @noindent
14879 @var{help-string} may be more than one line long, if more detail is
14880 needed.  Just make sure the columns line up in @samp{configure
14881 --help}.  Avoid tabs in the help string.  You'll need to enclose the
14882 help string in @samp{[} and @samp{]} in order to produce the leading
14883 blanks.
14885 You should format your @var{help-string} with the macro
14886 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
14888 The following example shows how to use the @code{AC_ARG_WITH} macro in
14889 a common situation.  You want to let the user decide whether to enable
14890 support for an external library (e.g., the readline library); if the user
14891 specified neither @option{--with-readline} nor @option{--without-readline},
14892 you want to enable support for readline only if the library is available
14893 on the system.
14895 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14896 @example
14897 AC_ARG_WITH([readline],
14898   [AS_HELP_STRING([--with-readline],
14899     [support fancy command line editing @@<:@@default=check@@:>@@])],
14900   [],
14901   [with_readline=check])
14903 LIBREADLINE=
14904 AS_IF([test "x$with_readline" != xno],
14905   [AC_CHECK_LIB([readline], [main],
14906     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14907      AC_DEFINE([HAVE_LIBREADLINE], [1],
14908                [Define if you have libreadline])
14909     ],
14910     [if test "x$with_readline" != xcheck; then
14911        AC_MSG_FAILURE(
14912          [--with-readline was given, but test for readline failed])
14913      fi
14914     ], -lncurses)])
14915 @end example
14917 The next example shows how to use @code{AC_ARG_WITH} to give the user the
14918 possibility to enable support for the readline library, in case it is still
14919 experimental and not well tested, and is therefore disabled by default.
14921 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14922 @example
14923 AC_ARG_WITH([readline],
14924   [AS_HELP_STRING([--with-readline],
14925     [enable experimental support for readline])],
14926   [],
14927   [with_readline=no])
14929 LIBREADLINE=
14930 AS_IF([test "x$with_readline" != xno],
14931   [AC_CHECK_LIB([readline], [main],
14932     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14933      AC_DEFINE([HAVE_LIBREADLINE], [1],
14934                [Define if you have libreadline])
14935     ],
14936     [AC_MSG_FAILURE(
14937        [--with-readline was given, but test for readline failed])],
14938     [-lncurses])])
14939 @end example
14941 The last example shows how to use @code{AC_ARG_WITH} to give the user the
14942 possibility to disable support for the readline library, given that it is
14943 an important feature and that it should be enabled by default.
14945 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
14946 @example
14947 AC_ARG_WITH([readline],
14948   [AS_HELP_STRING([--without-readline],
14949     [disable support for readline])],
14950   [],
14951   [with_readline=yes])
14953 LIBREADLINE=
14954 AS_IF([test "x$with_readline" != xno],
14955   [AC_CHECK_LIB([readline], [main],
14956     [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
14957      AC_DEFINE([HAVE_LIBREADLINE], [1],
14958                [Define if you have libreadline])
14959     ],
14960     [AC_MSG_FAILURE(
14961        [readline test failed (--without-readline to disable)])],
14962     [-lncurses])])
14963 @end example
14965 These three examples can be easily adapted to the case where
14966 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
14967 @ref{Package Options}).
14968 @end defmac
14970 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
14971 @acindex{WITH}
14972 This is an obsolete version of @code{AC_ARG_WITH} that does not
14973 support providing a help string.
14974 @end defmac
14976 @node Package Options
14977 @section Choosing Package Options
14978 @cindex Package options
14979 @cindex Options, package
14981 If a software package has optional compile-time features, the user can
14982 give @command{configure} command line options to specify whether to
14983 compile them.  The options have one of these forms:
14985 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
14986 @c awful.
14987 @example
14988 --enable-@var{feature}[=@var{arg}]
14989 --disable-@var{feature}
14990 @end example
14992 These options allow users to choose which optional features to build and
14993 install.  @option{--enable-@var{feature}} options should never make a
14994 feature behave differently or cause one feature to replace another.
14995 They should only cause parts of the program to be built rather than left
14996 out.
14998 The user can give an argument by following the feature name with
14999 @samp{=} and the argument.  Giving an argument of @samp{no} requests
15000 that the feature @emph{not} be made available.  A feature with an
15001 argument looks like @option{--enable-debug=stabs}.  If no argument is
15002 given, it defaults to @samp{yes}.  @option{--disable-@var{feature}} is
15003 equivalent to @option{--enable-@var{feature}=no}.
15005 @command{configure} scripts do not complain about
15006 @option{--enable-@var{feature}} options that they do not support.
15007 This behavior permits configuring a source tree containing multiple
15008 packages with a top-level @command{configure} script when the packages
15009 support different options, without spurious error messages about options
15010 that some of the packages support.
15011 An unfortunate side effect is that option spelling errors are not diagnosed.
15012 No better approach to this problem has been suggested so far.
15014 For each optional feature, @file{configure.ac} should call
15015 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
15016 to include it.  Whether each feature is included or not by default, and
15017 which arguments are valid, is up to you.
15019 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15020 @acindex{ARG_ENABLE}
15021 If the user gave @command{configure} the option
15022 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
15023 shell commands @var{action-if-given}.  If neither option was given, run
15024 shell commands @var{action-if-not-given}.  The name @var{feature}
15025 indicates an optional user-level facility.  It should consist only of
15026 alphanumeric characters and dashes.
15028 The option's argument is available to the shell commands
15029 @var{action-if-given} in the shell variable @code{enableval}, which is
15030 actually just the value of the shell variable
15031 @code{enable_@var{feature}}, with any @option{-} characters changed into
15032 @samp{_}.  You may use that variable instead, if you wish.  The
15033 @var{help-string} argument is like that of @code{AC_ARG_WITH}
15034 (@pxref{External Software}).
15036 You should format your @var{help-string} with the macro
15037 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15039 See the examples suggested with the definition of @code{AC_ARG_WITH}
15040 (@pxref{External Software}) to get an idea of possible applications of
15041 @code{AC_ARG_ENABLE}.
15042 @end defmac
15044 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
15045 @acindex{ENABLE}
15046 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
15047 support providing a help string.
15048 @end defmac
15051 @node Pretty Help Strings
15052 @section Making Your Help Strings Look Pretty
15053 @cindex Help strings
15055 Properly formatting the @samp{help strings} which are used in
15056 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
15057 (@pxref{Package Options}) can be challenging.  Specifically, you want
15058 your own @samp{help strings} to line up in the appropriate columns of
15059 @samp{configure --help} just like the standard Autoconf @samp{help
15060 strings} do.  This is the purpose of the @code{AS_HELP_STRING} macro.
15062 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
15063 @acindex{HELP_STRING}
15065 Expands into an help string that looks pretty when the user executes
15066 @samp{configure --help}.  It is typically used in @code{AC_ARG_WITH}
15067 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
15068 Options}).  The following example will make this clearer.
15070 @example
15071 AC_ARG_WITH([foo],
15072   [AS_HELP_STRING([--with-foo],
15073      [use foo (default is no)])],
15074   [use_foo=$withval],
15075   [use_foo=no])
15076 @end example
15078 The second argument of @code{AS_HELP_STRING} is
15079 not a literal, and should not be double quoted.
15080 @xref{Autoconf Language}, for a more detailed explanation.
15081 Then the last few lines of @samp{configure --help} will appear like
15082 this:
15084 @example
15085 --enable and --with options recognized:
15086   --with-foo              use foo (default is no)
15087 @end example
15089 The @code{AS_HELP_STRING} macro is particularly helpful when the
15090 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
15091 arguments, as shown in the following example.
15093 @example
15094 AC_DEFUN([MY_ARG_WITH],
15095   [AC_ARG_WITH([$1],
15096      [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
15097      [use_[]$1=$withval],
15098      [use_[]$1=$2])])
15099 @end example
15100 @end defmac
15103 @node Site Details
15104 @section Configuring Site Details
15105 @cindex Site details
15107 Some software packages require complex site-specific information.  Some
15108 examples are host names to use for certain services, company names, and
15109 email addresses to contact.  Since some configuration scripts generated
15110 by Metaconfig ask for such information interactively, people sometimes
15111 wonder how to get that information in Autoconf-generated configuration
15112 scripts, which aren't interactive.
15114 Such site configuration information should be put in a file that is
15115 edited @emph{only by users}, not by programs.  The location of the file
15116 can either be based on the @code{prefix} variable, or be a standard
15117 location such as the user's home directory.  It could even be specified
15118 by an environment variable.  The programs should examine that file at
15119 runtime, rather than at compile time.  Runtime configuration is more
15120 convenient for users and makes the configuration process simpler than
15121 getting the information while configuring.  @xref{Directory Variables, ,
15122 Variables for Installation Directories, standards, @acronym{GNU} Coding
15123 Standards}, for more information on where to put data files.
15125 @node Transforming Names
15126 @section Transforming Program Names When Installing
15127 @cindex Transforming program names
15128 @cindex Program names, transforming
15130 Autoconf supports changing the names of programs when installing them.
15131 In order to use these transformations, @file{configure.ac} must call the
15132 macro @code{AC_ARG_PROGRAM}.
15134 @defmac AC_ARG_PROGRAM
15135 @acindex{ARG_PROGRAM}
15136 @ovindex program_transform_name
15137 Place in output variable @code{program_transform_name} a sequence of
15138 @code{sed} commands for changing the names of installed programs.
15140 If any of the options described below are given to @command{configure},
15141 program names are transformed accordingly.  Otherwise, if
15142 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
15143 is given, the target type followed by a dash is used as a prefix.
15144 Otherwise, no program name transformation is done.
15145 @end defmac
15147 @menu
15148 * Transformation Options::      @command{configure} options to transform names
15149 * Transformation Examples::     Sample uses of transforming names
15150 * Transformation Rules::        @file{Makefile} uses of transforming names
15151 @end menu
15153 @node Transformation Options
15154 @subsection Transformation Options
15156 You can specify name transformations by giving @command{configure} these
15157 command line options:
15159 @table @option
15160 @item --program-prefix=@var{prefix}
15161 prepend @var{prefix} to the names;
15163 @item --program-suffix=@var{suffix}
15164 append @var{suffix} to the names;
15166 @item --program-transform-name=@var{expression}
15167 perform @code{sed} substitution @var{expression} on the names.
15168 @end table
15170 @node Transformation Examples
15171 @subsection Transformation Examples
15173 These transformations are useful with programs that can be part of a
15174 cross-compilation development environment.  For example, a
15175 cross-assembler running on a Sun 4 configured with
15176 @option{--target=i960-vxworks} is normally installed as
15177 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
15178 with a native Sun 4 assembler.
15180 You can force a program name to begin with @file{g}, if you don't want
15181 @acronym{GNU} programs installed on your system to shadow other programs with
15182 the same name.  For example, if you configure @acronym{GNU} @code{diff} with
15183 @option{--program-prefix=g}, then when you run @samp{make install} it is
15184 installed as @file{/usr/local/bin/gdiff}.
15186 As a more sophisticated example, you could use
15188 @example
15189 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
15190 @end example
15191 @noindent
15193 to prepend @samp{g} to most of the program names in a source tree,
15194 excepting those like @code{gdb} that already have one and those like
15195 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs.  (That is
15196 assuming that you have a source tree containing those programs that is
15197 set up to use this feature.)
15199 One way to install multiple versions of some programs simultaneously is
15200 to append a version number to the name of one or both.  For example, if
15201 you want to keep Autoconf version 1 around for awhile, you can configure
15202 Autoconf version 2 using @option{--program-suffix=2} to install the
15203 programs as @file{/usr/local/bin/autoconf2},
15204 @file{/usr/local/bin/autoheader2}, etc.  Nevertheless, pay attention
15205 that only the binaries are renamed, therefore you'd have problems with
15206 the library files which might overlap.
15208 @node Transformation Rules
15209 @subsection Transformation Rules
15211 Here is how to use the variable @code{program_transform_name} in a
15212 @file{Makefile.in}:
15214 @example
15215 PROGRAMS = cp ls rm
15216 transform = @@program_transform_name@@
15217 install:
15218         for p in $(PROGRAMS); do \
15219           $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
15220                                               sed '$(transform)'`; \
15221         done
15223 uninstall:
15224         for p in $(PROGRAMS); do \
15225           rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
15226         done
15227 @end example
15229 It is guaranteed that @code{program_transform_name} is never empty, and
15230 that there are no useless separators.  Therefore you may safely embed
15231 @code{program_transform_name} within a sed program using @samp{;}:
15233 @example
15234 transform = @@program_transform_name@@
15235 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
15236 @end example
15238 Whether to do the transformations on documentation files (Texinfo or
15239 @code{man}) is a tricky question; there seems to be no perfect answer,
15240 due to the several reasons for name transforming.  Documentation is not
15241 usually particular to a specific architecture, and Texinfo files do not
15242 conflict with system documentation.  But they might conflict with
15243 earlier versions of the same files, and @code{man} pages sometimes do
15244 conflict with system documentation.  As a compromise, it is probably
15245 best to do name transformations on @code{man} pages but not on Texinfo
15246 manuals.
15248 @node Site Defaults
15249 @section Setting Site Defaults
15250 @cindex Site defaults
15252 Autoconf-generated @command{configure} scripts allow your site to provide
15253 default values for some configuration values.  You do this by creating
15254 site- and system-wide initialization files.
15256 @evindex CONFIG_SITE
15257 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
15258 uses its value as the name of a shell script to read.  Otherwise, it
15259 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
15260 then @file{@var{prefix}/etc/config.site} if it exists.  Thus,
15261 settings in machine-specific files override those in machine-independent
15262 ones in case of conflict.
15264 Site files can be arbitrary shell scripts, but only certain kinds of
15265 code are really appropriate to be in them.  Because @command{configure}
15266 reads any cache file after it has read any site files, a site file can
15267 define a default cache file to be shared between all Autoconf-generated
15268 @command{configure} scripts run on that system (@pxref{Cache Files}).  If
15269 you set a default cache file in a site file, it is a good idea to also
15270 set the output variable @code{CC} in that site file, because the cache
15271 file is only valid for a particular compiler, but many systems have
15272 several available.
15274 You can examine or override the value set by a command line option to
15275 @command{configure} in a site file; options set shell variables that have
15276 the same names as the options, with any dashes turned into underscores.
15277 The exceptions are that @option{--without-} and @option{--disable-} options
15278 are like giving the corresponding @option{--with-} or @option{--enable-}
15279 option and the value @samp{no}.  Thus, @option{--cache-file=localcache}
15280 sets the variable @code{cache_file} to the value @samp{localcache};
15281 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
15282 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
15283 variable @code{prefix} to the value @samp{/usr}; etc.
15285 Site files are also good places to set default values for other output
15286 variables, such as @code{CFLAGS}, if you need to give them non-default
15287 values: anything you would normally do, repetitively, on the command
15288 line.  If you use non-default values for @var{prefix} or
15289 @var{exec_prefix} (wherever you locate the site file), you can set them
15290 in the site file if you specify it with the @code{CONFIG_SITE}
15291 environment variable.
15293 You can set some cache values in the site file itself.  Doing this is
15294 useful if you are cross-compiling, where it is impossible to check features
15295 that require running a test program.  You could ``prime the cache'' by
15296 setting those values correctly for that system in
15297 @file{@var{prefix}/etc/config.site}.  To find out the names of the cache
15298 variables you need to set, look for shell variables with @samp{_cv_} in
15299 their names in the affected @command{configure} scripts, or in the Autoconf
15300 M4 source code for those macros.
15302 The cache file is careful to not override any variables set in the site
15303 files.  Similarly, you should not override command-line options in the
15304 site files.  Your code should check that variables such as @code{prefix}
15305 and @code{cache_file} have their default values (as set near the top of
15306 @command{configure}) before changing them.
15308 Here is a sample file @file{/usr/share/local/gnu/share/config.site}.  The
15309 command @samp{configure --prefix=/usr/share/local/gnu} would read this
15310 file (if @code{CONFIG_SITE} is not set to a different file).
15312 @example
15313 # config.site for configure
15315 # Change some defaults.
15316 test "$prefix" = NONE && prefix=/usr/share/local/gnu
15317 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
15318 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
15319 test "$localstatedir" = '$prefix/var' && localstatedir=/var
15321 # Give Autoconf 2.x generated configure scripts a shared default
15322 # cache file for feature test results, architecture-specific.
15323 if test "$cache_file" = /dev/null; then
15324   cache_file="$prefix/var/config.cache"
15325   # A cache file is only valid for one C compiler.
15326   CC=gcc
15328 @end example
15331 @c ============================================== Running configure Scripts.
15333 @node Running configure Scripts
15334 @chapter Running @command{configure} Scripts
15335 @cindex @command{configure}
15337 Below are instructions on how to configure a package that uses a
15338 @command{configure} script, suitable for inclusion as an @file{INSTALL}
15339 file in the package.  A plain-text version of @file{INSTALL} which you
15340 may use comes with Autoconf.
15342 @menu
15343 * Basic Installation::          Instructions for typical cases
15344 * Compilers and Options::       Selecting compilers and optimization
15345 * Multiple Architectures::      Compiling for multiple architectures at once
15346 * Installation Names::          Installing in different directories
15347 * Optional Features::           Selecting optional features
15348 * System Type::                 Specifying the system type
15349 * Sharing Defaults::            Setting site-wide defaults for @command{configure}
15350 * Defining Variables::          Specifying the compiler etc.
15351 * configure Invocation::        Changing how @command{configure} runs
15352 @end menu
15354 @set autoconf
15355 @include install.texi
15358 @c ============================================== Recreating a Configuration
15360 @node config.status Invocation
15361 @chapter Recreating a Configuration
15362 @cindex @command{config.status}
15364 The @command{configure} script creates a file named @file{config.status},
15365 which actually configures, @dfn{instantiates}, the template files.  It
15366 also records the configuration options that were specified when the
15367 package was last configured in case reconfiguring is needed.
15369 Synopsis:
15370 @example
15371 ./config.status @var{option}@dots{} [@var{file}@dots{}]
15372 @end example
15374 It configures the @var{files}; if none are specified, all the templates
15375 are instantiated.  The files must be specified without their
15376 dependencies, as in
15378 @example
15379 ./config.status foobar
15380 @end example
15382 @noindent
15385 @example
15386 ./config.status foobar:foo.in:bar.in
15387 @end example
15389 The supported @var{option}s are:
15391 @table @option
15392 @item --help
15393 @itemx -h
15394 Print a summary of the command line options, the list of the template
15395 files, and exit.
15397 @item --version
15398 @itemx -V
15399 Print the version number of Autoconf and exit.
15401 @item --silent
15402 @itemx --quiet
15403 @itemx -q
15404 Do not print progress messages.
15406 @item --debug
15407 @itemx -d
15408 Don't remove the temporary files.
15410 @item --file=@var{file}[:@var{template}]
15411 Require that @var{file} be instantiated as if
15412 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used.  Both
15413 @var{file} and @var{template} may be @samp{-} in which case the standard
15414 output and/or standard input, respectively, is used.  If a
15415 @var{template} file name is relative, it is first looked for in the build
15416 tree, and then in the source tree.  @xref{Configuration Actions}, for
15417 more details.
15419 This option and the following ones provide one way for separately
15420 distributed packages to share the values computed by @command{configure}.
15421 Doing so can be useful if some of the packages need a superset of the
15422 features that one of them, perhaps a common library, does.  These
15423 options allow a @file{config.status} file to create files other than the
15424 ones that its @file{configure.ac} specifies, so it can be used for a
15425 different package.
15427 @item --header=@var{file}[:@var{template}]
15428 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
15430 @item --recheck
15431 Ask @file{config.status} to update itself and exit (no instantiation).
15432 This option is useful if you change @command{configure}, so that the
15433 results of some tests might be different from the previous run.  The
15434 @option{--recheck} option re-runs @command{configure} with the same arguments
15435 you used before, plus the @option{--no-create} option, which prevents
15436 @command{configure} from running @file{config.status} and creating
15437 @file{Makefile} and other files, and the @option{--no-recursion} option,
15438 which prevents @command{configure} from running other @command{configure}
15439 scripts in subdirectories.  (This is so other @file{Makefile} rules can
15440 run @file{config.status} when it changes; @pxref{Automatic Remaking},
15441 for an example).
15442 @end table
15444 @file{config.status} checks several optional environment variables that
15445 can alter its behavior:
15447 @defvar CONFIG_SHELL
15448 @evindex CONFIG_SHELL
15449 The shell with which to run @command{configure} for the @option{--recheck}
15450 option.  It must be Bourne-compatible.  The default is a shell that
15451 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
15452 Invoking @command{configure} by hand bypasses this setting, so you may
15453 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
15454 to insure that the same shell is used everywhere.  The absolute name of the
15455 shell should be passed.
15456 @end defvar
15458 @defvar CONFIG_STATUS
15459 @evindex CONFIG_STATUS
15460 The file name to use for the shell script that records the
15461 configuration.  The default is @file{./config.status}.  This variable is
15462 useful when one package uses parts of another and the @command{configure}
15463 scripts shouldn't be merged because they are maintained separately.
15464 @end defvar
15466 You can use @file{./config.status} in your Makefiles.  For example, in
15467 the dependencies given above (@pxref{Automatic Remaking}),
15468 @file{config.status} is run twice when @file{configure.ac} has changed.
15469 If that bothers you, you can make each run only regenerate the files for
15470 that rule:
15471 @example
15472 @group
15473 config.h: stamp-h
15474 stamp-h: config.h.in config.status
15475         ./config.status config.h
15476         echo > stamp-h
15478 Makefile: Makefile.in config.status
15479         ./config.status Makefile
15480 @end group
15481 @end example
15483 The calling convention of @file{config.status} has changed; see
15484 @ref{Obsolete config.status Use}, for details.
15487 @c =================================================== Obsolete Constructs
15489 @node Obsolete Constructs
15490 @chapter Obsolete Constructs
15491 @cindex Obsolete constructs
15493 Autoconf changes, and throughout the years some constructs have been
15494 obsoleted.  Most of the changes involve the macros, but in some cases
15495 the tools themselves, or even some concepts, are now considered
15496 obsolete.
15498 You may completely skip this chapter if you are new to Autoconf.  Its
15499 intention is mainly to help maintainers updating their packages by
15500 understanding how to move to more modern constructs.
15502 @menu
15503 * Obsolete config.status Use::  Different calling convention
15504 * acconfig.h::                  Additional entries in @file{config.h.in}
15505 * autoupdate Invocation::       Automatic update of @file{configure.ac}
15506 * Obsolete Macros::             Backward compatibility macros
15507 * Autoconf 1::                  Tips for upgrading your files
15508 * Autoconf 2.13::               Some fresher tips
15509 @end menu
15511 @node Obsolete config.status Use
15512 @section Obsolete @file{config.status} Invocation
15514 @file{config.status} now supports arguments to specify the files to
15515 instantiate; see @ref{config.status Invocation}, for more details.
15516 Before, environment variables had to be used.
15518 @defvar CONFIG_COMMANDS
15519 @evindex CONFIG_COMMANDS
15520 The tags of the commands to execute.  The default is the arguments given
15521 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
15522 @file{configure.ac}.
15523 @end defvar
15525 @defvar CONFIG_FILES
15526 @evindex CONFIG_FILES
15527 The files in which to perform @samp{@@@var{variable}@@} substitutions.
15528 The default is the arguments given to @code{AC_OUTPUT} and
15529 @code{AC_CONFIG_FILES} in @file{configure.ac}.
15530 @end defvar
15532 @defvar CONFIG_HEADERS
15533 @evindex CONFIG_HEADERS
15534 The files in which to substitute C @code{#define} statements.  The
15535 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
15536 macro was not called, @file{config.status} ignores this variable.
15537 @end defvar
15539 @defvar CONFIG_LINKS
15540 @evindex CONFIG_LINKS
15541 The symbolic links to establish.  The default is the arguments given to
15542 @code{AC_CONFIG_LINKS}; if that macro was not called,
15543 @file{config.status} ignores this variable.
15544 @end defvar
15546 In @ref{config.status Invocation}, using this old interface, the example
15547 would be:
15549 @example
15550 @group
15551 config.h: stamp-h
15552 stamp-h: config.h.in config.status
15553         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
15554           CONFIG_HEADERS=config.h ./config.status
15555         echo > stamp-h
15557 Makefile: Makefile.in config.status
15558         CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
15559           CONFIG_FILES=Makefile ./config.status
15560 @end group
15561 @end example
15563 @noindent
15564 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
15565 no need to set @code{CONFIG_HEADERS} in the @code{make} rules.  Equally
15566 for @code{CONFIG_COMMANDS}, etc.)
15569 @node acconfig.h
15570 @section @file{acconfig.h}
15572 @cindex @file{acconfig.h}
15573 @cindex @file{config.h.top}
15574 @cindex @file{config.h.bot}
15576 In order to produce @file{config.h.in}, @command{autoheader} needs to
15577 build or to find templates for each symbol.  Modern releases of Autoconf
15578 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
15579 Macros}), but in older releases a file, @file{acconfig.h}, contained the
15580 list of needed templates.  @command{autoheader} copied comments and
15581 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
15582 the current directory, if present.  This file used to be mandatory if
15583 you @code{AC_DEFINE} any additional symbols.
15585 Modern releases of Autoconf also provide @code{AH_TOP} and
15586 @code{AH_BOTTOM} if you need to prepend/append some information to
15587 @file{config.h.in}.  Ancient versions of Autoconf had a similar feature:
15588 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
15589 @command{autoheader} copies the lines before the line containing
15590 @samp{@@TOP@@} into the top of the file that it generates.  Similarly,
15591 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
15592 @command{autoheader} copies the lines after that line to the end of the
15593 file it generates.  Either or both of those strings may be omitted.  An
15594 even older alternate way to produce the same effect in ancient versions
15595 of Autoconf is to create the files @file{@var{file}.top} (typically
15596 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
15597 directory.  If they exist, @command{autoheader} copies them to the
15598 beginning and end, respectively, of its output.
15600 In former versions of Autoconf, the files used in preparing a software
15601 package for distribution were:
15602 @example
15603 @group
15604 configure.ac --.   .------> autoconf* -----> configure
15605                +---+
15606 [aclocal.m4] --+   `---.
15607 [acsite.m4] ---'       |
15608                        +--> [autoheader*] -> [config.h.in]
15609 [acconfig.h] ----.     |
15610                  +-----'
15611 [config.h.top] --+
15612 [config.h.bot] --'
15613 @end group
15614 @end example
15616 Using only the @code{AH_} macros, @file{configure.ac} should be
15617 self-contained, and should not depend upon @file{acconfig.h} etc.
15620 @node autoupdate Invocation
15621 @section Using @command{autoupdate} to Modernize @file{configure.ac}
15622 @cindex @command{autoupdate}
15624 The @command{autoupdate} program updates a @file{configure.ac} file that
15625 calls Autoconf macros by their old names to use the current macro names.
15626 In version 2 of Autoconf, most of the macros were renamed to use a more
15627 uniform and descriptive naming scheme.  @xref{Macro Names}, for a
15628 description of the new scheme.  Although the old names still work
15629 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
15630 new names), you can make your @file{configure.ac} files more readable
15631 and make it easier to use the current Autoconf documentation if you
15632 update them to use the new macro names.
15634 @evindex SIMPLE_BACKUP_SUFFIX
15635 If given no arguments, @command{autoupdate} updates @file{configure.ac},
15636 backing up the original version with the suffix @file{~} (or the value
15637 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
15638 set).  If you give @command{autoupdate} an argument, it reads that file
15639 instead of @file{configure.ac} and writes the updated file to the
15640 standard output.
15642 @noindent
15643 @command{autoupdate} accepts the following options:
15645 @table @option
15646 @item --help
15647 @itemx -h
15648 Print a summary of the command line options and exit.
15650 @item --version
15651 @itemx -V
15652 Print the version number of Autoconf and exit.
15654 @item --verbose
15655 @itemx -v
15656 Report processing steps.
15658 @item --debug
15659 @itemx -d
15660 Don't remove the temporary files.
15662 @item --force
15663 @itemx -f
15664 Force the update even if the file has not changed.  Disregard the cache.
15666 @item --include=@var{dir}
15667 @itemx -I @var{dir}
15668 Also look for input files in @var{dir}.  Multiple invocations accumulate.
15669 Directories are browsed from last to first.
15670 @end table
15672 @node Obsolete Macros
15673 @section Obsolete Macros
15675 Several macros are obsoleted in Autoconf, for various reasons (typically
15676 they failed to quote properly, couldn't be extended for more recent
15677 issues, etc.).  They are still supported, but deprecated: their use
15678 should be avoided.
15680 During the jump from Autoconf version 1 to version 2, most of the
15681 macros were renamed to use a more uniform and descriptive naming scheme,
15682 but their signature did not change.  @xref{Macro Names}, for a
15683 description of the new naming scheme.  Below, if there is just the mapping
15684 from old names to new names for these macros, the reader is invited to
15685 refer to the definition of the new macro for the signature and the
15686 description.
15688 @defmac AC_ALLOCA
15689 @acindex{ALLOCA}
15690 @code{AC_FUNC_ALLOCA}
15691 @end defmac
15693 @defmac AC_ARG_ARRAY
15694 @acindex{ARG_ARRAY}
15695 removed because of limited usefulness
15696 @end defmac
15698 @defmac AC_C_CROSS
15699 @acindex{C_CROSS}
15700 This macro is obsolete; it does nothing.
15701 @end defmac
15703 @defmac AC_C_LONG_DOUBLE
15704 @acindex{C_LONG_DOUBLE}
15705 @cvindex HAVE_LONG_DOUBLE
15706 If the C compiler supports a working @code{long double} type with more
15707 range or precision than the @code{double} type, define
15708 @code{HAVE_LONG_DOUBLE}.
15710 You should use @code{AC_TYPE_LONG_DOUBLE} or
15711 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
15712 @end defmac
15714 @defmac AC_CANONICAL_SYSTEM
15715 @acindex{CANONICAL_SYSTEM}
15716 Determine the system type and set output variables to the names of the
15717 canonical system types.  @xref{Canonicalizing}, for details about the
15718 variables this macro sets.
15720 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
15721 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
15722 the needs.  Using @code{AC_CANONICAL_TARGET} is enough to run the two
15723 other macros.
15724 @end defmac
15726 @defmac AC_CHAR_UNSIGNED
15727 @acindex{CHAR_UNSIGNED}
15728 @code{AC_C_CHAR_UNSIGNED}
15729 @end defmac
15731 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
15732 @acindex{CHECK_TYPE}
15733 Autoconf, up to 2.13, used to provide this version of
15734 @code{AC_CHECK_TYPE}, deprecated because of its flaws.  Firstly, although
15735 it is a member of the @code{CHECK} clan, singular sub-family, it does
15736 more than just checking.  Secondly, missing types are not
15737 @code{typedef}'d, they are @code{#define}'d, which can lead to
15738 incompatible code in the case of pointer types.
15740 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
15741 @ref{Generic Types}, for the description of the current macro.
15743 If the type @var{type} is not defined, define it to be the C (or C++)
15744 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
15746 This macro is equivalent to:
15748 @example
15749 AC_CHECK_TYPE([@var{type}], [],
15750   [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
15751      [Define to `@var{default}'
15752       if <sys/types.h> does not define.])])
15753 @end example
15755 In order to keep backward compatibility, the two versions of
15756 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
15758 @enumerate
15759 @item
15760 If there are three or four arguments, the modern version is used.
15762 @item
15763 If the second argument appears to be a C or C++ type, then the
15764 obsolete version is used.  This happens if the argument is a C or C++
15765 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
15766 followed by one of @samp{[(* } and then by a string of zero or more
15767 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
15769 @item
15770 If the second argument is spelled with the alphabet of valid C and C++
15771 types, the user is warned and the modern version is used.
15773 @item
15774 Otherwise, the modern version is used.
15775 @end enumerate
15777 @noindent
15778 You are encouraged either to use a valid builtin type, or to use the
15779 equivalent modern code (see above), or better yet, to use
15780 @code{AC_CHECK_TYPES} together with
15782 @example
15783 #if !HAVE_LOFF_T
15784 typedef loff_t off_t;
15785 #endif
15786 @end example
15787 @end defmac
15788 @c end of AC_CHECK_TYPE
15790 @defmac AC_CHECKING (@var{feature-description})
15791 @acindex{CHECKING}
15792 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
15793 @end defmac
15795 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
15796 @acindex{COMPILE_CHECK}
15797 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
15798 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
15799 addition that it prints @samp{checking for @var{echo-text}} to the
15800 standard output first, if @var{echo-text} is non-empty.  Use
15801 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
15802 messages (@pxref{Printing Messages}).
15803 @end defmac
15805 @defmac AC_CONST
15806 @acindex{CONST}
15807 @code{AC_C_CONST}
15808 @end defmac
15810 @defmac AC_CROSS_CHECK
15811 @acindex{CROSS_CHECK}
15812 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
15813 @code{:-)}.
15814 @end defmac
15816 @defmac AC_CYGWIN
15817 @acindex{CYGWIN}
15818 Check for the Cygwin environment in which case the shell variable
15819 @code{CYGWIN} is set to @samp{yes}.  Don't use this macro, the dignified
15820 means to check the nature of the host is using
15821 @code{AC_CANONICAL_HOST}.  As a matter of fact this macro is defined as:
15823 @example
15824 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
15825 case $host_os in
15826   *cygwin* ) CYGWIN=yes;;
15827          * ) CYGWIN=no;;
15828 esac
15829 @end example
15831 Beware that the variable @code{CYGWIN} has a very special meaning when
15832 running Cygwin, and should not be changed.  That's yet another reason
15833 not to use this macro.
15834 @end defmac
15836 @defmac AC_DECL_SYS_SIGLIST
15837 @acindex{DECL_SYS_SIGLIST}
15838 @cvindex SYS_SIGLIST_DECLARED
15839 Same as:
15841 @example
15842 AC_CHECK_DECLS([sys_siglist], [], [],
15843 [#include <signal.h>
15844 /* NetBSD declares sys_siglist in unistd.h.  */
15845 #if HAVE_UNISTD_H
15846 # include <unistd.h>
15847 #endif
15849 @end example
15850 @end defmac
15852 @defmac AC_DECL_YYTEXT
15853 @acindex{DECL_YYTEXT}
15854 Does nothing, now integrated in @code{AC_PROG_LEX}.
15855 @end defmac
15857 @defmac AC_DIR_HEADER
15858 @acindex{DIR_HEADER}
15859 @cvindex DIRENT
15860 @cvindex SYSNDIR
15861 @cvindex SYSDIR
15862 @cvindex NDIR
15863 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
15864 but defines a different set of C preprocessor macros to indicate which
15865 header file is found:
15867 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
15868 @item Header            @tab Old Symbol     @tab New Symbol
15869 @item @file{dirent.h}   @tab @code{DIRENT}  @tab @code{HAVE_DIRENT_H}
15870 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
15871 @item @file{sys/dir.h}  @tab @code{SYSDIR}  @tab @code{HAVE_SYS_DIR_H}
15872 @item @file{ndir.h}     @tab @code{NDIR}    @tab @code{HAVE_NDIR_H}
15873 @end multitable
15874 @end defmac
15876 @defmac AC_DYNIX_SEQ
15877 @acindex{DYNIX_SEQ}
15878 If on DYNIX/ptx, add @option{-lseq} to output variable
15879 @code{LIBS}.  This macro used to be defined as
15881 @example
15882 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
15883 @end example
15885 @noindent
15886 now it is just @code{AC_FUNC_GETMNTENT}.
15887 @end defmac
15889 @defmac AC_EXEEXT
15890 @acindex{EXEEXT}
15891 @ovindex EXEEXT
15892 Defined the output variable @code{EXEEXT} based on the output of the
15893 compiler, which is now done automatically.  Typically set to empty
15894 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
15895 @end defmac
15897 @defmac AC_EMXOS2
15898 @acindex{EMXOS2}
15899 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
15900 and sets @code{EMXOS2}.
15901 @end defmac
15903 @defmac AC_ERROR
15904 @acindex{ERROR}
15905 @code{AC_MSG_ERROR}
15906 @end defmac
15908 @defmac AC_FIND_X
15909 @acindex{FIND_X}
15910 @code{AC_PATH_X}
15911 @end defmac
15913 @defmac AC_FIND_XTRA
15914 @acindex{FIND_XTRA}
15915 @code{AC_PATH_XTRA}
15916 @end defmac
15918 @defmac AC_FOREACH
15919 @acindex{FOREACH}
15920 @code{m4_foreach_w}
15921 @end defmac
15923 @defmac AC_FUNC_CHECK
15924 @acindex{FUNC_CHECK}
15925 @code{AC_CHECK_FUNC}
15926 @end defmac
15928 @defmac AC_FUNC_WAIT3
15929 @acindex{FUNC_WAIT3}
15930 @cvindex HAVE_WAIT3
15931 If @code{wait3} is found and fills in the contents of its third argument
15932 (a @samp{struct rusage *}), which HP-UX does not do, define
15933 @code{HAVE_WAIT3}.
15935 These days portable programs should use @code{waitpid}, not
15936 @code{wait3}, as @code{wait3} has been removed from Posix.
15937 @end defmac
15939 @defmac AC_GCC_TRADITIONAL
15940 @acindex{GCC_TRADITIONAL}
15941 @code{AC_PROG_GCC_TRADITIONAL}
15942 @end defmac
15944 @defmac AC_GETGROUPS_T
15945 @acindex{GETGROUPS_T}
15946 @code{AC_TYPE_GETGROUPS}
15947 @end defmac
15949 @defmac AC_GETLOADAVG
15950 @acindex{GETLOADAVG}
15951 @code{AC_FUNC_GETLOADAVG}
15952 @end defmac
15954 @defmac AC_HAVE_FUNCS
15955 @acindex{HAVE_FUNCS}
15956 @code{AC_CHECK_FUNCS}
15957 @end defmac
15959 @defmac AC_HAVE_HEADERS
15960 @acindex{HAVE_HEADERS}
15961 @code{AC_CHECK_HEADERS}
15962 @end defmac
15964 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
15965 @acindex{HAVE_LIBRARY}
15966 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
15967 @var{function} argument of @code{main}.  In addition, @var{library} can
15968 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}.  In
15969 all of those cases, the compiler is passed @option{-lfoo}.  However,
15970 @var{library} cannot be a shell variable; it must be a literal name.
15971 @end defmac
15973 @defmac AC_HAVE_POUNDBANG
15974 @acindex{HAVE_POUNDBANG}
15975 @code{AC_SYS_INTERPRETER} (different calling convention)
15976 @end defmac
15978 @defmac AC_HEADER_CHECK
15979 @acindex{HEADER_CHECK}
15980 @code{AC_CHECK_HEADER}
15981 @end defmac
15983 @defmac AC_HEADER_EGREP
15984 @acindex{HEADER_EGREP}
15985 @code{AC_EGREP_HEADER}
15986 @end defmac
15988 @defmac AC_HELP_STRING
15989 @acindex{HELP_STRING}
15990 @code{AS_HELP_STRING}
15991 @end defmac
15993 @defmac AC_INIT (@var{unique-file-in-source-dir})
15994 @acindex{INIT}
15995 Formerly @code{AC_INIT} used to have a single argument, and was
15996 equivalent to:
15998 @example
15999 AC_INIT
16000 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
16001 @end example
16002 @end defmac
16004 @defmac AC_INLINE
16005 @acindex{INLINE}
16006 @code{AC_C_INLINE}
16007 @end defmac
16009 @defmac AC_INT_16_BITS
16010 @acindex{INT_16_BITS}
16011 @cvindex INT_16_BITS
16012 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
16013 Use @samp{AC_CHECK_SIZEOF(int)} instead.
16014 @end defmac
16016 @defmac AC_IRIX_SUN
16017 @acindex{IRIX_SUN}
16018 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
16019 @code{LIBS}.  If you were using it to get @code{getmntent}, use
16020 @code{AC_FUNC_GETMNTENT} instead.  If you used it for the NIS versions
16021 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
16022 getpwnam)}.  Up to Autoconf 2.13, it used to be
16024 @example
16025 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
16026 @end example
16028 @noindent
16029 now it is defined as
16031 @example
16032 AC_FUNC_GETMNTENT
16033 AC_CHECK_LIB([sun], [getpwnam])
16034 @end example
16035 @end defmac
16037 @defmac AC_LANG_C
16038 @acindex{LANG_C}
16039 Same as @samp{AC_LANG([C])}.
16040 @end defmac
16042 @defmac AC_LANG_CPLUSPLUS
16043 @acindex{LANG_CPLUSPLUS}
16044 Same as @samp{AC_LANG([C++])}.
16045 @end defmac
16047 @defmac AC_LANG_FORTRAN77
16048 @acindex{LANG_FORTRAN77}
16049 Same as @samp{AC_LANG([Fortran 77])}.
16050 @end defmac
16052 @defmac AC_LANG_RESTORE
16053 @acindex{LANG_RESTORE}
16054 Select the @var{language} that is saved on the top of the stack, as set
16055 by @code{AC_LANG_SAVE}, remove it from the stack, and call
16056 @code{AC_LANG(@var{language})}.
16057 @end defmac
16059 @defmac AC_LANG_SAVE
16060 @acindex{LANG_SAVE}
16061 Remember the current language (as set by @code{AC_LANG}) on a stack.
16062 The current language does not change.  @code{AC_LANG_PUSH} is preferred.
16063 @end defmac
16065 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
16066 @acindex{LINK_FILES}
16067 This is an obsolete version of @code{AC_CONFIG_LINKS}.  An updated
16068 version of:
16070 @example
16071 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
16072               host.h            object.h)
16073 @end example
16075 @noindent
16078 @example
16079 AC_CONFIG_LINKS([host.h:config/$machine.h
16080                 object.h:config/$obj_format.h])
16081 @end example
16082 @end defmac
16084 @defmac AC_LN_S
16085 @acindex{LN_S}
16086 @code{AC_PROG_LN_S}
16087 @end defmac
16089 @defmac AC_LONG_64_BITS
16090 @acindex{LONG_64_BITS}
16091 @cvindex LONG_64_BITS
16092 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
16093 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
16094 @end defmac
16096 @defmac AC_LONG_DOUBLE
16097 @acindex{LONG_DOUBLE}
16098 If the C compiler supports a working @code{long double} type with more
16099 range or precision than the @code{double} type, define
16100 @code{HAVE_LONG_DOUBLE}.
16102 You should use @code{AC_TYPE_LONG_DOUBLE} or
16103 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead.  @xref{Particular Types}.
16104 @end defmac
16106 @defmac AC_LONG_FILE_NAMES
16107 @acindex{LONG_FILE_NAMES}
16108 @code{AC_SYS_LONG_FILE_NAMES}
16109 @end defmac
16111 @defmac AC_MAJOR_HEADER
16112 @acindex{MAJOR_HEADER}
16113 @code{AC_HEADER_MAJOR}
16114 @end defmac
16116 @defmac AC_MEMORY_H
16117 @acindex{MEMORY_H}
16118 @cvindex NEED_MEMORY_H
16119 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
16120 defined in @file{memory.h}.  Today it is equivalent to
16121 @samp{AC_CHECK_HEADERS([memory.h])}.  Adjust your code to depend upon
16122 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
16123 Symbols}.
16124 @end defmac
16126 @defmac AC_MINGW32
16127 @acindex{MINGW32}
16128 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
16129 environment and sets @code{MINGW32}.
16130 @end defmac
16132 @defmac AC_MINUS_C_MINUS_O
16133 @acindex{MINUS_C_MINUS_O}
16134 @code{AC_PROG_CC_C_O}
16135 @end defmac
16137 @defmac AC_MMAP
16138 @acindex{MMAP}
16139 @code{AC_FUNC_MMAP}
16140 @end defmac
16142 @defmac AC_MODE_T
16143 @acindex{MODE_T}
16144 @code{AC_TYPE_MODE_T}
16145 @end defmac
16147 @defmac AC_OBJEXT
16148 @acindex{OBJEXT}
16149 @ovindex OBJEXT
16150 Defined the output variable @code{OBJEXT} based on the output of the
16151 compiler, after .c files have been excluded.  Typically set to @samp{o}
16152 if Posix, @samp{obj} if a @acronym{DOS} variant.
16153 Now the compiler checking macros handle
16154 this automatically.
16155 @end defmac
16157 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
16158 @acindex{OBSOLETE}
16159 Make M4 print a message to the standard error output warning that
16160 @var{this-macro-name} is obsolete, and giving the file and line number
16161 where it was called.  @var{this-macro-name} should be the name of the
16162 macro that is calling @code{AC_OBSOLETE}.  If @var{suggestion} is given,
16163 it is printed at the end of the warning message; for example, it can be
16164 a suggestion for what to use instead of @var{this-macro-name}.
16166 For instance
16168 @example
16169 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
16170 @end example
16172 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
16173 services to the user.
16174 @end defmac
16176 @defmac AC_OFF_T
16177 @acindex{OFF_T}
16178 @code{AC_TYPE_OFF_T}
16179 @end defmac
16181 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
16182 @acindex{OUTPUT}
16183 The use of @code{AC_OUTPUT} with argument is deprecated.  This obsoleted
16184 interface is equivalent to:
16186 @example
16187 @group
16188 AC_CONFIG_FILES(@var{file}@dots{})
16189 AC_CONFIG_COMMANDS([default],
16190                    @var{extra-cmds}, @var{init-cmds})
16191 AC_OUTPUT
16192 @end group
16193 @end example
16194 @end defmac
16196 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
16197 @acindex{OUTPUT_COMMANDS}
16198 Specify additional shell commands to run at the end of
16199 @file{config.status}, and shell commands to initialize any variables
16200 from @command{configure}.  This macro may be called multiple times.  It is
16201 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
16203 Here is an unrealistic example:
16205 @example
16206 fubar=27
16207 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
16208                    [fubar=$fubar])
16209 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
16210                    [echo init bit])
16211 @end example
16213 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
16214 additional key, an important difference is that
16215 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
16216 @code{AC_CONFIG_COMMANDS}.  This means that @code{AC_CONFIG_COMMANDS}
16217 can safely be given macro calls as arguments:
16219 @example
16220 AC_CONFIG_COMMANDS(foo, [my_FOO()])
16221 @end example
16223 @noindent
16224 Conversely, where one level of quoting was enough for literal strings
16225 with @code{AC_OUTPUT_COMMANDS}, you need two with
16226 @code{AC_CONFIG_COMMANDS}.  The following lines are equivalent:
16228 @example
16229 @group
16230 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
16231 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
16232 @end group
16233 @end example
16234 @end defmac
16236 @defmac AC_PID_T
16237 @acindex{PID_T}
16238 @code{AC_TYPE_PID_T}
16239 @end defmac
16241 @defmac AC_PREFIX
16242 @acindex{PREFIX}
16243 @code{AC_PREFIX_PROGRAM}
16244 @end defmac
16246 @defmac AC_PROGRAMS_CHECK
16247 @acindex{PROGRAMS_CHECK}
16248 @code{AC_CHECK_PROGS}
16249 @end defmac
16251 @defmac AC_PROGRAMS_PATH
16252 @acindex{PROGRAMS_PATH}
16253 @code{AC_PATH_PROGS}
16254 @end defmac
16256 @defmac AC_PROGRAM_CHECK
16257 @acindex{PROGRAM_CHECK}
16258 @code{AC_CHECK_PROG}
16259 @end defmac
16261 @defmac AC_PROGRAM_EGREP
16262 @acindex{PROGRAM_EGREP}
16263 @code{AC_EGREP_CPP}
16264 @end defmac
16266 @defmac AC_PROGRAM_PATH
16267 @acindex{PROGRAM_PATH}
16268 @code{AC_PATH_PROG}
16269 @end defmac
16271 @defmac AC_REMOTE_TAPE
16272 @acindex{REMOTE_TAPE}
16273 removed because of limited usefulness
16274 @end defmac
16276 @defmac AC_RESTARTABLE_SYSCALLS
16277 @acindex{RESTARTABLE_SYSCALLS}
16278 @code{AC_SYS_RESTARTABLE_SYSCALLS}
16279 @end defmac
16281 @defmac AC_RETSIGTYPE
16282 @acindex{RETSIGTYPE}
16283 @code{AC_TYPE_SIGNAL}
16284 @end defmac
16286 @defmac AC_RSH
16287 @acindex{RSH}
16288 removed because of limited usefulness
16289 @end defmac
16291 @defmac AC_SCO_INTL
16292 @acindex{SCO_INTL}
16293 @ovindex LIBS
16294 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}.  This
16295 macro used to do this:
16297 @example
16298 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
16299 @end example
16301 @noindent
16302 Now it just calls @code{AC_FUNC_STRFTIME} instead.
16303 @end defmac
16305 @defmac AC_SETVBUF_REVERSED
16306 @acindex{SETVBUF_REVERSED}
16307 @code{AC_FUNC_SETVBUF_REVERSED}
16308 @end defmac
16310 @defmac AC_SET_MAKE
16311 @acindex{SET_MAKE}
16312 @code{AC_PROG_MAKE_SET}
16313 @end defmac
16315 @defmac AC_SIZEOF_TYPE
16316 @acindex{SIZEOF_TYPE}
16317 @code{AC_CHECK_SIZEOF}
16318 @end defmac
16320 @defmac AC_SIZE_T
16321 @acindex{SIZE_T}
16322 @code{AC_TYPE_SIZE_T}
16323 @end defmac
16325 @defmac AC_STAT_MACROS_BROKEN
16326 @acindex{STAT_MACROS_BROKEN}
16327 @code{AC_HEADER_STAT}
16328 @end defmac
16330 @defmac AC_STDC_HEADERS
16331 @acindex{STDC_HEADERS}
16332 @code{AC_HEADER_STDC}
16333 @end defmac
16335 @defmac AC_STRCOLL
16336 @acindex{STRCOLL}
16337 @code{AC_FUNC_STRCOLL}
16338 @end defmac
16340 @defmac AC_ST_BLKSIZE
16341 @acindex{ST_BLKSIZE}
16342 @code{AC_CHECK_MEMBERS}
16343 @end defmac
16345 @defmac AC_ST_BLOCKS
16346 @acindex{ST_BLOCKS}
16347 @code{AC_STRUCT_ST_BLOCKS}
16348 @end defmac
16350 @defmac AC_ST_RDEV
16351 @acindex{ST_RDEV}
16352 @code{AC_CHECK_MEMBERS}
16353 @end defmac
16355 @defmac AC_SYS_RESTARTABLE_SYSCALLS
16356 @acindex{SYS_RESTARTABLE_SYSCALLS}
16357 @cvindex HAVE_RESTARTABLE_SYSCALLS
16358 If the system automatically restarts a system call that is interrupted
16359 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}.  This macro does
16360 not check whether system calls are restarted in general---it checks whether a
16361 signal handler installed with @code{signal} (but not @code{sigaction})
16362 causes system calls to be restarted.  It does not check whether system calls
16363 can be restarted when interrupted by signals that have no handler.
16365 These days portable programs should use @code{sigaction} with
16366 @code{SA_RESTART} if they want restartable system calls.  They should
16367 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
16368 system call is restartable is a dynamic issue, not a configuration-time
16369 issue.
16370 @end defmac
16372 @defmac AC_SYS_SIGLIST_DECLARED
16373 @acindex{SYS_SIGLIST_DECLARED}
16374 @code{AC_DECL_SYS_SIGLIST}
16375 @end defmac
16377 @defmac AC_TEST_CPP
16378 @acindex{TEST_CPP}
16379 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
16380 @end defmac
16382 @defmac AC_TEST_PROGRAM
16383 @acindex{TEST_PROGRAM}
16384 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
16385 @end defmac
16387 @defmac AC_TIMEZONE
16388 @acindex{TIMEZONE}
16389 @code{AC_STRUCT_TIMEZONE}
16390 @end defmac
16392 @defmac AC_TIME_WITH_SYS_TIME
16393 @acindex{TIME_WITH_SYS_TIME}
16394 @code{AC_HEADER_TIME}
16395 @end defmac
16397 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16398 @acindex{TRY_COMPILE}
16399 Same as:
16401 @example
16402 AC_COMPILE_IFELSE(
16403   [AC_LANG_PROGRAM([[@var{includes}]],
16404      [[@var{function-body}]])],
16405   [@var{action-if-true}],
16406   [@var{action-if-false}])
16407 @end example
16409 @noindent
16410 @xref{Running the Compiler}.
16412 This macro double quotes both @var{includes} and @var{function-body}.
16414 For C and C++, @var{includes} is any @code{#include} statements needed
16415 by the code in @var{function-body} (@var{includes} will be ignored if
16416 the currently selected language is Fortran or Fortran 77).  The compiler
16417 and compilation flags are determined by the current language
16418 (@pxref{Language Choice}).
16419 @end defmac
16421 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
16422 @acindex{TRY_CPP}
16423 Same as:
16425 @example
16426 AC_PREPROC_IFELSE(
16427   [AC_LANG_SOURCE([[@var{input}]])],
16428   [@var{action-if-true}],
16429   [@var{action-if-false}])
16430 @end example
16432 @noindent
16433 @xref{Running the Preprocessor}.
16435 This macro double quotes the @var{input}.
16436 @end defmac
16438 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16439 @acindex{TRY_LINK}
16440 Same as:
16442 @example
16443 AC_LINK_IFELSE(
16444   [AC_LANG_PROGRAM([[@var{includes}]],
16445      [[@var{function-body}]])],
16446   [@var{action-if-true}],
16447   [@var{action-if-false}])
16448 @end example
16450 @noindent
16451 @xref{Running the Compiler}.
16453 This macro double quotes both @var{includes} and @var{function-body}.
16455 Depending on the current language (@pxref{Language Choice}), create a
16456 test program to see whether a function whose body consists of
16457 @var{function-body} can be compiled and linked.  If the file compiles
16458 and links successfully, run shell commands @var{action-if-found},
16459 otherwise run @var{action-if-not-found}.
16461 This macro double quotes both @var{includes} and @var{function-body}.
16463 For C and C++, @var{includes} is any @code{#include} statements needed
16464 by the code in @var{function-body} (@var{includes} will be ignored if
16465 the currently selected language is Fortran or Fortran 77).  The compiler
16466 and compilation flags are determined by the current language
16467 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
16468 @code{LIBS} are used for linking.
16469 @end defmac
16471 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
16472 @acindex{TRY_LINK_FUNC}
16473 This macro is equivalent to
16474 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
16475 [@var{action-if-found}], [@var{action-if-not-found}])}.
16476 @end defmac
16478 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
16479 @acindex{TRY_RUN}
16480 Same as:
16482 @example
16483 AC_RUN_IFELSE(
16484   [AC_LANG_SOURCE([[@var{program}]])],
16485   [@var{action-if-true}],
16486   [@var{action-if-false}],
16487   [@var{action-if-cross-compiling}])
16488 @end example
16490 @noindent
16491 @xref{Runtime}.
16492 @end defmac
16494 @defmac AC_UID_T
16495 @acindex{UID_T}
16496 @code{AC_TYPE_UID_T}
16497 @end defmac
16499 @defmac AC_UNISTD_H
16500 @acindex{UNISTD_H}
16501 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
16502 @end defmac
16504 @defmac AC_USG
16505 @acindex{USG}
16506 @cvindex USG
16507 Define @code{USG} if the @acronym{BSD} string functions are defined in
16508 @file{strings.h}.  You should no longer depend upon @code{USG}, but on
16509 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
16510 @end defmac
16512 @defmac AC_UTIME_NULL
16513 @acindex{UTIME_NULL}
16514 @code{AC_FUNC_UTIME_NULL}
16515 @end defmac
16517 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
16518 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
16519 If the cache file is inconsistent with the current host, target and
16520 build system types, it used to execute @var{cmd} or print a default
16521 error message.  This is now handled by default.
16522 @end defmac
16524 @defmac AC_VERBOSE (@var{result-description})
16525 @acindex{VERBOSE}
16526 @code{AC_MSG_RESULT}.
16527 @end defmac
16529 @defmac AC_VFORK
16530 @acindex{VFORK}
16531 @code{AC_FUNC_VFORK}
16532 @end defmac
16534 @defmac AC_VPRINTF
16535 @acindex{VPRINTF}
16536 @code{AC_FUNC_VPRINTF}
16537 @end defmac
16539 @defmac AC_WAIT3
16540 @acindex{WAIT3}
16541 @code{AC_FUNC_WAIT3}
16542 @end defmac
16544 @defmac AC_WARN
16545 @acindex{WARN}
16546 @code{AC_MSG_WARN}
16547 @end defmac
16549 @defmac AC_WORDS_BIGENDIAN
16550 @acindex{WORDS_BIGENDIAN}
16551 @code{AC_C_BIGENDIAN}
16552 @end defmac
16554 @defmac AC_XENIX_DIR
16555 @acindex{XENIX_DIR}
16556 @ovindex LIBS
16557 This macro used to add @option{-lx} to output variable @code{LIBS} if on
16558 Xenix.  Also, if @file{dirent.h} is being checked for, added
16559 @option{-ldir} to @code{LIBS}.  Now it is merely an alias of
16560 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
16561 running @sc{xenix} on which you should not depend:
16563 @example
16564 AC_MSG_CHECKING([for Xenix])
16565 AC_EGREP_CPP([yes],
16566 [#if defined M_XENIX && !defined M_UNIX
16567   yes
16568 #endif],
16569              [AC_MSG_RESULT([yes]); XENIX=yes],
16570              [AC_MSG_RESULT([no]); XENIX=])
16571 @end example
16572 @end defmac
16574 @defmac AC_YYTEXT_POINTER
16575 @acindex{YYTEXT_POINTER}
16576 @code{AC_DECL_YYTEXT}
16577 @end defmac
16579 @node Autoconf 1
16580 @section Upgrading From Version 1
16581 @cindex Upgrading autoconf
16582 @cindex Autoconf upgrading
16584 Autoconf version 2 is mostly backward compatible with version 1.
16585 However, it introduces better ways to do some things, and doesn't
16586 support some of the ugly things in version 1.  So, depending on how
16587 sophisticated your @file{configure.ac} files are, you might have to do
16588 some manual work in order to upgrade to version 2.  This chapter points
16589 out some problems to watch for when upgrading.  Also, perhaps your
16590 @command{configure} scripts could benefit from some of the new features in
16591 version 2; the changes are summarized in the file @file{NEWS} in the
16592 Autoconf distribution.
16594 @menu
16595 * Changed File Names::          Files you might rename
16596 * Changed Makefiles::           New things to put in @file{Makefile.in}
16597 * Changed Macros::              Macro calls you might replace
16598 * Changed Results::             Changes in how to check test results
16599 * Changed Macro Writing::       Better ways to write your own macros
16600 @end menu
16602 @node Changed File Names
16603 @subsection Changed File Names
16605 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
16606 in a particular package's source directory), you must rename it to
16607 @file{acsite.m4}.  @xref{autoconf Invocation}.
16609 If you distribute @file{install.sh} with your package, rename it to
16610 @file{install-sh} so @code{make} builtin rules won't inadvertently
16611 create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
16612 looks for the script under both names, but it is best to use the new name.
16614 If you were using @file{config.h.top}, @file{config.h.bot}, or
16615 @file{acconfig.h}, you still can, but you will have less clutter if you
16616 use the @code{AH_} macros.  @xref{Autoheader Macros}.
16618 @node Changed Makefiles
16619 @subsection Changed Makefiles
16621 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
16622 your @file{Makefile.in} files, so they can take advantage of the values
16623 of those variables in the environment when @command{configure} is run.
16624 Doing this isn't necessary, but it's a convenience for users.
16626 Also add @samp{@@configure_input@@} in a comment to each input file for
16627 @code{AC_OUTPUT}, so that the output files will contain a comment saying
16628 they were produced by @command{configure}.  Automatically selecting the
16629 right comment syntax for all the kinds of files that people call
16630 @code{AC_OUTPUT} on became too much work.
16632 Add @file{config.log} and @file{config.cache} to the list of files you
16633 remove in @code{distclean} targets.
16635 If you have the following in @file{Makefile.in}:
16637 @example
16638 prefix = /usr/local
16639 exec_prefix = $(prefix)
16640 @end example
16642 @noindent
16643 you must change it to:
16645 @example
16646 prefix = @@prefix@@
16647 exec_prefix = @@exec_prefix@@
16648 @end example
16650 @noindent
16651 The old behavior of replacing those variables without @samp{@@}
16652 characters around them has been removed.
16654 @node Changed Macros
16655 @subsection Changed Macros
16657 Many of the macros were renamed in Autoconf version 2.  You can still
16658 use the old names, but the new ones are clearer, and it's easier to find
16659 the documentation for them.  @xref{Obsolete Macros}, for a table showing the
16660 new names for the old macros.  Use the @command{autoupdate} program to
16661 convert your @file{configure.ac} to using the new macro names.
16662 @xref{autoupdate Invocation}.
16664 Some macros have been superseded by similar ones that do the job better,
16665 but are not call-compatible.  If you get warnings about calling obsolete
16666 macros while running @command{autoconf}, you may safely ignore them, but
16667 your @command{configure} script will generally work better if you follow
16668 the advice that is printed about what to replace the obsolete macros with.  In
16669 particular, the mechanism for reporting the results of tests has
16670 changed.  If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
16671 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
16672 look better if you switch to @code{AC_MSG_CHECKING} and
16673 @code{AC_MSG_RESULT}.  @xref{Printing Messages}.  Those macros work best
16674 in conjunction with cache variables.  @xref{Caching Results}.
16678 @node Changed Results
16679 @subsection Changed Results
16681 If you were checking the results of previous tests by examining the
16682 shell variable @code{DEFS}, you need to switch to checking the values of
16683 the cache variables for those tests.  @code{DEFS} no longer exists while
16684 @command{configure} is running; it is only created when generating output
16685 files.  This difference from version 1 is because properly quoting the
16686 contents of that variable turned out to be too cumbersome and
16687 inefficient to do every time @code{AC_DEFINE} is called.  @xref{Cache
16688 Variable Names}.
16690 For example, here is a @file{configure.ac} fragment written for Autoconf
16691 version 1:
16693 @example
16694 AC_HAVE_FUNCS(syslog)
16695 case "$DEFS" in
16696 *-DHAVE_SYSLOG*) ;;
16697 *) # syslog is not in the default libraries.  See if it's in some other.
16698   saved_LIBS="$LIBS"
16699   for lib in bsd socket inet; do
16700     AC_CHECKING(for syslog in -l$lib)
16701     LIBS="-l$lib $saved_LIBS"
16702     AC_HAVE_FUNCS(syslog)
16703     case "$DEFS" in
16704     *-DHAVE_SYSLOG*) break ;;
16705     *) ;;
16706     esac
16707     LIBS="$saved_LIBS"
16708   done ;;
16709 esac
16710 @end example
16712 Here is a way to write it for version 2:
16714 @example
16715 AC_CHECK_FUNCS([syslog])
16716 if test $ac_cv_func_syslog = no; then
16717   # syslog is not in the default libraries.  See if it's in some other.
16718   for lib in bsd socket inet; do
16719     AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
16720       LIBS="-l$lib $LIBS"; break])
16721   done
16723 @end example
16725 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
16726 backslashes before quotes, you need to remove them.  It now works
16727 predictably, and does not treat quotes (except back quotes) specially.
16728 @xref{Setting Output Variables}.
16730 All of the Boolean shell variables set by Autoconf macros now use
16731 @samp{yes} for the true value.  Most of them use @samp{no} for false,
16732 though for backward compatibility some use the empty string instead.  If
16733 you were relying on a shell variable being set to something like 1 or
16734 @samp{t} for true, you need to change your tests.
16736 @node Changed Macro Writing
16737 @subsection Changed Macro Writing
16739 When defining your own macros, you should now use @code{AC_DEFUN}
16740 instead of @code{define}.  @code{AC_DEFUN} automatically calls
16741 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
16742 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
16743 messages on the screen.  There's no actual harm in continuing to use the
16744 older way, but it's less convenient and attractive.  @xref{Macro
16745 Definitions}.
16747 You probably looked at the macros that came with Autoconf as a guide for
16748 how to do things.  It would be a good idea to take a look at the new
16749 versions of them, as the style is somewhat improved and they take
16750 advantage of some new features.
16752 If you were doing tricky things with undocumented Autoconf internals
16753 (macros, variables, diversions), check whether you need to change
16754 anything to account for changes that have been made.  Perhaps you can
16755 even use an officially supported technique in version 2 instead of
16756 kludging.  Or perhaps not.
16758 To speed up your locally written feature tests, add caching to them.
16759 See whether any of your tests are of general enough usefulness to
16760 encapsulate them into macros that you can share.
16763 @node Autoconf 2.13
16764 @section Upgrading From Version 2.13
16765 @cindex Upgrading autoconf
16766 @cindex Autoconf upgrading
16768 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
16769 suits this section@enddots{}
16771 @quotation
16772 Autoconf version 2.50 is mostly backward compatible with version 2.13.
16773 However, it introduces better ways to do some things, and doesn't
16774 support some of the ugly things in version 2.13.  So, depending on how
16775 sophisticated your @file{configure.ac} files are, you might have to do
16776 some manual work in order to upgrade to version 2.50.  This chapter
16777 points out some problems to watch for when upgrading.  Also, perhaps
16778 your @command{configure} scripts could benefit from some of the new
16779 features in version 2.50; the changes are summarized in the file
16780 @file{NEWS} in the Autoconf distribution.
16781 @end quotation
16783 @menu
16784 * Changed Quotation::           Broken code which used to work
16785 * New Macros::                  Interaction with foreign macros
16786 * Hosts and Cross-Compilation::  Bugward compatibility kludges
16787 * AC_LIBOBJ vs LIBOBJS::        LIBOBJS is a forbidden token
16788 * AC_FOO_IFELSE vs AC_TRY_FOO::  A more generic scheme for testing sources
16789 @end menu
16791 @node Changed Quotation
16792 @subsection Changed Quotation
16794 The most important changes are invisible to you: the implementation of
16795 most macros have completely changed.  This allowed more factorization of
16796 the code, better error messages, a higher uniformity of the user's
16797 interface etc.  Unfortunately, as a side effect, some construct which
16798 used to (miraculously) work might break starting with Autoconf 2.50.
16799 The most common culprit is bad quotation.
16801 For instance, in the following example, the message is not properly
16802 quoted:
16804 @example
16805 AC_INIT
16806 AC_CHECK_HEADERS(foo.h, ,
16807   AC_MSG_ERROR(cannot find foo.h, bailing out))
16808 AC_OUTPUT
16809 @end example
16811 @noindent
16812 Autoconf 2.13 simply ignores it:
16814 @example
16815 $ @kbd{autoconf-2.13; ./configure --silent}
16816 creating cache ./config.cache
16817 configure: error: cannot find foo.h
16819 @end example
16821 @noindent
16822 while Autoconf 2.50 will produce a broken @file{configure}:
16824 @example
16825 $ @kbd{autoconf-2.50; ./configure --silent}
16826 configure: error: cannot find foo.h
16827 ./configure: exit: bad non-numeric arg `bailing'
16828 ./configure: exit: bad non-numeric arg `bailing'
16830 @end example
16832 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
16833 too!
16835 @example
16836 AC_INIT([Example], [1.0], [bug-example@@example.org])
16837 AC_CHECK_HEADERS([foo.h], [],
16838   [AC_MSG_ERROR([cannot find foo.h, bailing out])])
16839 AC_OUTPUT
16840 @end example
16842 Many many (and many more) Autoconf macros were lacking proper quotation,
16843 including no less than@dots{} @code{AC_DEFUN} itself!
16845 @example
16846 $ @kbd{cat configure.in}
16847 AC_DEFUN([AC_PROG_INSTALL],
16848 [# My own much better version
16850 AC_INIT
16851 AC_PROG_INSTALL
16852 AC_OUTPUT
16853 $ @kbd{autoconf-2.13}
16854 autoconf: Undefined macros:
16855 ***BUG in Autoconf--please report*** AC_FD_MSG
16856 ***BUG in Autoconf--please report*** AC_EPI
16857 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
16858 configure.in:5:AC_PROG_INSTALL
16859 $ @kbd{autoconf-2.50}
16861 @end example
16864 @node New Macros
16865 @subsection New Macros
16867 @cindex undefined macro
16868 @cindex @code{_m4_divert_diversion}
16870 While Autoconf was relatively dormant in the late 1990s, Automake
16871 provided Autoconf-like macros for a while.  Starting with Autoconf 2.50
16872 in 2001, Autoconf provided
16873 versions of these macros, integrated in the @code{AC_} namespace,
16874 instead of @code{AM_}.  But in order to ease the upgrading via
16875 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
16877 Unfortunately older versions of Automake (e.g., Automake 1.4)
16878 did not quote the names of these macros.
16879 Therefore, when @command{m4} finds something like
16880 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
16881 @code{AM_TYPE_PTRDIFF_T} is
16882 expanded, replaced with its Autoconf definition.
16884 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
16885 complain, in its own words:
16887 @example
16888 $ @kbd{cat configure.ac}
16889 AC_INIT([Example], [1.0], [bug-example@@example.org])
16890 AM_TYPE_PTRDIFF_T
16891 $ @kbd{aclocal-1.4}
16892 $ @kbd{autoconf}
16893 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
16894 aclocal.m4:17: the top level
16895 autom4te: m4 failed with exit status: 1
16897 @end example
16899 Modern versions of Automake no longer define most of these
16900 macros, and will properly quote the names of the remaining macros.
16901 If you must use an old Automake, do not depend upon macros from Automake
16902 as it is simply not its job
16903 to provide macros (but the one it requires itself):
16905 @example
16906 $ @kbd{cat configure.ac}
16907 AC_INIT([Example], [1.0], [bug-example@@example.org])
16908 AM_TYPE_PTRDIFF_T
16909 $ @kbd{rm aclocal.m4}
16910 $ @kbd{autoupdate}
16911 autoupdate: `configure.ac' is updated
16912 $ @kbd{cat configure.ac}
16913 AC_INIT([Example], [1.0], [bug-example@@example.org])
16914 AC_CHECK_TYPES([ptrdiff_t])
16915 $ @kbd{aclocal-1.4}
16916 $ @kbd{autoconf}
16918 @end example
16921 @node Hosts and Cross-Compilation
16922 @subsection Hosts and Cross-Compilation
16923 @cindex Cross compilation
16925 Based on the experience of compiler writers, and after long public
16926 debates, many aspects of the cross-compilation chain have changed:
16928 @itemize @minus
16929 @item
16930 the relationship between the build, host, and target architecture types,
16932 @item
16933 the command line interface for specifying them to @command{configure},
16935 @item
16936 the variables defined in @command{configure},
16938 @item
16939 the enabling of cross-compilation mode.
16940 @end itemize
16942 @sp 1
16944 The relationship between build, host, and target have been cleaned up:
16945 the chain of default is now simply: target defaults to host, host to
16946 build, and build to the result of @command{config.guess}.  Nevertheless,
16947 in order to ease the transition from 2.13 to 2.50, the following
16948 transition scheme is implemented.  @emph{Do not rely on it}, as it will
16949 be completely disabled in a couple of releases (we cannot keep it, as it
16950 proves to cause more problems than it cures).
16952 They all default to the result of running @command{config.guess}, unless
16953 you specify either @option{--build} or @option{--host}.  In this case,
16954 the default becomes the system type you specified.  If you specify both,
16955 and they're different, @command{configure} will enter cross compilation
16956 mode, so it won't run any tests that require execution.
16958 Hint: if you mean to override the result of @command{config.guess},
16959 prefer @option{--build} over @option{--host}.  In the future,
16960 @option{--host} will not override the name of the build system type.
16961 Whenever you specify @option{--host}, be sure to specify @option{--build}
16962 too.
16964 @sp 1
16966 For backward compatibility, @command{configure} will accept a system
16967 type as an option by itself.  Such an option will override the
16968 defaults for build, host, and target system types.  The following
16969 configure statement will configure a cross toolchain that will run on
16970 Net@acronym{BSD}/alpha but generate code for @acronym{GNU} Hurd/sparc, which is
16971 also the build platform.
16973 @example
16974 ./configure --host=alpha-netbsd sparc-gnu
16975 @end example
16977 @sp 1
16979 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
16980 and @code{target} had a different semantics before and after the
16981 invocation of @code{AC_CANONICAL_BUILD} etc.  Now, the argument of
16982 @option{--build} is strictly copied into @code{build_alias}, and is left
16983 empty otherwise.  After the @code{AC_CANONICAL_BUILD}, @code{build} is
16984 set to the canonicalized build type.  To ease the transition, before,
16985 its contents is the same as that of @code{build_alias}.  Do @emph{not}
16986 rely on this broken feature.
16988 For consistency with the backward compatibility scheme exposed above,
16989 when @option{--host} is specified but @option{--build} isn't, the build
16990 system will be assumed to be the same as @option{--host}, and
16991 @samp{build_alias} will be set to that value.  Eventually, this
16992 historically incorrect behavior will go away.
16994 @sp 1
16996 The former scheme to enable cross-compilation proved to cause more harm
16997 than good, in particular, it used to be triggered too easily, leaving
16998 regular end users puzzled in front of cryptic error messages.
16999 @command{configure} could even enter cross-compilation mode only
17000 because the compiler was not functional.  This is mainly because
17001 @command{configure} used to try to detect cross-compilation, instead of
17002 waiting for an explicit flag from the user.
17004 Now, @command{configure} enters cross-compilation mode if and only if
17005 @option{--host} is passed.
17007 That's the short documentation.  To ease the transition between 2.13 and
17008 its successors, a more complicated scheme is implemented.  @emph{Do not
17009 rely on the following}, as it will be removed in the near future.
17011 If you specify @option{--host}, but not @option{--build}, when
17012 @command{configure} performs the first compiler test it will try to run
17013 an executable produced by the compiler.  If the execution fails, it will
17014 enter cross-compilation mode.  This is fragile.  Moreover, by the time
17015 the compiler test is performed, it may be too late to modify the
17016 build-system type: other tests may have already been performed.
17017 Therefore, whenever you specify @option{--host}, be sure to specify
17018 @option{--build} too.
17020 @example
17021 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
17022 @end example
17024 @noindent
17025 will enter cross-compilation mode.  The former interface, which
17026 consisted in setting the compiler to a cross-compiler without informing
17027 @command{configure} is obsolete.  For instance, @command{configure} will
17028 fail if it can't run the code generated by the specified compiler if you
17029 configure as follows:
17031 @example
17032 ./configure CC=m68k-coff-gcc
17033 @end example
17036 @node AC_LIBOBJ vs LIBOBJS
17037 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
17039 Up to Autoconf 2.13, the replacement of functions was triggered via the
17040 variable @code{LIBOBJS}.  Since Autoconf 2.50, the macro
17041 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
17042 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
17044 This change is mandated by the unification of the @acronym{GNU} Build System
17045 components.  In particular, the various fragile techniques used to parse
17046 a @file{configure.ac} are all replaced with the use of traces.  As a
17047 consequence, any action must be traceable, which obsoletes critical
17048 variable assignments.  Fortunately, @code{LIBOBJS} was the only problem,
17049 and it can even be handled gracefully (read, ``without your having to
17050 change something'').
17052 There were two typical uses of @code{LIBOBJS}: asking for a replacement
17053 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
17055 @sp 1
17057 As for function replacement, the fix is immediate: use
17058 @code{AC_LIBOBJ}.  For instance:
17060 @example
17061 LIBOBJS="$LIBOBJS fnmatch.o"
17062 LIBOBJS="$LIBOBJS malloc.$ac_objext"
17063 @end example
17065 @noindent
17066 should be replaced with:
17068 @example
17069 AC_LIBOBJ([fnmatch])
17070 AC_LIBOBJ([malloc])
17071 @end example
17073 @sp 1
17075 @ovindex LIBOBJDIR
17076 When used with Automake 1.10 or newer, a suitable value for
17077 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
17078 can be referenced from any @file{Makefile.am}.  Even without Automake,
17079 arranging for @code{LIBOBJDIR} to be set correctly will enable
17080 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
17081 The @code{LIBOJBDIR} feature is experimental.
17084 @node AC_FOO_IFELSE vs AC_TRY_FOO
17085 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
17087 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
17088 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
17089 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
17090 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
17091 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
17092 @code{AC_TRY_RUN}.  The motivations where:
17093 @itemize @minus
17094 @item
17095 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
17096 quoting their arguments;
17098 @item
17099 the combinatoric explosion is solved by decomposing on the one hand the
17100 generation of sources, and on the other hand executing the program;
17102 @item
17103 this scheme helps supporting more languages than plain C and C++.
17104 @end itemize
17106 In addition to the change of syntax, the philosophy has changed too:
17107 while emphasis was put on speed at the expense of accuracy, today's
17108 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
17109 expense of speed.
17112 As a perfect example of what is @emph{not} to be done, here is how to
17113 find out whether a header file contains a particular declaration, such
17114 as a typedef, a structure, a structure member, or a function.  Use
17115 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
17116 header file; on some systems the symbol might be defined in another
17117 header file that the file you are checking @samp{#include}s.
17119 As a (bad) example, here is how you should not check for C preprocessor
17120 symbols, either defined by header files or predefined by the C
17121 preprocessor: using @code{AC_EGREP_CPP}:
17123 @example
17124 @group
17125 AC_EGREP_CPP(yes,
17126 [#ifdef _AIX
17127   yes
17128 #endif
17129 ], is_aix=yes, is_aix=no)
17130 @end group
17131 @end example
17133 The above example, properly written would (i) use
17134 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
17136 @example
17137 @group
17138 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
17139 [[#if !defined _AIX
17140  error: This isn't AIX!
17141 #endif
17142 ]])],
17143                    [is_aix=yes],
17144                    [is_aix=no])
17145 @end group
17146 @end example
17149 @c ============================= Generating Test Suites with Autotest
17151 @node Using Autotest
17152 @chapter Generating Test Suites with Autotest
17154 @cindex Autotest
17156 @display
17157 @strong{N.B.: This section describes an experimental feature which will
17158 be part of Autoconf in a forthcoming release.  Although we believe
17159 Autotest is stabilizing, this documentation describes an interface which
17160 might change in the future: do not depend upon Autotest without
17161 subscribing to the Autoconf mailing lists.}
17162 @end display
17164 It is paradoxical that portable projects depend on nonportable tools
17165 to run their test suite.  Autoconf by itself is the paragon of this
17166 problem: although it aims at perfectly portability, up to 2.13 its
17167 test suite was using Deja@acronym{GNU}, a rich and complex testing
17168 framework, but which is far from being standard on Posix systems.
17169 Worse yet, it was likely to be missing on the most fragile platforms,
17170 the very platforms that are most likely to torture Autoconf and
17171 exhibit deficiencies.
17173 To circumvent this problem, many package maintainers have developed their
17174 own testing framework, based on simple shell scripts whose sole outputs
17175 are exit status values describing whether the test succeeded.  Most of
17176 these tests share common patterns, and this can result in lots of
17177 duplicated code and tedious maintenance.
17179 Following exactly the same reasoning that yielded to the inception of
17180 Autoconf, Autotest provides a test suite generation framework, based on
17181 M4 macros building a portable shell script.  The suite itself is
17182 equipped with automatic logging and tracing facilities which greatly
17183 diminish the interaction with bug reporters, and simple timing reports.
17185 Autoconf itself has been using Autotest for years, and we do attest that
17186 it has considerably improved the strength of the test suite and the
17187 quality of bug reports.  Other projects are known to use some generation
17188 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
17189 them with different needs, and this usage has validated Autotest as a general
17190 testing framework.
17192 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
17193 interactive tool testing, which is probably its main limitation.
17195 @menu
17196 * Using an Autotest Test Suite::  Autotest and the user
17197 * Writing testsuite.at::        Autotest macros
17198 * testsuite Invocation::        Running @command{testsuite} scripts
17199 * Making testsuite Scripts::    Using autom4te to create @command{testsuite}
17200 @end menu
17202 @node Using an Autotest Test Suite
17203 @section Using an Autotest Test Suite
17205 @menu
17206 * testsuite Scripts::           The concepts of Autotest
17207 * Autotest Logs::               Their contents
17208 @end menu
17210 @node testsuite Scripts
17211 @subsection @command{testsuite} Scripts
17213 @cindex @command{testsuite}
17215 Generating testing or validation suites using Autotest is rather easy.
17216 The whole validation suite is held in a file to be processed through
17217 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
17218 produce a stand-alone Bourne shell script which then gets distributed.
17219 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
17220 the installer's end.
17222 @cindex test group
17223 Each test of the validation suite should be part of some test group.  A
17224 @dfn{test group} is a sequence of interwoven tests that ought to be
17225 executed together, usually because one test in the group creates data
17226 files than a later test in the same group needs to read.  Complex test
17227 groups make later debugging more tedious.  It is much better to
17228 keep only a few tests per test group.  Ideally there is only one test
17229 per test group.
17231 For all but the simplest packages, some file such as @file{testsuite.at}
17232 does not fully hold all test sources, as these are often easier to
17233 maintain in separate files.  Each of these separate files holds a single
17234 test group, or a sequence of test groups all addressing some common
17235 functionality in the package.  In such cases, @file{testsuite.at}
17236 merely initializes the validation suite, and sometimes does elementary
17237 health checking, before listing include statements for all other test
17238 files.  The special file @file{package.m4}, containing the
17239 identification of the package, is automatically included if found.
17241 A convenient alternative consists in moving all the global issues
17242 (local Autotest macros, elementary health checking, and @code{AT_INIT}
17243 invocation) into the file @code{local.at}, and making
17244 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
17245 suites.  In such case, generating the whole test suite or pieces of it
17246 is only a matter of choosing the @command{autom4te} command line
17247 arguments.
17249 The validation scripts that Autotest produces are by convention called
17250 @command{testsuite}.  When run, @command{testsuite} executes each test
17251 group in turn, producing only one summary line per test to say if that
17252 particular test succeeded or failed.  At end of all tests, summarizing
17253 counters get printed.  One debugging directory is left for each test
17254 group which failed, if any: such directories are named
17255 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
17256 the test group, and they include:
17258 @itemize @bullet
17259 @item a debugging script named @file{run} which reruns the test in
17260 @dfn{debug mode} (@pxref{testsuite Invocation}).  The automatic generation
17261 of debugging scripts has the purpose of easing the chase for bugs.
17263 @item all the files created with @code{AT_DATA}
17265 @item a log of the run, named @file{testsuite.log}
17266 @end itemize
17268 In the ideal situation, none of the tests fail, and consequently no
17269 debugging directory is left behind for validation.
17271 It often happens in practice that individual tests in the validation
17272 suite need to get information coming out of the configuration process.
17273 Some of this information, common for all validation suites, is provided
17274 through the file @file{atconfig}, automatically created by
17275 @code{AC_CONFIG_TESTDIR}.  For configuration informations which your
17276 testing environment specifically needs, you might prepare an optional
17277 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
17278 The configuration process produces @file{atconfig} and @file{atlocal}
17279 out of these two input files, and these two produced files are
17280 automatically read by the @file{testsuite} script.
17282 Here is a diagram showing the relationship between files.
17284 @noindent
17285 Files used in preparing a software package for distribution:
17287 @example
17288                 [package.m4] -->.
17289                                  \
17290 subfile-1.at ->.  [local.at] ---->+
17291     ...         \                  \
17292 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
17293     ...         /
17294 subfile-n.at ->'
17295 @end example
17297 @noindent
17298 Files used in configuring a software package:
17300 @example
17301                                      .--> atconfig
17302                                     /
17303 [atlocal.in] -->  config.status* --<
17304                                     \
17305                                      `--> [atlocal]
17306 @end example
17308 @noindent
17309 Files created during the test suite execution:
17311 @example
17312 atconfig -->.                    .--> testsuite.log
17313              \                  /
17314               >-- testsuite* --<
17315              /                  \
17316 [atlocal] ->'                    `--> [testsuite.dir]
17317 @end example
17320 @node Autotest Logs
17321 @subsection Autotest Logs
17323 When run, the test suite creates a log file named after itself, e.g., a
17324 test suite named @command{testsuite} creates @file{testsuite.log}.  It
17325 contains a lot of information, usually more than maintainers actually
17326 need, but therefore most of the time it contains all that is needed:
17328 @table @asis
17329 @item command line arguments
17330 @c akim s/to consist in/to consist of/
17331 A very bad but unfortunately widespread Posix habit consists of
17332 setting environment variables before the command, such as in
17333 @samp{CC=my-home-grown-cc ./testsuite}.  The test suite will not
17334 know this change, hence (i) it cannot report it to you, and (ii)
17335 it cannot preserve the value of @code{CC} for subsequent runs.
17336 Autoconf faced exactly the same problem, and solved it by asking
17337 users to pass the variable definitions as command line arguments.
17338 Autotest requires this rule, too, but has no means to enforce it; the log
17339 then contains a trace of the variables that were changed by the user.
17341 @item @file{ChangeLog} excerpts
17342 The topmost lines of all the @file{ChangeLog}s found in the source
17343 hierarchy.  This is especially useful when bugs are reported against
17344 development versions of the package, since the version string does not
17345 provide sufficient information to know the exact state of the sources
17346 the user compiled.  Of course, this relies on the use of a
17347 @file{ChangeLog}.
17349 @item build machine
17350 Running a test suite in a cross-compile environment is not an easy task,
17351 since it would mean having the test suite run on a machine @var{build},
17352 while running programs on a machine @var{host}.  It is much simpler to
17353 run both the test suite and the programs on @var{host}, but then, from
17354 the point of view of the test suite, there remains a single environment,
17355 @var{host} = @var{build}.  The log contains relevant information on the
17356 state of the build machine, including some important environment
17357 variables.
17358 @c FIXME: How about having an M4sh macro to say `hey, log the value
17359 @c of `@dots{}'?  This would help both Autoconf and Autotest.
17361 @item tested programs
17362 The absolute file name and answers to @option{--version} of the tested
17363 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
17365 @item configuration log
17366 The contents of @file{config.log}, as created by @command{configure},
17367 are appended.  It contains the configuration flags and a detailed report
17368 on the configuration itself.
17369 @end table
17372 @node Writing testsuite.at
17373 @section Writing @file{testsuite.at}
17375 The @file{testsuite.at} is a Bourne shell script making use of special
17376 Autotest M4 macros.  It often contains a call to @code{AT_INIT} near
17377 its beginning followed by one call to @code{m4_include} per source file
17378 for tests.  Each such included file, or the remainder of
17379 @file{testsuite.at} if include files are not used, contain a sequence of
17380 test groups.  Each test group begins with a call to @code{AT_SETUP},
17381 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
17382 and then completes with a call to @code{AT_CLEANUP}.
17384 @defmac AT_INIT (@ovar{name})
17385 @atindex{INIT}
17386 @c FIXME: Not clear, plus duplication of the information.
17387 Initialize Autotest.  Giving a @var{name} to the test suite is
17388 encouraged if your package includes several test suites.  In any case,
17389 the test suite always displays the package name and version.  It also
17390 inherits the package bug report address.
17391 @end defmac
17393 @defmac AT_COPYRIGHT (@var{copyright-notice})
17394 @atindex{COPYRIGHT}
17395 @cindex Copyright Notice
17396 State that, in addition to the Free Software Foundation's copyright on
17397 the Autotest macros, parts of your test suite are covered by
17398 @var{copyright-notice}.
17400 The @var{copyright-notice} will show up in both the head of
17401 @command{testsuite} and in @samp{testsuite --version}.
17402 @end defmac
17404 @defmac AT_TESTED (@var{executables})
17405 @atindex{TESTED}
17406 Log the file name and answer to @option{--version} of each program in
17407 space-separated list @var{executables}.  Several invocations register
17408 new executables, in other words, don't fear registering one program
17409 several times.
17410 @end defmac
17412 Autotest test suites rely on @env{PATH} to find the tested program.
17413 This avoids the need to generate absolute names of the various tools, and
17414 makes it possible to test installed programs.  Therefore, knowing which
17415 programs are being exercised is crucial to understanding problems in
17416 the test suite itself, or its occasional misuses.  It is a good idea to
17417 also subscribe foreign programs you depend upon, to avoid incompatible
17418 diagnostics.
17420 @sp 1
17422 @defmac AT_SETUP (@var{test-group-name})
17423 @atindex{SETUP}
17424 This macro starts a group of related tests, all to be executed in the
17425 same subshell.  It accepts a single argument, which holds a few words
17426 (no more than about 30 or 40 characters) quickly describing the purpose
17427 of the test group being started.
17428 @end defmac
17430 @defmac AT_KEYWORDS (@var{keywords})
17431 @atindex{KEYWORDS}
17432 Associate the space-separated list of @var{keywords} to the enclosing
17433 test group.  This makes it possible to run ``slices'' of the test suite.
17434 For instance, if some of your test groups exercise some @samp{foo}
17435 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
17436 @samp{./testsuite -k foo} to run exclusively these test groups.  The
17437 @var{title} of the test group is automatically recorded to
17438 @code{AT_KEYWORDS}.
17440 Several invocations within a test group accumulate new keywords.  In
17441 other words, don't fear registering the same keyword several times in a
17442 test group.
17443 @end defmac
17445 @defmac AT_CAPTURE_FILE (@var{file})
17446 @atindex{CAPTURE_FILE}
17447 If the current test group fails, log the contents of @var{file}.
17448 Several identical calls within one test group have no additional effect.
17449 @end defmac
17451 @defmac AT_XFAIL_IF (@var{shell-condition})
17452 @atindex{XFAIL_IF}
17453 Determine whether the test is expected to fail because it is a known
17454 bug (for unsupported features, you should skip the test).
17455 @var{shell-condition} is a shell expression such as a @code{test}
17456 command; you can instantiate this macro many times from within the
17457 same test group, and one of the conditions will be enough to turn
17458 the test into an expected failure.
17459 @end defmac
17461 @defmac AT_CLEANUP
17462 @atindex{CLEANUP}
17463 End the current test group.
17464 @end defmac
17466 @sp 1
17468 @defmac AT_DATA (@var{file}, @var{contents})
17469 @atindex{DATA}
17470 Initialize an input data @var{file} with given @var{contents}.  Of
17471 course, the @var{contents} have to be properly quoted between square
17472 brackets to protect against included commas or spurious M4
17473 expansion.  The contents ought to end with an end of line.
17474 @end defmac
17476 @defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @dvar{stdout, @samp{}}, @dvar{stderr, @samp{}}, @ovar{run-if-fail}, @ovar{run-if-pass})
17477 @atindex{CHECK}
17478 Execute a test by performing given shell @var{commands}.  These commands
17479 should normally exit with @var{status}, while producing expected
17480 @var{stdout} and @var{stderr} contents.  If @var{commands} exit with
17481 status 77, then the whole test group is skipped.  Otherwise, if this test
17482 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
17483 commands @var{run-if-pass}.
17485 The @var{commands} @emph{must not} redirect the standard output, nor the
17486 standard error.
17488 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
17489 the corresponding value is not checked.
17491 The special value @samp{expout} for @var{stdout} means the expected
17492 output of the @var{commands} is the content of the file @file{expout}.
17493 If @var{stdout} is @samp{stdout}, then the standard output of the
17494 @var{commands} is available for further tests in the file @file{stdout}.
17495 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
17496 @end defmac
17499 @node testsuite Invocation
17500 @section Running @command{testsuite} Scripts
17501 @cindex @command{testsuite}
17503 Autotest test suites support the following arguments:
17505 @table @option
17506 @item --help
17507 @itemx -h
17508 Display the list of options and exit successfully.
17510 @item --version
17511 @itemx -V
17512 Display the version of the test suite and exit successfully.
17514 @item --clean
17515 @itemx -c
17516 Remove all the files the test suite might have created and exit.  Meant
17517 for @code{clean} Makefile targets.
17519 @item --list
17520 @itemx -l
17521 List all the tests (or only the selection), including their possible
17522 keywords.
17523 @end table
17525 @sp 1
17527 By default all tests are performed (or described with
17528 @option{--list}) in the default environment first silently, then
17529 verbosely, but the environment, set of tests, and verbosity level can be
17530 tuned:
17532 @table @samp
17533 @item @var{variable}=@var{value}
17534 Set the environment @var{variable} to @var{value}.  Use this rather
17535 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
17536 different environment.
17538 @cindex @code{AUTOTEST_PATH}
17539 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
17540 to @env{PATH}.  Relative directory names (not starting with
17541 @samp{/}) are considered to be relative to the top level of the
17542 package being built.  All directories are made absolute, first
17543 starting from the top level @emph{build} tree, then from the
17544 @emph{source} tree.  For instance @samp{./testsuite
17545 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
17546 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
17547 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
17548 @env{PATH}.
17550 @item @var{number}
17551 @itemx @var{number}-@var{number}
17552 @itemx @var{number}-
17553 @itemx -@var{number}
17554 Add the corresponding test groups, with obvious semantics, to the
17555 selection.
17557 @item --keywords=@var{keywords}
17558 @itemx -k @var{keywords}
17559 Add to the selection the test groups with title or keywords (arguments
17560 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
17561 of the comma separated list @var{keywords}, case-insensitively.  Use
17562 @samp{!} immediately before the keyword to invert the selection for this
17563 keyword.  By default, the keywords match whole words; enclose them in
17564 @samp{.*} to also match parts of words.
17566 For example, running
17568 @example
17569 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
17570 @end example
17572 @noindent
17573 will select all tests tagged @samp{autoupdate} @emph{and} with tags
17574 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH},
17575 etc.), while
17577 @example
17578 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
17579 @end example
17581 @noindent
17582 will select all tests not tagged @samp{autoupdate} @emph{or} with tags
17583 containing @samp{FUNC}.
17585 @item --errexit
17586 @itemx -e
17587 If any test fails, immediately abort testing.  It implies
17588 @option{--debug}: post test group clean up, and top-level logging
17589 are inhibited.  This option is meant for the full test
17590 suite, it is not really useful for generated debugging scripts.
17592 @item --verbose
17593 @itemx -v
17594 Force more verbosity in the detailed output of what is being done.  This
17595 is the default for debugging scripts.
17597 @item --debug
17598 @itemx -d
17599 Do not remove the files after a test group was performed ---but they are
17600 still removed @emph{before}, therefore using this option is sane when
17601 running several test groups.  Create debugging scripts.  Do not
17602 overwrite the top-level
17603 log (in order to preserve supposedly existing full log file).  This is
17604 the default for debugging scripts, but it can also be useful to debug
17605 the testsuite itself.
17607 @item --trace
17608 @itemx -x
17609 Trigger shell tracing of the test groups.
17610 @end table
17613 @node Making testsuite Scripts
17614 @section Making @command{testsuite} Scripts
17616 For putting Autotest into movement, you need some configuration and
17617 Makefile machinery.  We recommend, at least if your package uses deep or
17618 shallow hierarchies, that you use @file{tests/} as the name of the
17619 directory holding all your tests and their @file{Makefile}.  Here is a
17620 check list of things to do.
17622 @itemize @minus
17624 @item
17625 @cindex @file{package.m4}
17626 Make sure to create the file @file{package.m4}, which defines the
17627 identity of the package.  It must define @code{AT_PACKAGE_STRING}, the
17628 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
17629 address to which bug reports should be sent.  For sake of completeness,
17630 we suggest that you also define @code{AT_PACKAGE_NAME},
17631 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
17632 @xref{Initializing configure}, for a description of these variables.  We
17633 suggest the following Makefile excerpt:
17635 @smallexample
17636 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
17637         @{                                      \
17638           echo '# Signature of the current package.'; \
17639           echo 'm4_define([AT_PACKAGE_NAME],      [@@PACKAGE_NAME@@])'; \
17640           echo 'm4_define([AT_PACKAGE_TARNAME],   [@@PACKAGE_TARNAME@@])'; \
17641           echo 'm4_define([AT_PACKAGE_VERSION],   [@@PACKAGE_VERSION@@])'; \
17642           echo 'm4_define([AT_PACKAGE_STRING],    [@@PACKAGE_STRING@@])'; \
17643           echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
17644         @} >$(srcdir)/package.m4
17645 @end smallexample
17647 @noindent
17648 Be sure to distribute @file{package.m4} and to put it into the source
17649 hierarchy: the test suite ought to be shipped!
17651 @item
17652 Invoke @code{AC_CONFIG_TESTDIR}.
17654 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, @var{directory}})
17655 @acindex{CONFIG_TESTDIR}
17656 An Autotest test suite is to be configured in @var{directory}.  This
17657 macro requires the instantiation of @file{@var{directory}/atconfig} from
17658 @file{@var{directory}/atconfig.in}, and sets the default
17659 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
17660 @end defmac
17662 @item
17663 Still within @file{configure.ac}, as appropriate, ensure that some
17664 @code{AC_CONFIG_FILES} command includes substitution for
17665 @file{tests/atlocal}.
17667 @item
17668 The @file{tests/Makefile.in} should be modified so the validation in
17669 your package is triggered by @samp{make check}.  An example is provided
17670 below.
17671 @end itemize
17673 With Automake, here is a minimal example about how to link @samp{make
17674 check} with a validation suite.
17676 @example
17677 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
17678 TESTSUITE = $(srcdir)/testsuite
17680 check-local: atconfig atlocal $(TESTSUITE)
17681         $(SHELL) $(TESTSUITE) $(TESTSUITEFLAGS)
17683 installcheck-local: atconfig atlocal $(TESTSUITE)
17684         $(SHELL) $(TESTSUITE) AUTOTEST_PATH="$(bindir)" \
17685           $(TESTSUITEFLAGS)
17687 AUTOTEST = $(AUTOM4TE) --language=autotest
17688 $(TESTSUITE): $(srcdir)/testsuite.at
17689         $(AUTOTEST) -I $(srcdir) -o $@@.tmp $@@.at
17690         mv $@@.tmp $@@
17691 @end example
17693 You might want to list explicitly the dependencies, i.e., the list of
17694 the files @file{testsuite.at} includes.
17696 With strict Autoconf, you might need to add lines inspired from the
17697 following:
17699 @example
17700 subdir = tests
17702 atconfig: $(top_builddir)/config.status
17703         cd $(top_builddir) && \
17704            $(SHELL) ./config.status $(subdir)/$@@
17706 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
17707         cd $(top_builddir) && \
17708            $(SHELL) ./config.status $(subdir)/$@@
17709 @end example
17711 @noindent
17712 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
17713 distributed.
17715 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
17716 within your Makefile, you can fine-tune test suite execution with this variable,
17717 for example:
17719 @example
17720 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
17721 @end example
17725 @c =============================== Frequent Autoconf Questions, with answers
17727 @node FAQ
17728 @chapter Frequent Autoconf Questions, with answers
17730 Several questions about Autoconf come up occasionally.  Here some of them
17731 are addressed.
17733 @menu
17734 * Distributing::                Distributing @command{configure} scripts
17735 * Why GNU m4::                  Why not use the standard M4?
17736 * Bootstrapping::               Autoconf and @acronym{GNU} M4 require each other?
17737 * Why Not Imake::               Why @acronym{GNU} uses @command{configure} instead of Imake
17738 * Defining Directories::        Passing @code{datadir} to program
17739 * autom4te.cache::              What is it?  Can I remove it?
17740 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
17741 @end menu
17743 @node Distributing
17744 @section Distributing @command{configure} Scripts
17745 @cindex License
17747 @display
17748 What are the restrictions on distributing @command{configure}
17749 scripts that Autoconf generates?  How does that affect my
17750 programs that use them?
17751 @end display
17753 There are no restrictions on how the configuration scripts that Autoconf
17754 produces may be distributed or used.  In Autoconf version 1, they were
17755 covered by the @acronym{GNU} General Public License.  We still encourage
17756 software authors to distribute their work under terms like those of the
17757 @acronym{GPL}, but doing so is not required to use Autoconf.
17759 Of the other files that might be used with @command{configure},
17760 @file{config.h.in} is under whatever copyright you use for your
17761 @file{configure.ac}.  @file{config.sub} and @file{config.guess} have an
17762 exception to the @acronym{GPL} when they are used with an Autoconf-generated
17763 @command{configure} script, which permits you to distribute them under the
17764 same terms as the rest of your package.  @file{install-sh} is from the X
17765 Consortium and is not copyrighted.
17767 @node Why GNU m4
17768 @section Why Require @acronym{GNU} M4?
17770 @display
17771 Why does Autoconf require @acronym{GNU} M4?
17772 @end display
17774 Many M4 implementations have hard-coded limitations on the size and
17775 number of macros that Autoconf exceeds.  They also lack several
17776 builtin macros that it would be difficult to get along without in a
17777 sophisticated application like Autoconf, including:
17779 @example
17780 m4_builtin
17781 m4_indir
17782 m4_bpatsubst
17783 __file__
17784 __line__
17785 @end example
17787 Autoconf requires version 1.4.3 or later of @acronym{GNU} M4.
17789 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
17790 M4 is simple to configure and install, it seems reasonable to require
17791 @acronym{GNU} M4 to be installed also.  Many maintainers of @acronym{GNU} and
17792 other free software already have most of the @acronym{GNU} utilities
17793 installed, since they prefer them.
17795 @node Bootstrapping
17796 @section How Can I Bootstrap?
17797 @cindex Bootstrap
17799 @display
17800 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
17801 @command{configure} script, how do I bootstrap?  It seems like a chicken
17802 and egg problem!
17803 @end display
17805 This is a misunderstanding.  Although @acronym{GNU} M4 does come with a
17806 @command{configure} script produced by Autoconf, Autoconf is not required
17807 in order to run the script and install @acronym{GNU} M4.  Autoconf is only
17808 required if you want to change the M4 @command{configure} script, which few
17809 people have to do (mainly its maintainer).
17811 @node Why Not Imake
17812 @section Why Not Imake?
17813 @cindex Imake
17815 @display
17816 Why not use Imake instead of @command{configure} scripts?
17817 @end display
17819 Several people have written addressing this question, so I include
17820 adaptations of their explanations here.
17822 The following answer is based on one written by Richard Pixley:
17824 @quotation
17825 Autoconf generated scripts frequently work on machines that it has
17826 never been set up to handle before.  That is, it does a good job of
17827 inferring a configuration for a new system.  Imake cannot do this.
17829 Imake uses a common database of host specific data.  For X11, this makes
17830 sense because the distribution is made as a collection of tools, by one
17831 central authority who has control over the database.
17833 @acronym{GNU} tools are not released this way.  Each @acronym{GNU} tool has a
17834 maintainer; these maintainers are scattered across the world.  Using a
17835 common database would be a maintenance nightmare.  Autoconf may appear
17836 to be this kind of database, but in fact it is not.  Instead of listing
17837 host dependencies, it lists program requirements.
17839 If you view the @acronym{GNU} suite as a collection of native tools, then the
17840 problems are similar.  But the @acronym{GNU} development tools can be
17841 configured as cross tools in almost any host+target permutation.  All of
17842 these configurations can be installed concurrently.  They can even be
17843 configured to share host independent files across hosts.  Imake doesn't
17844 address these issues.
17846 Imake templates are a form of standardization.  The @acronym{GNU} coding
17847 standards address the same issues without necessarily imposing the same
17848 restrictions.
17849 @end quotation
17852 Here is some further explanation, written by Per Bothner:
17854 @quotation
17855 One of the advantages of Imake is that it easy to generate large
17856 Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
17857 However, @code{cpp} is not programmable: it has limited conditional
17858 facilities, and no looping.  And @code{cpp} cannot inspect its
17859 environment.
17861 All of these problems are solved by using @code{sh} instead of
17862 @code{cpp}.  The shell is fully programmable, has macro substitution,
17863 can execute (or source) other shell scripts, and can inspect its
17864 environment.
17865 @end quotation
17868 Paul Eggert elaborates more:
17870 @quotation
17871 With Autoconf, installers need not assume that Imake itself is already
17872 installed and working well.  This may not seem like much of an advantage
17873 to people who are accustomed to Imake.  But on many hosts Imake is not
17874 installed or the default installation is not working well, and requiring
17875 Imake to install a package hinders the acceptance of that package on
17876 those hosts.  For example, the Imake template and configuration files
17877 might not be installed properly on a host, or the Imake build procedure
17878 might wrongly assume that all source files are in one big directory
17879 tree, or the Imake configuration might assume one compiler whereas the
17880 package or the installer needs to use another, or there might be a
17881 version mismatch between the Imake expected by the package and the Imake
17882 supported by the host.  These problems are much rarer with Autoconf,
17883 where each package comes with its own independent configuration
17884 processor.
17886 Also, Imake often suffers from unexpected interactions between
17887 @command{make} and the installer's C preprocessor.  The fundamental problem
17888 here is that the C preprocessor was designed to preprocess C programs,
17889 not @file{Makefile}s.  This is much less of a problem with Autoconf,
17890 which uses the general-purpose preprocessor M4, and where the
17891 package's author (rather than the installer) does the preprocessing in a
17892 standard way.
17893 @end quotation
17896 Finally, Mark Eichin notes:
17898 @quotation
17899 Imake isn't all that extensible, either.  In order to add new features to
17900 Imake, you need to provide your own project template, and duplicate most
17901 of the features of the existing one.  This means that for a sophisticated
17902 project, using the vendor-provided Imake templates fails to provide any
17903 leverage---since they don't cover anything that your own project needs
17904 (unless it is an X11 program).
17906 On the other side, though:
17908 The one advantage that Imake has over @command{configure}:
17909 @file{Imakefile}s tend to be much shorter (likewise, less redundant)
17910 than @file{Makefile.in}s.  There is a fix to this, however---at least
17911 for the Kerberos V5 tree, we've modified things to call in common
17912 @file{post.in} and @file{pre.in} @file{Makefile} fragments for the
17913 entire tree.  This means that a lot of common things don't have to be
17914 duplicated, even though they normally are in @command{configure} setups.
17915 @end quotation
17918 @node Defining Directories
17919 @section How Do I @code{#define} Installation Directories?
17921 @display
17922 My program needs library files, installed in @code{datadir} and
17923 similar.  If I use
17925 @example
17926 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
17927   [Define to the read-only architecture-independent
17928    data directory.])
17929 @end example
17931 @noindent
17932 I get
17934 @example
17935 #define DATADIR "$@{prefix@}/share"
17936 @end example
17937 @end display
17939 As already explained, this behavior is on purpose, mandated by the
17940 @acronym{GNU} Coding Standards, see @ref{Installation Directory
17941 Variables}.  There are several means to achieve a similar goal:
17943 @itemize @minus
17944 @item
17945 Do not use @code{AC_DEFINE} but use your @file{Makefile} to pass the
17946 actual value of @code{datadir} via compilation flags, see
17947 @ref{Installation Directory Variables}, for the details.
17949 @item
17950 This solution can be simplified when compiling a program: you may either
17951 extend the @code{CPPFLAGS}:
17953 @example
17954 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
17955 @end example
17957 @noindent
17958 or create a dedicated header file:
17960 @example
17961 DISTCLEANFILES = datadir.h
17962 datadir.h: Makefile
17963         echo '#define DATADIR "$(datadir)"' >$@@
17964 @end example
17966 @item
17967 Use @code{AC_DEFINE} but have @command{configure} compute the literal
17968 value of @code{datadir} and others.  Many people have wrapped macros to
17969 automate this task.  For instance, the macro @code{AC_DEFINE_DIR} from
17970 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
17971 Archive}.
17973 This solution does not conform to the @acronym{GNU} Coding Standards.
17975 @item
17976 Note that all the previous solutions hard wire the absolute name of
17977 these directories in the executables, which is not a good property.  You
17978 may try to compute the names relative to @code{prefix}, and try to
17979 find @code{prefix} at runtime, this way your package is relocatable.
17980 Some macros are already available to address this issue: see
17981 @code{adl_COMPUTE_RELATIVE_PATHS} and
17982 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
17983 @uref{http://autoconf-archive.cryp.to/,
17984 Autoconf Macro Archive}.
17985 @end itemize
17988 @node autom4te.cache
17989 @section What is @file{autom4te.cache}?
17991 @display
17992 What is this directory @file{autom4te.cache}?  Can I safely remove it?
17993 @end display
17995 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
17996 role and is read by many tools: @command{autoconf} to create
17997 @file{configure}, @command{autoheader} to create @file{config.h.in},
17998 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
17999 check the completeness of @file{configure.ac}, @command{autoreconf} to
18000 check the @acronym{GNU} Build System components that are used.  To
18001 ``read @file{configure.ac}'' actually means to compile it with M4,
18002 which can be a very long process for complex @file{configure.ac}.
18004 This is why all these tools, instead of running directly M4, invoke
18005 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
18006 a specific demand, stores additional information in
18007 @file{autom4te.cache} for future runs.  For instance, if you run
18008 @command{autoconf}, behind the scenes, @command{autom4te} will also
18009 store information for the other tools, so that when you invoke
18010 @command{autoheader} or @command{automake} etc., re-processing
18011 @file{configure.ac} is not needed.  The speed up is frequently of 30%,
18012 and is increasing with the size of @file{configure.ac}.
18014 But it is and remains being simply a cache: you can safely remove it.
18016 @sp 1
18018 @display
18019 Can I permanently get rid of it?
18020 @end display
18022 The creation of this cache can be disabled from
18023 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
18024 details.  You should be aware that disabling the cache slows down the
18025 Autoconf test suite by 40%.  The more @acronym{GNU} Build System
18026 components are used, the more the cache is useful; for instance
18027 running @samp{autoreconf -f} on the Core Utilities is twice slower without
18028 the cache @emph{although @option{--force} implies that the cache is
18029 not fully exploited}, and eight times slower than without
18030 @option{--force}.
18033 @node Present But Cannot Be Compiled
18034 @section Header Present But Cannot Be Compiled
18036 The most important guideline to bear in mind when checking for
18037 features is to mimic as much as possible the intended use.
18038 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
18039 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
18040 the preprocessor, instead of the compiler, to check for headers.  As a
18041 result, incompatibilities between headers went unnoticed during
18042 configuration, and maintainers finally had to deal with this issue
18043 elsewhere.
18045 As of Autoconf 2.56 both checks are performed, and @code{configure}
18046 complains loudly if the compiler and the preprocessor do not agree.
18047 For the time being the result used is that of the preprocessor, to give
18048 maintainers time to adjust their @file{configure.ac}, but in the
18049 future, only the compiler will be considered.
18051 Consider the following example:
18053 @smallexample
18054 $ @kbd{cat number.h}
18055 typedef int number;
18056 $ @kbd{cat pi.h}
18057 const number pi = 3;
18058 $ @kbd{cat configure.ac}
18059 AC_INIT([Example], [1.0], [bug-example@@example.org])
18060 AC_CHECK_HEADERS([pi.h])
18061 $ @kbd{autoconf -Wall}
18062 $ @kbd{./configure}
18063 checking for gcc... gcc
18064 checking for C compiler default output file name... a.out
18065 checking whether the C compiler works... yes
18066 checking whether we are cross compiling... no
18067 checking for suffix of executables...
18068 checking for suffix of object files... o
18069 checking whether we are using the GNU C compiler... yes
18070 checking whether gcc accepts -g... yes
18071 checking for gcc option to accept ISO C89... none needed
18072 checking how to run the C preprocessor... gcc -E
18073 checking for grep that handles long lines and -e... grep
18074 checking for egrep... grep -E
18075 checking for ANSI C header files... yes
18076 checking for sys/types.h... yes
18077 checking for sys/stat.h... yes
18078 checking for stdlib.h... yes
18079 checking for string.h... yes
18080 checking for memory.h... yes
18081 checking for strings.h... yes
18082 checking for inttypes.h... yes
18083 checking for stdint.h... yes
18084 checking for unistd.h... yes
18085 checking pi.h usability... no
18086 checking pi.h presence... yes
18087 configure: WARNING: pi.h: present but cannot be compiled
18088 configure: WARNING: pi.h:     check for missing prerequisite headers?
18089 configure: WARNING: pi.h: see the Autoconf documentation
18090 configure: WARNING: pi.h:     section "Present But Cannot Be Compiled"
18091 configure: WARNING: pi.h: proceeding with the preprocessor's result
18092 configure: WARNING: pi.h: in the future, the compiler will take precedence
18093 configure: WARNING:     ## -------------------------------------- ##
18094 configure: WARNING:     ## Report this to bug-example@@example.org ##
18095 configure: WARNING:     ## -------------------------------------- ##
18096 checking for pi.h... yes
18097 @end smallexample
18099 @noindent
18100 The proper way the handle this case is using the fourth argument
18101 (@pxref{Generic Headers}):
18103 @example
18104 $ @kbd{cat configure.ac}
18105 AC_INIT([Example], [1.0], [bug-example@@example.org])
18106 AC_CHECK_HEADERS([number.h pi.h], [], [],
18107 [[#if HAVE_NUMBER_H
18108 # include <number.h>
18109 #endif
18111 $ @kbd{autoconf -Wall}
18112 $ @kbd{./configure}
18113 checking for gcc... gcc
18114 checking for C compiler default output... a.out
18115 checking whether the C compiler works... yes
18116 checking whether we are cross compiling... no
18117 checking for suffix of executables...
18118 checking for suffix of object files... o
18119 checking whether we are using the GNU C compiler... yes
18120 checking whether gcc accepts -g... yes
18121 checking for gcc option to accept ANSI C... none needed
18122 checking for number.h... yes
18123 checking for pi.h... yes
18124 @end example
18126 See @ref{Particular Headers}, for a list of headers with their
18127 prerequisite.
18129 @c ===================================================== History of Autoconf.
18131 @node History
18132 @chapter History of Autoconf
18133 @cindex History of autoconf
18135 You may be wondering, Why was Autoconf originally written?  How did it
18136 get into its present form?  (Why does it look like gorilla spit?)  If
18137 you're not wondering, then this chapter contains no information useful
18138 to you, and you might as well skip it.  If you @emph{are} wondering,
18139 then let there be light@enddots{}
18141 @menu
18142 * Genesis::                     Prehistory and naming of @command{configure}
18143 * Exodus::                      The plagues of M4 and Perl
18144 * Leviticus::                   The priestly code of portability arrives
18145 * Numbers::                     Growth and contributors
18146 * Deuteronomy::                 Approaching the promises of easy configuration
18147 @end menu
18149 @node Genesis
18150 @section Genesis
18152 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
18153 Free Software Foundation.  As they were ported to more platforms and
18154 more programs were added, the number of @option{-D} options that users
18155 had to select in the @file{Makefile} (around 20) became burdensome.
18156 Especially for me---I had to test each new release on a bunch of
18157 different systems.  So I wrote a little shell script to guess some of
18158 the correct settings for the fileutils package, and released it as part
18159 of fileutils 2.0.  That @command{configure} script worked well enough that
18160 the next month I adapted it (by hand) to create similar @command{configure}
18161 scripts for several other @acronym{GNU} utilities packages.  Brian Berliner
18162 also adapted one of my scripts for his @acronym{CVS} revision control system.
18164 Later that summer, I learned that Richard Stallman and Richard Pixley
18165 were developing similar scripts to use in the @acronym{GNU} compiler tools;
18166 so I adapted my @command{configure} scripts to support their evolving
18167 interface: using the file name @file{Makefile.in} as the templates;
18168 adding @samp{+srcdir}, the first option (of many); and creating
18169 @file{config.status} files.
18171 @node Exodus
18172 @section Exodus
18174 As I got feedback from users, I incorporated many improvements, using
18175 Emacs to search and replace, cut and paste, similar changes in each of
18176 the scripts.  As I adapted more @acronym{GNU} utilities packages to use
18177 @command{configure} scripts, updating them all by hand became impractical.
18178 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
18179 mail saying that the @command{configure} scripts were great, and asking if
18180 I had a tool for generating them that I could send him.  No, I thought,
18181 but I should!  So I started to work out how to generate them.  And the
18182 journey from the slavery of hand-written @command{configure} scripts to the
18183 abundance and ease of Autoconf began.
18185 Cygnus @command{configure}, which was being developed at around that time,
18186 is table driven; it is meant to deal mainly with a discrete number of
18187 system types with a small number of mainly unguessable features (such as
18188 details of the object file format).  The automatic configuration system
18189 that Brian Fox had developed for Bash takes a similar approach.  For
18190 general use, it seems to me a hopeless cause to try to maintain an
18191 up-to-date database of which features each variant of each operating
18192 system has.  It's easier and more reliable to check for most features on
18193 the fly---especially on hybrid systems that people have hacked on
18194 locally or that have patches from vendors installed.
18196 I considered using an architecture similar to that of Cygnus
18197 @command{configure}, where there is a single @command{configure} script that
18198 reads pieces of @file{configure.in} when run.  But I didn't want to have
18199 to distribute all of the feature tests with every package, so I settled
18200 on having a different @command{configure} made from each
18201 @file{configure.in} by a preprocessor.  That approach also offered more
18202 control and flexibility.
18204 I looked briefly into using the Metaconfig package, by Larry Wall,
18205 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
18206 reasons.  The @command{Configure} scripts it produces are interactive,
18207 which I find quite inconvenient; I didn't like the ways it checked for
18208 some features (such as library functions); I didn't know that it was
18209 still being maintained, and the @command{Configure} scripts I had
18210 seen didn't work on many modern systems (such as System V R4 and NeXT);
18211 it wasn't very flexible in what it could do in response to a feature's
18212 presence or absence; I found it confusing to learn; and it was too big
18213 and complex for my needs (I didn't realize then how much Autoconf would
18214 eventually have to grow).
18216 I considered using Perl to generate my style of @command{configure}
18217 scripts, but decided that M4 was better suited to the job of simple
18218 textual substitutions: it gets in the way less, because output is
18219 implicit.  Plus, everyone already has it.  (Initially I didn't rely on
18220 the @acronym{GNU} extensions to M4.)  Also, some of my friends at the
18221 University of Maryland had recently been putting M4 front ends on
18222 several programs, including @code{tvtwm}, and I was interested in trying
18223 out a new language.
18225 @node Leviticus
18226 @section Leviticus
18228 Since my @command{configure} scripts determine the system's capabilities
18229 automatically, with no interactive user intervention, I decided to call
18230 the program that generates them Autoconfig.  But with a version number
18231 tacked on, that name would be too long for old Unix file systems,
18232 so I shortened it to Autoconf.
18234 In the fall of 1991 I called together a group of fellow questers after
18235 the Holy Grail of portability (er, that is, alpha testers) to give me
18236 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
18237 and continued to add features and improve the techniques used in the
18238 checks.  Prominent among the testers were Fran@,{c}ois Pinard, who came up
18239 with the idea of making an Autoconf shell script to run M4
18240 and check for unresolved macro calls; Richard Pixley, who suggested
18241 running the compiler instead of searching the file system to find
18242 include files and symbols, for more accurate results; Karl Berry, who
18243 got Autoconf to configure @TeX{} and added the macro index to the
18244 documentation; and Ian Lance Taylor, who added support for creating a C
18245 header file as an alternative to putting @option{-D} options in a
18246 @file{Makefile}, so he could use Autoconf for his @acronym{UUCP} package.
18247 The alpha testers cheerfully adjusted their files again and again as the
18248 names and calling conventions of the Autoconf macros changed from
18249 release to release.  They all contributed many specific checks, great
18250 ideas, and bug fixes.
18252 @node Numbers
18253 @section Numbers
18255 In July 1992, after months of alpha testing, I released Autoconf 1.0,
18256 and converted many @acronym{GNU} packages to use it.  I was surprised by how
18257 positive the reaction to it was.  More people started using it than I
18258 could keep track of, including people working on software that wasn't
18259 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
18260 Autoconf continued to improve rapidly, as many people using the
18261 @command{configure} scripts reported problems they encountered.
18263 Autoconf turned out to be a good torture test for M4 implementations.
18264 Unix M4 started to dump core because of the length of the
18265 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
18266 M4 as well.  Eventually, we realized that we needed to use some
18267 features that only @acronym{GNU} M4 has.  4.3@acronym{BSD} M4, in
18268 particular, has an impoverished set of builtin macros; the System V
18269 version is better, but still doesn't provide everything we need.
18271 More development occurred as people put Autoconf under more stresses
18272 (and to uses I hadn't anticipated).  Karl Berry added checks for X11.
18273 david zuhn contributed C++ support.  Fran@,{c}ois Pinard made it diagnose
18274 invalid arguments.  Jim Blandy bravely coerced it into configuring
18275 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
18276 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
18277 @command{autoheader} script to automate the creation of C header file
18278 templates, and added a @option{--verbose} option to @command{configure}.
18279 Noah Friedman added the @option{--autoconf-dir} option and
18280 @code{AC_MACRODIR} environment variable.  (He also coined the term
18281 @dfn{autoconfiscate} to mean ``adapt a software package to use
18282 Autoconf''.)  Roland and Noah improved the quoting protection in
18283 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
18284 dealing with portability problems from February through June, 1993.
18286 @node Deuteronomy
18287 @section Deuteronomy
18289 A long wish list for major features had accumulated, and the effect of
18290 several years of patching by various people had left some residual
18291 cruft.  In April 1994, while working for Cygnus Support, I began a major
18292 revision of Autoconf.  I added most of the features of the Cygnus
18293 @command{configure} that Autoconf had lacked, largely by adapting the
18294 relevant parts of Cygnus @command{configure} with the help of david zuhn
18295 and Ken Raeburn.  These features include support for using
18296 @file{config.sub}, @file{config.guess}, @option{--host}, and
18297 @option{--target}; making links to files; and running @command{configure}
18298 scripts in subdirectories.  Adding these features enabled Ken to convert
18299 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
18300 Autoconf.
18302 I added more features in response to other peoples' requests.  Many
18303 people had asked for @command{configure} scripts to share the results of
18304 the checks between runs, because (particularly when configuring a large
18305 source tree, like Cygnus does) they were frustratingly slow.  Mike
18306 Haertel suggested adding site-specific initialization scripts.  People
18307 distributing software that had to unpack on MS-DOS asked for a way to
18308 override the @file{.in} extension on the file names, which produced file
18309 names like @file{config.h.in} containing two dots.  Jim Avera did an
18310 extensive examination of the problems with quoting in @code{AC_DEFINE}
18311 and @code{AC_SUBST}; his insights led to significant improvements.
18312 Richard Stallman asked that compiler output be sent to @file{config.log}
18313 instead of @file{/dev/null}, to help people debug the Emacs
18314 @command{configure} script.
18316 I made some other changes because of my dissatisfaction with the quality
18317 of the program.  I made the messages showing results of the checks less
18318 ambiguous, always printing a result.  I regularized the names of the
18319 macros and cleaned up coding style inconsistencies.  I added some
18320 auxiliary utilities that I had developed to help convert source code
18321 packages to use Autoconf.  With the help of Fran@,{c}ois Pinard, I made
18322 the macros not interrupt each others' messages.  (That feature revealed
18323 some performance bottlenecks in @acronym{GNU} M4, which he hastily
18324 corrected!)  I reorganized the documentation around problems people want
18325 to solve.  And I began a test suite, because experience had shown that
18326 Autoconf has a pronounced tendency to regress when we change it.
18328 Again, several alpha testers gave invaluable feedback, especially
18329 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
18330 and Mark Eichin.
18332 Finally, version 2.0 was ready.  And there was much rejoicing.  (And I
18333 have free time again.  I think.  Yeah, right.)
18336 @c ========================================================== Appendices
18338 @node Copying This Manual
18339 @appendix Copying This Manual
18340 @cindex License
18342 @menu
18343 * GNU Free Documentation License::  License for copying this manual
18344 @end menu
18346 @include fdl.texi
18348 @node Indices
18349 @appendix Indices
18351 @menu
18352 * Environment Variable Index::  Index of environment variables used
18353 * Output Variable Index::       Index of variables set in output files
18354 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
18355 * Autoconf Macro Index::        Index of Autoconf macros
18356 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
18357 * Autotest Macro Index::        Index of Autotest macros
18358 * Program & Function Index::    Index of those with portability problems
18359 * Concept Index::               General index
18360 @end menu
18362 @node Environment Variable Index
18363 @appendixsec Environment Variable Index
18365 This is an alphabetical list of the environment variables that Autoconf
18366 checks.
18368 @printindex ev
18370 @node Output Variable Index
18371 @appendixsec Output Variable Index
18373 This is an alphabetical list of the variables that Autoconf can
18374 substitute into files that it creates, typically one or more
18375 @file{Makefile}s.  @xref{Setting Output Variables}, for more information
18376 on how this is done.
18378 @printindex ov
18380 @node Preprocessor Symbol Index
18381 @appendixsec Preprocessor Symbol Index
18383 This is an alphabetical list of the C preprocessor symbols that the
18384 Autoconf macros define.  To work with Autoconf, C source code needs to
18385 use these names in @code{#if} directives.
18387 @printindex cv
18389 @node Autoconf Macro Index
18390 @appendixsec Autoconf Macro Index
18392 This is an alphabetical list of the Autoconf macros.
18393 @ifset shortindexflag
18394 To make the list easier to use, the macros are listed without their
18395 preceding @samp{AC_}.
18396 @end ifset
18398 @printindex AC
18400 @node M4 Macro Index
18401 @appendixsec M4 Macro Index
18403 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
18404 @ifset shortindexflag
18405 To make the list easier to use, the macros are listed without their
18406 preceding @samp{m4_} or @samp{AS_}.
18407 @end ifset
18409 @printindex MS
18411 @node Autotest Macro Index
18412 @appendixsec Autotest Macro Index
18414 This is an alphabetical list of the Autotest macros.
18415 @ifset shortindexflag
18416 To make the list easier to use, the macros are listed without their
18417 preceding @samp{AT_}.
18418 @end ifset
18420 @printindex AT
18422 @node Program & Function Index
18423 @appendixsec Program and Function Index
18425 This is an alphabetical list of the programs and functions which
18426 portability is discussed in this document.
18428 @printindex pr
18430 @node Concept Index
18431 @appendixsec Concept Index
18433 This is an alphabetical list of the files, tools, and concepts
18434 introduced in this document.
18436 @printindex cp
18438 @bye
18440 @c  LocalWords:  texinfo setfilename autoconf texi settitle setchapternewpage
18441 @c  LocalWords:  setcontentsaftertitlepage finalout ARG ovar varname dvar acx
18442 @c  LocalWords:  makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
18443 @c  LocalWords:  shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
18444 @c  LocalWords:  asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
18445 @c  LocalWords:  msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
18446 @c  LocalWords:  direntry autoscan autoreconf autoheader autoupdate config FDs
18447 @c  LocalWords:  testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
18448 @c  LocalWords:  insertcopying Autoconf's detailmenu Automake Libtool Posix ois
18449 @c  LocalWords:  Systemology Checkpointing Changequote INTERCAL changequote dfn
18450 @c  LocalWords:  Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
18451 @c  LocalWords:  LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
18452 @c  LocalWords:  distclean uninstall noindent versioning Tromey dir
18453 @c  LocalWords:  SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
18454 @c  LocalWords:  evindex automake Gettext autopoint gettext symlink libtoolize
18455 @c  LocalWords:  defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
18456 @c  LocalWords:  SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
18457 @c  LocalWords:  builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
18458 @c  LocalWords:  CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
18459 @c  LocalWords:  datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
18460 @c  LocalWords:  includedir infodir libexecdir localedir localstatedir mandir
18461 @c  LocalWords:  oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
18462 @c  LocalWords:  sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
18463 @c  LocalWords:  undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
18464 @c  LocalWords:  PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
18465 @c  LocalWords:  inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
18466 @c  LocalWords:  LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
18467 @c  LocalWords:  inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
18468 @c  LocalWords:  NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
18469 @c  LocalWords:  ld inline malloc OSF putenv setenv FreeBSD realloc SunOS MinGW
18470 @c  LocalWords:  snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
18471 @c  LocalWords:  strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
18472 @c  LocalWords:  PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
18473 @c  LocalWords:  closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
18474 @c  LocalWords:  largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
18475 @c  LocalWords:  GETLODAVG SETGID getloadavg nlist setgid setuid GETMNTENT irix
18476 @c  LocalWords:  getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
18477 @c  LocalWords:  lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
18478 @c  LocalWords:  localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
18479 @c  LocalWords:  SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
18480 @c  LocalWords:  STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
18481 @c  LocalWords:  DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
18482 @c  LocalWords:  linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
18483 @c  LocalWords:  NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
18484 @c  LocalWords:  inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB
18485 @c  LocalWords:  STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
18486 @c  LocalWords:  ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
18487 @c  LocalWords:  WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
18488 @c  LocalWords:  DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
18489 @c  LocalWords:  passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
18490 @c  LocalWords:  gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str
18491 @c  LocalWords:  ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
18492 @c  LocalWords:  varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
18493 @c  LocalWords:  const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
18494 @c  LocalWords:  xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
18495 @c  LocalWords:  ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
18496 @c  LocalWords:  fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
18497 @c  LocalWords:  statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
18498 @c  LocalWords:  GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
18499 @c  LocalWords:  changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
18500 @c  LocalWords:  Aas Wcross sep args namespace undefine bpatsubst popdef dquote
18501 @c  LocalWords:  bregexp Overquote overquotation meisch maisch meische maische
18502 @c  LocalWords:  miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
18503 @c  LocalWords:  EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
18504 @c  LocalWords:  pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
18505 @c  LocalWords:  drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
18506 @c  LocalWords:  yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
18507 @c  LocalWords:  CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
18508 @c  LocalWords:  MAILPATH scanset arg NetBSD Almquist printf expr cp
18509 @c  LocalWords:  Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS unwriteable te VM
18510 @c  LocalWords:  coreutils sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc
18511 @c  LocalWords:  mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
18512 @c  LocalWords:  fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped
18513 @c  LocalWords:  pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
18514 @c  LocalWords:  dec ultrix cpu wildcards rpcc rdtsc powerpc behaviour readline
18515 @c  LocalWords:  withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
18516 @c  LocalWords:  cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
18517 @c  LocalWords:  lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
18518 @c  LocalWords:  intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
18519 @c  LocalWords:  fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
18520 @c  LocalWords:  ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
18521 @c  LocalWords:  installcheck autotest indir Pixley Bothner Eichin Kerberos adl
18522 @c  LocalWords:  DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
18523 @c  LocalWords:  Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
18524 @c  LocalWords:  autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
18525 @c  LocalWords:  printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
18526 @c  LocalWords:  VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
18527 @c  LocalWords:  GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
18528 @c  LocalWords:  esyscmd len maketemp pushdef substr syscmd sysval translit txt
18529 @c  LocalWords:  sinclude foreach myvar tolower toupper uniq BASENAME STDIN ig
18530 @c  LocalWords:  Dynix descrips basename aname cname ih macroexpands xno xcheck
18531 @c  LocalWords:  LIBREADLINE lreadline lncurses libreadline
18533 @c Local Variables:
18534 @c fill-column: 72
18535 @c ispell-local-dictionary: "american"
18536 @c End: