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 * Versioning:: Dealing with Autoconf versions
306 * Notices:: Copyright, version numbers in @command{configure}
307 * Input:: Where Autoconf should find files
308 * Output:: Outputting results from the configuration
309 * Configuration Actions:: Preparing the output based on results
310 * Configuration Files:: Creating output files
311 * Makefile Substitutions:: Using output variables in makefiles
312 * Configuration Headers:: Creating a configuration header file
313 * Configuration Commands:: Running arbitrary instantiation commands
314 * Configuration Links:: Links depending on the configuration
315 * Subdirectories:: Configuring independent packages together
316 * Default Prefix:: Changing the default installation prefix
318 Substitutions in Makefiles
320 * Preset Output Variables:: Output variables that are always set
321 * Installation Directory Variables:: Other preset output variables
322 * Changed Directory Variables:: Warnings about @file{datarootdir}
323 * Build Directories:: Supporting multiple concurrent compiles
324 * Automatic Remaking:: Makefile rules for configuring
326 Configuration Header Files
328 * Header Templates:: Input for the configuration headers
329 * autoheader Invocation:: How to create configuration templates
330 * Autoheader Macros:: How to specify CPP templates
334 * Common Behavior:: Macros' standard schemes
335 * Alternative Programs:: Selecting between alternative programs
336 * Files:: Checking for the existence of files
337 * Libraries:: Library archives that might be missing
338 * Library Functions:: C library functions that might be missing
339 * Header Files:: Header files that might be missing
340 * Declarations:: Declarations that may be missing
341 * Structures:: Structures or members that might be missing
342 * Types:: Types that might be missing
343 * Compilers and Preprocessors:: Checking for compiling programs
344 * System Services:: Operating system services
345 * Posix Variants:: Special kludges for specific Posix variants
346 * Erlang Libraries:: Checking for the existence of Erlang libraries
350 * Standard Symbols:: Symbols defined by the macros
351 * Default Includes:: Includes used by the generic macros
355 * Particular Programs:: Special handling to find certain programs
356 * Generic Programs:: How to find other programs
360 * Function Portability:: Pitfalls with usual functions
361 * Particular Functions:: Special handling to find certain functions
362 * Generic Functions:: How to find other functions
366 * Header Portability:: Collected knowledge on common headers
367 * Particular Headers:: Special handling to find certain headers
368 * Generic Headers:: How to find other headers
372 * Particular Declarations:: Macros to check for certain declarations
373 * Generic Declarations:: How to find other declarations
377 * Particular Structures:: Macros to check for certain structure members
378 * Generic Structures:: How to find other structure members
382 * Particular Types:: Special handling to find certain types
383 * Generic Types:: How to find other types
385 Compilers and Preprocessors
387 * Specific Compiler Characteristics:: Some portability issues
388 * Generic Compiler Characteristics:: Language independent tests and features
389 * C Compiler:: Checking its characteristics
390 * C++ Compiler:: Likewise
391 * Objective C Compiler:: Likewise
392 * Erlang Compiler and Interpreter:: Likewise
393 * Fortran Compiler:: Likewise
397 * Language Choice:: Selecting which language to use for testing
398 * Writing Test Programs:: Forging source files for compilers
399 * Running the Preprocessor:: Detecting preprocessor symbols
400 * Running the Compiler:: Detecting language or header features
401 * Running the Linker:: Detecting library features
402 * Runtime:: Testing for runtime features
403 * Systemology:: A zoology of operating systems
404 * Multiple Cases:: Tests for several possible values
406 Writing Test Programs
408 * Guidelines:: General rules for writing test programs
409 * Test Functions:: Avoiding pitfalls in test programs
410 * Generating Sources:: Source program boilerplate
414 * Defining Symbols:: Defining C preprocessor symbols
415 * Setting Output Variables:: Replacing variables in output files
416 * Special Chars in Variables:: Characters to beware of in variables
417 * Caching Results:: Speeding up subsequent @command{configure} runs
418 * Printing Messages:: Notifying @command{configure} users
422 * Cache Variable Names:: Shell variables used in caches
423 * Cache Files:: Files @command{configure} uses for caching
424 * Cache Checkpointing:: Loading and saving the cache file
428 * M4 Quotation:: Protecting macros from unwanted expansion
429 * Using autom4te:: The Autoconf executables backbone
430 * Programming in M4sugar:: Convenient pure M4 macros
431 * Programming in M4sh:: Common shell Constructs
432 * File Descriptor Macros:: File descriptor macros for input and output
436 * Active Characters:: Characters that change the behavior of M4
437 * One Macro Call:: Quotation and one macro call
438 * Quoting and Parameters:: M4 vs. shell parameters
439 * Quotation and Nested Macros:: Macros calling macros
440 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
441 * Quadrigraphs:: Another way to escape special characters
442 * Quotation Rule Of Thumb:: One parenthesis, one quote
444 Using @command{autom4te}
446 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
447 * Customizing autom4te:: Customizing the Autoconf package
449 Programming in M4sugar
451 * Redefined M4 Macros:: M4 builtins changed in M4sugar
452 * Conditional constructs:: Conditions in M4
453 * Looping constructs:: Iteration in M4
454 * Evaluation Macros:: More quotation and evaluation control
455 * Text processing Macros:: String manipulation in M4
456 * Forbidden Patterns:: Catching unexpanded macros
458 Writing Autoconf Macros
460 * Macro Definitions:: Basic format of an Autoconf macro
461 * Macro Names:: What to call your new macros
462 * Reporting Messages:: Notifying @command{autoconf} users
463 * Dependencies Between Macros:: What to do when macros depend on other macros
464 * Obsoleting Macros:: Warning about old ways of doing things
465 * Coding Style:: Writing Autoconf macros @`a la Autoconf
467 Dependencies Between Macros
469 * Prerequisite Macros:: Ensuring required information
470 * Suggested Ordering:: Warning about possible ordering problems
471 * One-Shot Macros:: Ensuring a macro is called only once
473 Portable Shell Programming
475 * Shellology:: A zoology of shells
476 * Here-Documents:: Quirks and tricks
477 * File Descriptors:: FDs and redirections
478 * File System Conventions:: File names
479 * Shell Pattern Matching:: Pattern matching
480 * Shell Substitutions:: Variable and command expansions
481 * Assignments:: Varying side effects of assignments
482 * Parentheses:: Parentheses in shell scripts
483 * Slashes:: Slashes in shell scripts
484 * Special Shell Variables:: Variables you should not change
485 * Limitations of Builtins:: Portable use of not so portable /bin/sh
486 * Limitations of Usual Tools:: Portable use of portable tools
488 Portable Make Programming
490 * $< in Ordinary Make Rules:: $< in ordinary rules
491 * Failure in Make Rules:: Failing portably in rules
492 * Special Chars in Names:: Special Characters in Macro Names
493 * Backslash-Newline-Newline:: Empty last lines in macro definitions
494 * Backslash-Newline Comments:: Spanning comments across line boundaries
495 * Long Lines in Makefiles:: Line length limitations
496 * Macros and Submakes:: @code{make macro=value} and submakes
497 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
498 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
499 * Comments in Make Rules:: Other problems with Make comments
500 * obj/ and Make:: Don't name a subdirectory @file{obj}
501 * make -k Status:: Exit status of @samp{make -k}
502 * VPATH and Make:: @code{VPATH} woes
503 * Single Suffix Rules:: Single suffix rules and separated dependencies
504 * Timestamps and Make:: Subsecond timestamp resolution
506 @code{VPATH} and Make
508 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
509 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
510 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
511 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
512 * Make Target Lookup:: More details about @code{VPATH} lookup
514 Portable C and C++ Programming
516 * Varieties of Unportability:: How to make your programs unportable
517 * Integer Overflow:: When integers get too large
518 * Null Pointers:: Properties of null pointers
519 * Buffer Overruns:: Subscript errors and the like
520 * Volatile Objects:: @code{volatile} and signals
521 * Floating Point Portability:: Portable floating-point arithmetic
522 * Exiting Portably:: Exiting and the exit status
526 * Specifying Names:: Specifying the system type
527 * Canonicalizing:: Getting the canonical system type
528 * Using System Type:: What to do with the system type
532 * Help Formatting:: Customizing @samp{configure --help}
533 * External Software:: Working with other optional software
534 * Package Options:: Selecting optional features
535 * Pretty Help Strings:: Formatting help string
536 * Option Checking:: Controlling checking of @command{configure} options
537 * Site Details:: Configuring site details
538 * Transforming Names:: Changing program names when installing
539 * Site Defaults:: Giving @command{configure} local defaults
541 Transforming Program Names When Installing
543 * Transformation Options:: @command{configure} options to transform names
544 * Transformation Examples:: Sample uses of transforming names
545 * Transformation Rules:: Makefile uses of transforming names
547 Running @command{configure} Scripts
549 * Basic Installation:: Instructions for typical cases
550 * Compilers and Options:: Selecting compilers and optimization
551 * Multiple Architectures:: Compiling for multiple architectures at once
552 * Installation Names:: Installing in different directories
553 * Optional Features:: Selecting optional features
554 * System Type:: Specifying the system type
555 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
556 * Defining Variables:: Specifying the compiler etc.
557 * configure Invocation:: Changing how @command{configure} runs
561 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
562 * acconfig Header:: Additional entries in @file{config.h.in}
563 * autoupdate Invocation:: Automatic update of @file{configure.ac}
564 * Obsolete Macros:: Backward compatibility macros
565 * Autoconf 1:: Tips for upgrading your files
566 * Autoconf 2.13:: Some fresher tips
568 Upgrading From Version 1
570 * Changed File Names:: Files you might rename
571 * Changed Makefiles:: New things to put in @file{Makefile.in}
572 * Changed Macros:: Macro calls you might replace
573 * Changed Results:: Changes in how to check test results
574 * Changed Macro Writing:: Better ways to write your own macros
576 Upgrading From Version 2.13
578 * Changed Quotation:: Broken code which used to work
579 * New Macros:: Interaction with foreign macros
580 * Hosts and Cross-Compilation:: Bugward compatibility kludges
581 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
582 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
584 Generating Test Suites with Autotest
586 * Using an Autotest Test Suite:: Autotest and the user
587 * Writing Testsuites:: Autotest macros
588 * testsuite Invocation:: Running @command{testsuite} scripts
589 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
591 Using an Autotest Test Suite
593 * testsuite Scripts:: The concepts of Autotest
594 * Autotest Logs:: Their contents
596 Frequent Autoconf Questions, with answers
598 * Distributing:: Distributing @command{configure} scripts
599 * Why GNU M4:: Why not use the standard M4?
600 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
601 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
602 * Defining Directories:: Passing @code{datadir} to program
603 * Autom4te Cache:: What is it? Can I remove it?
604 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
608 * Genesis:: Prehistory and naming of @command{configure}
609 * Exodus:: The plagues of M4 and Perl
610 * Leviticus:: The priestly code of portability arrives
611 * Numbers:: Growth and contributors
612 * Deuteronomy:: Approaching the promises of easy configuration
616 * GNU Free Documentation License:: License for copying this manual
620 * Environment Variable Index:: Index of environment variables used
621 * Output Variable Index:: Index of variables set in output files
622 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
623 * Autoconf Macro Index:: Index of Autoconf macros
624 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
625 * Autotest Macro Index:: Index of Autotest macros
626 * Program & Function Index:: Index of those with portability problems
627 * Concept Index:: General index
632 @c ============================================================= Introduction.
635 @chapter Introduction
639 A physicist, an engineer, and a computer scientist were discussing the
640 nature of God. ``Surely a Physicist,'' said the physicist, ``because
641 early in the Creation, God made Light; and you know, Maxwell's
642 equations, the dual nature of electromagnetic waves, the relativistic
643 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
644 before making Light, God split the Chaos into Land and Water; it takes a
645 hell of an engineer to handle that big amount of mud, and orderly
646 separation of solids from liquids@dots{}'' The computer scientist
647 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
651 @c (via Franc,ois Pinard)
653 Autoconf is a tool for producing shell scripts that automatically
654 configure software source code packages to adapt to many kinds of
655 Posix-like systems. The configuration scripts produced by Autoconf
656 are independent of Autoconf when they are run, so their users do not
657 need to have Autoconf.
659 The configuration scripts produced by Autoconf require no manual user
660 intervention when run; they do not normally even need an argument
661 specifying the system type. Instead, they individually test for the
662 presence of each feature that the software package they are for might need.
663 (Before each check, they print a one-line message stating what they are
664 checking for, so the user doesn't get too bored while waiting for the
665 script to finish.) As a result, they deal well with systems that are
666 hybrids or customized from the more common Posix variants. There is
667 no need to maintain files that list the features supported by each
668 release of each variant of Posix.
670 For each software package that Autoconf is used with, it creates a
671 configuration script from a template file that lists the system features
672 that the package needs or can use. After the shell code to recognize
673 and respond to a system feature has been written, Autoconf allows it to
674 be shared by many software packages that can use (or need) that feature.
675 If it later turns out that the shell code needs adjustment for some
676 reason, it needs to be changed in only one place; all of the
677 configuration scripts can be regenerated automatically to take advantage
680 The Metaconfig package is similar in purpose to Autoconf, but the
681 scripts it produces require manual user intervention, which is quite
682 inconvenient when configuring large source trees. Unlike Metaconfig
683 scripts, Autoconf scripts can support cross-compiling, if some care is
684 taken in writing them.
686 Autoconf does not solve all problems related to making portable
687 software packages---for a more complete solution, it should be used in
688 concert with other @acronym{GNU} build tools like Automake and
689 Libtool. These other tools take on jobs like the creation of a
690 portable, recursive makefile with all of the standard targets,
691 linking of shared libraries, and so on. @xref{The GNU Build System},
692 for more information.
694 Autoconf imposes some restrictions on the names of macros used with
695 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
697 Autoconf requires @acronym{GNU} M4 version 1.4.5 or later in order to
698 generate the scripts. It uses features that some versions of M4,
699 including @acronym{GNU} M4 1.3, do not have. Autoconf works better
700 with @acronym{GNU} M4 version 1.4.8 or later, though this is not
703 @xref{Autoconf 1}, for information about upgrading from version 1.
704 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
705 for answers to some common questions about Autoconf.
707 See the @uref{http://www.gnu.org/software/autoconf/,
708 Autoconf web page} for up-to-date information, details on the mailing
709 lists, pointers to a list of known bugs, etc.
711 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
712 list}. Past suggestions are
713 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
715 Mail bug reports to @email{bug-autoconf@@gnu.org, the
716 Autoconf Bugs mailing list}. Past bug reports are
717 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
719 If possible, first check that your bug is
720 not already solved in current development versions, and that it has not
721 been reported yet. Be sure to include all the needed information and a
722 short @file{configure.ac} that demonstrates the problem.
724 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
725 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
726 Summary} for details. Patches relative to the
727 current @acronym{CVS} version can be sent for review to the
728 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
730 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
732 Because of its mission, the Autoconf package itself
733 includes only a set of often-used
734 macros that have already demonstrated their usefulness. Nevertheless,
735 if you wish to share your macros, or find existing ones, see the
736 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
737 Archive}, which is kindly run by @email{simons@@cryp.to,
741 @c ================================================= The GNU Build System
743 @node The GNU Build System
744 @chapter The @acronym{GNU} Build System
745 @cindex @acronym{GNU} build system
747 Autoconf solves an important problem---reliable discovery of
748 system-specific build and runtime information---but this is only one
749 piece of the puzzle for the development of portable software. To this
750 end, the @acronym{GNU} project has developed a suite of integrated
751 utilities to finish the job Autoconf started: the @acronym{GNU} build
752 system, whose most important components are Autoconf, Automake, and
753 Libtool. In this chapter, we introduce you to those tools, point you
754 to sources of more information, and try to convince you to use the
755 entire @acronym{GNU} build system for your software.
758 * Automake:: Escaping makefile hell
759 * Gnulib:: The @acronym{GNU} portability library
760 * Libtool:: Building libraries portably
761 * Pointers:: More info on the @acronym{GNU} build system
767 The ubiquity of @command{make} means that a makefile is almost the
768 only viable way to distribute automatic build rules for software, but
769 one quickly runs into its numerous limitations. Its lack of
770 support for automatic dependency tracking, recursive builds in
771 subdirectories, reliable timestamps (e.g., for network file systems), and
772 so on, mean that developers must painfully (and often incorrectly)
773 reinvent the wheel for each project. Portability is non-trivial, thanks
774 to the quirks of @command{make} on many systems. On top of all this is the
775 manual labor required to implement the many standard targets that users
776 have come to expect (@code{make install}, @code{make distclean},
777 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
778 you also have to insert repetitive code in your @code{Makefile.in} to
779 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
780 provided by @command{configure}. Into this mess steps @dfn{Automake}.
783 Automake allows you to specify your build needs in a @code{Makefile.am}
784 file with a vastly simpler and more powerful syntax than that of a plain
785 makefile, and then generates a portable @code{Makefile.in} for
786 use with Autoconf. For example, the @code{Makefile.am} to build and
787 install a simple ``Hello world'' program might look like:
791 hello_SOURCES = hello.c
795 The resulting @code{Makefile.in} (~400 lines) automatically supports all
796 the standard targets, the substitutions provided by Autoconf, automatic
797 dependency tracking, @code{VPATH} building, and so on. @command{make}
798 builds the @code{hello} program, and @code{make install} installs it
799 in @file{/usr/local/bin} (or whatever prefix was given to
800 @command{configure}, if not @file{/usr/local}).
802 The benefits of Automake increase for larger packages (especially ones
803 with subdirectories), but even for small programs the added convenience
804 and portability can be substantial. And that's not all@enddots{}
809 @acronym{GNU} software has a well-deserved reputation for running on
810 many different types of systems. While our primary goal is to write
811 software for the @acronym{GNU} system, many users and developers have
812 been introduced to us through the systems that they were already using.
815 Gnulib is a central location for common @acronym{GNU} code, intended to
816 be shared among free software packages. Its components are typically
817 shared at the source level, rather than being a library that gets built,
818 installed, and linked against. The idea is to copy files from Gnulib
819 into your own source tree. There is no distribution tarball; developers
820 should just grab source modules from the repository. The source files
821 are available online, under various licenses, mostly @acronym{GNU}
822 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
824 Gnulib modules typically contain C source code along with Autoconf
825 macros used to configure the source code. For example, the Gnulib
826 @code{stdbool} module implements a @file{stdbool.h} header that nearly
827 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
828 This module contains a source file for the replacement header, along
829 with an Autoconf macro that arranges to use the replacement header on
830 old-fashioned systems.
835 Often, one wants to build not only programs, but libraries, so that
836 other programs can benefit from the fruits of your labor. Ideally, one
837 would like to produce @emph{shared} (dynamically linked) libraries,
838 which can be used by multiple programs without duplication on disk or in
839 memory and can be updated independently of the linked programs.
840 Producing shared libraries portably, however, is the stuff of
841 nightmares---each system has its own incompatible tools, compiler flags,
842 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
846 Libtool handles all the requirements of building shared libraries for
847 you, and at this time seems to be the @emph{only} way to do so with any
848 portability. It also handles many other headaches, such as: the
849 interaction of Make rules with the variable suffixes of
850 shared libraries, linking reliably with shared libraries before they are
851 installed by the superuser, and supplying a consistent versioning system
852 (so that different versions of a library can be installed or upgraded
853 without breaking binary compatibility). Although Libtool, like
854 Autoconf, can be used without Automake, it is most simply utilized in
855 conjunction with Automake---there, Libtool is used automatically
856 whenever shared libraries are needed, and you need not know its syntax.
861 Developers who are used to the simplicity of @command{make} for small
862 projects on a single system might be daunted at the prospect of
863 learning to use Automake and Autoconf. As your software is
864 distributed to more and more users, however, you otherwise
865 quickly find yourself putting lots of effort into reinventing the
866 services that the @acronym{GNU} build tools provide, and making the
867 same mistakes that they once made and overcame. (Besides, since
868 you're already learning Autoconf, Automake is a piece of cake.)
870 There are a number of places that you can go to for more information on
871 the @acronym{GNU} build tools.
878 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
879 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
880 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
881 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
883 @item Automake Manual
885 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
886 information on Automake.
890 The book @cite{@acronym{GNU} Autoconf, Automake and
891 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
892 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
893 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
894 build environment. You can also find
895 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
899 @c ================================================= Making configure Scripts.
901 @node Making configure Scripts
902 @chapter Making @command{configure} Scripts
903 @cindex @file{aclocal.m4}
904 @cindex @command{configure}
906 The configuration scripts that Autoconf produces are by convention
907 called @command{configure}. When run, @command{configure} creates several
908 files, replacing configuration parameters in them with appropriate
909 values. The files that @command{configure} creates are:
913 one or more @file{Makefile} files, usually one in each subdirectory of the
914 package (@pxref{Makefile Substitutions});
917 optionally, a C header file, the name of which is configurable,
918 containing @code{#define} directives (@pxref{Configuration Headers});
921 a shell script called @file{config.status} that, when run, recreates
922 the files listed above (@pxref{config.status Invocation});
925 an optional shell script normally called @file{config.cache}
926 (created when using @samp{configure --config-cache}) that
927 saves the results of running many of the tests (@pxref{Cache Files});
930 a file called @file{config.log} containing any messages produced by
931 compilers, to help debugging if @command{configure} makes a mistake.
934 @cindex @file{configure.in}
935 @cindex @file{configure.ac}
936 To create a @command{configure} script with Autoconf, you need to write an
937 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
938 @command{autoconf} on it. If you write your own feature tests to
939 supplement those that come with Autoconf, you might also write files
940 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
941 file to contain @code{#define} directives, you might also run
942 @command{autoheader}, and you can distribute the generated file
943 @file{config.h.in} with the package.
945 Here is a diagram showing how the files that can be used in
946 configuration are produced. Programs that are executed are suffixed by
947 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
948 @command{autoconf} and @command{autoheader} also read the installed Autoconf
949 macro files (by reading @file{autoconf.m4}).
952 Files used in preparing a software package for distribution:
954 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
958 | .------> autoconf* -----> configure
960 | `-----> [autoheader*] --> [config.h.in]
964 Makefile.in -------------------------------> Makefile.in
968 Files used in configuring a software package:
971 .-------------> [config.cache]
972 configure* ------------+-------------> config.log
974 [config.h.in] -. v .-> [config.h] -.
975 +--> config.status* -+ +--> make*
976 Makefile.in ---' `-> Makefile ---'
981 * Writing Autoconf Input:: What to put in an Autoconf input file
982 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
983 * ifnames Invocation:: Listing the conditionals in source code
984 * autoconf Invocation:: How to create configuration scripts
985 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
988 @node Writing Autoconf Input
989 @section Writing @file{configure.ac}
991 To produce a @command{configure} script for a software package, create a
992 file called @file{configure.ac} that contains invocations of the
993 Autoconf macros that test the system features your package needs or can
994 use. Autoconf macros already exist to check for many features; see
995 @ref{Existing Tests}, for their descriptions. For most other features,
996 you can use Autoconf template macros to produce custom checks; see
997 @ref{Writing Tests}, for information about them. For especially tricky
998 or specialized features, @file{configure.ac} might need to contain some
999 hand-crafted shell commands; see @ref{Portable Shell}. The
1000 @command{autoscan} program can give you a good start in writing
1001 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
1003 Previous versions of Autoconf promoted the name @file{configure.in},
1004 which is somewhat ambiguous (the tool needed to process this file is not
1005 described by its extension), and introduces a slight confusion with
1006 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1007 processed by @command{configure}''). Using @file{configure.ac} is now
1011 * Shell Script Compiler:: Autoconf as solution of a problem
1012 * Autoconf Language:: Programming in Autoconf
1013 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
1016 @node Shell Script Compiler
1017 @subsection A Shell Script Compiler
1019 Just as for any other computer language, in order to properly program
1020 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1021 the language tries to address and @emph{how} it does so.
1023 The problem Autoconf addresses is that the world is a mess. After all,
1024 you are using Autoconf in order to have your package compile easily on
1025 all sorts of different systems, some of them being extremely hostile.
1026 Autoconf itself bears the price for these differences: @command{configure}
1027 must run on all those systems, and thus @command{configure} must limit itself
1028 to their lowest common denominator of features.
1030 Naturally, you might then think of shell scripts; who needs
1031 @command{autoconf}? A set of properly written shell functions is enough to
1032 make it easy to write @command{configure} scripts by hand. Sigh!
1033 Unfortunately, shell functions do not belong to the least common
1034 denominator; therefore, where you would like to define a function and
1035 use it ten times, you would instead need to copy its body ten times.
1037 So, what is really needed is some kind of compiler, @command{autoconf},
1038 that takes an Autoconf program, @file{configure.ac}, and transforms it
1039 into a portable shell script, @command{configure}.
1041 How does @command{autoconf} perform this task?
1043 There are two obvious possibilities: creating a brand new language or
1044 extending an existing one. The former option is attractive: all
1045 sorts of optimizations could easily be implemented in the compiler and
1046 many rigorous checks could be performed on the Autoconf program
1047 (e.g., rejecting any non-portable construct). Alternatively, you can
1048 extend an existing language, such as the @code{sh} (Bourne shell)
1051 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1052 therefore most convenient to implement @command{autoconf} as a macro
1053 expander: a program that repeatedly performs @dfn{macro expansions} on
1054 text input, replacing macro calls with macro bodies and producing a pure
1055 @code{sh} script in the end. Instead of implementing a dedicated
1056 Autoconf macro expander, it is natural to use an existing
1057 general-purpose macro language, such as M4, and implement the extensions
1058 as a set of M4 macros.
1061 @node Autoconf Language
1062 @subsection The Autoconf Language
1065 The Autoconf language differs from many other computer
1066 languages because it treats actual code the same as plain text. Whereas
1067 in C, for instance, data and instructions have different syntactic
1068 status, in Autoconf their status is rigorously the same. Therefore, we
1069 need a means to distinguish literal strings from text to be expanded:
1072 When calling macros that take arguments, there must not be any white
1073 space between the macro name and the open parenthesis. Arguments should
1074 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1075 separated by commas. Any leading blanks or newlines in arguments are ignored,
1076 unless they are quoted. You should always quote an argument that
1077 might contain a macro name, comma, parenthesis, or a leading blank or
1078 newline. This rule applies recursively for every macro
1079 call, including macros called from other macros.
1084 AC_CHECK_HEADER([stdio.h],
1085 [AC_DEFINE([HAVE_STDIO_H], [1],
1086 [Define to 1 if you have <stdio.h>.])],
1087 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1091 is quoted properly. You may safely simplify its quotation to:
1094 AC_CHECK_HEADER([stdio.h],
1095 [AC_DEFINE([HAVE_STDIO_H], 1,
1096 [Define to 1 if you have <stdio.h>.])],
1097 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1101 because @samp{1} cannot contain a macro call. Here, the argument of
1102 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1103 interpreted as an argument separator. Also, the second and third arguments
1104 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1105 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1106 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1107 if you unwisely defined a macro with a name like @samp{Define} or
1108 @samp{stdio} then they would need quoting. Cautious Autoconf users
1109 would keep the quotes, but many Autoconf users find such precautions
1110 annoying, and would rewrite the example as follows:
1113 AC_CHECK_HEADER(stdio.h,
1114 [AC_DEFINE(HAVE_STDIO_H, 1,
1115 [Define to 1 if you have <stdio.h>.])],
1116 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1120 This is safe, so long as you adopt good naming conventions and do not
1121 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1122 @samp{h}. Though it is also safe here to omit the quotes around
1123 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1124 message strings are more likely to inadvertently contain commas.
1126 The following example is wrong and dangerous, as it is underquoted:
1129 AC_CHECK_HEADER(stdio.h,
1130 AC_DEFINE(HAVE_STDIO_H, 1,
1131 Define to 1 if you have <stdio.h>.),
1132 AC_MSG_ERROR([Sorry, can't do anything for you]))
1135 In other cases, you may have to use text that also resembles a macro
1136 call. You must quote that text even when it is not passed as a macro
1140 echo "Hard rock was here! --[AC_DC]"
1147 echo "Hard rock was here! --AC_DC"
1151 When you use the same text in a macro argument, you must therefore have
1152 an extra quotation level (since one is stripped away by the macro
1153 substitution). In general, then, it is a good idea to @emph{use double
1154 quoting for all literal string arguments}:
1157 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1160 You are now able to understand one of the constructs of Autoconf that
1161 has been continually misunderstood@dots{} The rule of thumb is that
1162 @emph{whenever you expect macro expansion, expect quote expansion};
1163 i.e., expect one level of quotes to be lost. For instance:
1166 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1170 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1171 @samp{char b[10];} and is expanded once, which results in
1172 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1173 address this issue via the M4 @code{changequote} primitive, but do not
1174 use it!) Let's take a closer look: the author meant the first argument
1175 to be understood as a literal, and therefore it must be quoted twice:
1178 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1182 Voil@`a, you actually produce @samp{char b[10];} this time!
1184 On the other hand, descriptions (e.g., the last parameter of
1185 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1186 are subject to line breaking, for example---and should not be double quoted.
1187 Even if these descriptions are short and are not actually broken, double
1188 quoting them yields weird results.
1190 Some macros take optional arguments, which this documentation represents
1191 as @ovar{arg} (not to be confused with the quote characters). You may
1192 just leave them empty, or use @samp{[]} to make the emptiness of the
1193 argument explicit, or you may simply omit the trailing commas. The
1194 three lines below are equivalent:
1197 AC_CHECK_HEADERS([stdio.h], [], [], [])
1198 AC_CHECK_HEADERS([stdio.h],,,)
1199 AC_CHECK_HEADERS([stdio.h])
1202 It is best to put each macro call on its own line in
1203 @file{configure.ac}. Most of the macros don't add extra newlines; they
1204 rely on the newline after the macro call to terminate the commands.
1205 This approach makes the generated @command{configure} script a little
1206 easier to read by not inserting lots of blank lines. It is generally
1207 safe to set shell variables on the same line as a macro call, because
1208 the shell allows assignments without intervening newlines.
1210 You can include comments in @file{configure.ac} files by starting them
1211 with the @samp{#}. For example, it is helpful to begin
1212 @file{configure.ac} files with a line like this:
1215 # Process this file with autoconf to produce a configure script.
1218 @node Autoconf Input Layout
1219 @subsection Standard @file{configure.ac} Layout
1221 The order in which @file{configure.ac} calls the Autoconf macros is not
1222 important, with a few exceptions. Every @file{configure.ac} must
1223 contain a call to @code{AC_INIT} before the checks, and a call to
1224 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1225 rely on other macros having been called first, because they check
1226 previously set values of some variables to decide what to do. These
1227 macros are noted in the individual descriptions (@pxref{Existing
1228 Tests}), and they also warn you when @command{configure} is created if they
1229 are called out of order.
1231 To encourage consistency, here is a suggested order for calling the
1232 Autoconf macros. Generally speaking, the things near the end of this
1233 list are those that could depend on things earlier in it. For example,
1234 library functions could be affected by types and libraries.
1238 Autoconf requirements
1239 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1240 information on the package
1242 checks for libraries
1243 checks for header files
1245 checks for structures
1246 checks for compiler characteristics
1247 checks for library functions
1248 checks for system services
1249 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1255 @node autoscan Invocation
1256 @section Using @command{autoscan} to Create @file{configure.ac}
1257 @cindex @command{autoscan}
1259 The @command{autoscan} program can help you create and/or maintain a
1260 @file{configure.ac} file for a software package. @command{autoscan}
1261 examines source files in the directory tree rooted at a directory given
1262 as a command line argument, or the current directory if none is given.
1263 It searches the source files for common portability problems and creates
1264 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1265 for that package, and checks a possibly existing @file{configure.ac} for
1268 When using @command{autoscan} to create a @file{configure.ac}, you
1269 should manually examine @file{configure.scan} before renaming it to
1270 @file{configure.ac}; it probably needs some adjustments.
1271 Occasionally, @command{autoscan} outputs a macro in the wrong order
1272 relative to another macro, so that @command{autoconf} produces a warning;
1273 you need to move such macros manually. Also, if you want the package to
1274 use a configuration header file, you must add a call to
1275 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1276 also have to change or add some @code{#if} directives to your program in
1277 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1278 information about a program that can help with that job).
1280 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1281 consider adding its suggestions. The file @file{autoscan.log}
1282 contains detailed information on why a macro is requested.
1284 @command{autoscan} uses several data files (installed along with Autoconf)
1285 to determine which macros to output when it finds particular symbols in
1286 a package's source files. These data files all have the same format:
1287 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1288 output if that symbol is encountered. Lines starting with @samp{#} are
1291 @command{autoscan} accepts the following options:
1296 Print a summary of the command line options and exit.
1300 Print the version number of Autoconf and exit.
1304 Print the names of the files it examines and the potentially interesting
1305 symbols it finds in them. This output can be voluminous.
1307 @item --include=@var{dir}
1309 Append @var{dir} to the include path. Multiple invocations accumulate.
1311 @item --prepend-include=@var{dir}
1313 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1316 @node ifnames Invocation
1317 @section Using @command{ifnames} to List Conditionals
1318 @cindex @command{ifnames}
1320 @command{ifnames} can help you write @file{configure.ac} for a software
1321 package. It prints the identifiers that the package already uses in C
1322 preprocessor conditionals. If a package has already been set up to have
1323 some portability, @command{ifnames} can thus help you figure out what its
1324 @command{configure} needs to check for. It may help fill in some gaps in a
1325 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1328 @command{ifnames} scans all of the C source files named on the command line
1329 (or the standard input, if none are given) and writes to the standard
1330 output a sorted list of all the identifiers that appear in those files
1331 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1332 directives. It prints each identifier on a line, followed by a
1333 space-separated list of the files in which that identifier occurs.
1336 @command{ifnames} accepts the following options:
1341 Print a summary of the command line options and exit.
1345 Print the version number of Autoconf and exit.
1348 @node autoconf Invocation
1349 @section Using @command{autoconf} to Create @command{configure}
1350 @cindex @command{autoconf}
1352 To create @command{configure} from @file{configure.ac}, run the
1353 @command{autoconf} program with no arguments. @command{autoconf} processes
1354 @file{configure.ac} with the M4 macro processor, using the
1355 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1356 file instead of @file{configure.ac} and writes the configuration script
1357 to the standard output instead of to @command{configure}. If you give
1358 @command{autoconf} the argument @option{-}, it reads from the standard
1359 input instead of @file{configure.ac} and writes the configuration script
1360 to the standard output.
1362 The Autoconf macros are defined in several files. Some of the files are
1363 distributed with Autoconf; @command{autoconf} reads them first. Then it
1364 looks for the optional file @file{acsite.m4} in the directory that
1365 contains the distributed Autoconf macro files, and for the optional file
1366 @file{aclocal.m4} in the current directory. Those files can contain
1367 your site's or the package's own Autoconf macro definitions
1368 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1369 defined in more than one of the files that @command{autoconf} reads, the
1370 last definition it reads overrides the earlier ones.
1372 @command{autoconf} accepts the following options:
1377 Print a summary of the command line options and exit.
1381 Print the version number of Autoconf and exit.
1385 Report processing steps.
1389 Don't remove the temporary files.
1393 Remake @file{configure} even if newer than its input files.
1395 @item --include=@var{dir}
1397 Append @var{dir} to the include path. Multiple invocations accumulate.
1399 @item --prepend-include=@var{dir}
1401 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1403 @item --output=@var{file}
1404 @itemx -o @var{file}
1405 Save output (script or trace) to @var{file}. The file @option{-} stands
1406 for the standard output.
1408 @item --warnings=@var{category}
1409 @itemx -W @var{category}
1411 Report the warnings related to @var{category} (which can actually be a
1412 comma separated list). @xref{Reporting Messages}, macro
1413 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1418 report all the warnings
1424 treats warnings as errors
1426 @item no-@var{category}
1427 disable warnings falling into @var{category}
1430 Warnings about @samp{syntax} are enabled by default, and the environment
1431 variable @env{WARNINGS}, a comma separated list of categories, is
1432 honored as well. Passing @option{-W @var{category}} actually behaves as if
1433 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. If
1434 you want to disable the defaults and @env{WARNINGS}, but (for example)
1435 enable the warnings about obsolete constructs, you would use @option{-W
1439 @cindex Macro invocation stack
1440 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1441 displays a back trace for errors, but not for warnings; if you want
1442 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1445 @item --trace=@var{macro}[:@var{format}]
1446 @itemx -t @var{macro}[:@var{format}]
1447 Do not create the @command{configure} script, but list the calls to
1448 @var{macro} according to the @var{format}. Multiple @option{--trace}
1449 arguments can be used to list several macros. Multiple @option{--trace}
1450 arguments for a single macro are not cumulative; instead, you should
1451 just make @var{format} as long as needed.
1453 The @var{format} is a regular string, with newlines if desired, and
1454 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1455 @ref{autom4te Invocation}, for details on the @var{format}.
1457 @item --initialization
1459 By default, @option{--trace} does not trace the initialization of the
1460 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1461 results in a noticeable speedup, but can be disabled by this option.
1465 It is often necessary to check the content of a @file{configure.ac}
1466 file, but parsing it yourself is extremely fragile and error-prone. It
1467 is suggested that you rely upon @option{--trace} to scan
1468 @file{configure.ac}. For instance, to find the list of variables that
1469 are substituted, use:
1473 $ @kbd{autoconf -t AC_SUBST}
1474 configure.ac:2:AC_SUBST:ECHO_C
1475 configure.ac:2:AC_SUBST:ECHO_N
1476 configure.ac:2:AC_SUBST:ECHO_T
1477 @i{More traces deleted}
1482 The example below highlights the difference between @samp{$@@},
1483 @samp{$*}, and @samp{$%}.
1487 $ @kbd{cat configure.ac}
1488 AC_DEFINE(This, is, [an
1490 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1497 %: This:is:an [example]
1502 The @var{format} gives you a lot of freedom:
1506 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1507 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1508 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1509 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1510 @i{More traces deleted}
1515 A long @var{separator} can be used to improve the readability of complex
1516 structures, and to ease their parsing (for instance when no single
1517 character is suitable as a separator):
1521 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1522 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1523 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1524 AUTOMAKE|:::::|automake|:::::|$missing_dir
1525 @i{More traces deleted}
1529 @node autoreconf Invocation
1530 @section Using @command{autoreconf} to Update @command{configure} Scripts
1531 @cindex @command{autoreconf}
1533 Installing the various components of the @acronym{GNU} Build System can be
1534 tedious: running @command{autopoint} for Gettext, @command{automake} for
1535 @file{Makefile.in} etc.@: in each directory. It may be needed either
1536 because some tools such as @command{automake} have been updated on your
1537 system, or because some of the sources such as @file{configure.ac} have
1538 been updated, or finally, simply in order to install the @acronym{GNU} Build
1539 System in a fresh tree.
1541 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1542 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1543 @command{autopoint} (when appropriate) repeatedly to update the
1544 @acronym{GNU} Build System in the specified directories and their
1545 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1546 those files that are older than their sources.
1548 If you install a new version of some tool, you can make
1549 @command{autoreconf} remake @emph{all} of the files by giving it the
1550 @option{--force} option.
1552 @xref{Automatic Remaking}, for Make rules to automatically
1553 remake @command{configure} scripts when their source files change. That
1554 method handles the timestamps of configuration header templates
1555 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1556 @option{--localdir=@var{dir}}.
1559 @cindex @command{autopoint}
1560 Gettext supplies the @command{autopoint} command to add translation
1561 infrastructure to a source package. If you use @command{autopoint},
1562 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1563 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1564 Invocation, , Invoking the @code{autopoint} Program, gettext,
1565 @acronym{GNU} @code{gettext} utilities}, for further details.
1568 @command{autoreconf} accepts the following options:
1573 Print a summary of the command line options and exit.
1577 Print the version number of Autoconf and exit.
1580 Print the name of each directory @command{autoreconf} examines and the
1581 commands it runs. If given two or more times, pass @option{--verbose}
1582 to subordinate tools that support it.
1586 Don't remove the temporary files.
1590 Remake even @file{configure} scripts and configuration headers that are
1591 newer than their input files (@file{configure.ac} and, if present,
1596 Install the missing auxiliary files in the package. By default, files
1597 are copied; this can be changed with @option{--symlink}.
1599 If deemed appropriate, this option triggers calls to
1600 @samp{automake --add-missing},
1601 @samp{libtoolize}, @samp{autopoint}, etc.
1603 @item --no-recursive
1604 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1605 macro @code{AC_CONFIG_SUBDIRS}).
1609 When used with @option{--install}, install symbolic links to the missing
1610 auxiliary files instead of copying them.
1614 When the directories were configured, update the configuration by
1615 running @samp{./config.status --recheck && ./config.status}, and then
1618 @item --include=@var{dir}
1620 Append @var{dir} to the include path. Multiple invocations accumulate.
1621 Passed on to @command{autoconf} and @command{autoheader} internally.
1623 @item --prepend-include=@var{dir}
1625 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1626 Passed on to @command{autoconf} and @command{autoheader} internally.
1628 @item --warnings=@var{category}
1629 @itemx -W @var{category}
1631 Report the warnings related to @var{category} (which can actually be a
1632 comma separated list).
1636 related to cross compilation issues.
1639 report the uses of obsolete constructs.
1645 dubious syntactic constructs.
1648 report all the warnings
1654 treats warnings as errors
1656 @item no-@var{category}
1657 disable warnings falling into @var{category}
1660 Warnings about @samp{syntax} are enabled by default, and the environment
1661 variable @env{WARNINGS}, a comma separated list of categories, is
1662 honored as well. Passing @option{-W @var{category}} actually behaves as if
1663 you had passed @option{--warnings syntax,$WARNINGS,@var{category}}. If
1664 you want to disable the defaults and @env{WARNINGS}, but (for example)
1665 enable the warnings about obsolete constructs, you would use @option{-W
1669 If you want @command{autoreconf} to pass flags that are not listed here
1670 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1671 Due to a limitation in the Autoconf implementation these flags currently
1672 must be set on a single line in @file{Makefile.am}, without any
1675 @c ========================================= Initialization and Output Files.
1678 @chapter Initialization and Output Files
1680 Autoconf-generated @command{configure} scripts need some information about
1681 how to initialize, such as how to find the package's source files and
1682 about the output files to produce. The following sections describe the
1683 initialization and the creation of output files.
1686 * Initializing configure:: Option processing etc.
1687 * Versioning:: Dealing with Autoconf versions
1688 * Notices:: Copyright, version numbers in @command{configure}
1689 * Input:: Where Autoconf should find files
1690 * Output:: Outputting results from the configuration
1691 * Configuration Actions:: Preparing the output based on results
1692 * Configuration Files:: Creating output files
1693 * Makefile Substitutions:: Using output variables in makefiles
1694 * Configuration Headers:: Creating a configuration header file
1695 * Configuration Commands:: Running arbitrary instantiation commands
1696 * Configuration Links:: Links depending on the configuration
1697 * Subdirectories:: Configuring independent packages together
1698 * Default Prefix:: Changing the default installation prefix
1701 @node Initializing configure
1702 @section Initializing @command{configure}
1704 Every @command{configure} script must call @code{AC_INIT} before doing
1705 anything else. The only other required macro is @code{AC_OUTPUT}
1709 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
1712 Process any command-line arguments and perform various initializations
1715 Set the name of the @var{package} and its @var{version}. These are
1716 typically used in @option{--version} support, including that of
1717 @command{configure}. The optional argument @var{bug-report} should be
1718 the email to which users should send bug reports. The package
1719 @var{tarname} differs from @var{package}: the latter designates the full
1720 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1721 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1722 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1723 other than alphanumerics and underscores are changed to @samp{-}.
1725 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1726 there should not be any shell computation, but they can be computed by
1729 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1730 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1731 @code{PACKAGE_NAME}), are defined by @code{AC_INIT}:
1734 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1735 @acindex{PACKAGE_NAME}
1736 @ovindex PACKAGE_NAME
1737 @cvindex PACKAGE_NAME
1738 Exactly @var{package}.
1740 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1741 @acindex{PACKAGE_TARNAME}
1742 @ovindex PACKAGE_TARNAME
1743 @cvindex PACKAGE_TARNAME
1744 Exactly @var{tarname}.
1746 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1747 @acindex{PACKAGE_VERSION}
1748 @ovindex PACKAGE_VERSION
1749 @cvindex PACKAGE_VERSION
1750 Exactly @var{version}.
1752 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1753 @acindex{PACKAGE_STRING}
1754 @ovindex PACKAGE_STRING
1755 @cvindex PACKAGE_STRING
1756 Exactly @samp{@var{package} @var{version}}.
1758 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1759 @acindex{PACKAGE_BUGREPORT}
1760 @ovindex PACKAGE_BUGREPORT
1761 @cvindex PACKAGE_BUGREPORT
1762 Exactly @var{bug-report}.
1766 If your @command{configure} script does its own option processing, it
1767 should inspect @samp{$@@} or @samp{$*} immediately after calling
1768 @code{AC_INIT}, because other Autoconf macros liberally use the
1769 @command{set} command to process strings, and this has the side effect
1770 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1771 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1772 implement your own option processing. @xref{Site Configuration}.
1775 @section Dealing with Autoconf versions
1776 @cindex Autoconf version
1777 @cindex version, Autoconf
1779 The following optional macros can be used to help choose the minimum
1780 version of Autoconf that can successfully compile a given
1781 @file{configure.ac}.
1783 @defmac AC_PREREQ (@var{version})
1786 Ensure that a recent enough version of Autoconf is being used. If the
1787 version of Autoconf being used to create @command{configure} is
1788 earlier than @var{version}, print an error message to the standard
1789 error output and exit with failure (exit status is 63). For example:
1792 AC_PREREQ([@value{VERSION}])
1795 This macro is the only macro that may be used before @code{AC_INIT}, but
1796 for consistency, you are invited not to do so.
1801 This macro was introduced in Autoconf 2.62. It identifies the version
1802 of Autoconf that is currently parsing the input file, in a format
1803 suitable for @code{m4_version_compare} (@pxref{m4_version_compare}); in
1804 other words, for this release of Autoconf, its value is
1805 @samp{@value{VERSION}}. One potential use of this macro is for writing
1806 conditional fallbacks based on when a feature was added to Autoconf,
1807 rather than using @code{AC_PREREQ} to require the newer version of
1808 Autoconf. However, remember that the Autoconf philosophy favors feature
1809 checks over version checks.
1813 @section Notices in @command{configure}
1814 @cindex Notices in @command{configure}
1816 The following macros manage version numbers for @command{configure}
1817 scripts. Using them is optional.
1819 @defmac AC_COPYRIGHT (@var{copyright-notice})
1821 @cindex Copyright Notice
1822 State that, in addition to the Free Software Foundation's copyright on
1823 the Autoconf macros, parts of your @command{configure} are covered by the
1824 @var{copyright-notice}.
1826 The @var{copyright-notice} shows up in both the head of
1827 @command{configure} and in @samp{configure --version}.
1831 @defmac AC_REVISION (@var{revision-info})
1834 Copy revision stamp @var{revision-info} into the @command{configure}
1835 script, with any dollar signs or double-quotes removed. This macro lets
1836 you put a revision stamp from @file{configure.ac} into @command{configure}
1837 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1838 @command{configure}. That way, you can determine easily which revision of
1839 @file{configure.ac} a particular @command{configure} corresponds to.
1841 For example, this line in @file{configure.ac}:
1843 @c The asis prevents RCS from changing the example in the manual.
1845 AC_REVISION([$@asis{Revision: 1.30 }$])
1849 produces this in @command{configure}:
1853 # From configure.ac Revision: 1.30
1859 @section Finding @command{configure} Input
1861 @anchor{AC_CONFIG_SRCDIR}
1862 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1863 @acindex{CONFIG_SRCDIR}
1864 @var{unique-file-in-source-dir} is some file that is in the package's
1865 source directory; @command{configure} checks for this file's existence to
1866 make sure that the directory that it is told contains the source code in
1867 fact does. Occasionally people accidentally specify the wrong directory
1868 with @option{--srcdir}; this is a safety check. @xref{configure
1869 Invocation}, for more information.
1873 @c FIXME: Remove definitively once --install explained.
1875 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1876 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1877 @c to split the macros in several files. In this case, Autoconf must be
1878 @c told which files to load, and in which order.
1880 @c @defmac AC_INCLUDE (@var{file}@dots{})
1881 @c @acindex{INCLUDE}
1882 @c @c FIXME: There is no longer shell globbing.
1883 @c Read the macro definitions that appear in the listed files. A list of
1884 @c space-separated file names or shell globbing patterns is expected. The
1885 @c files are read in the order they're listed.
1887 @c Because the order of definition of macros is important (only the last
1888 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1889 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1890 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1891 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1892 @c the latter case, non-macro lines from included files may end up in the
1893 @c @file{configure} script, whereas in the former case, they'd be discarded
1894 @c just like any text that appear before @code{AC_INIT}.
1897 Packages that do manual configuration or use the @command{install} program
1898 might need to tell @command{configure} where to find some other shell
1899 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1900 it looks are correct for most cases.
1902 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1903 @acindex{CONFIG_AUX_DIR}
1904 Use the auxiliary build tools (e.g., @file{install-sh},
1905 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1906 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1907 These are auxiliary files used in configuration. @var{dir} can be
1908 either absolute or relative to @file{@var{srcdir}}. The default is
1909 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1910 @file{@var{srcdir}/../..}, whichever is the first that contains
1911 @file{install-sh}. The other files are not checked for, so that using
1912 @code{AC_PROG_INSTALL} does not automatically require distributing the
1913 other auxiliary files. It checks for @file{install.sh} also, but that
1914 name is obsolete because some @code{make} have a rule that creates
1915 @file{install} from it if there is no makefile.
1917 The auxiliary directory is commonly named @file{build-aux}.
1918 If you need portability to @acronym{DOS} variants, do not name the
1919 auxiliary directory @file{aux}. @xref{File System Conventions}.
1922 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1923 @acindex{REQUIRE_AUX_FILE}
1924 Declares that @var{file} is expected in the directory defined above. In
1925 Autoconf proper, this macro does nothing: its sole purpose is to be
1926 traced by third-party tools to produce a list of expected auxiliary
1927 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1928 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1929 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1932 Similarly, packages that use @command{aclocal} should declare where
1933 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1935 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1936 @acindex{CONFIG_MACRO_DIR}
1937 Specify @var{dir} as the location of additional local Autoconf macros.
1938 This macro is intended for use by future versions of commands like
1939 @command{autoreconf} that trace macro calls. It should be called
1940 directly from @file{configure.ac} so that tools that install macros for
1941 @command{aclocal} can find the macros' declarations.
1946 @section Outputting Files
1947 @cindex Outputting files
1949 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1950 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1951 @file{config.status}, which in turn creates the makefiles and any
1952 other files resulting from configuration. This is the only required
1953 macro besides @code{AC_INIT} (@pxref{Input}).
1958 @cindex Instantiation
1959 Generate @file{config.status} and launch it. Call this macro once, at
1960 the end of @file{configure.ac}.
1962 @file{config.status} performs all the configuration actions: all the
1963 output files (see @ref{Configuration Files}, macro
1964 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1965 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1966 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1967 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1968 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1971 The location of your @code{AC_OUTPUT} invocation is the exact point
1972 where configuration actions are taken: any code afterwards is
1973 executed by @code{configure} once @command{config.status} was run. If
1974 you want to bind actions to @command{config.status} itself
1975 (independently of whether @command{configure} is being run), see
1976 @ref{Configuration Commands, , Running Arbitrary Configuration
1980 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1981 @xref{Obsolete Macros}, for a description of the arguments that
1982 @code{AC_OUTPUT} used to support.
1985 If you run @command{make} in subdirectories, you should run it using the
1986 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1987 @code{MAKE} to the name of the @command{make} program plus any options it
1988 was given. (But many do not include in it the values of any variables
1989 set on the command line, so those are not passed on automatically.)
1990 Some old versions of @command{make} do not set this variable. The
1991 following macro allows you to use it even with those versions.
1993 @anchor{AC_PROG_MAKE_SET}
1994 @defmac AC_PROG_MAKE_SET
1995 @acindex{PROG_MAKE_SET}
1997 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1998 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1999 Otherwise, define @code{SET_MAKE} to a macro definition that sets
2000 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
2004 If you use this macro, place a line like this in each @file{Makefile.in}
2005 that runs @code{MAKE} on other directories:
2013 @node Configuration Actions
2014 @section Performing Configuration Actions
2015 @cindex Configuration actions
2017 @file{configure} is designed so that it appears to do everything itself,
2018 but there is actually a hidden slave: @file{config.status}.
2019 @file{configure} is in charge of examining your system, but it is
2020 @file{config.status} that actually takes the proper actions based on the
2021 results of @file{configure}. The most typical task of
2022 @file{config.status} is to @emph{instantiate} files.
2024 This section describes the common behavior of the four standard
2025 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
2026 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
2027 have this prototype:
2029 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
2032 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2036 where the arguments are:
2040 A blank-or-newline-separated list of tags, which are typically the names of
2041 the files to instantiate.
2043 You are encouraged to use literals as @var{tags}. In particular, you
2047 @dots{} && my_foos="$my_foos fooo"
2048 @dots{} && my_foos="$my_foos foooo"
2049 AC_CONFIG_FOOS([$my_foos])
2053 and use this instead:
2056 @dots{} && AC_CONFIG_FOOS([fooo])
2057 @dots{} && AC_CONFIG_FOOS([foooo])
2060 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2061 special @var{tag} values: they may have the form @samp{@var{output}} or
2062 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2063 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2065 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2066 for example, asks for
2067 the creation of the file @file{Makefile} that contains the expansion of the
2068 output variables in the concatenation of @file{boiler/top.mk} and
2069 @file{boiler/bot.mk}.
2071 The special value @samp{-} might be used to denote the standard output
2072 when used in @var{output}, or the standard input when used in the
2073 @var{inputs}. You most probably don't need to use this in
2074 @file{configure.ac}, but it is convenient when using the command line
2075 interface of @file{./config.status}, see @ref{config.status Invocation},
2078 The @var{inputs} may be absolute or relative file names. In the latter
2079 case they are first looked for in the build tree, and then in the source
2083 Shell commands output literally into @file{config.status}, and
2084 associated with a tag that the user can use to tell @file{config.status}
2085 which the commands to run. The commands are run each time a @var{tag}
2086 request is given to @file{config.status}, typically each time the file
2087 @file{@var{tag}} is created.
2089 The variables set during the execution of @command{configure} are
2090 @emph{not} available here: you first need to set them via the
2091 @var{init-cmds}. Nonetheless the following variables are precomputed:
2095 The name of the top source directory, assuming that the working
2096 directory is the top build directory. This
2097 is what the @command{configure} option @option{--srcdir} sets.
2100 The name of the top source directory, assuming that the working
2101 directory is the current build directory.
2104 @item ac_top_build_prefix
2105 The name of the top build directory, assuming that the working
2106 directory is the current build directory.
2107 It can be empty, or else ends with a slash, so that you may concatenate
2111 The name of the corresponding source directory, assuming that the
2112 working directory is the current build directory.
2116 The @dfn{current} directory refers to the directory (or
2117 pseudo-directory) containing the input part of @var{tags}. For
2121 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2125 with @option{--srcdir=../package} produces the following values:
2128 # Argument of --srcdir
2130 # Reversing deep/dir
2131 ac_top_build_prefix='../../'
2132 # Concatenation of $ac_top_build_prefix and srcdir
2133 ac_top_srcdir='../../../package'
2134 # Concatenation of $ac_top_srcdir and deep/dir
2135 ac_srcdir='../../../package/deep/dir'
2139 independently of @samp{in/in.in}.
2142 Shell commands output @emph{unquoted} near the beginning of
2143 @file{config.status}, and executed each time @file{config.status} runs
2144 (regardless of the tag). Because they are unquoted, for example,
2145 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2146 is typically used by @file{configure} to give @file{config.status} some
2147 variables it needs to run the @var{commands}.
2149 You should be extremely cautious in your variable names: all the
2150 @var{init-cmds} share the same name space and may overwrite each other
2151 in unpredictable ways. Sorry@enddots{}
2154 All these macros can be called multiple times, with different
2155 @var{tag} values, of course!
2158 @node Configuration Files
2159 @section Creating Configuration Files
2160 @cindex Creating configuration files
2161 @cindex Configuration file creation
2163 Be sure to read the previous section, @ref{Configuration Actions}.
2165 @anchor{AC_CONFIG_FILES}
2166 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2167 @acindex{CONFIG_FILES}
2168 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2169 file (by default @file{@var{file}.in}), substituting the output variable
2171 @c Before we used to have this feature, which was later rejected
2172 @c because it complicates the writing of makefiles:
2173 @c If the file would be unchanged, it is left untouched, to preserve
2175 This macro is one of the instantiating macros; see @ref{Configuration
2176 Actions}. @xref{Makefile Substitutions}, for more information on using
2177 output variables. @xref{Setting Output Variables}, for more information
2178 on creating them. This macro creates the directory that the file is in
2179 if it doesn't exist. Usually, makefiles are created this way,
2180 but other files, such as @file{.gdbinit}, can be specified as well.
2182 Typical calls to @code{AC_CONFIG_FILES} look like this:
2185 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2186 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2189 You can override an input file name by appending to @var{file} a
2190 colon-separated list of input files. Examples:
2193 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2194 [lib/Makefile:boiler/lib.mk])
2198 Doing this allows you to keep your file names acceptable to
2199 @acronym{DOS} variants, or
2200 to prepend and/or append boilerplate to the file.
2205 @node Makefile Substitutions
2206 @section Substitutions in Makefiles
2207 @cindex Substitutions in makefiles
2208 @cindex Makefile substitutions
2210 Each subdirectory in a distribution that contains something to be
2211 compiled or installed should come with a file @file{Makefile.in}, from
2212 which @command{configure} creates a file @file{Makefile} in that directory.
2213 To create @file{Makefile}, @command{configure} performs a simple variable
2214 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2215 @file{Makefile.in} with the value that @command{configure} has determined
2216 for that variable. Variables that are substituted into output files in
2217 this way are called @dfn{output variables}. They are ordinary shell
2218 variables that are set in @command{configure}. To make @command{configure}
2219 substitute a particular variable into the output files, the macro
2220 @code{AC_SUBST} must be called with that variable name as an argument.
2221 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2222 left unchanged. @xref{Setting Output Variables}, for more information
2223 on creating output variables with @code{AC_SUBST}.
2225 A software package that uses a @command{configure} script should be
2226 distributed with a file @file{Makefile.in}, but no makefile; that
2227 way, the user has to properly configure the package for the local system
2228 before compiling it.
2230 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2231 @acronym{GNU} Coding Standards}, for more information on what to put in
2235 * Preset Output Variables:: Output variables that are always set
2236 * Installation Directory Variables:: Other preset output variables
2237 * Changed Directory Variables:: Warnings about @file{datarootdir}
2238 * Build Directories:: Supporting multiple concurrent compiles
2239 * Automatic Remaking:: Makefile rules for configuring
2242 @node Preset Output Variables
2243 @subsection Preset Output Variables
2244 @cindex Output variables
2246 Some output variables are preset by the Autoconf macros. Some of the
2247 Autoconf macros set additional output variables, which are mentioned in
2248 the descriptions for those macros. @xref{Output Variable Index}, for a
2249 complete list of output variables. @xref{Installation Directory
2250 Variables}, for the list of the preset ones related to installation
2251 directories. Below are listed the other preset ones. They all are
2252 precious variables (@pxref{Setting Output Variables},
2255 @c Just say no to ASCII sorting! We're humans, not computers.
2256 @c These variables are listed as they would be in a dictionary:
2263 Debugging and optimization options for the C compiler. If it is not set
2264 in the environment when @command{configure} runs, the default value is set
2265 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2266 uses this variable when compiling or linking programs to test for C features.
2268 If a compiler option affects only the behavior of the preprocessor
2269 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2270 instead. If it affects only the linker (e.g., @option{-L
2271 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2272 affects only the compiler proper, @code{CFLAGS} is the natural home for
2273 it. If an option affects multiple phases of the compiler, though,
2274 matters get tricky. One approach to put such options directly into
2275 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2276 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2280 @defvar configure_input
2281 @ovindex configure_input
2282 A comment saying that the file was generated automatically by
2283 @command{configure} and giving the name of the input file.
2284 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2285 of every makefile it creates. For other files, you should
2286 reference this variable in a comment at the top of each input file. For
2287 example, an input shell script should begin like this:
2291 # @@configure_input@@
2295 The presence of that line also reminds people editing the file that it
2296 needs to be processed by @command{configure} in order to be used.
2301 Preprocessor options for the C, C++, and Objective C preprocessors and
2303 it is not set in the environment when @command{configure} runs, the default
2304 value is empty. @command{configure} uses this variable when preprocessing
2305 or compiling programs to test for C, C++, and Objective C features.
2307 This variable's contents should contain options like @option{-I},
2308 @option{-D}, and @option{-U} that affect only the behavior of the
2309 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2310 can do if an option affects other phases of the compiler as well.
2312 Currently, @command{configure} always links as part of a single
2313 invocation of the compiler that also preprocesses and compiles, so it
2314 uses this variable also when linking programs. However, it is unwise to
2315 depend on this behavior because the @acronym{GNU} coding standards do
2316 not require it and many packages do not use @code{CPPFLAGS} when linking
2319 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2325 Debugging and optimization options for the C++ compiler. It acts like
2326 @code{CFLAGS}, but for C++ instead of C.
2331 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2332 is called, @command{configure} replaces @samp{@@DEFS@@} with
2333 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2334 variable is not defined while @command{configure} is performing its tests,
2335 only when creating the output files. @xref{Setting Output Variables}, for
2336 how to check the results of previous tests.
2345 How does one suppress the trailing newline from @command{echo} for
2346 question-answer message pairs? These variables provide a way:
2349 echo $ECHO_N "And the winner is... $ECHO_C"
2351 echo "$@{ECHO_T@}dead."
2355 Some old and uncommon @command{echo} implementations offer no means to
2356 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2362 Debugging and optimization options for the Erlang compiler. If it is not set
2363 in the environment when @command{configure} runs, the default value is empty.
2364 @command{configure} uses this variable when compiling
2365 programs to test for Erlang features.
2370 Debugging and optimization options for the Fortran compiler. If it
2371 is not set in the environment when @command{configure} runs, the default
2372 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2373 @command{configure} uses this variable when compiling or linking
2374 programs to test for Fortran features.
2379 Debugging and optimization options for the Fortran 77 compiler. If it
2380 is not set in the environment when @command{configure} runs, the default
2381 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2382 @command{configure} uses this variable when compiling or linking
2383 programs to test for Fortran 77 features.
2388 Options for the linker. If it is not set
2389 in the environment when @command{configure} runs, the default value is empty.
2390 @command{configure} uses this variable when linking programs to test for
2391 C, C++, Objective C, and Fortran features.
2393 This variable's contents should contain options like @option{-s} and
2394 @option{-L} that affect only the behavior of the linker. Please see the
2395 explanation of @code{CFLAGS} for what you can do if an option also
2396 affects other phases of the compiler.
2398 Don't use this variable to pass library names
2399 (@option{-l}) to the linker; use @code{LIBS} instead.
2404 @option{-l} options to pass to the linker. The default value is empty,
2405 but some Autoconf macros may prepend extra libraries to this variable if
2406 those libraries are found and provide necessary functions, see
2407 @ref{Libraries}. @command{configure} uses this variable when linking
2408 programs to test for C, C++, and Fortran features.
2413 Debugging and optimization options for the Objective C compiler. It
2414 acts like @code{CFLAGS}, but for Objective C instead of C.
2419 Rigorously equal to @samp{.}. Added for symmetry only.
2422 @defvar abs_builddir
2423 @ovindex abs_builddir
2424 Absolute name of @code{builddir}.
2427 @defvar top_builddir
2428 @ovindex top_builddir
2429 The relative name of the top level of the current build tree. In the
2430 top-level directory, this is the same as @code{builddir}.
2433 @defvar abs_top_builddir
2434 @ovindex abs_top_builddir
2435 Absolute name of @code{top_builddir}.
2440 The name of the directory that contains the source code for
2446 Absolute name of @code{srcdir}.
2451 The name of the top-level source code directory for the
2452 package. In the top-level directory, this is the same as @code{srcdir}.
2455 @defvar abs_top_srcdir
2456 @ovindex abs_top_srcdir
2457 Absolute name of @code{top_srcdir}.
2460 @node Installation Directory Variables
2461 @subsection Installation Directory Variables
2462 @cindex Installation directories
2463 @cindex Directories, installation
2465 The following variables specify the directories for
2466 package installation, see @ref{Directory Variables, , Variables for
2467 Installation Directories, standards, The @acronym{GNU} Coding
2468 Standards}, for more information. Each variable corresponds to an
2469 argument of @command{configure}; trailing slashes are stripped so that
2470 expressions such as @samp{$@{prefix@}/lib} expand with only one slash
2471 between directory names. See the end of this section for
2472 details on when and how to use these variables.
2476 The directory for installing executables that users run.
2481 The directory for installing idiosyncratic read-only
2482 architecture-independent data.
2486 @ovindex datarootdir
2487 The root of the directory tree for read-only architecture-independent
2493 The directory for installing documentation files (other than Info and
2499 The directory for installing documentation files in DVI format.
2503 @ovindex exec_prefix
2504 The installation prefix for architecture-dependent files. By default
2505 it's the same as @var{prefix}. You should avoid installing anything
2506 directly to @var{exec_prefix}. However, the default value for
2507 directories containing architecture-dependent files should be relative
2508 to @var{exec_prefix}.
2513 The directory for installing HTML documentation.
2518 The directory for installing C header files.
2523 The directory for installing documentation in Info format.
2528 The directory for installing object code libraries.
2533 The directory for installing executables that other programs run.
2538 The directory for installing locale-dependent but
2539 architecture-independent data, such as message catalogs. This directory
2540 usually has a subdirectory per locale.
2543 @defvar localstatedir
2544 @ovindex localstatedir
2545 The directory for installing modifiable single-machine data.
2550 The top-level directory for installing documentation in man format.
2553 @defvar oldincludedir
2554 @ovindex oldincludedir
2555 The directory for installing C header files for non-@acronym{GCC} compilers.
2560 The directory for installing PDF documentation.
2565 The common installation prefix for all files. If @var{exec_prefix}
2566 is defined to a different value, @var{prefix} is used only for
2567 architecture-independent files.
2572 The directory for installing PostScript documentation.
2577 The directory for installing executables that system
2581 @defvar sharedstatedir
2582 @ovindex sharedstatedir
2583 The directory for installing modifiable architecture-independent data.
2588 The directory for installing read-only single-machine data.
2592 Most of these variables have values that rely on @code{prefix} or
2593 @code{exec_prefix}. It is deliberate that the directory output
2594 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2595 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2596 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2598 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2603 she can still specify a different prefix from the one specified to
2604 @command{configure}, in which case, if needed, the package should hard
2605 code dependencies corresponding to the make-specified prefix.
2608 she can specify a different installation location, in which case the
2609 package @emph{must} still depend on the location which was compiled in
2610 (i.e., never recompile when @samp{make install} is run). This is an
2611 extremely important feature, as many people may decide to install all
2612 the files of a package grouped together, and then install links from
2613 the final locations to there.
2616 In order to support these features, it is essential that
2617 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2618 depend upon the current value of @code{prefix}.
2620 A corollary is that you should not use these variables except in
2621 makefiles. For instance, instead of trying to evaluate @code{datadir}
2622 in @file{configure} and hard-coding it in makefiles using
2623 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2625 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2626 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2628 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2629 @code{datadir} and friends in your shell scripts and other files; instead,
2630 let @command{make} manage their replacement. For instance Autoconf
2631 ships templates of its shell scripts ending with @samp{.in}, and uses a
2632 makefile snippet similar to the following to build scripts like
2633 @command{autoheader} and @command{autom4te}:
2638 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2639 -e 's|@@prefix[@@]|$(prefix)|g'
2643 autoheader autom4te: Makefile
2645 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2652 autoheader: $(srcdir)/autoheader.in
2653 autom4te: $(srcdir)/autom4te.in
2657 Some details are noteworthy:
2660 @item @samp{@@datadir[@@]}
2661 The brackets prevent @command{configure} from replacing
2662 @samp{@@datadir@@} in the Sed expression itself.
2663 Brackets are preferable to a backslash here, since
2664 Posix says @samp{\@@} is not portable.
2666 @item @samp{$(pkgdatadir)}
2667 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2671 Don't use @samp{/} in the Sed expressions that replace file names since
2673 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2674 Use a shell metacharacter instead, such as @samp{|}.
2676 @item special characters
2677 File names, file name components, and the value of @code{VPATH} should
2678 not contain shell metacharacters or white
2679 space. @xref{Special Chars in Variables}.
2681 @item dependency on @file{Makefile}
2682 Since @code{edit} uses values that depend on the configuration specific
2683 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2684 the output depends on @file{Makefile}, not @file{configure.ac}.
2687 The main rule is generic, and uses @samp{$@@} extensively to
2688 avoid the need for multiple copies of the rule.
2690 @item Separated dependencies and single suffix rules
2691 You can't use them! The above snippet cannot be (portably) rewritten
2695 autoconf autoheader: Makefile
2705 @xref{Single Suffix Rules}, for details.
2707 @item @samp{$(srcdir)}
2708 Be sure to specify the name of the source directory,
2709 otherwise the package won't support separated builds.
2712 For the more specific installation of Erlang libraries, the following variables
2715 @defvar ERLANG_INSTALL_LIB_DIR
2716 @ovindex ERLANG_INSTALL_LIB_DIR
2717 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2718 The common parent directory of Erlang library installation directories.
2719 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2720 macro in @file{configure.ac}.
2723 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2724 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2725 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2726 The installation directory for Erlang library @var{library}.
2727 This variable is set by calling the
2728 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2729 macro in @file{configure.ac}.
2732 @xref{Erlang Libraries}, for details.
2735 @node Changed Directory Variables
2736 @subsection Changed Directory Variables
2737 @cindex @file{datarootdir}
2739 In Autoconf 2.60, the set of directory variables has changed, and the
2740 defaults of some variables have been adjusted
2741 (@pxref{Installation Directory Variables}) to changes in the
2742 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2743 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2744 upgrading from an earlier Autoconf version, you may need to adjust your files
2745 to ensure that the directory variables are substituted correctly
2746 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2747 in place. For example, in a @file{Makefile.in}, adding
2750 datarootdir = @@datarootdir@@
2754 is usually sufficient. If you use Automake to create @file{Makefile.in},
2755 it will add this for you.
2757 To help with the transition, Autoconf warns about files that seem to use
2758 @code{datarootdir} without defining it. In some cases, it then expands
2759 the value of @code{$datarootdir} in substitutions of the directory
2760 variables. The following example shows such a warning:
2763 $ @kbd{cat configure.ac}
2765 AC_CONFIG_FILES([Makefile])
2767 $ @kbd{cat Makefile.in}
2769 datadir = @@datadir@@
2772 configure: creating ./config.status
2773 config.status: creating Makefile
2774 config.status: WARNING:
2775 Makefile.in seems to ignore the --datarootdir setting
2776 $ @kbd{cat Makefile}
2778 datadir = $@{prefix@}/share
2781 Usually one can easily change the file to accommodate both older and newer
2785 $ @kbd{cat Makefile.in}
2787 datarootdir = @@datarootdir@@
2788 datadir = @@datadir@@
2790 configure: creating ./config.status
2791 config.status: creating Makefile
2792 $ @kbd{cat Makefile}
2794 datarootdir = $@{prefix@}/share
2795 datadir = $@{datarootdir@}
2798 @acindex{DATAROOTDIR_CHECKED}
2799 In some cases, however, the checks may not be able to detect that a suitable
2800 initialization of @code{datarootdir} is in place, or they may fail to detect
2801 that such an initialization is necessary in the output file. If, after
2802 auditing your package, there are still spurious @file{configure} warnings about
2803 @code{datarootdir}, you may add the line
2806 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2810 to your @file{configure.ac} to disable the warnings. This is an exception
2811 to the usual rule that you should not define a macro whose name begins with
2812 @code{AC_} (@pxref{Macro Names}).
2816 @node Build Directories
2817 @subsection Build Directories
2818 @cindex Build directories
2819 @cindex Directories, build
2821 You can support compiling a software package for several architectures
2822 simultaneously from the same copy of the source code. The object files
2823 for each architecture are kept in their own directory.
2825 To support doing this, @command{make} uses the @code{VPATH} variable to
2826 find the files that are in the source directory. @acronym{GNU} Make
2827 can do this. Most other recent @command{make} programs can do this as
2828 well, though they may have difficulties and it is often simpler to
2829 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}). Older
2830 @command{make} programs do not support @code{VPATH}; when using them, the
2831 source code must be in the same directory as the object files.
2833 To support @code{VPATH}, each @file{Makefile.in} should contain two
2834 lines that look like:
2841 Do not set @code{VPATH} to the value of another variable, for example
2842 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2843 variable substitutions on the value of @code{VPATH}.
2845 @command{configure} substitutes the correct value for @code{srcdir} when
2846 it produces @file{Makefile}.
2848 Do not use the @code{make} variable @code{$<}, which expands to the
2849 file name of the file in the source directory (found with @code{VPATH}),
2850 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2851 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2852 versions of @command{make} do not set @code{$<} in explicit rules; they
2853 expand it to an empty value.
2855 Instead, Make command lines should always refer to source
2856 files by prefixing them with @samp{$(srcdir)/}. For example:
2859 time.info: time.texinfo
2860 $(MAKEINFO) '$(srcdir)/time.texinfo'
2863 @node Automatic Remaking
2864 @subsection Automatic Remaking
2865 @cindex Automatic remaking
2866 @cindex Remaking automatically
2868 You can put rules like the following in the top-level @file{Makefile.in}
2869 for a package to automatically update the configuration information when
2870 you change the configuration files. This example includes all of the
2871 optional files, such as @file{aclocal.m4} and those related to
2872 configuration header files. Omit from the @file{Makefile.in} rules for
2873 any of these files that your package does not use.
2875 The @samp{$(srcdir)/} prefix is included because of limitations in the
2876 @code{VPATH} mechanism.
2878 The @file{stamp-} files are necessary because the timestamps of
2879 @file{config.h.in} and @file{config.h} are not changed if remaking
2880 them does not change their contents. This feature avoids unnecessary
2881 recompilation. You should include the file @file{stamp-h.in} your
2882 package's distribution, so that @command{make} considers
2883 @file{config.h.in} up to date. Don't use @command{touch}
2884 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2885 @command{date} would cause needless differences, hence @acronym{CVS}
2890 $(srcdir)/configure: configure.ac aclocal.m4
2891 cd '$(srcdir)' && autoconf
2893 # autoheader might not change config.h.in, so touch a stamp file.
2894 $(srcdir)/config.h.in: stamp-h.in
2895 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2896 cd '$(srcdir)' && autoheader
2897 echo timestamp > '$(srcdir)/stamp-h.in'
2900 stamp-h: config.h.in config.status
2903 Makefile: Makefile.in config.status
2906 config.status: configure
2907 ./config.status --recheck
2912 (Be careful if you copy these lines directly into your makefile, as you
2913 need to convert the indented lines to start with the tab character.)
2915 In addition, you should use
2918 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2922 so @file{config.status} ensures that @file{config.h} is considered up to
2923 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2925 @xref{config.status Invocation}, for more examples of handling
2926 configuration-related dependencies.
2928 @node Configuration Headers
2929 @section Configuration Header Files
2930 @cindex Configuration Header
2931 @cindex @file{config.h}
2933 When a package contains more than a few tests that define C preprocessor
2934 symbols, the command lines to pass @option{-D} options to the compiler
2935 can get quite long. This causes two problems. One is that the
2936 @command{make} output is hard to visually scan for errors. More
2937 seriously, the command lines can exceed the length limits of some
2938 operating systems. As an alternative to passing @option{-D} options to
2939 the compiler, @command{configure} scripts can create a C header file
2940 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2941 macro selects this kind of output. Though it can be called anywhere
2942 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2943 it right after @code{AC_INIT}.
2945 The package should @samp{#include} the configuration header file before
2946 any other header files, to prevent inconsistencies in declarations (for
2947 example, if it redefines @code{const}).
2949 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2950 option (or @option{-I..}; whichever directory contains @file{config.h}).
2951 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2952 the directory of the currently read file, i.e., the source directory, not
2953 the build directory.
2955 With the appropriate @option{-I} option, you can use
2956 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2957 because in the rare case when the source directory contains another
2958 @file{config.h}, the build directory should be searched first.
2961 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2962 @acindex{CONFIG_HEADERS}
2963 @cvindex HAVE_CONFIG_H
2964 This macro is one of the instantiating macros; see @ref{Configuration
2965 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2966 blank-or-newline-separated list @var{header} containing C preprocessor
2967 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2968 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2969 The usual name for @var{header} is @file{config.h}.
2971 If @var{header} already exists and its contents are identical to what
2972 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2973 making some changes in the configuration without needlessly causing
2974 object files that depend on the header file to be recompiled.
2976 Usually the input file is named @file{@var{header}.in}; however, you can
2977 override the input file name by appending to @var{header} a
2978 colon-separated list of input files. For example, you might need to make
2979 the input file name acceptable to @acronym{DOS} variants:
2982 AC_CONFIG_HEADERS([config.h:config.hin])
2989 This macro is defined as the name of the first declared config header
2990 and undefined if no config headers have been declared up to this point.
2991 A third-party macro may, for example, require use of a config header
2992 without invoking AC_CONFIG_HEADERS twice, like this:
2995 AC_CONFIG_COMMANDS_PRE(
2996 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
3001 @xref{Configuration Actions}, for more details on @var{header}.
3004 * Header Templates:: Input for the configuration headers
3005 * autoheader Invocation:: How to create configuration templates
3006 * Autoheader Macros:: How to specify CPP templates
3009 @node Header Templates
3010 @subsection Configuration Header Templates
3011 @cindex Configuration Header Template
3012 @cindex Header templates
3013 @cindex @file{config.h.in}
3015 Your distribution should contain a template file that looks as you want
3016 the final header file to look, including comments, with @code{#undef}
3017 statements which are used as hooks. For example, suppose your
3018 @file{configure.ac} makes these calls:
3021 AC_CONFIG_HEADERS([conf.h])
3022 AC_CHECK_HEADERS([unistd.h])
3026 Then you could have code like the following in @file{conf.h.in}. On
3027 systems that have @file{unistd.h}, @command{configure} defines
3028 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
3029 commented out (in case the system predefines that symbol).
3033 /* Define as 1 if you have unistd.h. */
3034 #undef HAVE_UNISTD_H
3038 Pay attention that @samp{#undef} is in the first column, and there is
3039 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3040 then decode the configuration header using the preprocessor directives:
3046 #ifdef HAVE_UNISTD_H
3047 # include <unistd.h>
3049 /* We are in trouble. */
3054 The use of old form templates, with @samp{#define} instead of
3055 @samp{#undef} is strongly discouraged. Similarly with old templates
3056 with comments on the same line as the @samp{#undef}. Anyway, putting
3057 comments in preprocessor macros has never been a good idea.
3059 Since it is a tedious task to keep a template header up to date, you may
3060 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3063 @node autoheader Invocation
3064 @subsection Using @command{autoheader} to Create @file{config.h.in}
3065 @cindex @command{autoheader}
3067 The @command{autoheader} program can create a template file of C
3068 @samp{#define} statements for @command{configure} to use.
3069 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3070 @file{configure} sources to determine the name of the template.
3071 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3072 input file name, @command{autoheader} uses the first one.)
3074 It is recommended that only one input file is used. If you want to append
3075 a boilerplate code, it is preferable to use
3076 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3077 File @file{conf_post.h} is not processed during the configuration then,
3078 which make things clearer. Analogically, @code{AH_TOP} can be used to
3079 prepend a boilerplate code.
3081 In order to do its job, @command{autoheader} needs you to document all
3082 of the symbols that you might use. Typically this is done via an
3083 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3084 is a literal symbol and whose third argument describes the symbol
3085 (@pxref{Defining Symbols}). Alternatively, you can use
3086 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3087 suitable input file for a subsequent configuration header file.
3088 Symbols defined by Autoconf's builtin tests are already documented properly;
3089 you need to document only those that you
3092 You might wonder why @command{autoheader} is needed: after all, why
3093 would @command{configure} need to ``patch'' a @file{config.h.in} to
3094 produce a @file{config.h} instead of just creating @file{config.h} from
3095 scratch? Well, when everything rocks, the answer is just that we are
3096 wasting our time maintaining @command{autoheader}: generating
3097 @file{config.h} directly is all that is needed. When things go wrong,
3098 however, you'll be thankful for the existence of @command{autoheader}.
3100 The fact that the symbols are documented is important in order to
3101 @emph{check} that @file{config.h} makes sense. The fact that there is a
3102 well-defined list of symbols that should be defined (or not) is
3103 also important for people who are porting packages to environments where
3104 @command{configure} cannot be run: they just have to @emph{fill in the
3107 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3109 If you give @command{autoheader} an argument, it uses that file instead
3110 of @file{configure.ac} and writes the header file to the standard output
3111 instead of to @file{config.h.in}. If you give @command{autoheader} an
3112 argument of @option{-}, it reads the standard input instead of
3113 @file{configure.ac} and writes the header file to the standard output.
3115 @command{autoheader} accepts the following options:
3120 Print a summary of the command line options and exit.
3124 Print the version number of Autoconf and exit.
3128 Report processing steps.
3132 Don't remove the temporary files.
3136 Remake the template file even if newer than its input files.
3138 @item --include=@var{dir}
3140 Append @var{dir} to the include path. Multiple invocations accumulate.
3142 @item --prepend-include=@var{dir}
3144 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3146 @item --warnings=@var{category}
3147 @itemx -W @var{category}
3149 Report the warnings related to @var{category} (which can actually be a
3150 comma separated list). Current categories include:
3154 report the uses of obsolete constructs
3157 report all the warnings
3163 treats warnings as errors
3165 @item no-@var{category}
3166 disable warnings falling into @var{category}
3173 @node Autoheader Macros
3174 @subsection Autoheader Macros
3175 @cindex Autoheader macros
3177 @command{autoheader} scans @file{configure.ac} and figures out which C
3178 preprocessor symbols it might define. It knows how to generate
3179 templates for symbols defined by @code{AC_CHECK_HEADERS},
3180 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3181 symbol, you must define a template for it. If there are missing
3182 templates, @command{autoheader} fails with an error message.
3184 The template for a @var{symbol} is created
3185 by @command{autoheader} from
3186 the @var{description} argument to an @code{AC_DEFINE};
3187 see @ref{Defining Symbols}.
3189 For special needs, you can use the following macros.
3192 @defmac AH_TEMPLATE (@var{key}, @var{description})
3194 Tell @command{autoheader} to generate a template for @var{key}. This macro
3195 generates standard templates just like @code{AC_DEFINE} when a
3196 @var{description} is given.
3201 AH_TEMPLATE([CRAY_STACKSEG_END],
3202 [Define to one of _getb67, GETB67, getb67
3203 for Cray-2 and Cray-YMP systems. This
3204 function is required for alloca.c support
3209 generates the following template, with the description properly
3213 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3214 Cray-YMP systems. This function is required for alloca.c
3215 support on those systems. */
3216 #undef CRAY_STACKSEG_END
3221 @defmac AH_VERBATIM (@var{key}, @var{template})
3223 Tell @command{autoheader} to include the @var{template} as-is in the header
3224 template file. This @var{template} is associated with the @var{key},
3225 which is used to sort all the different templates and guarantee their
3226 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3230 @defmac AH_TOP (@var{text})
3232 Include @var{text} at the top of the header template file.
3236 @defmac AH_BOTTOM (@var{text})
3238 Include @var{text} at the bottom of the header template file.
3242 Please note that @var{text} gets included ``verbatim'' to the template file,
3243 not to the resulting config header, so it can easily get mangled when the
3244 template is processed. There is rarely a need for something other than
3247 AH_BOTTOM([#include <custom.h>])
3252 @node Configuration Commands
3253 @section Running Arbitrary Configuration Commands
3254 @cindex Configuration commands
3255 @cindex Commands for configuration
3257 You can execute arbitrary commands before, during, and after
3258 @file{config.status} is run. The three following macros accumulate the
3259 commands to run when they are called multiple times.
3260 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3261 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3263 @anchor{AC_CONFIG_COMMANDS}
3264 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3265 @acindex{CONFIG_COMMANDS}
3266 Specify additional shell commands to run at the end of
3267 @file{config.status}, and shell commands to initialize any variables
3268 from @command{configure}. Associate the commands with @var{tag}.
3269 Since typically the @var{cmds} create a file, @var{tag} should
3270 naturally be the name of that file. If needed, the directory hosting
3271 @var{tag} is created. This macro is one of the instantiating macros;
3272 see @ref{Configuration Actions}.
3274 Here is an unrealistic example:
3277 AC_CONFIG_COMMANDS([fubar],
3278 [echo this is extra $fubar, and so on.],
3282 Here is a better one:
3284 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3288 The following two macros look similar, but in fact they are not of the same
3289 breed: they are executed directly by @file{configure}, so you cannot use
3290 @file{config.status} to rerun them.
3292 @c Yet it is good to leave them here. The user sees them together and
3293 @c decides which best fits their needs.
3295 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3296 @acindex{CONFIG_COMMANDS_PRE}
3297 Execute the @var{cmds} right before creating @file{config.status}.
3299 This macro presents the last opportunity to call @code{AC_SUBST},
3300 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3303 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3304 @acindex{CONFIG_COMMANDS_POST}
3305 Execute the @var{cmds} right after creating @file{config.status}.
3311 @node Configuration Links
3312 @section Creating Configuration Links
3313 @cindex Configuration links
3314 @cindex Links for configuration
3316 You may find it convenient to create links whose destinations depend upon
3317 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3318 creation of relative symbolic links can be delicate when the package is
3319 built in a directory different from the source directory.
3321 @anchor{AC_CONFIG_LINKS}
3322 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @
3324 @acindex{CONFIG_LINKS}
3326 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3327 the corresponding link name @var{dest}. Makes a symbolic link if
3328 possible, otherwise a hard link if possible, otherwise a copy. The
3329 @var{dest} and @var{source} names should be relative to the top level
3330 source or build directory. This macro is one of the instantiating
3331 macros; see @ref{Configuration Actions}.
3333 For example, this call:
3336 AC_CONFIG_LINKS([host.h:config/$machine.h
3337 object.h:config/$obj_format.h])
3341 creates in the current directory @file{host.h} as a link to
3342 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3343 link to @file{@var{srcdir}/config/$obj_format.h}.
3345 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3346 impossible for @samp{config.status} to guess the links to establish.
3350 ./config.status host.h object.h
3353 to create the links.
3358 @node Subdirectories
3359 @section Configuring Other Packages in Subdirectories
3360 @cindex Configure subdirectories
3361 @cindex Subdirectory configure
3363 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3364 makefiles in subdirectories. However, @command{configure} scripts
3365 that control more than one independent package can use
3366 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3367 packages in subdirectories.
3369 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3370 @acindex{CONFIG_SUBDIRS}
3372 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3373 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3374 be a literal, i.e., please do not use:
3377 if test "$package_foo_enabled" = yes; then
3378 $my_subdirs="$my_subdirs foo"
3380 AC_CONFIG_SUBDIRS([$my_subdirs])
3384 because this prevents @samp{./configure --help=recursive} from
3385 displaying the options of the package @code{foo}. Instead, you should
3389 if test "$package_foo_enabled" = yes; then
3390 AC_CONFIG_SUBDIRS([foo])
3394 If a given @var{dir} is not found, an error is reported: if the
3395 subdirectory is optional, write:
3398 if test -d "$srcdir/foo"; then
3399 AC_CONFIG_SUBDIRS([foo])
3403 @c NB: Yes, below we mean configure.in, not configure.ac.
3404 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3405 of @command{configure}. This is for packages that might use a
3406 non-Autoconf script @command{Configure}, which can't be called through a
3407 wrapper @command{configure} since it would be the same file on
3408 case-insensitive file systems. Likewise, if a @var{dir} contains
3409 @file{configure.in} but no @command{configure}, the Cygnus
3410 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3412 The subdirectory @command{configure} scripts are given the same command
3413 line options that were given to this @command{configure} script, with minor
3414 changes if needed, which include:
3418 adjusting a relative name for the cache file;
3421 adjusting a relative name for the source directory;
3424 propagating the current value of @code{$prefix}, including if it was
3425 defaulted, and if the default values of the top level and of the subdirectory
3426 @file{configure} differ.
3429 This macro also sets the output variable @code{subdirs} to the list of
3430 directories @samp{@var{dir} @dots{}}. Make rules can use
3431 this variable to determine which subdirectories to recurse into.
3433 This macro may be called multiple times.
3436 @node Default Prefix
3437 @section Default Prefix
3438 @cindex Install prefix
3439 @cindex Prefix for install
3441 By default, @command{configure} sets the prefix for files it installs to
3442 @file{/usr/local}. The user of @command{configure} can select a different
3443 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3444 There are two ways to change the default: when creating
3445 @command{configure}, and when running it.
3447 Some software packages might want to install in a directory other than
3448 @file{/usr/local} by default. To accomplish that, use the
3449 @code{AC_PREFIX_DEFAULT} macro.
3451 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3452 @acindex{PREFIX_DEFAULT}
3453 Set the default installation prefix to @var{prefix} instead of
3457 It may be convenient for users to have @command{configure} guess the
3458 installation prefix from the location of a related program that they
3459 have already installed. If you wish to do that, you can call
3460 @code{AC_PREFIX_PROGRAM}.
3462 @anchor{AC_PREFIX_PROGRAM}
3463 @defmac AC_PREFIX_PROGRAM (@var{program})
3464 @acindex{PREFIX_PROGRAM}
3465 If the user did not specify an installation prefix (using the
3466 @option{--prefix} option), guess a value for it by looking for
3467 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3468 is found, set the prefix to the parent of the directory containing
3469 @var{program}, else default the prefix as described above
3470 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3471 @var{program} is @code{gcc} and the @env{PATH} contains
3472 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3477 @c ======================================================== Existing tests
3479 @node Existing Tests
3480 @chapter Existing Tests
3482 These macros test for particular system features that packages might
3483 need or want to use. If you need to test for a kind of feature that
3484 none of these macros check for, you can probably do it by calling
3485 primitive test macros with appropriate arguments (@pxref{Writing
3488 These tests print messages telling the user which feature they're
3489 checking for, and what they find. They cache their results for future
3490 @command{configure} runs (@pxref{Caching Results}).
3492 Some of these macros set output variables. @xref{Makefile
3493 Substitutions}, for how to get their values. The phrase ``define
3494 @var{name}'' is used below as a shorthand to mean ``define the C
3495 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3496 Symbols}, for how to get those symbol definitions into your program.
3499 * Common Behavior:: Macros' standard schemes
3500 * Alternative Programs:: Selecting between alternative programs
3501 * Files:: Checking for the existence of files
3502 * Libraries:: Library archives that might be missing
3503 * Library Functions:: C library functions that might be missing
3504 * Header Files:: Header files that might be missing
3505 * Declarations:: Declarations that may be missing
3506 * Structures:: Structures or members that might be missing
3507 * Types:: Types that might be missing
3508 * Compilers and Preprocessors:: Checking for compiling programs
3509 * System Services:: Operating system services
3510 * Posix Variants:: Special kludges for specific Posix variants
3511 * Erlang Libraries:: Checking for the existence of Erlang libraries
3514 @node Common Behavior
3515 @section Common Behavior
3516 @cindex Common autoconf behavior
3518 Much effort has been expended to make Autoconf easy to learn. The most
3519 obvious way to reach this goal is simply to enforce standard interfaces
3520 and behaviors, avoiding exceptions as much as possible. Because of
3521 history and inertia, unfortunately, there are still too many exceptions
3522 in Autoconf; nevertheless, this section describes some of the common
3526 * Standard Symbols:: Symbols defined by the macros
3527 * Default Includes:: Includes used by the generic macros
3530 @node Standard Symbols
3531 @subsection Standard Symbols
3532 @cindex Standard symbols
3534 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3535 their test transform their @var{argument} values to a standard alphabet.
3536 First, @var{argument} is converted to upper case and any asterisks
3537 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3538 that are not alphanumeric are converted to underscores.
3543 AC_CHECK_TYPES([struct $Expensive*])
3547 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3551 @node Default Includes
3552 @subsection Default Includes
3553 @cindex Default includes
3554 @cindex Includes, default
3556 Several tests depend upon a set of header files. Since these headers
3557 are not universally available, tests actually have to provide a set of
3558 protected includes, such as:
3562 #ifdef TIME_WITH_SYS_TIME
3563 # include <sys/time.h>
3566 # ifdef HAVE_SYS_TIME_H
3567 # include <sys/time.h>
3576 Unless you know exactly what you are doing, you should avoid using
3577 unconditional includes, and check the existence of the headers you
3578 include beforehand (@pxref{Header Files}).
3580 Most generic macros use the following macro to provide the default set
3583 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3584 @acindex{INCLUDES_DEFAULT}
3585 Expand to @var{include-directives} if defined, otherwise to:
3590 #ifdef HAVE_SYS_TYPES_H
3591 # include <sys/types.h>
3593 #ifdef HAVE_SYS_STAT_H
3594 # include <sys/stat.h>
3597 # include <stdlib.h>
3598 # include <stddef.h>
3600 # ifdef HAVE_STDLIB_H
3601 # include <stdlib.h>
3604 #ifdef HAVE_STRING_H
3605 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3606 # include <memory.h>
3608 # include <string.h>
3610 #ifdef HAVE_STRINGS_H
3611 # include <strings.h>
3613 #ifdef HAVE_INTTYPES_H
3614 # include <inttypes.h>
3616 #ifdef HAVE_STDINT_H
3617 # include <stdint.h>
3619 #ifdef HAVE_UNISTD_H
3620 # include <unistd.h>
3625 If the default includes are used, then check for the presence of these
3626 headers and their compatibility, i.e., you don't need to run
3627 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3629 These headers are checked for in the same order as they are included.
3630 For instance, on some systems @file{string.h} and @file{strings.h} both
3631 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3632 @code{HAVE_STRINGS_H}.
3635 @node Alternative Programs
3636 @section Alternative Programs
3637 @cindex Programs, checking
3639 These macros check for the presence or behavior of particular programs.
3640 They are used to choose between several alternative programs and to
3641 decide what to do once one has been chosen. If there is no macro
3642 specifically defined to check for a program you need, and you don't need
3643 to check for any special properties of it, then you can use one of the
3644 general program-check macros.
3647 * Particular Programs:: Special handling to find certain programs
3648 * Generic Programs:: How to find other programs
3651 @node Particular Programs
3652 @subsection Particular Program Checks
3654 These macros check for particular programs---whether they exist, and
3655 in some cases whether they support certain features.
3660 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3661 order, and set output variable @code{AWK} to the first one that is found.
3662 It tries @code{gawk} first because that is reported to be the
3663 best implementation.
3666 @defmac AC_PROG_GREP
3669 Look for the best available @code{grep} or @code{ggrep} that accepts the
3670 longest input lines possible, and that supports multiple @option{-e} options.
3671 Set the output variable @code{GREP} to whatever is chosen.
3672 @xref{Limitations of Usual Tools}, for more information about
3673 portability problems with the @command{grep} command family.
3676 @defmac AC_PROG_EGREP
3677 @acindex{PROG_EGREP}
3679 Check whether @code{$GREP -E} works, or else look for the best available
3680 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3681 Set the output variable @code{EGREP} to whatever is chosen.
3684 @defmac AC_PROG_FGREP
3685 @acindex{PROG_FGREP}
3687 Check whether @code{$GREP -F} works, or else look for the best available
3688 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3689 Set the output variable @code{FGREP} to whatever is chosen.
3692 @defmac AC_PROG_INSTALL
3693 @acindex{PROG_INSTALL}
3695 @ovindex INSTALL_PROGRAM
3696 @ovindex INSTALL_DATA
3697 @ovindex INSTALL_SCRIPT
3698 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3699 @command{install} program, if one is found in the current @env{PATH}.
3700 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3701 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3702 default directories) to determine @var{dir} (@pxref{Output}). Also set
3703 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3704 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3706 @samp{@@INSTALL@@} is special, as its value may vary for different
3707 configuration files.
3709 This macro screens out various instances of @command{install} known not to
3710 work. It prefers to find a C program rather than a shell script, for
3711 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3712 but that name is obsolete because some @command{make} programs have a rule
3713 that creates @file{install} from it if there is no makefile.
3715 Autoconf comes with a copy of @file{install-sh} that you can use. If
3716 you use @code{AC_PROG_INSTALL}, you must include either
3717 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3718 @command{configure} produces an error message saying it can't find
3719 them---even if the system you're on has a good @command{install} program.
3720 This check is a safety measure to prevent you from accidentally leaving
3721 that file out, which would prevent your package from installing on
3722 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3724 If you need to use your own installation program because it has features
3725 not found in standard @command{install} programs, there is no reason to use
3726 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3727 @file{Makefile.in} files.
3730 @defmac AC_PROG_MKDIR_P
3731 @acindex{PROG_MKDIR_P}
3733 Set output variable @code{MKDIR_P} to a program that ensures that for
3734 each argument, a directory named by this argument exists, creating it
3735 and its parent directories if needed, and without race conditions when
3736 two instances of the program attempt to make the same directory at
3737 nearly the same time.
3739 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3740 falls back on invoking @command{install-sh} with the @option{-d} option,
3741 so your package should
3742 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3743 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3744 is vulnerable to race conditions, so if you want to support parallel
3746 different packages into the same directory you need to make sure you
3747 have an up-to-date @file{install-sh}. In particular, be careful about
3748 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3750 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3751 in M4sh}), but it sets an output variable intended for use in other
3752 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3753 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3754 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3755 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3756 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3757 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3758 Finally, @code{AS_MKDIR_P} does not check for race condition
3759 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3761 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3762 configuration files.
3765 @anchor{AC_PROG_LEX}
3770 @cvindex YYTEXT_POINTER
3771 @ovindex LEX_OUTPUT_ROOT
3772 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3773 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3774 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3777 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3778 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3779 the base of the file name that the lexer generates; usually
3780 @file{lex.yy}, but sometimes something else. These results vary
3781 according to whether @code{lex} or @code{flex} is being used.
3783 You are encouraged to use Flex in your sources, since it is both more
3784 pleasant to use than plain Lex and the C source it produces is portable.
3785 In order to ensure portability, however, you must either provide a
3786 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3787 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3788 statement in the scanner's source. Once this done, the scanner is
3789 portable (unless @emph{you} felt free to use nonportable constructs) and
3790 does not depend on any library. In this case, and in this case only, it
3791 is suggested that you use this Autoconf snippet:
3795 if test "$LEX" != flex; then
3796 LEX="$SHELL $missing_dir/missing flex"
3797 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3798 AC_SUBST([LEXLIB], [''])
3802 The shell script @command{missing} can be found in the Automake
3805 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3806 (indirectly) this macro twice, which causes an annoying but benign
3807 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3808 of Automake will fix this issue; meanwhile, just ignore this message.
3810 As part of running the test, this macro may delete any file in the
3811 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3814 @anchor{AC_PROG_LN_S}
3815 @defmac AC_PROG_LN_S
3818 If @samp{ln -s} works on the current file system (the operating system
3819 and file system support symbolic links), set the output variable
3820 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3821 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3823 If you make a link in a directory other than the current directory, its
3824 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3825 create links using @samp{$(LN_S)}, either find out which form is used
3826 and adjust the arguments, or always invoke @code{ln} in the directory
3827 where the link is to be created.
3829 In other words, it does not work to do:
3837 (cd /x && $(LN_S) foo bar)
3841 @defmac AC_PROG_RANLIB
3842 @acindex{PROG_RANLIB}
3844 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3845 is found, and otherwise to @samp{:} (do nothing).
3851 Set output variable @code{SED} to a Sed implementation that conforms to
3852 Posix and does not have arbitrary length limits. Report an error if no
3853 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3854 information about portability problems with Sed.
3857 @defmac AC_PROG_YACC
3860 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3861 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3862 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3865 @node Generic Programs
3866 @subsection Generic Program and File Checks
3868 These macros are used to find programs not covered by the ``particular''
3869 test macros. If you need to check the behavior of a program as well as
3870 find out whether it is present, you have to write your own test for it
3871 (@pxref{Writing Tests}). By default, these macros use the environment
3872 variable @env{PATH}. If you need to check for a program that might not
3873 be in the user's @env{PATH}, you can pass a modified path to use
3877 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3878 [$PATH$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl
3879 [/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/etc])
3882 You are strongly encouraged to declare the @var{variable} passed to
3883 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3884 @code{AC_ARG_VAR}, for more details.
3886 @anchor{AC_CHECK_PROG}
3887 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @
3888 @var{value-if-found}, @ovar{value-if-not-found}, @dvar{path, $PATH}, @
3890 @acindex{CHECK_PROG}
3891 Check whether program @var{prog-to-check-for} exists in @var{path}. If
3892 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3893 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3894 absolute file name) even if it is the first found in the search path; in
3895 that case, set @var{variable} using the absolute file name of the
3896 @var{prog-to-check-for} found that is not @var{reject}. If
3897 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3901 @anchor{AC_CHECK_PROGS}
3902 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @
3903 @ovar{value-if-not-found}, @dvar{path, $PATH})
3904 @acindex{CHECK_PROGS}
3905 Check for each program in the blank-separated list
3906 @var{progs-to-check-for} existing in the @var{path}. If one is found, set
3907 @var{variable} to the name of that program. Otherwise, continue
3908 checking the next program in the list. If none of the programs in the
3909 list are found, set @var{variable} to @var{value-if-not-found}; if
3910 @var{value-if-not-found} is not specified, the value of @var{variable}
3911 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3914 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
3915 @ovar{value-if-not-found}, @dvar{path, $PATH})
3916 @acindex{CHECK_TARGET_TOOL}
3917 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3918 with a prefix of the target type as determined by
3919 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3920 If the tool cannot be found with a prefix, and if the build and target
3921 types are equal, then it is also searched for without a prefix.
3923 As noted in @ref{Specifying Names, , Specifying the system type}, the
3924 target is rarely specified, because most of the time it is the same
3925 as the host: it is the type of system for which any compiler tool in
3926 the package produces code. What this macro looks for is,
3927 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3928 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3929 uses to produce objects, archives or executables}.
3932 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @
3933 @ovar{value-if-not-found}, @dvar{path, $PATH})
3934 @acindex{CHECK_TOOL}
3935 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3936 with a prefix of the host type as determined by
3937 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3938 For example, if the user runs @samp{configure --host=i386-gnu}, then
3941 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3944 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3945 @var{path}, or otherwise to @samp{ranlib} if that program exists in
3946 @var{path}, or to @samp{:} if neither program exists.
3948 In the future, when cross-compiling this macro will @emph{only}
3949 accept program names that are prefixed with the host type.
3950 For more information, see @ref{Specifying Names, , Specifying the
3954 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @
3955 @ovar{value-if-not-found}, @dvar{path, $PATH})
3956 @acindex{CHECK_TARGET_TOOLS}
3957 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3958 @var{progs-to-check-for} are checked with a prefix of the target type as
3959 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3960 (@pxref{Canonicalizing}). If none of the tools can be found with a
3961 prefix, and if the build and target types are equal, then the first one
3962 without a prefix is used. If a tool is found, set @var{variable} to
3963 the name of that program. If none of the tools in the list are found,
3964 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3965 is not specified, the value of @var{variable} is not changed. Calls
3966 @code{AC_SUBST} for @var{variable}.
3969 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @
3970 @ovar{value-if-not-found}, @dvar{path, $PATH})
3971 @acindex{CHECK_TOOLS}
3972 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3973 @var{progs-to-check-for} are checked with a prefix of the host type as
3974 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3975 (@pxref{Canonicalizing}). If none of the tools can be found with a
3976 prefix, then the first one without a prefix is used. If a tool is found,
3977 set @var{variable} to the name of that program. If none of the tools in
3978 the list are found, set @var{variable} to @var{value-if-not-found}; if
3979 @var{value-if-not-found} is not specified, the value of @var{variable}
3980 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3982 In the future, when cross-compiling this macro will @emph{not}
3983 accept program names that are not prefixed with the host type.
3986 @anchor{AC_PATH_PROG}
3987 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @
3988 @ovar{value-if-not-found}, @dvar{path, $PATH})
3990 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3991 name of @var{prog-to-check-for} if found.
3994 @anchor{AC_PATH_PROGS}
3995 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @
3996 @ovar{value-if-not-found}, @dvar{path, $PATH})
3997 @acindex{PATH_PROGS}
3998 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3999 are found, set @var{variable} to the absolute name of the program
4003 @defmac AC_PATH_PROGS_FEATURE_CHECK (@var{variable}, @
4004 @var{progs-to-check-for}, @var{feature-test}, @
4005 @ovar{action-if-not-found}, @dvar{path, $PATH})
4006 @acindex{PATH_PROGS_FEATURE_CHECK}
4007 This macro was introduced in Autoconf 2.62. If @var{variable} is not
4008 empty, then set the cache variable @code{$ac_cv_path_@var{variable}} to
4009 its value. Otherwise, check for each program in the blank-separated
4010 list @var{progs-to-check-for} existing in @var{path}. For each program
4011 found, execute @var{feature-test} with @code{$ac_path_@var{variable}}
4012 set to the absolute name of the candidate program. If no invocation of
4013 @var{feature-test} sets the shell variable
4014 @code{$ac_cv_path_@var{variable}}, then @var{action-if-not-found} is
4015 executed. @var{feature-test} will be run even when
4016 @code{ac_cv_path_@var{variable}} is set, to provide the ability to
4017 choose a better candidate found later in @var{path}; to accept the
4018 current setting and bypass all futher checks, @var{feature-test} can
4019 execute @code{ac_path_@var{variable}_found=:}.
4021 Note that this macro has some subtle differences from
4022 @code{AC_CHECK_PROGS}. It is designed to be run inside
4023 @code{AC_CACHE_VAL}, therefore, it should have no side effects. In
4024 particular, @var{variable} is not set to the final value of
4025 @code{ac_cv_path_@var{variable}}, nor is @code{AC_SUBST} automatically
4026 run. Also, on failure, any action can be performed, whereas
4027 @code{AC_CHECK_PROGS} only performs
4028 @code{@var{variable}=@var{value-if-not-found}}.
4030 Here is an example, similar to what Autoconf uses in its own configure
4031 script. It will search for an implementation of @command{m4} that
4032 supports the @code{indir} builtin, even if it goes by the name
4033 @command{gm4} or is not the first implementation on @env{PATH}.
4036 AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4],
4037 [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4],
4038 [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4`
4039 test "x$m4out" = x0 \
4040 && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]],
4041 [AC_MSG_ERROR([could not find m4 that supports indir])])])
4042 AC_SUBST([M4], [$ac_cv_path_M4])
4046 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @
4047 @ovar{value-if-not-found}, @dvar{path, $PATH})
4048 @acindex{PATH_TARGET_TOOL}
4049 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
4050 name of the program if it is found.
4053 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @
4054 @ovar{value-if-not-found}, @dvar{path, $PATH})
4056 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
4057 name of the program if it is found.
4059 In the future, when cross-compiling this macro will @emph{not}
4060 accept program names that are not prefixed with the host type.
4066 @cindex File, checking
4068 You might also need to check for the existence of files. Before using
4069 these macros, ask yourself whether a runtime test might not be a better
4070 solution. Be aware that, like most Autoconf macros, they test a feature
4071 of the host machine, and therefore, they die when cross-compiling.
4073 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @
4074 @ovar{action-if-not-found})
4075 @acindex{CHECK_FILE}
4076 Check whether file @var{file} exists on the native system. If it is
4077 found, execute @var{action-if-found}, otherwise do
4078 @var{action-if-not-found}, if given.
4081 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @
4082 @ovar{action-if-not-found})
4083 @acindex{CHECK_FILES}
4084 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
4085 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
4086 for each file found.
4091 @section Library Files
4092 @cindex Library, checking
4094 The following macros check for the presence of certain C, C++, or Fortran
4095 library archive files.
4097 @anchor{AC_CHECK_LIB}
4098 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @
4099 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4101 Test whether the library @var{library} is available by trying to link
4102 a test program that calls function @var{function} with the library.
4103 @var{function} should be a function provided by the library.
4105 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4106 the @var{library} argument.
4108 @var{action-if-found} is a list of shell commands to run if the link
4109 with the library succeeds; @var{action-if-not-found} is a list of shell
4110 commands to run if the link fails. If @var{action-if-found} is not
4111 specified, the default action prepends @option{-l@var{library}} to
4112 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4113 capitals). This macro is intended to support building @code{LIBS} in
4114 a right-to-left (least-dependent to most-dependent) fashion such that
4115 library dependencies are satisfied as a natural side effect of
4116 consecutive tests. Linkers are sensitive to library ordering
4117 so the order in which @code{LIBS} is generated is important to reliable
4118 detection of libraries.
4120 If linking with @var{library} results in unresolved symbols that would
4121 be resolved by linking with additional libraries, give those libraries
4122 as the @var{other-libraries} argument, separated by spaces:
4123 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4124 that @var{library} is present, because linking the test program
4125 always fails with unresolved symbols. The @var{other-libraries} argument
4126 should be limited to cases where it is desirable to test for one library
4127 in the presence of another that is not already in @code{LIBS}.
4129 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4130 in some common cases. Many standard functions like @code{gethostbyname}
4131 appear in the standard C library on some hosts, and in special libraries
4132 like @code{nsl} on other hosts. On some hosts the special libraries
4133 contain variant implementations that you may not want to use. These
4134 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4135 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4138 @anchor{AC_SEARCH_LIBS}
4139 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @
4140 @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4141 @acindex{SEARCH_LIBS}
4142 Search for a library defining @var{function} if it's not already
4143 available. This equates to calling
4144 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4145 no libraries, then for each library listed in @var{search-libs}.
4147 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4148 to contain @var{function}, and run @var{action-if-found}. If the
4149 function is not found, run @var{action-if-not-found}.
4151 If linking with @var{library} results in unresolved symbols that would
4152 be resolved by linking with additional libraries, give those libraries
4153 as the @var{other-libraries} argument, separated by spaces:
4154 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4155 that @var{function} is present, because linking the test program
4156 always fails with unresolved symbols.
4161 @node Library Functions
4162 @section Library Functions
4164 The following macros check for particular C library functions.
4165 If there is no macro specifically defined to check for a function you need,
4166 and you don't need to check for any special properties of
4167 it, then you can use one of the general function-check macros.
4170 * Function Portability:: Pitfalls with usual functions
4171 * Particular Functions:: Special handling to find certain functions
4172 * Generic Functions:: How to find other functions
4175 @node Function Portability
4176 @subsection Portability of C Functions
4177 @cindex Portability of C functions
4178 @cindex C function portability
4180 Most usual functions can either be missing, or be buggy, or be limited
4181 on some architectures. This section tries to make an inventory of these
4182 portability issues. By definition, this list always requires
4183 additions. Please help us keeping it as complete as possible.
4188 @prindex @code{exit}
4189 On ancient hosts, @code{exit} returned @code{int}.
4190 This is because @code{exit} predates @code{void}, and there was a long
4191 tradition of it returning @code{int}.
4193 On current hosts, the problem more likely is that @code{exit} is not
4194 declared, due to C++ problems of some sort or another. For this reason
4195 we suggest that test programs not invoke @code{exit}, but return from
4196 @code{main} instead.
4200 @prindex @code{free}
4201 The C standard says a call @code{free (NULL)} does nothing, but
4202 some old systems don't support this (e.g., NextStep).
4208 @prindex @code{isinf}
4209 @prindex @code{isnan}
4210 The C99 standard says that @code{isinf} and @code{isnan} are
4211 macros. On some systems just macros are available
4212 (e.g., @acronym{HP-UX} and Solaris 10), on
4213 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4214 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4215 these functions are declared in nonstandard headers like
4216 @code{<sunmath.h>} and defined in non-default libraries like
4217 @option{-lm} or @option{-lsunmath}.
4219 The C99 @code{isinf} and @code{isnan} macros work correctly with
4220 @code{long double} arguments, but pre-C99 systems that use functions
4221 typically assume @code{double} arguments. On such a system,
4222 @code{isinf} incorrectly returns true for a finite @code{long double}
4223 argument that is outside the range of @code{double}.
4225 To work around this porting mess, you can use code like the following.
4232 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4233 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4235 static inline int isnan_f (float x) @{ return x != x; @}
4236 static inline int isnan_d (double x) @{ return x != x; @}
4237 static inline int isnan_ld (long double x) @{ return x != x; @}
4242 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4243 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4245 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4246 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4247 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4251 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4252 compilers that lack the @code{inline} keyword. Some optimizing
4253 compilers mishandle these definitions, but systems with that bug
4254 typically have missing or broken @code{isnan} functions anyway, so it's
4255 probably not worth worrying about.
4259 @prindex @code{malloc}
4260 The C standard says a call @code{malloc (0)} is implementation
4261 dependent. It can return either @code{NULL} or a new non-null pointer.
4262 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4263 no means universal. @code{AC_FUNC_MALLOC}
4264 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4268 @prindex @code{putenv}
4269 Posix prefers @code{setenv} to @code{putenv}; among other things,
4270 @code{putenv} is not required of all Posix implementations, but
4273 Posix specifies that @code{putenv} puts the given string directly in
4274 @code{environ}, but some systems make a copy of it instead (e.g.,
4275 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4276 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4278 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4279 environment, but this is not standard usage and it dumps core
4280 on some systems (e.g., AIX).
4282 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4283 environment, rather than inserting it with an empty value.
4285 @item @code{realloc}
4287 @prindex @code{realloc}
4288 The C standard says a call @code{realloc (NULL, size)} is equivalent
4289 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4292 @item @code{signal} handler
4294 @prindex @code{signal}
4295 Normally @code{signal} takes a handler function with a return type of
4296 @code{void}, but some old systems required @code{int} instead. Any
4297 actual @code{int} value returned is not used; this is only a
4298 difference in the function prototype demanded.
4300 All systems we know of in current use return @code{void}. The
4301 @code{int} was to support K&R C, where of course @code{void} is not
4302 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4303 used to establish the correct type in all cases.
4305 @item @code{snprintf}
4306 @c @fuindex snprintf
4307 @prindex @code{snprintf}
4308 @c @fuindex vsnprintf
4309 @prindex @code{vsnprintf}
4310 The C99 standard says that if the output array isn't big enough
4311 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4312 truncate the output and return the number of bytes that ought to have
4313 been produced. Some older systems return the truncated length (e.g.,
4314 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4315 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4316 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4317 older systems ignore the length and overrun the buffer (e.g., 64-bit
4320 @item @code{sprintf}
4322 @prindex @code{sprintf}
4323 @c @fuindex vsprintf
4324 @prindex @code{vsprintf}
4325 The C standard says @code{sprintf} and @code{vsprintf} return the
4326 number of bytes written. On some ancient systems (SunOS 4 for
4327 instance) they return the buffer pointer instead, but these no
4328 longer need to be worried about.
4332 @prindex @code{sscanf}
4333 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires
4335 input string be writable (though it doesn't actually change it). This
4336 can be a problem when using @command{gcc} since it normally puts
4337 constant strings in read-only memory (@pxref{Incompatibilities,
4338 Incompatibilities of @acronym{GCC}, , gcc, Using and
4339 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4340 having format strings read-only can be a problem.
4342 @item @code{strerror_r}
4343 @c @fuindex strerror_r
4344 @prindex @code{strerror_r}
4345 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4346 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4347 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4348 can detect which is in use (@pxref{Particular Functions}).
4350 @item @code{strnlen}
4352 @prindex @code{strnlen}
4353 @acronym{AIX} 4.3 provides a broken version which produces the
4357 strnlen ("foobar", 0) = 0
4358 strnlen ("foobar", 1) = 3
4359 strnlen ("foobar", 2) = 2
4360 strnlen ("foobar", 3) = 1
4361 strnlen ("foobar", 4) = 0
4362 strnlen ("foobar", 5) = 6
4363 strnlen ("foobar", 6) = 6
4364 strnlen ("foobar", 7) = 6
4365 strnlen ("foobar", 8) = 6
4366 strnlen ("foobar", 9) = 6
4369 @item @code{sysconf}
4371 @prindex @code{sysconf}
4372 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4373 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4378 @prindex @code{unlink}
4379 The Posix spec says that @code{unlink} causes the given file to be
4380 removed only after there are no more open file handles for it. Some
4381 non-Posix hosts have trouble with this requirement, though,
4382 and some @acronym{DOS} variants even corrupt the file system.
4384 @item @code{unsetenv}
4385 @c @fuindex unsetenv
4386 @prindex @code{unsetenv}
4387 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4388 can be removed with a call @code{putenv ("FOO=")}, as described under
4389 @code{putenv} above.
4391 @item @code{va_copy}
4393 @prindex @code{va_copy}
4394 The C99 standard provides @code{va_copy} for copying
4395 @code{va_list} variables. It may be available in older environments
4396 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4397 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4398 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4401 @item @code{va_list}
4403 @prindex @code{va_list}
4404 @code{va_list} is not necessarily just a pointer. It can be a
4405 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4406 not portable. Or it can be an array (e.g., @command{gcc} in some
4407 PowerPC configurations), which means as a function parameter it can be
4408 effectively call-by-reference and library routines might modify the
4409 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4412 @item Signed @code{>>}
4413 Normally the C @code{>>} right shift of a signed type replicates the
4414 high bit, giving a so-called ``arithmetic'' shift. But care should be
4415 taken since Standard C doesn't require that behavior. On those
4416 few processors without a native arithmetic shift (for instance Cray
4417 vector systems) zero bits may be shifted in, the same as a shift of an
4420 @item Integer @code{/}
4421 C divides signed integers by truncating their quotient toward zero,
4422 yielding the same result as Fortran. However, before C99 the standard
4423 allowed C implementations to take the floor or ceiling of the quotient
4424 in some cases. Hardly any implementations took advantage of this
4425 freedom, though, and it's probably not worth worrying about this issue
4430 @node Particular Functions
4431 @subsection Particular Function Checks
4432 @cindex Function, checking
4434 These macros check for particular C functions---whether they exist, and
4435 in some cases how they respond when given certain arguments.
4437 @anchor{AC_FUNC_ALLOCA}
4438 @defmac AC_FUNC_ALLOCA
4439 @acindex{FUNC_ALLOCA}
4441 @cvindex HAVE_ALLOCA_H
4444 @prindex @code{alloca}
4446 Check how to get @code{alloca}. Tries to get a builtin version by
4447 checking for @file{alloca.h} or the predefined C preprocessor macros
4448 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4449 it defines @code{HAVE_ALLOCA_H}.
4451 If those attempts fail, it looks for the function in the standard C
4452 library. If any of those methods succeed, it defines
4453 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4454 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4455 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4456 garbage collect). This variable is separate from @code{LIBOBJS} so
4457 multiple programs can share the value of @code{ALLOCA} without needing
4458 to create an actual library, in case only some of them use the code in
4459 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4460 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4462 This macro does not try to get @code{alloca} from the System V R3
4463 @file{libPW} or the System V R4 @file{libucb} because those libraries
4464 contain some incompatible functions that cause trouble. Some versions
4465 do not even contain @code{alloca} or contain a buggy version. If you
4466 still want to use their @code{alloca}, use @code{ar} to extract
4467 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4469 Source files that use @code{alloca} should start with a piece of code
4470 like the following, to declare it properly.
4474 #ifdef HAVE_ALLOCA_H
4475 # include <alloca.h>
4476 #elif defined __GNUC__
4477 # define alloca __builtin_alloca
4479 # define alloca __alloca
4480 #elif defined _MSC_VER
4481 # include <malloc.h>
4482 # define alloca _alloca
4484 # include <stddef.h>
4488 void *alloca (size_t);
4494 @defmac AC_FUNC_CHOWN
4495 @acindex{FUNC_CHOWN}
4498 @prindex @code{chown}
4499 If the @code{chown} function is available and works (in particular, it
4500 should accept @option{-1} for @code{uid} and @code{gid}), define
4504 @anchor{AC_FUNC_CLOSEDIR_VOID}
4505 @defmac AC_FUNC_CLOSEDIR_VOID
4506 @acindex{FUNC_CLOSEDIR_VOID}
4507 @cvindex CLOSEDIR_VOID
4508 @c @fuindex closedir
4509 @prindex @code{closedir}
4510 If the @code{closedir} function does not return a meaningful value,
4511 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4512 return value for an error indicator.
4514 Currently this test is implemented by running a test program. When
4515 cross compiling the pessimistic assumption that @code{closedir} does not
4516 return a meaningful value is made.
4518 This macro is obsolescent, as @code{closedir} returns a meaningful value
4519 on current systems. New programs need not use this macro.
4522 @defmac AC_FUNC_ERROR_AT_LINE
4523 @acindex{FUNC_ERROR_AT_LINE}
4524 @c @fuindex error_at_line
4525 @prindex @code{error_at_line}
4526 If the @code{error_at_line} function is not found, require an
4527 @code{AC_LIBOBJ} replacement of @samp{error}.
4530 @defmac AC_FUNC_FNMATCH
4531 @acindex{FUNC_FNMATCH}
4533 @prindex @code{fnmatch}
4534 If the @code{fnmatch} function conforms to Posix, define
4535 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4536 the bugs in Solaris 2.4.
4538 Unlike the other specific
4539 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4540 broken/missing @code{fnmatch}. This is for historical reasons.
4541 See @code{AC_REPLACE_FNMATCH} below.
4543 This macro is obsolescent. New programs should use Gnulib's
4544 @code{fnmatch-posix} module. @xref{Gnulib}.
4547 @defmac AC_FUNC_FNMATCH_GNU
4548 @acindex{FUNC_FNMATCH_GNU}
4550 @prindex @code{fnmatch}
4551 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4552 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4553 implementation bugs, for example, the bugs in the @acronym{GNU} C
4556 This macro is obsolescent. New programs should use Gnulib's
4557 @code{fnmatch-gnu} module. @xref{Gnulib}.
4560 @anchor{AC_FUNC_FORK}
4561 @defmac AC_FUNC_FORK
4563 @cvindex HAVE_VFORK_H
4564 @cvindex HAVE_WORKING_FORK
4565 @cvindex HAVE_WORKING_VFORK
4568 @prindex @code{fork}
4570 @prindex @code{vfork}
4572 This macro checks for the @code{fork} and @code{vfork} functions. If a
4573 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4574 checks whether @code{fork} is just a stub by trying to run it.
4576 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4577 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4578 define @code{vfork} to be @code{fork} for backward compatibility with
4579 previous versions of @command{autoconf}. This macro checks for several known
4580 errors in implementations of @code{vfork} and considers the system to not
4581 have a working @code{vfork} if it detects any of them. It is not considered
4582 to be an implementation error if a child's invocation of @code{signal}
4583 modifies the parent's signal handler, since child processes rarely change
4584 their signal handlers.
4586 Since this macro defines @code{vfork} only for backward compatibility with
4587 previous versions of @command{autoconf} you're encouraged to define it
4588 yourself in new code:
4591 #ifndef HAVE_WORKING_VFORK
4598 @defmac AC_FUNC_FSEEKO
4599 @acindex{FUNC_FSEEKO}
4600 @cvindex _LARGEFILE_SOURCE
4601 @cvindex HAVE_FSEEKO
4603 @prindex @code{fseeko}
4604 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4605 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4606 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4607 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4608 largefile-sensitive systems where @code{off_t} does not default to a
4612 @defmac AC_FUNC_GETGROUPS
4613 @acindex{FUNC_GETGROUPS}
4614 @cvindex HAVE_GETGROUPS
4615 @ovindex GETGROUPS_LIBS
4616 @c @fuindex getgroups
4617 @prindex @code{getgroups}
4618 If the @code{getgroups} function is available and works (unlike on
4619 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4620 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4621 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4624 @anchor{AC_FUNC_GETLOADAVG}
4625 @defmac AC_FUNC_GETLOADAVG
4626 @acindex{FUNC_GETLOADAVG}
4631 @cvindex HAVE_NLIST_H
4632 @cvindex NLIST_NAME_UNION
4633 @cvindex GETLOADAVG_PRIVILEGED
4634 @cvindex NEED_SETGID
4635 @cvindex C_GETLOADAVG
4637 @ovindex NEED_SETGID
4639 @ovindex GETLOADAVG_LIBS
4640 @c @fuindex getloadavg
4641 @prindex @code{getloadavg}
4642 Check how to get the system load averages. To perform its tests
4643 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4644 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4645 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4647 If the system has the @code{getloadavg} function, define
4648 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4649 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4650 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4651 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4652 possibly define several other C preprocessor macros and output
4657 Define @code{C_GETLOADAVG}.
4660 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4665 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4668 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4669 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4670 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4673 Programs may need to be installed set-group-ID (or set-user-ID) for
4674 @code{getloadavg} to work. In this case, define
4675 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4676 to @samp{true} (and otherwise to @samp{false}), and set
4677 @code{KMEM_GROUP} to the name of the group that should own the installed
4681 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
4682 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
4685 @anchor{AC_FUNC_GETMNTENT}
4686 @defmac AC_FUNC_GETMNTENT
4687 @acindex{FUNC_GETMNTENT}
4688 @cvindex HAVE_GETMNTENT
4689 @c @fuindex getmntent
4690 @prindex @code{getmntent}
4691 Check for @code{getmntent} in the standard C library, and then in the
4692 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4693 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4694 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4697 @defmac AC_FUNC_GETPGRP
4698 @acindex{FUNC_GETPGRP}
4699 @cvindex GETPGRP_VOID
4702 @prindex @code{getpgid}
4703 @prindex @code{getpgrp}
4704 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4705 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4706 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4707 behaves like Posix's @code{getpgid}.
4717 This macro does not check whether
4718 @code{getpgrp} exists at all; if you need to work in that situation,
4719 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4721 This macro is obsolescent, as current systems have a @code{getpgrp}
4722 whose signature conforms to Posix. New programs need not use this macro.
4725 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4726 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4727 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4729 @prindex @code{lstat}
4730 If @file{link} is a symbolic link, then @code{lstat} should treat
4731 @file{link/} the same as @file{link/.}. However, many older
4732 @code{lstat} implementations incorrectly ignore trailing slashes.
4734 It is safe to assume that if @code{lstat} incorrectly ignores
4735 trailing slashes, then other symbolic-link-aware functions like
4736 @code{unlink} also incorrectly ignore trailing slashes.
4738 If @code{lstat} behaves properly, define
4739 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4740 @code{AC_LIBOBJ} replacement of @code{lstat}.
4743 @defmac AC_FUNC_MALLOC
4744 @acindex{FUNC_MALLOC}
4745 @cvindex HAVE_MALLOC
4748 @prindex @code{malloc}
4749 If the @code{malloc} function is compatible with the @acronym{GNU} C
4750 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4751 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4752 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4753 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4754 native @code{malloc} is not used in the main project.
4756 Typically, the replacement file @file{malloc.c} should look like (note
4757 the @samp{#undef malloc}):
4760 #ifdef HAVE_CONFIG_H
4761 # include <config.h>
4765 #include <sys/types.h>
4769 /* Allocate an N-byte block of memory from the heap.
4770 If N is zero, allocate a 1-byte block. */
4773 rpl_malloc (size_t n)
4782 @defmac AC_FUNC_MEMCMP
4783 @acindex{FUNC_MEMCMP}
4786 @prindex @code{memcmp}
4787 If the @code{memcmp} function is not available, or does not work on
4788 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4789 bytes or more and with at least one buffer not starting on a 4-byte
4790 boundary (such as the one on NeXT x86 OpenStep), require an
4791 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4793 This macro is obsolescent, as current systems have a working
4794 @code{memcmp}. New programs need not use this macro.
4797 @defmac AC_FUNC_MBRTOWC
4798 @acindex{FUNC_MBRTOWC}
4799 @cvindex HAVE_MBRTOWC
4801 @prindex @code{mbrtowc}
4802 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4803 type @code{mbstate_t} are properly declared.
4806 @defmac AC_FUNC_MKTIME
4807 @acindex{FUNC_MKTIME}
4810 @prindex @code{mktime}
4811 If the @code{mktime} function is not available, or does not work
4812 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4813 For the purposes of this test, @code{mktime} should conform to the
4814 Posix standard and should be the inverse of
4818 @anchor{AC_FUNC_MMAP}
4819 @defmac AC_FUNC_MMAP
4823 @prindex @code{mmap}
4824 If the @code{mmap} function exists and works correctly, define
4825 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4829 @defmac AC_FUNC_OBSTACK
4830 @acindex{FUNC_OBSTACK}
4831 @cvindex HAVE_OBSTACK
4833 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4834 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4837 @defmac AC_FUNC_REALLOC
4838 @acindex{FUNC_REALLOC}
4839 @cvindex HAVE_REALLOC
4842 @prindex @code{realloc}
4843 If the @code{realloc} function is compatible with the @acronym{GNU} C
4844 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4845 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4846 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4847 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4848 the native @code{realloc} is not used in the main project. See
4849 @code{AC_FUNC_MALLOC} for details.
4852 @defmac AC_FUNC_SELECT_ARGTYPES
4853 @acindex{FUNC_SELECT_ARGTYPES}
4854 @cvindex SELECT_TYPE_ARG1
4855 @cvindex SELECT_TYPE_ARG234
4856 @cvindex SELECT_TYPE_ARG5
4858 @prindex @code{select}
4859 Determines the correct type to be passed for each of the
4860 @code{select} function's arguments, and defines those types
4861 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4862 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4863 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4864 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4866 This macro is obsolescent, as current systems have a @code{select} whose
4867 signature conforms to Posix. New programs need not use this macro.
4870 @defmac AC_FUNC_SETPGRP
4871 @acindex{FUNC_SETPGRP}
4872 @cvindex SETPGRP_VOID
4874 @prindex @code{setpgrp}
4875 If @code{setpgrp} takes no argument (the Posix version), define
4876 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4877 two process IDs as arguments. This macro does not check whether
4878 @code{setpgrp} exists at all; if you need to work in that situation,
4879 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4881 This macro is obsolescent, as current systems have a @code{setpgrp}
4882 whose signature conforms to Posix. New programs need not use this macro.
4885 @defmac AC_FUNC_STAT
4886 @defmacx AC_FUNC_LSTAT
4888 @acindex{FUNC_LSTAT}
4889 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4890 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4892 @prindex @code{stat}
4894 @prindex @code{lstat}
4895 Determine whether @code{stat} or @code{lstat} have the bug that it
4896 succeeds when given the zero-length file name as argument. The @code{stat}
4897 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4900 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4901 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4904 These macros are obsolescent, as no current systems have the bug.
4905 New programs need not use these macros.
4908 @anchor{AC_FUNC_STRCOLL}
4909 @defmac AC_FUNC_STRCOLL
4910 @acindex{FUNC_STRCOLL}
4911 @cvindex HAVE_STRCOLL
4913 @prindex @code{strcoll}
4914 If the @code{strcoll} function exists and works correctly, define
4915 @code{HAVE_STRCOLL}. This does a bit more than
4916 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4917 definitions of @code{strcoll} that should not be used.
4920 @defmac AC_FUNC_STRERROR_R
4921 @acindex{FUNC_STRERROR_R}
4922 @cvindex HAVE_STRERROR_R
4923 @cvindex HAVE_DECL_STRERROR_R
4924 @cvindex STRERROR_R_CHAR_P
4925 @c @fuindex strerror_r
4926 @prindex @code{strerror_r}
4927 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4928 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4929 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4930 returns an @code{int} error number. The Thread-Safe Functions option of
4931 Posix requires @code{strerror_r} to return @code{int}, but
4932 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4933 Library) return a @code{char *} value that is not necessarily equal to
4934 the buffer argument.
4937 @anchor{AC_FUNC_STRFTIME}
4938 @defmac AC_FUNC_STRFTIME
4939 @acindex{FUNC_STRFTIME}
4940 @cvindex HAVE_STRFTIME
4941 @c @fuindex strftime
4942 @prindex @code{strftime}
4943 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4944 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4946 This macro is obsolescent, as no current systems require the @file{intl}
4947 library for @code{strftime}. New programs need not use this macro.
4950 @defmac AC_FUNC_STRTOD
4951 @acindex{FUNC_STRTOD}
4954 @prindex @code{strtod}
4955 If the @code{strtod} function does not exist or doesn't work correctly,
4956 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4957 because @file{strtod.c} is likely to need @samp{pow}, set the output
4958 variable @code{POW_LIB} to the extra library needed.
4961 @defmac AC_FUNC_STRTOLD
4962 @acindex{FUNC_STRTOLD}
4963 @cvindex HAVE_STRTOLD
4964 @prindex @code{strtold}
4965 If the @code{strtold} function exists and conforms to C99, define
4966 @code{HAVE_STRTOLD}.
4969 @defmac AC_FUNC_STRNLEN
4970 @acindex{FUNC_STRNLEN}
4971 @cvindex HAVE_STRNLEN
4973 @prindex @code{strnlen}
4974 If the @code{strnlen} function is not available, or is buggy (like the one
4975 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4978 @anchor{AC_FUNC_UTIME_NULL}
4979 @defmac AC_FUNC_UTIME_NULL
4980 @acindex{FUNC_UTIME_NULL}
4981 @cvindex HAVE_UTIME_NULL
4983 @prindex @code{utime}
4984 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4985 the present, define @code{HAVE_UTIME_NULL}.
4987 This macro is obsolescent, as all current systems have a @code{utime}
4988 that behaves this way. New programs need not use this macro.
4991 @anchor{AC_FUNC_VPRINTF}
4992 @defmac AC_FUNC_VPRINTF
4993 @acindex{FUNC_VPRINTF}
4994 @cvindex HAVE_VPRINTF
4995 @cvindex HAVE_DOPRNT
4997 @prindex @code{vprintf}
4998 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4999 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
5000 is available, you may assume that @code{vfprintf} and @code{vsprintf}
5001 are also available.)
5003 This macro is obsolescent, as all current systems have @code{vprintf}.
5004 New programs need not use this macro.
5007 @defmac AC_REPLACE_FNMATCH
5008 @acindex{REPLACE_FNMATCH}
5010 @prindex @code{fnmatch}
5011 @hdrindex{fnmatch.h}
5012 If the @code{fnmatch} function does not conform to Posix (see
5013 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
5015 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
5016 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
5017 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
5018 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
5019 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
5020 included in place of the system @code{<fnmatch.h>}.
5022 This macro is obsolescent, as it assumes the use of particular source
5023 files. New programs should use Gnulib's @code{fnmatch-posix} module,
5024 which provides this macro along with the source files. @xref{Gnulib}.
5029 @node Generic Functions
5030 @subsection Generic Function Checks
5032 These macros are used to find functions not covered by the ``particular''
5033 test macros. If the functions might be in libraries other than the
5034 default C library, first call @code{AC_CHECK_LIB} for those libraries.
5035 If you need to check the behavior of a function as well as find out
5036 whether it is present, you have to write your own test for
5037 it (@pxref{Writing Tests}).
5039 @anchor{AC_CHECK_FUNC}
5040 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @
5041 @ovar{action-if-not-found})
5042 @acindex{CHECK_FUNC}
5043 If C function @var{function} is available, run shell commands
5044 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
5045 want to define a symbol if the function is available, consider using
5046 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
5047 linkage even when @code{AC_LANG(C++)} has been called, since C is more
5048 standardized than C++. (@pxref{Language Choice}, for more information
5049 about selecting the language for checks.)
5052 @anchor{AC_CHECK_FUNCS}
5053 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @
5054 @ovar{action-if-not-found})
5055 @acindex{CHECK_FUNCS}
5056 @cvindex HAVE_@var{function}
5057 For each @var{function} enumerated in the blank-or-newline-separated argument
5058 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5059 If @var{action-if-found} is given, it is additional shell code to
5060 execute when one of the functions is found. You can give it a value of
5061 @samp{break} to break out of the loop on the first match. If
5062 @var{action-if-not-found} is given, it is executed when one of the
5063 functions is not found.
5066 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
5067 @acindex{CHECK_FUNCS_ONCE}
5068 @cvindex HAVE_@var{function}
5069 For each @var{function} enumerated in the blank-or-newline-separated argument
5070 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
5071 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
5072 checking code at most once, so that @command{configure} is smaller and
5073 faster; but the checks cannot be conditionalized and are always done once,
5074 early during the @command{configure} run.
5079 Autoconf follows a philosophy that was formed over the years by those
5080 who have struggled for portability: isolate the portability issues in
5081 specific files, and then program as if you were in a Posix
5082 environment. Some functions may be missing or unfixable, and your
5083 package must be ready to replace them.
5085 Suitable replacements for many such problem functions are available from
5086 Gnulib (@pxref{Gnulib}).
5088 @defmac AC_LIBOBJ (@var{function})
5091 Specify that @samp{@var{function}.c} must be included in the executables
5092 to replace a missing or broken implementation of @var{function}.
5094 Technically, it adds @samp{@var{function}.$ac_objext} to the output
5095 variable @code{LIBOBJS} if it is not already in, and calls
5096 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
5097 directly change @code{LIBOBJS}, since this is not traceable.
5100 @defmac AC_LIBSOURCE (@var{file})
5102 Specify that @var{file} might be needed to compile the project. If you
5103 need to know what files might be needed by a @file{configure.ac}, you
5104 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
5106 This macro is called automatically from @code{AC_LIBOBJ}, but you must
5107 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
5108 that case, since shell variables cannot be traced statically, you must
5109 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
5110 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
5111 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
5112 @code{"foo"} or @code{"bar"}, you should do:
5115 AC_LIBSOURCE([foo.c])
5116 AC_LIBSOURCE([bar.c])
5117 AC_LIBOBJ([$foo_or_bar])
5121 There is usually a way to avoid this, however, and you are encouraged to
5122 simply call @code{AC_LIBOBJ} with literal arguments.
5124 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5125 slightly different semantics: the old macro took the function name,
5126 e.g., @code{foo}, as its argument rather than the file name.
5129 @defmac AC_LIBSOURCES (@var{files})
5130 @acindex{LIBSOURCES}
5131 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5132 comma-separated M4 list. Thus, the above example might be rewritten:
5135 AC_LIBSOURCES([foo.c, bar.c])
5136 AC_LIBOBJ([$foo_or_bar])
5140 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5141 @acindex{CONFIG_LIBOBJ_DIR}
5142 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5143 @var{directory}, a name relative to the top level of the
5144 source tree. The replacement directory defaults to @file{.}, the top
5145 level directory, and the most typical value is @file{lib}, corresponding
5146 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5148 @command{configure} might need to know the replacement directory for the
5149 following reasons: (i) some checks use the replacement files, (ii) some
5150 macros bypass broken system headers by installing links to the
5151 replacement headers (iii) when used in conjunction with Automake,
5152 within each makefile, @var{directory} is used as a relative path
5153 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5154 @code{LTLIBOBJS}, etc.
5159 It is common to merely check for the existence of a function, and ask
5160 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5161 a convenient shorthand.
5163 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5164 @acindex{REPLACE_FUNCS}
5165 @cvindex HAVE_@var{function}
5167 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5168 @var{action-if-not-found}. You can declare your replacement function by
5169 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5170 system has the function, it probably declares it in a header file you
5171 should be including, so you shouldn't redeclare it lest your declaration
5176 @section Header Files
5177 @cindex Header, checking
5179 The following macros check for the presence of certain C header files.
5180 If there is no macro specifically defined to check for a header file you need,
5181 and you don't need to check for any special properties of
5182 it, then you can use one of the general header-file check macros.
5185 * Header Portability:: Collected knowledge on common headers
5186 * Particular Headers:: Special handling to find certain headers
5187 * Generic Headers:: How to find other headers
5190 @node Header Portability
5191 @subsection Portability of Headers
5192 @cindex Portability of headers
5193 @cindex Header portability
5195 This section tries to collect knowledge about common headers, and the
5196 problems they cause. By definition, this list always requires
5197 additions. Please help us keeping it as complete as possible.
5201 @item @file{limits.h}
5202 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5203 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5204 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5207 @item @file{inttypes.h} vs.@: @file{stdint.h}
5208 @hdrindex{inttypes.h}
5210 The C99 standard says that @file{inttypes.h} includes
5211 @file{stdint.h}, so there's no need to include @file{stdint.h}
5212 separately in a standard environment. Some implementations have
5213 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5214 know of any implementation that has @file{stdint.h} but not
5217 @item @file{linux/irda.h}
5218 @hdrindex{linux/irda.h}
5219 It requires @file{linux/types.h} and @file{sys/socket.h}.
5221 @item @file{linux/random.h}
5222 @hdrindex{linux/random.h}
5223 It requires @file{linux/types.h}.
5225 @item @file{net/if.h}
5227 On Darwin, this file requires that @file{sys/socket.h} be included
5228 beforehand. One should run:
5231 AC_CHECK_HEADERS([sys/socket.h])
5232 AC_CHECK_HEADERS([net/if.h], [], [],
5235 # include <stdlib.h>
5236 # include <stddef.h>
5238 # ifdef HAVE_STDLIB_H
5239 # include <stdlib.h>
5242 #ifdef HAVE_SYS_SOCKET_H
5243 # include <sys/socket.h>
5248 @item @file{netinet/if_ether.h}
5249 @hdrindex{netinet/if_ether.h}
5250 On Darwin, this file requires that @file{stdio.h} and
5251 @file{sys/socket.h} be included beforehand. One should run:
5254 AC_CHECK_HEADERS([sys/socket.h])
5255 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5258 # include <stdlib.h>
5259 # include <stddef.h>
5261 # ifdef HAVE_STDLIB_H
5262 # include <stdlib.h>
5265 #ifdef HAVE_SYS_SOCKET_H
5266 # include <sys/socket.h>
5271 @item @file{stdint.h}
5272 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5274 @item @file{stdlib.h}
5276 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5278 @item @file{sys/mount.h}
5279 @hdrindex{sys/mount.h}
5280 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5281 @file{sys/params.h} is a prerequisite.
5283 @item @file{sys/ptem.h}
5284 @hdrindex{sys/ptem.h}
5285 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5287 @item @file{sys/socket.h}
5288 @hdrindex{sys/socket.h}
5289 On Darwin, @file{stdlib.h} is a prerequisite.
5291 @item @file{sys/ucred.h}
5292 @hdrindex{sys/ucred.h}
5293 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5295 @item @file{X11/extensions/scrnsaver.h}
5296 @hdrindex{X11/extensions/scrnsaver.h}
5297 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5298 so required that you might not even consider looking for it.
5301 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5302 [[#include <X11/Xlib.h>
5308 @node Particular Headers
5309 @subsection Particular Header Checks
5311 These macros check for particular system header files---whether they
5312 exist, and in some cases whether they declare certain symbols.
5314 @defmac AC_HEADER_ASSERT
5315 @acindex{HEADER_ASSERT}
5318 Check whether to enable assertions in the style of @file{assert.h}.
5319 Assertions are enabled by default, but the user can override this by
5320 invoking @command{configure} with the @option{--disable-assert} option.
5323 @anchor{AC_HEADER_DIRENT}
5324 @defmac AC_HEADER_DIRENT
5325 @acindex{HEADER_DIRENT}
5326 @cvindex HAVE_DIRENT_H
5327 @cvindex HAVE_NDIR_H
5328 @cvindex HAVE_SYS_DIR_H
5329 @cvindex HAVE_SYS_NDIR_H
5331 @hdrindex{sys/ndir.h}
5332 @hdrindex{sys/dir.h}
5334 Check for the following header files. For the first one that is
5335 found and defines @samp{DIR}, define the listed C preprocessor macro:
5337 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5338 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5339 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5340 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5341 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5344 The directory-library declarations in your source code should look
5345 something like the following:
5349 #include <sys/types.h>
5350 #ifdef HAVE_DIRENT_H
5351 # include <dirent.h>
5352 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5354 # define dirent direct
5355 # define NAMLEN(dirent) ((dirent)->d_namlen)
5356 # ifdef HAVE_SYS_NDIR_H
5357 # include <sys/ndir.h>
5359 # ifdef HAVE_SYS_DIR_H
5360 # include <sys/dir.h>
5369 Using the above declarations, the program would declare variables to be
5370 of type @code{struct dirent}, not @code{struct direct}, and would access
5371 the length of a directory entry name by passing a pointer to a
5372 @code{struct dirent} to the @code{NAMLEN} macro.
5374 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5376 This macro is obsolescent, as all current systems with directory
5377 libraries have @code{<dirent.h>}. New programs need not use this macro.
5379 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5380 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5383 @anchor{AC_HEADER_MAJOR}
5384 @defmac AC_HEADER_MAJOR
5385 @acindex{HEADER_MAJOR}
5386 @cvindex MAJOR_IN_MKDEV
5387 @cvindex MAJOR_IN_SYSMACROS
5388 @hdrindex{sys/mkdev.h}
5389 @hdrindex{sys/sysmacros.h}
5390 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5391 @code{makedev}, but @file{sys/mkdev.h} does, define
5392 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5393 @code{MAJOR_IN_SYSMACROS}.
5396 @defmac AC_HEADER_RESOLV
5397 @acindex{HEADER_RESOLV}
5398 @cvindex HAVE_RESOLV_H
5400 Checks for header @file{resolv.h}, checking for prerequisites first.
5401 To properly use @file{resolv.h}, your code should contain something like
5405 #ifdef HAVE_SYS_TYPES_H
5406 # include <sys/types.h>
5408 #ifdef HAVE_NETINET_IN_H
5409 # include <netinet/in.h> /* inet_ functions / structs */
5411 #ifdef HAVE_ARPA_NAMESER_H
5412 # include <arpa/nameser.h> /* DNS HEADER struct */
5421 @anchor{AC_HEADER_STAT}
5422 @defmac AC_HEADER_STAT
5423 @acindex{HEADER_STAT}
5424 @cvindex STAT_MACROS_BROKEN
5425 @hdrindex{sys/stat.h}
5426 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5427 @file{sys/stat.h} do not work properly (returning false positives),
5428 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5429 Amdahl UTS and Motorola System V/88.
5431 This macro is obsolescent, as no current systems have the bug.
5432 New programs need not use this macro.
5435 @defmac AC_HEADER_STDBOOL
5436 @acindex{HEADER_STDBOOL}
5437 @cvindex HAVE_STDBOOL_H
5439 @hdrindex{stdbool.h}
5441 If @file{stdbool.h} exists and conforms to C99, define
5442 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5443 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5444 @file{system.h} could contain the following code:
5447 #ifdef HAVE_STDBOOL_H
5448 # include <stdbool.h>
5454 # define _Bool signed char
5460 # define __bool_true_false_are_defined 1
5464 Alternatively you can use the @samp{stdbool} package of Gnulib
5465 (@pxref{Gnulib}); it packages the above code into a replacement header
5466 and contains a few other bells and whistles.
5470 @anchor{AC_HEADER_STDC}
5471 @defmac AC_HEADER_STDC
5472 @acindex{HEADER_STDC}
5473 @cvindex STDC_HEADERS
5479 Define @code{STDC_HEADERS} if the system has C header files
5480 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5481 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5482 @file{string.h}, and @file{float.h}; if the system has those, it
5483 probably has the rest of the C89 header files. This macro also
5484 checks whether @file{string.h} declares @code{memchr} (and thus
5485 presumably the other @code{mem} functions), whether @file{stdlib.h}
5486 declare @code{free} (and thus presumably @code{malloc} and other related
5487 functions), and whether the @file{ctype.h} macros work on characters
5488 with the high bit set, as the C standard requires.
5490 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5491 determine whether the system has conforming header files (and probably C
5494 This macro is obsolescent, as current systems have conforming header
5495 files. New programs need not use this macro.
5498 @hdrindex{strings.h}
5499 Nowadays @file{string.h} is part of the C standard and declares functions like
5500 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5501 @acronym{BSD} functions like @code{bcopy}; but
5502 historically, string functions were a major sticking point in this area.
5503 If you still want to worry about portability to ancient systems without
5504 standard headers, there is so much variation
5505 that it is probably easier to declare the functions you use than to
5506 figure out exactly what the system header files declare. Some ancient systems
5507 contained a mix of functions from the C standard and from @acronym{BSD};
5508 some were mostly standard but lacked @samp{memmove}; some defined the
5509 @acronym{BSD} functions as macros in @file{string.h} or
5510 @file{strings.h}; some had only the @acronym{BSD} functions but
5511 @file{string.h}; some declared the memory functions in @file{memory.h},
5512 some in @file{string.h}; etc. It is probably sufficient to check for
5513 one string function and one memory function; if the library had the
5514 standard versions of those then it probably had most of the others.
5515 If you put the following in @file{configure.ac}:
5518 # This example is obsolescent.
5519 # Nowadays you can omit these macro calls.
5521 AC_CHECK_FUNCS([strchr memcpy])
5525 then, in your code, you can use declarations like this:
5529 /* This example is obsolescent.
5530 Nowadays you can just #include <string.h>. */
5532 # include <string.h>
5534 # ifndef HAVE_STRCHR
5535 # define strchr index
5536 # define strrchr rindex
5538 char *strchr (), *strrchr ();
5539 # ifndef HAVE_MEMCPY
5540 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5541 # define memmove(d, s, n) bcopy ((s), (d), (n))
5548 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5549 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5550 suffice to port to ancient hosts; you must provide an implementation of
5551 each function. An easy
5552 way to incorporate your implementations only when needed (since the ones
5553 in system C libraries may be hand optimized) is to, taking @code{memchr}
5554 for example, put it in @file{memchr.c} and use
5555 @samp{AC_REPLACE_FUNCS([memchr])}.
5558 @defmac AC_HEADER_SYS_WAIT
5559 @acindex{HEADER_SYS_WAIT}
5560 @cvindex HAVE_SYS_WAIT_H
5561 @hdrindex{sys/wait.h}
5562 If @file{sys/wait.h} exists and is compatible with Posix, define
5563 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5564 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5565 of @code{int} to store a status value. If @file{sys/wait.h} is not
5566 Posix compatible, then instead of including it, define the
5567 Posix macros with their usual interpretations. Here is an
5572 #include <sys/types.h>
5573 #ifdef HAVE_SYS_WAIT_H
5574 # include <sys/wait.h>
5577 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5580 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5586 This macro is obsolescent, as current systems are compatible with Posix.
5587 New programs need not use this macro.
5590 @cvindex _POSIX_VERSION
5592 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5593 Posix systems. If there is no @file{unistd.h}, it is definitely
5594 not a Posix system. However, some non-Posix systems do
5595 have @file{unistd.h}.
5597 The way to check whether the system supports Posix is:
5601 #ifdef HAVE_UNISTD_H
5602 # include <sys/types.h>
5603 # include <unistd.h>
5606 #ifdef _POSIX_VERSION
5607 /* Code for Posix systems. */
5612 @anchor{AC_HEADER_TIME}
5613 @defmac AC_HEADER_TIME
5614 @acindex{HEADER_TIME}
5615 @cvindex TIME_WITH_SYS_TIME
5617 @hdrindex{sys/time.h}
5618 If a program may include both @file{time.h} and @file{sys/time.h},
5619 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5620 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5621 protected against multiple inclusion, so programs could not explicitly
5622 include both files. This macro is useful in programs that use, for
5623 example, @code{struct timeval} as well as
5624 @code{struct tm}. It is best used in conjunction with
5625 @code{HAVE_SYS_TIME_H}, which can be checked for using
5626 @code{AC_CHECK_HEADERS([sys/time.h])}.
5630 #ifdef TIME_WITH_SYS_TIME
5631 # include <sys/time.h>
5634 # ifdef HAVE_SYS_TIME_H
5635 # include <sys/time.h>
5644 This macro is obsolescent, as current systems can include both files
5645 when they exist. New programs need not use this macro.
5649 @defmac AC_HEADER_TIOCGWINSZ
5650 @acindex{HEADER_TIOCGWINSZ}
5651 @cvindex GWINSZ_IN_SYS_IOCTL
5652 @hdrindex{sys/ioctl.h}
5653 @hdrindex{termios.h}
5654 @c FIXME: I need clarifications from Jim.
5655 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5656 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5657 found in @file{<termios.h>}.
5663 #ifdef HAVE_TERMIOS_H
5664 # include <termios.h>
5667 #ifdef GWINSZ_IN_SYS_IOCTL
5668 # include <sys/ioctl.h>
5674 @node Generic Headers
5675 @subsection Generic Header Checks
5677 These macros are used to find system header files not covered by the
5678 ``particular'' test macros. If you need to check the contents of a header
5679 as well as find out whether it is present, you have to write your own
5680 test for it (@pxref{Writing Tests}).
5682 @anchor{AC_CHECK_HEADER}
5683 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
5684 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5685 @acindex{CHECK_HEADER}
5686 If the system header file @var{header-file} is compilable, execute shell
5687 commands @var{action-if-found}, otherwise execute
5688 @var{action-if-not-found}. If you just want to define a symbol if the
5689 header file is available, consider using @code{AC_CHECK_HEADERS}
5692 For compatibility issues with older versions of Autoconf, please read
5696 @anchor{AC_CHECK_HEADERS}
5697 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @
5698 @ovar{action-if-found}, @ovar{action-if-not-found}, @
5699 @dvar{includes, default-includes})
5700 @acindex{CHECK_HEADERS}
5701 @cvindex HAVE_@var{header}
5702 For each given system header file @var{header-file} in the
5703 blank-separated argument list that exists, define
5704 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5705 is given, it is additional shell code to execute when one of the header
5706 files is found. You can give it a value of @samp{break} to break out of
5707 the loop on the first match. If @var{action-if-not-found} is given, it
5708 is executed when one of the header files is not found.
5710 For compatibility issues with older versions of Autoconf, please read
5714 Previous versions of Autoconf merely checked whether the header was
5715 accepted by the preprocessor. This was changed because the old test was
5716 inappropriate for typical uses. Headers are typically used to compile,
5717 not merely to preprocess, and the old behavior sometimes accepted
5718 headers that clashed at compile-time. If you need to check whether a
5719 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5720 (@pxref{Running the Preprocessor}).
5722 This scheme, which improves the robustness of the test, also requires
5723 that you make sure that headers that must be included before the
5724 @var{header-file} be part of the @var{includes}, (@pxref{Default
5725 Includes}). If looking for @file{bar.h}, which requires that
5726 @file{foo.h} be included before if it exists, we suggest the following
5730 AC_CHECK_HEADERS([foo.h])
5731 AC_CHECK_HEADERS([bar.h], [], [],
5738 The following variant generates smaller, faster @command{configure}
5739 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5741 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5742 @acindex{CHECK_HEADERS_ONCE}
5743 @cvindex HAVE_@var{header}
5744 For each given system header file @var{header-file} in the
5745 blank-separated argument list that exists, define
5746 @code{HAVE_@var{header-file}} (in all capitals).
5747 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5748 checking code at most once, so that @command{configure} is smaller and
5749 faster; but the checks cannot be conditionalized and are always done once,
5750 early during the @command{configure} run.
5754 @section Declarations
5755 @cindex Declaration, checking
5757 The following macros check for the declaration of variables and
5758 functions. If there is no macro specifically defined to check for a
5759 symbol you need, then you can use the general macros (@pxref{Generic
5760 Declarations}) or, for more complex tests, you may use
5761 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5764 * Particular Declarations:: Macros to check for certain declarations
5765 * Generic Declarations:: How to find other declarations
5768 @node Particular Declarations
5769 @subsection Particular Declaration Checks
5771 There are no specific macros for declarations.
5773 @node Generic Declarations
5774 @subsection Generic Declaration Checks
5776 These macros are used to find declarations not covered by the ``particular''
5779 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
5780 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5781 @acindex{CHECK_DECL}
5782 If @var{symbol} (a function, variable, or constant) is not declared in
5783 @var{includes} and a declaration is needed, run the shell commands
5784 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5785 @var{includes} are specified, the default includes are used
5786 (@pxref{Default Includes}).
5788 This macro actually tests whether @var{symbol} is defined as a macro or
5789 can be used as an r-value, not whether it is really declared, because it
5790 is much safer to avoid
5791 introducing extra declarations when they are not needed.
5794 @anchor{AC_CHECK_DECLS}
5795 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
5796 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5797 @acindex{CHECK_DECLS}
5798 @cvindex HAVE_DECL_@var{symbol}
5799 For each of the @var{symbols} (@emph{comma}-separated list), define
5800 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5801 @var{symbol} is declared, otherwise to @samp{0}. If
5802 @var{action-if-not-found} is given, it is additional shell code to
5803 execute when one of the function declarations is needed, otherwise
5804 @var{action-if-found} is executed.
5806 This macro uses an M4 list as first argument:
5808 AC_CHECK_DECLS([strdup])
5809 AC_CHECK_DECLS([strlen])
5810 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5813 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5814 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5815 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5816 @emph{sure} that the check was performed, use
5817 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5820 #if !HAVE_DECL_SYMBOL
5821 extern char *symbol;
5826 If the test may have not been performed, however, because it is safer
5827 @emph{not} to declare a symbol than to use a declaration that conflicts
5828 with the system's one, you should use:
5831 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5832 void *malloc (size_t *s);
5837 You fall into the second category only in extreme situations: either
5838 your files may be used without being configured, or they are used during
5839 the configuration. In most cases the traditional approach is enough.
5842 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5843 @acindex{CHECK_DECLS_ONCE}
5844 @cvindex HAVE_DECL_@var{symbol}
5845 For each of the @var{symbols} (@emph{comma}-separated list), define
5846 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5847 @var{symbol} is declared in the default include files, otherwise to
5848 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5849 generates the checking code at most once, so that @command{configure} is
5850 smaller and faster; but the checks cannot be conditionalized and are
5851 always done once, early during the @command{configure} run.
5857 @cindex Structure, checking
5859 The following macros check for the presence of certain members in C
5860 structures. If there is no macro specifically defined to check for a
5861 member you need, then you can use the general structure-member macros
5862 (@pxref{Generic Structures}) or, for more complex tests, you may use
5863 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5866 * Particular Structures:: Macros to check for certain structure members
5867 * Generic Structures:: How to find other structure members
5870 @node Particular Structures
5871 @subsection Particular Structure Checks
5873 The following macros check for certain structures or structure members.
5875 @defmac AC_STRUCT_DIRENT_D_INO
5876 @acindex{STRUCT_DIRENT_D_INO}
5877 @cvindex HAVE_STRUCT_DIRENT_D_INO
5878 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5879 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5880 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5882 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5883 @code{d_ino}, not whether its contents are always reliable.
5884 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5885 though current systems hide this detail from the user and never return
5886 zero @code{d_ino} values.
5887 Many current systems report an incorrect @code{d_ino} for a directory
5888 entry that is a mount point.
5891 @defmac AC_STRUCT_DIRENT_D_TYPE
5892 @acindex{STRUCT_DIRENT_D_TYPE}
5893 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5894 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5895 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5896 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5899 @anchor{AC_STRUCT_ST_BLOCKS}
5900 @defmac AC_STRUCT_ST_BLOCKS
5901 @acindex{STRUCT_ST_BLOCKS}
5902 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5903 @cvindex HAVE_ST_BLOCKS
5905 If @code{struct stat} contains an @code{st_blocks} member, define
5906 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5907 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5908 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5912 @defmac AC_STRUCT_TM
5914 @cvindex TM_IN_SYS_TIME
5916 @hdrindex{sys/time.h}
5917 If @file{time.h} does not define @code{struct tm}, define
5918 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5919 had better define @code{struct tm}.
5921 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5922 current systems. New programs need not use this macro.
5925 @anchor{AC_STRUCT_TIMEZONE}
5926 @defmac AC_STRUCT_TIMEZONE
5927 @acindex{STRUCT_TIMEZONE}
5928 @cvindex HAVE_DECL_TZNAME
5929 @cvindex HAVE_STRUCT_TM_TM_ZONE
5930 @cvindex HAVE_TM_ZONE
5931 @cvindex HAVE_TZNAME
5932 Figure out how to get the current timezone. If @code{struct tm} has a
5933 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5934 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5935 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5936 define @code{HAVE_DECL_TZNAME}.
5939 @node Generic Structures
5940 @subsection Generic Structure Checks
5942 These macros are used to find structure members not covered by the
5943 ``particular'' test macros.
5945 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @
5946 @ovar{action-if-found}, @ovar{action-if-not-found}, @
5947 @dvar{includes, default-includes})
5948 @acindex{CHECK_MEMBER}
5949 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5950 If no @var{includes} are specified, the default includes are used
5951 (@pxref{Default Includes}).
5954 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5955 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5959 You can use this macro for submembers:
5962 AC_CHECK_MEMBER(struct top.middle.bot)
5966 @anchor{AC_CHECK_MEMBERS}
5967 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
5968 @ovar{action-if-not-found}, @dvar{includes, default-includes})
5969 @acindex{CHECK_MEMBERS}
5970 @cvindex HAVE_@var{aggregate}_@var{member}
5971 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5972 @var{members} using the previous macro. When @var{member} belongs to
5973 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5974 capitals, with spaces and dots replaced by underscores). If
5975 @var{action-if-found} is given, it is executed for each of the found
5976 members. If @var{action-if-not-found} is given, it is executed for each
5977 of the members that could not be found.
5979 This macro uses M4 lists:
5981 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5991 The following macros check for C types, either builtin or typedefs. If
5992 there is no macro specifically defined to check for a type you need, and
5993 you don't need to check for any special properties of it, then you can
5994 use a general type-check macro.
5997 * Particular Types:: Special handling to find certain types
5998 * Generic Types:: How to find other types
6001 @node Particular Types
6002 @subsection Particular Type Checks
6004 @hdrindex{sys/types.h}
6007 @hdrindex{inttypes.h}
6008 These macros check for particular C types in @file{sys/types.h},
6009 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
6012 The Gnulib @code{stdint} module is an alternate way to define many of
6013 these symbols; it is useful if you prefer your code to assume a
6014 C99-or-better environment. @xref{Gnulib}.
6016 @anchor{AC_TYPE_GETGROUPS}
6017 @defmac AC_TYPE_GETGROUPS
6018 @acindex{TYPE_GETGROUPS}
6019 @cvindex GETGROUPS_T
6020 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
6021 is the base type of the array argument to @code{getgroups}.
6024 @defmac AC_TYPE_INT8_T
6025 @acindex{TYPE_INT8_T}
6026 @cvindex HAVE_INT8_T
6028 If @file{stdint.h} or @file{inttypes.h} does not define the type
6029 @code{int8_t}, define @code{int8_t} to a signed
6030 integer type that is exactly 8 bits wide and that uses two's complement
6031 representation, if such a type exists.
6032 If you are worried about porting to hosts that lack such a type, you can
6033 use the results of this macro in C89-or-later code as follows:
6037 # include <stdint.h>
6039 #if defined INT8_MAX || defined int8_t
6040 @emph{code using int8_t}
6042 @emph{complicated alternative using >8-bit 'signed char'}
6047 @defmac AC_TYPE_INT16_T
6048 @acindex{TYPE_INT16_T}
6049 @cvindex HAVE_INT16_T
6051 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
6054 @defmac AC_TYPE_INT32_T
6055 @acindex{TYPE_INT32_T}
6056 @cvindex HAVE_INT32_T
6058 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
6061 @defmac AC_TYPE_INT64_T
6062 @acindex{TYPE_INT64_T}
6063 @cvindex HAVE_INT64_T
6065 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
6068 @defmac AC_TYPE_INTMAX_T
6069 @acindex{TYPE_INTMAX_T}
6070 @cvindex HAVE_INTMAX_T
6072 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
6073 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
6074 widest signed integer type.
6077 @defmac AC_TYPE_INTPTR_T
6078 @acindex{TYPE_INTPTR_T}
6079 @cvindex HAVE_INTPTR_T
6081 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
6082 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
6083 signed integer type wide enough to hold a pointer, if such a type
6087 @defmac AC_TYPE_LONG_DOUBLE
6088 @acindex{TYPE_LONG_DOUBLE}
6089 @cvindex HAVE_LONG_DOUBLE
6090 If the C compiler supports a working @code{long double} type, define
6091 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
6092 same range and precision as @code{double}.
6094 This macro is obsolescent, as current C compilers support @code{long
6095 double}. New programs need not use this macro.
6098 @defmac AC_TYPE_LONG_DOUBLE_WIDER
6099 @acindex{TYPE_LONG_DOUBLE_WIDER}
6100 @cvindex HAVE_LONG_DOUBLE_WIDER
6101 If the C compiler supports a working @code{long double} type with more
6102 range or precision than the @code{double} type, define
6103 @code{HAVE_LONG_DOUBLE_WIDER}.
6106 @defmac AC_TYPE_LONG_LONG_INT
6107 @acindex{TYPE_LONG_LONG_INT}
6108 @cvindex HAVE_LONG_LONG_INT
6109 If the C compiler supports a working @code{long long int} type, define
6110 @code{HAVE_LONG_LONG_INT}.
6113 @defmac AC_TYPE_MBSTATE_T
6114 @acindex{TYPE_MBSTATE_T}
6117 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
6118 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
6119 @code{<wchar.h>} does not declare it.
6122 @anchor{AC_TYPE_MODE_T}
6123 @defmac AC_TYPE_MODE_T
6124 @acindex{TYPE_MODE_T}
6126 Define @code{mode_t} to a suitable type, if standard headers do not
6130 @anchor{AC_TYPE_OFF_T}
6131 @defmac AC_TYPE_OFF_T
6132 @acindex{TYPE_OFF_T}
6134 Define @code{off_t} to a suitable type, if standard headers do not
6138 @anchor{AC_TYPE_PID_T}
6139 @defmac AC_TYPE_PID_T
6140 @acindex{TYPE_PID_T}
6142 Define @code{pid_t} to a suitable type, if standard headers do not
6146 @anchor{AC_TYPE_SIGNAL}
6147 @defmac AC_TYPE_SIGNAL
6148 @acindex{TYPE_SIGNAL}
6151 If @file{signal.h} declares @code{signal} as returning a pointer to a
6152 function returning @code{void}, define @code{RETSIGTYPE} to be
6153 @code{void}; otherwise, define it to be @code{int}.
6155 Define signal handlers as returning type @code{RETSIGTYPE}:
6168 @anchor{AC_TYPE_SIZE_T}
6169 @defmac AC_TYPE_SIZE_T
6170 @acindex{TYPE_SIZE_T}
6172 Define @code{size_t} to a suitable type, if standard headers do not
6176 @defmac AC_TYPE_SSIZE_T
6177 @acindex{TYPE_SSIZE_T}
6179 Define @code{ssize_t} to a suitable type, if standard headers do not
6183 @anchor{AC_TYPE_UID_T}
6184 @defmac AC_TYPE_UID_T
6185 @acindex{TYPE_UID_T}
6188 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6189 headers do not define them.
6192 @defmac AC_TYPE_UINT8_T
6193 @acindex{TYPE_UINT8_T}
6194 @cvindex HAVE_UINT8_T
6196 If @file{stdint.h} or @file{inttypes.h} does not define the type
6197 @code{uint8_t}, define @code{uint8_t} to an
6198 unsigned integer type that is exactly 8 bits wide, if such a type
6200 This is like @code{AC_TYPE_INT8_T}, except for unsigned integers.
6203 @defmac AC_TYPE_UINT16_T
6204 @acindex{TYPE_UINT16_T}
6205 @cvindex HAVE_UINT16_T
6207 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit integers.
6210 @defmac AC_TYPE_UINT32_T
6211 @acindex{TYPE_UINT32_T}
6212 @cvindex HAVE_UINT32_T
6214 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit integers.
6217 @defmac AC_TYPE_UINT64_T
6218 @acindex{TYPE_UINT64_T}
6219 @cvindex HAVE_UINT64_T
6221 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit integers.
6224 @defmac AC_TYPE_UINTMAX_T
6225 @acindex{TYPE_UINTMAX_T}
6226 @cvindex HAVE_UINTMAX_T
6228 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6229 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6230 widest unsigned integer type.
6233 @defmac AC_TYPE_UINTPTR_T
6234 @acindex{TYPE_UINTPTR_T}
6235 @cvindex HAVE_UINTPTR_T
6237 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6238 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6239 unsigned integer type wide enough to hold a pointer, if such a type
6243 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6244 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6245 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6246 If the C compiler supports a working @code{unsigned long long int} type,
6247 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6251 @subsection Generic Type Checks
6253 These macros are used to check for types not covered by the ``particular''
6256 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
6257 @ovar{action-if-not-found}, @dvar{includes, default-includes})
6258 @acindex{CHECK_TYPE}
6259 Check whether @var{type} is defined. It may be a compiler builtin type
6260 or defined by the @var{includes} (@pxref{Default Includes}).
6262 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
6263 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
6264 same test is applied when compiling for C++, which means that in C++
6265 @var{type} should be a type-id and should not be an anonymous
6266 @samp{struct} or @samp{union}.
6270 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
6271 @ovar{action-if-not-found}, @dvar{includes, default-includes})
6272 @acindex{CHECK_TYPES}
6273 @cvindex HAVE_@var{type}
6274 For each @var{type} of the @var{types} that is defined, define
6275 @code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
6276 the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
6277 specified, the default includes are used (@pxref{Default Includes}). If
6278 @var{action-if-found} is given, it is additional shell code to execute
6279 when one of the types is found. If @var{action-if-not-found} is given,
6280 it is executed when one of the types is not found.
6282 This macro uses M4 lists:
6284 AC_CHECK_TYPES([ptrdiff_t])
6285 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6290 Autoconf, up to 2.13, used to provide to another version of
6291 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6292 compatibility, a simple heuristic, quite safe but not totally, is
6293 implemented. In case of doubt, read the documentation of the former
6294 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6297 @node Compilers and Preprocessors
6298 @section Compilers and Preprocessors
6300 @cindex Preprocessors
6303 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6304 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6305 the output of the compiler, typically to the empty string if
6306 Posix and @samp{.exe} if a @acronym{DOS} variant.
6309 They also define the output variable @code{OBJEXT} based on the
6310 output of the compiler, after @file{.c} files have been excluded, typically
6311 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6313 If the compiler being used does not produce executables, the tests fail. If
6314 the executables can't be run, and cross-compilation is not enabled, they
6315 fail too. @xref{Manual Configuration}, for more on support for cross
6319 * Specific Compiler Characteristics:: Some portability issues
6320 * Generic Compiler Characteristics:: Language independent tests and features
6321 * C Compiler:: Checking its characteristics
6322 * C++ Compiler:: Likewise
6323 * Objective C Compiler:: Likewise
6324 * Erlang Compiler and Interpreter:: Likewise
6325 * Fortran Compiler:: Likewise
6328 @node Specific Compiler Characteristics
6329 @subsection Specific Compiler Characteristics
6331 Some compilers exhibit different behaviors.
6334 @item Static/Dynamic Expressions
6335 Autoconf relies on a trick to extract one bit of information from the C
6336 compiler: using negative array sizes. For instance the following
6337 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6341 static int test_array[sizeof (int) == 4 ? 1 : -1];
6345 To our knowledge, there is a single compiler that does not support this
6346 trick: the @acronym{HP} C compilers (the real ones, not only the
6347 ``bundled'') on @acronym{HP-UX} 11.00.
6348 They incorrectly reject the above program with the diagnostic
6349 ``Variable-length arrays cannot have static storage.''
6350 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6351 not from the @code{? 1 : -1}, and
6352 Autoconf works around this problem by casting @code{sizeof (int)} to
6353 @code{long int} before comparing it.
6356 @node Generic Compiler Characteristics
6357 @subsection Generic Compiler Characteristics
6359 @anchor{AC_CHECK_SIZEOF}
6360 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
6361 @dvar{includes, default-includes})
6362 @acindex{CHECK_SIZEOF}
6363 @cvindex SIZEOF_@var{type-or-expr}
6364 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
6365 the size in bytes of @var{type-or-expr}, which may be either a type or
6366 an expression returning a value that has a size. If the expression
6367 @samp{sizeof (@var{type-or-expr})} is invalid, the result is 0. If no
6368 @var{includes} are specified, the default includes are used
6369 (@pxref{Default Includes}).
6371 This macro now works even when cross-compiling. The @var{unused}
6372 argument was used when cross-compiling.
6374 For example, the call
6377 AC_CHECK_SIZEOF([int *])
6381 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6384 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6385 @acindex{CHECK_ALIGNOF}
6386 @cvindex ALIGNOF_@var{type}
6387 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6388 alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
6389 a structure member declaration. If @samp{type} is unknown, the result
6390 is 0. If no @var{includes} are specified, the default includes are used
6391 (@pxref{Default Includes}).
6394 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
6395 @dvar{includes, default-includes}, @ovar{action-if-fails})
6396 @acindex{COMPUTE_INT}
6397 Store into the shell variable @var{var} the value of the integer
6398 @var{expression}. The
6399 value should fit in an initializer in a C variable of type @code{signed
6400 long}. To support cross compilation (in which case, the macro only works on
6401 hosts that use twos-complement arithmetic), it should be possible to evaluate
6402 the expression at compile-time. If no @var{includes} are specified, the
6403 default includes are used (@pxref{Default Includes}).
6405 Execute @var{action-if-fails} if the value cannot be determined correctly.
6408 @defmac AC_LANG_WERROR
6409 @acindex{LANG_WERROR}
6410 Normally Autoconf ignores warnings generated by the compiler, linker, and
6411 preprocessor. If this macro is used, warnings count as fatal
6412 errors for the current language. This macro is useful when the
6413 results of configuration are used where warnings are unacceptable; for
6414 instance, if parts of a program are built with the @acronym{GCC}
6416 option. If the whole program is built using @option{-Werror} it is
6417 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6424 @ovindex OPENMP_CFLAGS
6425 @ovindex OPENMP_CXXFLAGS
6426 @ovindex OPENMP_FFLAGS
6427 @ovindex OPENMP_FCFLAGS
6428 OpenMP (@url{http://www.openmp.org/}) specifies extensions of C, C++,
6429 and Fortran that simplify optimization of shared memory parallelism,
6430 which is a common problem on multicore CPUs.
6432 If the current language is C, the macro @code{AC_OPENMP} sets the
6433 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
6434 supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
6435 compiler already supports OpenMP, if it has no way to activate OpenMP
6436 support, or if the user rejects OpenMP support by invoking
6437 @samp{configure} with the @samp{--disable-openmp} option.
6439 @code{OPENMP_CFLAGS} needs to be used when compiling programs, when
6440 preprocessing program source, and when linking programs. Therefore you
6441 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
6442 that use OpenMP@. If you preprocess OpenMP-specific C code, you also
6443 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
6444 OpenMP support is revealed at compile time by the preprocessor macro
6447 Linking a program with @code{OPENMP_CFLAGS} typically adds one more
6448 shared library to the program's dependencies, so its use is recommended
6449 only on programs that actually require OpenMP.
6451 If the current language is C++, @code{AC_OPENMP} sets the variable
6452 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
6455 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
6456 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
6457 respectively. Similar remarks as for C hold, except that
6458 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
6459 signals OpenMP support.
6463 @subsection C Compiler Characteristics
6465 The following macros provide ways to find and exercise a C Compiler.
6466 There are a few constructs that ought to be avoided, but do not deserve
6467 being checked for, since they can easily be worked around.
6470 @item Don't use lines containing solitary backslashes
6471 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6472 @acronym{HP-UX} 10.20,
6473 11.00, and 11i). When given the following source:
6478 * A comment with backslash-newlines in it. %@{ %@} *\
6482 " A string with backslash-newlines in it %@{ %@} \\
6484 char apostrophe = '\\
6492 the compiler incorrectly fails with the diagnostics ``Non-terminating
6493 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6494 Removing the lines with solitary backslashes solves the problem.
6496 @item Don't compile several files at once if output matters to you
6497 Some compilers, such as @acronym{HP}'s, report names of files being
6498 compiled when given more than one file operand. For instance:
6507 This can cause problems if you observe the output of the compiler to
6508 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6509 b.o} solves the issue.
6511 @item Don't rely on @code{#error} failing
6512 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6513 simply emits a diagnostic and continues, exiting successfully. So,
6514 instead of an error directive like @code{#error "Unsupported word size"}
6515 it is more portable to use an invalid directive like @code{#Unsupported
6516 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6517 OK, since installers with inadequate compilers like @sc{irix} can simply
6518 examine these compilers' diagnostic output.
6520 @item Don't rely on correct @code{#line} support
6521 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6522 diagnoses @code{#line} directives whose line
6523 numbers are greater than 32767. Nothing in Posix
6524 makes this invalid. That is why Autoconf stopped issuing
6525 @code{#line} directives.
6528 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6532 Determine a C compiler to use. If @code{CC} is not already set in the
6533 environment, check for @code{gcc} and @code{cc}, then for other C
6534 compilers. Set output variable @code{CC} to the name of the compiler
6537 This macro may, however, be invoked with an optional first argument
6538 which, if specified, must be a blank-separated list of C compilers to
6539 search for. This just gives the user an opportunity to specify an
6540 alternative search list for the C compiler. For example, if you didn't
6541 like the default order, then you could invoke @code{AC_PROG_CC} like
6545 AC_PROG_CC([gcc cl cc])
6548 If the C compiler does not handle function prototypes correctly by
6549 default, try to add an option to output variable @code{CC} to make it
6550 so. This macro tries various options that select standard-conformance
6551 modes on various systems.
6553 After calling this macro you can check whether the C compiler has been
6554 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6556 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6557 @code{AC_C_PROTOTYPES} below.
6559 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6560 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6561 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6562 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6566 @anchor{AC_PROG_CC_C_O}
6567 @defmac AC_PROG_CC_C_O
6568 @acindex{PROG_CC_C_O}
6569 @cvindex NO_MINUS_C_MINUS_O
6570 If the C compiler does not accept the @option{-c} and @option{-o} options
6571 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6572 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6573 the first @code{cc} in the path. The test fails if one fails. This
6574 macro was created for @acronym{GNU} Make to choose the default C compilation
6582 Set output variable @code{CPP} to a command that runs the
6583 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6584 It is only portable to run @code{CPP} on files with a @file{.c}
6587 Some preprocessors don't indicate missing include files by the error
6588 status. For such preprocessors an internal variable is set that causes
6589 other macros to check the standard error from the preprocessor and
6590 consider the test failed if any warnings have been reported.
6591 For most preprocessors, though, warnings do not cause include-file
6592 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6595 @defmac AC_PROG_CPP_WERROR
6596 @acindex{PROG_CPP_WERROR}
6598 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6599 preprocessor as errors even if the preprocessor exit status indicates
6600 success. This is useful for avoiding headers that generate mandatory
6601 warnings, such as deprecation notices.
6605 The following macros check for C compiler or machine architecture
6606 features. To check for characteristics not listed here, use
6607 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6608 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6610 @defmac AC_PROG_CC_STDC
6611 @acindex{PROG_CC_STDC}
6612 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6613 C99), try to add an option to output variable @code{CC} to make it work.
6614 If the compiler does not support C99, fall back to supporting
6615 @acronym{ANSI} C89 (@acronym{ISO} C90).
6617 After calling this macro you can check whether the C compiler has been
6618 set to accept Standard C; if not, the shell variable
6619 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6622 @defmac AC_PROG_CC_C89
6623 @acindex{PROG_CC_C89}
6624 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6625 default, try to add an option to output variable @code{CC} to make it
6626 so. This macro tries various options that select @acronym{ANSI} C89 on
6627 some system or another. It considers the compiler to be in
6628 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6630 After calling this macro you can check whether the C compiler has been
6631 set to accept @acronym{ANSI} C89; if not, the shell variable
6632 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6634 This macro is called automatically by @code{AC_PROG_CC}.
6637 @defmac AC_PROG_CC_C99
6638 @acindex{PROG_CC_C99}
6639 If the C compiler is not in C99 mode by default, try to add an
6640 option to output variable @code{CC} to make it so. This macro tries
6641 various options that select C99 on some system or another. It
6642 considers the compiler to be in C99 mode if it handles @code{_Bool},
6643 @code{//} comments, flexible array members, @code{inline}, signed and
6644 unsigned @code{long long int}, mixed code and declarations, named
6645 initialization of structs,
6646 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6647 in @code{for} loops, and variable length arrays.
6649 After calling this macro you can check whether the C compiler has been
6650 set to accept C99; if not, the shell variable
6651 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6654 @defmac AC_C_BACKSLASH_A
6655 @acindex{C_BACKSLASH_A}
6656 @cvindex HAVE_C_BACKSLASH_A
6657 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6660 This macro is obsolescent, as current C compilers understand @samp{\a}.
6661 New programs need not use this macro.
6664 @anchor{AC_C_BIGENDIAN}
6665 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @
6666 @ovar{action-if-unknown}, @ovar{action-if-universal})
6667 @acindex{C_BIGENDIAN}
6668 @cvindex WORDS_BIGENDIAN
6670 If words are stored with the most significant byte first (like Motorola
6671 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6672 the least significant byte first (like Intel and VAX CPUs), execute
6673 @var{action-if-false}.
6675 This macro runs a test-case if endianness cannot be determined from the
6676 system header files. When cross-compiling, the test-case is not run but
6677 grep'ed for some magic values. @var{action-if-unknown} is executed if
6678 the latter case fails to determine the byte sex of the host system.
6680 In some cases a single run of a compiler can generate code for multiple
6681 architectures. This can happen, for example, when generating Mac OS X
6682 universal binary files, which work on both PowerPC and Intel
6683 architectures. In this case, the different variants might be for
6684 different architectures whose endiannesses differ. If
6685 @command{configure} detects this, it executes @var{action-if-universal}
6686 instead of @var{action-if-unknown}.
6688 The default for @var{action-if-true} is to define
6689 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6690 nothing. The default for @var{action-if-unknown} is to
6691 abort configure and tell the installer how to bypass this test.
6692 And finally, the default for @var{action-if-universal} is to define
6693 @samp{WORDS_BIGENDIAN} or not, depending on the architecture that the
6694 code is being generated for.
6696 If you use this macro without specifying @var{action-if-universal}, you
6697 should also use @code{AC_CONFIG_HEADERS}; otherwise
6698 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
6706 If the C compiler does not fully support the @code{const} keyword,
6707 define @code{const} to be empty. Some C compilers that do
6708 not define @code{__STDC__} do support @code{const}; some compilers that
6709 define @code{__STDC__} do not completely support @code{const}. Programs
6710 can simply use @code{const} as if every C compiler supported it; for
6711 those that don't, the makefile or configuration header file
6712 defines it as empty.
6714 Occasionally installers use a C++ compiler to compile C code, typically
6715 because they lack a C compiler. This causes problems with @code{const},
6716 because C and C++ treat @code{const} differently. For example:
6723 is valid in C but not in C++. These differences unfortunately cannot be
6724 papered over by defining @code{const} to be empty.
6726 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6727 as this generally yields better results in practice. However, using a
6728 C++ compiler to compile C code is not recommended or supported, and
6729 installers who run into trouble in this area should get a C compiler
6730 like @acronym{GCC} to compile their C code.
6732 This macro is obsolescent, as current C compilers support @code{const}.
6733 New programs need not use this macro.
6736 @defmac AC_C_RESTRICT
6737 @acindex{C_RESTRICT}
6739 If the C compiler recognizes a variant spelling for the @code{restrict}
6740 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
6741 then define @code{restrict} to that; this is more likely to do the right
6742 thing with compilers that support language variants where plain
6743 @code{restrict} is not a keyword. Otherwise, if the C compiler
6744 recognizes the @code{restrict} keyword, don't do anything.
6745 Otherwise, define @code{restrict} to be empty.
6746 Thus, programs may simply use @code{restrict} as if every C compiler
6747 supported it; for those that do not, the makefile
6748 or configuration header defines it away.
6750 Although support in C++ for the @code{restrict} keyword is not
6751 required, several C++ compilers do accept the keyword.
6752 This macro works for them, too.
6755 @defmac AC_C_VOLATILE
6756 @acindex{C_VOLATILE}
6758 If the C compiler does not understand the keyword @code{volatile},
6759 define @code{volatile} to be empty. Programs can simply use
6760 @code{volatile} as if every C compiler supported it; for those that do
6761 not, the makefile or configuration header defines it as
6764 If the correctness of your program depends on the semantics of
6765 @code{volatile}, simply defining it to be empty does, in a sense, break
6766 your code. However, given that the compiler does not support
6767 @code{volatile}, you are at its mercy anyway. At least your
6768 program compiles, when it wouldn't before.
6769 @xref{Volatile Objects}, for more about @code{volatile}.
6771 In general, the @code{volatile} keyword is a standard C feature, so
6772 you might expect that @code{volatile} is available only when
6773 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6774 support volatile, but does not define @code{__STDC__}.
6776 This macro is obsolescent, as current C compilers support @code{volatile}.
6777 New programs need not use this macro.
6780 @anchor{AC_C_INLINE}
6784 If the C compiler supports the keyword @code{inline}, do nothing.
6785 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6786 if it accepts one of those, otherwise define @code{inline} to be empty.
6789 @anchor{AC_C_CHAR_UNSIGNED}
6790 @defmac AC_C_CHAR_UNSIGNED
6791 @acindex{C_CHAR_UNSIGNED}
6792 @cvindex __CHAR_UNSIGNED__
6793 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6794 unless the C compiler predefines it.
6797 @defmac AC_C_STRINGIZE
6798 @acindex{C_STRINGIZE}
6799 @cvindex HAVE_STRINGIZE
6800 If the C preprocessor supports the stringizing operator, define
6801 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6802 found in macros such as this:
6808 This macro is obsolescent, as current C compilers support the
6809 stringizing operator. New programs need not use this macro.
6812 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6813 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6814 @cvindex FLEXIBLE_ARRAY_MEMBER
6815 If the C compiler supports flexible array members, define
6816 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6817 That way, a declaration like this:
6823 double val[FLEXIBLE_ARRAY_MEMBER];
6828 will let applications use the ``struct hack'' even with compilers that
6829 do not support flexible array members. To allocate and use such an
6830 object, you can use code like this:
6834 size_t n = compute_value_count ();
6836 malloc (offsetof (struct s, val)
6837 + n * sizeof (double));
6839 for (i = 0; i < n; i++)
6840 p->val[i] = compute_value (i);
6844 @defmac AC_C_VARARRAYS
6845 @acindex{C_VARARRAYS}
6846 @cvindex HAVE_C_VARARRAYS
6847 If the C compiler supports variable-length arrays, define
6848 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
6849 storage duration whose length is determined at run time, when the array
6855 @cvindex HAVE_TYPEOF
6857 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6859 through a different spelling of the keyword (e.g., @code{__typeof__}),
6860 define @code{HAVE_TYPEOF}. If the support is available only through a
6861 different spelling, define @code{typeof} to that spelling.
6864 @defmac AC_C_PROTOTYPES
6865 @acindex{C_PROTOTYPES}
6867 @cvindex __PROTOTYPES
6869 If function prototypes are understood by the compiler (as determined by
6870 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6871 Defining @code{__PROTOTYPES} is for the benefit of
6872 header files that cannot use macros that infringe on user name space.
6874 This macro is obsolescent, as current C compilers support prototypes.
6875 New programs need not use this macro.
6878 @anchor{AC_PROG_GCC_TRADITIONAL}
6879 @defmac AC_PROG_GCC_TRADITIONAL
6880 @acindex{PROG_GCC_TRADITIONAL}
6882 Add @option{-traditional} to output variable @code{CC} if using the
6883 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6884 @option{-traditional}. That usually happens when the fixed header files
6885 have not been installed on an old system.
6887 This macro is obsolescent, since current versions of the @acronym{GNU} C
6888 compiler fix the header files automatically when installed.
6893 @subsection C++ Compiler Characteristics
6896 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6900 Determine a C++ compiler to use. Check whether the environment variable
6901 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6902 variable @code{CXX} to its value.
6904 Otherwise, if the macro is invoked without an argument, then search for
6905 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6906 then other names). If none of those checks succeed, then as a last
6907 resort set @code{CXX} to @code{g++}.
6909 This macro may, however, be invoked with an optional first argument
6910 which, if specified, must be a blank-separated list of C++ compilers to
6911 search for. This just gives the user an opportunity to specify an
6912 alternative search list for the C++ compiler. For example, if you
6913 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6917 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6920 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6921 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6922 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6923 systems where G++ does not accept @option{-g}), or @option{-g} for other
6927 @defmac AC_PROG_CXXCPP
6928 @acindex{PROG_CXXCPP}
6930 Set output variable @code{CXXCPP} to a command that runs the C++
6931 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6932 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6933 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6935 Some preprocessors don't indicate missing include files by the error
6936 status. For such preprocessors an internal variable is set that causes
6937 other macros to check the standard error from the preprocessor and
6938 consider the test failed if any warnings have been reported. However,
6939 it is not known whether such broken preprocessors exist for C++.
6942 @defmac AC_PROG_CXX_C_O
6943 @acindex{PROG_CXX_C_O}
6944 @cvindex CXX_NO_MINUS_C_MINUS_O
6945 Test whether the C++ compiler accepts the options @option{-c} and
6946 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6951 @node Objective C Compiler
6952 @subsection Objective C Compiler Characteristics
6955 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6959 Determine an Objective C compiler to use. If @code{OBJC} is not already
6960 set in the environment, check for Objective C compilers. Set output
6961 variable @code{OBJC} to the name of the compiler found.
6963 This macro may, however, be invoked with an optional first argument
6964 which, if specified, must be a blank-separated list of Objective C compilers to
6965 search for. This just gives the user an opportunity to specify an
6966 alternative search list for the Objective C compiler. For example, if you
6967 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6971 AC_PROG_OBJC([gcc objcc objc])
6974 If using the @acronym{GNU} Objective C compiler, set shell variable
6975 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6976 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6977 compiler (@option{-O2} on systems where @command{gcc} does not accept
6978 @option{-g}), or @option{-g} for other compilers.
6981 @defmac AC_PROG_OBJCPP
6982 @acindex{PROG_OBJCPP}
6984 Set output variable @code{OBJCPP} to a command that runs the Objective C
6985 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6989 @node Erlang Compiler and Interpreter
6990 @subsection Erlang Compiler and Interpreter Characteristics
6993 Autoconf defines the following macros for determining paths to the essential
6994 Erlang/OTP programs:
6996 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @dvar{path, $PATH})
6997 @acindex{ERLANG_PATH_ERLC}
7000 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
7001 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
7002 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
7003 is not set in the environment, set it to an empty value.
7005 The two optional arguments have the same meaning as the two last arguments of
7006 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
7007 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
7011 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
7015 @defmac AC_ERLANG_NEED_ERLC (@dvar{path, $PATH})
7016 @acindex{ERLANG_NEED_ERLC}
7017 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
7018 error message and exits the @command{configure} script if the @command{erlc}
7019 program is not found.
7022 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @dvar{path, $PATH})
7023 @acindex{ERLANG_PATH_ERL}
7025 Determine an Erlang interpreter to use. If @code{ERL} is not already
7027 environment, check for @command{erl}. Set output variable @code{ERL} to the
7028 complete path of the interpreter command found.
7030 The two optional arguments have the same meaning as the two last arguments of
7031 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
7032 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
7036 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
7040 @defmac AC_ERLANG_NEED_ERL (@dvar{path, $PATH})
7041 @acindex{ERLANG_NEED_ERL}
7042 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
7043 error message and exits the @command{configure} script if the @command{erl}
7044 program is not found.
7048 @node Fortran Compiler
7049 @subsection Fortran Compiler Characteristics
7053 The Autoconf Fortran support is divided into two categories: legacy
7054 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
7055 The former are intended for traditional Fortran 77 code, and have output
7056 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
7057 are for newer programs that can (or must) compile under the newer
7058 Fortran standards, and have output variables like @code{FC},
7059 @code{FCFLAGS}, and @code{FCLIBS}.
7061 Except for two new macros @code{AC_FC_SRCEXT} and
7062 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
7063 behave almost identically, and so they are documented together in this
7067 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
7071 Determine a Fortran 77 compiler to use. If @code{F77} is not already
7072 set in the environment, then check for @code{g77} and @code{f77}, and
7073 then some other names. Set the output variable @code{F77} to the name
7074 of the compiler found.
7076 This macro may, however, be invoked with an optional first argument
7077 which, if specified, must be a blank-separated list of Fortran 77
7078 compilers to search for. This just gives the user an opportunity to
7079 specify an alternative search list for the Fortran 77 compiler. For
7080 example, if you didn't like the default order, then you could invoke
7081 @code{AC_PROG_F77} like this:
7084 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
7087 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
7088 set the shell variable @code{G77} to @samp{yes}.
7089 If the output variable @code{FFLAGS} was not already set in the
7090 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
7091 where @code{g77} does not accept @option{-g}). Otherwise, set
7092 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
7095 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
7099 Determine a Fortran compiler to use. If @code{FC} is not already set in
7100 the environment, then @code{dialect} is a hint to indicate what Fortran
7101 dialect to search for; the default is to search for the newest available
7102 dialect. Set the output variable @code{FC} to the name of the compiler
7105 By default, newer dialects are preferred over older dialects, but if
7106 @code{dialect} is specified then older dialects are preferred starting
7107 with the specified dialect. @code{dialect} can currently be one of
7108 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
7109 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
7110 and no attempt is made to guarantee that a particular language standard
7111 is actually supported. Thus, it is preferable that you avoid the
7112 @code{dialect} option, and use AC_PROG_FC only for code compatible with
7113 the latest Fortran standard.
7115 This macro may, alternatively, be invoked with an optional first argument
7116 which, if specified, must be a blank-separated list of Fortran
7117 compilers to search for, just as in @code{AC_PROG_F77}.
7119 If the output variable @code{FCFLAGS} was not already set in the
7120 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
7121 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
7122 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
7125 @defmac AC_PROG_F77_C_O
7126 @defmacx AC_PROG_FC_C_O
7127 @acindex{PROG_F77_C_O}
7128 @acindex{PROG_FC_C_O}
7129 @cvindex F77_NO_MINUS_C_MINUS_O
7130 @cvindex FC_NO_MINUS_C_MINUS_O
7131 Test whether the Fortran compiler accepts the options @option{-c} and
7132 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
7133 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
7136 The following macros check for Fortran compiler characteristics.
7137 To check for characteristics not listed here, use
7138 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
7139 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
7140 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
7141 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
7144 @defmac AC_F77_LIBRARY_LDFLAGS
7145 @defmacx AC_FC_LIBRARY_LDFLAGS
7146 @acindex{F77_LIBRARY_LDFLAGS}
7148 @acindex{FC_LIBRARY_LDFLAGS}
7150 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
7151 @dfn{Fortran intrinsic and runtime libraries} that are required to
7152 successfully link a Fortran program or shared library. The output
7153 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
7154 should be included after @code{LIBS} when linking).
7156 This macro is intended to be used in those situations when it is
7157 necessary to mix, e.g., C++ and Fortran source code in a single
7158 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
7159 automake, @acronym{GNU} Automake}).
7161 For example, if object files from a C++ and Fortran compiler must be
7162 linked together, then the C++ compiler/linker must be used for linking
7163 (since special C++-ish things need to happen at link time like calling
7164 global constructors, instantiating templates, enabling exception
7167 However, the Fortran intrinsic and runtime libraries must be linked in
7168 as well, but the C++ compiler/linker doesn't know by default how to add
7169 these Fortran 77 libraries. Hence, this macro was created to determine
7170 these Fortran libraries.
7172 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7173 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
7174 link C/C++ with Fortran; see below.
7177 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7178 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7179 @acindex{F77_DUMMY_MAIN}
7180 @cvindex F77_DUMMY_MAIN
7181 With many compilers, the Fortran libraries detected by
7182 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
7183 their own @code{main} entry function that initializes things like
7184 Fortran I/O, and which then calls a user-provided entry function named
7185 (say) @code{MAIN__} to run the user's program. The
7186 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7187 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
7190 When using Fortran for purely numerical functions (no I/O, etc.)@: often
7191 one prefers to provide one's own @code{main} and skip the Fortran
7192 library initializations. In this case, however, one may still need to
7193 provide a dummy @code{MAIN__} routine in order to prevent linking errors
7194 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
7195 detects whether any such routine is @emph{required} for linking, and
7196 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
7197 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
7198 was found, and @code{none} when no such dummy main is needed.
7200 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
7201 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
7202 @emph{if} it is required. @var{action-if-not-found} defaults to
7203 exiting with an error.
7205 In order to link with Fortran routines, the user's C/C++ program should
7206 then include the following code to define the dummy main if it is
7210 #ifdef F77_DUMMY_MAIN
7214 int F77_DUMMY_MAIN() @{ return 1; @}
7218 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7220 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7221 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7222 explicitly unless one wants to change the default actions.
7231 As discussed above, many Fortran libraries allow you to provide an entry
7232 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7233 is then called by a @code{main} function in the Fortran libraries that
7234 initializes things like Fortran I/O@. The
7235 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7236 @emph{possible} to utilize such an alternate main function, and defines
7237 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7238 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7239 simply defined to @code{main}.)
7241 Thus, when calling Fortran routines from C that perform things like I/O,
7242 one should use this macro and declare the "main" function like so:
7248 int F77_MAIN(int argc, char *argv[]);
7251 (Again, replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7254 @defmac AC_F77_WRAPPERS
7255 @defmacx AC_FC_WRAPPERS
7256 @acindex{F77_WRAPPERS}
7259 @acindex{FC_WRAPPERS}
7262 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7263 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7264 mangle the names of C/C++ identifiers, and identifiers with underscores,
7265 respectively, so that they match the name-mangling scheme used by the
7268 Fortran is case-insensitive, and in order to achieve this the Fortran
7269 compiler converts all identifiers into a canonical case and format. To
7270 call a Fortran subroutine from C or to write a C function that is
7271 callable from Fortran, the C program must explicitly use identifiers in
7272 the format expected by the Fortran compiler. In order to do this, one
7273 simply wraps all C identifiers in one of the macros provided by
7274 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7275 you have the following Fortran 77 subroutine:
7278 subroutine foobar (x, y)
7279 double precision x, y
7285 You would then declare its prototype in C or C++ as:
7288 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7290 extern "C" /* prevent C++ name mangling */
7292 void FOOBAR_F77(double *x, double *y);
7295 Note that we pass both the lowercase and uppercase versions of the
7296 function name to @code{F77_FUNC} so that it can select the right one.
7297 Note also that all parameters to Fortran 77 routines are passed as
7298 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7301 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7303 Although Autoconf tries to be intelligent about detecting the
7304 name-mangling scheme of the Fortran compiler, there may be Fortran
7305 compilers that it doesn't support yet. In this case, the above code
7306 generates a compile-time error, but some other behavior
7307 (e.g., disabling Fortran-related features) can be induced by checking
7308 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7310 Now, to call that routine from a C program, we would do something like:
7314 double x = 2.7183, y;
7315 FOOBAR_F77 (&x, &y);
7319 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7320 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7321 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7322 because some Fortran compilers mangle names differently if they contain
7326 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7327 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7330 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7331 hold the mangled version @var{name} according to the rules of the
7332 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7333 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7334 supplied, the shell variable is simply @var{name}. The purpose of
7335 this macro is to give the caller a way to access the name-mangling
7336 information other than through the C preprocessor as above, for example,
7337 to call Fortran routines from some language other than C/C++.
7340 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @
7341 @ovar{action-if-failure})
7343 By default, the @code{FC} macros perform their tests using a @file{.f}
7344 extension for source-code files. Some compilers, however, only enable
7345 newer language features for appropriately named files, e.g., Fortran 90
7346 features only for @file{.f90} files. On the other hand, some other
7347 compilers expect all source files to end in @file{.f} and require
7348 special flags to support other file name extensions. The
7349 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7351 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7352 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7353 contain the dot). If any special compiler flags are needed for this, it
7354 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7355 extension and these flags are then used for all subsequent @code{FC} tests
7356 (until @code{AC_FC_SRCEXT} is called again).
7358 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7359 @file{.f90} extension in future tests, and it would set a
7360 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7361 to compile such files.
7363 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7364 @code{FCFLAGS}, for two reasons based on the limitations of some
7365 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7366 time, so files with different extensions must be compiled separately.
7367 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7368 the source-code file name when compiling. So, continuing the example
7369 above, you might compile a @file{foo.f90} file in your makefile with the
7374 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7377 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7378 extension, it calls @var{action-if-success} (defaults to nothing). If
7379 it fails, and cannot find a way to make the @code{FC} compiler accept such
7380 files, it calls @var{action-if-failure} (defaults to exiting with an
7385 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7386 @acindex{FC_FREEFORM}
7388 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7389 (@code{$FC}) allows free-format source code (as opposed to the older
7390 fixed-format style from Fortran 77). If necessary, it may add some
7391 additional flags to @code{FCFLAGS}.
7393 This macro is most important if you are using the default @file{.f}
7394 extension, since many compilers interpret this extension as indicating
7395 fixed-format source unless an additional flag is supplied. If you
7396 specify a different extension with @code{AC_FC_SRCEXT}, such as
7397 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7398 succeeds without modifying @code{FCFLAGS}.
7400 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7401 calls @var{action-if-success} (defaults to nothing). If it fails, it
7402 calls @var{action-if-failure} (defaults to exiting with an error
7406 @node System Services
7407 @section System Services
7409 The following macros check for operating system services or capabilities.
7415 @cindex X Window System
7416 Try to locate the X Window System include files and libraries. If the
7417 user gave the command line options @option{--x-includes=@var{dir}} and
7418 @option{--x-libraries=@var{dir}}, use those directories.
7420 If either or both were not given, get the missing values by running
7421 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7422 environment variable) on a trivial @file{Imakefile} and examining the
7423 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7424 disables this method.
7426 If this method fails to find the X Window System, @command{configure}
7427 looks for the files in several directories where they often reside.
7428 If either method is successful, set the shell variables
7429 @code{x_includes} and @code{x_libraries} to their locations, unless they
7430 are in directories the compiler searches by default.
7432 If both methods fail, or the user gave the command line option
7433 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7434 otherwise set it to the empty string.
7437 @anchor{AC_PATH_XTRA}
7438 @defmac AC_PATH_XTRA
7442 @ovindex X_EXTRA_LIBS
7444 @cvindex X_DISPLAY_MISSING
7445 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7446 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7447 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7450 This macro also checks for special libraries that some systems need in
7451 order to compile X programs. It adds any that the system needs to
7452 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7453 libraries that need to be linked with before @option{-lX11}, and adds
7454 any found to the output variable @code{X_PRE_LIBS}.
7456 @c This is an incomplete kludge. Make a real way to do it.
7457 @c If you need to check for other X functions or libraries yourself, then
7458 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7459 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7462 @anchor{AC_SYS_INTERPRETER}
7463 @defmac AC_SYS_INTERPRETER
7464 @acindex{SYS_INTERPRETER}
7465 Check whether the system supports starting scripts with a line of the
7466 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7467 After running this macro, shell code in @file{configure.ac} can check
7468 the shell variable @code{interpval}; it is set to @samp{yes}
7469 if the system supports @samp{#!}, @samp{no} if not.
7472 @defmac AC_SYS_LARGEFILE
7473 @acindex{SYS_LARGEFILE}
7474 @cvindex _FILE_OFFSET_BITS
7475 @cvindex _LARGE_FILES
7477 @cindex Large file support
7480 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7481 large-file support}. On some hosts, one must use special compiler
7482 options to build programs that can access large files. Append any such
7483 options to the output variable @code{CC}. Define
7484 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7486 Large-file support can be disabled by configuring with the
7487 @option{--disable-largefile} option.
7489 If you use this macro, check that your program works even when
7490 @code{off_t} is wider than @code{long int}, since this is common when
7491 large-file support is enabled. For example, it is not correct to print
7492 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7495 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7496 replace their C counterparts @code{fseek} and @code{ftell} that do not
7497 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7498 prototypes available when using them and large-file support is
7502 @anchor{AC_SYS_LONG_FILE_NAMES}
7503 @defmac AC_SYS_LONG_FILE_NAMES
7504 @acindex{SYS_LONG_FILE_NAMES}
7505 @cvindex HAVE_LONG_FILE_NAMES
7506 If the system supports file names longer than 14 characters, define
7507 @code{HAVE_LONG_FILE_NAMES}.
7510 @defmac AC_SYS_POSIX_TERMIOS
7511 @acindex{SYS_POSIX_TERMIOS}
7512 @cindex Posix termios headers
7513 @cindex termios Posix headers
7514 Check to see if the Posix termios headers and functions are available on the
7515 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7516 @samp{yes}. If not, set the variable to @samp{no}.
7519 @node Posix Variants
7520 @section Posix Variants
7522 The following macro makes it possible to use features of Posix that are
7523 extensions to C, as well as platform extensions not defined by Posix.
7525 @anchor{AC_USE_SYSTEM_EXTENSIONS}
7526 @defmac AC_USE_SYSTEM_EXTENSIONS
7527 @acindex{USE_SYSTEM_EXTENSIONS}
7528 @cvindex _ALL_SOURCE
7529 @cvindex _GNU_SOURCE
7531 @cvindex _POSIX_1_SOURCE
7532 @cvindex _POSIX_PTHREAD_SEMANTICS
7533 @cvindex _POSIX_SOURCE
7534 @cvindex _TANDEM_SOURCE
7535 @cvindex __EXTENSIONS__
7536 This macro was introduced in Autoconf 2.60. If possible, enable
7537 extensions to C or Posix on hosts that normally disable the extensions,
7538 typically due to standards-conformance namespace issues. This should be
7539 called before any macros that run the C compiler. The following
7540 preprocessor macros are defined where appropriate:
7544 Enable extensions on @acronym{GNU}/Linux.
7545 @item __EXTENSIONS__
7546 Enable general extensions on Solaris.
7547 @item _POSIX_PTHREAD_SEMANTICS
7548 Enable threading extensions on Solaris.
7549 @item _TANDEM_SOURCE
7550 Enable extensions for the @acronym{HP} NonStop platform.
7552 Enable extensions for @acronym{AIX} 3, and for Interix.
7554 Enable Posix functions for Minix.
7555 @item _POSIX_1_SOURCE
7556 Enable additional Posix functions for Minix.
7558 Identify Minix platform. This particular preprocessor macro is
7559 obsolescent, and may be removed in a future release of Autoconf.
7564 @node Erlang Libraries
7565 @section Erlang Libraries
7566 @cindex Erlang, Library, checking
7568 The following macros check for an installation of Erlang/OTP, and for the
7569 presence of certain Erlang libraries. All those macros require the
7570 configuration of an Erlang interpreter and an Erlang compiler
7571 (@pxref{Erlang Compiler and Interpreter}).
7573 @defmac AC_ERLANG_SUBST_ROOT_DIR
7574 @acindex{ERLANG_SUBST_ROOT_DIR}
7575 @ovindex ERLANG_ROOT_DIR
7577 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base
7578 directory in which Erlang/OTP is installed (as returned by Erlang's
7579 @code{code:root_dir/0} function). The result of this test is cached if
7580 caching is enabled when running @command{configure}.
7583 @defmac AC_ERLANG_SUBST_LIB_DIR
7584 @acindex{ERLANG_SUBST_LIB_DIR}
7585 @ovindex ERLANG_LIB_DIR
7587 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7588 directory of Erlang/OTP (as returned by Erlang's
7589 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7590 Erlang/OTP library. The result of this test is cached if caching is enabled
7591 when running @command{configure}.
7594 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @
7595 @ovar{action-if-not-found})
7596 @acindex{ERLANG_CHECK_LIB}
7597 @ovindex ERLANG_LIB_DIR_@var{library}
7598 @ovindex ERLANG_LIB_VER_@var{library}
7600 Test whether the Erlang/OTP library @var{library} is installed by
7601 calling Erlang's @code{code:lib_dir/1} function. The result of this
7602 test is cached if caching is enabled when running @command{configure}.
7603 @var{action-if-found} is a list of shell commands to run if the library
7604 is installed; @var{action-if-not-found} is a list of shell commands to
7605 run if it is not. Additionally, if the library is installed, the output
7606 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7607 library installation directory, and the output variable
7608 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7609 part of the subdirectory name, if it is in the standard form
7610 (@code{@var{library}-@var{version}}). If the directory name does not
7611 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7612 empty string. If the library is not installed,
7613 @samp{ERLANG_LIB_DIR_@var{library}} and
7614 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
7615 example, to check if library @code{stdlib} is installed:
7618 AC_ERLANG_CHECK_LIB([stdlib],
7619 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7620 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7621 [AC_MSG_ERROR([stdlib was not found!])])
7625 In addition to the above macros, which test installed Erlang libraries, the
7626 following macros determine the paths to the directories into which newly built
7627 Erlang libraries are to be installed:
7629 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7630 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7631 @ovindex ERLANG_INSTALL_LIB_DIR
7633 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7634 which every built Erlang library should be installed in a separate
7636 If this variable is not set in the environment when @command{configure} runs,
7637 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7638 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7641 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7642 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7643 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7645 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7646 directory into which the built Erlang library @var{library} version
7647 @var{version} should be installed. If this variable is not set in the
7648 environment when @command{configure} runs, its default value is
7649 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7650 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7651 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7658 @c ========================================================= Writing Tests
7661 @chapter Writing Tests
7663 If the existing feature tests don't do something you need, you have to
7664 write new ones. These macros are the building blocks. They provide
7665 ways for other macros to check whether various kinds of features are
7666 available and report the results.
7668 This chapter contains some suggestions and some of the reasons why the
7669 existing tests are written the way they are. You can also learn a lot
7670 about how to write Autoconf tests by looking at the existing ones. If
7671 something goes wrong in one or more of the Autoconf tests, this
7672 information can help you understand the assumptions behind them, which
7673 might help you figure out how to best solve the problem.
7675 These macros check the output of the compiler system of the current
7676 language (@pxref{Language Choice}). They do not cache the results of
7677 their tests for future use (@pxref{Caching Results}), because they don't
7678 know enough about the information they are checking for to generate a
7679 cache variable name. They also do not print any messages, for the same
7680 reason. The checks for particular kinds of features call these macros
7681 and do cache their results and print messages about what they're
7684 When you write a feature test that could be applicable to more than one
7685 software package, the best thing to do is encapsulate it in a new macro.
7686 @xref{Writing Autoconf Macros}, for how to do that.
7689 * Language Choice:: Selecting which language to use for testing
7690 * Writing Test Programs:: Forging source files for compilers
7691 * Running the Preprocessor:: Detecting preprocessor symbols
7692 * Running the Compiler:: Detecting language or header features
7693 * Running the Linker:: Detecting library features
7694 * Runtime:: Testing for runtime features
7695 * Systemology:: A zoology of operating systems
7696 * Multiple Cases:: Tests for several possible values
7699 @node Language Choice
7700 @section Language Choice
7703 Autoconf-generated @command{configure} scripts check for the C compiler and
7704 its features by default. Packages that use other programming languages
7705 (maybe more than one, e.g., C and C++) need to test features of the
7706 compilers for the respective languages. The following macros determine
7707 which programming language is used in the subsequent tests in
7708 @file{configure.ac}.
7711 @defmac AC_LANG (@var{language})
7712 Do compilation tests using the compiler, preprocessor, and file
7713 extensions for the specified @var{language}.
7715 Supported languages are:
7719 Do compilation tests using @code{CC} and @code{CPP} and use extension
7720 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7721 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7724 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7725 extension @file{.C} for test programs. Use compilation flags:
7726 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
7727 @code{CXXFLAGS} with @code{CXX}.
7730 Do compilation tests using @code{F77} and use extension @file{.f} for
7731 test programs. Use compilation flags: @code{FFLAGS}.
7734 Do compilation tests using @code{FC} and use extension @file{.f} (or
7735 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7736 compilation flags: @code{FCFLAGS}.
7742 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7743 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7746 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
7747 extension @file{.m} for test programs. Use compilation flags:
7748 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7749 @code{OBJCFLAGS} with @code{OBJC}.
7753 @anchor{AC_LANG_PUSH}
7754 @defmac AC_LANG_PUSH (@var{language})
7756 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7757 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7758 in macros that need to temporarily switch to a particular language.
7761 @defmac AC_LANG_POP (@ovar{language})
7763 Select the language that is saved on the top of the stack, as set by
7764 @code{AC_LANG_PUSH}, and remove it from the stack.
7766 If given, @var{language} specifies the language we just @emph{quit}. It
7767 is a good idea to specify it when it's known (which should be the
7768 case@dots{}), since Autoconf detects inconsistencies.
7771 AC_LANG_PUSH([Fortran 77])
7772 # Perform some tests on Fortran 77.
7774 AC_LANG_POP([Fortran 77])
7778 @defmac AC_LANG_ASSERT (@var{language})
7779 @acindex{LANG_ASSERT} Check statically that the current language is
7780 @var{language}. You should use this in your language specific macros
7781 to avoid that they be called with an inappropriate language.
7783 This macro runs only at @command{autoconf} time, and incurs no cost at
7784 @command{configure} time. Sadly enough and because Autoconf is a two
7785 layer language @footnote{Because M4 is not aware of Sh code,
7786 especially conditionals, some optimizations that look nice statically
7787 may produce incorrect results at runtime.}, the macros
7788 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7789 therefore as much as possible you ought to avoid using them to wrap
7790 your code, rather, require from the user to run the macro with a
7791 correct current language, and check it with @code{AC_LANG_ASSERT}.
7792 And anyway, that may help the user understand she is running a Fortran
7793 macro while expecting a result about her Fortran 77 compiler@dots{}
7797 @defmac AC_REQUIRE_CPP
7798 @acindex{REQUIRE_CPP}
7799 Ensure that whichever preprocessor would currently be used for tests has
7800 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7801 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7802 depending on which language is current.
7806 @node Writing Test Programs
7807 @section Writing Test Programs
7809 Autoconf tests follow a common scheme: feed some program with some
7810 input, and most of the time, feed a compiler with some source file.
7811 This section is dedicated to these source samples.
7814 * Guidelines:: General rules for writing test programs
7815 * Test Functions:: Avoiding pitfalls in test programs
7816 * Generating Sources:: Source program boilerplate
7820 @subsection Guidelines for Test Programs
7822 The most important rule to follow when writing testing samples is:
7824 @center @emph{Look for realism.}
7826 This motto means that testing samples must be written with the same
7827 strictness as real programs are written. In particular, you should
7828 avoid ``shortcuts'' and simplifications.
7830 Don't just play with the preprocessor if you want to prepare a
7831 compilation. For instance, using @command{cpp} to check whether a header is
7832 functional might let your @command{configure} accept a header which
7833 causes some @emph{compiler} error. Do not hesitate to check a header with
7834 other headers included before, especially required headers.
7836 Make sure the symbols you use are properly defined, i.e., refrain for
7837 simply declaring a function yourself instead of including the proper
7840 Test programs should not write to standard output. They
7841 should exit with status 0 if the test succeeds, and with status 1
7842 otherwise, so that success
7843 can be distinguished easily from a core dump or other failure;
7844 segmentation violations and other failures produce a nonzero exit
7845 status. Unless you arrange for @code{exit} to be declared, test
7846 programs should @code{return}, not @code{exit}, from @code{main},
7847 because on many systems @code{exit} is not declared by default.
7849 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7850 preprocessor macros defined by tests that have already run. For
7851 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7852 @file{configure.ac} you can have a test program that includes
7853 @file{stdbool.h} conditionally:
7857 #ifdef HAVE_STDBOOL_H
7858 # include <stdbool.h>
7863 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7864 work with any standard C compiler. Some developers prefer @code{#if}
7865 because it is easier to read, while others prefer @code{#ifdef} because
7866 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7867 @option{-Wundef} option.
7869 If a test program needs to use or create a data file, give it a name
7870 that starts with @file{conftest}, such as @file{conftest.data}. The
7871 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7872 after running test programs and if the script is interrupted.
7874 @node Test Functions
7875 @subsection Test Functions
7877 These days it's safe to assume support for function prototypes
7878 (introduced in C89).
7880 Functions that test programs declare should also be conditionalized for
7881 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7882 include any header files containing clashing prototypes.
7888 void *valloc (size_t);
7891 If a test program calls a function with invalid parameters (just to see
7892 whether it exists), organize the program to ensure that it never invokes
7893 that function. You can do this by calling it in another function that is
7894 never invoked. You can't do it by putting it after a call to
7895 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7897 and optimizes out any code that follows it in the same block.
7899 If you include any header files, be sure to call the functions
7900 relevant to them with the correct number of arguments, even if they are
7901 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7903 has internal prototypes for several functions that it automatically
7904 inlines; for example, @code{memcpy}. To avoid errors when checking for
7905 them, either pass them the correct number of arguments or redeclare them
7906 with a different return type (such as @code{char}).
7909 @node Generating Sources
7910 @subsection Generating Sources
7912 Autoconf provides a set of macros that can be used to generate test
7913 source files. They are written to be language generic, i.e., they
7914 actually depend on the current language (@pxref{Language Choice}) to
7915 ``format'' the output properly.
7918 @defmac AC_LANG_CONFTEST (@var{source})
7919 @acindex{LANG_CONFTEST}
7920 Save the @var{source} text in the current test source file:
7921 @file{conftest.@var{extension}} where the @var{extension} depends on the
7924 Note that the @var{source} is evaluated exactly once, like regular
7925 Autoconf macro arguments, and therefore (i) you may pass a macro
7926 invocation, (ii) if not, be sure to double quote if needed.
7929 @defmac AC_LANG_SOURCE (@var{source})
7930 @acindex{LANG_SOURCE}
7931 Expands into the @var{source}, with the definition of
7932 all the @code{AC_DEFINE} performed so far.
7935 For instance executing (observe the double quotation!):
7938 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7939 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7940 [Greetings string.])
7943 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7944 gcc -E -dD -o - conftest.c
7954 #define PACKAGE_NAME "Hello"
7955 #define PACKAGE_TARNAME "hello"
7956 #define PACKAGE_VERSION "1.0"
7957 #define PACKAGE_STRING "Hello 1.0"
7958 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7959 #define HELLO_WORLD "Hello, World\n"
7961 const char hw[] = "Hello, World\n";
7964 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7965 are not automatically translated into constants in the source code by this
7968 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7969 @acindex{LANG_PROGRAM}
7970 Expands into a source file which consists of the @var{prologue}, and
7971 then @var{body} as body of the main function (e.g., @code{main} in
7972 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7979 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7980 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7981 [Greetings string.])
7983 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7984 [[fputs (hw, stdout);]])])
7985 gcc -E -dD -o - conftest.c
7995 #define PACKAGE_NAME "Hello"
7996 #define PACKAGE_TARNAME "hello"
7997 #define PACKAGE_VERSION "1.0"
7998 #define PACKAGE_STRING "Hello 1.0"
7999 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
8000 #define HELLO_WORLD "Hello, World\n"
8002 const char hw[] = "Hello, World\n";
8012 In Erlang tests, the created source file is that of an Erlang module called
8013 @code{conftest} (@file{conftest.erl}). This module defines and exports
8015 one @code{start/0} function, which is called to perform the test. The
8016 @var{prologue} is optional code that is inserted between the module header and
8017 the @code{start/0} function definition. @var{body} is the body of the
8018 @code{start/0} function without the final period (@pxref{Runtime}, about
8019 constraints on this function's behavior).
8024 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8027 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
8028 [[io:format("~s~n", [?HELLO_WORLD])]])])
8038 -define(HELLO_WORLD, "Hello, world!").
8040 io:format("~s~n", [?HELLO_WORLD])
8044 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
8046 Expands into a source file which consists of the @var{prologue}, and
8047 then a call to the @var{function} as body of the main function (e.g.,
8048 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
8049 of the latter are available.
8051 This function will probably be replaced in the future by a version
8052 which would enable specifying the arguments. The use of this macro is
8053 not encouraged, as it violates strongly the typing system.
8055 This macro cannot be used for Erlang tests.
8058 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
8059 @acindex{LANG_FUNC_LINK_TRY}
8060 Expands into a source file which uses the @var{function} in the body of
8061 the main function (e.g., @code{main} in C). Since it uses
8062 @code{AC_LANG_PROGRAM}, the features of the latter are available.
8064 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
8065 It is considered to be severely broken, and in the future will be
8066 removed in favor of actual function calls (with properly typed
8069 This macro cannot be used for Erlang tests.
8072 @node Running the Preprocessor
8073 @section Running the Preprocessor
8075 Sometimes one might need to run the preprocessor on some source file.
8076 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
8077 your project, not merely run the preprocessor on it; therefore you
8078 certainly want to run the compiler, not the preprocessor. Resist the
8079 temptation of following the easiest path.
8081 Nevertheless, if you need to run the preprocessor, then use
8082 @code{AC_PREPROC_IFELSE}.
8084 The macros described in this section cannot be used for tests in Erlang or
8085 Fortran, since those languages require no preprocessor.
8087 @anchor{AC_PREPROC_IFELSE}
8088 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @
8089 @ovar{action-if-false})
8090 @acindex{PREPROC_IFELSE}
8091 Run the preprocessor of the current language (@pxref{Language Choice})
8092 on the @var{input}, run the shell commands @var{action-if-true} on
8093 success, @var{action-if-false} otherwise. The @var{input} can be made
8094 by @code{AC_LANG_PROGRAM} and friends.
8096 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
8097 @option{-g}, @option{-O}, etc.@: are not valid options to many C
8100 It is customary to report unexpected failures with
8101 @code{AC_MSG_FAILURE}.
8107 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
8108 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
8109 [Greetings string.])
8111 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
8112 [[fputs (hw, stdout);]])],
8113 [AC_MSG_RESULT([OK])],
8114 [AC_MSG_FAILURE([unexpected preprocessor failure])])
8121 checking for gcc... gcc
8122 checking for C compiler default output file name... a.out
8123 checking whether the C compiler works... yes
8124 checking whether we are cross compiling... no
8125 checking for suffix of executables...
8126 checking for suffix of object files... o
8127 checking whether we are using the GNU C compiler... yes
8128 checking whether gcc accepts -g... yes
8129 checking for gcc option to accept ISO C89... none needed
8130 checking how to run the C preprocessor... gcc -E
8136 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
8137 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
8138 it impossible to use it to elaborate sources. You are encouraged to
8139 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
8140 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
8141 to run the @emph{preprocessor} and not the compiler?
8143 @anchor{AC_EGREP_HEADER}
8144 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @
8145 @var{action-if-found}, @ovar{action-if-not-found})
8146 @acindex{EGREP_HEADER}
8147 If the output of running the preprocessor on the system header file
8148 @var{header-file} matches the extended regular expression
8149 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
8150 execute @var{action-if-not-found}.
8153 @anchor{AC_EGREP_CPP}
8154 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @
8155 @ovar{action-if-found}, @ovar{action-if-not-found})
8157 @var{program} is the text of a C or C++ program, on which shell
8158 variable, back quote, and backslash substitutions are performed. If the
8159 output of running the preprocessor on @var{program} matches the
8160 extended regular expression @var{pattern}, execute shell commands
8161 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
8166 @node Running the Compiler
8167 @section Running the Compiler
8169 To check for a syntax feature of the current language's (@pxref{Language
8170 Choice}) compiler, such as whether it recognizes a certain keyword, or
8171 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
8172 to compile a small program that uses that feature.
8174 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @
8175 @ovar{action-if-false})
8176 @acindex{COMPILE_IFELSE}
8177 Run the compiler and compilation flags of the current language
8178 (@pxref{Language Choice}) on the @var{input}, run the shell commands
8179 @var{action-if-true} on success, @var{action-if-false} otherwise. The
8180 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8182 It is customary to report unexpected failures with
8183 @code{AC_MSG_FAILURE}. This macro does not try to link; use
8184 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
8189 For tests in Erlang, the @var{input} must be the source code of a module named
8190 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
8191 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
8192 recommended to use @code{AC_LANG_PROGRAM} to specify the test program,
8193 to ensure that the Erlang module has the right name.
8195 @node Running the Linker
8196 @section Running the Linker
8198 To check for a library, a function, or a global variable, Autoconf
8199 @command{configure} scripts try to compile and link a small program that
8200 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
8201 @code{ar} on the C library to try to figure out which functions are
8202 available. Trying to link with the function is usually a more reliable
8203 approach because it avoids dealing with the variations in the options
8204 and output formats of @code{nm} and @code{ar} and in the location of the
8205 standard libraries. It also allows configuring for cross-compilation or
8206 checking a function's runtime behavior if needed. On the other hand,
8207 it can be slower than scanning the libraries once, but accuracy is more
8208 important than speed.
8210 @code{AC_LINK_IFELSE} is used to compile test programs to test for
8211 functions and global variables. It is also used by @code{AC_CHECK_LIB}
8212 to check for libraries (@pxref{Libraries}), by adding the library being
8213 checked for to @code{LIBS} temporarily and trying to link a small
8216 @anchor{AC_LINK_IFELSE}
8217 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @
8218 @ovar{action-if-false})
8219 @acindex{LINK_IFELSE}
8220 Run the compiler (and compilation flags) and the linker of the current
8221 language (@pxref{Language Choice}) on the @var{input}, run the shell
8222 commands @var{action-if-true} on success, @var{action-if-false}
8223 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
8226 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8227 current compilation flags.
8229 It is customary to report unexpected failures with
8230 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
8231 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8234 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8235 programs are interpreted and do not require linking.
8240 @section Checking Runtime Behavior
8242 Sometimes you need to find out how a system performs at runtime, such
8243 as whether a given function has a certain capability or bug. If you
8244 can, make such checks when your program runs instead of when it is
8245 configured. You can check for things like the machine's endianness when
8246 your program initializes itself.
8248 If you really need to test for a runtime behavior while configuring,
8249 you can write a test program to determine the result, and compile and
8250 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
8251 possible, because this prevents people from configuring your package for
8254 @anchor{AC_RUN_IFELSE}
8255 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @
8256 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8257 @acindex{RUN_IFELSE}
8258 If @var{program} compiles and links successfully and returns an exit
8259 status of 0 when executed, run shell commands @var{action-if-true}.
8260 Otherwise, run shell commands @var{action-if-false}.
8262 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8263 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8264 compilation flags of the current language (@pxref{Language Choice}).
8266 If the compiler being used does not produce executables that run on the
8267 system where @command{configure} is being run, then the test program is
8268 not run. If the optional shell commands @var{action-if-cross-compiling}
8269 are given, they are run instead. Otherwise, @command{configure} prints
8270 an error message and exits.
8272 In the @var{action-if-false} section, the failing exit status is
8273 available in the shell variable @samp{$?}. This exit status might be
8274 that of a failed compilation, or it might be that of a failed program
8277 It is customary to report unexpected failures with
8278 @code{AC_MSG_FAILURE}.
8281 Try to provide a pessimistic default value to use when cross-compiling
8282 makes runtime tests impossible. You do this by passing the optional
8283 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
8284 warning message when creating @command{configure} each time it
8285 encounters a call to @code{AC_RUN_IFELSE} with no
8286 @var{action-if-cross-compiling} argument given. You may ignore the
8287 warning, though users cannot configure your package for
8288 cross-compiling. A few of the macros distributed with Autoconf produce
8289 this warning message.
8291 To configure for cross-compiling you can also choose a value for those
8292 parameters based on the canonical system name (@pxref{Manual
8293 Configuration}). Alternatively, set up a test results cache file with
8294 the correct values for the host system (@pxref{Caching Results}).
8296 @ovindex cross_compiling
8297 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8298 in other macros, including a few of the ones that come with Autoconf,
8299 you can test whether the shell variable @code{cross_compiling} is set to
8300 @samp{yes}, and then use an alternate method to get the results instead
8301 of calling the macros.
8303 A C or C++ runtime test should be portable.
8304 @xref{Portable C and C++}.
8306 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8307 function: the given status code is used to determine the success of the test
8308 (status is @code{0}) or its failure (status is different than @code{0}), as
8309 explained above. It must be noted that data output through the standard output
8310 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8311 Therefore, if a test must output configuration information, it is recommended
8312 to create and to output data into the temporary file named @file{conftest.out},
8313 using the functions of module @code{file}. The @code{conftest.out} file is
8314 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8315 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR}
8319 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8323 [AC_LANG_PROGRAM([], [dnl
8324 file:write_file("conftest.out", code:lib_dir()),
8326 [echo "code:lib_dir() returned: `cat conftest.out`"],
8327 [AC_MSG_FAILURE([test Erlang program execution failed])])
8332 @section Systemology
8335 This section aims at presenting some systems and pointers to
8336 documentation. It may help you addressing particular problems reported
8339 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8340 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8343 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8344 contains a table correlating the features of various Posix-conforming
8345 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8346 simplified diagram of how many Unix systems were derived from each
8349 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8350 provides some variants of traditional implementations of Unix utilities.
8355 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8356 case-preserving, but case insensitive. This can cause nasty problems,
8357 since for instance the installation attempt for a package having an
8358 @file{INSTALL} file can result in @samp{make install} report that
8359 nothing was to be done!
8361 That's all dependent on whether the file system is a UFS (case
8362 sensitive) or HFS+ (case preserving). By default Apple wants you to
8363 install the OS on HFS+. Unfortunately, there are some pieces of
8364 software which really need to be built on UFS@. We may want to rebuild
8365 Darwin to have both UFS and HFS+ available (and put the /local/build
8368 @item @acronym{QNX} 4.25
8369 @cindex @acronym{QNX} 4.25
8370 @c FIXME: Please, if you feel like writing something more precise,
8371 @c it'd be great. In particular, I can't understand the difference with
8373 @acronym{QNX} is a realtime operating system running on Intel architecture
8374 meant to be scalable from the small embedded systems to the hundred
8375 processor super-computer. It claims to be Posix certified. More
8376 information is available on the
8377 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8381 @uref{http://h30097.www3.hp.com/@/docs/,
8382 Documentation of several versions of Tru64} is available in different
8385 @item Unix version 7
8386 @cindex Unix version 7
8388 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8389 time-sharing system'' but we use the more-common name ``Unix version 7''.
8390 Documentation is available in the
8391 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8392 Previous versions of Unix are called ``Unix version 6'', etc., but
8393 they were not as widely used.
8397 @node Multiple Cases
8398 @section Multiple Cases
8400 Some operations are accomplished in several possible ways, depending on
8401 the OS variant. Checking for them essentially requires a ``case
8402 statement''. Autoconf does not directly provide one; however, it is
8403 easy to simulate by using a shell variable to keep track of whether a
8404 way to perform the operation has been found yet.
8406 Here is an example that uses the shell variable @code{fstype} to keep
8407 track of whether the remaining cases need to be checked.
8411 AC_MSG_CHECKING([how to get file system type])
8413 # The order of these tests is important.
8414 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8415 #include <sys/fstyp.h>]])],
8416 [AC_DEFINE([FSTYPE_STATVFS], [1],
8417 [Define if statvfs exists.])
8419 if test $fstype = no; then
8420 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8421 #include <sys/fstyp.h>]])],
8422 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8423 [Define if USG statfs.])
8426 if test $fstype = no; then
8427 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8428 #include <sys/vmount.h>]])]),
8429 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8430 [Define if AIX statfs.])
8433 # (more cases omitted here)
8434 AC_MSG_RESULT([$fstype])
8438 @c ====================================================== Results of Tests.
8441 @chapter Results of Tests
8443 Once @command{configure} has determined whether a feature exists, what can
8444 it do to record that information? There are four sorts of things it can
8445 do: define a C preprocessor symbol, set a variable in the output files,
8446 save the result in a cache file for future @command{configure} runs, and
8447 print a message letting the user know the result of the test.
8450 * Defining Symbols:: Defining C preprocessor symbols
8451 * Setting Output Variables:: Replacing variables in output files
8452 * Special Chars in Variables:: Characters to beware of in variables
8453 * Caching Results:: Speeding up subsequent @command{configure} runs
8454 * Printing Messages:: Notifying @command{configure} users
8457 @node Defining Symbols
8458 @section Defining C Preprocessor Symbols
8460 A common action to take in response to a feature test is to define a C
8461 preprocessor symbol indicating the results of the test. That is done by
8462 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8464 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8465 into the output variable @code{DEFS}, which contains an option
8466 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8467 Autoconf version 1, there is no variable @code{DEFS} defined while
8468 @command{configure} is running. To check whether Autoconf macros have
8469 already defined a certain C preprocessor symbol, test the value of the
8470 appropriate cache variable, as in this example:
8473 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8474 [Define if vprintf exists.])])
8475 if test "$ac_cv_func_vprintf" != yes; then
8476 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8477 [Define if _doprnt exists.])])
8481 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8482 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8483 correct values into @code{#define} statements in a template file.
8484 @xref{Configuration Headers}, for more information about this kind of
8487 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8488 @defmacx AC_DEFINE (@var{variable})
8489 @cvindex @var{variable}
8491 Define @var{variable} to @var{value} (verbatim), by defining a C
8492 preprocessor macro for @var{variable}. @var{variable} should be a C
8493 identifier, optionally suffixed by a parenthesized argument list to
8494 define a C preprocessor macro with arguments. The macro argument list,
8495 if present, should be a comma-separated list of C identifiers, possibly
8496 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8497 @var{variable} should not contain comments, white space, trigraphs,
8498 backslash-newlines, universal character names, or non-@acronym{ASCII}
8501 @var{value} should not contain literal newlines, and if you are not
8502 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8503 characters, as @command{make} tends to eat them. To use a shell variable,
8504 use @code{AC_DEFINE_UNQUOTED} instead.
8505 @var{description} is only useful if you are using
8506 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8507 the generated @file{config.h.in} as the comment before the macro define.
8508 The following example defines the C preprocessor variable
8509 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8512 AC_DEFINE([EQUATION], ["$a > $b"],
8516 If neither @var{value} nor @var{description} are given, then
8517 @var{value} defaults to 1 instead of to the empty string. This is for
8518 backwards compatibility with older versions of Autoconf, but this usage
8519 is obsolescent and may be withdrawn in future versions of Autoconf.
8521 If the @var{variable} is a literal string, it is passed to
8522 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8524 If multiple @code{AC_DEFINE} statements are executed for the same
8525 @var{variable} name (not counting any parenthesized argument list),
8529 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8530 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8531 @acindex{DEFINE_UNQUOTED}
8532 @cvindex @var{variable}
8533 Like @code{AC_DEFINE}, but three shell expansions are
8534 performed---once---on @var{variable} and @var{value}: variable expansion
8535 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8536 (@samp{\}). Single and double quote characters in the value have no
8537 special meaning. Use this macro instead of @code{AC_DEFINE} when
8538 @var{variable} or @var{value} is a shell variable. Examples:
8541 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8542 [Configuration machine file.])
8543 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8544 [getgroups return type.])
8545 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8546 [Translated header name.])
8550 Due to a syntactical bizarreness of the Bourne shell, do not use
8551 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8552 calls from other macro calls or shell code; that can cause syntax errors
8553 in the resulting @command{configure} script. Use either blanks or
8554 newlines. That is, do this:
8557 AC_CHECK_HEADER([elf.h],
8558 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8565 AC_CHECK_HEADER([elf.h],
8566 [AC_DEFINE([SVR4], [1], [System V Release 4])
8567 LIBS="-lelf $LIBS"])
8574 AC_CHECK_HEADER([elf.h],
8575 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8578 @node Setting Output Variables
8579 @section Setting Output Variables
8580 @cindex Output variables
8582 Another way to record the results of tests is to set @dfn{output
8583 variables}, which are shell variables whose values are substituted into
8584 files that @command{configure} outputs. The two macros below create new
8585 output variables. @xref{Preset Output Variables}, for a list of output
8586 variables that are always available.
8588 @defmac AC_SUBST (@var{variable}, @ovar{value})
8590 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8591 substitute the variable @var{variable} into output files (typically one
8592 or more makefiles). This means that @code{AC_OUTPUT}
8593 replaces instances of @samp{@@@var{variable}@@} in input files with the
8594 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8595 is called. The value can contain any non-@code{NUL} character, including
8597 Variable occurrences should not overlap: e.g., an input file should
8598 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8600 The substituted value is not rescanned for more output variables;
8601 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8602 literally into the output file. (The algorithm uses the special marker
8603 @code{|#_!!_#|} internally, so neither the substituted value nor the
8604 output file may contain @code{|#_!!_#|}.)
8606 If @var{value} is given, in addition assign it to @var{variable}.
8608 The string @var{variable} is passed to @code{m4_pattern_allow}
8609 (@pxref{Forbidden Patterns}).
8612 @defmac AC_SUBST_FILE (@var{variable})
8613 @acindex{SUBST_FILE}
8614 Another way to create an output variable from a shell variable. Make
8615 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8616 named by shell variable @var{variable} into output files. This means
8617 that @code{AC_OUTPUT} replaces instances of
8618 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8619 with the contents of the file that the shell variable @var{variable}
8620 names when @code{AC_OUTPUT} is called. Set the variable to
8621 @file{/dev/null} for cases that do not have a file to insert.
8622 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8623 line by itself, optionally surrounded by spaces and tabs. The
8624 substitution replaces the whole line, including the spaces, tabs, and
8625 the terminating newline.
8627 This macro is useful for inserting makefile fragments containing
8628 special dependencies or other @code{make} directives for particular host
8629 or target types into makefiles. For example, @file{configure.ac}
8633 AC_SUBST_FILE([host_frag])
8634 host_frag=$srcdir/conf/sun4.mh
8638 and then a @file{Makefile.in} could contain:
8644 The string @var{variable} is passed to @code{m4_pattern_allow}
8645 (@pxref{Forbidden Patterns}).
8648 @cindex Precious Variable
8649 @cindex Variable, Precious
8650 Running @command{configure} in varying environments can be extremely
8651 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8652 ./configure}, then the cache, @file{config.h}, and many other output
8653 files depend upon @command{bizarre-cc} being the C compiler. If
8654 for some reason the user runs @command{./configure} again, or if it is
8655 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8656 and @pxref{config.status Invocation}), then the configuration can be
8657 inconsistent, composed of results depending upon two different
8660 Environment variables that affect this situation, such as @samp{CC}
8661 above, are called @dfn{precious variables}, and can be declared as such
8662 by @code{AC_ARG_VAR}.
8664 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8666 Declare @var{variable} is a precious variable, and include its
8667 @var{description} in the variable section of @samp{./configure --help}.
8669 Being precious means that
8672 @var{variable} is substituted via @code{AC_SUBST}.
8675 The value of @var{variable} when @command{configure} was launched is
8676 saved in the cache, including if it was not specified on the command
8677 line but via the environment. Indeed, while @command{configure} can
8678 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8679 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8680 which, unfortunately, is what most users do.
8682 We emphasize that it is the @emph{initial} value of @var{variable} which
8683 is saved, not that found during the execution of @command{configure}.
8684 Indeed, specifying @samp{./configure FOO=foo} and letting
8685 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8689 @var{variable} is checked for consistency between two
8690 @command{configure} runs. For instance:
8693 $ @kbd{./configure --silent --config-cache}
8694 $ @kbd{CC=cc ./configure --silent --config-cache}
8695 configure: error: `CC' was not set in the previous run
8696 configure: error: changes in the environment can compromise \
8698 configure: error: run `make distclean' and/or \
8699 `rm config.cache' and start over
8703 and similarly if the variable is unset, or if its content is changed.
8707 @var{variable} is kept during automatic reconfiguration
8708 (@pxref{config.status Invocation}) as if it had been passed as a command
8709 line argument, including when no cache is used:
8712 $ @kbd{CC=/usr/bin/cc ./configure var=raboof --silent}
8713 $ @kbd{./config.status --recheck}
8714 running CONFIG_SHELL=/bin/sh /bin/sh ./configure var=raboof \
8715 CC=/usr/bin/cc --no-create --no-recursion
8720 @node Special Chars in Variables
8721 @section Special Characters in Output Variables
8722 @cindex Output variables, special characters in
8724 Many output variables are intended to be evaluated both by
8725 @command{make} and by the shell. Some characters are expanded
8726 differently in these two contexts, so to avoid confusion these
8727 variables' values should not contain any of the following characters:
8730 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8733 Also, these variables' values should neither contain newlines, nor start
8734 with @samp{~}, nor contain white space or @samp{:} immediately followed
8735 by @samp{~}. The values can contain nonempty sequences of white space
8736 characters like tabs and spaces, but each such sequence might
8737 arbitrarily be replaced by a single space during substitution.
8739 These restrictions apply both to the values that @command{configure}
8740 computes, and to the values set directly by the user. For example, the
8741 following invocations of @command{configure} are problematic, since they
8742 attempt to use special characters within @code{CPPFLAGS} and white space
8743 within @code{$(srcdir)}:
8746 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8748 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8751 @node Caching Results
8752 @section Caching Results
8755 To avoid checking for the same features repeatedly in various
8756 @command{configure} scripts (or in repeated runs of one script),
8757 @command{configure} can optionally save the results of many checks in a
8758 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8759 runs with caching enabled and finds a cache file, it reads the results
8760 of previous runs from the cache and avoids rerunning those checks. As a
8761 result, @command{configure} can then run much faster than if it had to
8762 perform all of the checks every time.
8764 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8766 Ensure that the results of the check identified by @var{cache-id} are
8767 available. If the results of the check were in the cache file that was
8768 read, and @command{configure} was not given the @option{--quiet} or
8769 @option{--silent} option, print a message saying that the result was
8770 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8771 the shell commands are run to determine the value, the value is
8772 saved in the cache file just before @command{configure} creates its output
8773 files. @xref{Cache Variable Names}, for how to choose the name of the
8774 @var{cache-id} variable.
8776 The @var{commands-to-set-it} @emph{must have no side effects} except for
8777 setting the variable @var{cache-id}, see below.
8780 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @
8781 @var{commands-to-set-it})
8782 @acindex{CACHE_CHECK}
8783 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8784 messages. This macro provides a convenient shorthand for the most
8785 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8786 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8787 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8789 The @var{commands-to-set-it} @emph{must have no side effects} except for
8790 setting the variable @var{cache-id}, see below.
8793 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8794 @code{AC_CACHE_CHECK}, because people are tempted to call
8795 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8796 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8797 @code{AC_DEFINE}, by examining the value of the cache variable. For
8798 instance, the following macro is broken:
8802 AC_DEFUN([AC_SHELL_TRUE],
8803 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8804 [my_cv_shell_true_works=no
8805 (true) 2>/dev/null && my_cv_shell_true_works=yes
8806 if test "$my_cv_shell_true_works" = yes; then
8807 AC_DEFINE([TRUE_WORKS], [1],
8808 [Define if `true(1)' works properly.])
8815 This fails if the cache is enabled: the second time this macro is run,
8816 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8821 AC_DEFUN([AC_SHELL_TRUE],
8822 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8823 [my_cv_shell_true_works=no
8824 (true) 2>/dev/null && my_cv_shell_true_works=yes])
8825 if test "$my_cv_shell_true_works" = yes; then
8826 AC_DEFINE([TRUE_WORKS], [1],
8827 [Define if `true(1)' works properly.])
8833 Also, @var{commands-to-set-it} should not print any messages, for
8834 example with @code{AC_MSG_CHECKING}; do that before calling
8835 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8836 the results of the check are retrieved from the cache or determined by
8837 running the shell commands.
8840 * Cache Variable Names:: Shell variables used in caches
8841 * Cache Files:: Files @command{configure} uses for caching
8842 * Cache Checkpointing:: Loading and saving the cache file
8845 @node Cache Variable Names
8846 @subsection Cache Variable Names
8847 @cindex Cache variable
8849 The names of cache variables should have the following format:
8852 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8856 for example, @samp{ac_cv_header_stat_broken} or
8857 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8860 @item @var{package-prefix}
8861 An abbreviation for your package or organization; the same prefix you
8862 begin local Autoconf macros with, except lowercase by convention.
8863 For cache values used by the distributed Autoconf macros, this value is
8867 Indicates that this shell variable is a cache value. This string
8868 @emph{must} be present in the variable name, including the leading
8871 @item @var{value-type}
8872 A convention for classifying cache values, to produce a rational naming
8873 system. The values used in Autoconf are listed in @ref{Macro Names}.
8875 @item @var{specific-value}
8876 Which member of the class of cache values this test applies to.
8877 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8878 output variable (@samp{INSTALL}).
8880 @item @var{additional-options}
8881 Any particular behavior of the specific member that this test applies to.
8882 For example, @samp{broken} or @samp{set}. This part of the name may
8883 be omitted if it does not apply.
8886 The values assigned to cache variables may not contain newlines.
8887 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8888 names of files or functions; so this is not an important restriction.
8891 @subsection Cache Files
8893 A cache file is a shell script that caches the results of configure
8894 tests run on one system so they can be shared between configure scripts
8895 and configure runs. It is not useful on other systems. If its contents
8896 are invalid for some reason, the user may delete or edit it.
8898 By default, @command{configure} uses no cache file,
8899 to avoid problems caused by accidental
8900 use of stale cache files.
8902 To enable caching, @command{configure} accepts @option{--config-cache} (or
8903 @option{-C}) to cache results in the file @file{config.cache}.
8904 Alternatively, @option{--cache-file=@var{file}} specifies that
8905 @var{file} be the cache file. The cache file is created if it does not
8906 exist already. When @command{configure} calls @command{configure} scripts in
8907 subdirectories, it uses the @option{--cache-file} argument so that they
8908 share the same cache. @xref{Subdirectories}, for information on
8909 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8911 @file{config.status} only pays attention to the cache file if it is
8912 given the @option{--recheck} option, which makes it rerun
8913 @command{configure}.
8915 It is wrong to try to distribute cache files for particular system types.
8916 There is too much room for error in doing that, and too much
8917 administrative overhead in maintaining them. For any features that
8918 can't be guessed automatically, use the standard method of the canonical
8919 system type and linking files (@pxref{Manual Configuration}).
8921 The site initialization script can specify a site-wide cache file to
8922 use, instead of the usual per-program cache. In this case, the cache
8923 file gradually accumulates information whenever someone runs a new
8924 @command{configure} script. (Running @command{configure} merges the new cache
8925 results with the existing cache file.) This may cause problems,
8926 however, if the system configuration (e.g., the installed libraries or
8927 compilers) changes and the stale cache file is not deleted.
8929 @node Cache Checkpointing
8930 @subsection Cache Checkpointing
8932 If your configure script, or a macro called from @file{configure.ac}, happens
8933 to abort the configure process, it may be useful to checkpoint the cache
8934 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8935 reduces the amount of time it takes to rerun the configure script with
8936 (hopefully) the error that caused the previous abort corrected.
8938 @c FIXME: Do we really want to document this guy?
8939 @defmac AC_CACHE_LOAD
8940 @acindex{CACHE_LOAD}
8941 Loads values from existing cache file, or creates a new cache file if a
8942 cache file is not found. Called automatically from @code{AC_INIT}.
8945 @defmac AC_CACHE_SAVE
8946 @acindex{CACHE_SAVE}
8947 Flushes all cached values to the cache file. Called automatically from
8948 @code{AC_OUTPUT}, but it can be quite useful to call
8949 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8955 @r{ @dots{} AC_INIT, etc. @dots{}}
8957 # Checks for programs.
8960 @r{ @dots{} more program checks @dots{}}
8965 # Checks for libraries.
8966 AC_CHECK_LIB([nsl], [gethostbyname])
8967 AC_CHECK_LIB([socket], [connect])
8968 @r{ @dots{} more lib checks @dots{}}
8973 # Might abort@dots{}
8974 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8975 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8977 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8980 @node Printing Messages
8981 @section Printing Messages
8982 @cindex Messages, from @command{configure}
8984 @command{configure} scripts need to give users running them several kinds
8985 of information. The following macros print messages in ways appropriate
8986 for each kind. The arguments to all of them get enclosed in shell
8987 double quotes, so the shell performs variable and back-quote
8988 substitution on them.
8990 These macros are all wrappers around the @command{echo} shell command.
8991 They direct output to the appropriate file descriptor (@pxref{File
8992 Descriptor Macros}).
8993 @command{configure} scripts should rarely need to run @command{echo} directly
8994 to print messages for the user. Using these macros makes it easy to
8995 change how and when each kind of message is printed; such changes need
8996 only be made to the macro definitions and all the callers change
8999 To diagnose static issues, i.e., when @command{autoconf} is run, see
9000 @ref{Reporting Messages}.
9002 @defmac AC_MSG_CHECKING (@var{feature-description})
9003 @acindex{MSG_CHECKING}
9004 Notify the user that @command{configure} is checking for a particular
9005 feature. This macro prints a message that starts with @samp{checking }
9006 and ends with @samp{...} and no newline. It must be followed by a call
9007 to @code{AC_MSG_RESULT} to print the result of the check and the
9008 newline. The @var{feature-description} should be something like
9009 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
9012 This macro prints nothing if @command{configure} is run with the
9013 @option{--quiet} or @option{--silent} option.
9016 @anchor{AC_MSG_RESULT}
9017 @defmac AC_MSG_RESULT (@var{result-description})
9018 @acindex{MSG_RESULT}
9019 Notify the user of the results of a check. @var{result-description} is
9020 almost always the value of the cache variable for the check, typically
9021 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
9022 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
9023 the completion of the message printed by the call to
9024 @code{AC_MSG_CHECKING}.
9026 This macro prints nothing if @command{configure} is run with the
9027 @option{--quiet} or @option{--silent} option.
9030 @anchor{AC_MSG_NOTICE}
9031 @defmac AC_MSG_NOTICE (@var{message})
9032 @acindex{MSG_NOTICE}
9033 Deliver the @var{message} to the user. It is useful mainly to print a
9034 general description of the overall purpose of a group of feature checks,
9038 AC_MSG_NOTICE([checking if stack overflow is detectable])
9041 This macro prints nothing if @command{configure} is run with the
9042 @option{--quiet} or @option{--silent} option.
9045 @anchor{AC_MSG_ERROR}
9046 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
9048 Notify the user of an error that prevents @command{configure} from
9049 completing. This macro prints an error message to the standard error
9050 output and exits @command{configure} with @var{exit-status} (1 by default).
9051 @var{error-description} should be something like @samp{invalid value
9054 The @var{error-description} should start with a lower-case letter, and
9055 ``cannot'' is preferred to ``can't''.
9058 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
9059 @acindex{MSG_FAILURE}
9060 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
9061 prevents @command{configure} from completing @emph{and} that additional
9062 details are provided in @file{config.log}. This is typically used when
9063 abnormal results are found during a compilation.
9066 @anchor{AC_MSG_WARN}
9067 @defmac AC_MSG_WARN (@var{problem-description})
9069 Notify the @command{configure} user of a possible problem. This macro
9070 prints the message to the standard error output; @command{configure}
9071 continues running afterward, so macros that call @code{AC_MSG_WARN} should
9072 provide a default (back-up) behavior for the situations they warn about.
9073 @var{problem-description} should be something like @samp{ln -s seems to
9079 @c ====================================================== Programming in M4.
9081 @node Programming in M4
9082 @chapter Programming in M4
9085 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
9086 convenient macros for pure M4 programming, and @dfn{M4sh}, which
9087 provides macros dedicated to shell script generation.
9089 As of this version of Autoconf, these two layers are still experimental,
9090 and their interface might change in the future. As a matter of fact,
9091 @emph{anything that is not documented must not be used}.
9094 * M4 Quotation:: Protecting macros from unwanted expansion
9095 * Using autom4te:: The Autoconf executables backbone
9096 * Programming in M4sugar:: Convenient pure M4 macros
9097 * Programming in M4sh:: Common shell Constructs
9098 * File Descriptor Macros:: File descriptor macros for input and output
9102 @section M4 Quotation
9103 @cindex M4 quotation
9106 The most common problem with existing macros is an improper quotation.
9107 This section, which users of Autoconf can skip, but which macro writers
9108 @emph{must} read, first justifies the quotation scheme that was chosen
9109 for Autoconf and then ends with a rule of thumb. Understanding the
9110 former helps one to follow the latter.
9113 * Active Characters:: Characters that change the behavior of M4
9114 * One Macro Call:: Quotation and one macro call
9115 * Quoting and Parameters:: M4 vs. shell parameters
9116 * Quotation and Nested Macros:: Macros calling macros
9117 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
9118 * Quadrigraphs:: Another way to escape special characters
9119 * Quotation Rule Of Thumb:: One parenthesis, one quote
9122 @node Active Characters
9123 @subsection Active Characters
9125 To fully understand where proper quotation is important, you first need
9126 to know what the special characters are in Autoconf: @samp{#} introduces
9127 a comment inside which no macro expansion is performed, @samp{,}
9128 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
9129 @samp{(} and @samp{)} (which M4 tries to match by pairs), and finally
9130 @samp{$} inside a macro definition.
9132 In order to understand the delicate case of macro calls, we first have
9133 to present some obvious failures. Below they are ``obvious-ified'',
9134 but when you find them in real life, they are usually in disguise.
9136 Comments, introduced by a hash and running up to the newline, are opaque
9137 tokens to the top level: active characters are turned off, and there is
9141 # define([def], ine)
9142 @result{}# define([def], ine)
9145 Each time there can be a macro expansion, there is a quotation
9146 expansion, i.e., one level of quotes is stripped:
9152 @result{}int tab[10];
9155 Without this in mind, the reader might try hopelessly to use her macro
9159 define([array], [int tab[10];])
9167 How can you correctly output the intended results@footnote{Using
9171 @node One Macro Call
9172 @subsection One Macro Call
9174 Let's proceed on the interaction between active characters and macros
9175 with this small macro, which just returns its first argument:
9182 The two pairs of quotes above are not part of the arguments of
9183 @code{define}; rather, they are understood by the top level when it
9184 tries to find the arguments of @code{define}. Therefore, assuming
9185 @code{car} is not already defined, it is equivalent to write:
9192 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
9193 quotes, it is bad practice for Autoconf macros which must both be more
9194 robust and also advocate perfect style.
9196 At the top level, there are only two possibilities: either you
9202 [car(foo, bar, baz)]
9203 @result{}car(foo, bar, baz)
9206 Let's pay attention to the special characters:
9210 @error{}EOF in argument list
9213 The closing parenthesis is hidden in the comment; with a hypothetical
9214 quoting, the top level understood it this way:
9221 Proper quotation, of course, fixes the problem:
9228 Here are more examples:
9251 @node Quoting and Parameters
9254 When M4 encounters @samp{$} within a macro definition, followed
9255 immediately by a character it recognizes (@samp{0}@dots{}@samp{9},
9256 @samp{#}, @samp{@@}, or @samp{*}), it will perform M4 parameter
9257 expansion. This happens regardless of how many layers of quotes the
9258 parameter expansion is nested within, or even if it occurs in text that
9259 will be rescanned as a comment.
9262 define([none], [$1])
9264 define([one], [[$1]])
9266 define([two], [[[$1]]])
9268 define([comment], [# $1])
9270 define([active], [ACTIVE])
9282 On the other hand, since autoconf generates shell code, you often want
9283 to output shell variable expansion, rather than performing M4 parameter
9284 expansion. To do this, you must use M4 quoting to separate the @samp{$}
9285 from the next character in the definition of your macro. If the macro
9286 definition occurs in single-quoted text, then insert another level of
9287 quoting; if the usage is already inside a double-quoted string, then
9288 split it into concatenated strings.
9291 define([single], [a single-quoted $[]1 definition])
9293 define([double], [[a double-quoted $][1 definition]])
9296 @result{}a single-quoted $1 definition
9298 @result{}a double-quoted $1 definition
9301 Posix states that M4 implementations are free to provide implementation
9302 extensions when @samp{$@{} is encountered in a macro definition.
9303 Autoconf reserves the longer sequence @samp{$@{@{} for use with planned
9304 extensions that will be available in the future @acronym{GNU} M4 2.0,
9305 but guarantees that all other instances of @samp{$@{} will be output
9306 literally. Therefore, this idiom can also be used to output shell code
9307 parameter references:
9310 define([first], [$@{1@}])first
9314 Posix also states that @samp{$11} should expand to the first parameter
9315 concatenated with a literal @samp{1}, although some versions of
9316 @acronym{GNU} M4 expand the eleventh parameter instead. For
9317 portability, you should only use single-digit M4 parameter expansion.
9319 With this in mind, we can explore the cases where macros invoke
9322 @node Quotation and Nested Macros
9323 @subsection Quotation and Nested Macros
9325 The examples below use the following macros:
9329 define([active], [ACT, IVE])
9330 define([array], [int tab[10]])
9333 Each additional embedded macro call introduces other possible
9334 interesting quotations:
9345 In the first case, the top level looks for the arguments of @code{car},
9346 and finds @samp{active}. Because M4 evaluates its arguments
9347 before applying the macro, @samp{active} is expanded, which results in:
9355 In the second case, the top level gives @samp{active} as first and only
9356 argument of @code{car}, which results in:
9364 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9365 In the third case, @code{car} receives @samp{[active]}, which results in:
9373 exactly as we already saw above.
9375 The example above, applied to a more realistic example, gives:
9382 car([[int tab[10];]])
9383 @result{}int tab[10];
9387 Huh? The first case is easily understood, but why is the second wrong,
9388 and the third right? To understand that, you must know that after
9389 M4 expands a macro, the resulting text is immediately subjected
9390 to macro expansion and quote removal. This means that the quote removal
9391 occurs twice---first before the argument is passed to the @code{car}
9392 macro, and second after the @code{car} macro expands to the first
9395 As the author of the Autoconf macro @code{car}, you then consider it to
9396 be incorrect that your users have to double-quote the arguments of
9397 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9401 define([qar], [[$1]])
9405 and check that @code{qar} is properly fixed:
9409 @result{}int tab[10];
9413 Ahhh! That's much better.
9415 But note what you've done: now that the result of @code{qar} is always
9416 a literal string, the only time a user can use nested macros is if she
9417 relies on an @emph{unquoted} macro call:
9427 leaving no way for her to reproduce what she used to do with @code{car}:
9435 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9439 define([my_includes], [#include <stdio.h>])
9441 @result{}#include <stdio.h>
9443 @error{}EOF in argument list
9446 This macro, @code{qar}, because it double quotes its arguments, forces
9447 its users to leave their macro calls unquoted, which is dangerous.
9448 Commas and other active symbols are interpreted by M4 before
9449 they are given to the macro, often not in the way the users expect.
9450 Also, because @code{qar} behaves differently from the other macros,
9451 it's an exception that should be avoided in Autoconf.
9453 @node Changequote is Evil
9454 @subsection @code{changequote} is Evil
9455 @cindex @code{changequote}
9457 The temptation is often high to bypass proper quotation, in particular
9458 when it's late at night. Then, many experienced Autoconf hackers
9459 finally surrender to the dark side of the force and use the ultimate
9460 weapon: @code{changequote}.
9462 The M4 builtin @code{changequote} belongs to a set of primitives that
9463 allow one to adjust the syntax of the language to adjust it to one's
9464 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9465 quotes, but in the context of shell programming (and actually of most
9466 programming languages), that's about the worst choice one can make:
9467 because of strings and back-quoted expressions in shell code (such as
9468 @samp{'this'} and @samp{`that`}), and because of literal characters in usual
9469 programming languages (as in @samp{'0'}), there are many unbalanced
9470 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9471 not impossible. In order to make M4 useful in such a context, its
9472 designers have equipped it with @code{changequote}, which makes it
9473 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9474 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9475 because they are unlikely characters, but @emph{because they are
9476 characters unlikely to be unbalanced}.
9478 There are other magic primitives, such as @code{changecom} to specify
9479 what syntactic forms are comments (it is common to see
9480 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9481 @code{changeword} and @code{changesyntax} to change other syntactic
9482 details (such as the character to denote the @var{n}th argument, @samp{$} by
9483 default, the parenthesis around arguments, etc.).
9485 These primitives are really meant to make M4 more useful for specific
9486 domains: they should be considered like command line options:
9487 @option{--quotes}, @option{--comments}, @option{--words}, and
9488 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9489 it makes M4 libraries self contained (no need for additional options).
9491 There lies the problem@enddots{}
9495 The problem is that it is then tempting to use them in the middle of an
9496 M4 script, as opposed to its initialization. This, if not carefully
9497 thought out, can lead to disastrous effects: @emph{you are changing the
9498 language in the middle of the execution}. Changing and restoring the
9499 syntax is often not enough: if you happened to invoke macros in between,
9500 these macros are lost, as the current syntax is probably not
9501 the one they were implemented with.
9503 @c FIXME: I've been looking for a short, real case example, but I
9508 @subsection Quadrigraphs
9509 @cindex quadrigraphs
9510 @cindex @samp{@@S|@@}
9511 @cindex @samp{@@&t@@}
9512 @c Info cannot handle `:' in index entries.
9513 @c @cindex @samp{@@<:@@}
9514 @c @cindex @samp{@@:>@@}
9515 @c @cindex @samp{@@%:@@}
9517 When writing an Autoconf macro you may occasionally need to generate
9518 special characters that are difficult to express with the standard
9519 Autoconf quoting rules. For example, you may need to output the regular
9520 expression @samp{[^[]}, which matches any character other than @samp{[}.
9521 This expression contains unbalanced brackets so it cannot be put easily
9524 You can work around this problem by using one of the following
9540 Quadrigraphs are replaced at a late stage of the translation process,
9541 after @command{m4} is run, so they do not get in the way of M4 quoting.
9542 For example, the string @samp{^@@<:@@}, independently of its quotation,
9543 appears as @samp{^[} in the output.
9545 The empty quadrigraph can be used:
9548 @item to mark trailing spaces explicitly
9550 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9552 @item to produce other quadrigraphs
9554 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9556 @item to escape @emph{occurrences} of forbidden patterns
9558 For instance you might want to mention @code{AC_FOO} in a comment, while
9559 still being sure that @command{autom4te} still catches unexpanded
9560 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9563 The name @samp{@@&t@@} was suggested by Paul Eggert:
9566 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9567 own invention, but the @samp{t} came from the source code of the
9568 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9569 and which used @samp{mt} to denote the empty string. In C, it would
9570 have looked like something like:
9573 char const mt[] = "";
9577 but of course the source code was written in Algol 68.
9579 I don't know where he got @samp{mt} from: it could have been his own
9580 invention, and I suppose it could have been a common pun around the
9581 Cambridge University computer lab at the time.
9584 @node Quotation Rule Of Thumb
9585 @subsection Quotation Rule Of Thumb
9587 To conclude, the quotation rule of thumb is:
9589 @center @emph{One pair of quotes per pair of parentheses.}
9591 Never over-quote, never under-quote, in particular in the definition of
9592 macros. In the few places where the macros need to use brackets
9593 (usually in C program text or regular expressions), properly quote
9594 @emph{the arguments}!
9596 It is common to read Autoconf programs with snippets like:
9600 changequote(<<, >>)dnl
9602 #ifndef tzname /* For SGI. */
9603 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9605 changequote([, ])dnl
9606 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9610 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9611 double quoting, so you just need:
9616 #ifndef tzname /* For SGI. */
9617 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9620 [ac_cv_var_tzname=yes],
9621 [ac_cv_var_tzname=no])
9625 The M4-fluent reader might note that these two examples are rigorously
9626 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9627 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9628 quotes are not part of the arguments!
9630 Simplified, the example above is just doing this:
9633 changequote(<<, >>)dnl
9635 changequote([, ])dnl
9645 With macros that do not double quote their arguments (which is the
9646 rule), double-quote the (risky) literals:
9649 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9651 #ifndef tzname /* For SGI. */
9652 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9654 [atoi (*tzname);])],
9655 [ac_cv_var_tzname=yes],
9656 [ac_cv_var_tzname=no])
9659 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9660 should be using @code{AC_LINK_IFELSE} instead.
9662 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9663 where quoting does not suffice.
9665 When you create a @command{configure} script using newly written macros,
9666 examine it carefully to check whether you need to add more quotes in
9667 your macros. If one or more words have disappeared in the M4
9668 output, you need more quotes. When in doubt, quote.
9670 However, it's also possible to put on too many layers of quotes. If
9671 this happens, the resulting @command{configure} script may contain
9672 unexpanded macros. The @command{autoconf} program checks for this problem
9673 by looking for the string @samp{AC_} in @file{configure}. However, this
9674 heuristic does not work in general: for example, it does not catch
9675 overquoting in @code{AC_DEFINE} descriptions.
9678 @c ---------------------------------------- Using autom4te
9680 @node Using autom4te
9681 @section Using @command{autom4te}
9683 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9684 to Autoconf per se, heavily rely on M4. All these different uses
9685 revealed common needs factored into a layer over M4:
9686 @command{autom4te}@footnote{
9688 Yet another great name from Lars J. Aas.
9692 @command{autom4te} is a preprocessor that is like @command{m4}.
9693 It supports M4 extensions designed for use in tools like Autoconf.
9696 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9697 * Customizing autom4te:: Customizing the Autoconf package
9700 @node autom4te Invocation
9701 @subsection Invoking @command{autom4te}
9703 The command line arguments are modeled after M4's:
9706 autom4te @var{options} @var{files}
9711 where the @var{files} are directly passed to @command{m4}. By default,
9712 @acronym{GNU} M4 is found during configuration, but the environment
9714 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9715 to the regular expansion, it handles the replacement of the quadrigraphs
9716 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9717 output. It supports an extended syntax for the @var{files}:
9720 @item @var{file}.m4f
9721 This file is an M4 frozen file. Note that @emph{all the previous files
9722 are ignored}. See the option @option{--melt} for the rationale.
9725 If found in the library path, the @var{file} is included for expansion,
9726 otherwise it is ignored instead of triggering a failure.
9731 Of course, it supports the Autoconf common subset of options:
9736 Print a summary of the command line options and exit.
9740 Print the version number of Autoconf and exit.
9744 Report processing steps.
9748 Don't remove the temporary files and be even more verbose.
9750 @item --include=@var{dir}
9752 Also look for input files in @var{dir}. Multiple invocations
9755 @item --output=@var{file}
9756 @itemx -o @var{file}
9757 Save output (script or trace) to @var{file}. The file @option{-} stands
9758 for the standard output.
9763 As an extension of @command{m4}, it includes the following options:
9766 @item --warnings=@var{category}
9767 @itemx -W @var{category}
9769 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9770 Report the warnings related to @var{category} (which can actually be a
9771 comma separated list). @xref{Reporting Messages}, macro
9772 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9777 report all the warnings
9783 treats warnings as errors
9785 @item no-@var{category}
9786 disable warnings falling into @var{category}
9789 Warnings about @samp{syntax} are enabled by default, and the environment
9790 variable @env{WARNINGS}, a comma separated list of categories, is
9791 honored. @samp{autom4te -W @var{category}} actually
9792 behaves as if you had run:
9795 autom4te --warnings=syntax,$WARNINGS,@var{category}
9799 For example, if you want to disable defaults and @env{WARNINGS}
9800 of @command{autom4te}, but enable the warnings about obsolete
9801 constructs, you would use @option{-W none,obsolete}.
9804 @cindex Macro invocation stack
9805 @command{autom4te} displays a back trace for errors, but not for
9806 warnings; if you want them, just pass @option{-W error}.
9810 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9811 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9812 are executed only when the files are frozen, typically
9813 @code{m4_define}. For instance, running:
9816 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9820 is roughly equivalent to running:
9823 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9830 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9837 m4 --reload-state=4.m4f input.m4
9842 Produce a frozen state file. @command{autom4te} freezing is stricter
9843 than M4's: it must produce no warnings, and no output other than empty
9844 lines (a line with white space is @emph{not} empty) and comments
9845 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9846 this option takes no argument:
9849 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9856 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9859 @item --mode=@var{octal-mode}
9860 @itemx -m @var{octal-mode}
9861 Set the mode of the non-traces output to @var{octal-mode}; by default
9867 @cindex @file{autom4te.cache}
9868 As another additional feature over @command{m4}, @command{autom4te}
9869 caches its results. @acronym{GNU} M4 is able to produce a regular
9870 output and traces at the same time. Traces are heavily used in the
9871 @acronym{GNU} Build System: @command{autoheader} uses them to build
9872 @file{config.h.in}, @command{autoreconf} to determine what
9873 @acronym{GNU} Build System components are used, @command{automake} to
9874 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9875 traces are cached while performing regular expansion,
9876 and conversely. This cache is (actually, the caches are) stored in
9877 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9878 at any moment (especially if for some reason @command{autom4te}
9879 considers it is trashed).
9882 @item --cache=@var{directory}
9883 @itemx -C @var{directory}
9884 Specify the name of the directory where the result should be cached.
9885 Passing an empty value disables caching. Be sure to pass a relative
9886 file name, as for the time being, global caches are not supported.
9889 Don't cache the results.
9893 If a cache is used, consider it obsolete (but update it anyway).
9898 Because traces are so important to the @acronym{GNU} Build System,
9899 @command{autom4te} provides high level tracing features as compared to
9900 M4, and helps exploiting the cache:
9903 @item --trace=@var{macro}[:@var{format}]
9904 @itemx -t @var{macro}[:@var{format}]
9905 Trace the invocations of @var{macro} according to the @var{format}.
9906 Multiple @option{--trace} arguments can be used to list several macros.
9907 Multiple @option{--trace} arguments for a single macro are not
9908 cumulative; instead, you should just make @var{format} as long as
9911 The @var{format} is a regular string, with newlines if desired, and
9912 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9913 use the following special escapes:
9917 The character @samp{$}.
9920 The file name from which @var{macro} is called.
9923 The line number from which @var{macro} is called.
9926 The depth of the @var{macro} call. This is an M4 technical detail that
9927 you probably don't want to know about.
9930 The name of the @var{macro}.
9933 The @var{num}th argument of the call to @var{macro}.
9937 @itemx $@{@var{separator}@}@@
9938 All the arguments passed to @var{macro}, separated by the character
9939 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9940 argument is quoted, i.e., enclosed in a pair of square brackets.
9944 @itemx $@{@var{separator}@}*
9945 As above, but the arguments are not quoted.
9949 @itemx $@{@var{separator}@}%
9950 As above, but the arguments are not quoted, all new line characters in
9951 the arguments are smashed, and the default separator is @samp{:}.
9953 The escape @samp{$%} produces single-line trace outputs (unless you put
9954 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9958 @xref{autoconf Invocation}, for examples of trace uses.
9960 @item --preselect=@var{macro}
9961 @itemx -p @var{macro}
9962 Cache the traces of @var{macro}, but do not enable traces. This is
9963 especially important to save CPU cycles in the future. For instance,
9964 when invoked, @command{autoconf} preselects all the macros that
9965 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9966 trace, so that running @command{m4} is not needed to trace them: the
9967 cache suffices. This results in a huge speed-up.
9972 @cindex Autom4te Library
9973 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9974 libraries}. They consists in a powerful yet extremely simple feature:
9975 sets of combined command line arguments:
9978 @item --language=@var{language}
9979 @itemx -l @var{language}
9980 Use the @var{language} Autom4te library. Current languages include:
9984 create M4sugar output.
9987 create M4sh executable shell scripts.
9990 create Autotest executable test suites.
9992 @item Autoconf-without-aclocal-m4
9993 create Autoconf executable configure scripts without
9994 reading @file{aclocal.m4}.
9997 create Autoconf executable configure scripts. This language inherits
9998 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9999 additionally reads @file{aclocal.m4}.
10002 @item --prepend-include=@var{dir}
10004 Prepend directory @var{dir} to the search path. This is used to include
10005 the language-specific files before any third-party macros.
10009 @cindex @file{autom4te.cfg}
10010 As an example, if Autoconf is installed in its default location,
10011 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
10012 strictly equivalent to the command:
10015 autom4te --prepend-include /usr/local/share/autoconf \
10016 m4sugar/m4sugar.m4f --warnings syntax foo.m4
10020 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
10021 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
10025 autom4te --prepend-include /usr/local/share/autoconf \
10026 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
10030 The definition of the languages is stored in @file{autom4te.cfg}.
10032 @node Customizing autom4te
10033 @subsection Customizing @command{autom4te}
10035 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
10036 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
10037 as found in the directory from which @command{autom4te} is run). The
10038 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
10039 then @file{./.autom4te.cfg}, and finally the command line arguments.
10041 In these text files, comments are introduced with @code{#}, and empty
10042 lines are ignored. Customization is performed on a per-language basis,
10043 wrapped in between a @samp{begin-language: "@var{language}"},
10044 @samp{end-language: "@var{language}"} pair.
10046 Customizing a language stands for appending options (@pxref{autom4te
10047 Invocation}) to the current definition of the language. Options, and
10048 more generally arguments, are introduced by @samp{args:
10049 @var{arguments}}. You may use the traditional shell syntax to quote the
10052 As an example, to disable Autoconf caches (@file{autom4te.cache})
10053 globally, include the following lines in @file{~/.autom4te.cfg}:
10056 ## ------------------ ##
10057 ## User Preferences. ##
10058 ## ------------------ ##
10060 begin-language: "Autoconf-without-aclocal-m4"
10062 end-language: "Autoconf-without-aclocal-m4"
10066 @node Programming in M4sugar
10067 @section Programming in M4sugar
10070 M4 by itself provides only a small, but sufficient, set of all-purpose
10071 macros. M4sugar introduces additional generic macros. Its name was
10072 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
10076 * Redefined M4 Macros:: M4 builtins changed in M4sugar
10077 * Conditional constructs:: Conditions in M4
10078 * Looping constructs:: Iteration in M4
10079 * Evaluation Macros:: More quotation and evaluation control
10080 * Text processing Macros:: String manipulation in M4
10081 * Forbidden Patterns:: Catching unexpanded macros
10084 @node Redefined M4 Macros
10085 @subsection Redefined M4 Macros
10088 @msindex{changecom}
10089 @msindex{changequote}
10090 @msindex{debugfile}
10091 @msindex{debugmode}
10114 With a few exceptions, all the M4 native macros are moved in the
10115 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
10116 @code{m4_define} etc.
10118 Some M4 macros are redefined, and are slightly incompatible with their
10123 This macro kept its original name: no @code{m4_dnl} is defined.
10126 @defmac m4_defn (@var{macro})
10128 Unlike the M4 builtin, this macro fails if @var{macro} is not
10129 defined. See @code{m4_undefine}.
10132 @c FIXME: Need to document m4_divert, m4_undivert, m4_divert_push,
10133 @c m4_divert_pop, m4_divert_text, m4_divert_once
10135 @defmac m4_exit (@var{exit-status})
10137 This macro corresponds to @code{m4exit}.
10140 @defmac m4_if (@var{comment})
10141 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
10142 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
10144 This macro corresponds to @code{ifelse}. @var{string-1} and
10145 @var{string-2} are compared literally, so usually one of the two
10146 arguments is passed unquoted. @xref{Conditional constructs}, for more
10147 conditional idioms.
10150 @defmac m4_include (@var{file})
10151 @defmacx m4_sinclude (@var{file})
10154 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
10157 @defmac m4_mkstemp (@var{template})
10158 @defmacx m4_maketemp (@var{template})
10161 Posix requires @code{maketemp} to replace the trailing @samp{X}
10162 characters in @var{template} with the process id, without regards to the
10163 existence of a file by that name, but this a security hole. When this
10164 was pointed out to the Posix folks, they agreed to invent a new macro
10165 @code{mkstemp} that always creates a uniquely named file, but not all
10166 versions of @acronym{GNU} M4 support the new macro. In M4sugar,
10167 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
10168 and both have the secure semantics regardless of which macro the
10169 underlying M4 provides.
10172 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
10173 @msindex{bpatsubst}
10174 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
10175 is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
10176 released and supports extended regular expression syntax.
10179 @defmac m4_popdef (@var{macro})
10181 Unlike the M4 builtin, this macro fails if @var{macro} is not
10182 defined. See @code{m4_undefine}.
10185 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
10187 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
10188 is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
10189 released and supports extended regular expression syntax.
10192 @defmac m4_undefine (@var{macro})
10194 Unlike the M4 builtin, this macro fails if @var{macro} is not
10198 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
10202 to recover the behavior of the builtin.
10205 @defmac m4_wrap (@var{text})
10207 This macro corresponds to @code{m4wrap}.
10209 Posix requires arguments of multiple @code{m4wrap} calls to be
10210 reprocessed at @acronym{EOF} in the same order as the original calls.
10211 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
10212 reverse order. Your code should not depend on the order.
10214 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
10215 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
10216 arguments with intervening spaces. Your code should not pass more than
10219 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
10220 token pasting between consecutive invocations of @code{m4_wrap}, as in:
10223 m4_define([foo], [bar])
10224 m4_define([foofoo], [OUCH])
10232 @node Conditional constructs
10233 @subsection Conditional constructs
10235 The following macros provide additional conditional contructs, as
10236 convenience wrappers around @code{m4_if}.
10238 @defmac m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @dots{}, @
10241 The string @var{string} is repeatedly compared against a series of
10242 @var{regex} arguments; if a match is found, the expansion is the
10243 corresponding @var{value}, otherwise, the macro moves on to the next
10244 @var{regex}. If no @var{regex} match, then the result is the optional
10245 @var{default}, or nothing.
10248 @defmac m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @dots{})
10249 @msindex{bpatsubsts}
10250 The string @var{string} is altered by @var{regex-1} and @var{subst-1},
10253 m4_bpatsubst([[@var{string}]], [@var{regex}], [@var{subst}])
10257 The result of the substitution is then passed through the next set of
10258 @var{regex} and @var{subst}, and so forth. An empty @var{subst} implies
10259 deletion of any matched portions in the current string. Note that this
10260 macro over-quotes @var{string}; this behavior is intentional, so that
10261 the result of each step of the recursion remains as a quoted string.
10262 However, it means that anchors (@samp{^} and @samp{$} in the @var{regex}
10263 will line up with the extra quotations, and not the characters of the
10267 @defmac m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @dots{}, @
10270 Test @var{string} against multiple @var{value} possibilities, resulting
10271 in the first @var{if-value} for a match, or in the optional
10272 @var{default}. This is shorthand for:
10274 m4_if([@var{string}], [@var{value-1}], [@var{if-value-1}],
10275 [@var{string}], [@var{value-2}], [@var{if-value-2}], @dots{},
10280 @defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
10281 @var{test-2}, @var{value-2}, @var{if-value-2}, @dots{}, @ovar{default})
10283 Similar to @code{m4_if}, except that each @var{test} is expanded only
10284 when it is encountered. This is useful for short-circuiting expensive
10285 tests; while @code{m4_if} requires all its strings to be expanded up
10286 front before doing comparisons, @code{m4_cond} only expands a @var{test}
10287 when all earlier tests have failed.
10289 For an example, these two sequences give the same result, but in the
10290 case where @samp{$1} does not contain a backslash, the @code{m4_cond}
10291 version only expands @code{m4_index} once, instead of five times, for
10292 faster computation if this is a common case for @samp{$1}. Notice that
10293 every third argument is unquoted for @code{m4_if}, and quoted for
10297 m4_if(m4_index([$1], [\]), [-1], [$2],
10298 m4_eval(m4_index([$1], [\\]) >= 0), [1], [$2],
10299 m4_eval(m4_index([$1], [\$]) >= 0), [1], [$2],
10300 m4_eval(m4_index([$1], [\`]) >= 0), [1], [$3],
10301 m4_eval(m4_index([$1], [\"]) >= 0), [1], [$3],
10303 m4_cond([m4_index([$1], [\])], [-1], [$2],
10304 [m4_eval(m4_index([$1], [\\]) >= 0)], [1], [$2],
10305 [m4_eval(m4_index([$1], [\$]) >= 0)], [1], [$2],
10306 [m4_eval(m4_index([$1], [\`]) >= 0)], [1], [$3],
10307 [m4_eval(m4_index([$1], [\"]) >= 0)], [1], [$3],
10312 @defmac m4_default (@var{expr-1}, @var{expr-2})
10314 If @var{expr-1} is not empty, use it. Otherwise, expand to
10315 @var{expr-2}. Useful for providing a fixed default if the expression
10316 that results in @var{expr-1} would otherwise be empty.
10319 @defmac m4_ifndef (@var{macro}, @var{if-not-defined}, @ovar{if-defined})
10321 This is shorthand for:
10323 m4_ifdef([@var{macro}], [@var{if-defined}], [@var{if-not-defined}])
10327 @defmac m4_ifset (@var{macro}, @ovar{if-true}, @ovar{if-false})
10329 If @var{macro} is undefined, or is defined as the empty string, expand
10330 to @var{if-false}. Otherwise, expands to @var{if-true}. Similar to:
10332 m4_ifval(m4_defn([@var{macro}]), [@var{if-true}], [@var{if-false}])
10335 except that it is not an error if @var{macro} is undefined.
10338 @defmac m4_ifval (@var{cond}, @ovar{if-true}, @ovar{if-false})
10340 Expands to @var{if-true} if @var{cond} is not empty, otherwise to
10341 @var{if-false}. This is shorthand for:
10343 m4_if([@var{cond}], [], [@var{if-true}], [@var{if-false}])
10347 @defmac m4_ifvaln (@var{cond}, @ovar{if-true}, @ovar{if-false})
10349 Similar to @code{m4_ifval}, except guarantee that a newline is present
10350 after any non-empty expansion.
10353 @defmac m4_n (@var{text})
10355 Expand to @var{text}, and add a newline if @var{text} is not empty.
10359 @node Looping constructs
10360 @subsection Looping constructs
10362 The following macros implement loops in M4.
10364 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @
10367 Loop over the numeric values between @var{first} and @var{last}
10368 including bounds by increments of @var{step}. For each iteration,
10369 expand @var{expression} with the numeric value assigned to @var{var}.
10370 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
10371 on the order of the limits. If given, @var{step} has to match this
10375 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
10377 Loop over the comma-separated M4 list @var{list}, assigning each value
10378 to @var{var}, and expand @var{expression}. The following example
10382 m4_foreach([myvar], [[foo], [bar, baz]],
10389 @anchor{m4_foreach_w}
10390 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
10391 @msindex{foreach_w}
10392 Loop over the white-space-separated list @var{list}, assigning each value
10393 to @var{var}, and expand @var{expression}.
10395 The deprecated macro @code{AC_FOREACH} is an alias of
10396 @code{m4_foreach_w}.
10399 The following macros are useful in implementing recursive algorithms.
10401 @defmac m4_do (@dots{})
10403 This macro loops over its arguments and expands each one in sequence.
10404 Its main use is for readability; it allows the use of indentation and
10405 fewer @code{dnl} to result in the same expansion.
10408 @defmac m4_shiftn (@var{count}, @dots{})
10409 @defmacx m4_shift2 (@dots{})
10410 @defmacx m4_shift3 (@dots{})
10414 @code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
10415 along with validation that enough arguments were passed in to match the
10416 shift count. @code{m4_shift2} and @code{m4_shift3} are specializations
10417 of @code{m4_shiftn} that are more efficient for two and three shifts,
10422 @node Evaluation Macros
10423 @subsection Evaluation Macros
10425 The following macros give some control over the order of the evaluation
10426 by adding or removing levels of quotes. They are meant for hard-core M4
10429 @defmac m4_dquote (@var{arg1}, @dots{})
10431 Return the arguments as a quoted list of quoted arguments.
10434 @defmac m4_quote (@var{arg1}, @dots{})
10436 Return the arguments as a single entity, i.e., wrap them into a pair of
10440 The following example aims at emphasizing the difference between (i), not
10441 using these macros, (ii), using @code{m4_quote}, and (iii), using
10445 $ @kbd{cat example.m4}
10446 # Overquote, so that quotes are visible.
10447 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
10448 m4_define([mkargs], [1, 2, 3])
10449 m4_define([arg1], [[$1]])
10452 show(m4_quote(a, b))
10453 show(m4_dquote(a, b))
10456 arg1(m4_defn([mkargs]))
10457 arg1(m4_quote(mkargs))
10458 arg1(m4_dquote(mkargs))
10459 $ @kbd{autom4te -l m4sugar example.m4}
10460 $1 = a, $@@ = [a],[b]
10461 $1 = a,b, $@@ = [a,b]
10462 $1 = [a],[b], $@@ = [[a],[b]]
10472 @node Text processing Macros
10473 @subsection Text processing Macros
10475 The following macros may be used to manipulate strings in M4.
10476 They are not intended for casual use.
10478 @defmac m4_re_escape (@var{string})
10479 @msindex{re_escape}
10480 Backslash-escape all characters in @var{string} that are active in
10484 @defmac m4_tolower (@var{string})
10485 @defmacx m4_toupper (@var{string})
10488 Return @var{string} with letters converted to upper or lower case,
10492 @defmac m4_split (@var{string}, @ovar{regexp})
10494 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10495 @samp{]}, while keeping white space at the beginning and at the end.
10496 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10497 If @var{string} is empty, the result is an empty list.
10500 @defmac m4_normalize (@var{string})
10501 @msindex{normalize}
10502 Remove leading and trailing spaces and tabs, sequences of
10503 backslash-then-newline, and replace multiple spaces and tabs with a
10507 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10508 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
10510 @msindex{append_uniq}
10511 Redefine @var{macro-name} to its former contents with @var{separator}
10512 and @var{string} added at the end. If @var{macro-name} was undefined
10513 before (but not if it was defined but empty), then no @var{separator} is
10514 added. @code{m4_append} can be used to grow strings, and
10515 @code{m4_append_uniq} to grow strings without duplicating substrings.
10518 @anchor{m4_version_compare}
10519 @defmac m4_version_compare (@var{version-1}, @var{version-2})
10520 @msindex{version_compare}
10521 Introduced in autoconf 2.53. Compare the version strings
10522 @var{version-1} and @var{version-2}, and expand to @samp{-1} if
10523 @var{version-1} is smaller, @samp{0} if they are the same, or @samp{1}
10524 @var{version-2} is smaller. Version strings must be a list of elements
10525 separated by @samp{.}, where each element is a number along with an
10526 optional lower case letter. The comparison stops at the leftmost
10527 element that contains a difference, although a 0 element compares equal
10528 to a missing element.
10531 m4_version_compare([1.1], [2.0])
10533 m4_version_compare([2.0b], [2.0a])
10535 m4_version_compare([1.1.1], [1.1.1a])
10537 m4_version_compare([1.2], [1.1.1a])
10539 m4_version_compare([1.0], [1])
10545 @node Forbidden Patterns
10546 @subsection Forbidden Patterns
10547 @cindex Forbidden patterns
10548 @cindex Patterns, forbidden
10550 M4sugar provides a means to define suspicious patterns, patterns
10551 describing tokens which should not be found in the output. For
10552 instance, if an Autoconf @file{configure} script includes tokens such as
10553 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10554 wrong (typically a macro was not evaluated because of overquotation).
10556 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
10558 @defmac m4_pattern_forbid (@var{pattern})
10559 @msindex{pattern_forbid}
10560 Declare that no token matching @var{pattern} must be found in the output.
10561 Comments are not checked; this can be a problem if, for instance, you
10562 have some macro left unexpanded after an @samp{#include}. No consensus
10563 is currently found in the Autoconf community, as some people consider it
10564 should be valid to name macros in comments (which doesn't make sense to
10565 the author of this documentation, as @samp{#}-comments should document
10566 the output, not the input, documented by @samp{dnl} comments).
10569 Of course, you might encounter exceptions to these generic rules, for
10570 instance you might have to refer to @samp{$m4_flags}.
10572 @defmac m4_pattern_allow (@var{pattern})
10573 @msindex{pattern_allow}
10574 Any token matching @var{pattern} is allowed, including if it matches an
10575 @code{m4_pattern_forbid} pattern.
10578 @node Programming in M4sh
10579 @section Programming in M4sh
10581 @c FIXME: Eventually will become a chapter, as it is not related to
10582 @c programming in M4 per se.
10584 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10585 scripts. This name was coined by Lars J. Aas, who notes that,
10586 according to the Webster's Revised Unabridged Dictionary (1913):
10589 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
10590 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
10594 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10598 A mixture of meal or bran and water fed to animals.
10601 A mess; trouble. [Obs.] --Beau.@: & Fl.
10606 For the time being, it is not mature enough to be widely used.
10608 M4sh provides portable alternatives for some common shell constructs
10609 that unfortunately are not portable in practice.
10611 @c Deprecated, to be replaced by a better API
10613 @defmac AS_BASENAME (@var{file-name})
10615 Output the non-directory portion of @var{file-name}. For example,
10616 if @code{$file} is @samp{/one/two/three}, the command
10617 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10621 @defmac AS_BOURNE_COMPATIBLE
10622 @asindex{BOURNE_COMPATIBLE}
10623 Set up the shell to be more compatible with the Bourne shell as
10624 standardized by Posix, if possible. This may involve setting
10625 environment variables, or setting options, or similar
10626 implementation-specific actions.
10629 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @
10630 @dots{}, @ovar{default})
10632 Expand into a shell @samp{case} statement, where @var{word} is matched
10633 against one or more patterns. @var{if-matched} is run if the
10634 corresponding pattern matched @var{word}, else @var{default} is run.
10637 @defmac AS_DIRNAME (@var{file-name})
10639 Output the directory portion of @var{file-name}. For example,
10640 if @code{$file} is @samp{/one/two/three}, the command
10641 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10644 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10646 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10647 run shell code @var{run-if-true1}, else examine further tests. If no test
10648 exits with a zero status, run shell code @var{run-if-false}, with
10649 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10650 is empty. For example,
10653 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10654 [test "$foo" != no], [HANDLE_FOO([maybe])],
10655 [echo foo not specified])
10659 ensures any required macros of @code{HANDLE_FOO}
10660 are expanded before the first test.
10663 @defmac AS_MKDIR_P (@var{file-name})
10665 Make the directory @var{file-name}, including intervening directories
10666 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10667 except that it is portable to older versions of @command{mkdir} that
10668 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10669 succeeds if @var{file-name} is a symbolic link to an existing directory,
10670 even though Posix is unclear whether @samp{mkdir -p} should
10671 succeed in that case. If creation of @var{file-name} fails, exit the
10674 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10677 @defmac AS_SHELL_SANITIZE
10678 @asindex{SHELL_SANITIZE}
10679 Initialize the shell suitably for @code{configure} scripts. This has
10680 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10681 environment variables for predictable results from configuration tests.
10682 For example, it sets @env{LC_ALL} to change to the default C locale.
10683 @xref{Special Shell Variables}.
10686 @defmac AS_TR_CPP (@var{expression})
10688 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10692 # This outputs "#define HAVE_CHAR_P 1".
10694 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10698 @defmac AS_TR_SH (@var{expression})
10700 Transform @var{expression} into a valid shell variable name. For example:
10703 # This outputs "Have it!".
10704 header="sys/some file.h"
10705 AS_TR_SH([HAVE_$header])=yes
10706 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10710 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10711 @asindex{SET_CATFILE}
10712 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10713 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10714 @var{file} is absolute, etc.).
10718 @node File Descriptor Macros
10719 @section File Descriptor Macros
10721 @cindex standard input
10722 @cindex file descriptors
10723 @cindex descriptors
10724 @cindex low-level output
10725 @cindex output, low-level
10727 The following macros define file descriptors used to output messages
10728 (or input values) from @file{configure} scripts.
10732 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10733 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10734 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10738 However doing so is seldom needed, because Autoconf provides higher
10739 level macros as described below.
10741 @defmac AS_MESSAGE_FD
10742 @asindex{MESSAGE_FD}
10743 The file descriptor for @samp{checking for...} messages and results.
10744 Normally this directs messages to the standard output, however when
10745 @command{configure} is run with the @option{-q} option, messages sent to
10746 @code{AS_MESSAGE_FD} are discarded.
10748 If you want to display some messages, consider using one of the printing
10749 macros (@pxref{Printing Messages}) instead. Copies of messages output
10750 via these macros are also recorded in @file{config.log}.
10753 @defmac AS_MESSAGE_LOG_FD
10754 @asindex{MESSAGE_LOG_FD}
10756 The file descriptor for messages logged to @file{config.log}. Macros
10757 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10758 Compiler}), redirect all output to this descriptor. You may want to do
10759 so if you develop such a low-level macro.
10762 @defmac AS_ORIGINAL_STDIN_FD
10763 @asindex{ORIGINAL_STDIN_FD}
10764 The file descriptor for the original standard input.
10766 When @command{configure} runs, it may accidentally execute an
10767 interactive command that has the same name as the non-interactive meant
10768 to be used or checked. If the standard input was the terminal, such
10769 interactive programs would cause @command{configure} to stop, pending
10770 some user input. Therefore @command{configure} redirects its standard
10771 input from @file{/dev/null} during its initialization. This is not
10772 normally a problem, since @command{configure} normally does not need
10775 In the extreme case where your @file{configure} script really needs to
10776 obtain some values from the original standard input, you can read them
10777 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10781 @c =================================================== Writing Autoconf Macros.
10783 @node Writing Autoconf Macros
10784 @chapter Writing Autoconf Macros
10786 When you write a feature test that could be applicable to more than one
10787 software package, the best thing to do is encapsulate it in a new macro.
10788 Here are some instructions and guidelines for writing Autoconf macros.
10791 * Macro Definitions:: Basic format of an Autoconf macro
10792 * Macro Names:: What to call your new macros
10793 * Reporting Messages:: Notifying @command{autoconf} users
10794 * Dependencies Between Macros:: What to do when macros depend on other macros
10795 * Obsoleting Macros:: Warning about old ways of doing things
10796 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10799 @node Macro Definitions
10800 @section Macro Definitions
10803 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10804 similar to the M4 builtin @code{m4_define} macro. In addition to
10805 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10806 constrain the order in which macros are called (@pxref{Prerequisite
10809 An Autoconf macro definition looks like this:
10812 AC_DEFUN(@var{macro-name}, @var{macro-body})
10815 You can refer to any arguments passed to the macro as @samp{$1},
10816 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10817 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10819 Be sure to properly quote both the @var{macro-body} @emph{and} the
10820 @var{macro-name} to avoid any problems if the macro happens to have
10821 been previously defined.
10823 Each macro should have a header comment that gives its prototype, and a
10824 brief description. When arguments have default values, display them in
10825 the prototype. For example:
10828 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10829 # --------------------------------------
10830 m4_define([AC_MSG_ERROR],
10831 [@{ AS_MESSAGE([error: $1], [2])
10832 exit m4_default([$2], [1]); @}])
10835 Comments about the macro should be left in the header comment. Most
10836 other comments make their way into @file{configure}, so just keep
10837 using @samp{#} to introduce comments.
10840 If you have some special comments about pure M4 code, comments
10841 that make no sense in @file{configure} and in the header comment, then
10842 use the builtin @code{dnl}: it causes M4 to discard the text
10843 through the next newline.
10845 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10846 @code{dnl} is more useful to get rid of the newlines following macros
10847 that produce no output, such as @code{AC_REQUIRE}.
10851 @section Macro Names
10853 All of the Autoconf macros have all-uppercase names starting with
10854 @samp{AC_} to prevent them from accidentally conflicting with other
10855 text. All shell variables that they use for internal purposes have
10856 mostly-lowercase names starting with @samp{ac_}. To ensure that your
10857 macros don't conflict with present or future Autoconf macros, you should
10858 prefix your own macro names and any shell variables they use with some
10859 other sequence. Possibilities include your initials, or an abbreviation
10860 for the name of your organization or software package.
10862 Most of the Autoconf macros' names follow a structured naming convention
10863 that indicates the kind of feature check by the name. The macro names
10864 consist of several words, separated by underscores, going from most
10865 general to most specific. The names of their cache variables use the
10866 same convention (@pxref{Cache Variable Names}, for more information on
10869 The first word of the name after @samp{AC_} usually tells the category
10870 of the feature being tested. Here are the categories used in Autoconf for
10871 specific test macros, the kind of macro that you are more likely to
10872 write. They are also used for cache variables, in all-lowercase. Use
10873 them where applicable; where they're not, invent your own categories.
10877 C language builtin features.
10879 Declarations of C variables in header files.
10881 Functions in libraries.
10883 Posix group owners of files.
10889 The base names of programs.
10891 Members of aggregates.
10893 Operating system features.
10895 C builtin or declared types.
10897 C variables in libraries.
10900 After the category comes the name of the particular feature being
10901 tested. Any further words in the macro name indicate particular aspects
10902 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
10903 C compiler supports @acronym{ISO} Standard C.
10905 An internal macro should have a name that starts with an underscore;
10906 Autoconf internals should therefore start with @samp{_AC_}.
10907 Additionally, a macro that is an internal subroutine of another macro
10908 should have a name that starts with an underscore and the name of that
10909 other macro, followed by one or more words saying what the internal
10910 macro does. For example, @code{AC_PATH_X} has internal macros
10911 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10913 @node Reporting Messages
10914 @section Reporting Messages
10915 @cindex Messages, from @command{autoconf}
10917 When macros statically diagnose abnormal situations, benign or fatal,
10918 they should report them using these macros. For dynamic issues, i.e.,
10919 when @command{configure} is run, see @ref{Printing Messages}.
10921 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10923 Report @var{message} as a warning (or as an error if requested by the
10924 user) if warnings of the @var{category} are turned on. You are
10925 encouraged to use standard categories, which currently include:
10929 messages that don't fall into one of the following categories. Use of an
10930 empty @var{category} is equivalent.
10933 related to cross compilation issues.
10936 use of an obsolete construct.
10939 dubious syntactic constructs, incorrectly ordered macro calls.
10943 @defmac AC_WARNING (@var{message})
10945 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10946 strongly encouraged to use a finer grained category.
10949 @defmac AC_FATAL (@var{message})
10951 Report a severe error @var{message}, and have @command{autoconf} die.
10954 When the user runs @samp{autoconf -W error}, warnings from
10955 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10956 @ref{autoconf Invocation}.
10958 @node Dependencies Between Macros
10959 @section Dependencies Between Macros
10960 @cindex Dependencies between macros
10962 Some Autoconf macros depend on other macros having been called first in
10963 order to work correctly. Autoconf provides a way to ensure that certain
10964 macros are called if needed and a way to warn the user if macros are
10965 called in an order that might cause incorrect operation.
10968 * Prerequisite Macros:: Ensuring required information
10969 * Suggested Ordering:: Warning about possible ordering problems
10970 * One-Shot Macros:: Ensuring a macro is called only once
10973 @node Prerequisite Macros
10974 @subsection Prerequisite Macros
10975 @cindex Prerequisite macros
10976 @cindex Macros, prerequisites
10978 A macro that you write might need to use values that have previously
10979 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10980 examines the output of @code{flex} or @code{lex}, so it depends on
10981 @code{AC_PROG_LEX} having been called first to set the shell variable
10984 Rather than forcing the user of the macros to keep track of the
10985 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10986 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10987 called if it is needed, and only called once.
10989 @defmac AC_REQUIRE (@var{macro-name})
10991 If the M4 macro @var{macro-name} has not already been called, call it
10992 (without any arguments). Make sure to quote @var{macro-name} with
10993 square brackets. @var{macro-name} must have been defined using
10994 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10995 that it has been called.
10997 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10998 must not be called from the top level.
11001 @code{AC_REQUIRE} is often misunderstood. It really implements
11002 dependencies between macros in the sense that if one macro depends upon
11003 another, the latter is expanded @emph{before} the body of the
11004 former. To be more precise, the required macro is expanded before
11005 the outermost defined macro in the current expansion stack.
11006 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
11007 @code{FOO}. For instance, this definition of macros:
11011 AC_DEFUN([TRAVOLTA],
11012 [test "$body_temperature_in_celsius" -gt "38" &&
11013 dance_floor=occupied])
11014 AC_DEFUN([NEWTON_JOHN],
11015 [test "$hair_style" = "curly" &&
11016 dance_floor=occupied])
11020 AC_DEFUN([RESERVE_DANCE_FLOOR],
11021 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
11022 AC_REQUIRE([TRAVOLTA])
11023 AC_REQUIRE([NEWTON_JOHN])
11029 with this @file{configure.ac}
11032 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
11033 RESERVE_DANCE_FLOOR
11034 if test "$dance_floor" = occupied; then
11035 AC_MSG_ERROR([cannot pick up here, let's move])
11040 does not leave you with a better chance to meet a kindred soul at
11041 other times than Saturday night since it expands into:
11045 test "$body_temperature_in_Celsius" -gt "38" &&
11046 dance_floor=occupied
11047 test "$hair_style" = "curly" &&
11048 dance_floor=occupied
11050 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
11057 This behavior was chosen on purpose: (i) it prevents messages in
11058 required macros from interrupting the messages in the requiring macros;
11059 (ii) it avoids bad surprises when shell conditionals are used, as in:
11064 AC_REQUIRE([SOME_CHECK])
11071 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
11072 enforce expansion of required macros outside of shell conditional
11073 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
11074 at the beginning of a macro. You can use @code{dnl} to avoid the empty
11077 @node Suggested Ordering
11078 @subsection Suggested Ordering
11079 @cindex Macros, ordering
11080 @cindex Ordering macros
11082 Some macros should be run before another macro if both are called, but
11083 neither @emph{requires} that the other be called. For example, a macro
11084 that changes the behavior of the C compiler should be called before any
11085 macros that run the C compiler. Many of these dependencies are noted in
11088 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
11089 with this kind of dependency appear out of order in a
11090 @file{configure.ac} file. The warning occurs when creating
11091 @command{configure} from @file{configure.ac}, not when running
11092 @command{configure}.
11094 For example, @code{AC_PROG_CPP} checks whether the C compiler
11095 can run the C preprocessor when given the @option{-E} option. It should
11096 therefore be called after any macros that change which C compiler is
11097 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
11100 AC_BEFORE([$0], [AC_PROG_CPP])dnl
11104 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
11105 when @code{AC_PROG_CC} is called.
11107 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
11109 Make M4 print a warning message to the standard error output if
11110 @var{called-macro-name} has already been called. @var{this-macro-name}
11111 should be the name of the macro that is calling @code{AC_BEFORE}. The
11112 macro @var{called-macro-name} must have been defined using
11113 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
11114 that it has been called.
11117 @node One-Shot Macros
11118 @subsection One-Shot Macros
11119 @cindex One-shot macros
11120 @cindex Macros, called once
11122 Some macros should be called only once, either because calling them
11123 multiple time is unsafe, or because it is bad style. For instance
11124 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
11125 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
11126 sense to run these expensive checks more than once. Such one-shot
11127 macros can be defined using @code{AC_DEFUN_ONCE}.
11129 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
11130 @acindex{DEFUN_ONCE}
11132 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
11133 Definitions}), and emit a warning any time the macro is called more than
11137 Obviously it is not sensible to evaluate a macro defined by
11138 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
11139 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
11142 @node Obsoleting Macros
11143 @section Obsoleting Macros
11144 @cindex Obsoleting macros
11145 @cindex Macros, obsoleting
11147 Configuration and portability technology has evolved over the years.
11148 Often better ways of solving a particular problem are developed, or
11149 ad-hoc approaches are systematized. This process has occurred in many
11150 parts of Autoconf. One result is that some of the macros are now
11151 considered @dfn{obsolete}; they still work, but are no longer considered
11152 the best thing to do, hence they should be replaced with more modern
11153 macros. Ideally, @command{autoupdate} should replace the old macro calls
11154 with their modern implementation.
11156 Autoconf provides a simple means to obsolete a macro.
11159 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
11161 Define @var{old-macro} as @var{implementation}. The only difference
11162 with @code{AC_DEFUN} is that the user is warned that
11163 @var{old-macro} is now obsolete.
11165 If she then uses @command{autoupdate}, the call to @var{old-macro} is
11166 replaced by the modern @var{implementation}. @var{message} should
11167 include information on what to do after running @command{autoupdate};
11168 @command{autoupdate} prints it as a warning, and includes it
11169 in the updated @file{configure.ac} file.
11171 The details of this macro are hairy: if @command{autoconf} encounters an
11172 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
11173 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
11174 macros are expanded here, while all other macros are disabled and
11175 appear literally in the updated @file{configure.ac}.
11178 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
11180 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
11181 with the same parameters. This happens for example if the macro was renamed.
11185 @section Coding Style
11186 @cindex Coding style
11188 The Autoconf macros follow a strict coding style. You are encouraged to
11189 follow this style, especially if you intend to distribute your macro,
11190 either by contributing it to Autoconf itself, or via other means.
11192 The first requirement is to pay great attention to the quotation. For
11193 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
11195 Do not try to invent new interfaces. It is likely that there is a macro
11196 in Autoconf that resembles the macro you are defining: try to stick to
11197 this existing interface (order of arguments, default values, etc.). We
11198 @emph{are} conscious that some of these interfaces are not perfect;
11199 nevertheless, when harmless, homogeneity should be preferred over
11202 Be careful about clashes both between M4 symbols and between shell
11205 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
11206 you are unlikely to generate conflicts. Nevertheless, when you need to
11207 set a special value, @emph{avoid using a regular macro name}; rather,
11208 use an ``impossible'' name. For instance, up to version 2.13, the macro
11209 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
11210 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
11211 But since there is a macro named @code{AC_SUBST_FILE}, it was just
11212 impossible to @samp{AC_SUBST(FILE)}! In this case,
11213 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
11214 have been used (yes, with the parentheses).
11215 @c or better yet, high-level macros such as @code{m4_expand_once}
11217 No Autoconf macro should ever enter the user-variable name space; i.e.,
11218 except for the variables that are the actual result of running the
11219 macro, all shell variables should start with @code{ac_}. In
11220 addition, small macros or any macro that is likely to be embedded in
11221 other macros should be careful not to use obvious names.
11224 Do not use @code{dnl} to introduce comments: most of the comments you
11225 are likely to write are either header comments which are not output
11226 anyway, or comments that should make their way into @file{configure}.
11227 There are exceptional cases where you do want to comment special M4
11228 constructs, in which case @code{dnl} is right, but keep in mind that it
11231 M4 ignores the leading blanks and newlines before each argument.
11232 Use this feature to
11233 indent in such a way that arguments are (more or less) aligned with the
11234 opening parenthesis of the macro being called. For instance, instead of
11237 AC_CACHE_CHECK(for EMX OS/2 environment,
11239 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
11240 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
11247 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
11248 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
11249 [ac_cv_emxos2=yes],
11250 [ac_cv_emxos2=no])])
11257 AC_CACHE_CHECK([for EMX OS/2 environment],
11259 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
11260 [return __EMX__;])],
11261 [ac_cv_emxos2=yes],
11262 [ac_cv_emxos2=no])])
11265 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
11266 cross-compiling, provide a pessimistic value (typically @samp{no}).
11268 Feel free to use various tricks to prevent auxiliary tools, such as
11269 syntax-highlighting editors, from behaving improperly. For instance,
11273 m4_bpatsubst([$1], [$"])
11280 m4_bpatsubst([$1], [$""])
11284 so that Emacsen do not open an endless ``string'' at the first quote.
11285 For the same reasons, avoid:
11295 test $[@@%:@@] != 0
11299 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
11300 breaking the bracket-matching highlighting from Emacsen. Note the
11301 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
11302 not escape when it is unnecessary. Common examples of useless quotation
11303 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
11304 etc. If you add portability issues to the picture, you'll prefer
11305 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
11306 better than hacking Autoconf @code{:-)}.
11308 When using @command{sed}, don't use @option{-e} except for indenting
11309 purposes. With the @code{s} and @code{y} commands, the preferred
11310 separator is @samp{/} unless @samp{/} itself might appear in the pattern
11311 or replacement, in which case you should use @samp{|}, or optionally
11312 @samp{,} if you know the pattern and replacement cannot contain a file
11313 name. If none of these characters will do, choose a printable character
11314 that cannot appear in the pattern or replacement. Characters from the
11315 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
11316 replacement might contain a file name, since they have special meaning
11317 to the shell and are less likely to occur in file names.
11319 @xref{Macro Definitions}, for details on how to define a macro. If a
11320 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
11321 of an @code{AC_REQUIRE} directive, and macros required by other macros
11322 inside arguments do not need to be expanded before this macro, then
11323 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
11324 All the @code{AC_REQUIRE} statements should be at the beginning of the
11325 macro, and each statement should be followed by @code{dnl}.
11327 You should not rely on the number of arguments: instead of checking
11328 whether an argument is missing, test that it is not empty. It provides
11329 both a simpler and a more predictable interface to the user, and saves
11330 room for further arguments.
11332 Unless the macro is short, try to leave the closing @samp{])} at the
11333 beginning of a line, followed by a comment that repeats the name of the
11334 macro being defined. This introduces an additional newline in
11335 @command{configure}; normally, that is not a problem, but if you want to
11336 remove it you can use @samp{[]dnl} on the last line. You can similarly
11337 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
11338 is recommended instead of @samp{dnl} to ensure that M4 does not
11339 interpret the @samp{dnl} as being attached to the preceding text or
11340 macro output. For example, instead of:
11343 AC_DEFUN([AC_PATH_X],
11344 [AC_MSG_CHECKING([for X])
11346 @r{# @dots{}omitted@dots{}}
11347 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
11355 AC_DEFUN([AC_PATH_X],
11356 [AC_REQUIRE_CPP()[]dnl
11357 AC_MSG_CHECKING([for X])
11358 @r{# @dots{}omitted@dots{}}
11359 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
11364 If the macro is long, try to split it into logical chunks. Typically,
11365 macros that check for a bug in a function and prepare its
11366 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
11367 this setup. Do not hesitate to introduce auxiliary macros to factor
11370 In order to highlight the recommended coding style, here is a macro
11371 written the old way:
11374 dnl Check for EMX on OS/2.
11376 AC_DEFUN(_AC_EMXOS2,
11377 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
11378 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
11379 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
11380 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
11389 # Check for EMX on OS/2.
11390 m4_define([_AC_EMXOS2],
11391 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
11392 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
11393 [ac_cv_emxos2=yes],
11394 [ac_cv_emxos2=no])])
11395 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
11402 @c ============================================= Portable Shell Programming
11404 @node Portable Shell
11405 @chapter Portable Shell Programming
11406 @cindex Portable shell programming
11408 When writing your own checks, there are some shell-script programming
11409 techniques you should avoid in order to make your code portable. The
11410 Bourne shell and upward-compatible shells like the Korn shell and Bash
11411 have evolved over the years, but to prevent trouble, do not take
11412 advantage of features that were added after Unix version 7, circa
11413 1977 (@pxref{Systemology}).
11415 You should not use aliases, negated character classes, or other features
11416 that are not found in all Bourne-compatible shells; restrict yourself
11417 to the lowest common denominator. Even @code{unset} is not supported
11420 Shell functions are considered portable nowadays, though Autoconf
11421 still does not use them (Autotest does). However, inside a shell
11422 function you should not be using @code{$?} to check the return code
11423 of a subshell invocation; in general, since the caller of a shell
11424 function might look at the function's return code, make sure that the
11425 last statement of a shell function does not invoke a subshell.
11426 Using subshells triggers bugs in zsh 4.x; while Autoconf tries
11427 to find a shell that does not exhibit the bug, zsh might be the
11428 only shell present on the user's machine.
11430 Some ancient systems have quite
11431 small limits on the length of the @samp{#!} line; for instance, 32
11432 bytes (not including the newline) on SunOS 4.
11433 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
11434 required a single space between the @samp{#!} and the @samp{/}.
11435 However, these ancient systems are no longer of practical concern.
11437 The set of external programs you should run in a @command{configure} script
11438 is fairly small. @xref{Utilities in Makefiles, , Utilities in
11439 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
11440 restriction allows users to start out with a fairly small set of
11441 programs and build the rest, avoiding too many interdependencies between
11444 Some of these external utilities have a portable subset of features; see
11445 @ref{Limitations of Usual Tools}.
11447 There are other sources of documentation about shells. The
11448 specification for the Posix
11449 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
11450 Command Language}, though more generous than the restrictive shell
11451 subset described above, is fairly portable nowadays. Also please see
11452 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
11455 * Shellology:: A zoology of shells
11456 * Here-Documents:: Quirks and tricks
11457 * File Descriptors:: FDs and redirections
11458 * File System Conventions:: File names
11459 * Shell Pattern Matching:: Pattern matching
11460 * Shell Substitutions:: Variable and command expansions
11461 * Assignments:: Varying side effects of assignments
11462 * Parentheses:: Parentheses in shell scripts
11463 * Slashes:: Slashes in shell scripts
11464 * Special Shell Variables:: Variables you should not change
11465 * Limitations of Builtins:: Portable use of not so portable /bin/sh
11466 * Limitations of Usual Tools:: Portable use of portable tools
11470 @section Shellology
11473 There are several families of shells, most prominently the Bourne family
11474 and the C shell family which are deeply incompatible. If you want to
11475 write portable shell scripts, avoid members of the C shell family. The
11476 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
11477 Shell difference FAQ} includes a small history of Posix shells, and a
11478 comparison between several of them.
11480 Below we describe some of the members of the Bourne shell family.
11485 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
11486 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
11487 bugs that are fixed in the 0.3.x series, but portable shell scripts
11488 should work around them, since version 0.2 is still shipped with many
11489 @acronym{GNU}/Linux distributions.
11491 To be compatible with Ash 0.2:
11495 don't use @samp{$?} after expanding empty or unset variables,
11496 or at the start of an @command{eval}:
11502 echo "Do not use it: $?"
11504 eval 'echo "Do not use it: $?"'
11508 don't use command substitution within variable expansion:
11515 beware that single builtin substitutions are not performed by a
11516 subshell, hence their effect applies to the current shell! @xref{Shell
11517 Substitutions}, item ``Command Substitution''.
11522 To detect whether you are running Bash, test whether
11523 @code{BASH_VERSION} is set. To require
11524 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
11525 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11526 Manual}, for details.
11528 @item Bash 2.05 and later
11529 @cindex Bash 2.05 and later
11530 Versions 2.05 and later of Bash use a different format for the
11531 output of the @command{set} builtin, designed to make evaluating its
11532 output easier. However, this output is not compatible with earlier
11533 versions of Bash (or with many other shells, probably). So if
11534 you use Bash 2.05 or higher to execute @command{configure},
11535 you'll need to use Bash 2.05 for all other build tasks as well.
11540 @prindex @samp{ksh}
11541 @prindex @samp{ksh88}
11542 @prindex @samp{ksh93}
11543 The Korn shell is compatible with the Bourne family and it mostly
11544 conforms to Posix. It has two major variants commonly
11545 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11546 release. It is usually called @command{ksh}, but is called @command{sh}
11547 on some hosts if you set your path appropriately.
11549 Solaris systems have three variants:
11550 @prindex @command{/usr/bin/ksh} on Solaris
11551 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11552 standard on Solaris 2.0 and later.
11553 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11554 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11555 @samp{ksh88}; it is standard on Solaris 9 and later.
11556 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11557 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11558 Variants that are not standard may be parts of optional
11559 packages. There is no extra charge for these packages, but they are
11560 not part of a minimal OS install and therefore some installations may
11563 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11564 is also available as @command{/usr/bin/posix/sh}. If the environment
11565 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11566 the standard shell conform to Posix.
11569 @prindex @samp{pdksh}
11570 A public-domain clone of the Korn shell called @command{pdksh} is widely
11571 available: it has most of the @samp{ksh88} features along with a few of
11572 its own. It usually sets @code{KSH_VERSION}, except if invoked as
11573 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11574 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
11575 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
11576 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11577 at least one respect:
11580 $ @kbd{echo "`echo \"hello\"`"}
11582 $ @kbd{set -o posix}
11583 $ @kbd{echo "`echo \"hello\"`"}
11587 The last line of output contains spurious quotes. This is yet another
11588 reason why portable shell code should not contain
11589 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11594 To detect whether you are running @command{zsh}, test whether
11595 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
11596 compatible with the Bourne shell: you must execute @samp{emulate sh},
11597 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11598 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
11599 zsh, The Z Shell Manual}, for details.
11601 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11602 Bash in Mac OS X 10.2.
11605 The following discussion between Russ Allbery and Robert Lipe is worth
11612 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11613 leads to a permanent deadlock. Vendors don't want to break users'
11614 existing shell scripts, and there are some corner cases in the Bourne
11615 shell that are not completely compatible with a Posix shell. Thus,
11616 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11617 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11625 This is exactly the problem. While most (at least most System V's) do
11626 have a Bourne shell that accepts shell functions most vendor
11627 @command{/bin/sh} programs are not the Posix shell.
11629 So while most modern systems do have a shell @emph{somewhere} that meets the
11630 Posix standard, the challenge is to find it.
11633 @node Here-Documents
11634 @section Here-Documents
11635 @cindex Here-documents
11636 @cindex Shell here-documents
11638 Don't rely on @samp{\} being preserved just because it has no special
11639 meaning together with the next symbol. In the native @command{sh}
11640 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11641 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11642 use @samp{\\} to get @samp{\}.
11644 With Open@acronym{BSD} 2.7's @command{sh}
11660 bash-2.04$ @kbd{cat <<EOF
11667 Some shells mishandle large here-documents: for example,
11668 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11669 derived from Korn shell version M-12/28/93d, mishandle braced variable
11670 expansion that crosses a 1024- or 4096-byte buffer boundary
11671 within a here-document. Only the part of the variable name after the boundary
11672 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11673 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11674 boundary, the shell reports an error, as if you used @code{$@{@}}.
11675 Instead of @code{$@{variable-default@}}, the shell may expand
11676 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11677 be worked around by omitting the braces: @code{$variable}. The bug was
11679 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11680 still shipping older versions with the bug.
11682 Many shells (including the Bourne shell) implement here-documents
11683 inefficiently. In particular, some shells can be extremely inefficient when
11684 a single statement contains many here-documents. For instance if your
11685 @file{configure.ac} includes something like:
11689 if <cross_compiling>; then
11690 assume this and that
11694 check something else
11702 A shell parses the whole @code{if}/@code{fi} construct, creating
11703 temporary files for each here-document in it. Some shells create links
11704 for such here-documents on every @code{fork}, so that the clean-up code
11705 they had installed correctly removes them. It is creating the links
11706 that can take the shell forever.
11708 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11709 @code{if}/@code{fi} constructs, would improve the performance
11710 significantly. Anyway, this kind of construct is not exactly the
11711 typical use of Autoconf. In fact, it's even not recommended, because M4
11712 macros can't look into shell conditionals, so we may fail to expand a
11713 macro when it was expanded before in a conditional path, and the
11714 condition turned out to be false at runtime, and we end up not
11715 executing the macro at all.
11717 @node File Descriptors
11718 @section File Descriptors
11719 @cindex Descriptors
11720 @cindex File descriptors
11721 @cindex Shell file descriptors
11723 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11724 stderr, even for subshells. This might result in undesirable content
11725 if you meant to capture the standard-error output of the inner command:
11728 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11730 + eval echo foo >&2
11733 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11735 + eval 'echo foo >&2'
11738 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11739 @i{# Traces on startup files deleted here.}
11741 +zsh:1> eval echo foo >&2
11747 One workaround is to grep out uninteresting lines, hoping not to remove
11750 If you intend to redirect both standard error and standard output,
11751 redirect standard output first. This works better with @acronym{HP-UX},
11752 since its shell mishandles tracing if standard error is redirected
11756 $ @kbd{sh -x -c ': 2>err >out'}
11758 + 2> err $ @kbd{cat err}
11762 Don't try to redirect the standard error of a command substitution. It
11763 must be done @emph{inside} the command substitution. When running
11764 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11765 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11767 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11768 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11770 When catering to old systems, don't redirect the same file descriptor
11771 several times, as you are doomed to failure under Ultrix.
11774 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11776 $ @kbd{eval 'echo matter >fullness' >void}
11778 $ @kbd{eval '(echo matter >fullness)' >void}
11780 $ @kbd{(eval '(echo matter >fullness)') >void}
11781 Ambiguous output redirect.
11785 In each case the expected result is of course @file{fullness} containing
11786 @samp{matter} and @file{void} being empty. However, this bug is
11787 probably not of practical concern to modern platforms.
11789 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11790 subsidiary program. If any of these descriptors is closed, the
11791 operating system may open an unspecified file for the descriptor in the
11792 new process image. Posix says this may be done only if the subsidiary
11793 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does
11794 it even for ordinary programs.
11796 Don't rely on open file descriptors being open in child processes. In
11797 @command{ksh}, file descriptors above 2 which are opened using
11798 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11799 that involved in the fork-and-exec which runs a program or script).
11800 Thus, using @command{sh}, we have:
11803 $ @kbd{cat ./descrips}
11825 Within the process which runs the @samp{descrips} script, file
11826 descriptor 5 is closed.
11828 @acronym{DOS} variants cannot rename or remove open files, such as in
11829 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11830 perfectly portable among Posix hosts.
11832 A few ancient systems reserved some file descriptors. By convention,
11833 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11834 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11835 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11836 1990), though we don't now remember what it was. Both these systems are
11837 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11838 other file descriptors.
11840 @node File System Conventions
11841 @section File System Conventions
11842 @cindex File system conventions
11844 Autoconf uses shell-script processing extensively, so the file names
11845 that it processes should not contain characters that are special to the
11846 shell. Special characters include space, tab, newline, @sc{nul}, and
11850 " # $ & ' ( ) * ; < = > ? [ \ ` |
11853 Also, file names should not begin with @samp{~} or @samp{-}, and should
11854 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11855 immediately after @samp{:}. On Posix-like platforms, directory names
11856 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11859 These restrictions apply not only to the files that you distribute, but
11860 also to the absolute file names of your source, build, and destination
11863 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11864 they should be avoided.
11866 Posix lets implementations treat leading @file{//} specially, but
11867 requires leading @file{///} and beyond to be equivalent to @file{/}.
11868 Most Unix variants treat @file{//} like @file{/}. However, some treat
11869 @file{//} as a ``super-root'' that can provide access to files that are
11870 not otherwise reachable from @file{/}. The super-root tradition began
11871 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11874 While @command{autoconf} and friends are usually run on some Posix
11875 variety, they can be used on other systems, most notably @acronym{DOS}
11876 variants. This impacts several assumptions regarding file names.
11879 For example, the following code:
11886 foo_dir=$dots$foo_dir ;;
11891 fails to properly detect absolute file names on those systems, because
11892 they can use a drivespec, and usually use a backslash as directory
11893 separator. If you want to be portable to @acronym{DOS} variants (at the
11894 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11895 you can check for absolute file names like this:
11897 @cindex absolute file names, detect
11900 [\\/]* | ?:[\\/]* ) # Absolute
11903 foo_dir=$dots$foo_dir ;;
11908 Make sure you quote the brackets if appropriate and keep the backslash as
11909 first character (@pxref{Limitations of Builtins}).
11911 Also, because the colon is used as part of a drivespec, these systems don't
11912 use it as path separator. When creating or accessing paths, you can use the
11913 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11914 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
11917 File names need extra care as well. While @acronym{DOS} variants
11918 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11919 are usually able to handle long file names properly, there are still
11920 limitations that can seriously break packages. Several of these issues
11921 can be easily detected by the
11922 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11925 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11926 indicate where they apply: @sc{sfn} means the issues are only relevant to
11927 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11928 variants, while @sc{lfn} identifies problems that exist even under
11929 Microsoft Windows variants.
11932 @item No multiple dots (@sc{sfn})
11933 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11934 important thing to remember when building a portable configure script,
11935 as @command{autoconf} uses a .in suffix for template files.
11937 This is perfectly OK on Posix variants:
11940 AC_CONFIG_HEADERS([config.h])
11941 AC_CONFIG_FILES([source.c foo.bar])
11946 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11947 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11948 to @acronym{DOS}-based environments, you should use this instead:
11951 AC_CONFIG_HEADERS([config.h:config.hin])
11952 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11956 @item No leading dot (@sc{sfn})
11957 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11958 not important for @command{autoconf}.
11960 @item Case insensitivity (@sc{lfn})
11961 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11962 file called @samp{INSTALL} and a directory called @samp{install}. This
11963 also affects @command{make}; if there's a file called @samp{INSTALL} in
11964 the directory, @samp{make install} does nothing (unless the
11965 @samp{install} target is marked as PHONY).
11967 @item The 8+3 limit (@sc{sfn})
11968 Because the @acronym{DOS} file system only stores the first 8 characters of
11969 the file name and the first 3 of the extension, those must be unique.
11970 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11971 @file{foobar-prettybird.c} all resolve to the same file name
11972 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11973 @file{foo.bartender}.
11975 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11977 tails in the short version of file names to make them unique. However, a
11978 registry setting can turn this behavior off. While this makes it
11979 possible to share file trees containing long file names between @sc{sfn}
11980 and @sc{lfn} environments, it also means the above problem applies there
11983 @item Invalid characters (@sc{lfn})
11984 Some characters are invalid in @acronym{DOS} file names, and should therefore
11985 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11986 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11987 In a @sc{sfn} environment, other characters are also invalid. These
11988 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11990 @item Invalid names (@sc{lfn})
11991 Some @acronym{DOS} file names are reserved, and cause problems if you
11992 try to use files with those names. These names include @file{CON},
11993 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11994 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11995 File names are case insensitive, so even names like
11996 @file{aux/config.guess} are disallowed.
12000 @node Shell Pattern Matching
12001 @section Shell Pattern Matching
12002 @cindex Shell pattern matching
12004 Nowadays portable patterns can use negated character classes like
12005 @samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
12006 some shells but not others; hence portable scripts should never use
12007 @samp{^} as the first character of a bracket pattern.
12009 Outside the C locale, patterns like @samp{[a-z]} are problematic since
12010 they may match characters that are not lower-case letters.
12012 @node Shell Substitutions
12013 @section Shell Substitutions
12014 @cindex Shell substitutions
12016 Contrary to a persistent urban legend, the Bourne shell does not
12017 systematically split variables and back-quoted expressions, in particular
12018 on the right-hand side of assignments and in the argument of @code{case}.
12019 For instance, the following code:
12022 case "$given_srcdir" in
12023 .) top_srcdir="`echo "$dots" | sed 's|/$||'`" ;;
12024 *) top_srcdir="$dots$given_srcdir" ;;
12029 is more readable when written as:
12032 case $given_srcdir in
12033 .) top_srcdir=`echo "$dots" | sed 's|/$||'` ;;
12034 *) top_srcdir=$dots$given_srcdir ;;
12039 and in fact it is even @emph{more} portable: in the first case of the
12040 first attempt, the computation of @code{top_srcdir} is not portable,
12041 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
12042 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
12043 the same way. There is just no portable way to use double-quoted
12044 strings inside double-quoted back-quoted expressions (pfew!).
12048 @cindex @samp{"$@@"}
12049 One of the most famous shell-portability issues is related to
12050 @samp{"$@@"}. When there are no positional arguments, Posix says
12051 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
12052 original Unix version 7 Bourne shell treated it as equivalent to
12053 @samp{""} instead, and this behavior survives in later implementations
12054 like Digital Unix 5.0.
12056 The traditional way to work around this portability problem is to use
12057 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
12058 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
12059 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
12062 zsh $ @kbd{emulate sh}
12063 zsh $ @kbd{for i in "$@@"; do echo $i; done}
12066 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
12073 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
12074 @samp{"$@@"} because of the portability problems mentioned above.
12075 One workaround relies on Zsh's ``global aliases'' to convert
12076 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
12079 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
12082 Zsh only recognizes this alias when a shell word matches it exactly;
12083 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
12084 case always yields at least one shell word, use plain @samp{"$@@"}.
12086 A more conservative workaround is to avoid @samp{"$@@"} if it is
12087 possible that there may be no positional arguments. For example,
12091 cat conftest.c "$@@"
12094 you can use this instead:
12098 0) cat conftest.c;;
12099 *) cat conftest.c "$@@";;
12103 Autoconf macros often use the @command{set} command to update
12104 @samp{$@@}, so if you are writing shell code intended for
12105 @command{configure} you should not assume that the value of @samp{$@@}
12106 persists for any length of time.
12110 @cindex positional parameters
12111 The 10th, 11th, @dots{} positional parameters can be accessed only after
12112 a @code{shift}. The 7th Edition shell reported an error if given
12113 @code{$@{10@}}, and
12114 Solaris 10 @command{/bin/sh} still acts that way:
12117 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
12118 $ @kbd{echo $@{10@}}
12122 @item $@{@var{var}:-@var{value}@}
12123 @c Info cannot handle `:' in index entries.
12124 @c @cindex $@{@var{var}:-@var{value}@}
12125 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
12126 colon for any shell substitution, and complain and die.
12127 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
12129 @item $@{@var{var}=@var{literal}@}
12130 @cindex $@{@var{var}=@var{literal}@}
12134 : $@{var='Some words'@}
12138 otherwise some shells, such as on Digital Unix V 5.0, die because
12139 of a ``bad substitution''.
12143 Solaris @command{/bin/sh} has a frightening bug in its interpretation
12144 of this. Imagine you need set a variable to a string containing
12145 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
12146 when the affected variable was already set. This bug can be exercised
12151 $ @kbd{foo=$@{foo='@}'@}}
12154 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
12157 $ @kbd{foo=$@{foo='@}'@}}
12163 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
12164 though it is enclosed in single quotes. The problem doesn't happen
12165 using double quotes.
12167 @item $@{@var{var}=@var{expanded-value}@}
12168 @cindex $@{@var{var}=@var{expanded-value}@}
12174 : $@{var="$default"@}
12178 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
12179 each char is set. You don't observe the phenomenon using a simple
12180 @samp{echo $var} since apparently the shell resets the 8th bit when it
12181 expands $var. Here are two means to make this shell confess its sins:
12184 $ @kbd{cat -v <<EOF
12193 $ @kbd{set | grep '^var=' | cat -v}
12196 One classic incarnation of this bug is:
12200 : $@{list="$default"@}
12207 You'll get @samp{a b c} on a single line. Why? Because there are no
12208 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
12209 bit set, hence no IFS splitting is performed!!!
12211 One piece of good news is that Ultrix works fine with @samp{:
12212 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
12213 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
12216 The portable way out consists in using a double assignment, to switch
12217 the 8th bit twice on Ultrix:
12220 list=$@{list="$default"@}
12224 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
12228 test "$@{var+set@}" = set || var=@var{@{value@}}
12231 @item $@{#@var{var}@}
12232 @itemx $@{@var{var}%@var{word}@}
12233 @itemx $@{@var{var}%%@var{word}@}
12234 @itemx $@{@var{var}#@var{word}@}
12235 @itemx $@{@var{var}##@var{word}@}
12236 @cindex $@{#@var{var}@}
12237 @cindex $@{@var{var}%@var{word}@}
12238 @cindex $@{@var{var}%%@var{word}@}
12239 @cindex $@{@var{var}#@var{word}@}
12240 @cindex $@{@var{var}##@var{word}@}
12241 Posix requires support for these usages, but they do not work with many
12242 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
12244 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
12245 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
12246 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
12247 yields the empty string.
12250 @item `@var{commands}`
12251 @cindex `@var{commands}`
12252 @cindex Command Substitution
12253 Posix requires shells to trim all trailing newlines from command
12254 output before substituting it, so assignments like
12255 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
12256 @samp{$file} ends in a newline.
12258 While in general it makes no sense, do not substitute a single builtin
12259 with side effects, because Ash 0.2, trying to optimize, does not fork a
12260 subshell to perform the command.
12262 For instance, if you wanted to check that @command{cd} is silent, do not
12263 use @samp{test -z "`cd /`"} because the following can happen:
12268 $ @kbd{test -z "`cd /`" && pwd}
12273 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
12275 The MSYS shell leaves a stray byte in the expansion of a double-quoted
12276 command substitution of a native program, if the end of the substitution
12277 is not aligned with the end of the double quote. This may be worked
12278 around by inserting another pair of quotes:
12281 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
12282 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
12283 - broken differ: char 4, line 1
12287 @item $(@var{commands})
12288 @cindex $(@var{commands})
12289 This construct is meant to replace @samp{`@var{commands}`},
12290 and it has most of the problems listed under @code{`@var{commands}`}.
12292 This construct can be
12293 nested while this is impossible to do portably with back quotes.
12294 Unfortunately it is not yet universally supported. Most notably, even recent
12295 releases of Solaris don't support it:
12298 $ @kbd{showrev -c /bin/sh | grep version}
12299 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
12300 $ @kbd{echo $(echo blah)}
12301 syntax error: `(' unexpected
12305 nor does @sc{irix} 6.5's Bourne shell:
12308 IRIX firebird-image 6.5 07151432 IP22
12309 $ @kbd{echo $(echo blah)}
12313 If you do use @samp{$(@var{commands})}, make sure that the commands
12314 do not start with a parenthesis, as that would cause confusion with
12315 a different notation @samp{$((@var{expression}))} that in modern
12316 shells is an arithmetic expression not a command. To avoid the
12317 confusion, insert a space between the two opening parentheses.
12319 Avoid @var{commands} that contain unbalanced parentheses in
12320 here-documents, comments, or case statement patterns, as many shells
12321 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
12322 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
12325 echo $(case x in x) echo hello;; esac)
12330 Always quote @samp{^}, otherwise traditional shells such as
12331 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
12337 @section Assignments
12338 @cindex Shell assignments
12340 When setting several variables in a row, be aware that the order of the
12341 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
12342 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
12344 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
12346 Don't rely on the following to find @file{subdir/program}:
12349 PATH=subdir$PATH_SEPARATOR$PATH program
12353 as this does not work with Zsh 3.0.6. Use something like this
12357 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
12360 Don't rely on the exit status of an assignment: Ash 0.2 does not change
12361 the status and propagates that of the last statement:
12364 $ @kbd{false || foo=bar; echo $?}
12366 $ @kbd{false || foo=`:`; echo $?}
12371 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
12375 $ @kbd{foo=`exit 1`; echo $?}
12379 To assign default values, follow this algorithm:
12383 If the default value is a literal and does not contain any closing
12387 : $@{var='my literal'@}
12391 If the default value contains no closing brace, has to be expanded, and
12392 the variable being initialized is not intended to be IFS-split
12393 (i.e., it's not a list), then use:
12396 : $@{var="$default"@}
12400 If the default value contains no closing brace, has to be expanded, and
12401 the variable being initialized is intended to be IFS-split (i.e., it's a list),
12405 var=$@{var="$default"@}
12409 If the default value contains a closing brace, then use:
12412 test "$@{var+set@}" = set || var="has a '@}'"
12416 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
12417 doubt, just use the last form. @xref{Shell Substitutions}, items
12418 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
12422 @section Parentheses in Shell Scripts
12423 @cindex Shell parentheses
12425 Beware of two opening parentheses in a row, as many shell
12426 implementations treat them specially. Posix requires that the command
12427 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
12428 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
12429 expression equivalent to @samp{let "cat"}, and may or may not report an
12430 error when they detect that @samp{cat} is not a number. As another
12431 example, @samp{pdksh} 5.2.14 misparses the following code:
12434 if ((true) || false); then
12440 To work around this problem, insert a space between the two opening
12441 parentheses. There is a similar problem and workaround with
12442 @samp{$((}; see @ref{Shell Substitutions}.
12445 @section Slashes in Shell Scripts
12446 @cindex Shell slashes
12448 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
12449 arguments that contain two trailing slashes:
12452 $ @kbd{echo / // /// //// .// //.}
12455 $ @kbd{eval "echo \$x"}
12458 $ @kbd{echo abc | tr -t ab //}
12464 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
12465 variable is empty and the second double-quote is followed by a word that
12466 begins and ends with slash:
12469 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
12475 However, our understanding is that patches are available, so perhaps
12476 it's not worth worrying about working around these horrendous bugs.
12478 @node Special Shell Variables
12479 @section Special Shell Variables
12480 @cindex Shell variables
12481 @cindex Special shell variables
12483 Some shell variables should not be used, since they can have a deep
12484 influence on the behavior of the shell. In order to recover a sane
12485 behavior from the shell, some variables should be unset, but
12486 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
12487 fallback value is needed.
12489 As a general rule, shell variable names containing a lower-case letter
12490 are safe; you can define and use these variables without worrying about
12491 their effect on the underlying system, and without worrying about
12492 whether the shell changes them unexpectedly. (The exception is the
12493 shell variable @code{status}, as described below.)
12495 Here is a list of names that are known to cause trouble. This list is
12496 not exhaustive, but you should be safe if you avoid the name
12497 @code{status} and names containing only upper-case letters and
12500 @c Alphabetical order, case insensitive, `A' before `a'.
12503 Many shells reserve @samp{$_} for various purposes, e.g., the name of
12504 the last command executed.
12508 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
12509 the standard shell conform to Posix.
12513 When this variable is set it specifies a list of directories to search
12514 when invoking @code{cd} with a relative file name that did not start
12515 with @samp{./} or @samp{../}. Posix
12516 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
12517 is used successfully, @code{cd} prints the resulting absolute
12518 file name. Unfortunately this output can break idioms like
12519 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
12520 Also, many shells do not conform to this part of Posix; for
12521 example, @command{zsh} prints the result only if a directory name
12522 other than @file{.} was chosen from @env{CDPATH}.
12524 In practice the shells that have this problem also support
12525 @command{unset}, so you can work around the problem as follows:
12528 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
12531 You can also avoid output by ensuring that your directory name is
12532 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
12534 Autoconf-generated scripts automatically unset @env{CDPATH} if
12535 possible, so you need not worry about this problem in those scripts.
12539 In the MKS shell, case statements and file name generation are
12540 case-insensitive unless @env{DUALCASE} is nonzero.
12541 Autoconf-generated scripts export this variable when they start up.
12555 These variables should not matter for shell scripts, since they are
12556 supposed to affect only interactive shells. However, at least one
12557 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12558 whether it is interactive, which means that (for example) a @env{PS1}
12559 with a side effect can unexpectedly modify @samp{$?}. To work around
12560 this bug, Autoconf-generated scripts do something like this:
12563 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12570 The Korn shell uses @env{FPATH} to find shell functions, so avoid
12571 @env{FPATH} in portable scripts. @env{FPATH} is consulted after
12572 @env{PATH}, but you still need to be wary of tests that use @env{PATH}
12573 to find whether a command exists, since they might report the wrong
12574 result if @env{FPATH} is also set.
12578 Long ago, shell scripts inherited @env{IFS} from the environment,
12579 but this caused many problems so modern shells ignore any environment
12580 settings for @env{IFS}.
12582 Don't set the first character of @code{IFS} to backslash. Indeed,
12583 Bourne shells use the first character (backslash) when joining the
12584 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12585 backslash escapes, so you can end up with backspace and other strange
12588 The proper value for @code{IFS} (in regular code, not when performing
12589 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
12590 especially important, as it is used to join the arguments in @samp{$*};
12591 however, note that traditional shells, but also bash-2.04, fail to adhere
12592 to this and join with a space anyway.
12604 @evindex LC_COLLATE
12606 @evindex LC_MESSAGES
12607 @evindex LC_MONETARY
12608 @evindex LC_NUMERIC
12611 Autoconf-generated scripts normally set all these variables to
12612 @samp{C} because so much configuration code assumes the C locale and
12613 Posix requires that locale environment variables be set to
12614 @samp{C} if the C locale is desired. However, some older, nonstandard
12615 systems (notably @acronym{SCO}) break if locale environment variables
12616 are set to @samp{C}, so when running on these systems
12617 Autoconf-generated scripts unset the variables instead.
12622 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12623 extension that overrides @env{LC_ALL} in some cases, so
12624 Autoconf-generated scripts set it too.
12627 @itemx LC_IDENTIFICATION
12628 @itemx LC_MEASUREMENT
12631 @itemx LC_TELEPHONE
12632 @evindex LC_ADDRESS
12633 @evindex LC_IDENTIFICATION
12634 @evindex LC_MEASUREMENT
12637 @evindex LC_TELEPHONE
12639 These locale environment variables are @acronym{GNU} extensions. They
12640 are treated like their Posix brethren (@env{LC_COLLATE},
12641 etc.)@: as described above.
12644 Most modern shells provide the current line number in @code{LINENO}.
12645 Its value is the line number of the beginning of the current command.
12646 Autoconf attempts to execute @command{configure} with a shell that
12647 supports @code{LINENO}.
12648 If no such shell is available, it attempts to implement @code{LINENO}
12649 with a Sed prepass that replaces each instance of the string
12650 @code{$LINENO} (not followed by an alphanumeric character) with the
12653 You should not rely on @code{LINENO} within @command{eval}, as the
12654 behavior differs in practice. Also, the possibility of the Sed
12655 prepass means that you should not rely on @code{$LINENO} when quoted,
12656 when in here-documents, or when in long commands that cross line
12657 boundaries. Subshells should be OK, though. In the following
12658 example, lines 1, 6, and 9 are portable, but the other instances of
12659 @code{LINENO} are not:
12669 ( echo 6. $LINENO )
12670 eval 'echo 7. $LINENO'
12676 $ @kbd{bash-2.05 lineno}
12687 $ @kbd{zsh-3.0.6 lineno}
12698 $ @kbd{pdksh-5.2.14 lineno}
12709 $ @kbd{sed '=' <lineno |}
12715 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12718 > @kbd{ s,^[0-9]*\n,,}
12734 When executing the command @samp{>foo}, @command{zsh} executes
12735 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12736 compatibility mode and the @command{zsh} version is newer
12737 than 3.1.6-dev-18. If you are using an older @command{zsh}
12738 and forget to set @env{NULLCMD},
12739 your script might be suspended waiting for data on its standard input.
12741 @item PATH_SEPARATOR
12742 @evindex PATH_SEPARATOR
12743 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12744 variable can be set to either @samp{:} or @samp{;} to control the path
12745 separator Bash uses to set up certain environment variables (such as
12746 @env{PATH}). You can set this variable to @samp{;} if you want
12747 @command{configure} to use @samp{;} as a separator; this might be useful
12748 if you plan to use non-Posix shells to execute files. @xref{File System
12749 Conventions}, for more information about @code{PATH_SEPARATOR}.
12753 Posix 1003.1-2001 requires that @command{cd} and
12754 @command{pwd} must update the @env{PWD} environment variable to point
12755 to the logical name of the current directory, but traditional shells
12756 do not support this. This can cause confusion if one shell instance
12757 maintains @env{PWD} but a subsidiary and different shell does not know
12758 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12759 points to the wrong directory. Use @samp{`pwd`} rather than
12763 Many shells provide @code{RANDOM}, a variable that returns a different
12764 integer each time it is used. Most of the time, its value does not
12765 change when it is not used, but on @sc{irix} 6.5 the value changes all
12766 the time. This can be observed by using @command{set}. It is common
12767 practice to use @code{$RANDOM} as part of a file name, but code
12768 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12771 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12772 hence read-only. Do not use it.
12775 @node Limitations of Builtins
12776 @section Limitations of Shell Builtins
12777 @cindex Shell builtins
12778 @cindex Limitations of shell builtins
12780 No, no, we are serious: some shells do have limitations! :)
12782 You should always keep in mind that any builtin or command may support
12783 options, and therefore differ in behavior with arguments
12784 starting with a dash. For instance, the innocent @samp{echo "$word"}
12785 can give unexpected results when @code{word} starts with a dash. It is
12786 often possible to avoid this problem using @samp{echo "x$word"}, taking
12787 the @samp{x} into account later in the pipe.
12791 @prindex @command{.}
12792 Use @command{.} only with regular files (use @samp{test -f}). Bash
12793 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12794 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12795 you want to use @command{.} on a file @file{foo} in the current
12796 directory, you must use @samp{. ./foo}.
12799 @prindex @command{!}
12800 The Unix version 7 shell did not support
12801 negating the exit status of commands with @command{!}, and this feature
12802 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12803 Shell code like this:
12806 if ! cmp file1 file2 >/dev/null 2>&1; then
12807 echo files differ or trouble
12811 is therefore not portable in practice. Typically it is easy to rewrite
12815 cmp file1 file2 >/dev/null 2>&1 ||
12816 echo files differ or trouble
12819 More generally, one can always rewrite @samp{! @var{command}} as:
12822 if @var{command}; then (exit 1); else :; fi
12825 @item @command{break}
12826 @c ------------------
12827 @prindex @command{break}
12828 The use of @samp{break 2} etc.@: is safe.
12831 @item @command{case}
12832 @c -----------------
12833 @prindex @command{case}
12834 You don't need to quote the argument; no splitting is performed.
12836 You don't need the final @samp{;;}, but you should use it.
12838 Posix requires support for @code{case} patterns with opening
12839 parentheses like this:
12843 (*.c) echo "C source code";;
12848 but the @code{(} in this example is not portable to many Bourne
12849 shell implementations. It can be omitted safely.
12851 Zsh handles pattern fragments derived from parameter expansions or
12852 command substitutions as though quoted:
12855 $ pat=\?; case aa in ?$pat) echo match;; esac
12856 $ pat=\?; case a? in ?$pat) echo match;; esac
12861 Because of a bug in its @code{fnmatch}, Bash fails to properly
12862 handle backslashes in character classes:
12865 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12870 This is extremely unfortunate, since you are likely to use this code to
12871 handle Posix or @sc{ms-dos} absolute file names. To work around this
12872 bug, always put the backslash first:
12875 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12877 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12881 Many Bourne shells cannot handle closing brackets in character classes
12884 Some shells also have problems with backslash escaping in case you do not want
12885 to match the backslash: both a backslash and the escaped character match this
12886 pattern. To work around this, specify the character class in a variable, so
12887 that quote removal does not apply afterwards, and the special characters don't
12888 have to be backslash-escaped:
12891 $ @kbd{case '\' in [\<]) echo OK;; esac}
12893 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12897 Even with this, Solaris @command{ksh} matches a backslash if the set
12899 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12901 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12902 a closing parenthesis if not specified in a character class:
12905 $ @kbd{case foo in *\)*) echo fail ;; esac}
12907 $ @kbd{case foo in *')'*) echo fail ;; esac}
12911 Some shells, such as Ash 0.3.8, are confused by an empty
12912 @code{case}/@code{esac}:
12915 ash-0.3.8 $ @kbd{case foo in esac;}
12916 @error{}Syntax error: ";" unexpected (expecting ")")
12919 Many shells still do not support parenthesized cases, which is a pity
12920 for those of us using tools that rely on balanced parentheses. For
12921 instance, Solaris @command{/bin/sh}:
12924 $ @kbd{case foo in (foo) echo foo;; esac}
12925 @error{}syntax error: `(' unexpected
12931 @prindex @command{cd}
12932 Posix 1003.1-2001 requires that @command{cd} must support
12933 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12934 with @option{-L} being the default. However, traditional shells do
12935 not support these options, and their @command{cd} command has the
12936 @option{-P} behavior.
12938 Portable scripts should assume neither option is supported, and should
12939 assume neither behavior is the default. This can be a bit tricky,
12940 since the Posix default behavior means that, for example,
12941 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12942 the current logical directory is a symbolic link. It is safe to use
12943 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12944 Also, Autoconf-generated scripts check for this problem when computing
12945 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12946 so it is safe to @command{cd} to these variables.
12948 See @xref{Special Shell Variables}, for portability problems involving
12949 @command{cd} and the @env{CDPATH} environment variable.
12950 Also please see the discussion of the @command{pwd} command.
12953 @item @command{echo}
12954 @c -----------------
12955 @prindex @command{echo}
12956 The simple @command{echo} is probably the most surprising source of
12957 portability troubles. It is not possible to use @samp{echo} portably
12958 unless both options and escape sequences are omitted. New applications
12959 which are not aiming at portability should use @samp{printf} instead of
12962 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
12963 etc.@: for a means to simulate @option{-n}.
12965 Do not use backslashes in the arguments, as there is no consensus on
12966 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
12967 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12968 The problem is truly @command{echo}: all the shells
12969 understand @samp{'\n'} as the string composed of a backslash and an
12972 Because of these problems, do not pass a string containing arbitrary
12973 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
12974 if you know that @var{foo}'s value cannot contain backslashes and cannot
12975 start with @samp{-}, but otherwise you should use a here-document like
12985 @item @command{eval}
12986 @c -----------------
12987 @prindex @command{eval}
12988 The @command{eval} command is useful in limited circumstances, e.g.,
12989 using commands like @samp{eval table_$key=\$value} and @samp{eval
12990 value=table_$key} to simulate a hash table when the key is known to be
12991 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12992 arguments, even when it is implemented correctly.
12994 It is obviously unwise to use @samp{eval $cmd} if the string value of
12995 @samp{cmd} was derived from an untrustworthy source. But even if the
12996 string value is valid, @samp{eval $cmd} might not work as intended,
12997 since it causes field splitting and file name expansion to occur twice,
12998 once for the @command{eval} and once for the command itself. It is
12999 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
13000 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
13001 equivalent of @samp{cat test;.c} if there happens to be a file named
13002 @file{test;.c} in the current directory; and this in turn
13003 mistakenly attempts to invoke @command{cat} on the file @file{test} and
13004 then execute the command @command{.c}. To avoid this problem, use
13005 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
13007 However, suppose that you want to output the text of the evaluated
13008 command just before executing it. Assuming the previous example,
13009 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
13010 this output doesn't show the user that @samp{test;.c} is the actual name
13011 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
13012 works on this example, but it fails with @samp{cmd='cat foo >bar'},
13013 since it mistakenly replaces the contents of @file{bar} by the
13014 string @samp{cat foo}. No simple, general, and portable solution to
13015 this problem is known.
13017 You should also be wary of common bugs in @command{eval} implementations.
13018 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
13019 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
13020 4.2.5), the arguments of @samp{eval} are evaluated in a context where
13021 @samp{$?} is 0, so they exhibit behavior like this:
13024 $ @kbd{false; eval 'echo $?'}
13028 The correct behavior here is to output a nonzero value,
13029 but portable scripts should not rely on this.
13031 You should not rely on @code{LINENO} within @command{eval}.
13032 @xref{Special Shell Variables}.
13034 @item @command{exit}
13035 @c -----------------
13036 @prindex @command{exit}
13037 The default value of @command{exit} is supposed to be @code{$?};
13038 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
13039 perform @samp{exit 0}.
13042 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
13044 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
13046 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
13050 Using @samp{exit $?} restores the expected behavior.
13052 Some shell scripts, such as those generated by @command{autoconf}, use a
13053 trap to clean up before exiting. If the last shell command exited with
13054 nonzero status, the trap also exits with nonzero status so that the
13055 invoker can tell that an error occurred.
13057 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
13058 trap ignores the @code{exit} command's argument. In these shells, a trap
13059 cannot determine whether it was invoked by plain @code{exit} or by
13060 @code{exit 1}. Instead of calling @code{exit} directly, use the
13061 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
13064 @item @command{export}
13065 @c -------------------
13066 @prindex @command{export}
13067 The builtin @command{export} dubs a shell variable @dfn{environment
13068 variable}. Each update of exported variables corresponds to an update
13069 of the environment variables. Conversely, each environment variable
13070 received by the shell when it is launched should be imported as a shell
13071 variable marked as exported.
13073 Alas, many shells, such as Solaris @command{/bin/sh},
13074 @sc{irix} 6.3, @sc{irix} 5.2,
13075 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
13076 @command{export} the environment variables they receive. As a result,
13077 two variables coexist: the environment variable and the shell
13078 variable. The following code demonstrates this failure:
13089 when run with @samp{FOO=foo} in the environment, these shells print
13090 alternately @samp{foo} and @samp{bar}, although they should print only
13091 @samp{foo} and then a sequence of @samp{bar}s.
13093 Therefore you should @command{export} again each environment variable
13097 @item @command{false}
13098 @c ------------------
13099 @prindex @command{false}
13100 Don't expect @command{false} to exit with status 1: in native
13101 Solaris @file{/bin/false} exits with status 255.
13104 @item @command{for}
13105 @c ----------------
13106 @prindex @command{for}
13107 To loop over positional arguments, use:
13117 You may @emph{not} leave the @code{do} on the same line as @code{for},
13118 since some shells improperly grok:
13126 If you want to explicitly refer to the positional arguments, given the
13127 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
13130 for arg in $@{1+"$@@"@}; do
13136 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
13137 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
13138 item @samp{$@@}, for more.
13143 @prindex @command{if}
13144 Using @samp{!} is not portable. Instead of:
13147 if ! cmp -s file file.new; then
13156 if cmp -s file file.new; then :; else
13161 There are shells that do not reset the exit status from an @command{if}:
13164 $ @kbd{if (exit 42); then true; fi; echo $?}
13169 whereas a proper shell should have printed @samp{0}. This is especially
13170 bad in makefiles since it produces false failures. This is why properly
13171 written makefiles, such as Automake's, have such hairy constructs:
13174 if test -f "$file"; then
13175 install "$file" "$dest"
13182 @item @command{printf}
13183 @c ------------------
13184 @prindex @command{printf}
13185 A format string starting with a @samp{-} can cause problems.
13186 Bash interprets it as an option and
13187 gives an error. And @samp{--} to mark the end of options is not good
13188 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
13189 literally as the format string. Putting the @samp{-} in a @samp{%c}
13190 or @samp{%s} is probably easiest:
13196 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
13199 $ @kbd{printf '\045'}
13200 bash: printf: `%': missing format character
13203 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
13204 example, @file{/usr/bin/printf} is buggy, so when using
13205 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
13209 @item @command{read}
13210 @c ------------------
13211 @prindex @command{read}
13212 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
13215 @item @command{pwd}
13216 @c ----------------
13217 @prindex @command{pwd}
13218 With modern shells, plain @command{pwd} outputs a ``logical''
13219 directory name, some of whose components may be symbolic links. These
13220 directory names are in contrast to ``physical'' directory names, whose
13221 components are all directories.
13223 Posix 1003.1-2001 requires that @command{pwd} must support
13224 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
13225 with @option{-L} being the default. However, traditional shells do
13226 not support these options, and their @command{pwd} command has the
13227 @option{-P} behavior.
13229 Portable scripts should assume neither option is supported, and should
13230 assume neither behavior is the default. Also, on many hosts
13231 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
13232 does not require this behavior and portable scripts should not rely on
13235 Typically it's best to use plain @command{pwd}. On modern hosts this
13236 outputs logical directory names, which have the following advantages:
13240 Logical names are what the user specified.
13242 Physical names may not be portable from one installation
13243 host to another due to network file system gymnastics.
13245 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
13246 some parent directory, but plain @command{pwd} cannot fail for this
13250 Also please see the discussion of the @command{cd} command.
13253 @item @command{set}
13254 @c ----------------
13255 @prindex @command{set}
13256 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
13257 any options) does not sort its output.
13259 The @command{set} builtin faces the usual problem with arguments
13261 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
13262 the end of the options (any argument after @option{--} is a parameter,
13263 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
13264 10 @command{/bin/sh}) simply stop option
13265 processing as soon as a non-option argument is found. Therefore, use
13266 @samp{dummy} or simply @samp{x} to end the option processing, and use
13267 @command{shift} to pop it out:
13270 set x $my_list; shift
13273 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
13274 longer requires support for this command, and in traditional shells
13275 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
13276 makes scripts harder to debug.
13278 Some nonstandard shells do not recognize more than one option
13279 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
13280 better to combine them:
13286 The @acronym{BSD} shell has had several problems with the @option{-e}
13287 option, partly because @acronym{BSD} @command{make} traditionally used
13288 @option{-e} even though this was incompatible with Posix
13289 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
13290 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
13291 @samp{case} when @option{-e} was in effect, causing the shell to exit
13292 unexpectedly in some cases. This was particularly a problem with
13293 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
13294 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
13295 wrapper works around the bug.
13297 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
13298 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
13299 @samp{&&} fails inside a compound statement. For example:
13305 test -n "$foo" && exit 1
13308 test -n "$foo" && exit 1
13314 does not print @samp{two}. One workaround is to use @samp{if test -n
13315 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
13316 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
13319 @item @command{shift}
13320 @c ------------------
13321 @prindex @command{shift}
13322 Not only is @command{shift}ing a bad idea when there is nothing left to
13323 shift, but in addition it is not portable: the shell of @acronym{MIPS
13324 RISC/OS} 4.52 refuses to do it.
13326 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
13327 and it is also absent in many pre-Posix shells.
13330 @item @command{source}
13331 @c -------------------
13332 @prindex @command{source}
13333 This command is not portable, as Posix does not require it; use
13334 @command{.} instead.
13337 @item @command{test}
13338 @c -----------------
13339 @prindex @command{test}
13340 The @code{test} program is the way to perform many file and string
13341 tests. It is often invoked by the alternate name @samp{[}, but using
13342 that name in Autoconf code is asking for trouble since it is an M4 quote
13345 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
13346 portable and should be avoided. Thus, portable uses of @command{test}
13347 should never have more than four arguments, and scripts should use shell
13348 constructs like @samp{&&} and @samp{||} instead. If you combine
13349 @samp{&&} and @samp{||} in the same statement, keep in mind that they
13350 have equal precedence, so it is often better to parenthesize even when
13351 this is redundant. For example:
13355 test "X$a" = "X$b" -a \
13356 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
13359 test "X$a" = "X$b" &&
13360 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
13363 @command{test} does not process options like most other commands do; for
13364 example, it does not recognize the @option{--} argument as marking the
13367 It is safe to use @samp{!} as a @command{test} operator. For example,
13368 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
13369 -d foo; @dots{}} is not.
13372 @item @command{test} (files)
13373 @c -------------------------
13374 To enable @command{configure} scripts to support cross-compilation, they
13375 shouldn't do anything that tests features of the build system instead of
13376 the host system. But occasionally you may find it necessary to check
13377 whether some arbitrary file exists. To do so, use @samp{test -f} or
13378 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
13379 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
13380 lacks it. To test for symbolic links on systems that have them, use
13381 @samp{test -h} rather than @samp{test -L}; either form conforms to
13382 Posix 1003.1-2001, but older shells like Solaris 8
13383 @code{/bin/sh} support only @option{-h}.
13385 @item @command{test} (strings)
13386 @c ---------------------------
13387 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
13388 not null, but this usage is not portable to traditional platforms like
13389 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
13392 Posix also says that @samp{test ! "@var{string}"},
13393 @samp{test -n "@var{string}"} and
13394 @samp{test -z "@var{string}"} work with any string, but many
13395 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
13396 Digital Unix 4, etc.)@: get confused if
13397 @var{string} looks like an operator:
13401 test: argument expected
13403 test: argument expected
13406 Similarly, Posix says that both @samp{test "@var{string1}" = "@var{string2"}}
13407 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
13408 strings, but in practice this is not true for troublesome strings that
13409 look like operators or parentheses, or that begin with @samp{-}.
13411 It is best to protect such strings with a leading @samp{X}, e.g.,
13412 @samp{test "X@var{string}" != X} rather than @samp{test -n
13413 "@var{string}"} or @samp{test ! "@var{string}"}.
13415 It is common to find variations of the following idiom:
13418 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
13423 to take an action when a token matches a given pattern. Such constructs
13424 should be avoided by using:
13427 case $ac_feature in
13428 *[!-a-zA-Z0-9_]*) @var{action};;
13432 If the pattern is a complicated regular expression that cannot be
13433 expressed as a shell pattern, use something like this instead:
13436 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
13440 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
13441 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
13442 @samp{@var{foo}} contains backslashes.
13445 @item @command{trap}
13446 @c -----------------
13447 @prindex @command{trap}
13448 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
13449 trap 0, i.e., have the @command{trap} run when the script ends (either via an
13450 explicit @command{exit}, or the end of the script). The trap for 0 should be
13451 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
13452 will invoke the trap at the end of this function.
13454 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
13455 specified signals to their default values, but many common shells (e.g.,
13456 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
13457 ``command'' named @command{-} when the specified conditions arise.
13458 There is no portable workaround, except for @samp{trap - 0}, for which
13459 @samp{trap '' 0} is a portable substitute.
13461 Although Posix is not absolutely clear on this point, it is widely
13462 admitted that when entering the trap @samp{$?} should be set to the exit
13463 status of the last command run before the trap. The ambiguity can be
13464 summarized as: ``when the trap is launched by an @command{exit}, what is
13465 the @emph{last} command run: that before @command{exit}, or
13466 @command{exit} itself?''
13468 Bash considers @command{exit} to be the last command, while Zsh and
13469 Solaris @command{/bin/sh} consider that when the trap is run it is
13470 @emph{still} in the @command{exit}, hence it is the previous exit status
13471 that the trap receives:
13474 $ @kbd{cat trap.sh}
13477 $ @kbd{zsh trap.sh}
13479 $ @kbd{bash trap.sh}
13483 The portable solution is then simple: when you want to @samp{exit 42},
13484 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
13485 set the exit status to 42 for Zsh, and the second to trigger the trap
13486 and pass 42 as exit status for Bash.
13488 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
13489 reset to 0 by empty lines if the code is inside @command{trap}.
13492 $ @kbd{trap 'false}
13500 Fortunately, this bug only affects @command{trap}.
13502 @item @command{true}
13503 @c -----------------
13504 @prindex @command{true}
13505 @c Info cannot handle `:' in index entries.
13506 @c @prindex @command{:}
13507 Don't worry: as far as we know @command{true} is portable.
13508 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
13509 portable shell community tends to prefer using @command{:}. This has a
13510 funny side effect: when asked whether @command{false} is more portable
13511 than @command{true} Alexandre Oliva answered:
13514 In a sense, yes, because if it doesn't exist, the shell will produce an
13515 exit status of failure, which is correct for @command{false}, but not
13516 for @command{true}.
13520 @item @command{unset}
13521 @c ------------------
13522 @prindex @command{unset}
13523 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
13524 when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset
13525 MAIL} in some cases and dumps core.
13527 A few ancient shells lack @command{unset} entirely. Nevertheless, because
13528 it is extremely useful to disable embarrassing variables such as
13529 @code{PS1}, you can test for its existence and use
13530 it @emph{provided} you give a neutralizing value when @command{unset} is
13534 # "|| exit" suppresses any "Segmentation fault" message.
13535 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
13540 $unset PS1 || PS1='$ '
13544 @xref{Special Shell Variables}, for some neutralizing values. Also, see
13545 @ref{Limitations of Builtins}, documentation of @command{export}, for
13546 the case of environment variables.
13549 @node Limitations of Usual Tools
13550 @section Limitations of Usual Tools
13551 @cindex Limitations of usual tools
13553 The small set of tools you can expect to find on any machine can still
13554 include some limitations you should be aware of.
13560 Don't leave white space before the opening parenthesis in a user function call.
13561 Posix does not allow this and @acronym{GNU} Awk rejects it:
13564 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13565 BEGIN @{ die () @}'}
13566 gawk: cmd. line:2: BEGIN @{ die () @}
13567 gawk: cmd. line:2: ^ parse error
13568 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13569 BEGIN @{ die() @}'}
13573 Posix says that if a program contains only @samp{BEGIN} actions, and
13574 contains no instances of @code{getline}, then the program merely
13575 executes the actions without reading input. However, traditional Awk
13576 implementations (such as Solaris 10 @command{awk}) read and discard
13577 input in this case. Portable scripts can redirect input from
13578 @file{/dev/null} to work around the problem. For example:
13581 awk 'BEGIN @{print "hello world"@}' </dev/null
13584 Posix says that in an @samp{END} action, @samp{$NF} (and presumably,
13585 @samp{$1}) retain their value from the last record read, if no
13586 intervening @samp{getline} occurred. However, some implementations
13587 (such as Solaris 10 @samp{/usr/bin/awk}, @samp{nawk}, or Darwin
13588 @samp{awk}) reset these variables. A workaround is to use an
13589 intermediate variable prior to the @samp{END} block. For example:
13592 $ @kbd{cat end.awk}
13594 END @{ print "a", $1, $NF, "b", tmp @}
13595 $ @kbd{echo 1 | awk -f end.awk}
13597 $ @kbd{echo 1 | gawk -f end.awk}
13601 If you want your program to be deterministic, don't depend on @code{for}
13605 $ @kbd{cat for.awk}
13612 $ @kbd{gawk -f for.awk </dev/null}
13615 $ @kbd{nawk -f for.awk </dev/null}
13620 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one,
13624 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13625 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13627 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13629 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13634 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13635 or use a simple test to reject such implementations.
13637 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13638 length of regular expressions and literal strings in an Awk program.
13640 Traditional Awk implementations derived from Unix version 7, such as
13641 Solaris @command{/bin/awk}, have many limitations and do not
13642 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13643 Programs}) finds you an Awk that doesn't have these problems, but if
13644 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13647 Traditional Awk does not support multidimensional arrays or user-defined
13650 Traditional Awk does not support the @option{-v} option. You can use
13651 assignments after the program instead, e.g., @command{$AWK '@{print v
13652 $1@}' v=x}; however, don't forget that such assignments are not
13653 evaluated until they are encountered (e.g., after any @code{BEGIN}
13656 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13658 Traditional Awk does not support the expressions
13659 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13660 or @code{@var{a}^=@var{b}}.
13662 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13664 Traditional Awk supports only the predefined functions @code{exp},
13665 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13666 @code{sqrt}, and @code{substr}.
13668 Traditional Awk @code{getline} is not at all compatible with Posix;
13671 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13672 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
13674 In code portable to both traditional and modern Awk, @code{FS} must be a
13675 string containing just one ordinary character, and similarly for the
13676 field-separator argument to @code{split}.
13678 Traditional Awk has a limit of 99
13679 fields in a record. You may be able to circumvent this problem by using
13682 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13683 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13686 The original version of Awk had a limit of at most 99 bytes per
13687 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13688 per run of non-special characters in a @code{printf} format, but these
13689 bugs have been fixed on all practical hosts that we know of.
13691 @item @command{basename}
13692 @c ---------------------
13693 @prindex @command{basename}
13694 Not all hosts have a working @command{basename}.
13695 You can use @command{expr} instead.
13697 @c AS_BASENAME is to be replaced by a better API.
13699 Not all hosts have a working @command{basename}, and you should instead
13700 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13701 @command{expr} if you need to strip a suffix. For example:
13704 a=`basename "$aname"` # This is not portable.
13705 a=`AS_BASENAME(["$aname"])` # This is more portable.
13707 # This is not portable.
13708 c=`basename "$cname" .c`
13710 # This is more portable.
13711 c=`AS_BASENAME(["$cname"])`
13713 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13719 @item @command{cat}
13720 @c ----------------
13721 @prindex @command{cat}
13722 Don't rely on any option.
13727 @prindex @command{cc}
13728 The command @samp{cc -c foo.c} traditionally produces an object file
13729 named @file{foo.o}. Most compilers allow @option{-c} to be combined
13730 with @option{-o} to specify a different object file name, but
13731 Posix does not require this combination and a few compilers
13732 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
13733 tests for this feature with @code{AC_PROG_CC_C_O}.
13735 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13736 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13738 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13739 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
13742 The default executable, produced by @samp{cc foo.c}, can be
13745 @item @file{a.out} --- usual Posix convention.
13746 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13747 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13748 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13749 @item @file{foo.exe} --- various MS-DOS compilers.
13752 The C compiler's traditional name is @command{cc}, but other names like
13753 @command{gcc} are common. Posix 1003.1-2001 specifies the
13754 name @command{c99}, but older Posix editions specified
13755 @command{c89} and anyway these standard names are rarely used in
13756 practice. Typically the C compiler is invoked from makefiles that use
13757 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13761 @item @command{chmod}
13762 @c ------------------
13763 @prindex @command{chmod}
13764 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13765 instead, for two reasons. First, plain @option{-w} does not necessarily
13766 make the file unwritable, since it does not affect mode bits that
13767 correspond to bits in the file mode creation mask. Second,
13768 Posix says that the @option{-w} might be interpreted as an
13769 implementation-specific option, not as a mode; Posix suggests
13770 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13771 @samp{--} does not work on some older hosts.
13774 @item @command{cmp}
13775 @c ----------------
13776 @prindex @command{cmp}
13777 @command{cmp} performs a raw data comparison of two files, while
13778 @command{diff} compares two text files. Therefore, if you might compare
13779 DOS files, even if only checking whether two files are different, use
13780 @command{diff} to avoid spurious differences due to differences of
13786 @prindex @command{cp}
13787 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13788 obsolescent and its behavior on special files is implementation-defined.
13789 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13790 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13791 reads from pipes instead of replicating them.
13793 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13794 trailing slashes at the end of nonexistent destination directories. To
13795 avoid this problem, omit the trailing slashes. For example, use
13796 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13797 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13799 @c This is thanks to Ian.
13800 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13801 its @command{mv} does.
13803 @cindex timestamp resolution
13804 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13805 -p} copied the timestamps exactly. However, many modern file systems
13806 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13807 -p} implementations truncate timestamps when copying files, so this
13808 can result in the destination file appearing to be older than the
13809 source. The exact amount of truncation depends on the resolution of
13810 the system calls that @command{cp} uses; traditionally this was
13811 @code{utime}, which has 1-second resolution, but some newer
13812 @command{cp} implementations use @code{utimes}, which has
13813 1-microsecond resolution. These newer implementations include @acronym{GNU}
13814 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13815 later. Unfortunately as of January 2006 there is still no system
13816 call to set timestamps to the full nanosecond resolution.
13818 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13819 ownerships. But whether it actually does copy ownerships or not is a
13820 system dependent policy decision implemented by the kernel. If the
13821 kernel allows it then it happens. If the kernel does not allow it then
13822 it does not happen. It is not something @command{cp} itself has control
13825 In Unix System V any user can chown files to any other user, and System
13826 V also has a non-sticky @file{/tmp}. That probably derives from the
13827 heritage of System V in a business environment without hostile users.
13828 @acronym{BSD} changed this
13829 to be a more secure model where only root can @command{chown} files and
13830 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13831 of @acronym{BSD} in a campus environment.
13833 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13834 can be configured to allow a System V style @command{chown}. On the
13835 other hand, @acronym{HP-UX} follows System V, but can
13836 be configured to use the modern security model and disallow
13837 @command{chown}. Since it is an administrator-configurable parameter
13838 you can't use the name of the kernel as an indicator of the behavior.
13842 @item @command{date}
13843 @c -----------------
13844 @prindex @command{date}
13845 Some versions of @command{date} do not recognize special @samp{%} directives,
13846 and unfortunately, instead of complaining, they just pass them through,
13847 and exit with success:
13851 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13857 @item @command{diff}
13858 @c -----------------
13859 @prindex @command{diff}
13860 Option @option{-u} is nonportable.
13862 Some implementations, such as Tru64's, fail when comparing to
13863 @file{/dev/null}. Use an empty file instead.
13866 @item @command{dirname}
13867 @c --------------------
13868 @prindex @command{dirname}
13869 Not all hosts have a working @command{dirname}, and you should instead
13870 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13873 dir=`dirname "$file"` # This is not portable.
13874 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13878 @item @command{egrep}
13879 @c ------------------
13880 @prindex @command{egrep}
13881 Posix 1003.1-2001 no longer requires @command{egrep},
13882 but many hosts do not yet support the Posix
13883 replacement @code{grep -E}. Also, some traditional implementations do
13884 not work on long input lines. To work around these problems, invoke
13885 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13887 Portable extended regular expressions should use @samp{\} only to escape
13888 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13889 is not portable, even though it typically matches @samp{@}}.
13891 The empty alternative is not portable. Use @samp{?} instead. For
13892 instance with Digital Unix v5.0:
13895 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13897 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13899 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13904 @command{$EGREP} also suffers the limitations of @command{grep}.
13906 @item @command{expr}
13907 @c -----------------
13908 @prindex @command{expr}
13909 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13910 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13911 misinterpreting @var{word}.
13913 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13915 @item @command{expr} (@samp{|})
13916 @prindex @command{expr} (@samp{|})
13917 You can use @samp{|}. Although Posix does require that @samp{expr
13918 ''} return the empty string, it does not specify the result when you
13919 @samp{|} together the empty string (or zero) with the empty string. For
13926 Posix 1003.2-1992 returns the empty string
13927 for this case, but traditional Unix returns @samp{0} (Solaris is
13928 one such example). In Posix 1003.1-2001, the specification was
13929 changed to match traditional Unix's behavior (which is
13930 bizarre, but it's too late to fix this). Please note that the same
13931 problem does arise when the empty string results from a computation,
13935 expr bar : foo \| foo : bar
13939 Avoid this portability problem by avoiding the empty string.
13942 @item @command{expr} (@samp{:})
13943 @c ----------------------------
13944 @prindex @command{expr}
13945 Portable @command{expr} regular expressions should use @samp{\} to
13946 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13947 For example, alternation, @samp{\|}, is common but Posix does not
13948 require its support, so it should be avoided in portable scripts.
13949 Similarly, @samp{\+} and @samp{\?} should be avoided.
13951 Portable @command{expr} regular expressions should not begin with
13952 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
13955 The Posix standard is ambiguous as to whether
13956 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13957 In practice, it outputs the empty string on most platforms, but portable
13958 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
13959 @command{expr} returns @samp{0}.
13961 One might think that a way to get a uniform behavior would be to use
13962 the empty string as a default value:
13965 expr a : '\(b\)' \| ''
13969 Unfortunately this behaves exactly as the original expression; see the
13970 @command{expr} (@samp{|}) entry for more information.
13972 Some ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13973 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13974 @command{expr} to fail if the matched substring is longer than 120
13975 bytes. In this case, you might want to fall back on @samp{echo|sed} if
13976 @command{expr} fails. Nowadays this is of practical importance only for
13977 the rare installer who mistakenly puts @file{/usr/ucb} before
13978 @file{/usr/bin} in @env{PATH}.
13980 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13981 some cases. For example, the command
13983 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13987 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13988 This particular case can be worked around by substituting @samp{[^--]}
13991 Don't leave, there is some more!
13993 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13994 the empty string, has a funny behavior in its exit status: it's always 1
13995 when parentheses are used!
13998 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
14000 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
14003 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
14005 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
14010 In practice this can be a big problem if you are ready to catch failures
14011 of @command{expr} programs with some other method (such as using
14012 @command{sed}), since you may get twice the result. For instance
14015 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
14019 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
14020 simple workaround consists of testing @command{expr} and using a variable
14021 set to @command{expr} or to @command{false} according to the result.
14023 Tru64 @command{expr} incorrectly treats the result as a number, if it
14024 can be interpreted that way:
14027 $ @kbd{expr 00001 : '.*\(...\)'}
14032 @item @command{fgrep}
14033 @c ------------------
14034 @prindex @command{fgrep}
14035 Posix 1003.1-2001 no longer requires @command{fgrep},
14036 but many hosts do not yet support the Posix
14037 replacement @code{grep -F}. Also, some traditional implementations do
14038 not work on long input lines. To work around these problems, invoke
14039 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
14042 @item @command{find}
14043 @c -----------------
14044 @prindex @command{find}
14045 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
14046 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
14047 commands do not understand it.
14049 The replacement of @samp{@{@}} is guaranteed only if the argument is
14050 exactly @emph{@{@}}, not if it's only a part of an argument. For
14051 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
14055 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
14060 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
14063 @item @command{grep}
14064 @c -----------------
14065 @prindex @command{grep}
14066 Portable scripts can rely on the @command{grep} options @option{-c},
14067 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
14068 options. For example, don't use @option{-w}, as Posix does not require
14069 it and Irix 6.5.16m's @command{grep} does not support it. Also,
14070 portable scripts should not combine @option{-c} with @option{-l},
14071 as Posix does not allow this.
14073 Some of the options required by Posix are not portable in practice.
14074 Don't use @samp{grep -q} to suppress output, because many @command{grep}
14075 implementations (e.g., Solaris) do not support @option{-q}.
14076 Don't use @samp{grep -s} to suppress output either, because Posix
14077 says @option{-s} does not suppress output, only some error messages;
14078 also, the @option{-s} option of traditional @command{grep} behaved
14079 like @option{-q} does in most modern implementations. Instead,
14080 redirect the standard output and standard error (in case the file
14081 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
14082 status of @code{grep} to determine whether it found a match.
14084 Some traditional @command{grep} implementations do not work on long
14085 input lines. On AIX the default @code{grep} silently truncates long
14086 lines on the input before matching.
14088 Also, many implementations do not support multiple regexps
14089 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
14090 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
14091 work around these problems, invoke @code{AC_PROG_GREP} and then use
14094 Another possible workaround for the multiple @option{-e} problem is to
14095 separate the patterns by newlines, for example:
14103 except that this fails with traditional @command{grep}
14104 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
14106 Traditional @command{grep} implementations (e.g., Solaris) do not
14107 support the @option{-E} or @option{-F} options. To work around these
14108 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
14109 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
14110 willing to require support for Posix @command{grep}, your script should
14111 not use both @option{-E} and @option{-F}, since Posix does not allow
14114 Portable @command{grep} regular expressions should use @samp{\} only to
14115 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
14116 alternation, @samp{\|}, is common but Posix does not require its
14117 support in basic regular expressions, so it should be avoided in
14118 portable scripts. Solaris and HP-UX @command{grep} do not support it.
14119 Similarly, the following escape sequences should also be avoided:
14120 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
14121 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
14124 @item @command{join}
14125 @c -----------------
14126 @prindex @command{join}
14127 Solaris 8 @command{join} has bugs when the second operand is standard
14128 input, and when standard input is a pipe. For example, the following
14129 shell script causes Solaris 8 @command{join} to loop forever:
14136 cat file | join file -
14139 Use @samp{join - file} instead.
14144 @prindex @command{ln}
14145 @cindex Symbolic links
14146 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
14147 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
14149 For versions of the @acronym{DJGPP} before 2.04,
14150 @command{ln} emulates symbolic links
14151 to executables by generating a stub that in turn calls the real
14152 program. This feature also works with nonexistent files like in the
14153 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
14154 which attempts to call @file{file.exe} if run. But this feature only
14155 works for executables, so @samp{cp -p} is used instead for these
14156 systems. @acronym{DJGPP} versions 2.04 and later have full support
14157 for symbolic links.
14162 @prindex @command{ls}
14163 @cindex Listing directories
14164 The portable options are @option{-acdilrtu}. Current practice is for
14165 @option{-l} to output both owner and group, even though ancient versions
14166 of @command{ls} omitted the group.
14168 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
14169 to standard output if @file{foo} did not exist. Hence a shell command
14170 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
14171 was equivalent to @samp{sources='*.c not found'} in the absence of
14172 @samp{.c} files. This is no longer a practical problem, since current
14173 @command{ls} implementations send diagnostics to standard error.
14175 @item @command{mkdir}
14176 @c ------------------
14177 @prindex @command{mkdir}
14178 @cindex Making directories
14179 No @command{mkdir} option is portable to older systems. Instead of
14180 @samp{mkdir -p @var{file-name}}, you should use
14181 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
14182 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
14184 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
14185 go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD}
14186 @command{mkdir} incorrectly attempts to change the permissions of
14187 @var{dir} even if it already exists. @acronym{HP-UX} 11.23 and
14188 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
14189 any newly-created parents of @var{dir}.
14191 Posix does not clearly specify whether @samp{mkdir -p foo}
14192 should succeed when @file{foo} is a symbolic link to an already-existing
14193 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
14194 succeeds, but Solaris @command{mkdir} fails.
14196 Traditional @code{mkdir -p} implementations suffer from race conditions.
14197 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
14198 at the same time, both processes might detect that @file{a} is missing,
14199 one might create @file{a}, then the other might try to create @file{a}
14200 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
14201 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
14202 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
14203 race-free when two processes invoke @code{mkdir -p} simultaneously, but
14204 earlier versions are vulnerable. Solaris @command{mkdir} is still
14205 vulnerable as of Solaris 10, and other traditional Unix systems are
14206 probably vulnerable too. This possible race is harmful in parallel
14207 builds when several Make rules call @code{mkdir -p} to
14208 construct directories. You may use
14209 @code{install-sh -d} as a safe replacement, provided this script is
14210 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
14211 OK, but copies from older versions are vulnerable.
14214 @item @command{mktemp}
14215 @c -------------------
14216 @prindex @command{mktemp}
14217 @cindex Creating temporary files
14218 Shell scripts can use temporary files safely with @command{mktemp}, but
14219 it does not exist on all systems. A portable way to create a safe
14220 temporary file name is to create a temporary directory with mode 700 and
14221 use a file inside this directory. Both methods prevent attackers from
14222 gaining control, though @command{mktemp} is far less likely to fail
14223 gratuitously under attack.
14225 Here is sample code to create a new temporary directory safely:
14228 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
14229 # Use mktemp if possible; otherwise fall back on mkdir,
14230 # with $RANDOM to make collisions less likely.
14234 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
14236 test -n "$tmp" && test -d "$tmp"
14238 tmp=$TMPDIR/foo$$-$RANDOM
14239 (umask 077 && mkdir "$tmp")
14246 @prindex @command{mv}
14247 @cindex Moving open files
14248 The only portable options are @option{-f} and @option{-i}.
14250 Moving individual files between file systems is portable (it was in Unix
14252 but it is not always atomic: when doing @samp{mv new existing}, there's
14253 a critical section where neither the old nor the new version of
14254 @file{existing} actually exists.
14256 On some systems moving files from @file{/tmp} can sometimes cause
14257 undesirable (but perfectly valid) warnings, even if you created these
14258 files. This is because @file{/tmp} belongs to a group that ordinary
14259 users are not members of, and files created in @file{/tmp} inherit
14260 the group of @file{/tmp}. When the file is copied, @command{mv} issues
14261 a diagnostic without failing:
14264 $ @kbd{touch /tmp/foo}
14265 $ @kbd{mv /tmp/foo .}
14266 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
14274 This annoying behavior conforms to Posix, unfortunately.
14276 Moving directories across mount points is not portable, use @command{cp}
14279 @acronym{DOS} variants cannot rename or remove open files, and do not
14280 support commands like @samp{mv foo bar >foo}, even though this is
14281 perfectly portable among Posix hosts.
14286 @prindex @command{od}
14288 In Mac OS X 10.3, @command{od} does not support the
14289 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
14290 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
14291 supported Posix option is @option{-v}, and the only supported
14292 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
14293 @command{hexdump} program can be used instead.
14295 This problem no longer exists in Mac OS X 10.4.3.
14300 @prindex @command{rm}
14301 The @option{-f} and @option{-r} options are portable.
14303 It is not portable to invoke @command{rm} without operands. For
14304 example, on many systems @samp{rm -f -r} (with no other arguments)
14305 silently succeeds without doing anything, but it fails with a diagnostic
14306 on Net@acronym{BSD} 2.0.2.
14308 A file might not be removed even if its parent directory is writable
14309 and searchable. Many Posix hosts cannot remove a mount point, a named
14310 stream, a working directory, or a last link to a file that is being
14313 @acronym{DOS} variants cannot rename or remove open files, and do not
14314 support commands like @samp{rm foo >foo}, even though this is
14315 perfectly portable among Posix hosts.
14318 @item @command{sed}
14319 @c ----------------
14320 @prindex @command{sed}
14321 Patterns should not include the separator (unless escaped), even as part
14322 of a character class. In conformance with Posix, the Cray
14323 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
14325 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
14326 not require support for empty patterns, and Unicos 9 @command{sed} rejects
14329 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
14331 Sed scripts should not use branch labels longer than 7 characters and
14332 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
14333 (not counting @samp{:} commands) and
14334 48 labels, which can not be circumvented by using more than one script
14335 file. It can execute up to 19 reads with the @samp{r} command per cycle.
14336 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
14337 about 6000 bytes for the internal representation of commands.
14339 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
14340 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
14341 @samp{;} as a command:
14344 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
14345 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
14348 Input should not have unreasonably long lines, since some @command{sed}
14349 implementations have an input buffer limited to 4000 bytes.
14351 Portable @command{sed} regular expressions should use @samp{\} only to escape
14352 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
14353 alternation, @samp{\|}, is common but Posix does not require its
14354 support, so it should be avoided in portable scripts. Solaris
14355 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
14356 deletes only lines that contain the literal string @samp{a|b}.
14357 Similarly, @samp{\+} and @samp{\?} should be avoided.
14359 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
14361 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
14362 quite portable to current hosts, but was not supported by some ancient
14363 @command{sed} implementations like SVR3.
14365 Some @command{sed} implementations, e.g., Solaris,
14366 restrict the special role of the asterisk to one-character regular expressions.
14367 This may lead to unexpected behavior:
14370 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
14372 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
14376 The @option{-e} option is mostly portable.
14377 However, its argument
14378 cannot start with @samp{a}, @samp{c}, or @samp{i},
14379 as this runs afoul of a Tru64 5.1 bug.
14380 Also, its argument cannot be empty, as this fails on @acronym{AIX} 5.3.
14381 Some people prefer to use @samp{-e}:
14384 sed -e '@var{command-1}' \
14385 -e '@var{command-2}'
14389 as opposed to the equivalent:
14399 The following usage is sometimes equivalent:
14402 sed '@var{command-1};@var{command-2}'
14405 but Posix says that this use of a semicolon has undefined effect if
14406 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
14407 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
14408 should use semicolon only with simple scripts that do not use these
14411 Commands inside @{ @} brackets are further restricted. Posix says that
14412 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
14413 each command must be followed immediately by a newline, without any
14414 intervening blanks or semicolons. The closing bracket must be alone on
14415 a line, other than white space preceding or following it.
14417 Contrary to yet another urban legend, you may portably use @samp{&} in
14418 the replacement part of the @code{s} command to mean ``what was
14419 matched''. All descendants of Unix version 7 @command{sed}
14421 don't have first hand experience with older @command{sed} implementations) have
14424 Posix requires that you must not have any white space between
14425 @samp{!} and the following command. It is OK to have blanks between
14426 the address and the @samp{!}. For instance, on Solaris:
14429 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
14430 @error{}Unrecognized command: /bar/ ! p
14431 $ @kbd{echo "foo" | sed -n '/bar/! p'}
14432 @error{}Unrecognized command: /bar/! p
14433 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
14437 Posix also says that you should not combine @samp{!} and @samp{;}. If
14438 you use @samp{!}, it is best to put it on a command that is delimited by
14439 newlines rather than @samp{;}.
14441 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
14442 @samp{w} commands be followed by exactly one space before their argument.
14443 On the other hand, no white space is allowed between @samp{:} and the
14444 subsequent label name.
14446 If a sed script is specified on the command line and ends in an
14447 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
14448 should be followed by a newline. Otherwise some @command{sed}
14449 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
14452 Many @command{sed} implementations (e.g., MacOS X 10.4,
14453 Open@acronym{BSD} 3.9, Solaris 10
14454 @command{/usr/ucb/sed}) strip leading white space from the text of
14455 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
14456 work around this incompatibility with Posix:
14459 $ @kbd{echo flushleft | sed 'a\}
14464 $ @kbd{echo foo | sed 'a\}
14472 @item @command{sed} (@samp{t})
14473 @c ---------------------------
14474 @prindex @command{sed} (@samp{t})
14475 Some old systems have @command{sed} that ``forget'' to reset their
14476 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
14477 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
14478 script (the line numbers are not actual part of the texts):
14481 s/keep me/kept/g # a
14517 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
14518 flag, and the output is produced. When processing
14519 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
14520 fails to match, but @command{sed} is not supposed to clear the @samp{t}
14521 flag when a substitution fails. Command (b) sees that the flag is set,
14522 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
14523 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
14524 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
14525 Finally, since the flag is clear, line 4 is processed properly.
14527 There are two things one should remember about @samp{t} in @command{sed}.
14528 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
14529 succeeded, not only the immediately preceding substitution. Therefore,
14530 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
14531 line, to reset the @samp{t} flag where needed.
14533 Secondly, you cannot rely on @command{sed} to clear the flag at each new
14536 One portable implementation of the script above is:
14547 @item @command{touch}
14548 @c ------------------
14549 @prindex @command{touch}
14550 @cindex timestamp resolution
14551 If you specify the desired timestamp (e.g., with the @option{-r}
14552 option), @command{touch} typically uses the @code{utime} or
14553 @code{utimes} system call, which can result in the same kind of
14554 timestamp truncation problems that @samp{cp -p} has.
14556 On ancient @acronym{BSD} systems, @command{touch} or any command that
14557 results in an empty file does not update the timestamps, so use a
14558 command like @command{echo} as a workaround.
14560 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
14561 fails to work on SunOS 4.1.3 when the empty file is on an
14562 @acronym{NFS}-mounted 4.2 volume.
14563 However, these problems are no longer of practical concern.
14568 @node Portable Make
14569 @chapter Portable Make Programming
14570 @prindex @command{make}
14571 @cindex Limitations of @command{make}
14573 Writing portable makefiles is an art. Since a makefile's commands are
14574 executed by the shell, you must consider the shell portability issues
14575 already mentioned. However, other issues are specific to @command{make}
14579 * $< in Ordinary Make Rules:: $< in ordinary rules
14580 * Failure in Make Rules:: Failing portably in rules
14581 * Special Chars in Names:: Special Characters in Macro Names
14582 * Backslash-Newline-Newline:: Empty last lines in macro definitions
14583 * Backslash-Newline Comments:: Spanning comments across line boundaries
14584 * Long Lines in Makefiles:: Line length limitations
14585 * Macros and Submakes:: @code{make macro=value} and submakes
14586 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
14587 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
14588 * Comments in Make Rules:: Other problems with Make comments
14589 * obj/ and Make:: Don't name a subdirectory @file{obj}
14590 * make -k Status:: Exit status of @samp{make -k}
14591 * VPATH and Make:: @code{VPATH} woes
14592 * Single Suffix Rules:: Single suffix rules and separated dependencies
14593 * Timestamps and Make:: Subsecond timestamp resolution
14596 @node $< in Ordinary Make Rules
14597 @section @code{$<} in Ordinary Make Rules
14599 Posix says that the @samp{$<} construct in makefiles can be
14600 used only in inference rules and in the @samp{.DEFAULT} rule; its
14601 meaning in ordinary rules is unspecified. Solaris @command{make}
14602 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
14603 later) @command{make} diagnoses these uses and errors out.
14605 @node Failure in Make Rules
14606 @section Failure in Make Rules
14608 Since 1992 Posix has required that @command{make} must invoke
14609 each command with the equivalent of a @samp{sh -c} subshell. However,
14610 many @command{make} implementations, including @acronym{BSD} make through 2004,
14611 use @samp{sh -e -c} instead, and the @option{-e} option causes the
14612 subshell to exit immediately if a subsidiary simple-command fails. For
14613 example, the command @samp{touch T; rm -f U} always attempts to
14614 remove @file{U} with Posix make, but incompatible
14615 @command{make} implementations skip the @command{rm} if the
14616 @command{touch} fails. One way to work around this is to reword the
14617 affected simple-commands so that they always succeed, e.g., @samp{touch
14619 However, even this approach can run into common bugs in @acronym{BSD}
14620 implementations of the @option{-e} option of @command{sh} and
14621 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14622 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14623 complicated @command{make} actions into separate scripts.
14625 @node Special Chars in Names
14626 @section Special Characters in Make Macro Names
14628 Posix limits macro names to nonempty strings containing only
14629 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
14630 @command{make} implementations allow a wider variety of characters, but
14631 portable makefiles should avoid them. It is portable to start a name
14632 with a special character, e.g., @samp{$(.FOO)}.
14634 Some ancient @command{make} implementations don't support leading
14635 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
14638 $ @kbd{cat Makefile}
14641 all:; @@echo this is test
14643 Make: Must be a separator on rules line 2. Stop.
14644 $ @kbd{cat Makefile2}
14647 all:; @@echo this is test
14648 $ @kbd{make -f Makefile2}
14653 However, this problem is no longer of practical concern.
14655 @node Backslash-Newline-Newline
14656 @section Backslash-Newline-Newline in Make Macro Values
14658 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14659 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
14660 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
14661 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14662 following a backslash, continuing to the next non-empty line. For
14676 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
14677 sensibly let a backslash continue only to the immediately following
14680 @node Backslash-Newline Comments
14681 @section Backslash-Newline in Make Comments
14683 According to Posix, Make comments start with @code{#}
14684 and continue until an unescaped newline is reached.
14687 $ @kbd{cat Makefile}
14694 $ @kbd{make} # GNU make
14699 However this is not always the case. Some implementations
14700 discard everything from @code{#} through the end of the line, ignoring any
14701 trailing backslash.
14704 $ @kbd{pmake} # BSD make
14705 "Makefile", line 3: Need an operator
14706 Fatal errors encountered -- cannot continue
14710 Therefore, if you want to comment out a multi-line definition, prefix each
14711 line with @code{#}, not only the first.
14719 @node Long Lines in Makefiles
14720 @section Long Lines in Makefiles
14722 Tru64 5.1's @command{make} has been reported to crash when given a
14723 makefile with lines longer than around 20 kB. Earlier versions are
14724 reported to exit with @code{Line too long} diagnostics.
14726 @node Macros and Submakes
14727 @section @code{make macro=value} and Submakes
14729 A command-line variable definition such as @code{foo=bar} overrides any
14730 definition of @code{foo} in a makefile. Some @command{make}
14731 implementations (such as @acronym{GNU} @command{make}) propagate this
14732 override to subsidiary invocations of @command{make}. Some other
14733 implementations do not pass the substitution along to submakes.
14736 $ @kbd{cat Makefile}
14743 $ @kbd{make foo=bar} # GNU make 3.79.1
14746 make[1]: Entering directory `/home/adl'
14748 make[1]: Leaving directory `/home/adl'
14749 $ @kbd{pmake foo=bar} # BSD make
14755 You have a few possibilities if you do want the @code{foo=bar} override
14756 to propagate to submakes. One is to use the @option{-e}
14757 option, which causes all environment variables to have precedence over
14758 the makefile macro definitions, and declare foo as an environment
14762 $ @kbd{env foo=bar make -e}
14765 The @option{-e} option is propagated to submakes automatically,
14766 and since the environment is inherited between @command{make}
14767 invocations, the @code{foo} macro is overridden in
14768 submakes as expected.
14770 This syntax (@code{foo=bar make -e}) is portable only when used
14771 outside of a makefile, for instance from a script or from the
14772 command line. When run inside a @command{make} rule, @acronym{GNU}
14773 @command{make} 3.80 and prior versions forget to propagate the
14774 @option{-e} option to submakes.
14776 Moreover, using @option{-e} could have unexpected side effects if your
14777 environment contains some other macros usually defined by the
14778 makefile. (See also the note about @code{make -e} and @code{SHELL}
14781 Another way to propagate overrides to submakes is to do it
14782 manually, from your makefile:
14788 $(MAKE) foo=$(foo) two
14793 You need to foresee all macros that a user might want to override if
14796 @node The Make Macro MAKEFLAGS
14797 @section The Make Macro MAKEFLAGS
14798 @cindex @code{MAKEFLAGS} and @command{make}
14799 @cindex @command{make} and @code{MAKEFLAGS}
14801 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14802 current and recursive invocations of make, but allows implementations
14803 several formats for the variable. It is tricky to parse
14804 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14805 or @option{-k} for continued execution are in effect. For example, you
14806 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14807 contains single-letter options, since in the Cygwin version of
14808 @acronym{GNU} @command{make} it is either @option{--unix} or
14809 @option{--win32} with the second word containing single-letter options.
14812 $ @kbd{cat Makefile}
14814 @@echo MAKEFLAGS = $(MAKEFLAGS)
14818 MAKEFLAGS = --unix -k
14821 @node The Make Macro SHELL
14822 @section The Make Macro @code{SHELL}
14823 @cindex @code{SHELL} and @command{make}
14824 @cindex @command{make} and @code{SHELL}
14826 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14827 macro to spawn shell processes and execute Make rules. This
14828 is a builtin macro supplied by @command{make}, but it can be modified
14829 by a makefile or by a command-line argument.
14831 Not all @command{make} implementations define this @code{SHELL} macro.
14833 @command{make} is an example; this implementation always uses
14834 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14835 your makefiles. If you use Autoconf, do
14841 Do not force @code{SHELL = /bin/sh} because that is not correct
14842 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14843 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14844 emulation mode where features like pipes and redirections are emulated
14845 on top of DOS's @command{command.com}. Unfortunately this emulation is
14846 incomplete; for instance it does not handle command substitutions.
14847 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14849 Posix-compliant @command{make} should never acquire the value of
14850 $(SHELL) from the environment, even when @code{make -e} is used
14851 (otherwise, think about what would happen to your rules if
14852 @code{SHELL=/bin/tcsh}).
14854 However not all @command{make} implementations have this exception.
14855 For instance it's not surprising that Tru64 @command{make} doesn't
14856 protect @code{SHELL}, since it doesn't use it.
14859 $ @kbd{cat Makefile}
14865 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14868 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14873 @node Comments in Make Rules
14874 @section Comments in Make Rules
14875 @cindex Comments in @file{Makefile} rules
14876 @cindex @file{Makefile} rules and comments
14878 Never put comments in a rule.
14880 Some @command{make} treat anything starting with a tab as a command for
14881 the current rule, even if the tab is immediately followed by a @code{#}.
14882 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14883 makefile runs @code{# foo} through the shell.
14890 @node obj/ and Make
14891 @section The @file{obj/} Subdirectory and Make
14892 @cindex @file{obj/}, subdirectory
14893 @cindex @acronym{BSD} @command{make} and @file{obj/}
14895 Never name one of your subdirectories @file{obj/} if you don't like
14898 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14899 before reading the makefile. Hence the makefile in the
14900 current directory is not read.
14903 $ @kbd{cat Makefile}
14906 $ @kbd{cat obj/Makefile}
14909 $ @kbd{make} # GNU make
14912 $ @kbd{pmake} # BSD make
14917 @node make -k Status
14918 @section Exit Status of @code{make -k}
14919 @cindex @code{make -k}
14921 Do not rely on the exit status of @code{make -k}. Some implementations
14922 reflect whether they encountered an error in their exit status; other
14923 implementations always succeed.
14926 $ @kbd{cat Makefile}
14929 $ @kbd{make -k; echo exit status: $?} # GNU make
14931 make: *** [all] Error 1
14933 $ @kbd{pmake -k; echo exit status: $?} # BSD make
14935 *** Error code 1 (continuing)
14939 @node VPATH and Make
14940 @section @code{VPATH} and Make
14941 @cindex @code{VPATH}
14943 Posix does not specify the semantics of @code{VPATH}. Typically,
14944 @command{make} supports @code{VPATH}, but its implementation is not
14947 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14948 portable to recent-enough popular implementations of @command{make}, but
14949 to keep the resulting makefiles portable, a package's makefile
14950 prototypes must take the following issues into account. These issues
14951 are complicated and are often poorly understood, and installers who use
14952 @code{VPATH} should expect to find many bugs in this area. If you use
14953 @code{VPATH}, the simplest way to avoid these portability bugs is to
14954 stick with @acronym{GNU} @command{make}, since it is the most
14955 commonly-used @command{make} among Autoconf users.
14957 Here are some known issues with some @code{VPATH}
14961 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
14962 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
14963 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
14964 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
14965 * Make Target Lookup:: More details about @code{VPATH} lookup
14968 @node VPATH and Double-colon
14969 @subsection @code{VPATH} and Double-colon Rules
14970 @cindex @code{VPATH} and double-colon rules
14971 @cindex double-colon rules and @code{VPATH}
14973 With ancient versions of Sun @command{make},
14974 any assignment to @code{VPATH} causes @command{make} to execute only
14975 the first set of double-colon rules.
14976 However, this problem is no longer of practical concern.
14978 @node $< in Explicit Rules
14979 @subsection @code{$<} Not Supported in Explicit Rules
14980 @cindex explicit rules, @code{$<}, and @code{VPATH}
14981 @cindex @code{$<}, explicit rules, and @code{VPATH}
14982 @cindex @code{VPATH}, explicit rules, and @code{$<}
14984 Using @code{$<} in explicit rules is not portable.
14985 The prerequisite file must be named explicitly in the rule. If you want
14986 to find the prerequisite via a @code{VPATH} search, you have to code the
14987 whole thing manually. @xref{Build Directories}.
14989 @node Automatic Rule Rewriting
14990 @subsection Automatic Rule Rewriting
14991 @cindex @code{VPATH} and automatic rule rewriting
14992 @cindex automatic rule rewriting and @code{VPATH}
14994 Some @command{make} implementations, such as Solaris and Tru64,
14995 search for prerequisites in @code{VPATH} and
14996 then rewrite each occurrence as a plain word in the rule.
15000 # This isn't portable to GNU make.
15007 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
15008 found in @file{../pkg/src}.
15010 However, this rule leads to real problems in practice. For example, if
15011 the source directory contains an ordinary file named @file{test} that is
15012 used in a dependency, Solaris @command{make} rewrites commands like
15013 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
15014 @dots{}}, which is typically undesirable. To avoid this problem,
15015 portable makefiles should never mention a source file whose name is that
15016 of a shell keyword like @file{until} or a shell command like
15017 @command{cat} or @command{gcc} or @command{test}.
15019 Because of these problems @acronym{GNU} @command{make} and many other
15020 @command{make} implementations do not rewrite commands, so portable
15022 search @code{VPATH} manually. It is tempting to write this:
15025 # This isn't portable to Solaris make.
15028 cp `test -f if.c || echo $(VPATH)/`if.c f.c
15032 However, the ``prerequisite rewriting'' still applies here. So if
15033 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
15037 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
15048 and thus fails. Oops.
15050 A simple workaround, and good practice anyway, is to use @samp{$?} and
15051 @samp{$@@} when possible:
15060 but this does not generalize well to commands with multiple
15061 prerequisites. A more general workaround is to rewrite the rule so that
15062 the prerequisite @file{if.c} never appears as a plain word. For
15063 example, these three rules would be safe, assuming @file{if.c} is in
15064 @file{../pkg/src} and the other files are in the working directory:
15069 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
15071 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
15073 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
15076 Things get worse when your prerequisites are in a macro.
15080 HEADERS = f.h g.h h.h
15081 install-HEADERS: $(HEADERS)
15082 for i in $(HEADERS); do \
15083 $(INSTALL) -m 644 \
15084 `test -f $$i || echo $(VPATH)/`$$i \
15085 $(DESTDIR)$(includedir)/$$i; \
15089 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
15090 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
15091 where @code{f.h} and @code{g.h} are plain words and are hence
15092 subject to @code{VPATH} adjustments.
15094 If the three files are in @file{../pkg/src}, the rule is run as:
15097 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
15099 `test -f $i || echo ../pkg/src/`$i \
15100 /usr/local/include/$i; \
15104 where the two first @command{install} calls fail. For instance,
15105 consider the @code{f.h} installation:
15109 `test -f ../pkg/src/f.h || \
15112 /usr/local/include/../pkg/src/f.h;
15121 /usr/local/include/../pkg/src/f.h;
15124 Note that the manual @code{VPATH} search did not cause any problems here;
15125 however this command installs @file{f.h} in an incorrect directory.
15127 Trying to quote @code{$(HEADERS)} in some way, as we did for
15128 @code{foo.c} a few makefiles ago, does not help:
15131 install-HEADERS: $(HEADERS)
15132 headers='$(HEADERS)'; \
15133 for i in $$headers; do \
15134 $(INSTALL) -m 644 \
15135 `test -f $$i || echo $(VPATH)/`$$i \
15136 $(DESTDIR)$(includedir)/$$i; \
15140 Now, @code{headers='$(HEADERS)'} macro-expands to:
15143 headers='f.h g.h h.h'
15147 but @code{g.h} is still a plain word. (As an aside, the idiom
15148 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
15149 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
15150 syntax error on @code{for i in;}.)
15152 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
15156 HEADERS = f.h g.h h.h
15157 install-HEADERS: $(HEADERS)
15158 headers='$(HEADERS)'; \
15159 for i in $$headers; do \
15160 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
15161 $(INSTALL) -m 644 \
15162 `test -f $$i || echo $(VPATH)/`$$i \
15163 $(DESTDIR)$(includedir)/$$i; \
15167 Automake does something similar. However the above hack works only if
15168 the files listed in @code{HEADERS} are in the current directory or a
15169 subdirectory; they should not be in an enclosing directory. If we had
15170 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
15171 build with Tru64 @command{make}. The reason is that not only does
15172 Tru64 @command{make} rewrite dependencies, but it also simplifies
15173 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
15174 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
15175 a leading @file{../pkg/src/} component.
15177 The following example makes the behavior of Tru64 @command{make}
15181 $ @kbd{cat Makefile}
15193 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
15194 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
15195 directory does not even exist, this just means that the simplification
15196 occurred before the file was checked for.)
15198 For the record here is how SunOS 4 @command{make} behaves on this
15203 make: Fatal error: Don't know how to make target `../foo'
15211 @node Tru64 Directory Magic
15212 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
15213 @cindex @code{VPATH} and prerequisite directories
15214 @cindex prerequisite directories and @code{VPATH}
15216 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
15217 @command{make} creates it in the current directory.
15220 $ @kbd{mkdir -p foo/bar build}
15222 $ @kbd{cat >Makefile <<END
15231 This can yield unexpected results if a rule uses a manual @code{VPATH}
15232 search as presented before.
15237 command `test -d foo/bar || echo ../`foo/bar
15240 The above @command{command} is run on the empty @file{foo/bar}
15241 directory that was created in the current directory.
15243 @node Make Target Lookup
15244 @subsection Make Target Lookup
15245 @cindex @code{VPATH}, resolving target pathnames
15247 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
15248 should use files found via a @code{VPATH} search. @xref{Search
15249 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
15252 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
15253 file name found during the @code{VPATH} search for this target, and
15254 builds the file locally using the file name given in the makefile.
15255 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
15256 file name found during the @code{VPATH} search.
15258 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
15259 easier to describe: the file name found during the @code{VPATH} search
15260 is used whether the target needs to be rebuilt or not. Therefore
15261 new files are created locally, but existing files are updated at their
15262 @code{VPATH} location.
15264 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
15266 @code{VPATH} search for a dependency that has an explicit rule.
15267 This is extremely annoying.
15269 When attempting a @code{VPATH} build for an autoconfiscated package
15270 (e.g., @code{mkdir build && cd build && ../configure}), this means
15272 @command{make} builds everything locally in the @file{build}
15273 directory, while @acronym{BSD} @command{make} builds new files locally and
15274 updates existing files in the source directory.
15277 $ @kbd{cat Makefile}
15280 foo.x bar.x: newer.x
15281 @@echo Building $@@
15282 $ @kbd{touch ../bar.x}
15283 $ @kbd{touch ../newer.x}
15284 $ @kbd{make} # GNU make
15287 $ @kbd{pmake} # NetBSD make
15290 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15293 $ @kbd{tmake} # Tru64 make
15296 $ @kbd{touch ../bar.x}
15297 $ @kbd{make} # GNU make
15299 $ @kbd{pmake} # NetBSD make
15301 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15304 $ @kbd{tmake} # Tru64 make
15309 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
15310 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
15311 @command{make} always
15312 update @file{bar.x}, even when @file{../bar.x} is up to date.
15314 Another point worth mentioning is that once @acronym{GNU} @command{make} has
15315 decided to ignore a @code{VPATH} file name (e.g., it ignored
15316 @file{../bar.x} in the above example) it continues to ignore it when
15317 the target occurs as a prerequisite of another rule.
15319 The following example shows that @acronym{GNU} @command{make} does not look up
15320 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
15321 because it ignored the @code{VPATH} result of @file{bar.x} while running
15322 the @code{bar.x: newer.x} rule.
15325 $ @kbd{cat Makefile}
15329 @@echo Building $@@
15333 $ @kbd{touch ../bar.x}
15334 $ @kbd{touch ../newer.x}
15335 $ @kbd{make} # GNU make
15338 cp: cannot stat `bar.x': No such file or directory
15339 make: *** [bar.y] Error 1
15340 $ @kbd{pmake} # NetBSD make
15344 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15345 echo Building bar.x
15347 cp: cannot stat `bar.x': No such file or directory
15349 $ @kbd{tmake} # Tru64 make
15351 cp: bar.x: No such file or directory
15355 Note that if you drop away the command from the @code{bar.x: newer.x}
15356 rule, @acronym{GNU} @command{make} magically starts to work: it
15357 knows that @code{bar.x} hasn't been updated, therefore it doesn't
15358 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
15359 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
15363 $ @kbd{cat Makefile}
15370 $ @kbd{touch ../bar.x}
15371 $ @kbd{touch ../newer.x}
15372 $ @kbd{make} # GNU make
15375 $ @kbd{pmake} # NetBSD make
15378 $ @kbd{fmake} # FreeBSD make, OpenBSD make
15380 cp: cannot stat `bar.x': No such file or directory
15382 $ @kbd{tmake} # Tru64 make
15386 It seems the sole solution that would please every @command{make}
15387 implementation is to never rely on @code{VPATH} searches for targets.
15388 In other words, @code{VPATH} should be reserved to unbuilt sources.
15391 @node Single Suffix Rules
15392 @section Single Suffix Rules and Separated Dependencies
15393 @cindex Single Suffix Inference Rule
15394 @cindex Rule, Single Suffix Inference
15395 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
15396 (@samp{.from.to:}), but which @emph{destination} suffix is empty
15399 @cindex Separated Dependencies
15400 @dfn{Separated dependencies} simply refers to listing the prerequisite
15401 of a target, without defining a rule. Usually one can list on the one
15402 hand side, the rules, and on the other hand side, the dependencies.
15404 Solaris @command{make} does not support separated dependencies for
15405 targets defined by single suffix rules:
15408 $ @kbd{cat Makefile}
15413 $ @kbd{touch foo.in}
15420 while @acronym{GNU} Make does:
15426 Makefile foo foo.in
15429 Note it works without the @samp{foo: foo.in} dependency.
15432 $ @kbd{cat Makefile}
15441 and it works with double suffix inference rules:
15444 $ @kbd{cat Makefile}
15446 .SUFFIXES: .in .out
15453 As a result, in such a case, you have to write target rules.
15455 @node Timestamps and Make
15456 @section Timestamp Resolution and Make
15457 @cindex timestamp resolution
15458 Traditionally, file timestamps had 1-second resolution, and
15459 @command{make} used those timestamps to determine whether one file was
15460 newer than the other. However, many modern file systems have
15461 timestamps with 1-nanosecond resolution. Some @command{make}
15462 implementations look at the entire timestamp; others ignore the
15463 fractional part, which can lead to incorrect results. Normally this
15464 is not a problem, but in some extreme cases you may need to use tricks
15465 like @samp{sleep 1} to work around timestamp truncation bugs.
15467 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
15468 file timestamps to their full resolutions (@pxref{Limitations of Usual
15469 Tools}). Hence you should be wary of rules like this:
15476 as @file{dest} often appears to be older than @file{src} after the
15477 timestamp is truncated, and this can cause @command{make} to do
15478 needless rework the next time it is invoked. To work around this
15479 problem, you can use a timestamp file, e.g.:
15490 @c ======================================== Portable C and C++ Programming
15492 @node Portable C and C++
15493 @chapter Portable C and C++ Programming
15494 @cindex Portable C and C++ programming
15496 C and C++ programs often use low-level features of the underlying
15497 system, and therefore are often more difficult to make portable to other
15500 Several standards have been developed to help make your programs more
15501 portable. If you write programs with these standards in mind, you can
15502 have greater confidence that your programs work on a wide variety
15503 of systems. @xref{Standards, , Language Standards Supported by
15504 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
15505 (@acronym{GCC})}, for a list of C-related
15506 standards. Many programs also assume the
15507 @uref{http://www.opengroup.org/susv3, Posix standard}.
15509 Some old code is written to be portable to K&R C, which predates any C
15510 standard. K&R C compilers are no longer of practical interest, though,
15511 and the rest of section assumes at least C89, the first C standard.
15513 Program portability is a huge topic, and this section can only briefly
15514 introduce common pitfalls. @xref{System Portability, , Portability
15515 between System Types, standards, @acronym{GNU} Coding Standards}, for
15519 * Varieties of Unportability:: How to make your programs unportable
15520 * Integer Overflow:: When integers get too large
15521 * Null Pointers:: Properties of null pointers
15522 * Buffer Overruns:: Subscript errors and the like
15523 * Volatile Objects:: @code{volatile} and signals
15524 * Floating Point Portability:: Portable floating-point arithmetic
15525 * Exiting Portably:: Exiting and the exit status
15528 @node Varieties of Unportability
15529 @section Varieties of Unportability
15530 @cindex portability
15532 Autoconf tests and ordinary programs often need to test what is allowed
15533 on a system, and therefore they may need to deliberately exceed the
15534 boundaries of what the standards allow, if only to see whether an
15535 optional feature is present. When you write such a program, you should
15536 keep in mind the difference between constraints, unspecified behavior,
15537 and undefined behavior.
15539 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
15540 example constraint is that C programs must not declare a bit-field with
15541 negative width. Tests can therefore reliably assume that programs with
15542 negative-width bit-fields are rejected by a compiler that conforms
15545 @dfn{Unspecified behavior} is valid behavior, where the standard allows
15546 multiple possibilities. For example, the order of evaluation of
15547 function arguments is unspecified. Some unspecified behavior is
15548 @dfn{implementation-defined}, i.e., documented by the implementation,
15549 but since Autoconf tests cannot read the documentation they cannot
15550 distinguish between implementation-defined and other unspecified
15551 behavior. It is common for Autoconf tests to probe implementations to
15552 determine otherwise-unspecified behavior.
15554 @dfn{Undefined behavior} is invalid behavior, where the standard allows
15555 the implementation to do anything it pleases. For example,
15556 dereferencing a null pointer leads to undefined behavior. If possible,
15557 test programs should avoid undefined behavior, since a program with
15558 undefined behavior might succeed on a test that should fail.
15560 The above rules apply to programs that are intended to conform to the
15561 standard. However, strictly-conforming programs are quite rare, since
15562 the standards are so limiting. A major goal of Autoconf is to support
15563 programs that use implementation features not described by the standard,
15564 and it is fairly common for test programs to violate the above rules, if
15565 the programs work well enough in practice.
15567 @node Integer Overflow
15568 @section Integer Overflow
15569 @cindex integer overflow
15570 @cindex overflow, signed integer
15571 @cindex signed integer overflow
15572 @cindex wraparound arithmetic
15574 In practice many portable C programs assume that signed integer overflow wraps
15575 around reliably using two's complement arithmetic. Yet the C standard
15576 says that program behavior is undefined on overflow, and in a few cases
15577 C programs do not work on some modern implementations because their
15578 overflows do not wrap around as their authors expected. Conversely, in
15579 signed integer remainder, the C standard requires overflow
15580 behavior that is commonly not implemented.
15583 * Integer Overflow Basics:: Why integer overflow is a problem
15584 * Signed Overflow Examples:: Examples of code assuming wraparound
15585 * Optimization and Wraparound:: Optimizations that break uses of wraparound
15586 * Signed Overflow Advice:: Practical advice for signed overflow issues
15587 * Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
15590 @node Integer Overflow Basics
15591 @subsection Basics of Integer Overflow
15592 @cindex integer overflow
15593 @cindex overflow, signed integer
15594 @cindex signed integer overflow
15595 @cindex wraparound arithmetic
15597 In languages like C, unsigned integer overflow reliably wraps around;
15598 e.g., @code{UINT_MAX + 1} yields zero.
15599 This is guaranteed by the C standard and is
15600 portable in practice, unless you specify aggressive,
15601 nonstandard optimization options
15602 suitable only for special applications.
15604 In contrast, the C standard says that signed integer overflow leads to
15605 undefined behavior where a program can do anything, including dumping
15606 core or overrunning a buffer. The misbehavior can even precede the
15607 overflow. Such an overflow can occur during addition, subtraction,
15608 multiplication, division, and left shift.
15610 Despite this requirement of the standard, many C programs and Autoconf
15611 tests assume that signed integer overflow silently wraps around modulo a
15612 power of two, using two's complement arithmetic, so long as you cast the
15613 resulting value to a signed integer type or store it into a signed
15614 integer variable. If you use conservative optimization flags, such
15615 programs are generally portable to the vast majority of modern
15616 platforms, with a few exceptions discussed later.
15618 For historical reasons the C standard also allows implementations with
15619 ones' complement or signed magnitude arithmetic, but it is safe to
15620 assume two's complement nowadays.
15622 Also, overflow can occur when converting an out-of-range value to a
15623 signed integer type. Here a standard implementation must define what
15624 happens, but this might include raising an exception. In practice all
15625 known implementations support silent wraparound in this case, so you need
15626 not worry about other possibilities.
15628 @node Signed Overflow Examples
15629 @subsection Examples of Code Assuming Wraparound Overflow
15630 @cindex integer overflow
15631 @cindex overflow, signed integer
15632 @cindex signed integer overflow
15633 @cindex wraparound arithmetic
15635 There has long been a tension between what the C standard requires for
15636 signed integer overflow, and what C programs commonly assume. The
15637 standard allows aggressive optimizations based on assumptions that
15638 overflow never occurs, but many practical C programs rely on overflow
15639 wrapping around. These programs do not conform to the standard, but
15640 they commonly work in practice because compiler writers are
15641 understandably reluctant to implement optimizations that would break
15642 many programs, unless perhaps a user specifies aggressive optimization.
15644 The C Standard says that if a program has signed integer overflow its
15645 behavior is undefined, and the undefined behavior can even precede the
15646 overflow. To take an extreme example:
15648 @c Inspired by Robert Dewar's example in
15649 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
15651 if (password == expected_password)
15652 allow_superuser_privileges ();
15653 else if (counter++ == INT_MAX)
15656 printf ("%d password mismatches\n", counter);
15660 If the @code{int} variable @code{counter} equals @code{INT_MAX},
15661 @code{counter++} must overflow and the behavior is undefined, so the C
15662 standard allows the compiler to optimize away the test against
15663 @code{INT_MAX} and the @code{abort} call.
15664 Worse, if an earlier bug in the program lets the compiler deduce that
15665 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
15666 the C standard allows the compiler to optimize away the password test
15667 and generate code that allows superuser privileges unconditionally.
15669 Despite this requirement by the standard, it has long been common for C
15670 code to assume wraparound arithmetic after signed overflow, and all
15671 known practical C implementations support some C idioms that assume
15672 wraparound signed arithmetic, even if the idioms do not conform
15673 strictly to the standard. If your code looks like the following
15674 examples it will almost surely work with real-world compilers.
15676 Here is an example derived from the 7th Edition Unix implementation of
15677 @code{atoi} (1979-01-10):
15683 while (*p >= '0' && *p <= '9')
15684 n = n * 10 + *p++ - '0';
15685 return (f ? -n : n);
15689 Even if the input string is in range, on most modern machines this has
15690 signed overflow when computing the most negative integer (the @code{-n}
15691 overflows) or a value near an extreme integer (the first @code{+}
15694 Here is another example, derived from the 7th Edition implementation of
15695 @code{rand} (1979-01-10). Here the programmer expects both
15696 multiplication and addition to wrap on overflow:
15699 static long int randx = 1;
15701 randx = randx * 1103515245 + 12345;
15702 return (randx >> 16) & 077777;
15705 In the following example, derived from the @acronym{GNU} C Library 2.5
15706 implementation of @code{mktime} (2006-09-09), the code assumes
15707 wraparound arithmetic in @code{+} to detect signed overflow:
15711 int sec_requested, sec_adjustment;
15713 t1 = t + sec_requested;
15714 t2 = t1 + sec_adjustment;
15715 if (((t1 < t) != (sec_requested < 0))
15716 | ((t2 < t1) != (sec_adjustment < 0)))
15720 If your code looks like these examples, it is probably safe even though
15721 it does not strictly conform to the C standard. This might lead one to
15722 believe that one can generally assume wraparound on overflow, but that
15723 is not always true, as can be seen in the next section.
15725 @node Optimization and Wraparound
15726 @subsection Optimizations That Break Wraparound Arithmetic
15727 @cindex loop induction
15729 Compilers sometimes generate code that is incompatible with wraparound
15730 integer arithmetic. A simple example is an algebraic simplification: a
15731 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
15732 because it assumes that @code{i * 2000} does not overflow. The
15733 translation is not equivalent to the original when overflow occurs:
15734 e.g., in the typical case of 32-bit signed two's complement wraparound
15735 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
15736 the original expression returns @minus{}2147483 but the optimized
15737 version returns the mathematically correct value 2147484.
15739 More subtly, loop induction optimizations often exploit the undefined
15740 behavior of signed overflow. Consider the following contrived function
15745 sumc (int lo, int hi)
15749 for (i = lo; i <= hi; i++)
15756 To avoid multiplying by 53 each time through the loop, an optimizing
15757 compiler might internally transform @code{sumc} to the equivalent of the
15762 transformed_sumc (int lo, int hi)
15767 for (ic = lo * 53; ic <= hic; ic += 53)
15774 This transformation is allowed by the C standard, but it is invalid for
15775 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
15776 overflow in computing expressions like @code{hi * 53} can cause the
15777 expression @code{i <= hi} to yield a different value from the
15778 transformed expression @code{ic <= hic}.
15780 For this reason, compilers that use loop induction and similar
15781 techniques often do not support reliable wraparound arithmetic when a
15782 loop induction variable like @code{ic} is involved. Since loop
15783 induction variables are generated by the compiler, and are not visible
15784 in the source code, it is not always trivial to say whether the problem
15787 Hardly any code actually depends on wraparound arithmetic in cases like
15788 these, so in practice these loop induction optimizations are almost
15789 always useful. However, edge cases in this area can cause problems.
15794 for (j = 1; 0 < j; j *= 2)
15799 Here, the loop attempts to iterate through all powers of 2 that
15800 @code{int} can represent, but the C standard allows a compiler to
15801 optimize away the comparison and generate an infinite loop,
15802 under the argument that behavior is undefined on overflow. As of this
15803 writing this optimization is not done by any production version of
15804 @acronym{GCC} with @option{-O2}, but it might be performed by other
15805 compilers, or by more aggressive @acronym{GCC} optimization options,
15806 and the @acronym{GCC} developers have not decided whether it will
15807 continue to work with @acronym{GCC} and @option{-O2}.
15809 @node Signed Overflow Advice
15810 @subsection Practical Advice for Signed Overflow Issues
15811 @cindex integer overflow
15812 @cindex overflow, signed integer
15813 @cindex signed integer overflow
15814 @cindex wraparound arithmetic
15816 Ideally the safest approach is to avoid signed integer overflow
15817 entirely. For example, instead of multiplying two signed integers, you
15818 can convert them to unsigned integers, multiply the unsigned values,
15819 then test whether the result is in signed range.
15821 Rewriting code in this way will be inconvenient, though, particularly if
15822 the signed values might be negative. Also, it may hurt
15823 performance. Using unsigned arithmetic to check for overflow is
15824 particularly painful to do portably and efficiently when dealing with an
15825 integer type like @code{uid_t} whose width and signedness vary from
15826 platform to platform.
15828 Furthermore, many C applications pervasively assume wraparound behavior
15829 and typically it is not easy to find and remove all these assumptions.
15830 Hence it is often useful to maintain nonstandard code that assumes
15831 wraparound on overflow, instead of rewriting the code. The rest of this
15832 section attempts to give practical advice for this situation.
15834 If your code wants to detect signed integer overflow in @code{sum = a +
15835 b}, it is generally safe to use an expression like @code{(sum < a) != (b
15838 If your code uses a signed loop index, make sure that the index cannot
15839 overflow, along with all signed expressions derived from the index.
15840 Here is a contrived example of problematic code with two instances of
15844 for (i = INT_MAX - 10; i <= INT_MAX; i++)
15847 report_overflow ();
15853 Because of the two overflows, a compiler might optimize away or
15854 transform the two comparisons in a way that is incompatible with the
15855 wraparound assumption.
15857 If your code uses an expression like @code{(i * 2000) / 1000} and you
15858 actually want the multiplication to wrap around on overflow, use
15859 unsigned arithmetic
15860 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
15862 If your code assumes wraparound behavior and you want to insulate it
15863 against any @acronym{GCC} optimizations that would fail to support that
15864 behavior, you should use @acronym{GCC}'s @option{-fwrapv} option, which
15865 causes signed overflow to wrap around reliably (except for division and
15866 remainder, as discussed in the next section).
15868 If you need to port to platforms where signed integer overflow does not
15869 reliably wrap around (e.g., due to hardware overflow checking, or to
15870 highly aggressive optimizations), you should consider debugging with
15871 @acronym{GCC}'s @option{-ftrapv} option, which causes signed overflow to
15872 raise an exception.
15874 @node Signed Integer Division
15875 @subsection Signed Integer Division and Integer Overflow
15876 @cindex division, integer
15879 integer division is not always harmless: for example, on CPUs of the
15880 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
15881 which by default terminates the program. Worse, taking the remainder
15882 of these two values typically yields the same signal on these CPUs,
15883 even though the C standard requires @code{INT_MIN % -1} to yield zero
15884 because the expression does not overflow.
15886 @node Null Pointers
15887 @section Properties of Null Pointers
15888 @cindex null pointers
15890 Most modern hosts reliably fail when you attempt to dereference a null
15893 On almost all modern hosts, null pointers use an all-bits-zero internal
15894 representation, so you can reliably use @code{memset} with 0 to set all
15895 the pointers in an array to null values.
15897 If @code{p} is a null pointer to an object type, the C expression
15898 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
15899 the standard says that it has undefined behavior.
15901 @node Buffer Overruns
15902 @section Buffer Overruns and Subscript Errors
15903 @cindex buffer overruns
15905 Buffer overruns and subscript errors are the most common dangerous
15906 errors in C programs. They result in undefined behavior because storing
15907 outside an array typically modifies storage that is used by some other
15908 object, and most modern systems lack runtime checks to catch these
15909 errors. Programs should not rely on buffer overruns being caught.
15911 There is one exception to the usual rule that a portable program cannot
15912 address outside an array. In C, it is valid to compute the address just
15913 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15914 so long as you do not dereference the resulting pointer. But it is not
15915 valid to compute the address just before an object, e.g., @code{&a[-1]};
15916 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
15917 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15918 reliable in general, and it is usually easy enough to avoid the
15919 potential portability problem, e.g., by allocating an extra unused array
15920 element at the start or end.
15922 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
15924 users might also consider using the @option{-fmudflap} option to catch
15927 Buffer overruns are usually caused by off-by-one errors, but there are
15928 more subtle ways to get them.
15930 Using @code{int} values to index into an array or compute array sizes
15931 causes problems on typical 64-bit hosts where an array index might
15932 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
15933 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
15934 are signed, and are wide enough in practice.
15936 If you add or multiply two numbers to calculate an array size, e.g.,
15937 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
15938 multiplication overflows.
15940 Many implementations of the @code{alloca} function silently misbehave
15941 and can generate buffer overflows if given sizes that are too large.
15942 The size limits are implementation dependent, but are at least 4000
15943 bytes on all platforms that we know about.
15945 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
15946 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
15947 portable code should not use them unless the inputs are known to be
15948 within certain limits. The time-related functions can overflow their
15949 buffers if given timestamps out of range (e.g., a year less than -999
15950 or greater than 9999). Time-related buffer overflows cannot happen with
15951 recent-enough versions of the @acronym{GNU} C library, but are possible
15953 implementations. The @code{gets} function is the worst, since it almost
15954 invariably overflows its buffer when presented with an input line larger
15957 @node Volatile Objects
15958 @section Volatile Objects
15959 @cindex volatile objects
15961 The keyword @code{volatile} is often misunderstood in portable code.
15962 Its use inhibits some memory-access optimizations, but programmers often
15963 wish that it had a different meaning than it actually does.
15965 @code{volatile} was designed for code that accesses special objects like
15966 memory-mapped device registers whose contents spontaneously change.
15967 Such code is inherently low-level, and it is difficult to specify
15968 portably what @code{volatile} means in these cases. The C standard
15969 says, ``What constitutes an access to an object that has
15970 volatile-qualified type is implementation-defined,'' so in theory each
15971 implementation is supposed to fill in the gap by documenting what
15972 @code{volatile} means for that implementation. In practice, though,
15973 this documentation is usually absent or incomplete.
15975 One area of confusion is the distinction between objects defined with
15976 volatile types, and volatile lvalues. From the C standard's point of
15977 view, an object defined with a volatile type has externally visible
15978 behavior. You can think of such objects as having little oscilloscope
15979 probes attached to them, so that the user can observe some properties of
15980 accesses to them, just as the user can observe data written to output
15981 files. However, the standard does not make it clear whether users can
15982 observe accesses by volatile lvalues to ordinary objects. For example:
15985 /* Declare and access a volatile object.
15986 Accesses to X are "visible" to users. */
15987 static int volatile x;
15990 /* Access two ordinary objects via a volatile lvalue.
15991 It's not clear whether accesses to *P are "visible". */
15993 int *z = malloc (sizeof (int));
16001 Programmers often wish that @code{volatile} meant ``Perform the memory
16002 access here and now, without merging several memory accesses, without
16003 changing the memory word size, and without reordering.'' But the C
16004 standard does not require this. For objects defined with a volatile
16005 type, accesses must be done before the next sequence point; but
16006 otherwise merging, reordering, and word-size change is allowed. Worse,
16007 it is not clear from the standard whether volatile lvalues provide more
16008 guarantees in general than nonvolatile lvalues, if the underlying
16009 objects are ordinary.
16011 Even when accessing objects defined with a volatile type,
16012 the C standard allows only
16013 extremely limited signal handlers: the behavior is undefined if a signal
16014 handler reads any nonlocal object, or writes to any nonlocal object
16015 whose type is not @code{sig_atomic_t volatile}, or calls any standard
16016 library function other than @code{abort}, @code{signal}, and (if C99)
16017 @code{_Exit}. Hence C compilers need not worry about a signal handler
16018 disturbing ordinary computation, unless the computation accesses a
16019 @code{sig_atomic_t volatile} lvalue that is not a local variable.
16020 (There is an obscure exception for accesses via a pointer to a volatile
16021 character, since it may point into part of a @code{sig_atomic_t
16022 volatile} object.) Posix
16023 adds to the list of library functions callable from a portable signal
16024 handler, but otherwise is like the C standard in this area.
16026 Some C implementations allow memory-access optimizations within each
16027 translation unit, such that actual behavior agrees with the behavior
16028 required by the standard only when calling a function in some other
16029 translation unit, and a signal handler acts like it was called from a
16030 different translation unit. The C standard hints that in these
16031 implementations, objects referred to by signal handlers ``would require
16032 explicit specification of @code{volatile} storage, as well as other
16033 implementation-defined restrictions.'' But unfortunately even for this
16034 special case these other restrictions are often not documented well.
16035 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
16036 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
16037 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
16038 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
16039 restrictions imposed by the @acronym{GNU} C library. Restrictions
16040 differ on other platforms.
16042 If possible, it is best to use a signal handler that fits within the
16043 limits imposed by the C and Posix standards.
16045 If this is not practical, you can try the following rules of thumb. A
16046 signal handler should access only volatile lvalues, preferably lvalues
16047 that refer to objects defined with a volatile type, and should not
16048 assume that the accessed objects have an internally consistent state
16049 if they are larger than a machine word. Furthermore, installers
16050 should employ compilers and compiler options that are commonly used
16051 for building operating system kernels, because kernels often need more
16052 from @code{volatile} than the C Standard requires, and installers who
16053 compile an application in a similar environment can sometimes benefit
16054 from the extra constraints imposed by kernels on compilers.
16055 Admittedly we are handwaving somewhat here, as there are few
16056 guarantees in this area; the rules of thumb may help to fix some bugs
16057 but there is a good chance that they will not fix them all.
16059 For @code{volatile}, C++ has the same problems that C does.
16060 Multithreaded applications have even more problems with @code{volatile},
16061 but they are beyond the scope of this section.
16063 The bottom line is that using @code{volatile} typically hurts
16064 performance but should not hurt correctness. In some cases its use
16065 does help correctness, but these cases are often so poorly understood
16066 that all too often adding @code{volatile} to a data structure merely
16067 alleviates some symptoms of a bug while not fixing the bug in general.
16069 @node Floating Point Portability
16070 @section Floating Point Portability
16071 @cindex floating point
16073 Almost all modern systems use IEEE-754 floating point, and it is safe to
16074 assume IEEE-754 in most portable code these days. For more information,
16075 please see David Goldberg's classic paper
16076 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
16077 Scientist Should Know About Floating-Point Arithmetic}.
16079 @node Exiting Portably
16080 @section Exiting Portably
16081 @cindex exiting portably
16083 A C or C++ program can exit with status @var{N} by returning
16084 @var{N} from the @code{main} function. Portable programs are supposed
16085 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
16086 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
16087 fail by exiting with status 1, and test programs that assume Posix can
16088 fail by exiting with status values from 1 through 255. Programs on
16089 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
16090 status when @code{main} returned nonzero, but ancient systems like these
16091 are no longer of practical concern.
16093 A program can also exit with status @var{N} by passing @var{N} to the
16094 @code{exit} function, and a program can fail by calling the @code{abort}
16095 function. If a program is specialized to just some platforms, it can fail
16096 by calling functions specific to those platforms, e.g., @code{_exit}
16097 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
16098 function should be declared, typically by including a header. For
16099 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
16100 either directly or via the default includes (@pxref{Default Includes}).
16102 A program can fail due to undefined behavior such as dereferencing a null
16103 pointer, but this is not recommended as undefined behavior allows an
16104 implementation to do whatever it pleases and this includes exiting
16108 @c ================================================== Manual Configuration
16110 @node Manual Configuration
16111 @chapter Manual Configuration
16113 A few kinds of features can't be guessed automatically by running test
16114 programs. For example, the details of the object-file format, or
16115 special options that need to be passed to the compiler or linker. You
16116 can check for such features using ad-hoc means, such as having
16117 @command{configure} check the output of the @code{uname} program, or
16118 looking for libraries that are unique to particular systems. However,
16119 Autoconf provides a uniform method for handling unguessable features.
16122 * Specifying Names:: Specifying the system type
16123 * Canonicalizing:: Getting the canonical system type
16124 * Using System Type:: What to do with the system type
16127 @node Specifying Names
16128 @section Specifying the System Type
16129 @cindex System type
16132 @command{configure} scripts can make decisions based on a canonical name
16133 for the system type, which has the form:
16134 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
16135 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
16137 @command{configure} can usually guess the canonical name for the type of
16138 system it's running on. To do so it runs a script called
16139 @command{config.guess}, which infers the name using the @code{uname}
16140 command or symbols predefined by the C preprocessor.
16142 Alternately, the user can specify the system type with command line
16143 arguments to @command{configure}. Doing so is necessary when
16144 cross-compiling. In the most complex case of cross-compiling, three
16145 system types are involved. The options to specify them are:
16148 @item --build=@var{build-type}
16149 the type of system on which the package is being configured and
16150 compiled. It defaults to the result of running @command{config.guess}.
16152 @item --host=@var{host-type}
16153 the type of system on which the package runs. By default it is the
16154 same as the build machine. Specifying it enables the cross-compilation
16157 @item --target=@var{target-type}
16158 the type of system for which any compiler tools in the package
16159 produce code (rarely needed). By default, it is the same as host.
16162 If you mean to override the result of @command{config.guess}, use
16163 @option{--build}, not @option{--host}, since the latter enables
16164 cross-compilation. For historical reasons,
16165 whenever you specify @option{--host},
16166 be sure to specify @option{--build} too; this will be fixed in the
16167 future. So, to enter cross-compilation mode, use a command like this
16170 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
16174 Note that if you do not specify @option{--host}, @command{configure}
16175 fails if it can't run the code generated by the specified compiler. For
16176 example, configuring as follows fails:
16179 ./configure CC=m68k-coff-gcc
16182 In the future, when cross-compiling Autoconf will @emph{not}
16183 accept tools (compilers, linkers, assemblers) whose name is not
16184 prefixed with the host type. The only case when this may be
16185 useful is when you really are not cross-compiling, but only
16186 building for a least-common-denominator architecture: an example
16187 is building for @code{i386-pc-linux-gnu} while running on an
16188 @code{i686-pc-linux-gnu} architecture. In this case, some particular
16189 pairs might be similar enough to let you get away with the system
16190 compilers, but in general the compiler might make bogus assumptions
16191 on the host: if you know what you are doing, please create symbolic
16192 links from the host compiler to the build compiler.
16194 @cindex @command{config.sub}
16195 @command{configure} recognizes short aliases for many system types; for
16196 example, @samp{decstation} can be used instead of
16197 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
16198 @command{config.sub} to canonicalize system type aliases.
16200 This section deliberately omits the description of the obsolete
16201 interface; see @ref{Hosts and Cross-Compilation}.
16204 @node Canonicalizing
16205 @section Getting the Canonical System Type
16206 @cindex System type
16207 @cindex Canonical system type
16209 The following macros make the system type available to @command{configure}
16212 @ovindex build_alias
16213 @ovindex host_alias
16214 @ovindex target_alias
16216 The variables @samp{build_alias}, @samp{host_alias}, and
16217 @samp{target_alias} are always exactly the arguments of @option{--build},
16218 @option{--host}, and @option{--target}; in particular, they are left empty
16219 if the user did not use them, even if the corresponding
16220 @code{AC_CANONICAL} macro was run. Any configure script may use these
16221 variables anywhere. These are the variables that should be used when in
16222 interaction with the user.
16224 If you need to recognize some special environments based on their system
16225 type, run the following macros to get canonical system names. These
16226 variables are not set before the macro call.
16228 If you use these macros, you must distribute @command{config.guess} and
16229 @command{config.sub} along with your source code. @xref{Output}, for
16230 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
16231 to control in which directory @command{configure} looks for those scripts.
16234 @defmac AC_CANONICAL_BUILD
16235 @acindex{CANONICAL_BUILD}
16238 @ovindex build_vendor
16240 Compute the canonical build-system type variable, @code{build}, and its
16241 three individual parts @code{build_cpu}, @code{build_vendor}, and
16244 If @option{--build} was specified, then @code{build} is the
16245 canonicalization of @code{build_alias} by @command{config.sub},
16246 otherwise it is determined by the shell script @command{config.guess}.
16249 @defmac AC_CANONICAL_HOST
16250 @acindex{CANONICAL_HOST}
16253 @ovindex host_vendor
16255 Compute the canonical host-system type variable, @code{host}, and its
16256 three individual parts @code{host_cpu}, @code{host_vendor}, and
16259 If @option{--host} was specified, then @code{host} is the
16260 canonicalization of @code{host_alias} by @command{config.sub},
16261 otherwise it defaults to @code{build}.
16264 @defmac AC_CANONICAL_TARGET
16265 @acindex{CANONICAL_TARGET}
16267 @ovindex target_cpu
16268 @ovindex target_vendor
16270 Compute the canonical target-system type variable, @code{target}, and its
16271 three individual parts @code{target_cpu}, @code{target_vendor}, and
16274 If @option{--target} was specified, then @code{target} is the
16275 canonicalization of @code{target_alias} by @command{config.sub},
16276 otherwise it defaults to @code{host}.
16279 Note that there can be artifacts due to the backward compatibility
16280 code. See @xref{Hosts and Cross-Compilation}, for more.
16282 @node Using System Type
16283 @section Using the System Type
16285 In @file{configure.ac} the system type is generally used by one or more
16286 @code{case} statements to select system-specifics. Shell wildcards can
16287 be used to match a group of system types.
16289 For example, an extra assembler code object file could be chosen, giving
16290 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
16291 following would be used in a makefile to add the object to a
16292 program or library.
16296 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
16297 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
16300 AC_SUBST([CYCLE_OBJ])
16303 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
16304 to select variant source files, for example optimized code for some
16305 CPUs. The configured CPU type doesn't always indicate exact CPU types,
16306 so some runtime capability checks may be necessary too.
16310 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
16311 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
16312 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
16316 The host system type can also be used to find cross-compilation tools
16317 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
16319 The above examples all show @samp{$host}, since this is where the code
16320 is going to run. Only rarely is it necessary to test @samp{$build}
16321 (which is where the build is being done).
16323 Whenever you're tempted to use @samp{$host} it's worth considering
16324 whether some sort of probe would be better. New system types come along
16325 periodically or previously missing features are added. Well-written
16326 probes can adapt themselves to such things, but hard-coded lists of
16327 names can't. Here are some guidelines,
16331 Availability of libraries and library functions should always be checked
16334 Variant behavior of system calls is best identified with runtime tests
16335 if possible, but bug workarounds or obscure difficulties might have to
16336 be driven from @samp{$host}.
16338 Assembler code is inevitably highly CPU-specific and is best selected
16339 according to @samp{$host_cpu}.
16341 Assembler variations like underscore prefix on globals or ELF versus
16342 COFF type directives are however best determined by probing, perhaps
16343 even examining the compiler output.
16346 @samp{$target} is for use by a package creating a compiler or similar.
16347 For ordinary packages it's meaningless and should not be used. It
16348 indicates what the created compiler should generate code for, if it can
16349 cross-compile. @samp{$target} generally selects various hard-coded CPU
16350 and system conventions, since usually the compiler or tools under
16351 construction themselves determine how the target works.
16354 @c ===================================================== Site Configuration.
16356 @node Site Configuration
16357 @chapter Site Configuration
16359 @command{configure} scripts support several kinds of local configuration
16360 decisions. There are ways for users to specify where external software
16361 packages are, include or exclude optional features, install programs
16362 under modified names, and set default values for @command{configure}
16366 * Help Formatting:: Customizing @samp{configure --help}
16367 * External Software:: Working with other optional software
16368 * Package Options:: Selecting optional features
16369 * Pretty Help Strings:: Formatting help string
16370 * Option Checking:: Controlling checking of @command{configure} options
16371 * Site Details:: Configuring site details
16372 * Transforming Names:: Changing program names when installing
16373 * Site Defaults:: Giving @command{configure} local defaults
16376 @node Help Formatting
16377 @section Controlling Help Output
16379 Users consult @samp{configure --help} to learn of configuration
16380 decisions specific to your package. By default, @command{configure}
16381 breaks this output into sections for each type of option; within each
16382 section, help strings appear in the order @file{configure.ac} defines
16388 --enable-bar include bar
16395 @defmac AC_PRESERVE_HELP_ORDER
16396 @acindex{PRESERVE_HELP_ORDER}
16398 Request an alternate @option{--help} format, in which options of all
16399 types appear together, in the order defined. Call this macro before any
16400 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
16403 Optional Features and Packages:
16405 --enable-bar include bar
16411 @node External Software
16412 @section Working With External Software
16413 @cindex External software
16415 Some packages require, or can optionally use, other software packages
16416 that are already installed. The user can give @command{configure}
16417 command line options to specify which such external software to use.
16418 The options have one of these forms:
16420 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16423 --with-@var{package}[=@var{arg}]
16424 --without-@var{package}
16427 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
16428 instead of some other linker. @option{--with-x} means work with The X
16431 The user can give an argument by following the package name with
16432 @samp{=} and the argument. Giving an argument of @samp{no} is for
16433 packages that are used by default; it says to @emph{not} use the
16434 package. An argument that is neither @samp{yes} nor @samp{no} could
16435 include a name or number of a version of the other package, to specify
16436 more precisely which other package this program is supposed to work
16437 with. If no argument is given, it defaults to @samp{yes}.
16438 @option{--without-@var{package}} is equivalent to
16439 @option{--with-@var{package}=no}.
16441 Normally @command{configure} scripts complain about
16442 @option{--with-@var{package}} options that they do not support.
16443 @xref{Option Checking}, for details, and for how to override the
16446 For each external software package that may be used, @file{configure.ac}
16447 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
16448 user asked to use it. Whether each package is used or not by default,
16449 and which arguments are valid, is up to you.
16451 @anchor{AC_ARG_WITH}
16452 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @
16453 @ovar{action-if-given}, @ovar{action-if-not-given})
16455 If the user gave @command{configure} the option @option{--with-@var{package}}
16456 or @option{--without-@var{package}}, run shell commands
16457 @var{action-if-given}. If neither option was given, run shell commands
16458 @var{action-if-not-given}. The name @var{package} indicates another
16459 software package that this program should work with. It should consist
16460 only of alphanumeric characters, dashes, and dots.
16462 The option's argument is available to the shell commands
16463 @var{action-if-given} in the shell variable @code{withval}, which is
16464 actually just the value of the shell variable named
16465 @code{with_@var{package}}, with any non-alphanumeric characters in
16466 @var{package} changed into @samp{_}. You may use that variable instead,
16469 The argument @var{help-string} is a description of the option that
16472 --with-readline support fancy command line editing
16476 @var{help-string} may be more than one line long, if more detail is
16477 needed. Just make sure the columns line up in @samp{configure
16478 --help}. Avoid tabs in the help string. You'll need to enclose the
16479 help string in @samp{[} and @samp{]} in order to produce the leading
16482 You should format your @var{help-string} with the macro
16483 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16485 The following example shows how to use the @code{AC_ARG_WITH} macro in
16486 a common situation. You want to let the user decide whether to enable
16487 support for an external library (e.g., the readline library); if the user
16488 specified neither @option{--with-readline} nor @option{--without-readline},
16489 you want to enable support for readline only if the library is available
16492 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16494 AC_ARG_WITH([readline],
16495 [AS_HELP_STRING([--with-readline],
16496 [support fancy command line editing @@<:@@default=check@@:>@@])],
16498 [with_readline=check])
16501 AS_IF([test "x$with_readline" != xno],
16502 [AC_CHECK_LIB([readline], [main],
16503 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16504 AC_DEFINE([HAVE_LIBREADLINE], [1],
16505 [Define if you have libreadline])
16507 [if test "x$with_readline" != xcheck; then
16509 [--with-readline was given, but test for readline failed])
16514 The next example shows how to use @code{AC_ARG_WITH} to give the user the
16515 possibility to enable support for the readline library, in case it is still
16516 experimental and not well tested, and is therefore disabled by default.
16518 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16520 AC_ARG_WITH([readline],
16521 [AS_HELP_STRING([--with-readline],
16522 [enable experimental support for readline])],
16524 [with_readline=no])
16527 AS_IF([test "x$with_readline" != xno],
16528 [AC_CHECK_LIB([readline], [main],
16529 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16530 AC_DEFINE([HAVE_LIBREADLINE], [1],
16531 [Define if you have libreadline])
16534 [--with-readline was given, but test for readline failed])],
16538 The last example shows how to use @code{AC_ARG_WITH} to give the user the
16539 possibility to disable support for the readline library, given that it is
16540 an important feature and that it should be enabled by default.
16542 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16544 AC_ARG_WITH([readline],
16545 [AS_HELP_STRING([--without-readline],
16546 [disable support for readline])],
16548 [with_readline=yes])
16551 AS_IF([test "x$with_readline" != xno],
16552 [AC_CHECK_LIB([readline], [main],
16553 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16554 AC_DEFINE([HAVE_LIBREADLINE], [1],
16555 [Define if you have libreadline])
16558 [readline test failed (--without-readline to disable)])],
16562 These three examples can be easily adapted to the case where
16563 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
16564 @ref{Package Options}).
16567 @node Package Options
16568 @section Choosing Package Options
16569 @cindex Package options
16570 @cindex Options, package
16572 If a software package has optional compile-time features, the user can
16573 give @command{configure} command line options to specify whether to
16574 compile them. The options have one of these forms:
16576 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16579 --enable-@var{feature}[=@var{arg}]
16580 --disable-@var{feature}
16583 These options allow users to choose which optional features to build and
16584 install. @option{--enable-@var{feature}} options should never make a
16585 feature behave differently or cause one feature to replace another.
16586 They should only cause parts of the program to be built rather than left
16589 The user can give an argument by following the feature name with
16590 @samp{=} and the argument. Giving an argument of @samp{no} requests
16591 that the feature @emph{not} be made available. A feature with an
16592 argument looks like @option{--enable-debug=stabs}. If no argument is
16593 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
16594 equivalent to @option{--enable-@var{feature}=no}.
16596 Normally @command{configure} scripts complain about
16597 @option{--enable-@var{package}} options that they do not support.
16598 @xref{Option Checking}, for details, and for how to override the
16601 For each optional feature, @file{configure.ac} should call
16602 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
16603 to include it. Whether each feature is included or not by default, and
16604 which arguments are valid, is up to you.
16606 @anchor{AC_ARG_ENABLE}
16607 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @
16608 @ovar{action-if-given}, @ovar{action-if-not-given})
16609 @acindex{ARG_ENABLE}
16610 If the user gave @command{configure} the option
16611 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
16612 shell commands @var{action-if-given}. If neither option was given, run
16613 shell commands @var{action-if-not-given}. The name @var{feature}
16614 indicates an optional user-level facility. It should consist only of
16615 alphanumeric characters, dashes, and dots.
16617 The option's argument is available to the shell commands
16618 @var{action-if-given} in the shell variable @code{enableval}, which is
16619 actually just the value of the shell variable named
16620 @code{enable_@var{feature}}, with any non-alphanumeric characters in
16621 @var{feature} changed into @samp{_}. You may use that variable instead,
16622 if you wish. The @var{help-string} argument is like that of
16623 @code{AC_ARG_WITH} (@pxref{External Software}).
16625 You should format your @var{help-string} with the macro
16626 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16628 See the examples suggested with the definition of @code{AC_ARG_WITH}
16629 (@pxref{External Software}) to get an idea of possible applications of
16630 @code{AC_ARG_ENABLE}.
16633 @node Pretty Help Strings
16634 @section Making Your Help Strings Look Pretty
16635 @cindex Help strings
16637 Properly formatting the @samp{help strings} which are used in
16638 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
16639 (@pxref{Package Options}) can be challenging. Specifically, you want
16640 your own @samp{help strings} to line up in the appropriate columns of
16641 @samp{configure --help} just like the standard Autoconf @samp{help
16642 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
16644 @anchor{AS_HELP_STRING}
16645 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
16646 @asindex{HELP_STRING}
16648 Expands into an help string that looks pretty when the user executes
16649 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
16650 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
16651 Options}). The following example makes this clearer.
16655 [AS_HELP_STRING([--with-foo],
16656 [use foo (default is no)])],
16657 [use_foo=$withval],
16661 The second argument of @code{AS_HELP_STRING} is
16662 not a literal, and should not be double quoted.
16663 @xref{Autoconf Language}, for a more detailed explanation.
16664 Then the last few lines of @samp{configure --help} appear like
16668 --enable and --with options recognized:
16669 --with-foo use foo (default is no)
16672 The @code{AS_HELP_STRING} macro is particularly helpful when the
16673 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
16674 arguments, as shown in the following example.
16677 AC_DEFUN([MY_ARG_WITH],
16679 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
16680 [use_[]$1=$withval],
16686 @node Option Checking
16687 @section Controlling Checking of @command{configure} Options
16688 @cindex Options, Package
16690 The @command{configure} script checks its command-line options against a
16691 list of known options, like @option{--help} or @option{--config-cache}.
16692 An unknown option ordinarily indicates a mistake by the user and
16693 @command{configure} halts with an error. However, by default unknown
16694 @option{--with-@var{package}} and @option{--enable-@var{feature}}
16695 options elicit only a warning, to support configuring entire source
16698 Source trees often contain multiple packages with a top-level
16699 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
16700 (@pxref{Subdirectories}). Because the packages generally support
16701 different @option{--with-@var{package}} and
16702 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
16703 Standards say they must accept unrecognized options without halting.
16704 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
16705 automatically disables the warnings.
16707 This default behavior may be modified in two ways. First, the installer
16708 can invoke @command{configure --disable-option-checking} to disable
16709 these warnings, or invoke @command{configure --enable-option-checking=fatal}
16710 options to turn them into fatal errors, respectively. Second, the
16711 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
16713 @defmac AC_DISABLE_OPTION_CHECKING
16714 @acindex{DISABLE_OPTION_CHECKING}
16716 By default, disable warnings related to any unrecognized
16717 @option{--with-@var{package}} or @option{--enable-@var{feature}}
16718 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
16720 The installer can override this behavior by passing
16721 @option{--enable-option-checking} (enable warnings) or
16722 @option{--enable-option-checking=fatal} (enable errors) to
16723 @command{configure}.
16728 @section Configuring Site Details
16729 @cindex Site details
16731 Some software packages require complex site-specific information. Some
16732 examples are host names to use for certain services, company names, and
16733 email addresses to contact. Since some configuration scripts generated
16734 by Metaconfig ask for such information interactively, people sometimes
16735 wonder how to get that information in Autoconf-generated configuration
16736 scripts, which aren't interactive.
16738 Such site configuration information should be put in a file that is
16739 edited @emph{only by users}, not by programs. The location of the file
16740 can either be based on the @code{prefix} variable, or be a standard
16741 location such as the user's home directory. It could even be specified
16742 by an environment variable. The programs should examine that file at
16743 runtime, rather than at compile time. Runtime configuration is more
16744 convenient for users and makes the configuration process simpler than
16745 getting the information while configuring. @xref{Directory Variables, ,
16746 Variables for Installation Directories, standards, @acronym{GNU} Coding
16747 Standards}, for more information on where to put data files.
16749 @node Transforming Names
16750 @section Transforming Program Names When Installing
16751 @cindex Transforming program names
16752 @cindex Program names, transforming
16754 Autoconf supports changing the names of programs when installing them.
16755 In order to use these transformations, @file{configure.ac} must call the
16756 macro @code{AC_ARG_PROGRAM}.
16758 @defmac AC_ARG_PROGRAM
16759 @acindex{ARG_PROGRAM}
16760 @ovindex program_transform_name
16761 Place in output variable @code{program_transform_name} a sequence of
16762 @code{sed} commands for changing the names of installed programs.
16764 If any of the options described below are given to @command{configure},
16765 program names are transformed accordingly. Otherwise, if
16766 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
16767 is given, the target type followed by a dash is used as a prefix.
16768 Otherwise, no program name transformation is done.
16772 * Transformation Options:: @command{configure} options to transform names
16773 * Transformation Examples:: Sample uses of transforming names
16774 * Transformation Rules:: Makefile uses of transforming names
16777 @node Transformation Options
16778 @subsection Transformation Options
16780 You can specify name transformations by giving @command{configure} these
16781 command line options:
16784 @item --program-prefix=@var{prefix}
16785 prepend @var{prefix} to the names;
16787 @item --program-suffix=@var{suffix}
16788 append @var{suffix} to the names;
16790 @item --program-transform-name=@var{expression}
16791 perform @code{sed} substitution @var{expression} on the names.
16794 @node Transformation Examples
16795 @subsection Transformation Examples
16797 These transformations are useful with programs that can be part of a
16798 cross-compilation development environment. For example, a
16799 cross-assembler running on a Sun 4 configured with
16800 @option{--target=i960-vxworks} is normally installed as
16801 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
16802 with a native Sun 4 assembler.
16804 You can force a program name to begin with @file{g}, if you don't want
16805 @acronym{GNU} programs installed on your system to shadow other programs with
16806 the same name. For example, if you configure @acronym{GNU} @code{diff} with
16807 @option{--program-prefix=g}, then when you run @samp{make install} it is
16808 installed as @file{/usr/local/bin/gdiff}.
16810 As a more sophisticated example, you could use
16813 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
16817 to prepend @samp{g} to most of the program names in a source tree,
16818 excepting those like @code{gdb} that already have one and those like
16819 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
16820 assuming that you have a source tree containing those programs that is
16821 set up to use this feature.)
16823 One way to install multiple versions of some programs simultaneously is
16824 to append a version number to the name of one or both. For example, if
16825 you want to keep Autoconf version 1 around for awhile, you can configure
16826 Autoconf version 2 using @option{--program-suffix=2} to install the
16827 programs as @file{/usr/local/bin/autoconf2},
16828 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
16829 that only the binaries are renamed, therefore you'd have problems with
16830 the library files which might overlap.
16832 @node Transformation Rules
16833 @subsection Transformation Rules
16835 Here is how to use the variable @code{program_transform_name} in a
16836 @file{Makefile.in}:
16839 PROGRAMS = cp ls rm
16840 transform = @@program_transform_name@@
16842 for p in $(PROGRAMS); do \
16843 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
16844 sed '$(transform)'`; \
16848 for p in $(PROGRAMS); do \
16849 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
16853 It is guaranteed that @code{program_transform_name} is never empty, and
16854 that there are no useless separators. Therefore you may safely embed
16855 @code{program_transform_name} within a sed program using @samp{;}:
16858 transform = @@program_transform_name@@
16859 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
16862 Whether to do the transformations on documentation files (Texinfo or
16863 @code{man}) is a tricky question; there seems to be no perfect answer,
16864 due to the several reasons for name transforming. Documentation is not
16865 usually particular to a specific architecture, and Texinfo files do not
16866 conflict with system documentation. But they might conflict with
16867 earlier versions of the same files, and @code{man} pages sometimes do
16868 conflict with system documentation. As a compromise, it is probably
16869 best to do name transformations on @code{man} pages but not on Texinfo
16872 @node Site Defaults
16873 @section Setting Site Defaults
16874 @cindex Site defaults
16876 Autoconf-generated @command{configure} scripts allow your site to provide
16877 default values for some configuration values. You do this by creating
16878 site- and system-wide initialization files.
16880 @evindex CONFIG_SITE
16881 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
16882 uses its value as the name of a shell script to read. Otherwise, it
16883 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
16884 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
16885 settings in machine-specific files override those in machine-independent
16886 ones in case of conflict.
16888 Site files can be arbitrary shell scripts, but only certain kinds of
16889 code are really appropriate to be in them. Because @command{configure}
16890 reads any cache file after it has read any site files, a site file can
16891 define a default cache file to be shared between all Autoconf-generated
16892 @command{configure} scripts run on that system (@pxref{Cache Files}). If
16893 you set a default cache file in a site file, it is a good idea to also
16894 set the output variable @code{CC} in that site file, because the cache
16895 file is only valid for a particular compiler, but many systems have
16898 You can examine or override the value set by a command line option to
16899 @command{configure} in a site file; options set shell variables that have
16900 the same names as the options, with any dashes turned into underscores.
16901 The exceptions are that @option{--without-} and @option{--disable-} options
16902 are like giving the corresponding @option{--with-} or @option{--enable-}
16903 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
16904 sets the variable @code{cache_file} to the value @samp{localcache};
16905 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16906 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16907 variable @code{prefix} to the value @samp{/usr}; etc.
16909 Site files are also good places to set default values for other output
16910 variables, such as @code{CFLAGS}, if you need to give them non-default
16911 values: anything you would normally do, repetitively, on the command
16912 line. If you use non-default values for @var{prefix} or
16913 @var{exec_prefix} (wherever you locate the site file), you can set them
16914 in the site file if you specify it with the @code{CONFIG_SITE}
16915 environment variable.
16917 You can set some cache values in the site file itself. Doing this is
16918 useful if you are cross-compiling, where it is impossible to check features
16919 that require running a test program. You could ``prime the cache'' by
16920 setting those values correctly for that system in
16921 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
16922 variables you need to set, look for shell variables with @samp{_cv_} in
16923 their names in the affected @command{configure} scripts, or in the Autoconf
16924 M4 source code for those macros.
16926 The cache file is careful to not override any variables set in the site
16927 files. Similarly, you should not override command-line options in the
16928 site files. Your code should check that variables such as @code{prefix}
16929 and @code{cache_file} have their default values (as set near the top of
16930 @command{configure}) before changing them.
16932 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
16933 command @samp{configure --prefix=/usr/share/local/gnu} would read this
16934 file (if @code{CONFIG_SITE} is not set to a different file).
16937 # config.site for configure
16939 # Change some defaults.
16940 test "$prefix" = NONE && prefix=/usr/share/local/gnu
16941 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
16942 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
16943 test "$localstatedir" = '$prefix/var' && localstatedir=/var
16945 # Give Autoconf 2.x generated configure scripts a shared default
16946 # cache file for feature test results, architecture-specific.
16947 if test "$cache_file" = /dev/null; then
16948 cache_file="$prefix/var/config.cache"
16949 # A cache file is only valid for one C compiler.
16955 @c ============================================== Running configure Scripts.
16957 @node Running configure Scripts
16958 @chapter Running @command{configure} Scripts
16959 @cindex @command{configure}
16961 Below are instructions on how to configure a package that uses a
16962 @command{configure} script, suitable for inclusion as an @file{INSTALL}
16963 file in the package. A plain-text version of @file{INSTALL} which you
16964 may use comes with Autoconf.
16967 * Basic Installation:: Instructions for typical cases
16968 * Compilers and Options:: Selecting compilers and optimization
16969 * Multiple Architectures:: Compiling for multiple architectures at once
16970 * Installation Names:: Installing in different directories
16971 * Optional Features:: Selecting optional features
16972 * System Type:: Specifying the system type
16973 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
16974 * Defining Variables:: Specifying the compiler etc.
16975 * configure Invocation:: Changing how @command{configure} runs
16979 @include install.texi
16982 @c ============================================== config.status Invocation
16984 @node config.status Invocation
16985 @chapter config.status Invocation
16986 @cindex @command{config.status}
16988 The @command{configure} script creates a file named @file{config.status},
16989 which actually configures, @dfn{instantiates}, the template files. It
16990 also records the configuration options that were specified when the
16991 package was last configured in case reconfiguring is needed.
16995 ./config.status @var{option}@dots{} [@var{file}@dots{}]
16998 It configures the @var{files}; if none are specified, all the templates
16999 are instantiated. The files must be specified without their
17000 dependencies, as in
17003 ./config.status foobar
17010 ./config.status foobar:foo.in:bar.in
17013 The supported options are:
17018 Print a summary of the command line options, the list of the template
17023 Print the version number of Autoconf and the configuration settings,
17029 Do not print progress messages.
17033 Don't remove the temporary files.
17035 @item --file=@var{file}[:@var{template}]
17036 Require that @var{file} be instantiated as if
17037 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
17038 @var{file} and @var{template} may be @samp{-} in which case the standard
17039 output and/or standard input, respectively, is used. If a
17040 @var{template} file name is relative, it is first looked for in the build
17041 tree, and then in the source tree. @xref{Configuration Actions}, for
17044 This option and the following ones provide one way for separately
17045 distributed packages to share the values computed by @command{configure}.
17046 Doing so can be useful if some of the packages need a superset of the
17047 features that one of them, perhaps a common library, does. These
17048 options allow a @file{config.status} file to create files other than the
17049 ones that its @file{configure.ac} specifies, so it can be used for a
17052 @item --header=@var{file}[:@var{template}]
17053 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
17056 Ask @file{config.status} to update itself and exit (no instantiation).
17057 This option is useful if you change @command{configure}, so that the
17058 results of some tests might be different from the previous run. The
17059 @option{--recheck} option reruns @command{configure} with the same arguments
17060 you used before, plus the @option{--no-create} option, which prevents
17061 @command{configure} from running @file{config.status} and creating
17062 @file{Makefile} and other files, and the @option{--no-recursion} option,
17063 which prevents @command{configure} from running other @command{configure}
17064 scripts in subdirectories. (This is so other Make rules can
17065 run @file{config.status} when it changes; @pxref{Automatic Remaking},
17069 @file{config.status} checks several optional environment variables that
17070 can alter its behavior:
17072 @defvar CONFIG_SHELL
17073 @evindex CONFIG_SHELL
17074 The shell with which to run @command{configure} for the @option{--recheck}
17075 option. It must be Bourne-compatible. The default is a shell that
17076 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
17077 Invoking @command{configure} by hand bypasses this setting, so you may
17078 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
17079 to insure that the same shell is used everywhere. The absolute name of the
17080 shell should be passed.
17083 @defvar CONFIG_STATUS
17084 @evindex CONFIG_STATUS
17085 The file name to use for the shell script that records the
17086 configuration. The default is @file{./config.status}. This variable is
17087 useful when one package uses parts of another and the @command{configure}
17088 scripts shouldn't be merged because they are maintained separately.
17091 You can use @file{./config.status} in your makefiles. For example, in
17092 the dependencies given above (@pxref{Automatic Remaking}),
17093 @file{config.status} is run twice when @file{configure.ac} has changed.
17094 If that bothers you, you can make each run only regenerate the files for
17099 stamp-h: config.h.in config.status
17100 ./config.status config.h
17103 Makefile: Makefile.in config.status
17104 ./config.status Makefile
17108 The calling convention of @file{config.status} has changed; see
17109 @ref{Obsolete config.status Use}, for details.
17112 @c =================================================== Obsolete Constructs
17114 @node Obsolete Constructs
17115 @chapter Obsolete Constructs
17116 @cindex Obsolete constructs
17118 Autoconf changes, and throughout the years some constructs have been
17119 obsoleted. Most of the changes involve the macros, but in some cases
17120 the tools themselves, or even some concepts, are now considered
17123 You may completely skip this chapter if you are new to Autoconf. Its
17124 intention is mainly to help maintainers updating their packages by
17125 understanding how to move to more modern constructs.
17128 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
17129 * acconfig Header:: Additional entries in @file{config.h.in}
17130 * autoupdate Invocation:: Automatic update of @file{configure.ac}
17131 * Obsolete Macros:: Backward compatibility macros
17132 * Autoconf 1:: Tips for upgrading your files
17133 * Autoconf 2.13:: Some fresher tips
17136 @node Obsolete config.status Use
17137 @section Obsolete @file{config.status} Invocation
17139 @file{config.status} now supports arguments to specify the files to
17140 instantiate; see @ref{config.status Invocation}, for more details.
17141 Before, environment variables had to be used.
17143 @defvar CONFIG_COMMANDS
17144 @evindex CONFIG_COMMANDS
17145 The tags of the commands to execute. The default is the arguments given
17146 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
17147 @file{configure.ac}.
17150 @defvar CONFIG_FILES
17151 @evindex CONFIG_FILES
17152 The files in which to perform @samp{@@@var{variable}@@} substitutions.
17153 The default is the arguments given to @code{AC_OUTPUT} and
17154 @code{AC_CONFIG_FILES} in @file{configure.ac}.
17157 @defvar CONFIG_HEADERS
17158 @evindex CONFIG_HEADERS
17159 The files in which to substitute C @code{#define} statements. The
17160 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
17161 macro was not called, @file{config.status} ignores this variable.
17164 @defvar CONFIG_LINKS
17165 @evindex CONFIG_LINKS
17166 The symbolic links to establish. The default is the arguments given to
17167 @code{AC_CONFIG_LINKS}; if that macro was not called,
17168 @file{config.status} ignores this variable.
17171 In @ref{config.status Invocation}, using this old interface, the example
17177 stamp-h: config.h.in config.status
17178 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
17179 CONFIG_HEADERS=config.h ./config.status
17182 Makefile: Makefile.in config.status
17183 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
17184 CONFIG_FILES=Makefile ./config.status
17189 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
17190 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
17191 for @code{CONFIG_COMMANDS}, etc.)
17194 @node acconfig Header
17195 @section @file{acconfig.h}
17197 @cindex @file{acconfig.h}
17198 @cindex @file{config.h.top}
17199 @cindex @file{config.h.bot}
17201 In order to produce @file{config.h.in}, @command{autoheader} needs to
17202 build or to find templates for each symbol. Modern releases of Autoconf
17203 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
17204 Macros}), but in older releases a file, @file{acconfig.h}, contained the
17205 list of needed templates. @command{autoheader} copied comments and
17206 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
17207 the current directory, if present. This file used to be mandatory if
17208 you @code{AC_DEFINE} any additional symbols.
17210 Modern releases of Autoconf also provide @code{AH_TOP} and
17211 @code{AH_BOTTOM} if you need to prepend/append some information to
17212 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
17213 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
17214 @command{autoheader} copies the lines before the line containing
17215 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
17216 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
17217 @command{autoheader} copies the lines after that line to the end of the
17218 file it generates. Either or both of those strings may be omitted. An
17219 even older alternate way to produce the same effect in ancient versions
17220 of Autoconf is to create the files @file{@var{file}.top} (typically
17221 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
17222 directory. If they exist, @command{autoheader} copies them to the
17223 beginning and end, respectively, of its output.
17225 In former versions of Autoconf, the files used in preparing a software
17226 package for distribution were:
17229 configure.ac --. .------> autoconf* -----> configure
17231 [aclocal.m4] --+ `---.
17233 +--> [autoheader*] -> [config.h.in]
17234 [acconfig.h] ----. |
17241 Using only the @code{AH_} macros, @file{configure.ac} should be
17242 self-contained, and should not depend upon @file{acconfig.h} etc.
17245 @node autoupdate Invocation
17246 @section Using @command{autoupdate} to Modernize @file{configure.ac}
17247 @cindex @command{autoupdate}
17249 The @command{autoupdate} program updates a @file{configure.ac} file that
17250 calls Autoconf macros by their old names to use the current macro names.
17251 In version 2 of Autoconf, most of the macros were renamed to use a more
17252 uniform and descriptive naming scheme. @xref{Macro Names}, for a
17253 description of the new scheme. Although the old names still work
17254 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
17255 new names), you can make your @file{configure.ac} files more readable
17256 and make it easier to use the current Autoconf documentation if you
17257 update them to use the new macro names.
17259 @evindex SIMPLE_BACKUP_SUFFIX
17260 If given no arguments, @command{autoupdate} updates @file{configure.ac},
17261 backing up the original version with the suffix @file{~} (or the value
17262 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
17263 set). If you give @command{autoupdate} an argument, it reads that file
17264 instead of @file{configure.ac} and writes the updated file to the
17268 @command{autoupdate} accepts the following options:
17273 Print a summary of the command line options and exit.
17277 Print the version number of Autoconf and exit.
17281 Report processing steps.
17285 Don't remove the temporary files.
17289 Force the update even if the file has not changed. Disregard the cache.
17291 @item --include=@var{dir}
17292 @itemx -I @var{dir}
17293 Also look for input files in @var{dir}. Multiple invocations accumulate.
17294 Directories are browsed from last to first.
17297 @node Obsolete Macros
17298 @section Obsolete Macros
17300 Several macros are obsoleted in Autoconf, for various reasons (typically
17301 they failed to quote properly, couldn't be extended for more recent
17302 issues, etc.). They are still supported, but deprecated: their use
17305 During the jump from Autoconf version 1 to version 2, most of the
17306 macros were renamed to use a more uniform and descriptive naming scheme,
17307 but their signature did not change. @xref{Macro Names}, for a
17308 description of the new naming scheme. Below, if there is just the mapping
17309 from old names to new names for these macros, the reader is invited to
17310 refer to the definition of the new macro for the signature and the
17315 @cvindex _ALL_SOURCE
17316 This macro is a platform-specific subset of
17317 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17322 Replaced by @code{AC_FUNC_ALLOCA} (@pxref{AC_FUNC_ALLOCA}).
17325 @defmac AC_ARG_ARRAY
17326 @acindex{ARG_ARRAY}
17327 Removed because of limited usefulness.
17332 This macro is obsolete; it does nothing.
17335 @defmac AC_C_LONG_DOUBLE
17336 @acindex{C_LONG_DOUBLE}
17337 @cvindex HAVE_LONG_DOUBLE
17338 If the C compiler supports a working @code{long double} type with more
17339 range or precision than the @code{double} type, define
17340 @code{HAVE_LONG_DOUBLE}.
17342 You should use @code{AC_TYPE_LONG_DOUBLE} or
17343 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17346 @defmac AC_CANONICAL_SYSTEM
17347 @acindex{CANONICAL_SYSTEM}
17348 Determine the system type and set output variables to the names of the
17349 canonical system types. @xref{Canonicalizing}, for details about the
17350 variables this macro sets.
17352 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
17353 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
17354 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
17355 other macros (@pxref{Canonicalizing}).
17358 @defmac AC_CHAR_UNSIGNED
17359 @acindex{CHAR_UNSIGNED}
17360 Replaced by @code{AC_C_CHAR_UNSIGNED} (@pxref{AC_C_CHAR_UNSIGNED}).
17363 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
17364 @acindex{CHECK_TYPE}
17365 Autoconf, up to 2.13, used to provide this version of
17366 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
17367 it is a member of the @code{CHECK} clan, it does
17368 more than just checking. Secondly, missing types are defined
17369 using @code{#define}, not @code{typedef}, and this can lead to
17370 problems in the case of pointer types.
17372 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
17373 @ref{Generic Types}, for the description of the current macro.
17375 If the type @var{type} is not defined, define it to be the C (or C++)
17376 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
17378 This macro is equivalent to:
17381 AC_CHECK_TYPE([@var{type}], [],
17382 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
17383 [Define to `@var{default}'
17384 if <sys/types.h> does not define.])])
17387 In order to keep backward compatibility, the two versions of
17388 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
17392 If there are three or four arguments, the modern version is used.
17395 If the second argument appears to be a C or C++ type, then the
17396 obsolete version is used. This happens if the argument is a C or C++
17397 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
17398 followed by one of @samp{[(* } and then by a string of zero or more
17399 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
17402 If the second argument is spelled with the alphabet of valid C and C++
17403 types, the user is warned and the modern version is used.
17406 Otherwise, the modern version is used.
17410 You are encouraged either to use a valid builtin type, or to use the
17411 equivalent modern code (see above), or better yet, to use
17412 @code{AC_CHECK_TYPES} together with
17415 #ifndef HAVE_LOFF_T
17416 typedef loff_t off_t;
17420 @c end of AC_CHECK_TYPE
17422 @defmac AC_CHECKING (@var{feature-description})
17427 AC_MSG_NOTICE([checking @var{feature-description}@dots{}]
17431 @xref{AC_MSG_NOTICE}.
17434 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @
17435 @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
17436 @acindex{COMPILE_CHECK}
17437 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
17438 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
17439 addition that it prints @samp{checking for @var{echo-text}} to the
17440 standard output first, if @var{echo-text} is non-empty. Use
17441 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
17442 messages (@pxref{Printing Messages}).
17447 Replaced by @code{AC_C_CONST} (@pxref{AC_C_CONST}).
17450 @defmac AC_CROSS_CHECK
17451 @acindex{CROSS_CHECK}
17452 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
17459 Check for the Cygwin environment in which case the shell variable
17460 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
17461 means to check the nature of the host is using @code{AC_CANONICAL_HOST}
17462 (@pxref{Canonicalizing}). As a matter of fact this macro is defined as:
17465 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
17467 *cygwin* ) CYGWIN=yes;;
17472 Beware that the variable @env{CYGWIN} has a special meaning when
17473 running Cygwin, and should not be changed. That's yet another reason
17474 not to use this macro.
17477 @defmac AC_DECL_SYS_SIGLIST
17478 @acindex{DECL_SYS_SIGLIST}
17479 @cvindex SYS_SIGLIST_DECLARED
17483 AC_CHECK_DECLS([sys_siglist], [], [],
17484 [#include <signal.h>
17485 /* NetBSD declares sys_siglist in unistd.h. */
17486 #ifdef HAVE_UNISTD_H
17487 # include <unistd.h>
17493 @xref{AC_CHECK_DECLS}.
17496 @defmac AC_DECL_YYTEXT
17497 @acindex{DECL_YYTEXT}
17498 Does nothing, now integrated in @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
17501 @defmac AC_DIR_HEADER
17502 @acindex{DIR_HEADER}
17507 Like calling @code{AC_FUNC_CLOSEDIR_VOID}
17508 (@pxref{AC_FUNC_CLOSEDIR_VOID}) and @code{AC_HEADER_DIRENT}
17509 (@pxref{AC_HEADER_DIRENT}),
17510 but defines a different set of C preprocessor macros to indicate which
17511 header file is found:
17513 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
17514 @item Header @tab Old Symbol @tab New Symbol
17515 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
17516 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
17517 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
17518 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
17522 @defmac AC_DYNIX_SEQ
17523 @acindex{DYNIX_SEQ}
17524 If on DYNIX/ptx, add @option{-lseq} to output variable
17525 @code{LIBS}. This macro used to be defined as
17528 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
17532 now it is just @code{AC_FUNC_GETMNTENT} (@pxref{AC_FUNC_GETMNTENT}).
17538 Defined the output variable @code{EXEEXT} based on the output of the
17539 compiler, which is now done automatically. Typically set to empty
17540 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
17545 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
17546 and sets @code{EMXOS2}. Don't use this macro, the dignified means to
17547 check the nature of the host is using @code{AC_CANONICAL_HOST}
17548 (@pxref{Canonicalizing}).
17551 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @
17552 @ovar{action-if-not-given})
17554 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
17555 support providing a help string (@pxref{AC_ARG_ENABLE}).
17560 Replaced by @code{AC_MSG_ERROR} (@pxref{AC_MSG_ERROR}).
17565 Replaced by @code{AC_PATH_X} (@pxref{AC_PATH_X}).
17568 @defmac AC_FIND_XTRA
17569 @acindex{FIND_XTRA}
17570 Replaced by @code{AC_PATH_XTRA} (@pxref{AC_PATH_XTRA}).
17575 Replaced by @code{m4_foreach_w} (@pxref{m4_foreach_w}).
17578 @defmac AC_FUNC_CHECK
17579 @acindex{FUNC_CHECK}
17580 Replaced by @code{AC_CHECK_FUNC} (@pxref{AC_CHECK_FUNC}).
17583 @anchor{AC_FUNC_SETVBUF_REVERSED}
17584 @defmac AC_FUNC_SETVBUF_REVERSED
17585 @acindex{FUNC_SETVBUF_REVERSED}
17586 @cvindex SETVBUF_REVERSED
17587 @c @fuindex setvbuf
17588 @prindex @code{setvbuf}
17589 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
17590 the buffering type as its second argument and the buffer pointer as the
17591 third, instead of the other way around, and defined
17592 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
17593 were those based on SVR2, which became obsolete in 1987, and the macro
17594 is no longer needed.
17597 @defmac AC_FUNC_WAIT3
17598 @acindex{FUNC_WAIT3}
17599 @cvindex HAVE_WAIT3
17600 If @code{wait3} is found and fills in the contents of its third argument
17601 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
17604 These days portable programs should use @code{waitpid}, not
17605 @code{wait3}, as @code{wait3} has been removed from Posix.
17608 @defmac AC_GCC_TRADITIONAL
17609 @acindex{GCC_TRADITIONAL}
17610 Replaced by @code{AC_PROG_GCC_TRADITIONAL} (@pxref{AC_PROG_GCC_TRADITIONAL}).
17613 @defmac AC_GETGROUPS_T
17614 @acindex{GETGROUPS_T}
17615 Replaced by @code{AC_TYPE_GETGROUPS} (@pxref{AC_TYPE_GETGROUPS}).
17618 @defmac AC_GETLOADAVG
17619 @acindex{GETLOADAVG}
17620 Replaced by @code{AC_FUNC_GETLOADAVG} (@pxref{AC_FUNC_GETLOADAVG}).
17623 @defmac AC_GNU_SOURCE
17624 @acindex{GNU_SOURCE}
17625 @cvindex _GNU_SOURCE
17626 This macro is a platform-specific subset of
17627 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17630 @defmac AC_HAVE_FUNCS
17631 @acindex{HAVE_FUNCS}
17632 Replaced by @code{AC_CHECK_FUNCS} (@pxref{AC_CHECK_FUNCS}).
17635 @defmac AC_HAVE_HEADERS
17636 @acindex{HAVE_HEADERS}
17637 Replaced by @code{AC_CHECK_HEADERS} (@pxref{AC_CHECK_HEADERS}).
17640 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @
17641 @ovar{action-if-not-found}, @ovar{other-libraries})
17642 @acindex{HAVE_LIBRARY}
17643 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
17644 @var{function} argument of @code{main}. In addition, @var{library} can
17645 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
17646 all of those cases, the compiler is passed @option{-lfoo}. However,
17647 @var{library} cannot be a shell variable; it must be a literal name.
17648 @xref{AC_CHECK_LIB}.
17651 @defmac AC_HAVE_POUNDBANG
17652 @acindex{HAVE_POUNDBANG}
17653 Replaced by @code{AC_SYS_INTERPRETER} (@pxref{AC_SYS_INTERPRETER}).
17656 @defmac AC_HEADER_CHECK
17657 @acindex{HEADER_CHECK}
17658 Replaced by @code{AC_CHECK_HEADER} (@pxref{AC_CHECK_HEADER}).
17661 @defmac AC_HEADER_EGREP
17662 @acindex{HEADER_EGREP}
17663 Replaced by @code{AC_EGREP_HEADER} (@pxref{AC_EGREP_HEADER}).
17666 @defmac AC_HELP_STRING
17667 @acindex{HELP_STRING}
17668 Replaced by @code{AS_HELP_STRING} (@pxref{AS_HELP_STRING}).
17671 @defmac AC_INIT (@var{unique-file-in-source-dir})
17673 Formerly @code{AC_INIT} used to have a single argument, and was
17678 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
17680 See @ref{AC_INIT} and @ref{AC_CONFIG_SRCDIR}.
17685 Replaced by @code{AC_C_INLINE} (@pxref{AC_C_INLINE}).
17688 @defmac AC_INT_16_BITS
17689 @acindex{INT_16_BITS}
17690 @cvindex INT_16_BITS
17691 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
17692 Use @samp{AC_CHECK_SIZEOF(int)} instead (@pxref{AC_CHECK_SIZEOF}).
17695 @defmac AC_IRIX_SUN
17697 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
17698 @code{LIBS}. If you were using it to get @code{getmntent}, use
17699 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
17700 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
17701 getpwnam)}. Up to Autoconf 2.13, it used to be
17704 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
17708 now it is defined as
17712 AC_CHECK_LIB([sun], [getpwnam])
17716 See @ref{AC_FUNC_GETMNTENT} and @ref{AC_CHECK_LIB}.
17719 @defmac AC_ISC_POSIX
17720 @acindex{ISC_POSIX}
17722 This macro adds @option{-lcposix} to output variable @code{LIBS} if
17723 necessary for Posix facilities. Sun dropped support for the obsolete
17724 @sc{interactive} Systems Corporation Unix on 2006-07-23. New programs
17725 need not use this macro. It is implemented as
17726 @code{AC_SEARCH_LIBS([strerror], [cposix])} (@pxref{AC_SEARCH_LIBS}).
17731 Same as @samp{AC_LANG([C])} (@pxref{AC_LANG}).
17734 @defmac AC_LANG_CPLUSPLUS
17735 @acindex{LANG_CPLUSPLUS}
17736 Same as @samp{AC_LANG([C++])} (@pxref{AC_LANG}).
17739 @defmac AC_LANG_FORTRAN77
17740 @acindex{LANG_FORTRAN77}
17741 Same as @samp{AC_LANG([Fortran 77])} (@pxref{AC_LANG}).
17744 @defmac AC_LANG_RESTORE
17745 @acindex{LANG_RESTORE}
17746 Select the @var{language} that is saved on the top of the stack, as set
17747 by @code{AC_LANG_SAVE}, remove it from the stack, and call
17748 @code{AC_LANG(@var{language})}. @xref{Language Choice}, for the
17749 preferred way to change languages.
17752 @defmac AC_LANG_SAVE
17753 @acindex{LANG_SAVE}
17754 Remember the current language (as set by @code{AC_LANG}) on a stack.
17755 The current language does not change. @code{AC_LANG_PUSH} is preferred
17756 (@pxref{AC_LANG_PUSH}).
17759 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
17760 @acindex{LINK_FILES}
17761 This is an obsolete version of @code{AC_CONFIG_LINKS}
17762 (@pxref{AC_CONFIG_LINKS}. An updated version of:
17765 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
17773 AC_CONFIG_LINKS([host.h:config/$machine.h
17774 object.h:config/$obj_format.h])
17780 Replaced by @code{AC_PROG_LN_S} (@pxref{AC_PROG_LN_S}).
17783 @defmac AC_LONG_64_BITS
17784 @acindex{LONG_64_BITS}
17785 @cvindex LONG_64_BITS
17786 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
17787 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead
17788 (@pxref{AC_CHECK_SIZEOF}).
17791 @defmac AC_LONG_DOUBLE
17792 @acindex{LONG_DOUBLE}
17793 If the C compiler supports a working @code{long double} type with more
17794 range or precision than the @code{double} type, define
17795 @code{HAVE_LONG_DOUBLE}.
17797 You should use @code{AC_TYPE_LONG_DOUBLE} or
17798 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17801 @defmac AC_LONG_FILE_NAMES
17802 @acindex{LONG_FILE_NAMES}
17805 AC_SYS_LONG_FILE_NAMES
17808 @xref{AC_SYS_LONG_FILE_NAMES}.
17811 @defmac AC_MAJOR_HEADER
17812 @acindex{MAJOR_HEADER}
17813 Replaced by @code{AC_HEADER_MAJOR} (@pxref{AC_HEADER_MAJOR}).
17816 @defmac AC_MEMORY_H
17818 @cvindex NEED_MEMORY_H
17819 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
17820 defined in @file{memory.h}. Today it is equivalent to
17821 @samp{AC_CHECK_HEADERS([memory.h])} (@pxref{AC_CHECK_HEADERS}). Adjust
17822 your code to depend upon
17823 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
17829 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
17830 environment and sets @code{MINGW32}. Don't use this macro, the
17831 dignified means to check the nature of the host is using
17832 @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
17838 @cvindex _POSIX_SOURCE
17839 @cvindex _POSIX_1_SOURCE
17840 This macro is a platform-specific subset of
17841 @code{AC_USE_SYSTEM_EXTENSIONS} (@pxref{AC_USE_SYSTEM_EXTENSIONS}).
17844 @defmac AC_MINUS_C_MINUS_O
17845 @acindex{MINUS_C_MINUS_O}
17846 Replaced by @code{AC_PROG_CC_C_O} (@pxref{AC_PROG_CC_C_O}).
17851 Replaced by @code{AC_FUNC_MMAP} (@pxref{AC_FUNC_MMAP}).
17856 Replaced by @code{AC_TYPE_MODE_T} (@pxref{AC_TYPE_MODE_T}).
17862 Defined the output variable @code{OBJEXT} based on the output of the
17863 compiler, after .c files have been excluded. Typically set to @samp{o}
17864 if Posix, @samp{obj} if a @acronym{DOS} variant.
17865 Now the compiler checking macros handle
17866 this automatically.
17869 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
17871 Make M4 print a message to the standard error output warning that
17872 @var{this-macro-name} is obsolete, and giving the file and line number
17873 where it was called. @var{this-macro-name} should be the name of the
17874 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
17875 it is printed at the end of the warning message; for example, it can be
17876 a suggestion for what to use instead of @var{this-macro-name}.
17881 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
17885 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
17886 services to the user (@pxref{AU_DEFUN}).
17891 Replaced by @code{AC_TYPE_OFF_T} (@pxref{AC_TYPE_OFF_T}).
17894 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
17896 The use of @code{AC_OUTPUT} with arguments is deprecated. This obsoleted
17897 interface is equivalent to:
17901 AC_CONFIG_FILES(@var{file}@dots{})
17902 AC_CONFIG_COMMANDS([default],
17903 @var{extra-cmds}, @var{init-cmds})
17909 See @ref{AC_CONFIG_FILES}, @ref{AC_CONFIG_COMMANDS}, and @ref{AC_OUTPUT}.
17912 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
17913 @acindex{OUTPUT_COMMANDS}
17914 Specify additional shell commands to run at the end of
17915 @file{config.status}, and shell commands to initialize any variables
17916 from @command{configure}. This macro may be called multiple times. It is
17917 obsolete, replaced by @code{AC_CONFIG_COMMANDS} (@pxref{AC_CONFIG_COMMANDS}).
17919 Here is an unrealistic example:
17923 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
17925 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
17929 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
17930 additional key, an important difference is that
17931 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
17932 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
17933 can safely be given macro calls as arguments:
17936 AC_CONFIG_COMMANDS(foo, [my_FOO()])
17940 Conversely, where one level of quoting was enough for literal strings
17941 with @code{AC_OUTPUT_COMMANDS}, you need two with
17942 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
17946 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
17947 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
17954 Replaced by @code{AC_TYPE_PID_T} (@pxref{AC_TYPE_PID_T}).
17959 Replaced by @code{AC_PREFIX_PROGRAM} (@pxref{AC_PREFIX_PROGRAM}).
17962 @defmac AC_PROGRAMS_CHECK
17963 @acindex{PROGRAMS_CHECK}
17964 Replaced by @code{AC_CHECK_PROGS} (@pxref{AC_CHECK_PROGS}).
17967 @defmac AC_PROGRAMS_PATH
17968 @acindex{PROGRAMS_PATH}
17969 Replaced by @code{AC_PATH_PROGS} (@pxref{AC_PATH_PROGS}).
17972 @defmac AC_PROGRAM_CHECK
17973 @acindex{PROGRAM_CHECK}
17974 Replaced by @code{AC_CHECK_PROG} (@pxref{AC_CHECK_PROG}).
17977 @defmac AC_PROGRAM_EGREP
17978 @acindex{PROGRAM_EGREP}
17979 Replaced by @code{AC_EGREP_CPP} (@pxref{AC_EGREP_CPP}).
17982 @defmac AC_PROGRAM_PATH
17983 @acindex{PROGRAM_PATH}
17984 Replaced by @code{AC_PATH_PROG} (@pxref{AC_PATH_PROG}).
17987 @defmac AC_REMOTE_TAPE
17988 @acindex{REMOTE_TAPE}
17989 Removed because of limited usefulness.
17992 @defmac AC_RESTARTABLE_SYSCALLS
17993 @acindex{RESTARTABLE_SYSCALLS}
17994 This macro was renamed @code{AC_SYS_RESTARTABLE_SYSCALLS}. However,
17995 these days portable programs should use @code{sigaction} with
17996 @code{SA_RESTART} if they want restartable system calls. They should
17997 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
17998 system call is restartable is a dynamic issue, not a configuration-time
18002 @defmac AC_RETSIGTYPE
18003 @acindex{RETSIGTYPE}
18004 Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}).
18009 Removed because of limited usefulness.
18012 @defmac AC_SCO_INTL
18015 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
18016 macro used to do this:
18019 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
18023 Now it just calls @code{AC_FUNC_STRFTIME} instead (@pxref{AC_FUNC_STRFTIME}).
18026 @defmac AC_SETVBUF_REVERSED
18027 @acindex{SETVBUF_REVERSED}
18030 AC_FUNC_SETVBUF_REVERSED
18033 @xref{AC_FUNC_SETVBUF_REVERSED}.
18036 @defmac AC_SET_MAKE
18038 Replaced by @code{AC_PROG_MAKE_SET} (@pxref{AC_PROG_MAKE_SET}).
18041 @defmac AC_SIZEOF_TYPE
18042 @acindex{SIZEOF_TYPE}
18043 Replaced by @code{AC_CHECK_SIZEOF} (@pxref{AC_CHECK_SIZEOF}).
18048 Replaced by @code{AC_TYPE_SIZE_T} (@pxref{AC_TYPE_SIZE_T}).
18051 @defmac AC_STAT_MACROS_BROKEN
18052 @acindex{STAT_MACROS_BROKEN}
18053 Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}).
18056 @defmac AC_STDC_HEADERS
18057 @acindex{STDC_HEADERS}
18058 Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}).
18063 Replaced by @code{AC_FUNC_STRCOLL} (@pxref{AC_FUNC_STRCOLL}).
18066 @defmac AC_STRUCT_ST_BLKSIZE
18067 @acindex{STRUCT_ST_BLKSIZE}
18068 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
18069 @cvindex HAVE_ST_BLKSIZE
18070 If @code{struct stat} contains an @code{st_blksize} member, define
18071 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
18072 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
18073 the future. This macro is obsoleted, and should be replaced by
18076 AC_CHECK_MEMBERS([struct stat.st_blksize])
18079 @xref{AC_CHECK_MEMBERS}.
18082 @defmac AC_STRUCT_ST_RDEV
18083 @acindex{STRUCT_ST_RDEV}
18084 @cvindex HAVE_ST_RDEV
18085 @cvindex HAVE_STRUCT_STAT_ST_RDEV
18086 If @code{struct stat} contains an @code{st_rdev} member, define
18087 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
18088 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
18089 in the future. Actually, even the new macro is obsolete and should be
18092 AC_CHECK_MEMBERS([struct stat.st_rdev])
18095 @xref{AC_CHECK_MEMBERS}.
18098 @defmac AC_ST_BLKSIZE
18099 @acindex{ST_BLKSIZE}
18100 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
18103 @defmac AC_ST_BLOCKS
18104 @acindex{ST_BLOCKS}
18105 Replaced by @code{AC_STRUCT_ST_BLOCKS} (@pxref{AC_STRUCT_ST_BLOCKS}).
18110 Replaced by @code{AC_CHECK_MEMBERS} (@pxref{AC_CHECK_MEMBERS}).
18113 @defmac AC_SYS_RESTARTABLE_SYSCALLS
18114 @acindex{SYS_RESTARTABLE_SYSCALLS}
18115 @cvindex HAVE_RESTARTABLE_SYSCALLS
18116 If the system automatically restarts a system call that is interrupted
18117 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
18118 not check whether system calls are restarted in general---it checks whether a
18119 signal handler installed with @code{signal} (but not @code{sigaction})
18120 causes system calls to be restarted. It does not check whether system calls
18121 can be restarted when interrupted by signals that have no handler.
18123 These days portable programs should use @code{sigaction} with
18124 @code{SA_RESTART} if they want restartable system calls. They should
18125 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
18126 system call is restartable is a dynamic issue, not a configuration-time
18130 @defmac AC_SYS_SIGLIST_DECLARED
18131 @acindex{SYS_SIGLIST_DECLARED}
18132 This macro was renamed @code{AC_DECL_SYS_SIGLIST}. However, even that
18133 name is obsolete, as the same functionality is now acheived via
18134 @code{AC_CHECK_DECLS} (@pxref{AC_CHECK_DECLS}).
18137 @defmac AC_TEST_CPP
18139 This macro was renamed @code{AC_TRY_CPP}, which in turn was replaced by
18140 @code{AC_PREPROC_IFELSE} (@pxref{AC_PREPROC_IFELSE}).
18143 @defmac AC_TEST_PROGRAM
18144 @acindex{TEST_PROGRAM}
18145 This macro was renamed @code{AC_TRY_RUN}, which in turn was replaced by
18146 @code{AC_RUN_IFELSE} (@pxref{AC_RUN_IFELSE}).
18149 @defmac AC_TIMEZONE
18151 Replaced by @code{AC_STRUCT_TIMEZONE} (@pxref{AC_STRUCT_TIMEZONE}).
18154 @defmac AC_TIME_WITH_SYS_TIME
18155 @acindex{TIME_WITH_SYS_TIME}
18156 Replaced by @code{AC_HEADER_TIME} (@pxref{AC_HEADER_TIME}).
18159 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @
18160 @ovar{action-if-true}, @ovar{action-if-false})
18161 @acindex{TRY_COMPILE}
18166 [AC_LANG_PROGRAM([[@var{includes}]],
18167 [[@var{function-body}]])],
18168 [@var{action-if-true}],
18169 [@var{action-if-false}])
18173 @xref{Running the Compiler}.
18175 This macro double quotes both @var{includes} and @var{function-body}.
18177 For C and C++, @var{includes} is any @code{#include} statements needed
18178 by the code in @var{function-body} (@var{includes} is ignored if
18179 the currently selected language is Fortran or Fortran 77). The compiler
18180 and compilation flags are determined by the current language
18181 (@pxref{Language Choice}).
18184 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
18190 [AC_LANG_SOURCE([[@var{input}]])],
18191 [@var{action-if-true}],
18192 [@var{action-if-false}])
18196 @xref{Running the Preprocessor}.
18198 This macro double quotes the @var{input}.
18201 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @
18202 @ovar{action-if-true}, @ovar{action-if-false})
18208 [AC_LANG_PROGRAM([[@var{includes}]],
18209 [[@var{function-body}]])],
18210 [@var{action-if-true}],
18211 [@var{action-if-false}])
18215 @xref{Running the Compiler}.
18217 This macro double quotes both @var{includes} and @var{function-body}.
18219 Depending on the current language (@pxref{Language Choice}), create a
18220 test program to see whether a function whose body consists of
18221 @var{function-body} can be compiled and linked. If the file compiles
18222 and links successfully, run shell commands @var{action-if-found},
18223 otherwise run @var{action-if-not-found}.
18225 This macro double quotes both @var{includes} and @var{function-body}.
18227 For C and C++, @var{includes} is any @code{#include} statements needed
18228 by the code in @var{function-body} (@var{includes} is ignored if
18229 the currently selected language is Fortran or Fortran 77). The compiler
18230 and compilation flags are determined by the current language
18231 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
18232 @code{LIBS} are used for linking.
18235 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @
18236 @ovar{action-if-not-found})
18237 @acindex{TRY_LINK_FUNC}
18238 This macro is equivalent to
18240 AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
18241 [@var{action-if-found}], [@var{action-if-not-found}])
18244 @xref{AC_LINK_IFELSE}.
18247 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @
18248 @ovar{action-if-false}, @ovar{action-if-cross-compiling})
18254 [AC_LANG_SOURCE([[@var{program}]])],
18255 [@var{action-if-true}],
18256 [@var{action-if-false}],
18257 [@var{action-if-cross-compiling}])
18266 Replaced by @code{AC_TYPE_UID_T} (@pxref{AC_TYPE_UID_T}).
18269 @defmac AC_UNISTD_H
18271 Same as @samp{AC_CHECK_HEADERS([unistd.h])} (@pxref{AC_CHECK_HEADERS}).
18277 Define @code{USG} if the @acronym{BSD} string functions are defined in
18278 @file{strings.h}. You should no longer depend upon @code{USG}, but on
18279 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
18282 @defmac AC_UTIME_NULL
18283 @acindex{UTIME_NULL}
18284 Replaced by @code{AC_FUNC_UTIME_NULL} (@pxref{AC_FUNC_UTIME_NULL}).
18287 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
18288 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
18289 If the cache file is inconsistent with the current host, target and
18290 build system types, it used to execute @var{cmd} or print a default
18291 error message. This is now handled by default.
18294 @defmac AC_VERBOSE (@var{result-description})
18296 Replaced by @code{AC_MSG_RESULT} (@pxref{AC_MSG_RESULT}).
18301 Replaced by @code{AC_FUNC_FORK} (@pxref{AC_FUNC_FORK}).
18306 Replaced by @code{AC_FUNC_VPRINTF} (@pxref{AC_FUNC_VPRINTF}).
18311 This macro was renamed @code{AC_FUNC_WAIT3}. However, these days
18312 portable programs should use @code{waitpid}, not @code{wait3}, as
18313 @code{wait3} has been removed from Posix.
18318 Replaced by @code{AC_MSG_WARN} (@pxref{AC_MSG_WARN}).
18321 @defmac AC_WITH (@var{package}, @var{action-if-given}, @
18322 @ovar{action-if-not-given})
18324 This is an obsolete version of @code{AC_ARG_WITH} that does not
18325 support providing a help string (@pxref{AC_ARG_WITH}).
18328 @defmac AC_WORDS_BIGENDIAN
18329 @acindex{WORDS_BIGENDIAN}
18330 Replaced by @code{AC_C_BIGENDIAN} (@pxref{AC_C_BIGENDIAN}).
18333 @defmac AC_XENIX_DIR
18334 @acindex{XENIX_DIR}
18336 This macro used to add @option{-lx} to output variable @code{LIBS} if on
18337 Xenix. Also, if @file{dirent.h} is being checked for, added
18338 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
18339 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
18340 running @sc{xenix} on which you should not depend:
18343 AC_MSG_CHECKING([for Xenix])
18344 AC_EGREP_CPP([yes],
18345 [#if defined M_XENIX && !defined M_UNIX
18348 [AC_MSG_RESULT([yes]); XENIX=yes],
18349 [AC_MSG_RESULT([no]); XENIX=])
18352 Don't use this macro, the dignified means to check the nature of the
18353 host is using @code{AC_CANONICAL_HOST} (@pxref{Canonicalizing}).
18356 @defmac AC_YYTEXT_POINTER
18357 @acindex{YYTEXT_POINTER}
18358 This macro was renamed @code{AC_DECL_YYTEXT}, which in turn was
18359 integrated into @code{AC_PROG_LEX} (@pxref{AC_PROG_LEX}).
18363 @section Upgrading From Version 1
18364 @cindex Upgrading autoconf
18365 @cindex Autoconf upgrading
18367 Autoconf version 2 is mostly backward compatible with version 1.
18368 However, it introduces better ways to do some things, and doesn't
18369 support some of the ugly things in version 1. So, depending on how
18370 sophisticated your @file{configure.ac} files are, you might have to do
18371 some manual work in order to upgrade to version 2. This chapter points
18372 out some problems to watch for when upgrading. Also, perhaps your
18373 @command{configure} scripts could benefit from some of the new features in
18374 version 2; the changes are summarized in the file @file{NEWS} in the
18375 Autoconf distribution.
18378 * Changed File Names:: Files you might rename
18379 * Changed Makefiles:: New things to put in @file{Makefile.in}
18380 * Changed Macros:: Macro calls you might replace
18381 * Changed Results:: Changes in how to check test results
18382 * Changed Macro Writing:: Better ways to write your own macros
18385 @node Changed File Names
18386 @subsection Changed File Names
18388 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
18389 in a particular package's source directory), you must rename it to
18390 @file{acsite.m4}. @xref{autoconf Invocation}.
18392 If you distribute @file{install.sh} with your package, rename it to
18393 @file{install-sh} so @code{make} builtin rules don't inadvertently
18394 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
18395 looks for the script under both names, but it is best to use the new name.
18397 If you were using @file{config.h.top}, @file{config.h.bot}, or
18398 @file{acconfig.h}, you still can, but you have less clutter if you
18399 use the @code{AH_} macros. @xref{Autoheader Macros}.
18401 @node Changed Makefiles
18402 @subsection Changed Makefiles
18404 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
18405 your @file{Makefile.in} files, so they can take advantage of the values
18406 of those variables in the environment when @command{configure} is run.
18407 Doing this isn't necessary, but it's a convenience for users.
18409 Also add @samp{@@configure_input@@} in a comment to each input file for
18410 @code{AC_OUTPUT}, so that the output files contain a comment saying
18411 they were produced by @command{configure}. Automatically selecting the
18412 right comment syntax for all the kinds of files that people call
18413 @code{AC_OUTPUT} on became too much work.
18415 Add @file{config.log} and @file{config.cache} to the list of files you
18416 remove in @code{distclean} targets.
18418 If you have the following in @file{Makefile.in}:
18421 prefix = /usr/local
18422 exec_prefix = $(prefix)
18426 you must change it to:
18429 prefix = @@prefix@@
18430 exec_prefix = @@exec_prefix@@
18434 The old behavior of replacing those variables without @samp{@@}
18435 characters around them has been removed.
18437 @node Changed Macros
18438 @subsection Changed Macros
18440 Many of the macros were renamed in Autoconf version 2. You can still
18441 use the old names, but the new ones are clearer, and it's easier to find
18442 the documentation for them. @xref{Obsolete Macros}, for a table showing the
18443 new names for the old macros. Use the @command{autoupdate} program to
18444 convert your @file{configure.ac} to using the new macro names.
18445 @xref{autoupdate Invocation}.
18447 Some macros have been superseded by similar ones that do the job better,
18448 but are not call-compatible. If you get warnings about calling obsolete
18449 macros while running @command{autoconf}, you may safely ignore them, but
18450 your @command{configure} script generally works better if you follow
18451 the advice that is printed about what to replace the obsolete macros with. In
18452 particular, the mechanism for reporting the results of tests has
18453 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
18454 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
18455 looks better if you switch to @code{AC_MSG_CHECKING} and
18456 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
18457 in conjunction with cache variables. @xref{Caching Results}.
18461 @node Changed Results
18462 @subsection Changed Results
18464 If you were checking the results of previous tests by examining the
18465 shell variable @code{DEFS}, you need to switch to checking the values of
18466 the cache variables for those tests. @code{DEFS} no longer exists while
18467 @command{configure} is running; it is only created when generating output
18468 files. This difference from version 1 is because properly quoting the
18469 contents of that variable turned out to be too cumbersome and
18470 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
18473 For example, here is a @file{configure.ac} fragment written for Autoconf
18477 AC_HAVE_FUNCS(syslog)
18479 *-DHAVE_SYSLOG*) ;;
18480 *) # syslog is not in the default libraries. See if it's in some other.
18482 for lib in bsd socket inet; do
18483 AC_CHECKING(for syslog in -l$lib)
18484 LIBS="-l$lib $saved_LIBS"
18485 AC_HAVE_FUNCS(syslog)
18487 *-DHAVE_SYSLOG*) break ;;
18495 Here is a way to write it for version 2:
18498 AC_CHECK_FUNCS([syslog])
18499 if test $ac_cv_func_syslog = no; then
18500 # syslog is not in the default libraries. See if it's in some other.
18501 for lib in bsd socket inet; do
18502 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
18503 LIBS="-l$lib $LIBS"; break])
18508 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
18509 backslashes before quotes, you need to remove them. It now works
18510 predictably, and does not treat quotes (except back quotes) specially.
18511 @xref{Setting Output Variables}.
18513 All of the Boolean shell variables set by Autoconf macros now use
18514 @samp{yes} for the true value. Most of them use @samp{no} for false,
18515 though for backward compatibility some use the empty string instead. If
18516 you were relying on a shell variable being set to something like 1 or
18517 @samp{t} for true, you need to change your tests.
18519 @node Changed Macro Writing
18520 @subsection Changed Macro Writing
18522 When defining your own macros, you should now use @code{AC_DEFUN}
18523 instead of @code{define}. @code{AC_DEFUN} automatically calls
18524 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
18525 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
18526 messages on the screen. There's no actual harm in continuing to use the
18527 older way, but it's less convenient and attractive. @xref{Macro
18530 You probably looked at the macros that came with Autoconf as a guide for
18531 how to do things. It would be a good idea to take a look at the new
18532 versions of them, as the style is somewhat improved and they take
18533 advantage of some new features.
18535 If you were doing tricky things with undocumented Autoconf internals
18536 (macros, variables, diversions), check whether you need to change
18537 anything to account for changes that have been made. Perhaps you can
18538 even use an officially supported technique in version 2 instead of
18539 kludging. Or perhaps not.
18541 To speed up your locally written feature tests, add caching to them.
18542 See whether any of your tests are of general enough usefulness to
18543 encapsulate them into macros that you can share.
18546 @node Autoconf 2.13
18547 @section Upgrading From Version 2.13
18548 @cindex Upgrading autoconf
18549 @cindex Autoconf upgrading
18551 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
18552 suits this section@enddots{}
18555 Autoconf version 2.50 is mostly backward compatible with version 2.13.
18556 However, it introduces better ways to do some things, and doesn't
18557 support some of the ugly things in version 2.13. So, depending on how
18558 sophisticated your @file{configure.ac} files are, you might have to do
18559 some manual work in order to upgrade to version 2.50. This chapter
18560 points out some problems to watch for when upgrading. Also, perhaps
18561 your @command{configure} scripts could benefit from some of the new
18562 features in version 2.50; the changes are summarized in the file
18563 @file{NEWS} in the Autoconf distribution.
18567 * Changed Quotation:: Broken code which used to work
18568 * New Macros:: Interaction with foreign macros
18569 * Hosts and Cross-Compilation:: Bugward compatibility kludges
18570 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
18571 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
18574 @node Changed Quotation
18575 @subsection Changed Quotation
18577 The most important changes are invisible to you: the implementation of
18578 most macros have completely changed. This allowed more factorization of
18579 the code, better error messages, a higher uniformity of the user's
18580 interface etc. Unfortunately, as a side effect, some construct which
18581 used to (miraculously) work might break starting with Autoconf 2.50.
18582 The most common culprit is bad quotation.
18584 For instance, in the following example, the message is not properly
18589 AC_CHECK_HEADERS(foo.h, ,
18590 AC_MSG_ERROR(cannot find foo.h, bailing out))
18595 Autoconf 2.13 simply ignores it:
18598 $ @kbd{autoconf-2.13; ./configure --silent}
18599 creating cache ./config.cache
18600 configure: error: cannot find foo.h
18605 while Autoconf 2.50 produces a broken @file{configure}:
18608 $ @kbd{autoconf-2.50; ./configure --silent}
18609 configure: error: cannot find foo.h
18610 ./configure: exit: bad non-numeric arg `bailing'
18611 ./configure: exit: bad non-numeric arg `bailing'
18615 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
18619 AC_INIT([Example], [1.0], [bug-example@@example.org])
18620 AC_CHECK_HEADERS([foo.h], [],
18621 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
18625 Many many (and many more) Autoconf macros were lacking proper quotation,
18626 including no less than@dots{} @code{AC_DEFUN} itself!
18629 $ @kbd{cat configure.in}
18630 AC_DEFUN([AC_PROG_INSTALL],
18631 [# My own much better version
18636 $ @kbd{autoconf-2.13}
18637 autoconf: Undefined macros:
18638 ***BUG in Autoconf--please report*** AC_FD_MSG
18639 ***BUG in Autoconf--please report*** AC_EPI
18640 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
18641 configure.in:5:AC_PROG_INSTALL
18642 $ @kbd{autoconf-2.50}
18648 @subsection New Macros
18650 @cindex undefined macro
18651 @cindex @code{_m4_divert_diversion}
18653 While Autoconf was relatively dormant in the late 1990s, Automake
18654 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
18655 in 2001, Autoconf provided
18656 versions of these macros, integrated in the @code{AC_} namespace,
18657 instead of @code{AM_}. But in order to ease the upgrading via
18658 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
18660 Unfortunately older versions of Automake (e.g., Automake 1.4)
18661 did not quote the names of these macros.
18662 Therefore, when @command{m4} finds something like
18663 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
18664 @code{AM_TYPE_PTRDIFF_T} is
18665 expanded, replaced with its Autoconf definition.
18667 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
18668 complains, in its own words:
18671 $ @kbd{cat configure.ac}
18672 AC_INIT([Example], [1.0], [bug-example@@example.org])
18674 $ @kbd{aclocal-1.4}
18676 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
18677 aclocal.m4:17: the top level
18678 autom4te: m4 failed with exit status: 1
18682 Modern versions of Automake no longer define most of these
18683 macros, and properly quote the names of the remaining macros.
18684 If you must use an old Automake, do not depend upon macros from Automake
18685 as it is simply not its job
18686 to provide macros (but the one it requires itself):
18689 $ @kbd{cat configure.ac}
18690 AC_INIT([Example], [1.0], [bug-example@@example.org])
18692 $ @kbd{rm aclocal.m4}
18694 autoupdate: `configure.ac' is updated
18695 $ @kbd{cat configure.ac}
18696 AC_INIT([Example], [1.0], [bug-example@@example.org])
18697 AC_CHECK_TYPES([ptrdiff_t])
18698 $ @kbd{aclocal-1.4}
18704 @node Hosts and Cross-Compilation
18705 @subsection Hosts and Cross-Compilation
18706 @cindex Cross compilation
18708 Based on the experience of compiler writers, and after long public
18709 debates, many aspects of the cross-compilation chain have changed:
18713 the relationship between the build, host, and target architecture types,
18716 the command line interface for specifying them to @command{configure},
18719 the variables defined in @command{configure},
18722 the enabling of cross-compilation mode.
18727 The relationship between build, host, and target have been cleaned up:
18728 the chain of default is now simply: target defaults to host, host to
18729 build, and build to the result of @command{config.guess}. Nevertheless,
18730 in order to ease the transition from 2.13 to 2.50, the following
18731 transition scheme is implemented. @emph{Do not rely on it}, as it will
18732 be completely disabled in a couple of releases (we cannot keep it, as it
18733 proves to cause more problems than it cures).
18735 They all default to the result of running @command{config.guess}, unless
18736 you specify either @option{--build} or @option{--host}. In this case,
18737 the default becomes the system type you specified. If you specify both,
18738 and they're different, @command{configure} enters cross compilation
18739 mode, so it doesn't run any tests that require execution.
18741 Hint: if you mean to override the result of @command{config.guess},
18742 prefer @option{--build} over @option{--host}. In the future,
18743 @option{--host} will not override the name of the build system type.
18744 Whenever you specify @option{--host}, be sure to specify @option{--build}
18749 For backward compatibility, @command{configure} accepts a system
18750 type as an option by itself. Such an option overrides the
18751 defaults for build, host, and target system types. The following
18752 configure statement configures a cross toolchain that runs on
18753 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
18754 which is also the build platform.
18757 ./configure --host=alpha-netbsd sparc-gnu
18762 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
18763 and @code{target} had a different semantics before and after the
18764 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
18765 @option{--build} is strictly copied into @code{build_alias}, and is left
18766 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
18767 set to the canonicalized build type. To ease the transition, before,
18768 its contents is the same as that of @code{build_alias}. Do @emph{not}
18769 rely on this broken feature.
18771 For consistency with the backward compatibility scheme exposed above,
18772 when @option{--host} is specified but @option{--build} isn't, the build
18773 system is assumed to be the same as @option{--host}, and
18774 @samp{build_alias} is set to that value. Eventually, this
18775 historically incorrect behavior will go away.
18779 The former scheme to enable cross-compilation proved to cause more harm
18780 than good, in particular, it used to be triggered too easily, leaving
18781 regular end users puzzled in front of cryptic error messages.
18782 @command{configure} could even enter cross-compilation mode only
18783 because the compiler was not functional. This is mainly because
18784 @command{configure} used to try to detect cross-compilation, instead of
18785 waiting for an explicit flag from the user.
18787 Now, @command{configure} enters cross-compilation mode if and only if
18788 @option{--host} is passed.
18790 That's the short documentation. To ease the transition between 2.13 and
18791 its successors, a more complicated scheme is implemented. @emph{Do not
18792 rely on the following}, as it will be removed in the near future.
18794 If you specify @option{--host}, but not @option{--build}, when
18795 @command{configure} performs the first compiler test it tries to run
18796 an executable produced by the compiler. If the execution fails, it
18797 enters cross-compilation mode. This is fragile. Moreover, by the time
18798 the compiler test is performed, it may be too late to modify the
18799 build-system type: other tests may have already been performed.
18800 Therefore, whenever you specify @option{--host}, be sure to specify
18801 @option{--build} too.
18804 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
18808 enters cross-compilation mode. The former interface, which
18809 consisted in setting the compiler to a cross-compiler without informing
18810 @command{configure} is obsolete. For instance, @command{configure}
18811 fails if it can't run the code generated by the specified compiler if you
18812 configure as follows:
18815 ./configure CC=m68k-coff-gcc
18819 @node AC_LIBOBJ vs LIBOBJS
18820 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
18822 Up to Autoconf 2.13, the replacement of functions was triggered via the
18823 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
18824 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
18825 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
18827 This change is mandated by the unification of the @acronym{GNU} Build System
18828 components. In particular, the various fragile techniques used to parse
18829 a @file{configure.ac} are all replaced with the use of traces. As a
18830 consequence, any action must be traceable, which obsoletes critical
18831 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
18832 and it can even be handled gracefully (read, ``without your having to
18833 change something'').
18835 There were two typical uses of @code{LIBOBJS}: asking for a replacement
18836 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
18840 As for function replacement, the fix is immediate: use
18841 @code{AC_LIBOBJ}. For instance:
18844 LIBOBJS="$LIBOBJS fnmatch.o"
18845 LIBOBJS="$LIBOBJS malloc.$ac_objext"
18849 should be replaced with:
18852 AC_LIBOBJ([fnmatch])
18853 AC_LIBOBJ([malloc])
18859 When used with Automake 1.10 or newer, a suitable value for
18860 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
18861 can be referenced from any @file{Makefile.am}. Even without Automake,
18862 arranging for @code{LIBOBJDIR} to be set correctly enables
18863 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
18864 The @code{LIBOBJDIR} feature is experimental.
18867 @node AC_FOO_IFELSE vs AC_TRY_FOO
18868 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
18870 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
18871 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
18872 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
18873 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
18874 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
18875 @code{AC_TRY_RUN}. The motivations where:
18878 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
18879 quoting their arguments;
18882 the combinatoric explosion is solved by decomposing on the one hand the
18883 generation of sources, and on the other hand executing the program;
18886 this scheme helps supporting more languages than plain C and C++.
18889 In addition to the change of syntax, the philosophy has changed too:
18890 while emphasis was put on speed at the expense of accuracy, today's
18891 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
18895 As a perfect example of what is @emph{not} to be done, here is how to
18896 find out whether a header file contains a particular declaration, such
18897 as a typedef, a structure, a structure member, or a function. Use
18898 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
18899 header file; on some systems the symbol might be defined in another
18900 header file that the file you are checking includes.
18902 As a (bad) example, here is how you should not check for C preprocessor
18903 symbols, either defined by header files or predefined by the C
18904 preprocessor: using @code{AC_EGREP_CPP}:
18912 ], is_aix=yes, is_aix=no)
18916 The above example, properly written would (i) use
18917 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
18921 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
18923 error: This isn't AIX!
18932 @c ============================= Generating Test Suites with Autotest
18934 @node Using Autotest
18935 @chapter Generating Test Suites with Autotest
18940 @strong{N.B.: This section describes an experimental feature which will
18941 be part of Autoconf in a forthcoming release. Although we believe
18942 Autotest is stabilizing, this documentation describes an interface which
18943 might change in the future: do not depend upon Autotest without
18944 subscribing to the Autoconf mailing lists.}
18947 It is paradoxical that portable projects depend on nonportable tools
18948 to run their test suite. Autoconf by itself is the paragon of this
18949 problem: although it aims at perfectly portability, up to 2.13 its
18950 test suite was using Deja@acronym{GNU}, a rich and complex testing
18951 framework, but which is far from being standard on Posix systems.
18952 Worse yet, it was likely to be missing on the most fragile platforms,
18953 the very platforms that are most likely to torture Autoconf and
18954 exhibit deficiencies.
18956 To circumvent this problem, many package maintainers have developed their
18957 own testing framework, based on simple shell scripts whose sole outputs
18958 are exit status values describing whether the test succeeded. Most of
18959 these tests share common patterns, and this can result in lots of
18960 duplicated code and tedious maintenance.
18962 Following exactly the same reasoning that yielded to the inception of
18963 Autoconf, Autotest provides a test suite generation framework, based on
18964 M4 macros building a portable shell script. The suite itself is
18965 equipped with automatic logging and tracing facilities which greatly
18966 diminish the interaction with bug reporters, and simple timing reports.
18968 Autoconf itself has been using Autotest for years, and we do attest that
18969 it has considerably improved the strength of the test suite and the
18970 quality of bug reports. Other projects are known to use some generation
18971 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
18972 them with different needs, and this usage has validated Autotest as a general
18975 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
18976 interactive tool testing, which is probably its main limitation.
18979 * Using an Autotest Test Suite:: Autotest and the user
18980 * Writing Testsuites:: Autotest macros
18981 * testsuite Invocation:: Running @command{testsuite} scripts
18982 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
18985 @node Using an Autotest Test Suite
18986 @section Using an Autotest Test Suite
18989 * testsuite Scripts:: The concepts of Autotest
18990 * Autotest Logs:: Their contents
18993 @node testsuite Scripts
18994 @subsection @command{testsuite} Scripts
18996 @cindex @command{testsuite}
18998 Generating testing or validation suites using Autotest is rather easy.
18999 The whole validation suite is held in a file to be processed through
19000 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
19001 produce a stand-alone Bourne shell script which then gets distributed.
19002 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
19003 the installer's end.
19006 Each test of the validation suite should be part of some test group. A
19007 @dfn{test group} is a sequence of interwoven tests that ought to be
19008 executed together, usually because one test in the group creates data
19009 files than a later test in the same group needs to read. Complex test
19010 groups make later debugging more tedious. It is much better to
19011 keep only a few tests per test group. Ideally there is only one test
19014 For all but the simplest packages, some file such as @file{testsuite.at}
19015 does not fully hold all test sources, as these are often easier to
19016 maintain in separate files. Each of these separate files holds a single
19017 test group, or a sequence of test groups all addressing some common
19018 functionality in the package. In such cases, @file{testsuite.at}
19019 merely initializes the validation suite, and sometimes does elementary
19020 health checking, before listing include statements for all other test
19021 files. The special file @file{package.m4}, containing the
19022 identification of the package, is automatically included if found.
19024 A convenient alternative consists in moving all the global issues
19025 (local Autotest macros, elementary health checking, and @code{AT_INIT}
19026 invocation) into the file @code{local.at}, and making
19027 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
19028 suites. In such case, generating the whole test suite or pieces of it
19029 is only a matter of choosing the @command{autom4te} command line
19032 The validation scripts that Autotest produces are by convention called
19033 @command{testsuite}. When run, @command{testsuite} executes each test
19034 group in turn, producing only one summary line per test to say if that
19035 particular test succeeded or failed. At end of all tests, summarizing
19036 counters get printed. One debugging directory is left for each test
19037 group which failed, if any: such directories are named
19038 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
19039 the test group, and they include:
19042 @item a debugging script named @file{run} which reruns the test in
19043 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
19044 of debugging scripts has the purpose of easing the chase for bugs.
19046 @item all the files created with @code{AT_DATA}
19048 @item a log of the run, named @file{testsuite.log}
19051 In the ideal situation, none of the tests fail, and consequently no
19052 debugging directory is left behind for validation.
19054 It often happens in practice that individual tests in the validation
19055 suite need to get information coming out of the configuration process.
19056 Some of this information, common for all validation suites, is provided
19057 through the file @file{atconfig}, automatically created by
19058 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
19059 testing environment specifically needs, you might prepare an optional
19060 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
19061 The configuration process produces @file{atconfig} and @file{atlocal}
19062 out of these two input files, and these two produced files are
19063 automatically read by the @file{testsuite} script.
19065 Here is a diagram showing the relationship between files.
19068 Files used in preparing a software package for distribution:
19073 subfile-1.at ->. [local.at] ---->+
19075 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
19081 Files used in configuring a software package:
19086 [atlocal.in] --> config.status* --<
19092 Files created during the test suite execution:
19095 atconfig -->. .--> testsuite.log
19099 [atlocal] ->' `--> [testsuite.dir]
19103 @node Autotest Logs
19104 @subsection Autotest Logs
19106 When run, the test suite creates a log file named after itself, e.g., a
19107 test suite named @command{testsuite} creates @file{testsuite.log}. It
19108 contains a lot of information, usually more than maintainers actually
19109 need, but therefore most of the time it contains all that is needed:
19112 @item command line arguments
19113 @c akim s/to consist in/to consist of/
19114 A bad but unfortunately widespread habit consists of
19115 setting environment variables before the command, such as in
19116 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
19117 know this change, hence (i) it cannot report it to you, and (ii)
19118 it cannot preserve the value of @code{CC} for subsequent runs.
19119 Autoconf faced exactly the same problem, and solved it by asking
19120 users to pass the variable definitions as command line arguments.
19121 Autotest requires this rule, too, but has no means to enforce it; the log
19122 then contains a trace of the variables that were changed by the user.
19124 @item @file{ChangeLog} excerpts
19125 The topmost lines of all the @file{ChangeLog} files found in the source
19126 hierarchy. This is especially useful when bugs are reported against
19127 development versions of the package, since the version string does not
19128 provide sufficient information to know the exact state of the sources
19129 the user compiled. Of course, this relies on the use of a
19132 @item build machine
19133 Running a test suite in a cross-compile environment is not an easy task,
19134 since it would mean having the test suite run on a machine @var{build},
19135 while running programs on a machine @var{host}. It is much simpler to
19136 run both the test suite and the programs on @var{host}, but then, from
19137 the point of view of the test suite, there remains a single environment,
19138 @var{host} = @var{build}. The log contains relevant information on the
19139 state of the build machine, including some important environment
19141 @c FIXME: How about having an M4sh macro to say `hey, log the value
19142 @c of `@dots{}'? This would help both Autoconf and Autotest.
19144 @item tested programs
19145 The absolute file name and answers to @option{--version} of the tested
19146 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
19148 @item configuration log
19149 The contents of @file{config.log}, as created by @command{configure},
19150 are appended. It contains the configuration flags and a detailed report
19151 on the configuration itself.
19155 @node Writing Testsuites
19156 @section Writing @file{testsuite.at}
19158 The @file{testsuite.at} is a Bourne shell script making use of special
19159 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
19160 its beginning followed by one call to @code{m4_include} per source file
19161 for tests. Each such included file, or the remainder of
19162 @file{testsuite.at} if include files are not used, contain a sequence of
19163 test groups. Each test group begins with a call to @code{AT_SETUP},
19164 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
19165 and then completes with a call to @code{AT_CLEANUP}.
19167 @defmac AT_INIT (@ovar{name})
19169 @c FIXME: Not clear, plus duplication of the information.
19170 Initialize Autotest. Giving a @var{name} to the test suite is
19171 encouraged if your package includes several test suites. In any case,
19172 the test suite always displays the package name and version. It also
19173 inherits the package bug report address.
19176 @defmac AT_COPYRIGHT (@var{copyright-notice})
19177 @atindex{COPYRIGHT}
19178 @cindex Copyright Notice
19179 State that, in addition to the Free Software Foundation's copyright on
19180 the Autotest macros, parts of your test suite are covered by
19181 @var{copyright-notice}.
19183 The @var{copyright-notice} shows up in both the head of
19184 @command{testsuite} and in @samp{testsuite --version}.
19187 @defmac AT_TESTED (@var{executables})
19189 Log the file name and answer to @option{--version} of each program in
19190 space-separated list @var{executables}. Several invocations register
19191 new executables, in other words, don't fear registering one program
19195 Autotest test suites rely on @env{PATH} to find the tested program.
19196 This avoids the need to generate absolute names of the various tools, and
19197 makes it possible to test installed programs. Therefore, knowing which
19198 programs are being exercised is crucial to understanding problems in
19199 the test suite itself, or its occasional misuses. It is a good idea to
19200 also subscribe foreign programs you depend upon, to avoid incompatible
19205 @defmac AT_SETUP (@var{test-group-name})
19207 This macro starts a group of related tests, all to be executed in the
19208 same subshell. It accepts a single argument, which holds a few words
19209 (no more than about 30 or 40 characters) quickly describing the purpose
19210 of the test group being started.
19213 @defmac AT_KEYWORDS (@var{keywords})
19215 Associate the space-separated list of @var{keywords} to the enclosing
19216 test group. This makes it possible to run ``slices'' of the test suite.
19217 For instance, if some of your test groups exercise some @samp{foo}
19218 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
19219 @samp{./testsuite -k foo} to run exclusively these test groups. The
19220 @var{title} of the test group is automatically recorded to
19221 @code{AT_KEYWORDS}.
19223 Several invocations within a test group accumulate new keywords. In
19224 other words, don't fear registering the same keyword several times in a
19228 @defmac AT_CAPTURE_FILE (@var{file})
19229 @atindex{CAPTURE_FILE}
19230 If the current test group fails, log the contents of @var{file}.
19231 Several identical calls within one test group have no additional effect.
19234 @defmac AT_XFAIL_IF (@var{shell-condition})
19236 Determine whether the test is expected to fail because it is a known
19237 bug (for unsupported features, you should skip the test).
19238 @var{shell-condition} is a shell expression such as a @code{test}
19239 command; you can instantiate this macro many times from within the
19240 same test group, and one of the conditions is enough to turn
19241 the test into an expected failure.
19246 End the current test group.
19251 @defmac AT_DATA (@var{file}, @var{contents})
19253 Initialize an input data @var{file} with given @var{contents}. Of
19254 course, the @var{contents} have to be properly quoted between square
19255 brackets to protect against included commas or spurious M4
19256 expansion. The contents ought to end with an end of line.
19259 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @
19260 @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
19262 Execute a test by performing given shell @var{commands}. These commands
19263 should normally exit with @var{status}, while producing expected
19264 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
19265 status 77, then the whole test group is skipped. Otherwise, if this test
19266 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
19267 commands @var{run-if-pass}.
19269 @c Previously, we had this:
19270 @c The @var{commands} @emph{must not} redirect the standard output, nor the
19272 @c to prevent trigerring the double redirect bug on Ultrix, see
19273 @c `File Descriptors'. This was too restricting, and Ultrix is pretty
19274 @c much dead, so we dropped the limitation; the obvious workaround on
19275 @c Ultrix is to use a working shell there.
19277 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
19278 the corresponding value is not checked.
19280 The special value @samp{expout} for @var{stdout} means the expected
19281 output of the @var{commands} is the content of the file @file{expout}.
19282 If @var{stdout} is @samp{stdout}, then the standard output of the
19283 @var{commands} is available for further tests in the file @file{stdout}.
19284 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
19288 @node testsuite Invocation
19289 @section Running @command{testsuite} Scripts
19290 @cindex @command{testsuite}
19292 Autotest test suites support the following arguments:
19297 Display the list of options and exit successfully.
19301 Display the version of the test suite and exit successfully.
19305 Remove all the files the test suite might have created and exit. Meant
19306 for @code{clean} Make targets.
19310 List all the tests (or only the selection), including their possible
19316 By default all tests are performed (or described with
19317 @option{--list}) in the default environment first silently, then
19318 verbosely, but the environment, set of tests, and verbosity level can be
19322 @item @var{variable}=@var{value}
19323 Set the environment @var{variable} to @var{value}. Use this rather
19324 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
19325 different environment.
19327 @cindex @code{AUTOTEST_PATH}
19328 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
19329 to @env{PATH}. Relative directory names (not starting with
19330 @samp{/}) are considered to be relative to the top level of the
19331 package being built. All directories are made absolute, first
19332 starting from the top level @emph{build} tree, then from the
19333 @emph{source} tree. For instance @samp{./testsuite
19334 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
19335 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
19336 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
19340 @itemx @var{number}-@var{number}
19341 @itemx @var{number}-
19342 @itemx -@var{number}
19343 Add the corresponding test groups, with obvious semantics, to the
19346 @item --keywords=@var{keywords}
19347 @itemx -k @var{keywords}
19348 Add to the selection the test groups with title or keywords (arguments
19349 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
19350 of the comma separated list @var{keywords}, case-insensitively. Use
19351 @samp{!} immediately before the keyword to invert the selection for this
19352 keyword. By default, the keywords match whole words; enclose them in
19353 @samp{.*} to also match parts of words.
19355 For example, running
19358 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
19362 selects all tests tagged @samp{autoupdate} @emph{and} with tags
19363 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
19367 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
19371 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
19372 containing @samp{FUNC}.
19376 If any test fails, immediately abort testing. It implies
19377 @option{--debug}: post test group clean up, and top-level logging
19378 are inhibited. This option is meant for the full test
19379 suite, it is not really useful for generated debugging scripts.
19383 Force more verbosity in the detailed output of what is being done. This
19384 is the default for debugging scripts.
19388 Do not remove the files after a test group was performed ---but they are
19389 still removed @emph{before}, therefore using this option is sane when
19390 running several test groups. Create debugging scripts. Do not
19391 overwrite the top-level
19392 log (in order to preserve supposedly existing full log file). This is
19393 the default for debugging scripts, but it can also be useful to debug
19394 the testsuite itself.
19398 Trigger shell tracing of the test groups.
19402 @node Making testsuite Scripts
19403 @section Making @command{testsuite} Scripts
19405 For putting Autotest into movement, you need some configuration and
19406 makefile machinery. We recommend, at least if your package uses deep or
19407 shallow hierarchies, that you use @file{tests/} as the name of the
19408 directory holding all your tests and their makefile. Here is a
19409 check list of things to do.
19414 @cindex @file{package.m4}
19415 Make sure to create the file @file{package.m4}, which defines the
19416 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
19417 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
19418 address to which bug reports should be sent. For sake of completeness,
19419 we suggest that you also define @code{AT_PACKAGE_NAME},
19420 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
19421 @xref{Initializing configure}, for a description of these variables. We
19422 suggest the following makefile excerpt:
19425 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
19427 echo '# Signature of the current package.'; \
19428 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
19429 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
19430 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
19431 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
19432 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
19433 @} >'$(srcdir)/package.m4'
19437 Be sure to distribute @file{package.m4} and to put it into the source
19438 hierarchy: the test suite ought to be shipped!
19441 Invoke @code{AC_CONFIG_TESTDIR}.
19443 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
19444 @acindex{CONFIG_TESTDIR}
19445 An Autotest test suite is to be configured in @var{directory}. This
19446 macro requires the instantiation of @file{@var{directory}/atconfig} from
19447 @file{@var{directory}/atconfig.in}, and sets the default
19448 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
19452 Still within @file{configure.ac}, as appropriate, ensure that some
19453 @code{AC_CONFIG_FILES} command includes substitution for
19454 @file{tests/atlocal}.
19457 The @file{tests/Makefile.in} should be modified so the validation in
19458 your package is triggered by @samp{make check}. An example is provided
19462 With Automake, here is a minimal example about how to link @samp{make
19463 check} with a validation suite.
19466 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
19467 TESTSUITE = $(srcdir)/testsuite
19469 check-local: atconfig atlocal $(TESTSUITE)
19470 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
19472 installcheck-local: atconfig atlocal $(TESTSUITE)
19473 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
19477 test ! -f '$(TESTSUITE)' || \
19478 $(SHELL) '$(TESTSUITE)' --clean
19480 AUTOTEST = $(AUTOM4TE) --language=autotest
19481 $(TESTSUITE): $(srcdir)/testsuite.at
19482 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
19486 You might want to list explicitly the dependencies, i.e., the list of
19487 the files @file{testsuite.at} includes.
19489 With strict Autoconf, you might need to add lines inspired from the
19495 atconfig: $(top_builddir)/config.status
19496 cd $(top_builddir) && \
19497 $(SHELL) ./config.status $(subdir)/$@@
19499 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
19500 cd $(top_builddir) && \
19501 $(SHELL) ./config.status $(subdir)/$@@
19505 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
19508 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
19509 within your makefile, you can fine-tune test suite execution with this
19510 variable, for example:
19513 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
19518 @c =============================== Frequent Autoconf Questions, with answers
19521 @chapter Frequent Autoconf Questions, with answers
19523 Several questions about Autoconf come up occasionally. Here some of them
19527 * Distributing:: Distributing @command{configure} scripts
19528 * Why GNU M4:: Why not use the standard M4?
19529 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
19530 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
19531 * Defining Directories:: Passing @code{datadir} to program
19532 * Autom4te Cache:: What is it? Can I remove it?
19533 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
19537 @section Distributing @command{configure} Scripts
19541 What are the restrictions on distributing @command{configure}
19542 scripts that Autoconf generates? How does that affect my
19543 programs that use them?
19546 There are no restrictions on how the configuration scripts that Autoconf
19547 produces may be distributed or used. In Autoconf version 1, they were
19548 covered by the @acronym{GNU} General Public License. We still encourage
19549 software authors to distribute their work under terms like those of the
19550 @acronym{GPL}, but doing so is not required to use Autoconf.
19552 Of the other files that might be used with @command{configure},
19553 @file{config.h.in} is under whatever copyright you use for your
19554 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
19555 exception to the @acronym{GPL} when they are used with an Autoconf-generated
19556 @command{configure} script, which permits you to distribute them under the
19557 same terms as the rest of your package. @file{install-sh} is from the X
19558 Consortium and is not copyrighted.
19561 @section Why Require @acronym{GNU} M4?
19564 Why does Autoconf require @acronym{GNU} M4?
19567 Many M4 implementations have hard-coded limitations on the size and
19568 number of macros that Autoconf exceeds. They also lack several
19569 builtin macros that it would be difficult to get along without in a
19570 sophisticated application like Autoconf, including:
19580 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
19582 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
19583 M4 is simple to configure and install, it seems reasonable to require
19584 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
19585 other free software already have most of the @acronym{GNU} utilities
19586 installed, since they prefer them.
19588 @node Bootstrapping
19589 @section How Can I Bootstrap?
19593 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
19594 @command{configure} script, how do I bootstrap? It seems like a chicken
19598 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
19599 @command{configure} script produced by Autoconf, Autoconf is not required
19600 in order to run the script and install @acronym{GNU} M4. Autoconf is only
19601 required if you want to change the M4 @command{configure} script, which few
19602 people have to do (mainly its maintainer).
19604 @node Why Not Imake
19605 @section Why Not Imake?
19609 Why not use Imake instead of @command{configure} scripts?
19612 Several people have written addressing this question, so I include
19613 adaptations of their explanations here.
19615 The following answer is based on one written by Richard Pixley:
19618 Autoconf generated scripts frequently work on machines that it has
19619 never been set up to handle before. That is, it does a good job of
19620 inferring a configuration for a new system. Imake cannot do this.
19622 Imake uses a common database of host specific data. For X11, this makes
19623 sense because the distribution is made as a collection of tools, by one
19624 central authority who has control over the database.
19626 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
19627 maintainer; these maintainers are scattered across the world. Using a
19628 common database would be a maintenance nightmare. Autoconf may appear
19629 to be this kind of database, but in fact it is not. Instead of listing
19630 host dependencies, it lists program requirements.
19632 If you view the @acronym{GNU} suite as a collection of native tools, then the
19633 problems are similar. But the @acronym{GNU} development tools can be
19634 configured as cross tools in almost any host+target permutation. All of
19635 these configurations can be installed concurrently. They can even be
19636 configured to share host independent files across hosts. Imake doesn't
19637 address these issues.
19639 Imake templates are a form of standardization. The @acronym{GNU} coding
19640 standards address the same issues without necessarily imposing the same
19645 Here is some further explanation, written by Per Bothner:
19648 One of the advantages of Imake is that it easy to generate large
19649 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
19650 However, @code{cpp} is not programmable: it has limited conditional
19651 facilities, and no looping. And @code{cpp} cannot inspect its
19654 All of these problems are solved by using @code{sh} instead of
19655 @code{cpp}. The shell is fully programmable, has macro substitution,
19656 can execute (or source) other shell scripts, and can inspect its
19661 Paul Eggert elaborates more:
19664 With Autoconf, installers need not assume that Imake itself is already
19665 installed and working well. This may not seem like much of an advantage
19666 to people who are accustomed to Imake. But on many hosts Imake is not
19667 installed or the default installation is not working well, and requiring
19668 Imake to install a package hinders the acceptance of that package on
19669 those hosts. For example, the Imake template and configuration files
19670 might not be installed properly on a host, or the Imake build procedure
19671 might wrongly assume that all source files are in one big directory
19672 tree, or the Imake configuration might assume one compiler whereas the
19673 package or the installer needs to use another, or there might be a
19674 version mismatch between the Imake expected by the package and the Imake
19675 supported by the host. These problems are much rarer with Autoconf,
19676 where each package comes with its own independent configuration
19679 Also, Imake often suffers from unexpected interactions between
19680 @command{make} and the installer's C preprocessor. The fundamental problem
19681 here is that the C preprocessor was designed to preprocess C programs,
19682 not makefiles. This is much less of a problem with Autoconf,
19683 which uses the general-purpose preprocessor M4, and where the
19684 package's author (rather than the installer) does the preprocessing in a
19689 Finally, Mark Eichin notes:
19692 Imake isn't all that extensible, either. In order to add new features to
19693 Imake, you need to provide your own project template, and duplicate most
19694 of the features of the existing one. This means that for a sophisticated
19695 project, using the vendor-provided Imake templates fails to provide any
19696 leverage---since they don't cover anything that your own project needs
19697 (unless it is an X11 program).
19699 On the other side, though:
19701 The one advantage that Imake has over @command{configure}:
19702 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
19703 than @file{Makefile.in} files. There is a fix to this, however---at least
19704 for the Kerberos V5 tree, we've modified things to call in common
19705 @file{post.in} and @file{pre.in} makefile fragments for the
19706 entire tree. This means that a lot of common things don't have to be
19707 duplicated, even though they normally are in @command{configure} setups.
19711 @node Defining Directories
19712 @section How Do I @code{#define} Installation Directories?
19715 My program needs library files, installed in @code{datadir} and
19719 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
19720 [Define to the read-only architecture-independent
19728 #define DATADIR "$@{prefix@}/share"
19732 As already explained, this behavior is on purpose, mandated by the
19733 @acronym{GNU} Coding Standards, see @ref{Installation Directory
19734 Variables}. There are several means to achieve a similar goal:
19738 Do not use @code{AC_DEFINE} but use your makefile to pass the
19739 actual value of @code{datadir} via compilation flags.
19740 @xref{Installation Directory Variables}, for the details.
19743 This solution can be simplified when compiling a program: you may either
19744 extend the @code{CPPFLAGS}:
19747 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
19751 If you are using Automake, you should use @code{AM_CPPFLAGS} instead:
19754 AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
19758 Alternatively, create a dedicated header file:
19761 DISTCLEANFILES = myprog-paths.h
19762 myprog-paths.h: Makefile
19763 echo '#define DATADIR "$(datadir)"' >$@@
19767 Use @code{AC_DEFINE} but have @command{configure} compute the literal
19768 value of @code{datadir} and others. Many people have wrapped macros to
19769 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
19770 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
19773 This solution does not conform to the @acronym{GNU} Coding Standards.
19776 Note that all the previous solutions hard wire the absolute name of
19777 these directories in the executables, which is not a good property. You
19778 may try to compute the names relative to @code{prefix}, and try to
19779 find @code{prefix} at runtime, this way your package is relocatable.
19783 @node Autom4te Cache
19784 @section What is @file{autom4te.cache}?
19787 What is this directory @file{autom4te.cache}? Can I safely remove it?
19790 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
19791 role and is read by many tools: @command{autoconf} to create
19792 @file{configure}, @command{autoheader} to create @file{config.h.in},
19793 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
19794 check the completeness of @file{configure.ac}, @command{autoreconf} to
19795 check the @acronym{GNU} Build System components that are used. To
19796 ``read @file{configure.ac}'' actually means to compile it with M4,
19797 which can be a long process for complex @file{configure.ac}.
19799 This is why all these tools, instead of running directly M4, invoke
19800 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
19801 a specific demand, stores additional information in
19802 @file{autom4te.cache} for future runs. For instance, if you run
19803 @command{autoconf}, behind the scenes, @command{autom4te} also
19804 stores information for the other tools, so that when you invoke
19805 @command{autoheader} or @command{automake} etc., reprocessing
19806 @file{configure.ac} is not needed. The speed up is frequently of 30%,
19807 and is increasing with the size of @file{configure.ac}.
19809 But it is and remains being simply a cache: you can safely remove it.
19814 Can I permanently get rid of it?
19817 The creation of this cache can be disabled from
19818 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
19819 details. You should be aware that disabling the cache slows down the
19820 Autoconf test suite by 40%. The more @acronym{GNU} Build System
19821 components are used, the more the cache is useful; for instance
19822 running @samp{autoreconf -f} on the Core Utilities is twice slower without
19823 the cache @emph{although @option{--force} implies that the cache is
19824 not fully exploited}, and eight times slower than without
19828 @node Present But Cannot Be Compiled
19829 @section Header Present But Cannot Be Compiled
19831 The most important guideline to bear in mind when checking for
19832 features is to mimic as much as possible the intended use.
19833 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
19834 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
19835 the preprocessor, instead of the compiler, to check for headers. As a
19836 result, incompatibilities between headers went unnoticed during
19837 configuration, and maintainers finally had to deal with this issue
19840 As of Autoconf 2.56 both checks are performed, and @code{configure}
19841 complains loudly if the compiler and the preprocessor do not agree.
19842 For the time being the result used is that of the preprocessor, to give
19843 maintainers time to adjust their @file{configure.ac}, but in the
19844 future, only the compiler will be considered.
19846 Consider the following example:
19849 $ @kbd{cat number.h}
19850 typedef int number;
19852 const number pi = 3;
19853 $ @kbd{cat configure.ac}
19854 AC_INIT([Example], [1.0], [bug-example@@example.org])
19855 AC_CHECK_HEADERS([pi.h])
19856 $ @kbd{autoconf -Wall}
19857 $ @kbd{./configure}
19858 checking for gcc... gcc
19859 checking for C compiler default output file name... a.out
19860 checking whether the C compiler works... yes
19861 checking whether we are cross compiling... no
19862 checking for suffix of executables...
19863 checking for suffix of object files... o
19864 checking whether we are using the GNU C compiler... yes
19865 checking whether gcc accepts -g... yes
19866 checking for gcc option to accept ISO C89... none needed
19867 checking how to run the C preprocessor... gcc -E
19868 checking for grep that handles long lines and -e... grep
19869 checking for egrep... grep -E
19870 checking for ANSI C header files... yes
19871 checking for sys/types.h... yes
19872 checking for sys/stat.h... yes
19873 checking for stdlib.h... yes
19874 checking for string.h... yes
19875 checking for memory.h... yes
19876 checking for strings.h... yes
19877 checking for inttypes.h... yes
19878 checking for stdint.h... yes
19879 checking for unistd.h... yes
19880 checking pi.h usability... no
19881 checking pi.h presence... yes
19882 configure: WARNING: pi.h: present but cannot be compiled
19883 configure: WARNING: pi.h: check for missing prerequisite headers?
19884 configure: WARNING: pi.h: see the Autoconf documentation
19885 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
19886 configure: WARNING: pi.h: proceeding with the preprocessor's result
19887 configure: WARNING: pi.h: in the future, the compiler will take precedence
19888 configure: WARNING: ## -------------------------------------- ##
19889 configure: WARNING: ## Report this to bug-example@@example.org ##
19890 configure: WARNING: ## -------------------------------------- ##
19891 checking for pi.h... yes
19895 The proper way the handle this case is using the fourth argument
19896 (@pxref{Generic Headers}):
19899 $ @kbd{cat configure.ac}
19900 AC_INIT([Example], [1.0], [bug-example@@example.org])
19901 AC_CHECK_HEADERS([number.h pi.h], [], [],
19902 [[#ifdef HAVE_NUMBER_H
19903 # include <number.h>
19906 $ @kbd{autoconf -Wall}
19907 $ @kbd{./configure}
19908 checking for gcc... gcc
19909 checking for C compiler default output... a.out
19910 checking whether the C compiler works... yes
19911 checking whether we are cross compiling... no
19912 checking for suffix of executables...
19913 checking for suffix of object files... o
19914 checking whether we are using the GNU C compiler... yes
19915 checking whether gcc accepts -g... yes
19916 checking for gcc option to accept ANSI C... none needed
19917 checking for number.h... yes
19918 checking for pi.h... yes
19921 See @ref{Particular Headers}, for a list of headers with their
19924 @c ===================================================== History of Autoconf.
19927 @chapter History of Autoconf
19928 @cindex History of autoconf
19930 You may be wondering, Why was Autoconf originally written? How did it
19931 get into its present form? (Why does it look like gorilla spit?) If
19932 you're not wondering, then this chapter contains no information useful
19933 to you, and you might as well skip it. If you @emph{are} wondering,
19934 then let there be light@enddots{}
19937 * Genesis:: Prehistory and naming of @command{configure}
19938 * Exodus:: The plagues of M4 and Perl
19939 * Leviticus:: The priestly code of portability arrives
19940 * Numbers:: Growth and contributors
19941 * Deuteronomy:: Approaching the promises of easy configuration
19947 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
19948 Free Software Foundation. As they were ported to more platforms and
19949 more programs were added, the number of @option{-D} options that users
19950 had to select in the makefile (around 20) became burdensome.
19951 Especially for me---I had to test each new release on a bunch of
19952 different systems. So I wrote a little shell script to guess some of
19953 the correct settings for the fileutils package, and released it as part
19954 of fileutils 2.0. That @command{configure} script worked well enough that
19955 the next month I adapted it (by hand) to create similar @command{configure}
19956 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
19957 also adapted one of my scripts for his @acronym{CVS} revision control system.
19959 Later that summer, I learned that Richard Stallman and Richard Pixley
19960 were developing similar scripts to use in the @acronym{GNU} compiler tools;
19961 so I adapted my @command{configure} scripts to support their evolving
19962 interface: using the file name @file{Makefile.in} as the templates;
19963 adding @samp{+srcdir}, the first option (of many); and creating
19964 @file{config.status} files.
19969 As I got feedback from users, I incorporated many improvements, using
19970 Emacs to search and replace, cut and paste, similar changes in each of
19971 the scripts. As I adapted more @acronym{GNU} utilities packages to use
19972 @command{configure} scripts, updating them all by hand became impractical.
19973 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
19974 mail saying that the @command{configure} scripts were great, and asking if
19975 I had a tool for generating them that I could send him. No, I thought,
19976 but I should! So I started to work out how to generate them. And the
19977 journey from the slavery of hand-written @command{configure} scripts to the
19978 abundance and ease of Autoconf began.
19980 Cygnus @command{configure}, which was being developed at around that time,
19981 is table driven; it is meant to deal mainly with a discrete number of
19982 system types with a small number of mainly unguessable features (such as
19983 details of the object file format). The automatic configuration system
19984 that Brian Fox had developed for Bash takes a similar approach. For
19985 general use, it seems to me a hopeless cause to try to maintain an
19986 up-to-date database of which features each variant of each operating
19987 system has. It's easier and more reliable to check for most features on
19988 the fly---especially on hybrid systems that people have hacked on
19989 locally or that have patches from vendors installed.
19991 I considered using an architecture similar to that of Cygnus
19992 @command{configure}, where there is a single @command{configure} script that
19993 reads pieces of @file{configure.in} when run. But I didn't want to have
19994 to distribute all of the feature tests with every package, so I settled
19995 on having a different @command{configure} made from each
19996 @file{configure.in} by a preprocessor. That approach also offered more
19997 control and flexibility.
19999 I looked briefly into using the Metaconfig package, by Larry Wall,
20000 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
20001 reasons. The @command{Configure} scripts it produces are interactive,
20002 which I find quite inconvenient; I didn't like the ways it checked for
20003 some features (such as library functions); I didn't know that it was
20004 still being maintained, and the @command{Configure} scripts I had
20005 seen didn't work on many modern systems (such as System V R4 and NeXT);
20006 it wasn't flexible in what it could do in response to a feature's
20007 presence or absence; I found it confusing to learn; and it was too big
20008 and complex for my needs (I didn't realize then how much Autoconf would
20009 eventually have to grow).
20011 I considered using Perl to generate my style of @command{configure}
20012 scripts, but decided that M4 was better suited to the job of simple
20013 textual substitutions: it gets in the way less, because output is
20014 implicit. Plus, everyone already has it. (Initially I didn't rely on
20015 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
20016 University of Maryland had recently been putting M4 front ends on
20017 several programs, including @code{tvtwm}, and I was interested in trying
20018 out a new language.
20023 Since my @command{configure} scripts determine the system's capabilities
20024 automatically, with no interactive user intervention, I decided to call
20025 the program that generates them Autoconfig. But with a version number
20026 tacked on, that name would be too long for old Unix file systems,
20027 so I shortened it to Autoconf.
20029 In the fall of 1991 I called together a group of fellow questers after
20030 the Holy Grail of portability (er, that is, alpha testers) to give me
20031 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
20032 and continued to add features and improve the techniques used in the
20033 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
20034 with the idea of making an Autoconf shell script to run M4
20035 and check for unresolved macro calls; Richard Pixley, who suggested
20036 running the compiler instead of searching the file system to find
20037 include files and symbols, for more accurate results; Karl Berry, who
20038 got Autoconf to configure @TeX{} and added the macro index to the
20039 documentation; and Ian Lance Taylor, who added support for creating a C
20040 header file as an alternative to putting @option{-D} options in a
20041 makefile, so he could use Autoconf for his @acronym{UUCP} package.
20042 The alpha testers cheerfully adjusted their files again and again as the
20043 names and calling conventions of the Autoconf macros changed from
20044 release to release. They all contributed many specific checks, great
20045 ideas, and bug fixes.
20050 In July 1992, after months of alpha testing, I released Autoconf 1.0,
20051 and converted many @acronym{GNU} packages to use it. I was surprised by how
20052 positive the reaction to it was. More people started using it than I
20053 could keep track of, including people working on software that wasn't
20054 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
20055 Autoconf continued to improve rapidly, as many people using the
20056 @command{configure} scripts reported problems they encountered.
20058 Autoconf turned out to be a good torture test for M4 implementations.
20059 Unix M4 started to dump core because of the length of the
20060 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
20061 M4 as well. Eventually, we realized that we needed to use some
20062 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
20063 particular, has an impoverished set of builtin macros; the System V
20064 version is better, but still doesn't provide everything we need.
20066 More development occurred as people put Autoconf under more stresses
20067 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
20068 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
20069 invalid arguments. Jim Blandy bravely coerced it into configuring
20070 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
20071 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
20072 @command{autoheader} script to automate the creation of C header file
20073 templates, and added a @option{--verbose} option to @command{configure}.
20074 Noah Friedman added the @option{--autoconf-dir} option and
20075 @code{AC_MACRODIR} environment variable. (He also coined the term
20076 @dfn{autoconfiscate} to mean ``adapt a software package to use
20077 Autoconf''.) Roland and Noah improved the quoting protection in
20078 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
20079 dealing with portability problems from February through June, 1993.
20082 @section Deuteronomy
20084 A long wish list for major features had accumulated, and the effect of
20085 several years of patching by various people had left some residual
20086 cruft. In April 1994, while working for Cygnus Support, I began a major
20087 revision of Autoconf. I added most of the features of the Cygnus
20088 @command{configure} that Autoconf had lacked, largely by adapting the
20089 relevant parts of Cygnus @command{configure} with the help of david zuhn
20090 and Ken Raeburn. These features include support for using
20091 @file{config.sub}, @file{config.guess}, @option{--host}, and
20092 @option{--target}; making links to files; and running @command{configure}
20093 scripts in subdirectories. Adding these features enabled Ken to convert
20094 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
20097 I added more features in response to other peoples' requests. Many
20098 people had asked for @command{configure} scripts to share the results of
20099 the checks between runs, because (particularly when configuring a large
20100 source tree, like Cygnus does) they were frustratingly slow. Mike
20101 Haertel suggested adding site-specific initialization scripts. People
20102 distributing software that had to unpack on MS-DOS asked for a way to
20103 override the @file{.in} extension on the file names, which produced file
20104 names like @file{config.h.in} containing two dots. Jim Avera did an
20105 extensive examination of the problems with quoting in @code{AC_DEFINE}
20106 and @code{AC_SUBST}; his insights led to significant improvements.
20107 Richard Stallman asked that compiler output be sent to @file{config.log}
20108 instead of @file{/dev/null}, to help people debug the Emacs
20109 @command{configure} script.
20111 I made some other changes because of my dissatisfaction with the quality
20112 of the program. I made the messages showing results of the checks less
20113 ambiguous, always printing a result. I regularized the names of the
20114 macros and cleaned up coding style inconsistencies. I added some
20115 auxiliary utilities that I had developed to help convert source code
20116 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
20117 the macros not interrupt each others' messages. (That feature revealed
20118 some performance bottlenecks in @acronym{GNU} M4, which he hastily
20119 corrected!) I reorganized the documentation around problems people want
20120 to solve. And I began a test suite, because experience had shown that
20121 Autoconf has a pronounced tendency to regress when we change it.
20123 Again, several alpha testers gave invaluable feedback, especially
20124 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
20127 Finally, version 2.0 was ready. And there was much rejoicing. (And I
20128 have free time again. I think. Yeah, right.)
20131 @c ========================================================== Appendices
20133 @node Copying This Manual
20134 @appendix Copying This Manual
20138 * GNU Free Documentation License:: License for copying this manual
20142 @node GNU Free Documentation License
20143 @appendixsec GNU Free Documentation License
20145 @cindex FDL, GNU Free Documentation License
20153 * Environment Variable Index:: Index of environment variables used
20154 * Output Variable Index:: Index of variables set in output files
20155 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
20156 * Autoconf Macro Index:: Index of Autoconf macros
20157 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
20158 * Autotest Macro Index:: Index of Autotest macros
20159 * Program & Function Index:: Index of those with portability problems
20160 * Concept Index:: General index
20163 @node Environment Variable Index
20164 @appendixsec Environment Variable Index
20166 This is an alphabetical list of the environment variables that Autoconf
20171 @node Output Variable Index
20172 @appendixsec Output Variable Index
20174 This is an alphabetical list of the variables that Autoconf can
20175 substitute into files that it creates, typically one or more
20176 makefiles. @xref{Setting Output Variables}, for more information
20177 on how this is done.
20181 @node Preprocessor Symbol Index
20182 @appendixsec Preprocessor Symbol Index
20184 This is an alphabetical list of the C preprocessor symbols that the
20185 Autoconf macros define. To work with Autoconf, C source code needs to
20186 use these names in @code{#if} or @code{#ifdef} directives.
20190 @node Autoconf Macro Index
20191 @appendixsec Autoconf Macro Index
20193 This is an alphabetical list of the Autoconf macros.
20194 @ifset shortindexflag
20195 To make the list easier to use, the macros are listed without their
20196 preceding @samp{AC_}.
20201 @node M4 Macro Index
20202 @appendixsec M4 Macro Index
20204 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
20205 @ifset shortindexflag
20206 To make the list easier to use, the macros are listed without their
20207 preceding @samp{m4_} or @samp{AS_}.
20212 @node Autotest Macro Index
20213 @appendixsec Autotest Macro Index
20215 This is an alphabetical list of the Autotest macros.
20216 @ifset shortindexflag
20217 To make the list easier to use, the macros are listed without their
20218 preceding @samp{AT_}.
20223 @node Program & Function Index
20224 @appendixsec Program and Function Index
20226 This is an alphabetical list of the programs and functions whose
20227 portability is discussed in this document.
20231 @node Concept Index
20232 @appendixsec Concept Index
20234 This is an alphabetical list of the files, tools, and concepts
20235 introduced in this document.
20241 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
20242 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
20243 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
20244 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
20245 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
20246 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
20247 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
20248 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
20249 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
20250 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
20251 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
20252 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
20253 @c LocalWords: distclean uninstall noindent versioning Tromey dir
20254 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
20255 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
20256 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
20257 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
20258 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
20259 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
20260 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
20261 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
20262 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
20263 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
20264 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
20265 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
20266 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
20267 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
20268 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
20269 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
20270 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
20271 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
20272 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
20273 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
20274 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
20275 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
20276 @c LocalWords: SETGID getloadavg nlist GETMNTENT irix
20277 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
20278 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
20279 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
20280 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
20281 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
20282 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
20283 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
20284 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
20285 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
20286 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
20287 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
20288 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
20289 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
20290 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
20291 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
20292 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
20293 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
20294 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
20295 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
20296 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
20297 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
20298 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
20299 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
20300 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
20301 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
20302 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
20303 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
20304 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
20305 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
20306 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
20307 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
20308 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
20309 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
20310 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
20311 @c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
20312 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
20313 @c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
20314 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
20315 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
20316 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
20317 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
20318 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
20319 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
20320 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
20321 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
20322 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
20323 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
20324 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
20325 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
20326 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
20327 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
20328 @c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
20329 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
20330 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
20331 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
20332 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
20334 @c Local Variables:
20336 @c ispell-local-dictionary: "american"
20337 @c indent-tabs-mode: nil
20338 @c whitespace-check-buffer-indent: nil