1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
9 @setcontentsaftertitlepage
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).
18 @r{[}@var{\varname\}@r{]}
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{]}
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.
51 @c Define an output variable index.
53 @c Define a CPP variable index.
55 @c Define an Autoconf macro index that @defmac doesn't write to.
57 @c Define an Autotest macro index that @defmac doesn't write to.
59 @c Define an M4sugar macro index that @defmac doesn't write to.
61 @c Define an index for *foreign* programs: `mv' etc. Used for the
62 @c portability sections and so on.
67 @c Shall we factor AC_ out of the Autoconf macro index etc.?
74 @c Registering an AC_\MACRO\.
81 @ifclear shortindexflag
89 @c Registering an AH_\MACRO\.
97 @c Registering an AS_\MACRO\.
104 @ifclear shortindexflag
105 @macro asindex{macro}
112 @c Registering an AT_\MACRO\.
113 @ifset shortindexflag
114 @macro atindex{macro}
119 @ifclear shortindexflag
120 @macro atindex{macro}
127 @c Registering an AU_\MACRO\.
128 @macro auindex{macro}
135 @c Indexing a header.
136 @macro hdrindex{macro}
137 @prindex @file{\macro\}
143 @c Registering an m4_\MACRO\.
144 @ifset shortindexflag
145 @macro msindex{macro}
150 @ifclear shortindexflag
151 @macro msindex{macro}
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.
172 @c @c Put the programs and functions into their own index.
173 @c @syncodeindex fu pr
175 @comment %**end of header
176 @comment ========================================================
180 This manual is for @acronym{GNU} Autoconf
181 (version @value{VERSION}, @value{UPDATED}),
182 a package for creating scripts to configure source code packages using
183 templates and an M4 macro package.
185 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
186 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
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.''
206 @dircategory Software development
208 * Autoconf: (autoconf). Create source code configuration scripts.
211 @dircategory Individual utilities
213 * autoscan: (autoconf)autoscan Invocation.
214 Semi-automatic @file{configure.ac} writing
215 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
216 * autoconf-invocation: (autoconf)autoconf Invocation.
217 How to create configuration scripts
218 * autoreconf: (autoconf)autoreconf Invocation.
219 Remaking multiple @command{configure} scripts
220 * autoheader: (autoconf)autoheader Invocation.
221 How to create configuration templates
222 * autom4te: (autoconf)autom4te Invocation.
223 The Autoconf executables backbone
224 * configure: (autoconf)configure Invocation. Configuring a package.
225 * autoupdate: (autoconf)autoupdate Invocation.
226 Automatic update of @file{configure.ac}
227 * config.status: (autoconf)config.status Invocation. Recreating configurations.
228 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
233 @subtitle Creating Automatic Configuration Scripts
234 @subtitle for version @value{VERSION}, @value{UPDATED}
235 @author David MacKenzie
237 @author Akim Demaille
239 @vskip 0pt plus 1filll
252 @c The master menu, created with texinfo-master-menu, goes here.
255 * Introduction:: Autoconf's purpose, strengths, and weaknesses
256 * The GNU Build System:: A set of tools for portable software packages
257 * Making configure Scripts:: How to organize and produce Autoconf scripts
258 * Setup:: Initialization and output
259 * Existing Tests:: Macros that check for particular features
260 * Writing Tests:: How to write new feature checks
261 * Results:: What to do with results from feature checks
262 * Programming in M4:: Layers on top of which Autoconf is written
263 * Writing Autoconf Macros:: Adding new macros to Autoconf
264 * Portable Shell:: Shell script portability pitfalls
265 * Portable Make:: Makefile portability pitfalls
266 * Portable C and C++:: C and C++ portability pitfalls
267 * Manual Configuration:: Selecting features that can't be guessed
268 * Site Configuration:: Local defaults for @command{configure}
269 * Running configure Scripts:: How to use the Autoconf output
270 * config.status Invocation:: Recreating a configuration
271 * Obsolete Constructs:: Kept for backward compatibility
272 * Using Autotest:: Creating portable test suites
273 * FAQ:: Frequent Autoconf Questions, with answers
274 * History:: History of Autoconf
275 * GNU Free Documentation License:: License for copying this manual
276 * Indices:: Indices of symbols, concepts, etc.
279 --- The Detailed Node Listing ---
281 The @acronym{GNU} Build System
283 * Automake:: Escaping makefile hell
284 * Gnulib:: The @acronym{GNU} portability library
285 * Libtool:: Building libraries portably
286 * Pointers:: More info on the @acronym{GNU} build system
288 Making @command{configure} Scripts
290 * Writing Autoconf Input:: What to put in an Autoconf input file
291 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
292 * ifnames Invocation:: Listing the conditionals in source code
293 * autoconf Invocation:: How to create configuration scripts
294 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
296 Writing @file{configure.ac}
298 * Shell Script Compiler:: Autoconf as solution of a problem
299 * Autoconf Language:: Programming in Autoconf
300 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
302 Initialization and Output Files
304 * Initializing configure:: Option processing etc.
305 * Versioning:: Dealing with Autoconf versions
306 * Notices:: Copyright, version numbers in @command{configure}
307 * Input:: Where Autoconf should find files
308 * Output:: Outputting results from the configuration
309 * Configuration Actions:: Preparing the output based on results
310 * Configuration Files:: Creating output files
311 * Makefile Substitutions:: Using output variables in makefiles
312 * Configuration Headers:: Creating a configuration header file
313 * Configuration Commands:: Running arbitrary instantiation commands
314 * Configuration Links:: Links depending on the configuration
315 * Subdirectories:: Configuring independent packages together
316 * Default Prefix:: Changing the default installation prefix
318 Substitutions in Makefiles
320 * Preset Output Variables:: Output variables that are always set
321 * Installation Directory Variables:: Other preset output variables
322 * Changed Directory Variables:: Warnings about @file{datarootdir}
323 * Build Directories:: Supporting multiple concurrent compiles
324 * Automatic Remaking:: Makefile rules for configuring
326 Configuration Header Files
328 * Header Templates:: Input for the configuration headers
329 * autoheader Invocation:: How to create configuration templates
330 * Autoheader Macros:: How to specify CPP templates
334 * Common Behavior:: Macros' standard schemes
335 * Alternative Programs:: Selecting between alternative programs
336 * Files:: Checking for the existence of files
337 * Libraries:: Library archives that might be missing
338 * Library Functions:: C library functions that might be missing
339 * Header Files:: Header files that might be missing
340 * Declarations:: Declarations that may be missing
341 * Structures:: Structures or members that might be missing
342 * Types:: Types that might be missing
343 * Compilers and Preprocessors:: Checking for compiling programs
344 * System Services:: Operating system services
345 * Posix Variants:: Special kludges for specific Posix variants
346 * Erlang Libraries:: Checking for the existence of Erlang libraries
350 * Standard Symbols:: Symbols defined by the macros
351 * Default Includes:: Includes used by the generic macros
355 * Particular Programs:: Special handling to find certain programs
356 * Generic Programs:: How to find other programs
360 * Function Portability:: Pitfalls with usual functions
361 * Particular Functions:: Special handling to find certain functions
362 * Generic Functions:: How to find other functions
366 * Header Portability:: Collected knowledge on common headers
367 * Particular Headers:: Special handling to find certain headers
368 * Generic Headers:: How to find other headers
372 * Particular Declarations:: Macros to check for certain declarations
373 * Generic Declarations:: How to find other declarations
377 * Particular Structures:: Macros to check for certain structure members
378 * Generic Structures:: How to find other structure members
382 * Particular Types:: Special handling to find certain types
383 * Generic Types:: How to find other types
385 Compilers and Preprocessors
387 * Specific Compiler Characteristics:: Some portability issues
388 * Generic Compiler Characteristics:: Language independent tests and features
389 * C Compiler:: Checking its characteristics
390 * C++ Compiler:: Likewise
391 * Objective C Compiler:: Likewise
392 * Erlang Compiler and Interpreter:: Likewise
393 * Fortran Compiler:: Likewise
397 * Language Choice:: Selecting which language to use for testing
398 * Writing Test Programs:: Forging source files for compilers
399 * Running the Preprocessor:: Detecting preprocessor symbols
400 * Running the Compiler:: Detecting language or header features
401 * Running the Linker:: Detecting library features
402 * Runtime:: Testing for runtime features
403 * Systemology:: A zoology of operating systems
404 * Multiple Cases:: Tests for several possible values
406 Writing Test Programs
408 * Guidelines:: General rules for writing test programs
409 * Test Functions:: Avoiding pitfalls in test programs
410 * Generating Sources:: Source program boilerplate
414 * Defining Symbols:: Defining C preprocessor symbols
415 * Setting Output Variables:: Replacing variables in output files
416 * Special Chars in Variables:: Characters to beware of in variables
417 * Caching Results:: Speeding up subsequent @command{configure} runs
418 * Printing Messages:: Notifying @command{configure} users
422 * Cache Variable Names:: Shell variables used in caches
423 * Cache Files:: Files @command{configure} uses for caching
424 * Cache Checkpointing:: Loading and saving the cache file
428 * M4 Quotation:: Protecting macros from unwanted expansion
429 * Using autom4te:: The Autoconf executables backbone
430 * Programming in M4sugar:: Convenient pure M4 macros
431 * Programming in M4sh:: Common shell Constructs
432 * File Descriptor Macros:: File descriptor macros for input and output
436 * Active Characters:: Characters that change the behavior of M4
437 * One Macro Call:: Quotation and one macro call
438 * Quoting and Parameters:: M4 vs. shell parameters
439 * Quotation and Nested Macros:: Macros calling macros
440 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
441 * Quadrigraphs:: Another way to escape special characters
442 * Quotation Rule Of Thumb:: One parenthesis, one quote
444 Using @command{autom4te}
446 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
447 * Customizing autom4te:: Customizing the Autoconf package
449 Programming in M4sugar
451 * Redefined M4 Macros:: M4 builtins changed in M4sugar
452 * Conditional constructs:: Conditions in M4
453 * Looping constructs:: Iteration in M4
454 * Evaluation Macros:: More quotation and evaluation control
455 * Text processing Macros:: String manipulation in M4
456 * Forbidden Patterns:: Catching unexpanded macros
458 Writing Autoconf Macros
460 * Macro Definitions:: Basic format of an Autoconf macro
461 * Macro Names:: What to call your new macros
462 * Reporting Messages:: Notifying @command{autoconf} users
463 * Dependencies Between Macros:: What to do when macros depend on other macros
464 * Obsoleting Macros:: Warning about old ways of doing things
465 * Coding Style:: Writing Autoconf macros @`a la Autoconf
467 Dependencies Between Macros
469 * Prerequisite Macros:: Ensuring required information
470 * Suggested Ordering:: Warning about possible ordering problems
471 * One-Shot Macros:: Ensuring a macro is called only once
473 Portable Shell Programming
475 * Shellology:: A zoology of shells
476 * Here-Documents:: Quirks and tricks
477 * File Descriptors:: FDs and redirections
478 * File System Conventions:: File names
479 * Shell Pattern Matching:: Pattern matching
480 * Shell Substitutions:: Variable and command expansions
481 * Assignments:: Varying side effects of assignments
482 * Parentheses:: Parentheses in shell scripts
483 * Slashes:: Slashes in shell scripts
484 * Special Shell Variables:: Variables you should not change
485 * Limitations of Builtins:: Portable use of not so portable /bin/sh
486 * Limitations of Usual Tools:: Portable use of portable tools
488 Portable Make Programming
490 * $< in Ordinary Make Rules:: $< in ordinary rules
491 * Failure in Make Rules:: Failing portably in rules
492 * Special Chars in Names:: Special Characters in Macro Names
493 * Backslash-Newline-Newline:: Empty last lines in macro definitions
494 * Backslash-Newline Comments:: Spanning comments across line boundaries
495 * Long Lines in Makefiles:: Line length limitations
496 * Macros and Submakes:: @code{make macro=value} and submakes
497 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
498 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
499 * Comments in Make Rules:: Other problems with Make comments
500 * obj/ and Make:: Don't name a subdirectory @file{obj}
501 * make -k Status:: Exit status of @samp{make -k}
502 * VPATH and Make:: @code{VPATH} woes
503 * Single Suffix Rules:: Single suffix rules and separated dependencies
504 * Timestamps and Make:: Subsecond timestamp resolution
506 @code{VPATH} and Make
508 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
509 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
510 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
511 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
512 * Make Target Lookup:: More details about @code{VPATH} lookup
514 Portable C and C++ Programming
516 * Varieties of Unportability:: How to make your programs unportable
517 * Integer Overflow:: When integers get too large
518 * Null Pointers:: Properties of null pointers
519 * Buffer Overruns:: Subscript errors and the like
520 * Volatile Objects:: @code{volatile} and signals
521 * Floating Point Portability:: Portable floating-point arithmetic
522 * Exiting Portably:: Exiting and the exit status
526 * Specifying Names:: Specifying the system type
527 * Canonicalizing:: Getting the canonical system type
528 * Using System Type:: What to do with the system type
532 * Help Formatting:: Customizing @samp{configure --help}
533 * External Software:: Working with other optional software
534 * Package Options:: Selecting optional features
535 * Pretty Help Strings:: Formatting help string
536 * Option Checking:: Controlling checking of @command{configure} options
537 * Site Details:: Configuring site details
538 * Transforming Names:: Changing program names when installing
539 * Site Defaults:: Giving @command{configure} local defaults
541 Transforming Program Names When Installing
543 * Transformation Options:: @command{configure} options to transform names
544 * Transformation Examples:: Sample uses of transforming names
545 * Transformation Rules:: Makefile uses of transforming names
547 Running @command{configure} Scripts
549 * Basic Installation:: Instructions for typical cases
550 * Compilers and Options:: Selecting compilers and optimization
551 * Multiple Architectures:: Compiling for multiple architectures at once
552 * Installation Names:: Installing in different directories
553 * Optional Features:: Selecting optional features
554 * System Type:: Specifying the system type
555 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
556 * Defining Variables:: Specifying the compiler etc.
557 * configure Invocation:: Changing how @command{configure} runs
561 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
562 * acconfig Header:: Additional entries in @file{config.h.in}
563 * autoupdate Invocation:: Automatic update of @file{configure.ac}
564 * Obsolete Macros:: Backward compatibility macros
565 * Autoconf 1:: Tips for upgrading your files
566 * Autoconf 2.13:: Some fresher tips
568 Upgrading From Version 1
570 * Changed File Names:: Files you might rename
571 * Changed Makefiles:: New things to put in @file{Makefile.in}
572 * Changed Macros:: Macro calls you might replace
573 * Changed Results:: Changes in how to check test results
574 * Changed Macro Writing:: Better ways to write your own macros
576 Upgrading From Version 2.13
578 * Changed Quotation:: Broken code which used to work
579 * New Macros:: Interaction with foreign macros
580 * Hosts and Cross-Compilation:: Bugward compatibility kludges
581 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
582 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
584 Generating Test Suites with Autotest
586 * Using an Autotest Test Suite:: Autotest and the user
587 * Writing Testsuites:: Autotest macros
588 * testsuite Invocation:: Running @command{testsuite} scripts
589 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
591 Using an Autotest Test Suite
593 * testsuite Scripts:: The concepts of Autotest
594 * Autotest Logs:: Their contents
596 Frequent Autoconf Questions, with answers
598 * Distributing:: Distributing @command{configure} scripts
599 * Why GNU M4:: Why not use the standard M4?
600 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
601 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
602 * Defining Directories:: Passing @code{datadir} to program
603 * Autom4te Cache:: What is it? Can I remove it?
604 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
608 * Genesis:: Prehistory and naming of @command{configure}
609 * Exodus:: The plagues of M4 and Perl
610 * Leviticus:: The priestly code of portability arrives
611 * Numbers:: Growth and contributors
612 * Deuteronomy:: Approaching the promises of easy configuration
616 * Environment Variable Index:: Index of environment variables used
617 * Output Variable Index:: Index of variables set in output files
618 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
619 * Autoconf Macro Index:: Index of Autoconf macros
620 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
621 * Autotest Macro Index:: Index of Autotest macros
622 * Program & Function Index:: Index of those with portability problems
623 * Concept Index:: General index
628 @c ============================================================= Introduction.
631 @chapter Introduction
635 A physicist, an engineer, and a computer scientist were discussing the
636 nature of God. ``Surely a Physicist,'' said the physicist, ``because
637 early in the Creation, God made Light; and you know, Maxwell's
638 equations, the dual nature of electromagnetic waves, the relativistic
639 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
640 before making Light, God split the Chaos into Land and Water; it takes a
641 hell of an engineer to handle that big amount of mud, and orderly
642 separation of solids from liquids@dots{}'' The computer scientist
643 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
647 @c (via Franc,ois Pinard)
649 Autoconf is a tool for producing shell scripts that automatically
650 configure software source code packages to adapt to many kinds of
651 Posix-like systems. The configuration scripts produced by Autoconf
652 are independent of Autoconf when they are run, so their users do not
653 need to have Autoconf.
655 The configuration scripts produced by Autoconf require no manual user
656 intervention when run; they do not normally even need an argument
657 specifying the system type. Instead, they individually test for the
658 presence of each feature that the software package they are for might need.
659 (Before each check, they print a one-line message stating what they are
660 checking for, so the user doesn't get too bored while waiting for the
661 script to finish.) As a result, they deal well with systems that are
662 hybrids or customized from the more common Posix variants. There is
663 no need to maintain files that list the features supported by each
664 release of each variant of Posix.
666 For each software package that Autoconf is used with, it creates a
667 configuration script from a template file that lists the system features
668 that the package needs or can use. After the shell code to recognize
669 and respond to a system feature has been written, Autoconf allows it to
670 be shared by many software packages that can use (or need) that feature.
671 If it later turns out that the shell code needs adjustment for some
672 reason, it needs to be changed in only one place; all of the
673 configuration scripts can be regenerated automatically to take advantage
676 The Metaconfig package is similar in purpose to Autoconf, but the
677 scripts it produces require manual user intervention, which is quite
678 inconvenient when configuring large source trees. Unlike Metaconfig
679 scripts, Autoconf scripts can support cross-compiling, if some care is
680 taken in writing them.
682 Autoconf does not solve all problems related to making portable
683 software packages---for a more complete solution, it should be used in
684 concert with other @acronym{GNU} build tools like Automake and
685 Libtool. These other tools take on jobs like the creation of a
686 portable, recursive makefile with all of the standard targets,
687 linking of shared libraries, and so on. @xref{The GNU Build System},
688 for more information.
690 Autoconf imposes some restrictions on the names of macros used with
691 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
693 Autoconf requires @acronym{GNU} M4 version 1.4.5 or later in order to
694 generate the scripts. It uses features that some versions of M4,
695 including @acronym{GNU} M4 1.3, do not have. Autoconf works better
696 with @acronym{GNU} M4 version 1.4.8 or later, though this is not
699 @xref{Autoconf 1}, for information about upgrading from version 1.
700 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
701 for answers to some common questions about Autoconf.
703 See the @uref{http://www.gnu.org/software/autoconf/,
704 Autoconf web page} for up-to-date information, details on the mailing
705 lists, pointers to a list of known bugs, etc.
707 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
708 list}. Past suggestions are
709 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
711 Mail bug reports to @email{bug-autoconf@@gnu.org, the
712 Autoconf Bugs mailing list}. Past bug reports are
713 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
715 If possible, first check that your bug is
716 not already solved in current development versions, and that it has not
717 been reported yet. Be sure to include all the needed information and a
718 short @file{configure.ac} that demonstrates the problem.
720 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
721 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
722 Summary} for details. Patches relative to the
723 current @acronym{CVS} version can be sent for review to the
724 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
726 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
728 Because of its mission, the Autoconf package itself
729 includes only a set of often-used
730 macros that have already demonstrated their usefulness. Nevertheless,
731 if you wish to share your macros, or find existing ones, see the
732 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
733 Archive}, which is kindly run by @email{simons@@cryp.to,
737 @c ================================================= The GNU Build System
739 @node The GNU Build System
740 @chapter The @acronym{GNU} Build System
741 @cindex @acronym{GNU} build system
743 Autoconf solves an important problem---reliable discovery of
744 system-specific build and runtime information---but this is only one
745 piece of the puzzle for the development of portable software. To this
746 end, the @acronym{GNU} project has developed a suite of integrated
747 utilities to finish the job Autoconf started: the @acronym{GNU} build
748 system, whose most important components are Autoconf, Automake, and
749 Libtool. In this chapter, we introduce you to those tools, point you
750 to sources of more information, and try to convince you to use the
751 entire @acronym{GNU} build system for your software.
754 * Automake:: Escaping makefile hell
755 * Gnulib:: The @acronym{GNU} portability library
756 * Libtool:: Building libraries portably
757 * Pointers:: More info on the @acronym{GNU} build system
763 The ubiquity of @command{make} means that a makefile is almost the
764 only viable way to distribute automatic build rules for software, but
765 one quickly runs into its numerous limitations. Its lack of
766 support for automatic dependency tracking, recursive builds in
767 subdirectories, reliable timestamps (e.g., for network file systems), and
768 so on, mean that developers must painfully (and often incorrectly)
769 reinvent the wheel for each project. Portability is non-trivial, thanks
770 to the quirks of @command{make} on many systems. On top of all this is the
771 manual labor required to implement the many standard targets that users
772 have come to expect (@code{make install}, @code{make distclean},
773 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
774 you also have to insert repetitive code in your @code{Makefile.in} to
775 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
776 provided by @command{configure}. Into this mess steps @dfn{Automake}.
779 Automake allows you to specify your build needs in a @code{Makefile.am}
780 file with a vastly simpler and more powerful syntax than that of a plain
781 makefile, and then generates a portable @code{Makefile.in} for
782 use with Autoconf. For example, the @code{Makefile.am} to build and
783 install a simple ``Hello world'' program might look like:
787 hello_SOURCES = hello.c
791 The resulting @code{Makefile.in} (~400 lines) automatically supports all
792 the standard targets, the substitutions provided by Autoconf, automatic
793 dependency tracking, @code{VPATH} building, and so on. @command{make}
794 builds the @code{hello} program, and @code{make install} installs it
795 in @file{/usr/local/bin} (or whatever prefix was given to
796 @command{configure}, if not @file{/usr/local}).
798 The benefits of Automake increase for larger packages (especially ones
799 with subdirectories), but even for small programs the added convenience
800 and portability can be substantial. And that's not all@enddots{}
805 @acronym{GNU} software has a well-deserved reputation for running on
806 many different types of systems. While our primary goal is to write
807 software for the @acronym{GNU} system, many users and developers have
808 been introduced to us through the systems that they were already using.
811 Gnulib is a central location for common @acronym{GNU} code, intended to
812 be shared among free software packages. Its components are typically
813 shared at the source level, rather than being a library that gets built,
814 installed, and linked against. The idea is to copy files from Gnulib
815 into your own source tree. There is no distribution tarball; developers
816 should just grab source modules from the repository. The source files
817 are available online, under various licenses, mostly @acronym{GNU}
818 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
820 Gnulib modules typically contain C source code along with Autoconf
821 macros used to configure the source code. For example, the Gnulib
822 @code{stdbool} module implements a @file{stdbool.h} header that nearly
823 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
824 This module contains a source file for the replacement header, along
825 with an Autoconf macro that arranges to use the replacement header on
826 old-fashioned systems.
831 Often, one wants to build not only programs, but libraries, so that
832 other programs can benefit from the fruits of your labor. Ideally, one
833 would like to produce @emph{shared} (dynamically linked) libraries,
834 which can be used by multiple programs without duplication on disk or in
835 memory and can be updated independently of the linked programs.
836 Producing shared libraries portably, however, is the stuff of
837 nightmares---each system has its own incompatible tools, compiler flags,
838 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
842 Libtool handles all the requirements of building shared libraries for
843 you, and at this time seems to be the @emph{only} way to do so with any
844 portability. It also handles many other headaches, such as: the
845 interaction of Make rules with the variable suffixes of
846 shared libraries, linking reliably with shared libraries before they are
847 installed by the superuser, and supplying a consistent versioning system
848 (so that different versions of a library can be installed or upgraded
849 without breaking binary compatibility). Although Libtool, like
850 Autoconf, can be used without Automake, it is most simply utilized in
851 conjunction with Automake---there, Libtool is used automatically
852 whenever shared libraries are needed, and you need not know its syntax.
857 Developers who are used to the simplicity of @command{make} for small
858 projects on a single system might be daunted at the prospect of
859 learning to use Automake and Autoconf. As your software is
860 distributed to more and more users, however, you otherwise
861 quickly find yourself putting lots of effort into reinventing the
862 services that the @acronym{GNU} build tools provide, and making the
863 same mistakes that they once made and overcame. (Besides, since
864 you're already learning Autoconf, Automake is a piece of cake.)
866 There are a number of places that you can go to for more information on
867 the @acronym{GNU} build tools.
874 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
875 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
876 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
877 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
879 @item Automake Manual
881 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
882 information on Automake.
886 The book @cite{@acronym{GNU} Autoconf, Automake and
887 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
888 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
889 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
890 build environment. You can also find
891 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
895 @c ================================================= Making configure Scripts.
897 @node Making configure Scripts
898 @chapter Making @command{configure} Scripts
899 @cindex @file{aclocal.m4}
900 @cindex @command{configure}
902 The configuration scripts that Autoconf produces are by convention
903 called @command{configure}. When run, @command{configure} creates several
904 files, replacing configuration parameters in them with appropriate
905 values. The files that @command{configure} creates are:
909 one or more @file{Makefile} files, usually one in each subdirectory of the
910 package (@pxref{Makefile Substitutions});
913 optionally, a C header file, the name of which is configurable,
914 containing @code{#define} directives (@pxref{Configuration Headers});
917 a shell script called @file{config.status} that, when run, recreates
918 the files listed above (@pxref{config.status Invocation});
921 an optional shell script normally called @file{config.cache}
922 (created when using @samp{configure --config-cache}) that
923 saves the results of running many of the tests (@pxref{Cache Files});
926 a file called @file{config.log} containing any messages produced by
927 compilers, to help debugging if @command{configure} makes a mistake.
930 @cindex @file{configure.in}
931 @cindex @file{configure.ac}
932 To create a @command{configure} script with Autoconf, you need to write an
933 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
934 @command{autoconf} on it. If you write your own feature tests to
935 supplement those that come with Autoconf, you might also write files
936 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
937 file to contain @code{#define} directives, you might also run
938 @command{autoheader}, and you can distribute the generated file
939 @file{config.h.in} with the package.
941 Here is a diagram showing how the files that can be used in
942 configuration are produced. Programs that are executed are suffixed by
943 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
944 @command{autoconf} and @command{autoheader} also read the installed Autoconf
945 macro files (by reading @file{autoconf.m4}).
948 Files used in preparing a software package for distribution:
950 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
954 | .------> autoconf* -----> configure
956 | `-----> [autoheader*] --> [config.h.in]
960 Makefile.in -------------------------------> Makefile.in
964 Files used in configuring a software package:
967 .-------------> [config.cache]
968 configure* ------------+-------------> config.log
970 [config.h.in] -. v .-> [config.h] -.
971 +--> config.status* -+ +--> make*
972 Makefile.in ---' `-> Makefile ---'
977 * Writing Autoconf Input:: What to put in an Autoconf input file
978 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
979 * ifnames Invocation:: Listing the conditionals in source code
980 * autoconf Invocation:: How to create configuration scripts
981 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
984 @node Writing Autoconf Input
985 @section Writing @file{configure.ac}
987 To produce a @command{configure} script for a software package, create a
988 file called @file{configure.ac} that contains invocations of the
989 Autoconf macros that test the system features your package needs or can
990 use. Autoconf macros already exist to check for many features; see
991 @ref{Existing Tests}, for their descriptions. For most other features,
992 you can use Autoconf template macros to produce custom checks; see
993 @ref{Writing Tests}, for information about them. For especially tricky
994 or specialized features, @file{configure.ac} might need to contain some
995 hand-crafted shell commands; see @ref{Portable Shell}. The
996 @command{autoscan} program can give you a good start in writing
997 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
999 Previous versions of Autoconf promoted the name @file{configure.in},
1000 which is somewhat ambiguous (the tool needed to process this file is not
1001 described by its extension), and introduces a slight confusion with
1002 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1003 processed by @command{configure}''). Using @file{configure.ac} is now
1007 * Shell Script Compiler:: Autoconf as solution of a problem
1008 * Autoconf Language:: Programming in Autoconf
1009 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
1012 @node Shell Script Compiler
1013 @subsection A Shell Script Compiler
1015 Just as for any other computer language, in order to properly program
1016 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1017 the language tries to address and @emph{how} it does so.
1019 The problem Autoconf addresses is that the world is a mess. After all,
1020 you are using Autoconf in order to have your package compile easily on
1021 all sorts of different systems, some of them being extremely hostile.
1022 Autoconf itself bears the price for these differences: @command{configure}
1023 must run on all those systems, and thus @command{configure} must limit itself
1024 to their lowest common denominator of features.
1026 Naturally, you might then think of shell scripts; who needs
1027 @command{autoconf}? A set of properly written shell functions is enough to
1028 make it easy to write @command{configure} scripts by hand. Sigh!
1029 Unfortunately, shell functions do not belong to the least common
1030 denominator; therefore, where you would like to define a function and
1031 use it ten times, you would instead need to copy its body ten times.
1033 So, what is really needed is some kind of compiler, @command{autoconf},
1034 that takes an Autoconf program, @file{configure.ac}, and transforms it
1035 into a portable shell script, @command{configure}.
1037 How does @command{autoconf} perform this task?
1039 There are two obvious possibilities: creating a brand new language or
1040 extending an existing one. The former option is attractive: all
1041 sorts of optimizations could easily be implemented in the compiler and
1042 many rigorous checks could be performed on the Autoconf program
1043 (e.g., rejecting any non-portable construct). Alternatively, you can
1044 extend an existing language, such as the @code{sh} (Bourne shell)
1047 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1048 therefore most convenient to implement @command{autoconf} as a macro
1049 expander: a program that repeatedly performs @dfn{macro expansions} on
1050 text input, replacing macro calls with macro bodies and producing a pure
1051 @code{sh} script in the end. Instead of implementing a dedicated
1052 Autoconf macro expander, it is natural to use an existing
1053 general-purpose macro language, such as M4, and implement the extensions
1054 as a set of M4 macros.
1057 @node Autoconf Language
1058 @subsection The Autoconf Language
1061 The Autoconf language differs from many other computer
1062 languages because it treats actual code the same as plain text. Whereas
1063 in C, for instance, data and instructions have different syntactic
1064 status, in Autoconf their status is rigorously the same. Therefore, we
1065 need a means to distinguish literal strings from text to be expanded:
1068 When calling macros that take arguments, there must not be any white
1069 space between the macro name and the open parenthesis. Arguments should
1070 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1071 separated by commas. Any leading blanks or newlines in arguments are ignored,
1072 unless they are quoted. You should always quote an argument that
1073 might contain a macro name, comma, parenthesis, or a leading blank or
1074 newline. This rule applies recursively for every macro
1075 call, including macros called from other macros.
1080 AC_CHECK_HEADER([stdio.h],
1081 [AC_DEFINE([HAVE_STDIO_H], [1],
1082 [Define to 1 if you have <stdio.h>.])],
1083 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1087 is quoted properly. You may safely simplify its quotation to:
1090 AC_CHECK_HEADER([stdio.h],
1091 [AC_DEFINE([HAVE_STDIO_H], 1,
1092 [Define to 1 if you have <stdio.h>.])],
1093 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1097 because @samp{1} cannot contain a macro call. Here, the argument of
1098 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1099 interpreted as an argument separator. Also, the second and third arguments
1100 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1101 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1102 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1103 if you unwisely defined a macro with a name like @samp{Define} or
1104 @samp{stdio} then they would need quoting. Cautious Autoconf users
1105 would keep the quotes, but many Autoconf users find such precautions
1106 annoying, and would rewrite the example as follows:
1109 AC_CHECK_HEADER(stdio.h,
1110 [AC_DEFINE(HAVE_STDIO_H, 1,
1111 [Define to 1 if you have <stdio.h>.])],
1112 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1116 This is safe, so long as you adopt good naming conventions and do not
1117 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1118 @samp{h}. Though it is also safe here to omit the quotes around
1119 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1120 message strings are more likely to inadvertently contain commas.
1122 The following example is wrong and dangerous, as it is underquoted:
1125 AC_CHECK_HEADER(stdio.h,
1126 AC_DEFINE(HAVE_STDIO_H, 1,
1127 Define to 1 if you have <stdio.h>.),
1128 AC_MSG_ERROR([Sorry, can't do anything for you]))
1131 In other cases, you may have to use text that also resembles a macro
1132 call. You must quote that text even when it is not passed as a macro
1136 echo "Hard rock was here! --[AC_DC]"
1143 echo "Hard rock was here! --AC_DC"
1147 When you use the same text in a macro argument, you must therefore have
1148 an extra quotation level (since one is stripped away by the macro
1149 substitution). In general, then, it is a good idea to @emph{use double
1150 quoting for all literal string arguments}:
1153 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1156 You are now able to understand one of the constructs of Autoconf that
1157 has been continually misunderstood@dots{} The rule of thumb is that
1158 @emph{whenever you expect macro expansion, expect quote expansion};
1159 i.e., expect one level of quotes to be lost. For instance:
1162 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1166 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1167 @samp{char b[10];} and is expanded once, which results in
1168 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1169 address this issue via the M4 @code{changequote} primitive, but do not
1170 use it!) Let's take a closer look: the author meant the first argument
1171 to be understood as a literal, and therefore it must be quoted twice:
1174 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1178 Voil@`a, you actually produce @samp{char b[10];} this time!
1180 On the other hand, descriptions (e.g., the last parameter of
1181 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1182 are subject to line breaking, for example---and should not be double quoted.
1183 Even if these descriptions are short and are not actually broken, double
1184 quoting them yields weird results.
1186 Some macros take optional arguments, which this documentation represents
1187 as @ovar{arg} (not to be confused with the quote characters). You may
1188 just leave them empty, or use @samp{[]} to make the emptiness of the
1189 argument explicit, or you may simply omit the trailing commas. The
1190 three lines below are equivalent:
1193 AC_CHECK_HEADERS([stdio.h], [], [], [])
1194 AC_CHECK_HEADERS([stdio.h],,,)
1195 AC_CHECK_HEADERS([stdio.h])
1198 It is best to put each macro call on its own line in
1199 @file{configure.ac}. Most of the macros don't add extra newlines; they
1200 rely on the newline after the macro call to terminate the commands.
1201 This approach makes the generated @command{configure} script a little
1202 easier to read by not inserting lots of blank lines. It is generally
1203 safe to set shell variables on the same line as a macro call, because
1204 the shell allows assignments without intervening newlines.
1206 You can include comments in @file{configure.ac} files by starting them
1207 with the @samp{#}. For example, it is helpful to begin
1208 @file{configure.ac} files with a line like this:
1211 # Process this file with autoconf to produce a configure script.
1214 @node Autoconf Input Layout
1215 @subsection Standard @file{configure.ac} Layout
1217 The order in which @file{configure.ac} calls the Autoconf macros is not
1218 important, with a few exceptions. Every @file{configure.ac} must
1219 contain a call to @code{AC_INIT} before the checks, and a call to
1220 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1221 rely on other macros having been called first, because they check
1222 previously set values of some variables to decide what to do. These
1223 macros are noted in the individual descriptions (@pxref{Existing
1224 Tests}), and they also warn you when @command{configure} is created if they
1225 are called out of order.
1227 To encourage consistency, here is a suggested order for calling the
1228 Autoconf macros. Generally speaking, the things near the end of this
1229 list are those that could depend on things earlier in it. For example,
1230 library functions could be affected by types and libraries.
1234 Autoconf requirements
1235 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1236 information on the package
1238 checks for libraries
1239 checks for header files
1241 checks for structures
1242 checks for compiler characteristics
1243 checks for library functions
1244 checks for system services
1245 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1251 @node autoscan Invocation
1252 @section Using @command{autoscan} to Create @file{configure.ac}
1253 @cindex @command{autoscan}
1255 The @command{autoscan} program can help you create and/or maintain a
1256 @file{configure.ac} file for a software package. @command{autoscan}
1257 examines source files in the directory tree rooted at a directory given
1258 as a command line argument, or the current directory if none is given.
1259 It searches the source files for common portability problems and creates
1260 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1261 for that package, and checks a possibly existing @file{configure.ac} for
1264 When using @command{autoscan} to create a @file{configure.ac}, you
1265 should manually examine @file{configure.scan} before renaming it to
1266 @file{configure.ac}; it probably needs some adjustments.
1267 Occasionally, @command{autoscan} outputs a macro in the wrong order
1268 relative to another macro, so that @command{autoconf} produces a warning;
1269 you need to move such macros manually. Also, if you want the package to
1270 use a configuration header file, you must add a call to
1271 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1272 also have to change or add some @code{#if} directives to your program in
1273 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1274 information about a program that can help with that job).
1276 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1277 consider adding its suggestions. The file @file{autoscan.log}
1278 contains detailed information on why a macro is requested.
1280 @command{autoscan} uses several data files (installed along with Autoconf)
1281 to determine which macros to output when it finds particular symbols in
1282 a package's source files. These data files all have the same format:
1283 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1284 output if that symbol is encountered. Lines starting with @samp{#} are
1287 @command{autoscan} accepts the following options:
1292 Print a summary of the command line options and exit.
1296 Print the version number of Autoconf and exit.
1300 Print the names of the files it examines and the potentially interesting
1301 symbols it finds in them. This output can be voluminous.
1303 @item --include=@var{dir}
1305 Append @var{dir} to the include path. Multiple invocations accumulate.
1307 @item --prepend-include=@var{dir}
1309 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1312 @node ifnames Invocation
1313 @section Using @command{ifnames} to List Conditionals
1314 @cindex @command{ifnames}
1316 @command{ifnames} can help you write @file{configure.ac} for a software
1317 package. It prints the identifiers that the package already uses in C
1318 preprocessor conditionals. If a package has already been set up to have
1319 some portability, @command{ifnames} can thus help you figure out what its
1320 @command{configure} needs to check for. It may help fill in some gaps in a
1321 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1324 @command{ifnames} scans all of the C source files named on the command line
1325 (or the standard input, if none are given) and writes to the standard
1326 output a sorted list of all the identifiers that appear in those files
1327 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1328 directives. It prints each identifier on a line, followed by a
1329 space-separated list of the files in which that identifier occurs.
1332 @command{ifnames} accepts the following options:
1337 Print a summary of the command line options and exit.
1341 Print the version number of Autoconf and exit.
1344 @node autoconf Invocation
1345 @section Using @command{autoconf} to Create @command{configure}
1346 @cindex @command{autoconf}
1348 To create @command{configure} from @file{configure.ac}, run the
1349 @command{autoconf} program with no arguments. @command{autoconf} processes
1350 @file{configure.ac} with the M4 macro processor, using the
1351 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1352 file instead of @file{configure.ac} and writes the configuration script
1353 to the standard output instead of to @command{configure}. If you give
1354 @command{autoconf} the argument @option{-}, it reads from the standard
1355 input instead of @file{configure.ac} and writes the configuration script
1356 to the standard output.
1358 The Autoconf macros are defined in several files. Some of the files are
1359 distributed with Autoconf; @command{autoconf} reads them first. Then it
1360 looks for the optional file @file{acsite.m4} in the directory that
1361 contains the distributed Autoconf macro files, and for the optional file
1362 @file{aclocal.m4} in the current directory. Those files can contain
1363 your site's or the package's own Autoconf macro definitions
1364 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1365 defined in more than one of the files that @command{autoconf} reads, the
1366 last definition it reads overrides the earlier ones.
1368 @command{autoconf} accepts the following options:
1373 Print a summary of the command line options and exit.
1377 Print the version number of Autoconf and exit.
1381 Report processing steps.
1385 Don't remove the temporary files.
1389 Remake @file{configure} even if newer than its input files.
1391 @item --include=@var{dir}
1393 Append @var{dir} to the include path. Multiple invocations accumulate.
1395 @item --prepend-include=@var{dir}
1397 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1399 @item --output=@var{file}
1400 @itemx -o @var{file}
1401 Save output (script or trace) to @var{file}. The file @option{-} stands
1402 for the standard output.
1404 @item --warnings=@var{category}
1405 @itemx -W @var{category}
1407 Report the warnings related to @var{category} (which can actually be a
1408 comma separated list). @xref{Reporting Messages}, macro
1409 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1414 report all the warnings
1420 treats warnings as errors
1422 @item no-@var{category}
1423 disable warnings falling into @var{category}
1426 Warnings about @samp{syntax} are enabled by default, and the environment
1427 variable @env{WARNINGS}, a comma separated list of categories, is
1428 honored as well. Passing @option{-W @var{category}} actually behaves as if
1429 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. If
1430 you want to disable the defaults and @env{WARNINGS}, but (for example)
1431 enable the warnings about obsolete constructs, you would use @option{-W
1435 @cindex Macro invocation stack
1436 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1437 displays a back trace for errors, but not for warnings; if you want
1438 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1441 @item --trace=@var{macro}[:@var{format}]
1442 @itemx -t @var{macro}[:@var{format}]
1443 Do not create the @command{configure} script, but list the calls to
1444 @var{macro} according to the @var{format}. Multiple @option{--trace}
1445 arguments can be used to list several macros. Multiple @option{--trace}
1446 arguments for a single macro are not cumulative; instead, you should
1447 just make @var{format} as long as needed.
1449 The @var{format} is a regular string, with newlines if desired, and
1450 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1451 @ref{autom4te Invocation}, for details on the @var{format}.
1453 @item --initialization
1455 By default, @option{--trace} does not trace the initialization of the
1456 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1457 results in a noticeable speedup, but can be disabled by this option.
1461 It is often necessary to check the content of a @file{configure.ac}
1462 file, but parsing it yourself is extremely fragile and error-prone. It
1463 is suggested that you rely upon @option{--trace} to scan
1464 @file{configure.ac}. For instance, to find the list of variables that
1465 are substituted, use:
1469 $ @kbd{autoconf -t AC_SUBST}
1470 configure.ac:2:AC_SUBST:ECHO_C
1471 configure.ac:2:AC_SUBST:ECHO_N
1472 configure.ac:2:AC_SUBST:ECHO_T
1473 @i{More traces deleted}
1478 The example below highlights the difference between @samp{$@@},
1479 @samp{$*}, and @samp{$%}.
1483 $ @kbd{cat configure.ac}
1484 AC_DEFINE(This, is, [an
1486 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1493 %: This:is:an [example]
1498 The @var{format} gives you a lot of freedom:
1502 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1503 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1504 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1505 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1506 @i{More traces deleted}
1511 A long @var{separator} can be used to improve the readability of complex
1512 structures, and to ease their parsing (for instance when no single
1513 character is suitable as a separator):
1517 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1518 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1519 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1520 AUTOMAKE|:::::|automake|:::::|$missing_dir
1521 @i{More traces deleted}
1525 @node autoreconf Invocation
1526 @section Using @command{autoreconf} to Update @command{configure} Scripts
1527 @cindex @command{autoreconf}
1529 Installing the various components of the @acronym{GNU} Build System can be
1530 tedious: running @command{autopoint} for Gettext, @command{automake} for
1531 @file{Makefile.in} etc.@: in each directory. It may be needed either
1532 because some tools such as @command{automake} have been updated on your
1533 system, or because some of the sources such as @file{configure.ac} have
1534 been updated, or finally, simply in order to install the @acronym{GNU} Build
1535 System in a fresh tree.
1537 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1538 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1539 @command{autopoint} (when appropriate) repeatedly to update the
1540 @acronym{GNU} Build System in the specified directories and their
1541 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1542 those files that are older than their sources.
1544 If you install a new version of some tool, you can make
1545 @command{autoreconf} remake @emph{all} of the files by giving it the
1546 @option{--force} option.
1548 @xref{Automatic Remaking}, for Make rules to automatically
1549 remake @command{configure} scripts when their source files change. That
1550 method handles the timestamps of configuration header templates
1551 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1552 @option{--localdir=@var{dir}}.
1555 @cindex @command{autopoint}
1556 Gettext supplies the @command{autopoint} command to add translation
1557 infrastructure to a source package. If you use @command{autopoint},
1558 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1559 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1560 Invocation, , Invoking the @code{autopoint} Program, gettext,
1561 @acronym{GNU} @code{gettext} utilities}, for further details.
1564 @command{autoreconf} accepts the following options:
1569 Print a summary of the command line options and exit.
1573 Print the version number of Autoconf and exit.
1576 Print the name of each directory @command{autoreconf} examines and the
1577 commands it runs. If given two or more times, pass @option{--verbose}
1578 to subordinate tools that support it.
1582 Don't remove the temporary files.
1586 Remake even @file{configure} scripts and configuration headers that are
1587 newer than their input files (@file{configure.ac} and, if present,
1592 Install the missing auxiliary files in the package. By default, files
1593 are copied; this can be changed with @option{--symlink}.
1595 If deemed appropriate, this option triggers calls to
1596 @samp{automake --add-missing},
1597 @samp{libtoolize}, @samp{autopoint}, etc.
1599 @item --no-recursive
1600 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1601 macro @code{AC_CONFIG_SUBDIRS}).
1605 When used with @option{--install}, install symbolic links to the missing
1606 auxiliary files instead of copying them.
1610 When the directories were configured, update the configuration by
1611 running @samp{./config.status --recheck && ./config.status}, and then
1614 @item --include=@var{dir}
1616 Append @var{dir} to the include path. Multiple invocations accumulate.
1617 Passed on to @command{autoconf} and @command{autoheader} internally.
1619 @item --prepend-include=@var{dir}
1621 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1622 Passed on to @command{autoconf} and @command{autoheader} internally.
1624 @item --warnings=@var{category}
1625 @itemx -W @var{category}
1627 Report the warnings related to @var{category} (which can actually be a
1628 comma separated list).
1632 related to cross compilation issues.
1635 report the uses of obsolete constructs.
1641 dubious syntactic constructs.
1644 report all the warnings
1650 treats warnings as errors
1652 @item no-@var{category}
1653 disable warnings falling into @var{category}
1656 Warnings about @samp{syntax} are enabled by default, and the environment
1657 variable @env{WARNINGS}, a comma separated list of categories, is
1658 honored as well. Passing @option{-W @var{category}} actually behaves as if
1659 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. If
1660 you want to disable the defaults and @env{WARNINGS}, but (for example)
1661 enable the warnings about obsolete constructs, you would use @option{-W
1665 If you want @command{autoreconf} to pass flags that are not listed here
1666 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1667 Due to a limitation in the Autoconf implementation these flags currently
1668 must be set on a single line in @file{Makefile.am}, without any
1671 @c ========================================= Initialization and Output Files.
1674 @chapter Initialization and Output Files
1676 Autoconf-generated @command{configure} scripts need some information about
1677 how to initialize, such as how to find the package's source files and
1678 about the output files to produce. The following sections describe the
1679 initialization and the creation of output files.
1682 * Initializing configure:: Option processing etc.
1683 * Versioning:: Dealing with Autoconf versions
1684 * Notices:: Copyright, version numbers in @command{configure}
1685 * Input:: Where Autoconf should find files
1686 * Output:: Outputting results from the configuration
1687 * Configuration Actions:: Preparing the output based on results
1688 * Configuration Files:: Creating output files
1689 * Makefile Substitutions:: Using output variables in makefiles
1690 * Configuration Headers:: Creating a configuration header file
1691 * Configuration Commands:: Running arbitrary instantiation commands
1692 * Configuration Links:: Links depending on the configuration
1693 * Subdirectories:: Configuring independent packages together
1694 * Default Prefix:: Changing the default installation prefix
1697 @node Initializing configure
1698 @section Initializing @command{configure}
1700 Every @command{configure} script must call @code{AC_INIT} before doing
1701 anything else. The only other required macro is @code{AC_OUTPUT}
1705 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
1708 Process any command-line arguments and perform various initializations
1711 Set the name of the @var{package} and its @var{version}. These are
1712 typically used in @option{--version} support, including that of
1713 @command{configure}. The optional argument @var{bug-report} should be
1714 the email to which users should send bug reports. The package
1715 @var{tarname} differs from @var{package}: the latter designates the full
1716 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1717 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1718 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1719 other than alphanumerics and underscores are changed to @samp{-}.
1721 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1722 there should not be any shell computation, but they can be computed by
1725 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1726 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1727 @code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
1730 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1731 @acindex{PACKAGE_NAME}
1732 @ovindex PACKAGE_NAME
1733 @cvindex PACKAGE_NAME
1734 Exactly @var{package}.
1736 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1737 @acindex{PACKAGE_TARNAME}
1738 @ovindex PACKAGE_TARNAME
1739 @cvindex PACKAGE_TARNAME
1740 Exactly @var{tarname}.
1742 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1743 @acindex{PACKAGE_VERSION}
1744 @ovindex PACKAGE_VERSION
1745 @cvindex PACKAGE_VERSION
1746 Exactly @var{version}.
1748 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1749 @acindex{PACKAGE_STRING}
1750 @ovindex PACKAGE_STRING
1751 @cvindex PACKAGE_STRING
1752 Exactly @samp{@var{package} @var{version}}.
1754 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1755 @acindex{PACKAGE_BUGREPORT}
1756 @ovindex PACKAGE_BUGREPORT
1757 @cvindex PACKAGE_BUGREPORT
1758 Exactly @var{bug-report}.
1762 If your @command{configure} script does its own option processing, it
1763 should inspect @samp{$@@} or @samp{$*} immediately after calling
1764 @code{AC_INIT}, because other Autoconf macros liberally use the
1765 @command{set} command to process strings, and this has the side effect
1766 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1767 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1768 implement your own option processing. @xref{Site Configuration}.
1771 @section Dealing with Autoconf versions
1772 @cindex Autoconf version
1773 @cindex version, Autoconf
1775 The following optional macros can be used to help choose the minimum
1776 version of Autoconf that can successfully compile a given
1777 @file{configure.ac}.
1779 @defmac AC_PREREQ (@var{version})
1782 Ensure that a recent enough version of Autoconf is being used. If the
1783 version of Autoconf being used to create @command{configure} is
1784 earlier than @var{version}, print an error message to the standard
1785 error output and exit with failure (exit status is 63). For example:
1788 AC_PREREQ([@value{VERSION}])
1791 This macro is the only macro that may be used before @code{AC_INIT}, but
1792 for consistency, you are invited not to do so.
1795 @defmac AC_AUTOCONF_VERSION
1796 @acindex{AUTOCONF_VERSION}
1797 This macro was introduced in Autoconf 2.62. It identifies the version
1798 of Autoconf that is currently parsing the input file, in a format
1799 suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
1800 other words, for this release of Autoconf, its value is
1801 @samp{@value{VERSION}}. One potential use of this macro is for writing
1802 conditional fallbacks based on when a feature was added to Autoconf,
1803 rather than using @code{AC_PREREQ} to require the newer version of
1804 Autoconf. However, remember that the Autoconf philosophy favors feature
1805 checks over version checks.
1809 @section Notices in @command{configure}
1810 @cindex Notices in @command{configure}
1812 The following macros manage version numbers for @command{configure}
1813 scripts. Using them is optional.
1815 @defmac AC_COPYRIGHT (@var{copyright-notice})
1817 @cindex Copyright Notice
1818 State that, in addition to the Free Software Foundation's copyright on
1819 the Autoconf macros, parts of your @command{configure} are covered by the
1820 @var{copyright-notice}.
1822 The @var{copyright-notice} shows up in both the head of
1823 @command{configure} and in @samp{configure --version}.
1827 @defmac AC_REVISION (@var{revision-info})
1830 Copy revision stamp @var{revision-info} into the @command{configure}
1831 script, with any dollar signs or double-quotes removed. This macro lets
1832 you put a revision stamp from @file{configure.ac} into @command{configure}
1833 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1834 @command{configure}. That way, you can determine easily which revision of
1835 @file{configure.ac} a particular @command{configure} corresponds to.
1837 For example, this line in @file{configure.ac}:
1839 @c The asis prevents RCS from changing the example in the manual.
1841 AC_REVISION([$@asis{Revision: 1.30 }$])
1845 produces this in @command{configure}:
1849 # From configure.ac Revision: 1.30
1855 @section Finding @command{configure} Input
1857 @anchor{AC_CONFIG_SRCDIR}
1858 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1859 @acindex{CONFIG_SRCDIR}
1860 @var{unique-file-in-source-dir} is some file that is in the package's
1861 source directory; @command{configure} checks for this file's existence to
1862 make sure that the directory that it is told contains the source code in
1863 fact does. Occasionally people accidentally specify the wrong directory
1864 with @option{--srcdir}; this is a safety check. @xref{configure
1865 Invocation}, for more information.
1869 @c FIXME: Remove definitively once --install explained.
1871 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1872 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1873 @c to split the macros in several files. In this case, Autoconf must be
1874 @c told which files to load, and in which order.
1876 @c @defmac AC_INCLUDE (@var{file}@dots{})
1877 @c @acindex{INCLUDE}
1878 @c @c FIXME: There is no longer shell globbing.
1879 @c Read the macro definitions that appear in the listed files. A list of
1880 @c space-separated file names or shell globbing patterns is expected. The
1881 @c files are read in the order they're listed.
1883 @c Because the order of definition of macros is important (only the last
1884 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1885 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1886 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1887 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1888 @c the latter case, non-macro lines from included files may end up in the
1889 @c @file{configure} script, whereas in the former case, they'd be discarded
1890 @c just like any text that appear before @code{AC_INIT}.
1893 Packages that do manual configuration or use the @command{install} program
1894 might need to tell @command{configure} where to find some other shell
1895 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1896 it looks are correct for most cases.
1898 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1899 @acindex{CONFIG_AUX_DIR}
1900 Use the auxiliary build tools (e.g., @file{install-sh},
1901 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1902 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1903 These are auxiliary files used in configuration. @var{dir} can be
1904 either absolute or relative to @file{@var{srcdir}}. The default is
1905 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1906 @file{@var{srcdir}/../..}, whichever is the first that contains
1907 @file{install-sh}. The other files are not checked for, so that using
1908 @code{AC_PROG_INSTALL} does not automatically require distributing the
1909 other auxiliary files. It checks for @file{install.sh} also, but that
1910 name is obsolete because some @code{make} have a rule that creates
1911 @file{install} from it if there is no makefile.
1913 The auxiliary directory is commonly named @file{build-aux}.
1914 If you need portability to @acronym{DOS} variants, do not name the
1915 auxiliary directory @file{aux}. @xref{File System Conventions}.
1918 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1919 @acindex{REQUIRE_AUX_FILE}
1920 Declares that @var{file} is expected in the directory defined above. In
1921 Autoconf proper, this macro does nothing: its sole purpose is to be
1922 traced by third-party tools to produce a list of expected auxiliary
1923 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1924 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1925 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1928 Similarly, packages that use @command{aclocal} should declare where
1929 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1931 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1932 @acindex{CONFIG_MACRO_DIR}
1933 Specify @var{dir} as the location of additional local Autoconf macros.
1934 This macro is intended for use by future versions of commands like
1935 @command{autoreconf} that trace macro calls. It should be called
1936 directly from @file{configure.ac} so that tools that install macros for
1937 @command{aclocal} can find the macros' declarations.
1942 @section Outputting Files
1943 @cindex Outputting files
1945 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1946 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1947 @file{config.status}, which in turn creates the makefiles and any
1948 other files resulting from configuration. This is the only required
1949 macro besides @code{AC_INIT} (@pxref{Input}).
1954 @cindex Instantiation
1955 Generate @file{config.status} and launch it. Call this macro once, at
1956 the end of @file{configure.ac}.
1958 @file{config.status} performs all the configuration actions: all the
1959 output files (see @ref{Configuration Files}, macro
1960 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1961 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1962 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1963 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1964 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1967 The location of your @code{AC_OUTPUT} invocation is the exact point
1968 where configuration actions are taken: any code afterwards is
1969 executed by @code{configure} once @command{config.status} was run. If
1970 you want to bind actions to @command{config.status} itself
1971 (independently of whether @command{configure} is being run), see
1972 @ref{Configuration Commands, , Running Arbitrary Configuration
1976 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1977 @xref{Obsolete Macros}, for a description of the arguments that
1978 @code{AC_OUTPUT} used to support.
1981 If you run @command{make} in subdirectories, you should run it using the
1982 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1983 @code{MAKE} to the name of the @command{make} program plus any options it
1984 was given. (But many do not include in it the values of any variables
1985 set on the command line, so those are not passed on automatically.)
1986 Some old versions of @command{make} do not set this variable. The
1987 following macro allows you to use it even with those versions.
1989 @anchor{AC_PROG_MAKE_SET}
1990 @defmac AC_PROG_MAKE_SET
1991 @acindex{PROG_MAKE_SET}
1993 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1994 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1995 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1996 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
2000 If you use this macro, place a line like this in each @file{Makefile.in}
2001 that runs @code{MAKE} on other directories:
2009 @node Configuration Actions
2010 @section Performing Configuration Actions
2011 @cindex Configuration actions
2013 @file{configure} is designed so that it appears to do everything itself,
2014 but there is actually a hidden slave: @file{config.status}.
2015 @file{configure} is in charge of examining your system, but it is
2016 @file{config.status} that actually takes the proper actions based on the
2017 results of @file{configure}. The most typical task of
2018 @file{config.status} is to @emph{instantiate} files.
2020 This section describes the common behavior of the four standard
2021 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
2022 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
2023 have this prototype:
2025 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
2028 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2032 where the arguments are:
2036 A blank-or-newline-separated list of tags, which are typically the names of
2037 the files to instantiate.
2039 You are encouraged to use literals as @var{tags}. In particular, you
2043 @dots{} && my_foos="$my_foos fooo"
2044 @dots{} && my_foos="$my_foos foooo"
2045 AC_CONFIG_FOOS([$my_foos])
2049 and use this instead:
2052 @dots{} && AC_CONFIG_FOOS([fooo])
2053 @dots{} && AC_CONFIG_FOOS([foooo])
2056 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2057 special @var{tag} values: they may have the form @samp{@var{output}} or
2058 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2059 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2061 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2062 for example, asks for
2063 the creation of the file @file{Makefile} that contains the expansion of the
2064 output variables in the concatenation of @file{boiler/top.mk} and
2065 @file{boiler/bot.mk}.
2067 The special value @samp{-} might be used to denote the standard output
2068 when used in @var{output}, or the standard input when used in the
2069 @var{inputs}. You most probably don't need to use this in
2070 @file{configure.ac}, but it is convenient when using the command line
2071 interface of @file{./config.status}, see @ref{config.status Invocation},
2074 The @var{inputs} may be absolute or relative file names. In the latter
2075 case they are first looked for in the build tree, and then in the source
2079 Shell commands output literally into @file{config.status}, and
2080 associated with a tag that the user can use to tell @file{config.status}
2081 which the commands to run. The commands are run each time a @var{tag}
2082 request is given to @file{config.status}, typically each time the file
2083 @file{@var{tag}} is created.
2085 The variables set during the execution of @command{configure} are
2086 @emph{not} available here: you first need to set them via the
2087 @var{init-cmds}. Nonetheless the following variables are precomputed:
2091 The name of the top source directory, assuming that the working
2092 directory is the top build directory. This
2093 is what the @command{configure} option @option{--srcdir} sets.
2096 The name of the top source directory, assuming that the working
2097 directory is the current build directory.
2100 @item ac_top_build_prefix
2101 The name of the top build directory, assuming that the working
2102 directory is the current build directory.
2103 It can be empty, or else ends with a slash, so that you may concatenate
2107 The name of the corresponding source directory, assuming that the
2108 working directory is the current build directory.
2112 The @dfn{current} directory refers to the directory (or
2113 pseudo-directory) containing the input part of @var{tags}. For
2117 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2121 with @option{--srcdir=../package} produces the following values:
2124 # Argument of --srcdir
2126 # Reversing deep/dir
2127 ac_top_build_prefix='../../'
2128 # Concatenation of $ac_top_build_prefix and srcdir
2129 ac_top_srcdir='../../../package'
2130 # Concatenation of $ac_top_srcdir and deep/dir
2131 ac_srcdir='../../../package/deep/dir'
2135 independently of @samp{in/in.in}.
2138 Shell commands output @emph{unquoted} near the beginning of
2139 @file{config.status}, and executed each time @file{config.status} runs
2140 (regardless of the tag). Because they are unquoted, for example,
2141 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2142 is typically used by @file{configure} to give @file{config.status} some
2143 variables it needs to run the @var{commands}.
2145 You should be extremely cautious in your variable names: all the
2146 @var{init-cmds} share the same name space and may overwrite each other
2147 in unpredictable ways. Sorry@enddots{}
2150 All these macros can be called multiple times, with different
2151 @var{tag} values, of course!
2154 @node Configuration Files
2155 @section Creating Configuration Files
2156 @cindex Creating configuration files
2157 @cindex Configuration file creation
2159 Be sure to read the previous section, @ref{Configuration Actions}.
2161 @anchor{AC_CONFIG_FILES}
2162 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2163 @acindex{CONFIG_FILES}
2164 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2165 file (by default @file{@var{file}.in}), substituting the output variable
2167 @c Before we used to have this feature, which was later rejected
2168 @c because it complicates the writing of makefiles:
2169 @c If the file would be unchanged, it is left untouched, to preserve
2171 This macro is one of the instantiating macros; see @ref{Configuration
2172 Actions}. @xref{Makefile Substitutions}, for more information on using
2173 output variables. @xref{Setting Output Variables}, for more information
2174 on creating them. This macro creates the directory that the file is in
2175 if it doesn't exist. Usually, makefiles are created this way,
2176 but other files, such as @file{.gdbinit}, can be specified as well.
2178 Typical calls to @code{AC_CONFIG_FILES} look like this:
2181 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2182 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2185 You can override an input file name by appending to @var{file} a
2186 colon-separated list of input files. Examples:
2189 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2190 [lib/Makefile:boiler/lib.mk])
2194 Doing this allows you to keep your file names acceptable to
2195 @acronym{DOS} variants, or
2196 to prepend and/or append boilerplate to the file.
2201 @node Makefile Substitutions
2202 @section Substitutions in Makefiles
2203 @cindex Substitutions in makefiles
2204 @cindex Makefile substitutions
2206 Each subdirectory in a distribution that contains something to be
2207 compiled or installed should come with a file @file{Makefile.in}, from
2208 which @command{configure} creates a file @file{Makefile} in that directory.
2209 To create @file{Makefile}, @command{configure} performs a simple variable
2210 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2211 @file{Makefile.in} with the value that @command{configure} has determined
2212 for that variable. Variables that are substituted into output files in
2213 this way are called @dfn{output variables}. They are ordinary shell
2214 variables that are set in @command{configure}. To make @command{configure}
2215 substitute a particular variable into the output files, the macro
2216 @code{AC_SUBST} must be called with that variable name as an argument.
2217 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2218 left unchanged. @xref{Setting Output Variables}, for more information
2219 on creating output variables with @code{AC_SUBST}.
2221 A software package that uses a @command{configure} script should be
2222 distributed with a file @file{Makefile.in}, but no makefile; that
2223 way, the user has to properly configure the package for the local system
2224 before compiling it.
2226 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2227 @acronym{GNU} Coding Standards}, for more information on what to put in
2231 * Preset Output Variables:: Output variables that are always set
2232 * Installation Directory Variables:: Other preset output variables
2233 * Changed Directory Variables:: Warnings about @file{datarootdir}
2234 * Build Directories:: Supporting multiple concurrent compiles
2235 * Automatic Remaking:: Makefile rules for configuring
2238 @node Preset Output Variables
2239 @subsection Preset Output Variables
2240 @cindex Output variables
2242 Some output variables are preset by the Autoconf macros. Some of the
2243 Autoconf macros set additional output variables, which are mentioned in
2244 the descriptions for those macros. @xref{Output Variable Index}, for a
2245 complete list of output variables. @xref{Installation Directory
2246 Variables}, for the list of the preset ones related to installation
2247 directories. Below are listed the other preset ones. They all are
2248 precious variables (@pxref{Setting Output Variables},
2251 @c Just say no to ASCII sorting! We're humans, not computers.
2252 @c These variables are listed as they would be in a dictionary:
2259 Debugging and optimization options for the C compiler. If it is not set
2260 in the environment when @command{configure} runs, the default value is set
2261 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2262 uses this variable when compiling or linking programs to test for C features.
2264 If a compiler option affects only the behavior of the preprocessor
2265 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2266 instead. If it affects only the linker (e.g., @option{-L
2267 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2268 affects only the compiler proper, @code{CFLAGS} is the natural home for
2269 it. If an option affects multiple phases of the compiler, though,
2270 matters get tricky. One approach to put such options directly into
2271 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2272 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2276 @defvar configure_input
2277 @ovindex configure_input
2278 A comment saying that the file was generated automatically by
2279 @command{configure} and giving the name of the input file.
2280 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2281 of every makefile it creates. For other files, you should
2282 reference this variable in a comment at the top of each input file. For
2283 example, an input shell script should begin like this:
2287 # @@configure_input@@
2291 The presence of that line also reminds people editing the file that it
2292 needs to be processed by @command{configure} in order to be used.
2297 Preprocessor options for the C, C++, and Objective C preprocessors and
2299 it is not set in the environment when @command{configure} runs, the default
2300 value is empty. @command{configure} uses this variable when preprocessing
2301 or compiling programs to test for C, C++, and Objective C features.
2303 This variable's contents should contain options like @option{-I},
2304 @option{-D}, and @option{-U} that affect only the behavior of the
2305 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2306 can do if an option affects other phases of the compiler as well.
2308 Currently, @command{configure} always links as part of a single
2309 invocation of the compiler that also preprocesses and compiles, so it
2310 uses this variable also when linking programs. However, it is unwise to
2311 depend on this behavior because the @acronym{GNU} coding standards do
2312 not require it and many packages do not use @code{CPPFLAGS} when linking
2315 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2321 Debugging and optimization options for the C++ compiler. It acts like
2322 @code{CFLAGS}, but for C++ instead of C.
2327 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2328 is called, @command{configure} replaces @samp{@@DEFS@@} with
2329 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2330 variable is not defined while @command{configure} is performing its tests,
2331 only when creating the output files. @xref{Setting Output Variables}, for
2332 how to check the results of previous tests.
2341 How does one suppress the trailing newline from @command{echo} for
2342 question-answer message pairs? These variables provide a way:
2345 echo $ECHO_N "And the winner is... $ECHO_C"
2347 echo "$@{ECHO_T@}dead."
2351 Some old and uncommon @command{echo} implementations offer no means to
2352 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2358 Debugging and optimization options for the Erlang compiler. If it is not set
2359 in the environment when @command{configure} runs, the default value is empty.
2360 @command{configure} uses this variable when compiling
2361 programs to test for Erlang features.
2366 Debugging and optimization options for the Fortran compiler. If it
2367 is not set in the environment when @command{configure} runs, the default
2368 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2369 @command{configure} uses this variable when compiling or linking
2370 programs to test for Fortran features.
2375 Debugging and optimization options for the Fortran 77 compiler. If it
2376 is not set in the environment when @command{configure} runs, the default
2377 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2378 @command{configure} uses this variable when compiling or linking
2379 programs to test for Fortran 77 features.
2384 Options for the linker. If it is not set
2385 in the environment when @command{configure} runs, the default value is empty.
2386 @command{configure} uses this variable when linking programs to test for
2387 C, C++, Objective C, and Fortran features.
2389 This variable's contents should contain options like @option{-s} and
2390 @option{-L} that affect only the behavior of the linker. Please see the
2391 explanation of @code{CFLAGS} for what you can do if an option also
2392 affects other phases of the compiler.
2394 Don't use this variable to pass library names
2395 (@option{-l}) to the linker; use @code{LIBS} instead.
2400 @option{-l} options to pass to the linker. The default value is empty,
2401 but some Autoconf macros may prepend extra libraries to this variable if
2402 those libraries are found and provide necessary functions, see
2403 @ref{Libraries}. @command{configure} uses this variable when linking
2404 programs to test for C, C++, and Fortran features.
2409 Debugging and optimization options for the Objective C compiler. It
2410 acts like @code{CFLAGS}, but for Objective C instead of C.
2415 Rigorously equal to @samp{.}. Added for symmetry only.
2418 @defvar abs_builddir
2419 @ovindex abs_builddir
2420 Absolute name of @code{builddir}.
2423 @defvar top_builddir
2424 @ovindex top_builddir
2425 The relative name of the top level of the current build tree. In the
2426 top-level directory, this is the same as @code{builddir}.
2429 @defvar abs_top_builddir
2430 @ovindex abs_top_builddir
2431 Absolute name of @code{top_builddir}.
2436 The name of the directory that contains the source code for
2442 Absolute name of @code{srcdir}.
2447 The name of the top-level source code directory for the
2448 package. In the top-level directory, this is the same as @code{srcdir}.
2451 @defvar abs_top_srcdir
2452 @ovindex abs_top_srcdir
2453 Absolute name of @code{top_srcdir}.
2456 @node Installation Directory Variables
2457 @subsection Installation Directory Variables
2458 @cindex Installation directories
2459 @cindex Directories, installation
2461 The following variables specify the directories for
2462 package installation, see @ref{Directory Variables, , Variables for
2463 Installation Directories, standards, The @acronym{GNU} Coding
2464 Standards}, for more information. Each variable corresponds to an
2465 argument of @command{configure}; trailing slashes are stripped so that
2466 expressions such as @samp{$@{prefix@}/lib} expand with only one slash
2467 between directory names. See the end of this section for
2468 details on when and how to use these variables.
2472 The directory for installing executables that users run.
2477 The directory for installing idiosyncratic read-only
2478 architecture-independent data.
2482 @ovindex datarootdir
2483 The root of the directory tree for read-only architecture-independent
2489 The directory for installing documentation files (other than Info and
2495 The directory for installing documentation files in DVI format.
2499 @ovindex exec_prefix
2500 The installation prefix for architecture-dependent files. By default
2501 it's the same as @var{prefix}. You should avoid installing anything
2502 directly to @var{exec_prefix}. However, the default value for
2503 directories containing architecture-dependent files should be relative
2504 to @var{exec_prefix}.
2509 The directory for installing HTML documentation.
2514 The directory for installing C header files.
2519 The directory for installing documentation in Info format.
2524 The directory for installing object code libraries.
2529 The directory for installing executables that other programs run.
2534 The directory for installing locale-dependent but
2535 architecture-independent data, such as message catalogs. This directory
2536 usually has a subdirectory per locale.
2539 @defvar localstatedir
2540 @ovindex localstatedir
2541 The directory for installing modifiable single-machine data.
2546 The top-level directory for installing documentation in man format.
2549 @defvar oldincludedir
2550 @ovindex oldincludedir
2551 The directory for installing C header files for non-@acronym{GCC} compilers.
2556 The directory for installing PDF documentation.
2561 The common installation prefix for all files. If @var{exec_prefix}
2562 is defined to a different value, @var{prefix} is used only for
2563 architecture-independent files.
2568 The directory for installing PostScript documentation.
2573 The directory for installing executables that system
2577 @defvar sharedstatedir
2578 @ovindex sharedstatedir
2579 The directory for installing modifiable architecture-independent data.
2584 The directory for installing read-only single-machine data.
2588 Most of these variables have values that rely on @code{prefix} or
2589 @code{exec_prefix}. It is deliberate that the directory output
2590 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2591 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2592 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2594 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2599 she can still specify a different prefix from the one specified to
2600 @command{configure}, in which case, if needed, the package should hard
2601 code dependencies corresponding to the make-specified prefix.
2604 she can specify a different installation location, in which case the
2605 package @emph{must} still depend on the location which was compiled in
2606 (i.e., never recompile when @samp{make install} is run). This is an
2607 extremely important feature, as many people may decide to install all
2608 the files of a package grouped together, and then install links from
2609 the final locations to there.
2612 In order to support these features, it is essential that
2613 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2614 depend upon the current value of @code{prefix}.
2616 A corollary is that you should not use these variables except in
2617 makefiles. For instance, instead of trying to evaluate @code{datadir}
2618 in @file{configure} and hard-coding it in makefiles using
2619 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2621 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2622 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2624 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2625 @code{datadir} and friends in your shell scripts and other files; instead,
2626 let @command{make} manage their replacement. For instance Autoconf
2627 ships templates of its shell scripts ending with @samp{.in}, and uses a
2628 makefile snippet similar to the following to build scripts like
2629 @command{autoheader} and @command{autom4te}:
2634 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2635 -e 's|@@prefix[@@]|$(prefix)|g'
2639 autoheader autom4te: Makefile
2641 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2648 autoheader: $(srcdir)/autoheader.in
2649 autom4te: $(srcdir)/autom4te.in
2653 Some details are noteworthy:
2656 @item @samp{@@datadir[@@]}
2657 The brackets prevent @command{configure} from replacing
2658 @samp{@@datadir@@} in the Sed expression itself.
2659 Brackets are preferable to a backslash here, since
2660 Posix says @samp{\@@} is not portable.
2662 @item @samp{$(pkgdatadir)}
2663 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2667 Don't use @samp{/} in the Sed expressions that replace file names since
2669 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2670 Use a shell metacharacter instead, such as @samp{|}.
2672 @item special characters
2673 File names, file name components, and the value of @code{VPATH} should
2674 not contain shell metacharacters or white
2675 space. @xref{Special Chars in Variables}.
2677 @item dependency on @file{Makefile}
2678 Since @code{edit} uses values that depend on the configuration specific
2679 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2680 the output depends on @file{Makefile}, not @file{configure.ac}.
2683 The main rule is generic, and uses @samp{$@@} extensively to
2684 avoid the need for multiple copies of the rule.
2686 @item Separated dependencies and single suffix rules
2687 You can't use them! The above snippet cannot be (portably) rewritten
2691 autoconf autoheader: Makefile
2701 @xref{Single Suffix Rules}, for details.
2703 @item @samp{$(srcdir)}
2704 Be sure to specify the name of the source directory,
2705 otherwise the package won't support separated builds.
2708 For the more specific installation of Erlang libraries, the following variables
2711 @defvar ERLANG_INSTALL_LIB_DIR
2712 @ovindex ERLANG_INSTALL_LIB_DIR
2713 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2714 The common parent directory of Erlang library installation directories.
2715 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2716 macro in @file{configure.ac}.
2719 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2720 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2721 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2722 The installation directory for Erlang library @var{library}.
2723 This variable is set by calling the
2724 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2725 macro in @file{configure.ac}.
2728 @xref{Erlang Libraries}, for details.
2731 @node Changed Directory Variables
2732 @subsection Changed Directory Variables
2733 @cindex @file{datarootdir}
2735 In Autoconf 2.60, the set of directory variables has changed, and the
2736 defaults of some variables have been adjusted
2737 (@pxref{Installation Directory Variables}) to changes in the
2738 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2739 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2740 upgrading from an earlier Autoconf version, you may need to adjust your files
2741 to ensure that the directory variables are substituted correctly
2742 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2743 in place. For example, in a @file{Makefile.in}, adding
2746 datarootdir = @@datarootdir@@
2750 is usually sufficient. If you use Automake to create @file{Makefile.in},
2751 it will add this for you.
2753 To help with the transition, Autoconf warns about files that seem to use
2754 @code{datarootdir} without defining it. In some cases, it then expands
2755 the value of @code{$datarootdir} in substitutions of the directory
2756 variables. The following example shows such a warning:
2759 $ @kbd{cat configure.ac}
2761 AC_CONFIG_FILES([Makefile])
2763 $ @kbd{cat Makefile.in}
2765 datadir = @@datadir@@
2768 configure: creating ./config.status
2769 config.status: creating Makefile
2770 config.status: WARNING:
2771 Makefile.in seems to ignore the --datarootdir setting
2772 $ @kbd{cat Makefile}
2774 datadir = $@{prefix@}/share
2777 Usually one can easily change the file to accommodate both older and newer
2781 $ @kbd{cat Makefile.in}
2783 datarootdir = @@datarootdir@@
2784 datadir = @@datadir@@
2786 configure: creating ./config.status
2787 config.status: creating Makefile
2788 $ @kbd{cat Makefile}
2790 datarootdir = $@{prefix@}/share
2791 datadir = $@{datarootdir@}
2794 @acindex{DATAROOTDIR_CHECKED}
2795 In some cases, however, the checks may not be able to detect that a suitable
2796 initialization of @code{datarootdir} is in place, or they may fail to detect
2797 that such an initialization is necessary in the output file. If, after
2798 auditing your package, there are still spurious @file{configure} warnings about
2799 @code{datarootdir}, you may add the line
2802 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2806 to your @file{configure.ac} to disable the warnings. This is an exception
2807 to the usual rule that you should not define a macro whose name begins with
2808 @code{AC_} (@pxref{Macro Names}).
2812 @node Build Directories
2813 @subsection Build Directories
2814 @cindex Build directories
2815 @cindex Directories, build
2817 You can support compiling a software package for several architectures
2818 simultaneously from the same copy of the source code. The object files
2819 for each architecture are kept in their own directory.
2821 To support doing this, @command{make} uses the @code{VPATH} variable to
2822 find the files that are in the source directory. @acronym{GNU} Make
2823 can do this. Most other recent @command{make} programs can do this as
2824 well, though they may have difficulties and it is often simpler to
2825 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}). Older
2826 @command{make} programs do not support @code{VPATH}; when using them, the
2827 source code must be in the same directory as the object files.
2829 To support @code{VPATH}, each @file{Makefile.in} should contain two
2830 lines that look like:
2837 Do not set @code{VPATH} to the value of another variable, for example
2838 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2839 variable substitutions on the value of @code{VPATH}.
2841 @command{configure} substitutes the correct value for @code{srcdir} when
2842 it produces @file{Makefile}.
2844 Do not use the @code{make} variable @code{$<}, which expands to the
2845 file name of the file in the source directory (found with @code{VPATH}),
2846 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2847 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2848 versions of @command{make} do not set @code{$<} in explicit rules; they
2849 expand it to an empty value.
2851 Instead, Make command lines should always refer to source
2852 files by prefixing them with @samp{$(srcdir)/}. For example:
2855 time.info: time.texinfo
2856 $(MAKEINFO) '$(srcdir)/time.texinfo'
2859 @node Automatic Remaking
2860 @subsection Automatic Remaking
2861 @cindex Automatic remaking
2862 @cindex Remaking automatically
2864 You can put rules like the following in the top-level @file{Makefile.in}
2865 for a package to automatically update the configuration information when
2866 you change the configuration files. This example includes all of the
2867 optional files, such as @file{aclocal.m4} and those related to
2868 configuration header files. Omit from the @file{Makefile.in} rules for
2869 any of these files that your package does not use.
2871 The @samp{$(srcdir)/} prefix is included because of limitations in the
2872 @code{VPATH} mechanism.
2874 The @file{stamp-} files are necessary because the timestamps of
2875 @file{config.h.in} and @file{config.h} are not changed if remaking
2876 them does not change their contents. This feature avoids unnecessary
2877 recompilation. You should include the file @file{stamp-h.in} your
2878 package's distribution, so that @command{make} considers
2879 @file{config.h.in} up to date. Don't use @command{touch}
2880 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2881 @command{date} would cause needless differences, hence @acronym{CVS}
2886 $(srcdir)/configure: configure.ac aclocal.m4
2887 cd '$(srcdir)' && autoconf
2889 # autoheader might not change config.h.in, so touch a stamp file.
2890 $(srcdir)/config.h.in: stamp-h.in
2891 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2892 cd '$(srcdir)' && autoheader
2893 echo timestamp > '$(srcdir)/stamp-h.in'
2896 stamp-h: config.h.in config.status
2899 Makefile: Makefile.in config.status
2902 config.status: configure
2903 ./config.status --recheck
2908 (Be careful if you copy these lines directly into your makefile, as you
2909 need to convert the indented lines to start with the tab character.)
2911 In addition, you should use
2914 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2918 so @file{config.status} ensures that @file{config.h} is considered up to
2919 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2921 @xref{config.status Invocation}, for more examples of handling
2922 configuration-related dependencies.
2924 @node Configuration Headers
2925 @section Configuration Header Files
2926 @cindex Configuration Header
2927 @cindex @file{config.h}
2929 When a package contains more than a few tests that define C preprocessor
2930 symbols, the command lines to pass @option{-D} options to the compiler
2931 can get quite long. This causes two problems. One is that the
2932 @command{make} output is hard to visually scan for errors. More
2933 seriously, the command lines can exceed the length limits of some
2934 operating systems. As an alternative to passing @option{-D} options to
2935 the compiler, @command{configure} scripts can create a C header file
2936 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2937 macro selects this kind of output. Though it can be called anywhere
2938 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2939 it right after @code{AC_INIT}.
2941 The package should @samp{#include} the configuration header file before
2942 any other header files, to prevent inconsistencies in declarations (for
2943 example, if it redefines @code{const}).
2945 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2946 option (or @option{-I..}; whichever directory contains @file{config.h}).
2947 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2948 the directory of the currently read file, i.e., the source directory, not
2949 the build directory.
2951 With the appropriate @option{-I} option, you can use
2952 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2953 because in the rare case when the source directory contains another
2954 @file{config.h}, the build directory should be searched first.
2957 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2958 @acindex{CONFIG_HEADERS}
2959 @cvindex HAVE_CONFIG_H
2960 This macro is one of the instantiating macros; see @ref{Configuration
2961 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2962 blank-or-newline-separated list @var{header} containing C preprocessor
2963 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2964 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2965 The usual name for @var{header} is @file{config.h}.
2967 If @var{header} already exists and its contents are identical to what
2968 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2969 making some changes in the configuration without needlessly causing
2970 object files that depend on the header file to be recompiled.
2972 Usually the input file is named @file{@var{header}.in}; however, you can
2973 override the input file name by appending to @var{header} a
2974 colon-separated list of input files. For example, you might need to make
2975 the input file name acceptable to @acronym{DOS} variants:
2978 AC_CONFIG_HEADERS([config.h:config.hin])
2985 This macro is defined as the name of the first declared config header
2986 and undefined if no config headers have been declared up to this point.
2987 A third-party macro may, for example, require use of a config header
2988 without invoking AC_CONFIG_HEADERS twice, like this:
2991 AC_CONFIG_COMMANDS_PRE(
2992 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2997 @xref{Configuration Actions}, for more details on @var{header}.
3000 * Header Templates:: Input for the configuration headers
3001 * autoheader Invocation:: How to create configuration templates
3002 * Autoheader Macros:: How to specify CPP templates
3005 @node Header Templates
3006 @subsection Configuration Header Templates
3007 @cindex Configuration Header Template
3008 @cindex Header templates
3009 @cindex @file{config.h.in}
3011 Your distribution should contain a template file that looks as you want
3012 the final header file to look, including comments, with @code{#undef}
3013 statements which are used as hooks. For example, suppose your
3014 @file{configure.ac} makes these calls:
3017 AC_CONFIG_HEADERS([conf.h])
3018 AC_CHECK_HEADERS([unistd.h])
3022 Then you could have code like the following in @file{conf.h.in}. On
3023 systems that have @file{unistd.h}, @command{configure} defines
3024 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
3025 commented out (in case the system predefines that symbol).
3029 /* Define as 1 if you have unistd.h. */
3030 #undef HAVE_UNISTD_H
3034 Pay attention that @samp{#undef} is in the first column, and there is
3035 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3036 then decode the configuration header using the preprocessor directives:
3042 #ifdef HAVE_UNISTD_H
3043 # include <unistd.h>
3045 /* We are in trouble. */
3050 The use of old form templates, with @samp{#define} instead of
3051 @samp{#undef} is strongly discouraged. Similarly with old templates
3052 with comments on the same line as the @samp{#undef}. Anyway, putting
3053 comments in preprocessor macros has never been a good idea.
3055 Since it is a tedious task to keep a template header up to date, you may
3056 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3059 @node autoheader Invocation
3060 @subsection Using @command{autoheader} to Create @file{config.h.in}
3061 @cindex @command{autoheader}
3063 The @command{autoheader} program can create a template file of C
3064 @samp{#define} statements for @command{configure} to use.
3065 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3066 @file{configure} sources to determine the name of the template.
3067 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3068 input file name, @command{autoheader} uses the first one.)
3070 It is recommended that only one input file is used. If you want to append
3071 a boilerplate code, it is preferable to use
3072 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3073 File @file{conf_post.h} is not processed during the configuration then,
3074 which make things clearer. Analogically, @code{AH_TOP} can be used to
3075 prepend a boilerplate code.
3077 In order to do its job, @command{autoheader} needs you to document all
3078 of the symbols that you might use. Typically this is done via an
3079 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3080 is a literal symbol and whose third argument describes the symbol
3081 (@pxref{Defining Symbols}). Alternatively, you can use
3082 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3083 suitable input file for a subsequent configuration header file.
3084 Symbols defined by Autoconf's builtin tests are already documented properly;
3085 you need to document only those that you
3088 You might wonder why @command{autoheader} is needed: after all, why
3089 would @command{configure} need to ``patch'' a @file{config.h.in} to
3090 produce a @file{config.h} instead of just creating @file{config.h} from
3091 scratch? Well, when everything rocks, the answer is just that we are
3092 wasting our time maintaining @command{autoheader}: generating
3093 @file{config.h} directly is all that is needed. When things go wrong,
3094 however, you'll be thankful for the existence of @command{autoheader}.
3096 The fact that the symbols are documented is important in order to
3097 @emph{check} that @file{config.h} makes sense. The fact that there is a
3098 well-defined list of symbols that should be defined (or not) is
3099 also important for people who are porting packages to environments where
3100 @command{configure} cannot be run: they just have to @emph{fill in the
3103 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3105 If you give @command{autoheader} an argument, it uses that file instead
3106 of @file{configure.ac} and writes the header file to the standard output
3107 instead of to @file{config.h.in}. If you give @command{autoheader} an
3108 argument of @option{-}, it reads the standard input instead of
3109 @file{configure.ac} and writes the header file to the standard output.
3111 @command{autoheader} accepts the following options:
3116 Print a summary of the command line options and exit.
3120 Print the version number of Autoconf and exit.
3124 Report processing steps.
3128 Don't remove the temporary files.
3132 Remake the template file even if newer than its input files.
3134 @item --include=@var{dir}
3136 Append @var{dir} to the include path. Multiple invocations accumulate.
3138 @item --prepend-include=@var{dir}
3140 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3142 @item --warnings=@var{category}
3143 @itemx -W @var{category}
3145 Report the warnings related to @var{category} (which can actually be a
3146 comma separated list). Current categories include:
3150 report the uses of obsolete constructs
3153 report all the warnings
3159 treats warnings as errors
3161 @item no-@var{category}
3162 disable warnings falling into @var{category}
3169 @node Autoheader Macros
3170 @subsection Autoheader Macros
3171 @cindex Autoheader macros
3173 @command{autoheader} scans @file{configure.ac} and figures out which C
3174 preprocessor symbols it might define. It knows how to generate
3175 templates for symbols defined by @code{AC_CHECK_HEADERS},
3176 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3177 symbol, you must define a template for it. If there are missing
3178 templates, @command{autoheader} fails with an error message.
3180 The template for a @var{symbol} is created
3181 by @command{autoheader} from
3182 the @var{description} argument to an @code{AC_DEFINE};
3183 see @ref{Defining Symbols}.
3185 For special needs, you can use the following macros.
3188 @defmac AH_TEMPLATE (@var{key}, @var{description})
3190 Tell @command{autoheader} to generate a template for @var{key}. This macro
3191 generates standard templates just like @code{AC_DEFINE} when a
3192 @var{description} is given.
3197 AH_TEMPLATE([CRAY_STACKSEG_END],
3198 [Define to one of _getb67, GETB67, getb67
3199 for Cray-2 and Cray-YMP systems. This
3200 function is required for alloca.c support
3205 generates the following template, with the description properly
3209 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3210 Cray-YMP systems. This function is required for alloca.c
3211 support on those systems. */
3212 #undef CRAY_STACKSEG_END
3217 @defmac AH_VERBATIM (@var{key}, @var{template})
3219 Tell @command{autoheader} to include the @var{template} as-is in the header
3220 template file. This @var{template} is associated with the @var{key},
3221 which is used to sort all the different templates and guarantee their
3222 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3226 @defmac AH_TOP (@var{text})
3228 Include @var{text} at the top of the header template file.
3232 @defmac AH_BOTTOM (@var{text})
3234 Include @var{text} at the bottom of the header template file.
3238 Please note that @var{text} gets included ``verbatim'' to the template file,
3239 not to the resulting config header, so it can easily get mangled when the
3240 template is processed. There is rarely a need for something other than
3243 AH_BOTTOM([#include <custom.h>])
3248 @node Configuration Commands
3249 @section Running Arbitrary Configuration Commands
3250 @cindex Configuration commands
3251 @cindex Commands for configuration
3253 You can execute arbitrary commands before, during, and after
3254 @file{config.status} is run. The three following macros accumulate the
3255 commands to run when they are called multiple times.
3256 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3257 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3259 @anchor{AC_CONFIG_COMMANDS}
3260 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3261 @acindex{CONFIG_COMMANDS}
3262 Specify additional shell commands to run at the end of
3263 @file{config.status}, and shell commands to initialize any variables
3264 from @command{configure}. Associate the commands with @var{tag}.
3265 Since typically the @var{cmds} create a file, @var{tag} should
3266 naturally be the name of that file. If needed, the directory hosting
3267 @var{tag} is created. This macro is one of the instantiating macros;
3268 see @ref{Configuration Actions}.
3270 Here is an unrealistic example:
3273 AC_CONFIG_COMMANDS([fubar],
3274 [echo this is extra $fubar, and so on.],
3278 Here is a better one:
3280 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3284 The following two macros look similar, but in fact they are not of the same
3285 breed: they are executed directly by @file{configure}, so you cannot use
3286 @file{config.status} to rerun them.
3288 @c Yet it is good to leave them here. The user sees them together and
3289 @c decides which best fits their needs.
3291 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3292 @acindex{CONFIG_COMMANDS_PRE}
3293 Execute the @var{cmds} right before creating @file{config.status}.
3295 This macro presents the last opportunity to call @code{AC_SUBST},
3296 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3299 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3300 @acindex{CONFIG_COMMANDS_POST}
3301 Execute the @var{cmds} right after creating @file{config.status}.
3307 @node Configuration Links
3308 @section Creating Configuration Links
3309 @cindex Configuration links
3310 @cindex Links for configuration
3312 You may find it convenient to create links whose destinations depend upon
3313 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3314 creation of relative symbolic links can be delicate when the package is
3315 built in a directory different from the source directory.
3317 @anchor{AC_CONFIG_LINKS}
3318 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
3320 @acindex{CONFIG_LINKS}
3322 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3323 the corresponding link name @var{dest}. Makes a symbolic link if
3324 possible, otherwise a hard link if possible, otherwise a copy. The
3325 @var{dest} and @var{source} names should be relative to the top level
3326 source or build directory. This macro is one of the instantiating
3327 macros; see @ref{Configuration Actions}.
3329 For example, this call:
3332 AC_CONFIG_LINKS([host.h:config/$machine.h
3333 object.h:config/$obj_format.h])
3337 creates in the current directory @file{host.h} as a link to
3338 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3339 link to @file{@var{srcdir}/config/$obj_format.h}.
3341 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3342 impossible for @samp{config.status} to guess the links to establish.
3346 ./config.status host.h object.h
3349 to create the links.
3354 @node Subdirectories
3355 @section Configuring Other Packages in Subdirectories
3356 @cindex Configure subdirectories
3357 @cindex Subdirectory configure
3359 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3360 makefiles in subdirectories. However, @command{configure} scripts
3361 that control more than one independent package can use
3362 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3363 packages in subdirectories.
3365 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3366 @acindex{CONFIG_SUBDIRS}
3368 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3369 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3370 be a literal, i.e., please do not use:
3373 if test "$package_foo_enabled" = yes; then
3374 $my_subdirs="$my_subdirs foo"
3376 AC_CONFIG_SUBDIRS([$my_subdirs])
3380 because this prevents @samp{./configure --help=recursive} from
3381 displaying the options of the package @code{foo}. Instead, you should
3385 if test "$package_foo_enabled" = yes; then
3386 AC_CONFIG_SUBDIRS([foo])
3390 If a given @var{dir} is not found, an error is reported: if the
3391 subdirectory is optional, write:
3394 if test -d "$srcdir/foo"; then
3395 AC_CONFIG_SUBDIRS([foo])
3399 @c NB: Yes, below we mean configure.in, not configure.ac.
3400 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3401 of @command{configure}. This is for packages that might use a
3402 non-Autoconf script @command{Configure}, which can't be called through a
3403 wrapper @command{configure} since it would be the same file on
3404 case-insensitive file systems. Likewise, if a @var{dir} contains
3405 @file{configure.in} but no @command{configure}, the Cygnus
3406 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3408 The subdirectory @command{configure} scripts are given the same command
3409 line options that were given to this @command{configure} script, with minor
3410 changes if needed, which include:
3414 adjusting a relative name for the cache file;
3417 adjusting a relative name for the source directory;
3420 propagating the current value of @code{$prefix}, including if it was
3421 defaulted, and if the default values of the top level and of the subdirectory
3422 @file{configure} differ.
3425 This macro also sets the output variable @code{subdirs} to the list of
3426 directories @samp{@var{dir} @dots{}}. Make rules can use
3427 this variable to determine which subdirectories to recurse into.
3429 This macro may be called multiple times.
3432 @node Default Prefix
3433 @section Default Prefix
3434 @cindex Install prefix
3435 @cindex Prefix for install
3437 By default, @command{configure} sets the prefix for files it installs to
3438 @file{/usr/local}. The user of @command{configure} can select a different
3439 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3440 There are two ways to change the default: when creating
3441 @command{configure}, and when running it.
3443 Some software packages might want to install in a directory other than
3444 @file{/usr/local} by default. To accomplish that, use the
3445 @code{AC_PREFIX_DEFAULT} macro.
3447 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3448 @acindex{PREFIX_DEFAULT}
3449 Set the default installation prefix to @var{prefix} instead of
3453 It may be convenient for users to have @command{configure} guess the
3454 installation prefix from the location of a related program that they
3455 have already installed. If you wish to do that, you can call
3456 @code{AC_PREFIX_PROGRAM}.
3458 @anchor{AC_PREFIX_PROGRAM}
3459 @defmac AC_PREFIX_PROGRAM (@var{program})
3460 @acindex{PREFIX_PROGRAM}
3461 If the user did not specify an installation prefix (using the
3462 @option{--prefix} option), guess a value for it by looking for
3463 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3464 is found, set the prefix to the parent of the directory containing
3465 @var{program}, else default the prefix as described above
3466 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3467 @var{program} is @code{gcc} and the @env{PATH} contains
3468 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3473 @c ======================================================== Existing tests
3475 @node Existing Tests
3476 @chapter Existing Tests
3478 These macros test for particular system features that packages might
3479 need or want to use. If you need to test for a kind of feature that
3480 none of these macros check for, you can probably do it by calling
3481 primitive test macros with appropriate arguments (@pxref{Writing
3484 These tests print messages telling the user which feature they're
3485 checking for, and what they find. They cache their results for future
3486 @command{configure} runs (@pxref{Caching Results}).
3488 Some of these macros set output variables. @xref{Makefile
3489 Substitutions}, for how to get their values. The phrase ``define
3490 @var{name}'' is used below as a shorthand to mean ``define the C
3491 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3492 Symbols}, for how to get those symbol definitions into your program.
3495 * Common Behavior:: Macros' standard schemes
3496 * Alternative Programs:: Selecting between alternative programs
3497 * Files:: Checking for the existence of files
3498 * Libraries:: Library archives that might be missing
3499 * Library Functions:: C library functions that might be missing
3500 * Header Files:: Header files that might be missing
3501 * Declarations:: Declarations that may be missing
3502 * Structures:: Structures or members that might be missing
3503 * Types:: Types that might be missing
3504 * Compilers and Preprocessors:: Checking for compiling programs
3505 * System Services:: Operating system services
3506 * Posix Variants:: Special kludges for specific Posix variants
3507 * Erlang Libraries:: Checking for the existence of Erlang libraries
3510 @node Common Behavior
3511 @section Common Behavior
3512 @cindex Common autoconf behavior
3514 Much effort has been expended to make Autoconf easy to learn. The most
3515 obvious way to reach this goal is simply to enforce standard interfaces
3516 and behaviors, avoiding exceptions as much as possible. Because of
3517 history and inertia, unfortunately, there are still too many exceptions
3518 in Autoconf; nevertheless, this section describes some of the common
3522 * Standard Symbols:: Symbols defined by the macros
3523 * Default Includes:: Includes used by the generic macros
3526 @node Standard Symbols
3527 @subsection Standard Symbols
3528 @cindex Standard symbols
3530 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3531 their test transform their @var{argument} values to a standard alphabet.
3532 First, @var{argument} is converted to upper case and any asterisks
3533 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3534 that are not alphanumeric are converted to underscores.
3539 AC_CHECK_TYPES([struct $Expensive*])
3543 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3547 @node Default Includes
3548 @subsection Default Includes
3549 @cindex Default includes
3550 @cindex Includes, default
3552 Several tests depend upon a set of header files. Since these headers
3553 are not universally available, tests actually have to provide a set of
3554 protected includes, such as:
3558 #ifdef TIME_WITH_SYS_TIME
3559 # include <sys/time.h>
3562 # ifdef HAVE_SYS_TIME_H
3563 # include <sys/time.h>
3572 Unless you know exactly what you are doing, you should avoid using
3573 unconditional includes, and check the existence of the headers you
3574 include beforehand (@pxref{Header Files}).
3576 Most generic macros use the following macro to provide the default set
3579 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3580 @acindex{INCLUDES_DEFAULT}
3581 Expand to @var{include-directives} if defined, otherwise to:
3586 #ifdef HAVE_SYS_TYPES_H
3587 # include <sys/types.h>
3589 #ifdef HAVE_SYS_STAT_H
3590 # include <sys/stat.h>
3593 # include <stdlib.h>
3594 # include <stddef.h>
3596 # ifdef HAVE_STDLIB_H
3597 # include <stdlib.h>
3600 #ifdef HAVE_STRING_H
3601 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3602 # include <memory.h>
3604 # include <string.h>
3606 #ifdef HAVE_STRINGS_H
3607 # include <strings.h>
3609 #ifdef HAVE_INTTYPES_H
3610 # include <inttypes.h>
3612 #ifdef HAVE_STDINT_H
3613 # include <stdint.h>
3615 #ifdef HAVE_UNISTD_H
3616 # include <unistd.h>
3621 If the default includes are used, then check for the presence of these
3622 headers and their compatibility, i.e., you don't need to run
3623 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3625 These headers are checked for in the same order as they are included.
3626 For instance, on some systems @file{string.h} and @file{strings.h} both
3627 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3628 @code{HAVE_STRINGS_H}.
3631 @node Alternative Programs
3632 @section Alternative Programs
3633 @cindex Programs, checking
3635 These macros check for the presence or behavior of particular programs.
3636 They are used to choose between several alternative programs and to
3637 decide what to do once one has been chosen. If there is no macro
3638 specifically defined to check for a program you need, and you don't need
3639 to check for any special properties of it, then you can use one of the
3640 general program-check macros.
3643 * Particular Programs:: Special handling to find certain programs
3644 * Generic Programs:: How to find other programs
3647 @node Particular Programs
3648 @subsection Particular Program Checks
3650 These macros check for particular programs---whether they exist, and
3651 in some cases whether they support certain features.
3656 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3657 order, and set output variable @code{AWK} to the first one that is found.
3658 It tries @code{gawk} first because that is reported to be the
3659 best implementation.
3662 @defmac AC_PROG_GREP
3665 Look for the best available @code{grep} or @code{ggrep} that accepts the
3666 longest input lines possible, and that supports multiple @option{-e} options.
3667 Set the output variable @code{GREP} to whatever is chosen.
3668 @xref{Limitations of Usual Tools}, for more information about
3669 portability problems with the @command{grep} command family.
3672 @defmac AC_PROG_EGREP
3673 @acindex{PROG_EGREP}
3675 Check whether @code{$GREP -E} works, or else look for the best available
3676 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3677 Set the output variable @code{EGREP} to whatever is chosen.
3680 @defmac AC_PROG_FGREP
3681 @acindex{PROG_FGREP}
3683 Check whether @code{$GREP -F} works, or else look for the best available
3684 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3685 Set the output variable @code{FGREP} to whatever is chosen.
3688 @defmac AC_PROG_INSTALL
3689 @acindex{PROG_INSTALL}
3691 @ovindex INSTALL_PROGRAM
3692 @ovindex INSTALL_DATA
3693 @ovindex INSTALL_SCRIPT
3694 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3695 @command{install} program, if one is found in the current @env{PATH}.
3696 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3697 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3698 default directories) to determine @var{dir} (@pxref{Output}). Also set
3699 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3700 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3702 @samp{@@INSTALL@@} is special, as its value may vary for different
3703 configuration files.
3705 This macro screens out various instances of @command{install} known not to
3706 work. It prefers to find a C program rather than a shell script, for
3707 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3708 but that name is obsolete because some @command{make} programs have a rule
3709 that creates @file{install} from it if there is no makefile.
3711 Autoconf comes with a copy of @file{install-sh} that you can use. If
3712 you use @code{AC_PROG_INSTALL}, you must include either
3713 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3714 @command{configure} produces an error message saying it can't find
3715 them---even if the system you're on has a good @command{install} program.
3716 This check is a safety measure to prevent you from accidentally leaving
3717 that file out, which would prevent your package from installing on
3718 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3720 If you need to use your own installation program because it has features
3721 not found in standard @command{install} programs, there is no reason to use
3722 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3723 @file{Makefile.in} files.
3726 @defmac AC_PROG_MKDIR_P
3727 @acindex{PROG_MKDIR_P}
3729 Set output variable @code{MKDIR_P} to a program that ensures that for
3730 each argument, a directory named by this argument exists, creating it
3731 and its parent directories if needed, and without race conditions when
3732 two instances of the program attempt to make the same directory at
3733 nearly the same time.
3735 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3736 falls back on invoking @command{install-sh} with the @option{-d} option,
3737 so your package should
3738 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3739 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3740 is vulnerable to race conditions, so if you want to support parallel
3742 different packages into the same directory you need to make sure you
3743 have an up-to-date @file{install-sh}. In particular, be careful about
3744 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3746 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3747 in M4sh}), but it sets an output variable intended for use in other
3748 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3749 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3750 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3751 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3752 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3753 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3754 Finally, @code{AS_MKDIR_P} does not check for race condition
3755 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3757 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3758 configuration files.
3761 @anchor{AC_PROG_LEX}
3766 @cvindex YYTEXT_POINTER
3767 @ovindex LEX_OUTPUT_ROOT
3768 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3769 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3770 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3773 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3774 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3775 the base of the file name that the lexer generates; usually
3776 @file{lex.yy}, but sometimes something else. These results vary
3777 according to whether @code{lex} or @code{flex} is being used.
3779 You are encouraged to use Flex in your sources, since it is both more
3780 pleasant to use than plain Lex and the C source it produces is portable.
3781 In order to ensure portability, however, you must either provide a
3782 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3783 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3784 statement in the scanner's source. Once this done, the scanner is
3785 portable (unless @emph{you} felt free to use nonportable constructs) and
3786 does not depend on any library. In this case, and in this case only, it
3787 is suggested that you use this Autoconf snippet:
3791 if test "$LEX" != flex; then
3792 LEX="$SHELL $missing_dir/missing flex"
3793 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3794 AC_SUBST([LEXLIB], [''])
3798 The shell script @command{missing} can be found in the Automake
3801 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3802 (indirectly) this macro twice, which causes an annoying but benign
3803 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3804 of Automake will fix this issue; meanwhile, just ignore this message.
3806 As part of running the test, this macro may delete any file in the
3807 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3810 @anchor{AC_PROG_LN_S}
3811 @defmac AC_PROG_LN_S
3814 If @samp{ln -s} works on the current file system (the operating system
3815 and file system support symbolic links), set the output variable
3816 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3817 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3819 If you make a link in a directory other than the current directory, its
3820 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3821 create links using @samp{$(LN_S)}, either find out which form is used
3822 and adjust the arguments, or always invoke @code{ln} in the directory
3823 where the link is to be created.
3825 In other words, it does not work to do:
3833 (cd /x && $(LN_S) foo bar)
3837 @defmac AC_PROG_RANLIB
3838 @acindex{PROG_RANLIB}
3840 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3841 is found, and otherwise to @samp{:} (do nothing).
3847 Set output variable @code{SED} to a Sed implementation that conforms to
3848 Posix and does not have arbitrary length limits. Report an error if no
3849 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3850 information about portability problems with Sed.
3853 @defmac AC_PROG_YACC
3856 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3857 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3858 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3861 @node Generic Programs
3862 @subsection Generic Program and File Checks
3864 These macros are used to find programs not covered by the ``particular''
3865 test macros. If you need to check the behavior of a program as well as
3866 find out whether it is present, you have to write your own test for it
3867 (@pxref{Writing Tests}). By default, these macros use the environment
3868 variable @env{PATH}. If you need to check for a program that might not
3869 be in the user's @env{PATH}, you can pass a modified path to use
3873 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3874 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
3875 [/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
3878 You are strongly encouraged to declare the @var{variable} passed to
3879 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3880 @code{AC_ARG_VAR}, for more details.
3882 @anchor{AC_CHECK_PROG}
3883 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
3884 @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
3886 @acindex{CHECK_PROG}
3887 Check whether program @var{prog-to-check-for} exists in @var{path}. If
3888 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3889 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3890 absolute file name) even if it is the first found in the search path; in
3891 that case, set @var{variable} using the absolute file name of the
3892 @var{prog-to-check-for} found that is not @var{reject}. If
3893 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3897 @anchor{AC_CHECK_PROGS}
3898 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
3899 @ovar{value-if-not-found}, @dvar{path, $PATH})
3900 @acindex{CHECK_PROGS}
3901 Check for each program in the blank-separated list
3902 @var{progs-to-check-for} existing in the @var{path}. If one is found, set
3903 @var{variable} to the name of that program. Otherwise, continue
3904 checking the next program in the list. If none of the programs in the
3905 list are found, set @var{variable} to @var{value-if-not-found}; if
3906 @var{value-if-not-found} is not specified, the value of @var{variable}
3907 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3910 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
3911 @ovar{value-if-not-found}, @dvar{path, $PATH})
3912 @acindex{CHECK_TARGET_TOOL}
3913 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3914 with a prefix of the target type as determined by
3915 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3916 If the tool cannot be found with a prefix, and if the build and target
3917 types are equal, then it is also searched for without a prefix.
3919 As noted in @ref{Specifying Names, , Specifying the system type}, the
3920 target is rarely specified, because most of the time it is the same
3921 as the host: it is the type of system for which any compiler tool in
3922 the package produces code. What this macro looks for is,
3923 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3924 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3925 uses to produce objects, archives or executables}.
3928 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
3929 @ovar{value-if-not-found}, @dvar{path, $PATH})
3930 @acindex{CHECK_TOOL}
3931 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3932 with a prefix of the host type as determined by
3933 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3934 For example, if the user runs @samp{configure --host=i386-gnu}, then
3937 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3940 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3941 @var{path}, or otherwise to @samp{ranlib} if that program exists in
3942 @var{path}, or to @samp{:} if neither program exists.
3944 In the future, when cross-compiling this macro will @emph{only}
3945 accept program names that are prefixed with the host type.
3946 For more information, see @ref{Specifying Names, , Specifying the
3950 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
3951 @ovar{value-if-not-found}, @dvar{path, $PATH})
3952 @acindex{CHECK_TARGET_TOOLS}
3953 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3954 @var{progs-to-check-for} are checked with a prefix of the target type as
3955 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3956 (@pxref{Canonicalizing}). If none of the tools can be found with a
3957 prefix, and if the build and target types are equal, then the first one
3958 without a prefix is used. If a tool is found, set @var{variable} to
3959 the name of that program. If none of the tools in the list are found,
3960 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3961 is not specified, the value of @var{variable} is not changed. Calls
3962 @code{AC_SUBST} for @var{variable}.
3965 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
3966 @ovar{value-if-not-found}, @dvar{path, $PATH})
3967 @acindex{CHECK_TOOLS}
3968 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3969 @var{progs-to-check-for} are checked with a prefix of the host type as
3970 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3971 (@pxref{Canonicalizing}). If none of the tools can be found with a
3972 prefix, then the first one without a prefix is used. If a tool is found,
3973 set @var{variable} to the name of that program. If none of the tools in
3974 the list are found, set @var{variable} to @var{value-if-not-found}; if
3975 @var{value-if-not-found} is not specified, the value of @var{variable}
3976 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3978 In the future, when cross-compiling this macro will @emph{not}
3979 accept program names that are not prefixed with the host type.
3982 @anchor{AC_PATH_PROG}
3983 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
3984 @ovar{value-if-not-found}, @dvar{path, $PATH})
3986 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3987 name of @var{prog-to-check-for} if found.
3990 @anchor{AC_PATH_PROGS}
3991 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
3992 @ovar{value-if-not-found}, @dvar{path, $PATH})
3993 @acindex{PATH_PROGS}
3994 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3995 are found, set @var{variable} to the absolute name of the program
3999 @defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
4000 @var{progs-to-check-for}, @var{feature-test}, @
4001 @ovar{action-if-not-found}, @dvar{path, $PATH})
4002 @acindex{PATH_PROGS_FEATURE_CHECK}
4003 This macro was introduced in Autoconf 2.62. If @var{variable} is not
4004 empty, then set the cache variable @code{$ac_cv_path_@var{variable}} to
4005 its value. Otherwise, check for each program in the blank-separated
4006 list @var{progs-to-check-for} existing in @var{path}. For each program
4007 found, execute @var{feature-test} with @code{$ac_path_@var{variable}}
4008 set to the absolute name of the candidate program. If no invocation of
4009 @var{feature-test} sets the shell variable
4010 @code{$ac_cv_path_@var{variable}}, then @var{action-if-not-found} is
4011 executed. @var{feature-test} will be run even when
4012 @code{ac_cv_path_@var{variable}} is set, to provide the ability to
4013 choose a better candidate found later in @var{path}; to accept the
4014 current setting and bypass all futher checks, @var{feature-test} can
4015 execute @code{ac_path_@var{variable}_found=:}.
4017 Note that this macro has some subtle differences from
4018 @code{AC_CHECK_PROGS}. It is designed to be run inside
4019 @code{AC_CACHE_VAL}, therefore, it should have no side effects. In
4020 particular, @var{variable} is not set to the final value of
4021 @code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically
4022 run. Also, on failure, any action can be performed, whereas
4023 @code{AC_CHECK_PROGS} only performs
4024 @code{@var{variable}=@var{value-if-not-found}}.
4026 Here is an example, similar to what Autoconf uses in its own configure
4027 script. It will search for an implementation of @command{m4} that
4028 supports the @code{indir} builtin, even if it goes by the name
4029 @command{gm4} or is not the first implementation on @env{PATH}.
4032 AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
4033 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
4034 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
4035 test "x$m4out" = x0 \
4036 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
4037 [AC_MSG_ERROR([could not find m4 that supports indir])])])
4038 AC_SUBST([M4], [$ac_cv_path_M4])
4042 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
4043 @ovar{value-if-not-found}, @dvar{path, $PATH})
4044 @acindex{PATH_TARGET_TOOL}
4045 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
4046 name of the program if it is found.
4049 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
4050 @ovar{value-if-not-found}, @dvar{path, $PATH})
4052 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
4053 name of the program if it is found.
4055 In the future, when cross-compiling this macro will @emph{not}
4056 accept program names that are not prefixed with the host type.
4062 @cindex File, checking
4064 You might also need to check for the existence of files. Before using
4065 these macros, ask yourself whether a runtime test might not be a better
4066 solution. Be aware that, like most Autoconf macros, they test a feature
4067 of the host machine, and therefore, they die when cross-compiling.
4069 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
4070 @ovar{action-if-not-found})
4071 @acindex{CHECK_FILE}
4072 Check whether file @var{file} exists on the native system. If it is
4073 found, execute @var{action-if-found}, otherwise do
4074 @var{action-if-not-found}, if given.
4077 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
4078 @ovar{action-if-not-found})
4079 @acindex{CHECK_FILES}
4080 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
4081 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
4082 for each file found.
4087 @section Library Files
4088 @cindex Library, checking
4090 The following macros check for the presence of certain C, C++, or Fortran
4091 library archive files.
4093 @anchor{AC_CHECK_LIB}
4094 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @
4095 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4097 Test whether the library @var{library} is available by trying to link
4098 a test program that calls function @var{function} with the library.
4099 @var{function} should be a function provided by the library.
4101 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4102 the @var{library} argument.
4104 @var{action-if-found} is a list of shell commands to run if the link
4105 with the library succeeds; @var{action-if-not-found} is a list of shell
4106 commands to run if the link fails. If @var{action-if-found} is not
4107 specified, the default action prepends @option{-l@var{library}} to
4108 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4109 capitals). This macro is intended to support building @code{LIBS} in
4110 a right-to-left (least-dependent to most-dependent) fashion such that
4111 library dependencies are satisfied as a natural side effect of
4112 consecutive tests. Linkers are sensitive to library ordering
4113 so the order in which @code{LIBS} is generated is important to reliable
4114 detection of libraries.
4116 If linking with @var{library} results in unresolved symbols that would
4117 be resolved by linking with additional libraries, give those libraries
4118 as the @var{other-libraries} argument, separated by spaces:
4119 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4120 that @var{library} is present, because linking the test program
4121 always fails with unresolved symbols. The @var{other-libraries} argument
4122 should be limited to cases where it is desirable to test for one library
4123 in the presence of another that is not already in @code{LIBS}.
4125 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4126 in some common cases. Many standard functions like @code{gethostbyname}
4127 appear in the standard C library on some hosts, and in special libraries
4128 like @code{nsl} on other hosts. On some hosts the special libraries
4129 contain variant implementations that you may not want to use. These
4130 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4131 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4134 @anchor{AC_SEARCH_LIBS}
4135 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
4136 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4137 @acindex{SEARCH_LIBS}
4138 Search for a library defining @var{function} if it's not already
4139 available. This equates to calling
4140 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4141 no libraries, then for each library listed in @var{search-libs}.
4143 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4144 to contain @var{function}, and run @var{action-if-found}. If the
4145 function is not found, run @var{action-if-not-found}.
4147 If linking with @var{library} results in unresolved symbols that would
4148 be resolved by linking with additional libraries, give those libraries
4149 as the @var{other-libraries} argument, separated by spaces:
4150 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4151 that @var{function} is present, because linking the test program
4152 always fails with unresolved symbols.
4157 @node Library Functions
4158 @section Library Functions
4160 The following macros check for particular C library functions.
4161 If there is no macro specifically defined to check for a function you need,
4162 and you don't need to check for any special properties of
4163 it, then you can use one of the general function-check macros.
4166 * Function Portability:: Pitfalls with usual functions
4167 * Particular Functions:: Special handling to find certain functions
4168 * Generic Functions:: How to find other functions
4171 @node Function Portability
4172 @subsection Portability of C Functions
4173 @cindex Portability of C functions
4174 @cindex C function portability
4176 Most usual functions can either be missing, or be buggy, or be limited
4177 on some architectures. This section tries to make an inventory of these
4178 portability issues. By definition, this list always requires
4179 additions. Please help us keeping it as complete as possible.
4184 @prindex @code{exit}
4185 On ancient hosts, @code{exit} returned @code{int}.
4186 This is because @code{exit} predates @code{void}, and there was a long
4187 tradition of it returning @code{int}.
4189 On current hosts, the problem more likely is that @code{exit} is not
4190 declared, due to C++ problems of some sort or another. For this reason
4191 we suggest that test programs not invoke @code{exit}, but return from
4192 @code{main} instead.
4196 @prindex @code{free}
4197 The C standard says a call @code{free (NULL)} does nothing, but
4198 some old systems don't support this (e.g., NextStep).
4204 @prindex @code{isinf}
4205 @prindex @code{isnan}
4206 The C99 standard says that @code{isinf} and @code{isnan} are
4207 macros. On some systems just macros are available
4208 (e.g., @acronym{HP-UX} and Solaris 10), on
4209 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4210 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4211 these functions are declared in nonstandard headers like
4212 @code{<sunmath.h>} and defined in non-default libraries like
4213 @option{-lm} or @option{-lsunmath}.
4215 The C99 @code{isinf} and @code{isnan} macros work correctly with
4216 @code{long double} arguments, but pre-C99 systems that use functions
4217 typically assume @code{double} arguments. On such a system,
4218 @code{isinf} incorrectly returns true for a finite @code{long double}
4219 argument that is outside the range of @code{double}.
4221 To work around this porting mess, you can use code like the following.
4228 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4229 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4231 static inline int isnan_f (float x) @{ return x != x; @}
4232 static inline int isnan_d (double x) @{ return x != x; @}
4233 static inline int isnan_ld (long double x) @{ return x != x; @}
4238 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4239 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4241 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4242 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4243 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4247 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4248 compilers that lack the @code{inline} keyword. Some optimizing
4249 compilers mishandle these definitions, but systems with that bug
4250 typically have missing or broken @code{isnan} functions anyway, so it's
4251 probably not worth worrying about.
4255 @prindex @code{malloc}
4256 The C standard says a call @code{malloc (0)} is implementation
4257 dependent. It can return either @code{NULL} or a new non-null pointer.
4258 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4259 no means universal. @code{AC_FUNC_MALLOC}
4260 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4264 @prindex @code{putenv}
4265 Posix prefers @code{setenv} to @code{putenv}; among other things,
4266 @code{putenv} is not required of all Posix implementations, but
4269 Posix specifies that @code{putenv} puts the given string directly in
4270 @code{environ}, but some systems make a copy of it instead (e.g.,
4271 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4272 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4274 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4275 environment, but this is not standard usage and it dumps core
4276 on some systems (e.g., AIX).
4278 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4279 environment, rather than inserting it with an empty value.
4281 @item @code{realloc}
4283 @prindex @code{realloc}
4284 The C standard says a call @code{realloc (NULL, size)} is equivalent
4285 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4288 @item @code{signal} handler
4290 @prindex @code{signal}
4291 Normally @code{signal} takes a handler function with a return type of
4292 @code{void}, but some old systems required @code{int} instead. Any
4293 actual @code{int} value returned is not used; this is only a
4294 difference in the function prototype demanded.
4296 All systems we know of in current use return @code{void}. The
4297 @code{int} was to support K&R C, where of course @code{void} is not
4298 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4299 used to establish the correct type in all cases.
4301 @item @code{snprintf}
4302 @c @fuindex snprintf
4303 @prindex @code{snprintf}
4304 @c @fuindex vsnprintf
4305 @prindex @code{vsnprintf}
4306 The C99 standard says that if the output array isn't big enough
4307 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4308 truncate the output and return the number of bytes that ought to have
4309 been produced. Some older systems return the truncated length (e.g.,
4310 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4311 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4312 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4313 older systems ignore the length and overrun the buffer (e.g., 64-bit
4316 @item @code{sprintf}
4318 @prindex @code{sprintf}
4319 @c @fuindex vsprintf
4320 @prindex @code{vsprintf}
4321 The C standard says @code{sprintf} and @code{vsprintf} return the
4322 number of bytes written. On some ancient systems (SunOS 4 for
4323 instance) they return the buffer pointer instead, but these no
4324 longer need to be worried about.
4328 @prindex @code{sscanf}
4329 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires
4331 input string be writable (though it doesn't actually change it). This
4332 can be a problem when using @command{gcc} since it normally puts
4333 constant strings in read-only memory (@pxref{Incompatibilities,
4334 Incompatibilities of @acronym{GCC}, , gcc, Using and
4335 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4336 having format strings read-only can be a problem.
4338 @item @code{strerror_r}
4339 @c @fuindex strerror_r
4340 @prindex @code{strerror_r}
4341 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4342 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4343 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4344 can detect which is in use (@pxref{Particular Functions}).
4346 @item @code{strnlen}
4348 @prindex @code{strnlen}
4349 @acronym{AIX} 4.3 provides a broken version which produces the
4353 strnlen ("foobar", 0) = 0
4354 strnlen ("foobar", 1) = 3
4355 strnlen ("foobar", 2) = 2
4356 strnlen ("foobar", 3) = 1
4357 strnlen ("foobar", 4) = 0
4358 strnlen ("foobar", 5) = 6
4359 strnlen ("foobar", 6) = 6
4360 strnlen ("foobar", 7) = 6
4361 strnlen ("foobar", 8) = 6
4362 strnlen ("foobar", 9) = 6
4365 @item @code{sysconf}
4367 @prindex @code{sysconf}
4368 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4369 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4374 @prindex @code{unlink}
4375 The Posix spec says that @code{unlink} causes the given file to be
4376 removed only after there are no more open file handles for it. Some
4377 non-Posix hosts have trouble with this requirement, though,
4378 and some @acronym{DOS} variants even corrupt the file system.
4380 @item @code{unsetenv}
4381 @c @fuindex unsetenv
4382 @prindex @code{unsetenv}
4383 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4384 can be removed with a call @code{putenv ("FOO=")}, as described under
4385 @code{putenv} above.
4387 @item @code{va_copy}
4389 @prindex @code{va_copy}
4390 The C99 standard provides @code{va_copy} for copying
4391 @code{va_list} variables. It may be available in older environments
4392 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4393 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4394 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4397 @item @code{va_list}
4399 @prindex @code{va_list}
4400 @code{va_list} is not necessarily just a pointer. It can be a
4401 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4402 not portable. Or it can be an array (e.g., @command{gcc} in some
4403 PowerPC configurations), which means as a function parameter it can be
4404 effectively call-by-reference and library routines might modify the
4405 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4408 @item Signed @code{>>}
4409 Normally the C @code{>>} right shift of a signed type replicates the
4410 high bit, giving a so-called ``arithmetic'' shift. But care should be
4411 taken since Standard C doesn't require that behavior. On those
4412 few processors without a native arithmetic shift (for instance Cray
4413 vector systems) zero bits may be shifted in, the same as a shift of an
4416 @item Integer @code{/}
4417 C divides signed integers by truncating their quotient toward zero,
4418 yielding the same result as Fortran. However, before C99 the standard
4419 allowed C implementations to take the floor or ceiling of the quotient
4420 in some cases. Hardly any implementations took advantage of this
4421 freedom, though, and it's probably not worth worrying about this issue
4426 @node Particular Functions
4427 @subsection Particular Function Checks
4428 @cindex Function, checking
4430 These macros check for particular C functions---whether they exist, and
4431 in some cases how they respond when given certain arguments.
4433 @anchor{AC_FUNC_ALLOCA}
4434 @defmac AC_FUNC_ALLOCA
4435 @acindex{FUNC_ALLOCA}
4437 @cvindex HAVE_ALLOCA_H
4440 @prindex @code{alloca}
4442 Check how to get @code{alloca}. Tries to get a builtin version by
4443 checking for @file{alloca.h} or the predefined C preprocessor macros
4444 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4445 it defines @code{HAVE_ALLOCA_H}.
4447 If those attempts fail, it looks for the function in the standard C
4448 library. If any of those methods succeed, it defines
4449 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4450 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4451 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4452 garbage collect). This variable is separate from @code{LIBOBJS} so
4453 multiple programs can share the value of @code{ALLOCA} without needing
4454 to create an actual library, in case only some of them use the code in
4455 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4456 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4458 This macro does not try to get @code{alloca} from the System V R3
4459 @file{libPW} or the System V R4 @file{libucb} because those libraries
4460 contain some incompatible functions that cause trouble. Some versions
4461 do not even contain @code{alloca} or contain a buggy version. If you
4462 still want to use their @code{alloca}, use @code{ar} to extract
4463 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4465 Source files that use @code{alloca} should start with a piece of code
4466 like the following, to declare it properly.
4470 #ifdef HAVE_ALLOCA_H
4471 # include <alloca.h>
4472 #elif defined __GNUC__
4473 # define alloca __builtin_alloca
4475 # define alloca __alloca
4476 #elif defined _MSC_VER
4477 # include <malloc.h>
4478 # define alloca _alloca
4480 # include <stddef.h>
4484 void *alloca (size_t);
4490 @defmac AC_FUNC_CHOWN
4491 @acindex{FUNC_CHOWN}
4494 @prindex @code{chown}
4495 If the @code{chown} function is available and works (in particular, it
4496 should accept @option{-1} for @code{uid} and @code{gid}), define
4500 @anchor{AC_FUNC_CLOSEDIR_VOID}
4501 @defmac AC_FUNC_CLOSEDIR_VOID
4502 @acindex{FUNC_CLOSEDIR_VOID}
4503 @cvindex CLOSEDIR_VOID
4504 @c @fuindex closedir
4505 @prindex @code{closedir}
4506 If the @code{closedir} function does not return a meaningful value,
4507 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4508 return value for an error indicator.
4510 Currently this test is implemented by running a test program. When
4511 cross compiling the pessimistic assumption that @code{closedir} does not
4512 return a meaningful value is made.
4514 This macro is obsolescent, as @code{closedir} returns a meaningful value
4515 on current systems. New programs need not use this macro.
4518 @defmac AC_FUNC_ERROR_AT_LINE
4519 @acindex{FUNC_ERROR_AT_LINE}
4520 @c @fuindex error_at_line
4521 @prindex @code{error_at_line}
4522 If the @code{error_at_line} function is not found, require an
4523 @code{AC_LIBOBJ} replacement of @samp{error}.
4526 @defmac AC_FUNC_FNMATCH
4527 @acindex{FUNC_FNMATCH}
4529 @prindex @code{fnmatch}
4530 If the @code{fnmatch} function conforms to Posix, define
4531 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4532 the bugs in Solaris 2.4.
4534 Unlike the other specific
4535 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4536 broken/missing @code{fnmatch}. This is for historical reasons.
4537 See @code{AC_REPLACE_FNMATCH} below.
4539 This macro is obsolescent. New programs should use Gnulib's
4540 @code{fnmatch-posix} module. @xref{Gnulib}.
4543 @defmac AC_FUNC_FNMATCH_GNU
4544 @acindex{FUNC_FNMATCH_GNU}
4546 @prindex @code{fnmatch}
4547 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4548 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4549 implementation bugs, for example, the bugs in the @acronym{GNU} C
4552 This macro is obsolescent. New programs should use Gnulib's
4553 @code{fnmatch-gnu} module. @xref{Gnulib}.
4556 @anchor{AC_FUNC_FORK}
4557 @defmac AC_FUNC_FORK
4559 @cvindex HAVE_VFORK_H
4560 @cvindex HAVE_WORKING_FORK
4561 @cvindex HAVE_WORKING_VFORK
4564 @prindex @code{fork}
4566 @prindex @code{vfork}
4568 This macro checks for the @code{fork} and @code{vfork} functions. If a
4569 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4570 checks whether @code{fork} is just a stub by trying to run it.
4572 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4573 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4574 define @code{vfork} to be @code{fork} for backward compatibility with
4575 previous versions of @command{autoconf}. This macro checks for several known
4576 errors in implementations of @code{vfork} and considers the system to not
4577 have a working @code{vfork} if it detects any of them. It is not considered
4578 to be an implementation error if a child's invocation of @code{signal}
4579 modifies the parent's signal handler, since child processes rarely change
4580 their signal handlers.
4582 Since this macro defines @code{vfork} only for backward compatibility with
4583 previous versions of @command{autoconf} you're encouraged to define it
4584 yourself in new code:
4587 #ifndef HAVE_WORKING_VFORK
4594 @defmac AC_FUNC_FSEEKO
4595 @acindex{FUNC_FSEEKO}
4596 @cvindex _LARGEFILE_SOURCE
4597 @cvindex HAVE_FSEEKO
4599 @prindex @code{fseeko}
4600 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4601 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4602 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4603 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4604 largefile-sensitive systems where @code{off_t} does not default to a
4608 @defmac AC_FUNC_GETGROUPS
4609 @acindex{FUNC_GETGROUPS}
4610 @cvindex HAVE_GETGROUPS
4611 @ovindex GETGROUPS_LIBS
4612 @c @fuindex getgroups
4613 @prindex @code{getgroups}
4614 If the @code{getgroups} function is available and works (unlike on
4615 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4616 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4617 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4620 @anchor{AC_FUNC_GETLOADAVG}
4621 @defmac AC_FUNC_GETLOADAVG
4622 @acindex{FUNC_GETLOADAVG}
4627 @cvindex HAVE_NLIST_H
4628 @cvindex NLIST_NAME_UNION
4629 @cvindex GETLOADAVG_PRIVILEGED
4630 @cvindex NEED_SETGID
4631 @cvindex C_GETLOADAVG
4633 @ovindex NEED_SETGID
4635 @ovindex GETLOADAVG_LIBS
4636 @c @fuindex getloadavg
4637 @prindex @code{getloadavg}
4638 Check how to get the system load averages. To perform its tests
4639 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4640 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4641 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4643 If the system has the @code{getloadavg} function, define
4644 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4645 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4646 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4647 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4648 possibly define several other C preprocessor macros and output
4653 Define @code{C_GETLOADAVG}.
4656 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4661 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4664 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4665 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4666 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4669 Programs may need to be installed set-group-ID (or set-user-ID) for
4670 @code{getloadavg} to work. In this case, define
4671 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4672 to @samp{true} (and otherwise to @samp{false}), and set
4673 @code{KMEM_GROUP} to the name of the group that should own the installed
4677 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
4678 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
4681 @anchor{AC_FUNC_GETMNTENT}
4682 @defmac AC_FUNC_GETMNTENT
4683 @acindex{FUNC_GETMNTENT}
4684 @cvindex HAVE_GETMNTENT
4685 @c @fuindex getmntent
4686 @prindex @code{getmntent}
4687 Check for @code{getmntent} in the standard C library, and then in the
4688 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4689 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4690 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4693 @defmac AC_FUNC_GETPGRP
4694 @acindex{FUNC_GETPGRP}
4695 @cvindex GETPGRP_VOID
4698 @prindex @code{getpgid}
4699 @prindex @code{getpgrp}
4700 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4701 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4702 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4703 behaves like Posix's @code{getpgid}.
4713 This macro does not check whether
4714 @code{getpgrp} exists at all; if you need to work in that situation,
4715 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4717 This macro is obsolescent, as current systems have a @code{getpgrp}
4718 whose signature conforms to Posix. New programs need not use this macro.
4721 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4722 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4723 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4725 @prindex @code{lstat}
4726 If @file{link} is a symbolic link, then @code{lstat} should treat
4727 @file{link/} the same as @file{link/.}. However, many older
4728 @code{lstat} implementations incorrectly ignore trailing slashes.
4730 It is safe to assume that if @code{lstat} incorrectly ignores
4731 trailing slashes, then other symbolic-link-aware functions like
4732 @code{unlink} also incorrectly ignore trailing slashes.
4734 If @code{lstat} behaves properly, define
4735 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4736 @code{AC_LIBOBJ} replacement of @code{lstat}.
4739 @defmac AC_FUNC_MALLOC
4740 @acindex{FUNC_MALLOC}
4741 @cvindex HAVE_MALLOC
4744 @prindex @code{malloc}
4745 If the @code{malloc} function is compatible with the @acronym{GNU} C
4746 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4747 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4748 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4749 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4750 native @code{malloc} is not used in the main project.
4752 Typically, the replacement file @file{malloc.c} should look like (note
4753 the @samp{#undef malloc}):
4756 #ifdef HAVE_CONFIG_H
4757 # include <config.h>
4761 #include <sys/types.h>
4765 /* Allocate an N-byte block of memory from the heap.
4766 If N is zero, allocate a 1-byte block. */
4769 rpl_malloc (size_t n)
4778 @defmac AC_FUNC_MEMCMP
4779 @acindex{FUNC_MEMCMP}
4782 @prindex @code{memcmp}
4783 If the @code{memcmp} function is not available, or does not work on
4784 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4785 bytes or more and with at least one buffer not starting on a 4-byte
4786 boundary (such as the one on NeXT x86 OpenStep), require an
4787 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4789 This macro is obsolescent, as current systems have a working
4790 @code{memcmp}. New programs need not use this macro.
4793 @defmac AC_FUNC_MBRTOWC
4794 @acindex{FUNC_MBRTOWC}
4795 @cvindex HAVE_MBRTOWC
4797 @prindex @code{mbrtowc}
4798 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4799 type @code{mbstate_t} are properly declared.
4802 @defmac AC_FUNC_MKTIME
4803 @acindex{FUNC_MKTIME}
4806 @prindex @code{mktime}
4807 If the @code{mktime} function is not available, or does not work
4808 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4809 For the purposes of this test, @code{mktime} should conform to the
4810 Posix standard and should be the inverse of
4814 @anchor{AC_FUNC_MMAP}
4815 @defmac AC_FUNC_MMAP
4819 @prindex @code{mmap}
4820 If the @code{mmap} function exists and works correctly, define
4821 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4825 @defmac AC_FUNC_OBSTACK
4826 @acindex{FUNC_OBSTACK}
4827 @cvindex HAVE_OBSTACK
4829 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4830 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4833 @defmac AC_FUNC_REALLOC
4834 @acindex{FUNC_REALLOC}
4835 @cvindex HAVE_REALLOC
4838 @prindex @code{realloc}
4839 If the @code{realloc} function is compatible with the @acronym{GNU} C
4840 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4841 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4842 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4843 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4844 the native @code{realloc} is not used in the main project. See
4845 @code{AC_FUNC_MALLOC} for details.
4848 @defmac AC_FUNC_SELECT_ARGTYPES
4849 @acindex{FUNC_SELECT_ARGTYPES}
4850 @cvindex SELECT_TYPE_ARG1
4851 @cvindex SELECT_TYPE_ARG234
4852 @cvindex SELECT_TYPE_ARG5
4854 @prindex @code{select}
4855 Determines the correct type to be passed for each of the
4856 @code{select} function's arguments, and defines those types
4857 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4858 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4859 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4860 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4862 This macro is obsolescent, as current systems have a @code{select} whose
4863 signature conforms to Posix. New programs need not use this macro.
4866 @defmac AC_FUNC_SETPGRP
4867 @acindex{FUNC_SETPGRP}
4868 @cvindex SETPGRP_VOID
4870 @prindex @code{setpgrp}
4871 If @code{setpgrp} takes no argument (the Posix version), define
4872 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4873 two process IDs as arguments. This macro does not check whether
4874 @code{setpgrp} exists at all; if you need to work in that situation,
4875 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4877 This macro is obsolescent, as current systems have a @code{setpgrp}
4878 whose signature conforms to Posix. New programs need not use this macro.
4881 @defmac AC_FUNC_STAT
4882 @defmacx AC_FUNC_LSTAT
4884 @acindex{FUNC_LSTAT}
4885 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4886 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4888 @prindex @code{stat}
4890 @prindex @code{lstat}
4891 Determine whether @code{stat} or @code{lstat} have the bug that it
4892 succeeds when given the zero-length file name as argument. The @code{stat}
4893 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4896 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4897 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4900 These macros are obsolescent, as no current systems have the bug.
4901 New programs need not use these macros.
4904 @anchor{AC_FUNC_STRCOLL}
4905 @defmac AC_FUNC_STRCOLL
4906 @acindex{FUNC_STRCOLL}
4907 @cvindex HAVE_STRCOLL
4909 @prindex @code{strcoll}
4910 If the @code{strcoll} function exists and works correctly, define
4911 @code{HAVE_STRCOLL}. This does a bit more than
4912 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4913 definitions of @code{strcoll} that should not be used.
4916 @defmac AC_FUNC_STRERROR_R
4917 @acindex{FUNC_STRERROR_R}
4918 @cvindex HAVE_STRERROR_R
4919 @cvindex HAVE_DECL_STRERROR_R
4920 @cvindex STRERROR_R_CHAR_P
4921 @c @fuindex strerror_r
4922 @prindex @code{strerror_r}
4923 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4924 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4925 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4926 returns an @code{int} error number. The Thread-Safe Functions option of
4927 Posix requires @code{strerror_r} to return @code{int}, but
4928 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4929 Library) return a @code{char *} value that is not necessarily equal to
4930 the buffer argument.
4933 @anchor{AC_FUNC_STRFTIME}
4934 @defmac AC_FUNC_STRFTIME
4935 @acindex{FUNC_STRFTIME}
4936 @cvindex HAVE_STRFTIME
4937 @c @fuindex strftime
4938 @prindex @code{strftime}
4939 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4940 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4942 This macro is obsolescent, as no current systems require the @file{intl}
4943 library for @code{strftime}. New programs need not use this macro.
4946 @defmac AC_FUNC_STRTOD
4947 @acindex{FUNC_STRTOD}
4950 @prindex @code{strtod}
4951 If the @code{strtod} function does not exist or doesn't work correctly,
4952 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4953 because @file{strtod.c} is likely to need @samp{pow}, set the output
4954 variable @code{POW_LIB} to the extra library needed.
4957 @defmac AC_FUNC_STRTOLD
4958 @acindex{FUNC_STRTOLD}
4959 @cvindex HAVE_STRTOLD
4960 @prindex @code{strtold}
4961 If the @code{strtold} function exists and conforms to C99, define
4962 @code{HAVE_STRTOLD}.
4965 @defmac AC_FUNC_STRNLEN
4966 @acindex{FUNC_STRNLEN}
4967 @cvindex HAVE_STRNLEN
4969 @prindex @code{strnlen}
4970 If the @code{strnlen} function is not available, or is buggy (like the one
4971 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4974 @anchor{AC_FUNC_UTIME_NULL}
4975 @defmac AC_FUNC_UTIME_NULL
4976 @acindex{FUNC_UTIME_NULL}
4977 @cvindex HAVE_UTIME_NULL
4979 @prindex @code{utime}
4980 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4981 the present, define @code{HAVE_UTIME_NULL}.
4983 This macro is obsolescent, as all current systems have a @code{utime}
4984 that behaves this way. New programs need not use this macro.
4987 @anchor{AC_FUNC_VPRINTF}
4988 @defmac AC_FUNC_VPRINTF
4989 @acindex{FUNC_VPRINTF}
4990 @cvindex HAVE_VPRINTF
4991 @cvindex HAVE_DOPRNT
4993 @prindex @code{vprintf}
4994 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4995 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4996 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4997 are also available.)
4999 This macro is obsolescent, as all current systems have @code{vprintf}.
5000 New programs need not use this macro.
5003 @defmac AC_REPLACE_FNMATCH
5004 @acindex{REPLACE_FNMATCH}
5006 @prindex @code{fnmatch}
5007 @hdrindex{fnmatch.h}
5008 If the @code{fnmatch} function does not conform to Posix (see
5009 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
5011 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
5012 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
5013 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
5014 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
5015 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
5016 included in place of the system @code{<fnmatch.h>}.
5018 This macro is obsolescent, as it assumes the use of particular source
5019 files. New programs should use Gnulib's @code{fnmatch-posix} module,
5020 which provides this macro along with the source files. @xref{Gnulib}.
5025 @node Generic Functions
5026 @subsection Generic Function Checks
5028 These macros are used to find functions not covered by the ``particular''
5029 test macros. If the functions might be in libraries other than the
5030 default C library, first call @code{AC_CHECK_LIB} for those libraries.
5031 If you need to check the behavior of a function as well as find out
5032 whether it is present, you have to write your own test for
5033 it (@pxref{Writing Tests}).
5035 @anchor{AC_CHECK_FUNC}
5036 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
5037 @ovar{action-if-not-found})
5038 @acindex{CHECK_FUNC}
5039 If C function @var{function} is available, run shell commands
5040 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
5041 want to define a symbol if the function is available, consider using
5042 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
5043 linkage even when @code{AC_LANG(C++)} has been called, since C is more
5044 standardized than C++. (@pxref{Language Choice}, for more information
5045 about selecting the language for checks.)
5048 @anchor{AC_CHECK_FUNCS}
5049 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
5050 @ovar{action-if-not-found})
5051 @acindex{CHECK_FUNCS}
5052 @cvindex HAVE_@var{function}
5053 For each @var{function} enumerated in the blank-or-newline-separated argument
5054 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5055 If @var{action-if-found} is given, it is additional shell code to
5056 execute when one of the functions is found. You can give it a value of
5057 @samp{break} to break out of the loop on the first match. If
5058 @var{action-if-not-found} is given, it is executed when one of the
5059 functions is not found.
5062 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
5063 @acindex{CHECK_FUNCS_ONCE}
5064 @cvindex HAVE_@var{function}
5065 For each @var{function} enumerated in the blank-or-newline-separated argument
5066 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5067 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
5068 checking code at most once, so that @command{configure} is smaller and
5069 faster; but the checks cannot be conditionalized and are always done once,
5070 early during the @command{configure} run.
5075 Autoconf follows a philosophy that was formed over the years by those
5076 who have struggled for portability: isolate the portability issues in
5077 specific files, and then program as if you were in a Posix
5078 environment. Some functions may be missing or unfixable, and your
5079 package must be ready to replace them.
5081 Suitable replacements for many such problem functions are available from
5082 Gnulib (@pxref{Gnulib}).
5084 @defmac AC_LIBOBJ (@var{function})
5087 Specify that @samp{@var{function}.c} must be included in the executables
5088 to replace a missing or broken implementation of @var{function}.
5090 Technically, it adds @samp{@var{function}.$ac_objext} to the output
5091 variable @code{LIBOBJS} if it is not already in, and calls
5092 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
5093 directly change @code{LIBOBJS}, since this is not traceable.
5096 @defmac AC_LIBSOURCE (@var{file})
5098 Specify that @var{file} might be needed to compile the project. If you
5099 need to know what files might be needed by a @file{configure.ac}, you
5100 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
5102 This macro is called automatically from @code{AC_LIBOBJ}, but you must
5103 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
5104 that case, since shell variables cannot be traced statically, you must
5105 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
5106 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
5107 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
5108 @code{"foo"} or @code{"bar"}, you should do:
5111 AC_LIBSOURCE([foo.c])
5112 AC_LIBSOURCE([bar.c])
5113 AC_LIBOBJ([$foo_or_bar])
5117 There is usually a way to avoid this, however, and you are encouraged to
5118 simply call @code{AC_LIBOBJ} with literal arguments.
5120 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5121 slightly different semantics: the old macro took the function name,
5122 e.g., @code{foo}, as its argument rather than the file name.
5125 @defmac AC_LIBSOURCES (@var{files})
5126 @acindex{LIBSOURCES}
5127 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5128 comma-separated M4 list. Thus, the above example might be rewritten:
5131 AC_LIBSOURCES([foo.c, bar.c])
5132 AC_LIBOBJ([$foo_or_bar])
5136 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5137 @acindex{CONFIG_LIBOBJ_DIR}
5138 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5139 @var{directory}, a name relative to the top level of the
5140 source tree. The replacement directory defaults to @file{.}, the top
5141 level directory, and the most typical value is @file{lib}, corresponding
5142 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5144 @command{configure} might need to know the replacement directory for the
5145 following reasons: (i) some checks use the replacement files, (ii) some
5146 macros bypass broken system headers by installing links to the
5147 replacement headers (iii) when used in conjunction with Automake,
5148 within each makefile, @var{directory} is used as a relative path
5149 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5150 @code{LTLIBOBJS}, etc.
5155 It is common to merely check for the existence of a function, and ask
5156 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5157 a convenient shorthand.
5159 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5160 @acindex{REPLACE_FUNCS}
5161 @cvindex HAVE_@var{function}
5163 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5164 @var{action-if-not-found}. You can declare your replacement function by
5165 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5166 system has the function, it probably declares it in a header file you
5167 should be including, so you shouldn't redeclare it lest your declaration
5172 @section Header Files
5173 @cindex Header, checking
5175 The following macros check for the presence of certain C header files.
5176 If there is no macro specifically defined to check for a header file you need,
5177 and you don't need to check for any special properties of
5178 it, then you can use one of the general header-file check macros.
5181 * Header Portability:: Collected knowledge on common headers
5182 * Particular Headers:: Special handling to find certain headers
5183 * Generic Headers:: How to find other headers
5186 @node Header Portability
5187 @subsection Portability of Headers
5188 @cindex Portability of headers
5189 @cindex Header portability
5191 This section tries to collect knowledge about common headers, and the
5192 problems they cause. By definition, this list always requires
5193 additions. Please help us keeping it as complete as possible.
5197 @item @file{limits.h}
5198 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5199 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5200 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5203 @item @file{inttypes.h} vs.@: @file{stdint.h}
5204 @hdrindex{inttypes.h}
5206 The C99 standard says that @file{inttypes.h} includes
5207 @file{stdint.h}, so there's no need to include @file{stdint.h}
5208 separately in a standard environment. Some implementations have
5209 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5210 know of any implementation that has @file{stdint.h} but not
5213 @item @file{linux/irda.h}
5214 @hdrindex{linux/irda.h}
5215 It requires @file{linux/types.h} and @file{sys/socket.h}.
5217 @item @file{linux/random.h}
5218 @hdrindex{linux/random.h}
5219 It requires @file{linux/types.h}.
5221 @item @file{net/if.h}
5223 On Darwin, this file requires that @file{sys/socket.h} be included
5224 beforehand. One should run:
5227 AC_CHECK_HEADERS([sys/socket.h])
5228 AC_CHECK_HEADERS([net/if.h], [], [],
5231 # include <stdlib.h>
5232 # include <stddef.h>
5234 # ifdef HAVE_STDLIB_H
5235 # include <stdlib.h>
5238 #ifdef HAVE_SYS_SOCKET_H
5239 # include <sys/socket.h>
5244 @item @file{netinet/if_ether.h}
5245 @hdrindex{netinet/if_ether.h}
5246 On Darwin, this file requires that @file{stdio.h} and
5247 @file{sys/socket.h} be included beforehand. One should run:
5250 AC_CHECK_HEADERS([sys/socket.h])
5251 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5254 # include <stdlib.h>
5255 # include <stddef.h>
5257 # ifdef HAVE_STDLIB_H
5258 # include <stdlib.h>
5261 #ifdef HAVE_SYS_SOCKET_H
5262 # include <sys/socket.h>
5267 @item @file{stdint.h}
5268 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5270 @item @file{stdlib.h}
5272 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5274 @item @file{sys/mount.h}
5275 @hdrindex{sys/mount.h}
5276 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5277 @file{sys/params.h} is a prerequisite.
5279 @item @file{sys/ptem.h}
5280 @hdrindex{sys/ptem.h}
5281 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5283 @item @file{sys/socket.h}
5284 @hdrindex{sys/socket.h}
5285 On Darwin, @file{stdlib.h} is a prerequisite.
5287 @item @file{sys/ucred.h}
5288 @hdrindex{sys/ucred.h}
5289 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5291 @item @file{X11/extensions/scrnsaver.h}
5292 @hdrindex{X11/extensions/scrnsaver.h}
5293 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5294 so required that you might not even consider looking for it.
5297 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5298 [[#include <X11/Xlib.h>
5304 @node Particular Headers
5305 @subsection Particular Header Checks
5307 These macros check for particular system header files---whether they
5308 exist, and in some cases whether they declare certain symbols.
5310 @defmac AC_HEADER_ASSERT
5311 @acindex{HEADER_ASSERT}
5314 Check whether to enable assertions in the style of @file{assert.h}.
5315 Assertions are enabled by default, but the user can override this by
5316 invoking @command{configure} with the @option{--disable-assert} option.
5319 @anchor{AC_HEADER_DIRENT}
5320 @defmac AC_HEADER_DIRENT
5321 @acindex{HEADER_DIRENT}
5322 @cvindex HAVE_DIRENT_H
5323 @cvindex HAVE_NDIR_H
5324 @cvindex HAVE_SYS_DIR_H
5325 @cvindex HAVE_SYS_NDIR_H
5327 @hdrindex{sys/ndir.h}
5328 @hdrindex{sys/dir.h}
5330 Check for the following header files. For the first one that is
5331 found and defines @samp{DIR}, define the listed C preprocessor macro:
5333 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5334 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5335 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5336 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5337 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5340 The directory-library declarations in your source code should look
5341 something like the following:
5345 #include <sys/types.h>
5346 #ifdef HAVE_DIRENT_H
5347 # include <dirent.h>
5348 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5350 # define dirent direct
5351 # define NAMLEN(dirent) ((dirent)->d_namlen)
5352 # ifdef HAVE_SYS_NDIR_H
5353 # include <sys/ndir.h>
5355 # ifdef HAVE_SYS_DIR_H
5356 # include <sys/dir.h>
5365 Using the above declarations, the program would declare variables to be
5366 of type @code{struct dirent}, not @code{struct direct}, and would access
5367 the length of a directory entry name by passing a pointer to a
5368 @code{struct dirent} to the @code{NAMLEN} macro.
5370 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5372 This macro is obsolescent, as all current systems with directory
5373 libraries have @code{<dirent.h>}. New programs need not use this macro.
5375 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5376 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5379 @anchor{AC_HEADER_MAJOR}
5380 @defmac AC_HEADER_MAJOR
5381 @acindex{HEADER_MAJOR}
5382 @cvindex MAJOR_IN_MKDEV
5383 @cvindex MAJOR_IN_SYSMACROS
5384 @hdrindex{sys/mkdev.h}
5385 @hdrindex{sys/sysmacros.h}
5386 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5387 @code{makedev}, but @file{sys/mkdev.h} does, define
5388 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5389 @code{MAJOR_IN_SYSMACROS}.
5392 @defmac AC_HEADER_RESOLV
5393 @acindex{HEADER_RESOLV}
5394 @cvindex HAVE_RESOLV_H
5396 Checks for header @file{resolv.h}, checking for prerequisites first.
5397 To properly use @file{resolv.h}, your code should contain something like
5401 #ifdef HAVE_SYS_TYPES_H
5402 # include <sys/types.h>
5404 #ifdef HAVE_NETINET_IN_H
5405 # include <netinet/in.h> /* inet_ functions / structs */
5407 #ifdef HAVE_ARPA_NAMESER_H
5408 # include <arpa/nameser.h> /* DNS HEADER struct */
5417 @anchor{AC_HEADER_STAT}
5418 @defmac AC_HEADER_STAT
5419 @acindex{HEADER_STAT}
5420 @cvindex STAT_MACROS_BROKEN
5421 @hdrindex{sys/stat.h}
5422 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5423 @file{sys/stat.h} do not work properly (returning false positives),
5424 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5425 Amdahl UTS and Motorola System V/88.
5427 This macro is obsolescent, as no current systems have the bug.
5428 New programs need not use this macro.
5431 @defmac AC_HEADER_STDBOOL
5432 @acindex{HEADER_STDBOOL}
5433 @cvindex HAVE_STDBOOL_H
5435 @hdrindex{stdbool.h}
5437 If @file{stdbool.h} exists and conforms to C99, define
5438 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5439 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5440 @file{system.h} could contain the following code:
5443 #ifdef HAVE_STDBOOL_H
5444 # include <stdbool.h>
5450 # define _Bool signed char
5456 # define __bool_true_false_are_defined 1
5460 Alternatively you can use the @samp{stdbool} package of Gnulib
5461 (@pxref{Gnulib}); it packages the above code into a replacement header
5462 and contains a few other bells and whistles.
5466 @anchor{AC_HEADER_STDC}
5467 @defmac AC_HEADER_STDC
5468 @acindex{HEADER_STDC}
5469 @cvindex STDC_HEADERS
5475 Define @code{STDC_HEADERS} if the system has C header files
5476 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5477 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5478 @file{string.h}, and @file{float.h}; if the system has those, it
5479 probably has the rest of the C89 header files. This macro also
5480 checks whether @file{string.h} declares @code{memchr} (and thus
5481 presumably the other @code{mem} functions), whether @file{stdlib.h}
5482 declare @code{free} (and thus presumably @code{malloc} and other related
5483 functions), and whether the @file{ctype.h} macros work on characters
5484 with the high bit set, as the C standard requires.
5486 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5487 determine whether the system has conforming header files (and probably C
5490 This macro is obsolescent, as current systems have conforming header
5491 files. New programs need not use this macro.
5494 @hdrindex{strings.h}
5495 Nowadays @file{string.h} is part of the C standard and declares functions like
5496 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5497 @acronym{BSD} functions like @code{bcopy}; but
5498 historically, string functions were a major sticking point in this area.
5499 If you still want to worry about portability to ancient systems without
5500 standard headers, there is so much variation
5501 that it is probably easier to declare the functions you use than to
5502 figure out exactly what the system header files declare. Some ancient systems
5503 contained a mix of functions from the C standard and from @acronym{BSD};
5504 some were mostly standard but lacked @samp{memmove}; some defined the
5505 @acronym{BSD} functions as macros in @file{string.h} or
5506 @file{strings.h}; some had only the @acronym{BSD} functions but
5507 @file{string.h}; some declared the memory functions in @file{memory.h},
5508 some in @file{string.h}; etc. It is probably sufficient to check for
5509 one string function and one memory function; if the library had the
5510 standard versions of those then it probably had most of the others.
5511 If you put the following in @file{configure.ac}:
5514 # This example is obsolescent.
5515 # Nowadays you can omit these macro calls.
5517 AC_CHECK_FUNCS([strchr memcpy])
5521 then, in your code, you can use declarations like this:
5525 /* This example is obsolescent.
5526 Nowadays you can just #include <string.h>. */
5528 # include <string.h>
5530 # ifndef HAVE_STRCHR
5531 # define strchr index
5532 # define strrchr rindex
5534 char *strchr (), *strrchr ();
5535 # ifndef HAVE_MEMCPY
5536 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5537 # define memmove(d, s, n) bcopy ((s), (d), (n))
5544 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5545 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5546 suffice to port to ancient hosts; you must provide an implementation of
5547 each function. An easy
5548 way to incorporate your implementations only when needed (since the ones
5549 in system C libraries may be hand optimized) is to, taking @code{memchr}
5550 for example, put it in @file{memchr.c} and use
5551 @samp{AC_REPLACE_FUNCS([memchr])}.
5554 @defmac AC_HEADER_SYS_WAIT
5555 @acindex{HEADER_SYS_WAIT}
5556 @cvindex HAVE_SYS_WAIT_H
5557 @hdrindex{sys/wait.h}
5558 If @file{sys/wait.h} exists and is compatible with Posix, define
5559 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5560 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5561 of @code{int} to store a status value. If @file{sys/wait.h} is not
5562 Posix compatible, then instead of including it, define the
5563 Posix macros with their usual interpretations. Here is an
5568 #include <sys/types.h>
5569 #ifdef HAVE_SYS_WAIT_H
5570 # include <sys/wait.h>
5573 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5576 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5582 This macro is obsolescent, as current systems are compatible with Posix.
5583 New programs need not use this macro.
5586 @cvindex _POSIX_VERSION
5588 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5589 Posix systems. If there is no @file{unistd.h}, it is definitely
5590 not a Posix system. However, some non-Posix systems do
5591 have @file{unistd.h}.
5593 The way to check whether the system supports Posix is:
5597 #ifdef HAVE_UNISTD_H
5598 # include <sys/types.h>
5599 # include <unistd.h>
5602 #ifdef _POSIX_VERSION
5603 /* Code for Posix systems. */
5608 @anchor{AC_HEADER_TIME}
5609 @defmac AC_HEADER_TIME
5610 @acindex{HEADER_TIME}
5611 @cvindex TIME_WITH_SYS_TIME
5613 @hdrindex{sys/time.h}
5614 If a program may include both @file{time.h} and @file{sys/time.h},
5615 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5616 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5617 protected against multiple inclusion, so programs could not explicitly
5618 include both files. This macro is useful in programs that use, for
5619 example, @code{struct timeval} as well as
5620 @code{struct tm}. It is best used in conjunction with
5621 @code{HAVE_SYS_TIME_H}, which can be checked for using
5622 @code{AC_CHECK_HEADERS([sys/time.h])}.
5626 #ifdef TIME_WITH_SYS_TIME
5627 # include <sys/time.h>
5630 # ifdef HAVE_SYS_TIME_H
5631 # include <sys/time.h>
5640 This macro is obsolescent, as current systems can include both files
5641 when they exist. New programs need not use this macro.
5645 @defmac AC_HEADER_TIOCGWINSZ
5646 @acindex{HEADER_TIOCGWINSZ}
5647 @cvindex GWINSZ_IN_SYS_IOCTL
5648 @hdrindex{sys/ioctl.h}
5649 @hdrindex{termios.h}
5650 @c FIXME: I need clarifications from Jim.
5651 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5652 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5653 found in @file{<termios.h>}.
5659 #ifdef HAVE_TERMIOS_H
5660 # include <termios.h>
5663 #ifdef GWINSZ_IN_SYS_IOCTL
5664 # include <sys/ioctl.h>
5670 @node Generic Headers
5671 @subsection Generic Header Checks
5673 These macros are used to find system header files not covered by the
5674 ``particular'' test macros. If you need to check the contents of a header
5675 as well as find out whether it is present, you have to write your own
5676 test for it (@pxref{Writing Tests}).
5678 @anchor{AC_CHECK_HEADER}
5679 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
5680 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5681 @acindex{CHECK_HEADER}
5682 If the system header file @var{header-file} is compilable, execute shell
5683 commands @var{action-if-found}, otherwise execute
5684 @var{action-if-not-found}. If you just want to define a symbol if the
5685 header file is available, consider using @code{AC_CHECK_HEADERS}
5688 For compatibility issues with older versions of Autoconf, please read
5692 @anchor{AC_CHECK_HEADERS}
5693 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
5694 @ovar{action-if-found}, @ovar{action-if-not-found}, @
5695 @dvar{includes, default-includes})
5696 @acindex{CHECK_HEADERS}
5697 @cvindex HAVE_@var{header}
5698 For each given system header file @var{header-file} in the
5699 blank-separated argument list that exists, define
5700 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5701 is given, it is additional shell code to execute when one of the header
5702 files is found. You can give it a value of @samp{break} to break out of
5703 the loop on the first match. If @var{action-if-not-found} is given, it
5704 is executed when one of the header files is not found.
5706 For compatibility issues with older versions of Autoconf, please read
5710 Previous versions of Autoconf merely checked whether the header was
5711 accepted by the preprocessor. This was changed because the old test was
5712 inappropriate for typical uses. Headers are typically used to compile,
5713 not merely to preprocess, and the old behavior sometimes accepted
5714 headers that clashed at compile-time. If you need to check whether a
5715 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5716 (@pxref{Running the Preprocessor}).
5718 This scheme, which improves the robustness of the test, also requires
5719 that you make sure that headers that must be included before the
5720 @var{header-file} be part of the @var{includes}, (@pxref{Default
5721 Includes}). If looking for @file{bar.h}, which requires that
5722 @file{foo.h} be included before if it exists, we suggest the following
5726 AC_CHECK_HEADERS([foo.h])
5727 AC_CHECK_HEADERS([bar.h], [], [],
5734 The following variant generates smaller, faster @command{configure}
5735 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5737 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5738 @acindex{CHECK_HEADERS_ONCE}
5739 @cvindex HAVE_@var{header}
5740 For each given system header file @var{header-file} in the
5741 blank-separated argument list that exists, define
5742 @code{HAVE_@var{header-file}} (in all capitals).
5743 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5744 checking code at most once, so that @command{configure} is smaller and
5745 faster; but the checks cannot be conditionalized and are always done once,
5746 early during the @command{configure} run.
5750 @section Declarations
5751 @cindex Declaration, checking
5753 The following macros check for the declaration of variables and
5754 functions. If there is no macro specifically defined to check for a
5755 symbol you need, then you can use the general macros (@pxref{Generic
5756 Declarations}) or, for more complex tests, you may use
5757 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5760 * Particular Declarations:: Macros to check for certain declarations
5761 * Generic Declarations:: How to find other declarations
5764 @node Particular Declarations
5765 @subsection Particular Declaration Checks
5767 There are no specific macros for declarations.
5769 @node Generic Declarations
5770 @subsection Generic Declaration Checks
5772 These macros are used to find declarations not covered by the ``particular''
5775 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
5776 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5777 @acindex{CHECK_DECL}
5778 If @var{symbol} (a function, variable, or constant) is not declared in
5779 @var{includes} and a declaration is needed, run the shell commands
5780 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5781 @var{includes} are specified, the default includes are used
5782 (@pxref{Default Includes}).
5784 This macro actually tests whether @var{symbol} is defined as a macro or
5785 can be used as an r-value, not whether it is really declared, because it
5786 is much safer to avoid
5787 introducing extra declarations when they are not needed.
5790 @anchor{AC_CHECK_DECLS}
5791 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
5792 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5793 @acindex{CHECK_DECLS}
5794 @cvindex HAVE_DECL_@var{symbol}
5795 For each of the @var{symbols} (@emph{comma}-separated list), define
5796 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5797 @var{symbol} is declared, otherwise to @samp{0}. If
5798 @var{action-if-not-found} is given, it is additional shell code to
5799 execute when one of the function declarations is needed, otherwise
5800 @var{action-if-found} is executed.
5802 This macro uses an M4 list as first argument:
5804 AC_CHECK_DECLS([strdup])
5805 AC_CHECK_DECLS([strlen])
5806 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5809 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5810 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5811 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5812 @emph{sure} that the check was performed, use
5813 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5816 #if !HAVE_DECL_SYMBOL
5817 extern char *symbol;
5822 If the test may have not been performed, however, because it is safer
5823 @emph{not} to declare a symbol than to use a declaration that conflicts
5824 with the system's one, you should use:
5827 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5828 void *malloc (size_t *s);
5833 You fall into the second category only in extreme situations: either
5834 your files may be used without being configured, or they are used during
5835 the configuration. In most cases the traditional approach is enough.
5838 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5839 @acindex{CHECK_DECLS_ONCE}
5840 @cvindex HAVE_DECL_@var{symbol}
5841 For each of the @var{symbols} (@emph{comma}-separated list), define
5842 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5843 @var{symbol} is declared in the default include files, otherwise to
5844 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5845 generates the checking code at most once, so that @command{configure} is
5846 smaller and faster; but the checks cannot be conditionalized and are
5847 always done once, early during the @command{configure} run.
5853 @cindex Structure, checking
5855 The following macros check for the presence of certain members in C
5856 structures. If there is no macro specifically defined to check for a
5857 member you need, then you can use the general structure-member macros
5858 (@pxref{Generic Structures}) or, for more complex tests, you may use
5859 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5862 * Particular Structures:: Macros to check for certain structure members
5863 * Generic Structures:: How to find other structure members
5866 @node Particular Structures
5867 @subsection Particular Structure Checks
5869 The following macros check for certain structures or structure members.
5871 @defmac AC_STRUCT_DIRENT_D_INO
5872 @acindex{STRUCT_DIRENT_D_INO}
5873 @cvindex HAVE_STRUCT_DIRENT_D_INO
5874 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5875 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5876 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5878 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5879 @code{d_ino}, not whether its contents are always reliable.
5880 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5881 though current systems hide this detail from the user and never return
5882 zero @code{d_ino} values.
5883 Many current systems report an incorrect @code{d_ino} for a directory
5884 entry that is a mount point.
5887 @defmac AC_STRUCT_DIRENT_D_TYPE
5888 @acindex{STRUCT_DIRENT_D_TYPE}
5889 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5890 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5891 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5892 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5895 @anchor{AC_STRUCT_ST_BLOCKS}
5896 @defmac AC_STRUCT_ST_BLOCKS
5897 @acindex{STRUCT_ST_BLOCKS}
5898 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5899 @cvindex HAVE_ST_BLOCKS
5901 If @code{struct stat} contains an @code{st_blocks} member, define
5902 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5903 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5904 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5908 @defmac AC_STRUCT_TM
5910 @cvindex TM_IN_SYS_TIME
5912 @hdrindex{sys/time.h}
5913 If @file{time.h} does not define @code{struct tm}, define
5914 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5915 had better define @code{struct tm}.
5917 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5918 current systems. New programs need not use this macro.
5921 @anchor{AC_STRUCT_TIMEZONE}
5922 @defmac AC_STRUCT_TIMEZONE
5923 @acindex{STRUCT_TIMEZONE}
5924 @cvindex HAVE_DECL_TZNAME
5925 @cvindex HAVE_STRUCT_TM_TM_ZONE
5926 @cvindex HAVE_TM_ZONE
5927 @cvindex HAVE_TZNAME
5928 Figure out how to get the current timezone. If @code{struct tm} has a
5929 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5930 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5931 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5932 define @code{HAVE_DECL_TZNAME}.
5935 @node Generic Structures
5936 @subsection Generic Structure Checks
5938 These macros are used to find structure members not covered by the
5939 ``particular'' test macros.
5941 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @
5942 @ovar{action-if-found}, @ovar{action-if-not-found}, @
5943 @dvar{includes, default-includes})
5944 @acindex{CHECK_MEMBER}
5945 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5946 If no @var{includes} are specified, the default includes are used
5947 (@pxref{Default Includes}).
5950 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5951 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5955 You can use this macro for submembers:
5958 AC_CHECK_MEMBER(struct top.middle.bot)
5962 @anchor{AC_CHECK_MEMBERS}
5963 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
5964 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5965 @acindex{CHECK_MEMBERS}
5966 @cvindex HAVE_@var{aggregate}_@var{member}
5967 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5968 @var{members} using the previous macro. When @var{member} belongs to
5969 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5970 capitals, with spaces and dots replaced by underscores). If
5971 @var{action-if-found} is given, it is executed for each of the found
5972 members. If @var{action-if-not-found} is given, it is executed for each
5973 of the members that could not be found.
5975 This macro uses M4 lists:
5977 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5987 The following macros check for C types, either builtin or typedefs. If
5988 there is no macro specifically defined to check for a type you need, and
5989 you don't need to check for any special properties of it, then you can
5990 use a general type-check macro.
5993 * Particular Types:: Special handling to find certain types
5994 * Generic Types:: How to find other types
5997 @node Particular Types
5998 @subsection Particular Type Checks
6000 @hdrindex{sys/types.h}
6003 @hdrindex{inttypes.h}
6004 These macros check for particular C types in @file{sys/types.h},
6005 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
6008 The Gnulib @code{stdint} module is an alternate way to define many of
6009 these symbols; it is useful if you prefer your code to assume a
6010 C99-or-better environment. @xref{Gnulib}.
6012 @anchor{AC_TYPE_GETGROUPS}
6013 @defmac AC_TYPE_GETGROUPS
6014 @acindex{TYPE_GETGROUPS}
6015 @cvindex GETGROUPS_T
6016 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
6017 is the base type of the array argument to @code{getgroups}.
6020 @defmac AC_TYPE_INT8_T
6021 @acindex{TYPE_INT8_T}
6022 @cvindex HAVE_INT8_T
6024 If @file{stdint.h} or @file{inttypes.h} does not define the type
6025 @code{int8_t}, define @code{int8_t} to a signed
6026 integer type that is exactly 8 bits wide and that uses two's complement
6027 representation, if such a type exists.
6028 If you are worried about porting to hosts that lack such a type, you can
6029 use the results of this macro in C89-or-later code as follows:
6033 # include <stdint.h>
6035 #if defined INT8_MAX || defined int8_t
6036 @emph{code using int8_t}
6038 @emph{complicated alternative using >8-bit 'signed char'}
6043 @defmac AC_TYPE_INT16_T
6044 @acindex{TYPE_INT16_T}
6045 @cvindex HAVE_INT16_T
6047 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
6050 @defmac AC_TYPE_INT32_T
6051 @acindex{TYPE_INT32_T}
6052 @cvindex HAVE_INT32_T
6054 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
6057 @defmac AC_TYPE_INT64_T
6058 @acindex{TYPE_INT64_T}
6059 @cvindex HAVE_INT64_T
6061 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
6064 @defmac AC_TYPE_INTMAX_T
6065 @acindex{TYPE_INTMAX_T}
6066 @cvindex HAVE_INTMAX_T
6068 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
6069 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
6070 widest signed integer type.
6073 @defmac AC_TYPE_INTPTR_T
6074 @acindex{TYPE_INTPTR_T}
6075 @cvindex HAVE_INTPTR_T
6077 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
6078 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
6079 signed integer type wide enough to hold a pointer, if such a type
6083 @defmac AC_TYPE_LONG_DOUBLE
6084 @acindex{TYPE_LONG_DOUBLE}
6085 @cvindex HAVE_LONG_DOUBLE
6086 If the C compiler supports a working @code{long double} type, define
6087 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
6088 same range and precision as @code{double}.
6090 This macro is obsolescent, as current C compilers support @code{long
6091 double}. New programs need not use this macro.
6094 @defmac AC_TYPE_LONG_DOUBLE_WIDER
6095 @acindex{TYPE_LONG_DOUBLE_WIDER}
6096 @cvindex HAVE_LONG_DOUBLE_WIDER
6097 If the C compiler supports a working @code{long double} type with more
6098 range or precision than the @code{double} type, define
6099 @code{HAVE_LONG_DOUBLE_WIDER}.
6102 @defmac AC_TYPE_LONG_LONG_INT
6103 @acindex{TYPE_LONG_LONG_INT}
6104 @cvindex HAVE_LONG_LONG_INT
6105 If the C compiler supports a working @code{long long int} type, define
6106 @code{HAVE_LONG_LONG_INT}.
6109 @defmac AC_TYPE_MBSTATE_T
6110 @acindex{TYPE_MBSTATE_T}
6113 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
6114 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
6115 @code{<wchar.h>} does not declare it.
6118 @anchor{AC_TYPE_MODE_T}
6119 @defmac AC_TYPE_MODE_T
6120 @acindex{TYPE_MODE_T}
6122 Define @code{mode_t} to a suitable type, if standard headers do not
6126 @anchor{AC_TYPE_OFF_T}
6127 @defmac AC_TYPE_OFF_T
6128 @acindex{TYPE_OFF_T}
6130 Define @code{off_t} to a suitable type, if standard headers do not
6134 @anchor{AC_TYPE_PID_T}
6135 @defmac AC_TYPE_PID_T
6136 @acindex{TYPE_PID_T}
6138 Define @code{pid_t} to a suitable type, if standard headers do not
6142 @anchor{AC_TYPE_SIGNAL}
6143 @defmac AC_TYPE_SIGNAL
6144 @acindex{TYPE_SIGNAL}
6147 If @file{signal.h} declares @code{signal} as returning a pointer to a
6148 function returning @code{void}, define @code{RETSIGTYPE} to be
6149 @code{void}; otherwise, define it to be @code{int}.
6151 Define signal handlers as returning type @code{RETSIGTYPE}:
6164 @anchor{AC_TYPE_SIZE_T}
6165 @defmac AC_TYPE_SIZE_T
6166 @acindex{TYPE_SIZE_T}
6168 Define @code{size_t} to a suitable type, if standard headers do not
6172 @defmac AC_TYPE_SSIZE_T
6173 @acindex{TYPE_SSIZE_T}
6175 Define @code{ssize_t} to a suitable type, if standard headers do not
6179 @anchor{AC_TYPE_UID_T}
6180 @defmac AC_TYPE_UID_T
6181 @acindex{TYPE_UID_T}
6184 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6185 headers do not define them.
6188 @defmac AC_TYPE_UINT8_T
6189 @acindex{TYPE_UINT8_T}
6190 @cvindex HAVE_UINT8_T
6192 If @file{stdint.h} or @file{inttypes.h} does not define the type
6193 @code{uint8_t}, define @code{uint8_t} to an
6194 unsigned integer type that is exactly 8 bits wide, if such a type
6196 This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
6199 @defmac AC_TYPE_UINT16_T
6200 @acindex{TYPE_UINT16_T}
6201 @cvindex HAVE_UINT16_T
6203 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
6206 @defmac AC_TYPE_UINT32_T
6207 @acindex{TYPE_UINT32_T}
6208 @cvindex HAVE_UINT32_T
6210 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
6213 @defmac AC_TYPE_UINT64_T
6214 @acindex{TYPE_UINT64_T}
6215 @cvindex HAVE_UINT64_T
6217 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
6220 @defmac AC_TYPE_UINTMAX_T
6221 @acindex{TYPE_UINTMAX_T}
6222 @cvindex HAVE_UINTMAX_T
6224 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6225 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6226 widest unsigned integer type.
6229 @defmac AC_TYPE_UINTPTR_T
6230 @acindex{TYPE_UINTPTR_T}
6231 @cvindex HAVE_UINTPTR_T
6233 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6234 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6235 unsigned integer type wide enough to hold a pointer, if such a type
6239 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6240 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6241 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6242 If the C compiler supports a working @code{unsigned long long int} type,
6243 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6247 @subsection Generic Type Checks
6249 These macros are used to check for types not covered by the ``particular''
6252 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
6253 @ovar{action-if-not-found}, @dvar{includes, default-includes})
6254 @acindex{CHECK_TYPE}
6255 Check whether @var{type} is defined. It may be a compiler builtin type
6256 or defined by the @var{includes} (@pxref{Default Includes}).
6258 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
6259 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
6260 same test is applied when compiling for C++, which means that in C++
6261 @var{type} should be a type-id and should not be an anonymous
6262 @samp{struct} or @samp{union}.
6266 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
6267 @ovar{action-if-not-found}, @dvar{includes, default-includes})
6268 @acindex{CHECK_TYPES}
6269 @cvindex HAVE_@var{type}
6270 For each @var{type} of the @var{types} that is defined, define
6271 @code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
6272 the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
6273 specified, the default includes are used (@pxref{Default Includes}). If
6274 @var{action-if-found} is given, it is additional shell code to execute
6275 when one of the types is found. If @var{action-if-not-found} is given,
6276 it is executed when one of the types is not found.
6278 This macro uses M4 lists:
6280 AC_CHECK_TYPES([ptrdiff_t])
6281 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6286 Autoconf, up to 2.13, used to provide to another version of
6287 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6288 compatibility, a simple heuristic, quite safe but not totally, is
6289 implemented. In case of doubt, read the documentation of the former
6290 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6293 @node Compilers and Preprocessors
6294 @section Compilers and Preprocessors
6296 @cindex Preprocessors
6299 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6300 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6301 the output of the compiler, typically to the empty string if
6302 Posix and @samp{.exe} if a @acronym{DOS} variant.
6305 They also define the output variable @code{OBJEXT} based on the
6306 output of the compiler, after @file{.c} files have been excluded, typically
6307 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6309 If the compiler being used does not produce executables, the tests fail. If
6310 the executables can't be run, and cross-compilation is not enabled, they
6311 fail too. @xref{Manual Configuration}, for more on support for cross
6315 * Specific Compiler Characteristics:: Some portability issues
6316 * Generic Compiler Characteristics:: Language independent tests and features
6317 * C Compiler:: Checking its characteristics
6318 * C++ Compiler:: Likewise
6319 * Objective C Compiler:: Likewise
6320 * Erlang Compiler and Interpreter:: Likewise
6321 * Fortran Compiler:: Likewise
6324 @node Specific Compiler Characteristics
6325 @subsection Specific Compiler Characteristics
6327 Some compilers exhibit different behaviors.
6330 @item Static/Dynamic Expressions
6331 Autoconf relies on a trick to extract one bit of information from the C
6332 compiler: using negative array sizes. For instance the following
6333 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6337 static int test_array[sizeof (int) == 4 ? 1 : -1];
6341 To our knowledge, there is a single compiler that does not support this
6342 trick: the @acronym{HP} C compilers (the real ones, not only the
6343 ``bundled'') on @acronym{HP-UX} 11.00.
6344 They incorrectly reject the above program with the diagnostic
6345 ``Variable-length arrays cannot have static storage.''
6346 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6347 not from the @code{? 1 : -1}, and
6348 Autoconf works around this problem by casting @code{sizeof (int)} to
6349 @code{long int} before comparing it.
6352 @node Generic Compiler Characteristics
6353 @subsection Generic Compiler Characteristics
6355 @anchor{AC_CHECK_SIZEOF}
6356 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
6357 @dvar{includes, default-includes})
6358 @acindex{CHECK_SIZEOF}
6359 @cvindex SIZEOF_@var{type-or-expr}
6360 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
6361 the size in bytes of @var{type-or-expr}, which may be either a type or
6362 an expression returning a value that has a size. If the expression
6363 @samp{sizeof (@var{type-or-expr})} is invalid, the result is 0. If no
6364 @var{includes} are specified, the default includes are used
6365 (@pxref{Default Includes}).
6367 This macro now works even when cross-compiling. The @var{unused}
6368 argument was used when cross-compiling.
6370 For example, the call
6373 AC_CHECK_SIZEOF([int *])
6377 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6380 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6381 @acindex{CHECK_ALIGNOF}
6382 @cvindex ALIGNOF_@var{type}
6383 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6384 alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
6385 a structure member declaration. If @samp{type} is unknown, the result
6386 is 0. If no @var{includes} are specified, the default includes are used
6387 (@pxref{Default Includes}).
6390 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
6391 @dvar{includes, default-includes}, @ovar{action-if-fails})
6392 @acindex{COMPUTE_INT}
6393 Store into the shell variable @var{var} the value of the integer
6394 @var{expression}. The
6395 value should fit in an initializer in a C variable of type @code{signed
6396 long}. To support cross compilation (in which case, the macro only works on
6397 hosts that use twos-complement arithmetic), it should be possible to evaluate
6398 the expression at compile-time. If no @var{includes} are specified, the
6399 default includes are used (@pxref{Default Includes}).
6401 Execute @var{action-if-fails} if the value cannot be determined correctly.
6404 @defmac AC_LANG_WERROR
6405 @acindex{LANG_WERROR}
6406 Normally Autoconf ignores warnings generated by the compiler, linker, and
6407 preprocessor. If this macro is used, warnings count as fatal
6408 errors for the current language. This macro is useful when the
6409 results of configuration are used where warnings are unacceptable; for
6410 instance, if parts of a program are built with the @acronym{GCC}
6412 option. If the whole program is built using @option{-Werror} it is
6413 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6420 @ovindex OPENMP_CFLAGS
6421 @ovindex OPENMP_CXXFLAGS
6422 @ovindex OPENMP_FFLAGS
6423 @ovindex OPENMP_FCFLAGS
6424 OpenMP (@url{http://www.openmp.org/}) specifies extensions of C, C++,
6425 and Fortran that simplify optimization of shared memory parallelism,
6426 which is a common problem on multicore CPUs.
6428 If the current language is C, the macro @code{AC_OPENMP} sets the
6429 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
6430 supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
6431 compiler already supports OpenMP, if it has no way to activate OpenMP
6432 support, or if the user rejects OpenMP support by invoking
6433 @samp{configure} with the @samp{--disable-openmp} option.
6435 @code{OPENMP_CFLAGS} needs to be used when compiling programs, when
6436 preprocessing program source, and when linking programs. Therefore you
6437 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
6438 that use OpenMP@. If you preprocess OpenMP-specific C code, you also
6439 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
6440 OpenMP support is revealed at compile time by the preprocessor macro
6443 Linking a program with @code{OPENMP_CFLAGS} typically adds one more
6444 shared library to the program's dependencies, so its use is recommended
6445 only on programs that actually require OpenMP.
6447 If the current language is C++, @code{AC_OPENMP} sets the variable
6448 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
6451 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
6452 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
6453 respectively. Similar remarks as for C hold, except that
6454 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
6455 signals OpenMP support.
6459 @subsection C Compiler Characteristics
6461 The following macros provide ways to find and exercise a C Compiler.
6462 There are a few constructs that ought to be avoided, but do not deserve
6463 being checked for, since they can easily be worked around.
6466 @item Don't use lines containing solitary backslashes
6467 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6468 @acronym{HP-UX} 10.20,
6469 11.00, and 11i). When given the following source:
6474 * A comment with backslash-newlines in it. %@{ %@} *\
6478 " A string with backslash-newlines in it %@{ %@} \\
6480 char apostrophe = '\\
6488 the compiler incorrectly fails with the diagnostics ``Non-terminating
6489 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6490 Removing the lines with solitary backslashes solves the problem.
6492 @item Don't compile several files at once if output matters to you
6493 Some compilers, such as @acronym{HP}'s, report names of files being
6494 compiled when given more than one file operand. For instance:
6503 This can cause problems if you observe the output of the compiler to
6504 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6505 b.o} solves the issue.
6507 @item Don't rely on @code{#error} failing
6508 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6509 simply emits a diagnostic and continues, exiting successfully. So,
6510 instead of an error directive like @code{#error "Unsupported word size"}
6511 it is more portable to use an invalid directive like @code{#Unsupported
6512 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6513 OK, since installers with inadequate compilers like @sc{irix} can simply
6514 examine these compilers' diagnostic output.
6516 @item Don't rely on correct @code{#line} support
6517 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6518 diagnoses @code{#line} directives whose line
6519 numbers are greater than 32767. Nothing in Posix
6520 makes this invalid. That is why Autoconf stopped issuing
6521 @code{#line} directives.
6524 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6528 Determine a C compiler to use. If @code{CC} is not already set in the
6529 environment, check for @code{gcc} and @code{cc}, then for other C
6530 compilers. Set output variable @code{CC} to the name of the compiler
6533 This macro may, however, be invoked with an optional first argument
6534 which, if specified, must be a blank-separated list of C compilers to
6535 search for. This just gives the user an opportunity to specify an
6536 alternative search list for the C compiler. For example, if you didn't
6537 like the default order, then you could invoke @code{AC_PROG_CC} like
6541 AC_PROG_CC([gcc cl cc])
6544 If the C compiler does not handle function prototypes correctly by
6545 default, try to add an option to output variable @code{CC} to make it
6546 so. This macro tries various options that select standard-conformance
6547 modes on various systems.
6549 After calling this macro you can check whether the C compiler has been
6550 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6552 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6553 @code{AC_C_PROTOTYPES} below.
6555 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6556 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6557 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6558 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6562 @anchor{AC_PROG_CC_C_O}
6563 @defmac AC_PROG_CC_C_O
6564 @acindex{PROG_CC_C_O}
6565 @cvindex NO_MINUS_C_MINUS_O
6566 If the C compiler does not accept the @option{-c} and @option{-o} options
6567 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6568 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6569 the first @code{cc} in the path. The test fails if one fails. This
6570 macro was created for @acronym{GNU} Make to choose the default C compilation
6578 Set output variable @code{CPP} to a command that runs the
6579 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6580 It is only portable to run @code{CPP} on files with a @file{.c}
6583 Some preprocessors don't indicate missing include files by the error
6584 status. For such preprocessors an internal variable is set that causes
6585 other macros to check the standard error from the preprocessor and
6586 consider the test failed if any warnings have been reported.
6587 For most preprocessors, though, warnings do not cause include-file
6588 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6591 @defmac AC_PROG_CPP_WERROR
6592 @acindex{PROG_CPP_WERROR}
6594 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6595 preprocessor as errors even if the preprocessor exit status indicates
6596 success. This is useful for avoiding headers that generate mandatory
6597 warnings, such as deprecation notices.
6601 The following macros check for C compiler or machine architecture
6602 features. To check for characteristics not listed here, use
6603 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6604 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6606 @defmac AC_PROG_CC_STDC
6607 @acindex{PROG_CC_STDC}
6608 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6609 C99), try to add an option to output variable @code{CC} to make it work.
6610 If the compiler does not support C99, fall back to supporting
6611 @acronym{ANSI} C89 (@acronym{ISO} C90).
6613 After calling this macro you can check whether the C compiler has been
6614 set to accept Standard C; if not, the shell variable
6615 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6618 @defmac AC_PROG_CC_C89
6619 @acindex{PROG_CC_C89}
6620 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6621 default, try to add an option to output variable @code{CC} to make it
6622 so. This macro tries various options that select @acronym{ANSI} C89 on
6623 some system or another. It considers the compiler to be in
6624 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6626 After calling this macro you can check whether the C compiler has been
6627 set to accept @acronym{ANSI} C89; if not, the shell variable
6628 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6630 This macro is called automatically by @code{AC_PROG_CC}.
6633 @defmac AC_PROG_CC_C99
6634 @acindex{PROG_CC_C99}
6635 If the C compiler is not in C99 mode by default, try to add an
6636 option to output variable @code{CC} to make it so. This macro tries
6637 various options that select C99 on some system or another. It
6638 considers the compiler to be in C99 mode if it handles @code{_Bool},
6639 @code{//} comments, flexible array members, @code{inline}, signed and
6640 unsigned @code{long long int}, mixed code and declarations, named
6641 initialization of structs,
6642 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6643 in @code{for} loops, and variable length arrays.
6645 After calling this macro you can check whether the C compiler has been
6646 set to accept C99; if not, the shell variable
6647 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6650 @defmac AC_C_BACKSLASH_A
6651 @acindex{C_BACKSLASH_A}
6652 @cvindex HAVE_C_BACKSLASH_A
6653 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6656 This macro is obsolescent, as current C compilers understand @samp{\a}.
6657 New programs need not use this macro.
6660 @anchor{AC_C_BIGENDIAN}
6661 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
6662 @ovar{action-if-unknown}, @ovar{action-if-universal})
6663 @acindex{C_BIGENDIAN}
6664 @cvindex WORDS_BIGENDIAN
6666 If words are stored with the most significant byte first (like Motorola
6667 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6668 the least significant byte first (like Intel and VAX CPUs), execute
6669 @var{action-if-false}.
6671 This macro runs a test-case if endianness cannot be determined from the
6672 system header files. When cross-compiling, the test-case is not run but
6673 grep'ed for some magic values. @var{action-if-unknown} is executed if
6674 the latter case fails to determine the byte sex of the host system.
6676 In some cases a single run of a compiler can generate code for multiple
6677 architectures. This can happen, for example, when generating Mac OS X
6678 universal binary files, which work on both PowerPC and Intel
6679 architectures. In this case, the different variants might be for
6680 different architectures whose endiannesses differ. If
6681 @command{configure} detects this, it executes @var{action-if-universal}
6682 instead of @var{action-if-unknown}.
6684 The default for @var{action-if-true} is to define
6685 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6686 nothing. The default for @var{action-if-unknown} is to
6687 abort configure and tell the installer how to bypass this test.
6688 And finally, the default for @var{action-if-universal} is to define
6689 @samp{WORDS_BIGENDIAN} or not, depending on the architecture that the
6690 code is being generated for.
6692 If you use this macro without specifying @var{action-if-universal}, you
6693 should also use @code{AC_CONFIG_HEADERS}; otherwise
6694 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
6702 If the C compiler does not fully support the @code{const} keyword,
6703 define @code{const} to be empty. Some C compilers that do
6704 not define @code{__STDC__} do support @code{const}; some compilers that
6705 define @code{__STDC__} do not completely support @code{const}. Programs
6706 can simply use @code{const} as if every C compiler supported it; for
6707 those that don't, the makefile or configuration header file
6708 defines it as empty.
6710 Occasionally installers use a C++ compiler to compile C code, typically
6711 because they lack a C compiler. This causes problems with @code{const},
6712 because C and C++ treat @code{const} differently. For example:
6719 is valid in C but not in C++. These differences unfortunately cannot be
6720 papered over by defining @code{const} to be empty.
6722 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6723 as this generally yields better results in practice. However, using a
6724 C++ compiler to compile C code is not recommended or supported, and
6725 installers who run into trouble in this area should get a C compiler
6726 like @acronym{GCC} to compile their C code.
6728 This macro is obsolescent, as current C compilers support @code{const}.
6729 New programs need not use this macro.
6732 @defmac AC_C_RESTRICT
6733 @acindex{C_RESTRICT}
6735 If the C compiler recognizes a variant spelling for the @code{restrict}
6736 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
6737 then define @code{restrict} to that; this is more likely to do the right
6738 thing with compilers that support language variants where plain
6739 @code{restrict} is not a keyword. Otherwise, if the C compiler
6740 recognizes the @code{restrict} keyword, don't do anything.
6741 Otherwise, define @code{restrict} to be empty.
6742 Thus, programs may simply use @code{restrict} as if every C compiler
6743 supported it; for those that do not, the makefile
6744 or configuration header defines it away.
6746 Although support in C++ for the @code{restrict} keyword is not
6747 required, several C++ compilers do accept the keyword.
6748 This macro works for them, too.
6751 @defmac AC_C_VOLATILE
6752 @acindex{C_VOLATILE}
6754 If the C compiler does not understand the keyword @code{volatile},
6755 define @code{volatile} to be empty. Programs can simply use
6756 @code{volatile} as if every C compiler supported it; for those that do
6757 not, the makefile or configuration header defines it as
6760 If the correctness of your program depends on the semantics of
6761 @code{volatile}, simply defining it to be empty does, in a sense, break
6762 your code. However, given that the compiler does not support
6763 @code{volatile}, you are at its mercy anyway. At least your
6764 program compiles, when it wouldn't before.
6765 @xref{Volatile Objects}, for more about @code{volatile}.
6767 In general, the @code{volatile} keyword is a standard C feature, so
6768 you might expect that @code{volatile} is available only when
6769 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6770 support volatile, but does not define @code{__STDC__}.
6772 This macro is obsolescent, as current C compilers support @code{volatile}.
6773 New programs need not use this macro.
6776 @anchor{AC_C_INLINE}
6780 If the C compiler supports the keyword @code{inline}, do nothing.
6781 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6782 if it accepts one of those, otherwise define @code{inline} to be empty.
6785 @anchor{AC_C_CHAR_UNSIGNED}
6786 @defmac AC_C_CHAR_UNSIGNED
6787 @acindex{C_CHAR_UNSIGNED}
6788 @cvindex __CHAR_UNSIGNED__
6789 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6790 unless the C compiler predefines it.
6793 @defmac AC_C_STRINGIZE
6794 @acindex{C_STRINGIZE}
6795 @cvindex HAVE_STRINGIZE
6796 If the C preprocessor supports the stringizing operator, define
6797 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6798 found in macros such as this:
6804 This macro is obsolescent, as current C compilers support the
6805 stringizing operator. New programs need not use this macro.
6808 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6809 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6810 @cvindex FLEXIBLE_ARRAY_MEMBER
6811 If the C compiler supports flexible array members, define
6812 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6813 That way, a declaration like this:
6819 double val[FLEXIBLE_ARRAY_MEMBER];
6824 will let applications use the ``struct hack'' even with compilers that
6825 do not support flexible array members. To allocate and use such an
6826 object, you can use code like this:
6830 size_t n = compute_value_count ();
6832 malloc (offsetof (struct s, val)
6833 + n * sizeof (double));
6835 for (i = 0; i < n; i++)
6836 p->val[i] = compute_value (i);
6840 @defmac AC_C_VARARRAYS
6841 @acindex{C_VARARRAYS}
6842 @cvindex HAVE_C_VARARRAYS
6843 If the C compiler supports variable-length arrays, define
6844 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
6845 storage duration whose length is determined at run time, when the array
6851 @cvindex HAVE_TYPEOF
6853 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6855 through a different spelling of the keyword (e.g., @code{__typeof__}),
6856 define @code{HAVE_TYPEOF}. If the support is available only through a
6857 different spelling, define @code{typeof} to that spelling.
6860 @defmac AC_C_PROTOTYPES
6861 @acindex{C_PROTOTYPES}
6863 @cvindex __PROTOTYPES
6865 If function prototypes are understood by the compiler (as determined by
6866 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6867 Defining @code{__PROTOTYPES} is for the benefit of
6868 header files that cannot use macros that infringe on user name space.
6870 This macro is obsolescent, as current C compilers support prototypes.
6871 New programs need not use this macro.
6874 @anchor{AC_PROG_GCC_TRADITIONAL}
6875 @defmac AC_PROG_GCC_TRADITIONAL
6876 @acindex{PROG_GCC_TRADITIONAL}
6878 Add @option{-traditional} to output variable @code{CC} if using the
6879 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6880 @option{-traditional}. That usually happens when the fixed header files
6881 have not been installed on an old system.
6883 This macro is obsolescent, since current versions of the @acronym{GNU} C
6884 compiler fix the header files automatically when installed.
6889 @subsection C++ Compiler Characteristics
6892 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6896 Determine a C++ compiler to use. Check whether the environment variable
6897 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6898 variable @code{CXX} to its value.
6900 Otherwise, if the macro is invoked without an argument, then search for
6901 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6902 then other names). If none of those checks succeed, then as a last
6903 resort set @code{CXX} to @code{g++}.
6905 This macro may, however, be invoked with an optional first argument
6906 which, if specified, must be a blank-separated list of C++ compilers to
6907 search for. This just gives the user an opportunity to specify an
6908 alternative search list for the C++ compiler. For example, if you
6909 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6913 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6916 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6917 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6918 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6919 systems where G++ does not accept @option{-g}), or @option{-g} for other
6923 @defmac AC_PROG_CXXCPP
6924 @acindex{PROG_CXXCPP}
6926 Set output variable @code{CXXCPP} to a command that runs the C++
6927 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6928 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6929 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6931 Some preprocessors don't indicate missing include files by the error
6932 status. For such preprocessors an internal variable is set that causes
6933 other macros to check the standard error from the preprocessor and
6934 consider the test failed if any warnings have been reported. However,
6935 it is not known whether such broken preprocessors exist for C++.
6938 @defmac AC_PROG_CXX_C_O
6939 @acindex{PROG_CXX_C_O}
6940 @cvindex CXX_NO_MINUS_C_MINUS_O
6941 Test whether the C++ compiler accepts the options @option{-c} and
6942 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6947 @node Objective C Compiler
6948 @subsection Objective C Compiler Characteristics
6951 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6955 Determine an Objective C compiler to use. If @code{OBJC} is not already
6956 set in the environment, check for Objective C compilers. Set output
6957 variable @code{OBJC} to the name of the compiler found.
6959 This macro may, however, be invoked with an optional first argument
6960 which, if specified, must be a blank-separated list of Objective C compilers to
6961 search for. This just gives the user an opportunity to specify an
6962 alternative search list for the Objective C compiler. For example, if you
6963 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6967 AC_PROG_OBJC([gcc objcc objc])
6970 If using the @acronym{GNU} Objective C compiler, set shell variable
6971 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6972 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6973 compiler (@option{-O2} on systems where @command{gcc} does not accept
6974 @option{-g}), or @option{-g} for other compilers.
6977 @defmac AC_PROG_OBJCPP
6978 @acindex{PROG_OBJCPP}
6980 Set output variable @code{OBJCPP} to a command that runs the Objective C
6981 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6985 @node Erlang Compiler and Interpreter
6986 @subsection Erlang Compiler and Interpreter Characteristics
6989 Autoconf defines the following macros for determining paths to the essential
6990 Erlang/OTP programs:
6992 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
6993 @acindex{ERLANG_PATH_ERLC}
6996 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6997 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6998 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6999 is not set in the environment, set it to an empty value.
7001 The two optional arguments have the same meaning as the two last arguments of
7002 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
7003 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
7007 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
7011 @defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
7012 @acindex{ERLANG_NEED_ERLC}
7013 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
7014 error message and exits the @command{configure} script if the @command{erlc}
7015 program is not found.
7018 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
7019 @acindex{ERLANG_PATH_ERL}
7021 Determine an Erlang interpreter to use. If @code{ERL} is not already
7023 environment, check for @command{erl}. Set output variable @code{ERL} to the
7024 complete path of the interpreter command found.
7026 The two optional arguments have the same meaning as the two last arguments of
7027 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
7028 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
7032 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
7036 @defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
7037 @acindex{ERLANG_NEED_ERL}
7038 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
7039 error message and exits the @command{configure} script if the @command{erl}
7040 program is not found.
7044 @node Fortran Compiler
7045 @subsection Fortran Compiler Characteristics
7049 The Autoconf Fortran support is divided into two categories: legacy
7050 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
7051 The former are intended for traditional Fortran 77 code, and have output
7052 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
7053 are for newer programs that can (or must) compile under the newer
7054 Fortran standards, and have output variables like @code{FC},
7055 @code{FCFLAGS}, and @code{FCLIBS}.
7057 Except for two new macros @code{AC_FC_SRCEXT} and
7058 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
7059 behave almost identically, and so they are documented together in this
7063 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
7067 Determine a Fortran 77 compiler to use. If @code{F77} is not already
7068 set in the environment, then check for @code{g77} and @code{f77}, and
7069 then some other names. Set the output variable @code{F77} to the name
7070 of the compiler found.
7072 This macro may, however, be invoked with an optional first argument
7073 which, if specified, must be a blank-separated list of Fortran 77
7074 compilers to search for. This just gives the user an opportunity to
7075 specify an alternative search list for the Fortran 77 compiler. For
7076 example, if you didn't like the default order, then you could invoke
7077 @code{AC_PROG_F77} like this:
7080 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
7083 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
7084 set the shell variable @code{G77} to @samp{yes}.
7085 If the output variable @code{FFLAGS} was not already set in the
7086 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
7087 where @code{g77} does not accept @option{-g}). Otherwise, set
7088 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
7091 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
7095 Determine a Fortran compiler to use. If @code{FC} is not already set in
7096 the environment, then @code{dialect} is a hint to indicate what Fortran
7097 dialect to search for; the default is to search for the newest available
7098 dialect. Set the output variable @code{FC} to the name of the compiler
7101 By default, newer dialects are preferred over older dialects, but if
7102 @code{dialect} is specified then older dialects are preferred starting
7103 with the specified dialect. @code{dialect} can currently be one of
7104 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
7105 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
7106 and no attempt is made to guarantee that a particular language standard
7107 is actually supported. Thus, it is preferable that you avoid the
7108 @code{dialect} option, and use AC_PROG_FC only for code compatible with
7109 the latest Fortran standard.
7111 This macro may, alternatively, be invoked with an optional first argument
7112 which, if specified, must be a blank-separated list of Fortran
7113 compilers to search for, just as in @code{AC_PROG_F77}.
7115 If the output variable @code{FCFLAGS} was not already set in the
7116 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
7117 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
7118 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
7121 @defmac AC_PROG_F77_C_O
7122 @defmacx AC_PROG_FC_C_O
7123 @acindex{PROG_F77_C_O}
7124 @acindex{PROG_FC_C_O}
7125 @cvindex F77_NO_MINUS_C_MINUS_O
7126 @cvindex FC_NO_MINUS_C_MINUS_O
7127 Test whether the Fortran compiler accepts the options @option{-c} and
7128 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
7129 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
7132 The following macros check for Fortran compiler characteristics.
7133 To check for characteristics not listed here, use
7134 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
7135 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
7136 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
7137 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
7140 @defmac AC_F77_LIBRARY_LDFLAGS
7141 @defmacx AC_FC_LIBRARY_LDFLAGS
7142 @acindex{F77_LIBRARY_LDFLAGS}
7144 @acindex{FC_LIBRARY_LDFLAGS}
7146 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
7147 @dfn{Fortran intrinsic and runtime libraries} that are required to
7148 successfully link a Fortran program or shared library. The output
7149 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
7150 should be included after @code{LIBS} when linking).
7152 This macro is intended to be used in those situations when it is
7153 necessary to mix, e.g., C++ and Fortran source code in a single
7154 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
7155 automake, @acronym{GNU} Automake}).
7157 For example, if object files from a C++ and Fortran compiler must be
7158 linked together, then the C++ compiler/linker must be used for linking
7159 (since special C++-ish things need to happen at link time like calling
7160 global constructors, instantiating templates, enabling exception
7163 However, the Fortran intrinsic and runtime libraries must be linked in
7164 as well, but the C++ compiler/linker doesn't know by default how to add
7165 these Fortran 77 libraries. Hence, this macro was created to determine
7166 these Fortran libraries.
7168 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7169 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
7170 link C/C++ with Fortran; see below.
7173 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7174 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7175 @acindex{F77_DUMMY_MAIN}
7176 @cvindex F77_DUMMY_MAIN
7177 With many compilers, the Fortran libraries detected by
7178 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
7179 their own @code{main} entry function that initializes things like
7180 Fortran I/O, and which then calls a user-provided entry function named
7181 (say) @code{MAIN__} to run the user's program. The
7182 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7183 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
7186 When using Fortran for purely numerical functions (no I/O, etc.)@: often
7187 one prefers to provide one's own @code{main} and skip the Fortran
7188 library initializations. In this case, however, one may still need to
7189 provide a dummy @code{MAIN__} routine in order to prevent linking errors
7190 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
7191 detects whether any such routine is @emph{required} for linking, and
7192 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
7193 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
7194 was found, and @code{none} when no such dummy main is needed.
7196 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
7197 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
7198 @emph{if} it is required. @var{action-if-not-found} defaults to
7199 exiting with an error.
7201 In order to link with Fortran routines, the user's C/C++ program should
7202 then include the following code to define the dummy main if it is
7206 #ifdef F77_DUMMY_MAIN
7210 int F77_DUMMY_MAIN() @{ return 1; @}
7214 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7216 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7217 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7218 explicitly unless one wants to change the default actions.
7227 As discussed above, many Fortran libraries allow you to provide an entry
7228 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7229 is then called by a @code{main} function in the Fortran libraries that
7230 initializes things like Fortran I/O@. The
7231 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7232 @emph{possible} to utilize such an alternate main function, and defines
7233 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7234 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7235 simply defined to @code{main}.)
7237 Thus, when calling Fortran routines from C that perform things like I/O,
7238 one should use this macro and declare the "main" function like so:
7244 int F77_MAIN(int argc, char *argv[]);
7247 (Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7250 @defmac AC_F77_WRAPPERS
7251 @defmacx AC_FC_WRAPPERS
7252 @acindex{F77_WRAPPERS}
7255 @acindex{FC_WRAPPERS}
7258 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7259 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7260 mangle the names of C/C++ identifiers, and identifiers with underscores,
7261 respectively, so that they match the name-mangling scheme used by the
7264 Fortran is case-insensitive, and in order to achieve this the Fortran
7265 compiler converts all identifiers into a canonical case and format. To
7266 call a Fortran subroutine from C or to write a C function that is
7267 callable from Fortran, the C program must explicitly use identifiers in
7268 the format expected by the Fortran compiler. In order to do this, one
7269 simply wraps all C identifiers in one of the macros provided by
7270 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7271 you have the following Fortran 77 subroutine:
7274 subroutine foobar (x, y)
7275 double precision x, y
7281 You would then declare its prototype in C or C++ as:
7284 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7286 extern "C" /* prevent C++ name mangling */
7288 void FOOBAR_F77(double *x, double *y);
7291 Note that we pass both the lowercase and uppercase versions of the
7292 function name to @code{F77_FUNC} so that it can select the right one.
7293 Note also that all parameters to Fortran 77 routines are passed as
7294 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7297 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7299 Although Autoconf tries to be intelligent about detecting the
7300 name-mangling scheme of the Fortran compiler, there may be Fortran
7301 compilers that it doesn't support yet. In this case, the above code
7302 generates a compile-time error, but some other behavior
7303 (e.g., disabling Fortran-related features) can be induced by checking
7304 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7306 Now, to call that routine from a C program, we would do something like:
7310 double x = 2.7183, y;
7311 FOOBAR_F77 (&x, &y);
7315 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7316 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7317 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7318 because some Fortran compilers mangle names differently if they contain
7322 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7323 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7326 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7327 hold the mangled version @var{name} according to the rules of the
7328 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7329 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7330 supplied, the shell variable is simply @var{name}. The purpose of
7331 this macro is to give the caller a way to access the name-mangling
7332 information other than through the C preprocessor as above, for example,
7333 to call Fortran routines from some language other than C/C++.
7336 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
7337 @ovar{action-if-failure})
7339 By default, the @code{FC} macros perform their tests using a @file{.f}
7340 extension for source-code files. Some compilers, however, only enable
7341 newer language features for appropriately named files, e.g., Fortran 90
7342 features only for @file{.f90} files. On the other hand, some other
7343 compilers expect all source files to end in @file{.f} and require
7344 special flags to support other file name extensions. The
7345 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7347 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7348 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7349 contain the dot). If any special compiler flags are needed for this, it
7350 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7351 extension and these flags are then used for all subsequent @code{FC} tests
7352 (until @code{AC_FC_SRCEXT} is called again).
7354 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7355 @file{.f90} extension in future tests, and it would set a
7356 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7357 to compile such files.
7359 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7360 @code{FCFLAGS}, for two reasons based on the limitations of some
7361 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7362 time, so files with different extensions must be compiled separately.
7363 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7364 the source-code file name when compiling. So, continuing the example
7365 above, you might compile a @file{foo.f90} file in your makefile with the
7370 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7373 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7374 extension, it calls @var{action-if-success} (defaults to nothing). If
7375 it fails, and cannot find a way to make the @code{FC} compiler accept such
7376 files, it calls @var{action-if-failure} (defaults to exiting with an
7381 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7382 @acindex{FC_FREEFORM}
7384 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7385 (@code{$FC}) allows free-format source code (as opposed to the older
7386 fixed-format style from Fortran 77). If necessary, it may add some
7387 additional flags to @code{FCFLAGS}.
7389 This macro is most important if you are using the default @file{.f}
7390 extension, since many compilers interpret this extension as indicating
7391 fixed-format source unless an additional flag is supplied. If you
7392 specify a different extension with @code{AC_FC_SRCEXT}, such as
7393 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7394 succeeds without modifying @code{FCFLAGS}.
7396 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7397 calls @var{action-if-success} (defaults to nothing). If it fails, it
7398 calls @var{action-if-failure} (defaults to exiting with an error
7402 @node System Services
7403 @section System Services
7405 The following macros check for operating system services or capabilities.
7411 @cindex X Window System
7412 Try to locate the X Window System include files and libraries. If the
7413 user gave the command line options @option{--x-includes=@var{dir}} and
7414 @option{--x-libraries=@var{dir}}, use those directories.
7416 If either or both were not given, get the missing values by running
7417 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7418 environment variable) on a trivial @file{Imakefile} and examining the
7419 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7420 disables this method.
7422 If this method fails to find the X Window System, @command{configure}
7423 looks for the files in several directories where they often reside.
7424 If either method is successful, set the shell variables
7425 @code{x_includes} and @code{x_libraries} to their locations, unless they
7426 are in directories the compiler searches by default.
7428 If both methods fail, or the user gave the command line option
7429 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7430 otherwise set it to the empty string.
7433 @anchor{AC_PATH_XTRA}
7434 @defmac AC_PATH_XTRA
7438 @ovindex X_EXTRA_LIBS
7440 @cvindex X_DISPLAY_MISSING
7441 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7442 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7443 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7446 This macro also checks for special libraries that some systems need in
7447 order to compile X programs. It adds any that the system needs to
7448 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7449 libraries that need to be linked with before @option{-lX11}, and adds
7450 any found to the output variable @code{X_PRE_LIBS}.
7452 @c This is an incomplete kludge. Make a real way to do it.
7453 @c If you need to check for other X functions or libraries yourself, then
7454 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7455 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7458 @anchor{AC_SYS_INTERPRETER}
7459 @defmac AC_SYS_INTERPRETER
7460 @acindex{SYS_INTERPRETER}
7461 Check whether the system supports starting scripts with a line of the
7462 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7463 After running this macro, shell code in @file{configure.ac} can check
7464 the shell variable @code{interpval}; it is set to @samp{yes}
7465 if the system supports @samp{#!}, @samp{no} if not.
7468 @defmac AC_SYS_LARGEFILE
7469 @acindex{SYS_LARGEFILE}
7470 @cvindex _FILE_OFFSET_BITS
7471 @cvindex _LARGE_FILES
7473 @cindex Large file support
7476 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7477 large-file support}. On some hosts, one must use special compiler
7478 options to build programs that can access large files. Append any such
7479 options to the output variable @code{CC}. Define
7480 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7482 Large-file support can be disabled by configuring with the
7483 @option{--disable-largefile} option.
7485 If you use this macro, check that your program works even when
7486 @code{off_t} is wider than @code{long int}, since this is common when
7487 large-file support is enabled. For example, it is not correct to print
7488 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7491 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7492 replace their C counterparts @code{fseek} and @code{ftell} that do not
7493 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7494 prototypes available when using them and large-file support is
7498 @anchor{AC_SYS_LONG_FILE_NAMES}
7499 @defmac AC_SYS_LONG_FILE_NAMES
7500 @acindex{SYS_LONG_FILE_NAMES}
7501 @cvindex HAVE_LONG_FILE_NAMES
7502 If the system supports file names longer than 14 characters, define
7503 @code{HAVE_LONG_FILE_NAMES}.
7506 @defmac AC_SYS_POSIX_TERMIOS
7507 @acindex{SYS_POSIX_TERMIOS}
7508 @cindex Posix termios headers
7509 @cindex termios Posix headers
7510 Check to see if the Posix termios headers and functions are available on the
7511 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7512 @samp{yes}. If not, set the variable to @samp{no}.
7515 @node Posix Variants
7516 @section Posix Variants
7518 The following macro makes it possible to use features of Posix that are
7519 extensions to C, as well as platform extensions not defined by Posix.
7521 @anchor{AC_USE_SYSTEM_EXTENSIONS}
7522 @defmac AC_USE_SYSTEM_EXTENSIONS
7523 @acindex{USE_SYSTEM_EXTENSIONS}
7524 @cvindex _ALL_SOURCE
7525 @cvindex _GNU_SOURCE
7527 @cvindex _POSIX_1_SOURCE
7528 @cvindex _POSIX_PTHREAD_SEMANTICS
7529 @cvindex _POSIX_SOURCE
7530 @cvindex _TANDEM_SOURCE
7531 @cvindex __EXTENSIONS__
7532 This macro was introduced in Autoconf 2.60. If possible, enable
7533 extensions to C or Posix on hosts that normally disable the extensions,
7534 typically due to standards-conformance namespace issues. This should be
7535 called before any macros that run the C compiler. The following
7536 preprocessor macros are defined where appropriate:
7540 Enable extensions on @acronym{GNU}/Linux.
7541 @item __EXTENSIONS__
7542 Enable general extensions on Solaris.
7543 @item _POSIX_PTHREAD_SEMANTICS
7544 Enable threading extensions on Solaris.
7545 @item _TANDEM_SOURCE
7546 Enable extensions for the @acronym{HP} NonStop platform.
7548 Enable extensions for @acronym{AIX} 3, and for Interix.
7550 Enable Posix functions for Minix.
7551 @item _POSIX_1_SOURCE
7552 Enable additional Posix functions for Minix.
7554 Identify Minix platform. This particular preprocessor macro is
7555 obsolescent, and may be removed in a future release of Autoconf.
7560 @node Erlang Libraries
7561 @section Erlang Libraries
7562 @cindex Erlang, Library, checking
7564 The following macros check for an installation of Erlang/OTP, and for the
7565 presence of certain Erlang libraries. All those macros require the
7566 configuration of an Erlang interpreter and an Erlang compiler
7567 (@pxref{Erlang Compiler and Interpreter}).
7569 @defmac AC_ERLANG_SUBST_ROOT_DIR
7570 @acindex{ERLANG_SUBST_ROOT_DIR}
7571 @ovindex ERLANG_ROOT_DIR
7573 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
7574 directory in which Erlang/OTP is installed (as returned by Erlang's
7575 @code{code:root_dir/0} function). The result of this test is cached if
7576 caching is enabled when running @command{configure}.
7579 @defmac AC_ERLANG_SUBST_LIB_DIR
7580 @acindex{ERLANG_SUBST_LIB_DIR}
7581 @ovindex ERLANG_LIB_DIR
7583 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7584 directory of Erlang/OTP (as returned by Erlang's
7585 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7586 Erlang/OTP library. The result of this test is cached if caching is enabled
7587 when running @command{configure}.
7590 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
7591 @ovar{action-if-not-found})
7592 @acindex{ERLANG_CHECK_LIB}
7593 @ovindex ERLANG_LIB_DIR_@var{library}
7594 @ovindex ERLANG_LIB_VER_@var{library}
7596 Test whether the Erlang/OTP library @var{library} is installed by
7597 calling Erlang's @code{code:lib_dir/1} function. The result of this
7598 test is cached if caching is enabled when running @command{configure}.
7599 @var{action-if-found} is a list of shell commands to run if the library
7600 is installed; @var{action-if-not-found} is a list of shell commands to
7601 run if it is not. Additionally, if the library is installed, the output
7602 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7603 library installation directory, and the output variable
7604 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7605 part of the subdirectory name, if it is in the standard form
7606 (@code{@var{library}-@var{version}}). If the directory name does not
7607 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7608 empty string. If the library is not installed,
7609 @samp{ERLANG_LIB_DIR_@var{library}} and
7610 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
7611 example, to check if library @code{stdlib} is installed:
7614 AC_ERLANG_CHECK_LIB([stdlib],
7615 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7616 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7617 [AC_MSG_ERROR([stdlib was not found!])])
7621 In addition to the above macros, which test installed Erlang libraries, the
7622 following macros determine the paths to the directories into which newly built
7623 Erlang libraries are to be installed:
7625 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7626 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7627 @ovindex ERLANG_INSTALL_LIB_DIR
7629 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7630 which every built Erlang library should be installed in a separate
7632 If this variable is not set in the environment when @command{configure} runs,
7633 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7634 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7637 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7638 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7639 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7641 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7642 directory into which the built Erlang library @var{library} version
7643 @var{version} should be installed. If this variable is not set in the
7644 environment when @command{configure} runs, its default value is
7645 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7646 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7647 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7654 @c ========================================================= Writing Tests
7657 @chapter Writing Tests
7659 If the existing feature tests don't do something you need, you have to
7660 write new ones. These macros are the building blocks. They provide
7661 ways for other macros to check whether various kinds of features are
7662 available and report the results.
7664 This chapter contains some suggestions and some of the reasons why the
7665 existing tests are written the way they are. You can also learn a lot
7666 about how to write Autoconf tests by looking at the existing ones. If
7667 something goes wrong in one or more of the Autoconf tests, this
7668 information can help you understand the assumptions behind them, which
7669 might help you figure out how to best solve the problem.
7671 These macros check the output of the compiler system of the current
7672 language (@pxref{Language Choice}). They do not cache the results of
7673 their tests for future use (@pxref{Caching Results}), because they don't
7674 know enough about the information they are checking for to generate a
7675 cache variable name. They also do not print any messages, for the same
7676 reason. The checks for particular kinds of features call these macros
7677 and do cache their results and print messages about what they're
7680 When you write a feature test that could be applicable to more than one
7681 software package, the best thing to do is encapsulate it in a new macro.
7682 @xref{Writing Autoconf Macros}, for how to do that.
7685 * Language Choice:: Selecting which language to use for testing
7686 * Writing Test Programs:: Forging source files for compilers
7687 * Running the Preprocessor:: Detecting preprocessor symbols
7688 * Running the Compiler:: Detecting language or header features
7689 * Running the Linker:: Detecting library features
7690 * Runtime:: Testing for runtime features
7691 * Systemology:: A zoology of operating systems
7692 * Multiple Cases:: Tests for several possible values
7695 @node Language Choice
7696 @section Language Choice
7699 Autoconf-generated @command{configure} scripts check for the C compiler and
7700 its features by default. Packages that use other programming languages
7701 (maybe more than one, e.g., C and C++) need to test features of the
7702 compilers for the respective languages. The following macros determine
7703 which programming language is used in the subsequent tests in
7704 @file{configure.ac}.
7707 @defmac AC_LANG (@var{language})
7708 Do compilation tests using the compiler, preprocessor, and file
7709 extensions for the specified @var{language}.
7711 Supported languages are:
7715 Do compilation tests using @code{CC} and @code{CPP} and use extension
7716 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7717 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7720 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7721 extension @file{.C} for test programs. Use compilation flags:
7722 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
7723 @code{CXXFLAGS} with @code{CXX}.
7726 Do compilation tests using @code{F77} and use extension @file{.f} for
7727 test programs. Use compilation flags: @code{FFLAGS}.
7730 Do compilation tests using @code{FC} and use extension @file{.f} (or
7731 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7732 compilation flags: @code{FCFLAGS}.
7738 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7739 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7742 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
7743 extension @file{.m} for test programs. Use compilation flags:
7744 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7745 @code{OBJCFLAGS} with @code{OBJC}.
7749 @anchor{AC_LANG_PUSH}
7750 @defmac AC_LANG_PUSH (@var{language})
7752 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7753 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7754 in macros that need to temporarily switch to a particular language.
7757 @defmac AC_LANG_POP (@ovar{language})
7759 Select the language that is saved on the top of the stack, as set by
7760 @code{AC_LANG_PUSH}, and remove it from the stack.
7762 If given, @var{language} specifies the language we just @emph{quit}. It
7763 is a good idea to specify it when it's known (which should be the
7764 case@dots{}), since Autoconf detects inconsistencies.
7767 AC_LANG_PUSH([Fortran 77])
7768 # Perform some tests on Fortran 77.
7770 AC_LANG_POP([Fortran 77])
7774 @defmac AC_LANG_ASSERT (@var{language})
7775 @acindex{LANG_ASSERT} Check statically that the current language is
7776 @var{language}. You should use this in your language specific macros
7777 to avoid that they be called with an inappropriate language.
7779 This macro runs only at @command{autoconf} time, and incurs no cost at
7780 @command{configure} time. Sadly enough and because Autoconf is a two
7781 layer language @footnote{Because M4 is not aware of Sh code,
7782 especially conditionals, some optimizations that look nice statically
7783 may produce incorrect results at runtime.}, the macros
7784 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7785 therefore as much as possible you ought to avoid using them to wrap
7786 your code, rather, require from the user to run the macro with a
7787 correct current language, and check it with @code{AC_LANG_ASSERT}.
7788 And anyway, that may help the user understand she is running a Fortran
7789 macro while expecting a result about her Fortran 77 compiler@dots{}
7793 @defmac AC_REQUIRE_CPP
7794 @acindex{REQUIRE_CPP}
7795 Ensure that whichever preprocessor would currently be used for tests has
7796 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7797 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7798 depending on which language is current.
7802 @node Writing Test Programs
7803 @section Writing Test Programs
7805 Autoconf tests follow a common scheme: feed some program with some
7806 input, and most of the time, feed a compiler with some source file.
7807 This section is dedicated to these source samples.
7810 * Guidelines:: General rules for writing test programs
7811 * Test Functions:: Avoiding pitfalls in test programs
7812 * Generating Sources:: Source program boilerplate
7816 @subsection Guidelines for Test Programs
7818 The most important rule to follow when writing testing samples is:
7820 @center @emph{Look for realism.}
7822 This motto means that testing samples must be written with the same
7823 strictness as real programs are written. In particular, you should
7824 avoid ``shortcuts'' and simplifications.
7826 Don't just play with the preprocessor if you want to prepare a
7827 compilation. For instance, using @command{cpp} to check whether a header is
7828 functional might let your @command{configure} accept a header which
7829 causes some @emph{compiler} error. Do not hesitate to check a header with
7830 other headers included before, especially required headers.
7832 Make sure the symbols you use are properly defined, i.e., refrain for
7833 simply declaring a function yourself instead of including the proper
7836 Test programs should not write to standard output. They
7837 should exit with status 0 if the test succeeds, and with status 1
7838 otherwise, so that success
7839 can be distinguished easily from a core dump or other failure;
7840 segmentation violations and other failures produce a nonzero exit
7841 status. Unless you arrange for @code{exit} to be declared, test
7842 programs should @code{return}, not @code{exit}, from @code{main},
7843 because on many systems @code{exit} is not declared by default.
7845 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7846 preprocessor macros defined by tests that have already run. For
7847 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7848 @file{configure.ac} you can have a test program that includes
7849 @file{stdbool.h} conditionally:
7853 #ifdef HAVE_STDBOOL_H
7854 # include <stdbool.h>
7859 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7860 work with any standard C compiler. Some developers prefer @code{#if}
7861 because it is easier to read, while others prefer @code{#ifdef} because
7862 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7863 @option{-Wundef} option.
7865 If a test program needs to use or create a data file, give it a name
7866 that starts with @file{conftest}, such as @file{conftest.data}. The
7867 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7868 after running test programs and if the script is interrupted.
7870 @node Test Functions
7871 @subsection Test Functions
7873 These days it's safe to assume support for function prototypes
7874 (introduced in C89).
7876 Functions that test programs declare should also be conditionalized for
7877 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7878 include any header files containing clashing prototypes.
7884 void *valloc (size_t);
7887 If a test program calls a function with invalid parameters (just to see
7888 whether it exists), organize the program to ensure that it never invokes
7889 that function. You can do this by calling it in another function that is
7890 never invoked. You can't do it by putting it after a call to
7891 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7893 and optimizes out any code that follows it in the same block.
7895 If you include any header files, be sure to call the functions
7896 relevant to them with the correct number of arguments, even if they are
7897 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7899 has internal prototypes for several functions that it automatically
7900 inlines; for example, @code{memcpy}. To avoid errors when checking for
7901 them, either pass them the correct number of arguments or redeclare them
7902 with a different return type (such as @code{char}).
7905 @node Generating Sources
7906 @subsection Generating Sources
7908 Autoconf provides a set of macros that can be used to generate test
7909 source files. They are written to be language generic, i.e., they
7910 actually depend on the current language (@pxref{Language Choice}) to
7911 ``format'' the output properly.
7914 @defmac AC_LANG_CONFTEST (@var{source})
7915 @acindex{LANG_CONFTEST}
7916 Save the @var{source} text in the current test source file:
7917 @file{conftest.@var{extension}} where the @var{extension} depends on the
7920 Note that the @var{source} is evaluated exactly once, like regular
7921 Autoconf macro arguments, and therefore (i) you may pass a macro
7922 invocation, (ii) if not, be sure to double quote if needed.
7925 @defmac AC_LANG_SOURCE (@var{source})
7926 @acindex{LANG_SOURCE}
7927 Expands into the @var{source}, with the definition of
7928 all the @code{AC_DEFINE} performed so far.
7931 For instance executing (observe the double quotation!):
7934 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7935 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7936 [Greetings string.])
7939 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7940 gcc -E -dD -o - conftest.c
7950 #define PACKAGE_NAME "Hello"
7951 #define PACKAGE_TARNAME "hello"
7952 #define PACKAGE_VERSION "1.0"
7953 #define PACKAGE_STRING "Hello 1.0"
7954 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7955 #define HELLO_WORLD "Hello, World\n"
7957 const char hw[] = "Hello, World\n";
7960 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7961 are not automatically translated into constants in the source code by this
7964 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7965 @acindex{LANG_PROGRAM}
7966 Expands into a source file which consists of the @var{prologue}, and
7967 then @var{body} as body of the main function (e.g., @code{main} in
7968 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7975 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7976 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7977 [Greetings string.])
7979 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7980 [[fputs (hw, stdout);]])])
7981 gcc -E -dD -o - conftest.c
7991 #define PACKAGE_NAME "Hello"
7992 #define PACKAGE_TARNAME "hello"
7993 #define PACKAGE_VERSION "1.0"
7994 #define PACKAGE_STRING "Hello 1.0"
7995 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7996 #define HELLO_WORLD "Hello, World\n"
7998 const char hw[] = "Hello, World\n";
8008 In Erlang tests, the created source file is that of an Erlang module called
8009 @code{conftest} (@file{conftest.erl}). This module defines and exports
8011 one @code{start/0} function, which is called to perform the test. The
8012 @var{prologue} is optional code that is inserted between the module header and
8013 the @code{start/0} function definition. @var{body} is the body of the
8014 @code{start/0} function without the final period (@pxref{Runtime}, about
8015 constraints on this function's behavior).
8020 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8023 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
8024 [[io:format("~s~n", [?HELLO_WORLD])]])])
8034 -define(HELLO_WORLD, "Hello, world!").
8036 io:format("~s~n", [?HELLO_WORLD])
8040 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
8042 Expands into a source file which consists of the @var{prologue}, and
8043 then a call to the @var{function} as body of the main function (e.g.,
8044 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
8045 of the latter are available.
8047 This function will probably be replaced in the future by a version
8048 which would enable specifying the arguments. The use of this macro is
8049 not encouraged, as it violates strongly the typing system.
8051 This macro cannot be used for Erlang tests.
8054 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
8055 @acindex{LANG_FUNC_LINK_TRY}
8056 Expands into a source file which uses the @var{function} in the body of
8057 the main function (e.g., @code{main} in C). Since it uses
8058 @code{AC_LANG_PROGRAM}, the features of the latter are available.
8060 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
8061 It is considered to be severely broken, and in the future will be
8062 removed in favor of actual function calls (with properly typed
8065 This macro cannot be used for Erlang tests.
8068 @node Running the Preprocessor
8069 @section Running the Preprocessor
8071 Sometimes one might need to run the preprocessor on some source file.
8072 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
8073 your project, not merely run the preprocessor on it; therefore you
8074 certainly want to run the compiler, not the preprocessor. Resist the
8075 temptation of following the easiest path.
8077 Nevertheless, if you need to run the preprocessor, then use
8078 @code{AC_PREPROC_IFELSE}.
8080 The macros described in this section cannot be used for tests in Erlang or
8081 Fortran, since those languages require no preprocessor.
8083 @anchor{AC_PREPROC_IFELSE}
8084 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @
8085 @ovar{action-if-false})
8086 @acindex{PREPROC_IFELSE}
8087 Run the preprocessor of the current language (@pxref{Language Choice})
8088 on the @var{input}, run the shell commands @var{action-if-true} on
8089 success, @var{action-if-false} otherwise. The @var{input} can be made
8090 by @code{AC_LANG_PROGRAM} and friends.
8092 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
8093 @option{-g}, @option{-O}, etc.@: are not valid options to many C
8096 It is customary to report unexpected failures with
8097 @code{AC_MSG_FAILURE}.
8103 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8104 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
8105 [Greetings string.])
8107 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
8108 [[fputs (hw, stdout);]])],
8109 [AC_MSG_RESULT([OK])],
8110 [AC_MSG_FAILURE([unexpected preprocessor failure])])
8117 checking for gcc... gcc
8118 checking for C compiler default output file name... a.out
8119 checking whether the C compiler works... yes
8120 checking whether we are cross compiling... no
8121 checking for suffix of executables...
8122 checking for suffix of object files... o
8123 checking whether we are using the GNU C compiler... yes
8124 checking whether gcc accepts -g... yes
8125 checking for gcc option to accept ISO C89... none needed
8126 checking how to run the C preprocessor... gcc -E
8132 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
8133 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
8134 it impossible to use it to elaborate sources. You are encouraged to
8135 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
8136 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
8137 to run the @emph{preprocessor} and not the compiler?
8139 @anchor{AC_EGREP_HEADER}
8140 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @
8141 @var{action-if-found}, @ovar{action-if-not-found})
8142 @acindex{EGREP_HEADER}
8143 If the output of running the preprocessor on the system header file
8144 @var{header-file} matches the extended regular expression
8145 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
8146 execute @var{action-if-not-found}.
8149 @anchor{AC_EGREP_CPP}
8150 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @
8151 @ovar{action-if-found}, @ovar{action-if-not-found})
8153 @var{program} is the text of a C or C++ program, on which shell
8154 variable, back quote, and backslash substitutions are performed. If the
8155 output of running the preprocessor on @var{program} matches the
8156 extended regular expression @var{pattern}, execute shell commands
8157 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
8162 @node Running the Compiler
8163 @section Running the Compiler
8165 To check for a syntax feature of the current language's (@pxref{Language
8166 Choice}) compiler, such as whether it recognizes a certain keyword, or
8167 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
8168 to compile a small program that uses that feature.
8170 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @
8171 @ovar{action-if-false})
8172 @acindex{COMPILE_IFELSE}
8173 Run the compiler and compilation flags of the current language
8174 (@pxref{Language Choice}) on the @var{input}, run the shell commands
8175 @var{action-if-true} on success, @var{action-if-false} otherwise. The
8176 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8178 It is customary to report unexpected failures with
8179 @code{AC_MSG_FAILURE}. This macro does not try to link; use
8180 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
8185 For tests in Erlang, the @var{input} must be the source code of a module named
8186 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
8187 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
8188 recommended to use @code{AC_LANG_PROGRAM} to specify the test program,
8189 to ensure that the Erlang module has the right name.
8191 @node Running the Linker
8192 @section Running the Linker
8194 To check for a library, a function, or a global variable, Autoconf
8195 @command{configure} scripts try to compile and link a small program that
8196 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
8197 @code{ar} on the C library to try to figure out which functions are
8198 available. Trying to link with the function is usually a more reliable
8199 approach because it avoids dealing with the variations in the options
8200 and output formats of @code{nm} and @code{ar} and in the location of the
8201 standard libraries. It also allows configuring for cross-compilation or
8202 checking a function's runtime behavior if needed. On the other hand,
8203 it can be slower than scanning the libraries once, but accuracy is more
8204 important than speed.
8206 @code{AC_LINK_IFELSE} is used to compile test programs to test for
8207 functions and global variables. It is also used by @code{AC_CHECK_LIB}
8208 to check for libraries (@pxref{Libraries}), by adding the library being
8209 checked for to @code{LIBS} temporarily and trying to link a small
8212 @anchor{AC_LINK_IFELSE}
8213 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @
8214 @ovar{action-if-false})
8215 @acindex{LINK_IFELSE}
8216 Run the compiler (and compilation flags) and the linker of the current
8217 language (@pxref{Language Choice}) on the @var{input}, run the shell
8218 commands @var{action-if-true} on success, @var{action-if-false}
8219 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
8222 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8223 current compilation flags.
8225 It is customary to report unexpected failures with
8226 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
8227 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8230 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8231 programs are interpreted and do not require linking.
8236 @section Checking Runtime Behavior
8238 Sometimes you need to find out how a system performs at runtime, such
8239 as whether a given function has a certain capability or bug. If you
8240 can, make such checks when your program runs instead of when it is
8241 configured. You can check for things like the machine's endianness when
8242 your program initializes itself.
8244 If you really need to test for a runtime behavior while configuring,
8245 you can write a test program to determine the result, and compile and
8246 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
8247 possible, because this prevents people from configuring your package for
8250 @anchor{AC_RUN_IFELSE}
8251 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @
8252 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8253 @acindex{RUN_IFELSE}
8254 If @var{program} compiles and links successfully and returns an exit
8255 status of 0 when executed, run shell commands @var{action-if-true}.
8256 Otherwise, run shell commands @var{action-if-false}.
8258 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8259 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8260 compilation flags of the current language (@pxref{Language Choice}).
8262 If the compiler being used does not produce executables that run on the
8263 system where @command{configure} is being run, then the test program is
8264 not run. If the optional shell commands @var{action-if-cross-compiling}
8265 are given, they are run instead. Otherwise, @command{configure} prints
8266 an error message and exits.
8268 In the @var{action-if-false} section, the failing exit status is
8269 available in the shell variable @samp{$?}. This exit status might be
8270 that of a failed compilation, or it might be that of a failed program
8273 It is customary to report unexpected failures with
8274 @code{AC_MSG_FAILURE}.
8277 Try to provide a pessimistic default value to use when cross-compiling
8278 makes runtime tests impossible. You do this by passing the optional
8279 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
8280 warning message when creating @command{configure} each time it
8281 encounters a call to @code{AC_RUN_IFELSE} with no
8282 @var{action-if-cross-compiling} argument given. You may ignore the
8283 warning, though users cannot configure your package for
8284 cross-compiling. A few of the macros distributed with Autoconf produce
8285 this warning message.
8287 To configure for cross-compiling you can also choose a value for those
8288 parameters based on the canonical system name (@pxref{Manual
8289 Configuration}). Alternatively, set up a test results cache file with
8290 the correct values for the host system (@pxref{Caching Results}).
8292 @ovindex cross_compiling
8293 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8294 in other macros, including a few of the ones that come with Autoconf,
8295 you can test whether the shell variable @code{cross_compiling} is set to
8296 @samp{yes}, and then use an alternate method to get the results instead
8297 of calling the macros.
8299 A C or C++ runtime test should be portable.
8300 @xref{Portable C and C++}.
8302 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8303 function: the given status code is used to determine the success of the test
8304 (status is @code{0}) or its failure (status is different than @code{0}), as
8305 explained above. It must be noted that data output through the standard output
8306 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8307 Therefore, if a test must output configuration information, it is recommended
8308 to create and to output data into the temporary file named @file{conftest.out},
8309 using the functions of module @code{file}. The @code{conftest.out} file is
8310 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8311 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR}
8315 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8319 [AC_LANG_PROGRAM([], [dnl
8320 file:write_file("conftest.out", code:lib_dir()),
8322 [echo "code:lib_dir() returned: `cat conftest.out`"],
8323 [AC_MSG_FAILURE([test Erlang program execution failed])])
8328 @section Systemology
8331 This section aims at presenting some systems and pointers to
8332 documentation. It may help you addressing particular problems reported
8335 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8336 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8339 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8340 contains a table correlating the features of various Posix-conforming
8341 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8342 simplified diagram of how many Unix systems were derived from each
8345 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8346 provides some variants of traditional implementations of Unix utilities.
8351 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8352 case-preserving, but case insensitive. This can cause nasty problems,
8353 since for instance the installation attempt for a package having an
8354 @file{INSTALL} file can result in @samp{make install} report that
8355 nothing was to be done!
8357 That's all dependent on whether the file system is a UFS (case
8358 sensitive) or HFS+ (case preserving). By default Apple wants you to
8359 install the OS on HFS+. Unfortunately, there are some pieces of
8360 software which really need to be built on UFS@. We may want to rebuild
8361 Darwin to have both UFS and HFS+ available (and put the /local/build
8364 @item @acronym{QNX} 4.25
8365 @cindex @acronym{QNX} 4.25
8366 @c FIXME: Please, if you feel like writing something more precise,
8367 @c it'd be great. In particular, I can't understand the difference with
8369 @acronym{QNX} is a realtime operating system running on Intel architecture
8370 meant to be scalable from the small embedded systems to the hundred
8371 processor super-computer. It claims to be Posix certified. More
8372 information is available on the
8373 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8377 @uref{http://h30097.www3.hp.com/@/docs/,
8378 Documentation of several versions of Tru64} is available in different
8381 @item Unix version 7
8382 @cindex Unix version 7
8384 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8385 time-sharing system'' but we use the more-common name ``Unix version 7''.
8386 Documentation is available in the
8387 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8388 Previous versions of Unix are called ``Unix version 6'', etc., but
8389 they were not as widely used.
8393 @node Multiple Cases
8394 @section Multiple Cases
8396 Some operations are accomplished in several possible ways, depending on
8397 the OS variant. Checking for them essentially requires a ``case
8398 statement''. Autoconf does not directly provide one; however, it is
8399 easy to simulate by using a shell variable to keep track of whether a
8400 way to perform the operation has been found yet.
8402 Here is an example that uses the shell variable @code{fstype} to keep
8403 track of whether the remaining cases need to be checked.
8407 AC_MSG_CHECKING([how to get file system type])
8409 # The order of these tests is important.
8410 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8411 #include <sys/fstyp.h>]])],
8412 [AC_DEFINE([FSTYPE_STATVFS], [1],
8413 [Define if statvfs exists.])
8415 if test $fstype = no; then
8416 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8417 #include <sys/fstyp.h>]])],
8418 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8419 [Define if USG statfs.])
8422 if test $fstype = no; then
8423 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8424 #include <sys/vmount.h>]])]),
8425 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8426 [Define if AIX statfs.])
8429 # (more cases omitted here)
8430 AC_MSG_RESULT([$fstype])
8434 @c ====================================================== Results of Tests.
8437 @chapter Results of Tests
8439 Once @command{configure} has determined whether a feature exists, what can
8440 it do to record that information? There are four sorts of things it can
8441 do: define a C preprocessor symbol, set a variable in the output files,
8442 save the result in a cache file for future @command{configure} runs, and
8443 print a message letting the user know the result of the test.
8446 * Defining Symbols:: Defining C preprocessor symbols
8447 * Setting Output Variables:: Replacing variables in output files
8448 * Special Chars in Variables:: Characters to beware of in variables
8449 * Caching Results:: Speeding up subsequent @command{configure} runs
8450 * Printing Messages:: Notifying @command{configure} users
8453 @node Defining Symbols
8454 @section Defining C Preprocessor Symbols
8456 A common action to take in response to a feature test is to define a C
8457 preprocessor symbol indicating the results of the test. That is done by
8458 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8460 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8461 into the output variable @code{DEFS}, which contains an option
8462 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8463 Autoconf version 1, there is no variable @code{DEFS} defined while
8464 @command{configure} is running. To check whether Autoconf macros have
8465 already defined a certain C preprocessor symbol, test the value of the
8466 appropriate cache variable, as in this example:
8469 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8470 [Define if vprintf exists.])])
8471 if test "$ac_cv_func_vprintf" != yes; then
8472 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8473 [Define if _doprnt exists.])])
8477 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8478 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8479 correct values into @code{#define} statements in a template file.
8480 @xref{Configuration Headers}, for more information about this kind of
8483 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8484 @defmacx AC_DEFINE (@var{variable})
8485 @cvindex @var{variable}
8487 Define @var{variable} to @var{value} (verbatim), by defining a C
8488 preprocessor macro for @var{variable}. @var{variable} should be a C
8489 identifier, optionally suffixed by a parenthesized argument list to
8490 define a C preprocessor macro with arguments. The macro argument list,
8491 if present, should be a comma-separated list of C identifiers, possibly
8492 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8493 @var{variable} should not contain comments, white space, trigraphs,
8494 backslash-newlines, universal character names, or non-@acronym{ASCII}
8497 @var{value} may contain backslash-escaped newlines, which will be
8498 preserved if you use @code{AC_CONFIG_HEADERS} but flattened if passed
8499 via @code{@@DEFS@@} (with no effect on the compilation, since the
8500 preprocessor sees only one line in the first place). @var{value} should
8501 not contain raw newlines. If you are not using
8502 @code{AC_CONFIG_HEADERS}, @var{value} should not contain any @samp{#}
8503 characters, as @command{make} tends to eat them. To use a shell
8504 variable, use @code{AC_DEFINE_UNQUOTED} instead.
8506 @var{description} is only useful if you are using
8507 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8508 the generated @file{config.h.in} as the comment before the macro define.
8509 The following example defines the C preprocessor variable
8510 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8513 AC_DEFINE([EQUATION], ["$a > $b"],
8517 If neither @var{value} nor @var{description} are given, then
8518 @var{value} defaults to 1 instead of to the empty string. This is for
8519 backwards compatibility with older versions of Autoconf, but this usage
8520 is obsolescent and may be withdrawn in future versions of Autoconf.
8522 If the @var{variable} is a literal string, it is passed to
8523 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8525 If multiple @code{AC_DEFINE} statements are executed for the same
8526 @var{variable} name (not counting any parenthesized argument list),
8530 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8531 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8532 @acindex{DEFINE_UNQUOTED}
8533 @cvindex @var{variable}
8534 Like @code{AC_DEFINE}, but three shell expansions are
8535 performed---once---on @var{variable} and @var{value}: variable expansion
8536 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8537 (@samp{\}). Single and double quote characters in the value have no
8538 special meaning. Use this macro instead of @code{AC_DEFINE} when
8539 @var{variable} or @var{value} is a shell variable. Examples:
8542 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8543 [Configuration machine file.])
8544 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8545 [getgroups return type.])
8546 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8547 [Translated header name.])
8551 Due to a syntactical bizarreness of the Bourne shell, do not use
8552 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8553 calls from other macro calls or shell code; that can cause syntax errors
8554 in the resulting @command{configure} script. Use either blanks or
8555 newlines. That is, do this:
8558 AC_CHECK_HEADER([elf.h],
8559 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8566 AC_CHECK_HEADER([elf.h],
8567 [AC_DEFINE([SVR4], [1], [System V Release 4])
8568 LIBS="-lelf $LIBS"])
8575 AC_CHECK_HEADER([elf.h],
8576 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8579 @node Setting Output Variables
8580 @section Setting Output Variables
8581 @cindex Output variables
8583 Another way to record the results of tests is to set @dfn{output
8584 variables}, which are shell variables whose values are substituted into
8585 files that @command{configure} outputs. The two macros below create new
8586 output variables. @xref{Preset Output Variables}, for a list of output
8587 variables that are always available.
8589 @defmac AC_SUBST (@var{variable}, @ovar{value})
8591 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8592 substitute the variable @var{variable} into output files (typically one
8593 or more makefiles). This means that @code{AC_OUTPUT}
8594 replaces instances of @samp{@@@var{variable}@@} in input files with the
8595 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8596 is called. The value can contain any non-@code{NUL} character, including
8598 Variable occurrences should not overlap: e.g., an input file should
8599 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8601 The substituted value is not rescanned for more output variables;
8602 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8603 literally into the output file. (The algorithm uses the special marker
8604 @code{|#_!!_#|} internally, so neither the substituted value nor the
8605 output file may contain @code{|#_!!_#|}.)
8607 If @var{value} is given, in addition assign it to @var{variable}.
8609 The string @var{variable} is passed to @code{m4_pattern_allow}
8610 (@pxref{Forbidden Patterns}).
8613 @defmac AC_SUBST_FILE (@var{variable})
8614 @acindex{SUBST_FILE}
8615 Another way to create an output variable from a shell variable. Make
8616 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8617 named by shell variable @var{variable} into output files. This means
8618 that @code{AC_OUTPUT} replaces instances of
8619 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8620 with the contents of the file that the shell variable @var{variable}
8621 names when @code{AC_OUTPUT} is called. Set the variable to
8622 @file{/dev/null} for cases that do not have a file to insert.
8623 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8624 line by itself, optionally surrounded by spaces and tabs. The
8625 substitution replaces the whole line, including the spaces, tabs, and
8626 the terminating newline.
8628 This macro is useful for inserting makefile fragments containing
8629 special dependencies or other @code{make} directives for particular host
8630 or target types into makefiles. For example, @file{configure.ac}
8634 AC_SUBST_FILE([host_frag])
8635 host_frag=$srcdir/conf/sun4.mh
8639 and then a @file{Makefile.in} could contain:
8645 The string @var{variable} is passed to @code{m4_pattern_allow}
8646 (@pxref{Forbidden Patterns}).
8649 @cindex Precious Variable
8650 @cindex Variable, Precious
8651 Running @command{configure} in varying environments can be extremely
8652 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8653 ./configure}, then the cache, @file{config.h}, and many other output
8654 files depend upon @command{bizarre-cc} being the C compiler. If
8655 for some reason the user runs @command{./configure} again, or if it is
8656 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8657 and @pxref{config.status Invocation}), then the configuration can be
8658 inconsistent, composed of results depending upon two different
8661 Environment variables that affect this situation, such as @samp{CC}
8662 above, are called @dfn{precious variables}, and can be declared as such
8663 by @code{AC_ARG_VAR}.
8665 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8667 Declare @var{variable} is a precious variable, and include its
8668 @var{description} in the variable section of @samp{./configure --help}.
8670 Being precious means that
8673 @var{variable} is substituted via @code{AC_SUBST}.
8676 The value of @var{variable} when @command{configure} was launched is
8677 saved in the cache, including if it was not specified on the command
8678 line but via the environment. Indeed, while @command{configure} can
8679 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8680 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8681 which, unfortunately, is what most users do.
8683 We emphasize that it is the @emph{initial} value of @var{variable} which
8684 is saved, not that found during the execution of @command{configure}.
8685 Indeed, specifying @samp{./configure FOO=foo} and letting
8686 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8690 @var{variable} is checked for consistency between two
8691 @command{configure} runs. For instance:
8694 $ @kbd{./configure --silent --config-cache}
8695 $ @kbd{CC=cc ./configure --silent --config-cache}
8696 configure: error: `CC' was not set in the previous run
8697 configure: error: changes in the environment can compromise \
8699 configure: error: run `make distclean' and/or \
8700 `rm config.cache' and start over
8704 and similarly if the variable is unset, or if its content is changed.
8708 @var{variable} is kept during automatic reconfiguration
8709 (@pxref{config.status Invocation}) as if it had been passed as a command
8710 line argument, including when no cache is used:
8713 $ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent}
8714 $ @kbd{./config.status --recheck}
8715 running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
8716 CC=/usr/bin/cc --no-create --no-recursion
8721 @node Special Chars in Variables
8722 @section Special Characters in Output Variables
8723 @cindex Output variables, special characters in
8725 Many output variables are intended to be evaluated both by
8726 @command{make} and by the shell. Some characters are expanded
8727 differently in these two contexts, so to avoid confusion these
8728 variables' values should not contain any of the following characters:
8731 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8734 Also, these variables' values should neither contain newlines, nor start
8735 with @samp{~}, nor contain white space or @samp{:} immediately followed
8736 by @samp{~}. The values can contain nonempty sequences of white space
8737 characters like tabs and spaces, but each such sequence might
8738 arbitrarily be replaced by a single space during substitution.
8740 These restrictions apply both to the values that @command{configure}
8741 computes, and to the values set directly by the user. For example, the
8742 following invocations of @command{configure} are problematic, since they
8743 attempt to use special characters within @code{CPPFLAGS} and white space
8744 within @code{$(srcdir)}:
8747 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8749 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8752 @node Caching Results
8753 @section Caching Results
8756 To avoid checking for the same features repeatedly in various
8757 @command{configure} scripts (or in repeated runs of one script),
8758 @command{configure} can optionally save the results of many checks in a
8759 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8760 runs with caching enabled and finds a cache file, it reads the results
8761 of previous runs from the cache and avoids rerunning those checks. As a
8762 result, @command{configure} can then run much faster than if it had to
8763 perform all of the checks every time.
8765 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8767 Ensure that the results of the check identified by @var{cache-id} are
8768 available. If the results of the check were in the cache file that was
8769 read, and @command{configure} was not given the @option{--quiet} or
8770 @option{--silent} option, print a message saying that the result was
8771 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8772 the shell commands are run to determine the value, the value is
8773 saved in the cache file just before @command{configure} creates its output
8774 files. @xref{Cache Variable Names}, for how to choose the name of the
8775 @var{cache-id} variable.
8777 The @var{commands-to-set-it} @emph{must have no side effects} except for
8778 setting the variable @var{cache-id}, see below.
8781 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @
8782 @var{commands-to-set-it})
8783 @acindex{CACHE_CHECK}
8784 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8785 messages. This macro provides a convenient shorthand for the most
8786 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8787 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8788 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8790 The @var{commands-to-set-it} @emph{must have no side effects} except for
8791 setting the variable @var{cache-id}, see below.
8794 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8795 @code{AC_CACHE_CHECK}, because people are tempted to call
8796 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8797 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8798 @code{AC_DEFINE}, by examining the value of the cache variable. For
8799 instance, the following macro is broken:
8803 AC_DEFUN([AC_SHELL_TRUE],
8804 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8805 [my_cv_shell_true_works=no
8806 (true) 2>/dev/null && my_cv_shell_true_works=yes
8807 if test "$my_cv_shell_true_works" = yes; then
8808 AC_DEFINE([TRUE_WORKS], [1],
8809 [Define if `true(1)' works properly.])
8816 This fails if the cache is enabled: the second time this macro is run,
8817 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8822 AC_DEFUN([AC_SHELL_TRUE],
8823 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8824 [my_cv_shell_true_works=no
8825 (true) 2>/dev/null && my_cv_shell_true_works=yes])
8826 if test "$my_cv_shell_true_works" = yes; then
8827 AC_DEFINE([TRUE_WORKS], [1],
8828 [Define if `true(1)' works properly.])
8834 Also, @var{commands-to-set-it} should not print any messages, for
8835 example with @code{AC_MSG_CHECKING}; do that before calling
8836 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8837 the results of the check are retrieved from the cache or determined by
8838 running the shell commands.
8841 * Cache Variable Names:: Shell variables used in caches
8842 * Cache Files:: Files @command{configure} uses for caching
8843 * Cache Checkpointing:: Loading and saving the cache file
8846 @node Cache Variable Names
8847 @subsection Cache Variable Names
8848 @cindex Cache variable
8850 The names of cache variables should have the following format:
8853 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8857 for example, @samp{ac_cv_header_stat_broken} or
8858 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8861 @item @var{package-prefix}
8862 An abbreviation for your package or organization; the same prefix you
8863 begin local Autoconf macros with, except lowercase by convention.
8864 For cache values used by the distributed Autoconf macros, this value is
8868 Indicates that this shell variable is a cache value. This string
8869 @emph{must} be present in the variable name, including the leading
8872 @item @var{value-type}
8873 A convention for classifying cache values, to produce a rational naming
8874 system. The values used in Autoconf are listed in @ref{Macro Names}.
8876 @item @var{specific-value}
8877 Which member of the class of cache values this test applies to.
8878 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8879 output variable (@samp{INSTALL}).
8881 @item @var{additional-options}
8882 Any particular behavior of the specific member that this test applies to.
8883 For example, @samp{broken} or @samp{set}. This part of the name may
8884 be omitted if it does not apply.
8887 The values assigned to cache variables may not contain newlines.
8888 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8889 names of files or functions; so this is not an important restriction.
8892 @subsection Cache Files
8894 A cache file is a shell script that caches the results of configure
8895 tests run on one system so they can be shared between configure scripts
8896 and configure runs. It is not useful on other systems. If its contents
8897 are invalid for some reason, the user may delete or edit it.
8899 By default, @command{configure} uses no cache file,
8900 to avoid problems caused by accidental
8901 use of stale cache files.
8903 To enable caching, @command{configure} accepts @option{--config-cache} (or
8904 @option{-C}) to cache results in the file @file{config.cache}.
8905 Alternatively, @option{--cache-file=@var{file}} specifies that
8906 @var{file} be the cache file. The cache file is created if it does not
8907 exist already. When @command{configure} calls @command{configure} scripts in
8908 subdirectories, it uses the @option{--cache-file} argument so that they
8909 share the same cache. @xref{Subdirectories}, for information on
8910 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8912 @file{config.status} only pays attention to the cache file if it is
8913 given the @option{--recheck} option, which makes it rerun
8914 @command{configure}.
8916 It is wrong to try to distribute cache files for particular system types.
8917 There is too much room for error in doing that, and too much
8918 administrative overhead in maintaining them. For any features that
8919 can't be guessed automatically, use the standard method of the canonical
8920 system type and linking files (@pxref{Manual Configuration}).
8922 The site initialization script can specify a site-wide cache file to
8923 use, instead of the usual per-program cache. In this case, the cache
8924 file gradually accumulates information whenever someone runs a new
8925 @command{configure} script. (Running @command{configure} merges the new cache
8926 results with the existing cache file.) This may cause problems,
8927 however, if the system configuration (e.g., the installed libraries or
8928 compilers) changes and the stale cache file is not deleted.
8930 @node Cache Checkpointing
8931 @subsection Cache Checkpointing
8933 If your configure script, or a macro called from @file{configure.ac}, happens
8934 to abort the configure process, it may be useful to checkpoint the cache
8935 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8936 reduces the amount of time it takes to rerun the configure script with
8937 (hopefully) the error that caused the previous abort corrected.
8939 @c FIXME: Do we really want to document this guy?
8940 @defmac AC_CACHE_LOAD
8941 @acindex{CACHE_LOAD}
8942 Loads values from existing cache file, or creates a new cache file if a
8943 cache file is not found. Called automatically from @code{AC_INIT}.
8946 @defmac AC_CACHE_SAVE
8947 @acindex{CACHE_SAVE}
8948 Flushes all cached values to the cache file. Called automatically from
8949 @code{AC_OUTPUT}, but it can be quite useful to call
8950 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8956 @r{ @dots{} AC_INIT, etc. @dots{}}
8958 # Checks for programs.
8961 @r{ @dots{} more program checks @dots{}}
8966 # Checks for libraries.
8967 AC_CHECK_LIB([nsl], [gethostbyname])
8968 AC_CHECK_LIB([socket], [connect])
8969 @r{ @dots{} more lib checks @dots{}}
8974 # Might abort@dots{}
8975 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8976 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8978 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8981 @node Printing Messages
8982 @section Printing Messages
8983 @cindex Messages, from @command{configure}
8985 @command{configure} scripts need to give users running them several kinds
8986 of information. The following macros print messages in ways appropriate
8987 for each kind. The arguments to all of them get enclosed in shell
8988 double quotes, so the shell performs variable and back-quote
8989 substitution on them.
8991 These macros are all wrappers around the @command{echo} shell command.
8992 They direct output to the appropriate file descriptor (@pxref{File
8993 Descriptor Macros}).
8994 @command{configure} scripts should rarely need to run @command{echo} directly
8995 to print messages for the user. Using these macros makes it easy to
8996 change how and when each kind of message is printed; such changes need
8997 only be made to the macro definitions and all the callers change
9000 To diagnose static issues, i.e., when @command{autoconf} is run, see
9001 @ref{Reporting Messages}.
9003 @defmac AC_MSG_CHECKING (@var{feature-description})
9004 @acindex{MSG_CHECKING}
9005 Notify the user that @command{configure} is checking for a particular
9006 feature. This macro prints a message that starts with @samp{checking }
9007 and ends with @samp{...} and no newline. It must be followed by a call
9008 to @code{AC_MSG_RESULT} to print the result of the check and the
9009 newline. The @var{feature-description} should be something like
9010 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
9013 This macro prints nothing if @command{configure} is run with the
9014 @option{--quiet} or @option{--silent} option.
9017 @anchor{AC_MSG_RESULT}
9018 @defmac AC_MSG_RESULT (@var{result-description})
9019 @acindex{MSG_RESULT}
9020 Notify the user of the results of a check. @var{result-description} is
9021 almost always the value of the cache variable for the check, typically
9022 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
9023 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
9024 the completion of the message printed by the call to
9025 @code{AC_MSG_CHECKING}.
9027 This macro prints nothing if @command{configure} is run with the
9028 @option{--quiet} or @option{--silent} option.
9031 @anchor{AC_MSG_NOTICE}
9032 @defmac AC_MSG_NOTICE (@var{message})
9033 @acindex{MSG_NOTICE}
9034 Deliver the @var{message} to the user. It is useful mainly to print a
9035 general description of the overall purpose of a group of feature checks,
9039 AC_MSG_NOTICE([checking if stack overflow is detectable])
9042 This macro prints nothing if @command{configure} is run with the
9043 @option{--quiet} or @option{--silent} option.
9046 @anchor{AC_MSG_ERROR}
9047 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
9049 Notify the user of an error that prevents @command{configure} from
9050 completing. This macro prints an error message to the standard error
9051 output and exits @command{configure} with @var{exit-status} (1 by default).
9052 @var{error-description} should be something like @samp{invalid value
9055 The @var{error-description} should start with a lower-case letter, and
9056 ``cannot'' is preferred to ``can't''.
9059 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
9060 @acindex{MSG_FAILURE}
9061 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
9062 prevents @command{configure} from completing @emph{and} that additional
9063 details are provided in @file{config.log}. This is typically used when
9064 abnormal results are found during a compilation.
9067 @anchor{AC_MSG_WARN}
9068 @defmac AC_MSG_WARN (@var{problem-description})
9070 Notify the @command{configure} user of a possible problem. This macro
9071 prints the message to the standard error output; @command{configure}
9072 continues running afterward, so macros that call @code{AC_MSG_WARN} should
9073 provide a default (back-up) behavior for the situations they warn about.
9074 @var{problem-description} should be something like @samp{ln -s seems to
9080 @c ====================================================== Programming in M4.
9082 @node Programming in M4
9083 @chapter Programming in M4
9086 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
9087 convenient macros for pure M4 programming, and @dfn{M4sh}, which
9088 provides macros dedicated to shell script generation.
9090 As of this version of Autoconf, these two layers are still experimental,
9091 and their interface might change in the future. As a matter of fact,
9092 @emph{anything that is not documented must not be used}.
9095 * M4 Quotation:: Protecting macros from unwanted expansion
9096 * Using autom4te:: The Autoconf executables backbone
9097 * Programming in M4sugar:: Convenient pure M4 macros
9098 * Programming in M4sh:: Common shell Constructs
9099 * File Descriptor Macros:: File descriptor macros for input and output
9103 @section M4 Quotation
9104 @cindex M4 quotation
9107 The most common problem with existing macros is an improper quotation.
9108 This section, which users of Autoconf can skip, but which macro writers
9109 @emph{must} read, first justifies the quotation scheme that was chosen
9110 for Autoconf and then ends with a rule of thumb. Understanding the
9111 former helps one to follow the latter.
9114 * Active Characters:: Characters that change the behavior of M4
9115 * One Macro Call:: Quotation and one macro call
9116 * Quoting and Parameters:: M4 vs. shell parameters
9117 * Quotation and Nested Macros:: Macros calling macros
9118 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
9119 * Quadrigraphs:: Another way to escape special characters
9120 * Quotation Rule Of Thumb:: One parenthesis, one quote
9123 @node Active Characters
9124 @subsection Active Characters
9126 To fully understand where proper quotation is important, you first need
9127 to know what the special characters are in Autoconf: @samp{#} introduces
9128 a comment inside which no macro expansion is performed, @samp{,}
9129 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
9130 @samp{(} and @samp{)} (which M4 tries to match by pairs), and finally
9131 @samp{$} inside a macro definition.
9133 In order to understand the delicate case of macro calls, we first have
9134 to present some obvious failures. Below they are ``obvious-ified'',
9135 but when you find them in real life, they are usually in disguise.
9137 Comments, introduced by a hash and running up to the newline, are opaque
9138 tokens to the top level: active characters are turned off, and there is
9142 # define([def], ine)
9143 @result{}# define([def], ine)
9146 Each time there can be a macro expansion, there is a quotation
9147 expansion, i.e., one level of quotes is stripped:
9153 @result{}int tab[10];
9156 Without this in mind, the reader might try hopelessly to use her macro
9160 define([array], [int tab[10];])
9168 How can you correctly output the intended results@footnote{Using
9172 @node One Macro Call
9173 @subsection One Macro Call
9175 Let's proceed on the interaction between active characters and macros
9176 with this small macro, which just returns its first argument:
9183 The two pairs of quotes above are not part of the arguments of
9184 @code{define}; rather, they are understood by the top level when it
9185 tries to find the arguments of @code{define}. Therefore, assuming
9186 @code{car} is not already defined, it is equivalent to write:
9193 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
9194 quotes, it is bad practice for Autoconf macros which must both be more
9195 robust and also advocate perfect style.
9197 At the top level, there are only two possibilities: either you
9203 [car(foo, bar, baz)]
9204 @result{}car(foo, bar, baz)
9207 Let's pay attention to the special characters:
9211 @error{}EOF in argument list
9214 The closing parenthesis is hidden in the comment; with a hypothetical
9215 quoting, the top level understood it this way:
9222 Proper quotation, of course, fixes the problem:
9229 Here are more examples:
9252 @node Quoting and Parameters
9255 When M4 encounters @samp{$} within a macro definition, followed
9256 immediately by a character it recognizes (@samp{0}@dots{}@samp{9},
9257 @samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter
9258 expansion. This happens regardless of how many layers of quotes the
9259 parameter expansion is nested within, or even if it occurs in text that
9260 will be rescanned as a comment.
9263 define([none], [$1])
9265 define([one], [[$1]])
9267 define([two], [[[$1]]])
9269 define([comment], [# $1])
9271 define([active], [ACTIVE])
9283 On the other hand, since autoconf generates shell code, you often want
9284 to output shell variable expansion, rather than performing M4 parameter
9285 expansion. To do this, you must use M4 quoting to separate the @samp{$}
9286 from the next character in the definition of your macro. If the macro
9287 definition occurs in single-quoted text, then insert another level of
9288 quoting; if the usage is already inside a double-quoted string, then
9289 split it into concatenated strings.
9292 define([single], [a single-quoted $[]1 definition])
9294 define([double], [[a double-quoted $][1 definition]])
9297 @result{}a single-quoted $1 definition
9299 @result{}a double-quoted $1 definition
9302 Posix states that M4 implementations are free to provide implementation
9303 extensions when @samp{$@{} is encountered in a macro definition.
9304 Autoconf reserves the longer sequence @samp{$@{@{} for use with planned
9305 extensions that will be available in the future @acronym{GNU} M4 2.0,
9306 but guarantees that all other instances of @samp{$@{} will be output
9307 literally. Therefore, this idiom can also be used to output shell code
9308 parameter references:
9311 define([first], [$@{1@}])first
9315 Posix also states that @samp{$11} should expand to the first parameter
9316 concatenated with a literal @samp{1}, although some versions of
9317 @acronym{GNU} M4 expand the eleventh parameter instead. For
9318 portability, you should only use single-digit M4 parameter expansion.
9320 With this in mind, we can explore the cases where macros invoke
9323 @node Quotation and Nested Macros
9324 @subsection Quotation and Nested Macros
9326 The examples below use the following macros:
9330 define([active], [ACT, IVE])
9331 define([array], [int tab[10]])
9334 Each additional embedded macro call introduces other possible
9335 interesting quotations:
9346 In the first case, the top level looks for the arguments of @code{car},
9347 and finds @samp{active}. Because M4 evaluates its arguments
9348 before applying the macro, @samp{active} is expanded, which results in:
9356 In the second case, the top level gives @samp{active} as first and only
9357 argument of @code{car}, which results in:
9365 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9366 In the third case, @code{car} receives @samp{[active]}, which results in:
9374 exactly as we already saw above.
9376 The example above, applied to a more realistic example, gives:
9383 car([[int tab[10];]])
9384 @result{}int tab[10];
9388 Huh? The first case is easily understood, but why is the second wrong,
9389 and the third right? To understand that, you must know that after
9390 M4 expands a macro, the resulting text is immediately subjected
9391 to macro expansion and quote removal. This means that the quote removal
9392 occurs twice---first before the argument is passed to the @code{car}
9393 macro, and second after the @code{car} macro expands to the first
9396 As the author of the Autoconf macro @code{car}, you then consider it to
9397 be incorrect that your users have to double-quote the arguments of
9398 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9402 define([qar], [[$1]])
9406 and check that @code{qar} is properly fixed:
9410 @result{}int tab[10];
9414 Ahhh! That's much better.
9416 But note what you've done: now that the result of @code{qar} is always
9417 a literal string, the only time a user can use nested macros is if she
9418 relies on an @emph{unquoted} macro call:
9428 leaving no way for her to reproduce what she used to do with @code{car}:
9436 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9440 define([my_includes], [#include <stdio.h>])
9442 @result{}#include <stdio.h>
9444 @error{}EOF in argument list
9447 This macro, @code{qar}, because it double quotes its arguments, forces
9448 its users to leave their macro calls unquoted, which is dangerous.
9449 Commas and other active symbols are interpreted by M4 before
9450 they are given to the macro, often not in the way the users expect.
9451 Also, because @code{qar} behaves differently from the other macros,
9452 it's an exception that should be avoided in Autoconf.
9454 @node Changequote is Evil
9455 @subsection @code{changequote} is Evil
9456 @cindex @code{changequote}
9458 The temptation is often high to bypass proper quotation, in particular
9459 when it's late at night. Then, many experienced Autoconf hackers
9460 finally surrender to the dark side of the force and use the ultimate
9461 weapon: @code{changequote}.
9463 The M4 builtin @code{changequote} belongs to a set of primitives that
9464 allow one to adjust the syntax of the language to adjust it to one's
9465 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9466 quotes, but in the context of shell programming (and actually of most
9467 programming languages), that's about the worst choice one can make:
9468 because of strings and back-quoted expressions in shell code (such as
9469 @samp{'this'} and @samp{`that`}), and because of literal characters in usual
9470 programming languages (as in @samp{'0'}), there are many unbalanced
9471 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9472 not impossible. In order to make M4 useful in such a context, its
9473 designers have equipped it with @code{changequote}, which makes it
9474 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9475 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9476 because they are unlikely characters, but @emph{because they are
9477 characters unlikely to be unbalanced}.
9479 There are other magic primitives, such as @code{changecom} to specify
9480 what syntactic forms are comments (it is common to see
9481 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9482 @code{changeword} and @code{changesyntax} to change other syntactic
9483 details (such as the character to denote the @var{n}th argument, @samp{$} by
9484 default, the parenthesis around arguments, etc.).
9486 These primitives are really meant to make M4 more useful for specific
9487 domains: they should be considered like command line options:
9488 @option{--quotes}, @option{--comments}, @option{--words}, and
9489 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9490 it makes M4 libraries self contained (no need for additional options).
9492 There lies the problem@enddots{}
9496 The problem is that it is then tempting to use them in the middle of an
9497 M4 script, as opposed to its initialization. This, if not carefully
9498 thought out, can lead to disastrous effects: @emph{you are changing the
9499 language in the middle of the execution}. Changing and restoring the
9500 syntax is often not enough: if you happened to invoke macros in between,
9501 these macros are lost, as the current syntax is probably not
9502 the one they were implemented with.
9504 @c FIXME: I've been looking for a short, real case example, but I
9509 @subsection Quadrigraphs
9510 @cindex quadrigraphs
9511 @cindex @samp{@@S|@@}
9512 @cindex @samp{@@&t@@}
9513 @c Info cannot handle `:' in index entries.
9514 @c @cindex @samp{@@<:@@}
9515 @c @cindex @samp{@@:>@@}
9516 @c @cindex @samp{@@%:@@}
9518 When writing an Autoconf macro you may occasionally need to generate
9519 special characters that are difficult to express with the standard
9520 Autoconf quoting rules. For example, you may need to output the regular
9521 expression @samp{[^[]}, which matches any character other than @samp{[}.
9522 This expression contains unbalanced brackets so it cannot be put easily
9525 You can work around this problem by using one of the following
9541 Quadrigraphs are replaced at a late stage of the translation process,
9542 after @command{m4} is run, so they do not get in the way of M4 quoting.
9543 For example, the string @samp{^@@<:@@}, independently of its quotation,
9544 appears as @samp{^[} in the output.
9546 The empty quadrigraph can be used:
9549 @item to mark trailing spaces explicitly
9551 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9553 @item to produce other quadrigraphs
9555 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9557 @item to escape @emph{occurrences} of forbidden patterns
9559 For instance you might want to mention @code{AC_FOO} in a comment, while
9560 still being sure that @command{autom4te} still catches unexpanded
9561 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9564 The name @samp{@@&t@@} was suggested by Paul Eggert:
9567 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9568 own invention, but the @samp{t} came from the source code of the
9569 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9570 and which used @samp{mt} to denote the empty string. In C, it would
9571 have looked like something like:
9574 char const mt[] = "";
9578 but of course the source code was written in Algol 68.
9580 I don't know where he got @samp{mt} from: it could have been his own
9581 invention, and I suppose it could have been a common pun around the
9582 Cambridge University computer lab at the time.
9585 @node Quotation Rule Of Thumb
9586 @subsection Quotation Rule Of Thumb
9588 To conclude, the quotation rule of thumb is:
9590 @center @emph{One pair of quotes per pair of parentheses.}
9592 Never over-quote, never under-quote, in particular in the definition of
9593 macros. In the few places where the macros need to use brackets
9594 (usually in C program text or regular expressions), properly quote
9595 @emph{the arguments}!
9597 It is common to read Autoconf programs with snippets like:
9601 changequote(<<, >>)dnl
9603 #ifndef tzname /* For SGI. */
9604 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9606 changequote([, ])dnl
9607 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9611 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9612 double quoting, so you just need:
9617 #ifndef tzname /* For SGI. */
9618 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9621 [ac_cv_var_tzname=yes],
9622 [ac_cv_var_tzname=no])
9626 The M4-fluent reader might note that these two examples are rigorously
9627 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9628 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9629 quotes are not part of the arguments!
9631 Simplified, the example above is just doing this:
9634 changequote(<<, >>)dnl
9636 changequote([, ])dnl
9646 With macros that do not double quote their arguments (which is the
9647 rule), double-quote the (risky) literals:
9650 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9652 #ifndef tzname /* For SGI. */
9653 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9655 [atoi (*tzname);])],
9656 [ac_cv_var_tzname=yes],
9657 [ac_cv_var_tzname=no])
9660 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9661 should be using @code{AC_LINK_IFELSE} instead.
9663 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9664 where quoting does not suffice.
9666 When you create a @command{configure} script using newly written macros,
9667 examine it carefully to check whether you need to add more quotes in
9668 your macros. If one or more words have disappeared in the M4
9669 output, you need more quotes. When in doubt, quote.
9671 However, it's also possible to put on too many layers of quotes. If
9672 this happens, the resulting @command{configure} script may contain
9673 unexpanded macros. The @command{autoconf} program checks for this problem
9674 by looking for the string @samp{AC_} in @file{configure}. However, this
9675 heuristic does not work in general: for example, it does not catch
9676 overquoting in @code{AC_DEFINE} descriptions.
9679 @c ---------------------------------------- Using autom4te
9681 @node Using autom4te
9682 @section Using @command{autom4te}
9684 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9685 to Autoconf per se, heavily rely on M4. All these different uses
9686 revealed common needs factored into a layer over M4:
9687 @command{autom4te}@footnote{
9689 Yet another great name from Lars J. Aas.
9693 @command{autom4te} is a preprocessor that is like @command{m4}.
9694 It supports M4 extensions designed for use in tools like Autoconf.
9697 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9698 * Customizing autom4te:: Customizing the Autoconf package
9701 @node autom4te Invocation
9702 @subsection Invoking @command{autom4te}
9704 The command line arguments are modeled after M4's:
9707 autom4te @var{options} @var{files}
9712 where the @var{files} are directly passed to @command{m4}. By default,
9713 @acronym{GNU} M4 is found during configuration, but the environment
9715 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9716 to the regular expansion, it handles the replacement of the quadrigraphs
9717 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9718 output. It supports an extended syntax for the @var{files}:
9721 @item @var{file}.m4f
9722 This file is an M4 frozen file. Note that @emph{all the previous files
9723 are ignored}. See the option @option{--melt} for the rationale.
9726 If found in the library path, the @var{file} is included for expansion,
9727 otherwise it is ignored instead of triggering a failure.
9732 Of course, it supports the Autoconf common subset of options:
9737 Print a summary of the command line options and exit.
9741 Print the version number of Autoconf and exit.
9745 Report processing steps.
9749 Don't remove the temporary files and be even more verbose.
9751 @item --include=@var{dir}
9753 Also look for input files in @var{dir}. Multiple invocations
9756 @item --output=@var{file}
9757 @itemx -o @var{file}
9758 Save output (script or trace) to @var{file}. The file @option{-} stands
9759 for the standard output.
9764 As an extension of @command{m4}, it includes the following options:
9767 @item --warnings=@var{category}
9768 @itemx -W @var{category}
9770 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9771 Report the warnings related to @var{category} (which can actually be a
9772 comma separated list). @xref{Reporting Messages}, macro
9773 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9778 report all the warnings
9784 treats warnings as errors
9786 @item no-@var{category}
9787 disable warnings falling into @var{category}
9790 Warnings about @samp{syntax} are enabled by default, and the environment
9791 variable @env{WARNINGS}, a comma separated list of categories, is
9792 honored. @samp{autom4te -W @var{category}} actually
9793 behaves as if you had run:
9796 autom4te --warnings=syntax,$WARNINGS,@var{category}
9800 For example, if you want to disable defaults and @env{WARNINGS}
9801 of @command{autom4te}, but enable the warnings about obsolete
9802 constructs, you would use @option{-W none,obsolete}.
9805 @cindex Macro invocation stack
9806 @command{autom4te} displays a back trace for errors, but not for
9807 warnings; if you want them, just pass @option{-W error}.
9811 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9812 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9813 are executed only when the files are frozen, typically
9814 @code{m4_define}. For instance, running:
9817 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9821 is roughly equivalent to running:
9824 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9831 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9838 m4 --reload-state=4.m4f input.m4
9843 Produce a frozen state file. @command{autom4te} freezing is stricter
9844 than M4's: it must produce no warnings, and no output other than empty
9845 lines (a line with white space is @emph{not} empty) and comments
9846 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9847 this option takes no argument:
9850 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9857 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9860 @item --mode=@var{octal-mode}
9861 @itemx -m @var{octal-mode}
9862 Set the mode of the non-traces output to @var{octal-mode}; by default
9868 @cindex @file{autom4te.cache}
9869 As another additional feature over @command{m4}, @command{autom4te}
9870 caches its results. @acronym{GNU} M4 is able to produce a regular
9871 output and traces at the same time. Traces are heavily used in the
9872 @acronym{GNU} Build System: @command{autoheader} uses them to build
9873 @file{config.h.in}, @command{autoreconf} to determine what
9874 @acronym{GNU} Build System components are used, @command{automake} to
9875 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9876 traces are cached while performing regular expansion,
9877 and conversely. This cache is (actually, the caches are) stored in
9878 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9879 at any moment (especially if for some reason @command{autom4te}
9880 considers it is trashed).
9883 @item --cache=@var{directory}
9884 @itemx -C @var{directory}
9885 Specify the name of the directory where the result should be cached.
9886 Passing an empty value disables caching. Be sure to pass a relative
9887 file name, as for the time being, global caches are not supported.
9890 Don't cache the results.
9894 If a cache is used, consider it obsolete (but update it anyway).
9899 Because traces are so important to the @acronym{GNU} Build System,
9900 @command{autom4te} provides high level tracing features as compared to
9901 M4, and helps exploiting the cache:
9904 @item --trace=@var{macro}[:@var{format}]
9905 @itemx -t @var{macro}[:@var{format}]
9906 Trace the invocations of @var{macro} according to the @var{format}.
9907 Multiple @option{--trace} arguments can be used to list several macros.
9908 Multiple @option{--trace} arguments for a single macro are not
9909 cumulative; instead, you should just make @var{format} as long as
9912 The @var{format} is a regular string, with newlines if desired, and
9913 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9914 use the following special escapes:
9918 The character @samp{$}.
9921 The file name from which @var{macro} is called.
9924 The line number from which @var{macro} is called.
9927 The depth of the @var{macro} call. This is an M4 technical detail that
9928 you probably don't want to know about.
9931 The name of the @var{macro}.
9934 The @var{num}th argument of the call to @var{macro}.
9938 @itemx $@{@var{separator}@}@@
9939 All the arguments passed to @var{macro}, separated by the character
9940 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9941 argument is quoted, i.e., enclosed in a pair of square brackets.
9945 @itemx $@{@var{separator}@}*
9946 As above, but the arguments are not quoted.
9950 @itemx $@{@var{separator}@}%
9951 As above, but the arguments are not quoted, all new line characters in
9952 the arguments are smashed, and the default separator is @samp{:}.
9954 The escape @samp{$%} produces single-line trace outputs (unless you put
9955 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9959 @xref{autoconf Invocation}, for examples of trace uses.
9961 @item --preselect=@var{macro}
9962 @itemx -p @var{macro}
9963 Cache the traces of @var{macro}, but do not enable traces. This is
9964 especially important to save CPU cycles in the future. For instance,
9965 when invoked, @command{autoconf} preselects all the macros that
9966 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9967 trace, so that running @command{m4} is not needed to trace them: the
9968 cache suffices. This results in a huge speed-up.
9973 @cindex Autom4te Library
9974 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9975 libraries}. They consists in a powerful yet extremely simple feature:
9976 sets of combined command line arguments:
9979 @item --language=@var{language}
9980 @itemx -l @var{language}
9981 Use the @var{language} Autom4te library. Current languages include:
9985 create M4sugar output.
9988 create M4sh executable shell scripts.
9991 create Autotest executable test suites.
9993 @item Autoconf-without-aclocal-m4
9994 create Autoconf executable configure scripts without
9995 reading @file{aclocal.m4}.
9998 create Autoconf executable configure scripts. This language inherits
9999 all the characteristics of @code{Autoconf-without-aclocal-m4} and
10000 additionally reads @file{aclocal.m4}.
10003 @item --prepend-include=@var{dir}
10005 Prepend directory @var{dir} to the search path. This is used to include
10006 the language-specific files before any third-party macros.
10010 @cindex @file{autom4te.cfg}
10011 As an example, if Autoconf is installed in its default location,
10012 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
10013 strictly equivalent to the command:
10016 autom4te --prepend-include /usr/local/share/autoconf \
10017 m4sugar/m4sugar.m4f --warnings syntax foo.m4
10021 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
10022 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
10026 autom4te --prepend-include /usr/local/share/autoconf \
10027 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
10031 The definition of the languages is stored in @file{autom4te.cfg}.
10033 @node Customizing autom4te
10034 @subsection Customizing @command{autom4te}
10036 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
10037 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
10038 as found in the directory from which @command{autom4te} is run). The
10039 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
10040 then @file{./.autom4te.cfg}, and finally the command line arguments.
10042 In these text files, comments are introduced with @code{#}, and empty
10043 lines are ignored. Customization is performed on a per-language basis,
10044 wrapped in between a @samp{begin-language: "@var{language}"},
10045 @samp{end-language: "@var{language}"} pair.
10047 Customizing a language stands for appending options (@pxref{autom4te
10048 Invocation}) to the current definition of the language. Options, and
10049 more generally arguments, are introduced by @samp{args:
10050 @var{arguments}}. You may use the traditional shell syntax to quote the
10053 As an example, to disable Autoconf caches (@file{autom4te.cache})
10054 globally, include the following lines in @file{~/.autom4te.cfg}:
10057 ## ------------------ ##
10058 ## User Preferences. ##
10059 ## ------------------ ##
10061 begin-language: "Autoconf-without-aclocal-m4"
10063 end-language: "Autoconf-without-aclocal-m4"
10067 @node Programming in M4sugar
10068 @section Programming in M4sugar
10071 M4 by itself provides only a small, but sufficient, set of all-purpose
10072 macros. M4sugar introduces additional generic macros. Its name was
10073 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
10076 M4sugar reserves the macro namespace @samp{^_m4_} for internal use, and
10077 the macro namespace @samp{^m4_} for M4sugar macros. You should not
10078 define your own macros into these namespaces.
10081 * Redefined M4 Macros:: M4 builtins changed in M4sugar
10082 * Conditional constructs:: Conditions in M4
10083 * Looping constructs:: Iteration in M4
10084 * Evaluation Macros:: More quotation and evaluation control
10085 * Text processing Macros:: String manipulation in M4
10086 * Forbidden Patterns:: Catching unexpanded macros
10089 @node Redefined M4 Macros
10090 @subsection Redefined M4 Macros
10093 @msindex{changecom}
10094 @msindex{changequote}
10095 @msindex{debugfile}
10096 @msindex{debugmode}
10119 With a few exceptions, all the M4 native macros are moved in the
10120 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
10121 @code{m4_define} etc.
10123 Some M4 macros are redefined, and are slightly incompatible with their
10128 This macro kept its original name: no @code{m4_dnl} is defined.
10131 @defmac m4_defn (@var{macro})
10133 Unlike the M4 builtin, this macro fails if @var{macro} is not
10134 defined. See @code{m4_undefine}.
10137 @c FIXME: Need to document m4_divert, m4_undivert, m4_divert_push,
10138 @c m4_divert_pop, m4_divert_text, m4_divert_once
10140 @defmac m4_exit (@var{exit-status})
10142 This macro corresponds to @code{m4exit}.
10145 @defmac m4_if (@var{comment})
10146 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
10147 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
10149 This macro corresponds to @code{ifelse}. @var{string-1} and
10150 @var{string-2} are compared literally, so usually one of the two
10151 arguments is passed unquoted. @xref{Conditional constructs}, for more
10152 conditional idioms.
10155 @defmac m4_include (@var{file})
10156 @defmacx m4_sinclude (@var{file})
10159 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
10162 @defmac m4_mkstemp (@var{template})
10163 @defmacx m4_maketemp (@var{template})
10166 Posix requires @code{maketemp} to replace the trailing @samp{X}
10167 characters in @var{template} with the process id, without regards to the
10168 existence of a file by that name, but this a security hole. When this
10169 was pointed out to the Posix folks, they agreed to invent a new macro
10170 @code{mkstemp} that always creates a uniquely named file, but not all
10171 versions of @acronym{GNU} M4 support the new macro. In M4sugar,
10172 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
10173 and both have the secure semantics regardless of which macro the
10174 underlying M4 provides.
10177 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
10178 @msindex{bpatsubst}
10179 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
10180 is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
10181 released and supports extended regular expression syntax.
10184 @defmac m4_popdef (@var{macro})
10186 Unlike the M4 builtin, this macro fails if @var{macro} is not
10187 defined. See @code{m4_undefine}.
10190 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
10192 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
10193 is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
10194 released and supports extended regular expression syntax.
10197 @defmac m4_undefine (@var{macro})
10199 Unlike the M4 builtin, this macro fails if @var{macro} is not
10203 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
10207 to recover the behavior of the builtin.
10210 @defmac m4_wrap (@var{text})
10212 This macro corresponds to @code{m4wrap}.
10214 Posix requires arguments of multiple @code{m4wrap} calls to be
10215 reprocessed at @acronym{EOF} in the same order as the original calls.
10216 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
10217 reverse order. Your code should not depend on the order.
10219 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
10220 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
10221 arguments with intervening spaces. Your code should not pass more than
10224 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
10225 token pasting between consecutive invocations of @code{m4_wrap}, as in:
10228 m4_define([foo], [bar])
10229 m4_define([foofoo], [OUCH])
10237 @node Conditional constructs
10238 @subsection Conditional constructs
10240 The following macros provide additional conditional contructs, as
10241 convenience wrappers around @code{m4_if}.
10243 @defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @dots{}, @
10246 The string @var{string} is repeatedly compared against a series of
10247 @var{regex} arguments; if a match is found, the expansion is the
10248 corresponding @var{value}, otherwise, the macro moves on to the next
10249 @var{regex}. If no @var{regex} match, then the result is the optional
10250 @var{default}, or nothing.
10253 @defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @dots{})
10254 @msindex{bpatsubsts}
10255 The string @var{string} is altered by @var{regex-1} and @var{subst-1},
10258 m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}])
10262 The result of the substitution is then passed through the next set of
10263 @var{regex} and @var{subst}, and so forth. An empty @var{subst} implies
10264 deletion of any matched portions in the current string. Note that this
10265 macro over-quotes @var{string}; this behavior is intentional, so that
10266 the result of each step of the recursion remains as a quoted string.
10267 However, it means that anchors (@samp{^} and @samp{$} in the @var{regex}
10268 will line up with the extra quotations, and not the characters of the
10272 @defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @dots{}, @
10275 Test @var{string} against multiple @var{value} possibilities, resulting
10276 in the first @var{if-value} for a match, or in the optional
10277 @var{default}. This is shorthand for:
10279 m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}],
10280 [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{},
10285 @defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
10286 @var{test-2}, @var{value-2}, @var{if-value-2}, @dots{}, @ovar{default})
10288 Similar to @code{m4_if}, except that each @var{test} is expanded only
10289 when it is encountered. This is useful for short-circuiting expensive
10290 tests; while @code{m4_if} requires all its strings to be expanded up
10291 front before doing comparisons, @code{m4_cond} only expands a @var{test}
10292 when all earlier tests have failed.
10294 For an example, these two sequences give the same result, but in the
10295 case where @samp{$1} does not contain a backslash, the @code{m4_cond}
10296 version only expands @code{m4_index} once, instead of five times, for
10297 faster computation if this is a common case for @samp{$1}. Notice that
10298 every third argument is unquoted for @code{m4_if}, and quoted for
10302 m4_if(m4_index([$1], [\]), [-1], [$2],
10303 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
10304 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
10305 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
10306 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
10308 m4_cond([m4_index([$1], [\])], [-1], [$2],
10309 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
10310 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
10311 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
10312 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
10317 @defmac m4_default (@var{expr-1}, @var{expr-2})
10319 If @var{expr-1} is not empty, use it. Otherwise, expand to
10320 @var{expr-2}. Useful for providing a fixed default if the expression
10321 that results in @var{expr-1} would otherwise be empty.
10324 @defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined})
10326 This is shorthand for:
10328 m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}])
10332 @defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false})
10334 If @var{macro} is undefined, or is defined as the empty string, expand
10335 to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to:
10337 m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}])
10340 except that it is not an error if @var{macro} is undefined.
10343 @defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false})
10345 Expands to @var{if-true} if @var{cond} is not empty, otherwise to
10346 @var{if-false}. This is shorthand for:
10348 m4_if([@var{cond}], [], [@var{if-true}], [@var{if-false}])
10352 @defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false})
10354 Similar to @code{m4_ifval}, except guarantee that a newline is present
10355 after any non-empty expansion.
10358 @defmac m4_n (@var{text})
10360 Expand to @var{text}, and add a newline if @var{text} is not empty.
10364 @node Looping constructs
10365 @subsection Looping constructs
10367 The following macros implement loops in M4.
10369 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @
10372 Loop over the numeric values between @var{first} and @var{last}
10373 including bounds by increments of @var{step}. For each iteration,
10374 expand @var{expression} with the numeric value assigned to @var{var}.
10375 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
10376 on the order of the limits. If given, @var{step} has to match this
10380 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
10382 Loop over the comma-separated M4 list @var{list}, assigning each value
10383 to @var{var}, and expand @var{expression}. The following example
10387 m4_foreach([myvar], [[foo], [bar, baz]],
10394 @anchor{m4_foreach_w}
10395 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
10396 @msindex{foreach_w}
10397 Loop over the white-space-separated list @var{list}, assigning each value
10398 to @var{var}, and expand @var{expression}.
10400 The deprecated macro @code{AC_FOREACH} is an alias of
10401 @code{m4_foreach_w}.
10404 The following macros are useful in implementing recursive algorithms.
10406 @defmac m4_do (@dots{})
10408 This macro loops over its arguments and expands each one in sequence.
10409 Its main use is for readability; it allows the use of indentation and
10410 fewer @code{dnl} to result in the same expansion.
10413 @defmac m4_shiftn (@var{count}, @dots{})
10414 @defmacx m4_shift2 (@dots{})
10415 @defmacx m4_shift3 (@dots{})
10419 @code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
10420 along with validation that enough arguments were passed in to match the
10421 shift count. @code{m4_shift2} and @code{m4_shift3} are specializations
10422 of @code{m4_shiftn} that are more efficient for two and three shifts,
10427 @node Evaluation Macros
10428 @subsection Evaluation Macros
10430 The following macros give some control over the order of the evaluation
10431 by adding or removing levels of quotes. They are meant for hard-core M4
10434 @defmac m4_dquote (@var{arg1}, @dots{})
10436 Return the arguments as a quoted list of quoted arguments.
10439 @defmac m4_quote (@var{arg1}, @dots{})
10441 Return the arguments as a single entity, i.e., wrap them into a pair of
10445 The following example aims at emphasizing the difference between (i), not
10446 using these macros, (ii), using @code{m4_quote}, and (iii), using
10450 $ @kbd{cat example.m4}
10451 # Overquote, so that quotes are visible.
10452 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
10453 m4_define([mkargs], [1, 2, 3])
10454 m4_define([arg1], [[$1]])
10457 show(m4_quote(a, b))
10458 show(m4_dquote(a, b))
10461 arg1(m4_defn([mkargs]))
10462 arg1(m4_quote(mkargs))
10463 arg1(m4_dquote(mkargs))
10464 $ @kbd{autom4te -l m4sugar example.m4}
10465 $1 = a, $@@ = [a],[b]
10466 $1 = a,b, $@@ = [a,b]
10467 $1 = [a],[b], $@@ = [[a],[b]]
10477 @node Text processing Macros
10478 @subsection Text processing Macros
10480 The following macros may be used to manipulate strings in M4.
10481 They are not intended for casual use.
10483 @defmac m4_re_escape (@var{string})
10484 @msindex{re_escape}
10485 Backslash-escape all characters in @var{string} that are active in
10489 @defmac m4_tolower (@var{string})
10490 @defmacx m4_toupper (@var{string})
10493 Return @var{string} with letters converted to upper or lower case,
10497 @defmac m4_split (@var{string}, @ovar{regexp})
10499 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10500 @samp{]}, while keeping white space at the beginning and at the end.
10501 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10502 If @var{string} is empty, the result is an empty list.
10505 @defmac m4_normalize (@var{string})
10506 @msindex{normalize}
10507 Remove leading and trailing spaces and tabs, sequences of
10508 backslash-then-newline, and replace multiple spaces and tabs with a
10512 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10513 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @
10514 @ovar{if-uniq}, @ovar{if-duplicate})
10516 @msindex{append_uniq}
10517 Redefine @var{macro-name} to its former contents with @var{separator}
10518 and @var{string} added at the end. If @var{macro-name} was undefined
10519 before (but not if it was defined but empty), then no @var{separator} is
10520 added. As of Autoconf 2.62, neither @var{string} nor @var{separator}
10521 are expanded during this macro; instead, they are expanded when
10522 @var{macro-name} is invoked.
10524 @code{m4_append} can be used to grow strings, and @code{m4_append_uniq}
10525 to grow strings without duplicating substrings. Additionally,
10526 @code{m4_append_uniq} takes two optional parameters; @var{if-uniq} is
10527 expanded if @var{string} was appended, and @var{if-duplicate} is
10528 expanded if @var{string} was already present.
10531 m4_define([active], [ACTIVE])dnl
10532 m4_append([sentence], [This is an])dnl
10533 m4_append([sentence], [ active ])dnl
10534 m4_append([sentence], [symbol.])dnl
10536 @result{}This is an ACTIVE symbol.
10537 m4_undefine([active])dnl
10538 @result{}This is an active symbol.
10539 m4_append_uniq([list], [one], [, ], [new], [existing])
10541 m4_append_uniq([list], [one], [, ], [new], [existing])
10543 m4_append_uniq([list], [two], [, ], [new], [existing])
10545 m4_append_uniq([list], [three], [, ], [new], [existing])
10547 m4_append_uniq([list], [two], [, ], [new], [existing])
10550 @result{}one, two, three
10552 @result{}[one],[two],[three]
10553 m4_append([list2], [one], [[, ]])dnl
10554 m4_append_uniq([list2], [two], [[, ]])dnl
10555 m4_append([list2], [three], [[, ]])dnl
10557 @result{}one, two, three
10559 @result{}[one, two, three]
10563 @anchor{m4_version_compare}
10564 @defmac m4_version_compare (@var{version-1}, @var{version-2})
10565 @msindex{version_compare}
10566 Introduced in autoconf 2.53. Compare the version strings
10567 @var{version-1} and @var{version-2}, and expand to @samp{-1} if
10568 @var{version-1} is smaller, @samp{0} if they are the same, or @samp{1}
10569 @var{version-2} is smaller. Version strings must be a list of elements
10570 separated by @samp{.}, where each element is a number along with an
10571 optional lower case letter. The comparison stops at the leftmost
10572 element that contains a difference, although a 0 element compares equal
10573 to a missing element.
10576 m4_version_compare([1.1], [2.0])
10578 m4_version_compare([2.0b], [2.0a])
10580 m4_version_compare([1.1.1], [1.1.1a])
10582 m4_version_compare([1.2], [1.1.1a])
10584 m4_version_compare([1.0], [1])
10590 @node Forbidden Patterns
10591 @subsection Forbidden Patterns
10592 @cindex Forbidden patterns
10593 @cindex Patterns, forbidden
10595 M4sugar provides a means to define suspicious patterns, patterns
10596 describing tokens which should not be found in the output. For
10597 instance, if an Autoconf @file{configure} script includes tokens such as
10598 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10599 wrong (typically a macro was not evaluated because of overquotation).
10601 M4sugar forbids all the tokens matching @samp{^_?m4_} and @samp{^dnl$}.
10602 Additional layers, such as M4sh and Autoconf, add additional forbidden
10603 patterns to the list.
10605 @defmac m4_pattern_forbid (@var{pattern})
10606 @msindex{pattern_forbid}
10607 Declare that no token matching @var{pattern} must be found in the output.
10608 Comments are not checked; this can be a problem if, for instance, you
10609 have some macro left unexpanded after an @samp{#include}. No consensus
10610 is currently found in the Autoconf community, as some people consider it
10611 should be valid to name macros in comments (which doesn't make sense to
10612 the authors of this documentation: input, such as macros, should be
10613 documented by @samp{dnl} comments; reserving @samp{#}-comments to
10614 document the output).
10617 Of course, you might encounter exceptions to these generic rules, for
10618 instance you might have to refer to @samp{$m4_flags}.
10620 @defmac m4_pattern_allow (@var{pattern})
10621 @msindex{pattern_allow}
10622 Any token matching @var{pattern} is allowed, including if it matches an
10623 @code{m4_pattern_forbid} pattern.
10626 @node Programming in M4sh
10627 @section Programming in M4sh
10629 @c FIXME: Eventually will become a chapter, as it is not related to
10630 @c programming in M4 per se.
10632 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10633 scripts. This name was coined by Lars J. Aas, who notes that,
10634 according to the Webster's Revised Unabridged Dictionary (1913):
10637 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
10638 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
10642 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10646 A mixture of meal or bran and water fed to animals.
10649 A mess; trouble. [Obs.] --Beau.@: & Fl.
10654 For the time being, it is not mature enough to be widely used.
10656 M4sh reserves the M4 macro namespace @samp{^_AS_} for internal use, and
10657 the namespace @samp{^AS_} for M4sh macros. It also reserves the shell
10658 and environment variable namespace @samp{^as_}, and the here-doc
10659 delimiter namespace @samp{^_AS[A-Z]} in the output file. You should not
10660 define your own macros or output shell code that conflicts with these
10663 M4sh provides portable alternatives for some common shell constructs
10664 that unfortunately are not portable in practice.
10666 @c Deprecated, to be replaced by a better API
10668 @defmac AS_BASENAME (@var{file-name})
10670 Output the non-directory portion of @var{file-name}. For example,
10671 if @code{$file} is @samp{/one/two/three}, the command
10672 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10676 @defmac AS_BOURNE_COMPATIBLE
10677 @asindex{BOURNE_COMPATIBLE}
10678 Set up the shell to be more compatible with the Bourne shell as
10679 standardized by Posix, if possible. This may involve setting
10680 environment variables, or setting options, or similar
10681 implementation-specific actions.
10684 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
10685 @dots{}, @ovar{default})
10687 Expand into a shell @samp{case} statement, where @var{word} is matched
10688 against one or more patterns. @var{if-matched} is run if the
10689 corresponding pattern matched @var{word}, else @var{default} is run.
10692 @defmac AS_DIRNAME (@var{file-name})
10694 Output the directory portion of @var{file-name}. For example,
10695 if @code{$file} is @samp{/one/two/three}, the command
10696 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10699 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10701 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10702 run shell code @var{run-if-true1}, else examine further tests. If no test
10703 exits with a zero status, run shell code @var{run-if-false}, with
10704 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10705 is empty. For example,
10708 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10709 [test "$foo" != no], [HANDLE_FOO([maybe])],
10710 [echo foo not specified])
10714 ensures any required macros of @code{HANDLE_FOO}
10715 are expanded before the first test.
10718 @defmac AS_MKDIR_P (@var{file-name})
10720 Make the directory @var{file-name}, including intervening directories
10721 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10722 except that it is portable to older versions of @command{mkdir} that
10723 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10724 succeeds if @var{file-name} is a symbolic link to an existing directory,
10725 even though Posix is unclear whether @samp{mkdir -p} should
10726 succeed in that case. If creation of @var{file-name} fails, exit the
10729 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10732 @defmac AS_SHELL_SANITIZE
10733 @asindex{SHELL_SANITIZE}
10734 Initialize the shell suitably for @code{configure} scripts. This has
10735 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10736 environment variables for predictable results from configuration tests.
10737 For example, it sets @env{LC_ALL} to change to the default C locale.
10738 @xref{Special Shell Variables}.
10741 @defmac AS_TR_CPP (@var{expression})
10743 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10747 # This outputs "#define HAVE_CHAR_P 1".
10749 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10753 @defmac AS_TR_SH (@var{expression})
10755 Transform @var{expression} into a valid shell variable name. For example:
10758 # This outputs "Have it!".
10759 header="sys/some file.h"
10760 AS_TR_SH([HAVE_$header])=yes
10761 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10765 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10766 @asindex{SET_CATFILE}
10767 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10768 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10769 @var{file} is absolute, etc.).
10773 @node File Descriptor Macros
10774 @section File Descriptor Macros
10776 @cindex standard input
10777 @cindex file descriptors
10778 @cindex descriptors
10779 @cindex low-level output
10780 @cindex output, low-level
10782 The following macros define file descriptors used to output messages
10783 (or input values) from @file{configure} scripts.
10787 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10788 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10789 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10793 However doing so is seldom needed, because Autoconf provides higher
10794 level macros as described below.
10796 @defmac AS_MESSAGE_FD
10797 @asindex{MESSAGE_FD}
10798 The file descriptor for @samp{checking for...} messages and results.
10799 Normally this directs messages to the standard output, however when
10800 @command{configure} is run with the @option{-q} option, messages sent to
10801 @code{AS_MESSAGE_FD} are discarded.
10803 If you want to display some messages, consider using one of the printing
10804 macros (@pxref{Printing Messages}) instead. Copies of messages output
10805 via these macros are also recorded in @file{config.log}.
10808 @defmac AS_MESSAGE_LOG_FD
10809 @asindex{MESSAGE_LOG_FD}
10811 The file descriptor for messages logged to @file{config.log}. Macros
10812 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10813 Compiler}), redirect all output to this descriptor. You may want to do
10814 so if you develop such a low-level macro.
10817 @defmac AS_ORIGINAL_STDIN_FD
10818 @asindex{ORIGINAL_STDIN_FD}
10819 The file descriptor for the original standard input.
10821 When @command{configure} runs, it may accidentally execute an
10822 interactive command that has the same name as the non-interactive meant
10823 to be used or checked. If the standard input was the terminal, such
10824 interactive programs would cause @command{configure} to stop, pending
10825 some user input. Therefore @command{configure} redirects its standard
10826 input from @file{/dev/null} during its initialization. This is not
10827 normally a problem, since @command{configure} normally does not need
10830 In the extreme case where your @file{configure} script really needs to
10831 obtain some values from the original standard input, you can read them
10832 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10836 @c =================================================== Writing Autoconf Macros.
10838 @node Writing Autoconf Macros
10839 @chapter Writing Autoconf Macros
10841 When you write a feature test that could be applicable to more than one
10842 software package, the best thing to do is encapsulate it in a new macro.
10843 Here are some instructions and guidelines for writing Autoconf macros.
10846 * Macro Definitions:: Basic format of an Autoconf macro
10847 * Macro Names:: What to call your new macros
10848 * Reporting Messages:: Notifying @command{autoconf} users
10849 * Dependencies Between Macros:: What to do when macros depend on other macros
10850 * Obsoleting Macros:: Warning about old ways of doing things
10851 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10854 @node Macro Definitions
10855 @section Macro Definitions
10858 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10859 similar to the M4 builtin @code{m4_define} macro. In addition to
10860 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10861 constrain the order in which macros are called (@pxref{Prerequisite
10864 An Autoconf macro definition looks like this:
10867 AC_DEFUN(@var{macro-name}, @var{macro-body})
10870 You can refer to any arguments passed to the macro as @samp{$1},
10871 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10872 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10874 Be sure to properly quote both the @var{macro-body} @emph{and} the
10875 @var{macro-name} to avoid any problems if the macro happens to have
10876 been previously defined.
10878 Each macro should have a header comment that gives its prototype, and a
10879 brief description. When arguments have default values, display them in
10880 the prototype. For example:
10883 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10884 # --------------------------------------
10885 m4_define([AC_MSG_ERROR],
10886 [@{ AS_MESSAGE([error: $1], [2])
10887 exit m4_default([$2], [1]); @}])
10890 Comments about the macro should be left in the header comment. Most
10891 other comments make their way into @file{configure}, so just keep
10892 using @samp{#} to introduce comments.
10895 If you have some special comments about pure M4 code, comments
10896 that make no sense in @file{configure} and in the header comment, then
10897 use the builtin @code{dnl}: it causes M4 to discard the text
10898 through the next newline.
10900 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10901 @code{dnl} is more useful to get rid of the newlines following macros
10902 that produce no output, such as @code{AC_REQUIRE}.
10906 @section Macro Names
10908 All of the public Autoconf macros have all-uppercase names in the
10909 namespace @samp{^AC_} to prevent them from accidentally conflicting with
10910 other text; Autoconf also reserves the namespace @samp{^_AC_} for
10911 internal macros. All shell variables that they use for internal
10912 purposes have mostly-lowercase names starting with @samp{ac_}. Autoconf
10913 also uses here-doc delimiters in the namespace @samp{^_AC[A-Z]}. During
10914 @command{configure}, files produced by Autoconf make heavy use of the
10915 file system namespace @samp{^conf}.
10917 Since Autoconf is built on top of M4sugar (@pxref{Programming in
10918 M4sugar}) and M4sh (@pxref{Programming in M4sh}), you must also be aware
10919 of those namespaces (@samp{^_?\(m4\|AS\)_}). And since
10920 @file{configure.ac} is also designed to be scanned by Autoheader,
10921 Autoscan, Autoupdate, and Automake, you should be aware of the
10922 @samp{^_?A[HNUM]_} namespaces. In general, you @emph{should not use}
10923 the namespace of a package that does not own the macro or shell code you
10926 To ensure that your macros don't conflict with present or future
10927 Autoconf macros, you should prefix your own macro names and any shell
10928 variables they use with some other sequence. Possibilities include your
10929 initials, or an abbreviation for the name of your organization or
10930 software package. Historically, people have not always followed the
10931 rule of using a namespace appropriate for their package, and this has
10932 made it difficult for determining the origin of a macro (and where to
10933 report bugs about that macro), as well as difficult for the true
10934 namespace owner to add new macros without interference from pre-existing
10935 uses of third-party macros. Perhaps the best example of this confusion
10936 is the @code{AM_GNU_GETTEXT} macro, which belongs, not to Automake, but
10939 Most of the Autoconf macros' names follow a structured naming convention
10940 that indicates the kind of feature check by the name. The macro names
10941 consist of several words, separated by underscores, going from most
10942 general to most specific. The names of their cache variables use the
10943 same convention (@pxref{Cache Variable Names}, for more information on
10946 The first word of the name after the namepace initials (such as
10947 @samp{AC_}) usually tells the category
10948 of the feature being tested. Here are the categories used in Autoconf for
10949 specific test macros, the kind of macro that you are more likely to
10950 write. They are also used for cache variables, in all-lowercase. Use
10951 them where applicable; where they're not, invent your own categories.
10955 C language builtin features.
10957 Declarations of C variables in header files.
10959 Functions in libraries.
10961 Posix group owners of files.
10967 The base names of programs.
10969 Members of aggregates.
10971 Operating system features.
10973 C builtin or declared types.
10975 C variables in libraries.
10978 After the category comes the name of the particular feature being
10979 tested. Any further words in the macro name indicate particular aspects
10980 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
10981 C compiler supports @acronym{ISO} Standard C.
10983 An internal macro should have a name that starts with an underscore;
10984 Autoconf internals should therefore start with @samp{_AC_}.
10985 Additionally, a macro that is an internal subroutine of another macro
10986 should have a name that starts with an underscore and the name of that
10987 other macro, followed by one or more words saying what the internal
10988 macro does. For example, @code{AC_PATH_X} has internal macros
10989 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10991 @node Reporting Messages
10992 @section Reporting Messages
10993 @cindex Messages, from @command{autoconf}
10995 When macros statically diagnose abnormal situations, benign or fatal,
10996 they should report them using these macros. For dynamic issues, i.e.,
10997 when @command{configure} is run, see @ref{Printing Messages}.
10999 @defmac AC_DIAGNOSE (@var{category}, @var{message})
11001 Report @var{message} as a warning (or as an error if requested by the
11002 user) if warnings of the @var{category} are turned on. You are
11003 encouraged to use standard categories, which currently include:
11007 messages that don't fall into one of the following categories. Use of an
11008 empty @var{category} is equivalent.
11011 related to cross compilation issues.
11014 use of an obsolete construct.
11017 dubious syntactic constructs, incorrectly ordered macro calls.
11021 @defmac AC_WARNING (@var{message})
11023 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
11024 strongly encouraged to use a finer grained category.
11027 @defmac AC_FATAL (@var{message})
11029 Report a severe error @var{message}, and have @command{autoconf} die.
11032 When the user runs @samp{autoconf -W error}, warnings from
11033 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
11034 @ref{autoconf Invocation}.
11036 @node Dependencies Between Macros
11037 @section Dependencies Between Macros
11038 @cindex Dependencies between macros
11040 Some Autoconf macros depend on other macros having been called first in
11041 order to work correctly. Autoconf provides a way to ensure that certain
11042 macros are called if needed and a way to warn the user if macros are
11043 called in an order that might cause incorrect operation.
11046 * Prerequisite Macros:: Ensuring required information
11047 * Suggested Ordering:: Warning about possible ordering problems
11048 * One-Shot Macros:: Ensuring a macro is called only once
11051 @node Prerequisite Macros
11052 @subsection Prerequisite Macros
11053 @cindex Prerequisite macros
11054 @cindex Macros, prerequisites
11056 A macro that you write might need to use values that have previously
11057 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
11058 examines the output of @code{flex} or @code{lex}, so it depends on
11059 @code{AC_PROG_LEX} having been called first to set the shell variable
11062 Rather than forcing the user of the macros to keep track of the
11063 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
11064 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
11065 called if it is needed, and only called once.
11067 @defmac AC_REQUIRE (@var{macro-name})
11069 If the M4 macro @var{macro-name} has not already been called, call it
11070 (without any arguments). Make sure to quote @var{macro-name} with
11071 square brackets. @var{macro-name} must have been defined using
11072 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
11073 that it has been called.
11075 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
11076 must not be called from the top level.
11079 @code{AC_REQUIRE} is often misunderstood. It really implements
11080 dependencies between macros in the sense that if one macro depends upon
11081 another, the latter is expanded @emph{before} the body of the
11082 former. To be more precise, the required macro is expanded before
11083 the outermost defined macro in the current expansion stack.
11084 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
11085 @code{FOO}. For instance, this definition of macros:
11089 AC_DEFUN([TRAVOLTA],
11090 [test "$body_temperature_in_celsius" -gt "38" &&
11091 dance_floor=occupied])
11092 AC_DEFUN([NEWTON_JOHN],
11093 [test "$hair_style" = "curly" &&
11094 dance_floor=occupied])
11098 AC_DEFUN([RESERVE_DANCE_FLOOR],
11099 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
11100 AC_REQUIRE([TRAVOLTA])
11101 AC_REQUIRE([NEWTON_JOHN])
11107 with this @file{configure.ac}
11110 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
11111 RESERVE_DANCE_FLOOR
11112 if test "$dance_floor" = occupied; then
11113 AC_MSG_ERROR([cannot pick up here, let's move])
11118 does not leave you with a better chance to meet a kindred soul at
11119 other times than Saturday night since it expands into:
11123 test "$body_temperature_in_Celsius" -gt "38" &&
11124 dance_floor=occupied
11125 test "$hair_style" = "curly" &&
11126 dance_floor=occupied
11128 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
11135 This behavior was chosen on purpose: (i) it prevents messages in
11136 required macros from interrupting the messages in the requiring macros;
11137 (ii) it avoids bad surprises when shell conditionals are used, as in:
11142 AC_REQUIRE([SOME_CHECK])
11149 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
11150 enforce expansion of required macros outside of shell conditional
11151 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
11152 at the beginning of a macro. You can use @code{dnl} to avoid the empty
11155 @node Suggested Ordering
11156 @subsection Suggested Ordering
11157 @cindex Macros, ordering
11158 @cindex Ordering macros
11160 Some macros should be run before another macro if both are called, but
11161 neither @emph{requires} that the other be called. For example, a macro
11162 that changes the behavior of the C compiler should be called before any
11163 macros that run the C compiler. Many of these dependencies are noted in
11166 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
11167 with this kind of dependency appear out of order in a
11168 @file{configure.ac} file. The warning occurs when creating
11169 @command{configure} from @file{configure.ac}, not when running
11170 @command{configure}.
11172 For example, @code{AC_PROG_CPP} checks whether the C compiler
11173 can run the C preprocessor when given the @option{-E} option. It should
11174 therefore be called after any macros that change which C compiler is
11175 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
11178 AC_BEFORE([$0], [AC_PROG_CPP])dnl
11182 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
11183 when @code{AC_PROG_CC} is called.
11185 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
11187 Make M4 print a warning message to the standard error output if
11188 @var{called-macro-name} has already been called. @var{this-macro-name}
11189 should be the name of the macro that is calling @code{AC_BEFORE}. The
11190 macro @var{called-macro-name} must have been defined using
11191 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
11192 that it has been called.
11195 @node One-Shot Macros
11196 @subsection One-Shot Macros
11197 @cindex One-shot macros
11198 @cindex Macros, called once
11200 Some macros should be called only once, either because calling them
11201 multiple time is unsafe, or because it is bad style. For instance
11202 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
11203 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
11204 sense to run these expensive checks more than once. Such one-shot
11205 macros can be defined using @code{AC_DEFUN_ONCE}.
11207 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
11208 @acindex{DEFUN_ONCE}
11210 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
11211 Definitions}), and emit a warning any time the macro is called more than
11215 Obviously it is not sensible to evaluate a macro defined by
11216 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
11217 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
11220 @node Obsoleting Macros
11221 @section Obsoleting Macros
11222 @cindex Obsoleting macros
11223 @cindex Macros, obsoleting
11225 Configuration and portability technology has evolved over the years.
11226 Often better ways of solving a particular problem are developed, or
11227 ad-hoc approaches are systematized. This process has occurred in many
11228 parts of Autoconf. One result is that some of the macros are now
11229 considered @dfn{obsolete}; they still work, but are no longer considered
11230 the best thing to do, hence they should be replaced with more modern
11231 macros. Ideally, @command{autoupdate} should replace the old macro calls
11232 with their modern implementation.
11234 Autoconf provides a simple means to obsolete a macro.
11237 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
11239 Define @var{old-macro} as @var{implementation}. The only difference
11240 with @code{AC_DEFUN} is that the user is warned that
11241 @var{old-macro} is now obsolete.
11243 If she then uses @command{autoupdate}, the call to @var{old-macro} is
11244 replaced by the modern @var{implementation}. @var{message} should
11245 include information on what to do after running @command{autoupdate};
11246 @command{autoupdate} prints it as a warning, and includes it
11247 in the updated @file{configure.ac} file.
11249 The details of this macro are hairy: if @command{autoconf} encounters an
11250 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
11251 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
11252 macros are expanded here, while all other macros are disabled and
11253 appear literally in the updated @file{configure.ac}.
11256 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
11258 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
11259 with the same parameters. This happens for example if the macro was renamed.
11263 @section Coding Style
11264 @cindex Coding style
11266 The Autoconf macros follow a strict coding style. You are encouraged to
11267 follow this style, especially if you intend to distribute your macro,
11268 either by contributing it to Autoconf itself, or via other means.
11270 The first requirement is to pay great attention to the quotation. For
11271 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
11273 Do not try to invent new interfaces. It is likely that there is a macro
11274 in Autoconf that resembles the macro you are defining: try to stick to
11275 this existing interface (order of arguments, default values, etc.). We
11276 @emph{are} conscious that some of these interfaces are not perfect;
11277 nevertheless, when harmless, homogeneity should be preferred over
11280 Be careful about clashes both between M4 symbols and between shell
11283 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
11284 you are unlikely to generate conflicts. Nevertheless, when you need to
11285 set a special value, @emph{avoid using a regular macro name}; rather,
11286 use an ``impossible'' name. For instance, up to version 2.13, the macro
11287 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
11288 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
11289 But since there is a macro named @code{AC_SUBST_FILE}, it was just
11290 impossible to @samp{AC_SUBST(FILE)}! In this case,
11291 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
11292 have been used (yes, with the parentheses).
11293 @c or better yet, high-level macros such as @code{m4_expand_once}
11295 No Autoconf macro should ever enter the user-variable name space; i.e.,
11296 except for the variables that are the actual result of running the
11297 macro, all shell variables should start with @code{ac_}. In
11298 addition, small macros or any macro that is likely to be embedded in
11299 other macros should be careful not to use obvious names.
11302 Do not use @code{dnl} to introduce comments: most of the comments you
11303 are likely to write are either header comments which are not output
11304 anyway, or comments that should make their way into @file{configure}.
11305 There are exceptional cases where you do want to comment special M4
11306 constructs, in which case @code{dnl} is right, but keep in mind that it
11309 M4 ignores the leading blanks and newlines before each argument.
11310 Use this feature to
11311 indent in such a way that arguments are (more or less) aligned with the
11312 opening parenthesis of the macro being called. For instance, instead of
11315 AC_CACHE_CHECK(for EMX OS/2 environment,
11317 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
11318 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
11325 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
11326 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
11327 [ac_cv_emxos2=yes],
11328 [ac_cv_emxos2=no])])
11335 AC_CACHE_CHECK([for EMX OS/2 environment],
11337 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
11338 [return __EMX__;])],
11339 [ac_cv_emxos2=yes],
11340 [ac_cv_emxos2=no])])
11343 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
11344 cross-compiling, provide a pessimistic value (typically @samp{no}).
11346 Feel free to use various tricks to prevent auxiliary tools, such as
11347 syntax-highlighting editors, from behaving improperly. For instance,
11351 m4_bpatsubst([$1], [$"])
11358 m4_bpatsubst([$1], [$""])
11362 so that Emacsen do not open an endless ``string'' at the first quote.
11363 For the same reasons, avoid:
11373 test $[@@%:@@] != 0
11377 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
11378 breaking the bracket-matching highlighting from Emacsen. Note the
11379 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
11380 not escape when it is unnecessary. Common examples of useless quotation
11381 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
11382 etc. If you add portability issues to the picture, you'll prefer
11383 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
11384 better than hacking Autoconf @code{:-)}.
11386 When using @command{sed}, don't use @option{-e} except for indenting
11387 purposes. With the @code{s} and @code{y} commands, the preferred
11388 separator is @samp{/} unless @samp{/} itself might appear in the pattern
11389 or replacement, in which case you should use @samp{|}, or optionally
11390 @samp{,} if you know the pattern and replacement cannot contain a file
11391 name. If none of these characters will do, choose a printable character
11392 that cannot appear in the pattern or replacement. Characters from the
11393 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
11394 replacement might contain a file name, since they have special meaning
11395 to the shell and are less likely to occur in file names.
11397 @xref{Macro Definitions}, for details on how to define a macro. If a
11398 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
11399 of an @code{AC_REQUIRE} directive, and macros required by other macros
11400 inside arguments do not need to be expanded before this macro, then
11401 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
11402 All the @code{AC_REQUIRE} statements should be at the beginning of the
11403 macro, and each statement should be followed by @code{dnl}.
11405 You should not rely on the number of arguments: instead of checking
11406 whether an argument is missing, test that it is not empty. It provides
11407 both a simpler and a more predictable interface to the user, and saves
11408 room for further arguments.
11410 Unless the macro is short, try to leave the closing @samp{])} at the
11411 beginning of a line, followed by a comment that repeats the name of the
11412 macro being defined. This introduces an additional newline in
11413 @command{configure}; normally, that is not a problem, but if you want to
11414 remove it you can use @samp{[]dnl} on the last line. You can similarly
11415 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
11416 is recommended instead of @samp{dnl} to ensure that M4 does not
11417 interpret the @samp{dnl} as being attached to the preceding text or
11418 macro output. For example, instead of:
11421 AC_DEFUN([AC_PATH_X],
11422 [AC_MSG_CHECKING([for X])
11424 @r{# @dots{}omitted@dots{}}
11425 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
11433 AC_DEFUN([AC_PATH_X],
11434 [AC_REQUIRE_CPP()[]dnl
11435 AC_MSG_CHECKING([for X])
11436 @r{# @dots{}omitted@dots{}}
11437 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
11442 If the macro is long, try to split it into logical chunks. Typically,
11443 macros that check for a bug in a function and prepare its
11444 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
11445 this setup. Do not hesitate to introduce auxiliary macros to factor
11448 In order to highlight the recommended coding style, here is a macro
11449 written the old way:
11452 dnl Check for EMX on OS/2.
11454 AC_DEFUN(_AC_EMXOS2,
11455 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
11456 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
11457 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
11458 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
11467 # Check for EMX on OS/2.
11468 m4_define([_AC_EMXOS2],
11469 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
11470 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
11471 [ac_cv_emxos2=yes],
11472 [ac_cv_emxos2=no])])
11473 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
11480 @c ============================================= Portable Shell Programming
11482 @node Portable Shell
11483 @chapter Portable Shell Programming
11484 @cindex Portable shell programming
11486 When writing your own checks, there are some shell-script programming
11487 techniques you should avoid in order to make your code portable. The
11488 Bourne shell and upward-compatible shells like the Korn shell and Bash
11489 have evolved over the years, but to prevent trouble, do not take
11490 advantage of features that were added after Unix version 7, circa
11491 1977 (@pxref{Systemology}).
11493 You should not use aliases, negated character classes, or other features
11494 that are not found in all Bourne-compatible shells; restrict yourself
11495 to the lowest common denominator. Even @code{unset} is not supported
11498 Shell functions are considered portable nowadays, though Autoconf
11499 still does not use them (Autotest does). However, inside a shell
11500 function you should not be using @code{$?} to check the return code
11501 of a subshell invocation; in general, since the caller of a shell
11502 function might look at the function's return code, make sure that the
11503 last statement of a shell function does not invoke a subshell.
11504 Using subshells triggers bugs in zsh 4.x; while Autoconf tries
11505 to find a shell that does not exhibit the bug, zsh might be the
11506 only shell present on the user's machine.
11508 Some ancient systems have quite
11509 small limits on the length of the @samp{#!} line; for instance, 32
11510 bytes (not including the newline) on SunOS 4.
11511 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
11512 required a single space between the @samp{#!} and the @samp{/}.
11513 However, these ancient systems are no longer of practical concern.
11515 The set of external programs you should run in a @command{configure} script
11516 is fairly small. @xref{Utilities in Makefiles, , Utilities in
11517 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
11518 restriction allows users to start out with a fairly small set of
11519 programs and build the rest, avoiding too many interdependencies between
11522 Some of these external utilities have a portable subset of features; see
11523 @ref{Limitations of Usual Tools}.
11525 There are other sources of documentation about shells. The
11526 specification for the Posix
11527 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
11528 Command Language}, though more generous than the restrictive shell
11529 subset described above, is fairly portable nowadays. Also please see
11530 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
11533 * Shellology:: A zoology of shells
11534 * Here-Documents:: Quirks and tricks
11535 * File Descriptors:: FDs and redirections
11536 * File System Conventions:: File names
11537 * Shell Pattern Matching:: Pattern matching
11538 * Shell Substitutions:: Variable and command expansions
11539 * Assignments:: Varying side effects of assignments
11540 * Parentheses:: Parentheses in shell scripts
11541 * Slashes:: Slashes in shell scripts
11542 * Special Shell Variables:: Variables you should not change
11543 * Limitations of Builtins:: Portable use of not so portable /bin/sh
11544 * Limitations of Usual Tools:: Portable use of portable tools
11548 @section Shellology
11551 There are several families of shells, most prominently the Bourne family
11552 and the C shell family which are deeply incompatible. If you want to
11553 write portable shell scripts, avoid members of the C shell family. The
11554 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
11555 Shell difference FAQ} includes a small history of Posix shells, and a
11556 comparison between several of them.
11558 Below we describe some of the members of the Bourne shell family.
11563 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
11564 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
11565 bugs that are fixed in the 0.3.x series, but portable shell scripts
11566 should work around them, since version 0.2 is still shipped with many
11567 @acronym{GNU}/Linux distributions.
11569 To be compatible with Ash 0.2:
11573 don't use @samp{$?} after expanding empty or unset variables,
11574 or at the start of an @command{eval}:
11580 echo "Do not use it: $?"
11582 eval 'echo "Do not use it: $?"'
11586 don't use command substitution within variable expansion:
11593 beware that single builtin substitutions are not performed by a
11594 subshell, hence their effect applies to the current shell! @xref{Shell
11595 Substitutions}, item ``Command Substitution''.
11600 To detect whether you are running Bash, test whether
11601 @code{BASH_VERSION} is set. To require
11602 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
11603 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11604 Manual}, for details.
11606 @item Bash 2.05 and later
11607 @cindex Bash 2.05 and later
11608 Versions 2.05 and later of Bash use a different format for the
11609 output of the @command{set} builtin, designed to make evaluating its
11610 output easier. However, this output is not compatible with earlier
11611 versions of Bash (or with many other shells, probably). So if
11612 you use Bash 2.05 or higher to execute @command{configure},
11613 you'll need to use Bash 2.05 for all other build tasks as well.
11618 @prindex @samp{ksh}
11619 @prindex @samp{ksh88}
11620 @prindex @samp{ksh93}
11621 The Korn shell is compatible with the Bourne family and it mostly
11622 conforms to Posix. It has two major variants commonly
11623 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11624 release. It is usually called @command{ksh}, but is called @command{sh}
11625 on some hosts if you set your path appropriately.
11627 Solaris systems have three variants:
11628 @prindex @command{/usr/bin/ksh} on Solaris
11629 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11630 standard on Solaris 2.0 and later.
11631 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11632 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11633 @samp{ksh88}; it is standard on Solaris 9 and later.
11634 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11635 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11636 Variants that are not standard may be parts of optional
11637 packages. There is no extra charge for these packages, but they are
11638 not part of a minimal OS install and therefore some installations may
11641 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11642 is also available as @command{/usr/bin/posix/sh}. If the environment
11643 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11644 the standard shell conform to Posix.
11647 @prindex @samp{pdksh}
11648 A public-domain clone of the Korn shell called @command{pdksh} is widely
11649 available: it has most of the @samp{ksh88} features along with a few of
11650 its own. It usually sets @code{KSH_VERSION}, except if invoked as
11651 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11652 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
11653 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
11654 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11655 at least one respect:
11658 $ @kbd{echo "`echo \"hello\"`"}
11660 $ @kbd{set -o posix}
11661 $ @kbd{echo "`echo \"hello\"`"}
11665 The last line of output contains spurious quotes. This is yet another
11666 reason why portable shell code should not contain
11667 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11672 To detect whether you are running @command{zsh}, test whether
11673 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
11674 compatible with the Bourne shell: you must execute @samp{emulate sh},
11675 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11676 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
11677 zsh, The Z Shell Manual}, for details.
11679 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11680 Bash in Mac OS X 10.2.
11683 The following discussion between Russ Allbery and Robert Lipe is worth
11690 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11691 leads to a permanent deadlock. Vendors don't want to break users'
11692 existing shell scripts, and there are some corner cases in the Bourne
11693 shell that are not completely compatible with a Posix shell. Thus,
11694 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11695 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11703 This is exactly the problem. While most (at least most System V's) do
11704 have a Bourne shell that accepts shell functions most vendor
11705 @command{/bin/sh} programs are not the Posix shell.
11707 So while most modern systems do have a shell @emph{somewhere} that meets the
11708 Posix standard, the challenge is to find it.
11711 @node Here-Documents
11712 @section Here-Documents
11713 @cindex Here-documents
11714 @cindex Shell here-documents
11716 Don't rely on @samp{\} being preserved just because it has no special
11717 meaning together with the next symbol. In the native @command{sh}
11718 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11719 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11720 use @samp{\\} to get @samp{\}.
11722 With Open@acronym{BSD} 2.7's @command{sh}
11738 bash-2.04$ @kbd{cat <<EOF
11745 Some shells mishandle large here-documents: for example,
11746 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11747 derived from Korn shell version M-12/28/93d, mishandle braced variable
11748 expansion that crosses a 1024- or 4096-byte buffer boundary
11749 within a here-document. Only the part of the variable name after the boundary
11750 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11751 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11752 boundary, the shell reports an error, as if you used @code{$@{@}}.
11753 Instead of @code{$@{variable-default@}}, the shell may expand
11754 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11755 be worked around by omitting the braces: @code{$variable}. The bug was
11757 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11758 still shipping older versions with the bug.
11760 Many shells (including the Bourne shell) implement here-documents
11761 inefficiently. In particular, some shells can be extremely inefficient when
11762 a single statement contains many here-documents. For instance if your
11763 @file{configure.ac} includes something like:
11767 if <cross_compiling>; then
11768 assume this and that
11772 check something else
11780 A shell parses the whole @code{if}/@code{fi} construct, creating
11781 temporary files for each here-document in it. Some shells create links
11782 for such here-documents on every @code{fork}, so that the clean-up code
11783 they had installed correctly removes them. It is creating the links
11784 that can take the shell forever.
11786 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11787 @code{if}/@code{fi} constructs, would improve the performance
11788 significantly. Anyway, this kind of construct is not exactly the
11789 typical use of Autoconf. In fact, it's even not recommended, because M4
11790 macros can't look into shell conditionals, so we may fail to expand a
11791 macro when it was expanded before in a conditional path, and the
11792 condition turned out to be false at runtime, and we end up not
11793 executing the macro at all.
11795 @node File Descriptors
11796 @section File Descriptors
11797 @cindex Descriptors
11798 @cindex File descriptors
11799 @cindex Shell file descriptors
11801 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11802 stderr, even for subshells. This might result in undesirable content
11803 if you meant to capture the standard-error output of the inner command:
11806 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11808 + eval echo foo >&2
11811 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11813 + eval 'echo foo >&2'
11816 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11817 @i{# Traces on startup files deleted here.}
11819 +zsh:1> eval echo foo >&2
11825 One workaround is to grep out uninteresting lines, hoping not to remove
11828 If you intend to redirect both standard error and standard output,
11829 redirect standard output first. This works better with @acronym{HP-UX},
11830 since its shell mishandles tracing if standard error is redirected
11834 $ @kbd{sh -x -c ': 2>err >out'}
11836 + 2> err $ @kbd{cat err}
11840 Don't try to redirect the standard error of a command substitution. It
11841 must be done @emph{inside} the command substitution. When running
11842 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11843 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11845 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11846 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11848 When catering to old systems, don't redirect the same file descriptor
11849 several times, as you are doomed to failure under Ultrix.
11852 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11854 $ @kbd{eval 'echo matter >fullness' >void}
11856 $ @kbd{eval '(echo matter >fullness)' >void}
11858 $ @kbd{(eval '(echo matter >fullness)') >void}
11859 Ambiguous output redirect.
11863 In each case the expected result is of course @file{fullness} containing
11864 @samp{matter} and @file{void} being empty. However, this bug is
11865 probably not of practical concern to modern platforms.
11867 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11868 subsidiary program. If any of these descriptors is closed, the
11869 operating system may open an unspecified file for the descriptor in the
11870 new process image. Posix says this may be done only if the subsidiary
11871 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does
11872 it even for ordinary programs.
11874 Don't rely on open file descriptors being open in child processes. In
11875 @command{ksh}, file descriptors above 2 which are opened using
11876 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11877 that involved in the fork-and-exec which runs a program or script).
11878 Thus, using @command{sh}, we have:
11881 $ @kbd{cat ./descrips}
11903 Within the process which runs the @samp{descrips} script, file
11904 descriptor 5 is closed.
11906 @acronym{DOS} variants cannot rename or remove open files, such as in
11907 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11908 perfectly portable among Posix hosts.
11910 A few ancient systems reserved some file descriptors. By convention,
11911 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11912 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11913 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11914 1990), though we don't now remember what it was. Both these systems are
11915 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11916 other file descriptors.
11918 @node File System Conventions
11919 @section File System Conventions
11920 @cindex File system conventions
11922 Autoconf uses shell-script processing extensively, so the file names
11923 that it processes should not contain characters that are special to the
11924 shell. Special characters include space, tab, newline, @sc{nul}, and
11928 " # $ & ' ( ) * ; < = > ? [ \ ` |
11931 Also, file names should not begin with @samp{~} or @samp{-}, and should
11932 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11933 immediately after @samp{:}. On Posix-like platforms, directory names
11934 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11937 These restrictions apply not only to the files that you distribute, but
11938 also to the absolute file names of your source, build, and destination
11941 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11942 they should be avoided.
11944 Posix lets implementations treat leading @file{//} specially, but
11945 requires leading @file{///} and beyond to be equivalent to @file{/}.
11946 Most Unix variants treat @file{//} like @file{/}. However, some treat
11947 @file{//} as a ``super-root'' that can provide access to files that are
11948 not otherwise reachable from @file{/}. The super-root tradition began
11949 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11952 While @command{autoconf} and friends are usually run on some Posix
11953 variety, they can be used on other systems, most notably @acronym{DOS}
11954 variants. This impacts several assumptions regarding file names.
11957 For example, the following code:
11964 foo_dir=$dots$foo_dir ;;
11969 fails to properly detect absolute file names on those systems, because
11970 they can use a drivespec, and usually use a backslash as directory
11971 separator. If you want to be portable to @acronym{DOS} variants (at the
11972 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11973 you can check for absolute file names like this:
11975 @cindex absolute file names, detect
11978 [\\/]* | ?:[\\/]* ) # Absolute
11981 foo_dir=$dots$foo_dir ;;
11986 Make sure you quote the brackets if appropriate and keep the backslash as
11987 first character (@pxref{Limitations of Builtins}).
11989 Also, because the colon is used as part of a drivespec, these systems don't
11990 use it as path separator. When creating or accessing paths, you can use the
11991 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11992 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
11995 File names need extra care as well. While @acronym{DOS} variants
11996 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11997 are usually able to handle long file names properly, there are still
11998 limitations that can seriously break packages. Several of these issues
11999 can be easily detected by the
12000 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
12003 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
12004 indicate where they apply: @sc{sfn} means the issues are only relevant to
12005 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
12006 variants, while @sc{lfn} identifies problems that exist even under
12007 Microsoft Windows variants.
12010 @item No multiple dots (@sc{sfn})
12011 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
12012 important thing to remember when building a portable configure script,
12013 as @command{autoconf} uses a .in suffix for template files.
12015 This is perfectly OK on Posix variants:
12018 AC_CONFIG_HEADERS([config.h])
12019 AC_CONFIG_FILES([source.c foo.bar])
12024 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
12025 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
12026 to @acronym{DOS}-based environments, you should use this instead:
12029 AC_CONFIG_HEADERS([config.h:config.hin])
12030 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
12034 @item No leading dot (@sc{sfn})
12035 @acronym{DOS} cannot handle file names that start with a dot. This is usually
12036 not important for @command{autoconf}.
12038 @item Case insensitivity (@sc{lfn})
12039 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
12040 file called @samp{INSTALL} and a directory called @samp{install}. This
12041 also affects @command{make}; if there's a file called @samp{INSTALL} in
12042 the directory, @samp{make install} does nothing (unless the
12043 @samp{install} target is marked as PHONY).
12045 @item The 8+3 limit (@sc{sfn})
12046 Because the @acronym{DOS} file system only stores the first 8 characters of
12047 the file name and the first 3 of the extension, those must be unique.
12048 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
12049 @file{foobar-prettybird.c} all resolve to the same file name
12050 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
12051 @file{foo.bartender}.
12053 The 8+3 limit is not usually a problem under Microsoft Windows, as it
12055 tails in the short version of file names to make them unique. However, a
12056 registry setting can turn this behavior off. While this makes it
12057 possible to share file trees containing long file names between @sc{sfn}
12058 and @sc{lfn} environments, it also means the above problem applies there
12061 @item Invalid characters (@sc{lfn})
12062 Some characters are invalid in @acronym{DOS} file names, and should therefore
12063 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
12064 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
12065 In a @sc{sfn} environment, other characters are also invalid. These
12066 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
12068 @item Invalid names (@sc{lfn})
12069 Some @acronym{DOS} file names are reserved, and cause problems if you
12070 try to use files with those names. These names include @file{CON},
12071 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
12072 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
12073 File names are case insensitive, so even names like
12074 @file{aux/config.guess} are disallowed.
12078 @node Shell Pattern Matching
12079 @section Shell Pattern Matching
12080 @cindex Shell pattern matching
12082 Nowadays portable patterns can use negated character classes like
12083 @samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
12084 some shells but not others; hence portable scripts should never use
12085 @samp{^} as the first character of a bracket pattern.
12087 Outside the C locale, patterns like @samp{[a-z]} are problematic since
12088 they may match characters that are not lower-case letters.
12090 @node Shell Substitutions
12091 @section Shell Substitutions
12092 @cindex Shell substitutions
12094 Contrary to a persistent urban legend, the Bourne shell does not
12095 systematically split variables and back-quoted expressions, in particular
12096 on the right-hand side of assignments and in the argument of @code{case}.
12097 For instance, the following code:
12100 case "$given_srcdir" in
12101 .) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;;
12102 *) top_srcdir="$dots$given_srcdir" ;;
12107 is more readable when written as:
12110 case $given_srcdir in
12111 .) top_srcdir=`echo "$dots" | sed 's|/$||'` ;;
12112 *) top_srcdir=$dots$given_srcdir ;;
12117 and in fact it is even @emph{more} portable: in the first case of the
12118 first attempt, the computation of @code{top_srcdir} is not portable,
12119 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
12120 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
12121 the same way. There is just no portable way to use double-quoted
12122 strings inside double-quoted back-quoted expressions (pfew!).
12126 @cindex @samp{"$@@"}
12127 One of the most famous shell-portability issues is related to
12128 @samp{"$@@"}. When there are no positional arguments, Posix says
12129 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
12130 original Unix version 7 Bourne shell treated it as equivalent to
12131 @samp{""} instead, and this behavior survives in later implementations
12132 like Digital Unix 5.0.
12134 The traditional way to work around this portability problem is to use
12135 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
12136 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
12137 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
12140 zsh $ @kbd{emulate sh}
12141 zsh $ @kbd{for i in "$@@"; do echo $i; done}
12144 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
12151 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
12152 @samp{"$@@"} because of the portability problems mentioned above.
12153 One workaround relies on Zsh's ``global aliases'' to convert
12154 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
12157 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
12160 Zsh only recognizes this alias when a shell word matches it exactly;
12161 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
12162 case always yields at least one shell word, use plain @samp{"$@@"}.
12164 A more conservative workaround is to avoid @samp{"$@@"} if it is
12165 possible that there may be no positional arguments. For example,
12169 cat conftest.c "$@@"
12172 you can use this instead:
12176 0) cat conftest.c;;
12177 *) cat conftest.c "$@@";;
12181 Autoconf macros often use the @command{set} command to update
12182 @samp{$@@}, so if you are writing shell code intended for
12183 @command{configure} you should not assume that the value of @samp{$@@}
12184 persists for any length of time.
12188 @cindex positional parameters
12189 The 10th, 11th, @dots{} positional parameters can be accessed only after
12190 a @code{shift}. The 7th Edition shell reported an error if given
12191 @code{$@{10@}}, and
12192 Solaris 10 @command{/bin/sh} still acts that way:
12195 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
12196 $ @kbd{echo $@{10@}}
12200 @item $@{@var{var}:-@var{value}@}
12201 @c Info cannot handle `:' in index entries.
12202 @c @cindex $@{@var{var}:-@var{value}@}
12203 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
12204 colon for any shell substitution, and complain and die.
12205 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
12207 @item $@{@var{var}=@var{literal}@}
12208 @cindex $@{@var{var}=@var{literal}@}
12212 : $@{var='Some words'@}
12216 otherwise some shells, such as on Digital Unix V 5.0, die because
12217 of a ``bad substitution''.
12221 Solaris @command{/bin/sh} has a frightening bug in its interpretation
12222 of this. Imagine you need set a variable to a string containing
12223 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
12224 when the affected variable was already set. This bug can be exercised
12229 $ @kbd{foo=$@{foo='@}'@}}
12232 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
12235 $ @kbd{foo=$@{foo='@}'@}}
12241 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
12242 though it is enclosed in single quotes. The problem doesn't happen
12243 using double quotes.
12245 @item $@{@var{var}=@var{expanded-value}@}
12246 @cindex $@{@var{var}=@var{expanded-value}@}
12252 : $@{var="$default"@}
12256 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
12257 each char is set. You don't observe the phenomenon using a simple
12258 @samp{echo $var} since apparently the shell resets the 8th bit when it
12259 expands $var. Here are two means to make this shell confess its sins:
12262 $ @kbd{cat -v <<EOF
12271 $ @kbd{set | grep '^var=' | cat -v}
12274 One classic incarnation of this bug is:
12278 : $@{list="$default"@}
12285 You'll get @samp{a b c} on a single line. Why? Because there are no
12286 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
12287 bit set, hence no IFS splitting is performed!!!
12289 One piece of good news is that Ultrix works fine with @samp{:
12290 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
12291 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
12294 The portable way out consists in using a double assignment, to switch
12295 the 8th bit twice on Ultrix:
12298 list=$@{list="$default"@}
12302 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
12306 test "$@{var+set@}" = set || var=@var{@{value@}}
12309 @item $@{#@var{var}@}
12310 @itemx $@{@var{var}%@var{word}@}
12311 @itemx $@{@var{var}%%@var{word}@}
12312 @itemx $@{@var{var}#@var{word}@}
12313 @itemx $@{@var{var}##@var{word}@}
12314 @cindex $@{#@var{var}@}
12315 @cindex $@{@var{var}%@var{word}@}
12316 @cindex $@{@var{var}%%@var{word}@}
12317 @cindex $@{@var{var}#@var{word}@}
12318 @cindex $@{@var{var}##@var{word}@}
12319 Posix requires support for these usages, but they do not work with many
12320 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
12322 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
12323 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
12324 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
12325 yields the empty string.
12328 @item `@var{commands}`
12329 @cindex `@var{commands}`
12330 @cindex Command Substitution
12331 Posix requires shells to trim all trailing newlines from command
12332 output before substituting it, so assignments like
12333 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
12334 @samp{$file} ends in a newline.
12336 While in general it makes no sense, do not substitute a single builtin
12337 with side effects, because Ash 0.2, trying to optimize, does not fork a
12338 subshell to perform the command.
12340 For instance, if you wanted to check that @command{cd} is silent, do not
12341 use @samp{test -z "`cd /`"} because the following can happen:
12346 $ @kbd{test -z "`cd /`" && pwd}
12351 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
12353 The MSYS shell leaves a stray byte in the expansion of a double-quoted
12354 command substitution of a native program, if the end of the substitution
12355 is not aligned with the end of the double quote. This may be worked
12356 around by inserting another pair of quotes:
12359 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
12360 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
12361 - broken differ: char 4, line 1
12365 @item $(@var{commands})
12366 @cindex $(@var{commands})
12367 This construct is meant to replace @samp{`@var{commands}`},
12368 and it has most of the problems listed under @code{`@var{commands}`}.
12370 This construct can be
12371 nested while this is impossible to do portably with back quotes.
12372 Unfortunately it is not yet universally supported. Most notably, even recent
12373 releases of Solaris don't support it:
12376 $ @kbd{showrev -c /bin/sh | grep version}
12377 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
12378 $ @kbd{echo $(echo blah)}
12379 syntax error: `(' unexpected
12383 nor does @sc{irix} 6.5's Bourne shell:
12386 IRIX firebird-image 6.5 07151432 IP22
12387 $ @kbd{echo $(echo blah)}
12391 If you do use @samp{$(@var{commands})}, make sure that the commands
12392 do not start with a parenthesis, as that would cause confusion with
12393 a different notation @samp{$((@var{expression}))} that in modern
12394 shells is an arithmetic expression not a command. To avoid the
12395 confusion, insert a space between the two opening parentheses.
12397 Avoid @var{commands} that contain unbalanced parentheses in
12398 here-documents, comments, or case statement patterns, as many shells
12399 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
12400 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
12403 echo $(case x in x) echo hello;; esac)
12408 Always quote @samp{^}, otherwise traditional shells such as
12409 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
12415 @section Assignments
12416 @cindex Shell assignments
12418 When setting several variables in a row, be aware that the order of the
12419 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
12420 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
12422 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
12424 Don't rely on the following to find @file{subdir/program}:
12427 PATH=subdir$PATH_SEPARATOR$PATH program
12431 as this does not work with Zsh 3.0.6. Use something like this
12435 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
12438 Don't rely on the exit status of an assignment: Ash 0.2 does not change
12439 the status and propagates that of the last statement:
12442 $ @kbd{false || foo=bar; echo $?}
12444 $ @kbd{false || foo=`:`; echo $?}
12449 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
12453 $ @kbd{foo=`exit 1`; echo $?}
12457 To assign default values, follow this algorithm:
12461 If the default value is a literal and does not contain any closing
12465 : $@{var='my literal'@}
12469 If the default value contains no closing brace, has to be expanded, and
12470 the variable being initialized is not intended to be IFS-split
12471 (i.e., it's not a list), then use:
12474 : $@{var="$default"@}
12478 If the default value contains no closing brace, has to be expanded, and
12479 the variable being initialized is intended to be IFS-split (i.e., it's a list),
12483 var=$@{var="$default"@}
12487 If the default value contains a closing brace, then use:
12490 test "$@{var+set@}" = set || var="has a '@}'"
12494 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
12495 doubt, just use the last form. @xref{Shell Substitutions}, items
12496 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
12500 @section Parentheses in Shell Scripts
12501 @cindex Shell parentheses
12503 Beware of two opening parentheses in a row, as many shell
12504 implementations treat them specially. Posix requires that the command
12505 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
12506 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
12507 expression equivalent to @samp{let "cat"}, and may or may not report an
12508 error when they detect that @samp{cat} is not a number. As another
12509 example, @samp{pdksh} 5.2.14 misparses the following code:
12512 if ((true) || false); then
12518 To work around this problem, insert a space between the two opening
12519 parentheses. There is a similar problem and workaround with
12520 @samp{$((}; see @ref{Shell Substitutions}.
12523 @section Slashes in Shell Scripts
12524 @cindex Shell slashes
12526 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
12527 arguments that contain two trailing slashes:
12530 $ @kbd{echo / // /// //// .// //.}
12533 $ @kbd{eval "echo \$x"}
12536 $ @kbd{echo abc | tr -t ab //}
12542 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
12543 variable is empty and the second double-quote is followed by a word that
12544 begins and ends with slash:
12547 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
12553 However, our understanding is that patches are available, so perhaps
12554 it's not worth worrying about working around these horrendous bugs.
12556 @node Special Shell Variables
12557 @section Special Shell Variables
12558 @cindex Shell variables
12559 @cindex Special shell variables
12561 Some shell variables should not be used, since they can have a deep
12562 influence on the behavior of the shell. In order to recover a sane
12563 behavior from the shell, some variables should be unset, but
12564 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
12565 fallback value is needed.
12567 As a general rule, shell variable names containing a lower-case letter
12568 are safe; you can define and use these variables without worrying about
12569 their effect on the underlying system, and without worrying about
12570 whether the shell changes them unexpectedly. (The exception is the
12571 shell variable @code{status}, as described below.)
12573 Here is a list of names that are known to cause trouble. This list is
12574 not exhaustive, but you should be safe if you avoid the name
12575 @code{status} and names containing only upper-case letters and
12578 @c Alphabetical order, case insensitive, `A' before `a'.
12581 Many shells reserve @samp{$_} for various purposes, e.g., the name of
12582 the last command executed.
12586 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
12587 the standard shell conform to Posix.
12591 When this variable is set it specifies a list of directories to search
12592 when invoking @code{cd} with a relative file name that did not start
12593 with @samp{./} or @samp{../}. Posix
12594 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
12595 is used successfully, @code{cd} prints the resulting absolute
12596 file name. Unfortunately this output can break idioms like
12597 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
12598 Also, many shells do not conform to this part of Posix; for
12599 example, @command{zsh} prints the result only if a directory name
12600 other than @file{.} was chosen from @env{CDPATH}.
12602 In practice the shells that have this problem also support
12603 @command{unset}, so you can work around the problem as follows:
12606 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
12609 You can also avoid output by ensuring that your directory name is
12610 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
12612 Autoconf-generated scripts automatically unset @env{CDPATH} if
12613 possible, so you need not worry about this problem in those scripts.
12617 In the MKS shell, case statements and file name generation are
12618 case-insensitive unless @env{DUALCASE} is nonzero.
12619 Autoconf-generated scripts export this variable when they start up.
12633 These variables should not matter for shell scripts, since they are
12634 supposed to affect only interactive shells. However, at least one
12635 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12636 whether it is interactive, which means that (for example) a @env{PS1}
12637 with a side effect can unexpectedly modify @samp{$?}. To work around
12638 this bug, Autoconf-generated scripts do something like this:
12641 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12648 The Korn shell uses @env{FPATH} to find shell functions, so avoid
12649 @env{FPATH} in portable scripts. @env{FPATH} is consulted after
12650 @env{PATH}, but you still need to be wary of tests that use @env{PATH}
12651 to find whether a command exists, since they might report the wrong
12652 result if @env{FPATH} is also set.
12656 Long ago, shell scripts inherited @env{IFS} from the environment,
12657 but this caused many problems so modern shells ignore any environment
12658 settings for @env{IFS}.
12660 Don't set the first character of @code{IFS} to backslash. Indeed,
12661 Bourne shells use the first character (backslash) when joining the
12662 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12663 backslash escapes, so you can end up with backspace and other strange
12666 The proper value for @code{IFS} (in regular code, not when performing
12667 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
12668 especially important, as it is used to join the arguments in @samp{$*};
12669 however, note that traditional shells, but also bash-2.04, fail to adhere
12670 to this and join with a space anyway.
12682 @evindex LC_COLLATE
12684 @evindex LC_MESSAGES
12685 @evindex LC_MONETARY
12686 @evindex LC_NUMERIC
12689 Autoconf-generated scripts normally set all these variables to
12690 @samp{C} because so much configuration code assumes the C locale and
12691 Posix requires that locale environment variables be set to
12692 @samp{C} if the C locale is desired. However, some older, nonstandard
12693 systems (notably @acronym{SCO}) break if locale environment variables
12694 are set to @samp{C}, so when running on these systems
12695 Autoconf-generated scripts unset the variables instead.
12700 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12701 extension that overrides @env{LC_ALL} in some cases, so
12702 Autoconf-generated scripts set it too.
12705 @itemx LC_IDENTIFICATION
12706 @itemx LC_MEASUREMENT
12709 @itemx LC_TELEPHONE
12710 @evindex LC_ADDRESS
12711 @evindex LC_IDENTIFICATION
12712 @evindex LC_MEASUREMENT
12715 @evindex LC_TELEPHONE
12717 These locale environment variables are @acronym{GNU} extensions. They
12718 are treated like their Posix brethren (@env{LC_COLLATE},
12719 etc.)@: as described above.
12722 Most modern shells provide the current line number in @code{LINENO}.
12723 Its value is the line number of the beginning of the current command.
12724 Autoconf attempts to execute @command{configure} with a shell that
12725 supports @code{LINENO}.
12726 If no such shell is available, it attempts to implement @code{LINENO}
12727 with a Sed prepass that replaces each instance of the string
12728 @code{$LINENO} (not followed by an alphanumeric character) with the
12731 You should not rely on @code{LINENO} within @command{eval}, as the
12732 behavior differs in practice. Also, the possibility of the Sed
12733 prepass means that you should not rely on @code{$LINENO} when quoted,
12734 when in here-documents, or when in long commands that cross line
12735 boundaries. Subshells should be OK, though. In the following
12736 example, lines 1, 6, and 9 are portable, but the other instances of
12737 @code{LINENO} are not:
12747 ( echo 6. $LINENO )
12748 eval 'echo 7. $LINENO'
12754 $ @kbd{bash-2.05 lineno}
12765 $ @kbd{zsh-3.0.6 lineno}
12776 $ @kbd{pdksh-5.2.14 lineno}
12787 $ @kbd{sed '=' <lineno |}
12793 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12796 > @kbd{ s,^[0-9]*\n,,}
12812 When executing the command @samp{>foo}, @command{zsh} executes
12813 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12814 compatibility mode and the @command{zsh} version is newer
12815 than 3.1.6-dev-18. If you are using an older @command{zsh}
12816 and forget to set @env{NULLCMD},
12817 your script might be suspended waiting for data on its standard input.
12819 @item PATH_SEPARATOR
12820 @evindex PATH_SEPARATOR
12821 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12822 variable can be set to either @samp{:} or @samp{;} to control the path
12823 separator Bash uses to set up certain environment variables (such as
12824 @env{PATH}). You can set this variable to @samp{;} if you want
12825 @command{configure} to use @samp{;} as a separator; this might be useful
12826 if you plan to use non-Posix shells to execute files. @xref{File System
12827 Conventions}, for more information about @code{PATH_SEPARATOR}.
12831 Posix 1003.1-2001 requires that @command{cd} and
12832 @command{pwd} must update the @env{PWD} environment variable to point
12833 to the logical name of the current directory, but traditional shells
12834 do not support this. This can cause confusion if one shell instance
12835 maintains @env{PWD} but a subsidiary and different shell does not know
12836 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12837 points to the wrong directory. Use @samp{`pwd`} rather than
12841 Many shells provide @code{RANDOM}, a variable that returns a different
12842 integer each time it is used. Most of the time, its value does not
12843 change when it is not used, but on @sc{irix} 6.5 the value changes all
12844 the time. This can be observed by using @command{set}. It is common
12845 practice to use @code{$RANDOM} as part of a file name, but code
12846 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12849 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12850 hence read-only. Do not use it.
12853 @node Limitations of Builtins
12854 @section Limitations of Shell Builtins
12855 @cindex Shell builtins
12856 @cindex Limitations of shell builtins
12858 No, no, we are serious: some shells do have limitations! :)
12860 You should always keep in mind that any builtin or command may support
12861 options, and therefore differ in behavior with arguments
12862 starting with a dash. For instance, the innocent @samp{echo "$word"}
12863 can give unexpected results when @code{word} starts with a dash. It is
12864 often possible to avoid this problem using @samp{echo "x$word"}, taking
12865 the @samp{x} into account later in the pipe.
12869 @prindex @command{.}
12870 Use @command{.} only with regular files (use @samp{test -f}). Bash
12871 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12872 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12873 you want to use @command{.} on a file @file{foo} in the current
12874 directory, you must use @samp{. ./foo}.
12877 @prindex @command{!}
12878 The Unix version 7 shell did not support
12879 negating the exit status of commands with @command{!}, and this feature
12880 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12881 Shell code like this:
12884 if ! cmp file1 file2 >/dev/null 2>&1; then
12885 echo files differ or trouble
12889 is therefore not portable in practice. Typically it is easy to rewrite
12893 cmp file1 file2 >/dev/null 2>&1 ||
12894 echo files differ or trouble
12897 More generally, one can always rewrite @samp{! @var{command}} as:
12900 if @var{command}; then (exit 1); else :; fi
12903 @item @command{break}
12904 @c ------------------
12905 @prindex @command{break}
12906 The use of @samp{break 2} etc.@: is safe.
12909 @item @command{case}
12910 @c -----------------
12911 @prindex @command{case}
12912 You don't need to quote the argument; no splitting is performed.
12914 You don't need the final @samp{;;}, but you should use it.
12916 Posix requires support for @code{case} patterns with opening
12917 parentheses like this:
12921 (*.c) echo "C source code";;
12926 but the @code{(} in this example is not portable to many Bourne
12927 shell implementations. It can be omitted safely.
12929 Zsh handles pattern fragments derived from parameter expansions or
12930 command substitutions as though quoted:
12933 $ pat=\?; case aa in ?$pat) echo match;; esac
12934 $ pat=\?; case a? in ?$pat) echo match;; esac
12939 Because of a bug in its @code{fnmatch}, Bash fails to properly
12940 handle backslashes in character classes:
12943 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12948 This is extremely unfortunate, since you are likely to use this code to
12949 handle Posix or @sc{ms-dos} absolute file names. To work around this
12950 bug, always put the backslash first:
12953 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12955 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12959 Many Bourne shells cannot handle closing brackets in character classes
12962 Some shells also have problems with backslash escaping in case you do not want
12963 to match the backslash: both a backslash and the escaped character match this
12964 pattern. To work around this, specify the character class in a variable, so
12965 that quote removal does not apply afterwards, and the special characters don't
12966 have to be backslash-escaped:
12969 $ @kbd{case '\' in [\<]) echo OK;; esac}
12971 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12975 Even with this, Solaris @command{ksh} matches a backslash if the set
12977 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12979 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12980 a closing parenthesis if not specified in a character class:
12983 $ @kbd{case foo in *\)*) echo fail ;; esac}
12985 $ @kbd{case foo in *')'*) echo fail ;; esac}
12989 Some shells, such as Ash 0.3.8, are confused by an empty
12990 @code{case}/@code{esac}:
12993 ash-0.3.8 $ @kbd{case foo in esac;}
12994 @error{}Syntax error: ";" unexpected (expecting ")")
12997 Many shells still do not support parenthesized cases, which is a pity
12998 for those of us using tools that rely on balanced parentheses. For
12999 instance, Solaris @command{/bin/sh}:
13002 $ @kbd{case foo in (foo) echo foo;; esac}
13003 @error{}syntax error: `(' unexpected
13009 @prindex @command{cd}
13010 Posix 1003.1-2001 requires that @command{cd} must support
13011 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
13012 with @option{-L} being the default. However, traditional shells do
13013 not support these options, and their @command{cd} command has the
13014 @option{-P} behavior.
13016 Portable scripts should assume neither option is supported, and should
13017 assume neither behavior is the default. This can be a bit tricky,
13018 since the Posix default behavior means that, for example,
13019 @samp{ls ..} and @samp{cd ..} may refer to different directories if
13020 the current logical directory is a symbolic link. It is safe to use
13021 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
13022 Also, Autoconf-generated scripts check for this problem when computing
13023 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
13024 so it is safe to @command{cd} to these variables.
13026 See @xref{Special Shell Variables}, for portability problems involving
13027 @command{cd} and the @env{CDPATH} environment variable.
13028 Also please see the discussion of the @command{pwd} command.
13031 @item @command{echo}
13032 @c -----------------
13033 @prindex @command{echo}
13034 The simple @command{echo} is probably the most surprising source of
13035 portability troubles. It is not possible to use @samp{echo} portably
13036 unless both options and escape sequences are omitted. New applications
13037 which are not aiming at portability should use @samp{printf} instead of
13040 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
13041 etc.@: for a means to simulate @option{-n}.
13043 Do not use backslashes in the arguments, as there is no consensus on
13044 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
13045 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
13046 The problem is truly @command{echo}: all the shells
13047 understand @samp{'\n'} as the string composed of a backslash and an
13050 Because of these problems, do not pass a string containing arbitrary
13051 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
13052 if you know that @var{foo}'s value cannot contain backslashes and cannot
13053 start with @samp{-}, but otherwise you should use a here-document like
13063 @item @command{eval}
13064 @c -----------------
13065 @prindex @command{eval}
13066 The @command{eval} command is useful in limited circumstances, e.g.,
13067 using commands like @samp{eval table_$key=\$value} and @samp{eval
13068 value=table_$key} to simulate a hash table when the key is known to be
13069 alphanumeric. However, @command{eval} is tricky to use on arbitrary
13070 arguments, even when it is implemented correctly.
13072 It is obviously unwise to use @samp{eval $cmd} if the string value of
13073 @samp{cmd} was derived from an untrustworthy source. But even if the
13074 string value is valid, @samp{eval $cmd} might not work as intended,
13075 since it causes field splitting and file name expansion to occur twice,
13076 once for the @command{eval} and once for the command itself. It is
13077 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
13078 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
13079 equivalent of @samp{cat test;.c} if there happens to be a file named
13080 @file{test;.c} in the current directory; and this in turn
13081 mistakenly attempts to invoke @command{cat} on the file @file{test} and
13082 then execute the command @command{.c}. To avoid this problem, use
13083 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
13085 However, suppose that you want to output the text of the evaluated
13086 command just before executing it. Assuming the previous example,
13087 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
13088 this output doesn't show the user that @samp{test;.c} is the actual name
13089 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
13090 works on this example, but it fails with @samp{cmd='cat foo >bar'},
13091 since it mistakenly replaces the contents of @file{bar} by the
13092 string @samp{cat foo}. No simple, general, and portable solution to
13093 this problem is known.
13095 You should also be wary of common bugs in @command{eval} implementations.
13096 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
13097 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
13098 4.2.5), the arguments of @samp{eval} are evaluated in a context where
13099 @samp{$?} is 0, so they exhibit behavior like this:
13102 $ @kbd{false; eval 'echo $?'}
13106 The correct behavior here is to output a nonzero value,
13107 but portable scripts should not rely on this.
13109 You should not rely on @code{LINENO} within @command{eval}.
13110 @xref{Special Shell Variables}.
13112 @item @command{exit}
13113 @c -----------------
13114 @prindex @command{exit}
13115 The default value of @command{exit} is supposed to be @code{$?};
13116 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
13117 perform @samp{exit 0}.
13120 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
13122 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
13124 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
13128 Using @samp{exit $?} restores the expected behavior.
13130 Some shell scripts, such as those generated by @command{autoconf}, use a
13131 trap to clean up before exiting. If the last shell command exited with
13132 nonzero status, the trap also exits with nonzero status so that the
13133 invoker can tell that an error occurred.
13135 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
13136 trap ignores the @code{exit} command's argument. In these shells, a trap
13137 cannot determine whether it was invoked by plain @code{exit} or by
13138 @code{exit 1}. Instead of calling @code{exit} directly, use the
13139 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
13142 @item @command{export}
13143 @c -------------------
13144 @prindex @command{export}
13145 The builtin @command{export} dubs a shell variable @dfn{environment
13146 variable}. Each update of exported variables corresponds to an update
13147 of the environment variables. Conversely, each environment variable
13148 received by the shell when it is launched should be imported as a shell
13149 variable marked as exported.
13151 Alas, many shells, such as Solaris @command{/bin/sh},
13152 @sc{irix} 6.3, @sc{irix} 5.2,
13153 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
13154 @command{export} the environment variables they receive. As a result,
13155 two variables coexist: the environment variable and the shell
13156 variable. The following code demonstrates this failure:
13167 when run with @samp{FOO=foo} in the environment, these shells print
13168 alternately @samp{foo} and @samp{bar}, although they should print only
13169 @samp{foo} and then a sequence of @samp{bar}s.
13171 Therefore you should @command{export} again each environment variable
13175 @item @command{false}
13176 @c ------------------
13177 @prindex @command{false}
13178 Don't expect @command{false} to exit with status 1: in native
13179 Solaris @file{/bin/false} exits with status 255.
13182 @item @command{for}
13183 @c ----------------
13184 @prindex @command{for}
13185 To loop over positional arguments, use:
13195 You may @emph{not} leave the @code{do} on the same line as @code{for},
13196 since some shells improperly grok:
13204 If you want to explicitly refer to the positional arguments, given the
13205 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
13208 for arg in $@{1+"$@@"@}; do
13214 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
13215 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
13216 item @samp{$@@}, for more.
13221 @prindex @command{if}
13222 Using @samp{!} is not portable. Instead of:
13225 if ! cmp -s file file.new; then
13234 if cmp -s file file.new; then :; else
13239 There are shells that do not reset the exit status from an @command{if}:
13242 $ @kbd{if (exit 42); then true; fi; echo $?}
13247 whereas a proper shell should have printed @samp{0}. This is especially
13248 bad in makefiles since it produces false failures. This is why properly
13249 written makefiles, such as Automake's, have such hairy constructs:
13252 if test -f "$file"; then
13253 install "$file" "$dest"
13260 @item @command{printf}
13261 @c ------------------
13262 @prindex @command{printf}
13263 A format string starting with a @samp{-} can cause problems.
13264 Bash interprets it as an option and
13265 gives an error. And @samp{--} to mark the end of options is not good
13266 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
13267 literally as the format string. Putting the @samp{-} in a @samp{%c}
13268 or @samp{%s} is probably easiest:
13274 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
13277 $ @kbd{printf '\045'}
13278 bash: printf: `%': missing format character
13281 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
13282 example, @file{/usr/bin/printf} is buggy, so when using
13283 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
13287 @item @command{read}
13288 @c ------------------
13289 @prindex @command{read}
13290 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
13293 @item @command{pwd}
13294 @c ----------------
13295 @prindex @command{pwd}
13296 With modern shells, plain @command{pwd} outputs a ``logical''
13297 directory name, some of whose components may be symbolic links. These
13298 directory names are in contrast to ``physical'' directory names, whose
13299 components are all directories.
13301 Posix 1003.1-2001 requires that @command{pwd} must support
13302 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
13303 with @option{-L} being the default. However, traditional shells do
13304 not support these options, and their @command{pwd} command has the
13305 @option{-P} behavior.
13307 Portable scripts should assume neither option is supported, and should
13308 assume neither behavior is the default. Also, on many hosts
13309 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
13310 does not require this behavior and portable scripts should not rely on
13313 Typically it's best to use plain @command{pwd}. On modern hosts this
13314 outputs logical directory names, which have the following advantages:
13318 Logical names are what the user specified.
13320 Physical names may not be portable from one installation
13321 host to another due to network file system gymnastics.
13323 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
13324 some parent directory, but plain @command{pwd} cannot fail for this
13328 Also please see the discussion of the @command{cd} command.
13331 @item @command{set}
13332 @c ----------------
13333 @prindex @command{set}
13334 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
13335 any options) does not sort its output.
13337 The @command{set} builtin faces the usual problem with arguments
13339 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
13340 the end of the options (any argument after @option{--} is a parameter,
13341 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
13342 10 @command{/bin/sh}) simply stop option
13343 processing as soon as a non-option argument is found. Therefore, use
13344 @samp{dummy} or simply @samp{x} to end the option processing, and use
13345 @command{shift} to pop it out:
13348 set x $my_list; shift
13351 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
13352 longer requires support for this command, and in traditional shells
13353 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
13354 makes scripts harder to debug.
13356 Some nonstandard shells do not recognize more than one option
13357 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
13358 better to combine them:
13364 The @acronym{BSD} shell has had several problems with the @option{-e}
13365 option, partly because @acronym{BSD} @command{make} traditionally used
13366 @option{-e} even though this was incompatible with Posix
13367 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
13368 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
13369 @samp{case} when @option{-e} was in effect, causing the shell to exit
13370 unexpectedly in some cases. This was particularly a problem with
13371 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
13372 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
13373 wrapper works around the bug.
13375 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
13376 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
13377 @samp{&&} fails inside a compound statement. For example:
13383 test -n "$foo" && exit 1
13386 test -n "$foo" && exit 1
13392 does not print @samp{two}. One workaround is to use @samp{if test -n
13393 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
13394 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
13397 @item @command{shift}
13398 @c ------------------
13399 @prindex @command{shift}
13400 Not only is @command{shift}ing a bad idea when there is nothing left to
13401 shift, but in addition it is not portable: the shell of @acronym{MIPS
13402 RISC/OS} 4.52 refuses to do it.
13404 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
13405 and it is also absent in many pre-Posix shells.
13408 @item @command{source}
13409 @c -------------------
13410 @prindex @command{source}
13411 This command is not portable, as Posix does not require it; use
13412 @command{.} instead.
13415 @item @command{test}
13416 @c -----------------
13417 @prindex @command{test}
13418 The @code{test} program is the way to perform many file and string
13419 tests. It is often invoked by the alternate name @samp{[}, but using
13420 that name in Autoconf code is asking for trouble since it is an M4 quote
13423 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
13424 portable and should be avoided. Thus, portable uses of @command{test}
13425 should never have more than four arguments, and scripts should use shell
13426 constructs like @samp{&&} and @samp{||} instead. If you combine
13427 @samp{&&} and @samp{||} in the same statement, keep in mind that they
13428 have equal precedence, so it is often better to parenthesize even when
13429 this is redundant. For example:
13433 test "X$a" = "X$b" -a \
13434 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
13437 test "X$a" = "X$b" &&
13438 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
13441 @command{test} does not process options like most other commands do; for
13442 example, it does not recognize the @option{--} argument as marking the
13445 It is safe to use @samp{!} as a @command{test} operator. For example,
13446 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
13447 -d foo; @dots{}} is not.
13450 @item @command{test} (files)
13451 @c -------------------------
13452 To enable @command{configure} scripts to support cross-compilation, they
13453 shouldn't do anything that tests features of the build system instead of
13454 the host system. But occasionally you may find it necessary to check
13455 whether some arbitrary file exists. To do so, use @samp{test -f} or
13456 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
13457 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
13458 lacks it. To test for symbolic links on systems that have them, use
13459 @samp{test -h} rather than @samp{test -L}; either form conforms to
13460 Posix 1003.1-2001, but older shells like Solaris 8
13461 @code{/bin/sh} support only @option{-h}.
13463 @item @command{test} (strings)
13464 @c ---------------------------
13465 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
13466 not null, but this usage is not portable to traditional platforms like
13467 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
13470 Posix also says that @samp{test ! "@var{string}"},
13471 @samp{test -n "@var{string}"} and
13472 @samp{test -z "@var{string}"} work with any string, but many
13473 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
13474 Digital Unix 4, etc.)@: get confused if
13475 @var{string} looks like an operator:
13479 test: argument expected
13481 test: argument expected
13484 Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}}
13485 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
13486 strings, but in practice this is not true for troublesome strings that
13487 look like operators or parentheses, or that begin with @samp{-}.
13489 It is best to protect such strings with a leading @samp{X}, e.g.,
13490 @samp{test "X@var{string}" != X} rather than @samp{test -n
13491 "@var{string}"} or @samp{test ! "@var{string}"}.
13493 It is common to find variations of the following idiom:
13496 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
13501 to take an action when a token matches a given pattern. Such constructs
13502 should be avoided by using:
13505 case $ac_feature in
13506 *[!-a-zA-Z0-9_]*) @var{action};;
13510 If the pattern is a complicated regular expression that cannot be
13511 expressed as a shell pattern, use something like this instead:
13514 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
13518 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
13519 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
13520 @samp{@var{foo}} contains backslashes.
13523 @item @command{trap}
13524 @c -----------------
13525 @prindex @command{trap}
13526 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
13527 trap 0, i.e., have the @command{trap} run when the script ends (either via an
13528 explicit @command{exit}, or the end of the script). The trap for 0 should be
13529 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
13530 will invoke the trap at the end of this function.
13532 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
13533 specified signals to their default values, but many common shells (e.g.,
13534 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
13535 ``command'' named @command{-} when the specified conditions arise.
13536 There is no portable workaround, except for @samp{trap - 0}, for which
13537 @samp{trap '' 0} is a portable substitute.
13539 Although Posix is not absolutely clear on this point, it is widely
13540 admitted that when entering the trap @samp{$?} should be set to the exit
13541 status of the last command run before the trap. The ambiguity can be
13542 summarized as: ``when the trap is launched by an @command{exit}, what is
13543 the @emph{last} command run: that before @command{exit}, or
13544 @command{exit} itself?''
13546 Bash considers @command{exit} to be the last command, while Zsh and
13547 Solaris @command{/bin/sh} consider that when the trap is run it is
13548 @emph{still} in the @command{exit}, hence it is the previous exit status
13549 that the trap receives:
13552 $ @kbd{cat trap.sh}
13555 $ @kbd{zsh trap.sh}
13557 $ @kbd{bash trap.sh}
13561 The portable solution is then simple: when you want to @samp{exit 42},
13562 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
13563 set the exit status to 42 for Zsh, and the second to trigger the trap
13564 and pass 42 as exit status for Bash.
13566 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
13567 reset to 0 by empty lines if the code is inside @command{trap}.
13570 $ @kbd{trap 'false}
13578 Fortunately, this bug only affects @command{trap}.
13580 @item @command{true}
13581 @c -----------------
13582 @prindex @command{true}
13583 @c Info cannot handle `:' in index entries.
13584 @c @prindex @command{:}
13585 Don't worry: as far as we know @command{true} is portable.
13586 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
13587 portable shell community tends to prefer using @command{:}. This has a
13588 funny side effect: when asked whether @command{false} is more portable
13589 than @command{true} Alexandre Oliva answered:
13592 In a sense, yes, because if it doesn't exist, the shell will produce an
13593 exit status of failure, which is correct for @command{false}, but not
13594 for @command{true}.
13598 @item @command{unset}
13599 @c ------------------
13600 @prindex @command{unset}
13601 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
13602 when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset
13603 MAIL} in some cases and dumps core.
13605 A few ancient shells lack @command{unset} entirely. Nevertheless, because
13606 it is extremely useful to disable embarrassing variables such as
13607 @code{PS1}, you can test for its existence and use
13608 it @emph{provided} you give a neutralizing value when @command{unset} is
13612 # "|| exit" suppresses any "Segmentation fault" message.
13613 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
13618 $unset PS1 || PS1='$ '
13622 @xref{Special Shell Variables}, for some neutralizing values. Also, see
13623 @ref{Limitations of Builtins}, documentation of @command{export}, for
13624 the case of environment variables.
13627 @node Limitations of Usual Tools
13628 @section Limitations of Usual Tools
13629 @cindex Limitations of usual tools
13631 The small set of tools you can expect to find on any machine can still
13632 include some limitations you should be aware of.
13638 Don't leave white space before the opening parenthesis in a user function call.
13639 Posix does not allow this and @acronym{GNU} Awk rejects it:
13642 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13643 BEGIN @{ die () @}'}
13644 gawk: cmd. line:2: BEGIN @{ die () @}
13645 gawk: cmd. line:2: ^ parse error
13646 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13647 BEGIN @{ die() @}'}
13651 Posix says that if a program contains only @samp{BEGIN} actions, and
13652 contains no instances of @code{getline}, then the program merely
13653 executes the actions without reading input. However, traditional Awk
13654 implementations (such as Solaris 10 @command{awk}) read and discard
13655 input in this case. Portable scripts can redirect input from
13656 @file{/dev/null} to work around the problem. For example:
13659 awk 'BEGIN @{print "hello world"@}' </dev/null
13662 Posix says that in an @samp{END} action, @samp{$NF} (and presumably,
13663 @samp{$1}) retain their value from the last record read, if no
13664 intervening @samp{getline} occurred. However, some implementations
13665 (such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin
13666 @samp{awk}) reset these variables. A workaround is to use an
13667 intermediate variable prior to the @samp{END} block. For example:
13670 $ @kbd{cat end.awk}
13672 END @{ print "a", $1, $NF, "b", tmp @}
13673 $ @kbd{echo 1 | awk -f end.awk}
13675 $ @kbd{echo 1 | gawk -f end.awk}
13679 If you want your program to be deterministic, don't depend on @code{for}
13683 $ @kbd{cat for.awk}
13690 $ @kbd{gawk -f for.awk </dev/null}
13693 $ @kbd{nawk -f for.awk </dev/null}
13698 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one,
13702 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13703 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13705 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13707 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13712 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13713 or use a simple test to reject such implementations.
13715 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13716 length of regular expressions and literal strings in an Awk program.
13718 Traditional Awk implementations derived from Unix version 7, such as
13719 Solaris @command{/bin/awk}, have many limitations and do not
13720 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13721 Programs}) finds you an Awk that doesn't have these problems, but if
13722 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13725 Traditional Awk does not support multidimensional arrays or user-defined
13728 Traditional Awk does not support the @option{-v} option. You can use
13729 assignments after the program instead, e.g., @command{$AWK '@{print v
13730 $1@}' v=x}; however, don't forget that such assignments are not
13731 evaluated until they are encountered (e.g., after any @code{BEGIN}
13734 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13736 Traditional Awk does not support the expressions
13737 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13738 or @code{@var{a}^=@var{b}}.
13740 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13742 Traditional Awk supports only the predefined functions @code{exp}, @code{index},
13743 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13744 @code{sqrt}, and @code{substr}.
13746 Traditional Awk @code{getline} is not at all compatible with Posix;
13749 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13750 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
13752 In code portable to both traditional and modern Awk, @code{FS} must be a
13753 string containing just one ordinary character, and similarly for the
13754 field-separator argument to @code{split}.
13756 Traditional Awk has a limit of 99
13757 fields in a record. You may be able to circumvent this problem by using
13760 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13761 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13764 The original version of Awk had a limit of at most 99 bytes per
13765 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13766 per run of non-special characters in a @code{printf} format, but these
13767 bugs have been fixed on all practical hosts that we know of.
13769 @item @command{basename}
13770 @c ---------------------
13771 @prindex @command{basename}
13772 Not all hosts have a working @command{basename}.
13773 You can use @command{expr} instead.
13775 @c AS_BASENAME is to be replaced by a better API.
13777 Not all hosts have a working @command{basename}, and you should instead
13778 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13779 @command{expr} if you need to strip a suffix. For example:
13782 a=`basename "$aname"` # This is not portable.
13783 a=`AS_BASENAME(["$aname"])` # This is more portable.
13785 # This is not portable.
13786 c=`basename "$cname" .c`
13788 # This is more portable.
13789 c=`AS_BASENAME(["$cname"])`
13791 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13797 @item @command{cat}
13798 @c ----------------
13799 @prindex @command{cat}
13800 Don't rely on any option.
13805 @prindex @command{cc}
13806 The command @samp{cc -c foo.c} traditionally produces an object file
13807 named @file{foo.o}. Most compilers allow @option{-c} to be combined
13808 with @option{-o} to specify a different object file name, but
13809 Posix does not require this combination and a few compilers
13810 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
13811 tests for this feature with @code{AC_PROG_CC_C_O}.
13813 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13814 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13816 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13817 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
13820 The default executable, produced by @samp{cc foo.c}, can be
13823 @item @file{a.out} --- usual Posix convention.
13824 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13825 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13826 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13827 @item @file{foo.exe} --- various MS-DOS compilers.
13830 The C compiler's traditional name is @command{cc}, but other names like
13831 @command{gcc} are common. Posix 1003.1-2001 specifies the
13832 name @command{c99}, but older Posix editions specified
13833 @command{c89} and anyway these standard names are rarely used in
13834 practice. Typically the C compiler is invoked from makefiles that use
13835 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13839 @item @command{chmod}
13840 @c ------------------
13841 @prindex @command{chmod}
13842 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13843 instead, for two reasons. First, plain @option{-w} does not necessarily
13844 make the file unwritable, since it does not affect mode bits that
13845 correspond to bits in the file mode creation mask. Second,
13846 Posix says that the @option{-w} might be interpreted as an
13847 implementation-specific option, not as a mode; Posix suggests
13848 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13849 @samp{--} does not work on some older hosts.
13852 @item @command{cmp}
13853 @c ----------------
13854 @prindex @command{cmp}
13855 @command{cmp} performs a raw data comparison of two files, while
13856 @command{diff} compares two text files. Therefore, if you might compare
13857 DOS files, even if only checking whether two files are different, use
13858 @command{diff} to avoid spurious differences due to differences of
13864 @prindex @command{cp}
13865 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13866 obsolescent and its behavior on special files is implementation-defined.
13867 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13868 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13869 reads from pipes instead of replicating them.
13871 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13872 trailing slashes at the end of nonexistent destination directories. To
13873 avoid this problem, omit the trailing slashes. For example, use
13874 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13875 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13877 @c This is thanks to Ian.
13878 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13879 its @command{mv} does.
13881 @cindex timestamp resolution
13882 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13883 -p} copied the timestamps exactly. However, many modern file systems
13884 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13885 -p} implementations truncate timestamps when copying files, so this
13886 can result in the destination file appearing to be older than the
13887 source. The exact amount of truncation depends on the resolution of
13888 the system calls that @command{cp} uses; traditionally this was
13889 @code{utime}, which has 1-second resolution, but some newer
13890 @command{cp} implementations use @code{utimes}, which has
13891 1-microsecond resolution. These newer implementations include @acronym{GNU}
13892 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13893 later. Unfortunately as of January 2006 there is still no system
13894 call to set timestamps to the full nanosecond resolution.
13896 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13897 ownerships. But whether it actually does copy ownerships or not is a
13898 system dependent policy decision implemented by the kernel. If the
13899 kernel allows it then it happens. If the kernel does not allow it then
13900 it does not happen. It is not something @command{cp} itself has control
13903 In Unix System V any user can chown files to any other user, and System
13904 V also has a non-sticky @file{/tmp}. That probably derives from the
13905 heritage of System V in a business environment without hostile users.
13906 @acronym{BSD} changed this
13907 to be a more secure model where only root can @command{chown} files and
13908 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13909 of @acronym{BSD} in a campus environment.
13911 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13912 can be configured to allow a System V style @command{chown}. On the
13913 other hand, @acronym{HP-UX} follows System V, but can
13914 be configured to use the modern security model and disallow
13915 @command{chown}. Since it is an administrator-configurable parameter
13916 you can't use the name of the kernel as an indicator of the behavior.
13920 @item @command{date}
13921 @c -----------------
13922 @prindex @command{date}
13923 Some versions of @command{date} do not recognize special @samp{%} directives,
13924 and unfortunately, instead of complaining, they just pass them through,
13925 and exit with success:
13929 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13935 @item @command{diff}
13936 @c -----------------
13937 @prindex @command{diff}
13938 Option @option{-u} is nonportable.
13940 Some implementations, such as Tru64's, fail when comparing to
13941 @file{/dev/null}. Use an empty file instead.
13944 @item @command{dirname}
13945 @c --------------------
13946 @prindex @command{dirname}
13947 Not all hosts have a working @command{dirname}, and you should instead
13948 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13951 dir=`dirname "$file"` # This is not portable.
13952 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13956 @item @command{egrep}
13957 @c ------------------
13958 @prindex @command{egrep}
13959 Posix 1003.1-2001 no longer requires @command{egrep},
13960 but many hosts do not yet support the Posix
13961 replacement @code{grep -E}. Also, some traditional implementations do
13962 not work on long input lines. To work around these problems, invoke
13963 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13965 Portable extended regular expressions should use @samp{\} only to escape
13966 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13967 is not portable, even though it typically matches @samp{@}}.
13969 The empty alternative is not portable. Use @samp{?} instead. For
13970 instance with Digital Unix v5.0:
13973 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13975 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13977 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13982 @command{$EGREP} also suffers the limitations of @command{grep}.
13984 @item @command{expr}
13985 @c -----------------
13986 @prindex @command{expr}
13987 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13988 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13989 misinterpreting @var{word}.
13991 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13993 @item @command{expr} (@samp{|})
13994 @prindex @command{expr} (@samp{|})
13995 You can use @samp{|}. Although Posix does require that @samp{expr
13996 ''} return the empty string, it does not specify the result when you
13997 @samp{|} together the empty string (or zero) with the empty string. For
14004 Posix 1003.2-1992 returns the empty string
14005 for this case, but traditional Unix returns @samp{0} (Solaris is
14006 one such example). In Posix 1003.1-2001, the specification was
14007 changed to match traditional Unix's behavior (which is
14008 bizarre, but it's too late to fix this). Please note that the same
14009 problem does arise when the empty string results from a computation,
14013 expr bar : foo \| foo : bar
14017 Avoid this portability problem by avoiding the empty string.
14020 @item @command{expr} (@samp{:})
14021 @c ----------------------------
14022 @prindex @command{expr}
14023 Portable @command{expr} regular expressions should use @samp{\} to
14024 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
14025 For example, alternation, @samp{\|}, is common but Posix does not
14026 require its support, so it should be avoided in portable scripts.
14027 Similarly, @samp{\+} and @samp{\?} should be avoided.
14029 Portable @command{expr} regular expressions should not begin with
14030 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
14033 The Posix standard is ambiguous as to whether
14034 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
14035 In practice, it outputs the empty string on most platforms, but portable
14036 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
14037 @command{expr} returns @samp{0}.
14039 One might think that a way to get a uniform behavior would be to use
14040 the empty string as a default value:
14043 expr a : '\(b\)' \| ''
14047 Unfortunately this behaves exactly as the original expression; see the
14048 @command{expr} (@samp{|}) entry for more information.
14050 Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
14051 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
14052 @command{expr} to fail if the matched substring is longer than 120
14053 bytes. In this case, you might want to fall back on @samp{echo|sed} if
14054 @command{expr} fails. Nowadays this is of practical importance only for
14055 the rare installer who mistakenly puts @file{/usr/ucb} before
14056 @file{/usr/bin} in @env{PATH}.
14058 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
14059 some cases. For example, the command
14061 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
14065 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
14066 This particular case can be worked around by substituting @samp{[^--]}
14069 Don't leave, there is some more!
14071 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
14072 the empty string, has a funny behavior in its exit status: it's always 1
14073 when parentheses are used!
14076 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
14078 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
14081 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
14083 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
14088 In practice this can be a big problem if you are ready to catch failures
14089 of @command{expr} programs with some other method (such as using
14090 @command{sed}), since you may get twice the result. For instance
14093 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
14097 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
14098 simple workaround consists of testing @command{expr} and using a variable
14099 set to @command{expr} or to @command{false} according to the result.
14101 Tru64 @command{expr} incorrectly treats the result as a number, if it
14102 can be interpreted that way:
14105 $ @kbd{expr 00001 : '.*\(...\)'}
14110 @item @command{fgrep}
14111 @c ------------------
14112 @prindex @command{fgrep}
14113 Posix 1003.1-2001 no longer requires @command{fgrep},
14114 but many hosts do not yet support the Posix
14115 replacement @code{grep -F}. Also, some traditional implementations do
14116 not work on long input lines. To work around these problems, invoke
14117 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
14120 @item @command{find}
14121 @c -----------------
14122 @prindex @command{find}
14123 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
14124 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
14125 commands do not understand it.
14127 The replacement of @samp{@{@}} is guaranteed only if the argument is
14128 exactly @emph{@{@}}, not if it's only a part of an argument. For
14129 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
14133 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
14138 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
14141 @item @command{grep}
14142 @c -----------------
14143 @prindex @command{grep}
14144 Portable scripts can rely on the @command{grep} options @option{-c},
14145 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
14146 options. For example, don't use @option{-w}, as Posix does not require
14147 it and Irix 6.5.16m's @command{grep} does not support it. Also,
14148 portable scripts should not combine @option{-c} with @option{-l},
14149 as Posix does not allow this.
14151 Some of the options required by Posix are not portable in practice.
14152 Don't use @samp{grep -q} to suppress output, because many @command{grep}
14153 implementations (e.g., Solaris) do not support @option{-q}.
14154 Don't use @samp{grep -s} to suppress output either, because Posix
14155 says @option{-s} does not suppress output, only some error messages;
14156 also, the @option{-s} option of traditional @command{grep} behaved
14157 like @option{-q} does in most modern implementations. Instead,
14158 redirect the standard output and standard error (in case the file
14159 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
14160 status of @code{grep} to determine whether it found a match.
14162 Some traditional @command{grep} implementations do not work on long
14163 input lines. On AIX the default @code{grep} silently truncates long
14164 lines on the input before matching.
14166 Also, many implementations do not support multiple regexps
14167 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
14168 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
14169 work around these problems, invoke @code{AC_PROG_GREP} and then use
14172 Another possible workaround for the multiple @option{-e} problem is to
14173 separate the patterns by newlines, for example:
14181 except that this fails with traditional @command{grep}
14182 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
14184 Traditional @command{grep} implementations (e.g., Solaris) do not
14185 support the @option{-E} or @option{-F} options. To work around these
14186 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
14187 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
14188 willing to require support for Posix @command{grep}, your script should
14189 not use both @option{-E} and @option{-F}, since Posix does not allow
14192 Portable @command{grep} regular expressions should use @samp{\} only to
14193 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
14194 alternation, @samp{\|}, is common but Posix does not require its
14195 support in basic regular expressions, so it should be avoided in
14196 portable scripts. Solaris and HP-UX @command{grep} do not support it.
14197 Similarly, the following escape sequences should also be avoided:
14198 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
14199 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
14202 @item @command{join}
14203 @c -----------------
14204 @prindex @command{join}
14205 Solaris 8 @command{join} has bugs when the second operand is standard
14206 input, and when standard input is a pipe. For example, the following
14207 shell script causes Solaris 8 @command{join} to loop forever:
14214 cat file | join file -
14217 Use @samp{join - file} instead.
14222 @prindex @command{ln}
14223 @cindex Symbolic links
14224 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
14225 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
14227 For versions of the @acronym{DJGPP} before 2.04,
14228 @command{ln} emulates symbolic links
14229 to executables by generating a stub that in turn calls the real
14230 program. This feature also works with nonexistent files like in the
14231 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
14232 which attempts to call @file{file.exe} if run. But this feature only
14233 works for executables, so @samp{cp -p} is used instead for these
14234 systems. @acronym{DJGPP} versions 2.04 and later have full support
14235 for symbolic links.
14240 @prindex @command{ls}
14241 @cindex Listing directories
14242 The portable options are @option{-acdilrtu}. Current practice is for
14243 @option{-l} to output both owner and group, even though ancient versions
14244 of @command{ls} omitted the group.
14246 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
14247 to standard output if @file{foo} did not exist. Hence a shell command
14248 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
14249 was equivalent to @samp{sources='*.c not found'} in the absence of
14250 @samp{.c} files. This is no longer a practical problem, since current
14251 @command{ls} implementations send diagnostics to standard error.
14253 @item @command{mkdir}
14254 @c ------------------
14255 @prindex @command{mkdir}
14256 @cindex Making directories
14257 No @command{mkdir} option is portable to older systems. Instead of
14258 @samp{mkdir -p @var{file-name}}, you should use
14259 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
14260 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
14262 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
14263 go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD}
14264 @command{mkdir} incorrectly attempts to change the permissions of
14265 @var{dir} even if it already exists. @acronym{HP-UX} 11.23 and
14266 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
14267 any newly-created parents of @var{dir}.
14269 Posix does not clearly specify whether @samp{mkdir -p foo}
14270 should succeed when @file{foo} is a symbolic link to an already-existing
14271 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
14272 succeeds, but Solaris @command{mkdir} fails.
14274 Traditional @code{mkdir -p} implementations suffer from race conditions.
14275 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
14276 at the same time, both processes might detect that @file{a} is missing,
14277 one might create @file{a}, then the other might try to create @file{a}
14278 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
14279 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
14280 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
14281 race-free when two processes invoke @code{mkdir -p} simultaneously, but
14282 earlier versions are vulnerable. Solaris @command{mkdir} is still
14283 vulnerable as of Solaris 10, and other traditional Unix systems are
14284 probably vulnerable too. This possible race is harmful in parallel
14285 builds when several Make rules call @code{mkdir -p} to
14286 construct directories. You may use
14287 @code{install-sh -d} as a safe replacement, provided this script is
14288 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
14289 OK, but copies from older versions are vulnerable.
14292 @item @command{mktemp}
14293 @c -------------------
14294 @prindex @command{mktemp}
14295 @cindex Creating temporary files
14296 Shell scripts can use temporary files safely with @command{mktemp}, but
14297 it does not exist on all systems. A portable way to create a safe
14298 temporary file name is to create a temporary directory with mode 700 and
14299 use a file inside this directory. Both methods prevent attackers from
14300 gaining control, though @command{mktemp} is far less likely to fail
14301 gratuitously under attack.
14303 Here is sample code to create a new temporary directory safely:
14306 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
14307 # Use mktemp if possible; otherwise fall back on mkdir,
14308 # with $RANDOM to make collisions less likely.
14312 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
14314 test -n "$tmp" && test -d "$tmp"
14316 tmp=$TMPDIR/foo$$-$RANDOM
14317 (umask 077 && mkdir "$tmp")
14324 @prindex @command{mv}
14325 @cindex Moving open files
14326 The only portable options are @option{-f} and @option{-i}.
14328 Moving individual files between file systems is portable (it was in Unix
14330 but it is not always atomic: when doing @samp{mv new existing}, there's
14331 a critical section where neither the old nor the new version of
14332 @file{existing} actually exists.
14334 On some systems moving files from @file{/tmp} can sometimes cause
14335 undesirable (but perfectly valid) warnings, even if you created these
14336 files. This is because @file{/tmp} belongs to a group that ordinary
14337 users are not members of, and files created in @file{/tmp} inherit
14338 the group of @file{/tmp}. When the file is copied, @command{mv} issues
14339 a diagnostic without failing:
14342 $ @kbd{touch /tmp/foo}
14343 $ @kbd{mv /tmp/foo .}
14344 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
14352 This annoying behavior conforms to Posix, unfortunately.
14354 Moving directories across mount points is not portable, use @command{cp}
14357 @acronym{DOS} variants cannot rename or remove open files, and do not
14358 support commands like @samp{mv foo bar >foo}, even though this is
14359 perfectly portable among Posix hosts.
14364 @prindex @command{od}
14366 In Mac OS X 10.3, @command{od} does not support the
14367 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
14368 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
14369 supported Posix option is @option{-v}, and the only supported
14370 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
14371 @command{hexdump} program can be used instead.
14373 This problem no longer exists in Mac OS X 10.4.3.
14378 @prindex @command{rm}
14379 The @option{-f} and @option{-r} options are portable.
14381 It is not portable to invoke @command{rm} without operands. For
14382 example, on many systems @samp{rm -f -r} (with no other arguments)
14383 silently succeeds without doing anything, but it fails with a diagnostic
14384 on Net@acronym{BSD} 2.0.2.
14386 A file might not be removed even if its parent directory is writable
14387 and searchable. Many Posix hosts cannot remove a mount point, a named
14388 stream, a working directory, or a last link to a file that is being
14391 @acronym{DOS} variants cannot rename or remove open files, and do not
14392 support commands like @samp{rm foo >foo}, even though this is
14393 perfectly portable among Posix hosts.
14396 @item @command{sed}
14397 @c ----------------
14398 @prindex @command{sed}
14399 Patterns should not include the separator (unless escaped), even as part
14400 of a character class. In conformance with Posix, the Cray
14401 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
14403 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
14404 not require support for empty patterns, and Unicos 9 @command{sed} rejects
14407 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
14409 Sed scripts should not use branch labels longer than 7 characters and
14410 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
14411 (not counting @samp{:} commands) and
14412 48 labels, which can not be circumvented by using more than one script
14413 file. It can execute up to 19 reads with the @samp{r} command per cycle.
14414 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
14415 about 6000 bytes for the internal representation of commands.
14417 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
14418 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
14419 @samp{;} as a command:
14422 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
14423 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
14426 Input should not have unreasonably long lines, since some @command{sed}
14427 implementations have an input buffer limited to 4000 bytes.
14429 Portable @command{sed} regular expressions should use @samp{\} only to escape
14430 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
14431 alternation, @samp{\|}, is common but Posix does not require its
14432 support, so it should be avoided in portable scripts. Solaris
14433 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
14434 deletes only lines that contain the literal string @samp{a|b}.
14435 Similarly, @samp{\+} and @samp{\?} should be avoided.
14437 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
14439 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
14440 quite portable to current hosts, but was not supported by some ancient
14441 @command{sed} implementations like SVR3.
14443 Some @command{sed} implementations, e.g., Solaris,
14444 restrict the special role of the asterisk to one-character regular expressions.
14445 This may lead to unexpected behavior:
14448 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
14450 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
14454 The @option{-e} option is mostly portable.
14455 However, its argument
14456 cannot start with @samp{a}, @samp{c}, or @samp{i},
14457 as this runs afoul of a Tru64 5.1 bug.
14458 Also, its argument cannot be empty, as this fails on @acronym{AIX} 5.3.
14459 Some people prefer to use @samp{-e}:
14462 sed -e '@var{command-1}' \
14463 -e '@var{command-2}'
14467 as opposed to the equivalent:
14477 The following usage is sometimes equivalent:
14480 sed '@var{command-1};@var{command-2}'
14483 but Posix says that this use of a semicolon has undefined effect if
14484 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
14485 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
14486 should use semicolon only with simple scripts that do not use these
14489 Commands inside @{ @} brackets are further restricted. Posix says that
14490 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
14491 each command must be followed immediately by a newline, without any
14492 intervening blanks or semicolons. The closing bracket must be alone on
14493 a line, other than white space preceding or following it.
14495 Contrary to yet another urban legend, you may portably use @samp{&} in
14496 the replacement part of the @code{s} command to mean ``what was
14497 matched''. All descendants of Unix version 7 @command{sed}
14499 don't have first hand experience with older @command{sed} implementations) have
14502 Posix requires that you must not have any white space between
14503 @samp{!} and the following command. It is OK to have blanks between
14504 the address and the @samp{!}. For instance, on Solaris:
14507 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
14508 @error{}Unrecognized command: /bar/ ! p
14509 $ @kbd{echo "foo" | sed -n '/bar/! p'}
14510 @error{}Unrecognized command: /bar/! p
14511 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
14515 Posix also says that you should not combine @samp{!} and @samp{;}. If
14516 you use @samp{!}, it is best to put it on a command that is delimited by
14517 newlines rather than @samp{;}.
14519 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
14520 @samp{w} commands be followed by exactly one space before their argument.
14521 On the other hand, no white space is allowed between @samp{:} and the
14522 subsequent label name.
14524 If a sed script is specified on the command line and ends in an
14525 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
14526 should be followed by a newline. Otherwise some @command{sed}
14527 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
14530 Many @command{sed} implementations (e.g., MacOS X 10.4,
14531 Open@acronym{BSD} 3.9, Solaris 10
14532 @command{/usr/ucb/sed}) strip leading white space from the text of
14533 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
14534 work around this incompatibility with Posix:
14537 $ @kbd{echo flushleft | sed 'a\}
14542 $ @kbd{echo foo | sed 'a\}
14550 @item @command{sed} (@samp{t})
14551 @c ---------------------------
14552 @prindex @command{sed} (@samp{t})
14553 Some old systems have @command{sed} that ``forget'' to reset their
14554 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
14555 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
14556 script (the line numbers are not actual part of the texts):
14559 s/keep me/kept/g # a
14595 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
14596 flag, and the output is produced. When processing
14597 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
14598 fails to match, but @command{sed} is not supposed to clear the @samp{t}
14599 flag when a substitution fails. Command (b) sees that the flag is set,
14600 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
14601 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
14602 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
14603 Finally, since the flag is clear, line 4 is processed properly.
14605 There are two things one should remember about @samp{t} in @command{sed}.
14606 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
14607 succeeded, not only the immediately preceding substitution. Therefore,
14608 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
14609 line, to reset the @samp{t} flag where needed.
14611 Secondly, you cannot rely on @command{sed} to clear the flag at each new
14614 One portable implementation of the script above is:
14625 @item @command{touch}
14626 @c ------------------
14627 @prindex @command{touch}
14628 @cindex timestamp resolution
14629 If you specify the desired timestamp (e.g., with the @option{-r}
14630 option), @command{touch} typically uses the @code{utime} or
14631 @code{utimes} system call, which can result in the same kind of
14632 timestamp truncation problems that @samp{cp -p} has.
14634 On ancient @acronym{BSD} systems, @command{touch} or any command that
14635 results in an empty file does not update the timestamps, so use a
14636 command like @command{echo} as a workaround.
14638 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
14639 fails to work on SunOS 4.1.3 when the empty file is on an
14640 @acronym{NFS}-mounted 4.2 volume.
14641 However, these problems are no longer of practical concern.
14646 @node Portable Make
14647 @chapter Portable Make Programming
14648 @prindex @command{make}
14649 @cindex Limitations of @command{make}
14651 Writing portable makefiles is an art. Since a makefile's commands are
14652 executed by the shell, you must consider the shell portability issues
14653 already mentioned. However, other issues are specific to @command{make}
14657 * $< in Ordinary Make Rules:: $< in ordinary rules
14658 * Failure in Make Rules:: Failing portably in rules
14659 * Special Chars in Names:: Special Characters in Macro Names
14660 * Backslash-Newline-Newline:: Empty last lines in macro definitions
14661 * Backslash-Newline Comments:: Spanning comments across line boundaries
14662 * Long Lines in Makefiles:: Line length limitations
14663 * Macros and Submakes:: @code{make macro=value} and submakes
14664 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
14665 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
14666 * Comments in Make Rules:: Other problems with Make comments
14667 * obj/ and Make:: Don't name a subdirectory @file{obj}
14668 * make -k Status:: Exit status of @samp{make -k}
14669 * VPATH and Make:: @code{VPATH} woes
14670 * Single Suffix Rules:: Single suffix rules and separated dependencies
14671 * Timestamps and Make:: Subsecond timestamp resolution
14674 @node $< in Ordinary Make Rules
14675 @section @code{$<} in Ordinary Make Rules
14677 Posix says that the @samp{$<} construct in makefiles can be
14678 used only in inference rules and in the @samp{.DEFAULT} rule; its
14679 meaning in ordinary rules is unspecified. Solaris @command{make}
14680 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
14681 later) @command{make} diagnoses these uses and errors out.
14683 @node Failure in Make Rules
14684 @section Failure in Make Rules
14686 Since 1992 Posix has required that @command{make} must invoke
14687 each command with the equivalent of a @samp{sh -c} subshell. However,
14688 many @command{make} implementations, including @acronym{BSD} make through 2004,
14689 use @samp{sh -e -c} instead, and the @option{-e} option causes the
14690 subshell to exit immediately if a subsidiary simple-command fails. For
14691 example, the command @samp{touch T; rm -f U} always attempts to
14692 remove @file{U} with Posix make, but incompatible
14693 @command{make} implementations skip the @command{rm} if the
14694 @command{touch} fails. One way to work around this is to reword the
14695 affected simple-commands so that they always succeed, e.g., @samp{touch
14697 However, even this approach can run into common bugs in @acronym{BSD}
14698 implementations of the @option{-e} option of @command{sh} and
14699 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14700 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14701 complicated @command{make} actions into separate scripts.
14703 @node Special Chars in Names
14704 @section Special Characters in Make Macro Names
14706 Posix limits macro names to nonempty strings containing only
14707 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
14708 @command{make} implementations allow a wider variety of characters, but
14709 portable makefiles should avoid them. It is portable to start a name
14710 with a special character, e.g., @samp{$(.FOO)}.
14712 Some ancient @command{make} implementations don't support leading
14713 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
14716 $ @kbd{cat Makefile}
14719 all:; @@echo this is test
14721 Make: Must be a separator on rules line 2. Stop.
14722 $ @kbd{cat Makefile2}
14725 all:; @@echo this is test
14726 $ @kbd{make -f Makefile2}
14731 However, this problem is no longer of practical concern.
14733 @node Backslash-Newline-Newline
14734 @section Backslash-Newline-Newline in Make Macro Values
14736 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14737 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
14738 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
14739 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14740 following a backslash, continuing to the next non-empty line. For
14754 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
14755 sensibly let a backslash continue only to the immediately following
14758 @node Backslash-Newline Comments
14759 @section Backslash-Newline in Make Comments
14761 According to Posix, Make comments start with @code{#}
14762 and continue until an unescaped newline is reached.
14765 $ @kbd{cat Makefile}
14772 $ @kbd{make} # GNU make
14777 However this is not always the case. Some implementations
14778 discard everything from @code{#} through the end of the line, ignoring any
14779 trailing backslash.
14782 $ @kbd{pmake} # BSD make
14783 "Makefile", line 3: Need an operator
14784 Fatal errors encountered -- cannot continue
14788 Therefore, if you want to comment out a multi-line definition, prefix each
14789 line with @code{#}, not only the first.
14797 @node Long Lines in Makefiles
14798 @section Long Lines in Makefiles
14800 Tru64 5.1's @command{make} has been reported to crash when given a
14801 makefile with lines longer than around 20 kB. Earlier versions are
14802 reported to exit with @code{Line too long} diagnostics.
14804 @node Macros and Submakes
14805 @section @code{make macro=value} and Submakes
14807 A command-line variable definition such as @code{foo=bar} overrides any
14808 definition of @code{foo} in a makefile. Some @command{make}
14809 implementations (such as @acronym{GNU} @command{make}) propagate this
14810 override to subsidiary invocations of @command{make}. Some other
14811 implementations do not pass the substitution along to submakes.
14814 $ @kbd{cat Makefile}
14821 $ @kbd{make foo=bar} # GNU make 3.79.1
14824 make[1]: Entering directory `/home/adl'
14826 make[1]: Leaving directory `/home/adl'
14827 $ @kbd{pmake foo=bar} # BSD make
14833 You have a few possibilities if you do want the @code{foo=bar} override
14834 to propagate to submakes. One is to use the @option{-e}
14835 option, which causes all environment variables to have precedence over
14836 the makefile macro definitions, and declare foo as an environment
14840 $ @kbd{env foo=bar make -e}
14843 The @option{-e} option is propagated to submakes automatically,
14844 and since the environment is inherited between @command{make}
14845 invocations, the @code{foo} macro is overridden in
14846 submakes as expected.
14848 This syntax (@code{foo=bar make -e}) is portable only when used
14849 outside of a makefile, for instance from a script or from the
14850 command line. When run inside a @command{make} rule, @acronym{GNU}
14851 @command{make} 3.80 and prior versions forget to propagate the
14852 @option{-e} option to submakes.
14854 Moreover, using @option{-e} could have unexpected side effects if your
14855 environment contains some other macros usually defined by the
14856 makefile. (See also the note about @code{make -e} and @code{SHELL}
14859 Another way to propagate overrides to submakes is to do it
14860 manually, from your makefile:
14866 $(MAKE) foo=$(foo) two
14871 You need to foresee all macros that a user might want to override if
14874 @node The Make Macro MAKEFLAGS
14875 @section The Make Macro MAKEFLAGS
14876 @cindex @code{MAKEFLAGS} and @command{make}
14877 @cindex @command{make} and @code{MAKEFLAGS}
14879 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14880 current and recursive invocations of make, but allows implementations
14881 several formats for the variable. It is tricky to parse
14882 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14883 or @option{-k} for continued execution are in effect. For example, you
14884 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14885 contains single-letter options, since in the Cygwin version of
14886 @acronym{GNU} @command{make} it is either @option{--unix} or
14887 @option{--win32} with the second word containing single-letter options.
14890 $ @kbd{cat Makefile}
14892 @@echo MAKEFLAGS = $(MAKEFLAGS)
14896 MAKEFLAGS = --unix -k
14899 @node The Make Macro SHELL
14900 @section The Make Macro @code{SHELL}
14901 @cindex @code{SHELL} and @command{make}
14902 @cindex @command{make} and @code{SHELL}
14904 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14905 macro to spawn shell processes and execute Make rules. This
14906 is a builtin macro supplied by @command{make}, but it can be modified
14907 by a makefile or by a command-line argument.
14909 Not all @command{make} implementations define this @code{SHELL} macro.
14911 @command{make} is an example; this implementation always uses
14912 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14913 your makefiles. If you use Autoconf, do
14919 Do not force @code{SHELL = /bin/sh} because that is not correct
14920 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14921 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14922 emulation mode where features like pipes and redirections are emulated
14923 on top of DOS's @command{command.com}. Unfortunately this emulation is
14924 incomplete; for instance it does not handle command substitutions.
14925 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14927 Posix-compliant @command{make} should never acquire the value of
14928 $(SHELL) from the environment, even when @code{make -e} is used
14929 (otherwise, think about what would happen to your rules if
14930 @code{SHELL=/bin/tcsh}).
14932 However not all @command{make} implementations have this exception.
14933 For instance it's not surprising that Tru64 @command{make} doesn't
14934 protect @code{SHELL}, since it doesn't use it.
14937 $ @kbd{cat Makefile}
14943 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14946 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14951 @node Comments in Make Rules
14952 @section Comments in Make Rules
14953 @cindex Comments in @file{Makefile} rules
14954 @cindex @file{Makefile} rules and comments
14956 Never put comments in a rule.
14958 Some @command{make} treat anything starting with a tab as a command for
14959 the current rule, even if the tab is immediately followed by a @code{#}.
14960 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14961 makefile runs @code{# foo} through the shell.
14968 @node obj/ and Make
14969 @section The @file{obj/} Subdirectory and Make
14970 @cindex @file{obj/}, subdirectory
14971 @cindex @acronym{BSD} @command{make} and @file{obj/}
14973 Never name one of your subdirectories @file{obj/} if you don't like
14976 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14977 before reading the makefile. Hence the makefile in the
14978 current directory is not read.
14981 $ @kbd{cat Makefile}
14984 $ @kbd{cat obj/Makefile}
14987 $ @kbd{make} # GNU make
14990 $ @kbd{pmake} # BSD make
14995 @node make -k Status
14996 @section Exit Status of @code{make -k}
14997 @cindex @code{make -k}
14999 Do not rely on the exit status of @code{make -k}. Some implementations
15000 reflect whether they encountered an error in their exit status; other
15001 implementations always succeed.
15004 $ @kbd{cat Makefile}
15007 $ @kbd{make -k; echo exit status: $?} # GNU make
15009 make: *** [all] Error 1
15011 $ @kbd{pmake -k; echo exit status: $?} # BSD make
15013 *** Error code 1 (continuing)
15017 @node VPATH and Make
15018 @section @code{VPATH} and Make
15019 @cindex @code{VPATH}
15021 Posix does not specify the semantics of @code{VPATH}. Typically,
15022 @command{make} supports @code{VPATH}, but its implementation is not
15025 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
15026 portable to recent-enough popular implementations of @command{make}, but
15027 to keep the resulting makefiles portable, a package's makefile
15028 prototypes must take the following issues into account. These issues
15029 are complicated and are often poorly understood, and installers who use
15030 @code{VPATH} should expect to find many bugs in this area. If you use
15031 @code{VPATH}, the simplest way to avoid these portability bugs is to
15032 stick with @acronym{GNU} @command{make}, since it is the most
15033 commonly-used @command{make} among Autoconf users.
15035 Here are some known issues with some @code{VPATH}
15039 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
15040 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
15041 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
15042 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
15043 * Make Target Lookup:: More details about @code{VPATH} lookup
15046 @node VPATH and Double-colon
15047 @subsection @code{VPATH} and Double-colon Rules
15048 @cindex @code{VPATH} and double-colon rules
15049 @cindex double-colon rules and @code{VPATH}
15051 With ancient versions of Sun @command{make},
15052 any assignment to @code{VPATH} causes @command{make} to execute only
15053 the first set of double-colon rules.
15054 However, this problem is no longer of practical concern.
15056 @node $< in Explicit Rules
15057 @subsection @code{$<} Not Supported in Explicit Rules
15058 @cindex explicit rules, @code{$<}, and @code{VPATH}
15059 @cindex @code{$<}, explicit rules, and @code{VPATH}
15060 @cindex @code{VPATH}, explicit rules, and @code{$<}
15062 Using @code{$<} in explicit rules is not portable.
15063 The prerequisite file must be named explicitly in the rule. If you want
15064 to find the prerequisite via a @code{VPATH} search, you have to code the
15065 whole thing manually. @xref{Build Directories}.
15067 @node Automatic Rule Rewriting
15068 @subsection Automatic Rule Rewriting
15069 @cindex @code{VPATH} and automatic rule rewriting
15070 @cindex automatic rule rewriting and @code{VPATH}
15072 Some @command{make} implementations, such as Solaris and Tru64,
15073 search for prerequisites in @code{VPATH} and
15074 then rewrite each occurrence as a plain word in the rule.
15078 # This isn't portable to GNU make.
15085 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
15086 found in @file{../pkg/src}.
15088 However, this rule leads to real problems in practice. For example, if
15089 the source directory contains an ordinary file named @file{test} that is
15090 used in a dependency, Solaris @command{make} rewrites commands like
15091 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
15092 @dots{}}, which is typically undesirable. To avoid this problem,
15093 portable makefiles should never mention a source file whose name is that
15094 of a shell keyword like @file{until} or a shell command like
15095 @command{cat} or @command{gcc} or @command{test}.
15097 Because of these problems @acronym{GNU} @command{make} and many other
15098 @command{make} implementations do not rewrite commands, so portable
15100 search @code{VPATH} manually. It is tempting to write this:
15103 # This isn't portable to Solaris make.
15106 cp `test -f if.c || echo $(VPATH)/`if.c f.c
15110 However, the ``prerequisite rewriting'' still applies here. So if
15111 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
15115 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
15126 and thus fails. Oops.
15128 A simple workaround, and good practice anyway, is to use @samp{$?} and
15129 @samp{$@@} when possible:
15138 but this does not generalize well to commands with multiple
15139 prerequisites. A more general workaround is to rewrite the rule so that
15140 the prerequisite @file{if.c} never appears as a plain word. For
15141 example, these three rules would be safe, assuming @file{if.c} is in
15142 @file{../pkg/src} and the other files are in the working directory:
15147 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
15149 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
15151 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
15154 Things get worse when your prerequisites are in a macro.
15158 HEADERS = f.h g.h h.h
15159 install-HEADERS: $(HEADERS)
15160 for i in $(HEADERS); do \
15161 $(INSTALL) -m 644 \
15162 `test -f $$i || echo $(VPATH)/`$$i \
15163 $(DESTDIR)$(includedir)/$$i; \
15167 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
15168 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
15169 where @code{f.h} and @code{g.h} are plain words and are hence
15170 subject to @code{VPATH} adjustments.
15172 If the three files are in @file{../pkg/src}, the rule is run as:
15175 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
15177 `test -f $i || echo ../pkg/src/`$i \
15178 /usr/local/include/$i; \
15182 where the two first @command{install} calls fail. For instance,
15183 consider the @code{f.h} installation:
15187 `test -f ../pkg/src/f.h || \
15190 /usr/local/include/../pkg/src/f.h;
15199 /usr/local/include/../pkg/src/f.h;
15202 Note that the manual @code{VPATH} search did not cause any problems here;
15203 however this command installs @file{f.h} in an incorrect directory.
15205 Trying to quote @code{$(HEADERS)} in some way, as we did for
15206 @code{foo.c} a few makefiles ago, does not help:
15209 install-HEADERS: $(HEADERS)
15210 headers='$(HEADERS)'; \
15211 for i in $$headers; do \
15212 $(INSTALL) -m 644 \
15213 `test -f $$i || echo $(VPATH)/`$$i \
15214 $(DESTDIR)$(includedir)/$$i; \
15218 Now, @code{headers='$(HEADERS)'} macro-expands to:
15221 headers='f.h g.h h.h'
15225 but @code{g.h} is still a plain word. (As an aside, the idiom
15226 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
15227 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
15228 syntax error on @code{for i in;}.)
15230 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
15234 HEADERS = f.h g.h h.h
15235 install-HEADERS: $(HEADERS)
15236 headers='$(HEADERS)'; \
15237 for i in $$headers; do \
15238 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
15239 $(INSTALL) -m 644 \
15240 `test -f $$i || echo $(VPATH)/`$$i \
15241 $(DESTDIR)$(includedir)/$$i; \
15245 Automake does something similar. However the above hack works only if
15246 the files listed in @code{HEADERS} are in the current directory or a
15247 subdirectory; they should not be in an enclosing directory. If we had
15248 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
15249 build with Tru64 @command{make}. The reason is that not only does
15250 Tru64 @command{make} rewrite dependencies, but it also simplifies
15251 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
15252 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
15253 a leading @file{../pkg/src/} component.
15255 The following example makes the behavior of Tru64 @command{make}
15259 $ @kbd{cat Makefile}
15271 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
15272 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
15273 directory does not even exist, this just means that the simplification
15274 occurred before the file was checked for.)
15276 For the record here is how SunOS 4 @command{make} behaves on this
15281 make: Fatal error: Don't know how to make target `../foo'
15289 @node Tru64 Directory Magic
15290 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
15291 @cindex @code{VPATH} and prerequisite directories
15292 @cindex prerequisite directories and @code{VPATH}
15294 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
15295 @command{make} creates it in the current directory.
15298 $ @kbd{mkdir -p foo/bar build}
15300 $ @kbd{cat >Makefile <<END
15309 This can yield unexpected results if a rule uses a manual @code{VPATH}
15310 search as presented before.
15315 command `test -d foo/bar || echo ../`foo/bar
15318 The above @command{command} is run on the empty @file{foo/bar}
15319 directory that was created in the current directory.
15321 @node Make Target Lookup
15322 @subsection Make Target Lookup
15323 @cindex @code{VPATH}, resolving target pathnames
15325 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
15326 should use files found via a @code{VPATH} search. @xref{Search
15327 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
15330 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
15331 file name found during the @code{VPATH} search for this target, and
15332 builds the file locally using the file name given in the makefile.
15333 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
15334 file name found during the @code{VPATH} search.
15336 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
15337 easier to describe: the file name found during the @code{VPATH} search
15338 is used whether the target needs to be rebuilt or not. Therefore
15339 new files are created locally, but existing files are updated at their
15340 @code{VPATH} location.
15342 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
15344 @code{VPATH} search for a dependency that has an explicit rule.
15345 This is extremely annoying.
15347 When attempting a @code{VPATH} build for an autoconfiscated package
15348 (e.g., @code{mkdir build && cd build && ../configure}), this means
15350 @command{make} builds everything locally in the @file{build}
15351 directory, while @acronym{BSD} @command{make} builds new files locally and
15352 updates existing files in the source directory.
15355 $ @kbd{cat Makefile}
15358 foo.x bar.x: newer.x
15359 @@echo Building $@@
15360 $ @kbd{touch ../bar.x}
15361 $ @kbd{touch ../newer.x}
15362 $ @kbd{make} # GNU make
15365 $ @kbd{pmake} # NetBSD make
15368 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15371 $ @kbd{tmake} # Tru64 make
15374 $ @kbd{touch ../bar.x}
15375 $ @kbd{make} # GNU make
15377 $ @kbd{pmake} # NetBSD make
15379 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15382 $ @kbd{tmake} # Tru64 make
15387 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
15388 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
15389 @command{make} always
15390 update @file{bar.x}, even when @file{../bar.x} is up to date.
15392 Another point worth mentioning is that once @acronym{GNU} @command{make} has
15393 decided to ignore a @code{VPATH} file name (e.g., it ignored
15394 @file{../bar.x} in the above example) it continues to ignore it when
15395 the target occurs as a prerequisite of another rule.
15397 The following example shows that @acronym{GNU} @command{make} does not look up
15398 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
15399 because it ignored the @code{VPATH} result of @file{bar.x} while running
15400 the @code{bar.x: newer.x} rule.
15403 $ @kbd{cat Makefile}
15407 @@echo Building $@@
15411 $ @kbd{touch ../bar.x}
15412 $ @kbd{touch ../newer.x}
15413 $ @kbd{make} # GNU make
15416 cp: cannot stat `bar.x': No such file or directory
15417 make: *** [bar.y] Error 1
15418 $ @kbd{pmake} # NetBSD make
15422 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15423 echo Building bar.x
15425 cp: cannot stat `bar.x': No such file or directory
15427 $ @kbd{tmake} # Tru64 make
15429 cp: bar.x: No such file or directory
15433 Note that if you drop away the command from the @code{bar.x: newer.x}
15434 rule, @acronym{GNU} @command{make} magically starts to work: it
15435 knows that @code{bar.x} hasn't been updated, therefore it doesn't
15436 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
15437 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
15441 $ @kbd{cat Makefile}
15448 $ @kbd{touch ../bar.x}
15449 $ @kbd{touch ../newer.x}
15450 $ @kbd{make} # GNU make
15453 $ @kbd{pmake} # NetBSD make
15456 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15458 cp: cannot stat `bar.x': No such file or directory
15460 $ @kbd{tmake} # Tru64 make
15464 It seems the sole solution that would please every @command{make}
15465 implementation is to never rely on @code{VPATH} searches for targets.
15466 In other words, @code{VPATH} should be reserved to unbuilt sources.
15469 @node Single Suffix Rules
15470 @section Single Suffix Rules and Separated Dependencies
15471 @cindex Single Suffix Inference Rule
15472 @cindex Rule, Single Suffix Inference
15473 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
15474 (@samp{.from.to:}), but which @emph{destination} suffix is empty
15477 @cindex Separated Dependencies
15478 @dfn{Separated dependencies} simply refers to listing the prerequisite
15479 of a target, without defining a rule. Usually one can list on the one
15480 hand side, the rules, and on the other hand side, the dependencies.
15482 Solaris @command{make} does not support separated dependencies for
15483 targets defined by single suffix rules:
15486 $ @kbd{cat Makefile}
15491 $ @kbd{touch foo.in}
15498 while @acronym{GNU} Make does:
15504 Makefile foo foo.in
15507 Note it works without the @samp{foo: foo.in} dependency.
15510 $ @kbd{cat Makefile}
15519 and it works with double suffix inference rules:
15522 $ @kbd{cat Makefile}
15524 .SUFFIXES: .in .out
15531 As a result, in such a case, you have to write target rules.
15533 @node Timestamps and Make
15534 @section Timestamp Resolution and Make
15535 @cindex timestamp resolution
15536 Traditionally, file timestamps had 1-second resolution, and
15537 @command{make} used those timestamps to determine whether one file was
15538 newer than the other. However, many modern file systems have
15539 timestamps with 1-nanosecond resolution. Some @command{make}
15540 implementations look at the entire timestamp; others ignore the
15541 fractional part, which can lead to incorrect results. Normally this
15542 is not a problem, but in some extreme cases you may need to use tricks
15543 like @samp{sleep 1} to work around timestamp truncation bugs.
15545 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
15546 file timestamps to their full resolutions (@pxref{Limitations of Usual
15547 Tools}). Hence you should be wary of rules like this:
15554 as @file{dest} often appears to be older than @file{src} after the
15555 timestamp is truncated, and this can cause @command{make} to do
15556 needless rework the next time it is invoked. To work around this
15557 problem, you can use a timestamp file, e.g.:
15568 @c ======================================== Portable C and C++ Programming
15570 @node Portable C and C++
15571 @chapter Portable C and C++ Programming
15572 @cindex Portable C and C++ programming
15574 C and C++ programs often use low-level features of the underlying
15575 system, and therefore are often more difficult to make portable to other
15578 Several standards have been developed to help make your programs more
15579 portable. If you write programs with these standards in mind, you can
15580 have greater confidence that your programs work on a wide variety
15581 of systems. @xref{Standards, , Language Standards Supported by
15582 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
15583 (@acronym{GCC})}, for a list of C-related
15584 standards. Many programs also assume the
15585 @uref{http://www.opengroup.org/susv3, Posix standard}.
15587 Some old code is written to be portable to K&R C, which predates any C
15588 standard. K&R C compilers are no longer of practical interest, though,
15589 and the rest of section assumes at least C89, the first C standard.
15591 Program portability is a huge topic, and this section can only briefly
15592 introduce common pitfalls. @xref{System Portability, , Portability
15593 between System Types, standards, @acronym{GNU} Coding Standards}, for
15597 * Varieties of Unportability:: How to make your programs unportable
15598 * Integer Overflow:: When integers get too large
15599 * Null Pointers:: Properties of null pointers
15600 * Buffer Overruns:: Subscript errors and the like
15601 * Volatile Objects:: @code{volatile} and signals
15602 * Floating Point Portability:: Portable floating-point arithmetic
15603 * Exiting Portably:: Exiting and the exit status
15606 @node Varieties of Unportability
15607 @section Varieties of Unportability
15608 @cindex portability
15610 Autoconf tests and ordinary programs often need to test what is allowed
15611 on a system, and therefore they may need to deliberately exceed the
15612 boundaries of what the standards allow, if only to see whether an
15613 optional feature is present. When you write such a program, you should
15614 keep in mind the difference between constraints, unspecified behavior,
15615 and undefined behavior.
15617 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
15618 example constraint is that C programs must not declare a bit-field with
15619 negative width. Tests can therefore reliably assume that programs with
15620 negative-width bit-fields are rejected by a compiler that conforms
15623 @dfn{Unspecified behavior} is valid behavior, where the standard allows
15624 multiple possibilities. For example, the order of evaluation of
15625 function arguments is unspecified. Some unspecified behavior is
15626 @dfn{implementation-defined}, i.e., documented by the implementation,
15627 but since Autoconf tests cannot read the documentation they cannot
15628 distinguish between implementation-defined and other unspecified
15629 behavior. It is common for Autoconf tests to probe implementations to
15630 determine otherwise-unspecified behavior.
15632 @dfn{Undefined behavior} is invalid behavior, where the standard allows
15633 the implementation to do anything it pleases. For example,
15634 dereferencing a null pointer leads to undefined behavior. If possible,
15635 test programs should avoid undefined behavior, since a program with
15636 undefined behavior might succeed on a test that should fail.
15638 The above rules apply to programs that are intended to conform to the
15639 standard. However, strictly-conforming programs are quite rare, since
15640 the standards are so limiting. A major goal of Autoconf is to support
15641 programs that use implementation features not described by the standard,
15642 and it is fairly common for test programs to violate the above rules, if
15643 the programs work well enough in practice.
15645 @node Integer Overflow
15646 @section Integer Overflow
15647 @cindex integer overflow
15648 @cindex overflow, signed integer
15649 @cindex signed integer overflow
15650 @cindex wraparound arithmetic
15652 In practice many portable C programs assume that signed integer overflow wraps
15653 around reliably using two's complement arithmetic. Yet the C standard
15654 says that program behavior is undefined on overflow, and in a few cases
15655 C programs do not work on some modern implementations because their
15656 overflows do not wrap around as their authors expected. Conversely, in
15657 signed integer remainder, the C standard requires overflow
15658 behavior that is commonly not implemented.
15661 * Integer Overflow Basics:: Why integer overflow is a problem
15662 * Signed Overflow Examples:: Examples of code assuming wraparound
15663 * Optimization and Wraparound:: Optimizations that break uses of wraparound
15664 * Signed Overflow Advice:: Practical advice for signed overflow issues
15665 * Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
15668 @node Integer Overflow Basics
15669 @subsection Basics of Integer Overflow
15670 @cindex integer overflow
15671 @cindex overflow, signed integer
15672 @cindex signed integer overflow
15673 @cindex wraparound arithmetic
15675 In languages like C, unsigned integer overflow reliably wraps around;
15676 e.g., @code{UINT_MAX + 1} yields zero.
15677 This is guaranteed by the C standard and is
15678 portable in practice, unless you specify aggressive,
15679 nonstandard optimization options
15680 suitable only for special applications.
15682 In contrast, the C standard says that signed integer overflow leads to
15683 undefined behavior where a program can do anything, including dumping
15684 core or overrunning a buffer. The misbehavior can even precede the
15685 overflow. Such an overflow can occur during addition, subtraction,
15686 multiplication, division, and left shift.
15688 Despite this requirement of the standard, many C programs and Autoconf
15689 tests assume that signed integer overflow silently wraps around modulo a
15690 power of two, using two's complement arithmetic, so long as you cast the
15691 resulting value to a signed integer type or store it into a signed
15692 integer variable. If you use conservative optimization flags, such
15693 programs are generally portable to the vast majority of modern
15694 platforms, with a few exceptions discussed later.
15696 For historical reasons the C standard also allows implementations with
15697 ones' complement or signed magnitude arithmetic, but it is safe to
15698 assume two's complement nowadays.
15700 Also, overflow can occur when converting an out-of-range value to a
15701 signed integer type. Here a standard implementation must define what
15702 happens, but this might include raising an exception. In practice all
15703 known implementations support silent wraparound in this case, so you need
15704 not worry about other possibilities.
15706 @node Signed Overflow Examples
15707 @subsection Examples of Code Assuming Wraparound Overflow
15708 @cindex integer overflow
15709 @cindex overflow, signed integer
15710 @cindex signed integer overflow
15711 @cindex wraparound arithmetic
15713 There has long been a tension between what the C standard requires for
15714 signed integer overflow, and what C programs commonly assume. The
15715 standard allows aggressive optimizations based on assumptions that
15716 overflow never occurs, but many practical C programs rely on overflow
15717 wrapping around. These programs do not conform to the standard, but
15718 they commonly work in practice because compiler writers are
15719 understandably reluctant to implement optimizations that would break
15720 many programs, unless perhaps a user specifies aggressive optimization.
15722 The C Standard says that if a program has signed integer overflow its
15723 behavior is undefined, and the undefined behavior can even precede the
15724 overflow. To take an extreme example:
15726 @c Inspired by Robert Dewar's example in
15727 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
15729 if (password == expected_password)
15730 allow_superuser_privileges ();
15731 else if (counter++ == INT_MAX)
15734 printf ("%d password mismatches\n", counter);
15738 If the @code{int} variable @code{counter} equals @code{INT_MAX},
15739 @code{counter++} must overflow and the behavior is undefined, so the C
15740 standard allows the compiler to optimize away the test against
15741 @code{INT_MAX} and the @code{abort} call.
15742 Worse, if an earlier bug in the program lets the compiler deduce that
15743 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
15744 the C standard allows the compiler to optimize away the password test
15745 and generate code that allows superuser privileges unconditionally.
15747 Despite this requirement by the standard, it has long been common for C
15748 code to assume wraparound arithmetic after signed overflow, and all
15749 known practical C implementations support some C idioms that assume
15750 wraparound signed arithmetic, even if the idioms do not conform
15751 strictly to the standard. If your code looks like the following
15752 examples it will almost surely work with real-world compilers.
15754 Here is an example derived from the 7th Edition Unix implementation of
15755 @code{atoi} (1979-01-10):
15761 while (*p >= '0' && *p <= '9')
15762 n = n * 10 + *p++ - '0';
15763 return (f ? -n : n);
15767 Even if the input string is in range, on most modern machines this has
15768 signed overflow when computing the most negative integer (the @code{-n}
15769 overflows) or a value near an extreme integer (the first @code{+}
15772 Here is another example, derived from the 7th Edition implementation of
15773 @code{rand} (1979-01-10). Here the programmer expects both
15774 multiplication and addition to wrap on overflow:
15777 static long int randx = 1;
15779 randx = randx * 1103515245 + 12345;
15780 return (randx >> 16) & 077777;
15783 In the following example, derived from the @acronym{GNU} C Library 2.5
15784 implementation of @code{mktime} (2006-09-09), the code assumes
15785 wraparound arithmetic in @code{+} to detect signed overflow:
15789 int sec_requested, sec_adjustment;
15791 t1 = t + sec_requested;
15792 t2 = t1 + sec_adjustment;
15793 if (((t1 < t) != (sec_requested < 0))
15794 | ((t2 < t1) != (sec_adjustment < 0)))
15798 If your code looks like these examples, it is probably safe even though
15799 it does not strictly conform to the C standard. This might lead one to
15800 believe that one can generally assume wraparound on overflow, but that
15801 is not always true, as can be seen in the next section.
15803 @node Optimization and Wraparound
15804 @subsection Optimizations That Break Wraparound Arithmetic
15805 @cindex loop induction
15807 Compilers sometimes generate code that is incompatible with wraparound
15808 integer arithmetic. A simple example is an algebraic simplification: a
15809 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
15810 because it assumes that @code{i * 2000} does not overflow. The
15811 translation is not equivalent to the original when overflow occurs:
15812 e.g., in the typical case of 32-bit signed two's complement wraparound
15813 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
15814 the original expression returns @minus{}2147483 but the optimized
15815 version returns the mathematically correct value 2147484.
15817 More subtly, loop induction optimizations often exploit the undefined
15818 behavior of signed overflow. Consider the following contrived function
15823 sumc (int lo, int hi)
15827 for (i = lo; i <= hi; i++)
15834 To avoid multiplying by 53 each time through the loop, an optimizing
15835 compiler might internally transform @code{sumc} to the equivalent of the
15840 transformed_sumc (int lo, int hi)
15845 for (ic = lo * 53; ic <= hic; ic += 53)
15852 This transformation is allowed by the C standard, but it is invalid for
15853 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
15854 overflow in computing expressions like @code{hi * 53} can cause the
15855 expression @code{i <= hi} to yield a different value from the
15856 transformed expression @code{ic <= hic}.
15858 For this reason, compilers that use loop induction and similar
15859 techniques often do not support reliable wraparound arithmetic when a
15860 loop induction variable like @code{ic} is involved. Since loop
15861 induction variables are generated by the compiler, and are not visible
15862 in the source code, it is not always trivial to say whether the problem
15865 Hardly any code actually depends on wraparound arithmetic in cases like
15866 these, so in practice these loop induction optimizations are almost
15867 always useful. However, edge cases in this area can cause problems.
15872 for (j = 1; 0 < j; j *= 2)
15877 Here, the loop attempts to iterate through all powers of 2 that
15878 @code{int} can represent, but the C standard allows a compiler to
15879 optimize away the comparison and generate an infinite loop,
15880 under the argument that behavior is undefined on overflow. As of this
15881 writing this optimization is not done by any production version of
15882 @acronym{GCC} with @option{-O2}, but it might be performed by other
15883 compilers, or by more aggressive @acronym{GCC} optimization options,
15884 and the @acronym{GCC} developers have not decided whether it will
15885 continue to work with @acronym{GCC} and @option{-O2}.
15887 @node Signed Overflow Advice
15888 @subsection Practical Advice for Signed Overflow Issues
15889 @cindex integer overflow
15890 @cindex overflow, signed integer
15891 @cindex signed integer overflow
15892 @cindex wraparound arithmetic
15894 Ideally the safest approach is to avoid signed integer overflow
15895 entirely. For example, instead of multiplying two signed integers, you
15896 can convert them to unsigned integers, multiply the unsigned values,
15897 then test whether the result is in signed range.
15899 Rewriting code in this way will be inconvenient, though, particularly if
15900 the signed values might be negative. Also, it may hurt
15901 performance. Using unsigned arithmetic to check for overflow is
15902 particularly painful to do portably and efficiently when dealing with an
15903 integer type like @code{uid_t} whose width and signedness vary from
15904 platform to platform.
15906 Furthermore, many C applications pervasively assume wraparound behavior
15907 and typically it is not easy to find and remove all these assumptions.
15908 Hence it is often useful to maintain nonstandard code that assumes
15909 wraparound on overflow, instead of rewriting the code. The rest of this
15910 section attempts to give practical advice for this situation.
15912 If your code wants to detect signed integer overflow in @code{sum = a +
15913 b}, it is generally safe to use an expression like @code{(sum < a) != (b
15916 If your code uses a signed loop index, make sure that the index cannot
15917 overflow, along with all signed expressions derived from the index.
15918 Here is a contrived example of problematic code with two instances of
15922 for (i = INT_MAX - 10; i <= INT_MAX; i++)
15925 report_overflow ();
15931 Because of the two overflows, a compiler might optimize away or
15932 transform the two comparisons in a way that is incompatible with the
15933 wraparound assumption.
15935 If your code uses an expression like @code{(i * 2000) / 1000} and you
15936 actually want the multiplication to wrap around on overflow, use
15937 unsigned arithmetic
15938 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
15940 If your code assumes wraparound behavior and you want to insulate it
15941 against any @acronym{GCC} optimizations that would fail to support that
15942 behavior, you should use @acronym{GCC}'s @option{-fwrapv} option, which
15943 causes signed overflow to wrap around reliably (except for division and
15944 remainder, as discussed in the next section).
15946 If you need to port to platforms where signed integer overflow does not
15947 reliably wrap around (e.g., due to hardware overflow checking, or to
15948 highly aggressive optimizations), you should consider debugging with
15949 @acronym{GCC}'s @option{-ftrapv} option, which causes signed overflow to
15950 raise an exception.
15952 @node Signed Integer Division
15953 @subsection Signed Integer Division and Integer Overflow
15954 @cindex division, integer
15957 integer division is not always harmless: for example, on CPUs of the
15958 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
15959 which by default terminates the program. Worse, taking the remainder
15960 of these two values typically yields the same signal on these CPUs,
15961 even though the C standard requires @code{INT_MIN % -1} to yield zero
15962 because the expression does not overflow.
15964 @node Null Pointers
15965 @section Properties of Null Pointers
15966 @cindex null pointers
15968 Most modern hosts reliably fail when you attempt to dereference a null
15971 On almost all modern hosts, null pointers use an all-bits-zero internal
15972 representation, so you can reliably use @code{memset} with 0 to set all
15973 the pointers in an array to null values.
15975 If @code{p} is a null pointer to an object type, the C expression
15976 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
15977 the standard says that it has undefined behavior.
15979 @node Buffer Overruns
15980 @section Buffer Overruns and Subscript Errors
15981 @cindex buffer overruns
15983 Buffer overruns and subscript errors are the most common dangerous
15984 errors in C programs. They result in undefined behavior because storing
15985 outside an array typically modifies storage that is used by some other
15986 object, and most modern systems lack runtime checks to catch these
15987 errors. Programs should not rely on buffer overruns being caught.
15989 There is one exception to the usual rule that a portable program cannot
15990 address outside an array. In C, it is valid to compute the address just
15991 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15992 so long as you do not dereference the resulting pointer. But it is not
15993 valid to compute the address just before an object, e.g., @code{&a[-1]};
15994 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
15995 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15996 reliable in general, and it is usually easy enough to avoid the
15997 potential portability problem, e.g., by allocating an extra unused array
15998 element at the start or end.
16000 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
16002 users might also consider using the @option{-fmudflap} option to catch
16005 Buffer overruns are usually caused by off-by-one errors, but there are
16006 more subtle ways to get them.
16008 Using @code{int} values to index into an array or compute array sizes
16009 causes problems on typical 64-bit hosts where an array index might
16010 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
16011 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
16012 are signed, and are wide enough in practice.
16014 If you add or multiply two numbers to calculate an array size, e.g.,
16015 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
16016 multiplication overflows.
16018 Many implementations of the @code{alloca} function silently misbehave
16019 and can generate buffer overflows if given sizes that are too large.
16020 The size limits are implementation dependent, but are at least 4000
16021 bytes on all platforms that we know about.
16023 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
16024 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
16025 portable code should not use them unless the inputs are known to be
16026 within certain limits. The time-related functions can overflow their
16027 buffers if given timestamps out of range (e.g., a year less than -999
16028 or greater than 9999). Time-related buffer overflows cannot happen with
16029 recent-enough versions of the @acronym{GNU} C library, but are possible
16031 implementations. The @code{gets} function is the worst, since it almost
16032 invariably overflows its buffer when presented with an input line larger
16035 @node Volatile Objects
16036 @section Volatile Objects
16037 @cindex volatile objects
16039 The keyword @code{volatile} is often misunderstood in portable code.
16040 Its use inhibits some memory-access optimizations, but programmers often
16041 wish that it had a different meaning than it actually does.
16043 @code{volatile} was designed for code that accesses special objects like
16044 memory-mapped device registers whose contents spontaneously change.
16045 Such code is inherently low-level, and it is difficult to specify
16046 portably what @code{volatile} means in these cases. The C standard
16047 says, ``What constitutes an access to an object that has
16048 volatile-qualified type is implementation-defined,'' so in theory each
16049 implementation is supposed to fill in the gap by documenting what
16050 @code{volatile} means for that implementation. In practice, though,
16051 this documentation is usually absent or incomplete.
16053 One area of confusion is the distinction between objects defined with
16054 volatile types, and volatile lvalues. From the C standard's point of
16055 view, an object defined with a volatile type has externally visible
16056 behavior. You can think of such objects as having little oscilloscope
16057 probes attached to them, so that the user can observe some properties of
16058 accesses to them, just as the user can observe data written to output
16059 files. However, the standard does not make it clear whether users can
16060 observe accesses by volatile lvalues to ordinary objects. For example:
16063 /* Declare and access a volatile object.
16064 Accesses to X are "visible" to users. */
16065 static int volatile x;
16068 /* Access two ordinary objects via a volatile lvalue.
16069 It's not clear whether accesses to *P are "visible". */
16071 int *z = malloc (sizeof (int));
16079 Programmers often wish that @code{volatile} meant ``Perform the memory
16080 access here and now, without merging several memory accesses, without
16081 changing the memory word size, and without reordering.'' But the C
16082 standard does not require this. For objects defined with a volatile
16083 type, accesses must be done before the next sequence point; but
16084 otherwise merging, reordering, and word-size change is allowed. Worse,
16085 it is not clear from the standard whether volatile lvalues provide more
16086 guarantees in general than nonvolatile lvalues, if the underlying
16087 objects are ordinary.
16089 Even when accessing objects defined with a volatile type,
16090 the C standard allows only
16091 extremely limited signal handlers: the behavior is undefined if a signal
16092 handler reads any nonlocal object, or writes to any nonlocal object
16093 whose type is not @code{sig_atomic_t volatile}, or calls any standard
16094 library function other than @code{abort}, @code{signal}, and (if C99)
16095 @code{_Exit}. Hence C compilers need not worry about a signal handler
16096 disturbing ordinary computation, unless the computation accesses a
16097 @code{sig_atomic_t volatile} lvalue that is not a local variable.
16098 (There is an obscure exception for accesses via a pointer to a volatile
16099 character, since it may point into part of a @code{sig_atomic_t
16100 volatile} object.) Posix
16101 adds to the list of library functions callable from a portable signal
16102 handler, but otherwise is like the C standard in this area.
16104 Some C implementations allow memory-access optimizations within each
16105 translation unit, such that actual behavior agrees with the behavior
16106 required by the standard only when calling a function in some other
16107 translation unit, and a signal handler acts like it was called from a
16108 different translation unit. The C standard hints that in these
16109 implementations, objects referred to by signal handlers ``would require
16110 explicit specification of @code{volatile} storage, as well as other
16111 implementation-defined restrictions.'' But unfortunately even for this
16112 special case these other restrictions are often not documented well.
16113 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
16114 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
16115 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
16116 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
16117 restrictions imposed by the @acronym{GNU} C library. Restrictions
16118 differ on other platforms.
16120 If possible, it is best to use a signal handler that fits within the
16121 limits imposed by the C and Posix standards.
16123 If this is not practical, you can try the following rules of thumb. A
16124 signal handler should access only volatile lvalues, preferably lvalues
16125 that refer to objects defined with a volatile type, and should not
16126 assume that the accessed objects have an internally consistent state
16127 if they are larger than a machine word. Furthermore, installers
16128 should employ compilers and compiler options that are commonly used
16129 for building operating system kernels, because kernels often need more
16130 from @code{volatile} than the C Standard requires, and installers who
16131 compile an application in a similar environment can sometimes benefit
16132 from the extra constraints imposed by kernels on compilers.
16133 Admittedly we are handwaving somewhat here, as there are few
16134 guarantees in this area; the rules of thumb may help to fix some bugs
16135 but there is a good chance that they will not fix them all.
16137 For @code{volatile}, C++ has the same problems that C does.
16138 Multithreaded applications have even more problems with @code{volatile},
16139 but they are beyond the scope of this section.
16141 The bottom line is that using @code{volatile} typically hurts
16142 performance but should not hurt correctness. In some cases its use
16143 does help correctness, but these cases are often so poorly understood
16144 that all too often adding @code{volatile} to a data structure merely
16145 alleviates some symptoms of a bug while not fixing the bug in general.
16147 @node Floating Point Portability
16148 @section Floating Point Portability
16149 @cindex floating point
16151 Almost all modern systems use IEEE-754 floating point, and it is safe to
16152 assume IEEE-754 in most portable code these days. For more information,
16153 please see David Goldberg's classic paper
16154 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
16155 Scientist Should Know About Floating-Point Arithmetic}.
16157 @node Exiting Portably
16158 @section Exiting Portably
16159 @cindex exiting portably
16161 A C or C++ program can exit with status @var{N} by returning
16162 @var{N} from the @code{main} function. Portable programs are supposed
16163 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
16164 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
16165 fail by exiting with status 1, and test programs that assume Posix can
16166 fail by exiting with status values from 1 through 255. Programs on
16167 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
16168 status when @code{main} returned nonzero, but ancient systems like these
16169 are no longer of practical concern.
16171 A program can also exit with status @var{N} by passing @var{N} to the
16172 @code{exit} function, and a program can fail by calling the @code{abort}
16173 function. If a program is specialized to just some platforms, it can fail
16174 by calling functions specific to those platforms, e.g., @code{_exit}
16175 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
16176 function should be declared, typically by including a header. For
16177 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
16178 either directly or via the default includes (@pxref{Default Includes}).
16180 A program can fail due to undefined behavior such as dereferencing a null
16181 pointer, but this is not recommended as undefined behavior allows an
16182 implementation to do whatever it pleases and this includes exiting
16186 @c ================================================== Manual Configuration
16188 @node Manual Configuration
16189 @chapter Manual Configuration
16191 A few kinds of features can't be guessed automatically by running test
16192 programs. For example, the details of the object-file format, or
16193 special options that need to be passed to the compiler or linker. You
16194 can check for such features using ad-hoc means, such as having
16195 @command{configure} check the output of the @code{uname} program, or
16196 looking for libraries that are unique to particular systems. However,
16197 Autoconf provides a uniform method for handling unguessable features.
16200 * Specifying Names:: Specifying the system type
16201 * Canonicalizing:: Getting the canonical system type
16202 * Using System Type:: What to do with the system type
16205 @node Specifying Names
16206 @section Specifying the System Type
16207 @cindex System type
16210 @command{configure} scripts can make decisions based on a canonical name
16211 for the system type, which has the form:
16212 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
16213 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
16215 @command{configure} can usually guess the canonical name for the type of
16216 system it's running on. To do so it runs a script called
16217 @command{config.guess}, which infers the name using the @code{uname}
16218 command or symbols predefined by the C preprocessor.
16220 Alternately, the user can specify the system type with command line
16221 arguments to @command{configure}. Doing so is necessary when
16222 cross-compiling. In the most complex case of cross-compiling, three
16223 system types are involved. The options to specify them are:
16226 @item --build=@var{build-type}
16227 the type of system on which the package is being configured and
16228 compiled. It defaults to the result of running @command{config.guess}.
16230 @item --host=@var{host-type}
16231 the type of system on which the package runs. By default it is the
16232 same as the build machine. Specifying it enables the cross-compilation
16235 @item --target=@var{target-type}
16236 the type of system for which any compiler tools in the package
16237 produce code (rarely needed). By default, it is the same as host.
16240 If you mean to override the result of @command{config.guess}, use
16241 @option{--build}, not @option{--host}, since the latter enables
16242 cross-compilation. For historical reasons,
16243 whenever you specify @option{--host},
16244 be sure to specify @option{--build} too; this will be fixed in the
16245 future. So, to enter cross-compilation mode, use a command like this
16248 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
16252 Note that if you do not specify @option{--host}, @command{configure}
16253 fails if it can't run the code generated by the specified compiler. For
16254 example, configuring as follows fails:
16257 ./configure CC=m68k-coff-gcc
16260 In the future, when cross-compiling Autoconf will @emph{not}
16261 accept tools (compilers, linkers, assemblers) whose name is not
16262 prefixed with the host type. The only case when this may be
16263 useful is when you really are not cross-compiling, but only
16264 building for a least-common-denominator architecture: an example
16265 is building for @code{i386-pc-linux-gnu} while running on an
16266 @code{i686-pc-linux-gnu} architecture. In this case, some particular
16267 pairs might be similar enough to let you get away with the system
16268 compilers, but in general the compiler might make bogus assumptions
16269 on the host: if you know what you are doing, please create symbolic
16270 links from the host compiler to the build compiler.
16272 @cindex @command{config.sub}
16273 @command{configure} recognizes short aliases for many system types; for
16274 example, @samp{decstation} can be used instead of
16275 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
16276 @command{config.sub} to canonicalize system type aliases.
16278 This section deliberately omits the description of the obsolete
16279 interface; see @ref{Hosts and Cross-Compilation}.
16282 @node Canonicalizing
16283 @section Getting the Canonical System Type
16284 @cindex System type
16285 @cindex Canonical system type
16287 The following macros make the system type available to @command{configure}
16290 @ovindex build_alias
16291 @ovindex host_alias
16292 @ovindex target_alias
16294 The variables @samp{build_alias}, @samp{host_alias}, and
16295 @samp{target_alias} are always exactly the arguments of @option{--build},
16296 @option{--host}, and @option{--target}; in particular, they are left empty
16297 if the user did not use them, even if the corresponding
16298 @code{AC_CANONICAL} macro was run. Any configure script may use these
16299 variables anywhere. These are the variables that should be used when in
16300 interaction with the user.
16302 If you need to recognize some special environments based on their system
16303 type, run the following macros to get canonical system names. These
16304 variables are not set before the macro call.
16306 If you use these macros, you must distribute @command{config.guess} and
16307 @command{config.sub} along with your source code. @xref{Output}, for
16308 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
16309 to control in which directory @command{configure} looks for those scripts.
16312 @defmac AC_CANONICAL_BUILD
16313 @acindex{CANONICAL_BUILD}
16316 @ovindex build_vendor
16318 Compute the canonical build-system type variable, @code{build}, and its
16319 three individual parts @code{build_cpu}, @code{build_vendor}, and
16322 If @option{--build} was specified, then @code{build} is the
16323 canonicalization of @code{build_alias} by @command{config.sub},
16324 otherwise it is determined by the shell script @command{config.guess}.
16327 @defmac AC_CANONICAL_HOST
16328 @acindex{CANONICAL_HOST}
16331 @ovindex host_vendor
16333 Compute the canonical host-system type variable, @code{host}, and its
16334 three individual parts @code{host_cpu}, @code{host_vendor}, and
16337 If @option{--host} was specified, then @code{host} is the
16338 canonicalization of @code{host_alias} by @command{config.sub},
16339 otherwise it defaults to @code{build}.
16342 @defmac AC_CANONICAL_TARGET
16343 @acindex{CANONICAL_TARGET}
16345 @ovindex target_cpu
16346 @ovindex target_vendor
16348 Compute the canonical target-system type variable, @code{target}, and its
16349 three individual parts @code{target_cpu}, @code{target_vendor}, and
16352 If @option{--target} was specified, then @code{target} is the
16353 canonicalization of @code{target_alias} by @command{config.sub},
16354 otherwise it defaults to @code{host}.
16357 Note that there can be artifacts due to the backward compatibility
16358 code. See @xref{Hosts and Cross-Compilation}, for more.
16360 @node Using System Type
16361 @section Using the System Type
16363 In @file{configure.ac} the system type is generally used by one or more
16364 @code{case} statements to select system-specifics. Shell wildcards can
16365 be used to match a group of system types.
16367 For example, an extra assembler code object file could be chosen, giving
16368 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
16369 following would be used in a makefile to add the object to a
16370 program or library.
16374 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
16375 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
16378 AC_SUBST([CYCLE_OBJ])
16381 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
16382 to select variant source files, for example optimized code for some
16383 CPUs. The configured CPU type doesn't always indicate exact CPU types,
16384 so some runtime capability checks may be necessary too.
16388 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
16389 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
16390 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
16394 The host system type can also be used to find cross-compilation tools
16395 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
16397 The above examples all show @samp{$host}, since this is where the code
16398 is going to run. Only rarely is it necessary to test @samp{$build}
16399 (which is where the build is being done).
16401 Whenever you're tempted to use @samp{$host} it's worth considering
16402 whether some sort of probe would be better. New system types come along
16403 periodically or previously missing features are added. Well-written
16404 probes can adapt themselves to such things, but hard-coded lists of
16405 names can't. Here are some guidelines,
16409 Availability of libraries and library functions should always be checked
16412 Variant behavior of system calls is best identified with runtime tests
16413 if possible, but bug workarounds or obscure difficulties might have to
16414 be driven from @samp{$host}.
16416 Assembler code is inevitably highly CPU-specific and is best selected
16417 according to @samp{$host_cpu}.
16419 Assembler variations like underscore prefix on globals or ELF versus
16420 COFF type directives are however best determined by probing, perhaps
16421 even examining the compiler output.
16424 @samp{$target} is for use by a package creating a compiler or similar.
16425 For ordinary packages it's meaningless and should not be used. It
16426 indicates what the created compiler should generate code for, if it can
16427 cross-compile. @samp{$target} generally selects various hard-coded CPU
16428 and system conventions, since usually the compiler or tools under
16429 construction themselves determine how the target works.
16432 @c ===================================================== Site Configuration.
16434 @node Site Configuration
16435 @chapter Site Configuration
16437 @command{configure} scripts support several kinds of local configuration
16438 decisions. There are ways for users to specify where external software
16439 packages are, include or exclude optional features, install programs
16440 under modified names, and set default values for @command{configure}
16444 * Help Formatting:: Customizing @samp{configure --help}
16445 * External Software:: Working with other optional software
16446 * Package Options:: Selecting optional features
16447 * Pretty Help Strings:: Formatting help string
16448 * Option Checking:: Controlling checking of @command{configure} options
16449 * Site Details:: Configuring site details
16450 * Transforming Names:: Changing program names when installing
16451 * Site Defaults:: Giving @command{configure} local defaults
16454 @node Help Formatting
16455 @section Controlling Help Output
16457 Users consult @samp{configure --help} to learn of configuration
16458 decisions specific to your package. By default, @command{configure}
16459 breaks this output into sections for each type of option; within each
16460 section, help strings appear in the order @file{configure.ac} defines
16466 --enable-bar include bar
16473 @defmac AC_PRESERVE_HELP_ORDER
16474 @acindex{PRESERVE_HELP_ORDER}
16476 Request an alternate @option{--help} format, in which options of all
16477 types appear together, in the order defined. Call this macro before any
16478 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
16481 Optional Features and Packages:
16483 --enable-bar include bar
16489 @node External Software
16490 @section Working With External Software
16491 @cindex External software
16493 Some packages require, or can optionally use, other software packages
16494 that are already installed. The user can give @command{configure}
16495 command line options to specify which such external software to use.
16496 The options have one of these forms:
16498 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16501 --with-@var{package}[=@var{arg}]
16502 --without-@var{package}
16505 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
16506 instead of some other linker. @option{--with-x} means work with The X
16509 The user can give an argument by following the package name with
16510 @samp{=} and the argument. Giving an argument of @samp{no} is for
16511 packages that are used by default; it says to @emph{not} use the
16512 package. An argument that is neither @samp{yes} nor @samp{no} could
16513 include a name or number of a version of the other package, to specify
16514 more precisely which other package this program is supposed to work
16515 with. If no argument is given, it defaults to @samp{yes}.
16516 @option{--without-@var{package}} is equivalent to
16517 @option{--with-@var{package}=no}.
16519 Normally @command{configure} scripts complain about
16520 @option{--with-@var{package}} options that they do not support.
16521 @xref{Option Checking}, for details, and for how to override the
16524 For each external software package that may be used, @file{configure.ac}
16525 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
16526 user asked to use it. Whether each package is used or not by default,
16527 and which arguments are valid, is up to you.
16529 @anchor{AC_ARG_WITH}
16530 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @
16531 @ovar{action-if-given}, @ovar{action-if-not-given})
16533 If the user gave @command{configure} the option @option{--with-@var{package}}
16534 or @option{--without-@var{package}}, run shell commands
16535 @var{action-if-given}. If neither option was given, run shell commands
16536 @var{action-if-not-given}. The name @var{package} indicates another
16537 software package that this program should work with. It should consist
16538 only of alphanumeric characters, dashes, and dots.
16540 The option's argument is available to the shell commands
16541 @var{action-if-given} in the shell variable @code{withval}, which is
16542 actually just the value of the shell variable named
16543 @code{with_@var{package}}, with any non-alphanumeric characters in
16544 @var{package} changed into @samp{_}. You may use that variable instead,
16547 The argument @var{help-string} is a description of the option that
16550 --with-readline support fancy command line editing
16554 @var{help-string} may be more than one line long, if more detail is
16555 needed. Just make sure the columns line up in @samp{configure
16556 --help}. Avoid tabs in the help string. You'll need to enclose the
16557 help string in @samp{[} and @samp{]} in order to produce the leading
16560 You should format your @var{help-string} with the macro
16561 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16563 The following example shows how to use the @code{AC_ARG_WITH} macro in
16564 a common situation. You want to let the user decide whether to enable
16565 support for an external library (e.g., the readline library); if the user
16566 specified neither @option{--with-readline} nor @option{--without-readline},
16567 you want to enable support for readline only if the library is available
16570 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16572 AC_ARG_WITH([readline],
16573 [AS_HELP_STRING([--with-readline],
16574 [support fancy command line editing @@<:@@default=check@@:>@@])],
16576 [with_readline=check])
16579 AS_IF([test "x$with_readline" != xno],
16580 [AC_CHECK_LIB([readline], [main],
16581 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16582 AC_DEFINE([HAVE_LIBREADLINE], [1],
16583 [Define if you have libreadline])
16585 [if test "x$with_readline" != xcheck; then
16587 [--with-readline was given, but test for readline failed])
16592 The next example shows how to use @code{AC_ARG_WITH} to give the user the
16593 possibility to enable support for the readline library, in case it is still
16594 experimental and not well tested, and is therefore disabled by default.
16596 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16598 AC_ARG_WITH([readline],
16599 [AS_HELP_STRING([--with-readline],
16600 [enable experimental support for readline])],
16602 [with_readline=no])
16605 AS_IF([test "x$with_readline" != xno],
16606 [AC_CHECK_LIB([readline], [main],
16607 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16608 AC_DEFINE([HAVE_LIBREADLINE], [1],
16609 [Define if you have libreadline])
16612 [--with-readline was given, but test for readline failed])],
16616 The last example shows how to use @code{AC_ARG_WITH} to give the user the
16617 possibility to disable support for the readline library, given that it is
16618 an important feature and that it should be enabled by default.
16620 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16622 AC_ARG_WITH([readline],
16623 [AS_HELP_STRING([--without-readline],
16624 [disable support for readline])],
16626 [with_readline=yes])
16629 AS_IF([test "x$with_readline" != xno],
16630 [AC_CHECK_LIB([readline], [main],
16631 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16632 AC_DEFINE([HAVE_LIBREADLINE], [1],
16633 [Define if you have libreadline])
16636 [readline test failed (--without-readline to disable)])],
16640 These three examples can be easily adapted to the case where
16641 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
16642 @ref{Package Options}).
16645 @node Package Options
16646 @section Choosing Package Options
16647 @cindex Package options
16648 @cindex Options, package
16650 If a software package has optional compile-time features, the user can
16651 give @command{configure} command line options to specify whether to
16652 compile them. The options have one of these forms:
16654 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16657 --enable-@var{feature}[=@var{arg}]
16658 --disable-@var{feature}
16661 These options allow users to choose which optional features to build and
16662 install. @option{--enable-@var{feature}} options should never make a
16663 feature behave differently or cause one feature to replace another.
16664 They should only cause parts of the program to be built rather than left
16667 The user can give an argument by following the feature name with
16668 @samp{=} and the argument. Giving an argument of @samp{no} requests
16669 that the feature @emph{not} be made available. A feature with an
16670 argument looks like @option{--enable-debug=stabs}. If no argument is
16671 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
16672 equivalent to @option{--enable-@var{feature}=no}.
16674 Normally @command{configure} scripts complain about
16675 @option{--enable-@var{package}} options that they do not support.
16676 @xref{Option Checking}, for details, and for how to override the
16679 For each optional feature, @file{configure.ac} should call
16680 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
16681 to include it. Whether each feature is included or not by default, and
16682 which arguments are valid, is up to you.
16684 @anchor{AC_ARG_ENABLE}
16685 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @
16686 @ovar{action-if-given}, @ovar{action-if-not-given})
16687 @acindex{ARG_ENABLE}
16688 If the user gave @command{configure} the option
16689 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
16690 shell commands @var{action-if-given}. If neither option was given, run
16691 shell commands @var{action-if-not-given}. The name @var{feature}
16692 indicates an optional user-level facility. It should consist only of
16693 alphanumeric characters, dashes, and dots.
16695 The option's argument is available to the shell commands
16696 @var{action-if-given} in the shell variable @code{enableval}, which is
16697 actually just the value of the shell variable named
16698 @code{enable_@var{feature}}, with any non-alphanumeric characters in
16699 @var{feature} changed into @samp{_}. You may use that variable instead,
16700 if you wish. The @var{help-string} argument is like that of
16701 @code{AC_ARG_WITH} (@pxref{External Software}).
16703 You should format your @var{help-string} with the macro
16704 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16706 See the examples suggested with the definition of @code{AC_ARG_WITH}
16707 (@pxref{External Software}) to get an idea of possible applications of
16708 @code{AC_ARG_ENABLE}.
16711 @node Pretty Help Strings
16712 @section Making Your Help Strings Look Pretty
16713 @cindex Help strings
16715 Properly formatting the @samp{help strings} which are used in
16716 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
16717 (@pxref{Package Options}) can be challenging. Specifically, you want
16718 your own @samp{help strings} to line up in the appropriate columns of
16719 @samp{configure --help} just like the standard Autoconf @samp{help
16720 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
16722 @anchor{AS_HELP_STRING}
16723 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
16724 @asindex{HELP_STRING}
16726 Expands into an help string that looks pretty when the user executes
16727 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
16728 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
16729 Options}). The following example makes this clearer.
16733 [AS_HELP_STRING([--with-foo],
16734 [use foo (default is no)])],
16735 [use_foo=$withval],
16739 The second argument of @code{AS_HELP_STRING} is
16740 not a literal, and should not be double quoted.
16741 @xref{Autoconf Language}, for a more detailed explanation.
16742 Then the last few lines of @samp{configure --help} appear like
16746 --enable and --with options recognized:
16747 --with-foo use foo (default is no)
16750 The @code{AS_HELP_STRING} macro is particularly helpful when the
16751 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
16752 arguments, as shown in the following example.
16755 AC_DEFUN([MY_ARG_WITH],
16757 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
16758 [use_[]$1=$withval],
16764 @node Option Checking
16765 @section Controlling Checking of @command{configure} Options
16766 @cindex Options, Package
16768 The @command{configure} script checks its command-line options against a
16769 list of known options, like @option{--help} or @option{--config-cache}.
16770 An unknown option ordinarily indicates a mistake by the user and
16771 @command{configure} halts with an error. However, by default unknown
16772 @option{--with-@var{package}} and @option{--enable-@var{feature}}
16773 options elicit only a warning, to support configuring entire source
16776 Source trees often contain multiple packages with a top-level
16777 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
16778 (@pxref{Subdirectories}). Because the packages generally support
16779 different @option{--with-@var{package}} and
16780 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
16781 Standards say they must accept unrecognized options without halting.
16782 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
16783 automatically disables the warnings.
16785 This default behavior may be modified in two ways. First, the installer
16786 can invoke @command{configure --disable-option-checking} to disable
16787 these warnings, or invoke @command{configure --enable-option-checking=fatal}
16788 options to turn them into fatal errors, respectively. Second, the
16789 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
16791 @defmac AC_DISABLE_OPTION_CHECKING
16792 @acindex{DISABLE_OPTION_CHECKING}
16794 By default, disable warnings related to any unrecognized
16795 @option{--with-@var{package}} or @option{--enable-@var{feature}}
16796 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
16798 The installer can override this behavior by passing
16799 @option{--enable-option-checking} (enable warnings) or
16800 @option{--enable-option-checking=fatal} (enable errors) to
16801 @command{configure}.
16806 @section Configuring Site Details
16807 @cindex Site details
16809 Some software packages require complex site-specific information. Some
16810 examples are host names to use for certain services, company names, and
16811 email addresses to contact. Since some configuration scripts generated
16812 by Metaconfig ask for such information interactively, people sometimes
16813 wonder how to get that information in Autoconf-generated configuration
16814 scripts, which aren't interactive.
16816 Such site configuration information should be put in a file that is
16817 edited @emph{only by users}, not by programs. The location of the file
16818 can either be based on the @code{prefix} variable, or be a standard
16819 location such as the user's home directory. It could even be specified
16820 by an environment variable. The programs should examine that file at
16821 runtime, rather than at compile time. Runtime configuration is more
16822 convenient for users and makes the configuration process simpler than
16823 getting the information while configuring. @xref{Directory Variables, ,
16824 Variables for Installation Directories, standards, @acronym{GNU} Coding
16825 Standards}, for more information on where to put data files.
16827 @node Transforming Names
16828 @section Transforming Program Names When Installing
16829 @cindex Transforming program names
16830 @cindex Program names, transforming
16832 Autoconf supports changing the names of programs when installing them.
16833 In order to use these transformations, @file{configure.ac} must call the
16834 macro @code{AC_ARG_PROGRAM}.
16836 @defmac AC_ARG_PROGRAM
16837 @acindex{ARG_PROGRAM}
16838 @ovindex program_transform_name
16839 Place in output variable @code{program_transform_name} a sequence of
16840 @code{sed} commands for changing the names of installed programs.
16842 If any of the options described below are given to @command{configure},
16843 program names are transformed accordingly. Otherwise, if
16844 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
16845 is given, the target type followed by a dash is used as a prefix.
16846 Otherwise, no program name transformation is done.
16850 * Transformation Options:: @command{configure} options to transform names
16851 * Transformation Examples:: Sample uses of transforming names
16852 * Transformation Rules:: Makefile uses of transforming names
16855 @node Transformation Options
16856 @subsection Transformation Options
16858 You can specify name transformations by giving @command{configure} these
16859 command line options:
16862 @item --program-prefix=@var{prefix}
16863 prepend @var{prefix} to the names;
16865 @item --program-suffix=@var{suffix}
16866 append @var{suffix} to the names;
16868 @item --program-transform-name=@var{expression}
16869 perform @code{sed} substitution @var{expression} on the names.
16872 @node Transformation Examples
16873 @subsection Transformation Examples
16875 These transformations are useful with programs that can be part of a
16876 cross-compilation development environment. For example, a
16877 cross-assembler running on a Sun 4 configured with
16878 @option{--target=i960-vxworks} is normally installed as
16879 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
16880 with a native Sun 4 assembler.
16882 You can force a program name to begin with @file{g}, if you don't want
16883 @acronym{GNU} programs installed on your system to shadow other programs with
16884 the same name. For example, if you configure @acronym{GNU} @code{diff} with
16885 @option{--program-prefix=g}, then when you run @samp{make install} it is
16886 installed as @file{/usr/local/bin/gdiff}.
16888 As a more sophisticated example, you could use
16891 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
16895 to prepend @samp{g} to most of the program names in a source tree,
16896 excepting those like @code{gdb} that already have one and those like
16897 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
16898 assuming that you have a source tree containing those programs that is
16899 set up to use this feature.)
16901 One way to install multiple versions of some programs simultaneously is
16902 to append a version number to the name of one or both. For example, if
16903 you want to keep Autoconf version 1 around for awhile, you can configure
16904 Autoconf version 2 using @option{--program-suffix=2} to install the
16905 programs as @file{/usr/local/bin/autoconf2},
16906 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
16907 that only the binaries are renamed, therefore you'd have problems with
16908 the library files which might overlap.
16910 @node Transformation Rules
16911 @subsection Transformation Rules
16913 Here is how to use the variable @code{program_transform_name} in a
16914 @file{Makefile.in}:
16917 PROGRAMS = cp ls rm
16918 transform = @@program_transform_name@@
16920 for p in $(PROGRAMS); do \
16921 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
16922 sed '$(transform)'`; \
16926 for p in $(PROGRAMS); do \
16927 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
16931 It is guaranteed that @code{program_transform_name} is never empty, and
16932 that there are no useless separators. Therefore you may safely embed
16933 @code{program_transform_name} within a sed program using @samp{;}:
16936 transform = @@program_transform_name@@
16937 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
16940 Whether to do the transformations on documentation files (Texinfo or
16941 @code{man}) is a tricky question; there seems to be no perfect answer,
16942 due to the several reasons for name transforming. Documentation is not
16943 usually particular to a specific architecture, and Texinfo files do not
16944 conflict with system documentation. But they might conflict with
16945 earlier versions of the same files, and @code{man} pages sometimes do
16946 conflict with system documentation. As a compromise, it is probably
16947 best to do name transformations on @code{man} pages but not on Texinfo
16950 @node Site Defaults
16951 @section Setting Site Defaults
16952 @cindex Site defaults
16954 Autoconf-generated @command{configure} scripts allow your site to provide
16955 default values for some configuration values. You do this by creating
16956 site- and system-wide initialization files.
16958 @evindex CONFIG_SITE
16959 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
16960 uses its value as the name of a shell script to read. Otherwise, it
16961 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
16962 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
16963 settings in machine-specific files override those in machine-independent
16964 ones in case of conflict.
16966 Site files can be arbitrary shell scripts, but only certain kinds of
16967 code are really appropriate to be in them. Because @command{configure}
16968 reads any cache file after it has read any site files, a site file can
16969 define a default cache file to be shared between all Autoconf-generated
16970 @command{configure} scripts run on that system (@pxref{Cache Files}). If
16971 you set a default cache file in a site file, it is a good idea to also
16972 set the output variable @code{CC} in that site file, because the cache
16973 file is only valid for a particular compiler, but many systems have
16976 You can examine or override the value set by a command line option to
16977 @command{configure} in a site file; options set shell variables that have
16978 the same names as the options, with any dashes turned into underscores.
16979 The exceptions are that @option{--without-} and @option{--disable-} options
16980 are like giving the corresponding @option{--with-} or @option{--enable-}
16981 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
16982 sets the variable @code{cache_file} to the value @samp{localcache};
16983 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16984 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16985 variable @code{prefix} to the value @samp{/usr}; etc.
16987 Site files are also good places to set default values for other output
16988 variables, such as @code{CFLAGS}, if you need to give them non-default
16989 values: anything you would normally do, repetitively, on the command
16990 line. If you use non-default values for @var{prefix} or
16991 @var{exec_prefix} (wherever you locate the site file), you can set them
16992 in the site file if you specify it with the @code{CONFIG_SITE}
16993 environment variable.
16995 You can set some cache values in the site file itself. Doing this is
16996 useful if you are cross-compiling, where it is impossible to check features
16997 that require running a test program. You could ``prime the cache'' by
16998 setting those values correctly for that system in
16999 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
17000 variables you need to set, look for shell variables with @samp{_cv_} in
17001 their names in the affected @command{configure} scripts, or in the Autoconf
17002 M4 source code for those macros.
17004 The cache file is careful to not override any variables set in the site
17005 files. Similarly, you should not override command-line options in the
17006 site files. Your code should check that variables such as @code{prefix}
17007 and @code{cache_file} have their default values (as set near the top of
17008 @command{configure}) before changing them.
17010 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
17011 command @samp{configure --prefix=/usr/share/local/gnu} would read this
17012 file (if @code{CONFIG_SITE} is not set to a different file).
17015 # config.site for configure
17017 # Change some defaults.
17018 test "$prefix" = NONE && prefix=/usr/share/local/gnu
17019 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
17020 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
17021 test "$localstatedir" = '$prefix/var' && localstatedir=/var
17023 # Give Autoconf 2.x generated configure scripts a shared default
17024 # cache file for feature test results, architecture-specific.
17025 if test "$cache_file" = /dev/null; then
17026 cache_file="$prefix/var/config.cache"
17027 # A cache file is only valid for one C compiler.
17033 @c ============================================== Running configure Scripts.
17035 @node Running configure Scripts
17036 @chapter Running @command{configure} Scripts
17037 @cindex @command{configure}
17039 Below are instructions on how to configure a package that uses a
17040 @command{configure} script, suitable for inclusion as an @file{INSTALL}
17041 file in the package. A plain-text version of @file{INSTALL} which you
17042 may use comes with Autoconf.
17045 * Basic Installation:: Instructions for typical cases
17046 * Compilers and Options:: Selecting compilers and optimization
17047 * Multiple Architectures:: Compiling for multiple architectures at once
17048 * Installation Names:: Installing in different directories
17049 * Optional Features:: Selecting optional features
17050 * System Type:: Specifying the system type
17051 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
17052 * Defining Variables:: Specifying the compiler etc.
17053 * configure Invocation:: Changing how @command{configure} runs
17057 @include install.texi
17060 @c ============================================== config.status Invocation
17062 @node config.status Invocation
17063 @chapter config.status Invocation
17064 @cindex @command{config.status}
17066 The @command{configure} script creates a file named @file{config.status},
17067 which actually configures, @dfn{instantiates}, the template files. It
17068 also records the configuration options that were specified when the
17069 package was last configured in case reconfiguring is needed.
17073 ./config.status @var{option}@dots{} [@var{file}@dots{}]
17076 It configures the @var{files}; if none are specified, all the templates
17077 are instantiated. The files must be specified without their
17078 dependencies, as in
17081 ./config.status foobar
17088 ./config.status foobar:foo.in:bar.in
17091 The supported options are:
17096 Print a summary of the command line options, the list of the template
17101 Print the version number of Autoconf and the configuration settings,
17107 Do not print progress messages.
17111 Don't remove the temporary files.
17113 @item --file=@var{file}[:@var{template}]
17114 Require that @var{file} be instantiated as if
17115 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
17116 @var{file} and @var{template} may be @samp{-} in which case the standard
17117 output and/or standard input, respectively, is used. If a
17118 @var{template} file name is relative, it is first looked for in the build
17119 tree, and then in the source tree. @xref{Configuration Actions}, for
17122 This option and the following ones provide one way for separately
17123 distributed packages to share the values computed by @command{configure}.
17124 Doing so can be useful if some of the packages need a superset of the
17125 features that one of them, perhaps a common library, does. These
17126 options allow a @file{config.status} file to create files other than the
17127 ones that its @file{configure.ac} specifies, so it can be used for a
17130 @item --header=@var{file}[:@var{template}]
17131 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
17134 Ask @file{config.status} to update itself and exit (no instantiation).
17135 This option is useful if you change @command{configure}, so that the
17136 results of some tests might be different from the previous run. The
17137 @option{--recheck} option reruns @command{configure} with the same arguments
17138 you used before, plus the @option{--no-create} option, which prevents
17139 @command{configure} from running @file{config.status} and creating
17140 @file{Makefile} and other files, and the @option{--no-recursion} option,
17141 which prevents @command{configure} from running other @command{configure}
17142 scripts in subdirectories. (This is so other Make rules can
17143 run @file{config.status} when it changes; @pxref{Automatic Remaking},
17147 @file{config.status} checks several optional environment variables that
17148 can alter its behavior:
17150 @defvar CONFIG_SHELL
17151 @evindex CONFIG_SHELL
17152 The shell with which to run @command{configure} for the @option{--recheck}
17153 option. It must be Bourne-compatible. The default is a shell that
17154 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
17155 Invoking @command{configure} by hand bypasses this setting, so you may
17156 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
17157 to insure that the same shell is used everywhere. The absolute name of the
17158 shell should be passed.
17161 @defvar CONFIG_STATUS
17162 @evindex CONFIG_STATUS
17163 The file name to use for the shell script that records the
17164 configuration. The default is @file{./config.status}. This variable is
17165 useful when one package uses parts of another and the @command{configure}
17166 scripts shouldn't be merged because they are maintained separately.
17169 You can use @file{./config.status} in your makefiles. For example, in
17170 the dependencies given above (@pxref{Automatic Remaking}),
17171 @file{config.status} is run twice when @file{configure.ac} has changed.
17172 If that bothers you, you can make each run only regenerate the files for
17177 stamp-h: config.h.in config.status
17178 ./config.status config.h
17181 Makefile: Makefile.in config.status
17182 ./config.status Makefile
17186 The calling convention of @file{config.status} has changed; see
17187 @ref{Obsolete config.status Use}, for details.
17190 @c =================================================== Obsolete Constructs
17192 @node Obsolete Constructs
17193 @chapter Obsolete Constructs
17194 @cindex Obsolete constructs
17196 Autoconf changes, and throughout the years some constructs have been
17197 obsoleted. Most of the changes involve the macros, but in some cases
17198 the tools themselves, or even some concepts, are now considered
17201 You may completely skip this chapter if you are new to Autoconf. Its
17202 intention is mainly to help maintainers updating their packages by
17203 understanding how to move to more modern constructs.
17206 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
17207 * acconfig Header:: Additional entries in @file{config.h.in}
17208 * autoupdate Invocation:: Automatic update of @file{configure.ac}
17209 * Obsolete Macros:: Backward compatibility macros
17210 * Autoconf 1:: Tips for upgrading your files
17211 * Autoconf 2.13:: Some fresher tips
17214 @node Obsolete config.status Use
17215 @section Obsolete @file{config.status} Invocation
17217 @file{config.status} now supports arguments to specify the files to
17218 instantiate; see @ref{config.status Invocation}, for more details.
17219 Before, environment variables had to be used.
17221 @defvar CONFIG_COMMANDS
17222 @evindex CONFIG_COMMANDS
17223 The tags of the commands to execute. The default is the arguments given
17224 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
17225 @file{configure.ac}.
17228 @defvar CONFIG_FILES
17229 @evindex CONFIG_FILES
17230 The files in which to perform @samp{@@@var{variable}@@} substitutions.
17231 The default is the arguments given to @code{AC_OUTPUT} and
17232 @code{AC_CONFIG_FILES} in @file{configure.ac}.
17235 @defvar CONFIG_HEADERS
17236 @evindex CONFIG_HEADERS
17237 The files in which to substitute C @code{#define} statements. The
17238 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
17239 macro was not called, @file{config.status} ignores this variable.
17242 @defvar CONFIG_LINKS
17243 @evindex CONFIG_LINKS
17244 The symbolic links to establish. The default is the arguments given to
17245 @code{AC_CONFIG_LINKS}; if that macro was not called,
17246 @file{config.status} ignores this variable.
17249 In @ref{config.status Invocation}, using this old interface, the example
17255 stamp-h: config.h.in config.status
17256 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
17257 CONFIG_HEADERS=config.h ./config.status
17260 Makefile: Makefile.in config.status
17261 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
17262 CONFIG_FILES=Makefile ./config.status
17267 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
17268 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
17269 for @code{CONFIG_COMMANDS}, etc.)
17272 @node acconfig Header
17273 @section @file{acconfig.h}
17275 @cindex @file{acconfig.h}
17276 @cindex @file{config.h.top}
17277 @cindex @file{config.h.bot}
17279 In order to produce @file{config.h.in}, @command{autoheader} needs to
17280 build or to find templates for each symbol. Modern releases of Autoconf
17281 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
17282 Macros}), but in older releases a file, @file{acconfig.h}, contained the
17283 list of needed templates. @command{autoheader} copied comments and
17284 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
17285 the current directory, if present. This file used to be mandatory if
17286 you @code{AC_DEFINE} any additional symbols.
17288 Modern releases of Autoconf also provide @code{AH_TOP} and
17289 @code{AH_BOTTOM} if you need to prepend/append some information to
17290 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
17291 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
17292 @command{autoheader} copies the lines before the line containing
17293 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
17294 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
17295 @command{autoheader} copies the lines after that line to the end of the
17296 file it generates. Either or both of those strings may be omitted. An
17297 even older alternate way to produce the same effect in ancient versions
17298 of Autoconf is to create the files @file{@var{file}.top} (typically
17299 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
17300 directory. If they exist, @command{autoheader} copies them to the
17301 beginning and end, respectively, of its output.
17303 In former versions of Autoconf, the files used in preparing a software
17304 package for distribution were:
17307 configure.ac --. .------> autoconf* -----> configure
17309 [aclocal.m4] --+ `---.
17311 +--> [autoheader*] -> [config.h.in]
17312 [acconfig.h] ----. |
17319 Using only the @code{AH_} macros, @file{configure.ac} should be
17320 self-contained, and should not depend upon @file{acconfig.h} etc.
17323 @node autoupdate Invocation
17324 @section Using @command{autoupdate} to Modernize @file{configure.ac}
17325 @cindex @command{autoupdate}
17327 The @command{autoupdate} program updates a @file{configure.ac} file that
17328 calls Autoconf macros by their old names to use the current macro names.
17329 In version 2 of Autoconf, most of the macros were renamed to use a more
17330 uniform and descriptive naming scheme. @xref{Macro Names}, for a
17331 description of the new scheme. Although the old names still work
17332 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
17333 new names), you can make your @file{configure.ac} files more readable
17334 and make it easier to use the current Autoconf documentation if you
17335 update them to use the new macro names.
17337 @evindex SIMPLE_BACKUP_SUFFIX
17338 If given no arguments, @command{autoupdate} updates @file{configure.ac},
17339 backing up the original version with the suffix @file{~} (or the value
17340 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
17341 set). If you give @command{autoupdate} an argument, it reads that file
17342 instead of @file{configure.ac} and writes the updated file to the
17346 @command{autoupdate} accepts the following options:
17351 Print a summary of the command line options and exit.
17355 Print the version number of Autoconf and exit.
17359 Report processing steps.
17363 Don't remove the temporary files.
17367 Force the update even if the file has not changed. Disregard the cache.
17369 @item --include=@var{dir}
17370 @itemx -I @var{dir}
17371 Also look for input files in @var{dir}. Multiple invocations accumulate.
17372 Directories are browsed from last to first.
17375 @node Obsolete Macros
17376 @section Obsolete Macros
17378 Several macros are obsoleted in Autoconf, for various reasons (typically
17379 they failed to quote properly, couldn't be extended for more recent
17380 issues, etc.). They are still supported, but deprecated: their use
17383 During the jump from Autoconf version 1 to version 2, most of the
17384 macros were renamed to use a more uniform and descriptive naming scheme,
17385 but their signature did not change. @xref{Macro Names}, for a
17386 description of the new naming scheme. Below, if there is just the mapping
17387 from old names to new names for these macros, the reader is invited to
17388 refer to the definition of the new macro for the signature and the
17393 @cvindex _ALL_SOURCE
17394 This macro is a platform-specific subset of
17395 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17400 Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}).
17403 @defmac AC_ARG_ARRAY
17404 @acindex{ARG_ARRAY}
17405 Removed because of limited usefulness.
17410 This macro is obsolete; it does nothing.
17413 @defmac AC_C_LONG_DOUBLE
17414 @acindex{C_LONG_DOUBLE}
17415 @cvindex HAVE_LONG_DOUBLE
17416 If the C compiler supports a working @code{long double} type with more
17417 range or precision than the @code{double} type, define
17418 @code{HAVE_LONG_DOUBLE}.
17420 You should use @code{AC_TYPE_LONG_DOUBLE} or
17421 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17424 @defmac AC_CANONICAL_SYSTEM
17425 @acindex{CANONICAL_SYSTEM}
17426 Determine the system type and set output variables to the names of the
17427 canonical system types. @xref{Canonicalizing}, for details about the
17428 variables this macro sets.
17430 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
17431 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
17432 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
17433 other macros (@pxref{Canonicalizing}).
17436 @defmac AC_CHAR_UNSIGNED
17437 @acindex{CHAR_UNSIGNED}
17438 Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}).
17441 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
17442 @acindex{CHECK_TYPE}
17443 Autoconf, up to 2.13, used to provide this version of
17444 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
17445 it is a member of the @code{CHECK} clan, it does
17446 more than just checking. Secondly, missing types are defined
17447 using @code{#define}, not @code{typedef}, and this can lead to
17448 problems in the case of pointer types.
17450 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
17451 @ref{Generic Types}, for the description of the current macro.
17453 If the type @var{type} is not defined, define it to be the C (or C++)
17454 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
17456 This macro is equivalent to:
17459 AC_CHECK_TYPE([@var{type}], [],
17460 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
17461 [Define to `@var{default}'
17462 if <sys/types.h> does not define.])])
17465 In order to keep backward compatibility, the two versions of
17466 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
17470 If there are three or four arguments, the modern version is used.
17473 If the second argument appears to be a C or C++ type, then the
17474 obsolete version is used. This happens if the argument is a C or C++
17475 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
17476 followed by one of @samp{[(* } and then by a string of zero or more
17477 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
17480 If the second argument is spelled with the alphabet of valid C and C++
17481 types, the user is warned and the modern version is used.
17484 Otherwise, the modern version is used.
17488 You are encouraged either to use a valid builtin type, or to use the
17489 equivalent modern code (see above), or better yet, to use
17490 @code{AC_CHECK_TYPES} together with
17493 #ifndef HAVE_LOFF_T
17494 typedef loff_t off_t;
17498 @c end of AC_CHECK_TYPE
17500 @defmac AC_CHECKING (@var{feature-description})
17505 AC_MSG_NOTICE([checking @var{feature-description}@dots{}]
17509 @xref{AC_MSG_NOTICE}.
17512 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @
17513 @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
17514 @acindex{COMPILE_CHECK}
17515 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
17516 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
17517 addition that it prints @samp{checking for @var{echo-text}} to the
17518 standard output first, if @var{echo-text} is non-empty. Use
17519 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
17520 messages (@pxref{Printing Messages}).
17525 Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}).
17528 @defmac AC_CROSS_CHECK
17529 @acindex{CROSS_CHECK}
17530 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
17537 Check for the Cygwin environment in which case the shell variable
17538 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
17539 means to check the nature of the host is using @code{AC_CANONICAL_HOST}
17540 (@pxref{Canonicalizing}). As a matter of fact this macro is defined as:
17543 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
17545 *cygwin* ) CYGWIN=yes;;
17550 Beware that the variable @env{CYGWIN} has a special meaning when
17551 running Cygwin, and should not be changed. That's yet another reason
17552 not to use this macro.
17555 @defmac AC_DECL_SYS_SIGLIST
17556 @acindex{DECL_SYS_SIGLIST}
17557 @cvindex SYS_SIGLIST_DECLARED
17561 AC_CHECK_DECLS([sys_siglist], [], [],
17562 [#include <signal.h>
17563 /* NetBSD declares sys_siglist in unistd.h. */
17564 #ifdef HAVE_UNISTD_H
17565 # include <unistd.h>
17571 @xref{AC_CHECK_DECLS}.
17574 @defmac AC_DECL_YYTEXT
17575 @acindex{DECL_YYTEXT}
17576 Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
17579 @defmac AC_DIR_HEADER
17580 @acindex{DIR_HEADER}
17585 Like calling @code{AC_FUNC_CLOSEDIR_VOID}
17586 (@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT}
17587 (@pxref{AC_HEADER_DIRENT}),
17588 but defines a different set of C preprocessor macros to indicate which
17589 header file is found:
17591 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
17592 @item Header @tab Old Symbol @tab New Symbol
17593 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
17594 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
17595 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
17596 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
17600 @defmac AC_DYNIX_SEQ
17601 @acindex{DYNIX_SEQ}
17602 If on DYNIX/ptx, add @option{-lseq} to output variable
17603 @code{LIBS}. This macro used to be defined as
17606 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
17610 now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}).
17616 Defined the output variable @code{EXEEXT} based on the output of the
17617 compiler, which is now done automatically. Typically set to empty
17618 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
17623 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
17624 and sets @code{EMXOS2}. Don't use this macro, the dignified means to
17625 check the nature of the host is using @code{AC_CANONICAL_HOST}
17626 (@pxref{Canonicalizing}).
17629 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @
17630 @ovar{action-if-not-given})
17632 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
17633 support providing a help string (@pxref{AC_ARG_ENABLE}).
17638 Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}).
17643 Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}).
17646 @defmac AC_FIND_XTRA
17647 @acindex{FIND_XTRA}
17648 Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}).
17653 Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}).
17656 @defmac AC_FUNC_CHECK
17657 @acindex{FUNC_CHECK}
17658 Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}).
17661 @anchor{AC_FUNC_SETVBUF_REVERSED}
17662 @defmac AC_FUNC_SETVBUF_REVERSED
17663 @acindex{FUNC_SETVBUF_REVERSED}
17664 @cvindex SETVBUF_REVERSED
17665 @c @fuindex setvbuf
17666 @prindex @code{setvbuf}
17667 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
17668 the buffering type as its second argument and the buffer pointer as the
17669 third, instead of the other way around, and defined
17670 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
17671 were those based on SVR2, which became obsolete in 1987, and the macro
17672 is no longer needed.
17675 @defmac AC_FUNC_WAIT3
17676 @acindex{FUNC_WAIT3}
17677 @cvindex HAVE_WAIT3
17678 If @code{wait3} is found and fills in the contents of its third argument
17679 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
17682 These days portable programs should use @code{waitpid}, not
17683 @code{wait3}, as @code{wait3} has been removed from Posix.
17686 @defmac AC_GCC_TRADITIONAL
17687 @acindex{GCC_TRADITIONAL}
17688 Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}).
17691 @defmac AC_GETGROUPS_T
17692 @acindex{GETGROUPS_T}
17693 Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}).
17696 @defmac AC_GETLOADAVG
17697 @acindex{GETLOADAVG}
17698 Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}).
17701 @defmac AC_GNU_SOURCE
17702 @acindex{GNU_SOURCE}
17703 @cvindex _GNU_SOURCE
17704 This macro is a platform-specific subset of
17705 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17708 @defmac AC_HAVE_FUNCS
17709 @acindex{HAVE_FUNCS}
17710 Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}).
17713 @defmac AC_HAVE_HEADERS
17714 @acindex{HAVE_HEADERS}
17715 Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}).
17718 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @
17719 @ovar{action-if-not-found}, @ovar{other-libraries})
17720 @acindex{HAVE_LIBRARY}
17721 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
17722 @var{function} argument of @code{main}. In addition, @var{library} can
17723 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
17724 all of those cases, the compiler is passed @option{-lfoo}. However,
17725 @var{library} cannot be a shell variable; it must be a literal name.
17726 @xref{AC_CHECK_LIB}.
17729 @defmac AC_HAVE_POUNDBANG
17730 @acindex{HAVE_POUNDBANG}
17731 Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}).
17734 @defmac AC_HEADER_CHECK
17735 @acindex{HEADER_CHECK}
17736 Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}).
17739 @defmac AC_HEADER_EGREP
17740 @acindex{HEADER_EGREP}
17741 Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}).
17744 @defmac AC_HELP_STRING
17745 @acindex{HELP_STRING}
17746 Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}).
17749 @defmac AC_INIT (@var{unique-file-in-source-dir})
17751 Formerly @code{AC_INIT} used to have a single argument, and was
17756 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
17758 See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}.
17763 Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}).
17766 @defmac AC_INT_16_BITS
17767 @acindex{INT_16_BITS}
17768 @cvindex INT_16_BITS
17769 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
17770 Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}).
17773 @defmac AC_IRIX_SUN
17775 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
17776 @code{LIBS}. If you were using it to get @code{getmntent}, use
17777 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
17778 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
17779 getpwnam)}. Up to Autoconf 2.13, it used to be
17782 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
17786 now it is defined as
17790 AC_CHECK_LIB([sun], [getpwnam])
17794 See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}.
17797 @defmac AC_ISC_POSIX
17798 @acindex{ISC_POSIX}
17800 This macro adds @option{-lcposix} to output variable @code{LIBS} if
17801 necessary for Posix facilities. Sun dropped support for the obsolete
17802 @sc{interactive} Systems Corporation Unix on 2006-07-23. New programs
17803 need not use this macro. It is implemented as
17804 @code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}).
17809 Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}).
17812 @defmac AC_LANG_CPLUSPLUS
17813 @acindex{LANG_CPLUSPLUS}
17814 Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}).
17817 @defmac AC_LANG_FORTRAN77
17818 @acindex{LANG_FORTRAN77}
17819 Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}).
17822 @defmac AC_LANG_RESTORE
17823 @acindex{LANG_RESTORE}
17824 Select the @var{language} that is saved on the top of the stack, as set
17825 by @code{AC_LANG_SAVE}, remove it from the stack, and call
17826 @code{AC_LANG(@var{language})}. @xref{Language Choice}, for the
17827 preferred way to change languages.
17830 @defmac AC_LANG_SAVE
17831 @acindex{LANG_SAVE}
17832 Remember the current language (as set by @code{AC_LANG}) on a stack.
17833 The current language does not change. @code{AC_LANG_PUSH} is preferred
17834 (@pxref{AC_LANG_PUSH}).
17837 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
17838 @acindex{LINK_FILES}
17839 This is an obsolete version of @code{AC_CONFIG_LINKS}
17840 (@pxref{AC_CONFIG_LINKS}. An updated version of:
17843 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
17851 AC_CONFIG_LINKS([host.h:config/$machine.h
17852 object.h:config/$obj_format.h])
17858 Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}).
17861 @defmac AC_LONG_64_BITS
17862 @acindex{LONG_64_BITS}
17863 @cvindex LONG_64_BITS
17864 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
17865 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead
17866 (@pxref{AC_CHECK_SIZEOF}).
17869 @defmac AC_LONG_DOUBLE
17870 @acindex{LONG_DOUBLE}
17871 If the C compiler supports a working @code{long double} type with more
17872 range or precision than the @code{double} type, define
17873 @code{HAVE_LONG_DOUBLE}.
17875 You should use @code{AC_TYPE_LONG_DOUBLE} or
17876 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17879 @defmac AC_LONG_FILE_NAMES
17880 @acindex{LONG_FILE_NAMES}
17883 AC_SYS_LONG_FILE_NAMES
17886 @xref{AC_SYS_LONG_FILE_NAMES}.
17889 @defmac AC_MAJOR_HEADER
17890 @acindex{MAJOR_HEADER}
17891 Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}).
17894 @defmac AC_MEMORY_H
17896 @cvindex NEED_MEMORY_H
17897 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
17898 defined in @file{memory.h}. Today it is equivalent to
17899 @samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust
17900 your code to depend upon
17901 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
17907 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
17908 environment and sets @code{MINGW32}. Don't use this macro, the
17909 dignified means to check the nature of the host is using
17910 @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
17916 @cvindex _POSIX_SOURCE
17917 @cvindex _POSIX_1_SOURCE
17918 This macro is a platform-specific subset of
17919 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17922 @defmac AC_MINUS_C_MINUS_O
17923 @acindex{MINUS_C_MINUS_O}
17924 Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}).
17929 Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}).
17934 Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}).
17940 Defined the output variable @code{OBJEXT} based on the output of the
17941 compiler, after .c files have been excluded. Typically set to @samp{o}
17942 if Posix, @samp{obj} if a @acronym{DOS} variant.
17943 Now the compiler checking macros handle
17944 this automatically.
17947 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
17949 Make M4 print a message to the standard error output warning that
17950 @var{this-macro-name} is obsolete, and giving the file and line number
17951 where it was called. @var{this-macro-name} should be the name of the
17952 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
17953 it is printed at the end of the warning message; for example, it can be
17954 a suggestion for what to use instead of @var{this-macro-name}.
17959 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
17963 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
17964 services to the user (@pxref{AU_DEFUN}).
17969 Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}).
17972 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
17974 The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted
17975 interface is equivalent to:
17979 AC_CONFIG_FILES(@var{file}@dots{})
17980 AC_CONFIG_COMMANDS([default],
17981 @var{extra-cmds}, @var{init-cmds})
17987 See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}.
17990 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
17991 @acindex{OUTPUT_COMMANDS}
17992 Specify additional shell commands to run at the end of
17993 @file{config.status}, and shell commands to initialize any variables
17994 from @command{configure}. This macro may be called multiple times. It is
17995 obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}).
17997 Here is an unrealistic example:
18001 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
18003 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
18007 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
18008 additional key, an important difference is that
18009 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
18010 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
18011 can safely be given macro calls as arguments:
18014 AC_CONFIG_COMMANDS(foo, [my_FOO()])
18018 Conversely, where one level of quoting was enough for literal strings
18019 with @code{AC_OUTPUT_COMMANDS}, you need two with
18020 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
18024 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
18025 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
18032 Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}).
18037 Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}).
18040 @defmac AC_PROGRAMS_CHECK
18041 @acindex{PROGRAMS_CHECK}
18042 Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}).
18045 @defmac AC_PROGRAMS_PATH
18046 @acindex{PROGRAMS_PATH}
18047 Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}).
18050 @defmac AC_PROGRAM_CHECK
18051 @acindex{PROGRAM_CHECK}
18052 Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}).
18055 @defmac AC_PROGRAM_EGREP
18056 @acindex{PROGRAM_EGREP}
18057 Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}).
18060 @defmac AC_PROGRAM_PATH
18061 @acindex{PROGRAM_PATH}
18062 Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}).
18065 @defmac AC_REMOTE_TAPE
18066 @acindex{REMOTE_TAPE}
18067 Removed because of limited usefulness.
18070 @defmac AC_RESTARTABLE_SYSCALLS
18071 @acindex{RESTARTABLE_SYSCALLS}
18072 This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However,
18073 these days portable programs should use @code{sigaction} with
18074 @code{SA_RESTART} if they want restartable system calls. They should
18075 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
18076 system call is restartable is a dynamic issue, not a configuration-time
18080 @defmac AC_RETSIGTYPE
18081 @acindex{RETSIGTYPE}
18082 Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}).
18087 Removed because of limited usefulness.
18090 @defmac AC_SCO_INTL
18093 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
18094 macro used to do this:
18097 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
18101 Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}).
18104 @defmac AC_SETVBUF_REVERSED
18105 @acindex{SETVBUF_REVERSED}
18108 AC_FUNC_SETVBUF_REVERSED
18111 @xref{AC_FUNC_SETVBUF_REVERSED}.
18114 @defmac AC_SET_MAKE
18116 Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}).
18119 @defmac AC_SIZEOF_TYPE
18120 @acindex{SIZEOF_TYPE}
18121 Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}).
18126 Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}).
18129 @defmac AC_STAT_MACROS_BROKEN
18130 @acindex{STAT_MACROS_BROKEN}
18131 Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}).
18134 @defmac AC_STDC_HEADERS
18135 @acindex{STDC_HEADERS}
18136 Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}).
18141 Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}).
18144 @defmac AC_STRUCT_ST_BLKSIZE
18145 @acindex{STRUCT_ST_BLKSIZE}
18146 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
18147 @cvindex HAVE_ST_BLKSIZE
18148 If @code{struct stat} contains an @code{st_blksize} member, define
18149 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
18150 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
18151 the future. This macro is obsoleted, and should be replaced by
18154 AC_CHECK_MEMBERS([struct stat.st_blksize])
18157 @xref{AC_CHECK_MEMBERS}.
18160 @defmac AC_STRUCT_ST_RDEV
18161 @acindex{STRUCT_ST_RDEV}
18162 @cvindex HAVE_ST_RDEV
18163 @cvindex HAVE_STRUCT_STAT_ST_RDEV
18164 If @code{struct stat} contains an @code{st_rdev} member, define
18165 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
18166 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
18167 in the future. Actually, even the new macro is obsolete and should be
18170 AC_CHECK_MEMBERS([struct stat.st_rdev])
18173 @xref{AC_CHECK_MEMBERS}.
18176 @defmac AC_ST_BLKSIZE
18177 @acindex{ST_BLKSIZE}
18178 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
18181 @defmac AC_ST_BLOCKS
18182 @acindex{ST_BLOCKS}
18183 Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}).
18188 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
18191 @defmac AC_SYS_RESTARTABLE_SYSCALLS
18192 @acindex{SYS_RESTARTABLE_SYSCALLS}
18193 @cvindex HAVE_RESTARTABLE_SYSCALLS
18194 If the system automatically restarts a system call that is interrupted
18195 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
18196 not check whether system calls are restarted in general---it checks whether a
18197 signal handler installed with @code{signal} (but not @code{sigaction})
18198 causes system calls to be restarted. It does not check whether system calls
18199 can be restarted when interrupted by signals that have no handler.
18201 These days portable programs should use @code{sigaction} with
18202 @code{SA_RESTART} if they want restartable system calls. They should
18203 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
18204 system call is restartable is a dynamic issue, not a configuration-time
18208 @defmac AC_SYS_SIGLIST_DECLARED
18209 @acindex{SYS_SIGLIST_DECLARED}
18210 This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that
18211 name is obsolete, as the same functionality is now acheived via
18212 @code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}).
18215 @defmac AC_TEST_CPP
18217 This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by
18218 @code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}).
18221 @defmac AC_TEST_PROGRAM
18222 @acindex{TEST_PROGRAM}
18223 This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by
18224 @code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}).
18227 @defmac AC_TIMEZONE
18229 Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}).
18232 @defmac AC_TIME_WITH_SYS_TIME
18233 @acindex{TIME_WITH_SYS_TIME}
18234 Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}).
18237 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @
18238 @ovar{action-if-true}, @ovar{action-if-false})
18239 @acindex{TRY_COMPILE}
18244 [AC_LANG_PROGRAM([[@var{includes}]],
18245 [[@var{function-body}]])],
18246 [@var{action-if-true}],
18247 [@var{action-if-false}])
18251 @xref{Running the Compiler}.
18253 This macro double quotes both @var{includes} and @var{function-body}.
18255 For C and C++, @var{includes} is any @code{#include} statements needed
18256 by the code in @var{function-body} (@var{includes} is ignored if
18257 the currently selected language is Fortran or Fortran 77). The compiler
18258 and compilation flags are determined by the current language
18259 (@pxref{Language Choice}).
18262 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
18268 [AC_LANG_SOURCE([[@var{input}]])],
18269 [@var{action-if-true}],
18270 [@var{action-if-false}])
18274 @xref{Running the Preprocessor}.
18276 This macro double quotes the @var{input}.
18279 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @
18280 @ovar{action-if-true}, @ovar{action-if-false})
18286 [AC_LANG_PROGRAM([[@var{includes}]],
18287 [[@var{function-body}]])],
18288 [@var{action-if-true}],
18289 [@var{action-if-false}])
18293 @xref{Running the Compiler}.
18295 This macro double quotes both @var{includes} and @var{function-body}.
18297 Depending on the current language (@pxref{Language Choice}), create a
18298 test program to see whether a function whose body consists of
18299 @var{function-body} can be compiled and linked. If the file compiles
18300 and links successfully, run shell commands @var{action-if-found},
18301 otherwise run @var{action-if-not-found}.
18303 This macro double quotes both @var{includes} and @var{function-body}.
18305 For C and C++, @var{includes} is any @code{#include} statements needed
18306 by the code in @var{function-body} (@var{includes} is ignored if
18307 the currently selected language is Fortran or Fortran 77). The compiler
18308 and compilation flags are determined by the current language
18309 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
18310 @code{LIBS} are used for linking.
18313 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @
18314 @ovar{action-if-not-found})
18315 @acindex{TRY_LINK_FUNC}
18316 This macro is equivalent to
18318 AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
18319 [@var{action-if-found}], [@var{action-if-not-found}])
18322 @xref{AC_LINK_IFELSE}.
18325 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @
18326 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
18332 [AC_LANG_SOURCE([[@var{program}]])],
18333 [@var{action-if-true}],
18334 [@var{action-if-false}],
18335 [@var{action-if-cross-compiling}])
18344 Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}).
18347 @defmac AC_UNISTD_H
18349 Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}).
18355 Define @code{USG} if the @acronym{BSD} string functions are defined in
18356 @file{strings.h}. You should no longer depend upon @code{USG}, but on
18357 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
18360 @defmac AC_UTIME_NULL
18361 @acindex{UTIME_NULL}
18362 Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}).
18365 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
18366 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
18367 If the cache file is inconsistent with the current host, target and
18368 build system types, it used to execute @var{cmd} or print a default
18369 error message. This is now handled by default.
18372 @defmac AC_VERBOSE (@var{result-description})
18374 Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}).
18379 Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}).
18384 Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}).
18389 This macro was renamed @code{AC_FUNC_WAIT3}. However, these days
18390 portable programs should use @code{waitpid}, not @code{wait3}, as
18391 @code{wait3} has been removed from Posix.
18396 Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}).
18399 @defmac AC_WITH (@var{package}, @var{action-if-given}, @
18400 @ovar{action-if-not-given})
18402 This is an obsolete version of @code{AC_ARG_WITH} that does not
18403 support providing a help string (@pxref{AC_ARG_WITH}).
18406 @defmac AC_WORDS_BIGENDIAN
18407 @acindex{WORDS_BIGENDIAN}
18408 Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}).
18411 @defmac AC_XENIX_DIR
18412 @acindex{XENIX_DIR}
18414 This macro used to add @option{-lx} to output variable @code{LIBS} if on
18415 Xenix. Also, if @file{dirent.h} is being checked for, added
18416 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
18417 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
18418 running @sc{xenix} on which you should not depend:
18421 AC_MSG_CHECKING([for Xenix])
18422 AC_EGREP_CPP([yes],
18423 [#if defined M_XENIX && !defined M_UNIX
18426 [AC_MSG_RESULT([yes]); XENIX=yes],
18427 [AC_MSG_RESULT([no]); XENIX=])
18430 Don't use this macro, the dignified means to check the nature of the
18431 host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
18434 @defmac AC_YYTEXT_POINTER
18435 @acindex{YYTEXT_POINTER}
18436 This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was
18437 integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
18441 @section Upgrading From Version 1
18442 @cindex Upgrading autoconf
18443 @cindex Autoconf upgrading
18445 Autoconf version 2 is mostly backward compatible with version 1.
18446 However, it introduces better ways to do some things, and doesn't
18447 support some of the ugly things in version 1. So, depending on how
18448 sophisticated your @file{configure.ac} files are, you might have to do
18449 some manual work in order to upgrade to version 2. This chapter points
18450 out some problems to watch for when upgrading. Also, perhaps your
18451 @command{configure} scripts could benefit from some of the new features in
18452 version 2; the changes are summarized in the file @file{NEWS} in the
18453 Autoconf distribution.
18456 * Changed File Names:: Files you might rename
18457 * Changed Makefiles:: New things to put in @file{Makefile.in}
18458 * Changed Macros:: Macro calls you might replace
18459 * Changed Results:: Changes in how to check test results
18460 * Changed Macro Writing:: Better ways to write your own macros
18463 @node Changed File Names
18464 @subsection Changed File Names
18466 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
18467 in a particular package's source directory), you must rename it to
18468 @file{acsite.m4}. @xref{autoconf Invocation}.
18470 If you distribute @file{install.sh} with your package, rename it to
18471 @file{install-sh} so @code{make} builtin rules don't inadvertently
18472 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
18473 looks for the script under both names, but it is best to use the new name.
18475 If you were using @file{config.h.top}, @file{config.h.bot}, or
18476 @file{acconfig.h}, you still can, but you have less clutter if you
18477 use the @code{AH_} macros. @xref{Autoheader Macros}.
18479 @node Changed Makefiles
18480 @subsection Changed Makefiles
18482 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
18483 your @file{Makefile.in} files, so they can take advantage of the values
18484 of those variables in the environment when @command{configure} is run.
18485 Doing this isn't necessary, but it's a convenience for users.
18487 Also add @samp{@@configure_input@@} in a comment to each input file for
18488 @code{AC_OUTPUT}, so that the output files contain a comment saying
18489 they were produced by @command{configure}. Automatically selecting the
18490 right comment syntax for all the kinds of files that people call
18491 @code{AC_OUTPUT} on became too much work.
18493 Add @file{config.log} and @file{config.cache} to the list of files you
18494 remove in @code{distclean} targets.
18496 If you have the following in @file{Makefile.in}:
18499 prefix = /usr/local
18500 exec_prefix = $(prefix)
18504 you must change it to:
18507 prefix = @@prefix@@
18508 exec_prefix = @@exec_prefix@@
18512 The old behavior of replacing those variables without @samp{@@}
18513 characters around them has been removed.
18515 @node Changed Macros
18516 @subsection Changed Macros
18518 Many of the macros were renamed in Autoconf version 2. You can still
18519 use the old names, but the new ones are clearer, and it's easier to find
18520 the documentation for them. @xref{Obsolete Macros}, for a table showing the
18521 new names for the old macros. Use the @command{autoupdate} program to
18522 convert your @file{configure.ac} to using the new macro names.
18523 @xref{autoupdate Invocation}.
18525 Some macros have been superseded by similar ones that do the job better,
18526 but are not call-compatible. If you get warnings about calling obsolete
18527 macros while running @command{autoconf}, you may safely ignore them, but
18528 your @command{configure} script generally works better if you follow
18529 the advice that is printed about what to replace the obsolete macros with. In
18530 particular, the mechanism for reporting the results of tests has
18531 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
18532 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
18533 looks better if you switch to @code{AC_MSG_CHECKING} and
18534 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
18535 in conjunction with cache variables. @xref{Caching Results}.
18539 @node Changed Results
18540 @subsection Changed Results
18542 If you were checking the results of previous tests by examining the
18543 shell variable @code{DEFS}, you need to switch to checking the values of
18544 the cache variables for those tests. @code{DEFS} no longer exists while
18545 @command{configure} is running; it is only created when generating output
18546 files. This difference from version 1 is because properly quoting the
18547 contents of that variable turned out to be too cumbersome and
18548 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
18551 For example, here is a @file{configure.ac} fragment written for Autoconf
18555 AC_HAVE_FUNCS(syslog)
18557 *-DHAVE_SYSLOG*) ;;
18558 *) # syslog is not in the default libraries. See if it's in some other.
18560 for lib in bsd socket inet; do
18561 AC_CHECKING(for syslog in -l$lib)
18562 LIBS="-l$lib $saved_LIBS"
18563 AC_HAVE_FUNCS(syslog)
18565 *-DHAVE_SYSLOG*) break ;;
18573 Here is a way to write it for version 2:
18576 AC_CHECK_FUNCS([syslog])
18577 if test $ac_cv_func_syslog = no; then
18578 # syslog is not in the default libraries. See if it's in some other.
18579 for lib in bsd socket inet; do
18580 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
18581 LIBS="-l$lib $LIBS"; break])
18586 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
18587 backslashes before quotes, you need to remove them. It now works
18588 predictably, and does not treat quotes (except back quotes) specially.
18589 @xref{Setting Output Variables}.
18591 All of the Boolean shell variables set by Autoconf macros now use
18592 @samp{yes} for the true value. Most of them use @samp{no} for false,
18593 though for backward compatibility some use the empty string instead. If
18594 you were relying on a shell variable being set to something like 1 or
18595 @samp{t} for true, you need to change your tests.
18597 @node Changed Macro Writing
18598 @subsection Changed Macro Writing
18600 When defining your own macros, you should now use @code{AC_DEFUN}
18601 instead of @code{define}. @code{AC_DEFUN} automatically calls
18602 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
18603 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
18604 messages on the screen. There's no actual harm in continuing to use the
18605 older way, but it's less convenient and attractive. @xref{Macro
18608 You probably looked at the macros that came with Autoconf as a guide for
18609 how to do things. It would be a good idea to take a look at the new
18610 versions of them, as the style is somewhat improved and they take
18611 advantage of some new features.
18613 If you were doing tricky things with undocumented Autoconf internals
18614 (macros, variables, diversions), check whether you need to change
18615 anything to account for changes that have been made. Perhaps you can
18616 even use an officially supported technique in version 2 instead of
18617 kludging. Or perhaps not.
18619 To speed up your locally written feature tests, add caching to them.
18620 See whether any of your tests are of general enough usefulness to
18621 encapsulate them into macros that you can share.
18624 @node Autoconf 2.13
18625 @section Upgrading From Version 2.13
18626 @cindex Upgrading autoconf
18627 @cindex Autoconf upgrading
18629 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
18630 suits this section@enddots{}
18633 Autoconf version 2.50 is mostly backward compatible with version 2.13.
18634 However, it introduces better ways to do some things, and doesn't
18635 support some of the ugly things in version 2.13. So, depending on how
18636 sophisticated your @file{configure.ac} files are, you might have to do
18637 some manual work in order to upgrade to version 2.50. This chapter
18638 points out some problems to watch for when upgrading. Also, perhaps
18639 your @command{configure} scripts could benefit from some of the new
18640 features in version 2.50; the changes are summarized in the file
18641 @file{NEWS} in the Autoconf distribution.
18645 * Changed Quotation:: Broken code which used to work
18646 * New Macros:: Interaction with foreign macros
18647 * Hosts and Cross-Compilation:: Bugward compatibility kludges
18648 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
18649 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
18652 @node Changed Quotation
18653 @subsection Changed Quotation
18655 The most important changes are invisible to you: the implementation of
18656 most macros have completely changed. This allowed more factorization of
18657 the code, better error messages, a higher uniformity of the user's
18658 interface etc. Unfortunately, as a side effect, some construct which
18659 used to (miraculously) work might break starting with Autoconf 2.50.
18660 The most common culprit is bad quotation.
18662 For instance, in the following example, the message is not properly
18667 AC_CHECK_HEADERS(foo.h, ,
18668 AC_MSG_ERROR(cannot find foo.h, bailing out))
18673 Autoconf 2.13 simply ignores it:
18676 $ @kbd{autoconf-2.13; ./configure --silent}
18677 creating cache ./config.cache
18678 configure: error: cannot find foo.h
18683 while Autoconf 2.50 produces a broken @file{configure}:
18686 $ @kbd{autoconf-2.50; ./configure --silent}
18687 configure: error: cannot find foo.h
18688 ./configure: exit: bad non-numeric arg `bailing'
18689 ./configure: exit: bad non-numeric arg `bailing'
18693 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
18697 AC_INIT([Example], [1.0], [bug-example@@example.org])
18698 AC_CHECK_HEADERS([foo.h], [],
18699 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
18703 Many many (and many more) Autoconf macros were lacking proper quotation,
18704 including no less than@dots{} @code{AC_DEFUN} itself!
18707 $ @kbd{cat configure.in}
18708 AC_DEFUN([AC_PROG_INSTALL],
18709 [# My own much better version
18714 $ @kbd{autoconf-2.13}
18715 autoconf: Undefined macros:
18716 ***BUG in Autoconf--please report*** AC_FD_MSG
18717 ***BUG in Autoconf--please report*** AC_EPI
18718 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
18719 configure.in:5:AC_PROG_INSTALL
18720 $ @kbd{autoconf-2.50}
18726 @subsection New Macros
18728 @cindex undefined macro
18729 @cindex @code{_m4_divert_diversion}
18731 While Autoconf was relatively dormant in the late 1990s, Automake
18732 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
18733 in 2001, Autoconf provided
18734 versions of these macros, integrated in the @code{AC_} namespace,
18735 instead of @code{AM_}. But in order to ease the upgrading via
18736 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
18738 Unfortunately older versions of Automake (e.g., Automake 1.4)
18739 did not quote the names of these macros.
18740 Therefore, when @command{m4} finds something like
18741 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
18742 @code{AM_TYPE_PTRDIFF_T} is
18743 expanded, replaced with its Autoconf definition.
18745 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
18746 complains, in its own words:
18749 $ @kbd{cat configure.ac}
18750 AC_INIT([Example], [1.0], [bug-example@@example.org])
18752 $ @kbd{aclocal-1.4}
18754 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
18755 aclocal.m4:17: the top level
18756 autom4te: m4 failed with exit status: 1
18760 Modern versions of Automake no longer define most of these
18761 macros, and properly quote the names of the remaining macros.
18762 If you must use an old Automake, do not depend upon macros from Automake
18763 as it is simply not its job
18764 to provide macros (but the one it requires itself):
18767 $ @kbd{cat configure.ac}
18768 AC_INIT([Example], [1.0], [bug-example@@example.org])
18770 $ @kbd{rm aclocal.m4}
18772 autoupdate: `configure.ac' is updated
18773 $ @kbd{cat configure.ac}
18774 AC_INIT([Example], [1.0], [bug-example@@example.org])
18775 AC_CHECK_TYPES([ptrdiff_t])
18776 $ @kbd{aclocal-1.4}
18782 @node Hosts and Cross-Compilation
18783 @subsection Hosts and Cross-Compilation
18784 @cindex Cross compilation
18786 Based on the experience of compiler writers, and after long public
18787 debates, many aspects of the cross-compilation chain have changed:
18791 the relationship between the build, host, and target architecture types,
18794 the command line interface for specifying them to @command{configure},
18797 the variables defined in @command{configure},
18800 the enabling of cross-compilation mode.
18805 The relationship between build, host, and target have been cleaned up:
18806 the chain of default is now simply: target defaults to host, host to
18807 build, and build to the result of @command{config.guess}. Nevertheless,
18808 in order to ease the transition from 2.13 to 2.50, the following
18809 transition scheme is implemented. @emph{Do not rely on it}, as it will
18810 be completely disabled in a couple of releases (we cannot keep it, as it
18811 proves to cause more problems than it cures).
18813 They all default to the result of running @command{config.guess}, unless
18814 you specify either @option{--build} or @option{--host}. In this case,
18815 the default becomes the system type you specified. If you specify both,
18816 and they're different, @command{configure} enters cross compilation
18817 mode, so it doesn't run any tests that require execution.
18819 Hint: if you mean to override the result of @command{config.guess},
18820 prefer @option{--build} over @option{--host}. In the future,
18821 @option{--host} will not override the name of the build system type.
18822 Whenever you specify @option{--host}, be sure to specify @option{--build}
18827 For backward compatibility, @command{configure} accepts a system
18828 type as an option by itself. Such an option overrides the
18829 defaults for build, host, and target system types. The following
18830 configure statement configures a cross toolchain that runs on
18831 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
18832 which is also the build platform.
18835 ./configure --host=alpha-netbsd sparc-gnu
18840 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
18841 and @code{target} had a different semantics before and after the
18842 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
18843 @option{--build} is strictly copied into @code{build_alias}, and is left
18844 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
18845 set to the canonicalized build type. To ease the transition, before,
18846 its contents is the same as that of @code{build_alias}. Do @emph{not}
18847 rely on this broken feature.
18849 For consistency with the backward compatibility scheme exposed above,
18850 when @option{--host} is specified but @option{--build} isn't, the build
18851 system is assumed to be the same as @option{--host}, and
18852 @samp{build_alias} is set to that value. Eventually, this
18853 historically incorrect behavior will go away.
18857 The former scheme to enable cross-compilation proved to cause more harm
18858 than good, in particular, it used to be triggered too easily, leaving
18859 regular end users puzzled in front of cryptic error messages.
18860 @command{configure} could even enter cross-compilation mode only
18861 because the compiler was not functional. This is mainly because
18862 @command{configure} used to try to detect cross-compilation, instead of
18863 waiting for an explicit flag from the user.
18865 Now, @command{configure} enters cross-compilation mode if and only if
18866 @option{--host} is passed.
18868 That's the short documentation. To ease the transition between 2.13 and
18869 its successors, a more complicated scheme is implemented. @emph{Do not
18870 rely on the following}, as it will be removed in the near future.
18872 If you specify @option{--host}, but not @option{--build}, when
18873 @command{configure} performs the first compiler test it tries to run
18874 an executable produced by the compiler. If the execution fails, it
18875 enters cross-compilation mode. This is fragile. Moreover, by the time
18876 the compiler test is performed, it may be too late to modify the
18877 build-system type: other tests may have already been performed.
18878 Therefore, whenever you specify @option{--host}, be sure to specify
18879 @option{--build} too.
18882 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
18886 enters cross-compilation mode. The former interface, which
18887 consisted in setting the compiler to a cross-compiler without informing
18888 @command{configure} is obsolete. For instance, @command{configure}
18889 fails if it can't run the code generated by the specified compiler if you
18890 configure as follows:
18893 ./configure CC=m68k-coff-gcc
18897 @node AC_LIBOBJ vs LIBOBJS
18898 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
18900 Up to Autoconf 2.13, the replacement of functions was triggered via the
18901 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
18902 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
18903 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
18905 This change is mandated by the unification of the @acronym{GNU} Build System
18906 components. In particular, the various fragile techniques used to parse
18907 a @file{configure.ac} are all replaced with the use of traces. As a
18908 consequence, any action must be traceable, which obsoletes critical
18909 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
18910 and it can even be handled gracefully (read, ``without your having to
18911 change something'').
18913 There were two typical uses of @code{LIBOBJS}: asking for a replacement
18914 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
18918 As for function replacement, the fix is immediate: use
18919 @code{AC_LIBOBJ}. For instance:
18922 LIBOBJS="$LIBOBJS fnmatch.o"
18923 LIBOBJS="$LIBOBJS malloc.$ac_objext"
18927 should be replaced with:
18930 AC_LIBOBJ([fnmatch])
18931 AC_LIBOBJ([malloc])
18937 When used with Automake 1.10 or newer, a suitable value for
18938 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
18939 can be referenced from any @file{Makefile.am}. Even without Automake,
18940 arranging for @code{LIBOBJDIR} to be set correctly enables
18941 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
18942 The @code{LIBOBJDIR} feature is experimental.
18945 @node AC_FOO_IFELSE vs AC_TRY_FOO
18946 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
18948 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
18949 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
18950 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
18951 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
18952 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
18953 @code{AC_TRY_RUN}. The motivations where:
18956 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
18957 quoting their arguments;
18960 the combinatoric explosion is solved by decomposing on the one hand the
18961 generation of sources, and on the other hand executing the program;
18964 this scheme helps supporting more languages than plain C and C++.
18967 In addition to the change of syntax, the philosophy has changed too:
18968 while emphasis was put on speed at the expense of accuracy, today's
18969 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
18973 As a perfect example of what is @emph{not} to be done, here is how to
18974 find out whether a header file contains a particular declaration, such
18975 as a typedef, a structure, a structure member, or a function. Use
18976 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
18977 header file; on some systems the symbol might be defined in another
18978 header file that the file you are checking includes.
18980 As a (bad) example, here is how you should not check for C preprocessor
18981 symbols, either defined by header files or predefined by the C
18982 preprocessor: using @code{AC_EGREP_CPP}:
18990 ], is_aix=yes, is_aix=no)
18994 The above example, properly written would (i) use
18995 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
18999 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
19001 error: This isn't AIX!
19010 @c ============================= Generating Test Suites with Autotest
19012 @node Using Autotest
19013 @chapter Generating Test Suites with Autotest
19018 @strong{N.B.: This section describes an experimental feature which will
19019 be part of Autoconf in a forthcoming release. Although we believe
19020 Autotest is stabilizing, this documentation describes an interface which
19021 might change in the future: do not depend upon Autotest without
19022 subscribing to the Autoconf mailing lists.}
19025 It is paradoxical that portable projects depend on nonportable tools
19026 to run their test suite. Autoconf by itself is the paragon of this
19027 problem: although it aims at perfectly portability, up to 2.13 its
19028 test suite was using Deja@acronym{GNU}, a rich and complex testing
19029 framework, but which is far from being standard on Posix systems.
19030 Worse yet, it was likely to be missing on the most fragile platforms,
19031 the very platforms that are most likely to torture Autoconf and
19032 exhibit deficiencies.
19034 To circumvent this problem, many package maintainers have developed their
19035 own testing framework, based on simple shell scripts whose sole outputs
19036 are exit status values describing whether the test succeeded. Most of
19037 these tests share common patterns, and this can result in lots of
19038 duplicated code and tedious maintenance.
19040 Following exactly the same reasoning that yielded to the inception of
19041 Autoconf, Autotest provides a test suite generation framework, based on
19042 M4 macros building a portable shell script. The suite itself is
19043 equipped with automatic logging and tracing facilities which greatly
19044 diminish the interaction with bug reporters, and simple timing reports.
19046 Autoconf itself has been using Autotest for years, and we do attest that
19047 it has considerably improved the strength of the test suite and the
19048 quality of bug reports. Other projects are known to use some generation
19049 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
19050 them with different needs, and this usage has validated Autotest as a general
19053 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
19054 interactive tool testing, which is probably its main limitation.
19057 * Using an Autotest Test Suite:: Autotest and the user
19058 * Writing Testsuites:: Autotest macros
19059 * testsuite Invocation:: Running @command{testsuite} scripts
19060 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
19063 @node Using an Autotest Test Suite
19064 @section Using an Autotest Test Suite
19067 * testsuite Scripts:: The concepts of Autotest
19068 * Autotest Logs:: Their contents
19071 @node testsuite Scripts
19072 @subsection @command{testsuite} Scripts
19074 @cindex @command{testsuite}
19076 Generating testing or validation suites using Autotest is rather easy.
19077 The whole validation suite is held in a file to be processed through
19078 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
19079 produce a stand-alone Bourne shell script which then gets distributed.
19080 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
19081 the installer's end.
19084 Each test of the validation suite should be part of some test group. A
19085 @dfn{test group} is a sequence of interwoven tests that ought to be
19086 executed together, usually because one test in the group creates data
19087 files than a later test in the same group needs to read. Complex test
19088 groups make later debugging more tedious. It is much better to
19089 keep only a few tests per test group. Ideally there is only one test
19092 For all but the simplest packages, some file such as @file{testsuite.at}
19093 does not fully hold all test sources, as these are often easier to
19094 maintain in separate files. Each of these separate files holds a single
19095 test group, or a sequence of test groups all addressing some common
19096 functionality in the package. In such cases, @file{testsuite.at}
19097 merely initializes the validation suite, and sometimes does elementary
19098 health checking, before listing include statements for all other test
19099 files. The special file @file{package.m4}, containing the
19100 identification of the package, is automatically included if found.
19102 A convenient alternative consists in moving all the global issues
19103 (local Autotest macros, elementary health checking, and @code{AT_INIT}
19104 invocation) into the file @code{local.at}, and making
19105 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
19106 suites. In such case, generating the whole test suite or pieces of it
19107 is only a matter of choosing the @command{autom4te} command line
19110 The validation scripts that Autotest produces are by convention called
19111 @command{testsuite}. When run, @command{testsuite} executes each test
19112 group in turn, producing only one summary line per test to say if that
19113 particular test succeeded or failed. At end of all tests, summarizing
19114 counters get printed. One debugging directory is left for each test
19115 group which failed, if any: such directories are named
19116 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
19117 the test group, and they include:
19120 @item a debugging script named @file{run} which reruns the test in
19121 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
19122 of debugging scripts has the purpose of easing the chase for bugs.
19124 @item all the files created with @code{AT_DATA}
19126 @item a log of the run, named @file{testsuite.log}
19129 In the ideal situation, none of the tests fail, and consequently no
19130 debugging directory is left behind for validation.
19132 It often happens in practice that individual tests in the validation
19133 suite need to get information coming out of the configuration process.
19134 Some of this information, common for all validation suites, is provided
19135 through the file @file{atconfig}, automatically created by
19136 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
19137 testing environment specifically needs, you might prepare an optional
19138 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
19139 The configuration process produces @file{atconfig} and @file{atlocal}
19140 out of these two input files, and these two produced files are
19141 automatically read by the @file{testsuite} script.
19143 Here is a diagram showing the relationship between files.
19146 Files used in preparing a software package for distribution:
19151 subfile-1.at ->. [local.at] ---->+
19153 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
19159 Files used in configuring a software package:
19164 [atlocal.in] --> config.status* --<
19170 Files created during the test suite execution:
19173 atconfig -->. .--> testsuite.log
19177 [atlocal] ->' `--> [testsuite.dir]
19181 @node Autotest Logs
19182 @subsection Autotest Logs
19184 When run, the test suite creates a log file named after itself, e.g., a
19185 test suite named @command{testsuite} creates @file{testsuite.log}. It
19186 contains a lot of information, usually more than maintainers actually
19187 need, but therefore most of the time it contains all that is needed:
19190 @item command line arguments
19191 @c akim s/to consist in/to consist of/
19192 A bad but unfortunately widespread habit consists of
19193 setting environment variables before the command, such as in
19194 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
19195 know this change, hence (i) it cannot report it to you, and (ii)
19196 it cannot preserve the value of @code{CC} for subsequent runs.
19197 Autoconf faced exactly the same problem, and solved it by asking
19198 users to pass the variable definitions as command line arguments.
19199 Autotest requires this rule, too, but has no means to enforce it; the log
19200 then contains a trace of the variables that were changed by the user.
19202 @item @file{ChangeLog} excerpts
19203 The topmost lines of all the @file{ChangeLog} files found in the source
19204 hierarchy. This is especially useful when bugs are reported against
19205 development versions of the package, since the version string does not
19206 provide sufficient information to know the exact state of the sources
19207 the user compiled. Of course, this relies on the use of a
19210 @item build machine
19211 Running a test suite in a cross-compile environment is not an easy task,
19212 since it would mean having the test suite run on a machine @var{build},
19213 while running programs on a machine @var{host}. It is much simpler to
19214 run both the test suite and the programs on @var{host}, but then, from
19215 the point of view of the test suite, there remains a single environment,
19216 @var{host} = @var{build}. The log contains relevant information on the
19217 state of the build machine, including some important environment
19219 @c FIXME: How about having an M4sh macro to say `hey, log the value
19220 @c of `@dots{}'? This would help both Autoconf and Autotest.
19222 @item tested programs
19223 The absolute file name and answers to @option{--version} of the tested
19224 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
19226 @item configuration log
19227 The contents of @file{config.log}, as created by @command{configure},
19228 are appended. It contains the configuration flags and a detailed report
19229 on the configuration itself.
19233 @node Writing Testsuites
19234 @section Writing @file{testsuite.at}
19236 The @file{testsuite.at} is a Bourne shell script making use of special
19237 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
19238 its beginning followed by one call to @code{m4_include} per source file
19239 for tests. Each such included file, or the remainder of
19240 @file{testsuite.at} if include files are not used, contain a sequence of
19241 test groups. Each test group begins with a call to @code{AT_SETUP},
19242 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
19243 and then completes with a call to @code{AT_CLEANUP}.
19245 @defmac AT_INIT (@ovar{name})
19247 @c FIXME: Not clear, plus duplication of the information.
19248 Initialize Autotest. Giving a @var{name} to the test suite is
19249 encouraged if your package includes several test suites. In any case,
19250 the test suite always displays the package name and version. It also
19251 inherits the package bug report address.
19254 @defmac AT_COPYRIGHT (@var{copyright-notice})
19255 @atindex{COPYRIGHT}
19256 @cindex Copyright Notice
19257 State that, in addition to the Free Software Foundation's copyright on
19258 the Autotest macros, parts of your test suite are covered by
19259 @var{copyright-notice}.
19261 The @var{copyright-notice} shows up in both the head of
19262 @command{testsuite} and in @samp{testsuite --version}.
19265 @defmac AT_TESTED (@var{executables})
19267 Log the file name and answer to @option{--version} of each program in
19268 space-separated list @var{executables}. Several invocations register
19269 new executables, in other words, don't fear registering one program
19273 Autotest test suites rely on @env{PATH} to find the tested program.
19274 This avoids the need to generate absolute names of the various tools, and
19275 makes it possible to test installed programs. Therefore, knowing which
19276 programs are being exercised is crucial to understanding problems in
19277 the test suite itself, or its occasional misuses. It is a good idea to
19278 also subscribe foreign programs you depend upon, to avoid incompatible
19283 @defmac AT_SETUP (@var{test-group-name})
19285 This macro starts a group of related tests, all to be executed in the
19286 same subshell. It accepts a single argument, which holds a few words
19287 (no more than about 30 or 40 characters) quickly describing the purpose
19288 of the test group being started.
19291 @defmac AT_KEYWORDS (@var{keywords})
19293 Associate the space-separated list of @var{keywords} to the enclosing
19294 test group. This makes it possible to run ``slices'' of the test suite.
19295 For instance, if some of your test groups exercise some @samp{foo}
19296 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
19297 @samp{./testsuite -k foo} to run exclusively these test groups. The
19298 @var{title} of the test group is automatically recorded to
19299 @code{AT_KEYWORDS}.
19301 Several invocations within a test group accumulate new keywords. In
19302 other words, don't fear registering the same keyword several times in a
19306 @defmac AT_CAPTURE_FILE (@var{file})
19307 @atindex{CAPTURE_FILE}
19308 If the current test group fails, log the contents of @var{file}.
19309 Several identical calls within one test group have no additional effect.
19312 @defmac AT_XFAIL_IF (@var{shell-condition})
19314 Determine whether the test is expected to fail because it is a known
19315 bug (for unsupported features, you should skip the test).
19316 @var{shell-condition} is a shell expression such as a @code{test}
19317 command; you can instantiate this macro many times from within the
19318 same test group, and one of the conditions is enough to turn
19319 the test into an expected failure.
19324 End the current test group.
19329 @defmac AT_DATA (@var{file}, @var{contents})
19331 Initialize an input data @var{file} with given @var{contents}. Of
19332 course, the @var{contents} have to be properly quoted between square
19333 brackets to protect against included commas or spurious M4
19334 expansion. The contents ought to end with an end of line.
19337 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @
19338 @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
19340 Execute a test by performing given shell @var{commands}. These commands
19341 should normally exit with @var{status}, while producing expected
19342 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
19343 status 77, then the whole test group is skipped. Otherwise, if this test
19344 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
19345 commands @var{run-if-pass}.
19347 @c Previously, we had this:
19348 @c The @var{commands} @emph{must not} redirect the standard output, nor the
19350 @c to prevent trigerring the double redirect bug on Ultrix, see
19351 @c `File Descriptors'. This was too restricting, and Ultrix is pretty
19352 @c much dead, so we dropped the limitation; the obvious workaround on
19353 @c Ultrix is to use a working shell there.
19355 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
19356 the corresponding value is not checked.
19358 The special value @samp{expout} for @var{stdout} means the expected
19359 output of the @var{commands} is the content of the file @file{expout}.
19360 If @var{stdout} is @samp{stdout}, then the standard output of the
19361 @var{commands} is available for further tests in the file @file{stdout}.
19362 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
19366 @node testsuite Invocation
19367 @section Running @command{testsuite} Scripts
19368 @cindex @command{testsuite}
19370 Autotest test suites support the following arguments:
19375 Display the list of options and exit successfully.
19379 Display the version of the test suite and exit successfully.
19383 Remove all the files the test suite might have created and exit. Meant
19384 for @code{clean} Make targets.
19388 List all the tests (or only the selection), including their possible
19394 By default all tests are performed (or described with
19395 @option{--list}) in the default environment first silently, then
19396 verbosely, but the environment, set of tests, and verbosity level can be
19400 @item @var{variable}=@var{value}
19401 Set the environment @var{variable} to @var{value}. Use this rather
19402 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
19403 different environment.
19405 @cindex @code{AUTOTEST_PATH}
19406 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
19407 to @env{PATH}. Relative directory names (not starting with
19408 @samp{/}) are considered to be relative to the top level of the
19409 package being built. All directories are made absolute, first
19410 starting from the top level @emph{build} tree, then from the
19411 @emph{source} tree. For instance @samp{./testsuite
19412 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
19413 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
19414 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
19418 @itemx @var{number}-@var{number}
19419 @itemx @var{number}-
19420 @itemx -@var{number}
19421 Add the corresponding test groups, with obvious semantics, to the
19424 @item --keywords=@var{keywords}
19425 @itemx -k @var{keywords}
19426 Add to the selection the test groups with title or keywords (arguments
19427 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
19428 of the comma separated list @var{keywords}, case-insensitively. Use
19429 @samp{!} immediately before the keyword to invert the selection for this
19430 keyword. By default, the keywords match whole words; enclose them in
19431 @samp{.*} to also match parts of words.
19433 For example, running
19436 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
19440 selects all tests tagged @samp{autoupdate} @emph{and} with tags
19441 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
19445 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
19449 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
19450 containing @samp{FUNC}.
19454 If any test fails, immediately abort testing. It implies
19455 @option{--debug}: post test group clean up, and top-level logging
19456 are inhibited. This option is meant for the full test
19457 suite, it is not really useful for generated debugging scripts.
19461 Force more verbosity in the detailed output of what is being done. This
19462 is the default for debugging scripts.
19466 Do not remove the files after a test group was performed ---but they are
19467 still removed @emph{before}, therefore using this option is sane when
19468 running several test groups. Create debugging scripts. Do not
19469 overwrite the top-level
19470 log (in order to preserve supposedly existing full log file). This is
19471 the default for debugging scripts, but it can also be useful to debug
19472 the testsuite itself.
19476 Trigger shell tracing of the test groups.
19480 @node Making testsuite Scripts
19481 @section Making @command{testsuite} Scripts
19483 For putting Autotest into movement, you need some configuration and
19484 makefile machinery. We recommend, at least if your package uses deep or
19485 shallow hierarchies, that you use @file{tests/} as the name of the
19486 directory holding all your tests and their makefile. Here is a
19487 check list of things to do.
19492 @cindex @file{package.m4}
19493 Make sure to create the file @file{package.m4}, which defines the
19494 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
19495 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
19496 address to which bug reports should be sent. For sake of completeness,
19497 we suggest that you also define @code{AT_PACKAGE_NAME},
19498 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
19499 @xref{Initializing configure}, for a description of these variables. We
19500 suggest the following makefile excerpt:
19503 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
19505 echo '# Signature of the current package.'; \
19506 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
19507 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
19508 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
19509 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
19510 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
19511 @} >'$(srcdir)/package.m4'
19515 Be sure to distribute @file{package.m4} and to put it into the source
19516 hierarchy: the test suite ought to be shipped!
19519 Invoke @code{AC_CONFIG_TESTDIR}.
19521 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
19522 @acindex{CONFIG_TESTDIR}
19523 An Autotest test suite is to be configured in @var{directory}. This
19524 macro requires the instantiation of @file{@var{directory}/atconfig} from
19525 @file{@var{directory}/atconfig.in}, and sets the default
19526 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
19530 Still within @file{configure.ac}, as appropriate, ensure that some
19531 @code{AC_CONFIG_FILES} command includes substitution for
19532 @file{tests/atlocal}.
19535 The @file{tests/Makefile.in} should be modified so the validation in
19536 your package is triggered by @samp{make check}. An example is provided
19540 With Automake, here is a minimal example about how to link @samp{make
19541 check} with a validation suite.
19544 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
19545 TESTSUITE = $(srcdir)/testsuite
19547 check-local: atconfig atlocal $(TESTSUITE)
19548 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
19550 installcheck-local: atconfig atlocal $(TESTSUITE)
19551 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
19555 test ! -f '$(TESTSUITE)' || \
19556 $(SHELL) '$(TESTSUITE)' --clean
19558 AUTOTEST = $(AUTOM4TE) --language=autotest
19559 $(TESTSUITE): $(srcdir)/testsuite.at
19560 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
19564 You might want to list explicitly the dependencies, i.e., the list of
19565 the files @file{testsuite.at} includes.
19567 With strict Autoconf, you might need to add lines inspired from the
19573 atconfig: $(top_builddir)/config.status
19574 cd $(top_builddir) && \
19575 $(SHELL) ./config.status $(subdir)/$@@
19577 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
19578 cd $(top_builddir) && \
19579 $(SHELL) ./config.status $(subdir)/$@@
19583 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
19586 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
19587 within your makefile, you can fine-tune test suite execution with this
19588 variable, for example:
19591 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
19596 @c =============================== Frequent Autoconf Questions, with answers
19599 @chapter Frequent Autoconf Questions, with answers
19601 Several questions about Autoconf come up occasionally. Here some of them
19605 * Distributing:: Distributing @command{configure} scripts
19606 * Why GNU M4:: Why not use the standard M4?
19607 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
19608 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
19609 * Defining Directories:: Passing @code{datadir} to program
19610 * Autom4te Cache:: What is it? Can I remove it?
19611 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
19615 @section Distributing @command{configure} Scripts
19619 What are the restrictions on distributing @command{configure}
19620 scripts that Autoconf generates? How does that affect my
19621 programs that use them?
19624 There are no restrictions on how the configuration scripts that Autoconf
19625 produces may be distributed or used. In Autoconf version 1, they were
19626 covered by the @acronym{GNU} General Public License. We still encourage
19627 software authors to distribute their work under terms like those of the
19628 @acronym{GPL}, but doing so is not required to use Autoconf.
19630 Of the other files that might be used with @command{configure},
19631 @file{config.h.in} is under whatever copyright you use for your
19632 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
19633 exception to the @acronym{GPL} when they are used with an Autoconf-generated
19634 @command{configure} script, which permits you to distribute them under the
19635 same terms as the rest of your package. @file{install-sh} is from the X
19636 Consortium and is not copyrighted.
19639 @section Why Require @acronym{GNU} M4?
19642 Why does Autoconf require @acronym{GNU} M4?
19645 Many M4 implementations have hard-coded limitations on the size and
19646 number of macros that Autoconf exceeds. They also lack several
19647 builtin macros that it would be difficult to get along without in a
19648 sophisticated application like Autoconf, including:
19658 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
19660 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
19661 M4 is simple to configure and install, it seems reasonable to require
19662 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
19663 other free software already have most of the @acronym{GNU} utilities
19664 installed, since they prefer them.
19666 @node Bootstrapping
19667 @section How Can I Bootstrap?
19671 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
19672 @command{configure} script, how do I bootstrap? It seems like a chicken
19676 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
19677 @command{configure} script produced by Autoconf, Autoconf is not required
19678 in order to run the script and install @acronym{GNU} M4. Autoconf is only
19679 required if you want to change the M4 @command{configure} script, which few
19680 people have to do (mainly its maintainer).
19682 @node Why Not Imake
19683 @section Why Not Imake?
19687 Why not use Imake instead of @command{configure} scripts?
19690 Several people have written addressing this question, so I include
19691 adaptations of their explanations here.
19693 The following answer is based on one written by Richard Pixley:
19696 Autoconf generated scripts frequently work on machines that it has
19697 never been set up to handle before. That is, it does a good job of
19698 inferring a configuration for a new system. Imake cannot do this.
19700 Imake uses a common database of host specific data. For X11, this makes
19701 sense because the distribution is made as a collection of tools, by one
19702 central authority who has control over the database.
19704 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
19705 maintainer; these maintainers are scattered across the world. Using a
19706 common database would be a maintenance nightmare. Autoconf may appear
19707 to be this kind of database, but in fact it is not. Instead of listing
19708 host dependencies, it lists program requirements.
19710 If you view the @acronym{GNU} suite as a collection of native tools, then the
19711 problems are similar. But the @acronym{GNU} development tools can be
19712 configured as cross tools in almost any host+target permutation. All of
19713 these configurations can be installed concurrently. They can even be
19714 configured to share host independent files across hosts. Imake doesn't
19715 address these issues.
19717 Imake templates are a form of standardization. The @acronym{GNU} coding
19718 standards address the same issues without necessarily imposing the same
19723 Here is some further explanation, written by Per Bothner:
19726 One of the advantages of Imake is that it easy to generate large
19727 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
19728 However, @code{cpp} is not programmable: it has limited conditional
19729 facilities, and no looping. And @code{cpp} cannot inspect its
19732 All of these problems are solved by using @code{sh} instead of
19733 @code{cpp}. The shell is fully programmable, has macro substitution,
19734 can execute (or source) other shell scripts, and can inspect its
19739 Paul Eggert elaborates more:
19742 With Autoconf, installers need not assume that Imake itself is already
19743 installed and working well. This may not seem like much of an advantage
19744 to people who are accustomed to Imake. But on many hosts Imake is not
19745 installed or the default installation is not working well, and requiring
19746 Imake to install a package hinders the acceptance of that package on
19747 those hosts. For example, the Imake template and configuration files
19748 might not be installed properly on a host, or the Imake build procedure
19749 might wrongly assume that all source files are in one big directory
19750 tree, or the Imake configuration might assume one compiler whereas the
19751 package or the installer needs to use another, or there might be a
19752 version mismatch between the Imake expected by the package and the Imake
19753 supported by the host. These problems are much rarer with Autoconf,
19754 where each package comes with its own independent configuration
19757 Also, Imake often suffers from unexpected interactions between
19758 @command{make} and the installer's C preprocessor. The fundamental problem
19759 here is that the C preprocessor was designed to preprocess C programs,
19760 not makefiles. This is much less of a problem with Autoconf,
19761 which uses the general-purpose preprocessor M4, and where the
19762 package's author (rather than the installer) does the preprocessing in a
19767 Finally, Mark Eichin notes:
19770 Imake isn't all that extensible, either. In order to add new features to
19771 Imake, you need to provide your own project template, and duplicate most
19772 of the features of the existing one. This means that for a sophisticated
19773 project, using the vendor-provided Imake templates fails to provide any
19774 leverage---since they don't cover anything that your own project needs
19775 (unless it is an X11 program).
19777 On the other side, though:
19779 The one advantage that Imake has over @command{configure}:
19780 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
19781 than @file{Makefile.in} files. There is a fix to this, however---at least
19782 for the Kerberos V5 tree, we've modified things to call in common
19783 @file{post.in} and @file{pre.in} makefile fragments for the
19784 entire tree. This means that a lot of common things don't have to be
19785 duplicated, even though they normally are in @command{configure} setups.
19789 @node Defining Directories
19790 @section How Do I @code{#define} Installation Directories?
19793 My program needs library files, installed in @code{datadir} and
19797 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
19798 [Define to the read-only architecture-independent
19806 #define DATADIR "$@{prefix@}/share"
19810 As already explained, this behavior is on purpose, mandated by the
19811 @acronym{GNU} Coding Standards, see @ref{Installation Directory
19812 Variables}. There are several means to achieve a similar goal:
19816 Do not use @code{AC_DEFINE} but use your makefile to pass the
19817 actual value of @code{datadir} via compilation flags.
19818 @xref{Installation Directory Variables}, for the details.
19821 This solution can be simplified when compiling a program: you may either
19822 extend the @code{CPPFLAGS}:
19825 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
19829 If you are using Automake, you should use @code{AM_CPPFLAGS} instead:
19832 AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
19836 Alternatively, create a dedicated header file:
19839 DISTCLEANFILES = myprog-paths.h
19840 myprog-paths.h: Makefile
19841 echo '#define DATADIR "$(datadir)"' >$@@
19845 Use @code{AC_DEFINE} but have @command{configure} compute the literal
19846 value of @code{datadir} and others. Many people have wrapped macros to
19847 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
19848 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
19851 This solution does not conform to the @acronym{GNU} Coding Standards.
19854 Note that all the previous solutions hard wire the absolute name of
19855 these directories in the executables, which is not a good property. You
19856 may try to compute the names relative to @code{prefix}, and try to
19857 find @code{prefix} at runtime, this way your package is relocatable.
19861 @node Autom4te Cache
19862 @section What is @file{autom4te.cache}?
19865 What is this directory @file{autom4te.cache}? Can I safely remove it?
19868 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
19869 role and is read by many tools: @command{autoconf} to create
19870 @file{configure}, @command{autoheader} to create @file{config.h.in},
19871 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
19872 check the completeness of @file{configure.ac}, @command{autoreconf} to
19873 check the @acronym{GNU} Build System components that are used. To
19874 ``read @file{configure.ac}'' actually means to compile it with M4,
19875 which can be a long process for complex @file{configure.ac}.
19877 This is why all these tools, instead of running directly M4, invoke
19878 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
19879 a specific demand, stores additional information in
19880 @file{autom4te.cache} for future runs. For instance, if you run
19881 @command{autoconf}, behind the scenes, @command{autom4te} also
19882 stores information for the other tools, so that when you invoke
19883 @command{autoheader} or @command{automake} etc., reprocessing
19884 @file{configure.ac} is not needed. The speed up is frequently of 30%,
19885 and is increasing with the size of @file{configure.ac}.
19887 But it is and remains being simply a cache: you can safely remove it.
19892 Can I permanently get rid of it?
19895 The creation of this cache can be disabled from
19896 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
19897 details. You should be aware that disabling the cache slows down the
19898 Autoconf test suite by 40%. The more @acronym{GNU} Build System
19899 components are used, the more the cache is useful; for instance
19900 running @samp{autoreconf -f} on the Core Utilities is twice slower without
19901 the cache @emph{although @option{--force} implies that the cache is
19902 not fully exploited}, and eight times slower than without
19906 @node Present But Cannot Be Compiled
19907 @section Header Present But Cannot Be Compiled
19909 The most important guideline to bear in mind when checking for
19910 features is to mimic as much as possible the intended use.
19911 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
19912 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
19913 the preprocessor, instead of the compiler, to check for headers. As a
19914 result, incompatibilities between headers went unnoticed during
19915 configuration, and maintainers finally had to deal with this issue
19918 As of Autoconf 2.56 both checks are performed, and @code{configure}
19919 complains loudly if the compiler and the preprocessor do not agree.
19920 For the time being the result used is that of the preprocessor, to give
19921 maintainers time to adjust their @file{configure.ac}, but in the
19922 future, only the compiler will be considered.
19924 Consider the following example:
19927 $ @kbd{cat number.h}
19928 typedef int number;
19930 const number pi = 3;
19931 $ @kbd{cat configure.ac}
19932 AC_INIT([Example], [1.0], [bug-example@@example.org])
19933 AC_CHECK_HEADERS([pi.h])
19934 $ @kbd{autoconf -Wall}
19935 $ @kbd{./configure}
19936 checking for gcc... gcc
19937 checking for C compiler default output file name... a.out
19938 checking whether the C compiler works... yes
19939 checking whether we are cross compiling... no
19940 checking for suffix of executables...
19941 checking for suffix of object files... o
19942 checking whether we are using the GNU C compiler... yes
19943 checking whether gcc accepts -g... yes
19944 checking for gcc option to accept ISO C89... none needed
19945 checking how to run the C preprocessor... gcc -E
19946 checking for grep that handles long lines and -e... grep
19947 checking for egrep... grep -E
19948 checking for ANSI C header files... yes
19949 checking for sys/types.h... yes
19950 checking for sys/stat.h... yes
19951 checking for stdlib.h... yes
19952 checking for string.h... yes
19953 checking for memory.h... yes
19954 checking for strings.h... yes
19955 checking for inttypes.h... yes
19956 checking for stdint.h... yes
19957 checking for unistd.h... yes
19958 checking pi.h usability... no
19959 checking pi.h presence... yes
19960 configure: WARNING: pi.h: present but cannot be compiled
19961 configure: WARNING: pi.h: check for missing prerequisite headers?
19962 configure: WARNING: pi.h: see the Autoconf documentation
19963 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
19964 configure: WARNING: pi.h: proceeding with the preprocessor's result
19965 configure: WARNING: pi.h: in the future, the compiler will take precedence
19966 configure: WARNING: ## -------------------------------------- ##
19967 configure: WARNING: ## Report this to bug-example@@example.org ##
19968 configure: WARNING: ## -------------------------------------- ##
19969 checking for pi.h... yes
19973 The proper way the handle this case is using the fourth argument
19974 (@pxref{Generic Headers}):
19977 $ @kbd{cat configure.ac}
19978 AC_INIT([Example], [1.0], [bug-example@@example.org])
19979 AC_CHECK_HEADERS([number.h pi.h], [], [],
19980 [[#ifdef HAVE_NUMBER_H
19981 # include <number.h>
19984 $ @kbd{autoconf -Wall}
19985 $ @kbd{./configure}
19986 checking for gcc... gcc
19987 checking for C compiler default output... a.out
19988 checking whether the C compiler works... yes
19989 checking whether we are cross compiling... no
19990 checking for suffix of executables...
19991 checking for suffix of object files... o
19992 checking whether we are using the GNU C compiler... yes
19993 checking whether gcc accepts -g... yes
19994 checking for gcc option to accept ANSI C... none needed
19995 checking for number.h... yes
19996 checking for pi.h... yes
19999 See @ref{Particular Headers}, for a list of headers with their
20002 @c ===================================================== History of Autoconf.
20005 @chapter History of Autoconf
20006 @cindex History of autoconf
20008 You may be wondering, Why was Autoconf originally written? How did it
20009 get into its present form? (Why does it look like gorilla spit?) If
20010 you're not wondering, then this chapter contains no information useful
20011 to you, and you might as well skip it. If you @emph{are} wondering,
20012 then let there be light@enddots{}
20015 * Genesis:: Prehistory and naming of @command{configure}
20016 * Exodus:: The plagues of M4 and Perl
20017 * Leviticus:: The priestly code of portability arrives
20018 * Numbers:: Growth and contributors
20019 * Deuteronomy:: Approaching the promises of easy configuration
20025 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
20026 Free Software Foundation. As they were ported to more platforms and
20027 more programs were added, the number of @option{-D} options that users
20028 had to select in the makefile (around 20) became burdensome.
20029 Especially for me---I had to test each new release on a bunch of
20030 different systems. So I wrote a little shell script to guess some of
20031 the correct settings for the fileutils package, and released it as part
20032 of fileutils 2.0. That @command{configure} script worked well enough that
20033 the next month I adapted it (by hand) to create similar @command{configure}
20034 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
20035 also adapted one of my scripts for his @acronym{CVS} revision control system.
20037 Later that summer, I learned that Richard Stallman and Richard Pixley
20038 were developing similar scripts to use in the @acronym{GNU} compiler tools;
20039 so I adapted my @command{configure} scripts to support their evolving
20040 interface: using the file name @file{Makefile.in} as the templates;
20041 adding @samp{+srcdir}, the first option (of many); and creating
20042 @file{config.status} files.
20047 As I got feedback from users, I incorporated many improvements, using
20048 Emacs to search and replace, cut and paste, similar changes in each of
20049 the scripts. As I adapted more @acronym{GNU} utilities packages to use
20050 @command{configure} scripts, updating them all by hand became impractical.
20051 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
20052 mail saying that the @command{configure} scripts were great, and asking if
20053 I had a tool for generating them that I could send him. No, I thought,
20054 but I should! So I started to work out how to generate them. And the
20055 journey from the slavery of hand-written @command{configure} scripts to the
20056 abundance and ease of Autoconf began.
20058 Cygnus @command{configure}, which was being developed at around that time,
20059 is table driven; it is meant to deal mainly with a discrete number of
20060 system types with a small number of mainly unguessable features (such as
20061 details of the object file format). The automatic configuration system
20062 that Brian Fox had developed for Bash takes a similar approach. For
20063 general use, it seems to me a hopeless cause to try to maintain an
20064 up-to-date database of which features each variant of each operating
20065 system has. It's easier and more reliable to check for most features on
20066 the fly---especially on hybrid systems that people have hacked on
20067 locally or that have patches from vendors installed.
20069 I considered using an architecture similar to that of Cygnus
20070 @command{configure}, where there is a single @command{configure} script that
20071 reads pieces of @file{configure.in} when run. But I didn't want to have
20072 to distribute all of the feature tests with every package, so I settled
20073 on having a different @command{configure} made from each
20074 @file{configure.in} by a preprocessor. That approach also offered more
20075 control and flexibility.
20077 I looked briefly into using the Metaconfig package, by Larry Wall,
20078 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
20079 reasons. The @command{Configure} scripts it produces are interactive,
20080 which I find quite inconvenient; I didn't like the ways it checked for
20081 some features (such as library functions); I didn't know that it was
20082 still being maintained, and the @command{Configure} scripts I had
20083 seen didn't work on many modern systems (such as System V R4 and NeXT);
20084 it wasn't flexible in what it could do in response to a feature's
20085 presence or absence; I found it confusing to learn; and it was too big
20086 and complex for my needs (I didn't realize then how much Autoconf would
20087 eventually have to grow).
20089 I considered using Perl to generate my style of @command{configure}
20090 scripts, but decided that M4 was better suited to the job of simple
20091 textual substitutions: it gets in the way less, because output is
20092 implicit. Plus, everyone already has it. (Initially I didn't rely on
20093 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
20094 University of Maryland had recently been putting M4 front ends on
20095 several programs, including @code{tvtwm}, and I was interested in trying
20096 out a new language.
20101 Since my @command{configure} scripts determine the system's capabilities
20102 automatically, with no interactive user intervention, I decided to call
20103 the program that generates them Autoconfig. But with a version number
20104 tacked on, that name would be too long for old Unix file systems,
20105 so I shortened it to Autoconf.
20107 In the fall of 1991 I called together a group of fellow questers after
20108 the Holy Grail of portability (er, that is, alpha testers) to give me
20109 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
20110 and continued to add features and improve the techniques used in the
20111 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
20112 with the idea of making an Autoconf shell script to run M4
20113 and check for unresolved macro calls; Richard Pixley, who suggested
20114 running the compiler instead of searching the file system to find
20115 include files and symbols, for more accurate results; Karl Berry, who
20116 got Autoconf to configure @TeX{} and added the macro index to the
20117 documentation; and Ian Lance Taylor, who added support for creating a C
20118 header file as an alternative to putting @option{-D} options in a
20119 makefile, so he could use Autoconf for his @acronym{UUCP} package.
20120 The alpha testers cheerfully adjusted their files again and again as the
20121 names and calling conventions of the Autoconf macros changed from
20122 release to release. They all contributed many specific checks, great
20123 ideas, and bug fixes.
20128 In July 1992, after months of alpha testing, I released Autoconf 1.0,
20129 and converted many @acronym{GNU} packages to use it. I was surprised by how
20130 positive the reaction to it was. More people started using it than I
20131 could keep track of, including people working on software that wasn't
20132 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
20133 Autoconf continued to improve rapidly, as many people using the
20134 @command{configure} scripts reported problems they encountered.
20136 Autoconf turned out to be a good torture test for M4 implementations.
20137 Unix M4 started to dump core because of the length of the
20138 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
20139 M4 as well. Eventually, we realized that we needed to use some
20140 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
20141 particular, has an impoverished set of builtin macros; the System V
20142 version is better, but still doesn't provide everything we need.
20144 More development occurred as people put Autoconf under more stresses
20145 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
20146 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
20147 invalid arguments. Jim Blandy bravely coerced it into configuring
20148 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
20149 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
20150 @command{autoheader} script to automate the creation of C header file
20151 templates, and added a @option{--verbose} option to @command{configure}.
20152 Noah Friedman added the @option{--autoconf-dir} option and
20153 @code{AC_MACRODIR} environment variable. (He also coined the term
20154 @dfn{autoconfiscate} to mean ``adapt a software package to use
20155 Autoconf''.) Roland and Noah improved the quoting protection in
20156 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
20157 dealing with portability problems from February through June, 1993.
20160 @section Deuteronomy
20162 A long wish list for major features had accumulated, and the effect of
20163 several years of patching by various people had left some residual
20164 cruft. In April 1994, while working for Cygnus Support, I began a major
20165 revision of Autoconf. I added most of the features of the Cygnus
20166 @command{configure} that Autoconf had lacked, largely by adapting the
20167 relevant parts of Cygnus @command{configure} with the help of david zuhn
20168 and Ken Raeburn. These features include support for using
20169 @file{config.sub}, @file{config.guess}, @option{--host}, and
20170 @option{--target}; making links to files; and running @command{configure}
20171 scripts in subdirectories. Adding these features enabled Ken to convert
20172 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
20175 I added more features in response to other peoples' requests. Many
20176 people had asked for @command{configure} scripts to share the results of
20177 the checks between runs, because (particularly when configuring a large
20178 source tree, like Cygnus does) they were frustratingly slow. Mike
20179 Haertel suggested adding site-specific initialization scripts. People
20180 distributing software that had to unpack on MS-DOS asked for a way to
20181 override the @file{.in} extension on the file names, which produced file
20182 names like @file{config.h.in} containing two dots. Jim Avera did an
20183 extensive examination of the problems with quoting in @code{AC_DEFINE}
20184 and @code{AC_SUBST}; his insights led to significant improvements.
20185 Richard Stallman asked that compiler output be sent to @file{config.log}
20186 instead of @file{/dev/null}, to help people debug the Emacs
20187 @command{configure} script.
20189 I made some other changes because of my dissatisfaction with the quality
20190 of the program. I made the messages showing results of the checks less
20191 ambiguous, always printing a result. I regularized the names of the
20192 macros and cleaned up coding style inconsistencies. I added some
20193 auxiliary utilities that I had developed to help convert source code
20194 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
20195 the macros not interrupt each others' messages. (That feature revealed
20196 some performance bottlenecks in @acronym{GNU} M4, which he hastily
20197 corrected!) I reorganized the documentation around problems people want
20198 to solve. And I began a test suite, because experience had shown that
20199 Autoconf has a pronounced tendency to regress when we change it.
20201 Again, several alpha testers gave invaluable feedback, especially
20202 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
20205 Finally, version 2.0 was ready. And there was much rejoicing. (And I
20206 have free time again. I think. Yeah, right.)
20209 @c ========================================================== Appendices
20212 @node GNU Free Documentation License
20213 @appendix GNU Free Documentation License
20221 * Environment Variable Index:: Index of environment variables used
20222 * Output Variable Index:: Index of variables set in output files
20223 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
20224 * Autoconf Macro Index:: Index of Autoconf macros
20225 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
20226 * Autotest Macro Index:: Index of Autotest macros
20227 * Program & Function Index:: Index of those with portability problems
20228 * Concept Index:: General index
20231 @node Environment Variable Index
20232 @appendixsec Environment Variable Index
20234 This is an alphabetical list of the environment variables that Autoconf
20239 @node Output Variable Index
20240 @appendixsec Output Variable Index
20242 This is an alphabetical list of the variables that Autoconf can
20243 substitute into files that it creates, typically one or more
20244 makefiles. @xref{Setting Output Variables}, for more information
20245 on how this is done.
20249 @node Preprocessor Symbol Index
20250 @appendixsec Preprocessor Symbol Index
20252 This is an alphabetical list of the C preprocessor symbols that the
20253 Autoconf macros define. To work with Autoconf, C source code needs to
20254 use these names in @code{#if} or @code{#ifdef} directives.
20258 @node Autoconf Macro Index
20259 @appendixsec Autoconf Macro Index
20261 This is an alphabetical list of the Autoconf macros.
20262 @ifset shortindexflag
20263 To make the list easier to use, the macros are listed without their
20264 preceding @samp{AC_}.
20269 @node M4 Macro Index
20270 @appendixsec M4 Macro Index
20272 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
20273 @ifset shortindexflag
20274 To make the list easier to use, the macros are listed without their
20275 preceding @samp{m4_} or @samp{AS_}.
20280 @node Autotest Macro Index
20281 @appendixsec Autotest Macro Index
20283 This is an alphabetical list of the Autotest macros.
20284 @ifset shortindexflag
20285 To make the list easier to use, the macros are listed without their
20286 preceding @samp{AT_}.
20291 @node Program & Function Index
20292 @appendixsec Program and Function Index
20294 This is an alphabetical list of the programs and functions whose
20295 portability is discussed in this document.
20299 @node Concept Index
20300 @appendixsec Concept Index
20302 This is an alphabetical list of the files, tools, and concepts
20303 introduced in this document.
20309 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
20310 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
20311 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
20312 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
20313 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
20314 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
20315 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
20316 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
20317 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
20318 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
20319 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
20320 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
20321 @c LocalWords: distclean uninstall noindent versioning Tromey dir
20322 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
20323 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
20324 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
20325 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
20326 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
20327 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
20328 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
20329 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
20330 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
20331 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
20332 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
20333 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
20334 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
20335 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
20336 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
20337 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
20338 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
20339 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
20340 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
20341 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
20342 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
20343 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
20344 @c LocalWords: SETGID getloadavg nlist GETMNTENT irix
20345 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
20346 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
20347 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
20348 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
20349 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
20350 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
20351 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
20352 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
20353 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
20354 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
20355 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
20356 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
20357 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
20358 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
20359 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
20360 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
20361 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
20362 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
20363 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
20364 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
20365 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
20366 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
20367 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
20368 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
20369 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
20370 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
20371 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
20372 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
20373 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
20374 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
20375 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
20376 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
20377 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
20378 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
20379 @c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
20380 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
20381 @c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
20382 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
20383 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
20384 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
20385 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
20386 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
20387 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
20388 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
20389 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
20390 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
20391 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
20392 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
20393 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
20394 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
20395 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
20396 @c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
20397 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
20398 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
20399 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
20400 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
20402 @c Local Variables:
20404 @c ispell-local-dictionary: "american"
20405 @c indent-tabs-mode: nil
20406 @c whitespace-check-buffer-indent: nil