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 * Copying This Manual:: How to make copies of 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 * Notices:: Copyright, version numbers in @command{configure}
306 * Input:: Where Autoconf should find files
307 * Output:: Outputting results from the configuration
308 * Configuration Actions:: Preparing the output based on results
309 * Configuration Files:: Creating output files
310 * Makefile Substitutions:: Using output variables in makefiles
311 * Configuration Headers:: Creating a configuration header file
312 * Configuration Commands:: Running arbitrary instantiation commands
313 * Configuration Links:: Links depending on the configuration
314 * Subdirectories:: Configuring independent packages together
315 * Default Prefix:: Changing the default installation prefix
317 Substitutions in Makefiles
319 * Preset Output Variables:: Output variables that are always set
320 * Installation Directory Variables:: Other preset output variables
321 * Changed Directory Variables:: Warnings about @file{datarootdir}
322 * Build Directories:: Supporting multiple concurrent compiles
323 * Automatic Remaking:: Makefile rules for configuring
325 Configuration Header Files
327 * Header Templates:: Input for the configuration headers
328 * autoheader Invocation:: How to create configuration templates
329 * Autoheader Macros:: How to specify CPP templates
333 * Common Behavior:: Macros' standard schemes
334 * Alternative Programs:: Selecting between alternative programs
335 * Files:: Checking for the existence of files
336 * Libraries:: Library archives that might be missing
337 * Library Functions:: C library functions that might be missing
338 * Header Files:: Header files that might be missing
339 * Declarations:: Declarations that may be missing
340 * Structures:: Structures or members that might be missing
341 * Types:: Types that might be missing
342 * Compilers and Preprocessors:: Checking for compiling programs
343 * System Services:: Operating system services
344 * Posix Variants:: Special kludges for specific Posix variants
345 * Erlang Libraries:: Checking for the existence of Erlang libraries
349 * Standard Symbols:: Symbols defined by the macros
350 * Default Includes:: Includes used by the generic macros
354 * Particular Programs:: Special handling to find certain programs
355 * Generic Programs:: How to find other programs
359 * Function Portability:: Pitfalls with usual functions
360 * Particular Functions:: Special handling to find certain functions
361 * Generic Functions:: How to find other functions
365 * Header Portability:: Collected knowledge on common headers
366 * Particular Headers:: Special handling to find certain headers
367 * Generic Headers:: How to find other headers
371 * Particular Declarations:: Macros to check for certain declarations
372 * Generic Declarations:: How to find other declarations
376 * Particular Structures:: Macros to check for certain structure members
377 * Generic Structures:: How to find other structure members
381 * Particular Types:: Special handling to find certain types
382 * Generic Types:: How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics:: Some portability issues
387 * Generic Compiler Characteristics:: Language independent tests and features
388 * C Compiler:: Checking its characteristics
389 * C++ Compiler:: Likewise
390 * Objective C Compiler:: Likewise
391 * Erlang Compiler and Interpreter:: Likewise
392 * Fortran Compiler:: Likewise
396 * Language Choice:: Selecting which language to use for testing
397 * Writing Test Programs:: Forging source files for compilers
398 * Running the Preprocessor:: Detecting preprocessor symbols
399 * Running the Compiler:: Detecting language or header features
400 * Running the Linker:: Detecting library features
401 * Runtime:: Testing for runtime features
402 * Systemology:: A zoology of operating systems
403 * Multiple Cases:: Tests for several possible values
405 Writing Test Programs
407 * Guidelines:: General rules for writing test programs
408 * Test Functions:: Avoiding pitfalls in test programs
409 * Generating Sources:: Source program boilerplate
413 * Defining Symbols:: Defining C preprocessor symbols
414 * Setting Output Variables:: Replacing variables in output files
415 * Special Chars in Variables:: Characters to beware of in variables
416 * Caching Results:: Speeding up subsequent @command{configure} runs
417 * Printing Messages:: Notifying @command{configure} users
421 * Cache Variable Names:: Shell variables used in caches
422 * Cache Files:: Files @command{configure} uses for caching
423 * Cache Checkpointing:: Loading and saving the cache file
427 * M4 Quotation:: Protecting macros from unwanted expansion
428 * Using autom4te:: The Autoconf executables backbone
429 * Programming in M4sugar:: Convenient pure M4 macros
430 * Programming in M4sh:: Common shell Constructs
431 * File Descriptor Macros:: File descriptor macros for input and output
435 * Active Characters:: Characters that change the behavior of M4
436 * One Macro Call:: Quotation and one macro call
437 * Quotation and Nested Macros:: Macros calling macros
438 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
439 * Quadrigraphs:: Another way to escape special characters
440 * Quotation Rule Of Thumb:: One parenthesis, one quote
442 Using @command{autom4te}
444 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
445 * Customizing autom4te:: Customizing the Autoconf package
447 Programming in M4sugar
449 * Redefined M4 Macros:: M4 builtins changed in M4sugar
450 * Looping constructs:: Iteration in M4
451 * Evaluation Macros:: More quotation and evaluation control
452 * Text processing Macros:: String manipulation in M4
453 * Forbidden Patterns:: Catching unexpanded macros
455 Writing Autoconf Macros
457 * Macro Definitions:: Basic format of an Autoconf macro
458 * Macro Names:: What to call your new macros
459 * Reporting Messages:: Notifying @command{autoconf} users
460 * Dependencies Between Macros:: What to do when macros depend on other macros
461 * Obsoleting Macros:: Warning about old ways of doing things
462 * Coding Style:: Writing Autoconf macros @`a la Autoconf
464 Dependencies Between Macros
466 * Prerequisite Macros:: Ensuring required information
467 * Suggested Ordering:: Warning about possible ordering problems
468 * One-Shot Macros:: Ensuring a macro is called only once
470 Portable Shell Programming
472 * Shellology:: A zoology of shells
473 * Here-Documents:: Quirks and tricks
474 * File Descriptors:: FDs and redirections
475 * File System Conventions:: File names
476 * Shell Substitutions:: Variable and command expansions
477 * Assignments:: Varying side effects of assignments
478 * Parentheses:: Parentheses in shell scripts
479 * Slashes:: Slashes in shell scripts
480 * Special Shell Variables:: Variables you should not change
481 * Limitations of Builtins:: Portable use of not so portable /bin/sh
482 * Limitations of Usual Tools:: Portable use of portable tools
484 Portable Make Programming
486 * $< in Ordinary Make Rules:: $< in ordinary rules
487 * Failure in Make Rules:: Failing portably in rules
488 * Special Chars in Names:: Special Characters in Macro Names
489 * Backslash-Newline-Newline:: Empty last lines in macro definitions
490 * Backslash-Newline Comments:: Spanning comments across line boundaries
491 * Long Lines in Makefiles:: Line length limitations
492 * Macros and Submakes:: @code{make macro=value} and submakes
493 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
494 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
495 * Comments in Make Rules:: Other problems with Make comments
496 * obj/ and Make:: Don't name a subdirectory @file{obj}
497 * make -k Status:: Exit status of @samp{make -k}
498 * VPATH and Make:: @code{VPATH} woes
499 * Single Suffix Rules:: Single suffix rules and separated dependencies
500 * Timestamps and Make:: Subsecond timestamp resolution
502 @code{VPATH} and Make
504 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
505 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
506 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
507 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
508 * Make Target Lookup:: More details about @code{VPATH} lookup
510 Portable C and C++ Programming
512 * Varieties of Unportability:: How to make your programs unportable
513 * Integer Overflow:: When integers get too large
514 * Null Pointers:: Properties of null pointers
515 * Buffer Overruns:: Subscript errors and the like
516 * Volatile Objects:: @code{volatile} and signals
517 * Floating Point Portability:: Portable floating-point arithmetic
518 * Exiting Portably:: Exiting and the exit status
522 * Specifying Names:: Specifying the system type
523 * Canonicalizing:: Getting the canonical system type
524 * Using System Type:: What to do with the system type
528 * Help Formatting:: Customizing @samp{configure --help}
529 * External Software:: Working with other optional software
530 * Package Options:: Selecting optional features
531 * Pretty Help Strings:: Formatting help string
532 * Option Checking:: Controlling checking of @command{configure} options
533 * Site Details:: Configuring site details
534 * Transforming Names:: Changing program names when installing
535 * Site Defaults:: Giving @command{configure} local defaults
537 Transforming Program Names When Installing
539 * Transformation Options:: @command{configure} options to transform names
540 * Transformation Examples:: Sample uses of transforming names
541 * Transformation Rules:: Makefile uses of transforming names
543 Running @command{configure} Scripts
545 * Basic Installation:: Instructions for typical cases
546 * Compilers and Options:: Selecting compilers and optimization
547 * Multiple Architectures:: Compiling for multiple architectures at once
548 * Installation Names:: Installing in different directories
549 * Optional Features:: Selecting optional features
550 * System Type:: Specifying the system type
551 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
552 * Defining Variables:: Specifying the compiler etc.
553 * configure Invocation:: Changing how @command{configure} runs
557 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
558 * acconfig Header:: Additional entries in @file{config.h.in}
559 * autoupdate Invocation:: Automatic update of @file{configure.ac}
560 * Obsolete Macros:: Backward compatibility macros
561 * Autoconf 1:: Tips for upgrading your files
562 * Autoconf 2.13:: Some fresher tips
564 Upgrading From Version 1
566 * Changed File Names:: Files you might rename
567 * Changed Makefiles:: New things to put in @file{Makefile.in}
568 * Changed Macros:: Macro calls you might replace
569 * Changed Results:: Changes in how to check test results
570 * Changed Macro Writing:: Better ways to write your own macros
572 Upgrading From Version 2.13
574 * Changed Quotation:: Broken code which used to work
575 * New Macros:: Interaction with foreign macros
576 * Hosts and Cross-Compilation:: Bugward compatibility kludges
577 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
578 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
580 Generating Test Suites with Autotest
582 * Using an Autotest Test Suite:: Autotest and the user
583 * Writing Testsuites:: Autotest macros
584 * testsuite Invocation:: Running @command{testsuite} scripts
585 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
587 Using an Autotest Test Suite
589 * testsuite Scripts:: The concepts of Autotest
590 * Autotest Logs:: Their contents
592 Frequent Autoconf Questions, with answers
594 * Distributing:: Distributing @command{configure} scripts
595 * Why GNU M4:: Why not use the standard M4?
596 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
597 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
598 * Defining Directories:: Passing @code{datadir} to program
599 * Autom4te Cache:: What is it? Can I remove it?
600 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
604 * Genesis:: Prehistory and naming of @command{configure}
605 * Exodus:: The plagues of M4 and Perl
606 * Leviticus:: The priestly code of portability arrives
607 * Numbers:: Growth and contributors
608 * Deuteronomy:: Approaching the promises of easy configuration
612 * GNU Free Documentation License:: License for copying this manual
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}.
1668 @c ========================================= Initialization and Output Files.
1671 @chapter Initialization and Output Files
1673 Autoconf-generated @command{configure} scripts need some information about
1674 how to initialize, such as how to find the package's source files and
1675 about the output files to produce. The following sections describe the
1676 initialization and the creation of output files.
1679 * Initializing configure:: Option processing etc.
1680 * Notices:: Copyright, version numbers in @command{configure}
1681 * Input:: Where Autoconf should find files
1682 * Output:: Outputting results from the configuration
1683 * Configuration Actions:: Preparing the output based on results
1684 * Configuration Files:: Creating output files
1685 * Makefile Substitutions:: Using output variables in makefiles
1686 * Configuration Headers:: Creating a configuration header file
1687 * Configuration Commands:: Running arbitrary instantiation commands
1688 * Configuration Links:: Links depending on the configuration
1689 * Subdirectories:: Configuring independent packages together
1690 * Default Prefix:: Changing the default installation prefix
1693 @node Initializing configure
1694 @section Initializing @command{configure}
1696 Every @command{configure} script must call @code{AC_INIT} before doing
1697 anything else. The only other required macro is @code{AC_OUTPUT}
1700 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1702 Process any command-line arguments and perform various initializations
1705 Set the name of the @var{package} and its @var{version}. These are
1706 typically used in @option{--version} support, including that of
1707 @command{configure}. The optional argument @var{bug-report} should be
1708 the email to which users should send bug reports. The package
1709 @var{tarname} differs from @var{package}: the latter designates the full
1710 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1711 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1712 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1713 other than alphanumerics and underscores are changed to @samp{-}.
1715 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1716 there should not be any shell computation, but they can be computed by
1719 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1720 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1721 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1724 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1725 @acindex{PACKAGE_NAME}
1726 @ovindex PACKAGE_NAME
1727 @cvindex PACKAGE_NAME
1728 Exactly @var{package}.
1730 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1731 @acindex{PACKAGE_TARNAME}
1732 @ovindex PACKAGE_TARNAME
1733 @cvindex PACKAGE_TARNAME
1734 Exactly @var{tarname}.
1736 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1737 @acindex{PACKAGE_VERSION}
1738 @ovindex PACKAGE_VERSION
1739 @cvindex PACKAGE_VERSION
1740 Exactly @var{version}.
1742 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1743 @acindex{PACKAGE_STRING}
1744 @ovindex PACKAGE_STRING
1745 @cvindex PACKAGE_STRING
1746 Exactly @samp{@var{package} @var{version}}.
1748 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1749 @acindex{PACKAGE_BUGREPORT}
1750 @ovindex PACKAGE_BUGREPORT
1751 @cvindex PACKAGE_BUGREPORT
1752 Exactly @var{bug-report}.
1756 If your @command{configure} script does its own option processing, it
1757 should inspect @samp{$@@} or @samp{$*} immediately after calling
1758 @code{AC_INIT}, because other Autoconf macros liberally use the
1759 @command{set} command to process strings, and this has the side effect
1760 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1761 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1762 implement your own option processing. @xref{Site Configuration}.
1766 @section Notices in @command{configure}
1767 @cindex Notices in @command{configure}
1769 The following macros manage version numbers for @command{configure}
1770 scripts. Using them is optional.
1772 @c FIXME: AC_PREREQ should not be here
1773 @defmac AC_PREREQ (@var{version})
1776 Ensure that a recent enough version of Autoconf is being used. If the
1777 version of Autoconf being used to create @command{configure} is
1778 earlier than @var{version}, print an error message to the standard
1779 error output and exit with failure (exit status is 63). For example:
1782 AC_PREREQ([@value{VERSION}])
1785 This macro is the only macro that may be used before @code{AC_INIT}, but
1786 for consistency, you are invited not to do so.
1789 @defmac AC_COPYRIGHT (@var{copyright-notice})
1791 @cindex Copyright Notice
1792 State that, in addition to the Free Software Foundation's copyright on
1793 the Autoconf macros, parts of your @command{configure} are covered by the
1794 @var{copyright-notice}.
1796 The @var{copyright-notice} shows up in both the head of
1797 @command{configure} and in @samp{configure --version}.
1801 @defmac AC_REVISION (@var{revision-info})
1804 Copy revision stamp @var{revision-info} into the @command{configure}
1805 script, with any dollar signs or double-quotes removed. This macro lets
1806 you put a revision stamp from @file{configure.ac} into @command{configure}
1807 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1808 @command{configure}. That way, you can determine easily which revision of
1809 @file{configure.ac} a particular @command{configure} corresponds to.
1811 For example, this line in @file{configure.ac}:
1813 @c The asis prevents RCS from changing the example in the manual.
1815 AC_REVISION([$@asis{Revision: 1.30 }$])
1819 produces this in @command{configure}:
1823 # From configure.ac Revision: 1.30
1829 @section Finding @command{configure} Input
1832 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1833 @acindex{CONFIG_SRCDIR}
1834 @var{unique-file-in-source-dir} is some file that is in the package's
1835 source directory; @command{configure} checks for this file's existence to
1836 make sure that the directory that it is told contains the source code in
1837 fact does. Occasionally people accidentally specify the wrong directory
1838 with @option{--srcdir}; this is a safety check. @xref{configure
1839 Invocation}, for more information.
1843 @c FIXME: Remove definitively once --install explained.
1845 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1846 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1847 @c to split the macros in several files. In this case, Autoconf must be
1848 @c told which files to load, and in which order.
1850 @c @defmac AC_INCLUDE (@var{file}@dots{})
1851 @c @acindex{INCLUDE}
1852 @c @c FIXME: There is no longer shell globbing.
1853 @c Read the macro definitions that appear in the listed files. A list of
1854 @c space-separated file names or shell globbing patterns is expected. The
1855 @c files are read in the order they're listed.
1857 @c Because the order of definition of macros is important (only the last
1858 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1859 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1860 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1861 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1862 @c the latter case, non-macro lines from included files may end up in the
1863 @c @file{configure} script, whereas in the former case, they'd be discarded
1864 @c just like any text that appear before @code{AC_INIT}.
1867 Packages that do manual configuration or use the @command{install} program
1868 might need to tell @command{configure} where to find some other shell
1869 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1870 it looks are correct for most cases.
1872 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1873 @acindex{CONFIG_AUX_DIR}
1874 Use the auxiliary build tools (e.g., @file{install-sh},
1875 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1876 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1877 These are auxiliary files used in configuration. @var{dir} can be
1878 either absolute or relative to @file{@var{srcdir}}. The default is
1879 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1880 @file{@var{srcdir}/../..}, whichever is the first that contains
1881 @file{install-sh}. The other files are not checked for, so that using
1882 @code{AC_PROG_INSTALL} does not automatically require distributing the
1883 other auxiliary files. It checks for @file{install.sh} also, but that
1884 name is obsolete because some @code{make} have a rule that creates
1885 @file{install} from it if there is no makefile.
1887 The auxiliary directory is commonly named @file{build-aux}.
1888 If you need portability to @acronym{DOS} variants, do not name the
1889 auxiliary directory @file{aux}. @xref{File System Conventions}.
1892 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1893 @acindex{REQUIRE_AUX_FILE}
1894 Declares that @var{file} is expected in the directory defined above. In
1895 Autoconf proper, this macro does nothing: its sole purpose is to be
1896 traced by third-party tools to produce a list of expected auxiliary
1897 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1898 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1899 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1902 Similarly, packages that use @command{aclocal} should declare where
1903 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1905 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1906 @acindex{CONFIG_MACRO_DIR}
1907 Specify @var{dir} as the location of additional local Autoconf macros.
1908 This macro is intended for use by future versions of commands like
1909 @command{autoreconf} that trace macro calls. It should be called
1910 directly from @file{configure.ac} so that tools that install macros for
1911 @command{aclocal} can find the macros' declarations.
1916 @section Outputting Files
1917 @cindex Outputting files
1919 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1920 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1921 @file{config.status}, which in turn creates the makefiles and any
1922 other files resulting from configuration. This is the only required
1923 macro besides @code{AC_INIT} (@pxref{Input}).
1927 @cindex Instantiation
1928 Generate @file{config.status} and launch it. Call this macro once, at
1929 the end of @file{configure.ac}.
1931 @file{config.status} performs all the configuration actions: all the
1932 output files (see @ref{Configuration Files}, macro
1933 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1934 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1935 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1936 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1937 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1940 The location of your @code{AC_OUTPUT} invocation is the exact point
1941 where configuration actions are taken: any code afterwards is
1942 executed by @code{configure} once @command{config.status} was run. If
1943 you want to bind actions to @command{config.status} itself
1944 (independently of whether @command{configure} is being run), see
1945 @ref{Configuration Commands, , Running Arbitrary Configuration
1949 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1950 @xref{Obsolete Macros}, for a description of the arguments that
1951 @code{AC_OUTPUT} used to support.
1954 If you run @command{make} in subdirectories, you should run it using the
1955 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1956 @code{MAKE} to the name of the @command{make} program plus any options it
1957 was given. (But many do not include in it the values of any variables
1958 set on the command line, so those are not passed on automatically.)
1959 Some old versions of @command{make} do not set this variable. The
1960 following macro allows you to use it even with those versions.
1962 @defmac AC_PROG_MAKE_SET
1963 @acindex{PROG_MAKE_SET}
1965 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1966 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1967 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1968 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1972 If you use this macro, place a line like this in each @file{Makefile.in}
1973 that runs @code{MAKE} on other directories:
1981 @node Configuration Actions
1982 @section Performing Configuration Actions
1983 @cindex Configuration actions
1985 @file{configure} is designed so that it appears to do everything itself,
1986 but there is actually a hidden slave: @file{config.status}.
1987 @file{configure} is in charge of examining your system, but it is
1988 @file{config.status} that actually takes the proper actions based on the
1989 results of @file{configure}. The most typical task of
1990 @file{config.status} is to @emph{instantiate} files.
1992 This section describes the common behavior of the four standard
1993 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1994 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1995 have this prototype:
1997 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
2000 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2004 where the arguments are:
2008 A blank-or-newline-separated list of tags, which are typically the names of
2009 the files to instantiate.
2011 You are encouraged to use literals as @var{tags}. In particular, you
2015 @dots{} && my_foos="$my_foos fooo"
2016 @dots{} && my_foos="$my_foos foooo"
2017 AC_CONFIG_FOOS([$my_foos])
2021 and use this instead:
2024 @dots{} && AC_CONFIG_FOOS([fooo])
2025 @dots{} && AC_CONFIG_FOOS([foooo])
2028 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2029 special @var{tag} values: they may have the form @samp{@var{output}} or
2030 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2031 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2033 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2034 for example, asks for
2035 the creation of the file @file{Makefile} that contains the expansion of the
2036 output variables in the concatenation of @file{boiler/top.mk} and
2037 @file{boiler/bot.mk}.
2039 The special value @samp{-} might be used to denote the standard output
2040 when used in @var{output}, or the standard input when used in the
2041 @var{inputs}. You most probably don't need to use this in
2042 @file{configure.ac}, but it is convenient when using the command line
2043 interface of @file{./config.status}, see @ref{config.status Invocation},
2046 The @var{inputs} may be absolute or relative file names. In the latter
2047 case they are first looked for in the build tree, and then in the source
2051 Shell commands output literally into @file{config.status}, and
2052 associated with a tag that the user can use to tell @file{config.status}
2053 which the commands to run. The commands are run each time a @var{tag}
2054 request is given to @file{config.status}, typically each time the file
2055 @file{@var{tag}} is created.
2057 The variables set during the execution of @command{configure} are
2058 @emph{not} available here: you first need to set them via the
2059 @var{init-cmds}. Nonetheless the following variables are precomputed:
2063 The name of the top source directory, assuming that the working
2064 directory is the top build directory. This
2065 is what the @command{configure} option @option{--srcdir} sets.
2068 The name of the top source directory, assuming that the working
2069 directory is the current build directory.
2072 @item ac_top_build_prefix
2073 The name of the top build directory, assuming that the working
2074 directory is the current build directory.
2075 It can be empty, or else ends with a slash, so that you may concatenate
2079 The name of the corresponding source directory, assuming that the
2080 working directory is the current build directory.
2084 The @dfn{current} directory refers to the directory (or
2085 pseudo-directory) containing the input part of @var{tags}. For
2089 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2093 with @option{--srcdir=../package} produces the following values:
2096 # Argument of --srcdir
2098 # Reversing deep/dir
2099 ac_top_build_prefix='../../'
2100 # Concatenation of $ac_top_build_prefix and srcdir
2101 ac_top_srcdir='../../../package'
2102 # Concatenation of $ac_top_srcdir and deep/dir
2103 ac_srcdir='../../../package/deep/dir'
2107 independently of @samp{in/in.in}.
2110 Shell commands output @emph{unquoted} near the beginning of
2111 @file{config.status}, and executed each time @file{config.status} runs
2112 (regardless of the tag). Because they are unquoted, for example,
2113 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2114 is typically used by @file{configure} to give @file{config.status} some
2115 variables it needs to run the @var{commands}.
2117 You should be extremely cautious in your variable names: all the
2118 @var{init-cmds} share the same name space and may overwrite each other
2119 in unpredictable ways. Sorry@enddots{}
2122 All these macros can be called multiple times, with different
2123 @var{tag} values, of course!
2126 @node Configuration Files
2127 @section Creating Configuration Files
2128 @cindex Creating configuration files
2129 @cindex Configuration file creation
2131 Be sure to read the previous section, @ref{Configuration Actions}.
2133 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2134 @acindex{CONFIG_FILES}
2135 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2136 file (by default @file{@var{file}.in}), substituting the output variable
2138 @c Before we used to have this feature, which was later rejected
2139 @c because it complicates the writing of makefiles:
2140 @c If the file would be unchanged, it is left untouched, to preserve
2142 This macro is one of the instantiating macros; see @ref{Configuration
2143 Actions}. @xref{Makefile Substitutions}, for more information on using
2144 output variables. @xref{Setting Output Variables}, for more information
2145 on creating them. This macro creates the directory that the file is in
2146 if it doesn't exist. Usually, makefiles are created this way,
2147 but other files, such as @file{.gdbinit}, can be specified as well.
2149 Typical calls to @code{AC_CONFIG_FILES} look like this:
2152 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2153 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2156 You can override an input file name by appending to @var{file} a
2157 colon-separated list of input files. Examples:
2160 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2161 [lib/Makefile:boiler/lib.mk])
2165 Doing this allows you to keep your file names acceptable to
2166 @acronym{DOS} variants, or
2167 to prepend and/or append boilerplate to the file.
2172 @node Makefile Substitutions
2173 @section Substitutions in Makefiles
2174 @cindex Substitutions in makefiles
2175 @cindex Makefile substitutions
2177 Each subdirectory in a distribution that contains something to be
2178 compiled or installed should come with a file @file{Makefile.in}, from
2179 which @command{configure} creates a file @file{Makefile} in that directory.
2180 To create @file{Makefile}, @command{configure} performs a simple variable
2181 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2182 @file{Makefile.in} with the value that @command{configure} has determined
2183 for that variable. Variables that are substituted into output files in
2184 this way are called @dfn{output variables}. They are ordinary shell
2185 variables that are set in @command{configure}. To make @command{configure}
2186 substitute a particular variable into the output files, the macro
2187 @code{AC_SUBST} must be called with that variable name as an argument.
2188 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2189 left unchanged. @xref{Setting Output Variables}, for more information
2190 on creating output variables with @code{AC_SUBST}.
2192 A software package that uses a @command{configure} script should be
2193 distributed with a file @file{Makefile.in}, but no makefile; that
2194 way, the user has to properly configure the package for the local system
2195 before compiling it.
2197 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2198 @acronym{GNU} Coding Standards}, for more information on what to put in
2202 * Preset Output Variables:: Output variables that are always set
2203 * Installation Directory Variables:: Other preset output variables
2204 * Changed Directory Variables:: Warnings about @file{datarootdir}
2205 * Build Directories:: Supporting multiple concurrent compiles
2206 * Automatic Remaking:: Makefile rules for configuring
2209 @node Preset Output Variables
2210 @subsection Preset Output Variables
2211 @cindex Output variables
2213 Some output variables are preset by the Autoconf macros. Some of the
2214 Autoconf macros set additional output variables, which are mentioned in
2215 the descriptions for those macros. @xref{Output Variable Index}, for a
2216 complete list of output variables. @xref{Installation Directory
2217 Variables}, for the list of the preset ones related to installation
2218 directories. Below are listed the other preset ones. They all are
2219 precious variables (@pxref{Setting Output Variables},
2222 @c Just say no to ASCII sorting! We're humans, not computers.
2223 @c These variables are listed as they would be in a dictionary:
2230 Debugging and optimization options for the C compiler. If it is not set
2231 in the environment when @command{configure} runs, the default value is set
2232 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2233 uses this variable when compiling or linking programs to test for C features.
2235 If a compiler option affects only the behavior of the preprocessor
2236 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2237 instead. If it affects only the linker (e.g., @option{-L
2238 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2239 affects only the compiler proper, @code{CFLAGS} is the natural home for
2240 it. If an option affects multiple phases of the compiler, though,
2241 matters get tricky. One approach to put such options directly into
2242 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2243 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2247 @defvar configure_input
2248 @ovindex configure_input
2249 A comment saying that the file was generated automatically by
2250 @command{configure} and giving the name of the input file.
2251 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2252 of every makefile it creates. For other files, you should
2253 reference this variable in a comment at the top of each input file. For
2254 example, an input shell script should begin like this:
2258 # @@configure_input@@
2262 The presence of that line also reminds people editing the file that it
2263 needs to be processed by @command{configure} in order to be used.
2268 Preprocessor options for the C, C++, and Objective C preprocessors and
2270 it is not set in the environment when @command{configure} runs, the default
2271 value is empty. @command{configure} uses this variable when preprocessing
2272 or compiling programs to test for C, C++, and Objective C features.
2274 This variable's contents should contain options like @option{-I},
2275 @option{-D}, and @option{-U} that affect only the behavior of the
2276 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2277 can do if an option affects other phases of the compiler as well.
2279 Currently, @command{configure} always links as part of a single
2280 invocation of the compiler that also preprocesses and compiles, so it
2281 uses this variable also when linking programs. However, it is unwise to
2282 depend on this behavior because the @acronym{GNU} coding standards do
2283 not require it and many packages do not use @code{CPPFLAGS} when linking
2286 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2292 Debugging and optimization options for the C++ compiler. It acts like
2293 @code{CFLAGS}, but for C++ instead of C.
2298 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2299 is called, @command{configure} replaces @samp{@@DEFS@@} with
2300 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2301 variable is not defined while @command{configure} is performing its tests,
2302 only when creating the output files. @xref{Setting Output Variables}, for
2303 how to check the results of previous tests.
2312 How does one suppress the trailing newline from @command{echo} for
2313 question-answer message pairs? These variables provide a way:
2316 echo $ECHO_N "And the winner is... $ECHO_C"
2318 echo "$@{ECHO_T@}dead."
2322 Some old and uncommon @command{echo} implementations offer no means to
2323 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2329 Debugging and optimization options for the Erlang compiler. If it is not set
2330 in the environment when @command{configure} runs, the default value is empty.
2331 @command{configure} uses this variable when compiling
2332 programs to test for Erlang features.
2337 Debugging and optimization options for the Fortran compiler. If it
2338 is not set in the environment when @command{configure} runs, the default
2339 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2340 @command{configure} uses this variable when compiling or linking
2341 programs to test for Fortran features.
2346 Debugging and optimization options for the Fortran 77 compiler. If it
2347 is not set in the environment when @command{configure} runs, the default
2348 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2349 @command{configure} uses this variable when compiling or linking
2350 programs to test for Fortran 77 features.
2355 Options for the linker. If it is not set
2356 in the environment when @command{configure} runs, the default value is empty.
2357 @command{configure} uses this variable when linking programs to test for
2358 C, C++, Objective C, and Fortran features.
2360 This variable's contents should contain options like @option{-s} and
2361 @option{-L} that affect only the behavior of the linker. Please see the
2362 explanation of @code{CFLAGS} for what you can do if an option also
2363 affects other phases of the compiler.
2365 Don't use this variable to pass library names
2366 (@option{-l}) to the linker; use @code{LIBS} instead.
2371 @option{-l} options to pass to the linker. The default value is empty,
2372 but some Autoconf macros may prepend extra libraries to this variable if
2373 those libraries are found and provide necessary functions, see
2374 @ref{Libraries}. @command{configure} uses this variable when linking
2375 programs to test for C, C++, and Fortran features.
2380 Debugging and optimization options for the Objective C compiler. It
2381 acts like @code{CFLAGS}, but for Objective C instead of C.
2386 Rigorously equal to @samp{.}. Added for symmetry only.
2389 @defvar abs_builddir
2390 @ovindex abs_builddir
2391 Absolute name of @code{builddir}.
2394 @defvar top_builddir
2395 @ovindex top_builddir
2396 The relative name of the top level of the current build tree. In the
2397 top-level directory, this is the same as @code{builddir}.
2400 @defvar abs_top_builddir
2401 @ovindex abs_top_builddir
2402 Absolute name of @code{top_builddir}.
2407 The name of the directory that contains the source code for
2413 Absolute name of @code{srcdir}.
2418 The name of the top-level source code directory for the
2419 package. In the top-level directory, this is the same as @code{srcdir}.
2422 @defvar abs_top_srcdir
2423 @ovindex abs_top_srcdir
2424 Absolute name of @code{top_srcdir}.
2427 @node Installation Directory Variables
2428 @subsection Installation Directory Variables
2429 @cindex Installation directories
2430 @cindex Directories, installation
2432 The following variables specify the directories for
2433 package installation, see @ref{Directory Variables, , Variables for
2434 Installation Directories, standards, The @acronym{GNU} Coding
2435 Standards}, for more information. See the end of this section for
2436 details on when and how to use these variables.
2440 The directory for installing executables that users run.
2445 The directory for installing idiosyncratic read-only
2446 architecture-independent data.
2450 @ovindex datarootdir
2451 The root of the directory tree for read-only architecture-independent
2457 The directory for installing documentation files (other than Info and
2463 The directory for installing documentation files in DVI format.
2467 @ovindex exec_prefix
2468 The installation prefix for architecture-dependent files. By default
2469 it's the same as @var{prefix}. You should avoid installing anything
2470 directly to @var{exec_prefix}. However, the default value for
2471 directories containing architecture-dependent files should be relative
2472 to @var{exec_prefix}.
2477 The directory for installing HTML documentation.
2482 The directory for installing C header files.
2487 The directory for installing documentation in Info format.
2492 The directory for installing object code libraries.
2497 The directory for installing executables that other programs run.
2502 The directory for installing locale-dependent but
2503 architecture-independent data, such as message catalogs. This directory
2504 usually has a subdirectory per locale.
2507 @defvar localstatedir
2508 @ovindex localstatedir
2509 The directory for installing modifiable single-machine data.
2514 The top-level directory for installing documentation in man format.
2517 @defvar oldincludedir
2518 @ovindex oldincludedir
2519 The directory for installing C header files for non-@acronym{GCC} compilers.
2524 The directory for installing PDF documentation.
2529 The common installation prefix for all files. If @var{exec_prefix}
2530 is defined to a different value, @var{prefix} is used only for
2531 architecture-independent files.
2536 The directory for installing PostScript documentation.
2541 The directory for installing executables that system
2545 @defvar sharedstatedir
2546 @ovindex sharedstatedir
2547 The directory for installing modifiable architecture-independent data.
2552 The directory for installing read-only single-machine data.
2556 Most of these variables have values that rely on @code{prefix} or
2557 @code{exec_prefix}. It is deliberate that the directory output
2558 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2559 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2560 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2562 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2567 she can still specify a different prefix from the one specified to
2568 @command{configure}, in which case, if needed, the package should hard
2569 code dependencies corresponding to the make-specified prefix.
2572 she can specify a different installation location, in which case the
2573 package @emph{must} still depend on the location which was compiled in
2574 (i.e., never recompile when @samp{make install} is run). This is an
2575 extremely important feature, as many people may decide to install all
2576 the files of a package grouped together, and then install links from
2577 the final locations to there.
2580 In order to support these features, it is essential that
2581 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2582 depend upon the current value of @code{prefix}.
2584 A corollary is that you should not use these variables except in
2585 makefiles. For instance, instead of trying to evaluate @code{datadir}
2586 in @file{configure} and hard-coding it in makefiles using
2587 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2589 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2590 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2592 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2593 @code{datadir} and friends in your shell scripts and other files; instead,
2594 let @command{make} manage their replacement. For instance Autoconf
2595 ships templates of its shell scripts ending with @samp{.in}, and uses a
2596 makefile snippet similar to the following to build scripts like
2597 @command{autoheader} and @command{autom4te}:
2602 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2603 -e 's|@@prefix[@@]|$(prefix)|g'
2607 autoheader autom4te: Makefile
2609 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2616 autoheader: $(srcdir)/autoheader.in
2617 autom4te: $(srcdir)/autom4te.in
2621 Some details are noteworthy:
2624 @item @samp{@@datadir[@@]}
2625 The brackets prevent @command{configure} from replacing
2626 @samp{@@datadir@@} in the Sed expression itself.
2627 Brackets are preferable to a backslash here, since
2628 Posix says @samp{\@@} is not portable.
2630 @item @samp{$(pkgdatadir)}
2631 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2635 Don't use @samp{/} in the Sed expressions that replace file names since
2637 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2638 Use a shell metacharacter instead, such as @samp{|}.
2640 @item special characters
2641 File names, file name components, and the value of @code{VPATH} should
2642 not contain shell metacharacters or white
2643 space. @xref{Special Chars in Variables}.
2645 @item dependency on @file{Makefile}
2646 Since @code{edit} uses values that depend on the configuration specific
2647 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2648 the output depends on @file{Makefile}, not @file{configure.ac}.
2651 The main rule is generic, and uses @samp{$@@} extensively to
2652 avoid the need for multiple copies of the rule.
2654 @item Separated dependencies and single suffix rules
2655 You can't use them! The above snippet cannot be (portably) rewritten
2659 autoconf autoheader: Makefile
2669 @xref{Single Suffix Rules}, for details.
2671 @item @samp{$(srcdir)}
2672 Be sure to specify the name of the source directory,
2673 otherwise the package won't support separated builds.
2676 For the more specific installation of Erlang libraries, the following variables
2679 @defvar ERLANG_INSTALL_LIB_DIR
2680 @ovindex ERLANG_INSTALL_LIB_DIR
2681 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2682 The common parent directory of Erlang library installation directories.
2683 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2684 macro in @file{configure.ac}.
2687 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2688 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2689 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2690 The installation directory for Erlang library @var{library}.
2691 This variable is set by calling the
2692 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2693 macro in @file{configure.ac}.
2696 @xref{Erlang Libraries}, for details.
2699 @node Changed Directory Variables
2700 @subsection Changed Directory Variables
2701 @cindex @file{datarootdir}
2703 In Autoconf 2.60, the set of directory variables has changed, and the
2704 defaults of some variables have been adjusted
2705 (@pxref{Installation Directory Variables}) to changes in the
2706 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2707 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2708 upgrading from an earlier Autoconf version, you may need to adjust your files
2709 to ensure that the directory variables are substituted correctly
2710 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2711 in place. For example, in a @file{Makefile.in}, adding
2714 datarootdir = @@datarootdir@@
2718 is usually sufficient. If you use Automake to create @file{Makefile.in},
2719 it will add this for you.
2721 To help with the transition, Autoconf warns about files that seem to use
2722 @code{datarootdir} without defining it. In some cases, it then expands
2723 the value of @code{$datarootdir} in substitutions of the directory
2724 variables. The following example shows such a warning:
2727 $ @kbd{cat configure.ac}
2729 AC_CONFIG_FILES([Makefile])
2731 $ @kbd{cat Makefile.in}
2733 datadir = @@datadir@@
2736 configure: creating ./config.status
2737 config.status: creating Makefile
2738 config.status: WARNING:
2739 Makefile.in seems to ignore the --datarootdir setting
2740 $ @kbd{cat Makefile}
2742 datadir = $@{prefix@}/share
2745 Usually one can easily change the file to accommodate both older and newer
2749 $ @kbd{cat Makefile.in}
2751 datarootdir = @@datarootdir@@
2752 datadir = @@datadir@@
2754 configure: creating ./config.status
2755 config.status: creating Makefile
2756 $ @kbd{cat Makefile}
2758 datarootdir = $@{prefix@}/share
2759 datadir = $@{datarootdir@}
2762 @acindex{DATAROOTDIR_CHECKED}
2763 In some cases, however, the checks may not be able to detect that a suitable
2764 initialization of @code{datarootdir} is in place, or they may fail to detect
2765 that such an initialization is necessary in the output file. If, after
2766 auditing your package, there are still spurious @file{configure} warnings about
2767 @code{datarootdir}, you may add the line
2770 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2774 to your @file{configure.ac} to disable the warnings. This is an exception
2775 to the usual rule that you should not define a macro whose name begins with
2776 @code{AC_} (@pxref{Macro Names}).
2780 @node Build Directories
2781 @subsection Build Directories
2782 @cindex Build directories
2783 @cindex Directories, build
2785 You can support compiling a software package for several architectures
2786 simultaneously from the same copy of the source code. The object files
2787 for each architecture are kept in their own directory.
2789 To support doing this, @command{make} uses the @code{VPATH} variable to
2790 find the files that are in the source directory. @acronym{GNU} Make
2791 can do this. Most other recent @command{make} programs can do this as
2792 well, though they may have difficulties and it is often simpler to
2793 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}). Older
2794 @command{make} programs do not support @code{VPATH}; when using them, the
2795 source code must be in the same directory as the object files.
2797 To support @code{VPATH}, each @file{Makefile.in} should contain two
2798 lines that look like:
2805 Do not set @code{VPATH} to the value of another variable, for example
2806 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2807 variable substitutions on the value of @code{VPATH}.
2809 @command{configure} substitutes the correct value for @code{srcdir} when
2810 it produces @file{Makefile}.
2812 Do not use the @code{make} variable @code{$<}, which expands to the
2813 file name of the file in the source directory (found with @code{VPATH}),
2814 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2815 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2816 versions of @command{make} do not set @code{$<} in explicit rules; they
2817 expand it to an empty value.
2819 Instead, Make command lines should always refer to source
2820 files by prefixing them with @samp{$(srcdir)/}. For example:
2823 time.info: time.texinfo
2824 $(MAKEINFO) '$(srcdir)/time.texinfo'
2827 @node Automatic Remaking
2828 @subsection Automatic Remaking
2829 @cindex Automatic remaking
2830 @cindex Remaking automatically
2832 You can put rules like the following in the top-level @file{Makefile.in}
2833 for a package to automatically update the configuration information when
2834 you change the configuration files. This example includes all of the
2835 optional files, such as @file{aclocal.m4} and those related to
2836 configuration header files. Omit from the @file{Makefile.in} rules for
2837 any of these files that your package does not use.
2839 The @samp{$(srcdir)/} prefix is included because of limitations in the
2840 @code{VPATH} mechanism.
2842 The @file{stamp-} files are necessary because the timestamps of
2843 @file{config.h.in} and @file{config.h} are not changed if remaking
2844 them does not change their contents. This feature avoids unnecessary
2845 recompilation. You should include the file @file{stamp-h.in} your
2846 package's distribution, so that @command{make} considers
2847 @file{config.h.in} up to date. Don't use @command{touch}
2848 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2849 @command{date} would cause needless differences, hence @acronym{CVS}
2854 $(srcdir)/configure: configure.ac aclocal.m4
2855 cd '$(srcdir)' && autoconf
2857 # autoheader might not change config.h.in, so touch a stamp file.
2858 $(srcdir)/config.h.in: stamp-h.in
2859 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2860 cd '$(srcdir)' && autoheader
2861 echo timestamp > '$(srcdir)/stamp-h.in'
2864 stamp-h: config.h.in config.status
2867 Makefile: Makefile.in config.status
2870 config.status: configure
2871 ./config.status --recheck
2876 (Be careful if you copy these lines directly into your makefile, as you
2877 need to convert the indented lines to start with the tab character.)
2879 In addition, you should use
2882 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2886 so @file{config.status} ensures that @file{config.h} is considered up to
2887 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2889 @xref{config.status Invocation}, for more examples of handling
2890 configuration-related dependencies.
2892 @node Configuration Headers
2893 @section Configuration Header Files
2894 @cindex Configuration Header
2895 @cindex @file{config.h}
2897 When a package contains more than a few tests that define C preprocessor
2898 symbols, the command lines to pass @option{-D} options to the compiler
2899 can get quite long. This causes two problems. One is that the
2900 @command{make} output is hard to visually scan for errors. More
2901 seriously, the command lines can exceed the length limits of some
2902 operating systems. As an alternative to passing @option{-D} options to
2903 the compiler, @command{configure} scripts can create a C header file
2904 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2905 macro selects this kind of output. Though it can be called anywhere
2906 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2907 it right after @code{AC_INIT}.
2909 The package should @samp{#include} the configuration header file before
2910 any other header files, to prevent inconsistencies in declarations (for
2911 example, if it redefines @code{const}).
2913 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2914 option (or @option{-I..}; whichever directory contains @file{config.h}).
2915 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2916 the directory of the currently read file, i.e., the source directory, not
2917 the build directory.
2919 With the appropriate @option{-I} option, you can use
2920 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2921 because in the rare case when the source directory contains another
2922 @file{config.h}, the build directory should be searched first.
2925 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2926 @acindex{CONFIG_HEADERS}
2927 @cvindex HAVE_CONFIG_H
2928 This macro is one of the instantiating macros; see @ref{Configuration
2929 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2930 blank-or-newline-separated list @var{header} containing C preprocessor
2931 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2932 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2933 The usual name for @var{header} is @file{config.h}.
2935 If @var{header} already exists and its contents are identical to what
2936 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2937 making some changes in the configuration without needlessly causing
2938 object files that depend on the header file to be recompiled.
2940 Usually the input file is named @file{@var{header}.in}; however, you can
2941 override the input file name by appending to @var{header} a
2942 colon-separated list of input files. For example, you might need to make
2943 the input file name acceptable to @acronym{DOS} variants:
2946 AC_CONFIG_HEADERS([config.h:config.hin])
2953 This macro is defined as the name of the first declared config header
2954 and undefined if no config headers have been declared up to this point.
2955 A third-party macro may, for example, require use of a config header
2956 without invoking AC_CONFIG_HEADERS twice, like this:
2959 AC_CONFIG_COMMANDS_PRE(
2960 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2965 @xref{Configuration Actions}, for more details on @var{header}.
2968 * Header Templates:: Input for the configuration headers
2969 * autoheader Invocation:: How to create configuration templates
2970 * Autoheader Macros:: How to specify CPP templates
2973 @node Header Templates
2974 @subsection Configuration Header Templates
2975 @cindex Configuration Header Template
2976 @cindex Header templates
2977 @cindex @file{config.h.in}
2979 Your distribution should contain a template file that looks as you want
2980 the final header file to look, including comments, with @code{#undef}
2981 statements which are used as hooks. For example, suppose your
2982 @file{configure.ac} makes these calls:
2985 AC_CONFIG_HEADERS([conf.h])
2986 AC_CHECK_HEADERS([unistd.h])
2990 Then you could have code like the following in @file{conf.h.in}. On
2991 systems that have @file{unistd.h}, @command{configure} defines
2992 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
2993 commented out (in case the system predefines that symbol).
2997 /* Define as 1 if you have unistd.h. */
2998 #undef HAVE_UNISTD_H
3002 Pay attention that @samp{#undef} is in the first column, and there is
3003 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3004 then decode the configuration header using the preprocessor directives:
3010 #ifdef HAVE_UNISTD_H
3011 # include <unistd.h>
3013 /* We are in trouble. */
3018 The use of old form templates, with @samp{#define} instead of
3019 @samp{#undef} is strongly discouraged. Similarly with old templates
3020 with comments on the same line as the @samp{#undef}. Anyway, putting
3021 comments in preprocessor macros has never been a good idea.
3023 Since it is a tedious task to keep a template header up to date, you may
3024 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3027 @node autoheader Invocation
3028 @subsection Using @command{autoheader} to Create @file{config.h.in}
3029 @cindex @command{autoheader}
3031 The @command{autoheader} program can create a template file of C
3032 @samp{#define} statements for @command{configure} to use.
3033 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3034 @file{configure} sources to determine the name of the template.
3035 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3036 input file name, @command{autoheader} uses the first one.)
3038 It is recommended that only one input file is used. If you want to append
3039 a boilerplate code, it is preferable to use
3040 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3041 File @file{conf_post.h} is not processed during the configuration then,
3042 which make things clearer. Analogically, @code{AH_TOP} can be used to
3043 prepend a boilerplate code.
3045 In order to do its job, @command{autoheader} needs you to document all
3046 of the symbols that you might use. Typically this is done via an
3047 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3048 is a literal symbol and whose third argument describes the symbol
3049 (@pxref{Defining Symbols}). Alternatively, you can use
3050 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3051 suitable input file for a subsequent configuration header file.
3052 Symbols defined by Autoconf's builtin tests are already documented properly;
3053 you need to document only those that you
3056 You might wonder why @command{autoheader} is needed: after all, why
3057 would @command{configure} need to ``patch'' a @file{config.h.in} to
3058 produce a @file{config.h} instead of just creating @file{config.h} from
3059 scratch? Well, when everything rocks, the answer is just that we are
3060 wasting our time maintaining @command{autoheader}: generating
3061 @file{config.h} directly is all that is needed. When things go wrong,
3062 however, you'll be thankful for the existence of @command{autoheader}.
3064 The fact that the symbols are documented is important in order to
3065 @emph{check} that @file{config.h} makes sense. The fact that there is a
3066 well-defined list of symbols that should be defined (or not) is
3067 also important for people who are porting packages to environments where
3068 @command{configure} cannot be run: they just have to @emph{fill in the
3071 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3073 If you give @command{autoheader} an argument, it uses that file instead
3074 of @file{configure.ac} and writes the header file to the standard output
3075 instead of to @file{config.h.in}. If you give @command{autoheader} an
3076 argument of @option{-}, it reads the standard input instead of
3077 @file{configure.ac} and writes the header file to the standard output.
3079 @command{autoheader} accepts the following options:
3084 Print a summary of the command line options and exit.
3088 Print the version number of Autoconf and exit.
3092 Report processing steps.
3096 Don't remove the temporary files.
3100 Remake the template file even if newer than its input files.
3102 @item --include=@var{dir}
3104 Append @var{dir} to the include path. Multiple invocations accumulate.
3106 @item --prepend-include=@var{dir}
3108 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3110 @item --warnings=@var{category}
3111 @itemx -W @var{category}
3113 Report the warnings related to @var{category} (which can actually be a
3114 comma separated list). Current categories include:
3118 report the uses of obsolete constructs
3121 report all the warnings
3127 treats warnings as errors
3129 @item no-@var{category}
3130 disable warnings falling into @var{category}
3137 @node Autoheader Macros
3138 @subsection Autoheader Macros
3139 @cindex Autoheader macros
3141 @command{autoheader} scans @file{configure.ac} and figures out which C
3142 preprocessor symbols it might define. It knows how to generate
3143 templates for symbols defined by @code{AC_CHECK_HEADERS},
3144 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3145 symbol, you must define a template for it. If there are missing
3146 templates, @command{autoheader} fails with an error message.
3148 The template for a @var{symbol} is created
3149 by @command{autoheader} from
3150 the @var{description} argument to an @code{AC_DEFINE};
3151 see @ref{Defining Symbols}.
3153 For special needs, you can use the following macros.
3156 @defmac AH_TEMPLATE (@var{key}, @var{description})
3158 Tell @command{autoheader} to generate a template for @var{key}. This macro
3159 generates standard templates just like @code{AC_DEFINE} when a
3160 @var{description} is given.
3165 AH_TEMPLATE([CRAY_STACKSEG_END],
3166 [Define to one of _getb67, GETB67, getb67
3167 for Cray-2 and Cray-YMP systems. This
3168 function is required for alloca.c support
3173 generates the following template, with the description properly
3177 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3178 Cray-YMP systems. This function is required for alloca.c
3179 support on those systems. */
3180 #undef CRAY_STACKSEG_END
3185 @defmac AH_VERBATIM (@var{key}, @var{template})
3187 Tell @command{autoheader} to include the @var{template} as-is in the header
3188 template file. This @var{template} is associated with the @var{key},
3189 which is used to sort all the different templates and guarantee their
3190 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3194 @defmac AH_TOP (@var{text})
3196 Include @var{text} at the top of the header template file.
3200 @defmac AH_BOTTOM (@var{text})
3202 Include @var{text} at the bottom of the header template file.
3206 Please note that @var{text} gets included ``verbatim'' to the template file,
3207 not to the resulting config header, so it can easily get mangled when the
3208 template is processed. There is rarely a need for something other than
3211 AH_BOTTOM([#include <custom.h>])
3216 @node Configuration Commands
3217 @section Running Arbitrary Configuration Commands
3218 @cindex Configuration commands
3219 @cindex Commands for configuration
3221 You can execute arbitrary commands before, during, and after
3222 @file{config.status} is run. The three following macros accumulate the
3223 commands to run when they are called multiple times.
3224 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3225 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3227 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3228 @acindex{CONFIG_COMMANDS}
3229 Specify additional shell commands to run at the end of
3230 @file{config.status}, and shell commands to initialize any variables
3231 from @command{configure}. Associate the commands with @var{tag}.
3232 Since typically the @var{cmds} create a file, @var{tag} should
3233 naturally be the name of that file. If needed, the directory hosting
3234 @var{tag} is created. This macro is one of the instantiating macros;
3235 see @ref{Configuration Actions}.
3237 Here is an unrealistic example:
3240 AC_CONFIG_COMMANDS([fubar],
3241 [echo this is extra $fubar, and so on.],
3245 Here is a better one:
3247 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3251 The following two macros look similar, but in fact they are not of the same
3252 breed: they are executed directly by @file{configure}, so you cannot use
3253 @file{config.status} to rerun them.
3255 @c Yet it is good to leave them here. The user sees them together and
3256 @c decides which best fits their needs.
3258 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3259 @acindex{CONFIG_COMMANDS_PRE}
3260 Execute the @var{cmds} right before creating @file{config.status}.
3262 This macro presents the last opportunity to call @code{AC_SUBST},
3263 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3266 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3267 @acindex{CONFIG_COMMANDS_POST}
3268 Execute the @var{cmds} right after creating @file{config.status}.
3274 @node Configuration Links
3275 @section Creating Configuration Links
3276 @cindex Configuration links
3277 @cindex Links for configuration
3279 You may find it convenient to create links whose destinations depend upon
3280 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3281 creation of relative symbolic links can be delicate when the package is
3282 built in a directory different from the source directory.
3284 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3285 @acindex{CONFIG_LINKS}
3287 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3288 the corresponding link name @var{dest}. Makes a symbolic link if
3289 possible, otherwise a hard link if possible, otherwise a copy. The
3290 @var{dest} and @var{source} names should be relative to the top level
3291 source or build directory. This macro is one of the instantiating
3292 macros; see @ref{Configuration Actions}.
3294 For example, this call:
3297 AC_CONFIG_LINKS([host.h:config/$machine.h
3298 object.h:config/$obj_format.h])
3302 creates in the current directory @file{host.h} as a link to
3303 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3304 link to @file{@var{srcdir}/config/$obj_format.h}.
3306 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3307 impossible for @samp{config.status} to guess the links to establish.
3311 ./config.status host.h object.h
3314 to create the links.
3319 @node Subdirectories
3320 @section Configuring Other Packages in Subdirectories
3321 @cindex Configure subdirectories
3322 @cindex Subdirectory configure
3324 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3325 makefiles in subdirectories. However, @command{configure} scripts
3326 that control more than one independent package can use
3327 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3328 packages in subdirectories.
3330 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3331 @acindex{CONFIG_SUBDIRS}
3333 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3334 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3335 be a literal, i.e., please do not use:
3338 if test "$package_foo_enabled" = yes; then
3339 $my_subdirs="$my_subdirs foo"
3341 AC_CONFIG_SUBDIRS([$my_subdirs])
3345 because this prevents @samp{./configure --help=recursive} from
3346 displaying the options of the package @code{foo}. Instead, you should
3350 if test "$package_foo_enabled" = yes; then
3351 AC_CONFIG_SUBDIRS([foo])
3355 If a given @var{dir} is not found, an error is reported: if the
3356 subdirectory is optional, write:
3359 if test -d "$srcdir/foo"; then
3360 AC_CONFIG_SUBDIRS([foo])
3364 @c NB: Yes, below we mean configure.in, not configure.ac.
3365 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3366 of @command{configure}. This is for packages that might use a
3367 non-Autoconf script @command{Configure}, which can't be called through a
3368 wrapper @command{configure} since it would be the same file on
3369 case-insensitive file systems. Likewise, if a @var{dir} contains
3370 @file{configure.in} but no @command{configure}, the Cygnus
3371 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3373 The subdirectory @command{configure} scripts are given the same command
3374 line options that were given to this @command{configure} script, with minor
3375 changes if needed, which include:
3379 adjusting a relative name for the cache file;
3382 adjusting a relative name for the source directory;
3385 propagating the current value of @code{$prefix}, including if it was
3386 defaulted, and if the default values of the top level and of the subdirectory
3387 @file{configure} differ.
3390 This macro also sets the output variable @code{subdirs} to the list of
3391 directories @samp{@var{dir} @dots{}}. Make rules can use
3392 this variable to determine which subdirectories to recurse into.
3394 This macro may be called multiple times.
3397 @node Default Prefix
3398 @section Default Prefix
3399 @cindex Install prefix
3400 @cindex Prefix for install
3402 By default, @command{configure} sets the prefix for files it installs to
3403 @file{/usr/local}. The user of @command{configure} can select a different
3404 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3405 There are two ways to change the default: when creating
3406 @command{configure}, and when running it.
3408 Some software packages might want to install in a directory other than
3409 @file{/usr/local} by default. To accomplish that, use the
3410 @code{AC_PREFIX_DEFAULT} macro.
3412 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3413 @acindex{PREFIX_DEFAULT}
3414 Set the default installation prefix to @var{prefix} instead of
3418 It may be convenient for users to have @command{configure} guess the
3419 installation prefix from the location of a related program that they
3420 have already installed. If you wish to do that, you can call
3421 @code{AC_PREFIX_PROGRAM}.
3423 @defmac AC_PREFIX_PROGRAM (@var{program})
3424 @acindex{PREFIX_PROGRAM}
3425 If the user did not specify an installation prefix (using the
3426 @option{--prefix} option), guess a value for it by looking for
3427 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3428 is found, set the prefix to the parent of the directory containing
3429 @var{program}, else default the prefix as described above
3430 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3431 @var{program} is @code{gcc} and the @env{PATH} contains
3432 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3437 @c ======================================================== Existing tests
3439 @node Existing Tests
3440 @chapter Existing Tests
3442 These macros test for particular system features that packages might
3443 need or want to use. If you need to test for a kind of feature that
3444 none of these macros check for, you can probably do it by calling
3445 primitive test macros with appropriate arguments (@pxref{Writing
3448 These tests print messages telling the user which feature they're
3449 checking for, and what they find. They cache their results for future
3450 @command{configure} runs (@pxref{Caching Results}).
3452 Some of these macros set output variables. @xref{Makefile
3453 Substitutions}, for how to get their values. The phrase ``define
3454 @var{name}'' is used below as a shorthand to mean ``define the C
3455 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3456 Symbols}, for how to get those symbol definitions into your program.
3459 * Common Behavior:: Macros' standard schemes
3460 * Alternative Programs:: Selecting between alternative programs
3461 * Files:: Checking for the existence of files
3462 * Libraries:: Library archives that might be missing
3463 * Library Functions:: C library functions that might be missing
3464 * Header Files:: Header files that might be missing
3465 * Declarations:: Declarations that may be missing
3466 * Structures:: Structures or members that might be missing
3467 * Types:: Types that might be missing
3468 * Compilers and Preprocessors:: Checking for compiling programs
3469 * System Services:: Operating system services
3470 * Posix Variants:: Special kludges for specific Posix variants
3471 * Erlang Libraries:: Checking for the existence of Erlang libraries
3474 @node Common Behavior
3475 @section Common Behavior
3476 @cindex Common autoconf behavior
3478 Much effort has been expended to make Autoconf easy to learn. The most
3479 obvious way to reach this goal is simply to enforce standard interfaces
3480 and behaviors, avoiding exceptions as much as possible. Because of
3481 history and inertia, unfortunately, there are still too many exceptions
3482 in Autoconf; nevertheless, this section describes some of the common
3486 * Standard Symbols:: Symbols defined by the macros
3487 * Default Includes:: Includes used by the generic macros
3490 @node Standard Symbols
3491 @subsection Standard Symbols
3492 @cindex Standard symbols
3494 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3495 their test transform their @var{argument} values to a standard alphabet.
3496 First, @var{argument} is converted to upper case and any asterisks
3497 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3498 that are not alphanumeric are converted to underscores.
3503 AC_CHECK_TYPES([struct $Expensive*])
3507 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3511 @node Default Includes
3512 @subsection Default Includes
3513 @cindex Default includes
3514 @cindex Includes, default
3516 Several tests depend upon a set of header files. Since these headers
3517 are not universally available, tests actually have to provide a set of
3518 protected includes, such as:
3522 #ifdef TIME_WITH_SYS_TIME
3523 # include <sys/time.h>
3526 # ifdef HAVE_SYS_TIME_H
3527 # include <sys/time.h>
3536 Unless you know exactly what you are doing, you should avoid using
3537 unconditional includes, and check the existence of the headers you
3538 include beforehand (@pxref{Header Files}).
3540 Most generic macros use the following macro to provide the default set
3543 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3544 @acindex{INCLUDES_DEFAULT}
3545 Expand to @var{include-directives} if defined, otherwise to:
3550 #ifdef HAVE_SYS_TYPES_H
3551 # include <sys/types.h>
3553 #ifdef HAVE_SYS_STAT_H
3554 # include <sys/stat.h>
3557 # include <stdlib.h>
3558 # include <stddef.h>
3560 # ifdef HAVE_STDLIB_H
3561 # include <stdlib.h>
3564 #ifdef HAVE_STRING_H
3565 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3566 # include <memory.h>
3568 # include <string.h>
3570 #ifdef HAVE_STRINGS_H
3571 # include <strings.h>
3573 #ifdef HAVE_INTTYPES_H
3574 # include <inttypes.h>
3576 #ifdef HAVE_STDINT_H
3577 # include <stdint.h>
3579 #ifdef HAVE_UNISTD_H
3580 # include <unistd.h>
3585 If the default includes are used, then check for the presence of these
3586 headers and their compatibility, i.e., you don't need to run
3587 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3589 These headers are checked for in the same order as they are included.
3590 For instance, on some systems @file{string.h} and @file{strings.h} both
3591 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3592 @code{HAVE_STRINGS_H}.
3595 @node Alternative Programs
3596 @section Alternative Programs
3597 @cindex Programs, checking
3599 These macros check for the presence or behavior of particular programs.
3600 They are used to choose between several alternative programs and to
3601 decide what to do once one has been chosen. If there is no macro
3602 specifically defined to check for a program you need, and you don't need
3603 to check for any special properties of it, then you can use one of the
3604 general program-check macros.
3607 * Particular Programs:: Special handling to find certain programs
3608 * Generic Programs:: How to find other programs
3611 @node Particular Programs
3612 @subsection Particular Program Checks
3614 These macros check for particular programs---whether they exist, and
3615 in some cases whether they support certain features.
3620 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3621 order, and set output variable @code{AWK} to the first one that is found.
3622 It tries @code{gawk} first because that is reported to be the
3623 best implementation.
3626 @defmac AC_PROG_GREP
3629 Look for the best available @code{grep} or @code{ggrep} that accepts the
3630 longest input lines possible, and that supports multiple @option{-e} options.
3631 Set the output variable @code{GREP} to whatever is chosen.
3632 @xref{Limitations of Usual Tools}, for more information about
3633 portability problems with the @command{grep} command family.
3636 @defmac AC_PROG_EGREP
3637 @acindex{PROG_EGREP}
3639 Check whether @code{$GREP -E} works, or else look for the best available
3640 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3641 Set the output variable @code{EGREP} to whatever is chosen.
3644 @defmac AC_PROG_FGREP
3645 @acindex{PROG_FGREP}
3647 Check whether @code{$GREP -F} works, or else look for the best available
3648 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3649 Set the output variable @code{FGREP} to whatever is chosen.
3652 @defmac AC_PROG_INSTALL
3653 @acindex{PROG_INSTALL}
3655 @ovindex INSTALL_PROGRAM
3656 @ovindex INSTALL_DATA
3657 @ovindex INSTALL_SCRIPT
3658 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3659 @command{install} program, if one is found in the current @env{PATH}.
3660 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3661 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3662 default directories) to determine @var{dir} (@pxref{Output}). Also set
3663 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3664 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3666 @samp{@@INSTALL@@} is special, as its value may vary for different
3667 configuration files.
3669 This macro screens out various instances of @command{install} known not to
3670 work. It prefers to find a C program rather than a shell script, for
3671 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3672 but that name is obsolete because some @command{make} programs have a rule
3673 that creates @file{install} from it if there is no makefile.
3675 Autoconf comes with a copy of @file{install-sh} that you can use. If
3676 you use @code{AC_PROG_INSTALL}, you must include either
3677 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3678 @command{configure} produces an error message saying it can't find
3679 them---even if the system you're on has a good @command{install} program.
3680 This check is a safety measure to prevent you from accidentally leaving
3681 that file out, which would prevent your package from installing on
3682 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3684 If you need to use your own installation program because it has features
3685 not found in standard @command{install} programs, there is no reason to use
3686 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3687 @file{Makefile.in} files.
3690 @defmac AC_PROG_MKDIR_P
3691 @acindex{AC_PROG_MKDIR_P}
3693 Set output variable @code{MKDIR_P} to a program that ensures that for
3694 each argument, a directory named by this argument exists, creating it
3695 and its parent directories if needed, and without race conditions when
3696 two instances of the program attempt to make the same directory at
3697 nearly the same time.
3699 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3700 falls back on invoking @command{install-sh} with the @option{-d} option,
3701 so your package should
3702 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3703 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3704 is vulnerable to race conditions, so if you want to support parallel
3706 different packages into the same directory you need to make sure you
3707 have an up-to-date @file{install-sh}. In particular, be careful about
3708 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3710 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3711 in M4sh}), but it sets an output variable intended for use in other
3712 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3713 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3714 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3715 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3716 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3717 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3718 Finally, @code{AS_MKDIR_P} does not check for race condition
3719 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3721 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3722 configuration files.
3729 @cvindex YYTEXT_POINTER
3730 @ovindex LEX_OUTPUT_ROOT
3731 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3732 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3733 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3736 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3737 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3738 the base of the file name that the lexer generates; usually
3739 @file{lex.yy}, but sometimes something else. These results vary
3740 according to whether @code{lex} or @code{flex} is being used.
3742 You are encouraged to use Flex in your sources, since it is both more
3743 pleasant to use than plain Lex and the C source it produces is portable.
3744 In order to ensure portability, however, you must either provide a
3745 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3746 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3747 statement in the scanner's source. Once this done, the scanner is
3748 portable (unless @emph{you} felt free to use nonportable constructs) and
3749 does not depend on any library. In this case, and in this case only, it
3750 is suggested that you use this Autoconf snippet:
3754 if test "$LEX" != flex; then
3755 LEX="$SHELL $missing_dir/missing flex"
3756 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3757 AC_SUBST([LEXLIB], [''])
3761 The shell script @command{missing} can be found in the Automake
3764 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3765 (indirectly) this macro twice, which causes an annoying but benign
3766 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3767 of Automake will fix this issue; meanwhile, just ignore this message.
3769 As part of running the test, this macro may delete any file in the
3770 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3773 @defmac AC_PROG_LN_S
3776 If @samp{ln -s} works on the current file system (the operating system
3777 and file system support symbolic links), set the output variable
3778 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3779 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3781 If you make a link in a directory other than the current directory, its
3782 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3783 create links using @samp{$(LN_S)}, either find out which form is used
3784 and adjust the arguments, or always invoke @code{ln} in the directory
3785 where the link is to be created.
3787 In other words, it does not work to do:
3795 (cd /x && $(LN_S) foo bar)
3799 @defmac AC_PROG_RANLIB
3800 @acindex{PROG_RANLIB}
3802 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3803 is found, and otherwise to @samp{:} (do nothing).
3809 Set output variable @code{SED} to a Sed implementation that conforms to
3810 Posix and does not have arbitrary length limits. Report an error if no
3811 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3812 information about portability problems with Sed.
3815 @defmac AC_PROG_YACC
3818 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3819 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3820 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3823 @node Generic Programs
3824 @subsection Generic Program and File Checks
3826 These macros are used to find programs not covered by the ``particular''
3827 test macros. If you need to check the behavior of a program as well as
3828 find out whether it is present, you have to write your own test for it
3829 (@pxref{Writing Tests}). By default, these macros use the environment
3830 variable @env{PATH}. If you need to check for a program that might not
3831 be in the user's @env{PATH}, you can pass a modified path to use
3835 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3836 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3839 You are strongly encouraged to declare the @var{variable} passed to
3840 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3841 @code{AC_ARG_VAR}, for more details.
3843 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3844 @acindex{CHECK_PROG}
3845 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3846 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3847 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3848 absolute file name) even if it is the first found in the search path; in
3849 that case, set @var{variable} using the absolute file name of the
3850 @var{prog-to-check-for} found that is not @var{reject}. If
3851 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3855 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3856 @acindex{CHECK_PROGS}
3857 Check for each program in the blank-separated list
3858 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3859 @var{variable} to the name of that program. Otherwise, continue
3860 checking the next program in the list. If none of the programs in the
3861 list are found, set @var{variable} to @var{value-if-not-found}; if
3862 @var{value-if-not-found} is not specified, the value of @var{variable}
3863 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3866 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3867 @acindex{CHECK_TARGET_TOOL}
3868 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3869 with a prefix of the target type as determined by
3870 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3871 If the tool cannot be found with a prefix, and if the build and target
3872 types are equal, then it is also searched for without a prefix.
3874 As noted in @ref{Specifying Names, , Specifying the system type}, the
3875 target is rarely specified, because most of the time it is the same
3876 as the host: it is the type of system for which any compiler tool in
3877 the package produces code. What this macro looks for is,
3878 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3879 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3880 uses to produce objects, archives or executables}.
3883 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3884 @acindex{CHECK_TOOL}
3885 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3886 with a prefix of the host type as determined by
3887 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3888 For example, if the user runs @samp{configure --host=i386-gnu}, then
3891 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3894 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3895 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3896 @env{PATH}, or to @samp{:} if neither program exists.
3898 In the future, when cross-compiling this macro will @emph{only}
3899 accept program names that are prefixed with the host type.
3900 For more information, see @ref{Specifying Names, , Specifying the
3904 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3905 @acindex{CHECK_TARGET_TOOLS}
3906 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3907 @var{progs-to-check-for} are checked with a prefix of the target type as
3908 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3909 (@pxref{Canonicalizing}). If none of the tools can be found with a
3910 prefix, and if the build and target types are equal, then the first one
3911 without a prefix is used. If a tool is found, set @var{variable} to
3912 the name of that program. If none of the tools in the list are found,
3913 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3914 is not specified, the value of @var{variable} is not changed. Calls
3915 @code{AC_SUBST} for @var{variable}.
3918 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3919 @acindex{CHECK_TOOLS}
3920 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3921 @var{progs-to-check-for} are checked with a prefix of the host type as
3922 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3923 (@pxref{Canonicalizing}). If none of the tools can be found with a
3924 prefix, then the first one without a prefix is used. If a tool is found,
3925 set @var{variable} to the name of that program. If none of the tools in
3926 the list are found, set @var{variable} to @var{value-if-not-found}; if
3927 @var{value-if-not-found} is not specified, the value of @var{variable}
3928 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3930 In the future, when cross-compiling this macro will @emph{not}
3931 accept program names that are not prefixed with the host type.
3934 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3936 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3937 name of @var{prog-to-check-for} if found.
3940 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3941 @acindex{PATH_PROGS}
3942 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3943 are found, set @var{variable} to the absolute name of the program
3947 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3948 @acindex{PATH_TARGET_TOOL}
3949 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3950 name of the program if it is found.
3953 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3955 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3956 name of the program if it is found.
3958 In the future, when cross-compiling this macro will @emph{not}
3959 accept program names that are not prefixed with the host type.
3965 @cindex File, checking
3967 You might also need to check for the existence of files. Before using
3968 these macros, ask yourself whether a runtime test might not be a better
3969 solution. Be aware that, like most Autoconf macros, they test a feature
3970 of the host machine, and therefore, they die when cross-compiling.
3972 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3973 @acindex{CHECK_FILE}
3974 Check whether file @var{file} exists on the native system. If it is
3975 found, execute @var{action-if-found}, otherwise do
3976 @var{action-if-not-found}, if given.
3979 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3980 @acindex{CHECK_FILES}
3981 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3982 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3983 for each file found.
3988 @section Library Files
3989 @cindex Library, checking
3991 The following macros check for the presence of certain C, C++, or Fortran
3992 library archive files.
3994 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3996 Test whether the library @var{library} is available by trying to link
3997 a test program that calls function @var{function} with the library.
3998 @var{function} should be a function provided by the library.
4000 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4001 the @var{library} argument.
4003 @var{action-if-found} is a list of shell commands to run if the link
4004 with the library succeeds; @var{action-if-not-found} is a list of shell
4005 commands to run if the link fails. If @var{action-if-found} is not
4006 specified, the default action prepends @option{-l@var{library}} to
4007 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4008 capitals). This macro is intended to support building @code{LIBS} in
4009 a right-to-left (least-dependent to most-dependent) fashion such that
4010 library dependencies are satisfied as a natural side effect of
4011 consecutive tests. Linkers are sensitive to library ordering
4012 so the order in which @code{LIBS} is generated is important to reliable
4013 detection of libraries.
4015 If linking with @var{library} results in unresolved symbols that would
4016 be resolved by linking with additional libraries, give those libraries
4017 as the @var{other-libraries} argument, separated by spaces:
4018 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4019 that @var{library} is present, because linking the test program
4020 always fails with unresolved symbols. The @var{other-libraries} argument
4021 should be limited to cases where it is desirable to test for one library
4022 in the presence of another that is not already in @code{LIBS}.
4024 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4025 in some common cases. Many standard functions like @code{gethostbyname}
4026 appear the standard C library on some hosts, and in special libraries
4027 like @code{nsl} on other hosts. On some hosts the special libraries
4028 contain variant implementations that you may not want to use. These
4029 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4030 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4034 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4035 @acindex{SEARCH_LIBS}
4036 Search for a library defining @var{function} if it's not already
4037 available. This equates to calling
4038 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4039 no libraries, then for each library listed in @var{search-libs}.
4041 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4042 to contain @var{function}, and run @var{action-if-found}. If the
4043 function is not found, run @var{action-if-not-found}.
4045 If linking with @var{library} results in unresolved symbols that would
4046 be resolved by linking with additional libraries, give those libraries
4047 as the @var{other-libraries} argument, separated by spaces:
4048 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4049 that @var{function} is present, because linking the test program
4050 always fails with unresolved symbols.
4055 @node Library Functions
4056 @section Library Functions
4058 The following macros check for particular C library functions.
4059 If there is no macro specifically defined to check for a function you need,
4060 and you don't need to check for any special properties of
4061 it, then you can use one of the general function-check macros.
4064 * Function Portability:: Pitfalls with usual functions
4065 * Particular Functions:: Special handling to find certain functions
4066 * Generic Functions:: How to find other functions
4069 @node Function Portability
4070 @subsection Portability of C Functions
4071 @cindex Portability of C functions
4072 @cindex C function portability
4074 Most usual functions can either be missing, or be buggy, or be limited
4075 on some architectures. This section tries to make an inventory of these
4076 portability issues. By definition, this list always requires
4077 additions. Please help us keeping it as complete as possible.
4082 @prindex @code{exit}
4083 On ancient hosts, @code{exit} returned @code{int}.
4084 This is because @code{exit} predates @code{void}, and there was a long
4085 tradition of it returning @code{int}.
4087 On current hosts, the problem more likely is that @code{exit} is not
4088 declared, due to C++ problems of some sort or another. For this reason
4089 we suggest that test programs not invoke @code{exit}, but return from
4090 @code{main} instead.
4094 @prindex @code{free}
4095 The C standard says a call @code{free (NULL)} does nothing, but
4096 some old systems don't support this (e.g., NextStep).
4102 @prindex @code{isinf}
4103 @prindex @code{isnan}
4104 The C99 standard says that @code{isinf} and @code{isnan} are
4105 macros. On some systems just macros are available
4106 (e.g., @acronym{HP-UX} and Solaris 10), on
4107 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4108 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4109 these functions are declared in nonstandard headers like
4110 @code{<sunmath.h>} and defined in non-default libraries like
4111 @option{-lm} or @option{-lsunmath}.
4113 The C99 @code{isinf} and @code{isnan} macros work correctly with
4114 @code{long double} arguments, but pre-C99 systems that use functions
4115 typically assume @code{double} arguments. On such a system,
4116 @code{isinf} incorrectly returns true for a finite @code{long double}
4117 argument that is outside the range of @code{double}.
4119 To work around this porting mess, you can use code like the following.
4126 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4127 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4129 static inline int isnan_f (float x) @{ return x != x; @}
4130 static inline int isnan_d (double x) @{ return x != x; @}
4131 static inline int isnan_ld (long double x) @{ return x != x; @}
4136 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4137 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4139 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4140 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4141 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4145 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4146 compilers that lack the @code{inline} keyword. Some optimizing
4147 compilers mishandle these definitions, but systems with that bug
4148 typically have missing or broken @code{isnan} functions anyway, so it's
4149 probably not worth worrying about.
4153 @prindex @code{malloc}
4154 The C standard says a call @code{malloc (0)} is implementation
4155 dependent. It can return either @code{NULL} or a new non-null pointer.
4156 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4157 no means universal. @code{AC_FUNC_MALLOC}
4158 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4162 @prindex @code{putenv}
4163 Posix prefers @code{setenv} to @code{putenv}; among other things,
4164 @code{putenv} is not required of all Posix implementations, but
4167 Posix specifies that @code{putenv} puts the given string directly in
4168 @code{environ}, but some systems make a copy of it instead (e.g.,
4169 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4170 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4172 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4173 environment, but this is not standard usage and it dumps core
4174 on some systems (e.g., AIX).
4176 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4177 environment, rather than inserting it with an empty value.
4179 @item @code{realloc}
4181 @prindex @code{realloc}
4182 The C standard says a call @code{realloc (NULL, size)} is equivalent
4183 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4186 @item @code{signal} handler
4188 @prindex @code{signal}
4189 Normally @code{signal} takes a handler function with a return type of
4190 @code{void}, but some old systems required @code{int} instead. Any
4191 actual @code{int} value returned is not used; this is only a
4192 difference in the function prototype demanded.
4194 All systems we know of in current use return @code{void}. The
4195 @code{int} was to support K&R C, where of course @code{void} is not
4196 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4197 used to establish the correct type in all cases.
4199 @item @code{snprintf}
4200 @c @fuindex snprintf
4201 @prindex @code{snprintf}
4202 @c @fuindex vsnprintf
4203 @prindex @code{vsnprintf}
4204 The C99 standard says that if the output array isn't big enough
4205 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4206 truncate the output and return the number of bytes that ought to have
4207 been produced. Some older systems return the truncated length (e.g.,
4208 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4209 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4210 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4211 older systems ignore the length and overrun the buffer (e.g., 64-bit
4214 @item @code{sprintf}
4216 @prindex @code{sprintf}
4217 @c @fuindex vsprintf
4218 @prindex @code{vsprintf}
4219 The C standard says @code{sprintf} and @code{vsprintf} return the
4220 number of bytes written. On some ancient systems (SunOS 4 for
4221 instance) they return the buffer pointer instead, but these no
4222 longer need to be worried about.
4226 @prindex @code{sscanf}
4227 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4228 input string be writable (though it doesn't actually change it). This
4229 can be a problem when using @command{gcc} since it normally puts
4230 constant strings in read-only memory (@pxref{Incompatibilities,
4231 Incompatibilities of @acronym{GCC}, , gcc, Using and
4232 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4233 having format strings read-only can be a problem.
4235 @item @code{strerror_r}
4236 @c @fuindex strerror_r
4237 @prindex @code{strerror_r}
4238 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4239 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4240 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4241 can detect which is in use (@pxref{Particular Functions}).
4243 @item @code{strnlen}
4245 @prindex @code{strnlen}
4246 @acronym{AIX} 4.3 provides a broken version which produces the
4250 strnlen ("foobar", 0) = 0
4251 strnlen ("foobar", 1) = 3
4252 strnlen ("foobar", 2) = 2
4253 strnlen ("foobar", 3) = 1
4254 strnlen ("foobar", 4) = 0
4255 strnlen ("foobar", 5) = 6
4256 strnlen ("foobar", 6) = 6
4257 strnlen ("foobar", 7) = 6
4258 strnlen ("foobar", 8) = 6
4259 strnlen ("foobar", 9) = 6
4262 @item @code{sysconf}
4264 @prindex @code{sysconf}
4265 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4266 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4271 @prindex @code{unlink}
4272 The Posix spec says that @code{unlink} causes the given file to be
4273 removed only after there are no more open file handles for it. Some
4274 non-Posix hosts have trouble with this requirement, though,
4275 and some @acronym{DOS} variants even corrupt the file system.
4277 @item @code{unsetenv}
4278 @c @fuindex unsetenv
4279 @prindex @code{unsetenv}
4280 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4281 can be removed with a call @code{putenv ("FOO=")}, as described under
4282 @code{putenv} above.
4284 @item @code{va_copy}
4286 @prindex @code{va_copy}
4287 The C99 standard provides @code{va_copy} for copying
4288 @code{va_list} variables. It may be available in older environments
4289 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4290 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4291 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4294 @item @code{va_list}
4296 @prindex @code{va_list}
4297 @code{va_list} is not necessarily just a pointer. It can be a
4298 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4299 not portable. Or it can be an array (e.g., @command{gcc} in some
4300 PowerPC configurations), which means as a function parameter it can be
4301 effectively call-by-reference and library routines might modify the
4302 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4305 @item Signed @code{>>}
4306 Normally the C @code{>>} right shift of a signed type replicates the
4307 high bit, giving a so-called ``arithmetic'' shift. But care should be
4308 taken since Standard C doesn't require that behavior. On those
4309 few processors without a native arithmetic shift (for instance Cray
4310 vector systems) zero bits may be shifted in, the same as a shift of an
4313 @item Integer @code{/}
4314 C divides signed integers by truncating their quotient toward zero,
4315 yielding the same result as Fortran. However, before C99 the standard
4316 allowed C implementations to take the floor or ceiling of the quotient
4317 in some cases. Hardly any implementations took advantage of this
4318 freedom, though, and it's probably not worth worrying about this issue
4323 @node Particular Functions
4324 @subsection Particular Function Checks
4325 @cindex Function, checking
4327 These macros check for particular C functions---whether they exist, and
4328 in some cases how they respond when given certain arguments.
4330 @defmac AC_FUNC_ALLOCA
4331 @acindex{FUNC_ALLOCA}
4333 @cvindex HAVE_ALLOCA_H
4336 @prindex @code{alloca}
4338 Check how to get @code{alloca}. Tries to get a builtin version by
4339 checking for @file{alloca.h} or the predefined C preprocessor macros
4340 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4341 it defines @code{HAVE_ALLOCA_H}.
4343 If those attempts fail, it looks for the function in the standard C
4344 library. If any of those methods succeed, it defines
4345 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4346 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4347 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4348 garbage collect). This variable is separate from @code{LIBOBJS} so
4349 multiple programs can share the value of @code{ALLOCA} without needing
4350 to create an actual library, in case only some of them use the code in
4351 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4352 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4354 This macro does not try to get @code{alloca} from the System V R3
4355 @file{libPW} or the System V R4 @file{libucb} because those libraries
4356 contain some incompatible functions that cause trouble. Some versions
4357 do not even contain @code{alloca} or contain a buggy version. If you
4358 still want to use their @code{alloca}, use @code{ar} to extract
4359 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4361 Source files that use @code{alloca} should start with a piece of code
4362 like the following, to declare it properly.
4366 #ifdef HAVE_ALLOCA_H
4367 # include <alloca.h>
4368 #elif defined __GNUC__
4369 # define alloca __builtin_alloca
4371 # define alloca __alloca
4372 #elif defined _MSC_VER
4373 # include <malloc.h>
4374 # define alloca _alloca
4376 # include <stddef.h>
4380 void *alloca (size_t);
4386 @defmac AC_FUNC_CHOWN
4387 @acindex{FUNC_CHOWN}
4389 @prindex @code{chown}
4390 If the @code{chown} function is available and works (in particular, it
4391 should accept @option{-1} for @code{uid} and @code{gid}), define
4396 @defmac AC_FUNC_CLOSEDIR_VOID
4397 @acindex{FUNC_CLOSEDIR_VOID}
4398 @cvindex CLOSEDIR_VOID
4399 @c @fuindex closedir
4400 @prindex @code{closedir}
4401 If the @code{closedir} function does not return a meaningful value,
4402 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4403 return value for an error indicator.
4405 Currently this test is implemented by running a test program. When
4406 cross compiling the pessimistic assumption that @code{closedir} does not
4407 return a meaningful value is made.
4409 This macro is obsolescent, as @code{closedir} returns a meaningful value
4410 on current systems. New programs need not use this macro.
4413 @defmac AC_FUNC_ERROR_AT_LINE
4414 @acindex{FUNC_ERROR_AT_LINE}
4415 @c @fuindex error_at_line
4416 @prindex @code{error_at_line}
4417 If the @code{error_at_line} function is not found, require an
4418 @code{AC_LIBOBJ} replacement of @samp{error}.
4421 @defmac AC_FUNC_FNMATCH
4422 @acindex{FUNC_FNMATCH}
4424 @prindex @code{fnmatch}
4425 If the @code{fnmatch} function conforms to Posix, define
4426 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4427 the bugs in Solaris 2.4.
4429 Unlike the other specific
4430 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4431 broken/missing @code{fnmatch}. This is for historical reasons.
4432 See @code{AC_REPLACE_FNMATCH} below.
4434 This macro is obsolescent. New programs should use Gnulib's
4435 @code{fnmatch-posix} module. @xref{Gnulib}.
4438 @defmac AC_FUNC_FNMATCH_GNU
4439 @acindex{FUNC_FNMATCH_GNU}
4441 @prindex @code{fnmatch}
4442 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4443 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4444 implementation bugs, for example, the bugs in the @acronym{GNU} C
4447 This macro is obsolescent. New programs should use Gnulib's
4448 @code{fnmatch-gnu} module. @xref{Gnulib}.
4451 @defmac AC_FUNC_FORK
4453 @cvindex HAVE_VFORK_H
4454 @cvindex HAVE_WORKING_FORK
4455 @cvindex HAVE_WORKING_VFORK
4458 @prindex @code{fork}
4460 @prindex @code{vfork}
4462 This macro checks for the @code{fork} and @code{vfork} functions. If a
4463 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4464 checks whether @code{fork} is just a stub by trying to run it.
4466 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4467 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4468 define @code{vfork} to be @code{fork} for backward compatibility with
4469 previous versions of @command{autoconf}. This macro checks for several known
4470 errors in implementations of @code{vfork} and considers the system to not
4471 have a working @code{vfork} if it detects any of them. It is not considered
4472 to be an implementation error if a child's invocation of @code{signal}
4473 modifies the parent's signal handler, since child processes rarely change
4474 their signal handlers.
4476 Since this macro defines @code{vfork} only for backward compatibility with
4477 previous versions of @command{autoconf} you're encouraged to define it
4478 yourself in new code:
4481 #ifndef HAVE_WORKING_VFORK
4488 @defmac AC_FUNC_FSEEKO
4489 @acindex{FUNC_FSEEKO}
4490 @cvindex _LARGEFILE_SOURCE
4492 @prindex @code{fseeko}
4493 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4494 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4495 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4496 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4497 largefile-sensitive systems where @code{off_t} does not default to a
4501 @defmac AC_FUNC_GETGROUPS
4502 @acindex{FUNC_GETGROUPS}
4503 @ovindex GETGROUPS_LIBS
4504 @c @fuindex getgroups
4505 @prindex @code{getgroups}
4506 If the @code{getgroups} function is available and works (unlike on
4507 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4508 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4509 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4512 @defmac AC_FUNC_GETLOADAVG
4513 @acindex{FUNC_GETLOADAVG}
4518 @cvindex HAVE_NLIST_H
4519 @cvindex NLIST_NAME_UNION
4520 @cvindex GETLOADAVG_PRIVILEGED
4521 @cvindex NEED_SETGID
4522 @cvindex C_GETLOADAVG
4524 @ovindex NEED_SETGID
4526 @ovindex GETLOADAVG_LIBS
4527 @c @fuindex getloadavg
4528 @prindex @code{getloadavg}
4529 Check how to get the system load averages. To perform its tests
4530 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4531 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4532 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4534 If the system has the @code{getloadavg} function, define
4535 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4536 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4537 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4538 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4539 possibly define several other C preprocessor macros and output
4544 Define @code{C_GETLOADAVG}.
4547 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4552 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4555 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4556 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4557 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4560 Programs may need to be installed set-group-ID (or set-user-ID) for
4561 @code{getloadavg} to work. In this case, define
4562 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4563 to @samp{true} (and otherwise to @samp{false}), and set
4564 @code{KMEM_GROUP} to the name of the group that should own the installed
4568 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
4569 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
4572 @defmac AC_FUNC_GETMNTENT
4573 @acindex{FUNC_GETMNTENT}
4574 @cvindex HAVE_GETMNTENT
4575 @c @fuindex getmntent
4576 @prindex @code{getmntent}
4577 Check for @code{getmntent} in the standard C library, and then in the
4578 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4579 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4580 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4583 @defmac AC_FUNC_GETPGRP
4584 @acindex{FUNC_GETPGRP}
4585 @cvindex GETPGRP_VOID
4588 @prindex @code{getpgid}
4589 @prindex @code{getpgrp}
4590 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4591 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4592 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4593 behaves like Posix's @code{getpgid}.
4603 This macro does not check whether
4604 @code{getpgrp} exists at all; if you need to work in that situation,
4605 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4607 This macro is obsolescent, as current systems have a @code{getpgrp}
4608 whose signature conforms to Posix. New programs need not use this macro.
4611 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4612 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4613 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4615 @prindex @code{lstat}
4616 If @file{link} is a symbolic link, then @code{lstat} should treat
4617 @file{link/} the same as @file{link/.}. However, many older
4618 @code{lstat} implementations incorrectly ignore trailing slashes.
4620 It is safe to assume that if @code{lstat} incorrectly ignores
4621 trailing slashes, then other symbolic-link-aware functions like
4622 @code{unlink} also incorrectly ignore trailing slashes.
4624 If @code{lstat} behaves properly, define
4625 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4626 @code{AC_LIBOBJ} replacement of @code{lstat}.
4629 @defmac AC_FUNC_MALLOC
4630 @acindex{FUNC_MALLOC}
4631 @cvindex HAVE_MALLOC
4634 @prindex @code{malloc}
4635 If the @code{malloc} function is compatible with the @acronym{GNU} C
4636 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4637 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4638 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4639 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4640 native @code{malloc} is not used in the main project.
4642 Typically, the replacement file @file{malloc.c} should look like (note
4643 the @samp{#undef malloc}):
4646 #ifdef HAVE_CONFIG_H
4647 # include <config.h>
4651 #include <sys/types.h>
4655 /* Allocate an N-byte block of memory from the heap.
4656 If N is zero, allocate a 1-byte block. */
4659 rpl_malloc (size_t n)
4668 @defmac AC_FUNC_MEMCMP
4669 @acindex{FUNC_MEMCMP}
4672 @prindex @code{memcmp}
4673 If the @code{memcmp} function is not available, or does not work on
4674 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4675 bytes or more and with at least one buffer not starting on a 4-byte
4676 boundary (such as the one on NeXT x86 OpenStep), require an
4677 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4679 This macro is obsolescent, as current systems have a working
4680 @code{memcmp}. New programs need not use this macro.
4683 @defmac AC_FUNC_MBRTOWC
4684 @acindex{FUNC_MBRTOWC}
4685 @cvindex HAVE_MBRTOWC
4687 @prindex @code{mbrtowc}
4688 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4689 type @code{mbstate_t} are properly declared.
4692 @defmac AC_FUNC_MKTIME
4693 @acindex{FUNC_MKTIME}
4696 @prindex @code{mktime}
4697 If the @code{mktime} function is not available, or does not work
4698 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4699 For the purposes of this test, @code{mktime} should conform to the
4700 Posix standard and should be the inverse of
4704 @defmac AC_FUNC_MMAP
4708 @prindex @code{mmap}
4709 If the @code{mmap} function exists and works correctly, define
4710 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4714 @defmac AC_FUNC_OBSTACK
4715 @acindex{FUNC_OBSTACK}
4716 @cvindex HAVE_OBSTACK
4718 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4719 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4722 @defmac AC_FUNC_REALLOC
4723 @acindex{FUNC_REALLOC}
4724 @cvindex HAVE_REALLOC
4727 @prindex @code{realloc}
4728 If the @code{realloc} function is compatible with the @acronym{GNU} C
4729 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4730 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4731 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4732 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4733 the native @code{realloc} is not used in the main project. See
4734 @code{AC_FUNC_MALLOC} for details.
4737 @defmac AC_FUNC_SELECT_ARGTYPES
4738 @acindex{FUNC_SELECT_ARGTYPES}
4739 @cvindex SELECT_TYPE_ARG1
4740 @cvindex SELECT_TYPE_ARG234
4741 @cvindex SELECT_TYPE_ARG5
4743 @prindex @code{select}
4744 Determines the correct type to be passed for each of the
4745 @code{select} function's arguments, and defines those types
4746 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4747 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4748 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4749 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4751 This macro is obsolescent, as current systems have a @code{select} whose
4752 signature conforms to Posix. New programs need not use this macro.
4755 @defmac AC_FUNC_SETPGRP
4756 @acindex{FUNC_SETPGRP}
4757 @cvindex SETPGRP_VOID
4759 @prindex @code{setpgrp}
4760 If @code{setpgrp} takes no argument (the Posix version), define
4761 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4762 two process IDs as arguments. This macro does not check whether
4763 @code{setpgrp} exists at all; if you need to work in that situation,
4764 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4766 This macro is obsolescent, as current systems have a @code{setpgrp}
4767 whose signature conforms to Posix. New programs need not use this macro.
4770 @defmac AC_FUNC_STAT
4771 @defmacx AC_FUNC_LSTAT
4773 @acindex{FUNC_LSTAT}
4774 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4775 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4777 @prindex @code{stat}
4779 @prindex @code{lstat}
4780 Determine whether @code{stat} or @code{lstat} have the bug that it
4781 succeeds when given the zero-length file name as argument. The @code{stat}
4782 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4785 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4786 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4789 These macros are obsolescent, as no current systems have the bug.
4790 New programs need not use these macros.
4793 @defmac AC_FUNC_STRCOLL
4794 @acindex{FUNC_STRCOLL}
4795 @cvindex HAVE_STRCOLL
4797 @prindex @code{strcoll}
4798 If the @code{strcoll} function exists and works correctly, define
4799 @code{HAVE_STRCOLL}. This does a bit more than
4800 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4801 definitions of @code{strcoll} that should not be used.
4804 @defmac AC_FUNC_STRERROR_R
4805 @acindex{FUNC_STRERROR_R}
4806 @cvindex HAVE_STRERROR_R
4807 @cvindex HAVE_DECL_STRERROR_R
4808 @cvindex STRERROR_R_CHAR_P
4809 @c @fuindex strerror_r
4810 @prindex @code{strerror_r}
4811 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4812 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4813 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4814 returns an @code{int} error number. The Thread-Safe Functions option of
4815 Posix requires @code{strerror_r} to return @code{int}, but
4816 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4817 Library) return a @code{char *} value that is not necessarily equal to
4818 the buffer argument.
4821 @defmac AC_FUNC_STRFTIME
4822 @acindex{FUNC_STRFTIME}
4823 @cvindex HAVE_STRFTIME
4824 @c @fuindex strftime
4825 @prindex @code{strftime}
4826 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4827 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4829 This macro is obsolescent, as no current systems require the @file{intl}
4830 library for @code{strftime}. New programs need not use this macro.
4833 @defmac AC_FUNC_STRTOD
4834 @acindex{FUNC_STRTOD}
4837 @prindex @code{strtod}
4838 If the @code{strtod} function does not exist or doesn't work correctly,
4839 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4840 because @file{strtod.c} is likely to need @samp{pow}, set the output
4841 variable @code{POW_LIB} to the extra library needed.
4844 @defmac AC_FUNC_STRTOLD
4845 @acindex{FUNC_STRTOLD}
4846 @prindex @code{strtold}
4847 If the @code{strtold} function exists and conforms to C99, define
4848 @code{HAVE_STRTOLD}.
4851 @defmac AC_FUNC_STRNLEN
4852 @acindex{FUNC_STRNLEN}
4853 @cvindex HAVE_STRNLEN
4855 @prindex @code{strnlen}
4856 If the @code{strnlen} function is not available, or is buggy (like the one
4857 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4860 @defmac AC_FUNC_UTIME_NULL
4861 @acindex{FUNC_UTIME_NULL}
4862 @cvindex HAVE_UTIME_NULL
4864 @prindex @code{utime}
4865 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4866 the present, define @code{HAVE_UTIME_NULL}.
4868 This macro is obsolescent, as all current systems have a @code{utime}
4869 that behaves this way. New programs need not use this macro.
4872 @defmac AC_FUNC_VPRINTF
4873 @acindex{FUNC_VPRINTF}
4874 @cvindex HAVE_VPRINTF
4875 @cvindex HAVE_DOPRNT
4877 @prindex @code{vprintf}
4878 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4879 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4880 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4881 are also available.)
4883 This macro is obsolescent, as all current systems have @code{vprintf}.
4884 New programs need not use this macro.
4887 @defmac AC_REPLACE_FNMATCH
4888 @acindex{REPLACE_FNMATCH}
4890 @prindex @code{fnmatch}
4891 @hdrindex{fnmatch.h}
4892 If the @code{fnmatch} function does not conform to Posix (see
4893 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4895 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4896 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4897 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4898 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4899 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4900 included in place of the system @code{<fnmatch.h>}.
4902 This macro is obsolescent, as it assumes the use of particular source
4903 files. New programs should use Gnulib's @code{fnmatch-posix} module,
4904 which provides this macro along with the source files. @xref{Gnulib}.
4909 @node Generic Functions
4910 @subsection Generic Function Checks
4912 These macros are used to find functions not covered by the ``particular''
4913 test macros. If the functions might be in libraries other than the
4914 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4915 If you need to check the behavior of a function as well as find out
4916 whether it is present, you have to write your own test for
4917 it (@pxref{Writing Tests}).
4919 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4920 @acindex{CHECK_FUNC}
4921 If C function @var{function} is available, run shell commands
4922 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4923 want to define a symbol if the function is available, consider using
4924 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4925 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4926 standardized than C++. (@pxref{Language Choice}, for more information
4927 about selecting the language for checks.)
4930 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4931 @acindex{CHECK_FUNCS}
4932 @cvindex HAVE_@var{function}
4933 For each @var{function} enumerated in the blank-or-newline-separated argument
4934 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4935 If @var{action-if-found} is given, it is additional shell code to
4936 execute when one of the functions is found. You can give it a value of
4937 @samp{break} to break out of the loop on the first match. If
4938 @var{action-if-not-found} is given, it is executed when one of the
4939 functions is not found.
4942 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4943 @acindex{CHECK_FUNCS_ONCE}
4944 @cvindex HAVE_@var{function}
4945 For each @var{function} enumerated in the blank-or-newline-separated argument
4946 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4947 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
4948 checking code at most once, so that @command{configure} is smaller and
4949 faster; but the checks cannot be conditionalized and are always done once,
4950 early during the @command{configure} run.
4955 Autoconf follows a philosophy that was formed over the years by those
4956 who have struggled for portability: isolate the portability issues in
4957 specific files, and then program as if you were in a Posix
4958 environment. Some functions may be missing or unfixable, and your
4959 package must be ready to replace them.
4961 Suitable replacements for many such problem functions are available from
4962 Gnulib (@pxref{Gnulib}).
4964 @defmac AC_LIBOBJ (@var{function})
4967 Specify that @samp{@var{function}.c} must be included in the executables
4968 to replace a missing or broken implementation of @var{function}.
4970 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4971 variable @code{LIBOBJS} if it is not already in, and calls
4972 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4973 directly change @code{LIBOBJS}, since this is not traceable.
4976 @defmac AC_LIBSOURCE (@var{file})
4978 Specify that @var{file} might be needed to compile the project. If you
4979 need to know what files might be needed by a @file{configure.ac}, you
4980 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4982 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4983 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4984 that case, since shell variables cannot be traced statically, you must
4985 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4986 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4987 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4988 @code{"foo"} or @code{"bar"}, you should do:
4991 AC_LIBSOURCE([foo.c])
4992 AC_LIBSOURCE([bar.c])
4993 AC_LIBOBJ([$foo_or_bar])
4997 There is usually a way to avoid this, however, and you are encouraged to
4998 simply call @code{AC_LIBOBJ} with literal arguments.
5000 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5001 slightly different semantics: the old macro took the function name,
5002 e.g., @code{foo}, as its argument rather than the file name.
5005 @defmac AC_LIBSOURCES (@var{files})
5006 @acindex{LIBSOURCES}
5007 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5008 comma-separated M4 list. Thus, the above example might be rewritten:
5011 AC_LIBSOURCES([foo.c, bar.c])
5012 AC_LIBOBJ([$foo_or_bar])
5016 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5017 @acindex{CONFIG_LIBOBJ_DIR}
5018 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5019 @var{directory}, a name relative to the top level of the
5020 source tree. The replacement directory defaults to @file{.}, the top
5021 level directory, and the most typical value is @file{lib}, corresponding
5022 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5024 @command{configure} might need to know the replacement directory for the
5025 following reasons: (i) some checks use the replacement files, (ii) some
5026 macros bypass broken system headers by installing links to the
5027 replacement headers (iii) when used in conjunction with Automake,
5028 within each makefile, @var{directory} is used as a relative path
5029 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5030 @code{LTLIBOBJS}, etc.
5035 It is common to merely check for the existence of a function, and ask
5036 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5037 a convenient shorthand.
5039 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5040 @acindex{REPLACE_FUNCS}
5042 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5043 @var{action-if-not-found}. You can declare your replacement function by
5044 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5045 system has the function, it probably declares it in a header file you
5046 should be including, so you shouldn't redeclare it lest your declaration
5051 @section Header Files
5052 @cindex Header, checking
5054 The following macros check for the presence of certain C header files.
5055 If there is no macro specifically defined to check for a header file you need,
5056 and you don't need to check for any special properties of
5057 it, then you can use one of the general header-file check macros.
5060 * Header Portability:: Collected knowledge on common headers
5061 * Particular Headers:: Special handling to find certain headers
5062 * Generic Headers:: How to find other headers
5065 @node Header Portability
5066 @subsection Portability of Headers
5067 @cindex Portability of headers
5068 @cindex Header portability
5070 This section tries to collect knowledge about common headers, and the
5071 problems they cause. By definition, this list always requires
5072 additions. Please help us keeping it as complete as possible.
5076 @item @file{limits.h}
5077 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5078 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5079 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5082 @item @file{inttypes.h} vs.@: @file{stdint.h}
5083 @hdrindex{inttypes.h}
5085 The C99 standard says that @file{inttypes.h} includes
5086 @file{stdint.h}, so there's no need to include @file{stdint.h}
5087 separately in a standard environment. Some implementations have
5088 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5089 know of any implementation that has @file{stdint.h} but not
5092 @item @file{linux/irda.h}
5093 @hdrindex{linux/irda.h}
5094 It requires @file{linux/types.h} and @file{sys/socket.h}.
5096 @item @file{linux/random.h}
5097 @hdrindex{linux/random.h}
5098 It requires @file{linux/types.h}.
5100 @item @file{net/if.h}
5102 On Darwin, this file requires that @file{sys/socket.h} be included
5103 beforehand. One should run:
5106 AC_CHECK_HEADERS([sys/socket.h])
5107 AC_CHECK_HEADERS([net/if.h], [], [],
5110 # include <stdlib.h>
5111 # include <stddef.h>
5113 # ifdef HAVE_STDLIB_H
5114 # include <stdlib.h>
5117 #ifdef HAVE_SYS_SOCKET_H
5118 # include <sys/socket.h>
5123 @item @file{netinet/if_ether.h}
5124 @hdrindex{netinet/if_ether.h}
5125 On Darwin, this file requires that @file{stdio.h} and
5126 @file{sys/socket.h} be included beforehand. One should run:
5129 AC_CHECK_HEADERS([sys/socket.h])
5130 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5133 # include <stdlib.h>
5134 # include <stddef.h>
5136 # ifdef HAVE_STDLIB_H
5137 # include <stdlib.h>
5140 #ifdef HAVE_SYS_SOCKET_H
5141 # include <sys/socket.h>
5146 @item @file{stdint.h}
5147 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5149 @item @file{stdlib.h}
5151 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5153 @item @file{sys/mount.h}
5154 @hdrindex{sys/mount.h}
5155 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5156 @file{sys/params.h} is a prerequisite.
5158 @item @file{sys/ptem.h}
5159 @hdrindex{sys/ptem.h}
5160 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5162 @item @file{sys/socket.h}
5163 @hdrindex{sys/socket.h}
5164 On Darwin, @file{stdlib.h} is a prerequisite.
5166 @item @file{sys/ucred.h}
5167 @hdrindex{sys/ucred.h}
5168 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5170 @item @file{X11/extensions/scrnsaver.h}
5171 @hdrindex{X11/extensions/scrnsaver.h}
5172 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5173 so required that you might not even consider looking for it.
5176 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5177 [[#include <X11/Xlib.h>
5183 @node Particular Headers
5184 @subsection Particular Header Checks
5186 These macros check for particular system header files---whether they
5187 exist, and in some cases whether they declare certain symbols.
5189 @defmac AC_HEADER_ASSERT
5190 @acindex{HEADER_ASSERT}
5193 Check whether to enable assertions in the style of @file{assert.h}.
5194 Assertions are enabled by default, but the user can override this by
5195 invoking @command{configure} with the @option{--disable-assert} option.
5198 @defmac AC_HEADER_DIRENT
5199 @acindex{HEADER_DIRENT}
5200 @cvindex HAVE_DIRENT_H
5201 @cvindex HAVE_NDIR_H
5202 @cvindex HAVE_SYS_DIR_H
5203 @cvindex HAVE_SYS_NDIR_H
5205 @hdrindex{sys/ndir.h}
5206 @hdrindex{sys/dir.h}
5208 Check for the following header files. For the first one that is
5209 found and defines @samp{DIR}, define the listed C preprocessor macro:
5211 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5212 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5213 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5214 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5215 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5218 The directory-library declarations in your source code should look
5219 something like the following:
5223 #include <sys/types.h>
5224 #ifdef HAVE_DIRENT_H
5225 # include <dirent.h>
5226 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5228 # define dirent direct
5229 # define NAMLEN(dirent) ((dirent)->d_namlen)
5230 # ifdef HAVE_SYS_NDIR_H
5231 # include <sys/ndir.h>
5233 # ifdef HAVE_SYS_DIR_H
5234 # include <sys/dir.h>
5243 Using the above declarations, the program would declare variables to be
5244 of type @code{struct dirent}, not @code{struct direct}, and would access
5245 the length of a directory entry name by passing a pointer to a
5246 @code{struct dirent} to the @code{NAMLEN} macro.
5248 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5250 This macro is obsolescent, as all current systems with directory
5251 libraries have @code{<dirent.h>}. New programs need not use this macro.
5253 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5254 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5257 @defmac AC_HEADER_MAJOR
5258 @acindex{HEADER_MAJOR}
5259 @cvindex MAJOR_IN_MKDEV
5260 @cvindex MAJOR_IN_SYSMACROS
5261 @hdrindex{sys/mkdev.h}
5262 @hdrindex{sys/sysmacros.h}
5263 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5264 @code{makedev}, but @file{sys/mkdev.h} does, define
5265 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5266 @code{MAJOR_IN_SYSMACROS}.
5269 @defmac AC_HEADER_RESOLV
5270 @acindex{HEADER_RESOLV}
5271 @cvindex HAVE_RESOLV_H
5273 Checks for header @file{resolv.h}, checking for prerequisites first.
5274 To properly use @file{resolv.h}, your code should contain something like
5278 #ifdef HAVE_SYS_TYPES_H
5279 # include <sys/types.h>
5281 #ifdef HAVE_NETINET_IN_H
5282 # include <netinet/in.h> /* inet_ functions / structs */
5284 #ifdef HAVE_ARPA_NAMESER_H
5285 # include <arpa/nameser.h> /* DNS HEADER struct */
5294 @defmac AC_HEADER_STAT
5295 @acindex{HEADER_STAT}
5296 @cvindex STAT_MACROS_BROKEN
5297 @hdrindex{sys/stat.h}
5298 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5299 @file{sys/stat.h} do not work properly (returning false positives),
5300 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5301 Amdahl UTS and Motorola System V/88.
5303 This macro is obsolescent, as no current systems have the bug.
5304 New programs need not use this macro.
5307 @defmac AC_HEADER_STDBOOL
5308 @acindex{HEADER_STDBOOL}
5309 @cvindex HAVE_STDBOOL_H
5311 @hdrindex{stdbool.h}
5313 If @file{stdbool.h} exists and conforms to C99, define
5314 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5315 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5316 @file{system.h} could contain the following code:
5319 #ifdef HAVE_STDBOOL_H
5320 # include <stdbool.h>
5326 # define _Bool signed char
5332 # define __bool_true_false_are_defined 1
5336 Alternatively you can use the @samp{stdbool} package of Gnulib
5337 (@pxref{Gnulib}); it packages the above code into a replacement header
5338 and contains a few other bells and whistles.
5343 @defmac AC_HEADER_STDC
5344 @acindex{HEADER_STDC}
5345 @cvindex STDC_HEADERS
5351 Define @code{STDC_HEADERS} if the system has C header files
5352 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5353 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5354 @file{string.h}, and @file{float.h}; if the system has those, it
5355 probably has the rest of the C89 header files. This macro also
5356 checks whether @file{string.h} declares @code{memchr} (and thus
5357 presumably the other @code{mem} functions), whether @file{stdlib.h}
5358 declare @code{free} (and thus presumably @code{malloc} and other related
5359 functions), and whether the @file{ctype.h} macros work on characters
5360 with the high bit set, as the C standard requires.
5362 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5363 determine whether the system has conforming header files (and probably C
5366 This macro is obsolescent, as current systems have conforming header
5367 files. New programs need not use this macro.
5370 @hdrindex{strings.h}
5371 Nowadays @file{string.h} is part of the C standard and declares functions like
5372 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5373 @acronym{BSD} functions like @code{bcopy}; but
5374 historically, string functions were a major sticking point in this area.
5375 If you still want to worry about portability to ancient systems without
5376 standard headers, there is so much variation
5377 that it is probably easier to declare the functions you use than to
5378 figure out exactly what the system header files declare. Some ancient systems
5379 contained a mix of functions from the C standard and from @acronym{BSD};
5380 some were mostly standard but lacked @samp{memmove}; some defined the
5381 @acronym{BSD} functions as macros in @file{string.h} or
5382 @file{strings.h}; some had only the @acronym{BSD} functions but
5383 @file{string.h}; some declared the memory functions in @file{memory.h},
5384 some in @file{string.h}; etc. It is probably sufficient to check for
5385 one string function and one memory function; if the library had the
5386 standard versions of those then it probably had most of the others.
5387 If you put the following in @file{configure.ac}:
5390 # This example is obsolescent.
5391 # Nowadays you can omit these macro calls.
5393 AC_CHECK_FUNCS([strchr memcpy])
5397 then, in your code, you can use declarations like this:
5401 /* This example is obsolescent.
5402 Nowadays you can just #include <string.h>. */
5404 # include <string.h>
5406 # ifndef HAVE_STRCHR
5407 # define strchr index
5408 # define strrchr rindex
5410 char *strchr (), *strrchr ();
5411 # ifndef HAVE_MEMCPY
5412 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5413 # define memmove(d, s, n) bcopy ((s), (d), (n))
5420 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5421 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5422 suffice to port to ancient hosts; you must provide an implementation of
5423 each function. An easy
5424 way to incorporate your implementations only when needed (since the ones
5425 in system C libraries may be hand optimized) is to, taking @code{memchr}
5426 for example, put it in @file{memchr.c} and use
5427 @samp{AC_REPLACE_FUNCS([memchr])}.
5430 @defmac AC_HEADER_SYS_WAIT
5431 @acindex{HEADER_SYS_WAIT}
5432 @cvindex HAVE_SYS_WAIT_H
5433 @hdrindex{sys/wait.h}
5434 If @file{sys/wait.h} exists and is compatible with Posix, define
5435 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5436 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5437 of @code{int} to store a status value. If @file{sys/wait.h} is not
5438 Posix compatible, then instead of including it, define the
5439 Posix macros with their usual interpretations. Here is an
5444 #include <sys/types.h>
5445 #ifdef HAVE_SYS_WAIT_H
5446 # include <sys/wait.h>
5449 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5452 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5458 This macro is obsolescent, as current systems are compatible with Posix.
5459 New programs need not use this macro.
5462 @cvindex _POSIX_VERSION
5464 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5465 Posix systems. If there is no @file{unistd.h}, it is definitely
5466 not a Posix system. However, some non-Posix systems do
5467 have @file{unistd.h}.
5469 The way to check whether the system supports Posix is:
5473 #ifdef HAVE_UNISTD_H
5474 # include <sys/types.h>
5475 # include <unistd.h>
5478 #ifdef _POSIX_VERSION
5479 /* Code for Posix systems. */
5484 @defmac AC_HEADER_TIME
5485 @acindex{HEADER_TIME}
5486 @cvindex TIME_WITH_SYS_TIME
5488 @hdrindex{sys/time.h}
5489 If a program may include both @file{time.h} and @file{sys/time.h},
5490 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5491 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5492 protected against multiple inclusion, so programs could not explicitly
5493 include both files. This macro is useful in programs that use, for
5494 example, @code{struct timeval} as well as
5495 @code{struct tm}. It is best used in conjunction with
5496 @code{HAVE_SYS_TIME_H}, which can be checked for using
5497 @code{AC_CHECK_HEADERS([sys/time.h])}.
5501 #ifdef TIME_WITH_SYS_TIME
5502 # include <sys/time.h>
5505 # ifdef HAVE_SYS_TIME_H
5506 # include <sys/time.h>
5515 This macro is obsolescent, as current systems can include both files
5516 when they exist. New programs need not use this macro.
5520 @defmac AC_HEADER_TIOCGWINSZ
5521 @acindex{HEADER_TIOCGWINSZ}
5522 @cvindex GWINSZ_IN_SYS_IOCTL
5523 @hdrindex{sys/ioctl.h}
5524 @hdrindex{termios.h}
5525 @c FIXME: I need clarifications from Jim.
5526 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5527 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5528 found in @file{<termios.h>}.
5534 #ifdef HAVE_TERMIOS_H
5535 # include <termios.h>
5538 #ifdef GWINSZ_IN_SYS_IOCTL
5539 # include <sys/ioctl.h>
5545 @node Generic Headers
5546 @subsection Generic Header Checks
5548 These macros are used to find system header files not covered by the
5549 ``particular'' test macros. If you need to check the contents of a header
5550 as well as find out whether it is present, you have to write your own
5551 test for it (@pxref{Writing Tests}).
5553 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5554 @acindex{CHECK_HEADER}
5555 If the system header file @var{header-file} is compilable, execute shell
5556 commands @var{action-if-found}, otherwise execute
5557 @var{action-if-not-found}. If you just want to define a symbol if the
5558 header file is available, consider using @code{AC_CHECK_HEADERS}
5561 For compatibility issues with older versions of Autoconf, please read
5565 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5566 @acindex{CHECK_HEADERS}
5567 @cvindex HAVE_@var{header}
5568 For each given system header file @var{header-file} in the
5569 blank-separated argument list that exists, define
5570 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5571 is given, it is additional shell code to execute when one of the header
5572 files is found. You can give it a value of @samp{break} to break out of
5573 the loop on the first match. If @var{action-if-not-found} is given, it
5574 is executed when one of the header files is not found.
5576 For compatibility issues with older versions of Autoconf, please read
5580 Previous versions of Autoconf merely checked whether the header was
5581 accepted by the preprocessor. This was changed because the old test was
5582 inappropriate for typical uses. Headers are typically used to compile,
5583 not merely to preprocess, and the old behavior sometimes accepted
5584 headers that clashed at compile-time. If you need to check whether a
5585 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5586 (@pxref{Running the Preprocessor}).
5588 This scheme, which improves the robustness of the test, also requires
5589 that you make sure that headers that must be included before the
5590 @var{header-file} be part of the @var{includes}, (@pxref{Default
5591 Includes}). If looking for @file{bar.h}, which requires that
5592 @file{foo.h} be included before if it exists, we suggest the following
5596 AC_CHECK_HEADERS([foo.h])
5597 AC_CHECK_HEADERS([bar.h], [], [],
5604 The following variant generates smaller, faster @command{configure}
5605 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5607 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5608 @acindex{CHECK_HEADERS_ONCE}
5609 @cvindex HAVE_@var{header}
5610 For each given system header file @var{header-file} in the
5611 blank-separated argument list that exists, define
5612 @code{HAVE_@var{header-file}} (in all capitals).
5613 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5614 checking code at most once, so that @command{configure} is smaller and
5615 faster; but the checks cannot be conditionalized and are always done once,
5616 early during the @command{configure} run.
5620 @section Declarations
5621 @cindex Declaration, checking
5623 The following macros check for the declaration of variables and
5624 functions. If there is no macro specifically defined to check for a
5625 symbol you need, then you can use the general macros (@pxref{Generic
5626 Declarations}) or, for more complex tests, you may use
5627 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5630 * Particular Declarations:: Macros to check for certain declarations
5631 * Generic Declarations:: How to find other declarations
5634 @node Particular Declarations
5635 @subsection Particular Declaration Checks
5637 There are no specific macros for declarations.
5639 @node Generic Declarations
5640 @subsection Generic Declaration Checks
5642 These macros are used to find declarations not covered by the ``particular''
5645 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5646 @acindex{CHECK_DECL}
5647 If @var{symbol} (a function, variable, or constant) is not declared in
5648 @var{includes} and a declaration is needed, run the shell commands
5649 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5650 @var{includes} are specified, the default includes are used
5651 (@pxref{Default Includes}).
5653 This macro actually tests whether @var{symbol} is defined as a macro or
5654 can be used as an r-value, not whether it is really declared, because it
5655 is much safer to avoid
5656 introducing extra declarations when they are not needed.
5659 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5660 @acindex{CHECK_DECLS}
5661 @cvindex HAVE_DECL_@var{symbol}
5662 For each of the @var{symbols} (@emph{comma}-separated list), define
5663 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5664 @var{symbol} is declared, otherwise to @samp{0}. If
5665 @var{action-if-not-found} is given, it is additional shell code to
5666 execute when one of the function declarations is needed, otherwise
5667 @var{action-if-found} is executed.
5669 This macro uses an M4 list as first argument:
5671 AC_CHECK_DECLS([strdup])
5672 AC_CHECK_DECLS([strlen])
5673 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5676 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5677 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5678 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5679 @emph{sure} that the check was performed, use
5680 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5683 #if !HAVE_DECL_SYMBOL
5684 extern char *symbol;
5689 If the test may have not been performed, however, because it is safer
5690 @emph{not} to declare a symbol than to use a declaration that conflicts
5691 with the system's one, you should use:
5694 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5695 void *malloc (size_t *s);
5700 You fall into the second category only in extreme situations: either
5701 your files may be used without being configured, or they are used during
5702 the configuration. In most cases the traditional approach is enough.
5705 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5706 @acindex{CHECK_DECLS_ONCE}
5707 @cvindex HAVE_DECL_@var{symbol}
5708 For each of the @var{symbols} (@emph{comma}-separated list), define
5709 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5710 @var{symbol} is declared in the default include files, otherwise to
5711 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5712 generates the checking code at most once, so that @command{configure} is
5713 smaller and faster; but the checks cannot be conditionalized and are
5714 always done once, early during the @command{configure} run.
5720 @cindex Structure, checking
5722 The following macros check for the presence of certain members in C
5723 structures. If there is no macro specifically defined to check for a
5724 member you need, then you can use the general structure-member macros
5725 (@pxref{Generic Structures}) or, for more complex tests, you may use
5726 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5729 * Particular Structures:: Macros to check for certain structure members
5730 * Generic Structures:: How to find other structure members
5733 @node Particular Structures
5734 @subsection Particular Structure Checks
5736 The following macros check for certain structures or structure members.
5738 @defmac AC_STRUCT_DIRENT_D_INO
5739 @acindex{STRUCT_DIRENT_D_INO}
5740 @cvindex HAVE_STRUCT_DIRENT_D_INO
5741 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5742 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5743 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5745 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5746 @code{d_ino}, not whether its contents are always reliable.
5747 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5748 though current systems hide this detail from the user and never return
5749 zero @code{d_ino} values.
5750 Many current systems report an incorrect @code{d_ino} for a directory
5751 entry that is a mount point.
5754 @defmac AC_STRUCT_DIRENT_D_TYPE
5755 @acindex{STRUCT_DIRENT_D_TYPE}
5756 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5757 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5758 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5759 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5762 @defmac AC_STRUCT_ST_BLKSIZE
5763 @acindex{STRUCT_ST_BLKSIZE}
5764 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5765 @cvindex HAVE_ST_BLKSIZE
5766 If @code{struct stat} contains an @code{st_blksize} member, define
5767 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5768 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5769 the future. This macro is obsoleted, and should be replaced by
5772 AC_CHECK_MEMBERS([struct stat.st_blksize])
5776 @defmac AC_STRUCT_ST_BLOCKS
5777 @acindex{STRUCT_ST_BLOCKS}
5778 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5779 @cvindex HAVE_ST_BLOCKS
5781 If @code{struct stat} contains an @code{st_blocks} member, define
5782 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5783 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5784 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5788 @defmac AC_STRUCT_ST_RDEV
5789 @acindex{STRUCT_ST_RDEV}
5790 @cvindex HAVE_ST_RDEV
5791 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5792 If @code{struct stat} contains an @code{st_rdev} member, define
5793 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5794 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5795 in the future. Actually, even the new macro is obsolete and should be
5798 AC_CHECK_MEMBERS([struct stat.st_rdev])
5802 @defmac AC_STRUCT_TM
5804 @cvindex TM_IN_SYS_TIME
5806 @hdrindex{sys/time.h}
5807 If @file{time.h} does not define @code{struct tm}, define
5808 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5809 had better define @code{struct tm}.
5811 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5812 current systems. New programs need not use this macro.
5815 @defmac AC_STRUCT_TIMEZONE
5816 @acindex{STRUCT_TIMEZONE}
5817 @cvindex HAVE_TM_ZONE
5818 @cvindex HAVE_TZNAME
5819 Figure out how to get the current timezone. If @code{struct tm} has a
5820 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5821 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5822 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5823 define @code{HAVE_DECL_TZNAME}.
5826 @node Generic Structures
5827 @subsection Generic Structure Checks
5829 These macros are used to find structure members not covered by the
5830 ``particular'' test macros.
5832 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5833 @acindex{CHECK_MEMBER}
5834 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5835 If no @var{includes} are specified, the default includes are used
5836 (@pxref{Default Includes}).
5839 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5840 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5844 You can use this macro for submembers:
5847 AC_CHECK_MEMBER(struct top.middle.bot)
5851 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5852 @acindex{CHECK_MEMBERS}
5853 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5854 @var{members} using the previous macro. When @var{member} belongs to
5855 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5856 capitals, with spaces and dots replaced by underscores). If
5857 @var{action-if-found} is given, it is executed for each of the found
5858 members. If @var{action-if-not-found} is given, it is executed for each
5859 of the members that could not be found.
5861 This macro uses M4 lists:
5863 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5873 The following macros check for C types, either builtin or typedefs. If
5874 there is no macro specifically defined to check for a type you need, and
5875 you don't need to check for any special properties of it, then you can
5876 use a general type-check macro.
5879 * Particular Types:: Special handling to find certain types
5880 * Generic Types:: How to find other types
5883 @node Particular Types
5884 @subsection Particular Type Checks
5886 @hdrindex{sys/types.h}
5889 @hdrindex{inttypes.h}
5890 These macros check for particular C types in @file{sys/types.h},
5891 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5894 The Gnulib @code{stdint} module is an alternate way to define many of
5895 these symbols; it is useful if you prefer your code to assume a
5896 C99-or-better environment. @xref{Gnulib}.
5898 @defmac AC_TYPE_GETGROUPS
5899 @acindex{TYPE_GETGROUPS}
5900 @cvindex GETGROUPS_T
5901 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5902 is the base type of the array argument to @code{getgroups}.
5905 @defmac AC_TYPE_INT8_T
5906 @acindex{TYPE_INT8_T}
5907 @cvindex HAVE_INT8_T
5909 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5910 define @code{HAVE_INT8_T}. Otherwise, define @code{int8_t} to a signed
5911 integer type that is exactly 8 bits wide and that uses two's complement
5912 representation, if such a type exists.
5915 @defmac AC_TYPE_INT16_T
5916 @acindex{TYPE_INT16_T}
5917 @cvindex HAVE_INT16_T
5919 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5922 @defmac AC_TYPE_INT32_T
5923 @acindex{TYPE_INT32_T}
5924 @cvindex HAVE_INT32_T
5926 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5929 @defmac AC_TYPE_INT64_T
5930 @acindex{TYPE_INT64_T}
5931 @cvindex HAVE_INT64_T
5933 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5936 @defmac AC_TYPE_INTMAX_T
5937 @acindex{TYPE_INTMAX_T}
5938 @cvindex HAVE_INTMAX_T
5940 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5941 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
5942 widest signed integer type.
5945 @defmac AC_TYPE_INTPTR_T
5946 @acindex{TYPE_INTPTR_T}
5947 @cvindex HAVE_INTPTR_T
5949 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5950 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
5951 signed integer type wide enough to hold a pointer, if such a type
5955 @defmac AC_TYPE_LONG_DOUBLE
5956 @acindex{TYPE_LONG_DOUBLE}
5957 @cvindex HAVE_LONG_DOUBLE
5958 If the C compiler supports a working @code{long double} type, define
5959 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
5960 same range and precision as @code{double}.
5963 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5964 @acindex{TYPE_LONG_DOUBLE_WIDER}
5965 @cvindex HAVE_LONG_DOUBLE_WIDER
5966 If the C compiler supports a working @code{long double} type with more
5967 range or precision than the @code{double} type, define
5968 @code{HAVE_LONG_DOUBLE_WIDER}.
5971 @defmac AC_TYPE_LONG_LONG_INT
5972 @acindex{TYPE_LONG_LONG_INT}
5973 @cvindex HAVE_LONG_LONG_INT
5974 If the C compiler supports a working @code{long long int} type, define
5975 @code{HAVE_LONG_LONG_INT}.
5978 @defmac AC_TYPE_MBSTATE_T
5979 @acindex{TYPE_MBSTATE_T}
5982 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5983 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5984 @code{<wchar.h>} does not declare it.
5987 @defmac AC_TYPE_MODE_T
5988 @acindex{TYPE_MODE_T}
5990 Define @code{mode_t} to a suitable type, if standard headers do not
5994 @defmac AC_TYPE_OFF_T
5995 @acindex{TYPE_OFF_T}
5997 Define @code{off_t} to a suitable type, if standard headers do not
6001 @defmac AC_TYPE_PID_T
6002 @acindex{TYPE_PID_T}
6004 Define @code{pid_t} to a suitable type, if standard headers do not
6008 @defmac AC_TYPE_SIGNAL
6009 @acindex{TYPE_SIGNAL}
6012 If @file{signal.h} declares @code{signal} as returning a pointer to a
6013 function returning @code{void}, define @code{RETSIGTYPE} to be
6014 @code{void}; otherwise, define it to be @code{int}.
6016 Define signal handlers as returning type @code{RETSIGTYPE}:
6029 @defmac AC_TYPE_SIZE_T
6030 @acindex{TYPE_SIZE_T}
6032 Define @code{size_t} to a suitable type, if standard headers do not
6036 @defmac AC_TYPE_SSIZE_T
6037 @acindex{TYPE_SSIZE_T}
6039 Define @code{ssize_t} to a suitable type, if standard headers do not
6043 @defmac AC_TYPE_UID_T
6044 @acindex{TYPE_UID_T}
6047 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6048 headers do not define them.
6051 @defmac AC_TYPE_UINT8_T
6052 @acindex{TYPE_UINT8_T}
6053 @cvindex HAVE_UINT8_T
6055 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
6056 define @code{HAVE_UINT8_T}. Otherwise, define @code{uint8_t} to an
6057 unsigned integer type that is exactly 8 bits wide, if such a type
6061 @defmac AC_TYPE_UINT16_T
6062 @acindex{TYPE_UINT16_T}
6063 @cvindex HAVE_UINT16_T
6065 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
6068 @defmac AC_TYPE_UINT32_T
6069 @acindex{TYPE_UINT32_T}
6070 @cvindex HAVE_UINT32_T
6072 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
6075 @defmac AC_TYPE_UINT64_T
6076 @acindex{TYPE_UINT64_T}
6077 @cvindex HAVE_UINT64_T
6079 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
6082 @defmac AC_TYPE_UINTMAX_T
6083 @acindex{TYPE_UINTMAX_T}
6084 @cvindex HAVE_UINTMAX_T
6086 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6087 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6088 widest unsigned integer type.
6091 @defmac AC_TYPE_UINTPTR_T
6092 @acindex{TYPE_UINTPTR_T}
6093 @cvindex HAVE_UINTPTR_T
6095 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6096 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6097 unsigned integer type wide enough to hold a pointer, if such a type
6101 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6102 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6103 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6104 If the C compiler supports a working @code{unsigned long long int} type,
6105 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6109 @subsection Generic Type Checks
6111 These macros are used to check for types not covered by the ``particular''
6114 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6115 @acindex{CHECK_TYPE}
6116 Check whether @var{type} is defined. It may be a compiler builtin type
6117 or defined by the @var{includes} (@pxref{Default Includes}).
6121 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6122 @acindex{CHECK_TYPES}
6123 For each @var{type} of the @var{types} that is defined, define
6124 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
6125 specified, the default includes are used (@pxref{Default Includes}). If
6126 @var{action-if-found} is given, it is additional shell code to execute
6127 when one of the types is found. If @var{action-if-not-found} is given,
6128 it is executed when one of the types is not found.
6130 This macro uses M4 lists:
6132 AC_CHECK_TYPES([ptrdiff_t])
6133 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6138 Autoconf, up to 2.13, used to provide to another version of
6139 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6140 compatibility, a simple heuristic, quite safe but not totally, is
6141 implemented. In case of doubt, read the documentation of the former
6142 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6145 @node Compilers and Preprocessors
6146 @section Compilers and Preprocessors
6148 @cindex Preprocessors
6151 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6152 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6153 the output of the compiler, typically to the empty string if
6154 Posix and @samp{.exe} if a @acronym{DOS} variant.
6157 They also define the output variable @code{OBJEXT} based on the
6158 output of the compiler, after @file{.c} files have been excluded, typically
6159 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6161 If the compiler being used does not produce executables, the tests fail. If
6162 the executables can't be run, and cross-compilation is not enabled, they
6163 fail too. @xref{Manual Configuration}, for more on support for cross
6167 * Specific Compiler Characteristics:: Some portability issues
6168 * Generic Compiler Characteristics:: Language independent tests and features
6169 * C Compiler:: Checking its characteristics
6170 * C++ Compiler:: Likewise
6171 * Objective C Compiler:: Likewise
6172 * Erlang Compiler and Interpreter:: Likewise
6173 * Fortran Compiler:: Likewise
6176 @node Specific Compiler Characteristics
6177 @subsection Specific Compiler Characteristics
6179 Some compilers exhibit different behaviors.
6182 @item Static/Dynamic Expressions
6183 Autoconf relies on a trick to extract one bit of information from the C
6184 compiler: using negative array sizes. For instance the following
6185 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6189 static int test_array[sizeof (int) == 4 ? 1 : -1];
6193 To our knowledge, there is a single compiler that does not support this
6194 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6195 @acronym{HP-UX} 11.00.
6196 They incorrectly reject the above program with the diagnostic
6197 ``Variable-length arrays cannot have static storage.''
6198 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6199 not from the @code{? 1 : -1}, and
6200 Autoconf works around this problem by casting @code{sizeof (int)} to
6201 @code{long int} before comparing it.
6204 @node Generic Compiler Characteristics
6205 @subsection Generic Compiler Characteristics
6207 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
6208 @acindex{CHECK_SIZEOF}
6209 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
6210 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6211 of 0. If no @var{includes} are specified, the default includes are used
6212 (@pxref{Default Includes}).
6214 This macro now works even when cross-compiling. The @var{unused}
6215 argument was used when cross-compiling.
6217 For example, the call
6220 AC_CHECK_SIZEOF([int *])
6224 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6227 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6228 @acindex{CHECK_ALIGNOF}
6229 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6230 alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6231 of 0. If no @var{includes} are specified, the default includes are used
6232 (@pxref{Default Includes}).
6235 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
6236 @acindex{COMPUTE_INT}
6237 Store into the shell variable @var{var} the value of the integer
6238 @var{expression}. The
6239 value should fit in an initializer in a C variable of type @code{signed
6240 long}. To support cross compilation (in which case, the macro only works on
6241 hosts that use twos-complement arithmetic), it should be possible to evaluate
6242 the expression at compile-time. If no @var{includes} are specified, the default
6243 includes are used (@pxref{Default Includes}).
6245 Execute @var{action-if-fails} if the value cannot be determined correctly.
6248 @defmac AC_LANG_WERROR
6249 @acindex{LANG_WERROR}
6250 Normally Autoconf ignores warnings generated by the compiler, linker, and
6251 preprocessor. If this macro is used, warnings count as fatal
6252 errors for the current language. This macro is useful when the
6253 results of configuration are used where warnings are unacceptable; for
6254 instance, if parts of a program are built with the @acronym{GCC}
6256 option. If the whole program is built using @option{-Werror} it is
6257 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6262 @subsection C Compiler Characteristics
6264 The following macros provide ways to find and exercise a C Compiler.
6265 There are a few constructs that ought to be avoided, but do not deserve
6266 being checked for, since they can easily be worked around.
6269 @item Don't use lines containing solitary backslashes
6270 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6271 @acronym{HP-UX} 10.20,
6272 11.00, and 11i). When given the following source:
6277 * A comment with backslash-newlines in it. %@{ %@} *\
6281 " A string with backslash-newlines in it %@{ %@} \\
6283 char apostrophe = '\\
6291 the compiler incorrectly fails with the diagnostics ``Non-terminating
6292 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6293 Removing the lines with solitary backslashes solves the problem.
6295 @item Don't compile several files at once if output matters to you
6296 Some compilers, such as @acronym{HP}'s, report names of files being
6297 compiled when given more than one file operand. For instance:
6306 This can cause problems if you observe the output of the compiler to
6307 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6308 b.o} solves the issue.
6310 @item Don't rely on @code{#error} failing
6311 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6312 simply emits a diagnostic and continues, exiting successfully. So,
6313 instead of an error directive like @code{#error "Unsupported word size"}
6314 it is more portable to use an invalid directive like @code{#Unsupported
6315 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6316 OK, since installers with inadequate compilers like @sc{irix} can simply
6317 examine these compilers' diagnostic output.
6319 @item Don't rely on correct @code{#line} support
6320 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6321 diagnoses @code{#line} directives whose line
6322 numbers are greater than 32767. Nothing in Posix
6323 makes this invalid. That is why Autoconf stopped issuing
6324 @code{#line} directives.
6327 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6331 Determine a C compiler to use. If @code{CC} is not already set in the
6332 environment, check for @code{gcc} and @code{cc}, then for other C
6333 compilers. Set output variable @code{CC} to the name of the compiler
6336 This macro may, however, be invoked with an optional first argument
6337 which, if specified, must be a blank-separated list of C compilers to
6338 search for. This just gives the user an opportunity to specify an
6339 alternative search list for the C compiler. For example, if you didn't
6340 like the default order, then you could invoke @code{AC_PROG_CC} like
6344 AC_PROG_CC([gcc cl cc])
6347 If the C compiler does not handle function prototypes correctly by
6348 default, try to add an option to output variable @code{CC} to make it
6349 so. This macro tries various options that select standard-conformance
6350 modes on various systems.
6352 After calling this macro you can check whether the C compiler has been
6353 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6355 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6356 @code{AC_C_PROTOTYPES} below.
6358 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6359 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6360 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6361 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6365 @defmac AC_PROG_CC_C_O
6366 @acindex{PROG_CC_C_O}
6367 @cvindex NO_MINUS_C_MINUS_O
6368 If the C compiler does not accept the @option{-c} and @option{-o} options
6369 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6370 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6371 the first @code{cc} in the path. The test fails if one fails. This
6372 macro was created for @acronym{GNU} Make to choose the default C compilation
6380 Set output variable @code{CPP} to a command that runs the
6381 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6382 It is only portable to run @code{CPP} on files with a @file{.c}
6385 Some preprocessors don't indicate missing include files by the error
6386 status. For such preprocessors an internal variable is set that causes
6387 other macros to check the standard error from the preprocessor and
6388 consider the test failed if any warnings have been reported.
6389 For most preprocessors, though, warnings do not cause include-file
6390 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6393 @defmac AC_PROG_CPP_WERROR
6394 @acindex{PROG_CPP_WERROR}
6396 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6397 preprocessor as errors even if the preprocessor exit status indicates
6398 success. This is useful for avoiding headers that generate mandatory
6399 warnings, such as deprecation notices.
6403 The following macros check for C compiler or machine architecture
6404 features. To check for characteristics not listed here, use
6405 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6406 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6408 @defmac AC_PROG_CC_STDC
6409 @acindex{PROG_CC_STDC}
6410 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6411 C99), try to add an option to output variable @code{CC} to make it work.
6412 If the compiler does not support C99, fall back to supporting
6413 @acronym{ANSI} C89 (@acronym{ISO} C90).
6415 After calling this macro you can check whether the C compiler has been
6416 set to accept Standard C; if not, the shell variable
6417 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6420 @defmac AC_PROG_CC_C89
6421 @acindex{PROG_CC_C89}
6422 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6423 default, try to add an option to output variable @code{CC} to make it
6424 so. This macro tries various options that select @acronym{ANSI} C89 on
6425 some system or another. It considers the compiler to be in
6426 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6428 After calling this macro you can check whether the C compiler has been
6429 set to accept @acronym{ANSI} C89; if not, the shell variable
6430 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6432 This macro is called automatically by @code{AC_PROG_CC}.
6435 @defmac AC_PROG_CC_C99
6436 @acindex{PROG_CC_C99}
6437 If the C compiler is not in C99 mode by default, try to add an
6438 option to output variable @code{CC} to make it so. This macro tries
6439 various options that select C99 on some system or another. It
6440 considers the compiler to be in C99 mode if it handles @code{_Bool},
6441 @code{//} comments, flexible array members, @code{inline}, signed and
6442 unsigned @code{long long int}, mixed code and declarations, named
6443 initialization of structs,
6444 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6445 in @code{for} loops, and variable length arrays.
6447 After calling this macro you can check whether the C compiler has been
6448 set to accept C99; if not, the shell variable
6449 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6452 @defmac AC_C_BACKSLASH_A
6453 @acindex{HAVE_C_BACKSLASH_A}
6454 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6457 This macro is obsolescent, as current C compilers understand @samp{\a}.
6458 New programs need not use this macro.
6461 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown}, @ovar{action-if-universal})
6462 @acindex{C_BIGENDIAN}
6463 @cvindex WORDS_BIGENDIAN
6465 If words are stored with the most significant byte first (like Motorola
6466 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6467 the least significant byte first (like Intel and VAX CPUs), execute
6468 @var{action-if-false}.
6470 This macro runs a test-case if endianness cannot be determined from the
6471 system header files. When cross-compiling, the test-case is not run but
6472 grep'ed for some magic values. @var{action-if-unknown} is executed if
6473 the latter case fails to determine the byte sex of the host system.
6475 In some cases a single run of a compiler can generate code for multiple
6476 architectures. This can happen, for example, when generating Mac OS X
6477 universal binary files, which work on both PowerPC and Intel
6478 architectures. In this case, the different variants might be for
6479 different architectures whose endiannesses differ. If
6480 @command{configure} detects this, it executes @var{action-if-universal}
6481 instead of @var{action-if-unknown}.
6483 The default for @var{action-if-true} is to define
6484 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6485 nothing. The default for @var{action-if-unknown} is to
6486 abort configure and tell the installer how to bypass this test.
6487 And finally, the default for @var{action-if-universal} is to define
6488 @samp{WORDS_BIGENDIAN} or not, depending on the architecture that the
6489 code is being generated for.
6491 If you use this macro without specifying @var{action-if-universal}, you
6492 should also use @code{AC_CONFIG_HEADERS}; otherwise
6493 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
6500 If the C compiler does not fully support the @code{const} keyword,
6501 define @code{const} to be empty. Some C compilers that do
6502 not define @code{__STDC__} do support @code{const}; some compilers that
6503 define @code{__STDC__} do not completely support @code{const}. Programs
6504 can simply use @code{const} as if every C compiler supported it; for
6505 those that don't, the makefile or configuration header file
6506 defines it as empty.
6508 Occasionally installers use a C++ compiler to compile C code, typically
6509 because they lack a C compiler. This causes problems with @code{const},
6510 because C and C++ treat @code{const} differently. For example:
6517 is valid in C but not in C++. These differences unfortunately cannot be
6518 papered over by defining @code{const} to be empty.
6520 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6521 as this generally yields better results in practice. However, using a
6522 C++ compiler to compile C code is not recommended or supported, and
6523 installers who run into trouble in this area should get a C compiler
6524 like @acronym{GCC} to compile their C code.
6526 This macro is obsolescent, as current C compilers support @code{const}.
6527 New programs need not use this macro.
6530 @defmac AC_C_RESTRICT
6531 @acindex{C_RESTRICT}
6533 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6534 If it recognizes only a variant spelling (@code{__restrict},
6535 @code{__restrict__}, or @code{_Restrict}), then define
6536 @code{restrict} to that.
6537 Otherwise, define @code{restrict} to be empty.
6538 Thus, programs may simply use @code{restrict} as if every C compiler
6539 supported it; for those that do not, the makefile
6540 or configuration header defines it away.
6542 Although support in C++ for the @code{restrict} keyword is not
6543 required, several C++ compilers do accept the keyword.
6544 This macro works for them, too.
6547 @defmac AC_C_VOLATILE
6548 @acindex{C_VOLATILE}
6550 If the C compiler does not understand the keyword @code{volatile},
6551 define @code{volatile} to be empty. Programs can simply use
6552 @code{volatile} as if every C compiler supported it; for those that do
6553 not, the makefile or configuration header defines it as
6556 If the correctness of your program depends on the semantics of
6557 @code{volatile}, simply defining it to be empty does, in a sense, break
6558 your code. However, given that the compiler does not support
6559 @code{volatile}, you are at its mercy anyway. At least your
6560 program compiles, when it wouldn't before.
6561 @xref{Volatile Objects}, for more about @code{volatile}.
6563 In general, the @code{volatile} keyword is a standard C feature, so
6564 you might expect that @code{volatile} is available only when
6565 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6566 support volatile, but does not define @code{__STDC__}.
6568 This macro is obsolescent, as current C compilers support @code{volatile}.
6569 New programs need not use this macro.
6575 If the C compiler supports the keyword @code{inline}, do nothing.
6576 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6577 if it accepts one of those, otherwise define @code{inline} to be empty.
6580 @defmac AC_C_CHAR_UNSIGNED
6581 @acindex{C_CHAR_UNSIGNED}
6582 @cvindex __CHAR_UNSIGNED__
6583 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6584 unless the C compiler predefines it.
6587 @defmac AC_C_STRINGIZE
6588 @acindex{C_STRINGIZE}
6589 @cvindex HAVE_STRINGIZE
6590 If the C preprocessor supports the stringizing operator, define
6591 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6592 found in macros such as this:
6598 This macro is obsolescent, as current C compilers support the
6599 stringizing operator. New programs need not use this macro.
6602 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6603 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6604 @cvindex FLEXIBLE_ARRAY_MEMBER
6605 If the C compiler supports flexible array members, define
6606 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6607 That way, a declaration like this:
6613 double val[FLEXIBLE_ARRAY_MEMBER];
6618 will let applications use the ``struct hack'' even with compilers that
6619 do not support flexible array members. To allocate and use such an
6620 object, you can use code like this:
6624 size_t n = compute_value_count ();
6626 malloc (offsetof (struct s, val)
6627 + n * sizeof (double));
6629 for (i = 0; i < n; i++)
6630 p->val[i] = compute_value (i);
6634 @defmac AC_C_VARARRAYS
6635 @acindex{C_VARARRAYS}
6636 @cvindex HAVE_C_VARARRAYS
6637 If the C compiler supports variable-length arrays, define
6638 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
6639 storage duration whose length is determined at run time, when the array
6645 @cvindex HAVE_TYPEOF
6647 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6649 through a different spelling of the keyword (e.g., @code{__typeof__}),
6650 define @code{HAVE_TYPEOF}. If the support is available only through a
6651 different spelling, define @code{typeof} to that spelling.
6654 @defmac AC_C_PROTOTYPES
6655 @acindex{C_PROTOTYPES}
6657 @cvindex __PROTOTYPES
6659 If function prototypes are understood by the compiler (as determined by
6660 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6661 Defining @code{__PROTOTYPES} is for the benefit of
6662 header files that cannot use macros that infringe on user name space.
6664 This macro is obsolescent, as current C compilers support prototypes.
6665 New programs need not use this macro.
6668 @defmac AC_PROG_GCC_TRADITIONAL
6669 @acindex{PROG_GCC_TRADITIONAL}
6671 Add @option{-traditional} to output variable @code{CC} if using the
6672 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6673 @option{-traditional}. That usually happens when the fixed header files
6674 have not been installed on an old system.
6676 This macro is obsolescent, since current versions of the @acronym{GNU} C
6677 compiler fix the header files automatically when installed.
6682 @subsection C++ Compiler Characteristics
6685 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6689 Determine a C++ compiler to use. Check whether the environment variable
6690 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6691 variable @code{CXX} to its value.
6693 Otherwise, if the macro is invoked without an argument, then search for
6694 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6695 then other names). If none of those checks succeed, then as a last
6696 resort set @code{CXX} to @code{g++}.
6698 This macro may, however, be invoked with an optional first argument
6699 which, if specified, must be a blank-separated list of C++ compilers to
6700 search for. This just gives the user an opportunity to specify an
6701 alternative search list for the C++ compiler. For example, if you
6702 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6706 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6709 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6710 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6711 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6712 systems where G++ does not accept @option{-g}), or @option{-g} for other
6716 @defmac AC_PROG_CXXCPP
6717 @acindex{PROG_CXXCPP}
6719 Set output variable @code{CXXCPP} to a command that runs the C++
6720 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6721 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6722 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6724 Some preprocessors don't indicate missing include files by the error
6725 status. For such preprocessors an internal variable is set that causes
6726 other macros to check the standard error from the preprocessor and
6727 consider the test failed if any warnings have been reported. However,
6728 it is not known whether such broken preprocessors exist for C++.
6731 @defmac AC_PROG_CXX_C_O
6732 @acindex{PROG_CXX_C_O}
6733 @cvindex CXX_NO_MINUS_C_MINUS_O
6734 Test whether the C++ compiler accepts the options @option{-c} and
6735 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6740 @node Objective C Compiler
6741 @subsection Objective C Compiler Characteristics
6744 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6748 Determine an Objective C compiler to use. If @code{OBJC} is not already
6749 set in the environment, check for Objective C compilers. Set output
6750 variable @code{OBJC} to the name of the compiler found.
6752 This macro may, however, be invoked with an optional first argument
6753 which, if specified, must be a blank-separated list of Objective C compilers to
6754 search for. This just gives the user an opportunity to specify an
6755 alternative search list for the Objective C compiler. For example, if you
6756 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6760 AC_PROG_OBJC([gcc objcc objc])
6763 If using the @acronym{GNU} Objective C compiler, set shell variable
6764 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6765 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6766 compiler (@option{-O2} on systems where @command{gcc} does not accept
6767 @option{-g}), or @option{-g} for other compilers.
6770 @defmac AC_PROG_OBJCPP
6771 @acindex{PROG_OBJCPP}
6773 Set output variable @code{OBJCPP} to a command that runs the Objective C
6774 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6778 @node Erlang Compiler and Interpreter
6779 @subsection Erlang Compiler and Interpreter Characteristics
6782 Autoconf defines the following macros for determining paths to the essential
6783 Erlang/OTP programs:
6785 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6786 @acindex{ERLANG_PATH_ERLC}
6789 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6790 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6791 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6792 is not set in the environment, set it to an empty value.
6794 The two optional arguments have the same meaning as the two last arguments of
6795 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
6796 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6800 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6804 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6805 @acindex{ERLANG_NEED_ERLC}
6806 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6807 error message and exits the @command{configure} script if the @command{erlc}
6808 program is not found.
6811 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6812 @acindex{ERLANG_PATH_ERL}
6814 Determine an Erlang interpreter to use. If @code{ERL} is not already set in the
6815 environment, check for @command{erl}. Set output variable @code{ERL} to the
6816 complete path of the interpreter command found.
6818 The two optional arguments have the same meaning as the two last arguments of
6819 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
6820 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6824 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6828 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6829 @acindex{ERLANG_NEED_ERL}
6830 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6831 error message and exits the @command{configure} script if the @command{erl}
6832 program is not found.
6836 @node Fortran Compiler
6837 @subsection Fortran Compiler Characteristics
6841 The Autoconf Fortran support is divided into two categories: legacy
6842 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6843 The former are intended for traditional Fortran 77 code, and have output
6844 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6845 are for newer programs that can (or must) compile under the newer
6846 Fortran standards, and have output variables like @code{FC},
6847 @code{FCFLAGS}, and @code{FCLIBS}.
6849 Except for two new macros @code{AC_FC_SRCEXT} and
6850 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6851 behave almost identically, and so they are documented together in this
6855 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6859 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6860 set in the environment, then check for @code{g77} and @code{f77}, and
6861 then some other names. Set the output variable @code{F77} to the name
6862 of the compiler found.
6864 This macro may, however, be invoked with an optional first argument
6865 which, if specified, must be a blank-separated list of Fortran 77
6866 compilers to search for. This just gives the user an opportunity to
6867 specify an alternative search list for the Fortran 77 compiler. For
6868 example, if you didn't like the default order, then you could invoke
6869 @code{AC_PROG_F77} like this:
6872 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6875 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6876 set the shell variable @code{G77} to @samp{yes}.
6877 If the output variable @code{FFLAGS} was not already set in the
6878 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6879 where @code{g77} does not accept @option{-g}). Otherwise, set
6880 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6883 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6887 Determine a Fortran compiler to use. If @code{FC} is not already set in
6888 the environment, then @code{dialect} is a hint to indicate what Fortran
6889 dialect to search for; the default is to search for the newest available
6890 dialect. Set the output variable @code{FC} to the name of the compiler
6893 By default, newer dialects are preferred over older dialects, but if
6894 @code{dialect} is specified then older dialects are preferred starting
6895 with the specified dialect. @code{dialect} can currently be one of
6896 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6897 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6898 and no attempt is made to guarantee that a particular language standard
6899 is actually supported. Thus, it is preferable that you avoid the
6900 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6901 the latest Fortran standard.
6903 This macro may, alternatively, be invoked with an optional first argument
6904 which, if specified, must be a blank-separated list of Fortran
6905 compilers to search for, just as in @code{AC_PROG_F77}.
6907 If the output variable @code{FCFLAGS} was not already set in the
6908 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6909 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6910 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6913 @defmac AC_PROG_F77_C_O
6914 @defmacx AC_PROG_FC_C_O
6915 @acindex{PROG_F77_C_O}
6916 @acindex{PROG_FC_C_O}
6917 @cvindex F77_NO_MINUS_C_MINUS_O
6918 @cvindex FC_NO_MINUS_C_MINUS_O
6919 Test whether the Fortran compiler accepts the options @option{-c} and
6920 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6921 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6924 The following macros check for Fortran compiler characteristics.
6925 To check for characteristics not listed here, use
6926 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6927 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6928 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6929 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6932 @defmac AC_F77_LIBRARY_LDFLAGS
6933 @defmacx AC_FC_LIBRARY_LDFLAGS
6934 @acindex{F77_LIBRARY_LDFLAGS}
6936 @acindex{FC_LIBRARY_LDFLAGS}
6938 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6939 @dfn{Fortran intrinsic and runtime libraries} that are required to
6940 successfully link a Fortran program or shared library. The output
6941 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6942 should be included after @code{LIBS} when linking).
6944 This macro is intended to be used in those situations when it is
6945 necessary to mix, e.g., C++ and Fortran source code in a single
6946 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6947 automake, @acronym{GNU} Automake}).
6949 For example, if object files from a C++ and Fortran compiler must be
6950 linked together, then the C++ compiler/linker must be used for linking
6951 (since special C++-ish things need to happen at link time like calling
6952 global constructors, instantiating templates, enabling exception
6955 However, the Fortran intrinsic and runtime libraries must be linked in
6956 as well, but the C++ compiler/linker doesn't know by default how to add
6957 these Fortran 77 libraries. Hence, this macro was created to determine
6958 these Fortran libraries.
6960 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6961 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
6962 link C/C++ with Fortran; see below.
6965 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6966 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6967 @acindex{F77_DUMMY_MAIN}
6968 @cvindex F77_DUMMY_MAIN
6969 With many compilers, the Fortran libraries detected by
6970 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6971 their own @code{main} entry function that initializes things like
6972 Fortran I/O, and which then calls a user-provided entry function named
6973 (say) @code{MAIN__} to run the user's program. The
6974 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6975 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6978 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6979 one prefers to provide one's own @code{main} and skip the Fortran
6980 library initializations. In this case, however, one may still need to
6981 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6982 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6983 detects whether any such routine is @emph{required} for linking, and
6984 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6985 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6986 was found, and @code{none} when no such dummy main is needed.
6988 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6989 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6990 @emph{if} it is required. @var{action-if-not-found} defaults to
6991 exiting with an error.
6993 In order to link with Fortran routines, the user's C/C++ program should
6994 then include the following code to define the dummy main if it is
6998 #ifdef F77_DUMMY_MAIN
7002 int F77_DUMMY_MAIN() @{ return 1; @}
7006 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7008 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7009 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7010 explicitly unless one wants to change the default actions.
7019 As discussed above, many Fortran libraries allow you to provide an entry
7020 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7021 is then called by a @code{main} function in the Fortran libraries that
7022 initializes things like Fortran I/O@. The
7023 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7024 @emph{possible} to utilize such an alternate main function, and defines
7025 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7026 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7027 simply defined to @code{main}.)
7029 Thus, when calling Fortran routines from C that perform things like I/O,
7030 one should use this macro and name the "main" function
7031 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
7034 @defmac AC_F77_WRAPPERS
7035 @defmacx AC_FC_WRAPPERS
7036 @acindex{F77_WRAPPERS}
7039 @acindex{FC_WRAPPERS}
7042 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7043 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7044 mangle the names of C/C++ identifiers, and identifiers with underscores,
7045 respectively, so that they match the name-mangling scheme used by the
7048 Fortran is case-insensitive, and in order to achieve this the Fortran
7049 compiler converts all identifiers into a canonical case and format. To
7050 call a Fortran subroutine from C or to write a C function that is
7051 callable from Fortran, the C program must explicitly use identifiers in
7052 the format expected by the Fortran compiler. In order to do this, one
7053 simply wraps all C identifiers in one of the macros provided by
7054 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7055 you have the following Fortran 77 subroutine:
7058 subroutine foobar (x, y)
7059 double precision x, y
7065 You would then declare its prototype in C or C++ as:
7068 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7070 extern "C" /* prevent C++ name mangling */
7072 void FOOBAR_F77(double *x, double *y);
7075 Note that we pass both the lowercase and uppercase versions of the
7076 function name to @code{F77_FUNC} so that it can select the right one.
7077 Note also that all parameters to Fortran 77 routines are passed as
7078 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7081 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7083 Although Autoconf tries to be intelligent about detecting the
7084 name-mangling scheme of the Fortran compiler, there may be Fortran
7085 compilers that it doesn't support yet. In this case, the above code
7086 generates a compile-time error, but some other behavior
7087 (e.g., disabling Fortran-related features) can be induced by checking
7088 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7090 Now, to call that routine from a C program, we would do something like:
7094 double x = 2.7183, y;
7095 FOOBAR_F77 (&x, &y);
7099 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7100 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7101 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7102 because some Fortran compilers mangle names differently if they contain
7106 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7107 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7110 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7111 hold the mangled version @var{name} according to the rules of the
7112 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7113 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7114 supplied, the shell variable is simply @var{name}. The purpose of
7115 this macro is to give the caller a way to access the name-mangling
7116 information other than through the C preprocessor as above, for example,
7117 to call Fortran routines from some language other than C/C++.
7120 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7122 By default, the @code{FC} macros perform their tests using a @file{.f}
7123 extension for source-code files. Some compilers, however, only enable
7124 newer language features for appropriately named files, e.g., Fortran 90
7125 features only for @file{.f90} files. On the other hand, some other
7126 compilers expect all source files to end in @file{.f} and require
7127 special flags to support other file name extensions. The
7128 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7130 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7131 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7132 contain the dot). If any special compiler flags are needed for this, it
7133 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7134 extension and these flags are then used for all subsequent @code{FC} tests
7135 (until @code{AC_FC_SRCEXT} is called again).
7137 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7138 @file{.f90} extension in future tests, and it would set a
7139 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7140 to compile such files.
7142 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7143 @code{FCFLAGS}, for two reasons based on the limitations of some
7144 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7145 time, so files with different extensions must be compiled separately.
7146 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7147 the source-code file name when compiling. So, continuing the example
7148 above, you might compile a @file{foo.f90} file in your makefile with the
7153 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7156 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7157 extension, it calls @var{action-if-success} (defaults to nothing). If
7158 it fails, and cannot find a way to make the @code{FC} compiler accept such
7159 files, it calls @var{action-if-failure} (defaults to exiting with an
7164 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7165 @acindex{FC_FREEFORM}
7167 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7168 (@code{$FC}) allows free-format source code (as opposed to the older
7169 fixed-format style from Fortran 77). If necessary, it may add some
7170 additional flags to @code{FCFLAGS}.
7172 This macro is most important if you are using the default @file{.f}
7173 extension, since many compilers interpret this extension as indicating
7174 fixed-format source unless an additional flag is supplied. If you
7175 specify a different extension with @code{AC_FC_SRCEXT}, such as
7176 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7177 succeeds without modifying @code{FCFLAGS}.
7179 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7180 calls @var{action-if-success} (defaults to nothing). If it fails, it
7181 calls @var{action-if-failure} (defaults to exiting with an error
7185 @node System Services
7186 @section System Services
7188 The following macros check for operating system services or capabilities.
7193 @cindex X Window System
7194 Try to locate the X Window System include files and libraries. If the
7195 user gave the command line options @option{--x-includes=@var{dir}} and
7196 @option{--x-libraries=@var{dir}}, use those directories.
7198 If either or both were not given, get the missing values by running
7199 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7200 environment variable) on a trivial @file{Imakefile} and examining the
7201 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7202 disables this method.
7204 If this method fails to find the X Window System, @command{configure}
7205 looks for the files in several directories where they often reside.
7206 If either method is successful, set the shell variables
7207 @code{x_includes} and @code{x_libraries} to their locations, unless they
7208 are in directories the compiler searches by default.
7210 If both methods fail, or the user gave the command line option
7211 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7212 otherwise set it to the empty string.
7215 @defmac AC_PATH_XTRA
7219 @ovindex X_EXTRA_LIBS
7221 @cvindex X_DISPLAY_MISSING
7222 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7223 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7224 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7227 This macro also checks for special libraries that some systems need in
7228 order to compile X programs. It adds any that the system needs to
7229 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7230 libraries that need to be linked with before @option{-lX11}, and adds
7231 any found to the output variable @code{X_PRE_LIBS}.
7233 @c This is an incomplete kludge. Make a real way to do it.
7234 @c If you need to check for other X functions or libraries yourself, then
7235 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7236 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7239 @defmac AC_SYS_INTERPRETER
7240 @acindex{SYS_INTERPRETER}
7241 Check whether the system supports starting scripts with a line of the
7242 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7243 After running this macro, shell code in @file{configure.ac} can check
7244 the shell variable @code{interpval}; it is set to @samp{yes}
7245 if the system supports @samp{#!}, @samp{no} if not.
7248 @defmac AC_SYS_LARGEFILE
7249 @acindex{SYS_LARGEFILE}
7250 @cvindex _FILE_OFFSET_BITS
7251 @cvindex _LARGE_FILES
7253 @cindex Large file support
7256 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7257 large-file support}. On some hosts, one must use special compiler
7258 options to build programs that can access large files. Append any such
7259 options to the output variable @code{CC}. Define
7260 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7262 Large-file support can be disabled by configuring with the
7263 @option{--disable-largefile} option.
7265 If you use this macro, check that your program works even when
7266 @code{off_t} is wider than @code{long int}, since this is common when
7267 large-file support is enabled. For example, it is not correct to print
7268 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7271 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7272 replace their C counterparts @code{fseek} and @code{ftell} that do not
7273 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7274 prototypes available when using them and large-file support is
7278 @defmac AC_SYS_LONG_FILE_NAMES
7279 @acindex{SYS_LONG_FILE_NAMES}
7280 @cvindex HAVE_LONG_FILE_NAMES
7281 If the system supports file names longer than 14 characters, define
7282 @code{HAVE_LONG_FILE_NAMES}.
7285 @defmac AC_SYS_POSIX_TERMIOS
7286 @acindex{SYS_POSIX_TERMIOS}
7287 @cindex Posix termios headers
7288 @cindex termios Posix headers
7289 Check to see if the Posix termios headers and functions are available on the
7290 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7291 @samp{yes}. If not, set the variable to @samp{no}.
7294 @node Posix Variants
7295 @section Posix Variants
7297 The following macros check for certain operating systems that need
7298 special treatment for some programs, due to exceptional oddities in
7299 their header files or libraries. These macros are warts; they will be
7300 replaced by a more systematic approach, based on the functions they make
7301 available or the environments they provide.
7305 @cvindex _ALL_SOURCE
7306 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7307 Allows the use of some @acronym{BSD}
7308 functions. Should be called before any macros that run the C compiler.
7311 @defmac AC_GNU_SOURCE
7312 @acindex{GNU_SOURCE}
7313 @cvindex _GNU_SOURCE
7314 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7315 Allows the use of some @acronym{GNU} functions. Should be called
7316 before any macros that run the C compiler.
7319 @defmac AC_ISC_POSIX
7322 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7323 variable @code{LIBS} if necessary for Posix facilities. Call this
7324 after @code{AC_PROG_CC} and before any other macros that use Posix
7327 This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun
7328 dropped support for it on 2006-07-23. New programs need not use this
7335 @cvindex _POSIX_SOURCE
7336 @cvindex _POSIX_1_SOURCE
7337 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7338 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
7339 facilities. Should be called before any macros that run the C compiler.
7342 @defmac AC_USE_SYSTEM_EXTENSIONS
7343 @acindex{USE_SYSTEM_EXTENSIONS}
7344 @cvindex _ALL_SOURCE
7345 @cvindex _GNU_SOURCE
7347 @cvindex _POSIX_1_SOURCE
7348 @cvindex _POSIX_PTHREAD_SEMANTICS
7349 @cvindex _POSIX_SOURCE
7350 @cvindex _TANDEM_SOURCE
7351 @cvindex __EXTENSIONS__
7352 If possible, enable extensions to Posix on hosts that normally disable
7353 the extensions, typically due to standards-conformance namespace issues.
7354 This may involve defining @code{__EXTENSIONS__} and
7355 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.
7356 It also defines @code{_TANDEM_SOURCE} for the @acronym{HP} NonStop platform.
7357 This macro also has the combined effects of @code{AC_GNU_SOURCE},
7358 @code{AC_AIX}, and @code{AC_MINIX}.
7362 @node Erlang Libraries
7363 @section Erlang Libraries
7364 @cindex Erlang, Library, checking
7366 The following macros check for an installation of Erlang/OTP, and for the
7367 presence of certain Erlang libraries. All those macros require the
7368 configuration of an Erlang interpreter and an Erlang compiler
7369 (@pxref{Erlang Compiler and Interpreter}).
7371 @defmac AC_ERLANG_SUBST_ROOT_DIR
7372 @acindex{ERLANG_SUBST_ROOT_DIR}
7373 @ovindex ERLANG_ROOT_DIR
7375 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7376 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7377 function). The result of this test is cached if caching is enabled when running
7378 @command{configure}.
7381 @defmac AC_ERLANG_SUBST_LIB_DIR
7382 @acindex{ERLANG_SUBST_LIB_DIR}
7383 @ovindex ERLANG_LIB_DIR
7385 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7386 directory of Erlang/OTP (as returned by Erlang's
7387 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7388 Erlang/OTP library. The result of this test is cached if caching is enabled
7389 when running @command{configure}.
7392 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7393 @acindex{ERLANG_CHECK_LIB}
7394 @ovindex ERLANG_LIB_DIR_@var{library}
7395 @ovindex ERLANG_LIB_VER_@var{library}
7397 Test whether the Erlang/OTP library @var{library} is installed by
7398 calling Erlang's @code{code:lib_dir/1} function. The result of this
7399 test is cached if caching is enabled when running @command{configure}.
7400 @var{action-if-found} is a list of shell commands to run if the library
7401 is installed; @var{action-if-not-found} is a list of shell commands to
7402 run if it is not. Additionally, if the library is installed, the output
7403 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7404 library installation directory, and the output variable
7405 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7406 part of the subdirectory name, if it is in the standard form
7407 (@code{@var{library}-@var{version}}). If the directory name does not
7408 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7409 empty string. If the library is not installed,
7410 @samp{ERLANG_LIB_DIR_@var{library}} and
7411 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
7412 example, to check if library @code{stdlib} is installed:
7415 AC_ERLANG_CHECK_LIB([stdlib],
7416 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7417 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7418 [AC_MSG_ERROR([stdlib was not found!])])
7422 In addition to the above macros, which test installed Erlang libraries, the
7423 following macros determine the paths to the directories into which newly built
7424 Erlang libraries are to be installed:
7426 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7427 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7428 @ovindex ERLANG_INSTALL_LIB_DIR
7430 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7431 which every built Erlang library should be installed in a separate subdirectory.
7432 If this variable is not set in the environment when @command{configure} runs,
7433 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7434 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7437 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7438 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7439 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7441 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7442 directory into which the built Erlang library @var{library} version
7443 @var{version} should be installed. If this variable is not set in the
7444 environment when @command{configure} runs, its default value is
7445 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7446 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7447 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7454 @c ========================================================= Writing Tests
7457 @chapter Writing Tests
7459 If the existing feature tests don't do something you need, you have to
7460 write new ones. These macros are the building blocks. They provide
7461 ways for other macros to check whether various kinds of features are
7462 available and report the results.
7464 This chapter contains some suggestions and some of the reasons why the
7465 existing tests are written the way they are. You can also learn a lot
7466 about how to write Autoconf tests by looking at the existing ones. If
7467 something goes wrong in one or more of the Autoconf tests, this
7468 information can help you understand the assumptions behind them, which
7469 might help you figure out how to best solve the problem.
7471 These macros check the output of the compiler system of the current
7472 language (@pxref{Language Choice}). They do not cache the results of
7473 their tests for future use (@pxref{Caching Results}), because they don't
7474 know enough about the information they are checking for to generate a
7475 cache variable name. They also do not print any messages, for the same
7476 reason. The checks for particular kinds of features call these macros
7477 and do cache their results and print messages about what they're
7480 When you write a feature test that could be applicable to more than one
7481 software package, the best thing to do is encapsulate it in a new macro.
7482 @xref{Writing Autoconf Macros}, for how to do that.
7485 * Language Choice:: Selecting which language to use for testing
7486 * Writing Test Programs:: Forging source files for compilers
7487 * Running the Preprocessor:: Detecting preprocessor symbols
7488 * Running the Compiler:: Detecting language or header features
7489 * Running the Linker:: Detecting library features
7490 * Runtime:: Testing for runtime features
7491 * Systemology:: A zoology of operating systems
7492 * Multiple Cases:: Tests for several possible values
7495 @node Language Choice
7496 @section Language Choice
7499 Autoconf-generated @command{configure} scripts check for the C compiler and
7500 its features by default. Packages that use other programming languages
7501 (maybe more than one, e.g., C and C++) need to test features of the
7502 compilers for the respective languages. The following macros determine
7503 which programming language is used in the subsequent tests in
7504 @file{configure.ac}.
7506 @defmac AC_LANG (@var{language})
7507 Do compilation tests using the compiler, preprocessor, and file
7508 extensions for the specified @var{language}.
7510 Supported languages are:
7514 Do compilation tests using @code{CC} and @code{CPP} and use extension
7515 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7516 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7519 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7520 extension @file{.C} for test programs. Use compilation flags:
7521 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
7522 @code{CXXFLAGS} with @code{CXX}.
7525 Do compilation tests using @code{F77} and use extension @file{.f} for
7526 test programs. Use compilation flags: @code{FFLAGS}.
7529 Do compilation tests using @code{FC} and use extension @file{.f} (or
7530 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7531 compilation flags: @code{FCFLAGS}.
7537 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7538 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7541 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
7542 extension @file{.m} for test programs. Use compilation flags:
7543 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7544 @code{OBJCFLAGS} with @code{OBJC}.
7548 @defmac AC_LANG_PUSH (@var{language})
7550 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7551 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7552 in macros that need to temporarily switch to a particular language.
7555 @defmac AC_LANG_POP (@ovar{language})
7557 Select the language that is saved on the top of the stack, as set by
7558 @code{AC_LANG_PUSH}, and remove it from the stack.
7560 If given, @var{language} specifies the language we just @emph{quit}. It
7561 is a good idea to specify it when it's known (which should be the
7562 case@dots{}), since Autoconf detects inconsistencies.
7565 AC_LANG_PUSH([Fortran 77])
7566 # Perform some tests on Fortran 77.
7568 AC_LANG_POP([Fortran 77])
7572 @defmac AC_LANG_ASSERT (@var{language})
7573 @acindex{LANG_ASSERT} Check statically that the current language is
7574 @var{language}. You should use this in your language specific macros
7575 to avoid that they be called with an inappropriate language.
7577 This macro runs only at @command{autoconf} time, and incurs no cost at
7578 @command{configure} time. Sadly enough and because Autoconf is a two
7579 layer language @footnote{Because M4 is not aware of Sh code,
7580 especially conditionals, some optimizations that look nice statically
7581 may produce incorrect results at runtime.}, the macros
7582 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7583 therefore as much as possible you ought to avoid using them to wrap
7584 your code, rather, require from the user to run the macro with a
7585 correct current language, and check it with @code{AC_LANG_ASSERT}.
7586 And anyway, that may help the user understand she is running a Fortran
7587 macro while expecting a result about her Fortran 77 compiler@dots{}
7591 @defmac AC_REQUIRE_CPP
7592 @acindex{REQUIRE_CPP}
7593 Ensure that whichever preprocessor would currently be used for tests has
7594 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7595 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7596 depending on which language is current.
7600 @node Writing Test Programs
7601 @section Writing Test Programs
7603 Autoconf tests follow a common scheme: feed some program with some
7604 input, and most of the time, feed a compiler with some source file.
7605 This section is dedicated to these source samples.
7608 * Guidelines:: General rules for writing test programs
7609 * Test Functions:: Avoiding pitfalls in test programs
7610 * Generating Sources:: Source program boilerplate
7614 @subsection Guidelines for Test Programs
7616 The most important rule to follow when writing testing samples is:
7618 @center @emph{Look for realism.}
7620 This motto means that testing samples must be written with the same
7621 strictness as real programs are written. In particular, you should
7622 avoid ``shortcuts'' and simplifications.
7624 Don't just play with the preprocessor if you want to prepare a
7625 compilation. For instance, using @command{cpp} to check whether a header is
7626 functional might let your @command{configure} accept a header which
7627 causes some @emph{compiler} error. Do not hesitate to check a header with
7628 other headers included before, especially required headers.
7630 Make sure the symbols you use are properly defined, i.e., refrain for
7631 simply declaring a function yourself instead of including the proper
7634 Test programs should not write to standard output. They
7635 should exit with status 0 if the test succeeds, and with status 1
7636 otherwise, so that success
7637 can be distinguished easily from a core dump or other failure;
7638 segmentation violations and other failures produce a nonzero exit
7639 status. Unless you arrange for @code{exit} to be declared, test
7640 programs should @code{return}, not @code{exit}, from @code{main},
7641 because on many systems @code{exit} is not declared by default.
7643 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7644 preprocessor macros defined by tests that have already run. For
7645 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7646 @file{configure.ac} you can have a test program that includes
7647 @file{stdbool.h} conditionally:
7651 #ifdef HAVE_STDBOOL_H
7652 # include <stdbool.h>
7657 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7658 work with any standard C compiler. Some developers prefer @code{#if}
7659 because it is easier to read, while others prefer @code{#ifdef} because
7660 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7661 @option{-Wundef} option.
7663 If a test program needs to use or create a data file, give it a name
7664 that starts with @file{conftest}, such as @file{conftest.data}. The
7665 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7666 after running test programs and if the script is interrupted.
7668 @node Test Functions
7669 @subsection Test Functions
7671 These days it's safe to assume support for function prototypes
7672 (introduced in C89).
7674 Functions that test programs declare should also be conditionalized for
7675 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7676 include any header files containing clashing prototypes.
7682 void *valloc (size_t);
7685 If a test program calls a function with invalid parameters (just to see
7686 whether it exists), organize the program to ensure that it never invokes
7687 that function. You can do this by calling it in another function that is
7688 never invoked. You can't do it by putting it after a call to
7689 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7691 and optimizes out any code that follows it in the same block.
7693 If you include any header files, be sure to call the functions
7694 relevant to them with the correct number of arguments, even if they are
7695 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7697 has internal prototypes for several functions that it automatically
7698 inlines; for example, @code{memcpy}. To avoid errors when checking for
7699 them, either pass them the correct number of arguments or redeclare them
7700 with a different return type (such as @code{char}).
7703 @node Generating Sources
7704 @subsection Generating Sources
7706 Autoconf provides a set of macros that can be used to generate test
7707 source files. They are written to be language generic, i.e., they
7708 actually depend on the current language (@pxref{Language Choice}) to
7709 ``format'' the output properly.
7712 @defmac AC_LANG_CONFTEST (@var{source})
7713 @acindex{LANG_CONFTEST}
7714 Save the @var{source} text in the current test source file:
7715 @file{conftest.@var{extension}} where the @var{extension} depends on the
7718 Note that the @var{source} is evaluated exactly once, like regular
7719 Autoconf macro arguments, and therefore (i) you may pass a macro
7720 invocation, (ii) if not, be sure to double quote if needed.
7723 @defmac AC_LANG_SOURCE (@var{source})
7724 @acindex{LANG_SOURCE}
7725 Expands into the @var{source}, with the definition of
7726 all the @code{AC_DEFINE} performed so far.
7729 For instance executing (observe the double quotation!):
7732 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7733 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7734 [Greetings string.])
7737 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7738 gcc -E -dD -o - conftest.c
7748 #define PACKAGE_NAME "Hello"
7749 #define PACKAGE_TARNAME "hello"
7750 #define PACKAGE_VERSION "1.0"
7751 #define PACKAGE_STRING "Hello 1.0"
7752 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7753 #define HELLO_WORLD "Hello, World\n"
7755 const char hw[] = "Hello, World\n";
7758 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7759 are not automatically translated into constants in the source code by this
7762 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7763 @acindex{LANG_PROGRAM}
7764 Expands into a source file which consists of the @var{prologue}, and
7765 then @var{body} as body of the main function (e.g., @code{main} in
7766 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7773 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7774 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7775 [Greetings string.])
7777 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7778 [[fputs (hw, stdout);]])])
7779 gcc -E -dD -o - conftest.c
7789 #define PACKAGE_NAME "Hello"
7790 #define PACKAGE_TARNAME "hello"
7791 #define PACKAGE_VERSION "1.0"
7792 #define PACKAGE_STRING "Hello 1.0"
7793 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7794 #define HELLO_WORLD "Hello, World\n"
7796 const char hw[] = "Hello, World\n";
7806 In Erlang tests, the created source file is that of an Erlang module called
7807 @code{conftest} (@file{conftest.erl}). This module defines and exports at least
7808 one @code{start/0} function, which is called to perform the test. The
7809 @var{prologue} is optional code that is inserted between the module header and
7810 the @code{start/0} function definition. @var{body} is the body of the
7811 @code{start/0} function without the final period (@pxref{Runtime}, about
7812 constraints on this function's behavior).
7817 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7820 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7821 [[io:format("~s~n", [?HELLO_WORLD])]])])
7831 -define(HELLO_WORLD, "Hello, world!").
7833 io:format("~s~n", [?HELLO_WORLD])
7837 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7839 Expands into a source file which consists of the @var{prologue}, and
7840 then a call to the @var{function} as body of the main function (e.g.,
7841 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
7842 of the latter are available.
7844 This function will probably be replaced in the future by a version
7845 which would enable specifying the arguments. The use of this macro is
7846 not encouraged, as it violates strongly the typing system.
7848 This macro cannot be used for Erlang tests.
7851 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7852 @acindex{LANG_FUNC_LINK_TRY}
7853 Expands into a source file which uses the @var{function} in the body of
7854 the main function (e.g., @code{main} in C). Since it uses
7855 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7857 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7858 It is considered to be severely broken, and in the future will be
7859 removed in favor of actual function calls (with properly typed
7862 This macro cannot be used for Erlang tests.
7865 @node Running the Preprocessor
7866 @section Running the Preprocessor
7868 Sometimes one might need to run the preprocessor on some source file.
7869 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7870 your project, not merely run the preprocessor on it; therefore you
7871 certainly want to run the compiler, not the preprocessor. Resist the
7872 temptation of following the easiest path.
7874 Nevertheless, if you need to run the preprocessor, then use
7875 @code{AC_PREPROC_IFELSE}.
7877 The macros described in this section cannot be used for tests in Erlang or
7878 Fortran, since those languages require no preprocessor.
7880 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7881 @acindex{PREPROC_IFELSE}
7882 Run the preprocessor of the current language (@pxref{Language Choice})
7883 on the @var{input}, run the shell commands @var{action-if-true} on
7884 success, @var{action-if-false} otherwise. The @var{input} can be made
7885 by @code{AC_LANG_PROGRAM} and friends.
7887 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7888 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7891 It is customary to report unexpected failures with
7892 @code{AC_MSG_FAILURE}.
7898 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7899 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7900 [Greetings string.])
7902 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7903 [[fputs (hw, stdout);]])],
7904 [AC_MSG_RESULT([OK])],
7905 [AC_MSG_FAILURE([unexpected preprocessor failure])])
7912 checking for gcc... gcc
7913 checking for C compiler default output file name... a.out
7914 checking whether the C compiler works... yes
7915 checking whether we are cross compiling... no
7916 checking for suffix of executables...
7917 checking for suffix of object files... o
7918 checking whether we are using the GNU C compiler... yes
7919 checking whether gcc accepts -g... yes
7920 checking for gcc option to accept ISO C89... none needed
7921 checking how to run the C preprocessor... gcc -E
7927 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7928 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7929 it impossible to use it to elaborate sources. You are encouraged to
7930 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7931 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7932 to run the @emph{preprocessor} and not the compiler?
7934 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7935 @acindex{EGREP_HEADER}
7936 If the output of running the preprocessor on the system header file
7937 @var{header-file} matches the extended regular expression
7938 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7939 execute @var{action-if-not-found}.
7942 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7944 @var{program} is the text of a C or C++ program, on which shell
7945 variable, back quote, and backslash substitutions are performed. If the
7946 output of running the preprocessor on @var{program} matches the
7947 extended regular expression @var{pattern}, execute shell commands
7948 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7953 @node Running the Compiler
7954 @section Running the Compiler
7956 To check for a syntax feature of the current language's (@pxref{Language
7957 Choice}) compiler, such as whether it recognizes a certain keyword, or
7958 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7959 to compile a small program that uses that feature.
7961 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7962 @acindex{COMPILE_IFELSE}
7963 Run the compiler and compilation flags of the current language
7964 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7965 @var{action-if-true} on success, @var{action-if-false} otherwise. The
7966 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7968 It is customary to report unexpected failures with
7969 @code{AC_MSG_FAILURE}. This macro does not try to link; use
7970 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7975 For tests in Erlang, the @var{input} must be the source code of a module named
7976 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7977 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
7978 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7979 that the Erlang module has the right name.
7981 @node Running the Linker
7982 @section Running the Linker
7984 To check for a library, a function, or a global variable, Autoconf
7985 @command{configure} scripts try to compile and link a small program that
7986 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
7987 @code{ar} on the C library to try to figure out which functions are
7988 available. Trying to link with the function is usually a more reliable
7989 approach because it avoids dealing with the variations in the options
7990 and output formats of @code{nm} and @code{ar} and in the location of the
7991 standard libraries. It also allows configuring for cross-compilation or
7992 checking a function's runtime behavior if needed. On the other hand,
7993 it can be slower than scanning the libraries once, but accuracy is more
7994 important than speed.
7996 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7997 functions and global variables. It is also used by @code{AC_CHECK_LIB}
7998 to check for libraries (@pxref{Libraries}), by adding the library being
7999 checked for to @code{LIBS} temporarily and trying to link a small
8003 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
8004 @acindex{LINK_IFELSE}
8005 Run the compiler (and compilation flags) and the linker of the current
8006 language (@pxref{Language Choice}) on the @var{input}, run the shell
8007 commands @var{action-if-true} on success, @var{action-if-false}
8008 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
8011 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8012 current compilation flags.
8014 It is customary to report unexpected failures with
8015 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
8016 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8019 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8020 programs are interpreted and do not require linking.
8025 @section Checking Runtime Behavior
8027 Sometimes you need to find out how a system performs at runtime, such
8028 as whether a given function has a certain capability or bug. If you
8029 can, make such checks when your program runs instead of when it is
8030 configured. You can check for things like the machine's endianness when
8031 your program initializes itself.
8033 If you really need to test for a runtime behavior while configuring,
8034 you can write a test program to determine the result, and compile and
8035 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
8036 possible, because this prevents people from configuring your package for
8039 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8040 @acindex{RUN_IFELSE}
8041 If @var{program} compiles and links successfully and returns an exit
8042 status of 0 when executed, run shell commands @var{action-if-true}.
8043 Otherwise, run shell commands @var{action-if-false}.
8045 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8046 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8047 compilation flags of the current language (@pxref{Language Choice}).
8049 If the compiler being used does not produce executables that run on the
8050 system where @command{configure} is being run, then the test program is
8051 not run. If the optional shell commands @var{action-if-cross-compiling}
8052 are given, they are run instead. Otherwise, @command{configure} prints
8053 an error message and exits.
8055 In the @var{action-if-false} section, the failing exit status is
8056 available in the shell variable @samp{$?}. This exit status might be
8057 that of a failed compilation, or it might be that of a failed program
8060 It is customary to report unexpected failures with
8061 @code{AC_MSG_FAILURE}.
8064 Try to provide a pessimistic default value to use when cross-compiling
8065 makes runtime tests impossible. You do this by passing the optional
8066 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
8067 warning message when creating @command{configure} each time it
8068 encounters a call to @code{AC_RUN_IFELSE} with no
8069 @var{action-if-cross-compiling} argument given. You may ignore the
8070 warning, though users cannot configure your package for
8071 cross-compiling. A few of the macros distributed with Autoconf produce
8072 this warning message.
8074 To configure for cross-compiling you can also choose a value for those
8075 parameters based on the canonical system name (@pxref{Manual
8076 Configuration}). Alternatively, set up a test results cache file with
8077 the correct values for the host system (@pxref{Caching Results}).
8079 @ovindex cross_compiling
8080 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8081 in other macros, including a few of the ones that come with Autoconf,
8082 you can test whether the shell variable @code{cross_compiling} is set to
8083 @samp{yes}, and then use an alternate method to get the results instead
8084 of calling the macros.
8086 A C or C++ runtime test should be portable.
8087 @xref{Portable C and C++}.
8089 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8090 function: the given status code is used to determine the success of the test
8091 (status is @code{0}) or its failure (status is different than @code{0}), as
8092 explained above. It must be noted that data output through the standard output
8093 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8094 Therefore, if a test must output configuration information, it is recommended
8095 to create and to output data into the temporary file named @file{conftest.out},
8096 using the functions of module @code{file}. The @code{conftest.out} file is
8097 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8098 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8101 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8105 [AC_LANG_PROGRAM([], [dnl
8106 file:write_file("conftest.out", code:lib_dir()),
8108 [echo "code:lib_dir() returned: `cat conftest.out`"],
8109 [AC_MSG_FAILURE([test Erlang program execution failed])])
8114 @section Systemology
8117 This section aims at presenting some systems and pointers to
8118 documentation. It may help you addressing particular problems reported
8121 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8122 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8125 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8126 contains a table correlating the features of various Posix-conforming
8127 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8128 simplified diagram of how many Unix systems were derived from each
8131 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8132 provides some variants of traditional implementations of Unix utilities.
8137 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8138 case-preserving, but case insensitive. This can cause nasty problems,
8139 since for instance the installation attempt for a package having an
8140 @file{INSTALL} file can result in @samp{make install} report that
8141 nothing was to be done!
8143 That's all dependent on whether the file system is a UFS (case
8144 sensitive) or HFS+ (case preserving). By default Apple wants you to
8145 install the OS on HFS+. Unfortunately, there are some pieces of
8146 software which really need to be built on UFS@. We may want to rebuild
8147 Darwin to have both UFS and HFS+ available (and put the /local/build
8150 @item @acronym{QNX} 4.25
8151 @cindex @acronym{QNX} 4.25
8152 @c FIXME: Please, if you feel like writing something more precise,
8153 @c it'd be great. In particular, I can't understand the difference with
8155 @acronym{QNX} is a realtime operating system running on Intel architecture
8156 meant to be scalable from the small embedded systems to the hundred
8157 processor super-computer. It claims to be Posix certified. More
8158 information is available on the
8159 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8163 @uref{http://h30097.www3.hp.com/@/docs/,
8164 Documentation of several versions of Tru64} is available in different
8167 @item Unix version 7
8168 @cindex Unix version 7
8170 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8171 time-sharing system'' but we use the more-common name ``Unix version 7''.
8172 Documentation is available in the
8173 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8174 Previous versions of Unix are called ``Unix version 6'', etc., but
8175 they were not as widely used.
8179 @node Multiple Cases
8180 @section Multiple Cases
8182 Some operations are accomplished in several possible ways, depending on
8183 the OS variant. Checking for them essentially requires a ``case
8184 statement''. Autoconf does not directly provide one; however, it is
8185 easy to simulate by using a shell variable to keep track of whether a
8186 way to perform the operation has been found yet.
8188 Here is an example that uses the shell variable @code{fstype} to keep
8189 track of whether the remaining cases need to be checked.
8193 AC_MSG_CHECKING([how to get file system type])
8195 # The order of these tests is important.
8196 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8197 #include <sys/fstyp.h>]])],
8198 [AC_DEFINE([FSTYPE_STATVFS], [1],
8199 [Define if statvfs exists.])
8201 if test $fstype = no; then
8202 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8203 #include <sys/fstyp.h>]])],
8204 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8205 [Define if USG statfs.])
8208 if test $fstype = no; then
8209 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8210 #include <sys/vmount.h>]])]),
8211 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8212 [Define if AIX statfs.])
8215 # (more cases omitted here)
8216 AC_MSG_RESULT([$fstype])
8220 @c ====================================================== Results of Tests.
8223 @chapter Results of Tests
8225 Once @command{configure} has determined whether a feature exists, what can
8226 it do to record that information? There are four sorts of things it can
8227 do: define a C preprocessor symbol, set a variable in the output files,
8228 save the result in a cache file for future @command{configure} runs, and
8229 print a message letting the user know the result of the test.
8232 * Defining Symbols:: Defining C preprocessor symbols
8233 * Setting Output Variables:: Replacing variables in output files
8234 * Special Chars in Variables:: Characters to beware of in variables
8235 * Caching Results:: Speeding up subsequent @command{configure} runs
8236 * Printing Messages:: Notifying @command{configure} users
8239 @node Defining Symbols
8240 @section Defining C Preprocessor Symbols
8242 A common action to take in response to a feature test is to define a C
8243 preprocessor symbol indicating the results of the test. That is done by
8244 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8246 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8247 into the output variable @code{DEFS}, which contains an option
8248 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8249 Autoconf version 1, there is no variable @code{DEFS} defined while
8250 @command{configure} is running. To check whether Autoconf macros have
8251 already defined a certain C preprocessor symbol, test the value of the
8252 appropriate cache variable, as in this example:
8255 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8256 [Define if vprintf exists.])])
8257 if test "$ac_cv_func_vprintf" != yes; then
8258 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8259 [Define if _doprnt exists.])])
8263 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8264 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8265 correct values into @code{#define} statements in a template file.
8266 @xref{Configuration Headers}, for more information about this kind of
8269 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8270 @defmacx AC_DEFINE (@var{variable})
8272 Define @var{variable} to @var{value} (verbatim), by defining a C
8273 preprocessor macro for @var{variable}. @var{variable} should be a C
8274 identifier, optionally suffixed by a parenthesized argument list to
8275 define a C preprocessor macro with arguments. The macro argument list,
8276 if present, should be a comma-separated list of C identifiers, possibly
8277 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8278 @var{variable} should not contain comments, white space, trigraphs,
8279 backslash-newlines, universal character names, or non-@acronym{ASCII}
8282 @var{value} should not contain literal newlines, and if you are not
8283 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8284 characters, as @command{make} tends to eat them. To use a shell variable,
8285 use @code{AC_DEFINE_UNQUOTED} instead.
8286 @var{description} is only useful if you are using
8287 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8288 the generated @file{config.h.in} as the comment before the macro define.
8289 The following example defines the C preprocessor variable
8290 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8293 AC_DEFINE([EQUATION], ["$a > $b"],
8297 If neither @var{value} nor @var{description} are given, then
8298 @var{value} defaults to 1 instead of to the empty string. This is for
8299 backwards compatibility with older versions of Autoconf, but this usage
8300 is obsolescent and may be withdrawn in future versions of Autoconf.
8302 If the @var{variable} is a literal string, it is passed to
8303 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8305 If multiple @code{AC_DEFINE} statements are executed for the same
8306 @var{variable} name (not counting any parenthesized argument list),
8310 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8311 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8312 @acindex{DEFINE_UNQUOTED}
8313 Like @code{AC_DEFINE}, but three shell expansions are
8314 performed---once---on @var{variable} and @var{value}: variable expansion
8315 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8316 (@samp{\}). Single and double quote characters in the value have no
8317 special meaning. Use this macro instead of @code{AC_DEFINE} when
8318 @var{variable} or @var{value} is a shell variable. Examples:
8321 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8322 [Configuration machine file.])
8323 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8324 [getgroups return type.])
8325 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8326 [Translated header name.])
8330 Due to a syntactical bizarreness of the Bourne shell, do not use
8331 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8332 calls from other macro calls or shell code; that can cause syntax errors
8333 in the resulting @command{configure} script. Use either blanks or
8334 newlines. That is, do this:
8337 AC_CHECK_HEADER([elf.h],
8338 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8345 AC_CHECK_HEADER([elf.h],
8346 [AC_DEFINE([SVR4], [1], [System V Release 4])
8347 LIBS="-lelf $LIBS"])
8354 AC_CHECK_HEADER([elf.h],
8355 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8358 @node Setting Output Variables
8359 @section Setting Output Variables
8360 @cindex Output variables
8362 Another way to record the results of tests is to set @dfn{output
8363 variables}, which are shell variables whose values are substituted into
8364 files that @command{configure} outputs. The two macros below create new
8365 output variables. @xref{Preset Output Variables}, for a list of output
8366 variables that are always available.
8368 @defmac AC_SUBST (@var{variable}, @ovar{value})
8370 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8371 substitute the variable @var{variable} into output files (typically one
8372 or more makefiles). This means that @code{AC_OUTPUT}
8373 replaces instances of @samp{@@@var{variable}@@} in input files with the
8374 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8375 is called. The value can contain any non-@code{NUL} character, including
8377 Variable occurrences should not overlap: e.g., an input file should
8378 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8380 The substituted value is not rescanned for more output variables;
8381 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8382 literally into the output file. (The algorithm uses the special marker
8383 @code{|#_!!_#|} internally, so neither the substituted value nor the
8384 output file may contain @code{|#_!!_#|}.)
8386 If @var{value} is given, in addition assign it to @var{variable}.
8388 The string @var{variable} is passed to @code{m4_pattern_allow}
8389 (@pxref{Forbidden Patterns}).
8392 @defmac AC_SUBST_FILE (@var{variable})
8393 @acindex{SUBST_FILE}
8394 Another way to create an output variable from a shell variable. Make
8395 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8396 named by shell variable @var{variable} into output files. This means
8397 that @code{AC_OUTPUT} replaces instances of
8398 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8399 with the contents of the file that the shell variable @var{variable}
8400 names when @code{AC_OUTPUT} is called. Set the variable to
8401 @file{/dev/null} for cases that do not have a file to insert.
8402 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8403 line by itself, optionally surrounded by spaces and tabs. The
8404 substitution replaces the whole line, including the spaces, tabs, and
8405 the terminating newline.
8407 This macro is useful for inserting makefile fragments containing
8408 special dependencies or other @code{make} directives for particular host
8409 or target types into makefiles. For example, @file{configure.ac}
8413 AC_SUBST_FILE([host_frag])
8414 host_frag=$srcdir/conf/sun4.mh
8418 and then a @file{Makefile.in} could contain:
8424 The string @var{variable} is passed to @code{m4_pattern_allow}
8425 (@pxref{Forbidden Patterns}).
8428 @cindex Precious Variable
8429 @cindex Variable, Precious
8430 Running @command{configure} in varying environments can be extremely
8431 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8432 ./configure}, then the cache, @file{config.h}, and many other output
8433 files depend upon @command{bizarre-cc} being the C compiler. If
8434 for some reason the user runs @command{./configure} again, or if it is
8435 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8436 and @pxref{config.status Invocation}), then the configuration can be
8437 inconsistent, composed of results depending upon two different
8440 Environment variables that affect this situation, such as @samp{CC}
8441 above, are called @dfn{precious variables}, and can be declared as such
8442 by @code{AC_ARG_VAR}.
8444 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8446 Declare @var{variable} is a precious variable, and include its
8447 @var{description} in the variable section of @samp{./configure --help}.
8449 Being precious means that
8452 @var{variable} is substituted via @code{AC_SUBST}.
8455 The value of @var{variable} when @command{configure} was launched is
8456 saved in the cache, including if it was not specified on the command
8457 line but via the environment. Indeed, while @command{configure} can
8458 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8459 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8460 which, unfortunately, is what most users do.
8462 We emphasize that it is the @emph{initial} value of @var{variable} which
8463 is saved, not that found during the execution of @command{configure}.
8464 Indeed, specifying @samp{./configure FOO=foo} and letting
8465 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8469 @var{variable} is checked for consistency between two
8470 @command{configure} runs. For instance:
8473 $ @kbd{./configure --silent --config-cache}
8474 $ @kbd{CC=cc ./configure --silent --config-cache}
8475 configure: error: `CC' was not set in the previous run
8476 configure: error: changes in the environment can compromise \
8478 configure: error: run `make distclean' and/or \
8479 `rm config.cache' and start over
8483 and similarly if the variable is unset, or if its content is changed.
8487 @var{variable} is kept during automatic reconfiguration
8488 (@pxref{config.status Invocation}) as if it had been passed as a command
8489 line argument, including when no cache is used:
8492 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8493 $ @kbd{./config.status --recheck}
8494 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \
8495 CC=/usr/bin/cc --no-create --no-recursion
8500 @node Special Chars in Variables
8501 @section Special Characters in Output Variables
8502 @cindex Output variables, special characters in
8504 Many output variables are intended to be evaluated both by
8505 @command{make} and by the shell. Some characters are expanded
8506 differently in these two contexts, so to avoid confusion these
8507 variables' values should not contain any of the following characters:
8510 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8513 Also, these variables' values should neither contain newlines, nor start
8514 with @samp{~}, nor contain white space or @samp{:} immediately followed
8515 by @samp{~}. The values can contain nonempty sequences of white space
8516 characters like tabs and spaces, but each such sequence might
8517 arbitrarily be replaced by a single space during substitution.
8519 These restrictions apply both to the values that @command{configure}
8520 computes, and to the values set directly by the user. For example, the
8521 following invocations of @command{configure} are problematic, since they
8522 attempt to use special characters within @code{CPPFLAGS} and white space
8523 within @code{$(srcdir)}:
8526 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8528 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8531 @node Caching Results
8532 @section Caching Results
8535 To avoid checking for the same features repeatedly in various
8536 @command{configure} scripts (or in repeated runs of one script),
8537 @command{configure} can optionally save the results of many checks in a
8538 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8539 runs with caching enabled and finds a cache file, it reads the results
8540 of previous runs from the cache and avoids rerunning those checks. As a
8541 result, @command{configure} can then run much faster than if it had to
8542 perform all of the checks every time.
8544 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8546 Ensure that the results of the check identified by @var{cache-id} are
8547 available. If the results of the check were in the cache file that was
8548 read, and @command{configure} was not given the @option{--quiet} or
8549 @option{--silent} option, print a message saying that the result was
8550 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8551 the shell commands are run to determine the value, the value is
8552 saved in the cache file just before @command{configure} creates its output
8553 files. @xref{Cache Variable Names}, for how to choose the name of the
8554 @var{cache-id} variable.
8556 The @var{commands-to-set-it} @emph{must have no side effects} except for
8557 setting the variable @var{cache-id}, see below.
8560 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8561 @acindex{CACHE_CHECK}
8562 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8563 messages. This macro provides a convenient shorthand for the most
8564 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8565 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8566 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8568 The @var{commands-to-set-it} @emph{must have no side effects} except for
8569 setting the variable @var{cache-id}, see below.
8572 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8573 @code{AC_CACHE_CHECK}, because people are tempted to call
8574 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8575 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8576 @code{AC_DEFINE}, by examining the value of the cache variable. For
8577 instance, the following macro is broken:
8581 AC_DEFUN([AC_SHELL_TRUE],
8582 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8583 [ac_cv_shell_true_works=no
8584 (true) 2>/dev/null && ac_cv_shell_true_works=yes
8585 if test "$ac_cv_shell_true_works" = yes; then
8586 AC_DEFINE([TRUE_WORKS], [1],
8587 [Define if `true(1)' works properly.])
8594 This fails if the cache is enabled: the second time this macro is run,
8595 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8600 AC_DEFUN([AC_SHELL_TRUE],
8601 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8602 [ac_cv_shell_true_works=no
8603 (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8604 if test "$ac_cv_shell_true_works" = yes; then
8605 AC_DEFINE([TRUE_WORKS], [1],
8606 [Define if `true(1)' works properly.])
8612 Also, @var{commands-to-set-it} should not print any messages, for
8613 example with @code{AC_MSG_CHECKING}; do that before calling
8614 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8615 the results of the check are retrieved from the cache or determined by
8616 running the shell commands.
8619 * Cache Variable Names:: Shell variables used in caches
8620 * Cache Files:: Files @command{configure} uses for caching
8621 * Cache Checkpointing:: Loading and saving the cache file
8624 @node Cache Variable Names
8625 @subsection Cache Variable Names
8626 @cindex Cache variable
8628 The names of cache variables should have the following format:
8631 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8635 for example, @samp{ac_cv_header_stat_broken} or
8636 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8639 @item @var{package-prefix}
8640 An abbreviation for your package or organization; the same prefix you
8641 begin local Autoconf macros with, except lowercase by convention.
8642 For cache values used by the distributed Autoconf macros, this value is
8646 Indicates that this shell variable is a cache value. This string
8647 @emph{must} be present in the variable name, including the leading
8650 @item @var{value-type}
8651 A convention for classifying cache values, to produce a rational naming
8652 system. The values used in Autoconf are listed in @ref{Macro Names}.
8654 @item @var{specific-value}
8655 Which member of the class of cache values this test applies to.
8656 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8657 output variable (@samp{INSTALL}).
8659 @item @var{additional-options}
8660 Any particular behavior of the specific member that this test applies to.
8661 For example, @samp{broken} or @samp{set}. This part of the name may
8662 be omitted if it does not apply.
8665 The values assigned to cache variables may not contain newlines.
8666 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8667 names of files or functions; so this is not an important restriction.
8670 @subsection Cache Files
8672 A cache file is a shell script that caches the results of configure
8673 tests run on one system so they can be shared between configure scripts
8674 and configure runs. It is not useful on other systems. If its contents
8675 are invalid for some reason, the user may delete or edit it.
8677 By default, @command{configure} uses no cache file,
8678 to avoid problems caused by accidental
8679 use of stale cache files.
8681 To enable caching, @command{configure} accepts @option{--config-cache} (or
8682 @option{-C}) to cache results in the file @file{config.cache}.
8683 Alternatively, @option{--cache-file=@var{file}} specifies that
8684 @var{file} be the cache file. The cache file is created if it does not
8685 exist already. When @command{configure} calls @command{configure} scripts in
8686 subdirectories, it uses the @option{--cache-file} argument so that they
8687 share the same cache. @xref{Subdirectories}, for information on
8688 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8690 @file{config.status} only pays attention to the cache file if it is
8691 given the @option{--recheck} option, which makes it rerun
8692 @command{configure}.
8694 It is wrong to try to distribute cache files for particular system types.
8695 There is too much room for error in doing that, and too much
8696 administrative overhead in maintaining them. For any features that
8697 can't be guessed automatically, use the standard method of the canonical
8698 system type and linking files (@pxref{Manual Configuration}).
8700 The site initialization script can specify a site-wide cache file to
8701 use, instead of the usual per-program cache. In this case, the cache
8702 file gradually accumulates information whenever someone runs a new
8703 @command{configure} script. (Running @command{configure} merges the new cache
8704 results with the existing cache file.) This may cause problems,
8705 however, if the system configuration (e.g., the installed libraries or
8706 compilers) changes and the stale cache file is not deleted.
8708 @node Cache Checkpointing
8709 @subsection Cache Checkpointing
8711 If your configure script, or a macro called from @file{configure.ac}, happens
8712 to abort the configure process, it may be useful to checkpoint the cache
8713 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8714 reduces the amount of time it takes to rerun the configure script with
8715 (hopefully) the error that caused the previous abort corrected.
8717 @c FIXME: Do we really want to document this guy?
8718 @defmac AC_CACHE_LOAD
8719 @acindex{CACHE_LOAD}
8720 Loads values from existing cache file, or creates a new cache file if a
8721 cache file is not found. Called automatically from @code{AC_INIT}.
8724 @defmac AC_CACHE_SAVE
8725 @acindex{CACHE_SAVE}
8726 Flushes all cached values to the cache file. Called automatically from
8727 @code{AC_OUTPUT}, but it can be quite useful to call
8728 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8734 @r{ @dots{} AC_INIT, etc. @dots{}}
8736 # Checks for programs.
8739 @r{ @dots{} more program checks @dots{}}
8744 # Checks for libraries.
8745 AC_CHECK_LIB([nsl], [gethostbyname])
8746 AC_CHECK_LIB([socket], [connect])
8747 @r{ @dots{} more lib checks @dots{}}
8752 # Might abort@dots{}
8753 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8754 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8756 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8759 @node Printing Messages
8760 @section Printing Messages
8761 @cindex Messages, from @command{configure}
8763 @command{configure} scripts need to give users running them several kinds
8764 of information. The following macros print messages in ways appropriate
8765 for each kind. The arguments to all of them get enclosed in shell
8766 double quotes, so the shell performs variable and back-quote
8767 substitution on them.
8769 These macros are all wrappers around the @command{echo} shell command.
8770 They direct output to the appropriate file descriptor (@pxref{File
8771 Descriptor Macros}).
8772 @command{configure} scripts should rarely need to run @command{echo} directly
8773 to print messages for the user. Using these macros makes it easy to
8774 change how and when each kind of message is printed; such changes need
8775 only be made to the macro definitions and all the callers change
8778 To diagnose static issues, i.e., when @command{autoconf} is run, see
8779 @ref{Reporting Messages}.
8781 @defmac AC_MSG_CHECKING (@var{feature-description})
8782 @acindex{MSG_CHECKING}
8783 Notify the user that @command{configure} is checking for a particular
8784 feature. This macro prints a message that starts with @samp{checking }
8785 and ends with @samp{...} and no newline. It must be followed by a call
8786 to @code{AC_MSG_RESULT} to print the result of the check and the
8787 newline. The @var{feature-description} should be something like
8788 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8791 This macro prints nothing if @command{configure} is run with the
8792 @option{--quiet} or @option{--silent} option.
8795 @defmac AC_MSG_RESULT (@var{result-description})
8796 @acindex{MSG_RESULT}
8797 Notify the user of the results of a check. @var{result-description} is
8798 almost always the value of the cache variable for the check, typically
8799 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
8800 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8801 the completion of the message printed by the call to
8802 @code{AC_MSG_CHECKING}.
8804 This macro prints nothing if @command{configure} is run with the
8805 @option{--quiet} or @option{--silent} option.
8808 @defmac AC_MSG_NOTICE (@var{message})
8809 @acindex{MSG_NOTICE}
8810 Deliver the @var{message} to the user. It is useful mainly to print a
8811 general description of the overall purpose of a group of feature checks,
8815 AC_MSG_NOTICE([checking if stack overflow is detectable])
8818 This macro prints nothing if @command{configure} is run with the
8819 @option{--quiet} or @option{--silent} option.
8822 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8824 Notify the user of an error that prevents @command{configure} from
8825 completing. This macro prints an error message to the standard error
8826 output and exits @command{configure} with @var{exit-status} (1 by default).
8827 @var{error-description} should be something like @samp{invalid value
8830 The @var{error-description} should start with a lower-case letter, and
8831 ``cannot'' is preferred to ``can't''.
8834 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8835 @acindex{MSG_FAILURE}
8836 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8837 prevents @command{configure} from completing @emph{and} that additional
8838 details are provided in @file{config.log}. This is typically used when
8839 abnormal results are found during a compilation.
8842 @defmac AC_MSG_WARN (@var{problem-description})
8844 Notify the @command{configure} user of a possible problem. This macro
8845 prints the message to the standard error output; @command{configure}
8846 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8847 provide a default (back-up) behavior for the situations they warn about.
8848 @var{problem-description} should be something like @samp{ln -s seems to
8854 @c ====================================================== Programming in M4.
8856 @node Programming in M4
8857 @chapter Programming in M4
8860 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8861 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8862 provides macros dedicated to shell script generation.
8864 As of this version of Autoconf, these two layers are still experimental,
8865 and their interface might change in the future. As a matter of fact,
8866 @emph{anything that is not documented must not be used}.
8869 * M4 Quotation:: Protecting macros from unwanted expansion
8870 * Using autom4te:: The Autoconf executables backbone
8871 * Programming in M4sugar:: Convenient pure M4 macros
8872 * Programming in M4sh:: Common shell Constructs
8873 * File Descriptor Macros:: File descriptor macros for input and output
8877 @section M4 Quotation
8878 @cindex M4 quotation
8881 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8882 @c prevented `expansion' of $1. Unless it refers to the expansion
8883 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
8885 The most common problem with existing macros is an improper quotation.
8886 This section, which users of Autoconf can skip, but which macro writers
8887 @emph{must} read, first justifies the quotation scheme that was chosen
8888 for Autoconf and then ends with a rule of thumb. Understanding the
8889 former helps one to follow the latter.
8892 * Active Characters:: Characters that change the behavior of M4
8893 * One Macro Call:: Quotation and one macro call
8894 * Quotation and Nested Macros:: Macros calling macros
8895 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
8896 * Quadrigraphs:: Another way to escape special characters
8897 * Quotation Rule Of Thumb:: One parenthesis, one quote
8900 @node Active Characters
8901 @subsection Active Characters
8903 To fully understand where proper quotation is important, you first need
8904 to know what the special characters are in Autoconf: @samp{#} introduces
8905 a comment inside which no macro expansion is performed, @samp{,}
8906 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8907 and finally @samp{(} and @samp{)} (which M4 tries to match by
8910 In order to understand the delicate case of macro calls, we first have
8911 to present some obvious failures. Below they are ``obvious-ified'',
8912 but when you find them in real life, they are usually in disguise.
8914 Comments, introduced by a hash and running up to the newline, are opaque
8915 tokens to the top level: active characters are turned off, and there is
8919 # define([def], ine)
8920 @result{}# define([def], ine)
8923 Each time there can be a macro expansion, there is a quotation
8924 expansion, i.e., one level of quotes is stripped:
8930 @result{}int tab[10];
8933 Without this in mind, the reader might try hopelessly to use her macro
8937 define([array], [int tab[10];])
8945 How can you correctly output the intended results@footnote{Using
8949 @node One Macro Call
8950 @subsection One Macro Call
8952 Let's proceed on the interaction between active characters and macros
8953 with this small macro, which just returns its first argument:
8960 The two pairs of quotes above are not part of the arguments of
8961 @code{define}; rather, they are understood by the top level when it
8962 tries to find the arguments of @code{define}. Therefore, assuming
8963 @code{car} is not already defined, it is equivalent to write:
8970 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8971 quotes, it is bad practice for Autoconf macros which must both be more
8972 robust and also advocate perfect style.
8974 At the top level, there are only two possibilities: either you
8980 [car(foo, bar, baz)]
8981 @result{}car(foo, bar, baz)
8984 Let's pay attention to the special characters:
8988 @error{}EOF in argument list
8991 The closing parenthesis is hidden in the comment; with a hypothetical
8992 quoting, the top level understood it this way:
8999 Proper quotation, of course, fixes the problem:
9006 Here are more examples:
9029 With this in mind, we can explore the cases where macros invoke
9033 @node Quotation and Nested Macros
9034 @subsection Quotation and Nested Macros
9036 The examples below use the following macros:
9040 define([active], [ACT, IVE])
9041 define([array], [int tab[10]])
9044 Each additional embedded macro call introduces other possible
9045 interesting quotations:
9056 In the first case, the top level looks for the arguments of @code{car},
9057 and finds @samp{active}. Because M4 evaluates its arguments
9058 before applying the macro, @samp{active} is expanded, which results in:
9066 In the second case, the top level gives @samp{active} as first and only
9067 argument of @code{car}, which results in:
9075 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9076 In the third case, @code{car} receives @samp{[active]}, which results in:
9084 exactly as we already saw above.
9086 The example above, applied to a more realistic example, gives:
9093 car([[int tab[10];]])
9094 @result{}int tab[10];
9098 Huh? The first case is easily understood, but why is the second wrong,
9099 and the third right? To understand that, you must know that after
9100 M4 expands a macro, the resulting text is immediately subjected
9101 to macro expansion and quote removal. This means that the quote removal
9102 occurs twice---first before the argument is passed to the @code{car}
9103 macro, and second after the @code{car} macro expands to the first
9106 As the author of the Autoconf macro @code{car}, you then consider it to
9107 be incorrect that your users have to double-quote the arguments of
9108 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9112 define([qar], [[$1]])
9116 and check that @code{qar} is properly fixed:
9120 @result{}int tab[10];
9124 Ahhh! That's much better.
9126 But note what you've done: now that the arguments are literal strings,
9127 if the user wants to use the results of expansions as arguments, she has
9128 to use an @emph{unquoted} macro call:
9136 where she wanted to reproduce what she used to do with @code{car}:
9144 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9148 define([my_includes], [#include <stdio.h>])
9150 @result{}#include <stdio.h>
9152 @error{}EOF in argument list
9155 This macro, @code{qar}, because it double quotes its arguments, forces
9156 its users to leave their macro calls unquoted, which is dangerous.
9157 Commas and other active symbols are interpreted by M4 before
9158 they are given to the macro, often not in the way the users expect.
9159 Also, because @code{qar} behaves differently from the other macros,
9160 it's an exception that should be avoided in Autoconf.
9162 @node Changequote is Evil
9163 @subsection @code{changequote} is Evil
9164 @cindex @code{changequote}
9166 The temptation is often high to bypass proper quotation, in particular
9167 when it's late at night. Then, many experienced Autoconf hackers
9168 finally surrender to the dark side of the force and use the ultimate
9169 weapon: @code{changequote}.
9171 The M4 builtin @code{changequote} belongs to a set of primitives that
9172 allow one to adjust the syntax of the language to adjust it to one's
9173 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9174 quotes, but in the context of shell programming (and actually of most
9175 programming languages), that's about the worst choice one can make:
9176 because of strings and back-quoted expressions in shell code (such as
9177 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9178 programming languages (as in @samp{'0'}), there are many unbalanced
9179 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9180 not impossible. In order to make M4 useful in such a context, its
9181 designers have equipped it with @code{changequote}, which makes it
9182 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9183 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9184 because they are unlikely characters, but @emph{because they are
9185 characters unlikely to be unbalanced}.
9187 There are other magic primitives, such as @code{changecom} to specify
9188 what syntactic forms are comments (it is common to see
9189 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9190 @code{changeword} and @code{changesyntax} to change other syntactic
9191 details (such as the character to denote the @var{n}th argument, @samp{$} by
9192 default, the parenthesis around arguments, etc.).
9194 These primitives are really meant to make M4 more useful for specific
9195 domains: they should be considered like command line options:
9196 @option{--quotes}, @option{--comments}, @option{--words}, and
9197 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9198 it makes M4 libraries self contained (no need for additional options).
9200 There lies the problem@enddots{}
9204 The problem is that it is then tempting to use them in the middle of an
9205 M4 script, as opposed to its initialization. This, if not carefully
9206 thought out, can lead to disastrous effects: @emph{you are changing the
9207 language in the middle of the execution}. Changing and restoring the
9208 syntax is often not enough: if you happened to invoke macros in between,
9209 these macros are lost, as the current syntax is probably not
9210 the one they were implemented with.
9212 @c FIXME: I've been looking for a short, real case example, but I
9217 @subsection Quadrigraphs
9218 @cindex quadrigraphs
9219 @cindex @samp{@@S|@@}
9220 @cindex @samp{@@&t@@}
9221 @c Info cannot handle `:' in index entries.
9222 @c @cindex @samp{@@<:@@}
9223 @c @cindex @samp{@@:>@@}
9224 @c @cindex @samp{@@%:@@}
9226 When writing an Autoconf macro you may occasionally need to generate
9227 special characters that are difficult to express with the standard
9228 Autoconf quoting rules. For example, you may need to output the regular
9229 expression @samp{[^[]}, which matches any character other than @samp{[}.
9230 This expression contains unbalanced brackets so it cannot be put easily
9233 You can work around this problem by using one of the following
9249 Quadrigraphs are replaced at a late stage of the translation process,
9250 after @command{m4} is run, so they do not get in the way of M4 quoting.
9251 For example, the string @samp{^@@<:@@}, independently of its quotation,
9252 appears as @samp{^[} in the output.
9254 The empty quadrigraph can be used:
9257 @item to mark trailing spaces explicitly
9259 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9261 @item to produce other quadrigraphs
9263 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9265 @item to escape @emph{occurrences} of forbidden patterns
9267 For instance you might want to mention @code{AC_FOO} in a comment, while
9268 still being sure that @command{autom4te} still catches unexpanded
9269 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9272 The name @samp{@@&t@@} was suggested by Paul Eggert:
9275 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9276 own invention, but the @samp{t} came from the source code of the
9277 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9278 and which used @samp{mt} to denote the empty string. In C, it would
9279 have looked like something like:
9282 char const mt[] = "";
9286 but of course the source code was written in Algol 68.
9288 I don't know where he got @samp{mt} from: it could have been his own
9289 invention, and I suppose it could have been a common pun around the
9290 Cambridge University computer lab at the time.
9293 @node Quotation Rule Of Thumb
9294 @subsection Quotation Rule Of Thumb
9296 To conclude, the quotation rule of thumb is:
9298 @center @emph{One pair of quotes per pair of parentheses.}
9300 Never over-quote, never under-quote, in particular in the definition of
9301 macros. In the few places where the macros need to use brackets
9302 (usually in C program text or regular expressions), properly quote
9303 @emph{the arguments}!
9305 It is common to read Autoconf programs with snippets like:
9309 changequote(<<, >>)dnl
9311 #ifndef tzname /* For SGI. */
9312 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9314 changequote([, ])dnl
9315 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9319 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9320 double quoting, so you just need:
9325 #ifndef tzname /* For SGI. */
9326 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9329 [ac_cv_var_tzname=yes],
9330 [ac_cv_var_tzname=no])
9334 The M4-fluent reader might note that these two examples are rigorously
9335 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9336 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9337 quotes are not part of the arguments!
9339 Simplified, the example above is just doing this:
9342 changequote(<<, >>)dnl
9344 changequote([, ])dnl
9354 With macros that do not double quote their arguments (which is the
9355 rule), double-quote the (risky) literals:
9358 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9360 #ifndef tzname /* For SGI. */
9361 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9363 [atoi (*tzname);])],
9364 [ac_cv_var_tzname=yes],
9365 [ac_cv_var_tzname=no])
9368 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9369 should be using @code{AC_LINK_IFELSE} instead.
9371 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9372 where quoting does not suffice.
9374 When you create a @command{configure} script using newly written macros,
9375 examine it carefully to check whether you need to add more quotes in
9376 your macros. If one or more words have disappeared in the M4
9377 output, you need more quotes. When in doubt, quote.
9379 However, it's also possible to put on too many layers of quotes. If
9380 this happens, the resulting @command{configure} script may contain
9381 unexpanded macros. The @command{autoconf} program checks for this problem
9382 by looking for the string @samp{AC_} in @file{configure}. However, this
9383 heuristic does not work in general: for example, it does not catch
9384 overquoting in @code{AC_DEFINE} descriptions.
9387 @c ---------------------------------------- Using autom4te
9389 @node Using autom4te
9390 @section Using @command{autom4te}
9392 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9393 to Autoconf per se, heavily rely on M4. All these different uses
9394 revealed common needs factored into a layer over M4:
9395 @command{autom4te}@footnote{
9397 Yet another great name from Lars J. Aas.
9401 @command{autom4te} is a preprocessor that is like @command{m4}.
9402 It supports M4 extensions designed for use in tools like Autoconf.
9405 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9406 * Customizing autom4te:: Customizing the Autoconf package
9409 @node autom4te Invocation
9410 @subsection Invoking @command{autom4te}
9412 The command line arguments are modeled after M4's:
9415 autom4te @var{options} @var{files}
9420 where the @var{files} are directly passed to @command{m4}. By default,
9421 @acronym{GNU} M4 is found during configuration, but the environment
9423 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9424 to the regular expansion, it handles the replacement of the quadrigraphs
9425 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9426 output. It supports an extended syntax for the @var{files}:
9429 @item @var{file}.m4f
9430 This file is an M4 frozen file. Note that @emph{all the previous files
9431 are ignored}. See the option @option{--melt} for the rationale.
9434 If found in the library path, the @var{file} is included for expansion,
9435 otherwise it is ignored instead of triggering a failure.
9440 Of course, it supports the Autoconf common subset of options:
9445 Print a summary of the command line options and exit.
9449 Print the version number of Autoconf and exit.
9453 Report processing steps.
9457 Don't remove the temporary files and be even more verbose.
9459 @item --include=@var{dir}
9461 Also look for input files in @var{dir}. Multiple invocations
9464 @item --output=@var{file}
9465 @itemx -o @var{file}
9466 Save output (script or trace) to @var{file}. The file @option{-} stands
9467 for the standard output.
9472 As an extension of @command{m4}, it includes the following options:
9475 @item --warnings=@var{category}
9476 @itemx -W @var{category}
9478 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9479 Report the warnings related to @var{category} (which can actually be a
9480 comma separated list). @xref{Reporting Messages}, macro
9481 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9486 report all the warnings
9492 treats warnings as errors
9494 @item no-@var{category}
9495 disable warnings falling into @var{category}
9498 Warnings about @samp{syntax} are enabled by default, and the environment
9499 variable @env{WARNINGS}, a comma separated list of categories, is
9500 honored. @samp{autom4te -W @var{category}} actually
9501 behaves as if you had run:
9504 autom4te --warnings=syntax,$WARNINGS,@var{category}
9508 For example, if you want to disable defaults and @env{WARNINGS}
9509 of @command{autom4te}, but enable the warnings about obsolete
9510 constructs, you would use @option{-W none,obsolete}.
9513 @cindex Macro invocation stack
9514 @command{autom4te} displays a back trace for errors, but not for
9515 warnings; if you want them, just pass @option{-W error}.
9519 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9520 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9521 are executed only when the files are frozen, typically
9522 @code{m4_define}. For instance, running:
9525 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9529 is roughly equivalent to running:
9532 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9539 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9546 m4 --reload-state=4.m4f input.m4
9551 Produce a frozen state file. @command{autom4te} freezing is stricter
9552 than M4's: it must produce no warnings, and no output other than empty
9553 lines (a line with white space is @emph{not} empty) and comments
9554 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9555 this option takes no argument:
9558 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9565 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9568 @item --mode=@var{octal-mode}
9569 @itemx -m @var{octal-mode}
9570 Set the mode of the non-traces output to @var{octal-mode}; by default
9576 @cindex @file{autom4te.cache}
9577 As another additional feature over @command{m4}, @command{autom4te}
9578 caches its results. @acronym{GNU} M4 is able to produce a regular
9579 output and traces at the same time. Traces are heavily used in the
9580 @acronym{GNU} Build System: @command{autoheader} uses them to build
9581 @file{config.h.in}, @command{autoreconf} to determine what
9582 @acronym{GNU} Build System components are used, @command{automake} to
9583 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9584 traces are cached while performing regular expansion,
9585 and conversely. This cache is (actually, the caches are) stored in
9586 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9587 at any moment (especially if for some reason @command{autom4te}
9588 considers it is trashed).
9591 @item --cache=@var{directory}
9592 @itemx -C @var{directory}
9593 Specify the name of the directory where the result should be cached.
9594 Passing an empty value disables caching. Be sure to pass a relative
9595 file name, as for the time being, global caches are not supported.
9598 Don't cache the results.
9602 If a cache is used, consider it obsolete (but update it anyway).
9607 Because traces are so important to the @acronym{GNU} Build System,
9608 @command{autom4te} provides high level tracing features as compared to
9609 M4, and helps exploiting the cache:
9612 @item --trace=@var{macro}[:@var{format}]
9613 @itemx -t @var{macro}[:@var{format}]
9614 Trace the invocations of @var{macro} according to the @var{format}.
9615 Multiple @option{--trace} arguments can be used to list several macros.
9616 Multiple @option{--trace} arguments for a single macro are not
9617 cumulative; instead, you should just make @var{format} as long as
9620 The @var{format} is a regular string, with newlines if desired, and
9621 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9622 use the following special escapes:
9626 The character @samp{$}.
9629 The file name from which @var{macro} is called.
9632 The line number from which @var{macro} is called.
9635 The depth of the @var{macro} call. This is an M4 technical detail that
9636 you probably don't want to know about.
9639 The name of the @var{macro}.
9642 The @var{num}th argument of the call to @var{macro}.
9646 @itemx $@{@var{separator}@}@@
9647 All the arguments passed to @var{macro}, separated by the character
9648 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9649 argument is quoted, i.e., enclosed in a pair of square brackets.
9653 @itemx $@{@var{separator}@}*
9654 As above, but the arguments are not quoted.
9658 @itemx $@{@var{separator}@}%
9659 As above, but the arguments are not quoted, all new line characters in
9660 the arguments are smashed, and the default separator is @samp{:}.
9662 The escape @samp{$%} produces single-line trace outputs (unless you put
9663 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9667 @xref{autoconf Invocation}, for examples of trace uses.
9669 @item --preselect=@var{macro}
9670 @itemx -p @var{macro}
9671 Cache the traces of @var{macro}, but do not enable traces. This is
9672 especially important to save CPU cycles in the future. For instance,
9673 when invoked, @command{autoconf} preselects all the macros that
9674 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9675 trace, so that running @command{m4} is not needed to trace them: the
9676 cache suffices. This results in a huge speed-up.
9681 @cindex Autom4te Library
9682 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9683 libraries}. They consists in a powerful yet extremely simple feature:
9684 sets of combined command line arguments:
9687 @item --language=@var{language}
9688 @itemx -l @var{language}
9689 Use the @var{language} Autom4te library. Current languages include:
9693 create M4sugar output.
9696 create M4sh executable shell scripts.
9699 create Autotest executable test suites.
9701 @item Autoconf-without-aclocal-m4
9702 create Autoconf executable configure scripts without
9703 reading @file{aclocal.m4}.
9706 create Autoconf executable configure scripts. This language inherits
9707 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9708 additionally reads @file{aclocal.m4}.
9711 @item --prepend-include=@var{dir}
9713 Prepend directory @var{dir} to the search path. This is used to include
9714 the language-specific files before any third-party macros.
9718 @cindex @file{autom4te.cfg}
9719 As an example, if Autoconf is installed in its default location,
9720 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9721 strictly equivalent to the command:
9724 autom4te --prepend-include /usr/local/share/autoconf \
9725 m4sugar/m4sugar.m4f --warnings syntax foo.m4
9729 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9730 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9734 autom4te --prepend-include /usr/local/share/autoconf \
9735 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9739 The definition of the languages is stored in @file{autom4te.cfg}.
9741 @node Customizing autom4te
9742 @subsection Customizing @command{autom4te}
9744 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9745 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9746 as found in the directory from which @command{autom4te} is run). The
9747 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9748 then @file{./.autom4te.cfg}, and finally the command line arguments.
9750 In these text files, comments are introduced with @code{#}, and empty
9751 lines are ignored. Customization is performed on a per-language basis,
9752 wrapped in between a @samp{begin-language: "@var{language}"},
9753 @samp{end-language: "@var{language}"} pair.
9755 Customizing a language stands for appending options (@pxref{autom4te
9756 Invocation}) to the current definition of the language. Options, and
9757 more generally arguments, are introduced by @samp{args:
9758 @var{arguments}}. You may use the traditional shell syntax to quote the
9761 As an example, to disable Autoconf caches (@file{autom4te.cache})
9762 globally, include the following lines in @file{~/.autom4te.cfg}:
9765 ## ------------------ ##
9766 ## User Preferences. ##
9767 ## ------------------ ##
9769 begin-language: "Autoconf-without-aclocal-m4"
9771 end-language: "Autoconf-without-aclocal-m4"
9775 @node Programming in M4sugar
9776 @section Programming in M4sugar
9779 M4 by itself provides only a small, but sufficient, set of all-purpose
9780 macros. M4sugar introduces additional generic macros. Its name was
9781 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9785 * Redefined M4 Macros:: M4 builtins changed in M4sugar
9786 * Looping constructs:: Iteration in M4
9787 * Evaluation Macros:: More quotation and evaluation control
9788 * Text processing Macros:: String manipulation in M4
9789 * Forbidden Patterns:: Catching unexpanded macros
9792 @node Redefined M4 Macros
9793 @subsection Redefined M4 Macros
9815 With a few exceptions, all the M4 native macros are moved in the
9816 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9817 @code{m4_define} etc.
9819 Some M4 macros are redefined, and are slightly incompatible with their
9824 This macro kept its original name: no @code{m4_dnl} is defined.
9827 @defmac m4_defn (@var{macro})
9829 Unlike the M4 builtin, this macro fails if @var{macro} is not
9830 defined. See @code{m4_undefine}.
9833 @defmac m4_exit (@var{exit-status})
9835 This macro corresponds to @code{m4exit}.
9838 @defmac m4_if (@var{comment})
9839 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9840 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9842 This macro corresponds to @code{ifelse}.
9845 @defmac m4_include (@var{file})
9846 @defmacx m4_sinclude (@var{file})
9849 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9852 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9854 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
9855 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9856 provide extended regular expression syntax via @code{epatsubst}.
9859 @defmac m4_popdef (@var{macro})
9861 Unlike the M4 builtin, this macro fails if @var{macro} is not
9862 defined. See @code{m4_undefine}.
9865 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9867 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
9868 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9869 provide extended regular expression syntax via @code{eregexp}.
9872 @defmac m4_wrap (@var{text})
9874 This macro corresponds to @code{m4wrap}.
9876 Posix requires arguments of multiple @code{m4wrap} calls to be
9877 reprocessed at @acronym{EOF} in the same order as the original calls.
9878 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9879 reverse order. Your code should not depend on the order.
9881 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9882 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9883 arguments with intervening spaces. Your code should not pass more than
9886 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9887 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9890 m4_define([foo], [bar])
9891 m4_define([foofoo], [OUCH])
9898 @defmac m4_undefine (@var{macro})
9900 Unlike the M4 builtin, this macro fails if @var{macro} is not
9904 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9908 to recover the behavior of the builtin.
9911 @defmac m4_maketemp (@var{template})
9912 @defmacx m4_mkstemp (@var{template})
9915 Posix requires @code{maketemp} to replace the trailing @samp{X}
9916 characters in @var{template} with the process id, without regards to the
9917 existence of a file by that name, but this a security hole. When this
9918 was pointed out to the Posix folks, they agreed to invent a new macro
9919 @code{mkstemp} that always creates a uniquely named file, but not all
9920 versions of @acronym{GNU} M4 support the new macro. In M4sugar,
9921 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
9922 and both have the secure semantics regardless of which macro the
9923 underlying M4 provides.
9927 @node Looping constructs
9928 @subsection Looping constructs
9930 The following macros implement loops in M4.
9932 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9934 Loop over the numeric values between @var{first} and @var{last}
9935 including bounds by increments of @var{step}. For each iteration,
9936 expand @var{expression} with the numeric value assigned to @var{var}.
9937 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9938 on the order of the limits. If given, @var{step} has to match this
9942 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9944 Loop over the comma-separated M4 list @var{list}, assigning each value
9945 to @var{var}, and expand @var{expression}. The following example
9949 m4_foreach([myvar], [[foo], [bar, baz]],
9956 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9958 Loop over the white-space-separated list @var{list}, assigning each value
9959 to @var{var}, and expand @var{expression}.
9961 The deprecated macro @code{AC_FOREACH} is an alias of
9962 @code{m4_foreach_w}.
9967 @node Evaluation Macros
9968 @subsection Evaluation Macros
9970 The following macros give some control over the order of the evaluation
9971 by adding or removing levels of quotes. They are meant for hard-core M4
9974 @defmac m4_dquote (@var{arg1}, @dots{})
9976 Return the arguments as a quoted list of quoted arguments.
9979 @defmac m4_quote (@var{arg1}, @dots{})
9981 Return the arguments as a single entity, i.e., wrap them into a pair of
9985 The following example aims at emphasizing the difference between (i), not
9986 using these macros, (ii), using @code{m4_quote}, and (iii), using
9990 $ @kbd{cat example.m4}
9991 # Overquote, so that quotes are visible.
9992 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9993 m4_define([mkargs], [1, 2, 3])
9994 m4_define([arg1], [[$1]])
9997 show(m4_quote(a, b))
9998 show(m4_dquote(a, b))
10001 arg1(m4_defn([mkargs]))
10002 arg1(m4_quote(mkargs))
10003 arg1(m4_dquote(mkargs))
10004 $ @kbd{autom4te -l m4sugar example.m4}
10005 $1 = a, $@@ = [a],[b]
10006 $1 = a,b, $@@ = [a,b]
10007 $1 = [a],[b], $@@ = [[a],[b]]
10017 @node Text processing Macros
10018 @subsection Text processing Macros
10020 The following macros may be used to manipulate strings in M4.
10021 They are not intended for casual use.
10023 @defmac m4_re_escape (@var{string})
10024 @msindex{re_escape}
10025 Backslash-escape all characters in @var{string} that are active in
10029 @defmac m4_tolower (@var{string})
10030 @defmacx m4_toupper (@var{string})
10033 Return @var{string} with letters converted to upper or lower case,
10037 @defmac m4_split (@var{string}, @ovar{regexp})
10039 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10040 @samp{]}, while keeping white space at the beginning and at the end.
10041 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10042 If @var{string} is empty, the result is an empty list.
10045 @defmac m4_normalize (@var{string})
10046 @msindex{normalize}
10047 Remove leading and trailing spaces and tabs, sequences of
10048 backslash-then-newline, and replace multiple spaces and tabs with a
10052 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10053 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
10055 @msindex{append_uniq}
10056 Redefine @var{macro-name} to its former contents with @var{separator}
10057 and @var{string} added at the end. If @var{macro-name} was undefined
10058 before (but not if it was defined but empty), then no @var{separator} is
10059 added. @code{m4_append} can be used to grow strings, and
10060 @code{m4_append_uniq} to grow strings without duplicating substrings.
10065 @node Forbidden Patterns
10066 @subsection Forbidden Patterns
10067 @cindex Forbidden patterns
10068 @cindex Patterns, forbidden
10070 M4sugar provides a means to define suspicious patterns, patterns
10071 describing tokens which should not be found in the output. For
10072 instance, if an Autoconf @file{configure} script includes tokens such as
10073 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10074 wrong (typically a macro was not evaluated because of overquotation).
10076 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
10078 @defmac m4_pattern_forbid (@var{pattern})
10079 @msindex{pattern_forbid}
10080 Declare that no token matching @var{pattern} must be found in the output.
10081 Comments are not checked; this can be a problem if, for instance, you
10082 have some macro left unexpanded after an @samp{#include}. No consensus
10083 is currently found in the Autoconf community, as some people consider it
10084 should be valid to name macros in comments (which doesn't make sense to
10085 the author of this documentation, as @samp{#}-comments should document
10086 the output, not the input, documented by @samp{dnl} comments).
10089 Of course, you might encounter exceptions to these generic rules, for
10090 instance you might have to refer to @samp{$m4_flags}.
10092 @defmac m4_pattern_allow (@var{pattern})
10093 @msindex{pattern_allow}
10094 Any token matching @var{pattern} is allowed, including if it matches an
10095 @code{m4_pattern_forbid} pattern.
10098 @node Programming in M4sh
10099 @section Programming in M4sh
10101 @c FIXME: Eventually will become a chapter, as it is not related to
10102 @c programming in M4 per se.
10104 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10105 scripts. This name was coined by Lars J. Aas, who notes that,
10106 according to the Webster's Revised Unabridged Dictionary (1913):
10109 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
10110 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
10114 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10118 A mixture of meal or bran and water fed to animals.
10121 A mess; trouble. [Obs.] --Beau.@: & Fl.
10126 For the time being, it is not mature enough to be widely used.
10128 M4sh provides portable alternatives for some common shell constructs
10129 that unfortunately are not portable in practice.
10131 @c Deprecated, to be replaced by a better API
10133 @defmac AS_BASENAME (@var{file-name})
10135 Output the non-directory portion of @var{file-name}. For example,
10136 if @code{$file} is @samp{/one/two/three}, the command
10137 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10141 @defmac AS_BOURNE_COMPATIBLE
10142 @asindex{BOURNE_COMPATIBLE}
10143 Set up the shell to be more compatible with the Bourne shell as
10144 standardized by Posix, if possible. This may involve setting
10145 environment variables, or setting options, or similar
10146 implementation-specific actions.
10149 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10151 Expand into a shell @samp{case} statement, where @var{word} is matched
10152 against one or more patterns. @var{if-matched} is run if the
10153 corresponding pattern matched @var{word}, else @var{default} is run.
10156 @defmac AS_DIRNAME (@var{file-name})
10158 Output the directory portion of @var{file-name}. For example,
10159 if @code{$file} is @samp{/one/two/three}, the command
10160 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10163 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10165 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10166 run shell code @var{run-if-true1}, else examine further tests. If no test
10167 exits with a zero status, run shell code @var{run-if-false}, with
10168 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10169 is empty. For example,
10172 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10173 [test "$foo" != no], [HANDLE_FOO([maybe])],
10174 [echo foo not specified])
10178 ensures any required macros of @code{HANDLE_FOO}
10179 are expanded before the first test.
10182 @defmac AS_MKDIR_P (@var{file-name})
10184 Make the directory @var{file-name}, including intervening directories
10185 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10186 except that it is portable to older versions of @command{mkdir} that
10187 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10188 succeeds if @var{file-name} is a symbolic link to an existing directory,
10189 even though Posix is unclear whether @samp{mkdir -p} should
10190 succeed in that case. If creation of @var{file-name} fails, exit the
10193 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10196 @defmac AS_SHELL_SANITIZE
10197 @asindex{SHELL_SANITIZE}
10198 Initialize the shell suitably for @code{configure} scripts. This has
10199 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10200 environment variables for predictable results from configuration tests.
10201 For example, it sets @env{LC_ALL} to change to the default C locale.
10202 @xref{Special Shell Variables}.
10205 @defmac AS_TR_CPP (@var{expression})
10207 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10211 # This outputs "#define HAVE_CHAR_P 1".
10213 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10217 @defmac AS_TR_SH (@var{expression})
10219 Transform @var{expression} into a valid shell variable name. For example:
10222 # This outputs "Have it!".
10223 header="sys/some file.h"
10224 AS_TR_SH([HAVE_$header])=yes
10225 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10229 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10230 @asindex{SET_CATFILE}
10231 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10232 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10233 @var{file} is absolute, etc.).
10237 @node File Descriptor Macros
10238 @section File Descriptor Macros
10240 @cindex standard input
10241 @cindex file descriptors
10242 @cindex descriptors
10243 @cindex low-level output
10244 @cindex output, low-level
10246 The following macros define file descriptors used to output messages
10247 (or input values) from @file{configure} scripts.
10251 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10252 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10253 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10257 However doing so is seldom needed, because Autoconf provides higher
10258 level macros as described below.
10260 @defmac AS_MESSAGE_FD
10261 @asindex{MESSAGE_FD}
10262 The file descriptor for @samp{checking for...} messages and results.
10263 Normally this directs messages to the standard output, however when
10264 @command{configure} is run with the @option{-q} option, messages sent to
10265 @code{AS_MESSAGE_FD} are discarded.
10267 If you want to display some messages, consider using one of the printing
10268 macros (@pxref{Printing Messages}) instead. Copies of messages output
10269 via these macros are also recorded in @file{config.log}.
10272 @defmac AS_MESSAGE_LOG_FD
10273 @asindex{MESSAGE_LOG_FD}
10275 The file descriptor for messages logged to @file{config.log}. Macros
10276 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10277 Compiler}), redirect all output to this descriptor. You may want to do
10278 so if you develop such a low-level macro.
10281 @defmac AS_ORIGINAL_STDIN_FD
10282 @asindex{ORIGINAL_STDIN_FD}
10283 The file descriptor for the original standard input.
10285 When @command{configure} runs, it may accidentally execute an
10286 interactive command that has the same name as the non-interactive meant
10287 to be used or checked. If the standard input was the terminal, such
10288 interactive programs would cause @command{configure} to stop, pending
10289 some user input. Therefore @command{configure} redirects its standard
10290 input from @file{/dev/null} during its initialization. This is not
10291 normally a problem, since @command{configure} normally does not need
10294 In the extreme case where your @file{configure} script really needs to
10295 obtain some values from the original standard input, you can read them
10296 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10300 @c =================================================== Writing Autoconf Macros.
10302 @node Writing Autoconf Macros
10303 @chapter Writing Autoconf Macros
10305 When you write a feature test that could be applicable to more than one
10306 software package, the best thing to do is encapsulate it in a new macro.
10307 Here are some instructions and guidelines for writing Autoconf macros.
10310 * Macro Definitions:: Basic format of an Autoconf macro
10311 * Macro Names:: What to call your new macros
10312 * Reporting Messages:: Notifying @command{autoconf} users
10313 * Dependencies Between Macros:: What to do when macros depend on other macros
10314 * Obsoleting Macros:: Warning about old ways of doing things
10315 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10318 @node Macro Definitions
10319 @section Macro Definitions
10322 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10323 similar to the M4 builtin @code{m4_define} macro. In addition to
10324 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10325 constrain the order in which macros are called (@pxref{Prerequisite
10328 An Autoconf macro definition looks like this:
10331 AC_DEFUN(@var{macro-name}, @var{macro-body})
10334 You can refer to any arguments passed to the macro as @samp{$1},
10335 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10336 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10338 Be sure to properly quote both the @var{macro-body} @emph{and} the
10339 @var{macro-name} to avoid any problems if the macro happens to have
10340 been previously defined.
10342 Each macro should have a header comment that gives its prototype, and a
10343 brief description. When arguments have default values, display them in
10344 the prototype. For example:
10347 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10348 # --------------------------------------
10349 m4_define([AC_MSG_ERROR],
10350 [@{ AS_MESSAGE([error: $1], [2])
10351 exit m4_default([$2], [1]); @}])
10354 Comments about the macro should be left in the header comment. Most
10355 other comments make their way into @file{configure}, so just keep
10356 using @samp{#} to introduce comments.
10359 If you have some special comments about pure M4 code, comments
10360 that make no sense in @file{configure} and in the header comment, then
10361 use the builtin @code{dnl}: it causes M4 to discard the text
10362 through the next newline.
10364 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10365 @code{dnl} is more useful to get rid of the newlines following macros
10366 that produce no output, such as @code{AC_REQUIRE}.
10370 @section Macro Names
10372 All of the Autoconf macros have all-uppercase names starting with
10373 @samp{AC_} to prevent them from accidentally conflicting with other
10374 text. All shell variables that they use for internal purposes have
10375 mostly-lowercase names starting with @samp{ac_}. To ensure that your
10376 macros don't conflict with present or future Autoconf macros, you should
10377 prefix your own macro names and any shell variables they use with some
10378 other sequence. Possibilities include your initials, or an abbreviation
10379 for the name of your organization or software package.
10381 Most of the Autoconf macros' names follow a structured naming convention
10382 that indicates the kind of feature check by the name. The macro names
10383 consist of several words, separated by underscores, going from most
10384 general to most specific. The names of their cache variables use the
10385 same convention (@pxref{Cache Variable Names}, for more information on
10388 The first word of the name after @samp{AC_} usually tells the category
10389 of the feature being tested. Here are the categories used in Autoconf for
10390 specific test macros, the kind of macro that you are more likely to
10391 write. They are also used for cache variables, in all-lowercase. Use
10392 them where applicable; where they're not, invent your own categories.
10396 C language builtin features.
10398 Declarations of C variables in header files.
10400 Functions in libraries.
10402 Posix group owners of files.
10408 Absolute names of files, including programs.
10410 The base names of programs.
10412 Members of aggregates.
10414 Operating system features.
10416 C builtin or declared types.
10418 C variables in libraries.
10421 After the category comes the name of the particular feature being
10422 tested. Any further words in the macro name indicate particular aspects
10423 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
10424 C compiler supports @acronym{ISO} Standard C.
10426 An internal macro should have a name that starts with an underscore;
10427 Autoconf internals should therefore start with @samp{_AC_}.
10428 Additionally, a macro that is an internal subroutine of another macro
10429 should have a name that starts with an underscore and the name of that
10430 other macro, followed by one or more words saying what the internal
10431 macro does. For example, @code{AC_PATH_X} has internal macros
10432 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10434 @node Reporting Messages
10435 @section Reporting Messages
10436 @cindex Messages, from @command{autoconf}
10438 When macros statically diagnose abnormal situations, benign or fatal,
10439 they should report them using these macros. For dynamic issues, i.e.,
10440 when @command{configure} is run, see @ref{Printing Messages}.
10442 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10444 Report @var{message} as a warning (or as an error if requested by the
10445 user) if warnings of the @var{category} are turned on. You are
10446 encouraged to use standard categories, which currently include:
10450 messages that don't fall into one of the following categories. Use of an
10451 empty @var{category} is equivalent.
10454 related to cross compilation issues.
10457 use of an obsolete construct.
10460 dubious syntactic constructs, incorrectly ordered macro calls.
10464 @defmac AC_WARNING (@var{message})
10466 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10467 strongly encouraged to use a finer grained category.
10470 @defmac AC_FATAL (@var{message})
10472 Report a severe error @var{message}, and have @command{autoconf} die.
10475 When the user runs @samp{autoconf -W error}, warnings from
10476 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10477 @ref{autoconf Invocation}.
10479 @node Dependencies Between Macros
10480 @section Dependencies Between Macros
10481 @cindex Dependencies between macros
10483 Some Autoconf macros depend on other macros having been called first in
10484 order to work correctly. Autoconf provides a way to ensure that certain
10485 macros are called if needed and a way to warn the user if macros are
10486 called in an order that might cause incorrect operation.
10489 * Prerequisite Macros:: Ensuring required information
10490 * Suggested Ordering:: Warning about possible ordering problems
10491 * One-Shot Macros:: Ensuring a macro is called only once
10494 @node Prerequisite Macros
10495 @subsection Prerequisite Macros
10496 @cindex Prerequisite macros
10497 @cindex Macros, prerequisites
10499 A macro that you write might need to use values that have previously
10500 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10501 examines the output of @code{flex} or @code{lex}, so it depends on
10502 @code{AC_PROG_LEX} having been called first to set the shell variable
10505 Rather than forcing the user of the macros to keep track of the
10506 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10507 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10508 called if it is needed, and only called once.
10510 @defmac AC_REQUIRE (@var{macro-name})
10512 If the M4 macro @var{macro-name} has not already been called, call it
10513 (without any arguments). Make sure to quote @var{macro-name} with
10514 square brackets. @var{macro-name} must have been defined using
10515 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10516 that it has been called.
10518 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10519 must not be called from the top level.
10522 @code{AC_REQUIRE} is often misunderstood. It really implements
10523 dependencies between macros in the sense that if one macro depends upon
10524 another, the latter is expanded @emph{before} the body of the
10525 former. To be more precise, the required macro is expanded before
10526 the outermost defined macro in the current expansion stack.
10527 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10528 @code{FOO}. For instance, this definition of macros:
10532 AC_DEFUN([TRAVOLTA],
10533 [test "$body_temperature_in_celsius" -gt "38" &&
10534 dance_floor=occupied])
10535 AC_DEFUN([NEWTON_JOHN],
10536 [test "$hair_style" = "curly" &&
10537 dance_floor=occupied])
10541 AC_DEFUN([RESERVE_DANCE_FLOOR],
10542 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10543 AC_REQUIRE([TRAVOLTA])
10544 AC_REQUIRE([NEWTON_JOHN])
10550 with this @file{configure.ac}
10553 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10554 RESERVE_DANCE_FLOOR
10555 if test "$dance_floor" = occupied; then
10556 AC_MSG_ERROR([cannot pick up here, let's move])
10561 does not leave you with a better chance to meet a kindred soul at
10562 other times than Saturday night since it expands into:
10566 test "$body_temperature_in_Celsius" -gt "38" &&
10567 dance_floor=occupied
10568 test "$hair_style" = "curly" &&
10569 dance_floor=occupied
10571 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10578 This behavior was chosen on purpose: (i) it prevents messages in
10579 required macros from interrupting the messages in the requiring macros;
10580 (ii) it avoids bad surprises when shell conditionals are used, as in:
10585 AC_REQUIRE([SOME_CHECK])
10592 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10593 enforce expansion of required macros outside of shell conditional
10594 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10595 at the beginning of a macro. You can use @code{dnl} to avoid the empty
10598 @node Suggested Ordering
10599 @subsection Suggested Ordering
10600 @cindex Macros, ordering
10601 @cindex Ordering macros
10603 Some macros should be run before another macro if both are called, but
10604 neither @emph{requires} that the other be called. For example, a macro
10605 that changes the behavior of the C compiler should be called before any
10606 macros that run the C compiler. Many of these dependencies are noted in
10609 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10610 with this kind of dependency appear out of order in a
10611 @file{configure.ac} file. The warning occurs when creating
10612 @command{configure} from @file{configure.ac}, not when running
10613 @command{configure}.
10615 For example, @code{AC_PROG_CPP} checks whether the C compiler
10616 can run the C preprocessor when given the @option{-E} option. It should
10617 therefore be called after any macros that change which C compiler is
10618 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
10621 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10625 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10626 when @code{AC_PROG_CC} is called.
10628 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10630 Make M4 print a warning message to the standard error output if
10631 @var{called-macro-name} has already been called. @var{this-macro-name}
10632 should be the name of the macro that is calling @code{AC_BEFORE}. The
10633 macro @var{called-macro-name} must have been defined using
10634 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10635 that it has been called.
10638 @node One-Shot Macros
10639 @subsection One-Shot Macros
10640 @cindex One-shot macros
10641 @cindex Macros, called once
10643 Some macros should be called only once, either because calling them
10644 multiple time is unsafe, or because it is bad style. For instance
10645 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10646 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10647 sense to run these expensive checks more than once. Such one-shot
10648 macros can be defined using @code{AC_DEFUN_ONCE}.
10650 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10651 @acindex{DEFUN_ONCE}
10653 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10654 Definitions}), and emit a warning any time the macro is called more than
10658 Obviously it is not sensible to evaluate a macro defined by
10659 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10660 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10663 @node Obsoleting Macros
10664 @section Obsoleting Macros
10665 @cindex Obsoleting macros
10666 @cindex Macros, obsoleting
10668 Configuration and portability technology has evolved over the years.
10669 Often better ways of solving a particular problem are developed, or
10670 ad-hoc approaches are systematized. This process has occurred in many
10671 parts of Autoconf. One result is that some of the macros are now
10672 considered @dfn{obsolete}; they still work, but are no longer considered
10673 the best thing to do, hence they should be replaced with more modern
10674 macros. Ideally, @command{autoupdate} should replace the old macro calls
10675 with their modern implementation.
10677 Autoconf provides a simple means to obsolete a macro.
10679 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10681 Define @var{old-macro} as @var{implementation}. The only difference
10682 with @code{AC_DEFUN} is that the user is warned that
10683 @var{old-macro} is now obsolete.
10685 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10686 replaced by the modern @var{implementation}. @var{message} should
10687 include information on what to do after running @command{autoupdate};
10688 @command{autoupdate} prints it as a warning, and includes it
10689 in the updated @file{configure.ac} file.
10691 The details of this macro are hairy: if @command{autoconf} encounters an
10692 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10693 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
10694 macros are expanded here, while all other macros are disabled and
10695 appear literally in the updated @file{configure.ac}.
10698 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10700 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10701 with the same parameters. This happens for example if the macro was renamed.
10705 @section Coding Style
10706 @cindex Coding style
10708 The Autoconf macros follow a strict coding style. You are encouraged to
10709 follow this style, especially if you intend to distribute your macro,
10710 either by contributing it to Autoconf itself, or via other means.
10712 The first requirement is to pay great attention to the quotation. For
10713 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10715 Do not try to invent new interfaces. It is likely that there is a macro
10716 in Autoconf that resembles the macro you are defining: try to stick to
10717 this existing interface (order of arguments, default values, etc.). We
10718 @emph{are} conscious that some of these interfaces are not perfect;
10719 nevertheless, when harmless, homogeneity should be preferred over
10722 Be careful about clashes both between M4 symbols and between shell
10725 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10726 you are unlikely to generate conflicts. Nevertheless, when you need to
10727 set a special value, @emph{avoid using a regular macro name}; rather,
10728 use an ``impossible'' name. For instance, up to version 2.13, the macro
10729 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10730 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10731 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10732 impossible to @samp{AC_SUBST(FILE)}! In this case,
10733 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10734 have been used (yes, with the parentheses).
10735 @c or better yet, high-level macros such as @code{m4_expand_once}
10737 No Autoconf macro should ever enter the user-variable name space; i.e.,
10738 except for the variables that are the actual result of running the
10739 macro, all shell variables should start with @code{ac_}. In
10740 addition, small macros or any macro that is likely to be embedded in
10741 other macros should be careful not to use obvious names.
10744 Do not use @code{dnl} to introduce comments: most of the comments you
10745 are likely to write are either header comments which are not output
10746 anyway, or comments that should make their way into @file{configure}.
10747 There are exceptional cases where you do want to comment special M4
10748 constructs, in which case @code{dnl} is right, but keep in mind that it
10751 M4 ignores the leading blanks and newlines before each argument.
10752 Use this feature to
10753 indent in such a way that arguments are (more or less) aligned with the
10754 opening parenthesis of the macro being called. For instance, instead of
10757 AC_CACHE_CHECK(for EMX OS/2 environment,
10759 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10760 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10767 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10768 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10769 [ac_cv_emxos2=yes],
10770 [ac_cv_emxos2=no])])
10777 AC_CACHE_CHECK([for EMX OS/2 environment],
10779 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10780 [return __EMX__;])],
10781 [ac_cv_emxos2=yes],
10782 [ac_cv_emxos2=no])])
10785 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10786 cross-compiling, provide a pessimistic value (typically @samp{no}).
10788 Feel free to use various tricks to prevent auxiliary tools, such as
10789 syntax-highlighting editors, from behaving improperly. For instance,
10793 m4_bpatsubst([$1], [$"])
10800 m4_bpatsubst([$1], [$""])
10804 so that Emacsen do not open an endless ``string'' at the first quote.
10805 For the same reasons, avoid:
10815 test $[@@%:@@] != 0
10819 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10820 breaking the bracket-matching highlighting from Emacsen. Note the
10821 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
10822 not escape when it is unnecessary. Common examples of useless quotation
10823 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10824 etc. If you add portability issues to the picture, you'll prefer
10825 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10826 better than hacking Autoconf @code{:-)}.
10828 When using @command{sed}, don't use @option{-e} except for indenting
10829 purposes. With the @code{s} and @code{y} commands, the preferred
10830 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10831 or replacement, in which case you should use @samp{|}, or optionally
10832 @samp{,} if you know the pattern and replacement cannot contain a file
10833 name. If none of these characters will do, choose a printable character
10834 that cannot appear in the pattern or replacement. Characters from the
10835 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10836 replacement might contain a file name, since they have special meaning
10837 to the shell and are less likely to occur in file names.
10839 @xref{Macro Definitions}, for details on how to define a macro. If a
10840 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10841 of an @code{AC_REQUIRE} directive, and macros required by other macros
10842 inside arguments do not need to be expanded before this macro, then
10843 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
10844 All the @code{AC_REQUIRE} statements should be at the beginning of the
10845 macro, and each statement should be followed by @code{dnl}.
10847 You should not rely on the number of arguments: instead of checking
10848 whether an argument is missing, test that it is not empty. It provides
10849 both a simpler and a more predictable interface to the user, and saves
10850 room for further arguments.
10852 Unless the macro is short, try to leave the closing @samp{])} at the
10853 beginning of a line, followed by a comment that repeats the name of the
10854 macro being defined. This introduces an additional newline in
10855 @command{configure}; normally, that is not a problem, but if you want to
10856 remove it you can use @samp{[]dnl} on the last line. You can similarly
10857 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
10858 is recommended instead of @samp{dnl} to ensure that M4 does not
10859 interpret the @samp{dnl} as being attached to the preceding text or
10860 macro output. For example, instead of:
10863 AC_DEFUN([AC_PATH_X],
10864 [AC_MSG_CHECKING([for X])
10866 @r{# @dots{}omitted@dots{}}
10867 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10875 AC_DEFUN([AC_PATH_X],
10876 [AC_REQUIRE_CPP()[]dnl
10877 AC_MSG_CHECKING([for X])
10878 @r{# @dots{}omitted@dots{}}
10879 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10884 If the macro is long, try to split it into logical chunks. Typically,
10885 macros that check for a bug in a function and prepare its
10886 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10887 this setup. Do not hesitate to introduce auxiliary macros to factor
10890 In order to highlight the recommended coding style, here is a macro
10891 written the old way:
10894 dnl Check for EMX on OS/2.
10896 AC_DEFUN(_AC_EMXOS2,
10897 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10898 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10899 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10900 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10909 # Check for EMX on OS/2.
10910 m4_define([_AC_EMXOS2],
10911 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10912 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10913 [ac_cv_emxos2=yes],
10914 [ac_cv_emxos2=no])])
10915 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10922 @c ============================================= Portable Shell Programming
10924 @node Portable Shell
10925 @chapter Portable Shell Programming
10926 @cindex Portable shell programming
10928 When writing your own checks, there are some shell-script programming
10929 techniques you should avoid in order to make your code portable. The
10930 Bourne shell and upward-compatible shells like the Korn shell and Bash
10931 have evolved over the years, but to prevent trouble, do not take
10932 advantage of features that were added after Unix version 7, circa
10933 1977 (@pxref{Systemology}).
10935 You should not use shell functions, aliases, negated character
10936 classes, or other features that are not found in all Bourne-compatible
10937 shells; restrict yourself to the lowest common denominator. Even
10938 @code{unset} is not supported by all shells!
10940 Some ancient systems have quite
10941 small limits on the length of the @samp{#!} line; for instance, 32
10942 bytes (not including the newline) on SunOS 4.
10943 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10944 required a single space between the @samp{#!} and the @samp{/}.
10945 However, these ancient systems are no longer of practical concern.
10947 The set of external programs you should run in a @command{configure} script
10948 is fairly small. @xref{Utilities in Makefiles, , Utilities in
10949 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
10950 restriction allows users to start out with a fairly small set of
10951 programs and build the rest, avoiding too many interdependencies between
10954 Some of these external utilities have a portable subset of features; see
10955 @ref{Limitations of Usual Tools}.
10957 There are other sources of documentation about shells. The
10958 specification for the Posix
10959 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10960 Command Language}, though more generous than the restrictive shell
10961 subset described above, is fairly portable nowadays. Also please see
10962 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10965 * Shellology:: A zoology of shells
10966 * Here-Documents:: Quirks and tricks
10967 * File Descriptors:: FDs and redirections
10968 * File System Conventions:: File names
10969 * Shell Substitutions:: Variable and command expansions
10970 * Assignments:: Varying side effects of assignments
10971 * Parentheses:: Parentheses in shell scripts
10972 * Slashes:: Slashes in shell scripts
10973 * Special Shell Variables:: Variables you should not change
10974 * Limitations of Builtins:: Portable use of not so portable /bin/sh
10975 * Limitations of Usual Tools:: Portable use of portable tools
10979 @section Shellology
10982 There are several families of shells, most prominently the Bourne family
10983 and the C shell family which are deeply incompatible. If you want to
10984 write portable shell scripts, avoid members of the C shell family. The
10985 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10986 Shell difference FAQ} includes a small history of Posix shells, and a
10987 comparison between several of them.
10989 Below we describe some of the members of the Bourne shell family.
10994 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10995 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
10996 bugs that are fixed in the 0.3.x series, but portable shell scripts
10997 should work around them, since version 0.2 is still shipped with many
10998 @acronym{GNU}/Linux distributions.
11000 To be compatible with Ash 0.2:
11004 don't use @samp{$?} after expanding empty or unset variables,
11005 or at the start of an @command{eval}:
11011 echo "Do not use it: $?"
11013 eval 'echo "Do not use it: $?"'
11017 don't use command substitution within variable expansion:
11024 beware that single builtin substitutions are not performed by a
11025 subshell, hence their effect applies to the current shell! @xref{Shell
11026 Substitutions}, item ``Command Substitution''.
11031 To detect whether you are running Bash, test whether
11032 @code{BASH_VERSION} is set. To require
11033 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
11034 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11035 Manual}, for details.
11037 @item Bash 2.05 and later
11038 @cindex Bash 2.05 and later
11039 Versions 2.05 and later of Bash use a different format for the
11040 output of the @command{set} builtin, designed to make evaluating its
11041 output easier. However, this output is not compatible with earlier
11042 versions of Bash (or with many other shells, probably). So if
11043 you use Bash 2.05 or higher to execute @command{configure},
11044 you'll need to use Bash 2.05 for all other build tasks as well.
11049 @prindex @samp{ksh}
11050 @prindex @samp{ksh88}
11051 @prindex @samp{ksh93}
11052 The Korn shell is compatible with the Bourne family and it mostly
11053 conforms to Posix. It has two major variants commonly
11054 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11055 release. It is usually called @command{ksh}, but is called @command{sh}
11056 on some hosts if you set your path appropriately.
11058 Solaris systems have three variants:
11059 @prindex @command{/usr/bin/ksh} on Solaris
11060 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11061 standard on Solaris 2.0 and later.
11062 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11063 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11064 @samp{ksh88}; it is standard on Solaris 9 and later.
11065 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11066 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11067 Variants that are not standard may be parts of optional
11068 packages. There is no extra charge for these packages, but they are
11069 not part of a minimal OS install and therefore some installations may
11072 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11073 is also available as @command{/usr/bin/posix/sh}. If the environment
11074 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11075 the standard shell conform to Posix.
11078 @prindex @samp{pdksh}
11079 A public-domain clone of the Korn shell called @command{pdksh} is widely
11080 available: it has most of the @samp{ksh88} features along with a few of
11081 its own. It usually sets @code{KSH_VERSION}, except if invoked as
11082 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11083 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
11084 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
11085 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11086 at least one respect:
11089 $ @kbd{echo "`echo \"hello\"`"}
11091 $ @kbd{set -o posix}
11092 $ @kbd{echo "`echo \"hello\"`"}
11096 The last line of output contains spurious quotes. This is yet another
11097 reason why portable shell code should not contain
11098 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11103 To detect whether you are running @command{zsh}, test whether
11104 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
11105 compatible with the Bourne shell: you must execute @samp{emulate sh},
11106 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11107 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
11108 zsh, The Z Shell Manual}, for details.
11110 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11111 Bash in Mac OS X 10.2.
11114 The following discussion between Russ Allbery and Robert Lipe is worth
11121 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11122 leads to a permanent deadlock. Vendors don't want to break users'
11123 existing shell scripts, and there are some corner cases in the Bourne
11124 shell that are not completely compatible with a Posix shell. Thus,
11125 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11126 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11134 This is exactly the problem. While most (at least most System V's) do
11135 have a Bourne shell that accepts shell functions most vendor
11136 @command{/bin/sh} programs are not the Posix shell.
11138 So while most modern systems do have a shell @emph{somewhere} that meets the
11139 Posix standard, the challenge is to find it.
11142 @node Here-Documents
11143 @section Here-Documents
11144 @cindex Here-documents
11145 @cindex Shell here-documents
11147 Don't rely on @samp{\} being preserved just because it has no special
11148 meaning together with the next symbol. In the native @command{sh}
11149 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11150 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11151 use @samp{\\} to get @samp{\}.
11153 With Open@acronym{BSD} 2.7's @command{sh}
11169 bash-2.04$ @kbd{cat <<EOF
11176 Some shells mishandle large here-documents: for example,
11177 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11178 derived from Korn shell version M-12/28/93d, mishandle braced variable
11179 expansion that crosses a 1024- or 4096-byte buffer boundary
11180 within a here-document. Only the part of the variable name after the boundary
11181 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11182 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11183 boundary, the shell reports an error, as if you used @code{$@{@}}.
11184 Instead of @code{$@{variable-default@}}, the shell may expand
11185 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11186 be worked around by omitting the braces: @code{$variable}. The bug was fixed in
11187 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11188 still shipping older versions with the bug.
11190 Many older shells (including the Bourne shell) implement here-documents
11191 inefficiently. In particular, some shells can be extremely inefficient when
11192 a single statement contains many here-documents. For instance if your
11193 @file{configure.ac} includes something like:
11197 if <cross_compiling>; then
11198 assume this and that
11202 check something else
11210 A shell parses the whole @code{if}/@code{fi} construct, creating
11211 temporary files for each here-document in it. Some shells create links
11212 for such here-documents on every @code{fork}, so that the clean-up code
11213 they had installed correctly removes them. It is creating the links
11214 that can take the shell forever.
11216 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11217 @code{if}/@code{fi} constructs, would improve the performance
11218 significantly. Anyway, this kind of construct is not exactly the
11219 typical use of Autoconf. In fact, it's even not recommended, because M4
11220 macros can't look into shell conditionals, so we may fail to expand a
11221 macro when it was expanded before in a conditional path, and the
11222 condition turned out to be false at runtime, and we end up not
11223 executing the macro at all.
11225 @node File Descriptors
11226 @section File Descriptors
11227 @cindex Descriptors
11228 @cindex File descriptors
11229 @cindex Shell file descriptors
11231 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11232 stderr, even for subshells. This might result in undesirable content
11233 if you meant to capture the standard-error output of the inner command:
11236 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11238 + eval echo foo >&2
11241 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11243 + eval 'echo foo >&2'
11246 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11247 @i{# Traces on startup files deleted here.}
11249 +zsh:1> eval echo foo >&2
11255 One workaround is to grep out uninteresting lines, hoping not to remove
11258 If you intend to redirect both standard error and standard output,
11259 redirect standard output first. This works better with @acronym{HP-UX},
11260 since its shell mishandles tracing if standard error is redirected
11264 $ @kbd{sh -x -c ': 2>err >out'}
11266 + 2> err $ @kbd{cat err}
11270 Don't try to redirect the standard error of a command substitution. It
11271 must be done @emph{inside} the command substitution. When running
11272 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11273 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11275 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11276 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11278 Don't redirect the same file descriptor several times, as you are doomed
11279 to failure under Ultrix.
11282 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11284 $ @kbd{eval 'echo matter >fullness' >void}
11286 $ @kbd{eval '(echo matter >fullness)' >void}
11288 $ @kbd{(eval '(echo matter >fullness)') >void}
11289 Ambiguous output redirect.
11293 In each case the expected result is of course @file{fullness} containing
11294 @samp{matter} and @file{void} being empty.
11296 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11297 subsidiary program. If any of these descriptors is closed, the
11298 operating system may open an unspecified file for the descriptor in the
11299 new process image. Posix says this may be done only if the subsidiary
11300 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11303 Don't rely on open file descriptors being open in child processes. In
11304 @command{ksh}, file descriptors above 2 which are opened using
11305 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11306 that involved in the fork-and-exec which runs a program or script).
11307 Thus, using @command{sh}, we have:
11310 $ @kbd{cat ./descrips}
11332 Within the process which runs the @samp{descrips} script, file
11333 descriptor 5 is closed.
11335 @acronym{DOS} variants cannot rename or remove open files, such as in
11336 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11337 perfectly portable among Posix hosts.
11339 A few ancient systems reserved some file descriptors. By convention,
11340 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11341 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11342 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11343 1990), though we don't now remember what it was. Both these systems are
11344 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11345 other file descriptors.
11347 @node File System Conventions
11348 @section File System Conventions
11349 @cindex File system conventions
11351 Autoconf uses shell-script processing extensively, so the file names
11352 that it processes should not contain characters that are special to the
11353 shell. Special characters include space, tab, newline, @sc{nul}, and
11357 " # $ & ' ( ) * ; < = > ? [ \ ` |
11360 Also, file names should not begin with @samp{~} or @samp{-}, and should
11361 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11362 immediately after @samp{:}. On Posix-like platforms, directory names
11363 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11366 These restrictions apply not only to the files that you distribute, but
11367 also to the absolute file names of your source, build, and destination
11370 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11371 they should be avoided.
11373 Posix lets implementations treat leading @file{//} specially, but
11374 requires leading @file{///} and beyond to be equivalent to @file{/}.
11375 Most Unix variants treat @file{//} like @file{/}. However, some treat
11376 @file{//} as a ``super-root'' that can provide access to files that are
11377 not otherwise reachable from @file{/}. The super-root tradition began
11378 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11381 While @command{autoconf} and friends are usually run on some Posix
11382 variety, they can be used on other systems, most notably @acronym{DOS}
11383 variants. This impacts several assumptions regarding file names.
11386 For example, the following code:
11393 foo_dir=$dots$foo_dir ;;
11398 fails to properly detect absolute file names on those systems, because
11399 they can use a drivespec, and usually use a backslash as directory
11400 separator. If you want to be portable to @acronym{DOS} variants (at the
11401 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11402 you can check for absolute file names like this:
11406 [\\/]* | ?:[\\/]* ) # Absolute
11409 foo_dir=$dots$foo_dir ;;
11414 Make sure you quote the brackets if appropriate and keep the backslash as
11415 first character (@pxref{Limitations of Builtins}).
11417 Also, because the colon is used as part of a drivespec, these systems don't
11418 use it as path separator. When creating or accessing paths, you can use the
11419 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11420 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
11423 File names need extra care as well. While @acronym{DOS} variants
11424 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11425 are usually able to handle long file names properly, there are still
11426 limitations that can seriously break packages. Several of these issues
11427 can be easily detected by the
11428 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11431 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11432 indicate where they apply: @sc{sfn} means the issues are only relevant to
11433 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11434 variants, while @sc{lfn} identifies problems that exist even under
11435 Microsoft Windows variants.
11438 @item No multiple dots (@sc{sfn})
11439 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11440 important thing to remember when building a portable configure script,
11441 as @command{autoconf} uses a .in suffix for template files.
11443 This is perfectly OK on Posix variants:
11446 AC_CONFIG_HEADERS([config.h])
11447 AC_CONFIG_FILES([source.c foo.bar])
11452 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11453 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11454 to @acronym{DOS}-based environments, you should use this instead:
11457 AC_CONFIG_HEADERS([config.h:config.hin])
11458 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11462 @item No leading dot (@sc{sfn})
11463 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11464 not important for @command{autoconf}.
11466 @item Case insensitivity (@sc{lfn})
11467 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11468 file called @samp{INSTALL} and a directory called @samp{install}. This
11469 also affects @command{make}; if there's a file called @samp{INSTALL} in
11470 the directory, @samp{make install} does nothing (unless the
11471 @samp{install} target is marked as PHONY).
11473 @item The 8+3 limit (@sc{sfn})
11474 Because the @acronym{DOS} file system only stores the first 8 characters of
11475 the file name and the first 3 of the extension, those must be unique.
11476 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11477 @file{foobar-prettybird.c} all resolve to the same file name
11478 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11479 @file{foo.bartender}.
11481 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11483 tails in the short version of file names to make them unique. However, a
11484 registry setting can turn this behavior off. While this makes it
11485 possible to share file trees containing long file names between @sc{sfn}
11486 and @sc{lfn} environments, it also means the above problem applies there
11489 @item Invalid characters (@sc{lfn})
11490 Some characters are invalid in @acronym{DOS} file names, and should therefore
11491 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11492 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11493 In a @sc{sfn} environment, other characters are also invalid. These
11494 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11496 @item Invalid names (@sc{lfn})
11497 Some @acronym{DOS} file names are reserved, and cause problems if you
11498 try to use files with those names. These names include @file{CON},
11499 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11500 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11501 File names are case insensitive, so even names like
11502 @file{aux/config.guess} are disallowed.
11506 @node Shell Substitutions
11507 @section Shell Substitutions
11508 @cindex Shell substitutions
11510 Contrary to a persistent urban legend, the Bourne shell does not
11511 systematically split variables and back-quoted expressions, in particular
11512 on the right-hand side of assignments and in the argument of @code{case}.
11513 For instance, the following code:
11516 case "$given_srcdir" in
11517 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11518 *) top_srcdir="$dots$given_srcdir" ;;
11523 is more readable when written as:
11526 case $given_srcdir in
11527 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11528 *) top_srcdir=$dots$given_srcdir ;;
11533 and in fact it is even @emph{more} portable: in the first case of the
11534 first attempt, the computation of @code{top_srcdir} is not portable,
11535 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11536 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11537 the same way. There is just no portable way to use double-quoted
11538 strings inside double-quoted back-quoted expressions (pfew!).
11542 @cindex @samp{"$@@"}
11543 One of the most famous shell-portability issues is related to
11544 @samp{"$@@"}. When there are no positional arguments, Posix says
11545 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11546 original Unix version 7 Bourne shell treated it as equivalent to
11547 @samp{""} instead, and this behavior survives in later implementations
11548 like Digital Unix 5.0.
11550 The traditional way to work around this portability problem is to use
11551 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
11552 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
11553 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11556 zsh $ @kbd{emulate sh}
11557 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11560 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11567 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11568 @samp{"$@@"} because of the portability problems mentioned above.
11569 One workaround relies on Zsh's ``global aliases'' to convert
11570 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11573 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11576 A more conservative workaround is to avoid @samp{"$@@"} if it is
11577 possible that there may be no positional arguments. For example,
11581 cat conftest.c "$@@"
11584 you can use this instead:
11588 0) cat conftest.c;;
11589 *) cat conftest.c "$@@";;
11593 Autoconf macros often use the @command{set} command to update
11594 @samp{$@@}, so if you are writing shell code intended for
11595 @command{configure} you should not assume that the value of @samp{$@@}
11596 persists for any length of time.
11600 @cindex positional parameters
11601 The 10th, 11th, @dots{} positional parameters can be accessed only after
11602 a @code{shift}. The 7th Edition shell reported an error if given
11603 @code{$@{10@}}, and
11604 Solaris 10 @command{/bin/sh} still acts that way:
11607 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11608 $ @kbd{echo $@{10@}}
11612 @item $@{@var{var}:-@var{value}@}
11613 @c Info cannot handle `:' in index entries.
11614 @c @cindex $@{@var{var}:-@var{value}@}
11615 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11616 colon for any shell substitution, and complain and die.
11617 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
11619 @item $@{@var{var}=@var{literal}@}
11620 @cindex $@{@var{var}=@var{literal}@}
11624 : $@{var='Some words'@}
11628 otherwise some shells, such as on Digital Unix V 5.0, die because
11629 of a ``bad substitution''.
11633 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11634 of this. Imagine you need set a variable to a string containing
11635 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
11636 when the affected variable was already set. This bug can be exercised
11641 $ @kbd{foo=$@{foo='@}'@}}
11644 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
11647 $ @kbd{foo=$@{foo='@}'@}}
11653 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11654 though it is enclosed in single quotes. The problem doesn't happen
11655 using double quotes.
11657 @item $@{@var{var}=@var{expanded-value}@}
11658 @cindex $@{@var{var}=@var{expanded-value}@}
11664 : $@{var="$default"@}
11668 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11669 each char is set. You don't observe the phenomenon using a simple
11670 @samp{echo $var} since apparently the shell resets the 8th bit when it
11671 expands $var. Here are two means to make this shell confess its sins:
11674 $ @kbd{cat -v <<EOF
11683 $ @kbd{set | grep '^var=' | cat -v}
11686 One classic incarnation of this bug is:
11690 : $@{list="$default"@}
11697 You'll get @samp{a b c} on a single line. Why? Because there are no
11698 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11699 bit set, hence no IFS splitting is performed!!!
11701 One piece of good news is that Ultrix works fine with @samp{:
11702 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
11703 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11706 The portable way out consists in using a double assignment, to switch
11707 the 8th bit twice on Ultrix:
11710 list=$@{list="$default"@}
11714 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
11718 test "$@{var+set@}" = set || var=@var{@{value@}}
11721 @item $@{#@var{var}@}
11722 @itemx $@{@var{var}%@var{word}@}
11723 @itemx $@{@var{var}%%@var{word}@}
11724 @itemx $@{@var{var}#@var{word}@}
11725 @itemx $@{@var{var}##@var{word}@}
11726 @cindex $@{#@var{var}@}
11727 @cindex $@{@var{var}%@var{word}@}
11728 @cindex $@{@var{var}%%@var{word}@}
11729 @cindex $@{@var{var}#@var{word}@}
11730 @cindex $@{@var{var}##@var{word}@}
11731 Posix requires support for these usages, but they do not work with many
11732 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
11734 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
11735 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
11736 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
11737 yields the empty string.
11740 @item `@var{commands}`
11741 @cindex `@var{commands}`
11742 @cindex Command Substitution
11743 Posix requires shells to trim all trailing newlines from command
11744 output before substituting it, so assignments like
11745 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11746 @samp{$file} ends in a newline.
11748 While in general it makes no sense, do not substitute a single builtin
11749 with side effects, because Ash 0.2, trying to optimize, does not fork a
11750 subshell to perform the command.
11752 For instance, if you wanted to check that @command{cd} is silent, do not
11753 use @samp{test -z "`cd /`"} because the following can happen:
11758 $ @kbd{test -z "`cd /`" && pwd}
11763 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11765 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11766 command substitution of a native program, if the end of the substitution
11767 is not aligned with the end of the double quote. This may be worked
11768 around by inserting another pair of quotes:
11771 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11772 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11773 - broken differ: char 4, line 1
11777 @item $(@var{commands})
11778 @cindex $(@var{commands})
11779 This construct is meant to replace @samp{`@var{commands}`},
11780 and it has most of the problems listed under @code{`@var{commands}`}.
11782 This construct can be
11783 nested while this is impossible to do portably with back quotes.
11784 Unfortunately it is not yet universally supported. Most notably, even recent
11785 releases of Solaris don't support it:
11788 $ @kbd{showrev -c /bin/sh | grep version}
11789 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
11790 $ @kbd{echo $(echo blah)}
11791 syntax error: `(' unexpected
11795 nor does @sc{irix} 6.5's Bourne shell:
11798 IRIX firebird-image 6.5 07151432 IP22
11799 $ @kbd{echo $(echo blah)}
11803 If you do use @samp{$(@var{commands})}, make sure that the commands
11804 do not start with a parenthesis, as that would cause confusion with
11805 a different notation @samp{$((@var{expression}))} that in modern
11806 shells is an arithmetic expression not a command. To avoid the
11807 confusion, insert a space between the two opening parentheses.
11809 Avoid @var{commands} that contain unbalanced parentheses in
11810 here-documents, comments, or case statement patterns, as many shells
11811 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11812 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11815 echo $(case x in x) echo hello;; esac)
11820 Always quote @samp{^}, otherwise traditional shells such as
11821 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11827 @section Assignments
11828 @cindex Shell assignments
11830 When setting several variables in a row, be aware that the order of the
11831 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
11832 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11834 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11836 Don't rely on the following to find @file{subdir/program}:
11839 PATH=subdir$PATH_SEPARATOR$PATH program
11843 as this does not work with Zsh 3.0.6. Use something like this
11847 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11850 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11851 the status and propagates that of the last statement:
11854 $ @kbd{false || foo=bar; echo $?}
11856 $ @kbd{false || foo=`:`; echo $?}
11861 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11865 $ @kbd{foo=`exit 1`; echo $?}
11869 To assign default values, follow this algorithm:
11873 If the default value is a literal and does not contain any closing
11877 : $@{var='my literal'@}
11881 If the default value contains no closing brace, has to be expanded, and
11882 the variable being initialized is not intended to be IFS-split
11883 (i.e., it's not a list), then use:
11886 : $@{var="$default"@}
11890 If the default value contains no closing brace, has to be expanded, and
11891 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11895 var=$@{var="$default"@}
11899 If the default value contains a closing brace, then use:
11902 test "$@{var+set@}" = set || var="has a '@}'"
11906 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11907 doubt, just use the last form. @xref{Shell Substitutions}, items
11908 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11912 @section Parentheses in Shell Scripts
11913 @cindex Shell parentheses
11915 Beware of two opening parentheses in a row, as many shell
11916 implementations treat them specially. Posix requires that the command
11917 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
11918 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
11919 expression equivalent to @samp{let "cat"}, and may or may not report an
11920 error when they detect that @samp{cat} is not a number. As another
11921 example, @samp{pdksh} 5.2.14 misparses the following code:
11924 if ((true) || false); then
11930 To work around this problem, insert a space between the two opening
11931 parentheses. There is a similar problem and workaround with
11932 @samp{$((}; see @ref{Shell Substitutions}.
11934 Posix requires support for @code{case} patterns with opening
11935 parentheses like this:
11939 (*.c) echo "C source code";;
11944 but the @code{(} in this example is not portable to many older Bourne
11945 shell implementations. It can be omitted safely.
11948 @section Slashes in Shell Scripts
11949 @cindex Shell slashes
11951 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11952 arguments that contain two trailing slashes:
11955 $ @kbd{echo / // /// //// .// //.}
11958 $ @kbd{eval "echo \$x"}
11961 $ @kbd{echo abc | tr -t ab //}
11967 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
11968 variable is empty and the second double-quote is followed by a word that
11969 begins and ends with slash:
11972 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
11978 However, our understanding is that patches are available, so perhaps
11979 it's not worth worrying about working around these horrendous bugs.
11981 @node Special Shell Variables
11982 @section Special Shell Variables
11983 @cindex Shell variables
11984 @cindex Special shell variables
11986 Some shell variables should not be used, since they can have a deep
11987 influence on the behavior of the shell. In order to recover a sane
11988 behavior from the shell, some variables should be unset, but
11989 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11990 fallback value is needed.
11992 As a general rule, shell variable names containing a lower-case letter
11993 are safe; you can define and use these variables without worrying about
11994 their effect on the underlying system, and without worrying about
11995 whether the shell changes them unexpectedly. (The exception is the
11996 shell variable @code{status}, as described below.)
11998 Here is a list of names that are known to cause trouble. This list is
11999 not exhaustive, but you should be safe if you avoid the name
12000 @code{status} and names containing only upper-case letters and
12003 @c Alphabetical order, case insensitive, `A' before `a'.
12006 Many shells reserve @samp{$_} for various purposes, e.g., the name of
12007 the last command executed.
12011 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
12012 the standard shell conform to Posix.
12016 When this variable is set it specifies a list of directories to search
12017 when invoking @code{cd} with a relative file name that did not start
12018 with @samp{./} or @samp{../}. Posix
12019 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
12020 is used successfully, @code{cd} prints the resulting absolute
12021 file name. Unfortunately this output can break idioms like
12022 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
12023 Also, many shells do not conform to this part of Posix; for
12024 example, @command{zsh} prints the result only if a directory name
12025 other than @file{.} was chosen from @env{CDPATH}.
12027 In practice the shells that have this problem also support
12028 @command{unset}, so you can work around the problem as follows:
12031 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
12034 You can also avoid output by ensuring that your directory name is
12035 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
12037 Autoconf-generated scripts automatically unset @env{CDPATH} if
12038 possible, so you need not worry about this problem in those scripts.
12042 In the MKS shell, case statements and file name generation are
12043 case-insensitive unless @env{DUALCASE} is nonzero.
12044 Autoconf-generated scripts export this variable when they start up.
12058 These variables should not matter for shell scripts, since they are
12059 supposed to affect only interactive shells. However, at least one
12060 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12061 whether it is interactive, which means that (for example) a @env{PS1}
12062 with a side effect can unexpectedly modify @samp{$?}. To work around
12063 this bug, Autoconf-generated scripts do something like this:
12066 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12074 Long ago, shell scripts inherited @env{IFS} from the environment,
12075 but this caused many problems so modern shells ignore any environment
12076 settings for @env{IFS}.
12078 Don't set the first character of @code{IFS} to backslash. Indeed,
12079 Bourne shells use the first character (backslash) when joining the
12080 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12081 backslash escapes, so you can end up with backspace and other strange
12084 The proper value for @code{IFS} (in regular code, not when performing
12085 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
12086 especially important, as it is used to join the arguments in @samp{$*};
12087 however, note that traditional shells, but also bash-2.04, fail to adhere
12088 to this and join with a space anyway.
12100 @evindex LC_COLLATE
12102 @evindex LC_MESSAGES
12103 @evindex LC_MONETARY
12104 @evindex LC_NUMERIC
12107 Autoconf-generated scripts normally set all these variables to
12108 @samp{C} because so much configuration code assumes the C locale and
12109 Posix requires that locale environment variables be set to
12110 @samp{C} if the C locale is desired. However, some older, nonstandard
12111 systems (notably @acronym{SCO}) break if locale environment variables
12112 are set to @samp{C}, so when running on these systems
12113 Autoconf-generated scripts unset the variables instead.
12118 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12119 extension that overrides @env{LC_ALL} in some cases, so
12120 Autoconf-generated scripts set it too.
12123 @itemx LC_IDENTIFICATION
12124 @itemx LC_MEASUREMENT
12127 @itemx LC_TELEPHONE
12128 @evindex LC_ADDRESS
12129 @evindex LC_IDENTIFICATION
12130 @evindex LC_MEASUREMENT
12133 @evindex LC_TELEPHONE
12135 These locale environment variables are @acronym{GNU} extensions. They
12136 are treated like their Posix brethren (@env{LC_COLLATE},
12137 etc.)@: as described above.
12140 Most modern shells provide the current line number in @code{LINENO}.
12141 Its value is the line number of the beginning of the current command.
12142 Autoconf attempts to execute @command{configure} with a shell that
12143 supports @code{LINENO}.
12144 If no such shell is available, it attempts to implement @code{LINENO}
12145 with a Sed prepass that replaces each instance of the string
12146 @code{$LINENO} (not followed by an alphanumeric character) with the
12149 You should not rely on @code{LINENO} within @command{eval}, as the
12150 behavior differs in practice. Also, the possibility of the Sed
12151 prepass means that you should not rely on @code{$LINENO} when quoted,
12152 when in here-documents, or when in long commands that cross line
12153 boundaries. Subshells should be OK, though. In the following
12154 example, lines 1, 6, and 9 are portable, but the other instances of
12155 @code{LINENO} are not:
12165 ( echo 6. $LINENO )
12166 eval 'echo 7. $LINENO'
12172 $ @kbd{bash-2.05 lineno}
12183 $ @kbd{zsh-3.0.6 lineno}
12194 $ @kbd{pdksh-5.2.14 lineno}
12205 $ @kbd{sed '=' <lineno |}
12211 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12214 > @kbd{ s,^[0-9]*\n,,}
12230 When executing the command @samp{>foo}, @command{zsh} executes
12231 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12232 compatibility mode and the @command{zsh} version is newer
12233 than 3.1.6-dev-18. If you are using an older @command{zsh}
12234 and forget to set @env{NULLCMD},
12235 your script might be suspended waiting for data on its standard input.
12237 @item PATH_SEPARATOR
12238 @evindex PATH_SEPARATOR
12239 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12240 variable can be set to either @samp{:} or @samp{;} to control the path
12241 separator Bash uses to set up certain environment variables (such as
12242 @env{PATH}). You can set this variable to @samp{;} if you want
12243 @command{configure} to use @samp{;} as a separator; this might be useful
12244 if you plan to use non-Posix shells to execute files. @xref{File System
12245 Conventions}, for more information about @code{PATH_SEPARATOR}.
12249 Posix 1003.1-2001 requires that @command{cd} and
12250 @command{pwd} must update the @env{PWD} environment variable to point
12251 to the logical name of the current directory, but traditional shells
12252 do not support this. This can cause confusion if one shell instance
12253 maintains @env{PWD} but a subsidiary and different shell does not know
12254 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12255 points to the wrong directory. Use @samp{`pwd`} rather than
12259 Many shells provide @code{RANDOM}, a variable that returns a different
12260 integer each time it is used. Most of the time, its value does not
12261 change when it is not used, but on @sc{irix} 6.5 the value changes all
12262 the time. This can be observed by using @command{set}. It is common
12263 practice to use @code{$RANDOM} as part of a file name, but code
12264 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12267 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12268 hence read-only. Do not use it.
12271 @node Limitations of Builtins
12272 @section Limitations of Shell Builtins
12273 @cindex Shell builtins
12274 @cindex Limitations of shell builtins
12276 No, no, we are serious: some shells do have limitations! :)
12278 You should always keep in mind that any builtin or command may support
12279 options, and therefore differ in behavior with arguments
12280 starting with a dash. For instance, the innocent @samp{echo "$word"}
12281 can give unexpected results when @code{word} starts with a dash. It is
12282 often possible to avoid this problem using @samp{echo "x$word"}, taking
12283 the @samp{x} into account later in the pipe.
12287 @prindex @command{.}
12288 Use @command{.} only with regular files (use @samp{test -f}). Bash
12289 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12290 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12291 you want to use @command{.} on a file @file{foo} in the current
12292 directory, you must use @samp{. ./foo}.
12295 @prindex @command{!}
12296 The Unix version 7 shell did not support
12297 negating the exit status of commands with @command{!}, and this feature
12298 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12299 Shell code like this:
12302 if ! cmp file1 file2 >/dev/null 2>&1; then
12303 echo files differ or trouble
12307 is therefore not portable in practice. Typically it is easy to rewrite
12311 cmp file1 file2 >/dev/null 2>&1 ||
12312 echo files differ or trouble
12315 More generally, one can always rewrite @samp{! @var{command}} as:
12318 if @var{command}; then (exit 1); else :; fi
12321 @item @command{break}
12322 @c ------------------
12323 @prindex @command{break}
12324 The use of @samp{break 2} etc.@: is safe.
12327 @item @command{case}
12328 @c -----------------
12329 @prindex @command{case}
12330 You don't need to quote the argument; no splitting is performed.
12332 You don't need the final @samp{;;}, but you should use it.
12334 Because of a bug in its @code{fnmatch}, Bash fails to properly
12335 handle backslashes in character classes:
12338 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12343 This is extremely unfortunate, since you are likely to use this code to
12344 handle Posix or @sc{ms-dos} absolute file names. To work around this
12345 bug, always put the backslash first:
12348 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12350 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12354 Many Bourne shells cannot handle closing brackets in character classes
12357 Some shells also have problems with backslash escaping in case you do not want
12358 to match the backslash: both a backslash and the escaped character match this
12359 pattern. To work around this, specify the character class in a variable, so
12360 that quote removal does not apply afterwards, and the special characters don't
12361 have to be backslash-escaped:
12364 $ @kbd{case '\' in [\<]) echo OK;; esac}
12366 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12370 Even with this, Solaris @command{ksh} matches a backslash if the set
12372 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12374 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12375 a closing parenthesis if not specified in a character class:
12378 $ @kbd{case foo in *\)*) echo fail ;; esac}
12380 $ @kbd{case foo in *')'*) echo fail ;; esac}
12384 Some shells, such as Ash 0.3.8, are confused by an empty
12385 @code{case}/@code{esac}:
12388 ash-0.3.8 $ @kbd{case foo in esac;}
12389 @error{}Syntax error: ";" unexpected (expecting ")")
12392 Many shells still do not support parenthesized cases, which is a pity
12393 for those of us using tools that rely on balanced parentheses. For
12394 instance, Solaris @command{/bin/sh}:
12397 $ @kbd{case foo in (foo) echo foo;; esac}
12398 @error{}syntax error: `(' unexpected
12404 @prindex @command{cd}
12405 Posix 1003.1-2001 requires that @command{cd} must support
12406 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12407 with @option{-L} being the default. However, traditional shells do
12408 not support these options, and their @command{cd} command has the
12409 @option{-P} behavior.
12411 Portable scripts should assume neither option is supported, and should
12412 assume neither behavior is the default. This can be a bit tricky,
12413 since the Posix default behavior means that, for example,
12414 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12415 the current logical directory is a symbolic link. It is safe to use
12416 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12417 Also, Autoconf-generated scripts check for this problem when computing
12418 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12419 so it is safe to @command{cd} to these variables.
12421 See @xref{Special Shell Variables}, for portability problems involving
12422 @command{cd} and the @env{CDPATH} environment variable.
12423 Also please see the discussion of the @command{pwd} command.
12426 @item @command{echo}
12427 @c -----------------
12428 @prindex @command{echo}
12429 The simple @command{echo} is probably the most surprising source of
12430 portability troubles. It is not possible to use @samp{echo} portably
12431 unless both options and escape sequences are omitted. New applications
12432 which are not aiming at portability should use @samp{printf} instead of
12435 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
12436 etc.@: for a means to simulate @option{-n}.
12438 Do not use backslashes in the arguments, as there is no consensus on
12439 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
12440 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12441 The problem is truly @command{echo}: all the shells
12442 understand @samp{'\n'} as the string composed of a backslash and an
12445 Because of these problems, do not pass a string containing arbitrary
12446 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
12447 if you know that @var{foo}'s value cannot contain backslashes and cannot
12448 start with @samp{-}, but otherwise you should use a here-document like
12458 @item @command{eval}
12459 @c -----------------
12460 @prindex @command{eval}
12461 The @command{eval} command is useful in limited circumstances, e.g.,
12462 using commands like @samp{eval table_$key=\$value} and @samp{eval
12463 value=table_$key} to simulate a hash table when the key is known to be
12464 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12465 arguments, even when it is implemented correctly.
12467 It is obviously unwise to use @samp{eval $cmd} if the string value of
12468 @samp{cmd} was derived from an untrustworthy source. But even if the
12469 string value is valid, @samp{eval $cmd} might not work as intended,
12470 since it causes field splitting and file name expansion to occur twice,
12471 once for the @command{eval} and once for the command itself. It is
12472 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
12473 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12474 equivalent of @samp{cat test;.c} if there happens to be a file named
12475 @file{test;.c} in the current directory; and this in turn
12476 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12477 then execute the command @command{.c}. To avoid this problem, use
12478 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12480 However, suppose that you want to output the text of the evaluated
12481 command just before executing it. Assuming the previous example,
12482 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12483 this output doesn't show the user that @samp{test;.c} is the actual name
12484 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
12485 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12486 since it mistakenly replaces the contents of @file{bar} by the
12487 string @samp{cat foo}. No simple, general, and portable solution to
12488 this problem is known.
12490 You should also be wary of common bugs in @command{eval} implementations.
12491 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12492 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12493 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12494 @samp{$?} is 0, so they exhibit behavior like this:
12497 $ @kbd{false; eval 'echo $?'}
12501 The correct behavior here is to output a nonzero value,
12502 but portable scripts should not rely on this.
12504 You should not rely on @code{LINENO} within @command{eval}.
12505 @xref{Special Shell Variables}.
12507 @item @command{exit}
12508 @c -----------------
12509 @prindex @command{exit}
12510 The default value of @command{exit} is supposed to be @code{$?};
12511 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12512 perform @samp{exit 0}.
12515 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12517 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12519 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12523 Using @samp{exit $?} restores the expected behavior.
12525 Some shell scripts, such as those generated by @command{autoconf}, use a
12526 trap to clean up before exiting. If the last shell command exited with
12527 nonzero status, the trap also exits with nonzero status so that the
12528 invoker can tell that an error occurred.
12530 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12531 trap ignores the @code{exit} command's argument. In these shells, a trap
12532 cannot determine whether it was invoked by plain @code{exit} or by
12533 @code{exit 1}. Instead of calling @code{exit} directly, use the
12534 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12537 @item @command{export}
12538 @c -------------------
12539 @prindex @command{export}
12540 The builtin @command{export} dubs a shell variable @dfn{environment
12541 variable}. Each update of exported variables corresponds to an update
12542 of the environment variables. Conversely, each environment variable
12543 received by the shell when it is launched should be imported as a shell
12544 variable marked as exported.
12546 Alas, many shells, such as Solaris @command{/bin/sh},
12547 @sc{irix} 6.3, @sc{irix} 5.2,
12548 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12549 @command{export} the environment variables they receive. As a result,
12550 two variables coexist: the environment variable and the shell
12551 variable. The following code demonstrates this failure:
12562 when run with @samp{FOO=foo} in the environment, these shells print
12563 alternately @samp{foo} and @samp{bar}, although they should print only
12564 @samp{foo} and then a sequence of @samp{bar}s.
12566 Therefore you should @command{export} again each environment variable
12570 @item @command{false}
12571 @c ------------------
12572 @prindex @command{false}
12573 Don't expect @command{false} to exit with status 1: in native
12574 Solaris @file{/bin/false} exits with status 255.
12577 @item @command{for}
12578 @c ----------------
12579 @prindex @command{for}
12580 To loop over positional arguments, use:
12590 You may @emph{not} leave the @code{do} on the same line as @code{for},
12591 since some shells improperly grok:
12599 If you want to explicitly refer to the positional arguments, given the
12600 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12603 for arg in $@{1+"$@@"@}; do
12609 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12610 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12611 item @samp{$@@}, for more.
12616 @prindex @command{if}
12617 Using @samp{!} is not portable. Instead of:
12620 if ! cmp -s file file.new; then
12629 if cmp -s file file.new; then :; else
12634 There are shells that do not reset the exit status from an @command{if}:
12637 $ @kbd{if (exit 42); then true; fi; echo $?}
12642 whereas a proper shell should have printed @samp{0}. This is especially
12643 bad in makefiles since it produces false failures. This is why properly
12644 written makefiles, such as Automake's, have such hairy constructs:
12647 if test -f "$file"; then
12648 install "$file" "$dest"
12655 @item @command{printf}
12656 @c ------------------
12657 @prindex @command{printf}
12658 A format string starting with a @samp{-} can cause problems.
12659 Bash interprets it as an option and
12660 gives an error. And @samp{--} to mark the end of options is not good
12661 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12662 literally as the format string. Putting the @samp{-} in a @samp{%c}
12663 or @samp{%s} is probably easiest:
12669 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
12672 $ @kbd{printf '\045'}
12673 bash: printf: `%': missing format character
12677 @item @command{read}
12678 @c ------------------
12679 @prindex @command{read}
12680 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12683 @item @command{pwd}
12684 @c ----------------
12685 @prindex @command{pwd}
12686 With modern shells, plain @command{pwd} outputs a ``logical''
12687 directory name, some of whose components may be symbolic links. These
12688 directory names are in contrast to ``physical'' directory names, whose
12689 components are all directories.
12691 Posix 1003.1-2001 requires that @command{pwd} must support
12692 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12693 with @option{-L} being the default. However, traditional shells do
12694 not support these options, and their @command{pwd} command has the
12695 @option{-P} behavior.
12697 Portable scripts should assume neither option is supported, and should
12698 assume neither behavior is the default. Also, on many hosts
12699 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12700 does not require this behavior and portable scripts should not rely on
12703 Typically it's best to use plain @command{pwd}. On modern hosts this
12704 outputs logical directory names, which have the following advantages:
12708 Logical names are what the user specified.
12710 Physical names may not be portable from one installation
12711 host to another due to network file system gymnastics.
12713 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12714 some parent directory, but plain @command{pwd} cannot fail for this
12718 Also please see the discussion of the @command{cd} command.
12721 @item @command{set}
12722 @c ----------------
12723 @prindex @command{set}
12724 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12725 any options) does not sort its output.
12727 The @command{set} builtin faces the usual problem with arguments starting with a
12728 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
12729 the end of the options (any argument after @option{--} is a parameter,
12730 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12731 10 @command{/bin/sh}) simply stop option
12732 processing as soon as a non-option argument is found. Therefore, use
12733 @samp{dummy} or simply @samp{x} to end the option processing, and use
12734 @command{shift} to pop it out:
12737 set x $my_list; shift
12740 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
12741 longer requires support for this command, and in traditional shells
12742 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12743 makes scripts harder to debug.
12745 Some nonstandard shells do not recognize more than one option
12746 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
12747 better to combine them:
12753 The @acronym{BSD} shell has had several problems with the @option{-e}
12754 option, partly because @acronym{BSD} @command{make} traditionally used
12755 @option{-e} even though this was incompatible with Posix
12756 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
12757 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12758 @samp{case} when @option{-e} was in effect, causing the shell to exit
12759 unexpectedly in some cases. This was particularly a problem with
12760 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12761 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12762 wrapper works around the bug.
12764 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12765 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12766 @samp{&&} fails inside a compound statement. For example:
12772 test -n "$foo" && exit 1
12775 test -n "$foo" && exit 1
12781 does not print @samp{two}. One workaround is to use @samp{if test -n
12782 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12783 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12786 @item @command{shift}
12787 @c ------------------
12788 @prindex @command{shift}
12789 Not only is @command{shift}ing a bad idea when there is nothing left to
12790 shift, but in addition it is not portable: the shell of @acronym{MIPS
12791 RISC/OS} 4.52 refuses to do it.
12793 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12794 and it is also absent in many pre-Posix shells.
12797 @item @command{source}
12798 @c -------------------
12799 @prindex @command{source}
12800 This command is not portable, as Posix does not require it; use
12801 @command{.} instead.
12804 @item @command{test}
12805 @c -----------------
12806 @prindex @command{test}
12807 The @code{test} program is the way to perform many file and string
12808 tests. It is often invoked by the alternate name @samp{[}, but using
12809 that name in Autoconf code is asking for trouble since it is an M4 quote
12812 If you need to make multiple checks using @code{test}, combine them with
12813 the shell operators @samp{&&} and @samp{||} instead of using the
12814 @code{test} operators @option{-a} and @option{-o}. On System V, the
12815 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12816 operators; consequently, Posix does not specify them, so using them
12817 is nonportable. If you combine @samp{&&} and @samp{||} in the same
12818 statement, keep in mind that they have equal precedence.
12820 It is safe to use @samp{!} as a @command{test} operator. For example,
12821 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12822 -d foo; @dots{}} is not.
12825 @item @command{test} (files)
12826 @c -------------------------
12827 To enable @command{configure} scripts to support cross-compilation, they
12828 shouldn't do anything that tests features of the build system instead of
12829 the host system. But occasionally you may find it necessary to check
12830 whether some arbitrary file exists. To do so, use @samp{test -f} or
12831 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12832 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12833 lacks it. To test for symbolic links on systems that have them, use
12834 @samp{test -h} rather than @samp{test -L}; either form conforms to
12835 Posix 1003.1-2001, but older shells like Solaris 8
12836 @code{/bin/sh} support only @option{-h}.
12838 @item @command{test} (strings)
12839 @c ---------------------------
12840 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12841 start with a dash, since @code{test} might interpret its argument as an
12842 option (e.g., @samp{@var{string} = "-n"}).
12844 Contrary to a common belief, @samp{test -n @var{string}} and
12845 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
12846 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12847 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12848 @var{string} looks like an operator:
12852 test: argument expected
12855 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12856 "x@var{string}" != x} instead.
12858 It is common to find variations of the following idiom:
12861 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12866 to take an action when a token matches a given pattern. Such constructs
12867 should always be avoided by using:
12870 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12875 Use @code{case} where possible since it is faster, being a shell builtin:
12879 case $ac_feature in
12880 *[!-a-zA-Z0-9_]*) @var{action};;
12884 Alas, negated character classes are probably not portable, although no
12885 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12886 (when in interactive mode, @command{zsh} is confused by the
12887 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12888 @samp{!}). Many shells do not support the alternative syntax
12889 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12891 One solution can be:
12894 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12902 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12906 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12907 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12908 @samp{@var{foo}} contains backslashes.
12911 @item @command{trap}
12912 @c -----------------
12913 @prindex @command{trap}
12914 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
12915 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12916 explicit @command{exit}, or the end of the script). The trap for 0 should be
12917 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
12918 will invoke the trap at the end of this function.
12920 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12921 specified signals to their default values, but many common shells (e.g.,
12922 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12923 ``command'' named @command{-} when the specified conditions arise.
12924 There is no portable workaround, except for @samp{trap - 0}, for which
12925 @samp{trap '' 0} is a portable substitute.
12927 Although Posix is not absolutely clear on this point, it is widely
12928 admitted that when entering the trap @samp{$?} should be set to the exit
12929 status of the last command run before the trap. The ambiguity can be
12930 summarized as: ``when the trap is launched by an @command{exit}, what is
12931 the @emph{last} command run: that before @command{exit}, or
12932 @command{exit} itself?''
12934 Bash considers @command{exit} to be the last command, while Zsh and
12935 Solaris @command{/bin/sh} consider that when the trap is run it is
12936 @emph{still} in the @command{exit}, hence it is the previous exit status
12937 that the trap receives:
12940 $ @kbd{cat trap.sh}
12943 $ @kbd{zsh trap.sh}
12945 $ @kbd{bash trap.sh}
12949 The portable solution is then simple: when you want to @samp{exit 42},
12950 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12951 set the exit status to 42 for Zsh, and the second to trigger the trap
12952 and pass 42 as exit status for Bash.
12954 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12955 reset to 0 by empty lines if the code is inside @command{trap}.
12958 $ @kbd{trap 'false}
12966 Fortunately, this bug only affects @command{trap}.
12968 @item @command{true}
12969 @c -----------------
12970 @prindex @command{true}
12971 @c Info cannot handle `:' in index entries.
12972 @c @prindex @command{:}
12973 Don't worry: as far as we know @command{true} is portable.
12974 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12975 portable shell community tends to prefer using @command{:}. This has a
12976 funny side effect: when asked whether @command{false} is more portable
12977 than @command{true} Alexandre Oliva answered:
12980 In a sense, yes, because if it doesn't exist, the shell will produce an
12981 exit status of failure, which is correct for @command{false}, but not
12982 for @command{true}.
12986 @item @command{unset}
12987 @c ------------------
12988 @prindex @command{unset}
12989 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
12990 when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset
12991 MAIL} in some cases and dumps core.
12993 A few ancient shells lack @command{unset} entirely. Nevertheless, because
12994 it is extremely useful to disable embarrassing variables such as
12995 @code{PS1}, you can test for its existence and use
12996 it @emph{provided} you give a neutralizing value when @command{unset} is
13000 # "|| exit" suppresses any "Segmentation fault" message.
13001 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
13006 $unset PS1 || PS1='$ '
13010 @xref{Special Shell Variables}, for some neutralizing values. Also, see
13011 @ref{Limitations of Builtins}, documentation of @command{export}, for
13012 the case of environment variables.
13015 @node Limitations of Usual Tools
13016 @section Limitations of Usual Tools
13017 @cindex Limitations of usual tools
13019 The small set of tools you can expect to find on any machine can still
13020 include some limitations you should be aware of.
13026 Don't leave white space before the opening parenthesis in a user function call.
13027 Posix does not allow this and @acronym{GNU} Awk rejects it:
13030 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13031 BEGIN @{ die () @}'}
13032 gawk: cmd. line:2: BEGIN @{ die () @}
13033 gawk: cmd. line:2: ^ parse error
13034 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13035 BEGIN @{ die() @}'}
13039 Posix says that if a program contains only @samp{BEGIN} actions, and
13040 contains no instances of @code{getline}, then the program merely
13041 executes the actions without reading input. However, traditional Awk
13042 implementations (such as Solaris 10 @command{awk}) read and discard
13043 input in this case. Portable scripts can redirect input from
13044 @file{/dev/null} to work around the problem. For example:
13047 awk 'BEGIN @{print "hello world"@}' </dev/null
13050 If you want your program to be deterministic, don't depend on @code{for}
13054 $ @kbd{cat for.awk}
13061 $ @kbd{gawk -f for.awk </dev/null}
13064 $ @kbd{nawk -f for.awk </dev/null}
13069 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
13072 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13073 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13075 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13077 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13082 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13083 or use a simple test to reject such implementations.
13085 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13086 length of regular expressions and literal strings in an Awk program.
13088 Traditional Awk implementations derived from Unix version 7, such as
13089 Solaris @command{/bin/awk}, have many limitations and do not
13090 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13091 Programs}) finds you an Awk that doesn't have these problems, but if
13092 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13095 Traditional Awk does not support multidimensional arrays or user-defined
13098 Traditional Awk does not support the @option{-v} option. You can use
13099 assignments after the program instead, e.g., @command{$AWK '@{print v
13100 $1@}' v=x}; however, don't forget that such assignments are not
13101 evaluated until they are encountered (e.g., after any @code{BEGIN}
13104 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13106 Traditional Awk does not support the expressions
13107 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13108 or @code{@var{a}^=@var{b}}.
13110 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13112 Traditional Awk supports only the predefined functions @code{exp},
13113 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13114 @code{sqrt}, and @code{substr}.
13116 Traditional Awk @code{getline} is not at all compatible with Posix;
13119 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13120 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
13122 In code portable to both traditional and modern Awk, @code{FS} must be a
13123 string containing just one ordinary character, and similarly for the
13124 field-separator argument to @code{split}.
13126 Traditional Awk has a limit of 99
13127 fields in a record. You may be able to circumvent this problem by using
13130 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13131 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13134 The original version of Awk had a limit of at most 99 bytes per
13135 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13136 per run of non-special characters in a @code{printf} format, but these
13137 bugs have been fixed on all practical hosts that we know of.
13139 @item @command{basename}
13140 @c ---------------------
13141 @prindex @command{basename}
13142 Not all hosts have a working @command{basename}.
13143 You can use @command{expr} instead.
13145 @c AS_BASENAME is to be replaced by a better API.
13147 Not all hosts have a working @command{basename}, and you should instead
13148 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13149 @command{expr} if you need to strip a suffix. For example:
13152 a=`basename "$aname"` # This is not portable.
13153 a=`AS_BASENAME(["$aname"])` # This is more portable.
13155 # This is not portable.
13156 c=`basename "$cname" .c`
13158 # This is more portable.
13159 c=`AS_BASENAME(["$cname"])`
13161 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13167 @item @command{cat}
13168 @c ----------------
13169 @prindex @command{cat}
13170 Don't rely on any option.
13175 @prindex @command{cc}
13176 The command @samp{cc -c foo.c} traditionally produces an object file
13177 named @file{foo.o}. Most compilers allow @option{-c} to be combined
13178 with @option{-o} to specify a different object file name, but
13179 Posix does not require this combination and a few compilers
13180 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
13181 tests for this feature with @code{AC_PROG_CC_C_O}.
13183 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13184 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13186 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13187 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
13190 The default executable, produced by @samp{cc foo.c}, can be
13193 @item @file{a.out} --- usual Posix convention.
13194 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13195 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13196 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13197 @item @file{foo.exe} --- various MS-DOS compilers.
13200 The C compiler's traditional name is @command{cc}, but other names like
13201 @command{gcc} are common. Posix 1003.1-2001 specifies the
13202 name @command{c99}, but older Posix editions specified
13203 @command{c89} and anyway these standard names are rarely used in
13204 practice. Typically the C compiler is invoked from makefiles that use
13205 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13209 @item @command{chmod}
13210 @c ------------------
13211 @prindex @command{chmod}
13212 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13213 instead, for two reasons. First, plain @option{-w} does not necessarily
13214 make the file unwritable, since it does not affect mode bits that
13215 correspond to bits in the file mode creation mask. Second,
13216 Posix says that the @option{-w} might be interpreted as an
13217 implementation-specific option, not as a mode; Posix suggests
13218 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13219 @samp{--} does not work on some older hosts.
13222 @item @command{cmp}
13223 @c ----------------
13224 @prindex @command{cmp}
13225 @command{cmp} performs a raw data comparison of two files, while
13226 @command{diff} compares two text files. Therefore, if you might compare
13227 DOS files, even if only checking whether two files are different, use
13228 @command{diff} to avoid spurious differences due to differences of
13234 @prindex @command{cp}
13235 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13236 obsolescent and its behavior on special files is implementation-defined.
13237 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13238 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13239 reads from pipes instead of replicating them.
13241 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13242 trailing slashes at the end of nonexistent destination directories. To
13243 avoid this problem, omit the trailing slashes. For example, use
13244 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13245 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13247 @c This is thanks to Ian.
13248 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13249 its @command{mv} does.
13251 @cindex timestamp resolution
13252 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13253 -p} copied the timestamps exactly. However, many modern file systems
13254 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13255 -p} implementations truncate timestamps when copying files, so this
13256 can result in the destination file appearing to be older than the
13257 source. The exact amount of truncation depends on the resolution of
13258 the system calls that @command{cp} uses; traditionally this was
13259 @code{utime}, which has 1-second resolution, but some newer
13260 @command{cp} implementations use @code{utimes}, which has
13261 1-microsecond resolution. These newer implementations include @acronym{GNU}
13262 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13263 later. Unfortunately as of January 2006 there is still no system
13264 call to set timestamps to the full nanosecond resolution.
13266 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13267 ownerships. But whether it actually does copy ownerships or not is a
13268 system dependent policy decision implemented by the kernel. If the
13269 kernel allows it then it happens. If the kernel does not allow it then
13270 it does not happen. It is not something @command{cp} itself has control
13273 In Unix System V any user can chown files to any other user, and System
13274 V also has a non-sticky @file{/tmp}. That probably derives from the
13275 heritage of System V in a business environment without hostile users.
13276 @acronym{BSD} changed this
13277 to be a more secure model where only root can @command{chown} files and
13278 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13279 of @acronym{BSD} in a campus environment.
13281 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13282 can be configured to allow a System V style @command{chown}. On the
13283 other hand, @acronym{HP-UX} follows System V, but can
13284 be configured to use the modern security model and disallow
13285 @command{chown}. Since it is an administrator-configurable parameter
13286 you can't use the name of the kernel as an indicator of the behavior.
13290 @item @command{date}
13291 @c -----------------
13292 @prindex @command{date}
13293 Some versions of @command{date} do not recognize special @samp{%} directives,
13294 and unfortunately, instead of complaining, they just pass them through,
13295 and exit with success:
13299 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13305 @item @command{diff}
13306 @c -----------------
13307 @prindex @command{diff}
13308 Option @option{-u} is nonportable.
13310 Some implementations, such as Tru64's, fail when comparing to
13311 @file{/dev/null}. Use an empty file instead.
13314 @item @command{dirname}
13315 @c --------------------
13316 @prindex @command{dirname}
13317 Not all hosts have a working @command{dirname}, and you should instead
13318 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13321 dir=`dirname "$file"` # This is not portable.
13322 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13326 @item @command{egrep}
13327 @c ------------------
13328 @prindex @command{egrep}
13329 Posix 1003.1-2001 no longer requires @command{egrep},
13330 but many older hosts do not yet support the Posix
13331 replacement @code{grep -E}. Also, some traditional implementations do
13332 not work on long input lines. To work around these problems, invoke
13333 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13335 Portable extended regular expressions should use @samp{\} only to escape
13336 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13337 is not portable, even though it typically matches @samp{@}}.
13339 The empty alternative is not portable. Use @samp{?} instead. For
13340 instance with Digital Unix v5.0:
13343 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13345 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13347 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13352 @command{$EGREP} also suffers the limitations of @command{grep}.
13354 @item @command{expr}
13355 @c -----------------
13356 @prindex @command{expr}
13357 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13358 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13359 misinterpreting @var{word}.
13361 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13363 @item @command{expr} (@samp{|})
13364 @prindex @command{expr} (@samp{|})
13365 You can use @samp{|}. Although Posix does require that @samp{expr
13366 ''} return the empty string, it does not specify the result when you
13367 @samp{|} together the empty string (or zero) with the empty string. For
13374 Posix 1003.2-1992 returns the empty string
13375 for this case, but traditional Unix returns @samp{0} (Solaris is
13376 one such example). In Posix 1003.1-2001, the specification was
13377 changed to match traditional Unix's behavior (which is
13378 bizarre, but it's too late to fix this). Please note that the same
13379 problem does arise when the empty string results from a computation,
13383 expr bar : foo \| foo : bar
13387 Avoid this portability problem by avoiding the empty string.
13390 @item @command{expr} (@samp{:})
13391 @c ----------------------------
13392 @prindex @command{expr}
13393 Portable @command{expr} regular expressions should use @samp{\} to
13394 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13395 For example, alternation, @samp{\|}, is common but Posix does not
13396 require its support, so it should be avoided in portable scripts.
13397 Similarly, @samp{\+} and @samp{\?} should be avoided.
13399 Portable @command{expr} regular expressions should not begin with
13400 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
13403 The Posix standard is ambiguous as to whether
13404 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13405 In practice, it outputs the empty string on most platforms, but portable
13406 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
13407 @command{expr} returns @samp{0}.
13409 One might think that a way to get a uniform behavior would be to use
13410 the empty string as a default value:
13413 expr a : '\(b\)' \| ''
13417 Unfortunately this behaves exactly as the original expression; see the
13418 @command{expr} (@samp{|}) entry for more information.
13420 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13421 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13422 @command{expr} to fail if the matched substring is longer than 120
13423 bytes. In this case, you might want to fall back on @samp{echo|sed} if
13424 @command{expr} fails. Nowadays this is of practical importance only for
13425 the rare installer who mistakenly puts @file{/usr/ucb} before
13426 @file{/usr/bin} in @env{PATH}.
13428 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13429 some cases. For example, the command
13431 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13435 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13436 This particular case can be worked around by substituting @samp{[^--]}
13439 Don't leave, there is some more!
13441 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13442 the empty string, has a funny behavior in its exit status: it's always 1
13443 when parentheses are used!
13446 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13448 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13451 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13453 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13458 In practice this can be a big problem if you are ready to catch failures
13459 of @command{expr} programs with some other method (such as using
13460 @command{sed}), since you may get twice the result. For instance
13463 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13467 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
13468 simple workaround consists of testing @command{expr} and using a variable
13469 set to @command{expr} or to @command{false} according to the result.
13471 Tru64 @command{expr} incorrectly treats the result as a number, if it
13472 can be interpreted that way:
13475 $ @kbd{expr 00001 : '.*\(...\)'}
13480 @item @command{fgrep}
13481 @c ------------------
13482 @prindex @command{fgrep}
13483 Posix 1003.1-2001 no longer requires @command{fgrep},
13484 but many older hosts do not yet support the Posix
13485 replacement @code{grep -F}. Also, some traditional implementations do
13486 not work on long input lines. To work around these problems, invoke
13487 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13490 @item @command{find}
13491 @c -----------------
13492 @prindex @command{find}
13493 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13494 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13495 commands do not understand it.
13497 The replacement of @samp{@{@}} is guaranteed only if the argument is
13498 exactly @emph{@{@}}, not if it's only a part of an argument. For
13499 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13503 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13508 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13511 @item @command{grep}
13512 @c -----------------
13513 @prindex @command{grep}
13514 Portable scripts can rely on the @command{grep} options @option{-c},
13515 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13516 options. For example, don't use @option{-w}, as Posix does not require
13517 it and Irix 6.5.16m's @command{grep} does not support it. Also,
13518 portable scripts should not combine @option{-c} with @option{-l},
13519 as Posix does not allow this.
13521 Some of the options required by Posix are not portable in practice.
13522 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13523 implementations (e.g., Solaris) do not support @option{-q}.
13524 Don't use @samp{grep -s} to suppress output either, because Posix
13525 says @option{-s} does not suppress output, only some error messages;
13526 also, the @option{-s} option of traditional @command{grep} behaved
13527 like @option{-q} does in most modern implementations. Instead,
13528 redirect the standard output and standard error (in case the file
13529 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
13530 status of @code{grep} to determine whether it found a match.
13532 Some traditional @command{grep} implementations do not work on long
13533 input lines. On AIX the default @code{grep} silently truncates long
13534 lines on the input before matching.
13536 Also, many implementations do not support multiple regexps
13537 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13538 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
13539 work around these problems, invoke @code{AC_PROG_GREP} and then use
13542 Another possible workaround for the multiple @option{-e} problem is to
13543 separate the patterns by newlines, for example:
13551 except that this fails with traditional @command{grep}
13552 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13554 Traditional @command{grep} implementations (e.g., Solaris) do not
13555 support the @option{-E} or @option{-F} options. To work around these
13556 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13557 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
13558 willing to require support for Posix @command{grep}, your script should
13559 not use both @option{-E} and @option{-F}, since Posix does not allow
13562 Portable @command{grep} regular expressions should use @samp{\} only to
13563 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
13564 alternation, @samp{\|}, is common but Posix does not require its
13565 support in basic regular expressions, so it should be avoided in
13566 portable scripts. Solaris and HP-UX @command{grep} do not support it.
13567 Similarly, the following escape sequences should also be avoided:
13568 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
13569 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
13572 @item @command{join}
13573 @c -----------------
13574 @prindex @command{join}
13575 Solaris 8 @command{join} has bugs when the second operand is standard
13576 input, and when standard input is a pipe. For example, the following
13577 shell script causes Solaris 8 @command{join} to loop forever:
13584 cat file | join file -
13587 Use @samp{join - file} instead.
13592 @prindex @command{ln}
13593 @cindex Symbolic links
13594 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
13595 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13597 For versions of the @acronym{DJGPP} before 2.04,
13598 @command{ln} emulates symbolic links
13599 to executables by generating a stub that in turn calls the real
13600 program. This feature also works with nonexistent files like in the
13601 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
13602 which attempts to call @file{file.exe} if run. But this feature only
13603 works for executables, so @samp{cp -p} is used instead for these
13604 systems. @acronym{DJGPP} versions 2.04 and later have full support
13605 for symbolic links.
13610 @prindex @command{ls}
13611 @cindex Listing directories
13612 The portable options are @option{-acdilrtu}. Current practice is for
13613 @option{-l} to output both owner and group, even though ancient versions
13614 of @command{ls} omitted the group.
13616 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13617 to standard output if @file{foo} did not exist. Hence a shell command
13618 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13619 was equivalent to @samp{sources='*.c not found'} in the absence of
13620 @samp{.c} files. This is no longer a practical problem, since current
13621 @command{ls} implementations send diagnostics to standard error.
13623 @item @command{mkdir}
13624 @c ------------------
13625 @prindex @command{mkdir}
13626 @cindex Making directories
13627 No @command{mkdir} option is portable to older systems. Instead of
13628 @samp{mkdir -p @var{file-name}}, you should use
13629 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13630 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13632 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
13633 go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD}
13634 @command{mkdir} incorrectly attempts to change the permissions of
13635 @var{dir} even if it already exists. @acronym{HP-UX} 11.23 and
13636 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
13637 any newly-created parents of @var{dir}.
13639 Posix does not clearly specify whether @samp{mkdir -p foo}
13640 should succeed when @file{foo} is a symbolic link to an already-existing
13641 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13642 succeeds, but Solaris @command{mkdir} fails.
13644 Traditional @code{mkdir -p} implementations suffer from race conditions.
13645 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13646 at the same time, both processes might detect that @file{a} is missing,
13647 one might create @file{a}, then the other might try to create @file{a}
13648 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
13649 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13650 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13651 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13652 earlier versions are vulnerable. Solaris @command{mkdir} is still
13653 vulnerable as of Solaris 10, and other traditional Unix systems are
13654 probably vulnerable too. This possible race is harmful in parallel
13655 builds when several Make rules call @code{mkdir -p} to
13656 construct directories. You may use
13657 @code{install-sh -d} as a safe replacement, provided this script is
13658 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13659 OK, but copies from older versions are vulnerable.
13662 @item @command{mktemp}
13663 @c -------------------
13664 @prindex @command{mktemp}
13665 @cindex Creating temporary files
13666 Shell scripts can use temporary files safely with @command{mktemp}, but
13667 it does not exist on all systems. A portable way to create a safe
13668 temporary file name is to create a temporary directory with mode 700 and
13669 use a file inside this directory. Both methods prevent attackers from
13670 gaining control, though @command{mktemp} is far less likely to fail
13671 gratuitously under attack.
13673 Here is sample code to create a new temporary directory safely:
13676 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13677 # Use mktemp if possible; otherwise fall back on mkdir,
13678 # with $RANDOM to make collisions less likely.
13682 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13684 test -n "$tmp" && test -d "$tmp"
13686 tmp=$TMPDIR/foo$$-$RANDOM
13687 (umask 077 && mkdir "$tmp")
13694 @prindex @command{mv}
13695 @cindex Moving open files
13696 The only portable options are @option{-f} and @option{-i}.
13698 Moving individual files between file systems is portable (it was in Unix
13700 but it is not always atomic: when doing @samp{mv new existing}, there's
13701 a critical section where neither the old nor the new version of
13702 @file{existing} actually exists.
13704 On some systems moving files from @file{/tmp} can sometimes cause
13705 undesirable (but perfectly valid) warnings, even if you created these
13706 files. This is because @file{/tmp} belongs to a group that ordinary
13707 users are not members of, and files created in @file{/tmp} inherit
13708 the group of @file{/tmp}. When the file is copied, @command{mv} issues
13709 a diagnostic without failing:
13712 $ @kbd{touch /tmp/foo}
13713 $ @kbd{mv /tmp/foo .}
13714 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13722 This annoying behavior conforms to Posix, unfortunately.
13724 Moving directories across mount points is not portable, use @command{cp}
13727 @acronym{DOS} variants cannot rename or remove open files, and do not
13728 support commands like @samp{mv foo bar >foo}, even though this is
13729 perfectly portable among Posix hosts.
13734 @prindex @command{od}
13736 In Mac OS X 10.3, @command{od} does not support the
13737 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13738 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
13739 supported Posix option is @option{-v}, and the only supported
13740 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
13741 @command{hexdump} program can be used instead.
13743 This problem no longer exists in Mac OS X 10.4.3.
13748 @prindex @command{rm}
13749 The @option{-f} and @option{-r} options are portable.
13751 It is not portable to invoke @command{rm} without operands. For
13752 example, on many systems @samp{rm -f -r} (with no other arguments)
13753 silently succeeds without doing anything, but it fails with a diagnostic
13754 on Net@acronym{BSD} 2.0.2.
13756 A file might not be removed even if its parent directory is writable
13757 and searchable. Many Posix hosts cannot remove a mount point, a named
13758 stream, a working directory, or a last link to a file that is being
13761 @acronym{DOS} variants cannot rename or remove open files, and do not
13762 support commands like @samp{rm foo >foo}, even though this is
13763 perfectly portable among Posix hosts.
13766 @item @command{sed}
13767 @c ----------------
13768 @prindex @command{sed}
13769 Patterns should not include the separator (unless escaped), even as part
13770 of a character class. In conformance with Posix, the Cray
13771 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13773 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
13774 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13777 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13779 Sed scripts should not use branch labels longer than 7 characters and
13780 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
13781 (not counting @samp{:} commands) and
13782 48 labels, which can not be circumvented by using more than one script
13783 file. It can execute up to 19 reads with the @samp{r} command per cycle.
13784 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13785 about 6000 bytes for the internal representation of commands.
13787 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13788 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13789 @samp{;} as a command:
13792 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13793 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13796 Input should not have unreasonably long lines, since some @command{sed}
13797 implementations have an input buffer limited to 4000 bytes.
13799 Portable @command{sed} regular expressions should use @samp{\} only to escape
13800 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
13801 alternation, @samp{\|}, is common but Posix does not require its
13802 support, so it should be avoided in portable scripts. Solaris
13803 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13804 deletes only lines that contain the literal string @samp{a|b}.
13805 Similarly, @samp{\+} and @samp{\?} should be avoided.
13807 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13809 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
13810 quite portable to current hosts, but was not supported by some ancient
13811 @command{sed} implementations like SVR3.
13813 Some @command{sed} implementations, e.g., Solaris,
13814 restrict the special role of the asterisk to one-character regular expressions.
13815 This may lead to unexpected behavior:
13818 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13820 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13824 The @option{-e} option is portable, so long as its argument
13825 does not begin with @samp{a}, @samp{c}, or @samp{i}
13826 (as this runs afoul of a Tru64 5.1 bug).
13827 Some people prefer to use @samp{-e}:
13830 sed -e '@var{command-1}' \
13831 -e '@var{command-2}'
13835 as opposed to the equivalent:
13845 The following usage is sometimes equivalent:
13848 sed '@var{command-1};@var{command-2}'
13851 but Posix says that this use of a semicolon has undefined effect if
13852 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13853 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13854 should use semicolon only with simple scripts that do not use these
13857 Commands inside @{ @} brackets are further restricted. Posix says that
13858 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13859 each command must be followed immediately by a newline, without any
13860 intervening blanks or semicolons. The closing bracket must be alone on
13861 a line, other than white space preceding or following it.
13863 Contrary to yet another urban legend, you may portably use @samp{&} in
13864 the replacement part of the @code{s} command to mean ``what was
13865 matched''. All descendants of Unix version 7 @command{sed}
13867 don't have first hand experience with older @command{sed} implementations) have
13870 Posix requires that you must not have any white space between
13871 @samp{!} and the following command. It is OK to have blanks between
13872 the address and the @samp{!}. For instance, on Solaris:
13875 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13876 @error{}Unrecognized command: /bar/ ! p
13877 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13878 @error{}Unrecognized command: /bar/! p
13879 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13883 Posix also says that you should not combine @samp{!} and @samp{;}. If
13884 you use @samp{!}, it is best to put it on a command that is delimited by
13885 newlines rather than @samp{;}.
13887 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13888 @samp{w} commands be followed by exactly one space before their argument.
13889 On the other hand, no white space is allowed between @samp{:} and the
13890 subsequent label name.
13892 If a sed script is specified on the command line and ends in an
13893 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
13894 should be followed by a newline. Otherwise some @command{sed}
13895 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
13898 Many @command{sed} implementations (e.g., MacOS X 10.4,
13899 Open@acronym{BSD} 3.9, Solaris 10
13900 @command{/usr/ucb/sed}) strip leading white space from the text of
13901 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
13902 work around this incompatibility with Posix:
13905 $ @kbd{echo flushleft | sed 'a\}
13910 $ @kbd{echo foo | sed 'a\}
13918 @item @command{sed} (@samp{t})
13919 @c ---------------------------
13920 @prindex @command{sed} (@samp{t})
13921 Some old systems have @command{sed} that ``forget'' to reset their
13922 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
13923 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13924 script (the line numbers are not actual part of the texts):
13927 s/keep me/kept/g # a
13963 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
13964 flag, and the output is produced. When processing
13965 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
13966 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13967 flag when a substitution fails. Command (b) sees that the flag is set,
13968 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13969 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
13970 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13971 Finally, since the flag is clear, line 4 is processed properly.
13973 There are two things one should remember about @samp{t} in @command{sed}.
13974 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13975 succeeded, not only the immediately preceding substitution. Therefore,
13976 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13977 line, to reset the @samp{t} flag where needed.
13979 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13982 One portable implementation of the script above is:
13993 @item @command{touch}
13994 @c ------------------
13995 @prindex @command{touch}
13996 @cindex timestamp resolution
13997 If you specify the desired timestamp (e.g., with the @option{-r}
13998 option), @command{touch} typically uses the @code{utime} or
13999 @code{utimes} system call, which can result in the same kind of
14000 timestamp truncation problems that @samp{cp -p} has.
14002 On ancient @acronym{BSD} systems, @command{touch} or any command that
14003 results in an empty file does not update the timestamps, so use a
14004 command like @command{echo} as a workaround.
14006 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
14007 fails to work on SunOS 4.1.3 when the empty file is on an
14008 @acronym{NFS}-mounted 4.2 volume.
14009 However, these problems are no longer of practical concern.
14014 @node Portable Make
14015 @chapter Portable Make Programming
14016 @prindex @command{make}
14017 @cindex Limitations of @command{make}
14019 Writing portable makefiles is an art. Since a makefile's commands are
14020 executed by the shell, you must consider the shell portability issues
14021 already mentioned. However, other issues are specific to @command{make}
14025 * $< in Ordinary Make Rules:: $< in ordinary rules
14026 * Failure in Make Rules:: Failing portably in rules
14027 * Special Chars in Names:: Special Characters in Macro Names
14028 * Backslash-Newline-Newline:: Empty last lines in macro definitions
14029 * Backslash-Newline Comments:: Spanning comments across line boundaries
14030 * Long Lines in Makefiles:: Line length limitations
14031 * Macros and Submakes:: @code{make macro=value} and submakes
14032 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
14033 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
14034 * Comments in Make Rules:: Other problems with Make comments
14035 * obj/ and Make:: Don't name a subdirectory @file{obj}
14036 * make -k Status:: Exit status of @samp{make -k}
14037 * VPATH and Make:: @code{VPATH} woes
14038 * Single Suffix Rules:: Single suffix rules and separated dependencies
14039 * Timestamps and Make:: Subsecond timestamp resolution
14042 @node $< in Ordinary Make Rules
14043 @section @code{$<} in Ordinary Make Rules
14045 Posix says that the @samp{$<} construct in makefiles can be
14046 used only in inference rules and in the @samp{.DEFAULT} rule; its
14047 meaning in ordinary rules is unspecified. Solaris @command{make}
14048 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
14049 later) @command{make} diagnoses these uses and errors out.
14051 @node Failure in Make Rules
14052 @section Failure in Make Rules
14054 Since 1992 Posix has required that @command{make} must invoke
14055 each command with the equivalent of a @samp{sh -c} subshell. However,
14056 many @command{make} implementations, including @acronym{BSD} make through 2004,
14057 use @samp{sh -e -c} instead, and the @option{-e} option causes the
14058 subshell to exit immediately if a subsidiary simple-command fails. For
14059 example, the command @samp{touch T; rm -f U} always attempts to
14060 remove @file{U} with Posix make, but incompatible
14061 @command{make} implementations skip the @command{rm} if the
14062 @command{touch} fails. One way to work around this is to reword the
14063 affected simple-commands so that they always succeed, e.g., @samp{touch
14065 However, even this approach can run into common bugs in @acronym{BSD}
14066 implementations of the @option{-e} option of @command{sh} and
14067 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14068 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14069 complicated @command{make} actions into separate scripts.
14071 @node Special Chars in Names
14072 @section Special Characters in Make Macro Names
14074 Posix limits macro names to nonempty strings containing only
14075 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
14076 @command{make} implementations allow a wider variety of characters, but
14077 portable makefiles should avoid them. It is portable to start a name
14078 with a special character, e.g., @samp{$(.FOO)}.
14080 Some ancient @command{make} implementations don't support leading
14081 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
14084 $ @kbd{cat Makefile}
14087 all:; @@echo this is test
14089 Make: Must be a separator on rules line 2. Stop.
14090 $ @kbd{cat Makefile2}
14093 all:; @@echo this is test
14094 $ @kbd{make -f Makefile2}
14099 However, this problem is no longer of practical concern.
14101 @node Backslash-Newline-Newline
14102 @section Backslash-Newline-Newline in Make Macro Values
14104 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14105 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
14106 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
14107 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14108 following a backslash, continuing to the next non-empty line. For
14122 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
14123 sensibly let a backslash continue only to the immediately following
14126 @node Backslash-Newline Comments
14127 @section Backslash-Newline in Make Comments
14129 According to Posix, Make comments start with @code{#}
14130 and continue until an unescaped newline is reached.
14133 $ @kbd{cat Makefile}
14140 $ @kbd{make} # GNU make
14145 However this is not always the case. Some implementations
14146 discard everything from @code{#} through the end of the line, ignoring any
14147 trailing backslash.
14150 $ @kbd{pmake} # BSD make
14151 "Makefile", line 3: Need an operator
14152 Fatal errors encountered -- cannot continue
14156 Therefore, if you want to comment out a multi-line definition, prefix each
14157 line with @code{#}, not only the first.
14165 @node Long Lines in Makefiles
14166 @section Long Lines in Makefiles
14168 Tru64 5.1's @command{make} has been reported to crash when given a
14169 makefile with lines longer than around 20 kB. Earlier versions are
14170 reported to exit with @code{Line too long} diagnostics.
14172 @node Macros and Submakes
14173 @section @code{make macro=value} and Submakes
14175 A command-line variable definition such as @code{foo=bar} overrides any
14176 definition of @code{foo} in a makefile. Some @command{make}
14177 implementations (such as @acronym{GNU} @command{make}) propagate this
14178 override to subsidiary invocations of @command{make}. Some other
14179 implementations do not pass the substitution along to submakes.
14182 $ @kbd{cat Makefile}
14189 $ @kbd{make foo=bar} # GNU make 3.79.1
14192 make[1]: Entering directory `/home/adl'
14194 make[1]: Leaving directory `/home/adl'
14195 $ @kbd{pmake foo=bar} # BSD make
14201 You have a few possibilities if you do want the @code{foo=bar} override
14202 to propagate to submakes. One is to use the @option{-e}
14203 option, which causes all environment variables to have precedence over
14204 the makefile macro definitions, and declare foo as an environment
14208 $ @kbd{env foo=bar make -e}
14211 The @option{-e} option is propagated to submakes automatically,
14212 and since the environment is inherited between @command{make}
14213 invocations, the @code{foo} macro is overridden in
14214 submakes as expected.
14216 This syntax (@code{foo=bar make -e}) is portable only when used
14217 outside of a makefile, for instance from a script or from the
14218 command line. When run inside a @command{make} rule, @acronym{GNU}
14219 @command{make} 3.80 and prior versions forget to propagate the
14220 @option{-e} option to submakes.
14222 Moreover, using @option{-e} could have unexpected side effects if your
14223 environment contains some other macros usually defined by the
14224 makefile. (See also the note about @code{make -e} and @code{SHELL}
14227 Another way to propagate overrides to submakes is to do it
14228 manually, from your makefile:
14234 $(MAKE) foo=$(foo) two
14239 You need to foresee all macros that a user might want to override if
14242 @node The Make Macro MAKEFLAGS
14243 @section The Make Macro MAKEFLAGS
14244 @cindex @code{MAKEFLAGS} and @command{make}
14245 @cindex @command{make} and @code{MAKEFLAGS}
14247 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14248 current and recursive invocations of make, but allows implementations
14249 several formats for the variable. It is tricky to parse
14250 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14251 or @option{-k} for continued execution are in effect. For example, you
14252 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14253 contains single-letter options, since in the Cygwin version of
14254 @acronym{GNU} @command{make} it is either @option{--unix} or
14255 @option{--win32} with the second word containing single-letter options.
14258 $ @kbd{cat Makefile}
14260 @@echo MAKEFLAGS = $(MAKEFLAGS)
14264 MAKEFLAGS = --unix -k
14267 @node The Make Macro SHELL
14268 @section The Make Macro @code{SHELL}
14269 @cindex @code{SHELL} and @command{make}
14270 @cindex @command{make} and @code{SHELL}
14272 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14273 macro to spawn shell processes and execute Make rules. This
14274 is a builtin macro supplied by @command{make}, but it can be modified
14275 by a makefile or by a command-line argument.
14277 Not all @command{make} implementations define this @code{SHELL} macro.
14279 @command{make} is an example; this implementation always uses
14280 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14281 your makefiles. If you use Autoconf, do
14287 Do not force @code{SHELL = /bin/sh} because that is not correct
14288 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14289 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14290 emulation mode where features like pipes and redirections are emulated
14291 on top of DOS's @command{command.com}. Unfortunately this emulation is
14292 incomplete; for instance it does not handle command substitutions.
14293 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14295 Posix-compliant @command{make} should never acquire the value of
14296 $(SHELL) from the environment, even when @code{make -e} is used
14297 (otherwise, think about what would happen to your rules if
14298 @code{SHELL=/bin/tcsh}).
14300 However not all @command{make} implementations have this exception.
14301 For instance it's not surprising that Tru64 @command{make} doesn't
14302 protect @code{SHELL}, since it doesn't use it.
14305 $ @kbd{cat Makefile}
14311 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14314 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14319 @node Comments in Make Rules
14320 @section Comments in Make Rules
14321 @cindex Comments in @file{Makefile} rules
14322 @cindex @file{Makefile} rules and comments
14324 Never put comments in a rule.
14326 Some @command{make} treat anything starting with a tab as a command for
14327 the current rule, even if the tab is immediately followed by a @code{#}.
14328 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14329 makefile runs @code{# foo} through the shell.
14336 @node obj/ and Make
14337 @section The @file{obj/} Subdirectory and Make
14338 @cindex @file{obj/}, subdirectory
14339 @cindex @acronym{BSD} @command{make} and @file{obj/}
14341 Never name one of your subdirectories @file{obj/} if you don't like
14344 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14345 before reading the makefile. Hence the makefile in the
14346 current directory is not read.
14349 $ @kbd{cat Makefile}
14352 $ @kbd{cat obj/Makefile}
14355 $ @kbd{make} # GNU make
14358 $ @kbd{pmake} # BSD make
14363 @node make -k Status
14364 @section Exit Status of @code{make -k}
14365 @cindex @code{make -k}
14367 Do not rely on the exit status of @code{make -k}. Some implementations
14368 reflect whether they encountered an error in their exit status; other
14369 implementations always succeed.
14372 $ @kbd{cat Makefile}
14375 $ @kbd{make -k; echo exit status: $?} # GNU make
14377 make: *** [all] Error 1
14379 $ @kbd{pmake -k; echo exit status: $?} # BSD make
14381 *** Error code 1 (continuing)
14385 @node VPATH and Make
14386 @section @code{VPATH} and Make
14387 @cindex @code{VPATH}
14389 Posix does not specify the semantics of @code{VPATH}. Typically,
14390 @command{make} supports @code{VPATH}, but its implementation is not
14393 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14394 portable to recent-enough popular implementations of @command{make}, but
14395 to keep the resulting makefiles portable, a package's makefile
14396 prototypes must take the following issues into account. These issues
14397 are complicated and are often poorly understood, and installers who use
14398 @code{VPATH} should expect to find many bugs in this area. If you use
14399 @code{VPATH}, the simplest way to avoid these portability bugs is to
14400 stick with @acronym{GNU} @command{make}, since it is the most
14401 commonly-used @command{make} among Autoconf users.
14403 Here are some known issues with some @code{VPATH}
14407 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
14408 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
14409 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
14410 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
14411 * Make Target Lookup:: More details about @code{VPATH} lookup
14414 @node VPATH and Double-colon
14415 @subsection @code{VPATH} and Double-colon Rules
14416 @cindex @code{VPATH} and double-colon rules
14417 @cindex double-colon rules and @code{VPATH}
14419 With ancient versions of Sun @command{make},
14420 any assignment to @code{VPATH} causes @command{make} to execute only
14421 the first set of double-colon rules.
14422 However, this problem is no longer of practical concern.
14424 @node $< in Explicit Rules
14425 @subsection @code{$<} Not Supported in Explicit Rules
14426 @cindex explicit rules, @code{$<}, and @code{VPATH}
14427 @cindex @code{$<}, explicit rules, and @code{VPATH}
14428 @cindex @code{VPATH}, explicit rules, and @code{$<}
14430 Using @code{$<} in explicit rules is not portable.
14431 The prerequisite file must be named explicitly in the rule. If you want
14432 to find the prerequisite via a @code{VPATH} search, you have to code the
14433 whole thing manually. @xref{Build Directories}.
14435 @node Automatic Rule Rewriting
14436 @subsection Automatic Rule Rewriting
14437 @cindex @code{VPATH} and automatic rule rewriting
14438 @cindex automatic rule rewriting and @code{VPATH}
14440 Some @command{make} implementations, such as Solaris and Tru64,
14441 search for prerequisites in @code{VPATH} and
14442 then rewrite each occurrence as a plain word in the rule.
14446 # This isn't portable to GNU make.
14453 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14454 found in @file{../pkg/src}.
14456 However, this rule leads to real problems in practice. For example, if
14457 the source directory contains an ordinary file named @file{test} that is
14458 used in a dependency, Solaris @command{make} rewrites commands like
14459 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14460 @dots{}}, which is typically undesirable. To avoid this problem,
14461 portable makefiles should never mention a source file whose name is that
14462 of a shell keyword like @file{until} or a shell command like
14463 @command{cat} or @command{gcc} or @command{test}.
14465 Because of these problems @acronym{GNU} @command{make} and many other
14466 @command{make} implementations do not rewrite commands, so portable
14468 search @code{VPATH} manually. It is tempting to write this:
14471 # This isn't portable to Solaris make.
14474 cp `test -f if.c || echo $(VPATH)/`if.c f.c
14478 However, the ``prerequisite rewriting'' still applies here. So if
14479 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14483 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14494 and thus fails. Oops.
14496 A simple workaround, and good practice anyway, is to use @samp{$?} and
14497 @samp{$@@} when possible:
14506 but this does not generalize well to commands with multiple
14507 prerequisites. A more general workaround is to rewrite the rule so that
14508 the prerequisite @file{if.c} never appears as a plain word. For
14509 example, these three rules would be safe, assuming @file{if.c} is in
14510 @file{../pkg/src} and the other files are in the working directory:
14515 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14517 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14519 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14522 Things get worse when your prerequisites are in a macro.
14526 HEADERS = f.h g.h h.h
14527 install-HEADERS: $(HEADERS)
14528 for i in $(HEADERS); do \
14529 $(INSTALL) -m 644 \
14530 `test -f $$i || echo $(VPATH)/`$$i \
14531 $(DESTDIR)$(includedir)/$$i; \
14535 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14536 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14537 where @code{f.h} and @code{g.h} are plain words and are hence
14538 subject to @code{VPATH} adjustments.
14540 If the three files are in @file{../pkg/src}, the rule is run as:
14543 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14545 `test -f $i || echo ../pkg/src/`$i \
14546 /usr/local/include/$i; \
14550 where the two first @command{install} calls fail. For instance,
14551 consider the @code{f.h} installation:
14555 `test -f ../pkg/src/f.h || \
14558 /usr/local/include/../pkg/src/f.h;
14567 /usr/local/include/../pkg/src/f.h;
14570 Note that the manual @code{VPATH} search did not cause any problems here;
14571 however this command installs @file{f.h} in an incorrect directory.
14573 Trying to quote @code{$(HEADERS)} in some way, as we did for
14574 @code{foo.c} a few makefiles ago, does not help:
14577 install-HEADERS: $(HEADERS)
14578 headers='$(HEADERS)'; \
14579 for i in $$headers; do \
14580 $(INSTALL) -m 644 \
14581 `test -f $$i || echo $(VPATH)/`$$i \
14582 $(DESTDIR)$(includedir)/$$i; \
14586 Now, @code{headers='$(HEADERS)'} macro-expands to:
14589 headers='f.h g.h h.h'
14593 but @code{g.h} is still a plain word. (As an aside, the idiom
14594 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14595 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14596 syntax error on @code{for i in;}.)
14598 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14602 HEADERS = f.h g.h h.h
14603 install-HEADERS: $(HEADERS)
14604 headers='$(HEADERS)'; \
14605 for i in $$headers; do \
14606 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14607 $(INSTALL) -m 644 \
14608 `test -f $$i || echo $(VPATH)/`$$i \
14609 $(DESTDIR)$(includedir)/$$i; \
14613 Automake does something similar. However the above hack works only if
14614 the files listed in @code{HEADERS} are in the current directory or a
14615 subdirectory; they should not be in an enclosing directory. If we had
14616 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14617 build with Tru64 @command{make}. The reason is that not only does
14618 Tru64 @command{make} rewrite dependencies, but it also simplifies
14619 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14620 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
14621 a leading @file{../pkg/src/} component.
14623 The following example makes the behavior of Tru64 @command{make}
14627 $ @kbd{cat Makefile}
14639 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14640 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
14641 directory does not even exist, this just means that the simplification
14642 occurred before the file was checked for.)
14644 For the record here is how SunOS 4 @command{make} behaves on this
14649 make: Fatal error: Don't know how to make target `../foo'
14657 @node Tru64 Directory Magic
14658 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14659 @cindex @code{VPATH} and prerequisite directories
14660 @cindex prerequisite directories and @code{VPATH}
14662 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14663 @command{make} creates it in the current directory.
14666 $ @kbd{mkdir -p foo/bar build}
14668 $ @kbd{cat >Makefile <<END
14677 This can yield unexpected results if a rule uses a manual @code{VPATH}
14678 search as presented before.
14683 command `test -d foo/bar || echo ../`foo/bar
14686 The above @command{command} is run on the empty @file{foo/bar}
14687 directory that was created in the current directory.
14689 @node Make Target Lookup
14690 @subsection Make Target Lookup
14691 @cindex @code{VPATH}, resolving target pathnames
14693 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14694 should use files found via a @code{VPATH} search. @xref{Search
14695 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14698 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14699 file name found during the @code{VPATH} search for this target, and
14700 builds the file locally using the file name given in the makefile.
14701 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14702 file name found during the @code{VPATH} search.
14704 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14705 easier to describe: the file name found during the @code{VPATH} search
14706 is used whether the target needs to be rebuilt or not. Therefore
14707 new files are created locally, but existing files are updated at their
14708 @code{VPATH} location.
14710 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14712 @code{VPATH} search for a dependency that has an explicit rule.
14713 This is extremely annoying.
14715 When attempting a @code{VPATH} build for an autoconfiscated package
14716 (e.g., @code{mkdir build && cd build && ../configure}), this means
14718 @command{make} builds everything locally in the @file{build}
14719 directory, while @acronym{BSD} @command{make} builds new files locally and
14720 updates existing files in the source directory.
14723 $ @kbd{cat Makefile}
14726 foo.x bar.x: newer.x
14727 @@echo Building $@@
14728 $ @kbd{touch ../bar.x}
14729 $ @kbd{touch ../newer.x}
14730 $ @kbd{make} # GNU make
14733 $ @kbd{pmake} # NetBSD make
14736 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14739 $ @kbd{tmake} # Tru64 make
14742 $ @kbd{touch ../bar.x}
14743 $ @kbd{make} # GNU make
14745 $ @kbd{pmake} # NetBSD make
14747 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14750 $ @kbd{tmake} # Tru64 make
14755 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14756 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14757 @command{make} always
14758 update @file{bar.x}, even when @file{../bar.x} is up to date.
14760 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14761 decided to ignore a @code{VPATH} file name (e.g., it ignored
14762 @file{../bar.x} in the above example) it continues to ignore it when
14763 the target occurs as a prerequisite of another rule.
14765 The following example shows that @acronym{GNU} @command{make} does not look up
14766 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14767 because it ignored the @code{VPATH} result of @file{bar.x} while running
14768 the @code{bar.x: newer.x} rule.
14771 $ @kbd{cat Makefile}
14775 @@echo Building $@@
14779 $ @kbd{touch ../bar.x}
14780 $ @kbd{touch ../newer.x}
14781 $ @kbd{make} # GNU make
14784 cp: cannot stat `bar.x': No such file or directory
14785 make: *** [bar.y] Error 1
14786 $ @kbd{pmake} # NetBSD make
14790 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14791 echo Building bar.x
14793 cp: cannot stat `bar.x': No such file or directory
14795 $ @kbd{tmake} # Tru64 make
14797 cp: bar.x: No such file or directory
14801 Note that if you drop away the command from the @code{bar.x: newer.x}
14802 rule, @acronym{GNU} @command{make} magically starts to work: it
14803 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14804 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14805 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14809 $ @kbd{cat Makefile}
14816 $ @kbd{touch ../bar.x}
14817 $ @kbd{touch ../newer.x}
14818 $ @kbd{make} # GNU make
14821 $ @kbd{pmake} # NetBSD make
14824 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14826 cp: cannot stat `bar.x': No such file or directory
14828 $ @kbd{tmake} # Tru64 make
14832 It seems the sole solution that would please every @command{make}
14833 implementation is to never rely on @code{VPATH} searches for targets.
14834 In other words, @code{VPATH} should be reserved to unbuilt sources.
14837 @node Single Suffix Rules
14838 @section Single Suffix Rules and Separated Dependencies
14839 @cindex Single Suffix Inference Rule
14840 @cindex Rule, Single Suffix Inference
14841 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14842 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14845 @cindex Separated Dependencies
14846 @dfn{Separated dependencies} simply refers to listing the prerequisite
14847 of a target, without defining a rule. Usually one can list on the one
14848 hand side, the rules, and on the other hand side, the dependencies.
14850 Solaris @command{make} does not support separated dependencies for
14851 targets defined by single suffix rules:
14854 $ @kbd{cat Makefile}
14859 $ @kbd{touch foo.in}
14866 while @acronym{GNU} Make does:
14872 Makefile foo foo.in
14875 Note it works without the @samp{foo: foo.in} dependency.
14878 $ @kbd{cat Makefile}
14887 and it works with double suffix inference rules:
14890 $ @kbd{cat Makefile}
14892 .SUFFIXES: .in .out
14899 As a result, in such a case, you have to write target rules.
14901 @node Timestamps and Make
14902 @section Timestamp Resolution and Make
14903 @cindex timestamp resolution
14904 Traditionally, file timestamps had 1-second resolution, and
14905 @command{make} used those timestamps to determine whether one file was
14906 newer than the other. However, many modern file systems have
14907 timestamps with 1-nanosecond resolution. Some @command{make}
14908 implementations look at the entire timestamp; others ignore the
14909 fractional part, which can lead to incorrect results. Normally this
14910 is not a problem, but in some extreme cases you may need to use tricks
14911 like @samp{sleep 1} to work around timestamp truncation bugs.
14913 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14914 file timestamps to their full resolutions (@pxref{Limitations of Usual
14915 Tools}). Hence you should be wary of rules like this:
14922 as @file{dest} often appears to be older than @file{src} after the
14923 timestamp is truncated, and this can cause @command{make} to do
14924 needless rework the next time it is invoked. To work around this
14925 problem, you can use a timestamp file, e.g.:
14936 @c ======================================== Portable C and C++ Programming
14938 @node Portable C and C++
14939 @chapter Portable C and C++ Programming
14940 @cindex Portable C and C++ programming
14942 C and C++ programs often use low-level features of the underlying
14943 system, and therefore are often more difficult to make portable to other
14946 Several standards have been developed to help make your programs more
14947 portable. If you write programs with these standards in mind, you can
14948 have greater confidence that your programs work on a wide variety
14949 of systems. @xref{Standards, , Language Standards Supported by
14950 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
14951 (@acronym{GCC})}, for a list of C-related
14952 standards. Many programs also assume the
14953 @uref{http://www.opengroup.org/susv3, Posix standard}.
14955 Some old code is written to be portable to K&R C, which predates any C
14956 standard. K&R C compilers are no longer of practical interest, though,
14957 and the rest of section assumes at least C89, the first C standard.
14959 Program portability is a huge topic, and this section can only briefly
14960 introduce common pitfalls. @xref{System Portability, , Portability
14961 between System Types, standards, @acronym{GNU} Coding Standards}, for
14965 * Varieties of Unportability:: How to make your programs unportable
14966 * Integer Overflow:: When integers get too large
14967 * Null Pointers:: Properties of null pointers
14968 * Buffer Overruns:: Subscript errors and the like
14969 * Volatile Objects:: @code{volatile} and signals
14970 * Floating Point Portability:: Portable floating-point arithmetic
14971 * Exiting Portably:: Exiting and the exit status
14974 @node Varieties of Unportability
14975 @section Varieties of Unportability
14976 @cindex portability
14978 Autoconf tests and ordinary programs often need to test what is allowed
14979 on a system, and therefore they may need to deliberately exceed the
14980 boundaries of what the standards allow, if only to see whether an
14981 optional feature is present. When you write such a program, you should
14982 keep in mind the difference between constraints, unspecified behavior,
14983 and undefined behavior.
14985 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
14986 example constraint is that C programs must not declare a bit-field with
14987 negative width. Tests can therefore reliably assume that programs with
14988 negative-width bit-fields are rejected by a compiler that conforms
14991 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14992 multiple possibilities. For example, the order of evaluation of
14993 function arguments is unspecified. Some unspecified behavior is
14994 @dfn{implementation-defined}, i.e., documented by the implementation,
14995 but since Autoconf tests cannot read the documentation they cannot
14996 distinguish between implementation-defined and other unspecified
14997 behavior. It is common for Autoconf tests to probe implementations to
14998 determine otherwise-unspecified behavior.
15000 @dfn{Undefined behavior} is invalid behavior, where the standard allows
15001 the implementation to do anything it pleases. For example,
15002 dereferencing a null pointer leads to undefined behavior. If possible,
15003 test programs should avoid undefined behavior, since a program with
15004 undefined behavior might succeed on a test that should fail.
15006 The above rules apply to programs that are intended to conform to the
15007 standard. However, strictly-conforming programs are quite rare, since
15008 the standards are so limiting. A major goal of Autoconf is to support
15009 programs that use implementation features not described by the standard,
15010 and it is fairly common for test programs to violate the above rules, if
15011 the programs work well enough in practice.
15013 @node Integer Overflow
15014 @section Integer Overflow
15015 @cindex integer overflow
15016 @cindex overflow, signed integer
15017 @cindex signed integer overflow
15018 @cindex wraparound arithmetic
15020 In practice many portable C programs assume that signed integer overflow wraps
15021 around reliably using two's complement arithmetic. Yet the C standard
15022 says that program behavior is undefined on overflow, and in a few cases
15023 C programs do not work on some modern implementations because their
15024 overflows do not wrap around as their authors expected. Conversely, in
15025 signed integer remainder, the C standard requires overflow
15026 behavior that is commonly not implemented.
15029 * Integer Overflow Basics:: Why integer overflow is a problem
15030 * Signed Overflow Examples:: Examples of code assuming wraparound
15031 * Optimization and Wraparound:: Optimizations that break uses of wraparound
15032 * Signed Overflow Advice:: Practical advice for signed overflow issues
15033 * Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
15036 @node Integer Overflow Basics
15037 @subsection Basics of Integer Overflow
15038 @cindex integer overflow
15039 @cindex overflow, signed integer
15040 @cindex signed integer overflow
15041 @cindex wraparound arithmetic
15043 In languages like C, unsigned integer overflow reliably wraps around;
15044 e.g., @code{UINT_MAX + 1} yields zero.
15045 This is guaranteed by the C standard and is
15046 portable in practice, unless you specify aggressive,
15047 nonstandard optimization options
15048 suitable only for special applications.
15050 In contrast, the C standard says that signed integer overflow leads to
15051 undefined behavior where a program can do anything, including dumping
15052 core or overrunning a buffer. The misbehavior can even precede the
15053 overflow. Such an overflow can occur during addition, subtraction,
15054 multiplication, division, and left shift.
15056 Despite this requirement of the standard, many C programs and Autoconf
15057 tests assume that signed integer overflow silently wraps around modulo a
15058 power of two, using two's complement arithmetic, so long as you cast the
15059 resulting value to a signed integer type or store it into a signed
15060 integer variable. If you use conservative optimization flags, such
15061 programs are generally portable to the vast majority of modern
15062 platforms, with a few exceptions discussed later.
15064 For historical reasons the C standard also allows implementations with
15065 ones' complement or signed magnitude arithmetic, but it is safe to
15066 assume two's complement nowadays.
15068 Also, overflow can occur when converting an out-of-range value to a
15069 signed integer type. Here a standard implementation must define what
15070 happens, but this might include raising an exception. In practice all
15071 known implementations support silent wraparound in this case, so you need
15072 not worry about other possibilities.
15074 @node Signed Overflow Examples
15075 @subsection Examples of Code Assuming Wraparound Overflow
15076 @cindex integer overflow
15077 @cindex overflow, signed integer
15078 @cindex signed integer overflow
15079 @cindex wraparound arithmetic
15081 There has long been a tension between what the C standard requires for
15082 signed integer overflow, and what C programs commonly assume. The
15083 standard allows aggressive optimizations based on assumptions that
15084 overflow never occurs, but many practical C programs rely on overflow
15085 wrapping around. These programs do not conform to the standard, but
15086 they commonly work in practice because compiler writers are
15087 understandably reluctant to implement optimizations that would break
15088 many programs, unless perhaps a user specifies aggressive optimization.
15090 The C Standard says that if a program has signed integer overflow its
15091 behavior is undefined, and the undefined behavior can even precede the
15092 overflow. To take an extreme example:
15094 @c Inspired by Robert Dewar's example in
15095 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
15097 if (password == expected_password)
15098 allow_superuser_privileges ();
15099 else if (counter++ == INT_MAX)
15102 printf ("%d password mismatches\n", counter);
15106 If the @code{int} variable @code{counter} equals @code{INT_MAX},
15107 @code{counter++} must overflow and the behavior is undefined, so the C
15108 standard allows the compiler to optimize away the test against
15109 @code{INT_MAX} and the @code{abort} call.
15110 Worse, if an earlier bug in the program lets the compiler deduce that
15111 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
15112 the C standard allows the compiler to optimize away the password test
15113 and generate code that allows superuser privileges unconditionally.
15115 Despite this requirement by the standard, it has long been common for C
15116 code to assume wraparound arithmetic after signed overflow, and all
15117 known practical C implementations support some C idioms that assume
15118 wraparound signed arithmetic, even if the idioms do not conform
15119 strictly to the standard. If your code looks like the following
15120 examples it will almost surely work with real-world compilers.
15122 Here is an example derived from the 7th Edition Unix implementation of
15123 @code{atoi} (1979-01-10):
15129 while (*p >= '0' && *p <= '9')
15130 n = n * 10 + *p++ - '0';
15131 return (f ? -n : n);
15135 Even if the input string is in range, on most modern machines this has
15136 signed overflow when computing the most negative integer (the @code{-n}
15137 overflows) or a value near an extreme integer (the first @code{+}
15140 Here is another example, derived from the 7th Edition implementation of
15141 @code{rand} (1979-01-10). Here the programmer expects both
15142 multiplication and addition to wrap on overflow:
15145 static long int randx = 1;
15147 randx = randx * 1103515245 + 12345;
15148 return (randx >> 16) & 077777;
15151 In the following example, derived from the @acronym{GNU} C Library 2.5
15152 implementation of @code{mktime} (2006-09-09), the code assumes
15153 wraparound arithmetic in @code{+} to detect signed overflow:
15157 int sec_requested, sec_adjustment;
15159 t1 = t + sec_requested;
15160 t2 = t1 + sec_adjustment;
15161 if (((t1 < t) != (sec_requested < 0))
15162 | ((t2 < t1) != (sec_adjustment < 0)))
15166 If your code looks like these examples, it is probably safe even though
15167 it does not strictly conform to the C standard. This might lead one to
15168 believe that one can generally assume wraparound on overflow, but that
15169 is not always true, as can be seen in the next section.
15171 @node Optimization and Wraparound
15172 @subsection Optimizations That Break Wraparound Arithmetic
15173 @cindex loop induction
15175 Compilers sometimes generate code that is incompatible with wraparound
15176 integer arithmetic. A simple example is an algebraic simplification: a
15177 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
15178 because it assumes that @code{i * 2000} does not overflow. The
15179 translation is not equivalent to the original when overflow occurs:
15180 e.g., in the typical case of 32-bit signed two's complement wraparound
15181 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
15182 the original expression returns @minus{}2147483 but the optimized
15183 version returns the mathematically correct value 2147484.
15185 More subtly, loop induction optimizations often exploit the undefined
15186 behavior of signed overflow. Consider the following contrived function
15191 sumc (int lo, int hi)
15195 for (i = lo; i <= hi; i++)
15202 To avoid multiplying by 53 each time through the loop, an optimizing
15203 compiler might internally transform @code{sumc} to the equivalent of the
15208 transformed_sumc (int lo, int hi)
15213 for (ic = lo * 53; ic <= hic; ic += 53)
15220 This transformation is allowed by the C standard, but it is invalid for
15221 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
15222 overflow in computing expressions like @code{hi * 53} can cause the
15223 expression @code{i <= hi} to yield a different value from the
15224 transformed expression @code{ic <= hic}.
15226 For this reason, compilers that use loop induction and similar
15227 techniques often do not support reliable wraparound arithmetic when a
15228 loop induction variable like @code{ic} is involved. Since loop
15229 induction variables are generated by the compiler, and are not visible
15230 in the source code, it is not always trivial to say whether the problem
15233 Hardly any code actually depends on wraparound arithmetic in cases like
15234 these, so in practice these loop induction optimizations are almost
15235 always useful. However, edge cases in this area can cause problems.
15240 for (j = 1; 0 < j; j *= 2)
15245 Here, the loop attempts to iterate through all powers of 2 that
15246 @code{int} can represent, but the C standard allows a compiler to
15247 optimize away the comparison and generate an infinite loop,
15248 under the argument that behavior is undefined on overflow. As of this
15249 writing this optimization is not done by any production version of
15250 @acronym{GCC} with @option{-O2}, but it might be performed by other
15251 compilers, or by more aggressive @acronym{GCC} optimization options,
15252 and the @acronym{GCC} developers have not decided whether it will
15253 continue to work with @acronym{GCC} and @option{-O2}.
15255 @node Signed Overflow Advice
15256 @subsection Practical Advice for Signed Overflow Issues
15257 @cindex integer overflow
15258 @cindex overflow, signed integer
15259 @cindex signed integer overflow
15260 @cindex wraparound arithmetic
15262 Ideally the safest approach is to avoid signed integer overflow
15263 entirely. For example, instead of multiplying two signed integers, you
15264 can convert them to unsigned integers, multiply the unsigned values,
15265 then test whether the result is in signed range.
15267 Rewriting code in this way will be inconvenient, though, particularly if
15268 the signed values might be negative. Also, it may hurt
15269 performance. Using unsigned arithmetic to check for overflow is
15270 particularly painful to do portably and efficiently when dealing with an
15271 integer type like @code{uid_t} whose width and signedness vary from
15272 platform to platform.
15274 Furthermore, many C applications pervasively assume wraparound behavior
15275 and typically it is not easy to find and remove all these assumptions.
15276 Hence it is often useful to maintain nonstandard code that assumes
15277 wraparound on overflow, instead of rewriting the code. The rest of this
15278 section attempts to give practical advice for this situation.
15280 If your code wants to detect signed integer overflow in @code{sum = a +
15281 b}, it is generally safe to use an expression like @code{(sum < a) != (b
15284 If your code uses a signed loop index, make sure that the index cannot
15285 overflow, along with all signed expressions derived from the index.
15286 Here is a contrived example of problematic code with two instances of
15290 for (i = INT_MAX - 10; i <= INT_MAX; i++)
15293 report_overflow ();
15299 Because of the two overflows, a compiler might optimize away or
15300 transform the two comparisons in a way that is incompatible with the
15301 wraparound assumption.
15303 If your code uses an expression like @code{(i * 2000) / 1000} and you
15304 actually want the multiplication to wrap around on overflow, use
15305 unsigned arithmetic
15306 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
15308 If your code assumes wraparound behavior and you want to insulate it
15309 against any @acronym{GCC} optimizations that would fail to support that
15310 behavior, you should use @acronym{GCC}'s @option{-fwrapv} option, which
15311 causes signed overflow to wrap around reliably (except for division and
15312 remainder, as discussed in the next section).
15314 If you need to port to platforms where signed integer overflow does not
15315 reliably wrap around (e.g., due to hardware overflow checking, or to
15316 highly aggressive optimizations), you should consider debugging with
15317 @acronym{GCC}'s @option{-ftrapv} option, which causes signed overflow to
15318 raise an exception.
15320 @node Signed Integer Division
15321 @subsection Signed Integer Division and Integer Overflow
15322 @cindex division, integer
15325 integer division is not always harmless: for example, on CPUs of the
15326 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
15327 which by default terminates the program. Worse, taking the remainder
15328 of these two values typically yields the same signal on these CPUs,
15329 even though the C standard requires @code{INT_MIN % -1} to yield zero
15330 because the expression does not overflow.
15332 @node Null Pointers
15333 @section Properties of Null Pointers
15334 @cindex null pointers
15336 Most modern hosts reliably fail when you attempt to dereference a null
15339 On almost all modern hosts, null pointers use an all-bits-zero internal
15340 representation, so you can reliably use @code{memset} with 0 to set all
15341 the pointers in an array to null values.
15343 If @code{p} is a null pointer to an object type, the C expression
15344 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
15345 the standard says that it has undefined behavior.
15347 @node Buffer Overruns
15348 @section Buffer Overruns and Subscript Errors
15349 @cindex buffer overruns
15351 Buffer overruns and subscript errors are the most common dangerous
15352 errors in C programs. They result in undefined behavior because storing
15353 outside an array typically modifies storage that is used by some other
15354 object, and most modern systems lack runtime checks to catch these
15355 errors. Programs should not rely on buffer overruns being caught.
15357 There is one exception to the usual rule that a portable program cannot
15358 address outside an array. In C, it is valid to compute the address just
15359 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15360 so long as you do not dereference the resulting pointer. But it is not
15361 valid to compute the address just before an object, e.g., @code{&a[-1]};
15362 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
15363 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15364 reliable in general, and it is usually easy enough to avoid the
15365 potential portability problem, e.g., by allocating an extra unused array
15366 element at the start or end.
15368 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
15370 users might also consider using the @option{-fmudflap} option to catch
15373 Buffer overruns are usually caused by off-by-one errors, but there are
15374 more subtle ways to get them.
15376 Using @code{int} values to index into an array or compute array sizes
15377 causes problems on typical 64-bit hosts where an array index might
15378 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
15379 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
15380 are signed, and are wide enough in practice.
15382 If you add or multiply two numbers to calculate an array size, e.g.,
15383 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
15384 multiplication overflows.
15386 Many implementations of the @code{alloca} function silently misbehave
15387 and can generate buffer overflows if given sizes that are too large.
15388 The size limits are implementation dependent, but are at least 4000
15389 bytes on all platforms that we know about.
15391 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
15392 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
15393 portable code should not use them unless the inputs are known to be
15394 within certain limits. The time-related functions can overflow their
15395 buffers if given timestamps out of range (e.g., a year less than -999
15396 or greater than 9999). Time-related buffer overflows cannot happen with
15397 recent-enough versions of the @acronym{GNU} C library, but are possible
15399 implementations. The @code{gets} function is the worst, since it almost
15400 invariably overflows its buffer when presented with an input line larger
15403 @node Volatile Objects
15404 @section Volatile Objects
15405 @cindex volatile objects
15407 The keyword @code{volatile} is often misunderstood in portable code.
15408 Its use inhibits some memory-access optimizations, but programmers often
15409 wish that it had a different meaning than it actually does.
15411 @code{volatile} was designed for code that accesses special objects like
15412 memory-mapped device registers whose contents spontaneously change.
15413 Such code is inherently low-level, and it is difficult to specify
15414 portably what @code{volatile} means in these cases. The C standard
15415 says, ``What constitutes an access to an object that has
15416 volatile-qualified type is implementation-defined,'' so in theory each
15417 implementation is supposed to fill in the gap by documenting what
15418 @code{volatile} means for that implementation. In practice, though,
15419 this documentation is usually absent or incomplete.
15421 One area of confusion is the distinction between objects defined with
15422 volatile types, and volatile lvalues. From the C standard's point of
15423 view, an object defined with a volatile type has externally visible
15424 behavior. You can think of such objects as having little oscilloscope
15425 probes attached to them, so that the user can observe some properties of
15426 accesses to them, just as the user can observe data written to output
15427 files. However, the standard does not make it clear whether users can
15428 observe accesses by volatile lvalues to ordinary objects. For example:
15431 /* Declare and access a volatile object.
15432 Accesses to X are "visible" to users. */
15433 static int volatile x;
15436 /* Access two ordinary objects via a volatile lvalue.
15437 It's not clear whether accesses to *P are "visible". */
15439 int *z = malloc (sizeof (int));
15447 Programmers often wish that @code{volatile} meant ``Perform the memory
15448 access here and now, without merging several memory accesses, without
15449 changing the memory word size, and without reordering.'' But the C
15450 standard does not require this. For objects defined with a volatile
15451 type, accesses must be done before the next sequence point; but
15452 otherwise merging, reordering, and word-size change is allowed. Worse,
15453 it is not clear from the standard whether volatile lvalues provide more
15454 guarantees in general than nonvolatile lvalues, if the underlying
15455 objects are ordinary.
15457 Even when accessing objects defined with a volatile type,
15458 the C standard allows only
15459 extremely limited signal handlers: the behavior is undefined if a signal
15460 handler reads any nonlocal object, or writes to any nonlocal object
15461 whose type is not @code{sig_atomic_t volatile}, or calls any standard
15462 library function other than @code{abort}, @code{signal}, and (if C99)
15463 @code{_Exit}. Hence C compilers need not worry about a signal handler
15464 disturbing ordinary computation, unless the computation accesses a
15465 @code{sig_atomic_t volatile} lvalue that is not a local variable.
15466 (There is an obscure exception for accesses via a pointer to a volatile
15467 character, since it may point into part of a @code{sig_atomic_t
15468 volatile} object.) Posix
15469 adds to the list of library functions callable from a portable signal
15470 handler, but otherwise is like the C standard in this area.
15472 Some C implementations allow memory-access optimizations within each
15473 translation unit, such that actual behavior agrees with the behavior
15474 required by the standard only when calling a function in some other
15475 translation unit, and a signal handler acts like it was called from a
15476 different translation unit. The C standard hints that in these
15477 implementations, objects referred to by signal handlers ``would require
15478 explicit specification of @code{volatile} storage, as well as other
15479 implementation-defined restrictions.'' But unfortunately even for this
15480 special case these other restrictions are often not documented well.
15481 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
15482 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
15483 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
15484 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
15485 restrictions imposed by the @acronym{GNU} C library. Restrictions
15486 differ on other platforms.
15488 If possible, it is best to use a signal handler that fits within the
15489 limits imposed by the C and Posix standards.
15491 If this is not practical, you can try the following rules of thumb. A
15492 signal handler should access only volatile lvalues, preferably lvalues
15493 that refer to objects defined with a volatile type, and should not
15494 assume that the accessed objects have an internally consistent state
15495 if they are larger than a machine word. Furthermore, installers
15496 should employ compilers and compiler options that are commonly used
15497 for building operating system kernels, because kernels often need more
15498 from @code{volatile} than the C Standard requires, and installers who
15499 compile an application in a similar environment can sometimes benefit
15500 from the extra constraints imposed by kernels on compilers.
15501 Admittedly we are handwaving somewhat here, as there are few
15502 guarantees in this area; the rules of thumb may help to fix some bugs
15503 but there is a good chance that they will not fix them all.
15505 For @code{volatile}, C++ has the same problems that C does.
15506 Multithreaded applications have even more problems with @code{volatile},
15507 but they are beyond the scope of this section.
15509 The bottom line is that using @code{volatile} typically hurts
15510 performance but should not hurt correctness. In some cases its use
15511 does help correctness, but these cases are often so poorly understood
15512 that all too often adding @code{volatile} to a data structure merely
15513 alleviates some symptoms of a bug while not fixing the bug in general.
15515 @node Floating Point Portability
15516 @section Floating Point Portability
15517 @cindex floating point
15519 Almost all modern systems use IEEE-754 floating point, and it is safe to
15520 assume IEEE-754 in most portable code these days. For more information,
15521 please see David Goldberg's classic paper
15522 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15523 Scientist Should Know About Floating-Point Arithmetic}.
15525 @node Exiting Portably
15526 @section Exiting Portably
15527 @cindex exiting portably
15529 A C or C++ program can exit with status @var{N} by returning
15530 @var{N} from the @code{main} function. Portable programs are supposed
15531 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15532 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15533 fail by exiting with status 1, and test programs that assume Posix can
15534 fail by exiting with status values from 1 through 255. Programs on
15535 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15536 status when @code{main} returned nonzero, but ancient systems like these
15537 are no longer of practical concern.
15539 A program can also exit with status @var{N} by passing @var{N} to the
15540 @code{exit} function, and a program can fail by calling the @code{abort}
15541 function. If a program is specialized to just some platforms, it can fail
15542 by calling functions specific to those platforms, e.g., @code{_exit}
15543 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
15544 function should be declared, typically by including a header. For
15545 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15546 either directly or via the default includes (@pxref{Default Includes}).
15548 A program can fail due to undefined behavior such as dereferencing a null
15549 pointer, but this is not recommended as undefined behavior allows an
15550 implementation to do whatever it pleases and this includes exiting
15554 @c ================================================== Manual Configuration
15556 @node Manual Configuration
15557 @chapter Manual Configuration
15559 A few kinds of features can't be guessed automatically by running test
15560 programs. For example, the details of the object-file format, or
15561 special options that need to be passed to the compiler or linker. You
15562 can check for such features using ad-hoc means, such as having
15563 @command{configure} check the output of the @code{uname} program, or
15564 looking for libraries that are unique to particular systems. However,
15565 Autoconf provides a uniform method for handling unguessable features.
15568 * Specifying Names:: Specifying the system type
15569 * Canonicalizing:: Getting the canonical system type
15570 * Using System Type:: What to do with the system type
15573 @node Specifying Names
15574 @section Specifying the System Type
15575 @cindex System type
15578 @command{configure} scripts can make decisions based on a canonical name
15579 for the system type, which has the form:
15580 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15581 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15583 @command{configure} can usually guess the canonical name for the type of
15584 system it's running on. To do so it runs a script called
15585 @command{config.guess}, which infers the name using the @code{uname}
15586 command or symbols predefined by the C preprocessor.
15588 Alternately, the user can specify the system type with command line
15589 arguments to @command{configure}. Doing so is necessary when
15590 cross-compiling. In the most complex case of cross-compiling, three
15591 system types are involved. The options to specify them are:
15594 @item --build=@var{build-type}
15595 the type of system on which the package is being configured and
15596 compiled. It defaults to the result of running @command{config.guess}.
15598 @item --host=@var{host-type}
15599 the type of system on which the package runs. By default it is the
15600 same as the build machine. Specifying it enables the cross-compilation
15603 @item --target=@var{target-type}
15604 the type of system for which any compiler tools in the package
15605 produce code (rarely needed). By default, it is the same as host.
15608 If you mean to override the result of @command{config.guess}, use
15609 @option{--build}, not @option{--host}, since the latter enables
15610 cross-compilation. For historical reasons,
15611 whenever you specify @option{--host},
15612 be sure to specify @option{--build} too; this will be fixed in the
15613 future. So, to enter cross-compilation mode, use a command like this
15616 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15620 Note that if you do not specify @option{--host}, @command{configure}
15621 fails if it can't run the code generated by the specified compiler. For
15622 example, configuring as follows fails:
15625 ./configure CC=m68k-coff-gcc
15628 In the future, when cross-compiling Autoconf will @emph{not}
15629 accept tools (compilers, linkers, assemblers) whose name is not
15630 prefixed with the host type. The only case when this may be
15631 useful is when you really are not cross-compiling, but only
15632 building for a least-common-denominator architecture: an example
15633 is building for @code{i386-pc-linux-gnu} while running on an
15634 @code{i686-pc-linux-gnu} architecture. In this case, some particular
15635 pairs might be similar enough to let you get away with the system
15636 compilers, but in general the compiler might make bogus assumptions
15637 on the host: if you know what you are doing, please create symbolic
15638 links from the host compiler to the build compiler.
15640 @cindex @command{config.sub}
15641 @command{configure} recognizes short aliases for many system types; for
15642 example, @samp{decstation} can be used instead of
15643 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
15644 @command{config.sub} to canonicalize system type aliases.
15646 This section deliberately omits the description of the obsolete
15647 interface; see @ref{Hosts and Cross-Compilation}.
15650 @node Canonicalizing
15651 @section Getting the Canonical System Type
15652 @cindex System type
15653 @cindex Canonical system type
15655 The following macros make the system type available to @command{configure}
15658 @ovindex build_alias
15659 @ovindex host_alias
15660 @ovindex target_alias
15662 The variables @samp{build_alias}, @samp{host_alias}, and
15663 @samp{target_alias} are always exactly the arguments of @option{--build},
15664 @option{--host}, and @option{--target}; in particular, they are left empty
15665 if the user did not use them, even if the corresponding
15666 @code{AC_CANONICAL} macro was run. Any configure script may use these
15667 variables anywhere. These are the variables that should be used when in
15668 interaction with the user.
15670 If you need to recognize some special environments based on their system
15671 type, run the following macros to get canonical system names. These
15672 variables are not set before the macro call.
15674 If you use these macros, you must distribute @command{config.guess} and
15675 @command{config.sub} along with your source code. @xref{Output}, for
15676 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15677 to control in which directory @command{configure} looks for those scripts.
15680 @defmac AC_CANONICAL_BUILD
15681 @acindex{CANONICAL_BUILD}
15684 @ovindex build_vendor
15686 Compute the canonical build-system type variable, @code{build}, and its
15687 three individual parts @code{build_cpu}, @code{build_vendor}, and
15690 If @option{--build} was specified, then @code{build} is the
15691 canonicalization of @code{build_alias} by @command{config.sub},
15692 otherwise it is determined by the shell script @command{config.guess}.
15695 @defmac AC_CANONICAL_HOST
15696 @acindex{CANONICAL_HOST}
15699 @ovindex host_vendor
15701 Compute the canonical host-system type variable, @code{host}, and its
15702 three individual parts @code{host_cpu}, @code{host_vendor}, and
15705 If @option{--host} was specified, then @code{host} is the
15706 canonicalization of @code{host_alias} by @command{config.sub},
15707 otherwise it defaults to @code{build}.
15710 @defmac AC_CANONICAL_TARGET
15711 @acindex{CANONICAL_TARGET}
15713 @ovindex target_cpu
15714 @ovindex target_vendor
15716 Compute the canonical target-system type variable, @code{target}, and its
15717 three individual parts @code{target_cpu}, @code{target_vendor}, and
15720 If @option{--target} was specified, then @code{target} is the
15721 canonicalization of @code{target_alias} by @command{config.sub},
15722 otherwise it defaults to @code{host}.
15725 Note that there can be artifacts due to the backward compatibility
15726 code. See @xref{Hosts and Cross-Compilation}, for more.
15728 @node Using System Type
15729 @section Using the System Type
15731 In @file{configure.ac} the system type is generally used by one or more
15732 @code{case} statements to select system-specifics. Shell wildcards can
15733 be used to match a group of system types.
15735 For example, an extra assembler code object file could be chosen, giving
15736 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
15737 following would be used in a makefile to add the object to a
15738 program or library.
15742 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15743 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
15746 AC_SUBST([CYCLE_OBJ])
15749 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15750 to select variant source files, for example optimized code for some
15751 CPUs. The configured CPU type doesn't always indicate exact CPU types,
15752 so some runtime capability checks may be necessary too.
15756 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15757 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15758 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15762 The host system type can also be used to find cross-compilation tools
15763 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15765 The above examples all show @samp{$host}, since this is where the code
15766 is going to run. Only rarely is it necessary to test @samp{$build}
15767 (which is where the build is being done).
15769 Whenever you're tempted to use @samp{$host} it's worth considering
15770 whether some sort of probe would be better. New system types come along
15771 periodically or previously missing features are added. Well-written
15772 probes can adapt themselves to such things, but hard-coded lists of
15773 names can't. Here are some guidelines,
15777 Availability of libraries and library functions should always be checked
15780 Variant behavior of system calls is best identified with runtime tests
15781 if possible, but bug workarounds or obscure difficulties might have to
15782 be driven from @samp{$host}.
15784 Assembler code is inevitably highly CPU-specific and is best selected
15785 according to @samp{$host_cpu}.
15787 Assembler variations like underscore prefix on globals or ELF versus
15788 COFF type directives are however best determined by probing, perhaps
15789 even examining the compiler output.
15792 @samp{$target} is for use by a package creating a compiler or similar.
15793 For ordinary packages it's meaningless and should not be used. It
15794 indicates what the created compiler should generate code for, if it can
15795 cross-compile. @samp{$target} generally selects various hard-coded CPU
15796 and system conventions, since usually the compiler or tools under
15797 construction themselves determine how the target works.
15800 @c ===================================================== Site Configuration.
15802 @node Site Configuration
15803 @chapter Site Configuration
15805 @command{configure} scripts support several kinds of local configuration
15806 decisions. There are ways for users to specify where external software
15807 packages are, include or exclude optional features, install programs
15808 under modified names, and set default values for @command{configure}
15812 * Help Formatting:: Customizing @samp{configure --help}
15813 * External Software:: Working with other optional software
15814 * Package Options:: Selecting optional features
15815 * Pretty Help Strings:: Formatting help string
15816 * Option Checking:: Controlling checking of @command{configure} options
15817 * Site Details:: Configuring site details
15818 * Transforming Names:: Changing program names when installing
15819 * Site Defaults:: Giving @command{configure} local defaults
15822 @node Help Formatting
15823 @section Controlling Help Output
15825 Users consult @samp{configure --help} to learn of configuration
15826 decisions specific to your package. By default, @command{configure}
15827 breaks this output into sections for each type of option; within each
15828 section, help strings appear in the order @file{configure.ac} defines
15834 --enable-bar include bar
15841 @defmac AC_PRESERVE_HELP_ORDER
15842 @acindex{PRESERVE_HELP_ORDER}
15844 Request an alternate @option{--help} format, in which options of all
15845 types appear together, in the order defined. Call this macro before any
15846 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15849 Optional Features and Packages:
15851 --enable-bar include bar
15857 @node External Software
15858 @section Working With External Software
15859 @cindex External software
15861 Some packages require, or can optionally use, other software packages
15862 that are already installed. The user can give @command{configure}
15863 command line options to specify which such external software to use.
15864 The options have one of these forms:
15866 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15869 --with-@var{package}[=@var{arg}]
15870 --without-@var{package}
15873 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15874 instead of some other linker. @option{--with-x} means work with The X
15877 The user can give an argument by following the package name with
15878 @samp{=} and the argument. Giving an argument of @samp{no} is for
15879 packages that are used by default; it says to @emph{not} use the
15880 package. An argument that is neither @samp{yes} nor @samp{no} could
15881 include a name or number of a version of the other package, to specify
15882 more precisely which other package this program is supposed to work
15883 with. If no argument is given, it defaults to @samp{yes}.
15884 @option{--without-@var{package}} is equivalent to
15885 @option{--with-@var{package}=no}.
15887 Normally @command{configure} scripts complain about
15888 @option{--with-@var{package}} options that they do not support.
15889 @xref{Option Checking}, for details, and for how to override the
15892 For each external software package that may be used, @file{configure.ac}
15893 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
15894 user asked to use it. Whether each package is used or not by default,
15895 and which arguments are valid, is up to you.
15897 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15899 If the user gave @command{configure} the option @option{--with-@var{package}}
15900 or @option{--without-@var{package}}, run shell commands
15901 @var{action-if-given}. If neither option was given, run shell commands
15902 @var{action-if-not-given}. The name @var{package} indicates another
15903 software package that this program should work with. It should consist
15904 only of alphanumeric characters, dashes, and dots.
15906 The option's argument is available to the shell commands
15907 @var{action-if-given} in the shell variable @code{withval}, which is
15908 actually just the value of the shell variable @code{with_@var{package}},
15909 with any non-alphanumeric characters changed into @samp{_}. You may use that
15910 variable instead, if you wish.
15912 The argument @var{help-string} is a description of the option that
15915 --with-readline support fancy command line editing
15919 @var{help-string} may be more than one line long, if more detail is
15920 needed. Just make sure the columns line up in @samp{configure
15921 --help}. Avoid tabs in the help string. You'll need to enclose the
15922 help string in @samp{[} and @samp{]} in order to produce the leading
15925 You should format your @var{help-string} with the macro
15926 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15928 The following example shows how to use the @code{AC_ARG_WITH} macro in
15929 a common situation. You want to let the user decide whether to enable
15930 support for an external library (e.g., the readline library); if the user
15931 specified neither @option{--with-readline} nor @option{--without-readline},
15932 you want to enable support for readline only if the library is available
15935 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15937 AC_ARG_WITH([readline],
15938 [AS_HELP_STRING([--with-readline],
15939 [support fancy command line editing @@<:@@default=check@@:>@@])],
15941 [with_readline=check])
15944 AS_IF([test "x$with_readline" != xno],
15945 [AC_CHECK_LIB([readline], [main],
15946 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15947 AC_DEFINE([HAVE_LIBREADLINE], [1],
15948 [Define if you have libreadline])
15950 [if test "x$with_readline" != xcheck; then
15952 [--with-readline was given, but test for readline failed])
15957 The next example shows how to use @code{AC_ARG_WITH} to give the user the
15958 possibility to enable support for the readline library, in case it is still
15959 experimental and not well tested, and is therefore disabled by default.
15961 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15963 AC_ARG_WITH([readline],
15964 [AS_HELP_STRING([--with-readline],
15965 [enable experimental support for readline])],
15967 [with_readline=no])
15970 AS_IF([test "x$with_readline" != xno],
15971 [AC_CHECK_LIB([readline], [main],
15972 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15973 AC_DEFINE([HAVE_LIBREADLINE], [1],
15974 [Define if you have libreadline])
15977 [--with-readline was given, but test for readline failed])],
15981 The last example shows how to use @code{AC_ARG_WITH} to give the user the
15982 possibility to disable support for the readline library, given that it is
15983 an important feature and that it should be enabled by default.
15985 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15987 AC_ARG_WITH([readline],
15988 [AS_HELP_STRING([--without-readline],
15989 [disable support for readline])],
15991 [with_readline=yes])
15994 AS_IF([test "x$with_readline" != xno],
15995 [AC_CHECK_LIB([readline], [main],
15996 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15997 AC_DEFINE([HAVE_LIBREADLINE], [1],
15998 [Define if you have libreadline])
16001 [readline test failed (--without-readline to disable)])],
16005 These three examples can be easily adapted to the case where
16006 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
16007 @ref{Package Options}).
16010 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
16012 This is an obsolete version of @code{AC_ARG_WITH} that does not
16013 support providing a help string.
16016 @node Package Options
16017 @section Choosing Package Options
16018 @cindex Package options
16019 @cindex Options, package
16021 If a software package has optional compile-time features, the user can
16022 give @command{configure} command line options to specify whether to
16023 compile them. The options have one of these forms:
16025 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16028 --enable-@var{feature}[=@var{arg}]
16029 --disable-@var{feature}
16032 These options allow users to choose which optional features to build and
16033 install. @option{--enable-@var{feature}} options should never make a
16034 feature behave differently or cause one feature to replace another.
16035 They should only cause parts of the program to be built rather than left
16038 The user can give an argument by following the feature name with
16039 @samp{=} and the argument. Giving an argument of @samp{no} requests
16040 that the feature @emph{not} be made available. A feature with an
16041 argument looks like @option{--enable-debug=stabs}. If no argument is
16042 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
16043 equivalent to @option{--enable-@var{feature}=no}.
16045 Normally @command{configure} scripts complain about
16046 @option{--enable-@var{package}} options that they do not support.
16047 @xref{Option Checking}, for details, and for how to override the
16050 For each optional feature, @file{configure.ac} should call
16051 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
16052 to include it. Whether each feature is included or not by default, and
16053 which arguments are valid, is up to you.
16055 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
16056 @acindex{ARG_ENABLE}
16057 If the user gave @command{configure} the option
16058 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
16059 shell commands @var{action-if-given}. If neither option was given, run
16060 shell commands @var{action-if-not-given}. The name @var{feature}
16061 indicates an optional user-level facility. It should consist only of
16062 alphanumeric characters, dashes, and dots.
16064 The option's argument is available to the shell commands
16065 @var{action-if-given} in the shell variable @code{enableval}, which is
16066 actually just the value of the shell variable
16067 @code{enable_@var{feature}}, with any non-alphanumeric characters changed into
16068 @samp{_}. You may use that variable instead, if you wish. The
16069 @var{help-string} argument is like that of @code{AC_ARG_WITH}
16070 (@pxref{External Software}).
16072 You should format your @var{help-string} with the macro
16073 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16075 See the examples suggested with the definition of @code{AC_ARG_WITH}
16076 (@pxref{External Software}) to get an idea of possible applications of
16077 @code{AC_ARG_ENABLE}.
16080 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
16082 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
16083 support providing a help string.
16087 @node Pretty Help Strings
16088 @section Making Your Help Strings Look Pretty
16089 @cindex Help strings
16091 Properly formatting the @samp{help strings} which are used in
16092 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
16093 (@pxref{Package Options}) can be challenging. Specifically, you want
16094 your own @samp{help strings} to line up in the appropriate columns of
16095 @samp{configure --help} just like the standard Autoconf @samp{help
16096 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
16098 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
16099 @acindex{HELP_STRING}
16101 Expands into an help string that looks pretty when the user executes
16102 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
16103 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
16104 Options}). The following example makes this clearer.
16108 [AS_HELP_STRING([--with-foo],
16109 [use foo (default is no)])],
16110 [use_foo=$withval],
16114 The second argument of @code{AS_HELP_STRING} is
16115 not a literal, and should not be double quoted.
16116 @xref{Autoconf Language}, for a more detailed explanation.
16117 Then the last few lines of @samp{configure --help} appear like
16121 --enable and --with options recognized:
16122 --with-foo use foo (default is no)
16125 The @code{AS_HELP_STRING} macro is particularly helpful when the
16126 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
16127 arguments, as shown in the following example.
16130 AC_DEFUN([MY_ARG_WITH],
16132 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
16133 [use_[]$1=$withval],
16139 @node Option Checking
16140 @section Controlling Checking of @command{configure} Options
16141 @cindex Options, Package
16143 The @command{configure} script checks its command-line options against a
16144 list of known options, like @option{--help} or @option{--config-cache}.
16145 An unknown option ordinarily indicates a mistake by the user and
16146 @command{configure} halts with an error. However, by default unknown
16147 @option{--with-@var{package}} and @option{--enable-@var{feature}}
16148 options elicit only a warning, to support configuring entire source
16151 Source trees often contain multiple packages with a top-level
16152 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
16153 (@pxref{Subdirectories}). Because the packages generally support
16154 different @option{--with-@var{package}} and
16155 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
16156 Standards say they must accept unrecognized options without halting.
16157 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
16158 automatically disables the warnings.
16160 This default behavior may be modified in two ways. First, the installer
16161 can invoke @command{configure} with the
16162 @option{--disable-option-checking} or
16163 @option{--enable-option-checking=fatal} options to disable these
16164 warnings or turn them into fatal errors, respectively. Second, the
16165 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
16167 @defmac AC_DISABLE_OPTION_CHECKING
16168 @acindex{DISABLE_OPTION_CHECKING}
16170 By default, disable warnings for unrecognized
16171 @option{--with-@var{package}} or @option{--enable-@var{feature}}
16172 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
16174 The installer can override this behavior by passing
16175 @option{--enable-option-checking} (enable warnings) or
16176 @option{--enable-option-checking=fatal} (enable errors) to
16177 @command{configure}.
16182 @section Configuring Site Details
16183 @cindex Site details
16185 Some software packages require complex site-specific information. Some
16186 examples are host names to use for certain services, company names, and
16187 email addresses to contact. Since some configuration scripts generated
16188 by Metaconfig ask for such information interactively, people sometimes
16189 wonder how to get that information in Autoconf-generated configuration
16190 scripts, which aren't interactive.
16192 Such site configuration information should be put in a file that is
16193 edited @emph{only by users}, not by programs. The location of the file
16194 can either be based on the @code{prefix} variable, or be a standard
16195 location such as the user's home directory. It could even be specified
16196 by an environment variable. The programs should examine that file at
16197 runtime, rather than at compile time. Runtime configuration is more
16198 convenient for users and makes the configuration process simpler than
16199 getting the information while configuring. @xref{Directory Variables, ,
16200 Variables for Installation Directories, standards, @acronym{GNU} Coding
16201 Standards}, for more information on where to put data files.
16203 @node Transforming Names
16204 @section Transforming Program Names When Installing
16205 @cindex Transforming program names
16206 @cindex Program names, transforming
16208 Autoconf supports changing the names of programs when installing them.
16209 In order to use these transformations, @file{configure.ac} must call the
16210 macro @code{AC_ARG_PROGRAM}.
16212 @defmac AC_ARG_PROGRAM
16213 @acindex{ARG_PROGRAM}
16214 @ovindex program_transform_name
16215 Place in output variable @code{program_transform_name} a sequence of
16216 @code{sed} commands for changing the names of installed programs.
16218 If any of the options described below are given to @command{configure},
16219 program names are transformed accordingly. Otherwise, if
16220 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
16221 is given, the target type followed by a dash is used as a prefix.
16222 Otherwise, no program name transformation is done.
16226 * Transformation Options:: @command{configure} options to transform names
16227 * Transformation Examples:: Sample uses of transforming names
16228 * Transformation Rules:: Makefile uses of transforming names
16231 @node Transformation Options
16232 @subsection Transformation Options
16234 You can specify name transformations by giving @command{configure} these
16235 command line options:
16238 @item --program-prefix=@var{prefix}
16239 prepend @var{prefix} to the names;
16241 @item --program-suffix=@var{suffix}
16242 append @var{suffix} to the names;
16244 @item --program-transform-name=@var{expression}
16245 perform @code{sed} substitution @var{expression} on the names.
16248 @node Transformation Examples
16249 @subsection Transformation Examples
16251 These transformations are useful with programs that can be part of a
16252 cross-compilation development environment. For example, a
16253 cross-assembler running on a Sun 4 configured with
16254 @option{--target=i960-vxworks} is normally installed as
16255 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
16256 with a native Sun 4 assembler.
16258 You can force a program name to begin with @file{g}, if you don't want
16259 @acronym{GNU} programs installed on your system to shadow other programs with
16260 the same name. For example, if you configure @acronym{GNU} @code{diff} with
16261 @option{--program-prefix=g}, then when you run @samp{make install} it is
16262 installed as @file{/usr/local/bin/gdiff}.
16264 As a more sophisticated example, you could use
16267 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
16271 to prepend @samp{g} to most of the program names in a source tree,
16272 excepting those like @code{gdb} that already have one and those like
16273 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
16274 assuming that you have a source tree containing those programs that is
16275 set up to use this feature.)
16277 One way to install multiple versions of some programs simultaneously is
16278 to append a version number to the name of one or both. For example, if
16279 you want to keep Autoconf version 1 around for awhile, you can configure
16280 Autoconf version 2 using @option{--program-suffix=2} to install the
16281 programs as @file{/usr/local/bin/autoconf2},
16282 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
16283 that only the binaries are renamed, therefore you'd have problems with
16284 the library files which might overlap.
16286 @node Transformation Rules
16287 @subsection Transformation Rules
16289 Here is how to use the variable @code{program_transform_name} in a
16290 @file{Makefile.in}:
16293 PROGRAMS = cp ls rm
16294 transform = @@program_transform_name@@
16296 for p in $(PROGRAMS); do \
16297 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
16298 sed '$(transform)'`; \
16302 for p in $(PROGRAMS); do \
16303 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
16307 It is guaranteed that @code{program_transform_name} is never empty, and
16308 that there are no useless separators. Therefore you may safely embed
16309 @code{program_transform_name} within a sed program using @samp{;}:
16312 transform = @@program_transform_name@@
16313 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
16316 Whether to do the transformations on documentation files (Texinfo or
16317 @code{man}) is a tricky question; there seems to be no perfect answer,
16318 due to the several reasons for name transforming. Documentation is not
16319 usually particular to a specific architecture, and Texinfo files do not
16320 conflict with system documentation. But they might conflict with
16321 earlier versions of the same files, and @code{man} pages sometimes do
16322 conflict with system documentation. As a compromise, it is probably
16323 best to do name transformations on @code{man} pages but not on Texinfo
16326 @node Site Defaults
16327 @section Setting Site Defaults
16328 @cindex Site defaults
16330 Autoconf-generated @command{configure} scripts allow your site to provide
16331 default values for some configuration values. You do this by creating
16332 site- and system-wide initialization files.
16334 @evindex CONFIG_SITE
16335 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
16336 uses its value as the name of a shell script to read. Otherwise, it
16337 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
16338 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
16339 settings in machine-specific files override those in machine-independent
16340 ones in case of conflict.
16342 Site files can be arbitrary shell scripts, but only certain kinds of
16343 code are really appropriate to be in them. Because @command{configure}
16344 reads any cache file after it has read any site files, a site file can
16345 define a default cache file to be shared between all Autoconf-generated
16346 @command{configure} scripts run on that system (@pxref{Cache Files}). If
16347 you set a default cache file in a site file, it is a good idea to also
16348 set the output variable @code{CC} in that site file, because the cache
16349 file is only valid for a particular compiler, but many systems have
16352 You can examine or override the value set by a command line option to
16353 @command{configure} in a site file; options set shell variables that have
16354 the same names as the options, with any dashes turned into underscores.
16355 The exceptions are that @option{--without-} and @option{--disable-} options
16356 are like giving the corresponding @option{--with-} or @option{--enable-}
16357 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
16358 sets the variable @code{cache_file} to the value @samp{localcache};
16359 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16360 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16361 variable @code{prefix} to the value @samp{/usr}; etc.
16363 Site files are also good places to set default values for other output
16364 variables, such as @code{CFLAGS}, if you need to give them non-default
16365 values: anything you would normally do, repetitively, on the command
16366 line. If you use non-default values for @var{prefix} or
16367 @var{exec_prefix} (wherever you locate the site file), you can set them
16368 in the site file if you specify it with the @code{CONFIG_SITE}
16369 environment variable.
16371 You can set some cache values in the site file itself. Doing this is
16372 useful if you are cross-compiling, where it is impossible to check features
16373 that require running a test program. You could ``prime the cache'' by
16374 setting those values correctly for that system in
16375 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
16376 variables you need to set, look for shell variables with @samp{_cv_} in
16377 their names in the affected @command{configure} scripts, or in the Autoconf
16378 M4 source code for those macros.
16380 The cache file is careful to not override any variables set in the site
16381 files. Similarly, you should not override command-line options in the
16382 site files. Your code should check that variables such as @code{prefix}
16383 and @code{cache_file} have their default values (as set near the top of
16384 @command{configure}) before changing them.
16386 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
16387 command @samp{configure --prefix=/usr/share/local/gnu} would read this
16388 file (if @code{CONFIG_SITE} is not set to a different file).
16391 # config.site for configure
16393 # Change some defaults.
16394 test "$prefix" = NONE && prefix=/usr/share/local/gnu
16395 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
16396 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
16397 test "$localstatedir" = '$prefix/var' && localstatedir=/var
16399 # Give Autoconf 2.x generated configure scripts a shared default
16400 # cache file for feature test results, architecture-specific.
16401 if test "$cache_file" = /dev/null; then
16402 cache_file="$prefix/var/config.cache"
16403 # A cache file is only valid for one C compiler.
16409 @c ============================================== Running configure Scripts.
16411 @node Running configure Scripts
16412 @chapter Running @command{configure} Scripts
16413 @cindex @command{configure}
16415 Below are instructions on how to configure a package that uses a
16416 @command{configure} script, suitable for inclusion as an @file{INSTALL}
16417 file in the package. A plain-text version of @file{INSTALL} which you
16418 may use comes with Autoconf.
16421 * Basic Installation:: Instructions for typical cases
16422 * Compilers and Options:: Selecting compilers and optimization
16423 * Multiple Architectures:: Compiling for multiple architectures at once
16424 * Installation Names:: Installing in different directories
16425 * Optional Features:: Selecting optional features
16426 * System Type:: Specifying the system type
16427 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
16428 * Defining Variables:: Specifying the compiler etc.
16429 * configure Invocation:: Changing how @command{configure} runs
16433 @include install.texi
16436 @c ============================================== config.status Invocation
16438 @node config.status Invocation
16439 @chapter config.status Invocation
16440 @cindex @command{config.status}
16442 The @command{configure} script creates a file named @file{config.status},
16443 which actually configures, @dfn{instantiates}, the template files. It
16444 also records the configuration options that were specified when the
16445 package was last configured in case reconfiguring is needed.
16449 ./config.status @var{option}@dots{} [@var{file}@dots{}]
16452 It configures the @var{files}; if none are specified, all the templates
16453 are instantiated. The files must be specified without their
16454 dependencies, as in
16457 ./config.status foobar
16464 ./config.status foobar:foo.in:bar.in
16467 The supported options are:
16472 Print a summary of the command line options, the list of the template
16477 Print the version number of Autoconf and the configuration settings,
16483 Do not print progress messages.
16487 Don't remove the temporary files.
16489 @item --file=@var{file}[:@var{template}]
16490 Require that @var{file} be instantiated as if
16491 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
16492 @var{file} and @var{template} may be @samp{-} in which case the standard
16493 output and/or standard input, respectively, is used. If a
16494 @var{template} file name is relative, it is first looked for in the build
16495 tree, and then in the source tree. @xref{Configuration Actions}, for
16498 This option and the following ones provide one way for separately
16499 distributed packages to share the values computed by @command{configure}.
16500 Doing so can be useful if some of the packages need a superset of the
16501 features that one of them, perhaps a common library, does. These
16502 options allow a @file{config.status} file to create files other than the
16503 ones that its @file{configure.ac} specifies, so it can be used for a
16506 @item --header=@var{file}[:@var{template}]
16507 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
16510 Ask @file{config.status} to update itself and exit (no instantiation).
16511 This option is useful if you change @command{configure}, so that the
16512 results of some tests might be different from the previous run. The
16513 @option{--recheck} option reruns @command{configure} with the same arguments
16514 you used before, plus the @option{--no-create} option, which prevents
16515 @command{configure} from running @file{config.status} and creating
16516 @file{Makefile} and other files, and the @option{--no-recursion} option,
16517 which prevents @command{configure} from running other @command{configure}
16518 scripts in subdirectories. (This is so other Make rules can
16519 run @file{config.status} when it changes; @pxref{Automatic Remaking},
16523 @file{config.status} checks several optional environment variables that
16524 can alter its behavior:
16526 @defvar CONFIG_SHELL
16527 @evindex CONFIG_SHELL
16528 The shell with which to run @command{configure} for the @option{--recheck}
16529 option. It must be Bourne-compatible. The default is a shell that
16530 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
16531 Invoking @command{configure} by hand bypasses this setting, so you may
16532 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
16533 to insure that the same shell is used everywhere. The absolute name of the
16534 shell should be passed.
16537 @defvar CONFIG_STATUS
16538 @evindex CONFIG_STATUS
16539 The file name to use for the shell script that records the
16540 configuration. The default is @file{./config.status}. This variable is
16541 useful when one package uses parts of another and the @command{configure}
16542 scripts shouldn't be merged because they are maintained separately.
16545 You can use @file{./config.status} in your makefiles. For example, in
16546 the dependencies given above (@pxref{Automatic Remaking}),
16547 @file{config.status} is run twice when @file{configure.ac} has changed.
16548 If that bothers you, you can make each run only regenerate the files for
16553 stamp-h: config.h.in config.status
16554 ./config.status config.h
16557 Makefile: Makefile.in config.status
16558 ./config.status Makefile
16562 The calling convention of @file{config.status} has changed; see
16563 @ref{Obsolete config.status Use}, for details.
16566 @c =================================================== Obsolete Constructs
16568 @node Obsolete Constructs
16569 @chapter Obsolete Constructs
16570 @cindex Obsolete constructs
16572 Autoconf changes, and throughout the years some constructs have been
16573 obsoleted. Most of the changes involve the macros, but in some cases
16574 the tools themselves, or even some concepts, are now considered
16577 You may completely skip this chapter if you are new to Autoconf. Its
16578 intention is mainly to help maintainers updating their packages by
16579 understanding how to move to more modern constructs.
16582 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
16583 * acconfig Header:: Additional entries in @file{config.h.in}
16584 * autoupdate Invocation:: Automatic update of @file{configure.ac}
16585 * Obsolete Macros:: Backward compatibility macros
16586 * Autoconf 1:: Tips for upgrading your files
16587 * Autoconf 2.13:: Some fresher tips
16590 @node Obsolete config.status Use
16591 @section Obsolete @file{config.status} Invocation
16593 @file{config.status} now supports arguments to specify the files to
16594 instantiate; see @ref{config.status Invocation}, for more details.
16595 Before, environment variables had to be used.
16597 @defvar CONFIG_COMMANDS
16598 @evindex CONFIG_COMMANDS
16599 The tags of the commands to execute. The default is the arguments given
16600 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16601 @file{configure.ac}.
16604 @defvar CONFIG_FILES
16605 @evindex CONFIG_FILES
16606 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16607 The default is the arguments given to @code{AC_OUTPUT} and
16608 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16611 @defvar CONFIG_HEADERS
16612 @evindex CONFIG_HEADERS
16613 The files in which to substitute C @code{#define} statements. The
16614 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16615 macro was not called, @file{config.status} ignores this variable.
16618 @defvar CONFIG_LINKS
16619 @evindex CONFIG_LINKS
16620 The symbolic links to establish. The default is the arguments given to
16621 @code{AC_CONFIG_LINKS}; if that macro was not called,
16622 @file{config.status} ignores this variable.
16625 In @ref{config.status Invocation}, using this old interface, the example
16631 stamp-h: config.h.in config.status
16632 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16633 CONFIG_HEADERS=config.h ./config.status
16636 Makefile: Makefile.in config.status
16637 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16638 CONFIG_FILES=Makefile ./config.status
16643 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16644 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
16645 for @code{CONFIG_COMMANDS}, etc.)
16648 @node acconfig Header
16649 @section @file{acconfig.h}
16651 @cindex @file{acconfig.h}
16652 @cindex @file{config.h.top}
16653 @cindex @file{config.h.bot}
16655 In order to produce @file{config.h.in}, @command{autoheader} needs to
16656 build or to find templates for each symbol. Modern releases of Autoconf
16657 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16658 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16659 list of needed templates. @command{autoheader} copied comments and
16660 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16661 the current directory, if present. This file used to be mandatory if
16662 you @code{AC_DEFINE} any additional symbols.
16664 Modern releases of Autoconf also provide @code{AH_TOP} and
16665 @code{AH_BOTTOM} if you need to prepend/append some information to
16666 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
16667 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16668 @command{autoheader} copies the lines before the line containing
16669 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
16670 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16671 @command{autoheader} copies the lines after that line to the end of the
16672 file it generates. Either or both of those strings may be omitted. An
16673 even older alternate way to produce the same effect in ancient versions
16674 of Autoconf is to create the files @file{@var{file}.top} (typically
16675 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16676 directory. If they exist, @command{autoheader} copies them to the
16677 beginning and end, respectively, of its output.
16679 In former versions of Autoconf, the files used in preparing a software
16680 package for distribution were:
16683 configure.ac --. .------> autoconf* -----> configure
16685 [aclocal.m4] --+ `---.
16687 +--> [autoheader*] -> [config.h.in]
16688 [acconfig.h] ----. |
16695 Using only the @code{AH_} macros, @file{configure.ac} should be
16696 self-contained, and should not depend upon @file{acconfig.h} etc.
16699 @node autoupdate Invocation
16700 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16701 @cindex @command{autoupdate}
16703 The @command{autoupdate} program updates a @file{configure.ac} file that
16704 calls Autoconf macros by their old names to use the current macro names.
16705 In version 2 of Autoconf, most of the macros were renamed to use a more
16706 uniform and descriptive naming scheme. @xref{Macro Names}, for a
16707 description of the new scheme. Although the old names still work
16708 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16709 new names), you can make your @file{configure.ac} files more readable
16710 and make it easier to use the current Autoconf documentation if you
16711 update them to use the new macro names.
16713 @evindex SIMPLE_BACKUP_SUFFIX
16714 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16715 backing up the original version with the suffix @file{~} (or the value
16716 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16717 set). If you give @command{autoupdate} an argument, it reads that file
16718 instead of @file{configure.ac} and writes the updated file to the
16722 @command{autoupdate} accepts the following options:
16727 Print a summary of the command line options and exit.
16731 Print the version number of Autoconf and exit.
16735 Report processing steps.
16739 Don't remove the temporary files.
16743 Force the update even if the file has not changed. Disregard the cache.
16745 @item --include=@var{dir}
16746 @itemx -I @var{dir}
16747 Also look for input files in @var{dir}. Multiple invocations accumulate.
16748 Directories are browsed from last to first.
16751 @node Obsolete Macros
16752 @section Obsolete Macros
16754 Several macros are obsoleted in Autoconf, for various reasons (typically
16755 they failed to quote properly, couldn't be extended for more recent
16756 issues, etc.). They are still supported, but deprecated: their use
16759 During the jump from Autoconf version 1 to version 2, most of the
16760 macros were renamed to use a more uniform and descriptive naming scheme,
16761 but their signature did not change. @xref{Macro Names}, for a
16762 description of the new naming scheme. Below, if there is just the mapping
16763 from old names to new names for these macros, the reader is invited to
16764 refer to the definition of the new macro for the signature and the
16769 @code{AC_FUNC_ALLOCA}
16772 @defmac AC_ARG_ARRAY
16773 @acindex{ARG_ARRAY}
16774 removed because of limited usefulness
16779 This macro is obsolete; it does nothing.
16782 @defmac AC_C_LONG_DOUBLE
16783 @acindex{C_LONG_DOUBLE}
16784 @cvindex HAVE_LONG_DOUBLE
16785 If the C compiler supports a working @code{long double} type with more
16786 range or precision than the @code{double} type, define
16787 @code{HAVE_LONG_DOUBLE}.
16789 You should use @code{AC_TYPE_LONG_DOUBLE} or
16790 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16793 @defmac AC_CANONICAL_SYSTEM
16794 @acindex{CANONICAL_SYSTEM}
16795 Determine the system type and set output variables to the names of the
16796 canonical system types. @xref{Canonicalizing}, for details about the
16797 variables this macro sets.
16799 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16800 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16801 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
16805 @defmac AC_CHAR_UNSIGNED
16806 @acindex{CHAR_UNSIGNED}
16807 @code{AC_C_CHAR_UNSIGNED}
16810 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16811 @acindex{CHECK_TYPE}
16812 Autoconf, up to 2.13, used to provide this version of
16813 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
16814 it is a member of the @code{CHECK} clan, it does
16815 more than just checking. Secondly, missing types are defined
16816 using @code{#define}, not @code{typedef}, and this can lead to
16817 problems in the case of pointer types.
16819 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16820 @ref{Generic Types}, for the description of the current macro.
16822 If the type @var{type} is not defined, define it to be the C (or C++)
16823 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16825 This macro is equivalent to:
16828 AC_CHECK_TYPE([@var{type}], [],
16829 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16830 [Define to `@var{default}'
16831 if <sys/types.h> does not define.])])
16834 In order to keep backward compatibility, the two versions of
16835 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
16839 If there are three or four arguments, the modern version is used.
16842 If the second argument appears to be a C or C++ type, then the
16843 obsolete version is used. This happens if the argument is a C or C++
16844 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16845 followed by one of @samp{[(* } and then by a string of zero or more
16846 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16849 If the second argument is spelled with the alphabet of valid C and C++
16850 types, the user is warned and the modern version is used.
16853 Otherwise, the modern version is used.
16857 You are encouraged either to use a valid builtin type, or to use the
16858 equivalent modern code (see above), or better yet, to use
16859 @code{AC_CHECK_TYPES} together with
16862 #ifndef HAVE_LOFF_T
16863 typedef loff_t off_t;
16867 @c end of AC_CHECK_TYPE
16869 @defmac AC_CHECKING (@var{feature-description})
16871 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16874 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16875 @acindex{COMPILE_CHECK}
16876 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16877 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16878 addition that it prints @samp{checking for @var{echo-text}} to the
16879 standard output first, if @var{echo-text} is non-empty. Use
16880 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16881 messages (@pxref{Printing Messages}).
16889 @defmac AC_CROSS_CHECK
16890 @acindex{CROSS_CHECK}
16891 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
16897 Check for the Cygwin environment in which case the shell variable
16898 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
16899 means to check the nature of the host is using
16900 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
16903 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
16905 *cygwin* ) CYGWIN=yes;;
16910 Beware that the variable @code{CYGWIN} has a special meaning when
16911 running Cygwin, and should not be changed. That's yet another reason
16912 not to use this macro.
16915 @defmac AC_DECL_SYS_SIGLIST
16916 @acindex{DECL_SYS_SIGLIST}
16917 @cvindex SYS_SIGLIST_DECLARED
16921 AC_CHECK_DECLS([sys_siglist], [], [],
16922 [#include <signal.h>
16923 /* NetBSD declares sys_siglist in unistd.h. */
16924 #ifdef HAVE_UNISTD_H
16925 # include <unistd.h>
16931 @defmac AC_DECL_YYTEXT
16932 @acindex{DECL_YYTEXT}
16933 Does nothing, now integrated in @code{AC_PROG_LEX}.
16936 @defmac AC_DIR_HEADER
16937 @acindex{DIR_HEADER}
16942 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
16943 but defines a different set of C preprocessor macros to indicate which
16944 header file is found:
16946 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
16947 @item Header @tab Old Symbol @tab New Symbol
16948 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
16949 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
16950 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
16951 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
16955 @defmac AC_DYNIX_SEQ
16956 @acindex{DYNIX_SEQ}
16957 If on DYNIX/ptx, add @option{-lseq} to output variable
16958 @code{LIBS}. This macro used to be defined as
16961 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
16965 now it is just @code{AC_FUNC_GETMNTENT}.
16971 Defined the output variable @code{EXEEXT} based on the output of the
16972 compiler, which is now done automatically. Typically set to empty
16973 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
16978 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
16979 and sets @code{EMXOS2}.
16984 @code{AC_MSG_ERROR}
16992 @defmac AC_FIND_XTRA
16993 @acindex{FIND_XTRA}
16994 @code{AC_PATH_XTRA}
16999 @code{m4_foreach_w}
17002 @defmac AC_FUNC_CHECK
17003 @acindex{FUNC_CHECK}
17004 @code{AC_CHECK_FUNC}
17007 @defmac AC_FUNC_SETVBUF_REVERSED
17008 @acindex{FUNC_SETVBUF_REVERSED}
17009 @cvindex SETVBUF_REVERSED
17010 @c @fuindex setvbuf
17011 @prindex @code{setvbuf}
17012 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
17013 the buffering type as its second argument and the buffer pointer as the
17014 third, instead of the other way around, and defined
17015 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
17016 were those based on SVR2, which became obsolete in 1987, and the macro
17017 is no longer needed.
17020 @defmac AC_FUNC_WAIT3
17021 @acindex{FUNC_WAIT3}
17022 @cvindex HAVE_WAIT3
17023 If @code{wait3} is found and fills in the contents of its third argument
17024 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
17027 These days portable programs should use @code{waitpid}, not
17028 @code{wait3}, as @code{wait3} has been removed from Posix.
17031 @defmac AC_GCC_TRADITIONAL
17032 @acindex{GCC_TRADITIONAL}
17033 @code{AC_PROG_GCC_TRADITIONAL}
17036 @defmac AC_GETGROUPS_T
17037 @acindex{GETGROUPS_T}
17038 @code{AC_TYPE_GETGROUPS}
17041 @defmac AC_GETLOADAVG
17042 @acindex{GETLOADAVG}
17043 @code{AC_FUNC_GETLOADAVG}
17046 @defmac AC_HAVE_FUNCS
17047 @acindex{HAVE_FUNCS}
17048 @code{AC_CHECK_FUNCS}
17051 @defmac AC_HAVE_HEADERS
17052 @acindex{HAVE_HEADERS}
17053 @code{AC_CHECK_HEADERS}
17056 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
17057 @acindex{HAVE_LIBRARY}
17058 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
17059 @var{function} argument of @code{main}. In addition, @var{library} can
17060 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
17061 all of those cases, the compiler is passed @option{-lfoo}. However,
17062 @var{library} cannot be a shell variable; it must be a literal name.
17065 @defmac AC_HAVE_POUNDBANG
17066 @acindex{HAVE_POUNDBANG}
17067 @code{AC_SYS_INTERPRETER} (different calling convention)
17070 @defmac AC_HEADER_CHECK
17071 @acindex{HEADER_CHECK}
17072 @code{AC_CHECK_HEADER}
17075 @defmac AC_HEADER_EGREP
17076 @acindex{HEADER_EGREP}
17077 @code{AC_EGREP_HEADER}
17080 @defmac AC_HELP_STRING
17081 @acindex{HELP_STRING}
17082 @code{AS_HELP_STRING}
17085 @defmac AC_INIT (@var{unique-file-in-source-dir})
17087 Formerly @code{AC_INIT} used to have a single argument, and was
17092 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
17101 @defmac AC_INT_16_BITS
17102 @acindex{INT_16_BITS}
17103 @cvindex INT_16_BITS
17104 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
17105 Use @samp{AC_CHECK_SIZEOF(int)} instead.
17108 @defmac AC_IRIX_SUN
17110 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
17111 @code{LIBS}. If you were using it to get @code{getmntent}, use
17112 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
17113 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
17114 getpwnam)}. Up to Autoconf 2.13, it used to be
17117 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
17121 now it is defined as
17125 AC_CHECK_LIB([sun], [getpwnam])
17131 Same as @samp{AC_LANG([C])}.
17134 @defmac AC_LANG_CPLUSPLUS
17135 @acindex{LANG_CPLUSPLUS}
17136 Same as @samp{AC_LANG([C++])}.
17139 @defmac AC_LANG_FORTRAN77
17140 @acindex{LANG_FORTRAN77}
17141 Same as @samp{AC_LANG([Fortran 77])}.
17144 @defmac AC_LANG_RESTORE
17145 @acindex{LANG_RESTORE}
17146 Select the @var{language} that is saved on the top of the stack, as set
17147 by @code{AC_LANG_SAVE}, remove it from the stack, and call
17148 @code{AC_LANG(@var{language})}.
17151 @defmac AC_LANG_SAVE
17152 @acindex{LANG_SAVE}
17153 Remember the current language (as set by @code{AC_LANG}) on a stack.
17154 The current language does not change. @code{AC_LANG_PUSH} is preferred.
17157 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
17158 @acindex{LINK_FILES}
17159 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
17163 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
17171 AC_CONFIG_LINKS([host.h:config/$machine.h
17172 object.h:config/$obj_format.h])
17178 @code{AC_PROG_LN_S}
17181 @defmac AC_LONG_64_BITS
17182 @acindex{LONG_64_BITS}
17183 @cvindex LONG_64_BITS
17184 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
17185 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
17188 @defmac AC_LONG_DOUBLE
17189 @acindex{LONG_DOUBLE}
17190 If the C compiler supports a working @code{long double} type with more
17191 range or precision than the @code{double} type, define
17192 @code{HAVE_LONG_DOUBLE}.
17194 You should use @code{AC_TYPE_LONG_DOUBLE} or
17195 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17198 @defmac AC_LONG_FILE_NAMES
17199 @acindex{LONG_FILE_NAMES}
17200 @code{AC_SYS_LONG_FILE_NAMES}
17203 @defmac AC_MAJOR_HEADER
17204 @acindex{MAJOR_HEADER}
17205 @code{AC_HEADER_MAJOR}
17208 @defmac AC_MEMORY_H
17210 @cvindex NEED_MEMORY_H
17211 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
17212 defined in @file{memory.h}. Today it is equivalent to
17213 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
17214 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
17220 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
17221 environment and sets @code{MINGW32}.
17224 @defmac AC_MINUS_C_MINUS_O
17225 @acindex{MINUS_C_MINUS_O}
17226 @code{AC_PROG_CC_C_O}
17231 @code{AC_FUNC_MMAP}
17236 @code{AC_TYPE_MODE_T}
17242 Defined the output variable @code{OBJEXT} based on the output of the
17243 compiler, after .c files have been excluded. Typically set to @samp{o}
17244 if Posix, @samp{obj} if a @acronym{DOS} variant.
17245 Now the compiler checking macros handle
17246 this automatically.
17249 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
17251 Make M4 print a message to the standard error output warning that
17252 @var{this-macro-name} is obsolete, and giving the file and line number
17253 where it was called. @var{this-macro-name} should be the name of the
17254 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
17255 it is printed at the end of the warning message; for example, it can be
17256 a suggestion for what to use instead of @var{this-macro-name}.
17261 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
17264 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
17265 services to the user.
17270 @code{AC_TYPE_OFF_T}
17273 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
17275 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
17276 interface is equivalent to:
17280 AC_CONFIG_FILES(@var{file}@dots{})
17281 AC_CONFIG_COMMANDS([default],
17282 @var{extra-cmds}, @var{init-cmds})
17288 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
17289 @acindex{OUTPUT_COMMANDS}
17290 Specify additional shell commands to run at the end of
17291 @file{config.status}, and shell commands to initialize any variables
17292 from @command{configure}. This macro may be called multiple times. It is
17293 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
17295 Here is an unrealistic example:
17299 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
17301 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
17305 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
17306 additional key, an important difference is that
17307 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
17308 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
17309 can safely be given macro calls as arguments:
17312 AC_CONFIG_COMMANDS(foo, [my_FOO()])
17316 Conversely, where one level of quoting was enough for literal strings
17317 with @code{AC_OUTPUT_COMMANDS}, you need two with
17318 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
17322 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
17323 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
17330 @code{AC_TYPE_PID_T}
17335 @code{AC_PREFIX_PROGRAM}
17338 @defmac AC_PROGRAMS_CHECK
17339 @acindex{PROGRAMS_CHECK}
17340 @code{AC_CHECK_PROGS}
17343 @defmac AC_PROGRAMS_PATH
17344 @acindex{PROGRAMS_PATH}
17345 @code{AC_PATH_PROGS}
17348 @defmac AC_PROGRAM_CHECK
17349 @acindex{PROGRAM_CHECK}
17350 @code{AC_CHECK_PROG}
17353 @defmac AC_PROGRAM_EGREP
17354 @acindex{PROGRAM_EGREP}
17355 @code{AC_EGREP_CPP}
17358 @defmac AC_PROGRAM_PATH
17359 @acindex{PROGRAM_PATH}
17360 @code{AC_PATH_PROG}
17363 @defmac AC_REMOTE_TAPE
17364 @acindex{REMOTE_TAPE}
17365 removed because of limited usefulness
17368 @defmac AC_RESTARTABLE_SYSCALLS
17369 @acindex{RESTARTABLE_SYSCALLS}
17370 @code{AC_SYS_RESTARTABLE_SYSCALLS}
17373 @defmac AC_RETSIGTYPE
17374 @acindex{RETSIGTYPE}
17375 @code{AC_TYPE_SIGNAL}
17380 removed because of limited usefulness
17383 @defmac AC_SCO_INTL
17386 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
17387 macro used to do this:
17390 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
17394 Now it just calls @code{AC_FUNC_STRFTIME} instead.
17397 @defmac AC_SETVBUF_REVERSED
17398 @acindex{SETVBUF_REVERSED}
17399 @code{AC_FUNC_SETVBUF_REVERSED}
17402 @defmac AC_SET_MAKE
17404 @code{AC_PROG_MAKE_SET}
17407 @defmac AC_SIZEOF_TYPE
17408 @acindex{SIZEOF_TYPE}
17409 @code{AC_CHECK_SIZEOF}
17414 @code{AC_TYPE_SIZE_T}
17417 @defmac AC_STAT_MACROS_BROKEN
17418 @acindex{STAT_MACROS_BROKEN}
17419 @code{AC_HEADER_STAT}
17422 @defmac AC_STDC_HEADERS
17423 @acindex{STDC_HEADERS}
17424 @code{AC_HEADER_STDC}
17429 @code{AC_FUNC_STRCOLL}
17432 @defmac AC_ST_BLKSIZE
17433 @acindex{ST_BLKSIZE}
17434 @code{AC_CHECK_MEMBERS}
17437 @defmac AC_ST_BLOCKS
17438 @acindex{ST_BLOCKS}
17439 @code{AC_STRUCT_ST_BLOCKS}
17444 @code{AC_CHECK_MEMBERS}
17447 @defmac AC_SYS_RESTARTABLE_SYSCALLS
17448 @acindex{SYS_RESTARTABLE_SYSCALLS}
17449 @cvindex HAVE_RESTARTABLE_SYSCALLS
17450 If the system automatically restarts a system call that is interrupted
17451 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
17452 not check whether system calls are restarted in general---it checks whether a
17453 signal handler installed with @code{signal} (but not @code{sigaction})
17454 causes system calls to be restarted. It does not check whether system calls
17455 can be restarted when interrupted by signals that have no handler.
17457 These days portable programs should use @code{sigaction} with
17458 @code{SA_RESTART} if they want restartable system calls. They should
17459 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
17460 system call is restartable is a dynamic issue, not a configuration-time
17464 @defmac AC_SYS_SIGLIST_DECLARED
17465 @acindex{SYS_SIGLIST_DECLARED}
17466 @code{AC_DECL_SYS_SIGLIST}
17469 @defmac AC_TEST_CPP
17471 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
17474 @defmac AC_TEST_PROGRAM
17475 @acindex{TEST_PROGRAM}
17476 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
17479 @defmac AC_TIMEZONE
17481 @code{AC_STRUCT_TIMEZONE}
17484 @defmac AC_TIME_WITH_SYS_TIME
17485 @acindex{TIME_WITH_SYS_TIME}
17486 @code{AC_HEADER_TIME}
17489 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17490 @acindex{TRY_COMPILE}
17495 [AC_LANG_PROGRAM([[@var{includes}]],
17496 [[@var{function-body}]])],
17497 [@var{action-if-true}],
17498 [@var{action-if-false}])
17502 @xref{Running the Compiler}.
17504 This macro double quotes both @var{includes} and @var{function-body}.
17506 For C and C++, @var{includes} is any @code{#include} statements needed
17507 by the code in @var{function-body} (@var{includes} is ignored if
17508 the currently selected language is Fortran or Fortran 77). The compiler
17509 and compilation flags are determined by the current language
17510 (@pxref{Language Choice}).
17513 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
17519 [AC_LANG_SOURCE([[@var{input}]])],
17520 [@var{action-if-true}],
17521 [@var{action-if-false}])
17525 @xref{Running the Preprocessor}.
17527 This macro double quotes the @var{input}.
17530 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17536 [AC_LANG_PROGRAM([[@var{includes}]],
17537 [[@var{function-body}]])],
17538 [@var{action-if-true}],
17539 [@var{action-if-false}])
17543 @xref{Running the Compiler}.
17545 This macro double quotes both @var{includes} and @var{function-body}.
17547 Depending on the current language (@pxref{Language Choice}), create a
17548 test program to see whether a function whose body consists of
17549 @var{function-body} can be compiled and linked. If the file compiles
17550 and links successfully, run shell commands @var{action-if-found},
17551 otherwise run @var{action-if-not-found}.
17553 This macro double quotes both @var{includes} and @var{function-body}.
17555 For C and C++, @var{includes} is any @code{#include} statements needed
17556 by the code in @var{function-body} (@var{includes} is ignored if
17557 the currently selected language is Fortran or Fortran 77). The compiler
17558 and compilation flags are determined by the current language
17559 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17560 @code{LIBS} are used for linking.
17563 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17564 @acindex{TRY_LINK_FUNC}
17565 This macro is equivalent to
17566 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17567 [@var{action-if-found}], [@var{action-if-not-found}])}.
17570 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17576 [AC_LANG_SOURCE([[@var{program}]])],
17577 [@var{action-if-true}],
17578 [@var{action-if-false}],
17579 [@var{action-if-cross-compiling}])
17588 @code{AC_TYPE_UID_T}
17591 @defmac AC_UNISTD_H
17593 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17599 Define @code{USG} if the @acronym{BSD} string functions are defined in
17600 @file{strings.h}. You should no longer depend upon @code{USG}, but on
17601 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17604 @defmac AC_UTIME_NULL
17605 @acindex{UTIME_NULL}
17606 @code{AC_FUNC_UTIME_NULL}
17609 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17610 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17611 If the cache file is inconsistent with the current host, target and
17612 build system types, it used to execute @var{cmd} or print a default
17613 error message. This is now handled by default.
17616 @defmac AC_VERBOSE (@var{result-description})
17618 @code{AC_MSG_RESULT}.
17623 @code{AC_FUNC_VFORK}
17628 @code{AC_FUNC_VPRINTF}
17633 @code{AC_FUNC_WAIT3}
17641 @defmac AC_WORDS_BIGENDIAN
17642 @acindex{WORDS_BIGENDIAN}
17643 @code{AC_C_BIGENDIAN}
17646 @defmac AC_XENIX_DIR
17647 @acindex{XENIX_DIR}
17649 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17650 Xenix. Also, if @file{dirent.h} is being checked for, added
17651 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
17652 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17653 running @sc{xenix} on which you should not depend:
17656 AC_MSG_CHECKING([for Xenix])
17657 AC_EGREP_CPP([yes],
17658 [#if defined M_XENIX && !defined M_UNIX
17661 [AC_MSG_RESULT([yes]); XENIX=yes],
17662 [AC_MSG_RESULT([no]); XENIX=])
17666 @defmac AC_YYTEXT_POINTER
17667 @acindex{YYTEXT_POINTER}
17668 @code{AC_DECL_YYTEXT}
17672 @section Upgrading From Version 1
17673 @cindex Upgrading autoconf
17674 @cindex Autoconf upgrading
17676 Autoconf version 2 is mostly backward compatible with version 1.
17677 However, it introduces better ways to do some things, and doesn't
17678 support some of the ugly things in version 1. So, depending on how
17679 sophisticated your @file{configure.ac} files are, you might have to do
17680 some manual work in order to upgrade to version 2. This chapter points
17681 out some problems to watch for when upgrading. Also, perhaps your
17682 @command{configure} scripts could benefit from some of the new features in
17683 version 2; the changes are summarized in the file @file{NEWS} in the
17684 Autoconf distribution.
17687 * Changed File Names:: Files you might rename
17688 * Changed Makefiles:: New things to put in @file{Makefile.in}
17689 * Changed Macros:: Macro calls you might replace
17690 * Changed Results:: Changes in how to check test results
17691 * Changed Macro Writing:: Better ways to write your own macros
17694 @node Changed File Names
17695 @subsection Changed File Names
17697 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17698 in a particular package's source directory), you must rename it to
17699 @file{acsite.m4}. @xref{autoconf Invocation}.
17701 If you distribute @file{install.sh} with your package, rename it to
17702 @file{install-sh} so @code{make} builtin rules don't inadvertently
17703 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
17704 looks for the script under both names, but it is best to use the new name.
17706 If you were using @file{config.h.top}, @file{config.h.bot}, or
17707 @file{acconfig.h}, you still can, but you have less clutter if you
17708 use the @code{AH_} macros. @xref{Autoheader Macros}.
17710 @node Changed Makefiles
17711 @subsection Changed Makefiles
17713 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17714 your @file{Makefile.in} files, so they can take advantage of the values
17715 of those variables in the environment when @command{configure} is run.
17716 Doing this isn't necessary, but it's a convenience for users.
17718 Also add @samp{@@configure_input@@} in a comment to each input file for
17719 @code{AC_OUTPUT}, so that the output files contain a comment saying
17720 they were produced by @command{configure}. Automatically selecting the
17721 right comment syntax for all the kinds of files that people call
17722 @code{AC_OUTPUT} on became too much work.
17724 Add @file{config.log} and @file{config.cache} to the list of files you
17725 remove in @code{distclean} targets.
17727 If you have the following in @file{Makefile.in}:
17730 prefix = /usr/local
17731 exec_prefix = $(prefix)
17735 you must change it to:
17738 prefix = @@prefix@@
17739 exec_prefix = @@exec_prefix@@
17743 The old behavior of replacing those variables without @samp{@@}
17744 characters around them has been removed.
17746 @node Changed Macros
17747 @subsection Changed Macros
17749 Many of the macros were renamed in Autoconf version 2. You can still
17750 use the old names, but the new ones are clearer, and it's easier to find
17751 the documentation for them. @xref{Obsolete Macros}, for a table showing the
17752 new names for the old macros. Use the @command{autoupdate} program to
17753 convert your @file{configure.ac} to using the new macro names.
17754 @xref{autoupdate Invocation}.
17756 Some macros have been superseded by similar ones that do the job better,
17757 but are not call-compatible. If you get warnings about calling obsolete
17758 macros while running @command{autoconf}, you may safely ignore them, but
17759 your @command{configure} script generally works better if you follow
17760 the advice that is printed about what to replace the obsolete macros with. In
17761 particular, the mechanism for reporting the results of tests has
17762 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17763 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17764 looks better if you switch to @code{AC_MSG_CHECKING} and
17765 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
17766 in conjunction with cache variables. @xref{Caching Results}.
17770 @node Changed Results
17771 @subsection Changed Results
17773 If you were checking the results of previous tests by examining the
17774 shell variable @code{DEFS}, you need to switch to checking the values of
17775 the cache variables for those tests. @code{DEFS} no longer exists while
17776 @command{configure} is running; it is only created when generating output
17777 files. This difference from version 1 is because properly quoting the
17778 contents of that variable turned out to be too cumbersome and
17779 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
17782 For example, here is a @file{configure.ac} fragment written for Autoconf
17786 AC_HAVE_FUNCS(syslog)
17788 *-DHAVE_SYSLOG*) ;;
17789 *) # syslog is not in the default libraries. See if it's in some other.
17791 for lib in bsd socket inet; do
17792 AC_CHECKING(for syslog in -l$lib)
17793 LIBS="-l$lib $saved_LIBS"
17794 AC_HAVE_FUNCS(syslog)
17796 *-DHAVE_SYSLOG*) break ;;
17804 Here is a way to write it for version 2:
17807 AC_CHECK_FUNCS([syslog])
17808 if test $ac_cv_func_syslog = no; then
17809 # syslog is not in the default libraries. See if it's in some other.
17810 for lib in bsd socket inet; do
17811 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17812 LIBS="-l$lib $LIBS"; break])
17817 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17818 backslashes before quotes, you need to remove them. It now works
17819 predictably, and does not treat quotes (except back quotes) specially.
17820 @xref{Setting Output Variables}.
17822 All of the Boolean shell variables set by Autoconf macros now use
17823 @samp{yes} for the true value. Most of them use @samp{no} for false,
17824 though for backward compatibility some use the empty string instead. If
17825 you were relying on a shell variable being set to something like 1 or
17826 @samp{t} for true, you need to change your tests.
17828 @node Changed Macro Writing
17829 @subsection Changed Macro Writing
17831 When defining your own macros, you should now use @code{AC_DEFUN}
17832 instead of @code{define}. @code{AC_DEFUN} automatically calls
17833 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17834 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17835 messages on the screen. There's no actual harm in continuing to use the
17836 older way, but it's less convenient and attractive. @xref{Macro
17839 You probably looked at the macros that came with Autoconf as a guide for
17840 how to do things. It would be a good idea to take a look at the new
17841 versions of them, as the style is somewhat improved and they take
17842 advantage of some new features.
17844 If you were doing tricky things with undocumented Autoconf internals
17845 (macros, variables, diversions), check whether you need to change
17846 anything to account for changes that have been made. Perhaps you can
17847 even use an officially supported technique in version 2 instead of
17848 kludging. Or perhaps not.
17850 To speed up your locally written feature tests, add caching to them.
17851 See whether any of your tests are of general enough usefulness to
17852 encapsulate them into macros that you can share.
17855 @node Autoconf 2.13
17856 @section Upgrading From Version 2.13
17857 @cindex Upgrading autoconf
17858 @cindex Autoconf upgrading
17860 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17861 suits this section@enddots{}
17864 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17865 However, it introduces better ways to do some things, and doesn't
17866 support some of the ugly things in version 2.13. So, depending on how
17867 sophisticated your @file{configure.ac} files are, you might have to do
17868 some manual work in order to upgrade to version 2.50. This chapter
17869 points out some problems to watch for when upgrading. Also, perhaps
17870 your @command{configure} scripts could benefit from some of the new
17871 features in version 2.50; the changes are summarized in the file
17872 @file{NEWS} in the Autoconf distribution.
17876 * Changed Quotation:: Broken code which used to work
17877 * New Macros:: Interaction with foreign macros
17878 * Hosts and Cross-Compilation:: Bugward compatibility kludges
17879 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
17880 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
17883 @node Changed Quotation
17884 @subsection Changed Quotation
17886 The most important changes are invisible to you: the implementation of
17887 most macros have completely changed. This allowed more factorization of
17888 the code, better error messages, a higher uniformity of the user's
17889 interface etc. Unfortunately, as a side effect, some construct which
17890 used to (miraculously) work might break starting with Autoconf 2.50.
17891 The most common culprit is bad quotation.
17893 For instance, in the following example, the message is not properly
17898 AC_CHECK_HEADERS(foo.h, ,
17899 AC_MSG_ERROR(cannot find foo.h, bailing out))
17904 Autoconf 2.13 simply ignores it:
17907 $ @kbd{autoconf-2.13; ./configure --silent}
17908 creating cache ./config.cache
17909 configure: error: cannot find foo.h
17914 while Autoconf 2.50 produces a broken @file{configure}:
17917 $ @kbd{autoconf-2.50; ./configure --silent}
17918 configure: error: cannot find foo.h
17919 ./configure: exit: bad non-numeric arg `bailing'
17920 ./configure: exit: bad non-numeric arg `bailing'
17924 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
17928 AC_INIT([Example], [1.0], [bug-example@@example.org])
17929 AC_CHECK_HEADERS([foo.h], [],
17930 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
17934 Many many (and many more) Autoconf macros were lacking proper quotation,
17935 including no less than@dots{} @code{AC_DEFUN} itself!
17938 $ @kbd{cat configure.in}
17939 AC_DEFUN([AC_PROG_INSTALL],
17940 [# My own much better version
17945 $ @kbd{autoconf-2.13}
17946 autoconf: Undefined macros:
17947 ***BUG in Autoconf--please report*** AC_FD_MSG
17948 ***BUG in Autoconf--please report*** AC_EPI
17949 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
17950 configure.in:5:AC_PROG_INSTALL
17951 $ @kbd{autoconf-2.50}
17957 @subsection New Macros
17959 @cindex undefined macro
17960 @cindex @code{_m4_divert_diversion}
17962 While Autoconf was relatively dormant in the late 1990s, Automake
17963 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
17964 in 2001, Autoconf provided
17965 versions of these macros, integrated in the @code{AC_} namespace,
17966 instead of @code{AM_}. But in order to ease the upgrading via
17967 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
17969 Unfortunately older versions of Automake (e.g., Automake 1.4)
17970 did not quote the names of these macros.
17971 Therefore, when @command{m4} finds something like
17972 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
17973 @code{AM_TYPE_PTRDIFF_T} is
17974 expanded, replaced with its Autoconf definition.
17976 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
17977 complains, in its own words:
17980 $ @kbd{cat configure.ac}
17981 AC_INIT([Example], [1.0], [bug-example@@example.org])
17983 $ @kbd{aclocal-1.4}
17985 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
17986 aclocal.m4:17: the top level
17987 autom4te: m4 failed with exit status: 1
17991 Modern versions of Automake no longer define most of these
17992 macros, and properly quote the names of the remaining macros.
17993 If you must use an old Automake, do not depend upon macros from Automake
17994 as it is simply not its job
17995 to provide macros (but the one it requires itself):
17998 $ @kbd{cat configure.ac}
17999 AC_INIT([Example], [1.0], [bug-example@@example.org])
18001 $ @kbd{rm aclocal.m4}
18003 autoupdate: `configure.ac' is updated
18004 $ @kbd{cat configure.ac}
18005 AC_INIT([Example], [1.0], [bug-example@@example.org])
18006 AC_CHECK_TYPES([ptrdiff_t])
18007 $ @kbd{aclocal-1.4}
18013 @node Hosts and Cross-Compilation
18014 @subsection Hosts and Cross-Compilation
18015 @cindex Cross compilation
18017 Based on the experience of compiler writers, and after long public
18018 debates, many aspects of the cross-compilation chain have changed:
18022 the relationship between the build, host, and target architecture types,
18025 the command line interface for specifying them to @command{configure},
18028 the variables defined in @command{configure},
18031 the enabling of cross-compilation mode.
18036 The relationship between build, host, and target have been cleaned up:
18037 the chain of default is now simply: target defaults to host, host to
18038 build, and build to the result of @command{config.guess}. Nevertheless,
18039 in order to ease the transition from 2.13 to 2.50, the following
18040 transition scheme is implemented. @emph{Do not rely on it}, as it will
18041 be completely disabled in a couple of releases (we cannot keep it, as it
18042 proves to cause more problems than it cures).
18044 They all default to the result of running @command{config.guess}, unless
18045 you specify either @option{--build} or @option{--host}. In this case,
18046 the default becomes the system type you specified. If you specify both,
18047 and they're different, @command{configure} enters cross compilation
18048 mode, so it doesn't run any tests that require execution.
18050 Hint: if you mean to override the result of @command{config.guess},
18051 prefer @option{--build} over @option{--host}. In the future,
18052 @option{--host} will not override the name of the build system type.
18053 Whenever you specify @option{--host}, be sure to specify @option{--build}
18058 For backward compatibility, @command{configure} accepts a system
18059 type as an option by itself. Such an option overrides the
18060 defaults for build, host, and target system types. The following
18061 configure statement configures a cross toolchain that runs on
18062 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
18063 which is also the build platform.
18066 ./configure --host=alpha-netbsd sparc-gnu
18071 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
18072 and @code{target} had a different semantics before and after the
18073 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
18074 @option{--build} is strictly copied into @code{build_alias}, and is left
18075 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
18076 set to the canonicalized build type. To ease the transition, before,
18077 its contents is the same as that of @code{build_alias}. Do @emph{not}
18078 rely on this broken feature.
18080 For consistency with the backward compatibility scheme exposed above,
18081 when @option{--host} is specified but @option{--build} isn't, the build
18082 system is assumed to be the same as @option{--host}, and
18083 @samp{build_alias} is set to that value. Eventually, this
18084 historically incorrect behavior will go away.
18088 The former scheme to enable cross-compilation proved to cause more harm
18089 than good, in particular, it used to be triggered too easily, leaving
18090 regular end users puzzled in front of cryptic error messages.
18091 @command{configure} could even enter cross-compilation mode only
18092 because the compiler was not functional. This is mainly because
18093 @command{configure} used to try to detect cross-compilation, instead of
18094 waiting for an explicit flag from the user.
18096 Now, @command{configure} enters cross-compilation mode if and only if
18097 @option{--host} is passed.
18099 That's the short documentation. To ease the transition between 2.13 and
18100 its successors, a more complicated scheme is implemented. @emph{Do not
18101 rely on the following}, as it will be removed in the near future.
18103 If you specify @option{--host}, but not @option{--build}, when
18104 @command{configure} performs the first compiler test it tries to run
18105 an executable produced by the compiler. If the execution fails, it
18106 enters cross-compilation mode. This is fragile. Moreover, by the time
18107 the compiler test is performed, it may be too late to modify the
18108 build-system type: other tests may have already been performed.
18109 Therefore, whenever you specify @option{--host}, be sure to specify
18110 @option{--build} too.
18113 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
18117 enters cross-compilation mode. The former interface, which
18118 consisted in setting the compiler to a cross-compiler without informing
18119 @command{configure} is obsolete. For instance, @command{configure}
18120 fails if it can't run the code generated by the specified compiler if you
18121 configure as follows:
18124 ./configure CC=m68k-coff-gcc
18128 @node AC_LIBOBJ vs LIBOBJS
18129 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
18131 Up to Autoconf 2.13, the replacement of functions was triggered via the
18132 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
18133 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
18134 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
18136 This change is mandated by the unification of the @acronym{GNU} Build System
18137 components. In particular, the various fragile techniques used to parse
18138 a @file{configure.ac} are all replaced with the use of traces. As a
18139 consequence, any action must be traceable, which obsoletes critical
18140 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
18141 and it can even be handled gracefully (read, ``without your having to
18142 change something'').
18144 There were two typical uses of @code{LIBOBJS}: asking for a replacement
18145 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
18149 As for function replacement, the fix is immediate: use
18150 @code{AC_LIBOBJ}. For instance:
18153 LIBOBJS="$LIBOBJS fnmatch.o"
18154 LIBOBJS="$LIBOBJS malloc.$ac_objext"
18158 should be replaced with:
18161 AC_LIBOBJ([fnmatch])
18162 AC_LIBOBJ([malloc])
18168 When used with Automake 1.10 or newer, a suitable value for
18169 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
18170 can be referenced from any @file{Makefile.am}. Even without Automake,
18171 arranging for @code{LIBOBJDIR} to be set correctly enables
18172 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
18173 The @code{LIBOBJDIR} feature is experimental.
18176 @node AC_FOO_IFELSE vs AC_TRY_FOO
18177 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
18179 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
18180 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
18181 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
18182 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
18183 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
18184 @code{AC_TRY_RUN}. The motivations where:
18187 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
18188 quoting their arguments;
18191 the combinatoric explosion is solved by decomposing on the one hand the
18192 generation of sources, and on the other hand executing the program;
18195 this scheme helps supporting more languages than plain C and C++.
18198 In addition to the change of syntax, the philosophy has changed too:
18199 while emphasis was put on speed at the expense of accuracy, today's
18200 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
18204 As a perfect example of what is @emph{not} to be done, here is how to
18205 find out whether a header file contains a particular declaration, such
18206 as a typedef, a structure, a structure member, or a function. Use
18207 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
18208 header file; on some systems the symbol might be defined in another
18209 header file that the file you are checking includes.
18211 As a (bad) example, here is how you should not check for C preprocessor
18212 symbols, either defined by header files or predefined by the C
18213 preprocessor: using @code{AC_EGREP_CPP}:
18221 ], is_aix=yes, is_aix=no)
18225 The above example, properly written would (i) use
18226 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
18230 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
18232 error: This isn't AIX!
18241 @c ============================= Generating Test Suites with Autotest
18243 @node Using Autotest
18244 @chapter Generating Test Suites with Autotest
18249 @strong{N.B.: This section describes an experimental feature which will
18250 be part of Autoconf in a forthcoming release. Although we believe
18251 Autotest is stabilizing, this documentation describes an interface which
18252 might change in the future: do not depend upon Autotest without
18253 subscribing to the Autoconf mailing lists.}
18256 It is paradoxical that portable projects depend on nonportable tools
18257 to run their test suite. Autoconf by itself is the paragon of this
18258 problem: although it aims at perfectly portability, up to 2.13 its
18259 test suite was using Deja@acronym{GNU}, a rich and complex testing
18260 framework, but which is far from being standard on Posix systems.
18261 Worse yet, it was likely to be missing on the most fragile platforms,
18262 the very platforms that are most likely to torture Autoconf and
18263 exhibit deficiencies.
18265 To circumvent this problem, many package maintainers have developed their
18266 own testing framework, based on simple shell scripts whose sole outputs
18267 are exit status values describing whether the test succeeded. Most of
18268 these tests share common patterns, and this can result in lots of
18269 duplicated code and tedious maintenance.
18271 Following exactly the same reasoning that yielded to the inception of
18272 Autoconf, Autotest provides a test suite generation framework, based on
18273 M4 macros building a portable shell script. The suite itself is
18274 equipped with automatic logging and tracing facilities which greatly
18275 diminish the interaction with bug reporters, and simple timing reports.
18277 Autoconf itself has been using Autotest for years, and we do attest that
18278 it has considerably improved the strength of the test suite and the
18279 quality of bug reports. Other projects are known to use some generation
18280 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
18281 them with different needs, and this usage has validated Autotest as a general
18284 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
18285 interactive tool testing, which is probably its main limitation.
18288 * Using an Autotest Test Suite:: Autotest and the user
18289 * Writing Testsuites:: Autotest macros
18290 * testsuite Invocation:: Running @command{testsuite} scripts
18291 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
18294 @node Using an Autotest Test Suite
18295 @section Using an Autotest Test Suite
18298 * testsuite Scripts:: The concepts of Autotest
18299 * Autotest Logs:: Their contents
18302 @node testsuite Scripts
18303 @subsection @command{testsuite} Scripts
18305 @cindex @command{testsuite}
18307 Generating testing or validation suites using Autotest is rather easy.
18308 The whole validation suite is held in a file to be processed through
18309 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
18310 produce a stand-alone Bourne shell script which then gets distributed.
18311 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
18312 the installer's end.
18315 Each test of the validation suite should be part of some test group. A
18316 @dfn{test group} is a sequence of interwoven tests that ought to be
18317 executed together, usually because one test in the group creates data
18318 files than a later test in the same group needs to read. Complex test
18319 groups make later debugging more tedious. It is much better to
18320 keep only a few tests per test group. Ideally there is only one test
18323 For all but the simplest packages, some file such as @file{testsuite.at}
18324 does not fully hold all test sources, as these are often easier to
18325 maintain in separate files. Each of these separate files holds a single
18326 test group, or a sequence of test groups all addressing some common
18327 functionality in the package. In such cases, @file{testsuite.at}
18328 merely initializes the validation suite, and sometimes does elementary
18329 health checking, before listing include statements for all other test
18330 files. The special file @file{package.m4}, containing the
18331 identification of the package, is automatically included if found.
18333 A convenient alternative consists in moving all the global issues
18334 (local Autotest macros, elementary health checking, and @code{AT_INIT}
18335 invocation) into the file @code{local.at}, and making
18336 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
18337 suites. In such case, generating the whole test suite or pieces of it
18338 is only a matter of choosing the @command{autom4te} command line
18341 The validation scripts that Autotest produces are by convention called
18342 @command{testsuite}. When run, @command{testsuite} executes each test
18343 group in turn, producing only one summary line per test to say if that
18344 particular test succeeded or failed. At end of all tests, summarizing
18345 counters get printed. One debugging directory is left for each test
18346 group which failed, if any: such directories are named
18347 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
18348 the test group, and they include:
18351 @item a debugging script named @file{run} which reruns the test in
18352 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
18353 of debugging scripts has the purpose of easing the chase for bugs.
18355 @item all the files created with @code{AT_DATA}
18357 @item a log of the run, named @file{testsuite.log}
18360 In the ideal situation, none of the tests fail, and consequently no
18361 debugging directory is left behind for validation.
18363 It often happens in practice that individual tests in the validation
18364 suite need to get information coming out of the configuration process.
18365 Some of this information, common for all validation suites, is provided
18366 through the file @file{atconfig}, automatically created by
18367 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
18368 testing environment specifically needs, you might prepare an optional
18369 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
18370 The configuration process produces @file{atconfig} and @file{atlocal}
18371 out of these two input files, and these two produced files are
18372 automatically read by the @file{testsuite} script.
18374 Here is a diagram showing the relationship between files.
18377 Files used in preparing a software package for distribution:
18382 subfile-1.at ->. [local.at] ---->+
18384 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
18390 Files used in configuring a software package:
18395 [atlocal.in] --> config.status* --<
18401 Files created during the test suite execution:
18404 atconfig -->. .--> testsuite.log
18408 [atlocal] ->' `--> [testsuite.dir]
18412 @node Autotest Logs
18413 @subsection Autotest Logs
18415 When run, the test suite creates a log file named after itself, e.g., a
18416 test suite named @command{testsuite} creates @file{testsuite.log}. It
18417 contains a lot of information, usually more than maintainers actually
18418 need, but therefore most of the time it contains all that is needed:
18421 @item command line arguments
18422 @c akim s/to consist in/to consist of/
18423 A bad but unfortunately widespread habit consists of
18424 setting environment variables before the command, such as in
18425 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
18426 know this change, hence (i) it cannot report it to you, and (ii)
18427 it cannot preserve the value of @code{CC} for subsequent runs.
18428 Autoconf faced exactly the same problem, and solved it by asking
18429 users to pass the variable definitions as command line arguments.
18430 Autotest requires this rule, too, but has no means to enforce it; the log
18431 then contains a trace of the variables that were changed by the user.
18433 @item @file{ChangeLog} excerpts
18434 The topmost lines of all the @file{ChangeLog} files found in the source
18435 hierarchy. This is especially useful when bugs are reported against
18436 development versions of the package, since the version string does not
18437 provide sufficient information to know the exact state of the sources
18438 the user compiled. Of course, this relies on the use of a
18441 @item build machine
18442 Running a test suite in a cross-compile environment is not an easy task,
18443 since it would mean having the test suite run on a machine @var{build},
18444 while running programs on a machine @var{host}. It is much simpler to
18445 run both the test suite and the programs on @var{host}, but then, from
18446 the point of view of the test suite, there remains a single environment,
18447 @var{host} = @var{build}. The log contains relevant information on the
18448 state of the build machine, including some important environment
18450 @c FIXME: How about having an M4sh macro to say `hey, log the value
18451 @c of `@dots{}'? This would help both Autoconf and Autotest.
18453 @item tested programs
18454 The absolute file name and answers to @option{--version} of the tested
18455 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
18457 @item configuration log
18458 The contents of @file{config.log}, as created by @command{configure},
18459 are appended. It contains the configuration flags and a detailed report
18460 on the configuration itself.
18464 @node Writing Testsuites
18465 @section Writing @file{testsuite.at}
18467 The @file{testsuite.at} is a Bourne shell script making use of special
18468 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
18469 its beginning followed by one call to @code{m4_include} per source file
18470 for tests. Each such included file, or the remainder of
18471 @file{testsuite.at} if include files are not used, contain a sequence of
18472 test groups. Each test group begins with a call to @code{AT_SETUP},
18473 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
18474 and then completes with a call to @code{AT_CLEANUP}.
18476 @defmac AT_INIT (@ovar{name})
18478 @c FIXME: Not clear, plus duplication of the information.
18479 Initialize Autotest. Giving a @var{name} to the test suite is
18480 encouraged if your package includes several test suites. In any case,
18481 the test suite always displays the package name and version. It also
18482 inherits the package bug report address.
18485 @defmac AT_COPYRIGHT (@var{copyright-notice})
18486 @atindex{COPYRIGHT}
18487 @cindex Copyright Notice
18488 State that, in addition to the Free Software Foundation's copyright on
18489 the Autotest macros, parts of your test suite are covered by
18490 @var{copyright-notice}.
18492 The @var{copyright-notice} shows up in both the head of
18493 @command{testsuite} and in @samp{testsuite --version}.
18496 @defmac AT_TESTED (@var{executables})
18498 Log the file name and answer to @option{--version} of each program in
18499 space-separated list @var{executables}. Several invocations register
18500 new executables, in other words, don't fear registering one program
18504 Autotest test suites rely on @env{PATH} to find the tested program.
18505 This avoids the need to generate absolute names of the various tools, and
18506 makes it possible to test installed programs. Therefore, knowing which
18507 programs are being exercised is crucial to understanding problems in
18508 the test suite itself, or its occasional misuses. It is a good idea to
18509 also subscribe foreign programs you depend upon, to avoid incompatible
18514 @defmac AT_SETUP (@var{test-group-name})
18516 This macro starts a group of related tests, all to be executed in the
18517 same subshell. It accepts a single argument, which holds a few words
18518 (no more than about 30 or 40 characters) quickly describing the purpose
18519 of the test group being started.
18522 @defmac AT_KEYWORDS (@var{keywords})
18524 Associate the space-separated list of @var{keywords} to the enclosing
18525 test group. This makes it possible to run ``slices'' of the test suite.
18526 For instance, if some of your test groups exercise some @samp{foo}
18527 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
18528 @samp{./testsuite -k foo} to run exclusively these test groups. The
18529 @var{title} of the test group is automatically recorded to
18530 @code{AT_KEYWORDS}.
18532 Several invocations within a test group accumulate new keywords. In
18533 other words, don't fear registering the same keyword several times in a
18537 @defmac AT_CAPTURE_FILE (@var{file})
18538 @atindex{CAPTURE_FILE}
18539 If the current test group fails, log the contents of @var{file}.
18540 Several identical calls within one test group have no additional effect.
18543 @defmac AT_XFAIL_IF (@var{shell-condition})
18545 Determine whether the test is expected to fail because it is a known
18546 bug (for unsupported features, you should skip the test).
18547 @var{shell-condition} is a shell expression such as a @code{test}
18548 command; you can instantiate this macro many times from within the
18549 same test group, and one of the conditions is enough to turn
18550 the test into an expected failure.
18555 End the current test group.
18560 @defmac AT_DATA (@var{file}, @var{contents})
18562 Initialize an input data @var{file} with given @var{contents}. Of
18563 course, the @var{contents} have to be properly quoted between square
18564 brackets to protect against included commas or spurious M4
18565 expansion. The contents ought to end with an end of line.
18568 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18570 Execute a test by performing given shell @var{commands}. These commands
18571 should normally exit with @var{status}, while producing expected
18572 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
18573 status 77, then the whole test group is skipped. Otherwise, if this test
18574 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18575 commands @var{run-if-pass}.
18577 The @var{commands} @emph{must not} redirect the standard output, nor the
18580 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18581 the corresponding value is not checked.
18583 The special value @samp{expout} for @var{stdout} means the expected
18584 output of the @var{commands} is the content of the file @file{expout}.
18585 If @var{stdout} is @samp{stdout}, then the standard output of the
18586 @var{commands} is available for further tests in the file @file{stdout}.
18587 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
18591 @node testsuite Invocation
18592 @section Running @command{testsuite} Scripts
18593 @cindex @command{testsuite}
18595 Autotest test suites support the following arguments:
18600 Display the list of options and exit successfully.
18604 Display the version of the test suite and exit successfully.
18608 Remove all the files the test suite might have created and exit. Meant
18609 for @code{clean} Make targets.
18613 List all the tests (or only the selection), including their possible
18619 By default all tests are performed (or described with
18620 @option{--list}) in the default environment first silently, then
18621 verbosely, but the environment, set of tests, and verbosity level can be
18625 @item @var{variable}=@var{value}
18626 Set the environment @var{variable} to @var{value}. Use this rather
18627 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18628 different environment.
18630 @cindex @code{AUTOTEST_PATH}
18631 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18632 to @env{PATH}. Relative directory names (not starting with
18633 @samp{/}) are considered to be relative to the top level of the
18634 package being built. All directories are made absolute, first
18635 starting from the top level @emph{build} tree, then from the
18636 @emph{source} tree. For instance @samp{./testsuite
18637 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18638 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18639 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18643 @itemx @var{number}-@var{number}
18644 @itemx @var{number}-
18645 @itemx -@var{number}
18646 Add the corresponding test groups, with obvious semantics, to the
18649 @item --keywords=@var{keywords}
18650 @itemx -k @var{keywords}
18651 Add to the selection the test groups with title or keywords (arguments
18652 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18653 of the comma separated list @var{keywords}, case-insensitively. Use
18654 @samp{!} immediately before the keyword to invert the selection for this
18655 keyword. By default, the keywords match whole words; enclose them in
18656 @samp{.*} to also match parts of words.
18658 For example, running
18661 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18665 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18666 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
18670 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18674 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18675 containing @samp{FUNC}.
18679 If any test fails, immediately abort testing. It implies
18680 @option{--debug}: post test group clean up, and top-level logging
18681 are inhibited. This option is meant for the full test
18682 suite, it is not really useful for generated debugging scripts.
18686 Force more verbosity in the detailed output of what is being done. This
18687 is the default for debugging scripts.
18691 Do not remove the files after a test group was performed ---but they are
18692 still removed @emph{before}, therefore using this option is sane when
18693 running several test groups. Create debugging scripts. Do not
18694 overwrite the top-level
18695 log (in order to preserve supposedly existing full log file). This is
18696 the default for debugging scripts, but it can also be useful to debug
18697 the testsuite itself.
18701 Trigger shell tracing of the test groups.
18705 @node Making testsuite Scripts
18706 @section Making @command{testsuite} Scripts
18708 For putting Autotest into movement, you need some configuration and
18709 makefile machinery. We recommend, at least if your package uses deep or
18710 shallow hierarchies, that you use @file{tests/} as the name of the
18711 directory holding all your tests and their makefile. Here is a
18712 check list of things to do.
18717 @cindex @file{package.m4}
18718 Make sure to create the file @file{package.m4}, which defines the
18719 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
18720 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18721 address to which bug reports should be sent. For sake of completeness,
18722 we suggest that you also define @code{AT_PACKAGE_NAME},
18723 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18724 @xref{Initializing configure}, for a description of these variables. We
18725 suggest the following makefile excerpt:
18728 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18730 echo '# Signature of the current package.'; \
18731 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
18732 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
18733 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
18734 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
18735 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18736 @} >'$(srcdir)/package.m4'
18740 Be sure to distribute @file{package.m4} and to put it into the source
18741 hierarchy: the test suite ought to be shipped!
18744 Invoke @code{AC_CONFIG_TESTDIR}.
18746 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18747 @acindex{CONFIG_TESTDIR}
18748 An Autotest test suite is to be configured in @var{directory}. This
18749 macro requires the instantiation of @file{@var{directory}/atconfig} from
18750 @file{@var{directory}/atconfig.in}, and sets the default
18751 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18755 Still within @file{configure.ac}, as appropriate, ensure that some
18756 @code{AC_CONFIG_FILES} command includes substitution for
18757 @file{tests/atlocal}.
18760 The @file{tests/Makefile.in} should be modified so the validation in
18761 your package is triggered by @samp{make check}. An example is provided
18765 With Automake, here is a minimal example about how to link @samp{make
18766 check} with a validation suite.
18769 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18770 TESTSUITE = $(srcdir)/testsuite
18772 check-local: atconfig atlocal $(TESTSUITE)
18773 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18775 installcheck-local: atconfig atlocal $(TESTSUITE)
18776 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18780 test ! -f '$(TESTSUITE)' || \
18781 $(SHELL) '$(TESTSUITE)' --clean
18783 AUTOTEST = $(AUTOM4TE) --language=autotest
18784 $(TESTSUITE): $(srcdir)/testsuite.at
18785 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18789 You might want to list explicitly the dependencies, i.e., the list of
18790 the files @file{testsuite.at} includes.
18792 With strict Autoconf, you might need to add lines inspired from the
18798 atconfig: $(top_builddir)/config.status
18799 cd $(top_builddir) && \
18800 $(SHELL) ./config.status $(subdir)/$@@
18802 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18803 cd $(top_builddir) && \
18804 $(SHELL) ./config.status $(subdir)/$@@
18808 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18811 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18812 within your makefile, you can fine-tune test suite execution with this variable,
18816 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18821 @c =============================== Frequent Autoconf Questions, with answers
18824 @chapter Frequent Autoconf Questions, with answers
18826 Several questions about Autoconf come up occasionally. Here some of them
18830 * Distributing:: Distributing @command{configure} scripts
18831 * Why GNU M4:: Why not use the standard M4?
18832 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
18833 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
18834 * Defining Directories:: Passing @code{datadir} to program
18835 * Autom4te Cache:: What is it? Can I remove it?
18836 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
18840 @section Distributing @command{configure} Scripts
18844 What are the restrictions on distributing @command{configure}
18845 scripts that Autoconf generates? How does that affect my
18846 programs that use them?
18849 There are no restrictions on how the configuration scripts that Autoconf
18850 produces may be distributed or used. In Autoconf version 1, they were
18851 covered by the @acronym{GNU} General Public License. We still encourage
18852 software authors to distribute their work under terms like those of the
18853 @acronym{GPL}, but doing so is not required to use Autoconf.
18855 Of the other files that might be used with @command{configure},
18856 @file{config.h.in} is under whatever copyright you use for your
18857 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
18858 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18859 @command{configure} script, which permits you to distribute them under the
18860 same terms as the rest of your package. @file{install-sh} is from the X
18861 Consortium and is not copyrighted.
18864 @section Why Require @acronym{GNU} M4?
18867 Why does Autoconf require @acronym{GNU} M4?
18870 Many M4 implementations have hard-coded limitations on the size and
18871 number of macros that Autoconf exceeds. They also lack several
18872 builtin macros that it would be difficult to get along without in a
18873 sophisticated application like Autoconf, including:
18883 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
18885 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18886 M4 is simple to configure and install, it seems reasonable to require
18887 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
18888 other free software already have most of the @acronym{GNU} utilities
18889 installed, since they prefer them.
18891 @node Bootstrapping
18892 @section How Can I Bootstrap?
18896 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
18897 @command{configure} script, how do I bootstrap? It seems like a chicken
18901 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
18902 @command{configure} script produced by Autoconf, Autoconf is not required
18903 in order to run the script and install @acronym{GNU} M4. Autoconf is only
18904 required if you want to change the M4 @command{configure} script, which few
18905 people have to do (mainly its maintainer).
18907 @node Why Not Imake
18908 @section Why Not Imake?
18912 Why not use Imake instead of @command{configure} scripts?
18915 Several people have written addressing this question, so I include
18916 adaptations of their explanations here.
18918 The following answer is based on one written by Richard Pixley:
18921 Autoconf generated scripts frequently work on machines that it has
18922 never been set up to handle before. That is, it does a good job of
18923 inferring a configuration for a new system. Imake cannot do this.
18925 Imake uses a common database of host specific data. For X11, this makes
18926 sense because the distribution is made as a collection of tools, by one
18927 central authority who has control over the database.
18929 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
18930 maintainer; these maintainers are scattered across the world. Using a
18931 common database would be a maintenance nightmare. Autoconf may appear
18932 to be this kind of database, but in fact it is not. Instead of listing
18933 host dependencies, it lists program requirements.
18935 If you view the @acronym{GNU} suite as a collection of native tools, then the
18936 problems are similar. But the @acronym{GNU} development tools can be
18937 configured as cross tools in almost any host+target permutation. All of
18938 these configurations can be installed concurrently. They can even be
18939 configured to share host independent files across hosts. Imake doesn't
18940 address these issues.
18942 Imake templates are a form of standardization. The @acronym{GNU} coding
18943 standards address the same issues without necessarily imposing the same
18948 Here is some further explanation, written by Per Bothner:
18951 One of the advantages of Imake is that it easy to generate large
18952 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
18953 However, @code{cpp} is not programmable: it has limited conditional
18954 facilities, and no looping. And @code{cpp} cannot inspect its
18957 All of these problems are solved by using @code{sh} instead of
18958 @code{cpp}. The shell is fully programmable, has macro substitution,
18959 can execute (or source) other shell scripts, and can inspect its
18964 Paul Eggert elaborates more:
18967 With Autoconf, installers need not assume that Imake itself is already
18968 installed and working well. This may not seem like much of an advantage
18969 to people who are accustomed to Imake. But on many hosts Imake is not
18970 installed or the default installation is not working well, and requiring
18971 Imake to install a package hinders the acceptance of that package on
18972 those hosts. For example, the Imake template and configuration files
18973 might not be installed properly on a host, or the Imake build procedure
18974 might wrongly assume that all source files are in one big directory
18975 tree, or the Imake configuration might assume one compiler whereas the
18976 package or the installer needs to use another, or there might be a
18977 version mismatch between the Imake expected by the package and the Imake
18978 supported by the host. These problems are much rarer with Autoconf,
18979 where each package comes with its own independent configuration
18982 Also, Imake often suffers from unexpected interactions between
18983 @command{make} and the installer's C preprocessor. The fundamental problem
18984 here is that the C preprocessor was designed to preprocess C programs,
18985 not makefiles. This is much less of a problem with Autoconf,
18986 which uses the general-purpose preprocessor M4, and where the
18987 package's author (rather than the installer) does the preprocessing in a
18992 Finally, Mark Eichin notes:
18995 Imake isn't all that extensible, either. In order to add new features to
18996 Imake, you need to provide your own project template, and duplicate most
18997 of the features of the existing one. This means that for a sophisticated
18998 project, using the vendor-provided Imake templates fails to provide any
18999 leverage---since they don't cover anything that your own project needs
19000 (unless it is an X11 program).
19002 On the other side, though:
19004 The one advantage that Imake has over @command{configure}:
19005 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
19006 than @file{Makefile.in} files. There is a fix to this, however---at least
19007 for the Kerberos V5 tree, we've modified things to call in common
19008 @file{post.in} and @file{pre.in} makefile fragments for the
19009 entire tree. This means that a lot of common things don't have to be
19010 duplicated, even though they normally are in @command{configure} setups.
19014 @node Defining Directories
19015 @section How Do I @code{#define} Installation Directories?
19018 My program needs library files, installed in @code{datadir} and
19022 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
19023 [Define to the read-only architecture-independent
19031 #define DATADIR "$@{prefix@}/share"
19035 As already explained, this behavior is on purpose, mandated by the
19036 @acronym{GNU} Coding Standards, see @ref{Installation Directory
19037 Variables}. There are several means to achieve a similar goal:
19041 Do not use @code{AC_DEFINE} but use your makefile to pass the
19042 actual value of @code{datadir} via compilation flags.
19043 @xref{Installation Directory Variables}, for the details.
19046 This solution can be simplified when compiling a program: you may either
19047 extend the @code{CPPFLAGS}:
19050 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
19054 or create a dedicated header file:
19057 DISTCLEANFILES = datadir.h
19058 datadir.h: Makefile
19059 echo '#define DATADIR "$(datadir)"' >$@@
19063 Use @code{AC_DEFINE} but have @command{configure} compute the literal
19064 value of @code{datadir} and others. Many people have wrapped macros to
19065 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
19066 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
19069 This solution does not conform to the @acronym{GNU} Coding Standards.
19072 Note that all the previous solutions hard wire the absolute name of
19073 these directories in the executables, which is not a good property. You
19074 may try to compute the names relative to @code{prefix}, and try to
19075 find @code{prefix} at runtime, this way your package is relocatable.
19076 Some macros are already available to address this issue: see
19077 @code{adl_COMPUTE_RELATIVE_PATHS} and
19078 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
19079 @uref{http://autoconf-archive.cryp.to/,
19080 Autoconf Macro Archive}.
19084 @node Autom4te Cache
19085 @section What is @file{autom4te.cache}?
19088 What is this directory @file{autom4te.cache}? Can I safely remove it?
19091 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
19092 role and is read by many tools: @command{autoconf} to create
19093 @file{configure}, @command{autoheader} to create @file{config.h.in},
19094 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
19095 check the completeness of @file{configure.ac}, @command{autoreconf} to
19096 check the @acronym{GNU} Build System components that are used. To
19097 ``read @file{configure.ac}'' actually means to compile it with M4,
19098 which can be a long process for complex @file{configure.ac}.
19100 This is why all these tools, instead of running directly M4, invoke
19101 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
19102 a specific demand, stores additional information in
19103 @file{autom4te.cache} for future runs. For instance, if you run
19104 @command{autoconf}, behind the scenes, @command{autom4te} also
19105 stores information for the other tools, so that when you invoke
19106 @command{autoheader} or @command{automake} etc., reprocessing
19107 @file{configure.ac} is not needed. The speed up is frequently of 30%,
19108 and is increasing with the size of @file{configure.ac}.
19110 But it is and remains being simply a cache: you can safely remove it.
19115 Can I permanently get rid of it?
19118 The creation of this cache can be disabled from
19119 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
19120 details. You should be aware that disabling the cache slows down the
19121 Autoconf test suite by 40%. The more @acronym{GNU} Build System
19122 components are used, the more the cache is useful; for instance
19123 running @samp{autoreconf -f} on the Core Utilities is twice slower without
19124 the cache @emph{although @option{--force} implies that the cache is
19125 not fully exploited}, and eight times slower than without
19129 @node Present But Cannot Be Compiled
19130 @section Header Present But Cannot Be Compiled
19132 The most important guideline to bear in mind when checking for
19133 features is to mimic as much as possible the intended use.
19134 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
19135 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
19136 the preprocessor, instead of the compiler, to check for headers. As a
19137 result, incompatibilities between headers went unnoticed during
19138 configuration, and maintainers finally had to deal with this issue
19141 As of Autoconf 2.56 both checks are performed, and @code{configure}
19142 complains loudly if the compiler and the preprocessor do not agree.
19143 For the time being the result used is that of the preprocessor, to give
19144 maintainers time to adjust their @file{configure.ac}, but in the
19145 future, only the compiler will be considered.
19147 Consider the following example:
19150 $ @kbd{cat number.h}
19151 typedef int number;
19153 const number pi = 3;
19154 $ @kbd{cat configure.ac}
19155 AC_INIT([Example], [1.0], [bug-example@@example.org])
19156 AC_CHECK_HEADERS([pi.h])
19157 $ @kbd{autoconf -Wall}
19158 $ @kbd{./configure}
19159 checking for gcc... gcc
19160 checking for C compiler default output file name... a.out
19161 checking whether the C compiler works... yes
19162 checking whether we are cross compiling... no
19163 checking for suffix of executables...
19164 checking for suffix of object files... o
19165 checking whether we are using the GNU C compiler... yes
19166 checking whether gcc accepts -g... yes
19167 checking for gcc option to accept ISO C89... none needed
19168 checking how to run the C preprocessor... gcc -E
19169 checking for grep that handles long lines and -e... grep
19170 checking for egrep... grep -E
19171 checking for ANSI C header files... yes
19172 checking for sys/types.h... yes
19173 checking for sys/stat.h... yes
19174 checking for stdlib.h... yes
19175 checking for string.h... yes
19176 checking for memory.h... yes
19177 checking for strings.h... yes
19178 checking for inttypes.h... yes
19179 checking for stdint.h... yes
19180 checking for unistd.h... yes
19181 checking pi.h usability... no
19182 checking pi.h presence... yes
19183 configure: WARNING: pi.h: present but cannot be compiled
19184 configure: WARNING: pi.h: check for missing prerequisite headers?
19185 configure: WARNING: pi.h: see the Autoconf documentation
19186 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
19187 configure: WARNING: pi.h: proceeding with the preprocessor's result
19188 configure: WARNING: pi.h: in the future, the compiler will take precedence
19189 configure: WARNING: ## -------------------------------------- ##
19190 configure: WARNING: ## Report this to bug-example@@example.org ##
19191 configure: WARNING: ## -------------------------------------- ##
19192 checking for pi.h... yes
19196 The proper way the handle this case is using the fourth argument
19197 (@pxref{Generic Headers}):
19200 $ @kbd{cat configure.ac}
19201 AC_INIT([Example], [1.0], [bug-example@@example.org])
19202 AC_CHECK_HEADERS([number.h pi.h], [], [],
19203 [[#ifdef HAVE_NUMBER_H
19204 # include <number.h>
19207 $ @kbd{autoconf -Wall}
19208 $ @kbd{./configure}
19209 checking for gcc... gcc
19210 checking for C compiler default output... a.out
19211 checking whether the C compiler works... yes
19212 checking whether we are cross compiling... no
19213 checking for suffix of executables...
19214 checking for suffix of object files... o
19215 checking whether we are using the GNU C compiler... yes
19216 checking whether gcc accepts -g... yes
19217 checking for gcc option to accept ANSI C... none needed
19218 checking for number.h... yes
19219 checking for pi.h... yes
19222 See @ref{Particular Headers}, for a list of headers with their
19225 @c ===================================================== History of Autoconf.
19228 @chapter History of Autoconf
19229 @cindex History of autoconf
19231 You may be wondering, Why was Autoconf originally written? How did it
19232 get into its present form? (Why does it look like gorilla spit?) If
19233 you're not wondering, then this chapter contains no information useful
19234 to you, and you might as well skip it. If you @emph{are} wondering,
19235 then let there be light@enddots{}
19238 * Genesis:: Prehistory and naming of @command{configure}
19239 * Exodus:: The plagues of M4 and Perl
19240 * Leviticus:: The priestly code of portability arrives
19241 * Numbers:: Growth and contributors
19242 * Deuteronomy:: Approaching the promises of easy configuration
19248 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
19249 Free Software Foundation. As they were ported to more platforms and
19250 more programs were added, the number of @option{-D} options that users
19251 had to select in the makefile (around 20) became burdensome.
19252 Especially for me---I had to test each new release on a bunch of
19253 different systems. So I wrote a little shell script to guess some of
19254 the correct settings for the fileutils package, and released it as part
19255 of fileutils 2.0. That @command{configure} script worked well enough that
19256 the next month I adapted it (by hand) to create similar @command{configure}
19257 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
19258 also adapted one of my scripts for his @acronym{CVS} revision control system.
19260 Later that summer, I learned that Richard Stallman and Richard Pixley
19261 were developing similar scripts to use in the @acronym{GNU} compiler tools;
19262 so I adapted my @command{configure} scripts to support their evolving
19263 interface: using the file name @file{Makefile.in} as the templates;
19264 adding @samp{+srcdir}, the first option (of many); and creating
19265 @file{config.status} files.
19270 As I got feedback from users, I incorporated many improvements, using
19271 Emacs to search and replace, cut and paste, similar changes in each of
19272 the scripts. As I adapted more @acronym{GNU} utilities packages to use
19273 @command{configure} scripts, updating them all by hand became impractical.
19274 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
19275 mail saying that the @command{configure} scripts were great, and asking if
19276 I had a tool for generating them that I could send him. No, I thought,
19277 but I should! So I started to work out how to generate them. And the
19278 journey from the slavery of hand-written @command{configure} scripts to the
19279 abundance and ease of Autoconf began.
19281 Cygnus @command{configure}, which was being developed at around that time,
19282 is table driven; it is meant to deal mainly with a discrete number of
19283 system types with a small number of mainly unguessable features (such as
19284 details of the object file format). The automatic configuration system
19285 that Brian Fox had developed for Bash takes a similar approach. For
19286 general use, it seems to me a hopeless cause to try to maintain an
19287 up-to-date database of which features each variant of each operating
19288 system has. It's easier and more reliable to check for most features on
19289 the fly---especially on hybrid systems that people have hacked on
19290 locally or that have patches from vendors installed.
19292 I considered using an architecture similar to that of Cygnus
19293 @command{configure}, where there is a single @command{configure} script that
19294 reads pieces of @file{configure.in} when run. But I didn't want to have
19295 to distribute all of the feature tests with every package, so I settled
19296 on having a different @command{configure} made from each
19297 @file{configure.in} by a preprocessor. That approach also offered more
19298 control and flexibility.
19300 I looked briefly into using the Metaconfig package, by Larry Wall,
19301 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
19302 reasons. The @command{Configure} scripts it produces are interactive,
19303 which I find quite inconvenient; I didn't like the ways it checked for
19304 some features (such as library functions); I didn't know that it was
19305 still being maintained, and the @command{Configure} scripts I had
19306 seen didn't work on many modern systems (such as System V R4 and NeXT);
19307 it wasn't flexible in what it could do in response to a feature's
19308 presence or absence; I found it confusing to learn; and it was too big
19309 and complex for my needs (I didn't realize then how much Autoconf would
19310 eventually have to grow).
19312 I considered using Perl to generate my style of @command{configure}
19313 scripts, but decided that M4 was better suited to the job of simple
19314 textual substitutions: it gets in the way less, because output is
19315 implicit. Plus, everyone already has it. (Initially I didn't rely on
19316 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
19317 University of Maryland had recently been putting M4 front ends on
19318 several programs, including @code{tvtwm}, and I was interested in trying
19319 out a new language.
19324 Since my @command{configure} scripts determine the system's capabilities
19325 automatically, with no interactive user intervention, I decided to call
19326 the program that generates them Autoconfig. But with a version number
19327 tacked on, that name would be too long for old Unix file systems,
19328 so I shortened it to Autoconf.
19330 In the fall of 1991 I called together a group of fellow questers after
19331 the Holy Grail of portability (er, that is, alpha testers) to give me
19332 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
19333 and continued to add features and improve the techniques used in the
19334 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
19335 with the idea of making an Autoconf shell script to run M4
19336 and check for unresolved macro calls; Richard Pixley, who suggested
19337 running the compiler instead of searching the file system to find
19338 include files and symbols, for more accurate results; Karl Berry, who
19339 got Autoconf to configure @TeX{} and added the macro index to the
19340 documentation; and Ian Lance Taylor, who added support for creating a C
19341 header file as an alternative to putting @option{-D} options in a
19342 makefile, so he could use Autoconf for his @acronym{UUCP} package.
19343 The alpha testers cheerfully adjusted their files again and again as the
19344 names and calling conventions of the Autoconf macros changed from
19345 release to release. They all contributed many specific checks, great
19346 ideas, and bug fixes.
19351 In July 1992, after months of alpha testing, I released Autoconf 1.0,
19352 and converted many @acronym{GNU} packages to use it. I was surprised by how
19353 positive the reaction to it was. More people started using it than I
19354 could keep track of, including people working on software that wasn't
19355 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
19356 Autoconf continued to improve rapidly, as many people using the
19357 @command{configure} scripts reported problems they encountered.
19359 Autoconf turned out to be a good torture test for M4 implementations.
19360 Unix M4 started to dump core because of the length of the
19361 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
19362 M4 as well. Eventually, we realized that we needed to use some
19363 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
19364 particular, has an impoverished set of builtin macros; the System V
19365 version is better, but still doesn't provide everything we need.
19367 More development occurred as people put Autoconf under more stresses
19368 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
19369 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
19370 invalid arguments. Jim Blandy bravely coerced it into configuring
19371 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
19372 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
19373 @command{autoheader} script to automate the creation of C header file
19374 templates, and added a @option{--verbose} option to @command{configure}.
19375 Noah Friedman added the @option{--autoconf-dir} option and
19376 @code{AC_MACRODIR} environment variable. (He also coined the term
19377 @dfn{autoconfiscate} to mean ``adapt a software package to use
19378 Autoconf''.) Roland and Noah improved the quoting protection in
19379 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
19380 dealing with portability problems from February through June, 1993.
19383 @section Deuteronomy
19385 A long wish list for major features had accumulated, and the effect of
19386 several years of patching by various people had left some residual
19387 cruft. In April 1994, while working for Cygnus Support, I began a major
19388 revision of Autoconf. I added most of the features of the Cygnus
19389 @command{configure} that Autoconf had lacked, largely by adapting the
19390 relevant parts of Cygnus @command{configure} with the help of david zuhn
19391 and Ken Raeburn. These features include support for using
19392 @file{config.sub}, @file{config.guess}, @option{--host}, and
19393 @option{--target}; making links to files; and running @command{configure}
19394 scripts in subdirectories. Adding these features enabled Ken to convert
19395 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
19398 I added more features in response to other peoples' requests. Many
19399 people had asked for @command{configure} scripts to share the results of
19400 the checks between runs, because (particularly when configuring a large
19401 source tree, like Cygnus does) they were frustratingly slow. Mike
19402 Haertel suggested adding site-specific initialization scripts. People
19403 distributing software that had to unpack on MS-DOS asked for a way to
19404 override the @file{.in} extension on the file names, which produced file
19405 names like @file{config.h.in} containing two dots. Jim Avera did an
19406 extensive examination of the problems with quoting in @code{AC_DEFINE}
19407 and @code{AC_SUBST}; his insights led to significant improvements.
19408 Richard Stallman asked that compiler output be sent to @file{config.log}
19409 instead of @file{/dev/null}, to help people debug the Emacs
19410 @command{configure} script.
19412 I made some other changes because of my dissatisfaction with the quality
19413 of the program. I made the messages showing results of the checks less
19414 ambiguous, always printing a result. I regularized the names of the
19415 macros and cleaned up coding style inconsistencies. I added some
19416 auxiliary utilities that I had developed to help convert source code
19417 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
19418 the macros not interrupt each others' messages. (That feature revealed
19419 some performance bottlenecks in @acronym{GNU} M4, which he hastily
19420 corrected!) I reorganized the documentation around problems people want
19421 to solve. And I began a test suite, because experience had shown that
19422 Autoconf has a pronounced tendency to regress when we change it.
19424 Again, several alpha testers gave invaluable feedback, especially
19425 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
19428 Finally, version 2.0 was ready. And there was much rejoicing. (And I
19429 have free time again. I think. Yeah, right.)
19432 @c ========================================================== Appendices
19434 @node Copying This Manual
19435 @appendix Copying This Manual
19439 * GNU Free Documentation License:: License for copying this manual
19448 * Environment Variable Index:: Index of environment variables used
19449 * Output Variable Index:: Index of variables set in output files
19450 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
19451 * Autoconf Macro Index:: Index of Autoconf macros
19452 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
19453 * Autotest Macro Index:: Index of Autotest macros
19454 * Program & Function Index:: Index of those with portability problems
19455 * Concept Index:: General index
19458 @node Environment Variable Index
19459 @appendixsec Environment Variable Index
19461 This is an alphabetical list of the environment variables that Autoconf
19466 @node Output Variable Index
19467 @appendixsec Output Variable Index
19469 This is an alphabetical list of the variables that Autoconf can
19470 substitute into files that it creates, typically one or more
19471 makefiles. @xref{Setting Output Variables}, for more information
19472 on how this is done.
19476 @node Preprocessor Symbol Index
19477 @appendixsec Preprocessor Symbol Index
19479 This is an alphabetical list of the C preprocessor symbols that the
19480 Autoconf macros define. To work with Autoconf, C source code needs to
19481 use these names in @code{#if} or @code{#ifdef} directives.
19485 @node Autoconf Macro Index
19486 @appendixsec Autoconf Macro Index
19488 This is an alphabetical list of the Autoconf macros.
19489 @ifset shortindexflag
19490 To make the list easier to use, the macros are listed without their
19491 preceding @samp{AC_}.
19496 @node M4 Macro Index
19497 @appendixsec M4 Macro Index
19499 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
19500 @ifset shortindexflag
19501 To make the list easier to use, the macros are listed without their
19502 preceding @samp{m4_} or @samp{AS_}.
19507 @node Autotest Macro Index
19508 @appendixsec Autotest Macro Index
19510 This is an alphabetical list of the Autotest macros.
19511 @ifset shortindexflag
19512 To make the list easier to use, the macros are listed without their
19513 preceding @samp{AT_}.
19518 @node Program & Function Index
19519 @appendixsec Program and Function Index
19521 This is an alphabetical list of the programs and functions which
19522 portability is discussed in this document.
19526 @node Concept Index
19527 @appendixsec Concept Index
19529 This is an alphabetical list of the files, tools, and concepts
19530 introduced in this document.
19536 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
19537 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
19538 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
19539 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
19540 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
19541 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
19542 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
19543 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
19544 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
19545 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
19546 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
19547 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
19548 @c LocalWords: distclean uninstall noindent versioning Tromey dir
19549 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
19550 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
19551 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
19552 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
19553 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
19554 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
19555 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
19556 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
19557 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19558 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19559 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19560 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19561 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19562 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19563 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19564 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19565 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19566 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19567 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19568 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19569 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19570 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19571 @c LocalWords: SETGID getloadavg nlist GETMNTENT irix
19572 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19573 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19574 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19575 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19576 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19577 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19578 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19579 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19580 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
19581 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19582 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19583 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19584 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19585 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19586 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
19587 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19588 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19589 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19590 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19591 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19592 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19593 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19594 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19595 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19596 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19597 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
19598 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19599 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19600 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19601 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19602 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19603 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19604 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
19605 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19606 @c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
19607 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19608 @c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
19609 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19610 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19611 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19612 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19613 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19614 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19615 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19616 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19617 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19618 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19619 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19620 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19621 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19622 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19623 @c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
19624 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
19625 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19626 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
19627 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
19629 @c Local Variables:
19631 @c ispell-local-dictionary: "american"
19632 @c indent-tabs-mode: nil
19633 @c whitespace-check-buffer-indent: nil