1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
9 @setcontentsaftertitlepage
13 @c @ovar(ARG, DEFAULT)
14 @c -------------------
15 @c The ARG is an optional argument. To be used for macro arguments in
16 @c their documentation (@defmac).
18 @r{[}@var{\varname\}@r{]}
21 @c @dvar(ARG, DEFAULT)
22 @c -------------------
23 @c The ARG is an optional argument, defaulting to DEFAULT. To be used
24 @c for macro arguments in their documentation (@defmac).
25 @macro dvar{varname, default}
26 @r{[}@var{\varname\} = @samp{\default\}@r{]}
29 @c Handling the indexes with Texinfo yields several different problems.
31 @c Because we want to drop out the AC_ part of the macro names in the
32 @c printed manual, but not in the other outputs, we need a layer above
33 @c the usual @acindex{} etc. That's why we first define indexes such as
34 @c acx meant to become the macro @acindex. First of all, using ``ac_''
35 @c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
36 @c So use something more regular ``acx''. Then you finish with a printed
37 @c index saying ``index is not existent''. Of course: you ought to use
38 @c two letters :( So you use capitals.
40 @c Second, when defining a macro in the TeX world, following spaces are
41 @c eaten. But then, since we embed @acxindex commands that use the end
42 @c of line as an end marker, the whole things wrecks itself. So make
43 @c sure you do *force* an additional end of line, add a ``@c''.
45 @c Finally, you might want to get rid of TeX expansion, using --expand
46 @c with texi2dvi. But then you wake up an old problem: we use macros
47 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
49 @c Define an environment variable index.
51 @c Define an output variable index.
53 @c Define a CPP variable index.
55 @c Define an Autoconf macro index that @defmac doesn't write to.
57 @c Define an Autotest macro index that @defmac doesn't write to.
59 @c Define an M4sugar macro index that @defmac doesn't write to.
61 @c Define an index for *foreign* programs: `mv' etc. Used for the
62 @c portability sections and so on.
67 @c Shall we factor AC_ out of the Autoconf macro index etc.?
74 @c Registering an AC_\MACRO\.
81 @ifclear shortindexflag
89 @c Registering an AH_\MACRO\.
97 @c Registering an AS_\MACRO\.
104 @ifclear shortindexflag
105 @macro asindex{macro}
112 @c Registering an AT_\MACRO\.
113 @ifset shortindexflag
114 @macro atindex{macro}
119 @ifclear shortindexflag
120 @macro atindex{macro}
127 @c Registering an AU_\MACRO\.
128 @macro auindex{macro}
135 @c Indexing a header.
136 @macro hdrindex{macro}
137 @prindex @file{\macro\}
143 @c Registering an m4_\MACRO\.
144 @ifset shortindexflag
145 @macro msindex{macro}
150 @ifclear shortindexflag
151 @macro msindex{macro}
157 @c Define an index for functions: `alloca' etc. Used for the
158 @c portability sections and so on. We can't use `fn' (aka `fnindex),
159 @c since `@defmac' goes into it => we'd get all the macros too.
161 @c FIXME: Aaarg! It seems there are too many indices for TeX :(
163 @c ! No room for a new @write .
164 @c l.112 @defcodeindex fu
166 @c so don't define yet another one :( Just put some tags before each
167 @c @prindex which is actually a @funindex.
172 @c @c Put the programs and functions into their own index.
173 @c @syncodeindex fu pr
175 @comment %**end of header
176 @comment ========================================================
180 This manual is for @acronym{GNU} Autoconf
181 (version @value{VERSION}, @value{UPDATED}),
182 a package for creating scripts to configure source code packages using
183 templates and an M4 macro package.
185 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
186 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
189 Permission is granted to copy, distribute and/or modify this document
190 under the terms of the @acronym{GNU} Free Documentation License,
191 Version 1.2 or any later version published by the Free Software
192 Foundation; with no Invariant Sections, with the Front-Cover texts
193 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
194 (a) below. A copy of the license is included in the section entitled
195 ``@acronym{GNU} Free Documentation License.''
197 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
198 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
199 published by the Free Software Foundation raise funds for
200 @acronym{GNU} development.''
206 @dircategory Software development
208 * Autoconf: (autoconf). Create source code configuration scripts.
211 @dircategory Individual utilities
213 * autoscan: (autoconf)autoscan Invocation.
214 Semi-automatic @file{configure.ac} writing
215 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
216 * autoconf-invocation: (autoconf)autoconf Invocation.
217 How to create configuration scripts
218 * autoreconf: (autoconf)autoreconf Invocation.
219 Remaking multiple @command{configure} scripts
220 * autoheader: (autoconf)autoheader Invocation.
221 How to create configuration templates
222 * autom4te: (autoconf)autom4te Invocation.
223 The Autoconf executables backbone
224 * configure: (autoconf)configure Invocation. Configuring a package.
225 * autoupdate: (autoconf)autoupdate Invocation.
226 Automatic update of @file{configure.ac}
227 * config.status: (autoconf)config.status Invocation. Recreating configurations.
228 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
233 @subtitle Creating Automatic Configuration Scripts
234 @subtitle for version @value{VERSION}, @value{UPDATED}
235 @author David MacKenzie
237 @author Akim Demaille
239 @vskip 0pt plus 1filll
252 @c The master menu, created with texinfo-master-menu, goes here.
255 * Introduction:: Autoconf's purpose, strengths, and weaknesses
256 * The GNU Build System:: A set of tools for portable software packages
257 * Making configure Scripts:: How to organize and produce Autoconf scripts
258 * Setup:: Initialization and output
259 * Existing Tests:: Macros that check for particular features
260 * Writing Tests:: How to write new feature checks
261 * Results:: What to do with results from feature checks
262 * Programming in M4:: Layers on top of which Autoconf is written
263 * Writing Autoconf Macros:: Adding new macros to Autoconf
264 * Portable Shell:: Shell script portability pitfalls
265 * Portable Make:: Makefile portability pitfalls
266 * Portable C and C++:: C and C++ portability pitfalls
267 * Manual Configuration:: Selecting features that can't be guessed
268 * Site Configuration:: Local defaults for @command{configure}
269 * Running configure Scripts:: How to use the Autoconf output
270 * config.status Invocation:: Recreating a configuration
271 * Obsolete Constructs:: Kept for backward compatibility
272 * Using Autotest:: Creating portable test suites
273 * FAQ:: Frequent Autoconf Questions, with answers
274 * History:: History of Autoconf
275 * Copying This Manual:: How to make copies of this manual
276 * Indices:: Indices of symbols, concepts, etc.
279 --- The Detailed Node Listing ---
281 The @acronym{GNU} Build System
283 * Automake:: Escaping makefile hell
284 * Gnulib:: The @acronym{GNU} portability library
285 * Libtool:: Building libraries portably
286 * Pointers:: More info on the @acronym{GNU} build system
288 Making @command{configure} Scripts
290 * Writing Autoconf Input:: What to put in an Autoconf input file
291 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
292 * ifnames Invocation:: Listing the conditionals in source code
293 * autoconf Invocation:: How to create configuration scripts
294 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
296 Writing @file{configure.ac}
298 * Shell Script Compiler:: Autoconf as solution of a problem
299 * Autoconf Language:: Programming in Autoconf
300 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
302 Initialization and Output Files
304 * Initializing configure:: Option processing etc.
305 * Notices:: Copyright, version numbers in @command{configure}
306 * Input:: Where Autoconf should find files
307 * Output:: Outputting results from the configuration
308 * Configuration Actions:: Preparing the output based on results
309 * Configuration Files:: Creating output files
310 * Makefile Substitutions:: Using output variables in makefiles
311 * Configuration Headers:: Creating a configuration header file
312 * Configuration Commands:: Running arbitrary instantiation commands
313 * Configuration Links:: Links depending on the configuration
314 * Subdirectories:: Configuring independent packages together
315 * Default Prefix:: Changing the default installation prefix
317 Substitutions in Makefiles
319 * Preset Output Variables:: Output variables that are always set
320 * Installation Directory Variables:: Other preset output variables
321 * Changed Directory Variables:: Warnings about @file{datarootdir}
322 * Build Directories:: Supporting multiple concurrent compiles
323 * Automatic Remaking:: Makefile rules for configuring
325 Configuration Header Files
327 * Header Templates:: Input for the configuration headers
328 * autoheader Invocation:: How to create configuration templates
329 * Autoheader Macros:: How to specify CPP templates
333 * Common Behavior:: Macros' standard schemes
334 * Alternative Programs:: Selecting between alternative programs
335 * Files:: Checking for the existence of files
336 * Libraries:: Library archives that might be missing
337 * Library Functions:: C library functions that might be missing
338 * Header Files:: Header files that might be missing
339 * Declarations:: Declarations that may be missing
340 * Structures:: Structures or members that might be missing
341 * Types:: Types that might be missing
342 * Compilers and Preprocessors:: Checking for compiling programs
343 * System Services:: Operating system services
344 * Posix Variants:: Special kludges for specific Posix variants
345 * Erlang Libraries:: Checking for the existence of Erlang libraries
349 * Standard Symbols:: Symbols defined by the macros
350 * Default Includes:: Includes used by the generic macros
354 * Particular Programs:: Special handling to find certain programs
355 * Generic Programs:: How to find other programs
359 * Function Portability:: Pitfalls with usual functions
360 * Particular Functions:: Special handling to find certain functions
361 * Generic Functions:: How to find other functions
365 * Header Portability:: Collected knowledge on common headers
366 * Particular Headers:: Special handling to find certain headers
367 * Generic Headers:: How to find other headers
371 * Particular Declarations:: Macros to check for certain declarations
372 * Generic Declarations:: How to find other declarations
376 * Particular Structures:: Macros to check for certain structure members
377 * Generic Structures:: How to find other structure members
381 * Particular Types:: Special handling to find certain types
382 * Generic Types:: How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics:: Some portability issues
387 * Generic Compiler Characteristics:: Language independent tests and features
388 * C Compiler:: Checking its characteristics
389 * C++ Compiler:: Likewise
390 * Objective C Compiler:: Likewise
391 * Erlang Compiler and Interpreter:: Likewise
392 * Fortran Compiler:: Likewise
396 * Language Choice:: Selecting which language to use for testing
397 * Writing Test Programs:: Forging source files for compilers
398 * Running the Preprocessor:: Detecting preprocessor symbols
399 * Running the Compiler:: Detecting language or header features
400 * Running the Linker:: Detecting library features
401 * Runtime:: Testing for runtime features
402 * Systemology:: A zoology of operating systems
403 * Multiple Cases:: Tests for several possible values
405 Writing Test Programs
407 * Guidelines:: General rules for writing test programs
408 * Test Functions:: Avoiding pitfalls in test programs
409 * Generating Sources:: Source program boilerplate
413 * Defining Symbols:: Defining C preprocessor symbols
414 * Setting Output Variables:: Replacing variables in output files
415 * Special Chars in Variables:: Characters to beware of in variables
416 * Caching Results:: Speeding up subsequent @command{configure} runs
417 * Printing Messages:: Notifying @command{configure} users
421 * Cache Variable Names:: Shell variables used in caches
422 * Cache Files:: Files @command{configure} uses for caching
423 * Cache Checkpointing:: Loading and saving the cache file
427 * M4 Quotation:: Protecting macros from unwanted expansion
428 * Using autom4te:: The Autoconf executables backbone
429 * Programming in M4sugar:: Convenient pure M4 macros
430 * Programming in M4sh:: Common shell Constructs
431 * File Descriptor Macros:: File descriptor macros for input and output
435 * Active Characters:: Characters that change the behavior of M4
436 * One Macro Call:: Quotation and one macro call
437 * Quotation and Nested Macros:: Macros calling macros
438 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
439 * Quadrigraphs:: Another way to escape special characters
440 * Quotation Rule Of Thumb:: One parenthesis, one quote
442 Using @command{autom4te}
444 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
445 * Customizing autom4te:: Customizing the Autoconf package
447 Programming in M4sugar
449 * Redefined M4 Macros:: M4 builtins changed in M4sugar
450 * Looping constructs:: Iteration in M4
451 * Evaluation Macros:: More quotation and evaluation control
452 * Text processing Macros:: String manipulation in M4
453 * Forbidden Patterns:: Catching unexpanded macros
455 Writing Autoconf Macros
457 * Macro Definitions:: Basic format of an Autoconf macro
458 * Macro Names:: What to call your new macros
459 * Reporting Messages:: Notifying @command{autoconf} users
460 * Dependencies Between Macros:: What to do when macros depend on other macros
461 * Obsoleting Macros:: Warning about old ways of doing things
462 * Coding Style:: Writing Autoconf macros @`a la Autoconf
464 Dependencies Between Macros
466 * Prerequisite Macros:: Ensuring required information
467 * Suggested Ordering:: Warning about possible ordering problems
468 * One-Shot Macros:: Ensuring a macro is called only once
470 Portable Shell Programming
472 * Shellology:: A zoology of shells
473 * Here-Documents:: Quirks and tricks
474 * File Descriptors:: FDs and redirections
475 * File System Conventions:: File names
476 * Shell Pattern Matching:: Pattern matching
477 * Shell Substitutions:: Variable and command expansions
478 * Assignments:: Varying side effects of assignments
479 * Parentheses:: Parentheses in shell scripts
480 * Slashes:: Slashes in shell scripts
481 * Special Shell Variables:: Variables you should not change
482 * Limitations of Builtins:: Portable use of not so portable /bin/sh
483 * Limitations of Usual Tools:: Portable use of portable tools
485 Portable Make Programming
487 * $< in Ordinary Make Rules:: $< in ordinary rules
488 * Failure in Make Rules:: Failing portably in rules
489 * Special Chars in Names:: Special Characters in Macro Names
490 * Backslash-Newline-Newline:: Empty last lines in macro definitions
491 * Backslash-Newline Comments:: Spanning comments across line boundaries
492 * Long Lines in Makefiles:: Line length limitations
493 * Macros and Submakes:: @code{make macro=value} and submakes
494 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
495 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
496 * Comments in Make Rules:: Other problems with Make comments
497 * obj/ and Make:: Don't name a subdirectory @file{obj}
498 * make -k Status:: Exit status of @samp{make -k}
499 * VPATH and Make:: @code{VPATH} woes
500 * Single Suffix Rules:: Single suffix rules and separated dependencies
501 * Timestamps and Make:: Subsecond timestamp resolution
503 @code{VPATH} and Make
505 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
506 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
507 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
508 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
509 * Make Target Lookup:: More details about @code{VPATH} lookup
511 Portable C and C++ Programming
513 * Varieties of Unportability:: How to make your programs unportable
514 * Integer Overflow:: When integers get too large
515 * Null Pointers:: Properties of null pointers
516 * Buffer Overruns:: Subscript errors and the like
517 * Volatile Objects:: @code{volatile} and signals
518 * Floating Point Portability:: Portable floating-point arithmetic
519 * Exiting Portably:: Exiting and the exit status
523 * Specifying Names:: Specifying the system type
524 * Canonicalizing:: Getting the canonical system type
525 * Using System Type:: What to do with the system type
529 * Help Formatting:: Customizing @samp{configure --help}
530 * External Software:: Working with other optional software
531 * Package Options:: Selecting optional features
532 * Pretty Help Strings:: Formatting help string
533 * Option Checking:: Controlling checking of @command{configure} options
534 * Site Details:: Configuring site details
535 * Transforming Names:: Changing program names when installing
536 * Site Defaults:: Giving @command{configure} local defaults
538 Transforming Program Names When Installing
540 * Transformation Options:: @command{configure} options to transform names
541 * Transformation Examples:: Sample uses of transforming names
542 * Transformation Rules:: Makefile uses of transforming names
544 Running @command{configure} Scripts
546 * Basic Installation:: Instructions for typical cases
547 * Compilers and Options:: Selecting compilers and optimization
548 * Multiple Architectures:: Compiling for multiple architectures at once
549 * Installation Names:: Installing in different directories
550 * Optional Features:: Selecting optional features
551 * System Type:: Specifying the system type
552 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
553 * Defining Variables:: Specifying the compiler etc.
554 * configure Invocation:: Changing how @command{configure} runs
558 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
559 * acconfig Header:: Additional entries in @file{config.h.in}
560 * autoupdate Invocation:: Automatic update of @file{configure.ac}
561 * Obsolete Macros:: Backward compatibility macros
562 * Autoconf 1:: Tips for upgrading your files
563 * Autoconf 2.13:: Some fresher tips
565 Upgrading From Version 1
567 * Changed File Names:: Files you might rename
568 * Changed Makefiles:: New things to put in @file{Makefile.in}
569 * Changed Macros:: Macro calls you might replace
570 * Changed Results:: Changes in how to check test results
571 * Changed Macro Writing:: Better ways to write your own macros
573 Upgrading From Version 2.13
575 * Changed Quotation:: Broken code which used to work
576 * New Macros:: Interaction with foreign macros
577 * Hosts and Cross-Compilation:: Bugward compatibility kludges
578 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
579 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
581 Generating Test Suites with Autotest
583 * Using an Autotest Test Suite:: Autotest and the user
584 * Writing Testsuites:: Autotest macros
585 * testsuite Invocation:: Running @command{testsuite} scripts
586 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
588 Using an Autotest Test Suite
590 * testsuite Scripts:: The concepts of Autotest
591 * Autotest Logs:: Their contents
593 Frequent Autoconf Questions, with answers
595 * Distributing:: Distributing @command{configure} scripts
596 * Why GNU M4:: Why not use the standard M4?
597 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
598 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
599 * Defining Directories:: Passing @code{datadir} to program
600 * Autom4te Cache:: What is it? Can I remove it?
601 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
605 * Genesis:: Prehistory and naming of @command{configure}
606 * Exodus:: The plagues of M4 and Perl
607 * Leviticus:: The priestly code of portability arrives
608 * Numbers:: Growth and contributors
609 * Deuteronomy:: Approaching the promises of easy configuration
613 * GNU Free Documentation License:: License for copying this manual
617 * Environment Variable Index:: Index of environment variables used
618 * Output Variable Index:: Index of variables set in output files
619 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
620 * Autoconf Macro Index:: Index of Autoconf macros
621 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
622 * Autotest Macro Index:: Index of Autotest macros
623 * Program & Function Index:: Index of those with portability problems
624 * Concept Index:: General index
629 @c ============================================================= Introduction.
632 @chapter Introduction
636 A physicist, an engineer, and a computer scientist were discussing the
637 nature of God. ``Surely a Physicist,'' said the physicist, ``because
638 early in the Creation, God made Light; and you know, Maxwell's
639 equations, the dual nature of electromagnetic waves, the relativistic
640 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
641 before making Light, God split the Chaos into Land and Water; it takes a
642 hell of an engineer to handle that big amount of mud, and orderly
643 separation of solids from liquids@dots{}'' The computer scientist
644 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
648 @c (via Franc,ois Pinard)
650 Autoconf is a tool for producing shell scripts that automatically
651 configure software source code packages to adapt to many kinds of
652 Posix-like systems. The configuration scripts produced by Autoconf
653 are independent of Autoconf when they are run, so their users do not
654 need to have Autoconf.
656 The configuration scripts produced by Autoconf require no manual user
657 intervention when run; they do not normally even need an argument
658 specifying the system type. Instead, they individually test for the
659 presence of each feature that the software package they are for might need.
660 (Before each check, they print a one-line message stating what they are
661 checking for, so the user doesn't get too bored while waiting for the
662 script to finish.) As a result, they deal well with systems that are
663 hybrids or customized from the more common Posix variants. There is
664 no need to maintain files that list the features supported by each
665 release of each variant of Posix.
667 For each software package that Autoconf is used with, it creates a
668 configuration script from a template file that lists the system features
669 that the package needs or can use. After the shell code to recognize
670 and respond to a system feature has been written, Autoconf allows it to
671 be shared by many software packages that can use (or need) that feature.
672 If it later turns out that the shell code needs adjustment for some
673 reason, it needs to be changed in only one place; all of the
674 configuration scripts can be regenerated automatically to take advantage
677 The Metaconfig package is similar in purpose to Autoconf, but the
678 scripts it produces require manual user intervention, which is quite
679 inconvenient when configuring large source trees. Unlike Metaconfig
680 scripts, Autoconf scripts can support cross-compiling, if some care is
681 taken in writing them.
683 Autoconf does not solve all problems related to making portable
684 software packages---for a more complete solution, it should be used in
685 concert with other @acronym{GNU} build tools like Automake and
686 Libtool. These other tools take on jobs like the creation of a
687 portable, recursive makefile with all of the standard targets,
688 linking of shared libraries, and so on. @xref{The GNU Build System},
689 for more information.
691 Autoconf imposes some restrictions on the names of macros used with
692 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
694 Autoconf requires @acronym{GNU} M4 version 1.4.5 or later in order to
695 generate the scripts. It uses features that some versions of M4,
696 including @acronym{GNU} M4 1.3, do not have. Autoconf works better
697 with @acronym{GNU} M4 version 1.4.8 or later, though this is not
700 @xref{Autoconf 1}, for information about upgrading from version 1.
701 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
702 for answers to some common questions about Autoconf.
704 See the @uref{http://www.gnu.org/software/autoconf/,
705 Autoconf web page} for up-to-date information, details on the mailing
706 lists, pointers to a list of known bugs, etc.
708 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
709 list}. Past suggestions are
710 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
712 Mail bug reports to @email{bug-autoconf@@gnu.org, the
713 Autoconf Bugs mailing list}. Past bug reports are
714 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
716 If possible, first check that your bug is
717 not already solved in current development versions, and that it has not
718 been reported yet. Be sure to include all the needed information and a
719 short @file{configure.ac} that demonstrates the problem.
721 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
722 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
723 Summary} for details. Patches relative to the
724 current @acronym{CVS} version can be sent for review to the
725 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
727 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
729 Because of its mission, the Autoconf package itself
730 includes only a set of often-used
731 macros that have already demonstrated their usefulness. Nevertheless,
732 if you wish to share your macros, or find existing ones, see the
733 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
734 Archive}, which is kindly run by @email{simons@@cryp.to,
738 @c ================================================= The GNU Build System
740 @node The GNU Build System
741 @chapter The @acronym{GNU} Build System
742 @cindex @acronym{GNU} build system
744 Autoconf solves an important problem---reliable discovery of
745 system-specific build and runtime information---but this is only one
746 piece of the puzzle for the development of portable software. To this
747 end, the @acronym{GNU} project has developed a suite of integrated
748 utilities to finish the job Autoconf started: the @acronym{GNU} build
749 system, whose most important components are Autoconf, Automake, and
750 Libtool. In this chapter, we introduce you to those tools, point you
751 to sources of more information, and try to convince you to use the
752 entire @acronym{GNU} build system for your software.
755 * Automake:: Escaping makefile hell
756 * Gnulib:: The @acronym{GNU} portability library
757 * Libtool:: Building libraries portably
758 * Pointers:: More info on the @acronym{GNU} build system
764 The ubiquity of @command{make} means that a makefile is almost the
765 only viable way to distribute automatic build rules for software, but
766 one quickly runs into its numerous limitations. Its lack of
767 support for automatic dependency tracking, recursive builds in
768 subdirectories, reliable timestamps (e.g., for network file systems), and
769 so on, mean that developers must painfully (and often incorrectly)
770 reinvent the wheel for each project. Portability is non-trivial, thanks
771 to the quirks of @command{make} on many systems. On top of all this is the
772 manual labor required to implement the many standard targets that users
773 have come to expect (@code{make install}, @code{make distclean},
774 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
775 you also have to insert repetitive code in your @code{Makefile.in} to
776 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
777 provided by @command{configure}. Into this mess steps @dfn{Automake}.
780 Automake allows you to specify your build needs in a @code{Makefile.am}
781 file with a vastly simpler and more powerful syntax than that of a plain
782 makefile, and then generates a portable @code{Makefile.in} for
783 use with Autoconf. For example, the @code{Makefile.am} to build and
784 install a simple ``Hello world'' program might look like:
788 hello_SOURCES = hello.c
792 The resulting @code{Makefile.in} (~400 lines) automatically supports all
793 the standard targets, the substitutions provided by Autoconf, automatic
794 dependency tracking, @code{VPATH} building, and so on. @command{make}
795 builds the @code{hello} program, and @code{make install} installs it
796 in @file{/usr/local/bin} (or whatever prefix was given to
797 @command{configure}, if not @file{/usr/local}).
799 The benefits of Automake increase for larger packages (especially ones
800 with subdirectories), but even for small programs the added convenience
801 and portability can be substantial. And that's not all@enddots{}
806 @acronym{GNU} software has a well-deserved reputation for running on
807 many different types of systems. While our primary goal is to write
808 software for the @acronym{GNU} system, many users and developers have
809 been introduced to us through the systems that they were already using.
812 Gnulib is a central location for common @acronym{GNU} code, intended to
813 be shared among free software packages. Its components are typically
814 shared at the source level, rather than being a library that gets built,
815 installed, and linked against. The idea is to copy files from Gnulib
816 into your own source tree. There is no distribution tarball; developers
817 should just grab source modules from the repository. The source files
818 are available online, under various licenses, mostly @acronym{GNU}
819 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
821 Gnulib modules typically contain C source code along with Autoconf
822 macros used to configure the source code. For example, the Gnulib
823 @code{stdbool} module implements a @file{stdbool.h} header that nearly
824 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
825 This module contains a source file for the replacement header, along
826 with an Autoconf macro that arranges to use the replacement header on
827 old-fashioned systems.
832 Often, one wants to build not only programs, but libraries, so that
833 other programs can benefit from the fruits of your labor. Ideally, one
834 would like to produce @emph{shared} (dynamically linked) libraries,
835 which can be used by multiple programs without duplication on disk or in
836 memory and can be updated independently of the linked programs.
837 Producing shared libraries portably, however, is the stuff of
838 nightmares---each system has its own incompatible tools, compiler flags,
839 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
843 Libtool handles all the requirements of building shared libraries for
844 you, and at this time seems to be the @emph{only} way to do so with any
845 portability. It also handles many other headaches, such as: the
846 interaction of Make rules with the variable suffixes of
847 shared libraries, linking reliably with shared libraries before they are
848 installed by the superuser, and supplying a consistent versioning system
849 (so that different versions of a library can be installed or upgraded
850 without breaking binary compatibility). Although Libtool, like
851 Autoconf, can be used without Automake, it is most simply utilized in
852 conjunction with Automake---there, Libtool is used automatically
853 whenever shared libraries are needed, and you need not know its syntax.
858 Developers who are used to the simplicity of @command{make} for small
859 projects on a single system might be daunted at the prospect of
860 learning to use Automake and Autoconf. As your software is
861 distributed to more and more users, however, you otherwise
862 quickly find yourself putting lots of effort into reinventing the
863 services that the @acronym{GNU} build tools provide, and making the
864 same mistakes that they once made and overcame. (Besides, since
865 you're already learning Autoconf, Automake is a piece of cake.)
867 There are a number of places that you can go to for more information on
868 the @acronym{GNU} build tools.
875 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
876 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
877 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
878 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
880 @item Automake Manual
882 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
883 information on Automake.
887 The book @cite{@acronym{GNU} Autoconf, Automake and
888 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
889 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
890 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
891 build environment. You can also find
892 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
896 @c ================================================= Making configure Scripts.
898 @node Making configure Scripts
899 @chapter Making @command{configure} Scripts
900 @cindex @file{aclocal.m4}
901 @cindex @command{configure}
903 The configuration scripts that Autoconf produces are by convention
904 called @command{configure}. When run, @command{configure} creates several
905 files, replacing configuration parameters in them with appropriate
906 values. The files that @command{configure} creates are:
910 one or more @file{Makefile} files, usually one in each subdirectory of the
911 package (@pxref{Makefile Substitutions});
914 optionally, a C header file, the name of which is configurable,
915 containing @code{#define} directives (@pxref{Configuration Headers});
918 a shell script called @file{config.status} that, when run, recreates
919 the files listed above (@pxref{config.status Invocation});
922 an optional shell script normally called @file{config.cache}
923 (created when using @samp{configure --config-cache}) that
924 saves the results of running many of the tests (@pxref{Cache Files});
927 a file called @file{config.log} containing any messages produced by
928 compilers, to help debugging if @command{configure} makes a mistake.
931 @cindex @file{configure.in}
932 @cindex @file{configure.ac}
933 To create a @command{configure} script with Autoconf, you need to write an
934 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
935 @command{autoconf} on it. If you write your own feature tests to
936 supplement those that come with Autoconf, you might also write files
937 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
938 file to contain @code{#define} directives, you might also run
939 @command{autoheader}, and you can distribute the generated file
940 @file{config.h.in} with the package.
942 Here is a diagram showing how the files that can be used in
943 configuration are produced. Programs that are executed are suffixed by
944 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
945 @command{autoconf} and @command{autoheader} also read the installed Autoconf
946 macro files (by reading @file{autoconf.m4}).
949 Files used in preparing a software package for distribution:
951 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
955 | .------> autoconf* -----> configure
957 | `-----> [autoheader*] --> [config.h.in]
961 Makefile.in -------------------------------> Makefile.in
965 Files used in configuring a software package:
968 .-------------> [config.cache]
969 configure* ------------+-------------> config.log
971 [config.h.in] -. v .-> [config.h] -.
972 +--> config.status* -+ +--> make*
973 Makefile.in ---' `-> Makefile ---'
978 * Writing Autoconf Input:: What to put in an Autoconf input file
979 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
980 * ifnames Invocation:: Listing the conditionals in source code
981 * autoconf Invocation:: How to create configuration scripts
982 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
985 @node Writing Autoconf Input
986 @section Writing @file{configure.ac}
988 To produce a @command{configure} script for a software package, create a
989 file called @file{configure.ac} that contains invocations of the
990 Autoconf macros that test the system features your package needs or can
991 use. Autoconf macros already exist to check for many features; see
992 @ref{Existing Tests}, for their descriptions. For most other features,
993 you can use Autoconf template macros to produce custom checks; see
994 @ref{Writing Tests}, for information about them. For especially tricky
995 or specialized features, @file{configure.ac} might need to contain some
996 hand-crafted shell commands; see @ref{Portable Shell}. The
997 @command{autoscan} program can give you a good start in writing
998 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
1000 Previous versions of Autoconf promoted the name @file{configure.in},
1001 which is somewhat ambiguous (the tool needed to process this file is not
1002 described by its extension), and introduces a slight confusion with
1003 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1004 processed by @command{configure}''). Using @file{configure.ac} is now
1008 * Shell Script Compiler:: Autoconf as solution of a problem
1009 * Autoconf Language:: Programming in Autoconf
1010 * Autoconf Input Layout:: Standard organization of @file{configure.ac}
1013 @node Shell Script Compiler
1014 @subsection A Shell Script Compiler
1016 Just as for any other computer language, in order to properly program
1017 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1018 the language tries to address and @emph{how} it does so.
1020 The problem Autoconf addresses is that the world is a mess. After all,
1021 you are using Autoconf in order to have your package compile easily on
1022 all sorts of different systems, some of them being extremely hostile.
1023 Autoconf itself bears the price for these differences: @command{configure}
1024 must run on all those systems, and thus @command{configure} must limit itself
1025 to their lowest common denominator of features.
1027 Naturally, you might then think of shell scripts; who needs
1028 @command{autoconf}? A set of properly written shell functions is enough to
1029 make it easy to write @command{configure} scripts by hand. Sigh!
1030 Unfortunately, shell functions do not belong to the least common
1031 denominator; therefore, where you would like to define a function and
1032 use it ten times, you would instead need to copy its body ten times.
1034 So, what is really needed is some kind of compiler, @command{autoconf},
1035 that takes an Autoconf program, @file{configure.ac}, and transforms it
1036 into a portable shell script, @command{configure}.
1038 How does @command{autoconf} perform this task?
1040 There are two obvious possibilities: creating a brand new language or
1041 extending an existing one. The former option is attractive: all
1042 sorts of optimizations could easily be implemented in the compiler and
1043 many rigorous checks could be performed on the Autoconf program
1044 (e.g., rejecting any non-portable construct). Alternatively, you can
1045 extend an existing language, such as the @code{sh} (Bourne shell)
1048 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1049 therefore most convenient to implement @command{autoconf} as a macro
1050 expander: a program that repeatedly performs @dfn{macro expansions} on
1051 text input, replacing macro calls with macro bodies and producing a pure
1052 @code{sh} script in the end. Instead of implementing a dedicated
1053 Autoconf macro expander, it is natural to use an existing
1054 general-purpose macro language, such as M4, and implement the extensions
1055 as a set of M4 macros.
1058 @node Autoconf Language
1059 @subsection The Autoconf Language
1062 The Autoconf language differs from many other computer
1063 languages because it treats actual code the same as plain text. Whereas
1064 in C, for instance, data and instructions have different syntactic
1065 status, in Autoconf their status is rigorously the same. Therefore, we
1066 need a means to distinguish literal strings from text to be expanded:
1069 When calling macros that take arguments, there must not be any white
1070 space between the macro name and the open parenthesis. Arguments should
1071 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1072 separated by commas. Any leading blanks or newlines in arguments are ignored,
1073 unless they are quoted. You should always quote an argument that
1074 might contain a macro name, comma, parenthesis, or a leading blank or
1075 newline. This rule applies recursively for every macro
1076 call, including macros called from other macros.
1081 AC_CHECK_HEADER([stdio.h],
1082 [AC_DEFINE([HAVE_STDIO_H], [1],
1083 [Define to 1 if you have <stdio.h>.])],
1084 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1088 is quoted properly. You may safely simplify its quotation to:
1091 AC_CHECK_HEADER([stdio.h],
1092 [AC_DEFINE([HAVE_STDIO_H], 1,
1093 [Define to 1 if you have <stdio.h>.])],
1094 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1098 because @samp{1} cannot contain a macro call. Here, the argument of
1099 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1100 interpreted as an argument separator. Also, the second and third arguments
1101 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1102 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1103 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1104 if you unwisely defined a macro with a name like @samp{Define} or
1105 @samp{stdio} then they would need quoting. Cautious Autoconf users
1106 would keep the quotes, but many Autoconf users find such precautions
1107 annoying, and would rewrite the example as follows:
1110 AC_CHECK_HEADER(stdio.h,
1111 [AC_DEFINE(HAVE_STDIO_H, 1,
1112 [Define to 1 if you have <stdio.h>.])],
1113 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1117 This is safe, so long as you adopt good naming conventions and do not
1118 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1119 @samp{h}. Though it is also safe here to omit the quotes around
1120 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1121 message strings are more likely to inadvertently contain commas.
1123 The following example is wrong and dangerous, as it is underquoted:
1126 AC_CHECK_HEADER(stdio.h,
1127 AC_DEFINE(HAVE_STDIO_H, 1,
1128 Define to 1 if you have <stdio.h>.),
1129 AC_MSG_ERROR([Sorry, can't do anything for you]))
1132 In other cases, you may have to use text that also resembles a macro
1133 call. You must quote that text even when it is not passed as a macro
1137 echo "Hard rock was here! --[AC_DC]"
1144 echo "Hard rock was here! --AC_DC"
1148 When you use the same text in a macro argument, you must therefore have
1149 an extra quotation level (since one is stripped away by the macro
1150 substitution). In general, then, it is a good idea to @emph{use double
1151 quoting for all literal string arguments}:
1154 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1157 You are now able to understand one of the constructs of Autoconf that
1158 has been continually misunderstood@dots{} The rule of thumb is that
1159 @emph{whenever you expect macro expansion, expect quote expansion};
1160 i.e., expect one level of quotes to be lost. For instance:
1163 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1167 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1168 @samp{char b[10];} and is expanded once, which results in
1169 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1170 address this issue via the M4 @code{changequote} primitive, but do not
1171 use it!) Let's take a closer look: the author meant the first argument
1172 to be understood as a literal, and therefore it must be quoted twice:
1175 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1179 Voil@`a, you actually produce @samp{char b[10];} this time!
1181 On the other hand, descriptions (e.g., the last parameter of
1182 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1183 are subject to line breaking, for example---and should not be double quoted.
1184 Even if these descriptions are short and are not actually broken, double
1185 quoting them yields weird results.
1187 Some macros take optional arguments, which this documentation represents
1188 as @ovar{arg} (not to be confused with the quote characters). You may
1189 just leave them empty, or use @samp{[]} to make the emptiness of the
1190 argument explicit, or you may simply omit the trailing commas. The
1191 three lines below are equivalent:
1194 AC_CHECK_HEADERS([stdio.h], [], [], [])
1195 AC_CHECK_HEADERS([stdio.h],,,)
1196 AC_CHECK_HEADERS([stdio.h])
1199 It is best to put each macro call on its own line in
1200 @file{configure.ac}. Most of the macros don't add extra newlines; they
1201 rely on the newline after the macro call to terminate the commands.
1202 This approach makes the generated @command{configure} script a little
1203 easier to read by not inserting lots of blank lines. It is generally
1204 safe to set shell variables on the same line as a macro call, because
1205 the shell allows assignments without intervening newlines.
1207 You can include comments in @file{configure.ac} files by starting them
1208 with the @samp{#}. For example, it is helpful to begin
1209 @file{configure.ac} files with a line like this:
1212 # Process this file with autoconf to produce a configure script.
1215 @node Autoconf Input Layout
1216 @subsection Standard @file{configure.ac} Layout
1218 The order in which @file{configure.ac} calls the Autoconf macros is not
1219 important, with a few exceptions. Every @file{configure.ac} must
1220 contain a call to @code{AC_INIT} before the checks, and a call to
1221 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1222 rely on other macros having been called first, because they check
1223 previously set values of some variables to decide what to do. These
1224 macros are noted in the individual descriptions (@pxref{Existing
1225 Tests}), and they also warn you when @command{configure} is created if they
1226 are called out of order.
1228 To encourage consistency, here is a suggested order for calling the
1229 Autoconf macros. Generally speaking, the things near the end of this
1230 list are those that could depend on things earlier in it. For example,
1231 library functions could be affected by types and libraries.
1235 Autoconf requirements
1236 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1237 information on the package
1239 checks for libraries
1240 checks for header files
1242 checks for structures
1243 checks for compiler characteristics
1244 checks for library functions
1245 checks for system services
1246 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1252 @node autoscan Invocation
1253 @section Using @command{autoscan} to Create @file{configure.ac}
1254 @cindex @command{autoscan}
1256 The @command{autoscan} program can help you create and/or maintain a
1257 @file{configure.ac} file for a software package. @command{autoscan}
1258 examines source files in the directory tree rooted at a directory given
1259 as a command line argument, or the current directory if none is given.
1260 It searches the source files for common portability problems and creates
1261 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1262 for that package, and checks a possibly existing @file{configure.ac} for
1265 When using @command{autoscan} to create a @file{configure.ac}, you
1266 should manually examine @file{configure.scan} before renaming it to
1267 @file{configure.ac}; it probably needs some adjustments.
1268 Occasionally, @command{autoscan} outputs a macro in the wrong order
1269 relative to another macro, so that @command{autoconf} produces a warning;
1270 you need to move such macros manually. Also, if you want the package to
1271 use a configuration header file, you must add a call to
1272 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1273 also have to change or add some @code{#if} directives to your program in
1274 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1275 information about a program that can help with that job).
1277 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1278 consider adding its suggestions. The file @file{autoscan.log}
1279 contains detailed information on why a macro is requested.
1281 @command{autoscan} uses several data files (installed along with Autoconf)
1282 to determine which macros to output when it finds particular symbols in
1283 a package's source files. These data files all have the same format:
1284 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1285 output if that symbol is encountered. Lines starting with @samp{#} are
1288 @command{autoscan} accepts the following options:
1293 Print a summary of the command line options and exit.
1297 Print the version number of Autoconf and exit.
1301 Print the names of the files it examines and the potentially interesting
1302 symbols it finds in them. This output can be voluminous.
1304 @item --include=@var{dir}
1306 Append @var{dir} to the include path. Multiple invocations accumulate.
1308 @item --prepend-include=@var{dir}
1310 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1313 @node ifnames Invocation
1314 @section Using @command{ifnames} to List Conditionals
1315 @cindex @command{ifnames}
1317 @command{ifnames} can help you write @file{configure.ac} for a software
1318 package. It prints the identifiers that the package already uses in C
1319 preprocessor conditionals. If a package has already been set up to have
1320 some portability, @command{ifnames} can thus help you figure out what its
1321 @command{configure} needs to check for. It may help fill in some gaps in a
1322 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1325 @command{ifnames} scans all of the C source files named on the command line
1326 (or the standard input, if none are given) and writes to the standard
1327 output a sorted list of all the identifiers that appear in those files
1328 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1329 directives. It prints each identifier on a line, followed by a
1330 space-separated list of the files in which that identifier occurs.
1333 @command{ifnames} accepts the following options:
1338 Print a summary of the command line options and exit.
1342 Print the version number of Autoconf and exit.
1345 @node autoconf Invocation
1346 @section Using @command{autoconf} to Create @command{configure}
1347 @cindex @command{autoconf}
1349 To create @command{configure} from @file{configure.ac}, run the
1350 @command{autoconf} program with no arguments. @command{autoconf} processes
1351 @file{configure.ac} with the M4 macro processor, using the
1352 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1353 file instead of @file{configure.ac} and writes the configuration script
1354 to the standard output instead of to @command{configure}. If you give
1355 @command{autoconf} the argument @option{-}, it reads from the standard
1356 input instead of @file{configure.ac} and writes the configuration script
1357 to the standard output.
1359 The Autoconf macros are defined in several files. Some of the files are
1360 distributed with Autoconf; @command{autoconf} reads them first. Then it
1361 looks for the optional file @file{acsite.m4} in the directory that
1362 contains the distributed Autoconf macro files, and for the optional file
1363 @file{aclocal.m4} in the current directory. Those files can contain
1364 your site's or the package's own Autoconf macro definitions
1365 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1366 defined in more than one of the files that @command{autoconf} reads, the
1367 last definition it reads overrides the earlier ones.
1369 @command{autoconf} accepts the following options:
1374 Print a summary of the command line options and exit.
1378 Print the version number of Autoconf and exit.
1382 Report processing steps.
1386 Don't remove the temporary files.
1390 Remake @file{configure} even if newer than its input files.
1392 @item --include=@var{dir}
1394 Append @var{dir} to the include path. Multiple invocations accumulate.
1396 @item --prepend-include=@var{dir}
1398 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1400 @item --output=@var{file}
1401 @itemx -o @var{file}
1402 Save output (script or trace) to @var{file}. The file @option{-} stands
1403 for the standard output.
1405 @item --warnings=@var{category}
1406 @itemx -W @var{category}
1408 Report the warnings related to @var{category} (which can actually be a
1409 comma separated list). @xref{Reporting Messages}, macro
1410 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1415 report all the warnings
1421 treats warnings as errors
1423 @item no-@var{category}
1424 disable warnings falling into @var{category}
1427 Warnings about @samp{syntax} are enabled by default, and the environment
1428 variable @env{WARNINGS}, a comma separated list of categories, is
1429 honored as well. Passing @option{-W @var{category}} actually behaves as if
1430 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1431 you want to disable the defaults and @env{WARNINGS}, but (for example)
1432 enable the warnings about obsolete constructs, you would use @option{-W
1436 @cindex Macro invocation stack
1437 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1438 displays a back trace for errors, but not for warnings; if you want
1439 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1442 @item --trace=@var{macro}[:@var{format}]
1443 @itemx -t @var{macro}[:@var{format}]
1444 Do not create the @command{configure} script, but list the calls to
1445 @var{macro} according to the @var{format}. Multiple @option{--trace}
1446 arguments can be used to list several macros. Multiple @option{--trace}
1447 arguments for a single macro are not cumulative; instead, you should
1448 just make @var{format} as long as needed.
1450 The @var{format} is a regular string, with newlines if desired, and
1451 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1452 @ref{autom4te Invocation}, for details on the @var{format}.
1454 @item --initialization
1456 By default, @option{--trace} does not trace the initialization of the
1457 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1458 results in a noticeable speedup, but can be disabled by this option.
1462 It is often necessary to check the content of a @file{configure.ac}
1463 file, but parsing it yourself is extremely fragile and error-prone. It
1464 is suggested that you rely upon @option{--trace} to scan
1465 @file{configure.ac}. For instance, to find the list of variables that
1466 are substituted, use:
1470 $ @kbd{autoconf -t AC_SUBST}
1471 configure.ac:2:AC_SUBST:ECHO_C
1472 configure.ac:2:AC_SUBST:ECHO_N
1473 configure.ac:2:AC_SUBST:ECHO_T
1474 @i{More traces deleted}
1479 The example below highlights the difference between @samp{$@@},
1480 @samp{$*}, and @samp{$%}.
1484 $ @kbd{cat configure.ac}
1485 AC_DEFINE(This, is, [an
1487 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1494 %: This:is:an [example]
1499 The @var{format} gives you a lot of freedom:
1503 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1504 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1505 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1506 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1507 @i{More traces deleted}
1512 A long @var{separator} can be used to improve the readability of complex
1513 structures, and to ease their parsing (for instance when no single
1514 character is suitable as a separator):
1518 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1519 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1520 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1521 AUTOMAKE|:::::|automake|:::::|$missing_dir
1522 @i{More traces deleted}
1526 @node autoreconf Invocation
1527 @section Using @command{autoreconf} to Update @command{configure} Scripts
1528 @cindex @command{autoreconf}
1530 Installing the various components of the @acronym{GNU} Build System can be
1531 tedious: running @command{autopoint} for Gettext, @command{automake} for
1532 @file{Makefile.in} etc.@: in each directory. It may be needed either
1533 because some tools such as @command{automake} have been updated on your
1534 system, or because some of the sources such as @file{configure.ac} have
1535 been updated, or finally, simply in order to install the @acronym{GNU} Build
1536 System in a fresh tree.
1538 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1539 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1540 @command{autopoint} (when appropriate) repeatedly to update the
1541 @acronym{GNU} Build System in the specified directories and their
1542 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1543 those files that are older than their sources.
1545 If you install a new version of some tool, you can make
1546 @command{autoreconf} remake @emph{all} of the files by giving it the
1547 @option{--force} option.
1549 @xref{Automatic Remaking}, for Make rules to automatically
1550 remake @command{configure} scripts when their source files change. That
1551 method handles the timestamps of configuration header templates
1552 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1553 @option{--localdir=@var{dir}}.
1556 @cindex @command{autopoint}
1557 Gettext supplies the @command{autopoint} command to add translation
1558 infrastructure to a source package. If you use @command{autopoint},
1559 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1560 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1561 Invocation, , Invoking the @code{autopoint} Program, gettext,
1562 @acronym{GNU} @code{gettext} utilities}, for further details.
1565 @command{autoreconf} accepts the following options:
1570 Print a summary of the command line options and exit.
1574 Print the version number of Autoconf and exit.
1577 Print the name of each directory @command{autoreconf} examines and the
1578 commands it runs. If given two or more times, pass @option{--verbose}
1579 to subordinate tools that support it.
1583 Don't remove the temporary files.
1587 Remake even @file{configure} scripts and configuration headers that are
1588 newer than their input files (@file{configure.ac} and, if present,
1593 Install the missing auxiliary files in the package. By default, files
1594 are copied; this can be changed with @option{--symlink}.
1596 If deemed appropriate, this option triggers calls to
1597 @samp{automake --add-missing},
1598 @samp{libtoolize}, @samp{autopoint}, etc.
1600 @item --no-recursive
1601 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1602 macro @code{AC_CONFIG_SUBDIRS}).
1606 When used with @option{--install}, install symbolic links to the missing
1607 auxiliary files instead of copying them.
1611 When the directories were configured, update the configuration by
1612 running @samp{./config.status --recheck && ./config.status}, and then
1615 @item --include=@var{dir}
1617 Append @var{dir} to the include path. Multiple invocations accumulate.
1618 Passed on to @command{autoconf} and @command{autoheader} internally.
1620 @item --prepend-include=@var{dir}
1622 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1623 Passed on to @command{autoconf} and @command{autoheader} internally.
1625 @item --warnings=@var{category}
1626 @itemx -W @var{category}
1628 Report the warnings related to @var{category} (which can actually be a
1629 comma separated list).
1633 related to cross compilation issues.
1636 report the uses of obsolete constructs.
1642 dubious syntactic constructs.
1645 report all the warnings
1651 treats warnings as errors
1653 @item no-@var{category}
1654 disable warnings falling into @var{category}
1657 Warnings about @samp{syntax} are enabled by default, and the environment
1658 variable @env{WARNINGS}, a comma separated list of categories, is
1659 honored as well. Passing @option{-W @var{category}} actually behaves as if
1660 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1661 you want to disable the defaults and @env{WARNINGS}, but (for example)
1662 enable the warnings about obsolete constructs, you would use @option{-W
1666 If you want @command{autoreconf} to pass flags that are not listed here
1667 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1669 @c ========================================= Initialization and Output Files.
1672 @chapter Initialization and Output Files
1674 Autoconf-generated @command{configure} scripts need some information about
1675 how to initialize, such as how to find the package's source files and
1676 about the output files to produce. The following sections describe the
1677 initialization and the creation of output files.
1680 * Initializing configure:: Option processing etc.
1681 * Notices:: Copyright, version numbers in @command{configure}
1682 * Input:: Where Autoconf should find files
1683 * Output:: Outputting results from the configuration
1684 * Configuration Actions:: Preparing the output based on results
1685 * Configuration Files:: Creating output files
1686 * Makefile Substitutions:: Using output variables in makefiles
1687 * Configuration Headers:: Creating a configuration header file
1688 * Configuration Commands:: Running arbitrary instantiation commands
1689 * Configuration Links:: Links depending on the configuration
1690 * Subdirectories:: Configuring independent packages together
1691 * Default Prefix:: Changing the default installation prefix
1694 @node Initializing configure
1695 @section Initializing @command{configure}
1697 Every @command{configure} script must call @code{AC_INIT} before doing
1698 anything else. The only other required macro is @code{AC_OUTPUT}
1701 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1703 Process any command-line arguments and perform various initializations
1706 Set the name of the @var{package} and its @var{version}. These are
1707 typically used in @option{--version} support, including that of
1708 @command{configure}. The optional argument @var{bug-report} should be
1709 the email to which users should send bug reports. The package
1710 @var{tarname} differs from @var{package}: the latter designates the full
1711 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1712 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1713 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1714 other than alphanumerics and underscores are changed to @samp{-}.
1716 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1717 there should not be any shell computation, but they can be computed by
1720 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1721 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1722 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1725 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1726 @acindex{PACKAGE_NAME}
1727 @ovindex PACKAGE_NAME
1728 @cvindex PACKAGE_NAME
1729 Exactly @var{package}.
1731 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1732 @acindex{PACKAGE_TARNAME}
1733 @ovindex PACKAGE_TARNAME
1734 @cvindex PACKAGE_TARNAME
1735 Exactly @var{tarname}.
1737 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1738 @acindex{PACKAGE_VERSION}
1739 @ovindex PACKAGE_VERSION
1740 @cvindex PACKAGE_VERSION
1741 Exactly @var{version}.
1743 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1744 @acindex{PACKAGE_STRING}
1745 @ovindex PACKAGE_STRING
1746 @cvindex PACKAGE_STRING
1747 Exactly @samp{@var{package} @var{version}}.
1749 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1750 @acindex{PACKAGE_BUGREPORT}
1751 @ovindex PACKAGE_BUGREPORT
1752 @cvindex PACKAGE_BUGREPORT
1753 Exactly @var{bug-report}.
1757 If your @command{configure} script does its own option processing, it
1758 should inspect @samp{$@@} or @samp{$*} immediately after calling
1759 @code{AC_INIT}, because other Autoconf macros liberally use the
1760 @command{set} command to process strings, and this has the side effect
1761 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1762 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1763 implement your own option processing. @xref{Site Configuration}.
1767 @section Notices in @command{configure}
1768 @cindex Notices in @command{configure}
1770 The following macros manage version numbers for @command{configure}
1771 scripts. Using them is optional.
1773 @c FIXME: AC_PREREQ should not be here
1774 @defmac AC_PREREQ (@var{version})
1777 Ensure that a recent enough version of Autoconf is being used. If the
1778 version of Autoconf being used to create @command{configure} is
1779 earlier than @var{version}, print an error message to the standard
1780 error output and exit with failure (exit status is 63). For example:
1783 AC_PREREQ([@value{VERSION}])
1786 This macro is the only macro that may be used before @code{AC_INIT}, but
1787 for consistency, you are invited not to do so.
1790 @defmac AC_COPYRIGHT (@var{copyright-notice})
1792 @cindex Copyright Notice
1793 State that, in addition to the Free Software Foundation's copyright on
1794 the Autoconf macros, parts of your @command{configure} are covered by the
1795 @var{copyright-notice}.
1797 The @var{copyright-notice} shows up in both the head of
1798 @command{configure} and in @samp{configure --version}.
1802 @defmac AC_REVISION (@var{revision-info})
1805 Copy revision stamp @var{revision-info} into the @command{configure}
1806 script, with any dollar signs or double-quotes removed. This macro lets
1807 you put a revision stamp from @file{configure.ac} into @command{configure}
1808 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1809 @command{configure}. That way, you can determine easily which revision of
1810 @file{configure.ac} a particular @command{configure} corresponds to.
1812 For example, this line in @file{configure.ac}:
1814 @c The asis prevents RCS from changing the example in the manual.
1816 AC_REVISION([$@asis{Revision: 1.30 }$])
1820 produces this in @command{configure}:
1824 # From configure.ac Revision: 1.30
1830 @section Finding @command{configure} Input
1833 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1834 @acindex{CONFIG_SRCDIR}
1835 @var{unique-file-in-source-dir} is some file that is in the package's
1836 source directory; @command{configure} checks for this file's existence to
1837 make sure that the directory that it is told contains the source code in
1838 fact does. Occasionally people accidentally specify the wrong directory
1839 with @option{--srcdir}; this is a safety check. @xref{configure
1840 Invocation}, for more information.
1844 @c FIXME: Remove definitively once --install explained.
1846 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1847 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1848 @c to split the macros in several files. In this case, Autoconf must be
1849 @c told which files to load, and in which order.
1851 @c @defmac AC_INCLUDE (@var{file}@dots{})
1852 @c @acindex{INCLUDE}
1853 @c @c FIXME: There is no longer shell globbing.
1854 @c Read the macro definitions that appear in the listed files. A list of
1855 @c space-separated file names or shell globbing patterns is expected. The
1856 @c files are read in the order they're listed.
1858 @c Because the order of definition of macros is important (only the last
1859 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1860 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1861 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1862 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1863 @c the latter case, non-macro lines from included files may end up in the
1864 @c @file{configure} script, whereas in the former case, they'd be discarded
1865 @c just like any text that appear before @code{AC_INIT}.
1868 Packages that do manual configuration or use the @command{install} program
1869 might need to tell @command{configure} where to find some other shell
1870 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1871 it looks are correct for most cases.
1873 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1874 @acindex{CONFIG_AUX_DIR}
1875 Use the auxiliary build tools (e.g., @file{install-sh},
1876 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1877 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1878 These are auxiliary files used in configuration. @var{dir} can be
1879 either absolute or relative to @file{@var{srcdir}}. The default is
1880 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1881 @file{@var{srcdir}/../..}, whichever is the first that contains
1882 @file{install-sh}. The other files are not checked for, so that using
1883 @code{AC_PROG_INSTALL} does not automatically require distributing the
1884 other auxiliary files. It checks for @file{install.sh} also, but that
1885 name is obsolete because some @code{make} have a rule that creates
1886 @file{install} from it if there is no makefile.
1888 The auxiliary directory is commonly named @file{build-aux}.
1889 If you need portability to @acronym{DOS} variants, do not name the
1890 auxiliary directory @file{aux}. @xref{File System Conventions}.
1893 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1894 @acindex{REQUIRE_AUX_FILE}
1895 Declares that @var{file} is expected in the directory defined above. In
1896 Autoconf proper, this macro does nothing: its sole purpose is to be
1897 traced by third-party tools to produce a list of expected auxiliary
1898 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1899 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1900 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1903 Similarly, packages that use @command{aclocal} should declare where
1904 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1906 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1907 @acindex{CONFIG_MACRO_DIR}
1908 Specify @var{dir} as the location of additional local Autoconf macros.
1909 This macro is intended for use by future versions of commands like
1910 @command{autoreconf} that trace macro calls. It should be called
1911 directly from @file{configure.ac} so that tools that install macros for
1912 @command{aclocal} can find the macros' declarations.
1917 @section Outputting Files
1918 @cindex Outputting files
1920 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1921 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1922 @file{config.status}, which in turn creates the makefiles and any
1923 other files resulting from configuration. This is the only required
1924 macro besides @code{AC_INIT} (@pxref{Input}).
1928 @cindex Instantiation
1929 Generate @file{config.status} and launch it. Call this macro once, at
1930 the end of @file{configure.ac}.
1932 @file{config.status} performs all the configuration actions: all the
1933 output files (see @ref{Configuration Files}, macro
1934 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1935 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1936 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1937 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1938 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1941 The location of your @code{AC_OUTPUT} invocation is the exact point
1942 where configuration actions are taken: any code afterwards is
1943 executed by @code{configure} once @command{config.status} was run. If
1944 you want to bind actions to @command{config.status} itself
1945 (independently of whether @command{configure} is being run), see
1946 @ref{Configuration Commands, , Running Arbitrary Configuration
1950 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1951 @xref{Obsolete Macros}, for a description of the arguments that
1952 @code{AC_OUTPUT} used to support.
1955 If you run @command{make} in subdirectories, you should run it using the
1956 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1957 @code{MAKE} to the name of the @command{make} program plus any options it
1958 was given. (But many do not include in it the values of any variables
1959 set on the command line, so those are not passed on automatically.)
1960 Some old versions of @command{make} do not set this variable. The
1961 following macro allows you to use it even with those versions.
1963 @defmac AC_PROG_MAKE_SET
1964 @acindex{PROG_MAKE_SET}
1966 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1967 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1968 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1969 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1973 If you use this macro, place a line like this in each @file{Makefile.in}
1974 that runs @code{MAKE} on other directories:
1982 @node Configuration Actions
1983 @section Performing Configuration Actions
1984 @cindex Configuration actions
1986 @file{configure} is designed so that it appears to do everything itself,
1987 but there is actually a hidden slave: @file{config.status}.
1988 @file{configure} is in charge of examining your system, but it is
1989 @file{config.status} that actually takes the proper actions based on the
1990 results of @file{configure}. The most typical task of
1991 @file{config.status} is to @emph{instantiate} files.
1993 This section describes the common behavior of the four standard
1994 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1995 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1996 have this prototype:
1998 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
2001 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2005 where the arguments are:
2009 A blank-or-newline-separated list of tags, which are typically the names of
2010 the files to instantiate.
2012 You are encouraged to use literals as @var{tags}. In particular, you
2016 @dots{} && my_foos="$my_foos fooo"
2017 @dots{} && my_foos="$my_foos foooo"
2018 AC_CONFIG_FOOS([$my_foos])
2022 and use this instead:
2025 @dots{} && AC_CONFIG_FOOS([fooo])
2026 @dots{} && AC_CONFIG_FOOS([foooo])
2029 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2030 special @var{tag} values: they may have the form @samp{@var{output}} or
2031 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2032 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2034 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2035 for example, asks for
2036 the creation of the file @file{Makefile} that contains the expansion of the
2037 output variables in the concatenation of @file{boiler/top.mk} and
2038 @file{boiler/bot.mk}.
2040 The special value @samp{-} might be used to denote the standard output
2041 when used in @var{output}, or the standard input when used in the
2042 @var{inputs}. You most probably don't need to use this in
2043 @file{configure.ac}, but it is convenient when using the command line
2044 interface of @file{./config.status}, see @ref{config.status Invocation},
2047 The @var{inputs} may be absolute or relative file names. In the latter
2048 case they are first looked for in the build tree, and then in the source
2052 Shell commands output literally into @file{config.status}, and
2053 associated with a tag that the user can use to tell @file{config.status}
2054 which the commands to run. The commands are run each time a @var{tag}
2055 request is given to @file{config.status}, typically each time the file
2056 @file{@var{tag}} is created.
2058 The variables set during the execution of @command{configure} are
2059 @emph{not} available here: you first need to set them via the
2060 @var{init-cmds}. Nonetheless the following variables are precomputed:
2064 The name of the top source directory, assuming that the working
2065 directory is the top build directory. This
2066 is what the @command{configure} option @option{--srcdir} sets.
2069 The name of the top source directory, assuming that the working
2070 directory is the current build directory.
2073 @item ac_top_build_prefix
2074 The name of the top build directory, assuming that the working
2075 directory is the current build directory.
2076 It can be empty, or else ends with a slash, so that you may concatenate
2080 The name of the corresponding source directory, assuming that the
2081 working directory is the current build directory.
2085 The @dfn{current} directory refers to the directory (or
2086 pseudo-directory) containing the input part of @var{tags}. For
2090 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2094 with @option{--srcdir=../package} produces the following values:
2097 # Argument of --srcdir
2099 # Reversing deep/dir
2100 ac_top_build_prefix='../../'
2101 # Concatenation of $ac_top_build_prefix and srcdir
2102 ac_top_srcdir='../../../package'
2103 # Concatenation of $ac_top_srcdir and deep/dir
2104 ac_srcdir='../../../package/deep/dir'
2108 independently of @samp{in/in.in}.
2111 Shell commands output @emph{unquoted} near the beginning of
2112 @file{config.status}, and executed each time @file{config.status} runs
2113 (regardless of the tag). Because they are unquoted, for example,
2114 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2115 is typically used by @file{configure} to give @file{config.status} some
2116 variables it needs to run the @var{commands}.
2118 You should be extremely cautious in your variable names: all the
2119 @var{init-cmds} share the same name space and may overwrite each other
2120 in unpredictable ways. Sorry@enddots{}
2123 All these macros can be called multiple times, with different
2124 @var{tag} values, of course!
2127 @node Configuration Files
2128 @section Creating Configuration Files
2129 @cindex Creating configuration files
2130 @cindex Configuration file creation
2132 Be sure to read the previous section, @ref{Configuration Actions}.
2134 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2135 @acindex{CONFIG_FILES}
2136 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2137 file (by default @file{@var{file}.in}), substituting the output variable
2139 @c Before we used to have this feature, which was later rejected
2140 @c because it complicates the writing of makefiles:
2141 @c If the file would be unchanged, it is left untouched, to preserve
2143 This macro is one of the instantiating macros; see @ref{Configuration
2144 Actions}. @xref{Makefile Substitutions}, for more information on using
2145 output variables. @xref{Setting Output Variables}, for more information
2146 on creating them. This macro creates the directory that the file is in
2147 if it doesn't exist. Usually, makefiles are created this way,
2148 but other files, such as @file{.gdbinit}, can be specified as well.
2150 Typical calls to @code{AC_CONFIG_FILES} look like this:
2153 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2154 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2157 You can override an input file name by appending to @var{file} a
2158 colon-separated list of input files. Examples:
2161 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2162 [lib/Makefile:boiler/lib.mk])
2166 Doing this allows you to keep your file names acceptable to
2167 @acronym{DOS} variants, or
2168 to prepend and/or append boilerplate to the file.
2173 @node Makefile Substitutions
2174 @section Substitutions in Makefiles
2175 @cindex Substitutions in makefiles
2176 @cindex Makefile substitutions
2178 Each subdirectory in a distribution that contains something to be
2179 compiled or installed should come with a file @file{Makefile.in}, from
2180 which @command{configure} creates a file @file{Makefile} in that directory.
2181 To create @file{Makefile}, @command{configure} performs a simple variable
2182 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2183 @file{Makefile.in} with the value that @command{configure} has determined
2184 for that variable. Variables that are substituted into output files in
2185 this way are called @dfn{output variables}. They are ordinary shell
2186 variables that are set in @command{configure}. To make @command{configure}
2187 substitute a particular variable into the output files, the macro
2188 @code{AC_SUBST} must be called with that variable name as an argument.
2189 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2190 left unchanged. @xref{Setting Output Variables}, for more information
2191 on creating output variables with @code{AC_SUBST}.
2193 A software package that uses a @command{configure} script should be
2194 distributed with a file @file{Makefile.in}, but no makefile; that
2195 way, the user has to properly configure the package for the local system
2196 before compiling it.
2198 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2199 @acronym{GNU} Coding Standards}, for more information on what to put in
2203 * Preset Output Variables:: Output variables that are always set
2204 * Installation Directory Variables:: Other preset output variables
2205 * Changed Directory Variables:: Warnings about @file{datarootdir}
2206 * Build Directories:: Supporting multiple concurrent compiles
2207 * Automatic Remaking:: Makefile rules for configuring
2210 @node Preset Output Variables
2211 @subsection Preset Output Variables
2212 @cindex Output variables
2214 Some output variables are preset by the Autoconf macros. Some of the
2215 Autoconf macros set additional output variables, which are mentioned in
2216 the descriptions for those macros. @xref{Output Variable Index}, for a
2217 complete list of output variables. @xref{Installation Directory
2218 Variables}, for the list of the preset ones related to installation
2219 directories. Below are listed the other preset ones. They all are
2220 precious variables (@pxref{Setting Output Variables},
2223 @c Just say no to ASCII sorting! We're humans, not computers.
2224 @c These variables are listed as they would be in a dictionary:
2231 Debugging and optimization options for the C compiler. If it is not set
2232 in the environment when @command{configure} runs, the default value is set
2233 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2234 uses this variable when compiling or linking programs to test for C features.
2236 If a compiler option affects only the behavior of the preprocessor
2237 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2238 instead. If it affects only the linker (e.g., @option{-L
2239 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2240 affects only the compiler proper, @code{CFLAGS} is the natural home for
2241 it. If an option affects multiple phases of the compiler, though,
2242 matters get tricky. One approach to put such options directly into
2243 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2244 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2248 @defvar configure_input
2249 @ovindex configure_input
2250 A comment saying that the file was generated automatically by
2251 @command{configure} and giving the name of the input file.
2252 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2253 of every makefile it creates. For other files, you should
2254 reference this variable in a comment at the top of each input file. For
2255 example, an input shell script should begin like this:
2259 # @@configure_input@@
2263 The presence of that line also reminds people editing the file that it
2264 needs to be processed by @command{configure} in order to be used.
2269 Preprocessor options for the C, C++, and Objective C preprocessors and
2271 it is not set in the environment when @command{configure} runs, the default
2272 value is empty. @command{configure} uses this variable when preprocessing
2273 or compiling programs to test for C, C++, and Objective C features.
2275 This variable's contents should contain options like @option{-I},
2276 @option{-D}, and @option{-U} that affect only the behavior of the
2277 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2278 can do if an option affects other phases of the compiler as well.
2280 Currently, @command{configure} always links as part of a single
2281 invocation of the compiler that also preprocesses and compiles, so it
2282 uses this variable also when linking programs. However, it is unwise to
2283 depend on this behavior because the @acronym{GNU} coding standards do
2284 not require it and many packages do not use @code{CPPFLAGS} when linking
2287 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2293 Debugging and optimization options for the C++ compiler. It acts like
2294 @code{CFLAGS}, but for C++ instead of C.
2299 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2300 is called, @command{configure} replaces @samp{@@DEFS@@} with
2301 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2302 variable is not defined while @command{configure} is performing its tests,
2303 only when creating the output files. @xref{Setting Output Variables}, for
2304 how to check the results of previous tests.
2313 How does one suppress the trailing newline from @command{echo} for
2314 question-answer message pairs? These variables provide a way:
2317 echo $ECHO_N "And the winner is... $ECHO_C"
2319 echo "$@{ECHO_T@}dead."
2323 Some old and uncommon @command{echo} implementations offer no means to
2324 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2330 Debugging and optimization options for the Erlang compiler. If it is not set
2331 in the environment when @command{configure} runs, the default value is empty.
2332 @command{configure} uses this variable when compiling
2333 programs to test for Erlang features.
2338 Debugging and optimization options for the Fortran compiler. If it
2339 is not set in the environment when @command{configure} runs, the default
2340 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2341 @command{configure} uses this variable when compiling or linking
2342 programs to test for Fortran features.
2347 Debugging and optimization options for the Fortran 77 compiler. If it
2348 is not set in the environment when @command{configure} runs, the default
2349 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2350 @command{configure} uses this variable when compiling or linking
2351 programs to test for Fortran 77 features.
2356 Options for the linker. If it is not set
2357 in the environment when @command{configure} runs, the default value is empty.
2358 @command{configure} uses this variable when linking programs to test for
2359 C, C++, Objective C, and Fortran features.
2361 This variable's contents should contain options like @option{-s} and
2362 @option{-L} that affect only the behavior of the linker. Please see the
2363 explanation of @code{CFLAGS} for what you can do if an option also
2364 affects other phases of the compiler.
2366 Don't use this variable to pass library names
2367 (@option{-l}) to the linker; use @code{LIBS} instead.
2372 @option{-l} options to pass to the linker. The default value is empty,
2373 but some Autoconf macros may prepend extra libraries to this variable if
2374 those libraries are found and provide necessary functions, see
2375 @ref{Libraries}. @command{configure} uses this variable when linking
2376 programs to test for C, C++, and Fortran features.
2381 Debugging and optimization options for the Objective C compiler. It
2382 acts like @code{CFLAGS}, but for Objective C instead of C.
2387 Rigorously equal to @samp{.}. Added for symmetry only.
2390 @defvar abs_builddir
2391 @ovindex abs_builddir
2392 Absolute name of @code{builddir}.
2395 @defvar top_builddir
2396 @ovindex top_builddir
2397 The relative name of the top level of the current build tree. In the
2398 top-level directory, this is the same as @code{builddir}.
2401 @defvar abs_top_builddir
2402 @ovindex abs_top_builddir
2403 Absolute name of @code{top_builddir}.
2408 The name of the directory that contains the source code for
2414 Absolute name of @code{srcdir}.
2419 The name of the top-level source code directory for the
2420 package. In the top-level directory, this is the same as @code{srcdir}.
2423 @defvar abs_top_srcdir
2424 @ovindex abs_top_srcdir
2425 Absolute name of @code{top_srcdir}.
2428 @node Installation Directory Variables
2429 @subsection Installation Directory Variables
2430 @cindex Installation directories
2431 @cindex Directories, installation
2433 The following variables specify the directories for
2434 package installation, see @ref{Directory Variables, , Variables for
2435 Installation Directories, standards, The @acronym{GNU} Coding
2436 Standards}, for more information. See the end of this section for
2437 details on when and how to use these variables.
2441 The directory for installing executables that users run.
2446 The directory for installing idiosyncratic read-only
2447 architecture-independent data.
2451 @ovindex datarootdir
2452 The root of the directory tree for read-only architecture-independent
2458 The directory for installing documentation files (other than Info and
2464 The directory for installing documentation files in DVI format.
2468 @ovindex exec_prefix
2469 The installation prefix for architecture-dependent files. By default
2470 it's the same as @var{prefix}. You should avoid installing anything
2471 directly to @var{exec_prefix}. However, the default value for
2472 directories containing architecture-dependent files should be relative
2473 to @var{exec_prefix}.
2478 The directory for installing HTML documentation.
2483 The directory for installing C header files.
2488 The directory for installing documentation in Info format.
2493 The directory for installing object code libraries.
2498 The directory for installing executables that other programs run.
2503 The directory for installing locale-dependent but
2504 architecture-independent data, such as message catalogs. This directory
2505 usually has a subdirectory per locale.
2508 @defvar localstatedir
2509 @ovindex localstatedir
2510 The directory for installing modifiable single-machine data.
2515 The top-level directory for installing documentation in man format.
2518 @defvar oldincludedir
2519 @ovindex oldincludedir
2520 The directory for installing C header files for non-@acronym{GCC} compilers.
2525 The directory for installing PDF documentation.
2530 The common installation prefix for all files. If @var{exec_prefix}
2531 is defined to a different value, @var{prefix} is used only for
2532 architecture-independent files.
2537 The directory for installing PostScript documentation.
2542 The directory for installing executables that system
2546 @defvar sharedstatedir
2547 @ovindex sharedstatedir
2548 The directory for installing modifiable architecture-independent data.
2553 The directory for installing read-only single-machine data.
2557 Most of these variables have values that rely on @code{prefix} or
2558 @code{exec_prefix}. It is deliberate that the directory output
2559 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2560 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2561 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2563 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2568 she can still specify a different prefix from the one specified to
2569 @command{configure}, in which case, if needed, the package should hard
2570 code dependencies corresponding to the make-specified prefix.
2573 she can specify a different installation location, in which case the
2574 package @emph{must} still depend on the location which was compiled in
2575 (i.e., never recompile when @samp{make install} is run). This is an
2576 extremely important feature, as many people may decide to install all
2577 the files of a package grouped together, and then install links from
2578 the final locations to there.
2581 In order to support these features, it is essential that
2582 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2583 depend upon the current value of @code{prefix}.
2585 A corollary is that you should not use these variables except in
2586 makefiles. For instance, instead of trying to evaluate @code{datadir}
2587 in @file{configure} and hard-coding it in makefiles using
2588 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2590 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2591 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2593 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2594 @code{datadir} and friends in your shell scripts and other files; instead,
2595 let @command{make} manage their replacement. For instance Autoconf
2596 ships templates of its shell scripts ending with @samp{.in}, and uses a
2597 makefile snippet similar to the following to build scripts like
2598 @command{autoheader} and @command{autom4te}:
2603 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2604 -e 's|@@prefix[@@]|$(prefix)|g'
2608 autoheader autom4te: Makefile
2610 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2617 autoheader: $(srcdir)/autoheader.in
2618 autom4te: $(srcdir)/autom4te.in
2622 Some details are noteworthy:
2625 @item @samp{@@datadir[@@]}
2626 The brackets prevent @command{configure} from replacing
2627 @samp{@@datadir@@} in the Sed expression itself.
2628 Brackets are preferable to a backslash here, since
2629 Posix says @samp{\@@} is not portable.
2631 @item @samp{$(pkgdatadir)}
2632 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2636 Don't use @samp{/} in the Sed expressions that replace file names since
2638 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2639 Use a shell metacharacter instead, such as @samp{|}.
2641 @item special characters
2642 File names, file name components, and the value of @code{VPATH} should
2643 not contain shell metacharacters or white
2644 space. @xref{Special Chars in Variables}.
2646 @item dependency on @file{Makefile}
2647 Since @code{edit} uses values that depend on the configuration specific
2648 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2649 the output depends on @file{Makefile}, not @file{configure.ac}.
2652 The main rule is generic, and uses @samp{$@@} extensively to
2653 avoid the need for multiple copies of the rule.
2655 @item Separated dependencies and single suffix rules
2656 You can't use them! The above snippet cannot be (portably) rewritten
2660 autoconf autoheader: Makefile
2670 @xref{Single Suffix Rules}, for details.
2672 @item @samp{$(srcdir)}
2673 Be sure to specify the name of the source directory,
2674 otherwise the package won't support separated builds.
2677 For the more specific installation of Erlang libraries, the following variables
2680 @defvar ERLANG_INSTALL_LIB_DIR
2681 @ovindex ERLANG_INSTALL_LIB_DIR
2682 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2683 The common parent directory of Erlang library installation directories.
2684 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2685 macro in @file{configure.ac}.
2688 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2689 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2690 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2691 The installation directory for Erlang library @var{library}.
2692 This variable is set by calling the
2693 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2694 macro in @file{configure.ac}.
2697 @xref{Erlang Libraries}, for details.
2700 @node Changed Directory Variables
2701 @subsection Changed Directory Variables
2702 @cindex @file{datarootdir}
2704 In Autoconf 2.60, the set of directory variables has changed, and the
2705 defaults of some variables have been adjusted
2706 (@pxref{Installation Directory Variables}) to changes in the
2707 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2708 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2709 upgrading from an earlier Autoconf version, you may need to adjust your files
2710 to ensure that the directory variables are substituted correctly
2711 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2712 in place. For example, in a @file{Makefile.in}, adding
2715 datarootdir = @@datarootdir@@
2719 is usually sufficient. If you use Automake to create @file{Makefile.in},
2720 it will add this for you.
2722 To help with the transition, Autoconf warns about files that seem to use
2723 @code{datarootdir} without defining it. In some cases, it then expands
2724 the value of @code{$datarootdir} in substitutions of the directory
2725 variables. The following example shows such a warning:
2728 $ @kbd{cat configure.ac}
2730 AC_CONFIG_FILES([Makefile])
2732 $ @kbd{cat Makefile.in}
2734 datadir = @@datadir@@
2737 configure: creating ./config.status
2738 config.status: creating Makefile
2739 config.status: WARNING:
2740 Makefile.in seems to ignore the --datarootdir setting
2741 $ @kbd{cat Makefile}
2743 datadir = $@{prefix@}/share
2746 Usually one can easily change the file to accommodate both older and newer
2750 $ @kbd{cat Makefile.in}
2752 datarootdir = @@datarootdir@@
2753 datadir = @@datadir@@
2755 configure: creating ./config.status
2756 config.status: creating Makefile
2757 $ @kbd{cat Makefile}
2759 datarootdir = $@{prefix@}/share
2760 datadir = $@{datarootdir@}
2763 @acindex{DATAROOTDIR_CHECKED}
2764 In some cases, however, the checks may not be able to detect that a suitable
2765 initialization of @code{datarootdir} is in place, or they may fail to detect
2766 that such an initialization is necessary in the output file. If, after
2767 auditing your package, there are still spurious @file{configure} warnings about
2768 @code{datarootdir}, you may add the line
2771 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2775 to your @file{configure.ac} to disable the warnings. This is an exception
2776 to the usual rule that you should not define a macro whose name begins with
2777 @code{AC_} (@pxref{Macro Names}).
2781 @node Build Directories
2782 @subsection Build Directories
2783 @cindex Build directories
2784 @cindex Directories, build
2786 You can support compiling a software package for several architectures
2787 simultaneously from the same copy of the source code. The object files
2788 for each architecture are kept in their own directory.
2790 To support doing this, @command{make} uses the @code{VPATH} variable to
2791 find the files that are in the source directory. @acronym{GNU} Make
2792 can do this. Most other recent @command{make} programs can do this as
2793 well, though they may have difficulties and it is often simpler to
2794 recommend @acronym{GNU} @command{make} (@pxref{VPATH and Make}). Older
2795 @command{make} programs do not support @code{VPATH}; when using them, the
2796 source code must be in the same directory as the object files.
2798 To support @code{VPATH}, each @file{Makefile.in} should contain two
2799 lines that look like:
2806 Do not set @code{VPATH} to the value of another variable, for example
2807 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2808 variable substitutions on the value of @code{VPATH}.
2810 @command{configure} substitutes the correct value for @code{srcdir} when
2811 it produces @file{Makefile}.
2813 Do not use the @code{make} variable @code{$<}, which expands to the
2814 file name of the file in the source directory (found with @code{VPATH}),
2815 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2816 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2817 versions of @command{make} do not set @code{$<} in explicit rules; they
2818 expand it to an empty value.
2820 Instead, Make command lines should always refer to source
2821 files by prefixing them with @samp{$(srcdir)/}. For example:
2824 time.info: time.texinfo
2825 $(MAKEINFO) '$(srcdir)/time.texinfo'
2828 @node Automatic Remaking
2829 @subsection Automatic Remaking
2830 @cindex Automatic remaking
2831 @cindex Remaking automatically
2833 You can put rules like the following in the top-level @file{Makefile.in}
2834 for a package to automatically update the configuration information when
2835 you change the configuration files. This example includes all of the
2836 optional files, such as @file{aclocal.m4} and those related to
2837 configuration header files. Omit from the @file{Makefile.in} rules for
2838 any of these files that your package does not use.
2840 The @samp{$(srcdir)/} prefix is included because of limitations in the
2841 @code{VPATH} mechanism.
2843 The @file{stamp-} files are necessary because the timestamps of
2844 @file{config.h.in} and @file{config.h} are not changed if remaking
2845 them does not change their contents. This feature avoids unnecessary
2846 recompilation. You should include the file @file{stamp-h.in} your
2847 package's distribution, so that @command{make} considers
2848 @file{config.h.in} up to date. Don't use @command{touch}
2849 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2850 @command{date} would cause needless differences, hence @acronym{CVS}
2855 $(srcdir)/configure: configure.ac aclocal.m4
2856 cd '$(srcdir)' && autoconf
2858 # autoheader might not change config.h.in, so touch a stamp file.
2859 $(srcdir)/config.h.in: stamp-h.in
2860 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2861 cd '$(srcdir)' && autoheader
2862 echo timestamp > '$(srcdir)/stamp-h.in'
2865 stamp-h: config.h.in config.status
2868 Makefile: Makefile.in config.status
2871 config.status: configure
2872 ./config.status --recheck
2877 (Be careful if you copy these lines directly into your makefile, as you
2878 need to convert the indented lines to start with the tab character.)
2880 In addition, you should use
2883 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2887 so @file{config.status} ensures that @file{config.h} is considered up to
2888 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2890 @xref{config.status Invocation}, for more examples of handling
2891 configuration-related dependencies.
2893 @node Configuration Headers
2894 @section Configuration Header Files
2895 @cindex Configuration Header
2896 @cindex @file{config.h}
2898 When a package contains more than a few tests that define C preprocessor
2899 symbols, the command lines to pass @option{-D} options to the compiler
2900 can get quite long. This causes two problems. One is that the
2901 @command{make} output is hard to visually scan for errors. More
2902 seriously, the command lines can exceed the length limits of some
2903 operating systems. As an alternative to passing @option{-D} options to
2904 the compiler, @command{configure} scripts can create a C header file
2905 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2906 macro selects this kind of output. Though it can be called anywhere
2907 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2908 it right after @code{AC_INIT}.
2910 The package should @samp{#include} the configuration header file before
2911 any other header files, to prevent inconsistencies in declarations (for
2912 example, if it redefines @code{const}).
2914 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2915 option (or @option{-I..}; whichever directory contains @file{config.h}).
2916 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2917 the directory of the currently read file, i.e., the source directory, not
2918 the build directory.
2920 With the appropriate @option{-I} option, you can use
2921 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2922 because in the rare case when the source directory contains another
2923 @file{config.h}, the build directory should be searched first.
2926 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2927 @acindex{CONFIG_HEADERS}
2928 @cvindex HAVE_CONFIG_H
2929 This macro is one of the instantiating macros; see @ref{Configuration
2930 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2931 blank-or-newline-separated list @var{header} containing C preprocessor
2932 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2933 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2934 The usual name for @var{header} is @file{config.h}.
2936 If @var{header} already exists and its contents are identical to what
2937 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2938 making some changes in the configuration without needlessly causing
2939 object files that depend on the header file to be recompiled.
2941 Usually the input file is named @file{@var{header}.in}; however, you can
2942 override the input file name by appending to @var{header} a
2943 colon-separated list of input files. For example, you might need to make
2944 the input file name acceptable to @acronym{DOS} variants:
2947 AC_CONFIG_HEADERS([config.h:config.hin])
2954 This macro is defined as the name of the first declared config header
2955 and undefined if no config headers have been declared up to this point.
2956 A third-party macro may, for example, require use of a config header
2957 without invoking AC_CONFIG_HEADERS twice, like this:
2960 AC_CONFIG_COMMANDS_PRE(
2961 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2966 @xref{Configuration Actions}, for more details on @var{header}.
2969 * Header Templates:: Input for the configuration headers
2970 * autoheader Invocation:: How to create configuration templates
2971 * Autoheader Macros:: How to specify CPP templates
2974 @node Header Templates
2975 @subsection Configuration Header Templates
2976 @cindex Configuration Header Template
2977 @cindex Header templates
2978 @cindex @file{config.h.in}
2980 Your distribution should contain a template file that looks as you want
2981 the final header file to look, including comments, with @code{#undef}
2982 statements which are used as hooks. For example, suppose your
2983 @file{configure.ac} makes these calls:
2986 AC_CONFIG_HEADERS([conf.h])
2987 AC_CHECK_HEADERS([unistd.h])
2991 Then you could have code like the following in @file{conf.h.in}. On
2992 systems that have @file{unistd.h}, @command{configure} defines
2993 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
2994 commented out (in case the system predefines that symbol).
2998 /* Define as 1 if you have unistd.h. */
2999 #undef HAVE_UNISTD_H
3003 Pay attention that @samp{#undef} is in the first column, and there is
3004 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3005 then decode the configuration header using the preprocessor directives:
3011 #ifdef HAVE_UNISTD_H
3012 # include <unistd.h>
3014 /* We are in trouble. */
3019 The use of old form templates, with @samp{#define} instead of
3020 @samp{#undef} is strongly discouraged. Similarly with old templates
3021 with comments on the same line as the @samp{#undef}. Anyway, putting
3022 comments in preprocessor macros has never been a good idea.
3024 Since it is a tedious task to keep a template header up to date, you may
3025 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3028 @node autoheader Invocation
3029 @subsection Using @command{autoheader} to Create @file{config.h.in}
3030 @cindex @command{autoheader}
3032 The @command{autoheader} program can create a template file of C
3033 @samp{#define} statements for @command{configure} to use.
3034 It searches for the first invocation of @code{AC_CONFIG_HEADERS} in
3035 @file{configure} sources to determine the name of the template.
3036 (If the first call of @code{AC_CONFIG_HEADERS} specifies more than one
3037 input file name, @command{autoheader} uses the first one.)
3039 It is recommended that only one input file is used. If you want to append
3040 a boilerplate code, it is preferable to use
3041 @samp{AH_BOTTOM([#include <conf_post.h>])}.
3042 File @file{conf_post.h} is not processed during the configuration then,
3043 which make things clearer. Analogically, @code{AH_TOP} can be used to
3044 prepend a boilerplate code.
3046 In order to do its job, @command{autoheader} needs you to document all
3047 of the symbols that you might use. Typically this is done via an
3048 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3049 is a literal symbol and whose third argument describes the symbol
3050 (@pxref{Defining Symbols}). Alternatively, you can use
3051 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3052 suitable input file for a subsequent configuration header file.
3053 Symbols defined by Autoconf's builtin tests are already documented properly;
3054 you need to document only those that you
3057 You might wonder why @command{autoheader} is needed: after all, why
3058 would @command{configure} need to ``patch'' a @file{config.h.in} to
3059 produce a @file{config.h} instead of just creating @file{config.h} from
3060 scratch? Well, when everything rocks, the answer is just that we are
3061 wasting our time maintaining @command{autoheader}: generating
3062 @file{config.h} directly is all that is needed. When things go wrong,
3063 however, you'll be thankful for the existence of @command{autoheader}.
3065 The fact that the symbols are documented is important in order to
3066 @emph{check} that @file{config.h} makes sense. The fact that there is a
3067 well-defined list of symbols that should be defined (or not) is
3068 also important for people who are porting packages to environments where
3069 @command{configure} cannot be run: they just have to @emph{fill in the
3072 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3074 If you give @command{autoheader} an argument, it uses that file instead
3075 of @file{configure.ac} and writes the header file to the standard output
3076 instead of to @file{config.h.in}. If you give @command{autoheader} an
3077 argument of @option{-}, it reads the standard input instead of
3078 @file{configure.ac} and writes the header file to the standard output.
3080 @command{autoheader} accepts the following options:
3085 Print a summary of the command line options and exit.
3089 Print the version number of Autoconf and exit.
3093 Report processing steps.
3097 Don't remove the temporary files.
3101 Remake the template file even if newer than its input files.
3103 @item --include=@var{dir}
3105 Append @var{dir} to the include path. Multiple invocations accumulate.
3107 @item --prepend-include=@var{dir}
3109 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3111 @item --warnings=@var{category}
3112 @itemx -W @var{category}
3114 Report the warnings related to @var{category} (which can actually be a
3115 comma separated list). Current categories include:
3119 report the uses of obsolete constructs
3122 report all the warnings
3128 treats warnings as errors
3130 @item no-@var{category}
3131 disable warnings falling into @var{category}
3138 @node Autoheader Macros
3139 @subsection Autoheader Macros
3140 @cindex Autoheader macros
3142 @command{autoheader} scans @file{configure.ac} and figures out which C
3143 preprocessor symbols it might define. It knows how to generate
3144 templates for symbols defined by @code{AC_CHECK_HEADERS},
3145 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3146 symbol, you must define a template for it. If there are missing
3147 templates, @command{autoheader} fails with an error message.
3149 The template for a @var{symbol} is created
3150 by @command{autoheader} from
3151 the @var{description} argument to an @code{AC_DEFINE};
3152 see @ref{Defining Symbols}.
3154 For special needs, you can use the following macros.
3157 @defmac AH_TEMPLATE (@var{key}, @var{description})
3159 Tell @command{autoheader} to generate a template for @var{key}. This macro
3160 generates standard templates just like @code{AC_DEFINE} when a
3161 @var{description} is given.
3166 AH_TEMPLATE([CRAY_STACKSEG_END],
3167 [Define to one of _getb67, GETB67, getb67
3168 for Cray-2 and Cray-YMP systems. This
3169 function is required for alloca.c support
3174 generates the following template, with the description properly
3178 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3179 Cray-YMP systems. This function is required for alloca.c
3180 support on those systems. */
3181 #undef CRAY_STACKSEG_END
3186 @defmac AH_VERBATIM (@var{key}, @var{template})
3188 Tell @command{autoheader} to include the @var{template} as-is in the header
3189 template file. This @var{template} is associated with the @var{key},
3190 which is used to sort all the different templates and guarantee their
3191 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3195 @defmac AH_TOP (@var{text})
3197 Include @var{text} at the top of the header template file.
3201 @defmac AH_BOTTOM (@var{text})
3203 Include @var{text} at the bottom of the header template file.
3207 Please note that @var{text} gets included ``verbatim'' to the template file,
3208 not to the resulting config header, so it can easily get mangled when the
3209 template is processed. There is rarely a need for something other than
3212 AH_BOTTOM([#include <custom.h>])
3217 @node Configuration Commands
3218 @section Running Arbitrary Configuration Commands
3219 @cindex Configuration commands
3220 @cindex Commands for configuration
3222 You can execute arbitrary commands before, during, and after
3223 @file{config.status} is run. The three following macros accumulate the
3224 commands to run when they are called multiple times.
3225 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3226 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3228 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3229 @acindex{CONFIG_COMMANDS}
3230 Specify additional shell commands to run at the end of
3231 @file{config.status}, and shell commands to initialize any variables
3232 from @command{configure}. Associate the commands with @var{tag}.
3233 Since typically the @var{cmds} create a file, @var{tag} should
3234 naturally be the name of that file. If needed, the directory hosting
3235 @var{tag} is created. This macro is one of the instantiating macros;
3236 see @ref{Configuration Actions}.
3238 Here is an unrealistic example:
3241 AC_CONFIG_COMMANDS([fubar],
3242 [echo this is extra $fubar, and so on.],
3246 Here is a better one:
3248 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3252 The following two macros look similar, but in fact they are not of the same
3253 breed: they are executed directly by @file{configure}, so you cannot use
3254 @file{config.status} to rerun them.
3256 @c Yet it is good to leave them here. The user sees them together and
3257 @c decides which best fits their needs.
3259 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3260 @acindex{CONFIG_COMMANDS_PRE}
3261 Execute the @var{cmds} right before creating @file{config.status}.
3263 This macro presents the last opportunity to call @code{AC_SUBST},
3264 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3267 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3268 @acindex{CONFIG_COMMANDS_POST}
3269 Execute the @var{cmds} right after creating @file{config.status}.
3275 @node Configuration Links
3276 @section Creating Configuration Links
3277 @cindex Configuration links
3278 @cindex Links for configuration
3280 You may find it convenient to create links whose destinations depend upon
3281 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3282 creation of relative symbolic links can be delicate when the package is
3283 built in a directory different from the source directory.
3285 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3286 @acindex{CONFIG_LINKS}
3288 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3289 the corresponding link name @var{dest}. Makes a symbolic link if
3290 possible, otherwise a hard link if possible, otherwise a copy. The
3291 @var{dest} and @var{source} names should be relative to the top level
3292 source or build directory. This macro is one of the instantiating
3293 macros; see @ref{Configuration Actions}.
3295 For example, this call:
3298 AC_CONFIG_LINKS([host.h:config/$machine.h
3299 object.h:config/$obj_format.h])
3303 creates in the current directory @file{host.h} as a link to
3304 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3305 link to @file{@var{srcdir}/config/$obj_format.h}.
3307 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3308 impossible for @samp{config.status} to guess the links to establish.
3312 ./config.status host.h object.h
3315 to create the links.
3320 @node Subdirectories
3321 @section Configuring Other Packages in Subdirectories
3322 @cindex Configure subdirectories
3323 @cindex Subdirectory configure
3325 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3326 makefiles in subdirectories. However, @command{configure} scripts
3327 that control more than one independent package can use
3328 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3329 packages in subdirectories.
3331 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3332 @acindex{CONFIG_SUBDIRS}
3334 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3335 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3336 be a literal, i.e., please do not use:
3339 if test "$package_foo_enabled" = yes; then
3340 $my_subdirs="$my_subdirs foo"
3342 AC_CONFIG_SUBDIRS([$my_subdirs])
3346 because this prevents @samp{./configure --help=recursive} from
3347 displaying the options of the package @code{foo}. Instead, you should
3351 if test "$package_foo_enabled" = yes; then
3352 AC_CONFIG_SUBDIRS([foo])
3356 If a given @var{dir} is not found, an error is reported: if the
3357 subdirectory is optional, write:
3360 if test -d "$srcdir/foo"; then
3361 AC_CONFIG_SUBDIRS([foo])
3365 @c NB: Yes, below we mean configure.in, not configure.ac.
3366 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3367 of @command{configure}. This is for packages that might use a
3368 non-Autoconf script @command{Configure}, which can't be called through a
3369 wrapper @command{configure} since it would be the same file on
3370 case-insensitive file systems. Likewise, if a @var{dir} contains
3371 @file{configure.in} but no @command{configure}, the Cygnus
3372 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3374 The subdirectory @command{configure} scripts are given the same command
3375 line options that were given to this @command{configure} script, with minor
3376 changes if needed, which include:
3380 adjusting a relative name for the cache file;
3383 adjusting a relative name for the source directory;
3386 propagating the current value of @code{$prefix}, including if it was
3387 defaulted, and if the default values of the top level and of the subdirectory
3388 @file{configure} differ.
3391 This macro also sets the output variable @code{subdirs} to the list of
3392 directories @samp{@var{dir} @dots{}}. Make rules can use
3393 this variable to determine which subdirectories to recurse into.
3395 This macro may be called multiple times.
3398 @node Default Prefix
3399 @section Default Prefix
3400 @cindex Install prefix
3401 @cindex Prefix for install
3403 By default, @command{configure} sets the prefix for files it installs to
3404 @file{/usr/local}. The user of @command{configure} can select a different
3405 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3406 There are two ways to change the default: when creating
3407 @command{configure}, and when running it.
3409 Some software packages might want to install in a directory other than
3410 @file{/usr/local} by default. To accomplish that, use the
3411 @code{AC_PREFIX_DEFAULT} macro.
3413 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3414 @acindex{PREFIX_DEFAULT}
3415 Set the default installation prefix to @var{prefix} instead of
3419 It may be convenient for users to have @command{configure} guess the
3420 installation prefix from the location of a related program that they
3421 have already installed. If you wish to do that, you can call
3422 @code{AC_PREFIX_PROGRAM}.
3424 @defmac AC_PREFIX_PROGRAM (@var{program})
3425 @acindex{PREFIX_PROGRAM}
3426 If the user did not specify an installation prefix (using the
3427 @option{--prefix} option), guess a value for it by looking for
3428 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3429 is found, set the prefix to the parent of the directory containing
3430 @var{program}, else default the prefix as described above
3431 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3432 @var{program} is @code{gcc} and the @env{PATH} contains
3433 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3438 @c ======================================================== Existing tests
3440 @node Existing Tests
3441 @chapter Existing Tests
3443 These macros test for particular system features that packages might
3444 need or want to use. If you need to test for a kind of feature that
3445 none of these macros check for, you can probably do it by calling
3446 primitive test macros with appropriate arguments (@pxref{Writing
3449 These tests print messages telling the user which feature they're
3450 checking for, and what they find. They cache their results for future
3451 @command{configure} runs (@pxref{Caching Results}).
3453 Some of these macros set output variables. @xref{Makefile
3454 Substitutions}, for how to get their values. The phrase ``define
3455 @var{name}'' is used below as a shorthand to mean ``define the C
3456 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3457 Symbols}, for how to get those symbol definitions into your program.
3460 * Common Behavior:: Macros' standard schemes
3461 * Alternative Programs:: Selecting between alternative programs
3462 * Files:: Checking for the existence of files
3463 * Libraries:: Library archives that might be missing
3464 * Library Functions:: C library functions that might be missing
3465 * Header Files:: Header files that might be missing
3466 * Declarations:: Declarations that may be missing
3467 * Structures:: Structures or members that might be missing
3468 * Types:: Types that might be missing
3469 * Compilers and Preprocessors:: Checking for compiling programs
3470 * System Services:: Operating system services
3471 * Posix Variants:: Special kludges for specific Posix variants
3472 * Erlang Libraries:: Checking for the existence of Erlang libraries
3475 @node Common Behavior
3476 @section Common Behavior
3477 @cindex Common autoconf behavior
3479 Much effort has been expended to make Autoconf easy to learn. The most
3480 obvious way to reach this goal is simply to enforce standard interfaces
3481 and behaviors, avoiding exceptions as much as possible. Because of
3482 history and inertia, unfortunately, there are still too many exceptions
3483 in Autoconf; nevertheless, this section describes some of the common
3487 * Standard Symbols:: Symbols defined by the macros
3488 * Default Includes:: Includes used by the generic macros
3491 @node Standard Symbols
3492 @subsection Standard Symbols
3493 @cindex Standard symbols
3495 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3496 their test transform their @var{argument} values to a standard alphabet.
3497 First, @var{argument} is converted to upper case and any asterisks
3498 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3499 that are not alphanumeric are converted to underscores.
3504 AC_CHECK_TYPES([struct $Expensive*])
3508 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3512 @node Default Includes
3513 @subsection Default Includes
3514 @cindex Default includes
3515 @cindex Includes, default
3517 Several tests depend upon a set of header files. Since these headers
3518 are not universally available, tests actually have to provide a set of
3519 protected includes, such as:
3523 #ifdef TIME_WITH_SYS_TIME
3524 # include <sys/time.h>
3527 # ifdef HAVE_SYS_TIME_H
3528 # include <sys/time.h>
3537 Unless you know exactly what you are doing, you should avoid using
3538 unconditional includes, and check the existence of the headers you
3539 include beforehand (@pxref{Header Files}).
3541 Most generic macros use the following macro to provide the default set
3544 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3545 @acindex{INCLUDES_DEFAULT}
3546 Expand to @var{include-directives} if defined, otherwise to:
3551 #ifdef HAVE_SYS_TYPES_H
3552 # include <sys/types.h>
3554 #ifdef HAVE_SYS_STAT_H
3555 # include <sys/stat.h>
3558 # include <stdlib.h>
3559 # include <stddef.h>
3561 # ifdef HAVE_STDLIB_H
3562 # include <stdlib.h>
3565 #ifdef HAVE_STRING_H
3566 # if !defined STDC_HEADERS && defined HAVE_MEMORY_H
3567 # include <memory.h>
3569 # include <string.h>
3571 #ifdef HAVE_STRINGS_H
3572 # include <strings.h>
3574 #ifdef HAVE_INTTYPES_H
3575 # include <inttypes.h>
3577 #ifdef HAVE_STDINT_H
3578 # include <stdint.h>
3580 #ifdef HAVE_UNISTD_H
3581 # include <unistd.h>
3586 If the default includes are used, then check for the presence of these
3587 headers and their compatibility, i.e., you don't need to run
3588 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3590 These headers are checked for in the same order as they are included.
3591 For instance, on some systems @file{string.h} and @file{strings.h} both
3592 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3593 @code{HAVE_STRINGS_H}.
3596 @node Alternative Programs
3597 @section Alternative Programs
3598 @cindex Programs, checking
3600 These macros check for the presence or behavior of particular programs.
3601 They are used to choose between several alternative programs and to
3602 decide what to do once one has been chosen. If there is no macro
3603 specifically defined to check for a program you need, and you don't need
3604 to check for any special properties of it, then you can use one of the
3605 general program-check macros.
3608 * Particular Programs:: Special handling to find certain programs
3609 * Generic Programs:: How to find other programs
3612 @node Particular Programs
3613 @subsection Particular Program Checks
3615 These macros check for particular programs---whether they exist, and
3616 in some cases whether they support certain features.
3621 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3622 order, and set output variable @code{AWK} to the first one that is found.
3623 It tries @code{gawk} first because that is reported to be the
3624 best implementation.
3627 @defmac AC_PROG_GREP
3630 Look for the best available @code{grep} or @code{ggrep} that accepts the
3631 longest input lines possible, and that supports multiple @option{-e} options.
3632 Set the output variable @code{GREP} to whatever is chosen.
3633 @xref{Limitations of Usual Tools}, for more information about
3634 portability problems with the @command{grep} command family.
3637 @defmac AC_PROG_EGREP
3638 @acindex{PROG_EGREP}
3640 Check whether @code{$GREP -E} works, or else look for the best available
3641 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3642 Set the output variable @code{EGREP} to whatever is chosen.
3645 @defmac AC_PROG_FGREP
3646 @acindex{PROG_FGREP}
3648 Check whether @code{$GREP -F} works, or else look for the best available
3649 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3650 Set the output variable @code{FGREP} to whatever is chosen.
3653 @defmac AC_PROG_INSTALL
3654 @acindex{PROG_INSTALL}
3656 @ovindex INSTALL_PROGRAM
3657 @ovindex INSTALL_DATA
3658 @ovindex INSTALL_SCRIPT
3659 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3660 @command{install} program, if one is found in the current @env{PATH}.
3661 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3662 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3663 default directories) to determine @var{dir} (@pxref{Output}). Also set
3664 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3665 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3667 @samp{@@INSTALL@@} is special, as its value may vary for different
3668 configuration files.
3670 This macro screens out various instances of @command{install} known not to
3671 work. It prefers to find a C program rather than a shell script, for
3672 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3673 but that name is obsolete because some @command{make} programs have a rule
3674 that creates @file{install} from it if there is no makefile.
3676 Autoconf comes with a copy of @file{install-sh} that you can use. If
3677 you use @code{AC_PROG_INSTALL}, you must include either
3678 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3679 @command{configure} produces an error message saying it can't find
3680 them---even if the system you're on has a good @command{install} program.
3681 This check is a safety measure to prevent you from accidentally leaving
3682 that file out, which would prevent your package from installing on
3683 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3685 If you need to use your own installation program because it has features
3686 not found in standard @command{install} programs, there is no reason to use
3687 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3688 @file{Makefile.in} files.
3691 @defmac AC_PROG_MKDIR_P
3692 @acindex{PROG_MKDIR_P}
3694 Set output variable @code{MKDIR_P} to a program that ensures that for
3695 each argument, a directory named by this argument exists, creating it
3696 and its parent directories if needed, and without race conditions when
3697 two instances of the program attempt to make the same directory at
3698 nearly the same time.
3700 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3701 falls back on invoking @command{install-sh} with the @option{-d} option,
3702 so your package should
3703 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3704 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3705 is vulnerable to race conditions, so if you want to support parallel
3707 different packages into the same directory you need to make sure you
3708 have an up-to-date @file{install-sh}. In particular, be careful about
3709 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3711 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3712 in M4sh}), but it sets an output variable intended for use in other
3713 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3714 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3715 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3716 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3717 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3718 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3719 Finally, @code{AS_MKDIR_P} does not check for race condition
3720 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3722 @samp{@@MKDIR_P@@} is special, as its value may vary for different
3723 configuration files.
3730 @cvindex YYTEXT_POINTER
3731 @ovindex LEX_OUTPUT_ROOT
3732 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3733 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3734 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3737 Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead
3738 of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3739 the base of the file name that the lexer generates; usually
3740 @file{lex.yy}, but sometimes something else. These results vary
3741 according to whether @code{lex} or @code{flex} is being used.
3743 You are encouraged to use Flex in your sources, since it is both more
3744 pleasant to use than plain Lex and the C source it produces is portable.
3745 In order to ensure portability, however, you must either provide a
3746 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3747 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3748 statement in the scanner's source. Once this done, the scanner is
3749 portable (unless @emph{you} felt free to use nonportable constructs) and
3750 does not depend on any library. In this case, and in this case only, it
3751 is suggested that you use this Autoconf snippet:
3755 if test "$LEX" != flex; then
3756 LEX="$SHELL $missing_dir/missing flex"
3757 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3758 AC_SUBST([LEXLIB], [''])
3762 The shell script @command{missing} can be found in the Automake
3765 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3766 (indirectly) this macro twice, which causes an annoying but benign
3767 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3768 of Automake will fix this issue; meanwhile, just ignore this message.
3770 As part of running the test, this macro may delete any file in the
3771 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3774 @defmac AC_PROG_LN_S
3777 If @samp{ln -s} works on the current file system (the operating system
3778 and file system support symbolic links), set the output variable
3779 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3780 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3782 If you make a link in a directory other than the current directory, its
3783 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3784 create links using @samp{$(LN_S)}, either find out which form is used
3785 and adjust the arguments, or always invoke @code{ln} in the directory
3786 where the link is to be created.
3788 In other words, it does not work to do:
3796 (cd /x && $(LN_S) foo bar)
3800 @defmac AC_PROG_RANLIB
3801 @acindex{PROG_RANLIB}
3803 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3804 is found, and otherwise to @samp{:} (do nothing).
3810 Set output variable @code{SED} to a Sed implementation that conforms to
3811 Posix and does not have arbitrary length limits. Report an error if no
3812 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3813 information about portability problems with Sed.
3816 @defmac AC_PROG_YACC
3819 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3820 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3821 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3824 @node Generic Programs
3825 @subsection Generic Program and File Checks
3827 These macros are used to find programs not covered by the ``particular''
3828 test macros. If you need to check the behavior of a program as well as
3829 find out whether it is present, you have to write your own test for it
3830 (@pxref{Writing Tests}). By default, these macros use the environment
3831 variable @env{PATH}. If you need to check for a program that might not
3832 be in the user's @env{PATH}, you can pass a modified path to use
3836 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3837 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3840 You are strongly encouraged to declare the @var{variable} passed to
3841 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3842 @code{AC_ARG_VAR}, for more details.
3844 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3845 @acindex{CHECK_PROG}
3846 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3847 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3848 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3849 absolute file name) even if it is the first found in the search path; in
3850 that case, set @var{variable} using the absolute file name of the
3851 @var{prog-to-check-for} found that is not @var{reject}. If
3852 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3856 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3857 @acindex{CHECK_PROGS}
3858 Check for each program in the blank-separated list
3859 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3860 @var{variable} to the name of that program. Otherwise, continue
3861 checking the next program in the list. If none of the programs in the
3862 list are found, set @var{variable} to @var{value-if-not-found}; if
3863 @var{value-if-not-found} is not specified, the value of @var{variable}
3864 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3867 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3868 @acindex{CHECK_TARGET_TOOL}
3869 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3870 with a prefix of the target type as determined by
3871 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3872 If the tool cannot be found with a prefix, and if the build and target
3873 types are equal, then it is also searched for without a prefix.
3875 As noted in @ref{Specifying Names, , Specifying the system type}, the
3876 target is rarely specified, because most of the time it is the same
3877 as the host: it is the type of system for which any compiler tool in
3878 the package produces code. What this macro looks for is,
3879 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3880 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3881 uses to produce objects, archives or executables}.
3884 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3885 @acindex{CHECK_TOOL}
3886 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3887 with a prefix of the host type as determined by
3888 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3889 For example, if the user runs @samp{configure --host=i386-gnu}, then
3892 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3895 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3896 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3897 @env{PATH}, or to @samp{:} if neither program exists.
3899 In the future, when cross-compiling this macro will @emph{only}
3900 accept program names that are prefixed with the host type.
3901 For more information, see @ref{Specifying Names, , Specifying the
3905 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3906 @acindex{CHECK_TARGET_TOOLS}
3907 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3908 @var{progs-to-check-for} are checked with a prefix of the target type as
3909 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3910 (@pxref{Canonicalizing}). If none of the tools can be found with a
3911 prefix, and if the build and target types are equal, then the first one
3912 without a prefix is used. If a tool is found, set @var{variable} to
3913 the name of that program. If none of the tools in the list are found,
3914 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3915 is not specified, the value of @var{variable} is not changed. Calls
3916 @code{AC_SUBST} for @var{variable}.
3919 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3920 @acindex{CHECK_TOOLS}
3921 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3922 @var{progs-to-check-for} are checked with a prefix of the host type as
3923 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3924 (@pxref{Canonicalizing}). If none of the tools can be found with a
3925 prefix, then the first one without a prefix is used. If a tool is found,
3926 set @var{variable} to the name of that program. If none of the tools in
3927 the list are found, set @var{variable} to @var{value-if-not-found}; if
3928 @var{value-if-not-found} is not specified, the value of @var{variable}
3929 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3931 In the future, when cross-compiling this macro will @emph{not}
3932 accept program names that are not prefixed with the host type.
3935 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3937 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3938 name of @var{prog-to-check-for} if found.
3941 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3942 @acindex{PATH_PROGS}
3943 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3944 are found, set @var{variable} to the absolute name of the program
3948 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3949 @acindex{PATH_TARGET_TOOL}
3950 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3951 name of the program if it is found.
3954 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3956 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3957 name of the program if it is found.
3959 In the future, when cross-compiling this macro will @emph{not}
3960 accept program names that are not prefixed with the host type.
3966 @cindex File, checking
3968 You might also need to check for the existence of files. Before using
3969 these macros, ask yourself whether a runtime test might not be a better
3970 solution. Be aware that, like most Autoconf macros, they test a feature
3971 of the host machine, and therefore, they die when cross-compiling.
3973 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3974 @acindex{CHECK_FILE}
3975 Check whether file @var{file} exists on the native system. If it is
3976 found, execute @var{action-if-found}, otherwise do
3977 @var{action-if-not-found}, if given.
3980 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3981 @acindex{CHECK_FILES}
3982 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3983 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3984 for each file found.
3989 @section Library Files
3990 @cindex Library, checking
3992 The following macros check for the presence of certain C, C++, or Fortran
3993 library archive files.
3995 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3997 Test whether the library @var{library} is available by trying to link
3998 a test program that calls function @var{function} with the library.
3999 @var{function} should be a function provided by the library.
4001 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
4002 the @var{library} argument.
4004 @var{action-if-found} is a list of shell commands to run if the link
4005 with the library succeeds; @var{action-if-not-found} is a list of shell
4006 commands to run if the link fails. If @var{action-if-found} is not
4007 specified, the default action prepends @option{-l@var{library}} to
4008 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
4009 capitals). This macro is intended to support building @code{LIBS} in
4010 a right-to-left (least-dependent to most-dependent) fashion such that
4011 library dependencies are satisfied as a natural side effect of
4012 consecutive tests. Linkers are sensitive to library ordering
4013 so the order in which @code{LIBS} is generated is important to reliable
4014 detection of libraries.
4016 If linking with @var{library} results in unresolved symbols that would
4017 be resolved by linking with additional libraries, give those libraries
4018 as the @var{other-libraries} argument, separated by spaces:
4019 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4020 that @var{library} is present, because linking the test program
4021 always fails with unresolved symbols. The @var{other-libraries} argument
4022 should be limited to cases where it is desirable to test for one library
4023 in the presence of another that is not already in @code{LIBS}.
4025 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4026 in some common cases. Many standard functions like @code{gethostbyname}
4027 appear in the standard C library on some hosts, and in special libraries
4028 like @code{nsl} on other hosts. On some hosts the special libraries
4029 contain variant implementations that you may not want to use. These
4030 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4031 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4035 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4036 @acindex{SEARCH_LIBS}
4037 Search for a library defining @var{function} if it's not already
4038 available. This equates to calling
4039 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4040 no libraries, then for each library listed in @var{search-libs}.
4042 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4043 to contain @var{function}, and run @var{action-if-found}. If the
4044 function is not found, run @var{action-if-not-found}.
4046 If linking with @var{library} results in unresolved symbols that would
4047 be resolved by linking with additional libraries, give those libraries
4048 as the @var{other-libraries} argument, separated by spaces:
4049 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4050 that @var{function} is present, because linking the test program
4051 always fails with unresolved symbols.
4056 @node Library Functions
4057 @section Library Functions
4059 The following macros check for particular C library functions.
4060 If there is no macro specifically defined to check for a function you need,
4061 and you don't need to check for any special properties of
4062 it, then you can use one of the general function-check macros.
4065 * Function Portability:: Pitfalls with usual functions
4066 * Particular Functions:: Special handling to find certain functions
4067 * Generic Functions:: How to find other functions
4070 @node Function Portability
4071 @subsection Portability of C Functions
4072 @cindex Portability of C functions
4073 @cindex C function portability
4075 Most usual functions can either be missing, or be buggy, or be limited
4076 on some architectures. This section tries to make an inventory of these
4077 portability issues. By definition, this list always requires
4078 additions. Please help us keeping it as complete as possible.
4083 @prindex @code{exit}
4084 On ancient hosts, @code{exit} returned @code{int}.
4085 This is because @code{exit} predates @code{void}, and there was a long
4086 tradition of it returning @code{int}.
4088 On current hosts, the problem more likely is that @code{exit} is not
4089 declared, due to C++ problems of some sort or another. For this reason
4090 we suggest that test programs not invoke @code{exit}, but return from
4091 @code{main} instead.
4095 @prindex @code{free}
4096 The C standard says a call @code{free (NULL)} does nothing, but
4097 some old systems don't support this (e.g., NextStep).
4103 @prindex @code{isinf}
4104 @prindex @code{isnan}
4105 The C99 standard says that @code{isinf} and @code{isnan} are
4106 macros. On some systems just macros are available
4107 (e.g., @acronym{HP-UX} and Solaris 10), on
4108 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4109 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4110 these functions are declared in nonstandard headers like
4111 @code{<sunmath.h>} and defined in non-default libraries like
4112 @option{-lm} or @option{-lsunmath}.
4114 The C99 @code{isinf} and @code{isnan} macros work correctly with
4115 @code{long double} arguments, but pre-C99 systems that use functions
4116 typically assume @code{double} arguments. On such a system,
4117 @code{isinf} incorrectly returns true for a finite @code{long double}
4118 argument that is outside the range of @code{double}.
4120 To work around this porting mess, you can use code like the following.
4127 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4128 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4130 static inline int isnan_f (float x) @{ return x != x; @}
4131 static inline int isnan_d (double x) @{ return x != x; @}
4132 static inline int isnan_ld (long double x) @{ return x != x; @}
4137 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4138 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4140 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4141 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4142 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4146 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4147 compilers that lack the @code{inline} keyword. Some optimizing
4148 compilers mishandle these definitions, but systems with that bug
4149 typically have missing or broken @code{isnan} functions anyway, so it's
4150 probably not worth worrying about.
4154 @prindex @code{malloc}
4155 The C standard says a call @code{malloc (0)} is implementation
4156 dependent. It can return either @code{NULL} or a new non-null pointer.
4157 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4158 no means universal. @code{AC_FUNC_MALLOC}
4159 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4163 @prindex @code{putenv}
4164 Posix prefers @code{setenv} to @code{putenv}; among other things,
4165 @code{putenv} is not required of all Posix implementations, but
4168 Posix specifies that @code{putenv} puts the given string directly in
4169 @code{environ}, but some systems make a copy of it instead (e.g.,
4170 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4171 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4173 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4174 environment, but this is not standard usage and it dumps core
4175 on some systems (e.g., AIX).
4177 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4178 environment, rather than inserting it with an empty value.
4180 @item @code{realloc}
4182 @prindex @code{realloc}
4183 The C standard says a call @code{realloc (NULL, size)} is equivalent
4184 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4187 @item @code{signal} handler
4189 @prindex @code{signal}
4190 Normally @code{signal} takes a handler function with a return type of
4191 @code{void}, but some old systems required @code{int} instead. Any
4192 actual @code{int} value returned is not used; this is only a
4193 difference in the function prototype demanded.
4195 All systems we know of in current use return @code{void}. The
4196 @code{int} was to support K&R C, where of course @code{void} is not
4197 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4198 used to establish the correct type in all cases.
4200 @item @code{snprintf}
4201 @c @fuindex snprintf
4202 @prindex @code{snprintf}
4203 @c @fuindex vsnprintf
4204 @prindex @code{vsnprintf}
4205 The C99 standard says that if the output array isn't big enough
4206 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4207 truncate the output and return the number of bytes that ought to have
4208 been produced. Some older systems return the truncated length (e.g.,
4209 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4210 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4211 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4212 older systems ignore the length and overrun the buffer (e.g., 64-bit
4215 @item @code{sprintf}
4217 @prindex @code{sprintf}
4218 @c @fuindex vsprintf
4219 @prindex @code{vsprintf}
4220 The C standard says @code{sprintf} and @code{vsprintf} return the
4221 number of bytes written. On some ancient systems (SunOS 4 for
4222 instance) they return the buffer pointer instead, but these no
4223 longer need to be worried about.
4227 @prindex @code{sscanf}
4228 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4229 input string be writable (though it doesn't actually change it). This
4230 can be a problem when using @command{gcc} since it normally puts
4231 constant strings in read-only memory (@pxref{Incompatibilities,
4232 Incompatibilities of @acronym{GCC}, , gcc, Using and
4233 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4234 having format strings read-only can be a problem.
4236 @item @code{strerror_r}
4237 @c @fuindex strerror_r
4238 @prindex @code{strerror_r}
4239 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4240 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4241 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4242 can detect which is in use (@pxref{Particular Functions}).
4244 @item @code{strnlen}
4246 @prindex @code{strnlen}
4247 @acronym{AIX} 4.3 provides a broken version which produces the
4251 strnlen ("foobar", 0) = 0
4252 strnlen ("foobar", 1) = 3
4253 strnlen ("foobar", 2) = 2
4254 strnlen ("foobar", 3) = 1
4255 strnlen ("foobar", 4) = 0
4256 strnlen ("foobar", 5) = 6
4257 strnlen ("foobar", 6) = 6
4258 strnlen ("foobar", 7) = 6
4259 strnlen ("foobar", 8) = 6
4260 strnlen ("foobar", 9) = 6
4263 @item @code{sysconf}
4265 @prindex @code{sysconf}
4266 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4267 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4272 @prindex @code{unlink}
4273 The Posix spec says that @code{unlink} causes the given file to be
4274 removed only after there are no more open file handles for it. Some
4275 non-Posix hosts have trouble with this requirement, though,
4276 and some @acronym{DOS} variants even corrupt the file system.
4278 @item @code{unsetenv}
4279 @c @fuindex unsetenv
4280 @prindex @code{unsetenv}
4281 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4282 can be removed with a call @code{putenv ("FOO=")}, as described under
4283 @code{putenv} above.
4285 @item @code{va_copy}
4287 @prindex @code{va_copy}
4288 The C99 standard provides @code{va_copy} for copying
4289 @code{va_list} variables. It may be available in older environments
4290 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4291 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4292 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4295 @item @code{va_list}
4297 @prindex @code{va_list}
4298 @code{va_list} is not necessarily just a pointer. It can be a
4299 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4300 not portable. Or it can be an array (e.g., @command{gcc} in some
4301 PowerPC configurations), which means as a function parameter it can be
4302 effectively call-by-reference and library routines might modify the
4303 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4306 @item Signed @code{>>}
4307 Normally the C @code{>>} right shift of a signed type replicates the
4308 high bit, giving a so-called ``arithmetic'' shift. But care should be
4309 taken since Standard C doesn't require that behavior. On those
4310 few processors without a native arithmetic shift (for instance Cray
4311 vector systems) zero bits may be shifted in, the same as a shift of an
4314 @item Integer @code{/}
4315 C divides signed integers by truncating their quotient toward zero,
4316 yielding the same result as Fortran. However, before C99 the standard
4317 allowed C implementations to take the floor or ceiling of the quotient
4318 in some cases. Hardly any implementations took advantage of this
4319 freedom, though, and it's probably not worth worrying about this issue
4324 @node Particular Functions
4325 @subsection Particular Function Checks
4326 @cindex Function, checking
4328 These macros check for particular C functions---whether they exist, and
4329 in some cases how they respond when given certain arguments.
4331 @defmac AC_FUNC_ALLOCA
4332 @acindex{FUNC_ALLOCA}
4334 @cvindex HAVE_ALLOCA_H
4337 @prindex @code{alloca}
4339 Check how to get @code{alloca}. Tries to get a builtin version by
4340 checking for @file{alloca.h} or the predefined C preprocessor macros
4341 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4342 it defines @code{HAVE_ALLOCA_H}.
4344 If those attempts fail, it looks for the function in the standard C
4345 library. If any of those methods succeed, it defines
4346 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4347 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4348 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4349 garbage collect). This variable is separate from @code{LIBOBJS} so
4350 multiple programs can share the value of @code{ALLOCA} without needing
4351 to create an actual library, in case only some of them use the code in
4352 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4353 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4355 This macro does not try to get @code{alloca} from the System V R3
4356 @file{libPW} or the System V R4 @file{libucb} because those libraries
4357 contain some incompatible functions that cause trouble. Some versions
4358 do not even contain @code{alloca} or contain a buggy version. If you
4359 still want to use their @code{alloca}, use @code{ar} to extract
4360 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4362 Source files that use @code{alloca} should start with a piece of code
4363 like the following, to declare it properly.
4367 #ifdef HAVE_ALLOCA_H
4368 # include <alloca.h>
4369 #elif defined __GNUC__
4370 # define alloca __builtin_alloca
4372 # define alloca __alloca
4373 #elif defined _MSC_VER
4374 # include <malloc.h>
4375 # define alloca _alloca
4377 # include <stddef.h>
4381 void *alloca (size_t);
4387 @defmac AC_FUNC_CHOWN
4388 @acindex{FUNC_CHOWN}
4390 @prindex @code{chown}
4391 If the @code{chown} function is available and works (in particular, it
4392 should accept @option{-1} for @code{uid} and @code{gid}), define
4397 @defmac AC_FUNC_CLOSEDIR_VOID
4398 @acindex{FUNC_CLOSEDIR_VOID}
4399 @cvindex CLOSEDIR_VOID
4400 @c @fuindex closedir
4401 @prindex @code{closedir}
4402 If the @code{closedir} function does not return a meaningful value,
4403 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4404 return value for an error indicator.
4406 Currently this test is implemented by running a test program. When
4407 cross compiling the pessimistic assumption that @code{closedir} does not
4408 return a meaningful value is made.
4410 This macro is obsolescent, as @code{closedir} returns a meaningful value
4411 on current systems. New programs need not use this macro.
4414 @defmac AC_FUNC_ERROR_AT_LINE
4415 @acindex{FUNC_ERROR_AT_LINE}
4416 @c @fuindex error_at_line
4417 @prindex @code{error_at_line}
4418 If the @code{error_at_line} function is not found, require an
4419 @code{AC_LIBOBJ} replacement of @samp{error}.
4422 @defmac AC_FUNC_FNMATCH
4423 @acindex{FUNC_FNMATCH}
4425 @prindex @code{fnmatch}
4426 If the @code{fnmatch} function conforms to Posix, define
4427 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4428 the bugs in Solaris 2.4.
4430 Unlike the other specific
4431 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4432 broken/missing @code{fnmatch}. This is for historical reasons.
4433 See @code{AC_REPLACE_FNMATCH} below.
4435 This macro is obsolescent. New programs should use Gnulib's
4436 @code{fnmatch-posix} module. @xref{Gnulib}.
4439 @defmac AC_FUNC_FNMATCH_GNU
4440 @acindex{FUNC_FNMATCH_GNU}
4442 @prindex @code{fnmatch}
4443 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4444 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4445 implementation bugs, for example, the bugs in the @acronym{GNU} C
4448 This macro is obsolescent. New programs should use Gnulib's
4449 @code{fnmatch-gnu} module. @xref{Gnulib}.
4452 @defmac AC_FUNC_FORK
4454 @cvindex HAVE_VFORK_H
4455 @cvindex HAVE_WORKING_FORK
4456 @cvindex HAVE_WORKING_VFORK
4459 @prindex @code{fork}
4461 @prindex @code{vfork}
4463 This macro checks for the @code{fork} and @code{vfork} functions. If a
4464 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4465 checks whether @code{fork} is just a stub by trying to run it.
4467 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4468 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4469 define @code{vfork} to be @code{fork} for backward compatibility with
4470 previous versions of @command{autoconf}. This macro checks for several known
4471 errors in implementations of @code{vfork} and considers the system to not
4472 have a working @code{vfork} if it detects any of them. It is not considered
4473 to be an implementation error if a child's invocation of @code{signal}
4474 modifies the parent's signal handler, since child processes rarely change
4475 their signal handlers.
4477 Since this macro defines @code{vfork} only for backward compatibility with
4478 previous versions of @command{autoconf} you're encouraged to define it
4479 yourself in new code:
4482 #ifndef HAVE_WORKING_VFORK
4489 @defmac AC_FUNC_FSEEKO
4490 @acindex{FUNC_FSEEKO}
4491 @cvindex _LARGEFILE_SOURCE
4493 @prindex @code{fseeko}
4494 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4495 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4496 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4497 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4498 largefile-sensitive systems where @code{off_t} does not default to a
4502 @defmac AC_FUNC_GETGROUPS
4503 @acindex{FUNC_GETGROUPS}
4504 @ovindex GETGROUPS_LIBS
4505 @c @fuindex getgroups
4506 @prindex @code{getgroups}
4507 If the @code{getgroups} function is available and works (unlike on
4508 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4509 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4510 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4513 @defmac AC_FUNC_GETLOADAVG
4514 @acindex{FUNC_GETLOADAVG}
4519 @cvindex HAVE_NLIST_H
4520 @cvindex NLIST_NAME_UNION
4521 @cvindex GETLOADAVG_PRIVILEGED
4522 @cvindex NEED_SETGID
4523 @cvindex C_GETLOADAVG
4525 @ovindex NEED_SETGID
4527 @ovindex GETLOADAVG_LIBS
4528 @c @fuindex getloadavg
4529 @prindex @code{getloadavg}
4530 Check how to get the system load averages. To perform its tests
4531 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4532 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4533 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4535 If the system has the @code{getloadavg} function, define
4536 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4537 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4538 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4539 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4540 possibly define several other C preprocessor macros and output
4545 Define @code{C_GETLOADAVG}.
4548 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4553 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4556 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4557 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4558 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4561 Programs may need to be installed set-group-ID (or set-user-ID) for
4562 @code{getloadavg} to work. In this case, define
4563 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4564 to @samp{true} (and otherwise to @samp{false}), and set
4565 @code{KMEM_GROUP} to the name of the group that should own the installed
4569 The @code{AC_FUNC_GETLOADAVG} macro is obsolescent. New programs should
4570 use Gnulib's @code{getloadavg} module. @xref{Gnulib}.
4573 @defmac AC_FUNC_GETMNTENT
4574 @acindex{FUNC_GETMNTENT}
4575 @cvindex HAVE_GETMNTENT
4576 @c @fuindex getmntent
4577 @prindex @code{getmntent}
4578 Check for @code{getmntent} in the standard C library, and then in the
4579 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4580 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4581 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4584 @defmac AC_FUNC_GETPGRP
4585 @acindex{FUNC_GETPGRP}
4586 @cvindex GETPGRP_VOID
4589 @prindex @code{getpgid}
4590 @prindex @code{getpgrp}
4591 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4592 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4593 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4594 behaves like Posix's @code{getpgid}.
4604 This macro does not check whether
4605 @code{getpgrp} exists at all; if you need to work in that situation,
4606 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4608 This macro is obsolescent, as current systems have a @code{getpgrp}
4609 whose signature conforms to Posix. New programs need not use this macro.
4612 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4613 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4614 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4616 @prindex @code{lstat}
4617 If @file{link} is a symbolic link, then @code{lstat} should treat
4618 @file{link/} the same as @file{link/.}. However, many older
4619 @code{lstat} implementations incorrectly ignore trailing slashes.
4621 It is safe to assume that if @code{lstat} incorrectly ignores
4622 trailing slashes, then other symbolic-link-aware functions like
4623 @code{unlink} also incorrectly ignore trailing slashes.
4625 If @code{lstat} behaves properly, define
4626 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4627 @code{AC_LIBOBJ} replacement of @code{lstat}.
4630 @defmac AC_FUNC_MALLOC
4631 @acindex{FUNC_MALLOC}
4632 @cvindex HAVE_MALLOC
4635 @prindex @code{malloc}
4636 If the @code{malloc} function is compatible with the @acronym{GNU} C
4637 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4638 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4639 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4640 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4641 native @code{malloc} is not used in the main project.
4643 Typically, the replacement file @file{malloc.c} should look like (note
4644 the @samp{#undef malloc}):
4647 #ifdef HAVE_CONFIG_H
4648 # include <config.h>
4652 #include <sys/types.h>
4656 /* Allocate an N-byte block of memory from the heap.
4657 If N is zero, allocate a 1-byte block. */
4660 rpl_malloc (size_t n)
4669 @defmac AC_FUNC_MEMCMP
4670 @acindex{FUNC_MEMCMP}
4673 @prindex @code{memcmp}
4674 If the @code{memcmp} function is not available, or does not work on
4675 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4676 bytes or more and with at least one buffer not starting on a 4-byte
4677 boundary (such as the one on NeXT x86 OpenStep), require an
4678 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4680 This macro is obsolescent, as current systems have a working
4681 @code{memcmp}. New programs need not use this macro.
4684 @defmac AC_FUNC_MBRTOWC
4685 @acindex{FUNC_MBRTOWC}
4686 @cvindex HAVE_MBRTOWC
4688 @prindex @code{mbrtowc}
4689 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4690 type @code{mbstate_t} are properly declared.
4693 @defmac AC_FUNC_MKTIME
4694 @acindex{FUNC_MKTIME}
4697 @prindex @code{mktime}
4698 If the @code{mktime} function is not available, or does not work
4699 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4700 For the purposes of this test, @code{mktime} should conform to the
4701 Posix standard and should be the inverse of
4705 @defmac AC_FUNC_MMAP
4709 @prindex @code{mmap}
4710 If the @code{mmap} function exists and works correctly, define
4711 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4715 @defmac AC_FUNC_OBSTACK
4716 @acindex{FUNC_OBSTACK}
4717 @cvindex HAVE_OBSTACK
4719 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4720 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4723 @defmac AC_FUNC_REALLOC
4724 @acindex{FUNC_REALLOC}
4725 @cvindex HAVE_REALLOC
4728 @prindex @code{realloc}
4729 If the @code{realloc} function is compatible with the @acronym{GNU} C
4730 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4731 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4732 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4733 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4734 the native @code{realloc} is not used in the main project. See
4735 @code{AC_FUNC_MALLOC} for details.
4738 @defmac AC_FUNC_SELECT_ARGTYPES
4739 @acindex{FUNC_SELECT_ARGTYPES}
4740 @cvindex SELECT_TYPE_ARG1
4741 @cvindex SELECT_TYPE_ARG234
4742 @cvindex SELECT_TYPE_ARG5
4744 @prindex @code{select}
4745 Determines the correct type to be passed for each of the
4746 @code{select} function's arguments, and defines those types
4747 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4748 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4749 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4750 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4752 This macro is obsolescent, as current systems have a @code{select} whose
4753 signature conforms to Posix. New programs need not use this macro.
4756 @defmac AC_FUNC_SETPGRP
4757 @acindex{FUNC_SETPGRP}
4758 @cvindex SETPGRP_VOID
4760 @prindex @code{setpgrp}
4761 If @code{setpgrp} takes no argument (the Posix version), define
4762 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4763 two process IDs as arguments. This macro does not check whether
4764 @code{setpgrp} exists at all; if you need to work in that situation,
4765 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4767 This macro is obsolescent, as current systems have a @code{setpgrp}
4768 whose signature conforms to Posix. New programs need not use this macro.
4771 @defmac AC_FUNC_STAT
4772 @defmacx AC_FUNC_LSTAT
4774 @acindex{FUNC_LSTAT}
4775 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4776 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4778 @prindex @code{stat}
4780 @prindex @code{lstat}
4781 Determine whether @code{stat} or @code{lstat} have the bug that it
4782 succeeds when given the zero-length file name as argument. The @code{stat}
4783 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4786 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4787 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4790 These macros are obsolescent, as no current systems have the bug.
4791 New programs need not use these macros.
4794 @defmac AC_FUNC_STRCOLL
4795 @acindex{FUNC_STRCOLL}
4796 @cvindex HAVE_STRCOLL
4798 @prindex @code{strcoll}
4799 If the @code{strcoll} function exists and works correctly, define
4800 @code{HAVE_STRCOLL}. This does a bit more than
4801 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4802 definitions of @code{strcoll} that should not be used.
4805 @defmac AC_FUNC_STRERROR_R
4806 @acindex{FUNC_STRERROR_R}
4807 @cvindex HAVE_STRERROR_R
4808 @cvindex HAVE_DECL_STRERROR_R
4809 @cvindex STRERROR_R_CHAR_P
4810 @c @fuindex strerror_r
4811 @prindex @code{strerror_r}
4812 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4813 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4814 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4815 returns an @code{int} error number. The Thread-Safe Functions option of
4816 Posix requires @code{strerror_r} to return @code{int}, but
4817 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4818 Library) return a @code{char *} value that is not necessarily equal to
4819 the buffer argument.
4822 @defmac AC_FUNC_STRFTIME
4823 @acindex{FUNC_STRFTIME}
4824 @cvindex HAVE_STRFTIME
4825 @c @fuindex strftime
4826 @prindex @code{strftime}
4827 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4828 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4830 This macro is obsolescent, as no current systems require the @file{intl}
4831 library for @code{strftime}. New programs need not use this macro.
4834 @defmac AC_FUNC_STRTOD
4835 @acindex{FUNC_STRTOD}
4838 @prindex @code{strtod}
4839 If the @code{strtod} function does not exist or doesn't work correctly,
4840 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4841 because @file{strtod.c} is likely to need @samp{pow}, set the output
4842 variable @code{POW_LIB} to the extra library needed.
4845 @defmac AC_FUNC_STRTOLD
4846 @acindex{FUNC_STRTOLD}
4847 @prindex @code{strtold}
4848 If the @code{strtold} function exists and conforms to C99, define
4849 @code{HAVE_STRTOLD}.
4852 @defmac AC_FUNC_STRNLEN
4853 @acindex{FUNC_STRNLEN}
4854 @cvindex HAVE_STRNLEN
4856 @prindex @code{strnlen}
4857 If the @code{strnlen} function is not available, or is buggy (like the one
4858 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4861 @defmac AC_FUNC_UTIME_NULL
4862 @acindex{FUNC_UTIME_NULL}
4863 @cvindex HAVE_UTIME_NULL
4865 @prindex @code{utime}
4866 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4867 the present, define @code{HAVE_UTIME_NULL}.
4869 This macro is obsolescent, as all current systems have a @code{utime}
4870 that behaves this way. New programs need not use this macro.
4873 @defmac AC_FUNC_VPRINTF
4874 @acindex{FUNC_VPRINTF}
4875 @cvindex HAVE_VPRINTF
4876 @cvindex HAVE_DOPRNT
4878 @prindex @code{vprintf}
4879 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4880 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4881 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4882 are also available.)
4884 This macro is obsolescent, as all current systems have @code{vprintf}.
4885 New programs need not use this macro.
4888 @defmac AC_REPLACE_FNMATCH
4889 @acindex{REPLACE_FNMATCH}
4891 @prindex @code{fnmatch}
4892 @hdrindex{fnmatch.h}
4893 If the @code{fnmatch} function does not conform to Posix (see
4894 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4896 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4897 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4898 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4899 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4900 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4901 included in place of the system @code{<fnmatch.h>}.
4903 This macro is obsolescent, as it assumes the use of particular source
4904 files. New programs should use Gnulib's @code{fnmatch-posix} module,
4905 which provides this macro along with the source files. @xref{Gnulib}.
4910 @node Generic Functions
4911 @subsection Generic Function Checks
4913 These macros are used to find functions not covered by the ``particular''
4914 test macros. If the functions might be in libraries other than the
4915 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4916 If you need to check the behavior of a function as well as find out
4917 whether it is present, you have to write your own test for
4918 it (@pxref{Writing Tests}).
4920 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4921 @acindex{CHECK_FUNC}
4922 If C function @var{function} is available, run shell commands
4923 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4924 want to define a symbol if the function is available, consider using
4925 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4926 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4927 standardized than C++. (@pxref{Language Choice}, for more information
4928 about selecting the language for checks.)
4931 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4932 @acindex{CHECK_FUNCS}
4933 @cvindex HAVE_@var{function}
4934 For each @var{function} enumerated in the blank-or-newline-separated argument
4935 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4936 If @var{action-if-found} is given, it is additional shell code to
4937 execute when one of the functions is found. You can give it a value of
4938 @samp{break} to break out of the loop on the first match. If
4939 @var{action-if-not-found} is given, it is executed when one of the
4940 functions is not found.
4943 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4944 @acindex{CHECK_FUNCS_ONCE}
4945 @cvindex HAVE_@var{function}
4946 For each @var{function} enumerated in the blank-or-newline-separated argument
4947 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4948 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
4949 checking code at most once, so that @command{configure} is smaller and
4950 faster; but the checks cannot be conditionalized and are always done once,
4951 early during the @command{configure} run.
4956 Autoconf follows a philosophy that was formed over the years by those
4957 who have struggled for portability: isolate the portability issues in
4958 specific files, and then program as if you were in a Posix
4959 environment. Some functions may be missing or unfixable, and your
4960 package must be ready to replace them.
4962 Suitable replacements for many such problem functions are available from
4963 Gnulib (@pxref{Gnulib}).
4965 @defmac AC_LIBOBJ (@var{function})
4968 Specify that @samp{@var{function}.c} must be included in the executables
4969 to replace a missing or broken implementation of @var{function}.
4971 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4972 variable @code{LIBOBJS} if it is not already in, and calls
4973 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4974 directly change @code{LIBOBJS}, since this is not traceable.
4977 @defmac AC_LIBSOURCE (@var{file})
4979 Specify that @var{file} might be needed to compile the project. If you
4980 need to know what files might be needed by a @file{configure.ac}, you
4981 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4983 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4984 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4985 that case, since shell variables cannot be traced statically, you must
4986 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4987 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4988 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4989 @code{"foo"} or @code{"bar"}, you should do:
4992 AC_LIBSOURCE([foo.c])
4993 AC_LIBSOURCE([bar.c])
4994 AC_LIBOBJ([$foo_or_bar])
4998 There is usually a way to avoid this, however, and you are encouraged to
4999 simply call @code{AC_LIBOBJ} with literal arguments.
5001 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
5002 slightly different semantics: the old macro took the function name,
5003 e.g., @code{foo}, as its argument rather than the file name.
5006 @defmac AC_LIBSOURCES (@var{files})
5007 @acindex{LIBSOURCES}
5008 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
5009 comma-separated M4 list. Thus, the above example might be rewritten:
5012 AC_LIBSOURCES([foo.c, bar.c])
5013 AC_LIBOBJ([$foo_or_bar])
5017 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5018 @acindex{CONFIG_LIBOBJ_DIR}
5019 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5020 @var{directory}, a name relative to the top level of the
5021 source tree. The replacement directory defaults to @file{.}, the top
5022 level directory, and the most typical value is @file{lib}, corresponding
5023 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5025 @command{configure} might need to know the replacement directory for the
5026 following reasons: (i) some checks use the replacement files, (ii) some
5027 macros bypass broken system headers by installing links to the
5028 replacement headers (iii) when used in conjunction with Automake,
5029 within each makefile, @var{directory} is used as a relative path
5030 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5031 @code{LTLIBOBJS}, etc.
5036 It is common to merely check for the existence of a function, and ask
5037 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5038 a convenient shorthand.
5040 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5041 @acindex{REPLACE_FUNCS}
5043 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5044 @var{action-if-not-found}. You can declare your replacement function by
5045 enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the
5046 system has the function, it probably declares it in a header file you
5047 should be including, so you shouldn't redeclare it lest your declaration
5052 @section Header Files
5053 @cindex Header, checking
5055 The following macros check for the presence of certain C header files.
5056 If there is no macro specifically defined to check for a header file you need,
5057 and you don't need to check for any special properties of
5058 it, then you can use one of the general header-file check macros.
5061 * Header Portability:: Collected knowledge on common headers
5062 * Particular Headers:: Special handling to find certain headers
5063 * Generic Headers:: How to find other headers
5066 @node Header Portability
5067 @subsection Portability of Headers
5068 @cindex Portability of headers
5069 @cindex Header portability
5071 This section tries to collect knowledge about common headers, and the
5072 problems they cause. By definition, this list always requires
5073 additions. Please help us keeping it as complete as possible.
5077 @item @file{limits.h}
5078 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5079 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5080 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5083 @item @file{inttypes.h} vs.@: @file{stdint.h}
5084 @hdrindex{inttypes.h}
5086 The C99 standard says that @file{inttypes.h} includes
5087 @file{stdint.h}, so there's no need to include @file{stdint.h}
5088 separately in a standard environment. Some implementations have
5089 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5090 know of any implementation that has @file{stdint.h} but not
5093 @item @file{linux/irda.h}
5094 @hdrindex{linux/irda.h}
5095 It requires @file{linux/types.h} and @file{sys/socket.h}.
5097 @item @file{linux/random.h}
5098 @hdrindex{linux/random.h}
5099 It requires @file{linux/types.h}.
5101 @item @file{net/if.h}
5103 On Darwin, this file requires that @file{sys/socket.h} be included
5104 beforehand. One should run:
5107 AC_CHECK_HEADERS([sys/socket.h])
5108 AC_CHECK_HEADERS([net/if.h], [], [],
5111 # include <stdlib.h>
5112 # include <stddef.h>
5114 # ifdef HAVE_STDLIB_H
5115 # include <stdlib.h>
5118 #ifdef HAVE_SYS_SOCKET_H
5119 # include <sys/socket.h>
5124 @item @file{netinet/if_ether.h}
5125 @hdrindex{netinet/if_ether.h}
5126 On Darwin, this file requires that @file{stdio.h} and
5127 @file{sys/socket.h} be included beforehand. One should run:
5130 AC_CHECK_HEADERS([sys/socket.h])
5131 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5134 # include <stdlib.h>
5135 # include <stddef.h>
5137 # ifdef HAVE_STDLIB_H
5138 # include <stdlib.h>
5141 #ifdef HAVE_SYS_SOCKET_H
5142 # include <sys/socket.h>
5147 @item @file{stdint.h}
5148 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5150 @item @file{stdlib.h}
5152 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5154 @item @file{sys/mount.h}
5155 @hdrindex{sys/mount.h}
5156 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5157 @file{sys/params.h} is a prerequisite.
5159 @item @file{sys/ptem.h}
5160 @hdrindex{sys/ptem.h}
5161 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5163 @item @file{sys/socket.h}
5164 @hdrindex{sys/socket.h}
5165 On Darwin, @file{stdlib.h} is a prerequisite.
5167 @item @file{sys/ucred.h}
5168 @hdrindex{sys/ucred.h}
5169 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5171 @item @file{X11/extensions/scrnsaver.h}
5172 @hdrindex{X11/extensions/scrnsaver.h}
5173 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5174 so required that you might not even consider looking for it.
5177 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5178 [[#include <X11/Xlib.h>
5184 @node Particular Headers
5185 @subsection Particular Header Checks
5187 These macros check for particular system header files---whether they
5188 exist, and in some cases whether they declare certain symbols.
5190 @defmac AC_HEADER_ASSERT
5191 @acindex{HEADER_ASSERT}
5194 Check whether to enable assertions in the style of @file{assert.h}.
5195 Assertions are enabled by default, but the user can override this by
5196 invoking @command{configure} with the @option{--disable-assert} option.
5199 @defmac AC_HEADER_DIRENT
5200 @acindex{HEADER_DIRENT}
5201 @cvindex HAVE_DIRENT_H
5202 @cvindex HAVE_NDIR_H
5203 @cvindex HAVE_SYS_DIR_H
5204 @cvindex HAVE_SYS_NDIR_H
5206 @hdrindex{sys/ndir.h}
5207 @hdrindex{sys/dir.h}
5209 Check for the following header files. For the first one that is
5210 found and defines @samp{DIR}, define the listed C preprocessor macro:
5212 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5213 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5214 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5215 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5216 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5219 The directory-library declarations in your source code should look
5220 something like the following:
5224 #include <sys/types.h>
5225 #ifdef HAVE_DIRENT_H
5226 # include <dirent.h>
5227 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5229 # define dirent direct
5230 # define NAMLEN(dirent) ((dirent)->d_namlen)
5231 # ifdef HAVE_SYS_NDIR_H
5232 # include <sys/ndir.h>
5234 # ifdef HAVE_SYS_DIR_H
5235 # include <sys/dir.h>
5244 Using the above declarations, the program would declare variables to be
5245 of type @code{struct dirent}, not @code{struct direct}, and would access
5246 the length of a directory entry name by passing a pointer to a
5247 @code{struct dirent} to the @code{NAMLEN} macro.
5249 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5251 This macro is obsolescent, as all current systems with directory
5252 libraries have @code{<dirent.h>}. New programs need not use this macro.
5254 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5255 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5258 @defmac AC_HEADER_MAJOR
5259 @acindex{HEADER_MAJOR}
5260 @cvindex MAJOR_IN_MKDEV
5261 @cvindex MAJOR_IN_SYSMACROS
5262 @hdrindex{sys/mkdev.h}
5263 @hdrindex{sys/sysmacros.h}
5264 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5265 @code{makedev}, but @file{sys/mkdev.h} does, define
5266 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5267 @code{MAJOR_IN_SYSMACROS}.
5270 @defmac AC_HEADER_RESOLV
5271 @acindex{HEADER_RESOLV}
5272 @cvindex HAVE_RESOLV_H
5274 Checks for header @file{resolv.h}, checking for prerequisites first.
5275 To properly use @file{resolv.h}, your code should contain something like
5279 #ifdef HAVE_SYS_TYPES_H
5280 # include <sys/types.h>
5282 #ifdef HAVE_NETINET_IN_H
5283 # include <netinet/in.h> /* inet_ functions / structs */
5285 #ifdef HAVE_ARPA_NAMESER_H
5286 # include <arpa/nameser.h> /* DNS HEADER struct */
5295 @defmac AC_HEADER_STAT
5296 @acindex{HEADER_STAT}
5297 @cvindex STAT_MACROS_BROKEN
5298 @hdrindex{sys/stat.h}
5299 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5300 @file{sys/stat.h} do not work properly (returning false positives),
5301 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5302 Amdahl UTS and Motorola System V/88.
5304 This macro is obsolescent, as no current systems have the bug.
5305 New programs need not use this macro.
5308 @defmac AC_HEADER_STDBOOL
5309 @acindex{HEADER_STDBOOL}
5310 @cvindex HAVE_STDBOOL_H
5312 @hdrindex{stdbool.h}
5314 If @file{stdbool.h} exists and conforms to C99, define
5315 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5316 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5317 @file{system.h} could contain the following code:
5320 #ifdef HAVE_STDBOOL_H
5321 # include <stdbool.h>
5327 # define _Bool signed char
5333 # define __bool_true_false_are_defined 1
5337 Alternatively you can use the @samp{stdbool} package of Gnulib
5338 (@pxref{Gnulib}); it packages the above code into a replacement header
5339 and contains a few other bells and whistles.
5344 @defmac AC_HEADER_STDC
5345 @acindex{HEADER_STDC}
5346 @cvindex STDC_HEADERS
5352 Define @code{STDC_HEADERS} if the system has C header files
5353 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5354 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5355 @file{string.h}, and @file{float.h}; if the system has those, it
5356 probably has the rest of the C89 header files. This macro also
5357 checks whether @file{string.h} declares @code{memchr} (and thus
5358 presumably the other @code{mem} functions), whether @file{stdlib.h}
5359 declare @code{free} (and thus presumably @code{malloc} and other related
5360 functions), and whether the @file{ctype.h} macros work on characters
5361 with the high bit set, as the C standard requires.
5363 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5364 determine whether the system has conforming header files (and probably C
5367 This macro is obsolescent, as current systems have conforming header
5368 files. New programs need not use this macro.
5371 @hdrindex{strings.h}
5372 Nowadays @file{string.h} is part of the C standard and declares functions like
5373 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5374 @acronym{BSD} functions like @code{bcopy}; but
5375 historically, string functions were a major sticking point in this area.
5376 If you still want to worry about portability to ancient systems without
5377 standard headers, there is so much variation
5378 that it is probably easier to declare the functions you use than to
5379 figure out exactly what the system header files declare. Some ancient systems
5380 contained a mix of functions from the C standard and from @acronym{BSD};
5381 some were mostly standard but lacked @samp{memmove}; some defined the
5382 @acronym{BSD} functions as macros in @file{string.h} or
5383 @file{strings.h}; some had only the @acronym{BSD} functions but
5384 @file{string.h}; some declared the memory functions in @file{memory.h},
5385 some in @file{string.h}; etc. It is probably sufficient to check for
5386 one string function and one memory function; if the library had the
5387 standard versions of those then it probably had most of the others.
5388 If you put the following in @file{configure.ac}:
5391 # This example is obsolescent.
5392 # Nowadays you can omit these macro calls.
5394 AC_CHECK_FUNCS([strchr memcpy])
5398 then, in your code, you can use declarations like this:
5402 /* This example is obsolescent.
5403 Nowadays you can just #include <string.h>. */
5405 # include <string.h>
5407 # ifndef HAVE_STRCHR
5408 # define strchr index
5409 # define strrchr rindex
5411 char *strchr (), *strrchr ();
5412 # ifndef HAVE_MEMCPY
5413 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5414 # define memmove(d, s, n) bcopy ((s), (d), (n))
5421 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5422 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5423 suffice to port to ancient hosts; you must provide an implementation of
5424 each function. An easy
5425 way to incorporate your implementations only when needed (since the ones
5426 in system C libraries may be hand optimized) is to, taking @code{memchr}
5427 for example, put it in @file{memchr.c} and use
5428 @samp{AC_REPLACE_FUNCS([memchr])}.
5431 @defmac AC_HEADER_SYS_WAIT
5432 @acindex{HEADER_SYS_WAIT}
5433 @cvindex HAVE_SYS_WAIT_H
5434 @hdrindex{sys/wait.h}
5435 If @file{sys/wait.h} exists and is compatible with Posix, define
5436 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5437 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5438 of @code{int} to store a status value. If @file{sys/wait.h} is not
5439 Posix compatible, then instead of including it, define the
5440 Posix macros with their usual interpretations. Here is an
5445 #include <sys/types.h>
5446 #ifdef HAVE_SYS_WAIT_H
5447 # include <sys/wait.h>
5450 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5453 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5459 This macro is obsolescent, as current systems are compatible with Posix.
5460 New programs need not use this macro.
5463 @cvindex _POSIX_VERSION
5465 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5466 Posix systems. If there is no @file{unistd.h}, it is definitely
5467 not a Posix system. However, some non-Posix systems do
5468 have @file{unistd.h}.
5470 The way to check whether the system supports Posix is:
5474 #ifdef HAVE_UNISTD_H
5475 # include <sys/types.h>
5476 # include <unistd.h>
5479 #ifdef _POSIX_VERSION
5480 /* Code for Posix systems. */
5485 @defmac AC_HEADER_TIME
5486 @acindex{HEADER_TIME}
5487 @cvindex TIME_WITH_SYS_TIME
5489 @hdrindex{sys/time.h}
5490 If a program may include both @file{time.h} and @file{sys/time.h},
5491 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5492 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5493 protected against multiple inclusion, so programs could not explicitly
5494 include both files. This macro is useful in programs that use, for
5495 example, @code{struct timeval} as well as
5496 @code{struct tm}. It is best used in conjunction with
5497 @code{HAVE_SYS_TIME_H}, which can be checked for using
5498 @code{AC_CHECK_HEADERS([sys/time.h])}.
5502 #ifdef TIME_WITH_SYS_TIME
5503 # include <sys/time.h>
5506 # ifdef HAVE_SYS_TIME_H
5507 # include <sys/time.h>
5516 This macro is obsolescent, as current systems can include both files
5517 when they exist. New programs need not use this macro.
5521 @defmac AC_HEADER_TIOCGWINSZ
5522 @acindex{HEADER_TIOCGWINSZ}
5523 @cvindex GWINSZ_IN_SYS_IOCTL
5524 @hdrindex{sys/ioctl.h}
5525 @hdrindex{termios.h}
5526 @c FIXME: I need clarifications from Jim.
5527 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5528 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5529 found in @file{<termios.h>}.
5535 #ifdef HAVE_TERMIOS_H
5536 # include <termios.h>
5539 #ifdef GWINSZ_IN_SYS_IOCTL
5540 # include <sys/ioctl.h>
5546 @node Generic Headers
5547 @subsection Generic Header Checks
5549 These macros are used to find system header files not covered by the
5550 ``particular'' test macros. If you need to check the contents of a header
5551 as well as find out whether it is present, you have to write your own
5552 test for it (@pxref{Writing Tests}).
5554 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5555 @acindex{CHECK_HEADER}
5556 If the system header file @var{header-file} is compilable, execute shell
5557 commands @var{action-if-found}, otherwise execute
5558 @var{action-if-not-found}. If you just want to define a symbol if the
5559 header file is available, consider using @code{AC_CHECK_HEADERS}
5562 For compatibility issues with older versions of Autoconf, please read
5566 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5567 @acindex{CHECK_HEADERS}
5568 @cvindex HAVE_@var{header}
5569 For each given system header file @var{header-file} in the
5570 blank-separated argument list that exists, define
5571 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5572 is given, it is additional shell code to execute when one of the header
5573 files is found. You can give it a value of @samp{break} to break out of
5574 the loop on the first match. If @var{action-if-not-found} is given, it
5575 is executed when one of the header files is not found.
5577 For compatibility issues with older versions of Autoconf, please read
5581 Previous versions of Autoconf merely checked whether the header was
5582 accepted by the preprocessor. This was changed because the old test was
5583 inappropriate for typical uses. Headers are typically used to compile,
5584 not merely to preprocess, and the old behavior sometimes accepted
5585 headers that clashed at compile-time. If you need to check whether a
5586 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5587 (@pxref{Running the Preprocessor}).
5589 This scheme, which improves the robustness of the test, also requires
5590 that you make sure that headers that must be included before the
5591 @var{header-file} be part of the @var{includes}, (@pxref{Default
5592 Includes}). If looking for @file{bar.h}, which requires that
5593 @file{foo.h} be included before if it exists, we suggest the following
5597 AC_CHECK_HEADERS([foo.h])
5598 AC_CHECK_HEADERS([bar.h], [], [],
5605 The following variant generates smaller, faster @command{configure}
5606 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5608 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5609 @acindex{CHECK_HEADERS_ONCE}
5610 @cvindex HAVE_@var{header}
5611 For each given system header file @var{header-file} in the
5612 blank-separated argument list that exists, define
5613 @code{HAVE_@var{header-file}} (in all capitals).
5614 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5615 checking code at most once, so that @command{configure} is smaller and
5616 faster; but the checks cannot be conditionalized and are always done once,
5617 early during the @command{configure} run.
5621 @section Declarations
5622 @cindex Declaration, checking
5624 The following macros check for the declaration of variables and
5625 functions. If there is no macro specifically defined to check for a
5626 symbol you need, then you can use the general macros (@pxref{Generic
5627 Declarations}) or, for more complex tests, you may use
5628 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5631 * Particular Declarations:: Macros to check for certain declarations
5632 * Generic Declarations:: How to find other declarations
5635 @node Particular Declarations
5636 @subsection Particular Declaration Checks
5638 There are no specific macros for declarations.
5640 @node Generic Declarations
5641 @subsection Generic Declaration Checks
5643 These macros are used to find declarations not covered by the ``particular''
5646 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5647 @acindex{CHECK_DECL}
5648 If @var{symbol} (a function, variable, or constant) is not declared in
5649 @var{includes} and a declaration is needed, run the shell commands
5650 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5651 @var{includes} are specified, the default includes are used
5652 (@pxref{Default Includes}).
5654 This macro actually tests whether @var{symbol} is defined as a macro or
5655 can be used as an r-value, not whether it is really declared, because it
5656 is much safer to avoid
5657 introducing extra declarations when they are not needed.
5660 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5661 @acindex{CHECK_DECLS}
5662 @cvindex HAVE_DECL_@var{symbol}
5663 For each of the @var{symbols} (@emph{comma}-separated list), define
5664 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5665 @var{symbol} is declared, otherwise to @samp{0}. If
5666 @var{action-if-not-found} is given, it is additional shell code to
5667 execute when one of the function declarations is needed, otherwise
5668 @var{action-if-found} is executed.
5670 This macro uses an M4 list as first argument:
5672 AC_CHECK_DECLS([strdup])
5673 AC_CHECK_DECLS([strlen])
5674 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5677 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5678 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5679 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5680 @emph{sure} that the check was performed, use
5681 @code{HAVE_DECL_@var{symbol}} in @code{#if}:
5684 #if !HAVE_DECL_SYMBOL
5685 extern char *symbol;
5690 If the test may have not been performed, however, because it is safer
5691 @emph{not} to declare a symbol than to use a declaration that conflicts
5692 with the system's one, you should use:
5695 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5696 void *malloc (size_t *s);
5701 You fall into the second category only in extreme situations: either
5702 your files may be used without being configured, or they are used during
5703 the configuration. In most cases the traditional approach is enough.
5706 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5707 @acindex{CHECK_DECLS_ONCE}
5708 @cvindex HAVE_DECL_@var{symbol}
5709 For each of the @var{symbols} (@emph{comma}-separated list), define
5710 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5711 @var{symbol} is declared in the default include files, otherwise to
5712 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5713 generates the checking code at most once, so that @command{configure} is
5714 smaller and faster; but the checks cannot be conditionalized and are
5715 always done once, early during the @command{configure} run.
5721 @cindex Structure, checking
5723 The following macros check for the presence of certain members in C
5724 structures. If there is no macro specifically defined to check for a
5725 member you need, then you can use the general structure-member macros
5726 (@pxref{Generic Structures}) or, for more complex tests, you may use
5727 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5730 * Particular Structures:: Macros to check for certain structure members
5731 * Generic Structures:: How to find other structure members
5734 @node Particular Structures
5735 @subsection Particular Structure Checks
5737 The following macros check for certain structures or structure members.
5739 @defmac AC_STRUCT_DIRENT_D_INO
5740 @acindex{STRUCT_DIRENT_D_INO}
5741 @cvindex HAVE_STRUCT_DIRENT_D_INO
5742 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5743 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5744 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5746 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5747 @code{d_ino}, not whether its contents are always reliable.
5748 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5749 though current systems hide this detail from the user and never return
5750 zero @code{d_ino} values.
5751 Many current systems report an incorrect @code{d_ino} for a directory
5752 entry that is a mount point.
5755 @defmac AC_STRUCT_DIRENT_D_TYPE
5756 @acindex{STRUCT_DIRENT_D_TYPE}
5757 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5758 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5759 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5760 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5763 @defmac AC_STRUCT_ST_BLKSIZE
5764 @acindex{STRUCT_ST_BLKSIZE}
5765 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5766 @cvindex HAVE_ST_BLKSIZE
5767 If @code{struct stat} contains an @code{st_blksize} member, define
5768 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5769 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5770 the future. This macro is obsoleted, and should be replaced by
5773 AC_CHECK_MEMBERS([struct stat.st_blksize])
5777 @defmac AC_STRUCT_ST_BLOCKS
5778 @acindex{STRUCT_ST_BLOCKS}
5779 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5780 @cvindex HAVE_ST_BLOCKS
5782 If @code{struct stat} contains an @code{st_blocks} member, define
5783 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5784 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5785 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5789 @defmac AC_STRUCT_ST_RDEV
5790 @acindex{STRUCT_ST_RDEV}
5791 @cvindex HAVE_ST_RDEV
5792 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5793 If @code{struct stat} contains an @code{st_rdev} member, define
5794 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5795 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5796 in the future. Actually, even the new macro is obsolete and should be
5799 AC_CHECK_MEMBERS([struct stat.st_rdev])
5803 @defmac AC_STRUCT_TM
5805 @cvindex TM_IN_SYS_TIME
5807 @hdrindex{sys/time.h}
5808 If @file{time.h} does not define @code{struct tm}, define
5809 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5810 had better define @code{struct tm}.
5812 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5813 current systems. New programs need not use this macro.
5816 @defmac AC_STRUCT_TIMEZONE
5817 @acindex{STRUCT_TIMEZONE}
5818 @cvindex HAVE_TM_ZONE
5819 @cvindex HAVE_TZNAME
5820 Figure out how to get the current timezone. If @code{struct tm} has a
5821 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5822 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5823 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5824 define @code{HAVE_DECL_TZNAME}.
5827 @node Generic Structures
5828 @subsection Generic Structure Checks
5830 These macros are used to find structure members not covered by the
5831 ``particular'' test macros.
5833 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5834 @acindex{CHECK_MEMBER}
5835 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5836 If no @var{includes} are specified, the default includes are used
5837 (@pxref{Default Includes}).
5840 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5841 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5845 You can use this macro for submembers:
5848 AC_CHECK_MEMBER(struct top.middle.bot)
5852 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5853 @acindex{CHECK_MEMBERS}
5854 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5855 @var{members} using the previous macro. When @var{member} belongs to
5856 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5857 capitals, with spaces and dots replaced by underscores). If
5858 @var{action-if-found} is given, it is executed for each of the found
5859 members. If @var{action-if-not-found} is given, it is executed for each
5860 of the members that could not be found.
5862 This macro uses M4 lists:
5864 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5874 The following macros check for C types, either builtin or typedefs. If
5875 there is no macro specifically defined to check for a type you need, and
5876 you don't need to check for any special properties of it, then you can
5877 use a general type-check macro.
5880 * Particular Types:: Special handling to find certain types
5881 * Generic Types:: How to find other types
5884 @node Particular Types
5885 @subsection Particular Type Checks
5887 @hdrindex{sys/types.h}
5890 @hdrindex{inttypes.h}
5891 These macros check for particular C types in @file{sys/types.h},
5892 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5895 The Gnulib @code{stdint} module is an alternate way to define many of
5896 these symbols; it is useful if you prefer your code to assume a
5897 C99-or-better environment. @xref{Gnulib}.
5899 @defmac AC_TYPE_GETGROUPS
5900 @acindex{TYPE_GETGROUPS}
5901 @cvindex GETGROUPS_T
5902 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5903 is the base type of the array argument to @code{getgroups}.
5906 @defmac AC_TYPE_INT8_T
5907 @acindex{TYPE_INT8_T}
5908 @cvindex HAVE_INT8_T
5910 If @file{stdint.h} or @file{inttypes.h} does not define the type
5911 @code{int8_t}, define @code{int8_t} to a signed
5912 integer type that is exactly 8 bits wide and that uses two's complement
5913 representation, if such a type exists.
5916 @defmac AC_TYPE_INT16_T
5917 @acindex{TYPE_INT16_T}
5918 @cvindex HAVE_INT16_T
5920 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5923 @defmac AC_TYPE_INT32_T
5924 @acindex{TYPE_INT32_T}
5925 @cvindex HAVE_INT32_T
5927 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5930 @defmac AC_TYPE_INT64_T
5931 @acindex{TYPE_INT64_T}
5932 @cvindex HAVE_INT64_T
5934 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5937 @defmac AC_TYPE_INTMAX_T
5938 @acindex{TYPE_INTMAX_T}
5939 @cvindex HAVE_INTMAX_T
5941 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5942 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
5943 widest signed integer type.
5946 @defmac AC_TYPE_INTPTR_T
5947 @acindex{TYPE_INTPTR_T}
5948 @cvindex HAVE_INTPTR_T
5950 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5951 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
5952 signed integer type wide enough to hold a pointer, if such a type
5956 @defmac AC_TYPE_LONG_DOUBLE
5957 @acindex{TYPE_LONG_DOUBLE}
5958 @cvindex HAVE_LONG_DOUBLE
5959 If the C compiler supports a working @code{long double} type, define
5960 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
5961 same range and precision as @code{double}.
5963 This macro is obsolescent, as current C compilers support @code{long
5964 double}. New programs need not use this macro.
5967 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5968 @acindex{TYPE_LONG_DOUBLE_WIDER}
5969 @cvindex HAVE_LONG_DOUBLE_WIDER
5970 If the C compiler supports a working @code{long double} type with more
5971 range or precision than the @code{double} type, define
5972 @code{HAVE_LONG_DOUBLE_WIDER}.
5975 @defmac AC_TYPE_LONG_LONG_INT
5976 @acindex{TYPE_LONG_LONG_INT}
5977 @cvindex HAVE_LONG_LONG_INT
5978 If the C compiler supports a working @code{long long int} type, define
5979 @code{HAVE_LONG_LONG_INT}.
5982 @defmac AC_TYPE_MBSTATE_T
5983 @acindex{TYPE_MBSTATE_T}
5986 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5987 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5988 @code{<wchar.h>} does not declare it.
5991 @defmac AC_TYPE_MODE_T
5992 @acindex{TYPE_MODE_T}
5994 Define @code{mode_t} to a suitable type, if standard headers do not
5998 @defmac AC_TYPE_OFF_T
5999 @acindex{TYPE_OFF_T}
6001 Define @code{off_t} to a suitable type, if standard headers do not
6005 @defmac AC_TYPE_PID_T
6006 @acindex{TYPE_PID_T}
6008 Define @code{pid_t} to a suitable type, if standard headers do not
6012 @defmac AC_TYPE_SIGNAL
6013 @acindex{TYPE_SIGNAL}
6016 If @file{signal.h} declares @code{signal} as returning a pointer to a
6017 function returning @code{void}, define @code{RETSIGTYPE} to be
6018 @code{void}; otherwise, define it to be @code{int}.
6020 Define signal handlers as returning type @code{RETSIGTYPE}:
6033 @defmac AC_TYPE_SIZE_T
6034 @acindex{TYPE_SIZE_T}
6036 Define @code{size_t} to a suitable type, if standard headers do not
6040 @defmac AC_TYPE_SSIZE_T
6041 @acindex{TYPE_SSIZE_T}
6043 Define @code{ssize_t} to a suitable type, if standard headers do not
6047 @defmac AC_TYPE_UID_T
6048 @acindex{TYPE_UID_T}
6051 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6052 headers do not define them.
6055 @defmac AC_TYPE_UINT8_T
6056 @acindex{TYPE_UINT8_T}
6057 @cvindex HAVE_UINT8_T
6059 If @file{stdint.h} or @file{inttypes.h} does not define the type
6060 @code{uint8_t}, define @code{uint8_t} to an
6061 unsigned integer type that is exactly 8 bits wide, if such a type
6065 @defmac AC_TYPE_UINT16_T
6066 @acindex{TYPE_UINT16_T}
6067 @cvindex HAVE_UINT16_T
6069 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
6072 @defmac AC_TYPE_UINT32_T
6073 @acindex{TYPE_UINT32_T}
6074 @cvindex HAVE_UINT32_T
6076 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
6079 @defmac AC_TYPE_UINT64_T
6080 @acindex{TYPE_UINT64_T}
6081 @cvindex HAVE_UINT64_T
6083 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
6086 @defmac AC_TYPE_UINTMAX_T
6087 @acindex{TYPE_UINTMAX_T}
6088 @cvindex HAVE_UINTMAX_T
6090 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6091 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6092 widest unsigned integer type.
6095 @defmac AC_TYPE_UINTPTR_T
6096 @acindex{TYPE_UINTPTR_T}
6097 @cvindex HAVE_UINTPTR_T
6099 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6100 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6101 unsigned integer type wide enough to hold a pointer, if such a type
6105 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6106 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6107 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6108 If the C compiler supports a working @code{unsigned long long int} type,
6109 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6113 @subsection Generic Type Checks
6115 These macros are used to check for types not covered by the ``particular''
6118 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6119 @acindex{CHECK_TYPE}
6120 Check whether @var{type} is defined. It may be a compiler builtin type
6121 or defined by the @var{includes} (@pxref{Default Includes}).
6123 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
6124 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not). The
6125 same test is applied when compiling for C++, which means that in C++
6126 @var{type} should be a type-id and should not be an anonymous
6127 @samp{struct} or @samp{union}.
6131 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6132 @acindex{CHECK_TYPES}
6133 For each @var{type} of the @var{types} that is defined, define
6134 @code{HAVE_@var{type}} (in all capitals). Each @var{type} must follow
6135 the rules of @code{AC_CHECK_TYPE}. If no @var{includes} are
6136 specified, the default includes are used (@pxref{Default Includes}). If
6137 @var{action-if-found} is given, it is additional shell code to execute
6138 when one of the types is found. If @var{action-if-not-found} is given,
6139 it is executed when one of the types is not found.
6141 This macro uses M4 lists:
6143 AC_CHECK_TYPES([ptrdiff_t])
6144 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6149 Autoconf, up to 2.13, used to provide to another version of
6150 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6151 compatibility, a simple heuristic, quite safe but not totally, is
6152 implemented. In case of doubt, read the documentation of the former
6153 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6156 @node Compilers and Preprocessors
6157 @section Compilers and Preprocessors
6159 @cindex Preprocessors
6162 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6163 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6164 the output of the compiler, typically to the empty string if
6165 Posix and @samp{.exe} if a @acronym{DOS} variant.
6168 They also define the output variable @code{OBJEXT} based on the
6169 output of the compiler, after @file{.c} files have been excluded, typically
6170 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6172 If the compiler being used does not produce executables, the tests fail. If
6173 the executables can't be run, and cross-compilation is not enabled, they
6174 fail too. @xref{Manual Configuration}, for more on support for cross
6178 * Specific Compiler Characteristics:: Some portability issues
6179 * Generic Compiler Characteristics:: Language independent tests and features
6180 * C Compiler:: Checking its characteristics
6181 * C++ Compiler:: Likewise
6182 * Objective C Compiler:: Likewise
6183 * Erlang Compiler and Interpreter:: Likewise
6184 * Fortran Compiler:: Likewise
6187 @node Specific Compiler Characteristics
6188 @subsection Specific Compiler Characteristics
6190 Some compilers exhibit different behaviors.
6193 @item Static/Dynamic Expressions
6194 Autoconf relies on a trick to extract one bit of information from the C
6195 compiler: using negative array sizes. For instance the following
6196 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6200 static int test_array[sizeof (int) == 4 ? 1 : -1];
6204 To our knowledge, there is a single compiler that does not support this
6205 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6206 @acronym{HP-UX} 11.00.
6207 They incorrectly reject the above program with the diagnostic
6208 ``Variable-length arrays cannot have static storage.''
6209 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6210 not from the @code{? 1 : -1}, and
6211 Autoconf works around this problem by casting @code{sizeof (int)} to
6212 @code{long int} before comparing it.
6215 @node Generic Compiler Characteristics
6216 @subsection Generic Compiler Characteristics
6218 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @dvar{includes, default-includes})
6219 @acindex{CHECK_SIZEOF}
6220 Define @code{SIZEOF_@var{type-or-expr}} (@pxref{Standard Symbols}) to be
6221 the size in bytes of @var{type-or-expr}, which may be either a type or
6222 an expression returning a value that has a size. If the expression
6223 @samp{sizeof (@var{type-or-expr})} is invalid, the result is 0. If no
6224 @var{includes} are specified, the default includes are used
6225 (@pxref{Default Includes}).
6227 This macro now works even when cross-compiling. The @var{unused}
6228 argument was used when cross-compiling.
6230 For example, the call
6233 AC_CHECK_SIZEOF([int *])
6237 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6240 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6241 @acindex{CHECK_ALIGNOF}
6242 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6243 alignment in bytes of @var{type}. @samp{@var{type} y;} must be valid as
6244 a structure member declaration. If @samp{type} is unknown, the result
6245 is 0. If no @var{includes} are specified, the default includes are used
6246 (@pxref{Default Includes}).
6249 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails})
6250 @acindex{COMPUTE_INT}
6251 Store into the shell variable @var{var} the value of the integer
6252 @var{expression}. The
6253 value should fit in an initializer in a C variable of type @code{signed
6254 long}. To support cross compilation (in which case, the macro only works on
6255 hosts that use twos-complement arithmetic), it should be possible to evaluate
6256 the expression at compile-time. If no @var{includes} are specified, the default
6257 includes are used (@pxref{Default Includes}).
6259 Execute @var{action-if-fails} if the value cannot be determined correctly.
6262 @defmac AC_LANG_WERROR
6263 @acindex{LANG_WERROR}
6264 Normally Autoconf ignores warnings generated by the compiler, linker, and
6265 preprocessor. If this macro is used, warnings count as fatal
6266 errors for the current language. This macro is useful when the
6267 results of configuration are used where warnings are unacceptable; for
6268 instance, if parts of a program are built with the @acronym{GCC}
6270 option. If the whole program is built using @option{-Werror} it is
6271 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6278 OpenMP (@url{http://www.openmp.org/}) specifies extensions of C, C++,
6279 and Fortran that simplify optimization of shared memory parallelism,
6280 which is a common problem on multicore CPUs.
6282 If the current language is C, the macro @code{AC_OPENMP} sets the
6283 variable @code{OPENMP_CFLAGS} to the C compiler flags needed for
6284 supporting OpenMP@. @code{OPENMP_CFLAGS} is set to empty if the
6285 compiler already supports OpenMP, if it has no way to activate OpenMP
6286 support, or if the user rejects OpenMP support by invoking
6287 @samp{configure} with the @samp{--disable-openmp} option.
6289 @code{OPENMP_CFLAGS} needs to be used when compiling programs, when
6290 preprocessing program source, and when linking programs. Therefore you
6291 need to add @code{$(OPENMP_CFLAGS)} to the @code{CFLAGS} of C programs
6292 that use OpenMP@. If you preprocess OpenMP-specific C code, you also
6293 need to add @code{$(OPENMP_CFLAGS)} to @code{CPPFLAGS}. The presence of
6294 OpenMP support is revealed at compile time by the preprocessor macro
6297 Linking a program with @code{OPENMP_CFLAGS} typically adds one more
6298 shared library to the program's dependencies, so its use is recommended
6299 only on programs that actually require OpenMP.
6301 If the current language is C++, @code{AC_OPENMP} sets the variable
6302 @code{OPENMP_CXXFLAGS}, suitably for the C++ compiler. The same remarks
6305 If the current language is Fortran 77 or Fortran, @code{AC_OPENMP} sets
6306 the variable @code{OPENMP_FFLAGS} or @code{OPENMP_FCFLAGS},
6307 respectively. Similar remarks as for C hold, except that
6308 @code{CPPFLAGS} is not used for Fortran, and no preprocessor macro
6309 signals OpenMP support.
6313 @subsection C Compiler Characteristics
6315 The following macros provide ways to find and exercise a C Compiler.
6316 There are a few constructs that ought to be avoided, but do not deserve
6317 being checked for, since they can easily be worked around.
6320 @item Don't use lines containing solitary backslashes
6321 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6322 @acronym{HP-UX} 10.20,
6323 11.00, and 11i). When given the following source:
6328 * A comment with backslash-newlines in it. %@{ %@} *\
6332 " A string with backslash-newlines in it %@{ %@} \\
6334 char apostrophe = '\\
6342 the compiler incorrectly fails with the diagnostics ``Non-terminating
6343 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6344 Removing the lines with solitary backslashes solves the problem.
6346 @item Don't compile several files at once if output matters to you
6347 Some compilers, such as @acronym{HP}'s, report names of files being
6348 compiled when given more than one file operand. For instance:
6357 This can cause problems if you observe the output of the compiler to
6358 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6359 b.o} solves the issue.
6361 @item Don't rely on @code{#error} failing
6362 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6363 simply emits a diagnostic and continues, exiting successfully. So,
6364 instead of an error directive like @code{#error "Unsupported word size"}
6365 it is more portable to use an invalid directive like @code{#Unsupported
6366 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6367 OK, since installers with inadequate compilers like @sc{irix} can simply
6368 examine these compilers' diagnostic output.
6370 @item Don't rely on correct @code{#line} support
6371 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6372 diagnoses @code{#line} directives whose line
6373 numbers are greater than 32767. Nothing in Posix
6374 makes this invalid. That is why Autoconf stopped issuing
6375 @code{#line} directives.
6378 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6382 Determine a C compiler to use. If @code{CC} is not already set in the
6383 environment, check for @code{gcc} and @code{cc}, then for other C
6384 compilers. Set output variable @code{CC} to the name of the compiler
6387 This macro may, however, be invoked with an optional first argument
6388 which, if specified, must be a blank-separated list of C compilers to
6389 search for. This just gives the user an opportunity to specify an
6390 alternative search list for the C compiler. For example, if you didn't
6391 like the default order, then you could invoke @code{AC_PROG_CC} like
6395 AC_PROG_CC([gcc cl cc])
6398 If the C compiler does not handle function prototypes correctly by
6399 default, try to add an option to output variable @code{CC} to make it
6400 so. This macro tries various options that select standard-conformance
6401 modes on various systems.
6403 After calling this macro you can check whether the C compiler has been
6404 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6406 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6407 @code{AC_C_PROTOTYPES} below.
6409 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6410 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6411 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6412 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6416 @defmac AC_PROG_CC_C_O
6417 @acindex{PROG_CC_C_O}
6418 @cvindex NO_MINUS_C_MINUS_O
6419 If the C compiler does not accept the @option{-c} and @option{-o} options
6420 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6421 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6422 the first @code{cc} in the path. The test fails if one fails. This
6423 macro was created for @acronym{GNU} Make to choose the default C compilation
6431 Set output variable @code{CPP} to a command that runs the
6432 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6433 It is only portable to run @code{CPP} on files with a @file{.c}
6436 Some preprocessors don't indicate missing include files by the error
6437 status. For such preprocessors an internal variable is set that causes
6438 other macros to check the standard error from the preprocessor and
6439 consider the test failed if any warnings have been reported.
6440 For most preprocessors, though, warnings do not cause include-file
6441 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6444 @defmac AC_PROG_CPP_WERROR
6445 @acindex{PROG_CPP_WERROR}
6447 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6448 preprocessor as errors even if the preprocessor exit status indicates
6449 success. This is useful for avoiding headers that generate mandatory
6450 warnings, such as deprecation notices.
6454 The following macros check for C compiler or machine architecture
6455 features. To check for characteristics not listed here, use
6456 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6457 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6459 @defmac AC_PROG_CC_STDC
6460 @acindex{PROG_CC_STDC}
6461 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6462 C99), try to add an option to output variable @code{CC} to make it work.
6463 If the compiler does not support C99, fall back to supporting
6464 @acronym{ANSI} C89 (@acronym{ISO} C90).
6466 After calling this macro you can check whether the C compiler has been
6467 set to accept Standard C; if not, the shell variable
6468 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6471 @defmac AC_PROG_CC_C89
6472 @acindex{PROG_CC_C89}
6473 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6474 default, try to add an option to output variable @code{CC} to make it
6475 so. This macro tries various options that select @acronym{ANSI} C89 on
6476 some system or another. It considers the compiler to be in
6477 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6479 After calling this macro you can check whether the C compiler has been
6480 set to accept @acronym{ANSI} C89; if not, the shell variable
6481 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6483 This macro is called automatically by @code{AC_PROG_CC}.
6486 @defmac AC_PROG_CC_C99
6487 @acindex{PROG_CC_C99}
6488 If the C compiler is not in C99 mode by default, try to add an
6489 option to output variable @code{CC} to make it so. This macro tries
6490 various options that select C99 on some system or another. It
6491 considers the compiler to be in C99 mode if it handles @code{_Bool},
6492 @code{//} comments, flexible array members, @code{inline}, signed and
6493 unsigned @code{long long int}, mixed code and declarations, named
6494 initialization of structs,
6495 @code{restrict}, @code{va_copy}, varargs macros, variable declarations
6496 in @code{for} loops, and variable length arrays.
6498 After calling this macro you can check whether the C compiler has been
6499 set to accept C99; if not, the shell variable
6500 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6503 @defmac AC_C_BACKSLASH_A
6504 @acindex{HAVE_C_BACKSLASH_A}
6505 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6508 This macro is obsolescent, as current C compilers understand @samp{\a}.
6509 New programs need not use this macro.
6512 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown}, @ovar{action-if-universal})
6513 @acindex{C_BIGENDIAN}
6514 @cvindex WORDS_BIGENDIAN
6516 If words are stored with the most significant byte first (like Motorola
6517 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6518 the least significant byte first (like Intel and VAX CPUs), execute
6519 @var{action-if-false}.
6521 This macro runs a test-case if endianness cannot be determined from the
6522 system header files. When cross-compiling, the test-case is not run but
6523 grep'ed for some magic values. @var{action-if-unknown} is executed if
6524 the latter case fails to determine the byte sex of the host system.
6526 In some cases a single run of a compiler can generate code for multiple
6527 architectures. This can happen, for example, when generating Mac OS X
6528 universal binary files, which work on both PowerPC and Intel
6529 architectures. In this case, the different variants might be for
6530 different architectures whose endiannesses differ. If
6531 @command{configure} detects this, it executes @var{action-if-universal}
6532 instead of @var{action-if-unknown}.
6534 The default for @var{action-if-true} is to define
6535 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6536 nothing. The default for @var{action-if-unknown} is to
6537 abort configure and tell the installer how to bypass this test.
6538 And finally, the default for @var{action-if-universal} is to define
6539 @samp{WORDS_BIGENDIAN} or not, depending on the architecture that the
6540 code is being generated for.
6542 If you use this macro without specifying @var{action-if-universal}, you
6543 should also use @code{AC_CONFIG_HEADERS}; otherwise
6544 @samp{WORDS_BIGENDIAN} may be set incorrectly for Mac OS X universal
6551 If the C compiler does not fully support the @code{const} keyword,
6552 define @code{const} to be empty. Some C compilers that do
6553 not define @code{__STDC__} do support @code{const}; some compilers that
6554 define @code{__STDC__} do not completely support @code{const}. Programs
6555 can simply use @code{const} as if every C compiler supported it; for
6556 those that don't, the makefile or configuration header file
6557 defines it as empty.
6559 Occasionally installers use a C++ compiler to compile C code, typically
6560 because they lack a C compiler. This causes problems with @code{const},
6561 because C and C++ treat @code{const} differently. For example:
6568 is valid in C but not in C++. These differences unfortunately cannot be
6569 papered over by defining @code{const} to be empty.
6571 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6572 as this generally yields better results in practice. However, using a
6573 C++ compiler to compile C code is not recommended or supported, and
6574 installers who run into trouble in this area should get a C compiler
6575 like @acronym{GCC} to compile their C code.
6577 This macro is obsolescent, as current C compilers support @code{const}.
6578 New programs need not use this macro.
6581 @defmac AC_C_RESTRICT
6582 @acindex{C_RESTRICT}
6584 If the C compiler recognizes a variant spelling for the @code{restrict}
6585 keyword (@code{__restrict}, @code{__restrict__}, or @code{_Restrict}),
6586 then define @code{restrict} to that; this is more likely to do the right
6587 thing with compilers that support language variants where plain
6588 @code{restrict} is not a keyword. Otherwise, if the C compiler
6589 recognizes the @code{restrict} keyword, don't do anything.
6590 Otherwise, define @code{restrict} to be empty.
6591 Thus, programs may simply use @code{restrict} as if every C compiler
6592 supported it; for those that do not, the makefile
6593 or configuration header defines it away.
6595 Although support in C++ for the @code{restrict} keyword is not
6596 required, several C++ compilers do accept the keyword.
6597 This macro works for them, too.
6600 @defmac AC_C_VOLATILE
6601 @acindex{C_VOLATILE}
6603 If the C compiler does not understand the keyword @code{volatile},
6604 define @code{volatile} to be empty. Programs can simply use
6605 @code{volatile} as if every C compiler supported it; for those that do
6606 not, the makefile or configuration header defines it as
6609 If the correctness of your program depends on the semantics of
6610 @code{volatile}, simply defining it to be empty does, in a sense, break
6611 your code. However, given that the compiler does not support
6612 @code{volatile}, you are at its mercy anyway. At least your
6613 program compiles, when it wouldn't before.
6614 @xref{Volatile Objects}, for more about @code{volatile}.
6616 In general, the @code{volatile} keyword is a standard C feature, so
6617 you might expect that @code{volatile} is available only when
6618 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6619 support volatile, but does not define @code{__STDC__}.
6621 This macro is obsolescent, as current C compilers support @code{volatile}.
6622 New programs need not use this macro.
6628 If the C compiler supports the keyword @code{inline}, do nothing.
6629 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6630 if it accepts one of those, otherwise define @code{inline} to be empty.
6633 @defmac AC_C_CHAR_UNSIGNED
6634 @acindex{C_CHAR_UNSIGNED}
6635 @cvindex __CHAR_UNSIGNED__
6636 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6637 unless the C compiler predefines it.
6640 @defmac AC_C_STRINGIZE
6641 @acindex{C_STRINGIZE}
6642 @cvindex HAVE_STRINGIZE
6643 If the C preprocessor supports the stringizing operator, define
6644 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6645 found in macros such as this:
6651 This macro is obsolescent, as current C compilers support the
6652 stringizing operator. New programs need not use this macro.
6655 @defmac AC_C_FLEXIBLE_ARRAY_MEMBER
6656 @acindex{C_FLEXIBLE_ARRAY_MEMBER}
6657 @cvindex FLEXIBLE_ARRAY_MEMBER
6658 If the C compiler supports flexible array members, define
6659 @code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1.
6660 That way, a declaration like this:
6666 double val[FLEXIBLE_ARRAY_MEMBER];
6671 will let applications use the ``struct hack'' even with compilers that
6672 do not support flexible array members. To allocate and use such an
6673 object, you can use code like this:
6677 size_t n = compute_value_count ();
6679 malloc (offsetof (struct s, val)
6680 + n * sizeof (double));
6682 for (i = 0; i < n; i++)
6683 p->val[i] = compute_value (i);
6687 @defmac AC_C_VARARRAYS
6688 @acindex{C_VARARRAYS}
6689 @cvindex HAVE_C_VARARRAYS
6690 If the C compiler supports variable-length arrays, define
6691 @code{HAVE_C_VARARRAYS}. A variable-length array is an array of automatic
6692 storage duration whose length is determined at run time, when the array
6698 @cvindex HAVE_TYPEOF
6700 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6702 through a different spelling of the keyword (e.g., @code{__typeof__}),
6703 define @code{HAVE_TYPEOF}. If the support is available only through a
6704 different spelling, define @code{typeof} to that spelling.
6707 @defmac AC_C_PROTOTYPES
6708 @acindex{C_PROTOTYPES}
6710 @cvindex __PROTOTYPES
6712 If function prototypes are understood by the compiler (as determined by
6713 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6714 Defining @code{__PROTOTYPES} is for the benefit of
6715 header files that cannot use macros that infringe on user name space.
6717 This macro is obsolescent, as current C compilers support prototypes.
6718 New programs need not use this macro.
6721 @defmac AC_PROG_GCC_TRADITIONAL
6722 @acindex{PROG_GCC_TRADITIONAL}
6724 Add @option{-traditional} to output variable @code{CC} if using the
6725 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6726 @option{-traditional}. That usually happens when the fixed header files
6727 have not been installed on an old system.
6729 This macro is obsolescent, since current versions of the @acronym{GNU} C
6730 compiler fix the header files automatically when installed.
6735 @subsection C++ Compiler Characteristics
6738 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6742 Determine a C++ compiler to use. Check whether the environment variable
6743 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6744 variable @code{CXX} to its value.
6746 Otherwise, if the macro is invoked without an argument, then search for
6747 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6748 then other names). If none of those checks succeed, then as a last
6749 resort set @code{CXX} to @code{g++}.
6751 This macro may, however, be invoked with an optional first argument
6752 which, if specified, must be a blank-separated list of C++ compilers to
6753 search for. This just gives the user an opportunity to specify an
6754 alternative search list for the C++ compiler. For example, if you
6755 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6759 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6762 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6763 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6764 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6765 systems where G++ does not accept @option{-g}), or @option{-g} for other
6769 @defmac AC_PROG_CXXCPP
6770 @acindex{PROG_CXXCPP}
6772 Set output variable @code{CXXCPP} to a command that runs the C++
6773 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6774 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6775 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6777 Some preprocessors don't indicate missing include files by the error
6778 status. For such preprocessors an internal variable is set that causes
6779 other macros to check the standard error from the preprocessor and
6780 consider the test failed if any warnings have been reported. However,
6781 it is not known whether such broken preprocessors exist for C++.
6784 @defmac AC_PROG_CXX_C_O
6785 @acindex{PROG_CXX_C_O}
6786 @cvindex CXX_NO_MINUS_C_MINUS_O
6787 Test whether the C++ compiler accepts the options @option{-c} and
6788 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6793 @node Objective C Compiler
6794 @subsection Objective C Compiler Characteristics
6797 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6801 Determine an Objective C compiler to use. If @code{OBJC} is not already
6802 set in the environment, check for Objective C compilers. Set output
6803 variable @code{OBJC} to the name of the compiler found.
6805 This macro may, however, be invoked with an optional first argument
6806 which, if specified, must be a blank-separated list of Objective C compilers to
6807 search for. This just gives the user an opportunity to specify an
6808 alternative search list for the Objective C compiler. For example, if you
6809 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6813 AC_PROG_OBJC([gcc objcc objc])
6816 If using the @acronym{GNU} Objective C compiler, set shell variable
6817 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6818 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6819 compiler (@option{-O2} on systems where @command{gcc} does not accept
6820 @option{-g}), or @option{-g} for other compilers.
6823 @defmac AC_PROG_OBJCPP
6824 @acindex{PROG_OBJCPP}
6826 Set output variable @code{OBJCPP} to a command that runs the Objective C
6827 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6831 @node Erlang Compiler and Interpreter
6832 @subsection Erlang Compiler and Interpreter Characteristics
6835 Autoconf defines the following macros for determining paths to the essential
6836 Erlang/OTP programs:
6838 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6839 @acindex{ERLANG_PATH_ERLC}
6842 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6843 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6844 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6845 is not set in the environment, set it to an empty value.
6847 The two optional arguments have the same meaning as the two last arguments of
6848 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
6849 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6853 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6857 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6858 @acindex{ERLANG_NEED_ERLC}
6859 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6860 error message and exits the @command{configure} script if the @command{erlc}
6861 program is not found.
6864 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6865 @acindex{ERLANG_PATH_ERL}
6867 Determine an Erlang interpreter to use. If @code{ERL} is not already set in the
6868 environment, check for @command{erl}. Set output variable @code{ERL} to the
6869 complete path of the interpreter command found.
6871 The two optional arguments have the same meaning as the two last arguments of
6872 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
6873 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6877 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6881 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6882 @acindex{ERLANG_NEED_ERL}
6883 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6884 error message and exits the @command{configure} script if the @command{erl}
6885 program is not found.
6889 @node Fortran Compiler
6890 @subsection Fortran Compiler Characteristics
6894 The Autoconf Fortran support is divided into two categories: legacy
6895 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6896 The former are intended for traditional Fortran 77 code, and have output
6897 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6898 are for newer programs that can (or must) compile under the newer
6899 Fortran standards, and have output variables like @code{FC},
6900 @code{FCFLAGS}, and @code{FCLIBS}.
6902 Except for two new macros @code{AC_FC_SRCEXT} and
6903 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6904 behave almost identically, and so they are documented together in this
6908 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6912 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6913 set in the environment, then check for @code{g77} and @code{f77}, and
6914 then some other names. Set the output variable @code{F77} to the name
6915 of the compiler found.
6917 This macro may, however, be invoked with an optional first argument
6918 which, if specified, must be a blank-separated list of Fortran 77
6919 compilers to search for. This just gives the user an opportunity to
6920 specify an alternative search list for the Fortran 77 compiler. For
6921 example, if you didn't like the default order, then you could invoke
6922 @code{AC_PROG_F77} like this:
6925 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6928 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6929 set the shell variable @code{G77} to @samp{yes}.
6930 If the output variable @code{FFLAGS} was not already set in the
6931 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6932 where @code{g77} does not accept @option{-g}). Otherwise, set
6933 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6936 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6940 Determine a Fortran compiler to use. If @code{FC} is not already set in
6941 the environment, then @code{dialect} is a hint to indicate what Fortran
6942 dialect to search for; the default is to search for the newest available
6943 dialect. Set the output variable @code{FC} to the name of the compiler
6946 By default, newer dialects are preferred over older dialects, but if
6947 @code{dialect} is specified then older dialects are preferred starting
6948 with the specified dialect. @code{dialect} can currently be one of
6949 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6950 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6951 and no attempt is made to guarantee that a particular language standard
6952 is actually supported. Thus, it is preferable that you avoid the
6953 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6954 the latest Fortran standard.
6956 This macro may, alternatively, be invoked with an optional first argument
6957 which, if specified, must be a blank-separated list of Fortran
6958 compilers to search for, just as in @code{AC_PROG_F77}.
6960 If the output variable @code{FCFLAGS} was not already set in the
6961 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6962 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6963 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6966 @defmac AC_PROG_F77_C_O
6967 @defmacx AC_PROG_FC_C_O
6968 @acindex{PROG_F77_C_O}
6969 @acindex{PROG_FC_C_O}
6970 @cvindex F77_NO_MINUS_C_MINUS_O
6971 @cvindex FC_NO_MINUS_C_MINUS_O
6972 Test whether the Fortran compiler accepts the options @option{-c} and
6973 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6974 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6977 The following macros check for Fortran compiler characteristics.
6978 To check for characteristics not listed here, use
6979 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6980 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6981 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6982 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6985 @defmac AC_F77_LIBRARY_LDFLAGS
6986 @defmacx AC_FC_LIBRARY_LDFLAGS
6987 @acindex{F77_LIBRARY_LDFLAGS}
6989 @acindex{FC_LIBRARY_LDFLAGS}
6991 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6992 @dfn{Fortran intrinsic and runtime libraries} that are required to
6993 successfully link a Fortran program or shared library. The output
6994 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6995 should be included after @code{LIBS} when linking).
6997 This macro is intended to be used in those situations when it is
6998 necessary to mix, e.g., C++ and Fortran source code in a single
6999 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
7000 automake, @acronym{GNU} Automake}).
7002 For example, if object files from a C++ and Fortran compiler must be
7003 linked together, then the C++ compiler/linker must be used for linking
7004 (since special C++-ish things need to happen at link time like calling
7005 global constructors, instantiating templates, enabling exception
7008 However, the Fortran intrinsic and runtime libraries must be linked in
7009 as well, but the C++ compiler/linker doesn't know by default how to add
7010 these Fortran 77 libraries. Hence, this macro was created to determine
7011 these Fortran libraries.
7013 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7014 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
7015 link C/C++ with Fortran; see below.
7018 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7019 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
7020 @acindex{F77_DUMMY_MAIN}
7021 @cvindex F77_DUMMY_MAIN
7022 With many compilers, the Fortran libraries detected by
7023 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
7024 their own @code{main} entry function that initializes things like
7025 Fortran I/O, and which then calls a user-provided entry function named
7026 (say) @code{MAIN__} to run the user's program. The
7027 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
7028 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
7031 When using Fortran for purely numerical functions (no I/O, etc.)@: often
7032 one prefers to provide one's own @code{main} and skip the Fortran
7033 library initializations. In this case, however, one may still need to
7034 provide a dummy @code{MAIN__} routine in order to prevent linking errors
7035 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
7036 detects whether any such routine is @emph{required} for linking, and
7037 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
7038 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
7039 was found, and @code{none} when no such dummy main is needed.
7041 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
7042 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
7043 @emph{if} it is required. @var{action-if-not-found} defaults to
7044 exiting with an error.
7046 In order to link with Fortran routines, the user's C/C++ program should
7047 then include the following code to define the dummy main if it is
7051 #ifdef F77_DUMMY_MAIN
7055 int F77_DUMMY_MAIN() @{ return 1; @}
7059 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7061 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
7062 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
7063 explicitly unless one wants to change the default actions.
7072 As discussed above, many Fortran libraries allow you to provide an entry
7073 point called (say) @code{MAIN__} instead of the usual @code{main}, which
7074 is then called by a @code{main} function in the Fortran libraries that
7075 initializes things like Fortran I/O@. The
7076 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
7077 @emph{possible} to utilize such an alternate main function, and defines
7078 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
7079 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
7080 simply defined to @code{main}.)
7082 Thus, when calling Fortran routines from C that perform things like I/O,
7083 one should use this macro and name the "main" function
7084 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
7087 @defmac AC_F77_WRAPPERS
7088 @defmacx AC_FC_WRAPPERS
7089 @acindex{F77_WRAPPERS}
7092 @acindex{FC_WRAPPERS}
7095 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
7096 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
7097 mangle the names of C/C++ identifiers, and identifiers with underscores,
7098 respectively, so that they match the name-mangling scheme used by the
7101 Fortran is case-insensitive, and in order to achieve this the Fortran
7102 compiler converts all identifiers into a canonical case and format. To
7103 call a Fortran subroutine from C or to write a C function that is
7104 callable from Fortran, the C program must explicitly use identifiers in
7105 the format expected by the Fortran compiler. In order to do this, one
7106 simply wraps all C identifiers in one of the macros provided by
7107 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
7108 you have the following Fortran 77 subroutine:
7111 subroutine foobar (x, y)
7112 double precision x, y
7118 You would then declare its prototype in C or C++ as:
7121 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7123 extern "C" /* prevent C++ name mangling */
7125 void FOOBAR_F77(double *x, double *y);
7128 Note that we pass both the lowercase and uppercase versions of the
7129 function name to @code{F77_FUNC} so that it can select the right one.
7130 Note also that all parameters to Fortran 77 routines are passed as
7131 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7134 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7136 Although Autoconf tries to be intelligent about detecting the
7137 name-mangling scheme of the Fortran compiler, there may be Fortran
7138 compilers that it doesn't support yet. In this case, the above code
7139 generates a compile-time error, but some other behavior
7140 (e.g., disabling Fortran-related features) can be induced by checking
7141 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7143 Now, to call that routine from a C program, we would do something like:
7147 double x = 2.7183, y;
7148 FOOBAR_F77 (&x, &y);
7152 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7153 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7154 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7155 because some Fortran compilers mangle names differently if they contain
7159 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7160 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7163 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7164 hold the mangled version @var{name} according to the rules of the
7165 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7166 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7167 supplied, the shell variable is simply @var{name}. The purpose of
7168 this macro is to give the caller a way to access the name-mangling
7169 information other than through the C preprocessor as above, for example,
7170 to call Fortran routines from some language other than C/C++.
7173 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7175 By default, the @code{FC} macros perform their tests using a @file{.f}
7176 extension for source-code files. Some compilers, however, only enable
7177 newer language features for appropriately named files, e.g., Fortran 90
7178 features only for @file{.f90} files. On the other hand, some other
7179 compilers expect all source files to end in @file{.f} and require
7180 special flags to support other file name extensions. The
7181 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7183 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7184 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7185 contain the dot). If any special compiler flags are needed for this, it
7186 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7187 extension and these flags are then used for all subsequent @code{FC} tests
7188 (until @code{AC_FC_SRCEXT} is called again).
7190 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7191 @file{.f90} extension in future tests, and it would set a
7192 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7193 to compile such files.
7195 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7196 @code{FCFLAGS}, for two reasons based on the limitations of some
7197 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7198 time, so files with different extensions must be compiled separately.
7199 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7200 the source-code file name when compiling. So, continuing the example
7201 above, you might compile a @file{foo.f90} file in your makefile with the
7206 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7209 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7210 extension, it calls @var{action-if-success} (defaults to nothing). If
7211 it fails, and cannot find a way to make the @code{FC} compiler accept such
7212 files, it calls @var{action-if-failure} (defaults to exiting with an
7217 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7218 @acindex{FC_FREEFORM}
7220 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7221 (@code{$FC}) allows free-format source code (as opposed to the older
7222 fixed-format style from Fortran 77). If necessary, it may add some
7223 additional flags to @code{FCFLAGS}.
7225 This macro is most important if you are using the default @file{.f}
7226 extension, since many compilers interpret this extension as indicating
7227 fixed-format source unless an additional flag is supplied. If you
7228 specify a different extension with @code{AC_FC_SRCEXT}, such as
7229 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7230 succeeds without modifying @code{FCFLAGS}.
7232 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7233 calls @var{action-if-success} (defaults to nothing). If it fails, it
7234 calls @var{action-if-failure} (defaults to exiting with an error
7238 @node System Services
7239 @section System Services
7241 The following macros check for operating system services or capabilities.
7246 @cindex X Window System
7247 Try to locate the X Window System include files and libraries. If the
7248 user gave the command line options @option{--x-includes=@var{dir}} and
7249 @option{--x-libraries=@var{dir}}, use those directories.
7251 If either or both were not given, get the missing values by running
7252 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7253 environment variable) on a trivial @file{Imakefile} and examining the
7254 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7255 disables this method.
7257 If this method fails to find the X Window System, @command{configure}
7258 looks for the files in several directories where they often reside.
7259 If either method is successful, set the shell variables
7260 @code{x_includes} and @code{x_libraries} to their locations, unless they
7261 are in directories the compiler searches by default.
7263 If both methods fail, or the user gave the command line option
7264 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7265 otherwise set it to the empty string.
7268 @defmac AC_PATH_XTRA
7272 @ovindex X_EXTRA_LIBS
7274 @cvindex X_DISPLAY_MISSING
7275 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7276 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7277 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7280 This macro also checks for special libraries that some systems need in
7281 order to compile X programs. It adds any that the system needs to
7282 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7283 libraries that need to be linked with before @option{-lX11}, and adds
7284 any found to the output variable @code{X_PRE_LIBS}.
7286 @c This is an incomplete kludge. Make a real way to do it.
7287 @c If you need to check for other X functions or libraries yourself, then
7288 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7289 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7292 @defmac AC_SYS_INTERPRETER
7293 @acindex{SYS_INTERPRETER}
7294 Check whether the system supports starting scripts with a line of the
7295 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7296 After running this macro, shell code in @file{configure.ac} can check
7297 the shell variable @code{interpval}; it is set to @samp{yes}
7298 if the system supports @samp{#!}, @samp{no} if not.
7301 @defmac AC_SYS_LARGEFILE
7302 @acindex{SYS_LARGEFILE}
7303 @cvindex _FILE_OFFSET_BITS
7304 @cvindex _LARGE_FILES
7306 @cindex Large file support
7309 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7310 large-file support}. On some hosts, one must use special compiler
7311 options to build programs that can access large files. Append any such
7312 options to the output variable @code{CC}. Define
7313 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7315 Large-file support can be disabled by configuring with the
7316 @option{--disable-largefile} option.
7318 If you use this macro, check that your program works even when
7319 @code{off_t} is wider than @code{long int}, since this is common when
7320 large-file support is enabled. For example, it is not correct to print
7321 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7324 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7325 replace their C counterparts @code{fseek} and @code{ftell} that do not
7326 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7327 prototypes available when using them and large-file support is
7331 @defmac AC_SYS_LONG_FILE_NAMES
7332 @acindex{SYS_LONG_FILE_NAMES}
7333 @cvindex HAVE_LONG_FILE_NAMES
7334 If the system supports file names longer than 14 characters, define
7335 @code{HAVE_LONG_FILE_NAMES}.
7338 @defmac AC_SYS_POSIX_TERMIOS
7339 @acindex{SYS_POSIX_TERMIOS}
7340 @cindex Posix termios headers
7341 @cindex termios Posix headers
7342 Check to see if the Posix termios headers and functions are available on the
7343 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7344 @samp{yes}. If not, set the variable to @samp{no}.
7347 @node Posix Variants
7348 @section Posix Variants
7350 The following macros check for certain operating systems that need
7351 special treatment for some programs, due to exceptional oddities in
7352 their header files or libraries. These macros are warts; they will be
7353 replaced by a more systematic approach, based on the functions they make
7354 available or the environments they provide.
7358 @cvindex _ALL_SOURCE
7359 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7360 Allows the use of some @acronym{BSD}
7361 functions. Should be called before any macros that run the C compiler.
7364 @defmac AC_GNU_SOURCE
7365 @acindex{GNU_SOURCE}
7366 @cvindex _GNU_SOURCE
7367 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7368 Allows the use of some @acronym{GNU} functions. Should be called
7369 before any macros that run the C compiler.
7372 @defmac AC_ISC_POSIX
7375 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7376 variable @code{LIBS} if necessary for Posix facilities. Call this
7377 after @code{AC_PROG_CC} and before any other macros that use Posix
7380 This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun
7381 dropped support for it on 2006-07-23. New programs need not use this
7388 @cvindex _POSIX_SOURCE
7389 @cvindex _POSIX_1_SOURCE
7390 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7391 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
7392 facilities. Should be called before any macros that run the C compiler.
7395 @defmac AC_USE_SYSTEM_EXTENSIONS
7396 @acindex{USE_SYSTEM_EXTENSIONS}
7397 @cvindex _ALL_SOURCE
7398 @cvindex _GNU_SOURCE
7400 @cvindex _POSIX_1_SOURCE
7401 @cvindex _POSIX_PTHREAD_SEMANTICS
7402 @cvindex _POSIX_SOURCE
7403 @cvindex _TANDEM_SOURCE
7404 @cvindex __EXTENSIONS__
7405 If possible, enable extensions to Posix on hosts that normally disable
7406 the extensions, typically due to standards-conformance namespace issues.
7407 This may involve defining @code{__EXTENSIONS__} and
7408 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris.
7409 It also defines @code{_TANDEM_SOURCE} for the @acronym{HP} NonStop platform.
7410 This macro also has the combined effects of @code{AC_GNU_SOURCE},
7411 @code{AC_AIX}, and @code{AC_MINIX}.
7415 @node Erlang Libraries
7416 @section Erlang Libraries
7417 @cindex Erlang, Library, checking
7419 The following macros check for an installation of Erlang/OTP, and for the
7420 presence of certain Erlang libraries. All those macros require the
7421 configuration of an Erlang interpreter and an Erlang compiler
7422 (@pxref{Erlang Compiler and Interpreter}).
7424 @defmac AC_ERLANG_SUBST_ROOT_DIR
7425 @acindex{ERLANG_SUBST_ROOT_DIR}
7426 @ovindex ERLANG_ROOT_DIR
7428 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7429 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7430 function). The result of this test is cached if caching is enabled when running
7431 @command{configure}.
7434 @defmac AC_ERLANG_SUBST_LIB_DIR
7435 @acindex{ERLANG_SUBST_LIB_DIR}
7436 @ovindex ERLANG_LIB_DIR
7438 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7439 directory of Erlang/OTP (as returned by Erlang's
7440 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7441 Erlang/OTP library. The result of this test is cached if caching is enabled
7442 when running @command{configure}.
7445 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7446 @acindex{ERLANG_CHECK_LIB}
7447 @ovindex ERLANG_LIB_DIR_@var{library}
7448 @ovindex ERLANG_LIB_VER_@var{library}
7450 Test whether the Erlang/OTP library @var{library} is installed by
7451 calling Erlang's @code{code:lib_dir/1} function. The result of this
7452 test is cached if caching is enabled when running @command{configure}.
7453 @var{action-if-found} is a list of shell commands to run if the library
7454 is installed; @var{action-if-not-found} is a list of shell commands to
7455 run if it is not. Additionally, if the library is installed, the output
7456 variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the
7457 library installation directory, and the output variable
7458 @samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is
7459 part of the subdirectory name, if it is in the standard form
7460 (@code{@var{library}-@var{version}}). If the directory name does not
7461 have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the
7462 empty string. If the library is not installed,
7463 @samp{ERLANG_LIB_DIR_@var{library}} and
7464 @samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For
7465 example, to check if library @code{stdlib} is installed:
7468 AC_ERLANG_CHECK_LIB([stdlib],
7469 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\""
7470 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""],
7471 [AC_MSG_ERROR([stdlib was not found!])])
7475 In addition to the above macros, which test installed Erlang libraries, the
7476 following macros determine the paths to the directories into which newly built
7477 Erlang libraries are to be installed:
7479 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7480 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7481 @ovindex ERLANG_INSTALL_LIB_DIR
7483 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7484 which every built Erlang library should be installed in a separate subdirectory.
7485 If this variable is not set in the environment when @command{configure} runs,
7486 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7487 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7490 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7491 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7492 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7494 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7495 directory into which the built Erlang library @var{library} version
7496 @var{version} should be installed. If this variable is not set in the
7497 environment when @command{configure} runs, its default value is
7498 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7499 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7500 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7507 @c ========================================================= Writing Tests
7510 @chapter Writing Tests
7512 If the existing feature tests don't do something you need, you have to
7513 write new ones. These macros are the building blocks. They provide
7514 ways for other macros to check whether various kinds of features are
7515 available and report the results.
7517 This chapter contains some suggestions and some of the reasons why the
7518 existing tests are written the way they are. You can also learn a lot
7519 about how to write Autoconf tests by looking at the existing ones. If
7520 something goes wrong in one or more of the Autoconf tests, this
7521 information can help you understand the assumptions behind them, which
7522 might help you figure out how to best solve the problem.
7524 These macros check the output of the compiler system of the current
7525 language (@pxref{Language Choice}). They do not cache the results of
7526 their tests for future use (@pxref{Caching Results}), because they don't
7527 know enough about the information they are checking for to generate a
7528 cache variable name. They also do not print any messages, for the same
7529 reason. The checks for particular kinds of features call these macros
7530 and do cache their results and print messages about what they're
7533 When you write a feature test that could be applicable to more than one
7534 software package, the best thing to do is encapsulate it in a new macro.
7535 @xref{Writing Autoconf Macros}, for how to do that.
7538 * Language Choice:: Selecting which language to use for testing
7539 * Writing Test Programs:: Forging source files for compilers
7540 * Running the Preprocessor:: Detecting preprocessor symbols
7541 * Running the Compiler:: Detecting language or header features
7542 * Running the Linker:: Detecting library features
7543 * Runtime:: Testing for runtime features
7544 * Systemology:: A zoology of operating systems
7545 * Multiple Cases:: Tests for several possible values
7548 @node Language Choice
7549 @section Language Choice
7552 Autoconf-generated @command{configure} scripts check for the C compiler and
7553 its features by default. Packages that use other programming languages
7554 (maybe more than one, e.g., C and C++) need to test features of the
7555 compilers for the respective languages. The following macros determine
7556 which programming language is used in the subsequent tests in
7557 @file{configure.ac}.
7559 @defmac AC_LANG (@var{language})
7560 Do compilation tests using the compiler, preprocessor, and file
7561 extensions for the specified @var{language}.
7563 Supported languages are:
7567 Do compilation tests using @code{CC} and @code{CPP} and use extension
7568 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7569 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7572 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7573 extension @file{.C} for test programs. Use compilation flags:
7574 @code{CPPFLAGS} with @code{CXXCPP}, and both @code{CPPFLAGS} and
7575 @code{CXXFLAGS} with @code{CXX}.
7578 Do compilation tests using @code{F77} and use extension @file{.f} for
7579 test programs. Use compilation flags: @code{FFLAGS}.
7582 Do compilation tests using @code{FC} and use extension @file{.f} (or
7583 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7584 compilation flags: @code{FCFLAGS}.
7590 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7591 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7594 Do compilation tests using @code{OBJC} and @code{OBJCPP} and use
7595 extension @file{.m} for test programs. Use compilation flags:
7596 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7597 @code{OBJCFLAGS} with @code{OBJC}.
7601 @defmac AC_LANG_PUSH (@var{language})
7603 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7604 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7605 in macros that need to temporarily switch to a particular language.
7608 @defmac AC_LANG_POP (@ovar{language})
7610 Select the language that is saved on the top of the stack, as set by
7611 @code{AC_LANG_PUSH}, and remove it from the stack.
7613 If given, @var{language} specifies the language we just @emph{quit}. It
7614 is a good idea to specify it when it's known (which should be the
7615 case@dots{}), since Autoconf detects inconsistencies.
7618 AC_LANG_PUSH([Fortran 77])
7619 # Perform some tests on Fortran 77.
7621 AC_LANG_POP([Fortran 77])
7625 @defmac AC_LANG_ASSERT (@var{language})
7626 @acindex{LANG_ASSERT} Check statically that the current language is
7627 @var{language}. You should use this in your language specific macros
7628 to avoid that they be called with an inappropriate language.
7630 This macro runs only at @command{autoconf} time, and incurs no cost at
7631 @command{configure} time. Sadly enough and because Autoconf is a two
7632 layer language @footnote{Because M4 is not aware of Sh code,
7633 especially conditionals, some optimizations that look nice statically
7634 may produce incorrect results at runtime.}, the macros
7635 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7636 therefore as much as possible you ought to avoid using them to wrap
7637 your code, rather, require from the user to run the macro with a
7638 correct current language, and check it with @code{AC_LANG_ASSERT}.
7639 And anyway, that may help the user understand she is running a Fortran
7640 macro while expecting a result about her Fortran 77 compiler@dots{}
7644 @defmac AC_REQUIRE_CPP
7645 @acindex{REQUIRE_CPP}
7646 Ensure that whichever preprocessor would currently be used for tests has
7647 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7648 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7649 depending on which language is current.
7653 @node Writing Test Programs
7654 @section Writing Test Programs
7656 Autoconf tests follow a common scheme: feed some program with some
7657 input, and most of the time, feed a compiler with some source file.
7658 This section is dedicated to these source samples.
7661 * Guidelines:: General rules for writing test programs
7662 * Test Functions:: Avoiding pitfalls in test programs
7663 * Generating Sources:: Source program boilerplate
7667 @subsection Guidelines for Test Programs
7669 The most important rule to follow when writing testing samples is:
7671 @center @emph{Look for realism.}
7673 This motto means that testing samples must be written with the same
7674 strictness as real programs are written. In particular, you should
7675 avoid ``shortcuts'' and simplifications.
7677 Don't just play with the preprocessor if you want to prepare a
7678 compilation. For instance, using @command{cpp} to check whether a header is
7679 functional might let your @command{configure} accept a header which
7680 causes some @emph{compiler} error. Do not hesitate to check a header with
7681 other headers included before, especially required headers.
7683 Make sure the symbols you use are properly defined, i.e., refrain for
7684 simply declaring a function yourself instead of including the proper
7687 Test programs should not write to standard output. They
7688 should exit with status 0 if the test succeeds, and with status 1
7689 otherwise, so that success
7690 can be distinguished easily from a core dump or other failure;
7691 segmentation violations and other failures produce a nonzero exit
7692 status. Unless you arrange for @code{exit} to be declared, test
7693 programs should @code{return}, not @code{exit}, from @code{main},
7694 because on many systems @code{exit} is not declared by default.
7696 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7697 preprocessor macros defined by tests that have already run. For
7698 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7699 @file{configure.ac} you can have a test program that includes
7700 @file{stdbool.h} conditionally:
7704 #ifdef HAVE_STDBOOL_H
7705 # include <stdbool.h>
7710 Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will
7711 work with any standard C compiler. Some developers prefer @code{#if}
7712 because it is easier to read, while others prefer @code{#ifdef} because
7713 it avoids diagnostics with picky compilers like @acronym{GCC} with the
7714 @option{-Wundef} option.
7716 If a test program needs to use or create a data file, give it a name
7717 that starts with @file{conftest}, such as @file{conftest.data}. The
7718 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7719 after running test programs and if the script is interrupted.
7721 @node Test Functions
7722 @subsection Test Functions
7724 These days it's safe to assume support for function prototypes
7725 (introduced in C89).
7727 Functions that test programs declare should also be conditionalized for
7728 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7729 include any header files containing clashing prototypes.
7735 void *valloc (size_t);
7738 If a test program calls a function with invalid parameters (just to see
7739 whether it exists), organize the program to ensure that it never invokes
7740 that function. You can do this by calling it in another function that is
7741 never invoked. You can't do it by putting it after a call to
7742 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7744 and optimizes out any code that follows it in the same block.
7746 If you include any header files, be sure to call the functions
7747 relevant to them with the correct number of arguments, even if they are
7748 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7750 has internal prototypes for several functions that it automatically
7751 inlines; for example, @code{memcpy}. To avoid errors when checking for
7752 them, either pass them the correct number of arguments or redeclare them
7753 with a different return type (such as @code{char}).
7756 @node Generating Sources
7757 @subsection Generating Sources
7759 Autoconf provides a set of macros that can be used to generate test
7760 source files. They are written to be language generic, i.e., they
7761 actually depend on the current language (@pxref{Language Choice}) to
7762 ``format'' the output properly.
7765 @defmac AC_LANG_CONFTEST (@var{source})
7766 @acindex{LANG_CONFTEST}
7767 Save the @var{source} text in the current test source file:
7768 @file{conftest.@var{extension}} where the @var{extension} depends on the
7771 Note that the @var{source} is evaluated exactly once, like regular
7772 Autoconf macro arguments, and therefore (i) you may pass a macro
7773 invocation, (ii) if not, be sure to double quote if needed.
7776 @defmac AC_LANG_SOURCE (@var{source})
7777 @acindex{LANG_SOURCE}
7778 Expands into the @var{source}, with the definition of
7779 all the @code{AC_DEFINE} performed so far.
7782 For instance executing (observe the double quotation!):
7785 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7786 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7787 [Greetings string.])
7790 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7791 gcc -E -dD -o - conftest.c
7801 #define PACKAGE_NAME "Hello"
7802 #define PACKAGE_TARNAME "hello"
7803 #define PACKAGE_VERSION "1.0"
7804 #define PACKAGE_STRING "Hello 1.0"
7805 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7806 #define HELLO_WORLD "Hello, World\n"
7808 const char hw[] = "Hello, World\n";
7811 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7812 are not automatically translated into constants in the source code by this
7815 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7816 @acindex{LANG_PROGRAM}
7817 Expands into a source file which consists of the @var{prologue}, and
7818 then @var{body} as body of the main function (e.g., @code{main} in
7819 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7826 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7827 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7828 [Greetings string.])
7830 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7831 [[fputs (hw, stdout);]])])
7832 gcc -E -dD -o - conftest.c
7842 #define PACKAGE_NAME "Hello"
7843 #define PACKAGE_TARNAME "hello"
7844 #define PACKAGE_VERSION "1.0"
7845 #define PACKAGE_STRING "Hello 1.0"
7846 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7847 #define HELLO_WORLD "Hello, World\n"
7849 const char hw[] = "Hello, World\n";
7859 In Erlang tests, the created source file is that of an Erlang module called
7860 @code{conftest} (@file{conftest.erl}). This module defines and exports at least
7861 one @code{start/0} function, which is called to perform the test. The
7862 @var{prologue} is optional code that is inserted between the module header and
7863 the @code{start/0} function definition. @var{body} is the body of the
7864 @code{start/0} function without the final period (@pxref{Runtime}, about
7865 constraints on this function's behavior).
7870 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7873 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7874 [[io:format("~s~n", [?HELLO_WORLD])]])])
7884 -define(HELLO_WORLD, "Hello, world!").
7886 io:format("~s~n", [?HELLO_WORLD])
7890 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7892 Expands into a source file which consists of the @var{prologue}, and
7893 then a call to the @var{function} as body of the main function (e.g.,
7894 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
7895 of the latter are available.
7897 This function will probably be replaced in the future by a version
7898 which would enable specifying the arguments. The use of this macro is
7899 not encouraged, as it violates strongly the typing system.
7901 This macro cannot be used for Erlang tests.
7904 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7905 @acindex{LANG_FUNC_LINK_TRY}
7906 Expands into a source file which uses the @var{function} in the body of
7907 the main function (e.g., @code{main} in C). Since it uses
7908 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7910 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7911 It is considered to be severely broken, and in the future will be
7912 removed in favor of actual function calls (with properly typed
7915 This macro cannot be used for Erlang tests.
7918 @node Running the Preprocessor
7919 @section Running the Preprocessor
7921 Sometimes one might need to run the preprocessor on some source file.
7922 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7923 your project, not merely run the preprocessor on it; therefore you
7924 certainly want to run the compiler, not the preprocessor. Resist the
7925 temptation of following the easiest path.
7927 Nevertheless, if you need to run the preprocessor, then use
7928 @code{AC_PREPROC_IFELSE}.
7930 The macros described in this section cannot be used for tests in Erlang or
7931 Fortran, since those languages require no preprocessor.
7933 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7934 @acindex{PREPROC_IFELSE}
7935 Run the preprocessor of the current language (@pxref{Language Choice})
7936 on the @var{input}, run the shell commands @var{action-if-true} on
7937 success, @var{action-if-false} otherwise. The @var{input} can be made
7938 by @code{AC_LANG_PROGRAM} and friends.
7940 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7941 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7944 It is customary to report unexpected failures with
7945 @code{AC_MSG_FAILURE}.
7951 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7952 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7953 [Greetings string.])
7955 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7956 [[fputs (hw, stdout);]])],
7957 [AC_MSG_RESULT([OK])],
7958 [AC_MSG_FAILURE([unexpected preprocessor failure])])
7965 checking for gcc... gcc
7966 checking for C compiler default output file name... a.out
7967 checking whether the C compiler works... yes
7968 checking whether we are cross compiling... no
7969 checking for suffix of executables...
7970 checking for suffix of object files... o
7971 checking whether we are using the GNU C compiler... yes
7972 checking whether gcc accepts -g... yes
7973 checking for gcc option to accept ISO C89... none needed
7974 checking how to run the C preprocessor... gcc -E
7980 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7981 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7982 it impossible to use it to elaborate sources. You are encouraged to
7983 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7984 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7985 to run the @emph{preprocessor} and not the compiler?
7987 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7988 @acindex{EGREP_HEADER}
7989 If the output of running the preprocessor on the system header file
7990 @var{header-file} matches the extended regular expression
7991 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7992 execute @var{action-if-not-found}.
7995 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7997 @var{program} is the text of a C or C++ program, on which shell
7998 variable, back quote, and backslash substitutions are performed. If the
7999 output of running the preprocessor on @var{program} matches the
8000 extended regular expression @var{pattern}, execute shell commands
8001 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
8006 @node Running the Compiler
8007 @section Running the Compiler
8009 To check for a syntax feature of the current language's (@pxref{Language
8010 Choice}) compiler, such as whether it recognizes a certain keyword, or
8011 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
8012 to compile a small program that uses that feature.
8014 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
8015 @acindex{COMPILE_IFELSE}
8016 Run the compiler and compilation flags of the current language
8017 (@pxref{Language Choice}) on the @var{input}, run the shell commands
8018 @var{action-if-true} on success, @var{action-if-false} otherwise. The
8019 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8021 It is customary to report unexpected failures with
8022 @code{AC_MSG_FAILURE}. This macro does not try to link; use
8023 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
8028 For tests in Erlang, the @var{input} must be the source code of a module named
8029 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
8030 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
8031 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
8032 that the Erlang module has the right name.
8034 @node Running the Linker
8035 @section Running the Linker
8037 To check for a library, a function, or a global variable, Autoconf
8038 @command{configure} scripts try to compile and link a small program that
8039 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
8040 @code{ar} on the C library to try to figure out which functions are
8041 available. Trying to link with the function is usually a more reliable
8042 approach because it avoids dealing with the variations in the options
8043 and output formats of @code{nm} and @code{ar} and in the location of the
8044 standard libraries. It also allows configuring for cross-compilation or
8045 checking a function's runtime behavior if needed. On the other hand,
8046 it can be slower than scanning the libraries once, but accuracy is more
8047 important than speed.
8049 @code{AC_LINK_IFELSE} is used to compile test programs to test for
8050 functions and global variables. It is also used by @code{AC_CHECK_LIB}
8051 to check for libraries (@pxref{Libraries}), by adding the library being
8052 checked for to @code{LIBS} temporarily and trying to link a small
8056 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
8057 @acindex{LINK_IFELSE}
8058 Run the compiler (and compilation flags) and the linker of the current
8059 language (@pxref{Language Choice}) on the @var{input}, run the shell
8060 commands @var{action-if-true} on success, @var{action-if-false}
8061 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
8064 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8065 current compilation flags.
8067 It is customary to report unexpected failures with
8068 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
8069 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
8072 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
8073 programs are interpreted and do not require linking.
8078 @section Checking Runtime Behavior
8080 Sometimes you need to find out how a system performs at runtime, such
8081 as whether a given function has a certain capability or bug. If you
8082 can, make such checks when your program runs instead of when it is
8083 configured. You can check for things like the machine's endianness when
8084 your program initializes itself.
8086 If you really need to test for a runtime behavior while configuring,
8087 you can write a test program to determine the result, and compile and
8088 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
8089 possible, because this prevents people from configuring your package for
8092 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
8093 @acindex{RUN_IFELSE}
8094 If @var{program} compiles and links successfully and returns an exit
8095 status of 0 when executed, run shell commands @var{action-if-true}.
8096 Otherwise, run shell commands @var{action-if-false}.
8098 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
8099 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
8100 compilation flags of the current language (@pxref{Language Choice}).
8102 If the compiler being used does not produce executables that run on the
8103 system where @command{configure} is being run, then the test program is
8104 not run. If the optional shell commands @var{action-if-cross-compiling}
8105 are given, they are run instead. Otherwise, @command{configure} prints
8106 an error message and exits.
8108 In the @var{action-if-false} section, the failing exit status is
8109 available in the shell variable @samp{$?}. This exit status might be
8110 that of a failed compilation, or it might be that of a failed program
8113 It is customary to report unexpected failures with
8114 @code{AC_MSG_FAILURE}.
8117 Try to provide a pessimistic default value to use when cross-compiling
8118 makes runtime tests impossible. You do this by passing the optional
8119 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
8120 warning message when creating @command{configure} each time it
8121 encounters a call to @code{AC_RUN_IFELSE} with no
8122 @var{action-if-cross-compiling} argument given. You may ignore the
8123 warning, though users cannot configure your package for
8124 cross-compiling. A few of the macros distributed with Autoconf produce
8125 this warning message.
8127 To configure for cross-compiling you can also choose a value for those
8128 parameters based on the canonical system name (@pxref{Manual
8129 Configuration}). Alternatively, set up a test results cache file with
8130 the correct values for the host system (@pxref{Caching Results}).
8132 @ovindex cross_compiling
8133 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
8134 in other macros, including a few of the ones that come with Autoconf,
8135 you can test whether the shell variable @code{cross_compiling} is set to
8136 @samp{yes}, and then use an alternate method to get the results instead
8137 of calling the macros.
8139 A C or C++ runtime test should be portable.
8140 @xref{Portable C and C++}.
8142 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8143 function: the given status code is used to determine the success of the test
8144 (status is @code{0}) or its failure (status is different than @code{0}), as
8145 explained above. It must be noted that data output through the standard output
8146 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8147 Therefore, if a test must output configuration information, it is recommended
8148 to create and to output data into the temporary file named @file{conftest.out},
8149 using the functions of module @code{file}. The @code{conftest.out} file is
8150 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8151 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8154 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8158 [AC_LANG_PROGRAM([], [dnl
8159 file:write_file("conftest.out", code:lib_dir()),
8161 [echo "code:lib_dir() returned: `cat conftest.out`"],
8162 [AC_MSG_FAILURE([test Erlang program execution failed])])
8167 @section Systemology
8170 This section aims at presenting some systems and pointers to
8171 documentation. It may help you addressing particular problems reported
8174 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8175 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8178 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8179 contains a table correlating the features of various Posix-conforming
8180 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8181 simplified diagram of how many Unix systems were derived from each
8184 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8185 provides some variants of traditional implementations of Unix utilities.
8190 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8191 case-preserving, but case insensitive. This can cause nasty problems,
8192 since for instance the installation attempt for a package having an
8193 @file{INSTALL} file can result in @samp{make install} report that
8194 nothing was to be done!
8196 That's all dependent on whether the file system is a UFS (case
8197 sensitive) or HFS+ (case preserving). By default Apple wants you to
8198 install the OS on HFS+. Unfortunately, there are some pieces of
8199 software which really need to be built on UFS@. We may want to rebuild
8200 Darwin to have both UFS and HFS+ available (and put the /local/build
8203 @item @acronym{QNX} 4.25
8204 @cindex @acronym{QNX} 4.25
8205 @c FIXME: Please, if you feel like writing something more precise,
8206 @c it'd be great. In particular, I can't understand the difference with
8208 @acronym{QNX} is a realtime operating system running on Intel architecture
8209 meant to be scalable from the small embedded systems to the hundred
8210 processor super-computer. It claims to be Posix certified. More
8211 information is available on the
8212 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8216 @uref{http://h30097.www3.hp.com/@/docs/,
8217 Documentation of several versions of Tru64} is available in different
8220 @item Unix version 7
8221 @cindex Unix version 7
8223 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8224 time-sharing system'' but we use the more-common name ``Unix version 7''.
8225 Documentation is available in the
8226 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8227 Previous versions of Unix are called ``Unix version 6'', etc., but
8228 they were not as widely used.
8232 @node Multiple Cases
8233 @section Multiple Cases
8235 Some operations are accomplished in several possible ways, depending on
8236 the OS variant. Checking for them essentially requires a ``case
8237 statement''. Autoconf does not directly provide one; however, it is
8238 easy to simulate by using a shell variable to keep track of whether a
8239 way to perform the operation has been found yet.
8241 Here is an example that uses the shell variable @code{fstype} to keep
8242 track of whether the remaining cases need to be checked.
8246 AC_MSG_CHECKING([how to get file system type])
8248 # The order of these tests is important.
8249 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8250 #include <sys/fstyp.h>]])],
8251 [AC_DEFINE([FSTYPE_STATVFS], [1],
8252 [Define if statvfs exists.])
8254 if test $fstype = no; then
8255 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8256 #include <sys/fstyp.h>]])],
8257 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8258 [Define if USG statfs.])
8261 if test $fstype = no; then
8262 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8263 #include <sys/vmount.h>]])]),
8264 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8265 [Define if AIX statfs.])
8268 # (more cases omitted here)
8269 AC_MSG_RESULT([$fstype])
8273 @c ====================================================== Results of Tests.
8276 @chapter Results of Tests
8278 Once @command{configure} has determined whether a feature exists, what can
8279 it do to record that information? There are four sorts of things it can
8280 do: define a C preprocessor symbol, set a variable in the output files,
8281 save the result in a cache file for future @command{configure} runs, and
8282 print a message letting the user know the result of the test.
8285 * Defining Symbols:: Defining C preprocessor symbols
8286 * Setting Output Variables:: Replacing variables in output files
8287 * Special Chars in Variables:: Characters to beware of in variables
8288 * Caching Results:: Speeding up subsequent @command{configure} runs
8289 * Printing Messages:: Notifying @command{configure} users
8292 @node Defining Symbols
8293 @section Defining C Preprocessor Symbols
8295 A common action to take in response to a feature test is to define a C
8296 preprocessor symbol indicating the results of the test. That is done by
8297 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8299 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8300 into the output variable @code{DEFS}, which contains an option
8301 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8302 Autoconf version 1, there is no variable @code{DEFS} defined while
8303 @command{configure} is running. To check whether Autoconf macros have
8304 already defined a certain C preprocessor symbol, test the value of the
8305 appropriate cache variable, as in this example:
8308 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8309 [Define if vprintf exists.])])
8310 if test "$ac_cv_func_vprintf" != yes; then
8311 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8312 [Define if _doprnt exists.])])
8316 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8317 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8318 correct values into @code{#define} statements in a template file.
8319 @xref{Configuration Headers}, for more information about this kind of
8322 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8323 @defmacx AC_DEFINE (@var{variable})
8325 Define @var{variable} to @var{value} (verbatim), by defining a C
8326 preprocessor macro for @var{variable}. @var{variable} should be a C
8327 identifier, optionally suffixed by a parenthesized argument list to
8328 define a C preprocessor macro with arguments. The macro argument list,
8329 if present, should be a comma-separated list of C identifiers, possibly
8330 terminated by an ellipsis @samp{...} if C99 syntax is employed.
8331 @var{variable} should not contain comments, white space, trigraphs,
8332 backslash-newlines, universal character names, or non-@acronym{ASCII}
8335 @var{value} should not contain literal newlines, and if you are not
8336 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8337 characters, as @command{make} tends to eat them. To use a shell variable,
8338 use @code{AC_DEFINE_UNQUOTED} instead.
8339 @var{description} is only useful if you are using
8340 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8341 the generated @file{config.h.in} as the comment before the macro define.
8342 The following example defines the C preprocessor variable
8343 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8346 AC_DEFINE([EQUATION], ["$a > $b"],
8350 If neither @var{value} nor @var{description} are given, then
8351 @var{value} defaults to 1 instead of to the empty string. This is for
8352 backwards compatibility with older versions of Autoconf, but this usage
8353 is obsolescent and may be withdrawn in future versions of Autoconf.
8355 If the @var{variable} is a literal string, it is passed to
8356 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8358 If multiple @code{AC_DEFINE} statements are executed for the same
8359 @var{variable} name (not counting any parenthesized argument list),
8363 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8364 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8365 @acindex{DEFINE_UNQUOTED}
8366 Like @code{AC_DEFINE}, but three shell expansions are
8367 performed---once---on @var{variable} and @var{value}: variable expansion
8368 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8369 (@samp{\}). Single and double quote characters in the value have no
8370 special meaning. Use this macro instead of @code{AC_DEFINE} when
8371 @var{variable} or @var{value} is a shell variable. Examples:
8374 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8375 [Configuration machine file.])
8376 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8377 [getgroups return type.])
8378 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8379 [Translated header name.])
8383 Due to a syntactical bizarreness of the Bourne shell, do not use
8384 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8385 calls from other macro calls or shell code; that can cause syntax errors
8386 in the resulting @command{configure} script. Use either blanks or
8387 newlines. That is, do this:
8390 AC_CHECK_HEADER([elf.h],
8391 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8398 AC_CHECK_HEADER([elf.h],
8399 [AC_DEFINE([SVR4], [1], [System V Release 4])
8400 LIBS="-lelf $LIBS"])
8407 AC_CHECK_HEADER([elf.h],
8408 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8411 @node Setting Output Variables
8412 @section Setting Output Variables
8413 @cindex Output variables
8415 Another way to record the results of tests is to set @dfn{output
8416 variables}, which are shell variables whose values are substituted into
8417 files that @command{configure} outputs. The two macros below create new
8418 output variables. @xref{Preset Output Variables}, for a list of output
8419 variables that are always available.
8421 @defmac AC_SUBST (@var{variable}, @ovar{value})
8423 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8424 substitute the variable @var{variable} into output files (typically one
8425 or more makefiles). This means that @code{AC_OUTPUT}
8426 replaces instances of @samp{@@@var{variable}@@} in input files with the
8427 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8428 is called. The value can contain any non-@code{NUL} character, including
8430 Variable occurrences should not overlap: e.g., an input file should
8431 not contain @samp{@@@var{var1}@@@var{var2}@@} if @var{var1} and @var{var2}
8433 The substituted value is not rescanned for more output variables;
8434 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8435 literally into the output file. (The algorithm uses the special marker
8436 @code{|#_!!_#|} internally, so neither the substituted value nor the
8437 output file may contain @code{|#_!!_#|}.)
8439 If @var{value} is given, in addition assign it to @var{variable}.
8441 The string @var{variable} is passed to @code{m4_pattern_allow}
8442 (@pxref{Forbidden Patterns}).
8445 @defmac AC_SUBST_FILE (@var{variable})
8446 @acindex{SUBST_FILE}
8447 Another way to create an output variable from a shell variable. Make
8448 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8449 named by shell variable @var{variable} into output files. This means
8450 that @code{AC_OUTPUT} replaces instances of
8451 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8452 with the contents of the file that the shell variable @var{variable}
8453 names when @code{AC_OUTPUT} is called. Set the variable to
8454 @file{/dev/null} for cases that do not have a file to insert.
8455 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8456 line by itself, optionally surrounded by spaces and tabs. The
8457 substitution replaces the whole line, including the spaces, tabs, and
8458 the terminating newline.
8460 This macro is useful for inserting makefile fragments containing
8461 special dependencies or other @code{make} directives for particular host
8462 or target types into makefiles. For example, @file{configure.ac}
8466 AC_SUBST_FILE([host_frag])
8467 host_frag=$srcdir/conf/sun4.mh
8471 and then a @file{Makefile.in} could contain:
8477 The string @var{variable} is passed to @code{m4_pattern_allow}
8478 (@pxref{Forbidden Patterns}).
8481 @cindex Precious Variable
8482 @cindex Variable, Precious
8483 Running @command{configure} in varying environments can be extremely
8484 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8485 ./configure}, then the cache, @file{config.h}, and many other output
8486 files depend upon @command{bizarre-cc} being the C compiler. If
8487 for some reason the user runs @command{./configure} again, or if it is
8488 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8489 and @pxref{config.status Invocation}), then the configuration can be
8490 inconsistent, composed of results depending upon two different
8493 Environment variables that affect this situation, such as @samp{CC}
8494 above, are called @dfn{precious variables}, and can be declared as such
8495 by @code{AC_ARG_VAR}.
8497 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8499 Declare @var{variable} is a precious variable, and include its
8500 @var{description} in the variable section of @samp{./configure --help}.
8502 Being precious means that
8505 @var{variable} is substituted via @code{AC_SUBST}.
8508 The value of @var{variable} when @command{configure} was launched is
8509 saved in the cache, including if it was not specified on the command
8510 line but via the environment. Indeed, while @command{configure} can
8511 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8512 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8513 which, unfortunately, is what most users do.
8515 We emphasize that it is the @emph{initial} value of @var{variable} which
8516 is saved, not that found during the execution of @command{configure}.
8517 Indeed, specifying @samp{./configure FOO=foo} and letting
8518 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8522 @var{variable} is checked for consistency between two
8523 @command{configure} runs. For instance:
8526 $ @kbd{./configure --silent --config-cache}
8527 $ @kbd{CC=cc ./configure --silent --config-cache}
8528 configure: error: `CC' was not set in the previous run
8529 configure: error: changes in the environment can compromise \
8531 configure: error: run `make distclean' and/or \
8532 `rm config.cache' and start over
8536 and similarly if the variable is unset, or if its content is changed.
8540 @var{variable} is kept during automatic reconfiguration
8541 (@pxref{config.status Invocation}) as if it had been passed as a command
8542 line argument, including when no cache is used:
8545 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8546 $ @kbd{./config.status --recheck}
8547 running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \
8548 CC=/usr/bin/cc --no-create --no-recursion
8553 @node Special Chars in Variables
8554 @section Special Characters in Output Variables
8555 @cindex Output variables, special characters in
8557 Many output variables are intended to be evaluated both by
8558 @command{make} and by the shell. Some characters are expanded
8559 differently in these two contexts, so to avoid confusion these
8560 variables' values should not contain any of the following characters:
8563 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8566 Also, these variables' values should neither contain newlines, nor start
8567 with @samp{~}, nor contain white space or @samp{:} immediately followed
8568 by @samp{~}. The values can contain nonempty sequences of white space
8569 characters like tabs and spaces, but each such sequence might
8570 arbitrarily be replaced by a single space during substitution.
8572 These restrictions apply both to the values that @command{configure}
8573 computes, and to the values set directly by the user. For example, the
8574 following invocations of @command{configure} are problematic, since they
8575 attempt to use special characters within @code{CPPFLAGS} and white space
8576 within @code{$(srcdir)}:
8579 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8581 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8584 @node Caching Results
8585 @section Caching Results
8588 To avoid checking for the same features repeatedly in various
8589 @command{configure} scripts (or in repeated runs of one script),
8590 @command{configure} can optionally save the results of many checks in a
8591 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8592 runs with caching enabled and finds a cache file, it reads the results
8593 of previous runs from the cache and avoids rerunning those checks. As a
8594 result, @command{configure} can then run much faster than if it had to
8595 perform all of the checks every time.
8597 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8599 Ensure that the results of the check identified by @var{cache-id} are
8600 available. If the results of the check were in the cache file that was
8601 read, and @command{configure} was not given the @option{--quiet} or
8602 @option{--silent} option, print a message saying that the result was
8603 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8604 the shell commands are run to determine the value, the value is
8605 saved in the cache file just before @command{configure} creates its output
8606 files. @xref{Cache Variable Names}, for how to choose the name of the
8607 @var{cache-id} variable.
8609 The @var{commands-to-set-it} @emph{must have no side effects} except for
8610 setting the variable @var{cache-id}, see below.
8613 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8614 @acindex{CACHE_CHECK}
8615 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8616 messages. This macro provides a convenient shorthand for the most
8617 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8618 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8619 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8621 The @var{commands-to-set-it} @emph{must have no side effects} except for
8622 setting the variable @var{cache-id}, see below.
8625 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8626 @code{AC_CACHE_CHECK}, because people are tempted to call
8627 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8628 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8629 @code{AC_DEFINE}, by examining the value of the cache variable. For
8630 instance, the following macro is broken:
8634 AC_DEFUN([AC_SHELL_TRUE],
8635 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8636 [my_cv_shell_true_works=no
8637 (true) 2>/dev/null && my_cv_shell_true_works=yes
8638 if test "$my_cv_shell_true_works" = yes; then
8639 AC_DEFINE([TRUE_WORKS], [1],
8640 [Define if `true(1)' works properly.])
8647 This fails if the cache is enabled: the second time this macro is run,
8648 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8653 AC_DEFUN([AC_SHELL_TRUE],
8654 [AC_CACHE_CHECK([whether true(1) works], [my_cv_shell_true_works],
8655 [my_cv_shell_true_works=no
8656 (true) 2>/dev/null && my_cv_shell_true_works=yes])
8657 if test "$my_cv_shell_true_works" = yes; then
8658 AC_DEFINE([TRUE_WORKS], [1],
8659 [Define if `true(1)' works properly.])
8665 Also, @var{commands-to-set-it} should not print any messages, for
8666 example with @code{AC_MSG_CHECKING}; do that before calling
8667 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8668 the results of the check are retrieved from the cache or determined by
8669 running the shell commands.
8672 * Cache Variable Names:: Shell variables used in caches
8673 * Cache Files:: Files @command{configure} uses for caching
8674 * Cache Checkpointing:: Loading and saving the cache file
8677 @node Cache Variable Names
8678 @subsection Cache Variable Names
8679 @cindex Cache variable
8681 The names of cache variables should have the following format:
8684 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8688 for example, @samp{ac_cv_header_stat_broken} or
8689 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8692 @item @var{package-prefix}
8693 An abbreviation for your package or organization; the same prefix you
8694 begin local Autoconf macros with, except lowercase by convention.
8695 For cache values used by the distributed Autoconf macros, this value is
8699 Indicates that this shell variable is a cache value. This string
8700 @emph{must} be present in the variable name, including the leading
8703 @item @var{value-type}
8704 A convention for classifying cache values, to produce a rational naming
8705 system. The values used in Autoconf are listed in @ref{Macro Names}.
8707 @item @var{specific-value}
8708 Which member of the class of cache values this test applies to.
8709 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8710 output variable (@samp{INSTALL}).
8712 @item @var{additional-options}
8713 Any particular behavior of the specific member that this test applies to.
8714 For example, @samp{broken} or @samp{set}. This part of the name may
8715 be omitted if it does not apply.
8718 The values assigned to cache variables may not contain newlines.
8719 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8720 names of files or functions; so this is not an important restriction.
8723 @subsection Cache Files
8725 A cache file is a shell script that caches the results of configure
8726 tests run on one system so they can be shared between configure scripts
8727 and configure runs. It is not useful on other systems. If its contents
8728 are invalid for some reason, the user may delete or edit it.
8730 By default, @command{configure} uses no cache file,
8731 to avoid problems caused by accidental
8732 use of stale cache files.
8734 To enable caching, @command{configure} accepts @option{--config-cache} (or
8735 @option{-C}) to cache results in the file @file{config.cache}.
8736 Alternatively, @option{--cache-file=@var{file}} specifies that
8737 @var{file} be the cache file. The cache file is created if it does not
8738 exist already. When @command{configure} calls @command{configure} scripts in
8739 subdirectories, it uses the @option{--cache-file} argument so that they
8740 share the same cache. @xref{Subdirectories}, for information on
8741 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8743 @file{config.status} only pays attention to the cache file if it is
8744 given the @option{--recheck} option, which makes it rerun
8745 @command{configure}.
8747 It is wrong to try to distribute cache files for particular system types.
8748 There is too much room for error in doing that, and too much
8749 administrative overhead in maintaining them. For any features that
8750 can't be guessed automatically, use the standard method of the canonical
8751 system type and linking files (@pxref{Manual Configuration}).
8753 The site initialization script can specify a site-wide cache file to
8754 use, instead of the usual per-program cache. In this case, the cache
8755 file gradually accumulates information whenever someone runs a new
8756 @command{configure} script. (Running @command{configure} merges the new cache
8757 results with the existing cache file.) This may cause problems,
8758 however, if the system configuration (e.g., the installed libraries or
8759 compilers) changes and the stale cache file is not deleted.
8761 @node Cache Checkpointing
8762 @subsection Cache Checkpointing
8764 If your configure script, or a macro called from @file{configure.ac}, happens
8765 to abort the configure process, it may be useful to checkpoint the cache
8766 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8767 reduces the amount of time it takes to rerun the configure script with
8768 (hopefully) the error that caused the previous abort corrected.
8770 @c FIXME: Do we really want to document this guy?
8771 @defmac AC_CACHE_LOAD
8772 @acindex{CACHE_LOAD}
8773 Loads values from existing cache file, or creates a new cache file if a
8774 cache file is not found. Called automatically from @code{AC_INIT}.
8777 @defmac AC_CACHE_SAVE
8778 @acindex{CACHE_SAVE}
8779 Flushes all cached values to the cache file. Called automatically from
8780 @code{AC_OUTPUT}, but it can be quite useful to call
8781 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8787 @r{ @dots{} AC_INIT, etc. @dots{}}
8789 # Checks for programs.
8792 @r{ @dots{} more program checks @dots{}}
8797 # Checks for libraries.
8798 AC_CHECK_LIB([nsl], [gethostbyname])
8799 AC_CHECK_LIB([socket], [connect])
8800 @r{ @dots{} more lib checks @dots{}}
8805 # Might abort@dots{}
8806 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8807 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8809 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8812 @node Printing Messages
8813 @section Printing Messages
8814 @cindex Messages, from @command{configure}
8816 @command{configure} scripts need to give users running them several kinds
8817 of information. The following macros print messages in ways appropriate
8818 for each kind. The arguments to all of them get enclosed in shell
8819 double quotes, so the shell performs variable and back-quote
8820 substitution on them.
8822 These macros are all wrappers around the @command{echo} shell command.
8823 They direct output to the appropriate file descriptor (@pxref{File
8824 Descriptor Macros}).
8825 @command{configure} scripts should rarely need to run @command{echo} directly
8826 to print messages for the user. Using these macros makes it easy to
8827 change how and when each kind of message is printed; such changes need
8828 only be made to the macro definitions and all the callers change
8831 To diagnose static issues, i.e., when @command{autoconf} is run, see
8832 @ref{Reporting Messages}.
8834 @defmac AC_MSG_CHECKING (@var{feature-description})
8835 @acindex{MSG_CHECKING}
8836 Notify the user that @command{configure} is checking for a particular
8837 feature. This macro prints a message that starts with @samp{checking }
8838 and ends with @samp{...} and no newline. It must be followed by a call
8839 to @code{AC_MSG_RESULT} to print the result of the check and the
8840 newline. The @var{feature-description} should be something like
8841 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8844 This macro prints nothing if @command{configure} is run with the
8845 @option{--quiet} or @option{--silent} option.
8848 @defmac AC_MSG_RESULT (@var{result-description})
8849 @acindex{MSG_RESULT}
8850 Notify the user of the results of a check. @var{result-description} is
8851 almost always the value of the cache variable for the check, typically
8852 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
8853 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8854 the completion of the message printed by the call to
8855 @code{AC_MSG_CHECKING}.
8857 This macro prints nothing if @command{configure} is run with the
8858 @option{--quiet} or @option{--silent} option.
8861 @defmac AC_MSG_NOTICE (@var{message})
8862 @acindex{MSG_NOTICE}
8863 Deliver the @var{message} to the user. It is useful mainly to print a
8864 general description of the overall purpose of a group of feature checks,
8868 AC_MSG_NOTICE([checking if stack overflow is detectable])
8871 This macro prints nothing if @command{configure} is run with the
8872 @option{--quiet} or @option{--silent} option.
8875 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8877 Notify the user of an error that prevents @command{configure} from
8878 completing. This macro prints an error message to the standard error
8879 output and exits @command{configure} with @var{exit-status} (1 by default).
8880 @var{error-description} should be something like @samp{invalid value
8883 The @var{error-description} should start with a lower-case letter, and
8884 ``cannot'' is preferred to ``can't''.
8887 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8888 @acindex{MSG_FAILURE}
8889 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8890 prevents @command{configure} from completing @emph{and} that additional
8891 details are provided in @file{config.log}. This is typically used when
8892 abnormal results are found during a compilation.
8895 @defmac AC_MSG_WARN (@var{problem-description})
8897 Notify the @command{configure} user of a possible problem. This macro
8898 prints the message to the standard error output; @command{configure}
8899 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8900 provide a default (back-up) behavior for the situations they warn about.
8901 @var{problem-description} should be something like @samp{ln -s seems to
8907 @c ====================================================== Programming in M4.
8909 @node Programming in M4
8910 @chapter Programming in M4
8913 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8914 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8915 provides macros dedicated to shell script generation.
8917 As of this version of Autoconf, these two layers are still experimental,
8918 and their interface might change in the future. As a matter of fact,
8919 @emph{anything that is not documented must not be used}.
8922 * M4 Quotation:: Protecting macros from unwanted expansion
8923 * Using autom4te:: The Autoconf executables backbone
8924 * Programming in M4sugar:: Convenient pure M4 macros
8925 * Programming in M4sh:: Common shell Constructs
8926 * File Descriptor Macros:: File descriptor macros for input and output
8930 @section M4 Quotation
8931 @cindex M4 quotation
8934 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8935 @c prevented `expansion' of $1. Unless it refers to the expansion
8936 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
8938 The most common problem with existing macros is an improper quotation.
8939 This section, which users of Autoconf can skip, but which macro writers
8940 @emph{must} read, first justifies the quotation scheme that was chosen
8941 for Autoconf and then ends with a rule of thumb. Understanding the
8942 former helps one to follow the latter.
8945 * Active Characters:: Characters that change the behavior of M4
8946 * One Macro Call:: Quotation and one macro call
8947 * Quotation and Nested Macros:: Macros calling macros
8948 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
8949 * Quadrigraphs:: Another way to escape special characters
8950 * Quotation Rule Of Thumb:: One parenthesis, one quote
8953 @node Active Characters
8954 @subsection Active Characters
8956 To fully understand where proper quotation is important, you first need
8957 to know what the special characters are in Autoconf: @samp{#} introduces
8958 a comment inside which no macro expansion is performed, @samp{,}
8959 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8960 and finally @samp{(} and @samp{)} (which M4 tries to match by
8963 In order to understand the delicate case of macro calls, we first have
8964 to present some obvious failures. Below they are ``obvious-ified'',
8965 but when you find them in real life, they are usually in disguise.
8967 Comments, introduced by a hash and running up to the newline, are opaque
8968 tokens to the top level: active characters are turned off, and there is
8972 # define([def], ine)
8973 @result{}# define([def], ine)
8976 Each time there can be a macro expansion, there is a quotation
8977 expansion, i.e., one level of quotes is stripped:
8983 @result{}int tab[10];
8986 Without this in mind, the reader might try hopelessly to use her macro
8990 define([array], [int tab[10];])
8998 How can you correctly output the intended results@footnote{Using
9002 @node One Macro Call
9003 @subsection One Macro Call
9005 Let's proceed on the interaction between active characters and macros
9006 with this small macro, which just returns its first argument:
9013 The two pairs of quotes above are not part of the arguments of
9014 @code{define}; rather, they are understood by the top level when it
9015 tries to find the arguments of @code{define}. Therefore, assuming
9016 @code{car} is not already defined, it is equivalent to write:
9023 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
9024 quotes, it is bad practice for Autoconf macros which must both be more
9025 robust and also advocate perfect style.
9027 At the top level, there are only two possibilities: either you
9033 [car(foo, bar, baz)]
9034 @result{}car(foo, bar, baz)
9037 Let's pay attention to the special characters:
9041 @error{}EOF in argument list
9044 The closing parenthesis is hidden in the comment; with a hypothetical
9045 quoting, the top level understood it this way:
9052 Proper quotation, of course, fixes the problem:
9059 Here are more examples:
9082 With this in mind, we can explore the cases where macros invoke
9086 @node Quotation and Nested Macros
9087 @subsection Quotation and Nested Macros
9089 The examples below use the following macros:
9093 define([active], [ACT, IVE])
9094 define([array], [int tab[10]])
9097 Each additional embedded macro call introduces other possible
9098 interesting quotations:
9109 In the first case, the top level looks for the arguments of @code{car},
9110 and finds @samp{active}. Because M4 evaluates its arguments
9111 before applying the macro, @samp{active} is expanded, which results in:
9119 In the second case, the top level gives @samp{active} as first and only
9120 argument of @code{car}, which results in:
9128 i.e., the argument is evaluated @emph{after} the macro that invokes it.
9129 In the third case, @code{car} receives @samp{[active]}, which results in:
9137 exactly as we already saw above.
9139 The example above, applied to a more realistic example, gives:
9146 car([[int tab[10];]])
9147 @result{}int tab[10];
9151 Huh? The first case is easily understood, but why is the second wrong,
9152 and the third right? To understand that, you must know that after
9153 M4 expands a macro, the resulting text is immediately subjected
9154 to macro expansion and quote removal. This means that the quote removal
9155 occurs twice---first before the argument is passed to the @code{car}
9156 macro, and second after the @code{car} macro expands to the first
9159 As the author of the Autoconf macro @code{car}, you then consider it to
9160 be incorrect that your users have to double-quote the arguments of
9161 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9165 define([qar], [[$1]])
9169 and check that @code{qar} is properly fixed:
9173 @result{}int tab[10];
9177 Ahhh! That's much better.
9179 But note what you've done: now that the arguments are literal strings,
9180 if the user wants to use the results of expansions as arguments, she has
9181 to use an @emph{unquoted} macro call:
9189 where she wanted to reproduce what she used to do with @code{car}:
9197 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9201 define([my_includes], [#include <stdio.h>])
9203 @result{}#include <stdio.h>
9205 @error{}EOF in argument list
9208 This macro, @code{qar}, because it double quotes its arguments, forces
9209 its users to leave their macro calls unquoted, which is dangerous.
9210 Commas and other active symbols are interpreted by M4 before
9211 they are given to the macro, often not in the way the users expect.
9212 Also, because @code{qar} behaves differently from the other macros,
9213 it's an exception that should be avoided in Autoconf.
9215 @node Changequote is Evil
9216 @subsection @code{changequote} is Evil
9217 @cindex @code{changequote}
9219 The temptation is often high to bypass proper quotation, in particular
9220 when it's late at night. Then, many experienced Autoconf hackers
9221 finally surrender to the dark side of the force and use the ultimate
9222 weapon: @code{changequote}.
9224 The M4 builtin @code{changequote} belongs to a set of primitives that
9225 allow one to adjust the syntax of the language to adjust it to one's
9226 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9227 quotes, but in the context of shell programming (and actually of most
9228 programming languages), that's about the worst choice one can make:
9229 because of strings and back-quoted expressions in shell code (such as
9230 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9231 programming languages (as in @samp{'0'}), there are many unbalanced
9232 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9233 not impossible. In order to make M4 useful in such a context, its
9234 designers have equipped it with @code{changequote}, which makes it
9235 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9236 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9237 because they are unlikely characters, but @emph{because they are
9238 characters unlikely to be unbalanced}.
9240 There are other magic primitives, such as @code{changecom} to specify
9241 what syntactic forms are comments (it is common to see
9242 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9243 @code{changeword} and @code{changesyntax} to change other syntactic
9244 details (such as the character to denote the @var{n}th argument, @samp{$} by
9245 default, the parenthesis around arguments, etc.).
9247 These primitives are really meant to make M4 more useful for specific
9248 domains: they should be considered like command line options:
9249 @option{--quotes}, @option{--comments}, @option{--words}, and
9250 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9251 it makes M4 libraries self contained (no need for additional options).
9253 There lies the problem@enddots{}
9257 The problem is that it is then tempting to use them in the middle of an
9258 M4 script, as opposed to its initialization. This, if not carefully
9259 thought out, can lead to disastrous effects: @emph{you are changing the
9260 language in the middle of the execution}. Changing and restoring the
9261 syntax is often not enough: if you happened to invoke macros in between,
9262 these macros are lost, as the current syntax is probably not
9263 the one they were implemented with.
9265 @c FIXME: I've been looking for a short, real case example, but I
9270 @subsection Quadrigraphs
9271 @cindex quadrigraphs
9272 @cindex @samp{@@S|@@}
9273 @cindex @samp{@@&t@@}
9274 @c Info cannot handle `:' in index entries.
9275 @c @cindex @samp{@@<:@@}
9276 @c @cindex @samp{@@:>@@}
9277 @c @cindex @samp{@@%:@@}
9279 When writing an Autoconf macro you may occasionally need to generate
9280 special characters that are difficult to express with the standard
9281 Autoconf quoting rules. For example, you may need to output the regular
9282 expression @samp{[^[]}, which matches any character other than @samp{[}.
9283 This expression contains unbalanced brackets so it cannot be put easily
9286 You can work around this problem by using one of the following
9302 Quadrigraphs are replaced at a late stage of the translation process,
9303 after @command{m4} is run, so they do not get in the way of M4 quoting.
9304 For example, the string @samp{^@@<:@@}, independently of its quotation,
9305 appears as @samp{^[} in the output.
9307 The empty quadrigraph can be used:
9310 @item to mark trailing spaces explicitly
9312 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9314 @item to produce other quadrigraphs
9316 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9318 @item to escape @emph{occurrences} of forbidden patterns
9320 For instance you might want to mention @code{AC_FOO} in a comment, while
9321 still being sure that @command{autom4te} still catches unexpanded
9322 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9325 The name @samp{@@&t@@} was suggested by Paul Eggert:
9328 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9329 own invention, but the @samp{t} came from the source code of the
9330 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9331 and which used @samp{mt} to denote the empty string. In C, it would
9332 have looked like something like:
9335 char const mt[] = "";
9339 but of course the source code was written in Algol 68.
9341 I don't know where he got @samp{mt} from: it could have been his own
9342 invention, and I suppose it could have been a common pun around the
9343 Cambridge University computer lab at the time.
9346 @node Quotation Rule Of Thumb
9347 @subsection Quotation Rule Of Thumb
9349 To conclude, the quotation rule of thumb is:
9351 @center @emph{One pair of quotes per pair of parentheses.}
9353 Never over-quote, never under-quote, in particular in the definition of
9354 macros. In the few places where the macros need to use brackets
9355 (usually in C program text or regular expressions), properly quote
9356 @emph{the arguments}!
9358 It is common to read Autoconf programs with snippets like:
9362 changequote(<<, >>)dnl
9364 #ifndef tzname /* For SGI. */
9365 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9367 changequote([, ])dnl
9368 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9372 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9373 double quoting, so you just need:
9378 #ifndef tzname /* For SGI. */
9379 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9382 [ac_cv_var_tzname=yes],
9383 [ac_cv_var_tzname=no])
9387 The M4-fluent reader might note that these two examples are rigorously
9388 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9389 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9390 quotes are not part of the arguments!
9392 Simplified, the example above is just doing this:
9395 changequote(<<, >>)dnl
9397 changequote([, ])dnl
9407 With macros that do not double quote their arguments (which is the
9408 rule), double-quote the (risky) literals:
9411 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9413 #ifndef tzname /* For SGI. */
9414 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9416 [atoi (*tzname);])],
9417 [ac_cv_var_tzname=yes],
9418 [ac_cv_var_tzname=no])
9421 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9422 should be using @code{AC_LINK_IFELSE} instead.
9424 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9425 where quoting does not suffice.
9427 When you create a @command{configure} script using newly written macros,
9428 examine it carefully to check whether you need to add more quotes in
9429 your macros. If one or more words have disappeared in the M4
9430 output, you need more quotes. When in doubt, quote.
9432 However, it's also possible to put on too many layers of quotes. If
9433 this happens, the resulting @command{configure} script may contain
9434 unexpanded macros. The @command{autoconf} program checks for this problem
9435 by looking for the string @samp{AC_} in @file{configure}. However, this
9436 heuristic does not work in general: for example, it does not catch
9437 overquoting in @code{AC_DEFINE} descriptions.
9440 @c ---------------------------------------- Using autom4te
9442 @node Using autom4te
9443 @section Using @command{autom4te}
9445 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9446 to Autoconf per se, heavily rely on M4. All these different uses
9447 revealed common needs factored into a layer over M4:
9448 @command{autom4te}@footnote{
9450 Yet another great name from Lars J. Aas.
9454 @command{autom4te} is a preprocessor that is like @command{m4}.
9455 It supports M4 extensions designed for use in tools like Autoconf.
9458 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9459 * Customizing autom4te:: Customizing the Autoconf package
9462 @node autom4te Invocation
9463 @subsection Invoking @command{autom4te}
9465 The command line arguments are modeled after M4's:
9468 autom4te @var{options} @var{files}
9473 where the @var{files} are directly passed to @command{m4}. By default,
9474 @acronym{GNU} M4 is found during configuration, but the environment
9476 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9477 to the regular expansion, it handles the replacement of the quadrigraphs
9478 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9479 output. It supports an extended syntax for the @var{files}:
9482 @item @var{file}.m4f
9483 This file is an M4 frozen file. Note that @emph{all the previous files
9484 are ignored}. See the option @option{--melt} for the rationale.
9487 If found in the library path, the @var{file} is included for expansion,
9488 otherwise it is ignored instead of triggering a failure.
9493 Of course, it supports the Autoconf common subset of options:
9498 Print a summary of the command line options and exit.
9502 Print the version number of Autoconf and exit.
9506 Report processing steps.
9510 Don't remove the temporary files and be even more verbose.
9512 @item --include=@var{dir}
9514 Also look for input files in @var{dir}. Multiple invocations
9517 @item --output=@var{file}
9518 @itemx -o @var{file}
9519 Save output (script or trace) to @var{file}. The file @option{-} stands
9520 for the standard output.
9525 As an extension of @command{m4}, it includes the following options:
9528 @item --warnings=@var{category}
9529 @itemx -W @var{category}
9531 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9532 Report the warnings related to @var{category} (which can actually be a
9533 comma separated list). @xref{Reporting Messages}, macro
9534 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9539 report all the warnings
9545 treats warnings as errors
9547 @item no-@var{category}
9548 disable warnings falling into @var{category}
9551 Warnings about @samp{syntax} are enabled by default, and the environment
9552 variable @env{WARNINGS}, a comma separated list of categories, is
9553 honored. @samp{autom4te -W @var{category}} actually
9554 behaves as if you had run:
9557 autom4te --warnings=syntax,$WARNINGS,@var{category}
9561 For example, if you want to disable defaults and @env{WARNINGS}
9562 of @command{autom4te}, but enable the warnings about obsolete
9563 constructs, you would use @option{-W none,obsolete}.
9566 @cindex Macro invocation stack
9567 @command{autom4te} displays a back trace for errors, but not for
9568 warnings; if you want them, just pass @option{-W error}.
9572 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9573 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9574 are executed only when the files are frozen, typically
9575 @code{m4_define}. For instance, running:
9578 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9582 is roughly equivalent to running:
9585 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9592 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9599 m4 --reload-state=4.m4f input.m4
9604 Produce a frozen state file. @command{autom4te} freezing is stricter
9605 than M4's: it must produce no warnings, and no output other than empty
9606 lines (a line with white space is @emph{not} empty) and comments
9607 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9608 this option takes no argument:
9611 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9618 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9621 @item --mode=@var{octal-mode}
9622 @itemx -m @var{octal-mode}
9623 Set the mode of the non-traces output to @var{octal-mode}; by default
9629 @cindex @file{autom4te.cache}
9630 As another additional feature over @command{m4}, @command{autom4te}
9631 caches its results. @acronym{GNU} M4 is able to produce a regular
9632 output and traces at the same time. Traces are heavily used in the
9633 @acronym{GNU} Build System: @command{autoheader} uses them to build
9634 @file{config.h.in}, @command{autoreconf} to determine what
9635 @acronym{GNU} Build System components are used, @command{automake} to
9636 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9637 traces are cached while performing regular expansion,
9638 and conversely. This cache is (actually, the caches are) stored in
9639 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9640 at any moment (especially if for some reason @command{autom4te}
9641 considers it is trashed).
9644 @item --cache=@var{directory}
9645 @itemx -C @var{directory}
9646 Specify the name of the directory where the result should be cached.
9647 Passing an empty value disables caching. Be sure to pass a relative
9648 file name, as for the time being, global caches are not supported.
9651 Don't cache the results.
9655 If a cache is used, consider it obsolete (but update it anyway).
9660 Because traces are so important to the @acronym{GNU} Build System,
9661 @command{autom4te} provides high level tracing features as compared to
9662 M4, and helps exploiting the cache:
9665 @item --trace=@var{macro}[:@var{format}]
9666 @itemx -t @var{macro}[:@var{format}]
9667 Trace the invocations of @var{macro} according to the @var{format}.
9668 Multiple @option{--trace} arguments can be used to list several macros.
9669 Multiple @option{--trace} arguments for a single macro are not
9670 cumulative; instead, you should just make @var{format} as long as
9673 The @var{format} is a regular string, with newlines if desired, and
9674 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9675 use the following special escapes:
9679 The character @samp{$}.
9682 The file name from which @var{macro} is called.
9685 The line number from which @var{macro} is called.
9688 The depth of the @var{macro} call. This is an M4 technical detail that
9689 you probably don't want to know about.
9692 The name of the @var{macro}.
9695 The @var{num}th argument of the call to @var{macro}.
9699 @itemx $@{@var{separator}@}@@
9700 All the arguments passed to @var{macro}, separated by the character
9701 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9702 argument is quoted, i.e., enclosed in a pair of square brackets.
9706 @itemx $@{@var{separator}@}*
9707 As above, but the arguments are not quoted.
9711 @itemx $@{@var{separator}@}%
9712 As above, but the arguments are not quoted, all new line characters in
9713 the arguments are smashed, and the default separator is @samp{:}.
9715 The escape @samp{$%} produces single-line trace outputs (unless you put
9716 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9720 @xref{autoconf Invocation}, for examples of trace uses.
9722 @item --preselect=@var{macro}
9723 @itemx -p @var{macro}
9724 Cache the traces of @var{macro}, but do not enable traces. This is
9725 especially important to save CPU cycles in the future. For instance,
9726 when invoked, @command{autoconf} preselects all the macros that
9727 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9728 trace, so that running @command{m4} is not needed to trace them: the
9729 cache suffices. This results in a huge speed-up.
9734 @cindex Autom4te Library
9735 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9736 libraries}. They consists in a powerful yet extremely simple feature:
9737 sets of combined command line arguments:
9740 @item --language=@var{language}
9741 @itemx -l @var{language}
9742 Use the @var{language} Autom4te library. Current languages include:
9746 create M4sugar output.
9749 create M4sh executable shell scripts.
9752 create Autotest executable test suites.
9754 @item Autoconf-without-aclocal-m4
9755 create Autoconf executable configure scripts without
9756 reading @file{aclocal.m4}.
9759 create Autoconf executable configure scripts. This language inherits
9760 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9761 additionally reads @file{aclocal.m4}.
9764 @item --prepend-include=@var{dir}
9766 Prepend directory @var{dir} to the search path. This is used to include
9767 the language-specific files before any third-party macros.
9771 @cindex @file{autom4te.cfg}
9772 As an example, if Autoconf is installed in its default location,
9773 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9774 strictly equivalent to the command:
9777 autom4te --prepend-include /usr/local/share/autoconf \
9778 m4sugar/m4sugar.m4f --warnings syntax foo.m4
9782 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9783 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9787 autom4te --prepend-include /usr/local/share/autoconf \
9788 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9792 The definition of the languages is stored in @file{autom4te.cfg}.
9794 @node Customizing autom4te
9795 @subsection Customizing @command{autom4te}
9797 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9798 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9799 as found in the directory from which @command{autom4te} is run). The
9800 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9801 then @file{./.autom4te.cfg}, and finally the command line arguments.
9803 In these text files, comments are introduced with @code{#}, and empty
9804 lines are ignored. Customization is performed on a per-language basis,
9805 wrapped in between a @samp{begin-language: "@var{language}"},
9806 @samp{end-language: "@var{language}"} pair.
9808 Customizing a language stands for appending options (@pxref{autom4te
9809 Invocation}) to the current definition of the language. Options, and
9810 more generally arguments, are introduced by @samp{args:
9811 @var{arguments}}. You may use the traditional shell syntax to quote the
9814 As an example, to disable Autoconf caches (@file{autom4te.cache})
9815 globally, include the following lines in @file{~/.autom4te.cfg}:
9818 ## ------------------ ##
9819 ## User Preferences. ##
9820 ## ------------------ ##
9822 begin-language: "Autoconf-without-aclocal-m4"
9824 end-language: "Autoconf-without-aclocal-m4"
9828 @node Programming in M4sugar
9829 @section Programming in M4sugar
9832 M4 by itself provides only a small, but sufficient, set of all-purpose
9833 macros. M4sugar introduces additional generic macros. Its name was
9834 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9838 * Redefined M4 Macros:: M4 builtins changed in M4sugar
9839 * Looping constructs:: Iteration in M4
9840 * Evaluation Macros:: More quotation and evaluation control
9841 * Text processing Macros:: String manipulation in M4
9842 * Forbidden Patterns:: Catching unexpanded macros
9845 @node Redefined M4 Macros
9846 @subsection Redefined M4 Macros
9868 With a few exceptions, all the M4 native macros are moved in the
9869 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9870 @code{m4_define} etc.
9872 Some M4 macros are redefined, and are slightly incompatible with their
9877 This macro kept its original name: no @code{m4_dnl} is defined.
9880 @defmac m4_defn (@var{macro})
9882 Unlike the M4 builtin, this macro fails if @var{macro} is not
9883 defined. See @code{m4_undefine}.
9886 @defmac m4_exit (@var{exit-status})
9888 This macro corresponds to @code{m4exit}.
9891 @defmac m4_if (@var{comment})
9892 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9893 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9895 This macro corresponds to @code{ifelse}.
9898 @defmac m4_include (@var{file})
9899 @defmacx m4_sinclude (@var{file})
9902 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9905 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9907 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
9908 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9909 provide extended regular expression syntax via @code{epatsubst}.
9912 @defmac m4_popdef (@var{macro})
9914 Unlike the M4 builtin, this macro fails if @var{macro} is not
9915 defined. See @code{m4_undefine}.
9918 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9920 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
9921 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9922 provide extended regular expression syntax via @code{eregexp}.
9925 @defmac m4_wrap (@var{text})
9927 This macro corresponds to @code{m4wrap}.
9929 Posix requires arguments of multiple @code{m4wrap} calls to be
9930 reprocessed at @acronym{EOF} in the same order as the original calls.
9931 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9932 reverse order. Your code should not depend on the order.
9934 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9935 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9936 arguments with intervening spaces. Your code should not pass more than
9939 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9940 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9943 m4_define([foo], [bar])
9944 m4_define([foofoo], [OUCH])
9951 @defmac m4_undefine (@var{macro})
9953 Unlike the M4 builtin, this macro fails if @var{macro} is not
9957 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9961 to recover the behavior of the builtin.
9964 @defmac m4_maketemp (@var{template})
9965 @defmacx m4_mkstemp (@var{template})
9968 Posix requires @code{maketemp} to replace the trailing @samp{X}
9969 characters in @var{template} with the process id, without regards to the
9970 existence of a file by that name, but this a security hole. When this
9971 was pointed out to the Posix folks, they agreed to invent a new macro
9972 @code{mkstemp} that always creates a uniquely named file, but not all
9973 versions of @acronym{GNU} M4 support the new macro. In M4sugar,
9974 @code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other,
9975 and both have the secure semantics regardless of which macro the
9976 underlying M4 provides.
9980 @node Looping constructs
9981 @subsection Looping constructs
9983 The following macros implement loops in M4.
9985 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9987 Loop over the numeric values between @var{first} and @var{last}
9988 including bounds by increments of @var{step}. For each iteration,
9989 expand @var{expression} with the numeric value assigned to @var{var}.
9990 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9991 on the order of the limits. If given, @var{step} has to match this
9995 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9997 Loop over the comma-separated M4 list @var{list}, assigning each value
9998 to @var{var}, and expand @var{expression}. The following example
10002 m4_foreach([myvar], [[foo], [bar, baz]],
10009 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
10010 @msindex{foreach_w}
10011 Loop over the white-space-separated list @var{list}, assigning each value
10012 to @var{var}, and expand @var{expression}.
10014 The deprecated macro @code{AC_FOREACH} is an alias of
10015 @code{m4_foreach_w}.
10020 @node Evaluation Macros
10021 @subsection Evaluation Macros
10023 The following macros give some control over the order of the evaluation
10024 by adding or removing levels of quotes. They are meant for hard-core M4
10027 @defmac m4_dquote (@var{arg1}, @dots{})
10029 Return the arguments as a quoted list of quoted arguments.
10032 @defmac m4_quote (@var{arg1}, @dots{})
10034 Return the arguments as a single entity, i.e., wrap them into a pair of
10038 The following example aims at emphasizing the difference between (i), not
10039 using these macros, (ii), using @code{m4_quote}, and (iii), using
10043 $ @kbd{cat example.m4}
10044 # Overquote, so that quotes are visible.
10045 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
10046 m4_define([mkargs], [1, 2, 3])
10047 m4_define([arg1], [[$1]])
10050 show(m4_quote(a, b))
10051 show(m4_dquote(a, b))
10054 arg1(m4_defn([mkargs]))
10055 arg1(m4_quote(mkargs))
10056 arg1(m4_dquote(mkargs))
10057 $ @kbd{autom4te -l m4sugar example.m4}
10058 $1 = a, $@@ = [a],[b]
10059 $1 = a,b, $@@ = [a,b]
10060 $1 = [a],[b], $@@ = [[a],[b]]
10070 @node Text processing Macros
10071 @subsection Text processing Macros
10073 The following macros may be used to manipulate strings in M4.
10074 They are not intended for casual use.
10076 @defmac m4_re_escape (@var{string})
10077 @msindex{re_escape}
10078 Backslash-escape all characters in @var{string} that are active in
10082 @defmac m4_tolower (@var{string})
10083 @defmacx m4_toupper (@var{string})
10086 Return @var{string} with letters converted to upper or lower case,
10090 @defmac m4_split (@var{string}, @ovar{regexp})
10092 Split @var{string} into an M4 list of elements quoted by @samp{[} and
10093 @samp{]}, while keeping white space at the beginning and at the end.
10094 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
10095 If @var{string} is empty, the result is an empty list.
10098 @defmac m4_normalize (@var{string})
10099 @msindex{normalize}
10100 Remove leading and trailing spaces and tabs, sequences of
10101 backslash-then-newline, and replace multiple spaces and tabs with a
10105 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
10106 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
10108 @msindex{append_uniq}
10109 Redefine @var{macro-name} to its former contents with @var{separator}
10110 and @var{string} added at the end. If @var{macro-name} was undefined
10111 before (but not if it was defined but empty), then no @var{separator} is
10112 added. @code{m4_append} can be used to grow strings, and
10113 @code{m4_append_uniq} to grow strings without duplicating substrings.
10118 @node Forbidden Patterns
10119 @subsection Forbidden Patterns
10120 @cindex Forbidden patterns
10121 @cindex Patterns, forbidden
10123 M4sugar provides a means to define suspicious patterns, patterns
10124 describing tokens which should not be found in the output. For
10125 instance, if an Autoconf @file{configure} script includes tokens such as
10126 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
10127 wrong (typically a macro was not evaluated because of overquotation).
10129 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
10131 @defmac m4_pattern_forbid (@var{pattern})
10132 @msindex{pattern_forbid}
10133 Declare that no token matching @var{pattern} must be found in the output.
10134 Comments are not checked; this can be a problem if, for instance, you
10135 have some macro left unexpanded after an @samp{#include}. No consensus
10136 is currently found in the Autoconf community, as some people consider it
10137 should be valid to name macros in comments (which doesn't make sense to
10138 the author of this documentation, as @samp{#}-comments should document
10139 the output, not the input, documented by @samp{dnl} comments).
10142 Of course, you might encounter exceptions to these generic rules, for
10143 instance you might have to refer to @samp{$m4_flags}.
10145 @defmac m4_pattern_allow (@var{pattern})
10146 @msindex{pattern_allow}
10147 Any token matching @var{pattern} is allowed, including if it matches an
10148 @code{m4_pattern_forbid} pattern.
10151 @node Programming in M4sh
10152 @section Programming in M4sh
10154 @c FIXME: Eventually will become a chapter, as it is not related to
10155 @c programming in M4 per se.
10157 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
10158 scripts. This name was coined by Lars J. Aas, who notes that,
10159 according to the Webster's Revised Unabridged Dictionary (1913):
10162 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
10163 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
10167 A mass of mixed ingredients reduced to a soft pulpy state by beating or
10171 A mixture of meal or bran and water fed to animals.
10174 A mess; trouble. [Obs.] --Beau.@: & Fl.
10179 For the time being, it is not mature enough to be widely used.
10181 M4sh provides portable alternatives for some common shell constructs
10182 that unfortunately are not portable in practice.
10184 @c Deprecated, to be replaced by a better API
10186 @defmac AS_BASENAME (@var{file-name})
10188 Output the non-directory portion of @var{file-name}. For example,
10189 if @code{$file} is @samp{/one/two/three}, the command
10190 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10194 @defmac AS_BOURNE_COMPATIBLE
10195 @asindex{BOURNE_COMPATIBLE}
10196 Set up the shell to be more compatible with the Bourne shell as
10197 standardized by Posix, if possible. This may involve setting
10198 environment variables, or setting options, or similar
10199 implementation-specific actions.
10202 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10204 Expand into a shell @samp{case} statement, where @var{word} is matched
10205 against one or more patterns. @var{if-matched} is run if the
10206 corresponding pattern matched @var{word}, else @var{default} is run.
10209 @defmac AS_DIRNAME (@var{file-name})
10211 Output the directory portion of @var{file-name}. For example,
10212 if @code{$file} is @samp{/one/two/three}, the command
10213 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10216 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10218 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10219 run shell code @var{run-if-true1}, else examine further tests. If no test
10220 exits with a zero status, run shell code @var{run-if-false}, with
10221 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10222 is empty. For example,
10225 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10226 [test "$foo" != no], [HANDLE_FOO([maybe])],
10227 [echo foo not specified])
10231 ensures any required macros of @code{HANDLE_FOO}
10232 are expanded before the first test.
10235 @defmac AS_MKDIR_P (@var{file-name})
10237 Make the directory @var{file-name}, including intervening directories
10238 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10239 except that it is portable to older versions of @command{mkdir} that
10240 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10241 succeeds if @var{file-name} is a symbolic link to an existing directory,
10242 even though Posix is unclear whether @samp{mkdir -p} should
10243 succeed in that case. If creation of @var{file-name} fails, exit the
10246 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10249 @defmac AS_SHELL_SANITIZE
10250 @asindex{SHELL_SANITIZE}
10251 Initialize the shell suitably for @code{configure} scripts. This has
10252 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10253 environment variables for predictable results from configuration tests.
10254 For example, it sets @env{LC_ALL} to change to the default C locale.
10255 @xref{Special Shell Variables}.
10258 @defmac AS_TR_CPP (@var{expression})
10260 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10264 # This outputs "#define HAVE_CHAR_P 1".
10266 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10270 @defmac AS_TR_SH (@var{expression})
10272 Transform @var{expression} into a valid shell variable name. For example:
10275 # This outputs "Have it!".
10276 header="sys/some file.h"
10277 AS_TR_SH([HAVE_$header])=yes
10278 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10282 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10283 @asindex{SET_CATFILE}
10284 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10285 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10286 @var{file} is absolute, etc.).
10290 @node File Descriptor Macros
10291 @section File Descriptor Macros
10293 @cindex standard input
10294 @cindex file descriptors
10295 @cindex descriptors
10296 @cindex low-level output
10297 @cindex output, low-level
10299 The following macros define file descriptors used to output messages
10300 (or input values) from @file{configure} scripts.
10304 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10305 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10306 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10310 However doing so is seldom needed, because Autoconf provides higher
10311 level macros as described below.
10313 @defmac AS_MESSAGE_FD
10314 @asindex{MESSAGE_FD}
10315 The file descriptor for @samp{checking for...} messages and results.
10316 Normally this directs messages to the standard output, however when
10317 @command{configure} is run with the @option{-q} option, messages sent to
10318 @code{AS_MESSAGE_FD} are discarded.
10320 If you want to display some messages, consider using one of the printing
10321 macros (@pxref{Printing Messages}) instead. Copies of messages output
10322 via these macros are also recorded in @file{config.log}.
10325 @defmac AS_MESSAGE_LOG_FD
10326 @asindex{MESSAGE_LOG_FD}
10328 The file descriptor for messages logged to @file{config.log}. Macros
10329 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10330 Compiler}), redirect all output to this descriptor. You may want to do
10331 so if you develop such a low-level macro.
10334 @defmac AS_ORIGINAL_STDIN_FD
10335 @asindex{ORIGINAL_STDIN_FD}
10336 The file descriptor for the original standard input.
10338 When @command{configure} runs, it may accidentally execute an
10339 interactive command that has the same name as the non-interactive meant
10340 to be used or checked. If the standard input was the terminal, such
10341 interactive programs would cause @command{configure} to stop, pending
10342 some user input. Therefore @command{configure} redirects its standard
10343 input from @file{/dev/null} during its initialization. This is not
10344 normally a problem, since @command{configure} normally does not need
10347 In the extreme case where your @file{configure} script really needs to
10348 obtain some values from the original standard input, you can read them
10349 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10353 @c =================================================== Writing Autoconf Macros.
10355 @node Writing Autoconf Macros
10356 @chapter Writing Autoconf Macros
10358 When you write a feature test that could be applicable to more than one
10359 software package, the best thing to do is encapsulate it in a new macro.
10360 Here are some instructions and guidelines for writing Autoconf macros.
10363 * Macro Definitions:: Basic format of an Autoconf macro
10364 * Macro Names:: What to call your new macros
10365 * Reporting Messages:: Notifying @command{autoconf} users
10366 * Dependencies Between Macros:: What to do when macros depend on other macros
10367 * Obsoleting Macros:: Warning about old ways of doing things
10368 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10371 @node Macro Definitions
10372 @section Macro Definitions
10375 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10376 similar to the M4 builtin @code{m4_define} macro. In addition to
10377 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10378 constrain the order in which macros are called (@pxref{Prerequisite
10381 An Autoconf macro definition looks like this:
10384 AC_DEFUN(@var{macro-name}, @var{macro-body})
10387 You can refer to any arguments passed to the macro as @samp{$1},
10388 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10389 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10391 Be sure to properly quote both the @var{macro-body} @emph{and} the
10392 @var{macro-name} to avoid any problems if the macro happens to have
10393 been previously defined.
10395 Each macro should have a header comment that gives its prototype, and a
10396 brief description. When arguments have default values, display them in
10397 the prototype. For example:
10400 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10401 # --------------------------------------
10402 m4_define([AC_MSG_ERROR],
10403 [@{ AS_MESSAGE([error: $1], [2])
10404 exit m4_default([$2], [1]); @}])
10407 Comments about the macro should be left in the header comment. Most
10408 other comments make their way into @file{configure}, so just keep
10409 using @samp{#} to introduce comments.
10412 If you have some special comments about pure M4 code, comments
10413 that make no sense in @file{configure} and in the header comment, then
10414 use the builtin @code{dnl}: it causes M4 to discard the text
10415 through the next newline.
10417 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10418 @code{dnl} is more useful to get rid of the newlines following macros
10419 that produce no output, such as @code{AC_REQUIRE}.
10423 @section Macro Names
10425 All of the Autoconf macros have all-uppercase names starting with
10426 @samp{AC_} to prevent them from accidentally conflicting with other
10427 text. All shell variables that they use for internal purposes have
10428 mostly-lowercase names starting with @samp{ac_}. To ensure that your
10429 macros don't conflict with present or future Autoconf macros, you should
10430 prefix your own macro names and any shell variables they use with some
10431 other sequence. Possibilities include your initials, or an abbreviation
10432 for the name of your organization or software package.
10434 Most of the Autoconf macros' names follow a structured naming convention
10435 that indicates the kind of feature check by the name. The macro names
10436 consist of several words, separated by underscores, going from most
10437 general to most specific. The names of their cache variables use the
10438 same convention (@pxref{Cache Variable Names}, for more information on
10441 The first word of the name after @samp{AC_} usually tells the category
10442 of the feature being tested. Here are the categories used in Autoconf for
10443 specific test macros, the kind of macro that you are more likely to
10444 write. They are also used for cache variables, in all-lowercase. Use
10445 them where applicable; where they're not, invent your own categories.
10449 C language builtin features.
10451 Declarations of C variables in header files.
10453 Functions in libraries.
10455 Posix group owners of files.
10461 Absolute names of files, including programs.
10463 The base names of programs.
10465 Members of aggregates.
10467 Operating system features.
10469 C builtin or declared types.
10471 C variables in libraries.
10474 After the category comes the name of the particular feature being
10475 tested. Any further words in the macro name indicate particular aspects
10476 of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the
10477 C compiler supports @acronym{ISO} Standard C.
10479 An internal macro should have a name that starts with an underscore;
10480 Autoconf internals should therefore start with @samp{_AC_}.
10481 Additionally, a macro that is an internal subroutine of another macro
10482 should have a name that starts with an underscore and the name of that
10483 other macro, followed by one or more words saying what the internal
10484 macro does. For example, @code{AC_PATH_X} has internal macros
10485 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10487 @node Reporting Messages
10488 @section Reporting Messages
10489 @cindex Messages, from @command{autoconf}
10491 When macros statically diagnose abnormal situations, benign or fatal,
10492 they should report them using these macros. For dynamic issues, i.e.,
10493 when @command{configure} is run, see @ref{Printing Messages}.
10495 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10497 Report @var{message} as a warning (or as an error if requested by the
10498 user) if warnings of the @var{category} are turned on. You are
10499 encouraged to use standard categories, which currently include:
10503 messages that don't fall into one of the following categories. Use of an
10504 empty @var{category} is equivalent.
10507 related to cross compilation issues.
10510 use of an obsolete construct.
10513 dubious syntactic constructs, incorrectly ordered macro calls.
10517 @defmac AC_WARNING (@var{message})
10519 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10520 strongly encouraged to use a finer grained category.
10523 @defmac AC_FATAL (@var{message})
10525 Report a severe error @var{message}, and have @command{autoconf} die.
10528 When the user runs @samp{autoconf -W error}, warnings from
10529 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10530 @ref{autoconf Invocation}.
10532 @node Dependencies Between Macros
10533 @section Dependencies Between Macros
10534 @cindex Dependencies between macros
10536 Some Autoconf macros depend on other macros having been called first in
10537 order to work correctly. Autoconf provides a way to ensure that certain
10538 macros are called if needed and a way to warn the user if macros are
10539 called in an order that might cause incorrect operation.
10542 * Prerequisite Macros:: Ensuring required information
10543 * Suggested Ordering:: Warning about possible ordering problems
10544 * One-Shot Macros:: Ensuring a macro is called only once
10547 @node Prerequisite Macros
10548 @subsection Prerequisite Macros
10549 @cindex Prerequisite macros
10550 @cindex Macros, prerequisites
10552 A macro that you write might need to use values that have previously
10553 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10554 examines the output of @code{flex} or @code{lex}, so it depends on
10555 @code{AC_PROG_LEX} having been called first to set the shell variable
10558 Rather than forcing the user of the macros to keep track of the
10559 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10560 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10561 called if it is needed, and only called once.
10563 @defmac AC_REQUIRE (@var{macro-name})
10565 If the M4 macro @var{macro-name} has not already been called, call it
10566 (without any arguments). Make sure to quote @var{macro-name} with
10567 square brackets. @var{macro-name} must have been defined using
10568 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10569 that it has been called.
10571 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10572 must not be called from the top level.
10575 @code{AC_REQUIRE} is often misunderstood. It really implements
10576 dependencies between macros in the sense that if one macro depends upon
10577 another, the latter is expanded @emph{before} the body of the
10578 former. To be more precise, the required macro is expanded before
10579 the outermost defined macro in the current expansion stack.
10580 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10581 @code{FOO}. For instance, this definition of macros:
10585 AC_DEFUN([TRAVOLTA],
10586 [test "$body_temperature_in_celsius" -gt "38" &&
10587 dance_floor=occupied])
10588 AC_DEFUN([NEWTON_JOHN],
10589 [test "$hair_style" = "curly" &&
10590 dance_floor=occupied])
10594 AC_DEFUN([RESERVE_DANCE_FLOOR],
10595 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10596 AC_REQUIRE([TRAVOLTA])
10597 AC_REQUIRE([NEWTON_JOHN])
10603 with this @file{configure.ac}
10606 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10607 RESERVE_DANCE_FLOOR
10608 if test "$dance_floor" = occupied; then
10609 AC_MSG_ERROR([cannot pick up here, let's move])
10614 does not leave you with a better chance to meet a kindred soul at
10615 other times than Saturday night since it expands into:
10619 test "$body_temperature_in_Celsius" -gt "38" &&
10620 dance_floor=occupied
10621 test "$hair_style" = "curly" &&
10622 dance_floor=occupied
10624 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10631 This behavior was chosen on purpose: (i) it prevents messages in
10632 required macros from interrupting the messages in the requiring macros;
10633 (ii) it avoids bad surprises when shell conditionals are used, as in:
10638 AC_REQUIRE([SOME_CHECK])
10645 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10646 enforce expansion of required macros outside of shell conditional
10647 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10648 at the beginning of a macro. You can use @code{dnl} to avoid the empty
10651 @node Suggested Ordering
10652 @subsection Suggested Ordering
10653 @cindex Macros, ordering
10654 @cindex Ordering macros
10656 Some macros should be run before another macro if both are called, but
10657 neither @emph{requires} that the other be called. For example, a macro
10658 that changes the behavior of the C compiler should be called before any
10659 macros that run the C compiler. Many of these dependencies are noted in
10662 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10663 with this kind of dependency appear out of order in a
10664 @file{configure.ac} file. The warning occurs when creating
10665 @command{configure} from @file{configure.ac}, not when running
10666 @command{configure}.
10668 For example, @code{AC_PROG_CPP} checks whether the C compiler
10669 can run the C preprocessor when given the @option{-E} option. It should
10670 therefore be called after any macros that change which C compiler is
10671 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
10674 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10678 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10679 when @code{AC_PROG_CC} is called.
10681 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10683 Make M4 print a warning message to the standard error output if
10684 @var{called-macro-name} has already been called. @var{this-macro-name}
10685 should be the name of the macro that is calling @code{AC_BEFORE}. The
10686 macro @var{called-macro-name} must have been defined using
10687 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10688 that it has been called.
10691 @node One-Shot Macros
10692 @subsection One-Shot Macros
10693 @cindex One-shot macros
10694 @cindex Macros, called once
10696 Some macros should be called only once, either because calling them
10697 multiple time is unsafe, or because it is bad style. For instance
10698 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10699 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10700 sense to run these expensive checks more than once. Such one-shot
10701 macros can be defined using @code{AC_DEFUN_ONCE}.
10703 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10704 @acindex{DEFUN_ONCE}
10706 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10707 Definitions}), and emit a warning any time the macro is called more than
10711 Obviously it is not sensible to evaluate a macro defined by
10712 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10713 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10716 @node Obsoleting Macros
10717 @section Obsoleting Macros
10718 @cindex Obsoleting macros
10719 @cindex Macros, obsoleting
10721 Configuration and portability technology has evolved over the years.
10722 Often better ways of solving a particular problem are developed, or
10723 ad-hoc approaches are systematized. This process has occurred in many
10724 parts of Autoconf. One result is that some of the macros are now
10725 considered @dfn{obsolete}; they still work, but are no longer considered
10726 the best thing to do, hence they should be replaced with more modern
10727 macros. Ideally, @command{autoupdate} should replace the old macro calls
10728 with their modern implementation.
10730 Autoconf provides a simple means to obsolete a macro.
10732 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10734 Define @var{old-macro} as @var{implementation}. The only difference
10735 with @code{AC_DEFUN} is that the user is warned that
10736 @var{old-macro} is now obsolete.
10738 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10739 replaced by the modern @var{implementation}. @var{message} should
10740 include information on what to do after running @command{autoupdate};
10741 @command{autoupdate} prints it as a warning, and includes it
10742 in the updated @file{configure.ac} file.
10744 The details of this macro are hairy: if @command{autoconf} encounters an
10745 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10746 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
10747 macros are expanded here, while all other macros are disabled and
10748 appear literally in the updated @file{configure.ac}.
10751 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10753 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10754 with the same parameters. This happens for example if the macro was renamed.
10758 @section Coding Style
10759 @cindex Coding style
10761 The Autoconf macros follow a strict coding style. You are encouraged to
10762 follow this style, especially if you intend to distribute your macro,
10763 either by contributing it to Autoconf itself, or via other means.
10765 The first requirement is to pay great attention to the quotation. For
10766 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10768 Do not try to invent new interfaces. It is likely that there is a macro
10769 in Autoconf that resembles the macro you are defining: try to stick to
10770 this existing interface (order of arguments, default values, etc.). We
10771 @emph{are} conscious that some of these interfaces are not perfect;
10772 nevertheless, when harmless, homogeneity should be preferred over
10775 Be careful about clashes both between M4 symbols and between shell
10778 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10779 you are unlikely to generate conflicts. Nevertheless, when you need to
10780 set a special value, @emph{avoid using a regular macro name}; rather,
10781 use an ``impossible'' name. For instance, up to version 2.13, the macro
10782 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10783 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10784 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10785 impossible to @samp{AC_SUBST(FILE)}! In this case,
10786 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10787 have been used (yes, with the parentheses).
10788 @c or better yet, high-level macros such as @code{m4_expand_once}
10790 No Autoconf macro should ever enter the user-variable name space; i.e.,
10791 except for the variables that are the actual result of running the
10792 macro, all shell variables should start with @code{ac_}. In
10793 addition, small macros or any macro that is likely to be embedded in
10794 other macros should be careful not to use obvious names.
10797 Do not use @code{dnl} to introduce comments: most of the comments you
10798 are likely to write are either header comments which are not output
10799 anyway, or comments that should make their way into @file{configure}.
10800 There are exceptional cases where you do want to comment special M4
10801 constructs, in which case @code{dnl} is right, but keep in mind that it
10804 M4 ignores the leading blanks and newlines before each argument.
10805 Use this feature to
10806 indent in such a way that arguments are (more or less) aligned with the
10807 opening parenthesis of the macro being called. For instance, instead of
10810 AC_CACHE_CHECK(for EMX OS/2 environment,
10812 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10813 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10820 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10821 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10822 [ac_cv_emxos2=yes],
10823 [ac_cv_emxos2=no])])
10830 AC_CACHE_CHECK([for EMX OS/2 environment],
10832 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10833 [return __EMX__;])],
10834 [ac_cv_emxos2=yes],
10835 [ac_cv_emxos2=no])])
10838 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10839 cross-compiling, provide a pessimistic value (typically @samp{no}).
10841 Feel free to use various tricks to prevent auxiliary tools, such as
10842 syntax-highlighting editors, from behaving improperly. For instance,
10846 m4_bpatsubst([$1], [$"])
10853 m4_bpatsubst([$1], [$""])
10857 so that Emacsen do not open an endless ``string'' at the first quote.
10858 For the same reasons, avoid:
10868 test $[@@%:@@] != 0
10872 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10873 breaking the bracket-matching highlighting from Emacsen. Note the
10874 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
10875 not escape when it is unnecessary. Common examples of useless quotation
10876 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10877 etc. If you add portability issues to the picture, you'll prefer
10878 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10879 better than hacking Autoconf @code{:-)}.
10881 When using @command{sed}, don't use @option{-e} except for indenting
10882 purposes. With the @code{s} and @code{y} commands, the preferred
10883 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10884 or replacement, in which case you should use @samp{|}, or optionally
10885 @samp{,} if you know the pattern and replacement cannot contain a file
10886 name. If none of these characters will do, choose a printable character
10887 that cannot appear in the pattern or replacement. Characters from the
10888 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10889 replacement might contain a file name, since they have special meaning
10890 to the shell and are less likely to occur in file names.
10892 @xref{Macro Definitions}, for details on how to define a macro. If a
10893 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10894 of an @code{AC_REQUIRE} directive, and macros required by other macros
10895 inside arguments do not need to be expanded before this macro, then
10896 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
10897 All the @code{AC_REQUIRE} statements should be at the beginning of the
10898 macro, and each statement should be followed by @code{dnl}.
10900 You should not rely on the number of arguments: instead of checking
10901 whether an argument is missing, test that it is not empty. It provides
10902 both a simpler and a more predictable interface to the user, and saves
10903 room for further arguments.
10905 Unless the macro is short, try to leave the closing @samp{])} at the
10906 beginning of a line, followed by a comment that repeats the name of the
10907 macro being defined. This introduces an additional newline in
10908 @command{configure}; normally, that is not a problem, but if you want to
10909 remove it you can use @samp{[]dnl} on the last line. You can similarly
10910 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
10911 is recommended instead of @samp{dnl} to ensure that M4 does not
10912 interpret the @samp{dnl} as being attached to the preceding text or
10913 macro output. For example, instead of:
10916 AC_DEFUN([AC_PATH_X],
10917 [AC_MSG_CHECKING([for X])
10919 @r{# @dots{}omitted@dots{}}
10920 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10928 AC_DEFUN([AC_PATH_X],
10929 [AC_REQUIRE_CPP()[]dnl
10930 AC_MSG_CHECKING([for X])
10931 @r{# @dots{}omitted@dots{}}
10932 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10937 If the macro is long, try to split it into logical chunks. Typically,
10938 macros that check for a bug in a function and prepare its
10939 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10940 this setup. Do not hesitate to introduce auxiliary macros to factor
10943 In order to highlight the recommended coding style, here is a macro
10944 written the old way:
10947 dnl Check for EMX on OS/2.
10949 AC_DEFUN(_AC_EMXOS2,
10950 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10951 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10952 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10953 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10962 # Check for EMX on OS/2.
10963 m4_define([_AC_EMXOS2],
10964 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10965 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10966 [ac_cv_emxos2=yes],
10967 [ac_cv_emxos2=no])])
10968 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10975 @c ============================================= Portable Shell Programming
10977 @node Portable Shell
10978 @chapter Portable Shell Programming
10979 @cindex Portable shell programming
10981 When writing your own checks, there are some shell-script programming
10982 techniques you should avoid in order to make your code portable. The
10983 Bourne shell and upward-compatible shells like the Korn shell and Bash
10984 have evolved over the years, but to prevent trouble, do not take
10985 advantage of features that were added after Unix version 7, circa
10986 1977 (@pxref{Systemology}).
10988 You should not use shell functions, aliases, negated character
10989 classes, or other features that are not found in all Bourne-compatible
10990 shells; restrict yourself to the lowest common denominator. Even
10991 @code{unset} is not supported by all shells!
10993 Some ancient systems have quite
10994 small limits on the length of the @samp{#!} line; for instance, 32
10995 bytes (not including the newline) on SunOS 4.
10996 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10997 required a single space between the @samp{#!} and the @samp{/}.
10998 However, these ancient systems are no longer of practical concern.
11000 The set of external programs you should run in a @command{configure} script
11001 is fairly small. @xref{Utilities in Makefiles, , Utilities in
11002 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
11003 restriction allows users to start out with a fairly small set of
11004 programs and build the rest, avoiding too many interdependencies between
11007 Some of these external utilities have a portable subset of features; see
11008 @ref{Limitations of Usual Tools}.
11010 There are other sources of documentation about shells. The
11011 specification for the Posix
11012 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
11013 Command Language}, though more generous than the restrictive shell
11014 subset described above, is fairly portable nowadays. Also please see
11015 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
11018 * Shellology:: A zoology of shells
11019 * Here-Documents:: Quirks and tricks
11020 * File Descriptors:: FDs and redirections
11021 * File System Conventions:: File names
11022 * Shell Pattern Matching:: Pattern matching
11023 * Shell Substitutions:: Variable and command expansions
11024 * Assignments:: Varying side effects of assignments
11025 * Parentheses:: Parentheses in shell scripts
11026 * Slashes:: Slashes in shell scripts
11027 * Special Shell Variables:: Variables you should not change
11028 * Limitations of Builtins:: Portable use of not so portable /bin/sh
11029 * Limitations of Usual Tools:: Portable use of portable tools
11033 @section Shellology
11036 There are several families of shells, most prominently the Bourne family
11037 and the C shell family which are deeply incompatible. If you want to
11038 write portable shell scripts, avoid members of the C shell family. The
11039 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
11040 Shell difference FAQ} includes a small history of Posix shells, and a
11041 comparison between several of them.
11043 Below we describe some of the members of the Bourne shell family.
11048 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
11049 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
11050 bugs that are fixed in the 0.3.x series, but portable shell scripts
11051 should work around them, since version 0.2 is still shipped with many
11052 @acronym{GNU}/Linux distributions.
11054 To be compatible with Ash 0.2:
11058 don't use @samp{$?} after expanding empty or unset variables,
11059 or at the start of an @command{eval}:
11065 echo "Do not use it: $?"
11067 eval 'echo "Do not use it: $?"'
11071 don't use command substitution within variable expansion:
11078 beware that single builtin substitutions are not performed by a
11079 subshell, hence their effect applies to the current shell! @xref{Shell
11080 Substitutions}, item ``Command Substitution''.
11085 To detect whether you are running Bash, test whether
11086 @code{BASH_VERSION} is set. To require
11087 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
11088 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
11089 Manual}, for details.
11091 @item Bash 2.05 and later
11092 @cindex Bash 2.05 and later
11093 Versions 2.05 and later of Bash use a different format for the
11094 output of the @command{set} builtin, designed to make evaluating its
11095 output easier. However, this output is not compatible with earlier
11096 versions of Bash (or with many other shells, probably). So if
11097 you use Bash 2.05 or higher to execute @command{configure},
11098 you'll need to use Bash 2.05 for all other build tasks as well.
11103 @prindex @samp{ksh}
11104 @prindex @samp{ksh88}
11105 @prindex @samp{ksh93}
11106 The Korn shell is compatible with the Bourne family and it mostly
11107 conforms to Posix. It has two major variants commonly
11108 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
11109 release. It is usually called @command{ksh}, but is called @command{sh}
11110 on some hosts if you set your path appropriately.
11112 Solaris systems have three variants:
11113 @prindex @command{/usr/bin/ksh} on Solaris
11114 @command{/usr/bin/ksh} is @samp{ksh88}; it is
11115 standard on Solaris 2.0 and later.
11116 @prindex @command{/usr/xpg4/bin/sh} on Solaris
11117 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
11118 @samp{ksh88}; it is standard on Solaris 9 and later.
11119 @prindex @command{/usr/dt/bin/dtksh} on Solaris
11120 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
11121 Variants that are not standard may be parts of optional
11122 packages. There is no extra charge for these packages, but they are
11123 not part of a minimal OS install and therefore some installations may
11126 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
11127 is also available as @command{/usr/bin/posix/sh}. If the environment
11128 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11129 the standard shell conform to Posix.
11132 @prindex @samp{pdksh}
11133 A public-domain clone of the Korn shell called @command{pdksh} is widely
11134 available: it has most of the @samp{ksh88} features along with a few of
11135 its own. It usually sets @code{KSH_VERSION}, except if invoked as
11136 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
11137 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
11138 @command{pdksh} 5.2.14 (the latest stable version as of January 2007)
11139 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
11140 at least one respect:
11143 $ @kbd{echo "`echo \"hello\"`"}
11145 $ @kbd{set -o posix}
11146 $ @kbd{echo "`echo \"hello\"`"}
11150 The last line of output contains spurious quotes. This is yet another
11151 reason why portable shell code should not contain
11152 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
11157 To detect whether you are running @command{zsh}, test whether
11158 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
11159 compatible with the Bourne shell: you must execute @samp{emulate sh},
11160 and for @command{zsh} versions before 3.1.6-dev-18 you must also
11161 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
11162 zsh, The Z Shell Manual}, for details.
11164 The default Mac OS X @command{sh} was originally Zsh; it was changed to
11165 Bash in Mac OS X 10.2.
11168 The following discussion between Russ Allbery and Robert Lipe is worth
11175 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
11176 leads to a permanent deadlock. Vendors don't want to break users'
11177 existing shell scripts, and there are some corner cases in the Bourne
11178 shell that are not completely compatible with a Posix shell. Thus,
11179 vendors who have taken this route will @emph{never} (OK@dots{}``never say
11180 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11188 This is exactly the problem. While most (at least most System V's) do
11189 have a Bourne shell that accepts shell functions most vendor
11190 @command{/bin/sh} programs are not the Posix shell.
11192 So while most modern systems do have a shell @emph{somewhere} that meets the
11193 Posix standard, the challenge is to find it.
11196 @node Here-Documents
11197 @section Here-Documents
11198 @cindex Here-documents
11199 @cindex Shell here-documents
11201 Don't rely on @samp{\} being preserved just because it has no special
11202 meaning together with the next symbol. In the native @command{sh}
11203 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11204 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11205 use @samp{\\} to get @samp{\}.
11207 With Open@acronym{BSD} 2.7's @command{sh}
11223 bash-2.04$ @kbd{cat <<EOF
11230 Some shells mishandle large here-documents: for example,
11231 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11232 derived from Korn shell version M-12/28/93d, mishandle braced variable
11233 expansion that crosses a 1024- or 4096-byte buffer boundary
11234 within a here-document. Only the part of the variable name after the boundary
11235 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11236 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11237 boundary, the shell reports an error, as if you used @code{$@{@}}.
11238 Instead of @code{$@{variable-default@}}, the shell may expand
11239 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11240 be worked around by omitting the braces: @code{$variable}. The bug was fixed in
11241 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11242 still shipping older versions with the bug.
11244 Many shells (including the Bourne shell) implement here-documents
11245 inefficiently. In particular, some shells can be extremely inefficient when
11246 a single statement contains many here-documents. For instance if your
11247 @file{configure.ac} includes something like:
11251 if <cross_compiling>; then
11252 assume this and that
11256 check something else
11264 A shell parses the whole @code{if}/@code{fi} construct, creating
11265 temporary files for each here-document in it. Some shells create links
11266 for such here-documents on every @code{fork}, so that the clean-up code
11267 they had installed correctly removes them. It is creating the links
11268 that can take the shell forever.
11270 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11271 @code{if}/@code{fi} constructs, would improve the performance
11272 significantly. Anyway, this kind of construct is not exactly the
11273 typical use of Autoconf. In fact, it's even not recommended, because M4
11274 macros can't look into shell conditionals, so we may fail to expand a
11275 macro when it was expanded before in a conditional path, and the
11276 condition turned out to be false at runtime, and we end up not
11277 executing the macro at all.
11279 @node File Descriptors
11280 @section File Descriptors
11281 @cindex Descriptors
11282 @cindex File descriptors
11283 @cindex Shell file descriptors
11285 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11286 stderr, even for subshells. This might result in undesirable content
11287 if you meant to capture the standard-error output of the inner command:
11290 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11292 + eval echo foo >&2
11295 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11297 + eval 'echo foo >&2'
11300 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11301 @i{# Traces on startup files deleted here.}
11303 +zsh:1> eval echo foo >&2
11309 One workaround is to grep out uninteresting lines, hoping not to remove
11312 If you intend to redirect both standard error and standard output,
11313 redirect standard output first. This works better with @acronym{HP-UX},
11314 since its shell mishandles tracing if standard error is redirected
11318 $ @kbd{sh -x -c ': 2>err >out'}
11320 + 2> err $ @kbd{cat err}
11324 Don't try to redirect the standard error of a command substitution. It
11325 must be done @emph{inside} the command substitution. When running
11326 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11327 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11329 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11330 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11332 Don't redirect the same file descriptor several times, as you are doomed
11333 to failure under Ultrix.
11336 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11338 $ @kbd{eval 'echo matter >fullness' >void}
11340 $ @kbd{eval '(echo matter >fullness)' >void}
11342 $ @kbd{(eval '(echo matter >fullness)') >void}
11343 Ambiguous output redirect.
11347 In each case the expected result is of course @file{fullness} containing
11348 @samp{matter} and @file{void} being empty.
11350 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11351 subsidiary program. If any of these descriptors is closed, the
11352 operating system may open an unspecified file for the descriptor in the
11353 new process image. Posix says this may be done only if the subsidiary
11354 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11357 Don't rely on open file descriptors being open in child processes. In
11358 @command{ksh}, file descriptors above 2 which are opened using
11359 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11360 that involved in the fork-and-exec which runs a program or script).
11361 Thus, using @command{sh}, we have:
11364 $ @kbd{cat ./descrips}
11386 Within the process which runs the @samp{descrips} script, file
11387 descriptor 5 is closed.
11389 @acronym{DOS} variants cannot rename or remove open files, such as in
11390 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11391 perfectly portable among Posix hosts.
11393 A few ancient systems reserved some file descriptors. By convention,
11394 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11395 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11396 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11397 1990), though we don't now remember what it was. Both these systems are
11398 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11399 other file descriptors.
11401 @node File System Conventions
11402 @section File System Conventions
11403 @cindex File system conventions
11405 Autoconf uses shell-script processing extensively, so the file names
11406 that it processes should not contain characters that are special to the
11407 shell. Special characters include space, tab, newline, @sc{nul}, and
11411 " # $ & ' ( ) * ; < = > ? [ \ ` |
11414 Also, file names should not begin with @samp{~} or @samp{-}, and should
11415 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11416 immediately after @samp{:}. On Posix-like platforms, directory names
11417 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11420 These restrictions apply not only to the files that you distribute, but
11421 also to the absolute file names of your source, build, and destination
11424 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11425 they should be avoided.
11427 Posix lets implementations treat leading @file{//} specially, but
11428 requires leading @file{///} and beyond to be equivalent to @file{/}.
11429 Most Unix variants treat @file{//} like @file{/}. However, some treat
11430 @file{//} as a ``super-root'' that can provide access to files that are
11431 not otherwise reachable from @file{/}. The super-root tradition began
11432 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11435 While @command{autoconf} and friends are usually run on some Posix
11436 variety, they can be used on other systems, most notably @acronym{DOS}
11437 variants. This impacts several assumptions regarding file names.
11440 For example, the following code:
11447 foo_dir=$dots$foo_dir ;;
11452 fails to properly detect absolute file names on those systems, because
11453 they can use a drivespec, and usually use a backslash as directory
11454 separator. If you want to be portable to @acronym{DOS} variants (at the
11455 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11456 you can check for absolute file names like this:
11460 [\\/]* | ?:[\\/]* ) # Absolute
11463 foo_dir=$dots$foo_dir ;;
11468 Make sure you quote the brackets if appropriate and keep the backslash as
11469 first character (@pxref{Limitations of Builtins}).
11471 Also, because the colon is used as part of a drivespec, these systems don't
11472 use it as path separator. When creating or accessing paths, you can use the
11473 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11474 to the appropriate value for the build system (@samp{:} or @samp{;}) when it
11477 File names need extra care as well. While @acronym{DOS} variants
11478 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11479 are usually able to handle long file names properly, there are still
11480 limitations that can seriously break packages. Several of these issues
11481 can be easily detected by the
11482 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11485 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11486 indicate where they apply: @sc{sfn} means the issues are only relevant to
11487 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11488 variants, while @sc{lfn} identifies problems that exist even under
11489 Microsoft Windows variants.
11492 @item No multiple dots (@sc{sfn})
11493 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11494 important thing to remember when building a portable configure script,
11495 as @command{autoconf} uses a .in suffix for template files.
11497 This is perfectly OK on Posix variants:
11500 AC_CONFIG_HEADERS([config.h])
11501 AC_CONFIG_FILES([source.c foo.bar])
11506 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11507 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11508 to @acronym{DOS}-based environments, you should use this instead:
11511 AC_CONFIG_HEADERS([config.h:config.hin])
11512 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11516 @item No leading dot (@sc{sfn})
11517 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11518 not important for @command{autoconf}.
11520 @item Case insensitivity (@sc{lfn})
11521 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11522 file called @samp{INSTALL} and a directory called @samp{install}. This
11523 also affects @command{make}; if there's a file called @samp{INSTALL} in
11524 the directory, @samp{make install} does nothing (unless the
11525 @samp{install} target is marked as PHONY).
11527 @item The 8+3 limit (@sc{sfn})
11528 Because the @acronym{DOS} file system only stores the first 8 characters of
11529 the file name and the first 3 of the extension, those must be unique.
11530 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11531 @file{foobar-prettybird.c} all resolve to the same file name
11532 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11533 @file{foo.bartender}.
11535 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11537 tails in the short version of file names to make them unique. However, a
11538 registry setting can turn this behavior off. While this makes it
11539 possible to share file trees containing long file names between @sc{sfn}
11540 and @sc{lfn} environments, it also means the above problem applies there
11543 @item Invalid characters (@sc{lfn})
11544 Some characters are invalid in @acronym{DOS} file names, and should therefore
11545 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11546 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11547 In a @sc{sfn} environment, other characters are also invalid. These
11548 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11550 @item Invalid names (@sc{lfn})
11551 Some @acronym{DOS} file names are reserved, and cause problems if you
11552 try to use files with those names. These names include @file{CON},
11553 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11554 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11555 File names are case insensitive, so even names like
11556 @file{aux/config.guess} are disallowed.
11560 @node Shell Pattern Matching
11561 @section Shell Pattern Matching
11562 @cindex Shell pattern matching
11564 Nowadays portable patterns can use negated character classes like
11565 @samp{[!-aeiou]}. The older syntax @samp{[^-aeiou]} is supported by
11566 some shells but not others; hence portable scripts should never use
11567 @samp{^} as the first character of a bracket pattern.
11569 Outside the C locale, patterns like @samp{[a-z]} are problematic since
11570 they may match characters that are not lower-case letters.
11572 @node Shell Substitutions
11573 @section Shell Substitutions
11574 @cindex Shell substitutions
11576 Contrary to a persistent urban legend, the Bourne shell does not
11577 systematically split variables and back-quoted expressions, in particular
11578 on the right-hand side of assignments and in the argument of @code{case}.
11579 For instance, the following code:
11582 case "$given_srcdir" in
11583 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11584 *) top_srcdir="$dots$given_srcdir" ;;
11589 is more readable when written as:
11592 case $given_srcdir in
11593 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11594 *) top_srcdir=$dots$given_srcdir ;;
11599 and in fact it is even @emph{more} portable: in the first case of the
11600 first attempt, the computation of @code{top_srcdir} is not portable,
11601 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11602 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11603 the same way. There is just no portable way to use double-quoted
11604 strings inside double-quoted back-quoted expressions (pfew!).
11608 @cindex @samp{"$@@"}
11609 One of the most famous shell-portability issues is related to
11610 @samp{"$@@"}. When there are no positional arguments, Posix says
11611 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11612 original Unix version 7 Bourne shell treated it as equivalent to
11613 @samp{""} instead, and this behavior survives in later implementations
11614 like Digital Unix 5.0.
11616 The traditional way to work around this portability problem is to use
11617 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
11618 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
11619 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11622 zsh $ @kbd{emulate sh}
11623 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11626 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11633 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11634 @samp{"$@@"} because of the portability problems mentioned above.
11635 One workaround relies on Zsh's ``global aliases'' to convert
11636 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11639 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11642 Zsh only recognizes this alias when a shell word matches it exactly;
11643 @samp{"foo"$@{1+"$@@"@}} remains subject to word splitting. Since this
11644 case always yields at least one shell word, use plain @samp{"$@@"}.
11646 A more conservative workaround is to avoid @samp{"$@@"} if it is
11647 possible that there may be no positional arguments. For example,
11651 cat conftest.c "$@@"
11654 you can use this instead:
11658 0) cat conftest.c;;
11659 *) cat conftest.c "$@@";;
11663 Autoconf macros often use the @command{set} command to update
11664 @samp{$@@}, so if you are writing shell code intended for
11665 @command{configure} you should not assume that the value of @samp{$@@}
11666 persists for any length of time.
11670 @cindex positional parameters
11671 The 10th, 11th, @dots{} positional parameters can be accessed only after
11672 a @code{shift}. The 7th Edition shell reported an error if given
11673 @code{$@{10@}}, and
11674 Solaris 10 @command{/bin/sh} still acts that way:
11677 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11678 $ @kbd{echo $@{10@}}
11682 @item $@{@var{var}:-@var{value}@}
11683 @c Info cannot handle `:' in index entries.
11684 @c @cindex $@{@var{var}:-@var{value}@}
11685 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11686 colon for any shell substitution, and complain and die.
11687 Similarly for $@{@var{var}:=@var{value}@}, $@{@var{var}:?@var{value}@}, etc.
11689 @item $@{@var{var}=@var{literal}@}
11690 @cindex $@{@var{var}=@var{literal}@}
11694 : $@{var='Some words'@}
11698 otherwise some shells, such as on Digital Unix V 5.0, die because
11699 of a ``bad substitution''.
11703 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11704 of this. Imagine you need set a variable to a string containing
11705 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
11706 when the affected variable was already set. This bug can be exercised
11711 $ @kbd{foo=$@{foo='@}'@}}
11714 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
11717 $ @kbd{foo=$@{foo='@}'@}}
11723 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11724 though it is enclosed in single quotes. The problem doesn't happen
11725 using double quotes.
11727 @item $@{@var{var}=@var{expanded-value}@}
11728 @cindex $@{@var{var}=@var{expanded-value}@}
11734 : $@{var="$default"@}
11738 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11739 each char is set. You don't observe the phenomenon using a simple
11740 @samp{echo $var} since apparently the shell resets the 8th bit when it
11741 expands $var. Here are two means to make this shell confess its sins:
11744 $ @kbd{cat -v <<EOF
11753 $ @kbd{set | grep '^var=' | cat -v}
11756 One classic incarnation of this bug is:
11760 : $@{list="$default"@}
11767 You'll get @samp{a b c} on a single line. Why? Because there are no
11768 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11769 bit set, hence no IFS splitting is performed!!!
11771 One piece of good news is that Ultrix works fine with @samp{:
11772 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
11773 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11776 The portable way out consists in using a double assignment, to switch
11777 the 8th bit twice on Ultrix:
11780 list=$@{list="$default"@}
11784 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
11788 test "$@{var+set@}" = set || var=@var{@{value@}}
11791 @item $@{#@var{var}@}
11792 @itemx $@{@var{var}%@var{word}@}
11793 @itemx $@{@var{var}%%@var{word}@}
11794 @itemx $@{@var{var}#@var{word}@}
11795 @itemx $@{@var{var}##@var{word}@}
11796 @cindex $@{#@var{var}@}
11797 @cindex $@{@var{var}%@var{word}@}
11798 @cindex $@{@var{var}%%@var{word}@}
11799 @cindex $@{@var{var}#@var{word}@}
11800 @cindex $@{@var{var}##@var{word}@}
11801 Posix requires support for these usages, but they do not work with many
11802 traditional shells, e.g., Solaris 10 @command{/bin/sh}.
11804 Also, @command{pdksh} 5.2.14 mishandles some @var{word} forms. For
11805 example if @samp{$1} is @samp{a/b} and @samp{$2} is @samp{a}, then
11806 @samp{$@{1#$2@}} should yield @samp{/b}, but with @command{pdksh} it
11807 yields the empty string.
11810 @item `@var{commands}`
11811 @cindex `@var{commands}`
11812 @cindex Command Substitution
11813 Posix requires shells to trim all trailing newlines from command
11814 output before substituting it, so assignments like
11815 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11816 @samp{$file} ends in a newline.
11818 While in general it makes no sense, do not substitute a single builtin
11819 with side effects, because Ash 0.2, trying to optimize, does not fork a
11820 subshell to perform the command.
11822 For instance, if you wanted to check that @command{cd} is silent, do not
11823 use @samp{test -z "`cd /`"} because the following can happen:
11828 $ @kbd{test -z "`cd /`" && pwd}
11833 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11835 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11836 command substitution of a native program, if the end of the substitution
11837 is not aligned with the end of the double quote. This may be worked
11838 around by inserting another pair of quotes:
11841 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11842 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11843 - broken differ: char 4, line 1
11847 @item $(@var{commands})
11848 @cindex $(@var{commands})
11849 This construct is meant to replace @samp{`@var{commands}`},
11850 and it has most of the problems listed under @code{`@var{commands}`}.
11852 This construct can be
11853 nested while this is impossible to do portably with back quotes.
11854 Unfortunately it is not yet universally supported. Most notably, even recent
11855 releases of Solaris don't support it:
11858 $ @kbd{showrev -c /bin/sh | grep version}
11859 Command version: SunOS 5.10 Generic 121005-03 Oct 2006
11860 $ @kbd{echo $(echo blah)}
11861 syntax error: `(' unexpected
11865 nor does @sc{irix} 6.5's Bourne shell:
11868 IRIX firebird-image 6.5 07151432 IP22
11869 $ @kbd{echo $(echo blah)}
11873 If you do use @samp{$(@var{commands})}, make sure that the commands
11874 do not start with a parenthesis, as that would cause confusion with
11875 a different notation @samp{$((@var{expression}))} that in modern
11876 shells is an arithmetic expression not a command. To avoid the
11877 confusion, insert a space between the two opening parentheses.
11879 Avoid @var{commands} that contain unbalanced parentheses in
11880 here-documents, comments, or case statement patterns, as many shells
11881 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11882 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11885 echo $(case x in x) echo hello;; esac)
11890 Always quote @samp{^}, otherwise traditional shells such as
11891 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11897 @section Assignments
11898 @cindex Shell assignments
11900 When setting several variables in a row, be aware that the order of the
11901 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
11902 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11904 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11906 Don't rely on the following to find @file{subdir/program}:
11909 PATH=subdir$PATH_SEPARATOR$PATH program
11913 as this does not work with Zsh 3.0.6. Use something like this
11917 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11920 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11921 the status and propagates that of the last statement:
11924 $ @kbd{false || foo=bar; echo $?}
11926 $ @kbd{false || foo=`:`; echo $?}
11931 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11935 $ @kbd{foo=`exit 1`; echo $?}
11939 To assign default values, follow this algorithm:
11943 If the default value is a literal and does not contain any closing
11947 : $@{var='my literal'@}
11951 If the default value contains no closing brace, has to be expanded, and
11952 the variable being initialized is not intended to be IFS-split
11953 (i.e., it's not a list), then use:
11956 : $@{var="$default"@}
11960 If the default value contains no closing brace, has to be expanded, and
11961 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11965 var=$@{var="$default"@}
11969 If the default value contains a closing brace, then use:
11972 test "$@{var+set@}" = set || var="has a '@}'"
11976 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11977 doubt, just use the last form. @xref{Shell Substitutions}, items
11978 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11982 @section Parentheses in Shell Scripts
11983 @cindex Shell parentheses
11985 Beware of two opening parentheses in a row, as many shell
11986 implementations treat them specially. Posix requires that the command
11987 @samp{((cat))} must behave like @samp{(cat)}, but many shells, including
11988 Bash and the Korn shell, treat @samp{((cat))} as an arithmetic
11989 expression equivalent to @samp{let "cat"}, and may or may not report an
11990 error when they detect that @samp{cat} is not a number. As another
11991 example, @samp{pdksh} 5.2.14 misparses the following code:
11994 if ((true) || false); then
12000 To work around this problem, insert a space between the two opening
12001 parentheses. There is a similar problem and workaround with
12002 @samp{$((}; see @ref{Shell Substitutions}.
12005 @section Slashes in Shell Scripts
12006 @cindex Shell slashes
12008 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
12009 arguments that contain two trailing slashes:
12012 $ @kbd{echo / // /// //// .// //.}
12015 $ @kbd{eval "echo \$x"}
12018 $ @kbd{echo abc | tr -t ab //}
12024 Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the
12025 variable is empty and the second double-quote is followed by a word that
12026 begins and ends with slash:
12029 $ @kbd{sh -xc 'p=; echo "$p"/ouch/'}
12035 However, our understanding is that patches are available, so perhaps
12036 it's not worth worrying about working around these horrendous bugs.
12038 @node Special Shell Variables
12039 @section Special Shell Variables
12040 @cindex Shell variables
12041 @cindex Special shell variables
12043 Some shell variables should not be used, since they can have a deep
12044 influence on the behavior of the shell. In order to recover a sane
12045 behavior from the shell, some variables should be unset, but
12046 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
12047 fallback value is needed.
12049 As a general rule, shell variable names containing a lower-case letter
12050 are safe; you can define and use these variables without worrying about
12051 their effect on the underlying system, and without worrying about
12052 whether the shell changes them unexpectedly. (The exception is the
12053 shell variable @code{status}, as described below.)
12055 Here is a list of names that are known to cause trouble. This list is
12056 not exhaustive, but you should be safe if you avoid the name
12057 @code{status} and names containing only upper-case letters and
12060 @c Alphabetical order, case insensitive, `A' before `a'.
12063 Many shells reserve @samp{$_} for various purposes, e.g., the name of
12064 the last command executed.
12068 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
12069 the standard shell conform to Posix.
12073 When this variable is set it specifies a list of directories to search
12074 when invoking @code{cd} with a relative file name that did not start
12075 with @samp{./} or @samp{../}. Posix
12076 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
12077 is used successfully, @code{cd} prints the resulting absolute
12078 file name. Unfortunately this output can break idioms like
12079 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
12080 Also, many shells do not conform to this part of Posix; for
12081 example, @command{zsh} prints the result only if a directory name
12082 other than @file{.} was chosen from @env{CDPATH}.
12084 In practice the shells that have this problem also support
12085 @command{unset}, so you can work around the problem as follows:
12088 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
12091 You can also avoid output by ensuring that your directory name is
12092 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
12094 Autoconf-generated scripts automatically unset @env{CDPATH} if
12095 possible, so you need not worry about this problem in those scripts.
12099 In the MKS shell, case statements and file name generation are
12100 case-insensitive unless @env{DUALCASE} is nonzero.
12101 Autoconf-generated scripts export this variable when they start up.
12115 These variables should not matter for shell scripts, since they are
12116 supposed to affect only interactive shells. However, at least one
12117 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
12118 whether it is interactive, which means that (for example) a @env{PS1}
12119 with a side effect can unexpectedly modify @samp{$?}. To work around
12120 this bug, Autoconf-generated scripts do something like this:
12123 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
12131 Long ago, shell scripts inherited @env{IFS} from the environment,
12132 but this caused many problems so modern shells ignore any environment
12133 settings for @env{IFS}.
12135 Don't set the first character of @code{IFS} to backslash. Indeed,
12136 Bourne shells use the first character (backslash) when joining the
12137 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
12138 backslash escapes, so you can end up with backspace and other strange
12141 The proper value for @code{IFS} (in regular code, not when performing
12142 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
12143 especially important, as it is used to join the arguments in @samp{$*};
12144 however, note that traditional shells, but also bash-2.04, fail to adhere
12145 to this and join with a space anyway.
12157 @evindex LC_COLLATE
12159 @evindex LC_MESSAGES
12160 @evindex LC_MONETARY
12161 @evindex LC_NUMERIC
12164 Autoconf-generated scripts normally set all these variables to
12165 @samp{C} because so much configuration code assumes the C locale and
12166 Posix requires that locale environment variables be set to
12167 @samp{C} if the C locale is desired. However, some older, nonstandard
12168 systems (notably @acronym{SCO}) break if locale environment variables
12169 are set to @samp{C}, so when running on these systems
12170 Autoconf-generated scripts unset the variables instead.
12175 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
12176 extension that overrides @env{LC_ALL} in some cases, so
12177 Autoconf-generated scripts set it too.
12180 @itemx LC_IDENTIFICATION
12181 @itemx LC_MEASUREMENT
12184 @itemx LC_TELEPHONE
12185 @evindex LC_ADDRESS
12186 @evindex LC_IDENTIFICATION
12187 @evindex LC_MEASUREMENT
12190 @evindex LC_TELEPHONE
12192 These locale environment variables are @acronym{GNU} extensions. They
12193 are treated like their Posix brethren (@env{LC_COLLATE},
12194 etc.)@: as described above.
12197 Most modern shells provide the current line number in @code{LINENO}.
12198 Its value is the line number of the beginning of the current command.
12199 Autoconf attempts to execute @command{configure} with a shell that
12200 supports @code{LINENO}.
12201 If no such shell is available, it attempts to implement @code{LINENO}
12202 with a Sed prepass that replaces each instance of the string
12203 @code{$LINENO} (not followed by an alphanumeric character) with the
12206 You should not rely on @code{LINENO} within @command{eval}, as the
12207 behavior differs in practice. Also, the possibility of the Sed
12208 prepass means that you should not rely on @code{$LINENO} when quoted,
12209 when in here-documents, or when in long commands that cross line
12210 boundaries. Subshells should be OK, though. In the following
12211 example, lines 1, 6, and 9 are portable, but the other instances of
12212 @code{LINENO} are not:
12222 ( echo 6. $LINENO )
12223 eval 'echo 7. $LINENO'
12229 $ @kbd{bash-2.05 lineno}
12240 $ @kbd{zsh-3.0.6 lineno}
12251 $ @kbd{pdksh-5.2.14 lineno}
12262 $ @kbd{sed '=' <lineno |}
12268 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12271 > @kbd{ s,^[0-9]*\n,,}
12287 When executing the command @samp{>foo}, @command{zsh} executes
12288 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12289 compatibility mode and the @command{zsh} version is newer
12290 than 3.1.6-dev-18. If you are using an older @command{zsh}
12291 and forget to set @env{NULLCMD},
12292 your script might be suspended waiting for data on its standard input.
12294 @item PATH_SEPARATOR
12295 @evindex PATH_SEPARATOR
12296 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12297 variable can be set to either @samp{:} or @samp{;} to control the path
12298 separator Bash uses to set up certain environment variables (such as
12299 @env{PATH}). You can set this variable to @samp{;} if you want
12300 @command{configure} to use @samp{;} as a separator; this might be useful
12301 if you plan to use non-Posix shells to execute files. @xref{File System
12302 Conventions}, for more information about @code{PATH_SEPARATOR}.
12306 Posix 1003.1-2001 requires that @command{cd} and
12307 @command{pwd} must update the @env{PWD} environment variable to point
12308 to the logical name of the current directory, but traditional shells
12309 do not support this. This can cause confusion if one shell instance
12310 maintains @env{PWD} but a subsidiary and different shell does not know
12311 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12312 points to the wrong directory. Use @samp{`pwd`} rather than
12316 Many shells provide @code{RANDOM}, a variable that returns a different
12317 integer each time it is used. Most of the time, its value does not
12318 change when it is not used, but on @sc{irix} 6.5 the value changes all
12319 the time. This can be observed by using @command{set}. It is common
12320 practice to use @code{$RANDOM} as part of a file name, but code
12321 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12324 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12325 hence read-only. Do not use it.
12328 @node Limitations of Builtins
12329 @section Limitations of Shell Builtins
12330 @cindex Shell builtins
12331 @cindex Limitations of shell builtins
12333 No, no, we are serious: some shells do have limitations! :)
12335 You should always keep in mind that any builtin or command may support
12336 options, and therefore differ in behavior with arguments
12337 starting with a dash. For instance, the innocent @samp{echo "$word"}
12338 can give unexpected results when @code{word} starts with a dash. It is
12339 often possible to avoid this problem using @samp{echo "x$word"}, taking
12340 the @samp{x} into account later in the pipe.
12344 @prindex @command{.}
12345 Use @command{.} only with regular files (use @samp{test -f}). Bash
12346 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12347 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12348 you want to use @command{.} on a file @file{foo} in the current
12349 directory, you must use @samp{. ./foo}.
12352 @prindex @command{!}
12353 The Unix version 7 shell did not support
12354 negating the exit status of commands with @command{!}, and this feature
12355 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12356 Shell code like this:
12359 if ! cmp file1 file2 >/dev/null 2>&1; then
12360 echo files differ or trouble
12364 is therefore not portable in practice. Typically it is easy to rewrite
12368 cmp file1 file2 >/dev/null 2>&1 ||
12369 echo files differ or trouble
12372 More generally, one can always rewrite @samp{! @var{command}} as:
12375 if @var{command}; then (exit 1); else :; fi
12378 @item @command{break}
12379 @c ------------------
12380 @prindex @command{break}
12381 The use of @samp{break 2} etc.@: is safe.
12384 @item @command{case}
12385 @c -----------------
12386 @prindex @command{case}
12387 You don't need to quote the argument; no splitting is performed.
12389 You don't need the final @samp{;;}, but you should use it.
12391 Posix requires support for @code{case} patterns with opening
12392 parentheses like this:
12396 (*.c) echo "C source code";;
12401 but the @code{(} in this example is not portable to many Bourne
12402 shell implementations. It can be omitted safely.
12404 Zsh handles pattern fragments derived from parameter expansions or
12405 command substitutions as though quoted:
12408 $ pat=\?; case aa in ?$pat) echo match;; esac
12409 $ pat=\?; case a? in ?$pat) echo match;; esac
12414 Because of a bug in its @code{fnmatch}, Bash fails to properly
12415 handle backslashes in character classes:
12418 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12423 This is extremely unfortunate, since you are likely to use this code to
12424 handle Posix or @sc{ms-dos} absolute file names. To work around this
12425 bug, always put the backslash first:
12428 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12430 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12434 Many Bourne shells cannot handle closing brackets in character classes
12437 Some shells also have problems with backslash escaping in case you do not want
12438 to match the backslash: both a backslash and the escaped character match this
12439 pattern. To work around this, specify the character class in a variable, so
12440 that quote removal does not apply afterwards, and the special characters don't
12441 have to be backslash-escaped:
12444 $ @kbd{case '\' in [\<]) echo OK;; esac}
12446 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12450 Even with this, Solaris @command{ksh} matches a backslash if the set
12452 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12454 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12455 a closing parenthesis if not specified in a character class:
12458 $ @kbd{case foo in *\)*) echo fail ;; esac}
12460 $ @kbd{case foo in *')'*) echo fail ;; esac}
12464 Some shells, such as Ash 0.3.8, are confused by an empty
12465 @code{case}/@code{esac}:
12468 ash-0.3.8 $ @kbd{case foo in esac;}
12469 @error{}Syntax error: ";" unexpected (expecting ")")
12472 Many shells still do not support parenthesized cases, which is a pity
12473 for those of us using tools that rely on balanced parentheses. For
12474 instance, Solaris @command{/bin/sh}:
12477 $ @kbd{case foo in (foo) echo foo;; esac}
12478 @error{}syntax error: `(' unexpected
12484 @prindex @command{cd}
12485 Posix 1003.1-2001 requires that @command{cd} must support
12486 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12487 with @option{-L} being the default. However, traditional shells do
12488 not support these options, and their @command{cd} command has the
12489 @option{-P} behavior.
12491 Portable scripts should assume neither option is supported, and should
12492 assume neither behavior is the default. This can be a bit tricky,
12493 since the Posix default behavior means that, for example,
12494 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12495 the current logical directory is a symbolic link. It is safe to use
12496 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12497 Also, Autoconf-generated scripts check for this problem when computing
12498 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12499 so it is safe to @command{cd} to these variables.
12501 See @xref{Special Shell Variables}, for portability problems involving
12502 @command{cd} and the @env{CDPATH} environment variable.
12503 Also please see the discussion of the @command{pwd} command.
12506 @item @command{echo}
12507 @c -----------------
12508 @prindex @command{echo}
12509 The simple @command{echo} is probably the most surprising source of
12510 portability troubles. It is not possible to use @samp{echo} portably
12511 unless both options and escape sequences are omitted. New applications
12512 which are not aiming at portability should use @samp{printf} instead of
12515 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
12516 etc.@: for a means to simulate @option{-n}.
12518 Do not use backslashes in the arguments, as there is no consensus on
12519 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
12520 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12521 The problem is truly @command{echo}: all the shells
12522 understand @samp{'\n'} as the string composed of a backslash and an
12525 Because of these problems, do not pass a string containing arbitrary
12526 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
12527 if you know that @var{foo}'s value cannot contain backslashes and cannot
12528 start with @samp{-}, but otherwise you should use a here-document like
12538 @item @command{eval}
12539 @c -----------------
12540 @prindex @command{eval}
12541 The @command{eval} command is useful in limited circumstances, e.g.,
12542 using commands like @samp{eval table_$key=\$value} and @samp{eval
12543 value=table_$key} to simulate a hash table when the key is known to be
12544 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12545 arguments, even when it is implemented correctly.
12547 It is obviously unwise to use @samp{eval $cmd} if the string value of
12548 @samp{cmd} was derived from an untrustworthy source. But even if the
12549 string value is valid, @samp{eval $cmd} might not work as intended,
12550 since it causes field splitting and file name expansion to occur twice,
12551 once for the @command{eval} and once for the command itself. It is
12552 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
12553 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12554 equivalent of @samp{cat test;.c} if there happens to be a file named
12555 @file{test;.c} in the current directory; and this in turn
12556 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12557 then execute the command @command{.c}. To avoid this problem, use
12558 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12560 However, suppose that you want to output the text of the evaluated
12561 command just before executing it. Assuming the previous example,
12562 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12563 this output doesn't show the user that @samp{test;.c} is the actual name
12564 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
12565 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12566 since it mistakenly replaces the contents of @file{bar} by the
12567 string @samp{cat foo}. No simple, general, and portable solution to
12568 this problem is known.
12570 You should also be wary of common bugs in @command{eval} implementations.
12571 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12572 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12573 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12574 @samp{$?} is 0, so they exhibit behavior like this:
12577 $ @kbd{false; eval 'echo $?'}
12581 The correct behavior here is to output a nonzero value,
12582 but portable scripts should not rely on this.
12584 You should not rely on @code{LINENO} within @command{eval}.
12585 @xref{Special Shell Variables}.
12587 @item @command{exit}
12588 @c -----------------
12589 @prindex @command{exit}
12590 The default value of @command{exit} is supposed to be @code{$?};
12591 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12592 perform @samp{exit 0}.
12595 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12597 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12599 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12603 Using @samp{exit $?} restores the expected behavior.
12605 Some shell scripts, such as those generated by @command{autoconf}, use a
12606 trap to clean up before exiting. If the last shell command exited with
12607 nonzero status, the trap also exits with nonzero status so that the
12608 invoker can tell that an error occurred.
12610 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12611 trap ignores the @code{exit} command's argument. In these shells, a trap
12612 cannot determine whether it was invoked by plain @code{exit} or by
12613 @code{exit 1}. Instead of calling @code{exit} directly, use the
12614 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12617 @item @command{export}
12618 @c -------------------
12619 @prindex @command{export}
12620 The builtin @command{export} dubs a shell variable @dfn{environment
12621 variable}. Each update of exported variables corresponds to an update
12622 of the environment variables. Conversely, each environment variable
12623 received by the shell when it is launched should be imported as a shell
12624 variable marked as exported.
12626 Alas, many shells, such as Solaris @command{/bin/sh},
12627 @sc{irix} 6.3, @sc{irix} 5.2,
12628 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12629 @command{export} the environment variables they receive. As a result,
12630 two variables coexist: the environment variable and the shell
12631 variable. The following code demonstrates this failure:
12642 when run with @samp{FOO=foo} in the environment, these shells print
12643 alternately @samp{foo} and @samp{bar}, although they should print only
12644 @samp{foo} and then a sequence of @samp{bar}s.
12646 Therefore you should @command{export} again each environment variable
12650 @item @command{false}
12651 @c ------------------
12652 @prindex @command{false}
12653 Don't expect @command{false} to exit with status 1: in native
12654 Solaris @file{/bin/false} exits with status 255.
12657 @item @command{for}
12658 @c ----------------
12659 @prindex @command{for}
12660 To loop over positional arguments, use:
12670 You may @emph{not} leave the @code{do} on the same line as @code{for},
12671 since some shells improperly grok:
12679 If you want to explicitly refer to the positional arguments, given the
12680 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12683 for arg in $@{1+"$@@"@}; do
12689 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12690 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12691 item @samp{$@@}, for more.
12696 @prindex @command{if}
12697 Using @samp{!} is not portable. Instead of:
12700 if ! cmp -s file file.new; then
12709 if cmp -s file file.new; then :; else
12714 There are shells that do not reset the exit status from an @command{if}:
12717 $ @kbd{if (exit 42); then true; fi; echo $?}
12722 whereas a proper shell should have printed @samp{0}. This is especially
12723 bad in makefiles since it produces false failures. This is why properly
12724 written makefiles, such as Automake's, have such hairy constructs:
12727 if test -f "$file"; then
12728 install "$file" "$dest"
12735 @item @command{printf}
12736 @c ------------------
12737 @prindex @command{printf}
12738 A format string starting with a @samp{-} can cause problems.
12739 Bash interprets it as an option and
12740 gives an error. And @samp{--} to mark the end of options is not good
12741 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12742 literally as the format string. Putting the @samp{-} in a @samp{%c}
12743 or @samp{%s} is probably easiest:
12749 Bash 2.03 mishandles an escape sequence that happens to evaluate to @samp{%}:
12752 $ @kbd{printf '\045'}
12753 bash: printf: `%': missing format character
12756 Large outputs may cause trouble. On Solaris 2.5.1 through 10, for
12757 example, @file{/usr/bin/printf} is buggy, so when using
12758 @command{/bin/sh} the command @samp{printf %010000x 123} normally dumps
12762 @item @command{read}
12763 @c ------------------
12764 @prindex @command{read}
12765 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12768 @item @command{pwd}
12769 @c ----------------
12770 @prindex @command{pwd}
12771 With modern shells, plain @command{pwd} outputs a ``logical''
12772 directory name, some of whose components may be symbolic links. These
12773 directory names are in contrast to ``physical'' directory names, whose
12774 components are all directories.
12776 Posix 1003.1-2001 requires that @command{pwd} must support
12777 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12778 with @option{-L} being the default. However, traditional shells do
12779 not support these options, and their @command{pwd} command has the
12780 @option{-P} behavior.
12782 Portable scripts should assume neither option is supported, and should
12783 assume neither behavior is the default. Also, on many hosts
12784 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12785 does not require this behavior and portable scripts should not rely on
12788 Typically it's best to use plain @command{pwd}. On modern hosts this
12789 outputs logical directory names, which have the following advantages:
12793 Logical names are what the user specified.
12795 Physical names may not be portable from one installation
12796 host to another due to network file system gymnastics.
12798 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12799 some parent directory, but plain @command{pwd} cannot fail for this
12803 Also please see the discussion of the @command{cd} command.
12806 @item @command{set}
12807 @c ----------------
12808 @prindex @command{set}
12809 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12810 any options) does not sort its output.
12812 The @command{set} builtin faces the usual problem with arguments starting with a
12813 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
12814 the end of the options (any argument after @option{--} is a parameter,
12815 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12816 10 @command{/bin/sh}) simply stop option
12817 processing as soon as a non-option argument is found. Therefore, use
12818 @samp{dummy} or simply @samp{x} to end the option processing, and use
12819 @command{shift} to pop it out:
12822 set x $my_list; shift
12825 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
12826 longer requires support for this command, and in traditional shells
12827 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12828 makes scripts harder to debug.
12830 Some nonstandard shells do not recognize more than one option
12831 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
12832 better to combine them:
12838 The @acronym{BSD} shell has had several problems with the @option{-e}
12839 option, partly because @acronym{BSD} @command{make} traditionally used
12840 @option{-e} even though this was incompatible with Posix
12841 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
12842 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12843 @samp{case} when @option{-e} was in effect, causing the shell to exit
12844 unexpectedly in some cases. This was particularly a problem with
12845 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12846 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12847 wrapper works around the bug.
12849 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12850 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12851 @samp{&&} fails inside a compound statement. For example:
12857 test -n "$foo" && exit 1
12860 test -n "$foo" && exit 1
12866 does not print @samp{two}. One workaround is to use @samp{if test -n
12867 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12868 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12871 @item @command{shift}
12872 @c ------------------
12873 @prindex @command{shift}
12874 Not only is @command{shift}ing a bad idea when there is nothing left to
12875 shift, but in addition it is not portable: the shell of @acronym{MIPS
12876 RISC/OS} 4.52 refuses to do it.
12878 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12879 and it is also absent in many pre-Posix shells.
12882 @item @command{source}
12883 @c -------------------
12884 @prindex @command{source}
12885 This command is not portable, as Posix does not require it; use
12886 @command{.} instead.
12889 @item @command{test}
12890 @c -----------------
12891 @prindex @command{test}
12892 The @code{test} program is the way to perform many file and string
12893 tests. It is often invoked by the alternate name @samp{[}, but using
12894 that name in Autoconf code is asking for trouble since it is an M4 quote
12897 The @option{-a}, @option{-o}, @samp{(}, and @samp{)} operands are not
12898 portable and should be avoided. Thus, portable uses of @command{test}
12899 should never have more than four arguments, and scripts should use shell
12900 constructs like @samp{&&} and @samp{||} instead. If you combine
12901 @samp{&&} and @samp{||} in the same statement, keep in mind that they
12902 have equal precedence, so it is often better to parenthesize even when
12903 this is redundant. For example:
12907 test "X$a" = "X$b" -a \
12908 '(' "X$c" != "X$d" -o "X$e" = "X$f" ')'
12911 test "X$a" = "X$b" &&
12912 @{ test "X$c" != "X$d" || test "X$e" = "X$f"; @}
12915 @command{test} does not process options like most other commands do; for
12916 example, it does not recognize the @option{--} argument as marking the
12919 It is safe to use @samp{!} as a @command{test} operator. For example,
12920 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12921 -d foo; @dots{}} is not.
12924 @item @command{test} (files)
12925 @c -------------------------
12926 To enable @command{configure} scripts to support cross-compilation, they
12927 shouldn't do anything that tests features of the build system instead of
12928 the host system. But occasionally you may find it necessary to check
12929 whether some arbitrary file exists. To do so, use @samp{test -f} or
12930 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12931 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12932 lacks it. To test for symbolic links on systems that have them, use
12933 @samp{test -h} rather than @samp{test -L}; either form conforms to
12934 Posix 1003.1-2001, but older shells like Solaris 8
12935 @code{/bin/sh} support only @option{-h}.
12937 @item @command{test} (strings)
12938 @c ---------------------------
12939 Posix says that @samp{test "@var{string}"} succeeds if @var{string} is
12940 not null, but this usage is not portable to traditional platforms like
12941 Solaris 10 @command{/bin/sh}, which mishandle strings like @samp{!} and
12944 Posix says that @samp{test ! "@var{string}"}, @samp{test -n "@var{string}"} and
12945 @samp{test -z "@var{string}"} work with any string, but many
12946 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12947 Digital Unix 4, etc.)@: get confused if
12948 @var{string} looks like an operator:
12952 test: argument expected
12954 test: argument expected
12957 Similarly, Posix says that @samp{test "@var{string1}" = "@var{string2"}}
12958 and @samp{test "@var{string1}" != "@var{string2"}} work for any pairs of
12959 strings, but in practice this is not true for troublesome strings that
12960 look like operators or parentheses, or that begin with @samp{-}.
12962 It is best to protect such strings with a leading @samp{X}, e.g.,
12963 @samp{test "X@var{string}" != X} rather than @samp{test -n
12964 "@var{string}"} or @samp{test ! "@var{string}"}.
12966 It is common to find variations of the following idiom:
12969 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12974 to take an action when a token matches a given pattern. Such constructs
12975 should be avoided by using:
12978 case $ac_feature in
12979 *[!-a-zA-Z0-9_]*) @var{action};;
12983 If the pattern is a complicated regular expression that cannot be
12984 expressed as a shell pattern, use something like this instead:
12987 expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
12991 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12992 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12993 @samp{@var{foo}} contains backslashes.
12996 @item @command{trap}
12997 @c -----------------
12998 @prindex @command{trap}
12999 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
13000 trap 0, i.e., have the @command{trap} run when the script ends (either via an
13001 explicit @command{exit}, or the end of the script). The trap for 0 should be
13002 installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh}
13003 will invoke the trap at the end of this function.
13005 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
13006 specified signals to their default values, but many common shells (e.g.,
13007 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
13008 ``command'' named @command{-} when the specified conditions arise.
13009 There is no portable workaround, except for @samp{trap - 0}, for which
13010 @samp{trap '' 0} is a portable substitute.
13012 Although Posix is not absolutely clear on this point, it is widely
13013 admitted that when entering the trap @samp{$?} should be set to the exit
13014 status of the last command run before the trap. The ambiguity can be
13015 summarized as: ``when the trap is launched by an @command{exit}, what is
13016 the @emph{last} command run: that before @command{exit}, or
13017 @command{exit} itself?''
13019 Bash considers @command{exit} to be the last command, while Zsh and
13020 Solaris @command{/bin/sh} consider that when the trap is run it is
13021 @emph{still} in the @command{exit}, hence it is the previous exit status
13022 that the trap receives:
13025 $ @kbd{cat trap.sh}
13028 $ @kbd{zsh trap.sh}
13030 $ @kbd{bash trap.sh}
13034 The portable solution is then simple: when you want to @samp{exit 42},
13035 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
13036 set the exit status to 42 for Zsh, and the second to trigger the trap
13037 and pass 42 as exit status for Bash.
13039 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
13040 reset to 0 by empty lines if the code is inside @command{trap}.
13043 $ @kbd{trap 'false}
13051 Fortunately, this bug only affects @command{trap}.
13053 @item @command{true}
13054 @c -----------------
13055 @prindex @command{true}
13056 @c Info cannot handle `:' in index entries.
13057 @c @prindex @command{:}
13058 Don't worry: as far as we know @command{true} is portable.
13059 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
13060 portable shell community tends to prefer using @command{:}. This has a
13061 funny side effect: when asked whether @command{false} is more portable
13062 than @command{true} Alexandre Oliva answered:
13065 In a sense, yes, because if it doesn't exist, the shell will produce an
13066 exit status of failure, which is correct for @command{false}, but not
13067 for @command{true}.
13071 @item @command{unset}
13072 @c ------------------
13073 @prindex @command{unset}
13074 In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails
13075 when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset
13076 MAIL} in some cases and dumps core.
13078 A few ancient shells lack @command{unset} entirely. Nevertheless, because
13079 it is extremely useful to disable embarrassing variables such as
13080 @code{PS1}, you can test for its existence and use
13081 it @emph{provided} you give a neutralizing value when @command{unset} is
13085 # "|| exit" suppresses any "Segmentation fault" message.
13086 if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then
13091 $unset PS1 || PS1='$ '
13095 @xref{Special Shell Variables}, for some neutralizing values. Also, see
13096 @ref{Limitations of Builtins}, documentation of @command{export}, for
13097 the case of environment variables.
13100 @node Limitations of Usual Tools
13101 @section Limitations of Usual Tools
13102 @cindex Limitations of usual tools
13104 The small set of tools you can expect to find on any machine can still
13105 include some limitations you should be aware of.
13111 Don't leave white space before the opening parenthesis in a user function call.
13112 Posix does not allow this and @acronym{GNU} Awk rejects it:
13115 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13116 BEGIN @{ die () @}'}
13117 gawk: cmd. line:2: BEGIN @{ die () @}
13118 gawk: cmd. line:2: ^ parse error
13119 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
13120 BEGIN @{ die() @}'}
13124 Posix says that if a program contains only @samp{BEGIN} actions, and
13125 contains no instances of @code{getline}, then the program merely
13126 executes the actions without reading input. However, traditional Awk
13127 implementations (such as Solaris 10 @command{awk}) read and discard
13128 input in this case. Portable scripts can redirect input from
13129 @file{/dev/null} to work around the problem. For example:
13132 awk 'BEGIN @{print "hello world"@}' </dev/null
13135 If you want your program to be deterministic, don't depend on @code{for}
13139 $ @kbd{cat for.awk}
13146 $ @kbd{gawk -f for.awk </dev/null}
13149 $ @kbd{nawk -f for.awk </dev/null}
13154 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
13157 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
13158 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
13160 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
13162 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
13167 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
13168 or use a simple test to reject such implementations.
13170 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
13171 length of regular expressions and literal strings in an Awk program.
13173 Traditional Awk implementations derived from Unix version 7, such as
13174 Solaris @command{/bin/awk}, have many limitations and do not
13175 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
13176 Programs}) finds you an Awk that doesn't have these problems, but if
13177 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
13180 Traditional Awk does not support multidimensional arrays or user-defined
13183 Traditional Awk does not support the @option{-v} option. You can use
13184 assignments after the program instead, e.g., @command{$AWK '@{print v
13185 $1@}' v=x}; however, don't forget that such assignments are not
13186 evaluated until they are encountered (e.g., after any @code{BEGIN}
13189 Traditional Awk does not support the keywords @code{delete} or @code{do}.
13191 Traditional Awk does not support the expressions
13192 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
13193 or @code{@var{a}^=@var{b}}.
13195 Traditional Awk does not support the predefined @code{CONVFMT} variable.
13197 Traditional Awk supports only the predefined functions @code{exp},
13198 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
13199 @code{sqrt}, and @code{substr}.
13201 Traditional Awk @code{getline} is not at all compatible with Posix;
13204 Traditional Awk has @code{for (i in a) @dots{}} but no other uses of the
13205 @code{in} keyword. For example, it lacks @code{if (i in a) @dots{}}.
13207 In code portable to both traditional and modern Awk, @code{FS} must be a
13208 string containing just one ordinary character, and similarly for the
13209 field-separator argument to @code{split}.
13211 Traditional Awk has a limit of 99
13212 fields in a record. You may be able to circumvent this problem by using
13215 Traditional Awk has a limit of at most 99 bytes in a number formatted by
13216 @code{OFMT}; for example, @code{OFMT="%.300e"; print 0.1;} typically
13219 The original version of Awk had a limit of at most 99 bytes per
13220 @code{split} field, 99 bytes per @code{substr} substring, and 99 bytes
13221 per run of non-special characters in a @code{printf} format, but these
13222 bugs have been fixed on all practical hosts that we know of.
13224 @item @command{basename}
13225 @c ---------------------
13226 @prindex @command{basename}
13227 Not all hosts have a working @command{basename}.
13228 You can use @command{expr} instead.
13230 @c AS_BASENAME is to be replaced by a better API.
13232 Not all hosts have a working @command{basename}, and you should instead
13233 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
13234 @command{expr} if you need to strip a suffix. For example:
13237 a=`basename "$aname"` # This is not portable.
13238 a=`AS_BASENAME(["$aname"])` # This is more portable.
13240 # This is not portable.
13241 c=`basename "$cname" .c`
13243 # This is more portable.
13244 c=`AS_BASENAME(["$cname"])`
13246 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
13252 @item @command{cat}
13253 @c ----------------
13254 @prindex @command{cat}
13255 Don't rely on any option.
13260 @prindex @command{cc}
13261 The command @samp{cc -c foo.c} traditionally produces an object file
13262 named @file{foo.o}. Most compilers allow @option{-c} to be combined
13263 with @option{-o} to specify a different object file name, but
13264 Posix does not require this combination and a few compilers
13265 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
13266 tests for this feature with @code{AC_PROG_CC_C_O}.
13268 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
13269 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
13271 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
13272 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
13275 The default executable, produced by @samp{cc foo.c}, can be
13278 @item @file{a.out} --- usual Posix convention.
13279 @item @file{b.out} --- i960 compilers (including @command{gcc}).
13280 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
13281 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
13282 @item @file{foo.exe} --- various MS-DOS compilers.
13285 The C compiler's traditional name is @command{cc}, but other names like
13286 @command{gcc} are common. Posix 1003.1-2001 specifies the
13287 name @command{c99}, but older Posix editions specified
13288 @command{c89} and anyway these standard names are rarely used in
13289 practice. Typically the C compiler is invoked from makefiles that use
13290 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13294 @item @command{chmod}
13295 @c ------------------
13296 @prindex @command{chmod}
13297 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13298 instead, for two reasons. First, plain @option{-w} does not necessarily
13299 make the file unwritable, since it does not affect mode bits that
13300 correspond to bits in the file mode creation mask. Second,
13301 Posix says that the @option{-w} might be interpreted as an
13302 implementation-specific option, not as a mode; Posix suggests
13303 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13304 @samp{--} does not work on some older hosts.
13307 @item @command{cmp}
13308 @c ----------------
13309 @prindex @command{cmp}
13310 @command{cmp} performs a raw data comparison of two files, while
13311 @command{diff} compares two text files. Therefore, if you might compare
13312 DOS files, even if only checking whether two files are different, use
13313 @command{diff} to avoid spurious differences due to differences of
13319 @prindex @command{cp}
13320 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13321 obsolescent and its behavior on special files is implementation-defined.
13322 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13323 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13324 reads from pipes instead of replicating them.
13326 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13327 trailing slashes at the end of nonexistent destination directories. To
13328 avoid this problem, omit the trailing slashes. For example, use
13329 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13330 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13332 @c This is thanks to Ian.
13333 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13334 its @command{mv} does.
13336 @cindex timestamp resolution
13337 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13338 -p} copied the timestamps exactly. However, many modern file systems
13339 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13340 -p} implementations truncate timestamps when copying files, so this
13341 can result in the destination file appearing to be older than the
13342 source. The exact amount of truncation depends on the resolution of
13343 the system calls that @command{cp} uses; traditionally this was
13344 @code{utime}, which has 1-second resolution, but some newer
13345 @command{cp} implementations use @code{utimes}, which has
13346 1-microsecond resolution. These newer implementations include @acronym{GNU}
13347 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13348 later. Unfortunately as of January 2006 there is still no system
13349 call to set timestamps to the full nanosecond resolution.
13351 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13352 ownerships. But whether it actually does copy ownerships or not is a
13353 system dependent policy decision implemented by the kernel. If the
13354 kernel allows it then it happens. If the kernel does not allow it then
13355 it does not happen. It is not something @command{cp} itself has control
13358 In Unix System V any user can chown files to any other user, and System
13359 V also has a non-sticky @file{/tmp}. That probably derives from the
13360 heritage of System V in a business environment without hostile users.
13361 @acronym{BSD} changed this
13362 to be a more secure model where only root can @command{chown} files and
13363 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13364 of @acronym{BSD} in a campus environment.
13366 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13367 can be configured to allow a System V style @command{chown}. On the
13368 other hand, @acronym{HP-UX} follows System V, but can
13369 be configured to use the modern security model and disallow
13370 @command{chown}. Since it is an administrator-configurable parameter
13371 you can't use the name of the kernel as an indicator of the behavior.
13375 @item @command{date}
13376 @c -----------------
13377 @prindex @command{date}
13378 Some versions of @command{date} do not recognize special @samp{%} directives,
13379 and unfortunately, instead of complaining, they just pass them through,
13380 and exit with success:
13384 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13390 @item @command{diff}
13391 @c -----------------
13392 @prindex @command{diff}
13393 Option @option{-u} is nonportable.
13395 Some implementations, such as Tru64's, fail when comparing to
13396 @file{/dev/null}. Use an empty file instead.
13399 @item @command{dirname}
13400 @c --------------------
13401 @prindex @command{dirname}
13402 Not all hosts have a working @command{dirname}, and you should instead
13403 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13406 dir=`dirname "$file"` # This is not portable.
13407 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13411 @item @command{egrep}
13412 @c ------------------
13413 @prindex @command{egrep}
13414 Posix 1003.1-2001 no longer requires @command{egrep},
13415 but many hosts do not yet support the Posix
13416 replacement @code{grep -E}. Also, some traditional implementations do
13417 not work on long input lines. To work around these problems, invoke
13418 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13420 Portable extended regular expressions should use @samp{\} only to escape
13421 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13422 is not portable, even though it typically matches @samp{@}}.
13424 The empty alternative is not portable. Use @samp{?} instead. For
13425 instance with Digital Unix v5.0:
13428 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13430 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13432 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13437 @command{$EGREP} also suffers the limitations of @command{grep}.
13439 @item @command{expr}
13440 @c -----------------
13441 @prindex @command{expr}
13442 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13443 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13444 misinterpreting @var{word}.
13446 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13448 @item @command{expr} (@samp{|})
13449 @prindex @command{expr} (@samp{|})
13450 You can use @samp{|}. Although Posix does require that @samp{expr
13451 ''} return the empty string, it does not specify the result when you
13452 @samp{|} together the empty string (or zero) with the empty string. For
13459 Posix 1003.2-1992 returns the empty string
13460 for this case, but traditional Unix returns @samp{0} (Solaris is
13461 one such example). In Posix 1003.1-2001, the specification was
13462 changed to match traditional Unix's behavior (which is
13463 bizarre, but it's too late to fix this). Please note that the same
13464 problem does arise when the empty string results from a computation,
13468 expr bar : foo \| foo : bar
13472 Avoid this portability problem by avoiding the empty string.
13475 @item @command{expr} (@samp{:})
13476 @c ----------------------------
13477 @prindex @command{expr}
13478 Portable @command{expr} regular expressions should use @samp{\} to
13479 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13480 For example, alternation, @samp{\|}, is common but Posix does not
13481 require its support, so it should be avoided in portable scripts.
13482 Similarly, @samp{\+} and @samp{\?} should be avoided.
13484 Portable @command{expr} regular expressions should not begin with
13485 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
13488 The Posix standard is ambiguous as to whether
13489 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13490 In practice, it outputs the empty string on most platforms, but portable
13491 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
13492 @command{expr} returns @samp{0}.
13494 One might think that a way to get a uniform behavior would be to use
13495 the empty string as a default value:
13498 expr a : '\(b\)' \| ''
13502 Unfortunately this behaves exactly as the original expression; see the
13503 @command{expr} (@samp{|}) entry for more information.
13505 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13506 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13507 @command{expr} to fail if the matched substring is longer than 120
13508 bytes. In this case, you might want to fall back on @samp{echo|sed} if
13509 @command{expr} fails. Nowadays this is of practical importance only for
13510 the rare installer who mistakenly puts @file{/usr/ucb} before
13511 @file{/usr/bin} in @env{PATH}.
13513 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13514 some cases. For example, the command
13516 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13520 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13521 This particular case can be worked around by substituting @samp{[^--]}
13524 Don't leave, there is some more!
13526 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13527 the empty string, has a funny behavior in its exit status: it's always 1
13528 when parentheses are used!
13531 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13533 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13536 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13538 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13543 In practice this can be a big problem if you are ready to catch failures
13544 of @command{expr} programs with some other method (such as using
13545 @command{sed}), since you may get twice the result. For instance
13548 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13552 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
13553 simple workaround consists of testing @command{expr} and using a variable
13554 set to @command{expr} or to @command{false} according to the result.
13556 Tru64 @command{expr} incorrectly treats the result as a number, if it
13557 can be interpreted that way:
13560 $ @kbd{expr 00001 : '.*\(...\)'}
13565 @item @command{fgrep}
13566 @c ------------------
13567 @prindex @command{fgrep}
13568 Posix 1003.1-2001 no longer requires @command{fgrep},
13569 but many hosts do not yet support the Posix
13570 replacement @code{grep -F}. Also, some traditional implementations do
13571 not work on long input lines. To work around these problems, invoke
13572 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13575 @item @command{find}
13576 @c -----------------
13577 @prindex @command{find}
13578 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13579 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13580 commands do not understand it.
13582 The replacement of @samp{@{@}} is guaranteed only if the argument is
13583 exactly @emph{@{@}}, not if it's only a part of an argument. For
13584 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13588 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13593 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13596 @item @command{grep}
13597 @c -----------------
13598 @prindex @command{grep}
13599 Portable scripts can rely on the @command{grep} options @option{-c},
13600 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13601 options. For example, don't use @option{-w}, as Posix does not require
13602 it and Irix 6.5.16m's @command{grep} does not support it. Also,
13603 portable scripts should not combine @option{-c} with @option{-l},
13604 as Posix does not allow this.
13606 Some of the options required by Posix are not portable in practice.
13607 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13608 implementations (e.g., Solaris) do not support @option{-q}.
13609 Don't use @samp{grep -s} to suppress output either, because Posix
13610 says @option{-s} does not suppress output, only some error messages;
13611 also, the @option{-s} option of traditional @command{grep} behaved
13612 like @option{-q} does in most modern implementations. Instead,
13613 redirect the standard output and standard error (in case the file
13614 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
13615 status of @code{grep} to determine whether it found a match.
13617 Some traditional @command{grep} implementations do not work on long
13618 input lines. On AIX the default @code{grep} silently truncates long
13619 lines on the input before matching.
13621 Also, many implementations do not support multiple regexps
13622 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13623 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
13624 work around these problems, invoke @code{AC_PROG_GREP} and then use
13627 Another possible workaround for the multiple @option{-e} problem is to
13628 separate the patterns by newlines, for example:
13636 except that this fails with traditional @command{grep}
13637 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13639 Traditional @command{grep} implementations (e.g., Solaris) do not
13640 support the @option{-E} or @option{-F} options. To work around these
13641 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13642 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
13643 willing to require support for Posix @command{grep}, your script should
13644 not use both @option{-E} and @option{-F}, since Posix does not allow
13647 Portable @command{grep} regular expressions should use @samp{\} only to
13648 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
13649 alternation, @samp{\|}, is common but Posix does not require its
13650 support in basic regular expressions, so it should be avoided in
13651 portable scripts. Solaris and HP-UX @command{grep} do not support it.
13652 Similarly, the following escape sequences should also be avoided:
13653 @samp{\<}, @samp{\>}, @samp{\+}, @samp{\?}, @samp{\`}, @samp{\'},
13654 @samp{\B}, @samp{\b}, @samp{\S}, @samp{\s}, @samp{\W}, and @samp{\w}.
13657 @item @command{join}
13658 @c -----------------
13659 @prindex @command{join}
13660 Solaris 8 @command{join} has bugs when the second operand is standard
13661 input, and when standard input is a pipe. For example, the following
13662 shell script causes Solaris 8 @command{join} to loop forever:
13669 cat file | join file -
13672 Use @samp{join - file} instead.
13677 @prindex @command{ln}
13678 @cindex Symbolic links
13679 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
13680 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13682 For versions of the @acronym{DJGPP} before 2.04,
13683 @command{ln} emulates symbolic links
13684 to executables by generating a stub that in turn calls the real
13685 program. This feature also works with nonexistent files like in the
13686 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
13687 which attempts to call @file{file.exe} if run. But this feature only
13688 works for executables, so @samp{cp -p} is used instead for these
13689 systems. @acronym{DJGPP} versions 2.04 and later have full support
13690 for symbolic links.
13695 @prindex @command{ls}
13696 @cindex Listing directories
13697 The portable options are @option{-acdilrtu}. Current practice is for
13698 @option{-l} to output both owner and group, even though ancient versions
13699 of @command{ls} omitted the group.
13701 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13702 to standard output if @file{foo} did not exist. Hence a shell command
13703 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13704 was equivalent to @samp{sources='*.c not found'} in the absence of
13705 @samp{.c} files. This is no longer a practical problem, since current
13706 @command{ls} implementations send diagnostics to standard error.
13708 @item @command{mkdir}
13709 @c ------------------
13710 @prindex @command{mkdir}
13711 @cindex Making directories
13712 No @command{mkdir} option is portable to older systems. Instead of
13713 @samp{mkdir -p @var{file-name}}, you should use
13714 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13715 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13717 Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m
13718 go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD}
13719 @command{mkdir} incorrectly attempts to change the permissions of
13720 @var{dir} even if it already exists. @acronym{HP-UX} 11.23 and
13721 @acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to
13722 any newly-created parents of @var{dir}.
13724 Posix does not clearly specify whether @samp{mkdir -p foo}
13725 should succeed when @file{foo} is a symbolic link to an already-existing
13726 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13727 succeeds, but Solaris @command{mkdir} fails.
13729 Traditional @code{mkdir -p} implementations suffer from race conditions.
13730 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13731 at the same time, both processes might detect that @file{a} is missing,
13732 one might create @file{a}, then the other might try to create @file{a}
13733 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
13734 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13735 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13736 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13737 earlier versions are vulnerable. Solaris @command{mkdir} is still
13738 vulnerable as of Solaris 10, and other traditional Unix systems are
13739 probably vulnerable too. This possible race is harmful in parallel
13740 builds when several Make rules call @code{mkdir -p} to
13741 construct directories. You may use
13742 @code{install-sh -d} as a safe replacement, provided this script is
13743 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13744 OK, but copies from older versions are vulnerable.
13747 @item @command{mktemp}
13748 @c -------------------
13749 @prindex @command{mktemp}
13750 @cindex Creating temporary files
13751 Shell scripts can use temporary files safely with @command{mktemp}, but
13752 it does not exist on all systems. A portable way to create a safe
13753 temporary file name is to create a temporary directory with mode 700 and
13754 use a file inside this directory. Both methods prevent attackers from
13755 gaining control, though @command{mktemp} is far less likely to fail
13756 gratuitously under attack.
13758 Here is sample code to create a new temporary directory safely:
13761 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13762 # Use mktemp if possible; otherwise fall back on mkdir,
13763 # with $RANDOM to make collisions less likely.
13767 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13769 test -n "$tmp" && test -d "$tmp"
13771 tmp=$TMPDIR/foo$$-$RANDOM
13772 (umask 077 && mkdir "$tmp")
13779 @prindex @command{mv}
13780 @cindex Moving open files
13781 The only portable options are @option{-f} and @option{-i}.
13783 Moving individual files between file systems is portable (it was in Unix
13785 but it is not always atomic: when doing @samp{mv new existing}, there's
13786 a critical section where neither the old nor the new version of
13787 @file{existing} actually exists.
13789 On some systems moving files from @file{/tmp} can sometimes cause
13790 undesirable (but perfectly valid) warnings, even if you created these
13791 files. This is because @file{/tmp} belongs to a group that ordinary
13792 users are not members of, and files created in @file{/tmp} inherit
13793 the group of @file{/tmp}. When the file is copied, @command{mv} issues
13794 a diagnostic without failing:
13797 $ @kbd{touch /tmp/foo}
13798 $ @kbd{mv /tmp/foo .}
13799 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13807 This annoying behavior conforms to Posix, unfortunately.
13809 Moving directories across mount points is not portable, use @command{cp}
13812 @acronym{DOS} variants cannot rename or remove open files, and do not
13813 support commands like @samp{mv foo bar >foo}, even though this is
13814 perfectly portable among Posix hosts.
13819 @prindex @command{od}
13821 In Mac OS X 10.3, @command{od} does not support the
13822 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13823 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
13824 supported Posix option is @option{-v}, and the only supported
13825 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
13826 @command{hexdump} program can be used instead.
13828 This problem no longer exists in Mac OS X 10.4.3.
13833 @prindex @command{rm}
13834 The @option{-f} and @option{-r} options are portable.
13836 It is not portable to invoke @command{rm} without operands. For
13837 example, on many systems @samp{rm -f -r} (with no other arguments)
13838 silently succeeds without doing anything, but it fails with a diagnostic
13839 on Net@acronym{BSD} 2.0.2.
13841 A file might not be removed even if its parent directory is writable
13842 and searchable. Many Posix hosts cannot remove a mount point, a named
13843 stream, a working directory, or a last link to a file that is being
13846 @acronym{DOS} variants cannot rename or remove open files, and do not
13847 support commands like @samp{rm foo >foo}, even though this is
13848 perfectly portable among Posix hosts.
13851 @item @command{sed}
13852 @c ----------------
13853 @prindex @command{sed}
13854 Patterns should not include the separator (unless escaped), even as part
13855 of a character class. In conformance with Posix, the Cray
13856 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13858 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
13859 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13862 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13864 Sed scripts should not use branch labels longer than 7 characters and
13865 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
13866 (not counting @samp{:} commands) and
13867 48 labels, which can not be circumvented by using more than one script
13868 file. It can execute up to 19 reads with the @samp{r} command per cycle.
13869 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13870 about 6000 bytes for the internal representation of commands.
13872 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13873 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13874 @samp{;} as a command:
13877 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13878 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13881 Input should not have unreasonably long lines, since some @command{sed}
13882 implementations have an input buffer limited to 4000 bytes.
13884 Portable @command{sed} regular expressions should use @samp{\} only to escape
13885 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
13886 alternation, @samp{\|}, is common but Posix does not require its
13887 support, so it should be avoided in portable scripts. Solaris
13888 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13889 deletes only lines that contain the literal string @samp{a|b}.
13890 Similarly, @samp{\+} and @samp{\?} should be avoided.
13892 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13894 Nested parentheses in patterns (e.g., @samp{\(\(a*\)b*)\)}) are
13895 quite portable to current hosts, but was not supported by some ancient
13896 @command{sed} implementations like SVR3.
13898 Some @command{sed} implementations, e.g., Solaris,
13899 restrict the special role of the asterisk to one-character regular expressions.
13900 This may lead to unexpected behavior:
13903 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13905 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13909 The @option{-e} option is portable, so long as its argument
13910 does not begin with @samp{a}, @samp{c}, or @samp{i}
13911 (as this runs afoul of a Tru64 5.1 bug).
13912 Some people prefer to use @samp{-e}:
13915 sed -e '@var{command-1}' \
13916 -e '@var{command-2}'
13920 as opposed to the equivalent:
13930 The following usage is sometimes equivalent:
13933 sed '@var{command-1};@var{command-2}'
13936 but Posix says that this use of a semicolon has undefined effect if
13937 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13938 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13939 should use semicolon only with simple scripts that do not use these
13942 Commands inside @{ @} brackets are further restricted. Posix says that
13943 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13944 each command must be followed immediately by a newline, without any
13945 intervening blanks or semicolons. The closing bracket must be alone on
13946 a line, other than white space preceding or following it.
13948 Contrary to yet another urban legend, you may portably use @samp{&} in
13949 the replacement part of the @code{s} command to mean ``what was
13950 matched''. All descendants of Unix version 7 @command{sed}
13952 don't have first hand experience with older @command{sed} implementations) have
13955 Posix requires that you must not have any white space between
13956 @samp{!} and the following command. It is OK to have blanks between
13957 the address and the @samp{!}. For instance, on Solaris:
13960 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13961 @error{}Unrecognized command: /bar/ ! p
13962 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13963 @error{}Unrecognized command: /bar/! p
13964 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13968 Posix also says that you should not combine @samp{!} and @samp{;}. If
13969 you use @samp{!}, it is best to put it on a command that is delimited by
13970 newlines rather than @samp{;}.
13972 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13973 @samp{w} commands be followed by exactly one space before their argument.
13974 On the other hand, no white space is allowed between @samp{:} and the
13975 subsequent label name.
13977 If a sed script is specified on the command line and ends in an
13978 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
13979 should be followed by a newline. Otherwise some @command{sed}
13980 implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the
13983 Many @command{sed} implementations (e.g., MacOS X 10.4,
13984 Open@acronym{BSD} 3.9, Solaris 10
13985 @command{/usr/ucb/sed}) strip leading white space from the text of
13986 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
13987 work around this incompatibility with Posix:
13990 $ @kbd{echo flushleft | sed 'a\}
13995 $ @kbd{echo foo | sed 'a\}
14003 @item @command{sed} (@samp{t})
14004 @c ---------------------------
14005 @prindex @command{sed} (@samp{t})
14006 Some old systems have @command{sed} that ``forget'' to reset their
14007 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
14008 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
14009 script (the line numbers are not actual part of the texts):
14012 s/keep me/kept/g # a
14048 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
14049 flag, and the output is produced. When processing
14050 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
14051 fails to match, but @command{sed} is not supposed to clear the @samp{t}
14052 flag when a substitution fails. Command (b) sees that the flag is set,
14053 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
14054 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
14055 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
14056 Finally, since the flag is clear, line 4 is processed properly.
14058 There are two things one should remember about @samp{t} in @command{sed}.
14059 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
14060 succeeded, not only the immediately preceding substitution. Therefore,
14061 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
14062 line, to reset the @samp{t} flag where needed.
14064 Secondly, you cannot rely on @command{sed} to clear the flag at each new
14067 One portable implementation of the script above is:
14078 @item @command{touch}
14079 @c ------------------
14080 @prindex @command{touch}
14081 @cindex timestamp resolution
14082 If you specify the desired timestamp (e.g., with the @option{-r}
14083 option), @command{touch} typically uses the @code{utime} or
14084 @code{utimes} system call, which can result in the same kind of
14085 timestamp truncation problems that @samp{cp -p} has.
14087 On ancient @acronym{BSD} systems, @command{touch} or any command that
14088 results in an empty file does not update the timestamps, so use a
14089 command like @command{echo} as a workaround.
14091 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
14092 fails to work on SunOS 4.1.3 when the empty file is on an
14093 @acronym{NFS}-mounted 4.2 volume.
14094 However, these problems are no longer of practical concern.
14099 @node Portable Make
14100 @chapter Portable Make Programming
14101 @prindex @command{make}
14102 @cindex Limitations of @command{make}
14104 Writing portable makefiles is an art. Since a makefile's commands are
14105 executed by the shell, you must consider the shell portability issues
14106 already mentioned. However, other issues are specific to @command{make}
14110 * $< in Ordinary Make Rules:: $< in ordinary rules
14111 * Failure in Make Rules:: Failing portably in rules
14112 * Special Chars in Names:: Special Characters in Macro Names
14113 * Backslash-Newline-Newline:: Empty last lines in macro definitions
14114 * Backslash-Newline Comments:: Spanning comments across line boundaries
14115 * Long Lines in Makefiles:: Line length limitations
14116 * Macros and Submakes:: @code{make macro=value} and submakes
14117 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
14118 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
14119 * Comments in Make Rules:: Other problems with Make comments
14120 * obj/ and Make:: Don't name a subdirectory @file{obj}
14121 * make -k Status:: Exit status of @samp{make -k}
14122 * VPATH and Make:: @code{VPATH} woes
14123 * Single Suffix Rules:: Single suffix rules and separated dependencies
14124 * Timestamps and Make:: Subsecond timestamp resolution
14127 @node $< in Ordinary Make Rules
14128 @section @code{$<} in Ordinary Make Rules
14130 Posix says that the @samp{$<} construct in makefiles can be
14131 used only in inference rules and in the @samp{.DEFAULT} rule; its
14132 meaning in ordinary rules is unspecified. Solaris @command{make}
14133 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
14134 later) @command{make} diagnoses these uses and errors out.
14136 @node Failure in Make Rules
14137 @section Failure in Make Rules
14139 Since 1992 Posix has required that @command{make} must invoke
14140 each command with the equivalent of a @samp{sh -c} subshell. However,
14141 many @command{make} implementations, including @acronym{BSD} make through 2004,
14142 use @samp{sh -e -c} instead, and the @option{-e} option causes the
14143 subshell to exit immediately if a subsidiary simple-command fails. For
14144 example, the command @samp{touch T; rm -f U} always attempts to
14145 remove @file{U} with Posix make, but incompatible
14146 @command{make} implementations skip the @command{rm} if the
14147 @command{touch} fails. One way to work around this is to reword the
14148 affected simple-commands so that they always succeed, e.g., @samp{touch
14150 However, even this approach can run into common bugs in @acronym{BSD}
14151 implementations of the @option{-e} option of @command{sh} and
14152 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
14153 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
14154 complicated @command{make} actions into separate scripts.
14156 @node Special Chars in Names
14157 @section Special Characters in Make Macro Names
14159 Posix limits macro names to nonempty strings containing only
14160 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
14161 @command{make} implementations allow a wider variety of characters, but
14162 portable makefiles should avoid them. It is portable to start a name
14163 with a special character, e.g., @samp{$(.FOO)}.
14165 Some ancient @command{make} implementations don't support leading
14166 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
14169 $ @kbd{cat Makefile}
14172 all:; @@echo this is test
14174 Make: Must be a separator on rules line 2. Stop.
14175 $ @kbd{cat Makefile2}
14178 all:; @@echo this is test
14179 $ @kbd{make -f Makefile2}
14184 However, this problem is no longer of practical concern.
14186 @node Backslash-Newline-Newline
14187 @section Backslash-Newline-Newline in Make Macro Values
14189 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
14190 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
14191 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
14192 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
14193 following a backslash, continuing to the next non-empty line. For
14207 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
14208 sensibly let a backslash continue only to the immediately following
14211 @node Backslash-Newline Comments
14212 @section Backslash-Newline in Make Comments
14214 According to Posix, Make comments start with @code{#}
14215 and continue until an unescaped newline is reached.
14218 $ @kbd{cat Makefile}
14225 $ @kbd{make} # GNU make
14230 However this is not always the case. Some implementations
14231 discard everything from @code{#} through the end of the line, ignoring any
14232 trailing backslash.
14235 $ @kbd{pmake} # BSD make
14236 "Makefile", line 3: Need an operator
14237 Fatal errors encountered -- cannot continue
14241 Therefore, if you want to comment out a multi-line definition, prefix each
14242 line with @code{#}, not only the first.
14250 @node Long Lines in Makefiles
14251 @section Long Lines in Makefiles
14253 Tru64 5.1's @command{make} has been reported to crash when given a
14254 makefile with lines longer than around 20 kB. Earlier versions are
14255 reported to exit with @code{Line too long} diagnostics.
14257 @node Macros and Submakes
14258 @section @code{make macro=value} and Submakes
14260 A command-line variable definition such as @code{foo=bar} overrides any
14261 definition of @code{foo} in a makefile. Some @command{make}
14262 implementations (such as @acronym{GNU} @command{make}) propagate this
14263 override to subsidiary invocations of @command{make}. Some other
14264 implementations do not pass the substitution along to submakes.
14267 $ @kbd{cat Makefile}
14274 $ @kbd{make foo=bar} # GNU make 3.79.1
14277 make[1]: Entering directory `/home/adl'
14279 make[1]: Leaving directory `/home/adl'
14280 $ @kbd{pmake foo=bar} # BSD make
14286 You have a few possibilities if you do want the @code{foo=bar} override
14287 to propagate to submakes. One is to use the @option{-e}
14288 option, which causes all environment variables to have precedence over
14289 the makefile macro definitions, and declare foo as an environment
14293 $ @kbd{env foo=bar make -e}
14296 The @option{-e} option is propagated to submakes automatically,
14297 and since the environment is inherited between @command{make}
14298 invocations, the @code{foo} macro is overridden in
14299 submakes as expected.
14301 This syntax (@code{foo=bar make -e}) is portable only when used
14302 outside of a makefile, for instance from a script or from the
14303 command line. When run inside a @command{make} rule, @acronym{GNU}
14304 @command{make} 3.80 and prior versions forget to propagate the
14305 @option{-e} option to submakes.
14307 Moreover, using @option{-e} could have unexpected side effects if your
14308 environment contains some other macros usually defined by the
14309 makefile. (See also the note about @code{make -e} and @code{SHELL}
14312 Another way to propagate overrides to submakes is to do it
14313 manually, from your makefile:
14319 $(MAKE) foo=$(foo) two
14324 You need to foresee all macros that a user might want to override if
14327 @node The Make Macro MAKEFLAGS
14328 @section The Make Macro MAKEFLAGS
14329 @cindex @code{MAKEFLAGS} and @command{make}
14330 @cindex @command{make} and @code{MAKEFLAGS}
14332 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14333 current and recursive invocations of make, but allows implementations
14334 several formats for the variable. It is tricky to parse
14335 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14336 or @option{-k} for continued execution are in effect. For example, you
14337 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14338 contains single-letter options, since in the Cygwin version of
14339 @acronym{GNU} @command{make} it is either @option{--unix} or
14340 @option{--win32} with the second word containing single-letter options.
14343 $ @kbd{cat Makefile}
14345 @@echo MAKEFLAGS = $(MAKEFLAGS)
14349 MAKEFLAGS = --unix -k
14352 @node The Make Macro SHELL
14353 @section The Make Macro @code{SHELL}
14354 @cindex @code{SHELL} and @command{make}
14355 @cindex @command{make} and @code{SHELL}
14357 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14358 macro to spawn shell processes and execute Make rules. This
14359 is a builtin macro supplied by @command{make}, but it can be modified
14360 by a makefile or by a command-line argument.
14362 Not all @command{make} implementations define this @code{SHELL} macro.
14364 @command{make} is an example; this implementation always uses
14365 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14366 your makefiles. If you use Autoconf, do
14372 Do not force @code{SHELL = /bin/sh} because that is not correct
14373 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14374 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14375 emulation mode where features like pipes and redirections are emulated
14376 on top of DOS's @command{command.com}. Unfortunately this emulation is
14377 incomplete; for instance it does not handle command substitutions.
14378 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14380 Posix-compliant @command{make} should never acquire the value of
14381 $(SHELL) from the environment, even when @code{make -e} is used
14382 (otherwise, think about what would happen to your rules if
14383 @code{SHELL=/bin/tcsh}).
14385 However not all @command{make} implementations have this exception.
14386 For instance it's not surprising that Tru64 @command{make} doesn't
14387 protect @code{SHELL}, since it doesn't use it.
14390 $ @kbd{cat Makefile}
14396 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14399 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14404 @node Comments in Make Rules
14405 @section Comments in Make Rules
14406 @cindex Comments in @file{Makefile} rules
14407 @cindex @file{Makefile} rules and comments
14409 Never put comments in a rule.
14411 Some @command{make} treat anything starting with a tab as a command for
14412 the current rule, even if the tab is immediately followed by a @code{#}.
14413 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14414 makefile runs @code{# foo} through the shell.
14421 @node obj/ and Make
14422 @section The @file{obj/} Subdirectory and Make
14423 @cindex @file{obj/}, subdirectory
14424 @cindex @acronym{BSD} @command{make} and @file{obj/}
14426 Never name one of your subdirectories @file{obj/} if you don't like
14429 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14430 before reading the makefile. Hence the makefile in the
14431 current directory is not read.
14434 $ @kbd{cat Makefile}
14437 $ @kbd{cat obj/Makefile}
14440 $ @kbd{make} # GNU make
14443 $ @kbd{pmake} # BSD make
14448 @node make -k Status
14449 @section Exit Status of @code{make -k}
14450 @cindex @code{make -k}
14452 Do not rely on the exit status of @code{make -k}. Some implementations
14453 reflect whether they encountered an error in their exit status; other
14454 implementations always succeed.
14457 $ @kbd{cat Makefile}
14460 $ @kbd{make -k; echo exit status: $?} # GNU make
14462 make: *** [all] Error 1
14464 $ @kbd{pmake -k; echo exit status: $?} # BSD make
14466 *** Error code 1 (continuing)
14470 @node VPATH and Make
14471 @section @code{VPATH} and Make
14472 @cindex @code{VPATH}
14474 Posix does not specify the semantics of @code{VPATH}. Typically,
14475 @command{make} supports @code{VPATH}, but its implementation is not
14478 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14479 portable to recent-enough popular implementations of @command{make}, but
14480 to keep the resulting makefiles portable, a package's makefile
14481 prototypes must take the following issues into account. These issues
14482 are complicated and are often poorly understood, and installers who use
14483 @code{VPATH} should expect to find many bugs in this area. If you use
14484 @code{VPATH}, the simplest way to avoid these portability bugs is to
14485 stick with @acronym{GNU} @command{make}, since it is the most
14486 commonly-used @command{make} among Autoconf users.
14488 Here are some known issues with some @code{VPATH}
14492 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
14493 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
14494 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
14495 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
14496 * Make Target Lookup:: More details about @code{VPATH} lookup
14499 @node VPATH and Double-colon
14500 @subsection @code{VPATH} and Double-colon Rules
14501 @cindex @code{VPATH} and double-colon rules
14502 @cindex double-colon rules and @code{VPATH}
14504 With ancient versions of Sun @command{make},
14505 any assignment to @code{VPATH} causes @command{make} to execute only
14506 the first set of double-colon rules.
14507 However, this problem is no longer of practical concern.
14509 @node $< in Explicit Rules
14510 @subsection @code{$<} Not Supported in Explicit Rules
14511 @cindex explicit rules, @code{$<}, and @code{VPATH}
14512 @cindex @code{$<}, explicit rules, and @code{VPATH}
14513 @cindex @code{VPATH}, explicit rules, and @code{$<}
14515 Using @code{$<} in explicit rules is not portable.
14516 The prerequisite file must be named explicitly in the rule. If you want
14517 to find the prerequisite via a @code{VPATH} search, you have to code the
14518 whole thing manually. @xref{Build Directories}.
14520 @node Automatic Rule Rewriting
14521 @subsection Automatic Rule Rewriting
14522 @cindex @code{VPATH} and automatic rule rewriting
14523 @cindex automatic rule rewriting and @code{VPATH}
14525 Some @command{make} implementations, such as Solaris and Tru64,
14526 search for prerequisites in @code{VPATH} and
14527 then rewrite each occurrence as a plain word in the rule.
14531 # This isn't portable to GNU make.
14538 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14539 found in @file{../pkg/src}.
14541 However, this rule leads to real problems in practice. For example, if
14542 the source directory contains an ordinary file named @file{test} that is
14543 used in a dependency, Solaris @command{make} rewrites commands like
14544 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14545 @dots{}}, which is typically undesirable. To avoid this problem,
14546 portable makefiles should never mention a source file whose name is that
14547 of a shell keyword like @file{until} or a shell command like
14548 @command{cat} or @command{gcc} or @command{test}.
14550 Because of these problems @acronym{GNU} @command{make} and many other
14551 @command{make} implementations do not rewrite commands, so portable
14553 search @code{VPATH} manually. It is tempting to write this:
14556 # This isn't portable to Solaris make.
14559 cp `test -f if.c || echo $(VPATH)/`if.c f.c
14563 However, the ``prerequisite rewriting'' still applies here. So if
14564 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14568 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14579 and thus fails. Oops.
14581 A simple workaround, and good practice anyway, is to use @samp{$?} and
14582 @samp{$@@} when possible:
14591 but this does not generalize well to commands with multiple
14592 prerequisites. A more general workaround is to rewrite the rule so that
14593 the prerequisite @file{if.c} never appears as a plain word. For
14594 example, these three rules would be safe, assuming @file{if.c} is in
14595 @file{../pkg/src} and the other files are in the working directory:
14600 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14602 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14604 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14607 Things get worse when your prerequisites are in a macro.
14611 HEADERS = f.h g.h h.h
14612 install-HEADERS: $(HEADERS)
14613 for i in $(HEADERS); do \
14614 $(INSTALL) -m 644 \
14615 `test -f $$i || echo $(VPATH)/`$$i \
14616 $(DESTDIR)$(includedir)/$$i; \
14620 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14621 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14622 where @code{f.h} and @code{g.h} are plain words and are hence
14623 subject to @code{VPATH} adjustments.
14625 If the three files are in @file{../pkg/src}, the rule is run as:
14628 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14630 `test -f $i || echo ../pkg/src/`$i \
14631 /usr/local/include/$i; \
14635 where the two first @command{install} calls fail. For instance,
14636 consider the @code{f.h} installation:
14640 `test -f ../pkg/src/f.h || \
14643 /usr/local/include/../pkg/src/f.h;
14652 /usr/local/include/../pkg/src/f.h;
14655 Note that the manual @code{VPATH} search did not cause any problems here;
14656 however this command installs @file{f.h} in an incorrect directory.
14658 Trying to quote @code{$(HEADERS)} in some way, as we did for
14659 @code{foo.c} a few makefiles ago, does not help:
14662 install-HEADERS: $(HEADERS)
14663 headers='$(HEADERS)'; \
14664 for i in $$headers; do \
14665 $(INSTALL) -m 644 \
14666 `test -f $$i || echo $(VPATH)/`$$i \
14667 $(DESTDIR)$(includedir)/$$i; \
14671 Now, @code{headers='$(HEADERS)'} macro-expands to:
14674 headers='f.h g.h h.h'
14678 but @code{g.h} is still a plain word. (As an aside, the idiom
14679 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14680 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14681 syntax error on @code{for i in;}.)
14683 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14687 HEADERS = f.h g.h h.h
14688 install-HEADERS: $(HEADERS)
14689 headers='$(HEADERS)'; \
14690 for i in $$headers; do \
14691 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14692 $(INSTALL) -m 644 \
14693 `test -f $$i || echo $(VPATH)/`$$i \
14694 $(DESTDIR)$(includedir)/$$i; \
14698 Automake does something similar. However the above hack works only if
14699 the files listed in @code{HEADERS} are in the current directory or a
14700 subdirectory; they should not be in an enclosing directory. If we had
14701 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14702 build with Tru64 @command{make}. The reason is that not only does
14703 Tru64 @command{make} rewrite dependencies, but it also simplifies
14704 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14705 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
14706 a leading @file{../pkg/src/} component.
14708 The following example makes the behavior of Tru64 @command{make}
14712 $ @kbd{cat Makefile}
14724 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14725 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
14726 directory does not even exist, this just means that the simplification
14727 occurred before the file was checked for.)
14729 For the record here is how SunOS 4 @command{make} behaves on this
14734 make: Fatal error: Don't know how to make target `../foo'
14742 @node Tru64 Directory Magic
14743 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14744 @cindex @code{VPATH} and prerequisite directories
14745 @cindex prerequisite directories and @code{VPATH}
14747 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14748 @command{make} creates it in the current directory.
14751 $ @kbd{mkdir -p foo/bar build}
14753 $ @kbd{cat >Makefile <<END
14762 This can yield unexpected results if a rule uses a manual @code{VPATH}
14763 search as presented before.
14768 command `test -d foo/bar || echo ../`foo/bar
14771 The above @command{command} is run on the empty @file{foo/bar}
14772 directory that was created in the current directory.
14774 @node Make Target Lookup
14775 @subsection Make Target Lookup
14776 @cindex @code{VPATH}, resolving target pathnames
14778 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14779 should use files found via a @code{VPATH} search. @xref{Search
14780 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14783 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14784 file name found during the @code{VPATH} search for this target, and
14785 builds the file locally using the file name given in the makefile.
14786 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14787 file name found during the @code{VPATH} search.
14789 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14790 easier to describe: the file name found during the @code{VPATH} search
14791 is used whether the target needs to be rebuilt or not. Therefore
14792 new files are created locally, but existing files are updated at their
14793 @code{VPATH} location.
14795 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14797 @code{VPATH} search for a dependency that has an explicit rule.
14798 This is extremely annoying.
14800 When attempting a @code{VPATH} build for an autoconfiscated package
14801 (e.g., @code{mkdir build && cd build && ../configure}), this means
14803 @command{make} builds everything locally in the @file{build}
14804 directory, while @acronym{BSD} @command{make} builds new files locally and
14805 updates existing files in the source directory.
14808 $ @kbd{cat Makefile}
14811 foo.x bar.x: newer.x
14812 @@echo Building $@@
14813 $ @kbd{touch ../bar.x}
14814 $ @kbd{touch ../newer.x}
14815 $ @kbd{make} # GNU make
14818 $ @kbd{pmake} # NetBSD make
14821 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14824 $ @kbd{tmake} # Tru64 make
14827 $ @kbd{touch ../bar.x}
14828 $ @kbd{make} # GNU make
14830 $ @kbd{pmake} # NetBSD make
14832 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14835 $ @kbd{tmake} # Tru64 make
14840 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14841 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14842 @command{make} always
14843 update @file{bar.x}, even when @file{../bar.x} is up to date.
14845 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14846 decided to ignore a @code{VPATH} file name (e.g., it ignored
14847 @file{../bar.x} in the above example) it continues to ignore it when
14848 the target occurs as a prerequisite of another rule.
14850 The following example shows that @acronym{GNU} @command{make} does not look up
14851 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14852 because it ignored the @code{VPATH} result of @file{bar.x} while running
14853 the @code{bar.x: newer.x} rule.
14856 $ @kbd{cat Makefile}
14860 @@echo Building $@@
14864 $ @kbd{touch ../bar.x}
14865 $ @kbd{touch ../newer.x}
14866 $ @kbd{make} # GNU make
14869 cp: cannot stat `bar.x': No such file or directory
14870 make: *** [bar.y] Error 1
14871 $ @kbd{pmake} # NetBSD make
14875 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14876 echo Building bar.x
14878 cp: cannot stat `bar.x': No such file or directory
14880 $ @kbd{tmake} # Tru64 make
14882 cp: bar.x: No such file or directory
14886 Note that if you drop away the command from the @code{bar.x: newer.x}
14887 rule, @acronym{GNU} @command{make} magically starts to work: it
14888 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14889 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14890 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14894 $ @kbd{cat Makefile}
14901 $ @kbd{touch ../bar.x}
14902 $ @kbd{touch ../newer.x}
14903 $ @kbd{make} # GNU make
14906 $ @kbd{pmake} # NetBSD make
14909 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14911 cp: cannot stat `bar.x': No such file or directory
14913 $ @kbd{tmake} # Tru64 make
14917 It seems the sole solution that would please every @command{make}
14918 implementation is to never rely on @code{VPATH} searches for targets.
14919 In other words, @code{VPATH} should be reserved to unbuilt sources.
14922 @node Single Suffix Rules
14923 @section Single Suffix Rules and Separated Dependencies
14924 @cindex Single Suffix Inference Rule
14925 @cindex Rule, Single Suffix Inference
14926 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14927 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14930 @cindex Separated Dependencies
14931 @dfn{Separated dependencies} simply refers to listing the prerequisite
14932 of a target, without defining a rule. Usually one can list on the one
14933 hand side, the rules, and on the other hand side, the dependencies.
14935 Solaris @command{make} does not support separated dependencies for
14936 targets defined by single suffix rules:
14939 $ @kbd{cat Makefile}
14944 $ @kbd{touch foo.in}
14951 while @acronym{GNU} Make does:
14957 Makefile foo foo.in
14960 Note it works without the @samp{foo: foo.in} dependency.
14963 $ @kbd{cat Makefile}
14972 and it works with double suffix inference rules:
14975 $ @kbd{cat Makefile}
14977 .SUFFIXES: .in .out
14984 As a result, in such a case, you have to write target rules.
14986 @node Timestamps and Make
14987 @section Timestamp Resolution and Make
14988 @cindex timestamp resolution
14989 Traditionally, file timestamps had 1-second resolution, and
14990 @command{make} used those timestamps to determine whether one file was
14991 newer than the other. However, many modern file systems have
14992 timestamps with 1-nanosecond resolution. Some @command{make}
14993 implementations look at the entire timestamp; others ignore the
14994 fractional part, which can lead to incorrect results. Normally this
14995 is not a problem, but in some extreme cases you may need to use tricks
14996 like @samp{sleep 1} to work around timestamp truncation bugs.
14998 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14999 file timestamps to their full resolutions (@pxref{Limitations of Usual
15000 Tools}). Hence you should be wary of rules like this:
15007 as @file{dest} often appears to be older than @file{src} after the
15008 timestamp is truncated, and this can cause @command{make} to do
15009 needless rework the next time it is invoked. To work around this
15010 problem, you can use a timestamp file, e.g.:
15021 @c ======================================== Portable C and C++ Programming
15023 @node Portable C and C++
15024 @chapter Portable C and C++ Programming
15025 @cindex Portable C and C++ programming
15027 C and C++ programs often use low-level features of the underlying
15028 system, and therefore are often more difficult to make portable to other
15031 Several standards have been developed to help make your programs more
15032 portable. If you write programs with these standards in mind, you can
15033 have greater confidence that your programs work on a wide variety
15034 of systems. @xref{Standards, , Language Standards Supported by
15035 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
15036 (@acronym{GCC})}, for a list of C-related
15037 standards. Many programs also assume the
15038 @uref{http://www.opengroup.org/susv3, Posix standard}.
15040 Some old code is written to be portable to K&R C, which predates any C
15041 standard. K&R C compilers are no longer of practical interest, though,
15042 and the rest of section assumes at least C89, the first C standard.
15044 Program portability is a huge topic, and this section can only briefly
15045 introduce common pitfalls. @xref{System Portability, , Portability
15046 between System Types, standards, @acronym{GNU} Coding Standards}, for
15050 * Varieties of Unportability:: How to make your programs unportable
15051 * Integer Overflow:: When integers get too large
15052 * Null Pointers:: Properties of null pointers
15053 * Buffer Overruns:: Subscript errors and the like
15054 * Volatile Objects:: @code{volatile} and signals
15055 * Floating Point Portability:: Portable floating-point arithmetic
15056 * Exiting Portably:: Exiting and the exit status
15059 @node Varieties of Unportability
15060 @section Varieties of Unportability
15061 @cindex portability
15063 Autoconf tests and ordinary programs often need to test what is allowed
15064 on a system, and therefore they may need to deliberately exceed the
15065 boundaries of what the standards allow, if only to see whether an
15066 optional feature is present. When you write such a program, you should
15067 keep in mind the difference between constraints, unspecified behavior,
15068 and undefined behavior.
15070 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
15071 example constraint is that C programs must not declare a bit-field with
15072 negative width. Tests can therefore reliably assume that programs with
15073 negative-width bit-fields are rejected by a compiler that conforms
15076 @dfn{Unspecified behavior} is valid behavior, where the standard allows
15077 multiple possibilities. For example, the order of evaluation of
15078 function arguments is unspecified. Some unspecified behavior is
15079 @dfn{implementation-defined}, i.e., documented by the implementation,
15080 but since Autoconf tests cannot read the documentation they cannot
15081 distinguish between implementation-defined and other unspecified
15082 behavior. It is common for Autoconf tests to probe implementations to
15083 determine otherwise-unspecified behavior.
15085 @dfn{Undefined behavior} is invalid behavior, where the standard allows
15086 the implementation to do anything it pleases. For example,
15087 dereferencing a null pointer leads to undefined behavior. If possible,
15088 test programs should avoid undefined behavior, since a program with
15089 undefined behavior might succeed on a test that should fail.
15091 The above rules apply to programs that are intended to conform to the
15092 standard. However, strictly-conforming programs are quite rare, since
15093 the standards are so limiting. A major goal of Autoconf is to support
15094 programs that use implementation features not described by the standard,
15095 and it is fairly common for test programs to violate the above rules, if
15096 the programs work well enough in practice.
15098 @node Integer Overflow
15099 @section Integer Overflow
15100 @cindex integer overflow
15101 @cindex overflow, signed integer
15102 @cindex signed integer overflow
15103 @cindex wraparound arithmetic
15105 In practice many portable C programs assume that signed integer overflow wraps
15106 around reliably using two's complement arithmetic. Yet the C standard
15107 says that program behavior is undefined on overflow, and in a few cases
15108 C programs do not work on some modern implementations because their
15109 overflows do not wrap around as their authors expected. Conversely, in
15110 signed integer remainder, the C standard requires overflow
15111 behavior that is commonly not implemented.
15114 * Integer Overflow Basics:: Why integer overflow is a problem
15115 * Signed Overflow Examples:: Examples of code assuming wraparound
15116 * Optimization and Wraparound:: Optimizations that break uses of wraparound
15117 * Signed Overflow Advice:: Practical advice for signed overflow issues
15118 * Signed Integer Division:: @code{INT_MIN / -1} and @code{INT_MIN % -1}
15121 @node Integer Overflow Basics
15122 @subsection Basics of Integer Overflow
15123 @cindex integer overflow
15124 @cindex overflow, signed integer
15125 @cindex signed integer overflow
15126 @cindex wraparound arithmetic
15128 In languages like C, unsigned integer overflow reliably wraps around;
15129 e.g., @code{UINT_MAX + 1} yields zero.
15130 This is guaranteed by the C standard and is
15131 portable in practice, unless you specify aggressive,
15132 nonstandard optimization options
15133 suitable only for special applications.
15135 In contrast, the C standard says that signed integer overflow leads to
15136 undefined behavior where a program can do anything, including dumping
15137 core or overrunning a buffer. The misbehavior can even precede the
15138 overflow. Such an overflow can occur during addition, subtraction,
15139 multiplication, division, and left shift.
15141 Despite this requirement of the standard, many C programs and Autoconf
15142 tests assume that signed integer overflow silently wraps around modulo a
15143 power of two, using two's complement arithmetic, so long as you cast the
15144 resulting value to a signed integer type or store it into a signed
15145 integer variable. If you use conservative optimization flags, such
15146 programs are generally portable to the vast majority of modern
15147 platforms, with a few exceptions discussed later.
15149 For historical reasons the C standard also allows implementations with
15150 ones' complement or signed magnitude arithmetic, but it is safe to
15151 assume two's complement nowadays.
15153 Also, overflow can occur when converting an out-of-range value to a
15154 signed integer type. Here a standard implementation must define what
15155 happens, but this might include raising an exception. In practice all
15156 known implementations support silent wraparound in this case, so you need
15157 not worry about other possibilities.
15159 @node Signed Overflow Examples
15160 @subsection Examples of Code Assuming Wraparound Overflow
15161 @cindex integer overflow
15162 @cindex overflow, signed integer
15163 @cindex signed integer overflow
15164 @cindex wraparound arithmetic
15166 There has long been a tension between what the C standard requires for
15167 signed integer overflow, and what C programs commonly assume. The
15168 standard allows aggressive optimizations based on assumptions that
15169 overflow never occurs, but many practical C programs rely on overflow
15170 wrapping around. These programs do not conform to the standard, but
15171 they commonly work in practice because compiler writers are
15172 understandably reluctant to implement optimizations that would break
15173 many programs, unless perhaps a user specifies aggressive optimization.
15175 The C Standard says that if a program has signed integer overflow its
15176 behavior is undefined, and the undefined behavior can even precede the
15177 overflow. To take an extreme example:
15179 @c Inspired by Robert Dewar's example in
15180 @c <http://gcc.gnu.org/ml/gcc/2007-01/msg00038.html> (2007-01-01).
15182 if (password == expected_password)
15183 allow_superuser_privileges ();
15184 else if (counter++ == INT_MAX)
15187 printf ("%d password mismatches\n", counter);
15191 If the @code{int} variable @code{counter} equals @code{INT_MAX},
15192 @code{counter++} must overflow and the behavior is undefined, so the C
15193 standard allows the compiler to optimize away the test against
15194 @code{INT_MAX} and the @code{abort} call.
15195 Worse, if an earlier bug in the program lets the compiler deduce that
15196 @code{counter == INT_MAX} or that @code{counter} previously overflowed,
15197 the C standard allows the compiler to optimize away the password test
15198 and generate code that allows superuser privileges unconditionally.
15200 Despite this requirement by the standard, it has long been common for C
15201 code to assume wraparound arithmetic after signed overflow, and all
15202 known practical C implementations support some C idioms that assume
15203 wraparound signed arithmetic, even if the idioms do not conform
15204 strictly to the standard. If your code looks like the following
15205 examples it will almost surely work with real-world compilers.
15207 Here is an example derived from the 7th Edition Unix implementation of
15208 @code{atoi} (1979-01-10):
15214 while (*p >= '0' && *p <= '9')
15215 n = n * 10 + *p++ - '0';
15216 return (f ? -n : n);
15220 Even if the input string is in range, on most modern machines this has
15221 signed overflow when computing the most negative integer (the @code{-n}
15222 overflows) or a value near an extreme integer (the first @code{+}
15225 Here is another example, derived from the 7th Edition implementation of
15226 @code{rand} (1979-01-10). Here the programmer expects both
15227 multiplication and addition to wrap on overflow:
15230 static long int randx = 1;
15232 randx = randx * 1103515245 + 12345;
15233 return (randx >> 16) & 077777;
15236 In the following example, derived from the @acronym{GNU} C Library 2.5
15237 implementation of @code{mktime} (2006-09-09), the code assumes
15238 wraparound arithmetic in @code{+} to detect signed overflow:
15242 int sec_requested, sec_adjustment;
15244 t1 = t + sec_requested;
15245 t2 = t1 + sec_adjustment;
15246 if (((t1 < t) != (sec_requested < 0))
15247 | ((t2 < t1) != (sec_adjustment < 0)))
15251 If your code looks like these examples, it is probably safe even though
15252 it does not strictly conform to the C standard. This might lead one to
15253 believe that one can generally assume wraparound on overflow, but that
15254 is not always true, as can be seen in the next section.
15256 @node Optimization and Wraparound
15257 @subsection Optimizations That Break Wraparound Arithmetic
15258 @cindex loop induction
15260 Compilers sometimes generate code that is incompatible with wraparound
15261 integer arithmetic. A simple example is an algebraic simplification: a
15262 compiler might translate @code{(i * 2000) / 1000} to @code{i * 2}
15263 because it assumes that @code{i * 2000} does not overflow. The
15264 translation is not equivalent to the original when overflow occurs:
15265 e.g., in the typical case of 32-bit signed two's complement wraparound
15266 @code{int}, if @code{i} has type @code{int} and value @code{1073742},
15267 the original expression returns @minus{}2147483 but the optimized
15268 version returns the mathematically correct value 2147484.
15270 More subtly, loop induction optimizations often exploit the undefined
15271 behavior of signed overflow. Consider the following contrived function
15276 sumc (int lo, int hi)
15280 for (i = lo; i <= hi; i++)
15287 To avoid multiplying by 53 each time through the loop, an optimizing
15288 compiler might internally transform @code{sumc} to the equivalent of the
15293 transformed_sumc (int lo, int hi)
15298 for (ic = lo * 53; ic <= hic; ic += 53)
15305 This transformation is allowed by the C standard, but it is invalid for
15306 wraparound arithmetic when @code{INT_MAX / 53 < hi}, because then the
15307 overflow in computing expressions like @code{hi * 53} can cause the
15308 expression @code{i <= hi} to yield a different value from the
15309 transformed expression @code{ic <= hic}.
15311 For this reason, compilers that use loop induction and similar
15312 techniques often do not support reliable wraparound arithmetic when a
15313 loop induction variable like @code{ic} is involved. Since loop
15314 induction variables are generated by the compiler, and are not visible
15315 in the source code, it is not always trivial to say whether the problem
15318 Hardly any code actually depends on wraparound arithmetic in cases like
15319 these, so in practice these loop induction optimizations are almost
15320 always useful. However, edge cases in this area can cause problems.
15325 for (j = 1; 0 < j; j *= 2)
15330 Here, the loop attempts to iterate through all powers of 2 that
15331 @code{int} can represent, but the C standard allows a compiler to
15332 optimize away the comparison and generate an infinite loop,
15333 under the argument that behavior is undefined on overflow. As of this
15334 writing this optimization is not done by any production version of
15335 @acronym{GCC} with @option{-O2}, but it might be performed by other
15336 compilers, or by more aggressive @acronym{GCC} optimization options,
15337 and the @acronym{GCC} developers have not decided whether it will
15338 continue to work with @acronym{GCC} and @option{-O2}.
15340 @node Signed Overflow Advice
15341 @subsection Practical Advice for Signed Overflow Issues
15342 @cindex integer overflow
15343 @cindex overflow, signed integer
15344 @cindex signed integer overflow
15345 @cindex wraparound arithmetic
15347 Ideally the safest approach is to avoid signed integer overflow
15348 entirely. For example, instead of multiplying two signed integers, you
15349 can convert them to unsigned integers, multiply the unsigned values,
15350 then test whether the result is in signed range.
15352 Rewriting code in this way will be inconvenient, though, particularly if
15353 the signed values might be negative. Also, it may hurt
15354 performance. Using unsigned arithmetic to check for overflow is
15355 particularly painful to do portably and efficiently when dealing with an
15356 integer type like @code{uid_t} whose width and signedness vary from
15357 platform to platform.
15359 Furthermore, many C applications pervasively assume wraparound behavior
15360 and typically it is not easy to find and remove all these assumptions.
15361 Hence it is often useful to maintain nonstandard code that assumes
15362 wraparound on overflow, instead of rewriting the code. The rest of this
15363 section attempts to give practical advice for this situation.
15365 If your code wants to detect signed integer overflow in @code{sum = a +
15366 b}, it is generally safe to use an expression like @code{(sum < a) != (b
15369 If your code uses a signed loop index, make sure that the index cannot
15370 overflow, along with all signed expressions derived from the index.
15371 Here is a contrived example of problematic code with two instances of
15375 for (i = INT_MAX - 10; i <= INT_MAX; i++)
15378 report_overflow ();
15384 Because of the two overflows, a compiler might optimize away or
15385 transform the two comparisons in a way that is incompatible with the
15386 wraparound assumption.
15388 If your code uses an expression like @code{(i * 2000) / 1000} and you
15389 actually want the multiplication to wrap around on overflow, use
15390 unsigned arithmetic
15391 to do it, e.g., @code{((int) (i * 2000u)) / 1000}.
15393 If your code assumes wraparound behavior and you want to insulate it
15394 against any @acronym{GCC} optimizations that would fail to support that
15395 behavior, you should use @acronym{GCC}'s @option{-fwrapv} option, which
15396 causes signed overflow to wrap around reliably (except for division and
15397 remainder, as discussed in the next section).
15399 If you need to port to platforms where signed integer overflow does not
15400 reliably wrap around (e.g., due to hardware overflow checking, or to
15401 highly aggressive optimizations), you should consider debugging with
15402 @acronym{GCC}'s @option{-ftrapv} option, which causes signed overflow to
15403 raise an exception.
15405 @node Signed Integer Division
15406 @subsection Signed Integer Division and Integer Overflow
15407 @cindex division, integer
15410 integer division is not always harmless: for example, on CPUs of the
15411 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
15412 which by default terminates the program. Worse, taking the remainder
15413 of these two values typically yields the same signal on these CPUs,
15414 even though the C standard requires @code{INT_MIN % -1} to yield zero
15415 because the expression does not overflow.
15417 @node Null Pointers
15418 @section Properties of Null Pointers
15419 @cindex null pointers
15421 Most modern hosts reliably fail when you attempt to dereference a null
15424 On almost all modern hosts, null pointers use an all-bits-zero internal
15425 representation, so you can reliably use @code{memset} with 0 to set all
15426 the pointers in an array to null values.
15428 If @code{p} is a null pointer to an object type, the C expression
15429 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
15430 the standard says that it has undefined behavior.
15432 @node Buffer Overruns
15433 @section Buffer Overruns and Subscript Errors
15434 @cindex buffer overruns
15436 Buffer overruns and subscript errors are the most common dangerous
15437 errors in C programs. They result in undefined behavior because storing
15438 outside an array typically modifies storage that is used by some other
15439 object, and most modern systems lack runtime checks to catch these
15440 errors. Programs should not rely on buffer overruns being caught.
15442 There is one exception to the usual rule that a portable program cannot
15443 address outside an array. In C, it is valid to compute the address just
15444 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
15445 so long as you do not dereference the resulting pointer. But it is not
15446 valid to compute the address just before an object, e.g., @code{&a[-1]};
15447 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
15448 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
15449 reliable in general, and it is usually easy enough to avoid the
15450 potential portability problem, e.g., by allocating an extra unused array
15451 element at the start or end.
15453 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
15455 users might also consider using the @option{-fmudflap} option to catch
15458 Buffer overruns are usually caused by off-by-one errors, but there are
15459 more subtle ways to get them.
15461 Using @code{int} values to index into an array or compute array sizes
15462 causes problems on typical 64-bit hosts where an array index might
15463 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
15464 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
15465 are signed, and are wide enough in practice.
15467 If you add or multiply two numbers to calculate an array size, e.g.,
15468 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
15469 multiplication overflows.
15471 Many implementations of the @code{alloca} function silently misbehave
15472 and can generate buffer overflows if given sizes that are too large.
15473 The size limits are implementation dependent, but are at least 4000
15474 bytes on all platforms that we know about.
15476 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
15477 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
15478 portable code should not use them unless the inputs are known to be
15479 within certain limits. The time-related functions can overflow their
15480 buffers if given timestamps out of range (e.g., a year less than -999
15481 or greater than 9999). Time-related buffer overflows cannot happen with
15482 recent-enough versions of the @acronym{GNU} C library, but are possible
15484 implementations. The @code{gets} function is the worst, since it almost
15485 invariably overflows its buffer when presented with an input line larger
15488 @node Volatile Objects
15489 @section Volatile Objects
15490 @cindex volatile objects
15492 The keyword @code{volatile} is often misunderstood in portable code.
15493 Its use inhibits some memory-access optimizations, but programmers often
15494 wish that it had a different meaning than it actually does.
15496 @code{volatile} was designed for code that accesses special objects like
15497 memory-mapped device registers whose contents spontaneously change.
15498 Such code is inherently low-level, and it is difficult to specify
15499 portably what @code{volatile} means in these cases. The C standard
15500 says, ``What constitutes an access to an object that has
15501 volatile-qualified type is implementation-defined,'' so in theory each
15502 implementation is supposed to fill in the gap by documenting what
15503 @code{volatile} means for that implementation. In practice, though,
15504 this documentation is usually absent or incomplete.
15506 One area of confusion is the distinction between objects defined with
15507 volatile types, and volatile lvalues. From the C standard's point of
15508 view, an object defined with a volatile type has externally visible
15509 behavior. You can think of such objects as having little oscilloscope
15510 probes attached to them, so that the user can observe some properties of
15511 accesses to them, just as the user can observe data written to output
15512 files. However, the standard does not make it clear whether users can
15513 observe accesses by volatile lvalues to ordinary objects. For example:
15516 /* Declare and access a volatile object.
15517 Accesses to X are "visible" to users. */
15518 static int volatile x;
15521 /* Access two ordinary objects via a volatile lvalue.
15522 It's not clear whether accesses to *P are "visible". */
15524 int *z = malloc (sizeof (int));
15532 Programmers often wish that @code{volatile} meant ``Perform the memory
15533 access here and now, without merging several memory accesses, without
15534 changing the memory word size, and without reordering.'' But the C
15535 standard does not require this. For objects defined with a volatile
15536 type, accesses must be done before the next sequence point; but
15537 otherwise merging, reordering, and word-size change is allowed. Worse,
15538 it is not clear from the standard whether volatile lvalues provide more
15539 guarantees in general than nonvolatile lvalues, if the underlying
15540 objects are ordinary.
15542 Even when accessing objects defined with a volatile type,
15543 the C standard allows only
15544 extremely limited signal handlers: the behavior is undefined if a signal
15545 handler reads any nonlocal object, or writes to any nonlocal object
15546 whose type is not @code{sig_atomic_t volatile}, or calls any standard
15547 library function other than @code{abort}, @code{signal}, and (if C99)
15548 @code{_Exit}. Hence C compilers need not worry about a signal handler
15549 disturbing ordinary computation, unless the computation accesses a
15550 @code{sig_atomic_t volatile} lvalue that is not a local variable.
15551 (There is an obscure exception for accesses via a pointer to a volatile
15552 character, since it may point into part of a @code{sig_atomic_t
15553 volatile} object.) Posix
15554 adds to the list of library functions callable from a portable signal
15555 handler, but otherwise is like the C standard in this area.
15557 Some C implementations allow memory-access optimizations within each
15558 translation unit, such that actual behavior agrees with the behavior
15559 required by the standard only when calling a function in some other
15560 translation unit, and a signal handler acts like it was called from a
15561 different translation unit. The C standard hints that in these
15562 implementations, objects referred to by signal handlers ``would require
15563 explicit specification of @code{volatile} storage, as well as other
15564 implementation-defined restrictions.'' But unfortunately even for this
15565 special case these other restrictions are often not documented well.
15566 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
15567 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
15568 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
15569 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
15570 restrictions imposed by the @acronym{GNU} C library. Restrictions
15571 differ on other platforms.
15573 If possible, it is best to use a signal handler that fits within the
15574 limits imposed by the C and Posix standards.
15576 If this is not practical, you can try the following rules of thumb. A
15577 signal handler should access only volatile lvalues, preferably lvalues
15578 that refer to objects defined with a volatile type, and should not
15579 assume that the accessed objects have an internally consistent state
15580 if they are larger than a machine word. Furthermore, installers
15581 should employ compilers and compiler options that are commonly used
15582 for building operating system kernels, because kernels often need more
15583 from @code{volatile} than the C Standard requires, and installers who
15584 compile an application in a similar environment can sometimes benefit
15585 from the extra constraints imposed by kernels on compilers.
15586 Admittedly we are handwaving somewhat here, as there are few
15587 guarantees in this area; the rules of thumb may help to fix some bugs
15588 but there is a good chance that they will not fix them all.
15590 For @code{volatile}, C++ has the same problems that C does.
15591 Multithreaded applications have even more problems with @code{volatile},
15592 but they are beyond the scope of this section.
15594 The bottom line is that using @code{volatile} typically hurts
15595 performance but should not hurt correctness. In some cases its use
15596 does help correctness, but these cases are often so poorly understood
15597 that all too often adding @code{volatile} to a data structure merely
15598 alleviates some symptoms of a bug while not fixing the bug in general.
15600 @node Floating Point Portability
15601 @section Floating Point Portability
15602 @cindex floating point
15604 Almost all modern systems use IEEE-754 floating point, and it is safe to
15605 assume IEEE-754 in most portable code these days. For more information,
15606 please see David Goldberg's classic paper
15607 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15608 Scientist Should Know About Floating-Point Arithmetic}.
15610 @node Exiting Portably
15611 @section Exiting Portably
15612 @cindex exiting portably
15614 A C or C++ program can exit with status @var{N} by returning
15615 @var{N} from the @code{main} function. Portable programs are supposed
15616 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15617 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15618 fail by exiting with status 1, and test programs that assume Posix can
15619 fail by exiting with status values from 1 through 255. Programs on
15620 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15621 status when @code{main} returned nonzero, but ancient systems like these
15622 are no longer of practical concern.
15624 A program can also exit with status @var{N} by passing @var{N} to the
15625 @code{exit} function, and a program can fail by calling the @code{abort}
15626 function. If a program is specialized to just some platforms, it can fail
15627 by calling functions specific to those platforms, e.g., @code{_exit}
15628 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
15629 function should be declared, typically by including a header. For
15630 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15631 either directly or via the default includes (@pxref{Default Includes}).
15633 A program can fail due to undefined behavior such as dereferencing a null
15634 pointer, but this is not recommended as undefined behavior allows an
15635 implementation to do whatever it pleases and this includes exiting
15639 @c ================================================== Manual Configuration
15641 @node Manual Configuration
15642 @chapter Manual Configuration
15644 A few kinds of features can't be guessed automatically by running test
15645 programs. For example, the details of the object-file format, or
15646 special options that need to be passed to the compiler or linker. You
15647 can check for such features using ad-hoc means, such as having
15648 @command{configure} check the output of the @code{uname} program, or
15649 looking for libraries that are unique to particular systems. However,
15650 Autoconf provides a uniform method for handling unguessable features.
15653 * Specifying Names:: Specifying the system type
15654 * Canonicalizing:: Getting the canonical system type
15655 * Using System Type:: What to do with the system type
15658 @node Specifying Names
15659 @section Specifying the System Type
15660 @cindex System type
15663 @command{configure} scripts can make decisions based on a canonical name
15664 for the system type, which has the form:
15665 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15666 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15668 @command{configure} can usually guess the canonical name for the type of
15669 system it's running on. To do so it runs a script called
15670 @command{config.guess}, which infers the name using the @code{uname}
15671 command or symbols predefined by the C preprocessor.
15673 Alternately, the user can specify the system type with command line
15674 arguments to @command{configure}. Doing so is necessary when
15675 cross-compiling. In the most complex case of cross-compiling, three
15676 system types are involved. The options to specify them are:
15679 @item --build=@var{build-type}
15680 the type of system on which the package is being configured and
15681 compiled. It defaults to the result of running @command{config.guess}.
15683 @item --host=@var{host-type}
15684 the type of system on which the package runs. By default it is the
15685 same as the build machine. Specifying it enables the cross-compilation
15688 @item --target=@var{target-type}
15689 the type of system for which any compiler tools in the package
15690 produce code (rarely needed). By default, it is the same as host.
15693 If you mean to override the result of @command{config.guess}, use
15694 @option{--build}, not @option{--host}, since the latter enables
15695 cross-compilation. For historical reasons,
15696 whenever you specify @option{--host},
15697 be sure to specify @option{--build} too; this will be fixed in the
15698 future. So, to enter cross-compilation mode, use a command like this
15701 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15705 Note that if you do not specify @option{--host}, @command{configure}
15706 fails if it can't run the code generated by the specified compiler. For
15707 example, configuring as follows fails:
15710 ./configure CC=m68k-coff-gcc
15713 In the future, when cross-compiling Autoconf will @emph{not}
15714 accept tools (compilers, linkers, assemblers) whose name is not
15715 prefixed with the host type. The only case when this may be
15716 useful is when you really are not cross-compiling, but only
15717 building for a least-common-denominator architecture: an example
15718 is building for @code{i386-pc-linux-gnu} while running on an
15719 @code{i686-pc-linux-gnu} architecture. In this case, some particular
15720 pairs might be similar enough to let you get away with the system
15721 compilers, but in general the compiler might make bogus assumptions
15722 on the host: if you know what you are doing, please create symbolic
15723 links from the host compiler to the build compiler.
15725 @cindex @command{config.sub}
15726 @command{configure} recognizes short aliases for many system types; for
15727 example, @samp{decstation} can be used instead of
15728 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
15729 @command{config.sub} to canonicalize system type aliases.
15731 This section deliberately omits the description of the obsolete
15732 interface; see @ref{Hosts and Cross-Compilation}.
15735 @node Canonicalizing
15736 @section Getting the Canonical System Type
15737 @cindex System type
15738 @cindex Canonical system type
15740 The following macros make the system type available to @command{configure}
15743 @ovindex build_alias
15744 @ovindex host_alias
15745 @ovindex target_alias
15747 The variables @samp{build_alias}, @samp{host_alias}, and
15748 @samp{target_alias} are always exactly the arguments of @option{--build},
15749 @option{--host}, and @option{--target}; in particular, they are left empty
15750 if the user did not use them, even if the corresponding
15751 @code{AC_CANONICAL} macro was run. Any configure script may use these
15752 variables anywhere. These are the variables that should be used when in
15753 interaction with the user.
15755 If you need to recognize some special environments based on their system
15756 type, run the following macros to get canonical system names. These
15757 variables are not set before the macro call.
15759 If you use these macros, you must distribute @command{config.guess} and
15760 @command{config.sub} along with your source code. @xref{Output}, for
15761 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15762 to control in which directory @command{configure} looks for those scripts.
15765 @defmac AC_CANONICAL_BUILD
15766 @acindex{CANONICAL_BUILD}
15769 @ovindex build_vendor
15771 Compute the canonical build-system type variable, @code{build}, and its
15772 three individual parts @code{build_cpu}, @code{build_vendor}, and
15775 If @option{--build} was specified, then @code{build} is the
15776 canonicalization of @code{build_alias} by @command{config.sub},
15777 otherwise it is determined by the shell script @command{config.guess}.
15780 @defmac AC_CANONICAL_HOST
15781 @acindex{CANONICAL_HOST}
15784 @ovindex host_vendor
15786 Compute the canonical host-system type variable, @code{host}, and its
15787 three individual parts @code{host_cpu}, @code{host_vendor}, and
15790 If @option{--host} was specified, then @code{host} is the
15791 canonicalization of @code{host_alias} by @command{config.sub},
15792 otherwise it defaults to @code{build}.
15795 @defmac AC_CANONICAL_TARGET
15796 @acindex{CANONICAL_TARGET}
15798 @ovindex target_cpu
15799 @ovindex target_vendor
15801 Compute the canonical target-system type variable, @code{target}, and its
15802 three individual parts @code{target_cpu}, @code{target_vendor}, and
15805 If @option{--target} was specified, then @code{target} is the
15806 canonicalization of @code{target_alias} by @command{config.sub},
15807 otherwise it defaults to @code{host}.
15810 Note that there can be artifacts due to the backward compatibility
15811 code. See @xref{Hosts and Cross-Compilation}, for more.
15813 @node Using System Type
15814 @section Using the System Type
15816 In @file{configure.ac} the system type is generally used by one or more
15817 @code{case} statements to select system-specifics. Shell wildcards can
15818 be used to match a group of system types.
15820 For example, an extra assembler code object file could be chosen, giving
15821 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
15822 following would be used in a makefile to add the object to a
15823 program or library.
15827 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15828 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
15831 AC_SUBST([CYCLE_OBJ])
15834 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15835 to select variant source files, for example optimized code for some
15836 CPUs. The configured CPU type doesn't always indicate exact CPU types,
15837 so some runtime capability checks may be necessary too.
15841 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15842 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15843 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15847 The host system type can also be used to find cross-compilation tools
15848 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15850 The above examples all show @samp{$host}, since this is where the code
15851 is going to run. Only rarely is it necessary to test @samp{$build}
15852 (which is where the build is being done).
15854 Whenever you're tempted to use @samp{$host} it's worth considering
15855 whether some sort of probe would be better. New system types come along
15856 periodically or previously missing features are added. Well-written
15857 probes can adapt themselves to such things, but hard-coded lists of
15858 names can't. Here are some guidelines,
15862 Availability of libraries and library functions should always be checked
15865 Variant behavior of system calls is best identified with runtime tests
15866 if possible, but bug workarounds or obscure difficulties might have to
15867 be driven from @samp{$host}.
15869 Assembler code is inevitably highly CPU-specific and is best selected
15870 according to @samp{$host_cpu}.
15872 Assembler variations like underscore prefix on globals or ELF versus
15873 COFF type directives are however best determined by probing, perhaps
15874 even examining the compiler output.
15877 @samp{$target} is for use by a package creating a compiler or similar.
15878 For ordinary packages it's meaningless and should not be used. It
15879 indicates what the created compiler should generate code for, if it can
15880 cross-compile. @samp{$target} generally selects various hard-coded CPU
15881 and system conventions, since usually the compiler or tools under
15882 construction themselves determine how the target works.
15885 @c ===================================================== Site Configuration.
15887 @node Site Configuration
15888 @chapter Site Configuration
15890 @command{configure} scripts support several kinds of local configuration
15891 decisions. There are ways for users to specify where external software
15892 packages are, include or exclude optional features, install programs
15893 under modified names, and set default values for @command{configure}
15897 * Help Formatting:: Customizing @samp{configure --help}
15898 * External Software:: Working with other optional software
15899 * Package Options:: Selecting optional features
15900 * Pretty Help Strings:: Formatting help string
15901 * Option Checking:: Controlling checking of @command{configure} options
15902 * Site Details:: Configuring site details
15903 * Transforming Names:: Changing program names when installing
15904 * Site Defaults:: Giving @command{configure} local defaults
15907 @node Help Formatting
15908 @section Controlling Help Output
15910 Users consult @samp{configure --help} to learn of configuration
15911 decisions specific to your package. By default, @command{configure}
15912 breaks this output into sections for each type of option; within each
15913 section, help strings appear in the order @file{configure.ac} defines
15919 --enable-bar include bar
15926 @defmac AC_PRESERVE_HELP_ORDER
15927 @acindex{PRESERVE_HELP_ORDER}
15929 Request an alternate @option{--help} format, in which options of all
15930 types appear together, in the order defined. Call this macro before any
15931 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15934 Optional Features and Packages:
15936 --enable-bar include bar
15942 @node External Software
15943 @section Working With External Software
15944 @cindex External software
15946 Some packages require, or can optionally use, other software packages
15947 that are already installed. The user can give @command{configure}
15948 command line options to specify which such external software to use.
15949 The options have one of these forms:
15951 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15954 --with-@var{package}[=@var{arg}]
15955 --without-@var{package}
15958 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15959 instead of some other linker. @option{--with-x} means work with The X
15962 The user can give an argument by following the package name with
15963 @samp{=} and the argument. Giving an argument of @samp{no} is for
15964 packages that are used by default; it says to @emph{not} use the
15965 package. An argument that is neither @samp{yes} nor @samp{no} could
15966 include a name or number of a version of the other package, to specify
15967 more precisely which other package this program is supposed to work
15968 with. If no argument is given, it defaults to @samp{yes}.
15969 @option{--without-@var{package}} is equivalent to
15970 @option{--with-@var{package}=no}.
15972 Normally @command{configure} scripts complain about
15973 @option{--with-@var{package}} options that they do not support.
15974 @xref{Option Checking}, for details, and for how to override the
15977 For each external software package that may be used, @file{configure.ac}
15978 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
15979 user asked to use it. Whether each package is used or not by default,
15980 and which arguments are valid, is up to you.
15982 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15984 If the user gave @command{configure} the option @option{--with-@var{package}}
15985 or @option{--without-@var{package}}, run shell commands
15986 @var{action-if-given}. If neither option was given, run shell commands
15987 @var{action-if-not-given}. The name @var{package} indicates another
15988 software package that this program should work with. It should consist
15989 only of alphanumeric characters, dashes, and dots.
15991 The option's argument is available to the shell commands
15992 @var{action-if-given} in the shell variable @code{withval}, which is
15993 actually just the value of the shell variable named
15994 @code{with_@var{package}}, with any non-alphanumeric characters in
15995 @var{package} changed into @samp{_}. You may use that variable instead,
15998 The argument @var{help-string} is a description of the option that
16001 --with-readline support fancy command line editing
16005 @var{help-string} may be more than one line long, if more detail is
16006 needed. Just make sure the columns line up in @samp{configure
16007 --help}. Avoid tabs in the help string. You'll need to enclose the
16008 help string in @samp{[} and @samp{]} in order to produce the leading
16011 You should format your @var{help-string} with the macro
16012 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16014 The following example shows how to use the @code{AC_ARG_WITH} macro in
16015 a common situation. You want to let the user decide whether to enable
16016 support for an external library (e.g., the readline library); if the user
16017 specified neither @option{--with-readline} nor @option{--without-readline},
16018 you want to enable support for readline only if the library is available
16021 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16023 AC_ARG_WITH([readline],
16024 [AS_HELP_STRING([--with-readline],
16025 [support fancy command line editing @@<:@@default=check@@:>@@])],
16027 [with_readline=check])
16030 AS_IF([test "x$with_readline" != xno],
16031 [AC_CHECK_LIB([readline], [main],
16032 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16033 AC_DEFINE([HAVE_LIBREADLINE], [1],
16034 [Define if you have libreadline])
16036 [if test "x$with_readline" != xcheck; then
16038 [--with-readline was given, but test for readline failed])
16043 The next example shows how to use @code{AC_ARG_WITH} to give the user the
16044 possibility to enable support for the readline library, in case it is still
16045 experimental and not well tested, and is therefore disabled by default.
16047 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16049 AC_ARG_WITH([readline],
16050 [AS_HELP_STRING([--with-readline],
16051 [enable experimental support for readline])],
16053 [with_readline=no])
16056 AS_IF([test "x$with_readline" != xno],
16057 [AC_CHECK_LIB([readline], [main],
16058 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16059 AC_DEFINE([HAVE_LIBREADLINE], [1],
16060 [Define if you have libreadline])
16063 [--with-readline was given, but test for readline failed])],
16067 The last example shows how to use @code{AC_ARG_WITH} to give the user the
16068 possibility to disable support for the readline library, given that it is
16069 an important feature and that it should be enabled by default.
16071 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
16073 AC_ARG_WITH([readline],
16074 [AS_HELP_STRING([--without-readline],
16075 [disable support for readline])],
16077 [with_readline=yes])
16080 AS_IF([test "x$with_readline" != xno],
16081 [AC_CHECK_LIB([readline], [main],
16082 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
16083 AC_DEFINE([HAVE_LIBREADLINE], [1],
16084 [Define if you have libreadline])
16087 [readline test failed (--without-readline to disable)])],
16091 These three examples can be easily adapted to the case where
16092 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
16093 @ref{Package Options}).
16096 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
16098 This is an obsolete version of @code{AC_ARG_WITH} that does not
16099 support providing a help string.
16102 @node Package Options
16103 @section Choosing Package Options
16104 @cindex Package options
16105 @cindex Options, package
16107 If a software package has optional compile-time features, the user can
16108 give @command{configure} command line options to specify whether to
16109 compile them. The options have one of these forms:
16111 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
16114 --enable-@var{feature}[=@var{arg}]
16115 --disable-@var{feature}
16118 These options allow users to choose which optional features to build and
16119 install. @option{--enable-@var{feature}} options should never make a
16120 feature behave differently or cause one feature to replace another.
16121 They should only cause parts of the program to be built rather than left
16124 The user can give an argument by following the feature name with
16125 @samp{=} and the argument. Giving an argument of @samp{no} requests
16126 that the feature @emph{not} be made available. A feature with an
16127 argument looks like @option{--enable-debug=stabs}. If no argument is
16128 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
16129 equivalent to @option{--enable-@var{feature}=no}.
16131 Normally @command{configure} scripts complain about
16132 @option{--enable-@var{package}} options that they do not support.
16133 @xref{Option Checking}, for details, and for how to override the
16136 For each optional feature, @file{configure.ac} should call
16137 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
16138 to include it. Whether each feature is included or not by default, and
16139 which arguments are valid, is up to you.
16141 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
16142 @acindex{ARG_ENABLE}
16143 If the user gave @command{configure} the option
16144 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
16145 shell commands @var{action-if-given}. If neither option was given, run
16146 shell commands @var{action-if-not-given}. The name @var{feature}
16147 indicates an optional user-level facility. It should consist only of
16148 alphanumeric characters, dashes, and dots.
16150 The option's argument is available to the shell commands
16151 @var{action-if-given} in the shell variable @code{enableval}, which is
16152 actually just the value of the shell variable named
16153 @code{enable_@var{feature}}, with any non-alphanumeric characters in
16154 @var{feature} changed into @samp{_}. You may use that variable instead,
16155 if you wish. The @var{help-string} argument is like that of
16156 @code{AC_ARG_WITH} (@pxref{External Software}).
16158 You should format your @var{help-string} with the macro
16159 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
16161 See the examples suggested with the definition of @code{AC_ARG_WITH}
16162 (@pxref{External Software}) to get an idea of possible applications of
16163 @code{AC_ARG_ENABLE}.
16166 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
16168 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
16169 support providing a help string.
16173 @node Pretty Help Strings
16174 @section Making Your Help Strings Look Pretty
16175 @cindex Help strings
16177 Properly formatting the @samp{help strings} which are used in
16178 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
16179 (@pxref{Package Options}) can be challenging. Specifically, you want
16180 your own @samp{help strings} to line up in the appropriate columns of
16181 @samp{configure --help} just like the standard Autoconf @samp{help
16182 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
16184 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
16185 @acindex{HELP_STRING}
16187 Expands into an help string that looks pretty when the user executes
16188 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
16189 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
16190 Options}). The following example makes this clearer.
16194 [AS_HELP_STRING([--with-foo],
16195 [use foo (default is no)])],
16196 [use_foo=$withval],
16200 The second argument of @code{AS_HELP_STRING} is
16201 not a literal, and should not be double quoted.
16202 @xref{Autoconf Language}, for a more detailed explanation.
16203 Then the last few lines of @samp{configure --help} appear like
16207 --enable and --with options recognized:
16208 --with-foo use foo (default is no)
16211 The @code{AS_HELP_STRING} macro is particularly helpful when the
16212 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
16213 arguments, as shown in the following example.
16216 AC_DEFUN([MY_ARG_WITH],
16218 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
16219 [use_[]$1=$withval],
16225 @node Option Checking
16226 @section Controlling Checking of @command{configure} Options
16227 @cindex Options, Package
16229 The @command{configure} script checks its command-line options against a
16230 list of known options, like @option{--help} or @option{--config-cache}.
16231 An unknown option ordinarily indicates a mistake by the user and
16232 @command{configure} halts with an error. However, by default unknown
16233 @option{--with-@var{package}} and @option{--enable-@var{feature}}
16234 options elicit only a warning, to support configuring entire source
16237 Source trees often contain multiple packages with a top-level
16238 @command{configure} script that uses the @code{AC_CONFIG_SUBDIRS} macro
16239 (@pxref{Subdirectories}). Because the packages generally support
16240 different @option{--with-@var{package}} and
16241 @option{--enable-@var{feature}} options, the @acronym{GNU} Coding
16242 Standards say they must accept unrecognized options without halting.
16243 Even a warning message is undesirable here, so @code{AC_CONFIG_SUBDIRS}
16244 automatically disables the warnings.
16246 This default behavior may be modified in two ways. First, the installer
16247 can invoke @command{configure} with the
16248 @option{--disable-option-checking} or
16249 @option{--enable-option-checking=fatal} options to disable these
16250 warnings or turn them into fatal errors, respectively. Second, the
16251 maintainer can use @code{AC_DISABLE_OPTION_CHECKING}.
16253 @defmac AC_DISABLE_OPTION_CHECKING
16254 @acindex{DISABLE_OPTION_CHECKING}
16256 By default, disable warnings for unrecognized
16257 @option{--with-@var{package}} or @option{--enable-@var{feature}}
16258 options. This is implied by @code{AC_CONFIG_SUBDIRS}.
16260 The installer can override this behavior by passing
16261 @option{--enable-option-checking} (enable warnings) or
16262 @option{--enable-option-checking=fatal} (enable errors) to
16263 @command{configure}.
16268 @section Configuring Site Details
16269 @cindex Site details
16271 Some software packages require complex site-specific information. Some
16272 examples are host names to use for certain services, company names, and
16273 email addresses to contact. Since some configuration scripts generated
16274 by Metaconfig ask for such information interactively, people sometimes
16275 wonder how to get that information in Autoconf-generated configuration
16276 scripts, which aren't interactive.
16278 Such site configuration information should be put in a file that is
16279 edited @emph{only by users}, not by programs. The location of the file
16280 can either be based on the @code{prefix} variable, or be a standard
16281 location such as the user's home directory. It could even be specified
16282 by an environment variable. The programs should examine that file at
16283 runtime, rather than at compile time. Runtime configuration is more
16284 convenient for users and makes the configuration process simpler than
16285 getting the information while configuring. @xref{Directory Variables, ,
16286 Variables for Installation Directories, standards, @acronym{GNU} Coding
16287 Standards}, for more information on where to put data files.
16289 @node Transforming Names
16290 @section Transforming Program Names When Installing
16291 @cindex Transforming program names
16292 @cindex Program names, transforming
16294 Autoconf supports changing the names of programs when installing them.
16295 In order to use these transformations, @file{configure.ac} must call the
16296 macro @code{AC_ARG_PROGRAM}.
16298 @defmac AC_ARG_PROGRAM
16299 @acindex{ARG_PROGRAM}
16300 @ovindex program_transform_name
16301 Place in output variable @code{program_transform_name} a sequence of
16302 @code{sed} commands for changing the names of installed programs.
16304 If any of the options described below are given to @command{configure},
16305 program names are transformed accordingly. Otherwise, if
16306 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
16307 is given, the target type followed by a dash is used as a prefix.
16308 Otherwise, no program name transformation is done.
16312 * Transformation Options:: @command{configure} options to transform names
16313 * Transformation Examples:: Sample uses of transforming names
16314 * Transformation Rules:: Makefile uses of transforming names
16317 @node Transformation Options
16318 @subsection Transformation Options
16320 You can specify name transformations by giving @command{configure} these
16321 command line options:
16324 @item --program-prefix=@var{prefix}
16325 prepend @var{prefix} to the names;
16327 @item --program-suffix=@var{suffix}
16328 append @var{suffix} to the names;
16330 @item --program-transform-name=@var{expression}
16331 perform @code{sed} substitution @var{expression} on the names.
16334 @node Transformation Examples
16335 @subsection Transformation Examples
16337 These transformations are useful with programs that can be part of a
16338 cross-compilation development environment. For example, a
16339 cross-assembler running on a Sun 4 configured with
16340 @option{--target=i960-vxworks} is normally installed as
16341 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
16342 with a native Sun 4 assembler.
16344 You can force a program name to begin with @file{g}, if you don't want
16345 @acronym{GNU} programs installed on your system to shadow other programs with
16346 the same name. For example, if you configure @acronym{GNU} @code{diff} with
16347 @option{--program-prefix=g}, then when you run @samp{make install} it is
16348 installed as @file{/usr/local/bin/gdiff}.
16350 As a more sophisticated example, you could use
16353 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
16357 to prepend @samp{g} to most of the program names in a source tree,
16358 excepting those like @code{gdb} that already have one and those like
16359 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
16360 assuming that you have a source tree containing those programs that is
16361 set up to use this feature.)
16363 One way to install multiple versions of some programs simultaneously is
16364 to append a version number to the name of one or both. For example, if
16365 you want to keep Autoconf version 1 around for awhile, you can configure
16366 Autoconf version 2 using @option{--program-suffix=2} to install the
16367 programs as @file{/usr/local/bin/autoconf2},
16368 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
16369 that only the binaries are renamed, therefore you'd have problems with
16370 the library files which might overlap.
16372 @node Transformation Rules
16373 @subsection Transformation Rules
16375 Here is how to use the variable @code{program_transform_name} in a
16376 @file{Makefile.in}:
16379 PROGRAMS = cp ls rm
16380 transform = @@program_transform_name@@
16382 for p in $(PROGRAMS); do \
16383 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
16384 sed '$(transform)'`; \
16388 for p in $(PROGRAMS); do \
16389 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
16393 It is guaranteed that @code{program_transform_name} is never empty, and
16394 that there are no useless separators. Therefore you may safely embed
16395 @code{program_transform_name} within a sed program using @samp{;}:
16398 transform = @@program_transform_name@@
16399 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
16402 Whether to do the transformations on documentation files (Texinfo or
16403 @code{man}) is a tricky question; there seems to be no perfect answer,
16404 due to the several reasons for name transforming. Documentation is not
16405 usually particular to a specific architecture, and Texinfo files do not
16406 conflict with system documentation. But they might conflict with
16407 earlier versions of the same files, and @code{man} pages sometimes do
16408 conflict with system documentation. As a compromise, it is probably
16409 best to do name transformations on @code{man} pages but not on Texinfo
16412 @node Site Defaults
16413 @section Setting Site Defaults
16414 @cindex Site defaults
16416 Autoconf-generated @command{configure} scripts allow your site to provide
16417 default values for some configuration values. You do this by creating
16418 site- and system-wide initialization files.
16420 @evindex CONFIG_SITE
16421 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
16422 uses its value as the name of a shell script to read. Otherwise, it
16423 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
16424 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
16425 settings in machine-specific files override those in machine-independent
16426 ones in case of conflict.
16428 Site files can be arbitrary shell scripts, but only certain kinds of
16429 code are really appropriate to be in them. Because @command{configure}
16430 reads any cache file after it has read any site files, a site file can
16431 define a default cache file to be shared between all Autoconf-generated
16432 @command{configure} scripts run on that system (@pxref{Cache Files}). If
16433 you set a default cache file in a site file, it is a good idea to also
16434 set the output variable @code{CC} in that site file, because the cache
16435 file is only valid for a particular compiler, but many systems have
16438 You can examine or override the value set by a command line option to
16439 @command{configure} in a site file; options set shell variables that have
16440 the same names as the options, with any dashes turned into underscores.
16441 The exceptions are that @option{--without-} and @option{--disable-} options
16442 are like giving the corresponding @option{--with-} or @option{--enable-}
16443 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
16444 sets the variable @code{cache_file} to the value @samp{localcache};
16445 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
16446 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
16447 variable @code{prefix} to the value @samp{/usr}; etc.
16449 Site files are also good places to set default values for other output
16450 variables, such as @code{CFLAGS}, if you need to give them non-default
16451 values: anything you would normally do, repetitively, on the command
16452 line. If you use non-default values for @var{prefix} or
16453 @var{exec_prefix} (wherever you locate the site file), you can set them
16454 in the site file if you specify it with the @code{CONFIG_SITE}
16455 environment variable.
16457 You can set some cache values in the site file itself. Doing this is
16458 useful if you are cross-compiling, where it is impossible to check features
16459 that require running a test program. You could ``prime the cache'' by
16460 setting those values correctly for that system in
16461 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
16462 variables you need to set, look for shell variables with @samp{_cv_} in
16463 their names in the affected @command{configure} scripts, or in the Autoconf
16464 M4 source code for those macros.
16466 The cache file is careful to not override any variables set in the site
16467 files. Similarly, you should not override command-line options in the
16468 site files. Your code should check that variables such as @code{prefix}
16469 and @code{cache_file} have their default values (as set near the top of
16470 @command{configure}) before changing them.
16472 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
16473 command @samp{configure --prefix=/usr/share/local/gnu} would read this
16474 file (if @code{CONFIG_SITE} is not set to a different file).
16477 # config.site for configure
16479 # Change some defaults.
16480 test "$prefix" = NONE && prefix=/usr/share/local/gnu
16481 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
16482 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
16483 test "$localstatedir" = '$prefix/var' && localstatedir=/var
16485 # Give Autoconf 2.x generated configure scripts a shared default
16486 # cache file for feature test results, architecture-specific.
16487 if test "$cache_file" = /dev/null; then
16488 cache_file="$prefix/var/config.cache"
16489 # A cache file is only valid for one C compiler.
16495 @c ============================================== Running configure Scripts.
16497 @node Running configure Scripts
16498 @chapter Running @command{configure} Scripts
16499 @cindex @command{configure}
16501 Below are instructions on how to configure a package that uses a
16502 @command{configure} script, suitable for inclusion as an @file{INSTALL}
16503 file in the package. A plain-text version of @file{INSTALL} which you
16504 may use comes with Autoconf.
16507 * Basic Installation:: Instructions for typical cases
16508 * Compilers and Options:: Selecting compilers and optimization
16509 * Multiple Architectures:: Compiling for multiple architectures at once
16510 * Installation Names:: Installing in different directories
16511 * Optional Features:: Selecting optional features
16512 * System Type:: Specifying the system type
16513 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
16514 * Defining Variables:: Specifying the compiler etc.
16515 * configure Invocation:: Changing how @command{configure} runs
16519 @include install.texi
16522 @c ============================================== config.status Invocation
16524 @node config.status Invocation
16525 @chapter config.status Invocation
16526 @cindex @command{config.status}
16528 The @command{configure} script creates a file named @file{config.status},
16529 which actually configures, @dfn{instantiates}, the template files. It
16530 also records the configuration options that were specified when the
16531 package was last configured in case reconfiguring is needed.
16535 ./config.status @var{option}@dots{} [@var{file}@dots{}]
16538 It configures the @var{files}; if none are specified, all the templates
16539 are instantiated. The files must be specified without their
16540 dependencies, as in
16543 ./config.status foobar
16550 ./config.status foobar:foo.in:bar.in
16553 The supported options are:
16558 Print a summary of the command line options, the list of the template
16563 Print the version number of Autoconf and the configuration settings,
16569 Do not print progress messages.
16573 Don't remove the temporary files.
16575 @item --file=@var{file}[:@var{template}]
16576 Require that @var{file} be instantiated as if
16577 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
16578 @var{file} and @var{template} may be @samp{-} in which case the standard
16579 output and/or standard input, respectively, is used. If a
16580 @var{template} file name is relative, it is first looked for in the build
16581 tree, and then in the source tree. @xref{Configuration Actions}, for
16584 This option and the following ones provide one way for separately
16585 distributed packages to share the values computed by @command{configure}.
16586 Doing so can be useful if some of the packages need a superset of the
16587 features that one of them, perhaps a common library, does. These
16588 options allow a @file{config.status} file to create files other than the
16589 ones that its @file{configure.ac} specifies, so it can be used for a
16592 @item --header=@var{file}[:@var{template}]
16593 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
16596 Ask @file{config.status} to update itself and exit (no instantiation).
16597 This option is useful if you change @command{configure}, so that the
16598 results of some tests might be different from the previous run. The
16599 @option{--recheck} option reruns @command{configure} with the same arguments
16600 you used before, plus the @option{--no-create} option, which prevents
16601 @command{configure} from running @file{config.status} and creating
16602 @file{Makefile} and other files, and the @option{--no-recursion} option,
16603 which prevents @command{configure} from running other @command{configure}
16604 scripts in subdirectories. (This is so other Make rules can
16605 run @file{config.status} when it changes; @pxref{Automatic Remaking},
16609 @file{config.status} checks several optional environment variables that
16610 can alter its behavior:
16612 @defvar CONFIG_SHELL
16613 @evindex CONFIG_SHELL
16614 The shell with which to run @command{configure} for the @option{--recheck}
16615 option. It must be Bourne-compatible. The default is a shell that
16616 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
16617 Invoking @command{configure} by hand bypasses this setting, so you may
16618 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
16619 to insure that the same shell is used everywhere. The absolute name of the
16620 shell should be passed.
16623 @defvar CONFIG_STATUS
16624 @evindex CONFIG_STATUS
16625 The file name to use for the shell script that records the
16626 configuration. The default is @file{./config.status}. This variable is
16627 useful when one package uses parts of another and the @command{configure}
16628 scripts shouldn't be merged because they are maintained separately.
16631 You can use @file{./config.status} in your makefiles. For example, in
16632 the dependencies given above (@pxref{Automatic Remaking}),
16633 @file{config.status} is run twice when @file{configure.ac} has changed.
16634 If that bothers you, you can make each run only regenerate the files for
16639 stamp-h: config.h.in config.status
16640 ./config.status config.h
16643 Makefile: Makefile.in config.status
16644 ./config.status Makefile
16648 The calling convention of @file{config.status} has changed; see
16649 @ref{Obsolete config.status Use}, for details.
16652 @c =================================================== Obsolete Constructs
16654 @node Obsolete Constructs
16655 @chapter Obsolete Constructs
16656 @cindex Obsolete constructs
16658 Autoconf changes, and throughout the years some constructs have been
16659 obsoleted. Most of the changes involve the macros, but in some cases
16660 the tools themselves, or even some concepts, are now considered
16663 You may completely skip this chapter if you are new to Autoconf. Its
16664 intention is mainly to help maintainers updating their packages by
16665 understanding how to move to more modern constructs.
16668 * Obsolete config.status Use:: Obsolete convention for @command{config.status}
16669 * acconfig Header:: Additional entries in @file{config.h.in}
16670 * autoupdate Invocation:: Automatic update of @file{configure.ac}
16671 * Obsolete Macros:: Backward compatibility macros
16672 * Autoconf 1:: Tips for upgrading your files
16673 * Autoconf 2.13:: Some fresher tips
16676 @node Obsolete config.status Use
16677 @section Obsolete @file{config.status} Invocation
16679 @file{config.status} now supports arguments to specify the files to
16680 instantiate; see @ref{config.status Invocation}, for more details.
16681 Before, environment variables had to be used.
16683 @defvar CONFIG_COMMANDS
16684 @evindex CONFIG_COMMANDS
16685 The tags of the commands to execute. The default is the arguments given
16686 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16687 @file{configure.ac}.
16690 @defvar CONFIG_FILES
16691 @evindex CONFIG_FILES
16692 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16693 The default is the arguments given to @code{AC_OUTPUT} and
16694 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16697 @defvar CONFIG_HEADERS
16698 @evindex CONFIG_HEADERS
16699 The files in which to substitute C @code{#define} statements. The
16700 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16701 macro was not called, @file{config.status} ignores this variable.
16704 @defvar CONFIG_LINKS
16705 @evindex CONFIG_LINKS
16706 The symbolic links to establish. The default is the arguments given to
16707 @code{AC_CONFIG_LINKS}; if that macro was not called,
16708 @file{config.status} ignores this variable.
16711 In @ref{config.status Invocation}, using this old interface, the example
16717 stamp-h: config.h.in config.status
16718 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16719 CONFIG_HEADERS=config.h ./config.status
16722 Makefile: Makefile.in config.status
16723 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16724 CONFIG_FILES=Makefile ./config.status
16729 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16730 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
16731 for @code{CONFIG_COMMANDS}, etc.)
16734 @node acconfig Header
16735 @section @file{acconfig.h}
16737 @cindex @file{acconfig.h}
16738 @cindex @file{config.h.top}
16739 @cindex @file{config.h.bot}
16741 In order to produce @file{config.h.in}, @command{autoheader} needs to
16742 build or to find templates for each symbol. Modern releases of Autoconf
16743 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16744 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16745 list of needed templates. @command{autoheader} copied comments and
16746 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16747 the current directory, if present. This file used to be mandatory if
16748 you @code{AC_DEFINE} any additional symbols.
16750 Modern releases of Autoconf also provide @code{AH_TOP} and
16751 @code{AH_BOTTOM} if you need to prepend/append some information to
16752 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
16753 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16754 @command{autoheader} copies the lines before the line containing
16755 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
16756 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16757 @command{autoheader} copies the lines after that line to the end of the
16758 file it generates. Either or both of those strings may be omitted. An
16759 even older alternate way to produce the same effect in ancient versions
16760 of Autoconf is to create the files @file{@var{file}.top} (typically
16761 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16762 directory. If they exist, @command{autoheader} copies them to the
16763 beginning and end, respectively, of its output.
16765 In former versions of Autoconf, the files used in preparing a software
16766 package for distribution were:
16769 configure.ac --. .------> autoconf* -----> configure
16771 [aclocal.m4] --+ `---.
16773 +--> [autoheader*] -> [config.h.in]
16774 [acconfig.h] ----. |
16781 Using only the @code{AH_} macros, @file{configure.ac} should be
16782 self-contained, and should not depend upon @file{acconfig.h} etc.
16785 @node autoupdate Invocation
16786 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16787 @cindex @command{autoupdate}
16789 The @command{autoupdate} program updates a @file{configure.ac} file that
16790 calls Autoconf macros by their old names to use the current macro names.
16791 In version 2 of Autoconf, most of the macros were renamed to use a more
16792 uniform and descriptive naming scheme. @xref{Macro Names}, for a
16793 description of the new scheme. Although the old names still work
16794 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16795 new names), you can make your @file{configure.ac} files more readable
16796 and make it easier to use the current Autoconf documentation if you
16797 update them to use the new macro names.
16799 @evindex SIMPLE_BACKUP_SUFFIX
16800 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16801 backing up the original version with the suffix @file{~} (or the value
16802 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16803 set). If you give @command{autoupdate} an argument, it reads that file
16804 instead of @file{configure.ac} and writes the updated file to the
16808 @command{autoupdate} accepts the following options:
16813 Print a summary of the command line options and exit.
16817 Print the version number of Autoconf and exit.
16821 Report processing steps.
16825 Don't remove the temporary files.
16829 Force the update even if the file has not changed. Disregard the cache.
16831 @item --include=@var{dir}
16832 @itemx -I @var{dir}
16833 Also look for input files in @var{dir}. Multiple invocations accumulate.
16834 Directories are browsed from last to first.
16837 @node Obsolete Macros
16838 @section Obsolete Macros
16840 Several macros are obsoleted in Autoconf, for various reasons (typically
16841 they failed to quote properly, couldn't be extended for more recent
16842 issues, etc.). They are still supported, but deprecated: their use
16845 During the jump from Autoconf version 1 to version 2, most of the
16846 macros were renamed to use a more uniform and descriptive naming scheme,
16847 but their signature did not change. @xref{Macro Names}, for a
16848 description of the new naming scheme. Below, if there is just the mapping
16849 from old names to new names for these macros, the reader is invited to
16850 refer to the definition of the new macro for the signature and the
16855 @code{AC_FUNC_ALLOCA}
16858 @defmac AC_ARG_ARRAY
16859 @acindex{ARG_ARRAY}
16860 removed because of limited usefulness
16865 This macro is obsolete; it does nothing.
16868 @defmac AC_C_LONG_DOUBLE
16869 @acindex{C_LONG_DOUBLE}
16870 @cvindex HAVE_LONG_DOUBLE
16871 If the C compiler supports a working @code{long double} type with more
16872 range or precision than the @code{double} type, define
16873 @code{HAVE_LONG_DOUBLE}.
16875 You should use @code{AC_TYPE_LONG_DOUBLE} or
16876 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16879 @defmac AC_CANONICAL_SYSTEM
16880 @acindex{CANONICAL_SYSTEM}
16881 Determine the system type and set output variables to the names of the
16882 canonical system types. @xref{Canonicalizing}, for details about the
16883 variables this macro sets.
16885 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16886 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16887 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
16891 @defmac AC_CHAR_UNSIGNED
16892 @acindex{CHAR_UNSIGNED}
16893 @code{AC_C_CHAR_UNSIGNED}
16896 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16897 @acindex{CHECK_TYPE}
16898 Autoconf, up to 2.13, used to provide this version of
16899 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
16900 it is a member of the @code{CHECK} clan, it does
16901 more than just checking. Secondly, missing types are defined
16902 using @code{#define}, not @code{typedef}, and this can lead to
16903 problems in the case of pointer types.
16905 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16906 @ref{Generic Types}, for the description of the current macro.
16908 If the type @var{type} is not defined, define it to be the C (or C++)
16909 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16911 This macro is equivalent to:
16914 AC_CHECK_TYPE([@var{type}], [],
16915 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16916 [Define to `@var{default}'
16917 if <sys/types.h> does not define.])])
16920 In order to keep backward compatibility, the two versions of
16921 @code{AC_CHECK_TYPE} are implemented, selected using these heuristics:
16925 If there are three or four arguments, the modern version is used.
16928 If the second argument appears to be a C or C++ type, then the
16929 obsolete version is used. This happens if the argument is a C or C++
16930 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16931 followed by one of @samp{[(* } and then by a string of zero or more
16932 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16935 If the second argument is spelled with the alphabet of valid C and C++
16936 types, the user is warned and the modern version is used.
16939 Otherwise, the modern version is used.
16943 You are encouraged either to use a valid builtin type, or to use the
16944 equivalent modern code (see above), or better yet, to use
16945 @code{AC_CHECK_TYPES} together with
16948 #ifndef HAVE_LOFF_T
16949 typedef loff_t off_t;
16953 @c end of AC_CHECK_TYPE
16955 @defmac AC_CHECKING (@var{feature-description})
16957 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16960 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16961 @acindex{COMPILE_CHECK}
16962 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16963 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16964 addition that it prints @samp{checking for @var{echo-text}} to the
16965 standard output first, if @var{echo-text} is non-empty. Use
16966 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16967 messages (@pxref{Printing Messages}).
16975 @defmac AC_CROSS_CHECK
16976 @acindex{CROSS_CHECK}
16977 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
16983 Check for the Cygwin environment in which case the shell variable
16984 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
16985 means to check the nature of the host is using
16986 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
16989 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
16991 *cygwin* ) CYGWIN=yes;;
16996 Beware that the variable @code{CYGWIN} has a special meaning when
16997 running Cygwin, and should not be changed. That's yet another reason
16998 not to use this macro.
17001 @defmac AC_DECL_SYS_SIGLIST
17002 @acindex{DECL_SYS_SIGLIST}
17003 @cvindex SYS_SIGLIST_DECLARED
17007 AC_CHECK_DECLS([sys_siglist], [], [],
17008 [#include <signal.h>
17009 /* NetBSD declares sys_siglist in unistd.h. */
17010 #ifdef HAVE_UNISTD_H
17011 # include <unistd.h>
17017 @defmac AC_DECL_YYTEXT
17018 @acindex{DECL_YYTEXT}
17019 Does nothing, now integrated in @code{AC_PROG_LEX}.
17022 @defmac AC_DIR_HEADER
17023 @acindex{DIR_HEADER}
17028 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
17029 but defines a different set of C preprocessor macros to indicate which
17030 header file is found:
17032 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
17033 @item Header @tab Old Symbol @tab New Symbol
17034 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
17035 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
17036 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
17037 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
17041 @defmac AC_DYNIX_SEQ
17042 @acindex{DYNIX_SEQ}
17043 If on DYNIX/ptx, add @option{-lseq} to output variable
17044 @code{LIBS}. This macro used to be defined as
17047 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
17051 now it is just @code{AC_FUNC_GETMNTENT}.
17057 Defined the output variable @code{EXEEXT} based on the output of the
17058 compiler, which is now done automatically. Typically set to empty
17059 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
17064 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
17065 and sets @code{EMXOS2}.
17070 @code{AC_MSG_ERROR}
17078 @defmac AC_FIND_XTRA
17079 @acindex{FIND_XTRA}
17080 @code{AC_PATH_XTRA}
17085 @code{m4_foreach_w}
17088 @defmac AC_FUNC_CHECK
17089 @acindex{FUNC_CHECK}
17090 @code{AC_CHECK_FUNC}
17093 @defmac AC_FUNC_SETVBUF_REVERSED
17094 @acindex{FUNC_SETVBUF_REVERSED}
17095 @cvindex SETVBUF_REVERSED
17096 @c @fuindex setvbuf
17097 @prindex @code{setvbuf}
17098 Do nothing. Formerly, this macro checked whether @code{setvbuf} takes
17099 the buffering type as its second argument and the buffer pointer as the
17100 third, instead of the other way around, and defined
17101 @code{SETVBUF_REVERSED}. However, the last systems to have the problem
17102 were those based on SVR2, which became obsolete in 1987, and the macro
17103 is no longer needed.
17106 @defmac AC_FUNC_WAIT3
17107 @acindex{FUNC_WAIT3}
17108 @cvindex HAVE_WAIT3
17109 If @code{wait3} is found and fills in the contents of its third argument
17110 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
17113 These days portable programs should use @code{waitpid}, not
17114 @code{wait3}, as @code{wait3} has been removed from Posix.
17117 @defmac AC_GCC_TRADITIONAL
17118 @acindex{GCC_TRADITIONAL}
17119 @code{AC_PROG_GCC_TRADITIONAL}
17122 @defmac AC_GETGROUPS_T
17123 @acindex{GETGROUPS_T}
17124 @code{AC_TYPE_GETGROUPS}
17127 @defmac AC_GETLOADAVG
17128 @acindex{GETLOADAVG}
17129 @code{AC_FUNC_GETLOADAVG}
17132 @defmac AC_HAVE_FUNCS
17133 @acindex{HAVE_FUNCS}
17134 @code{AC_CHECK_FUNCS}
17137 @defmac AC_HAVE_HEADERS
17138 @acindex{HAVE_HEADERS}
17139 @code{AC_CHECK_HEADERS}
17142 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
17143 @acindex{HAVE_LIBRARY}
17144 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
17145 @var{function} argument of @code{main}. In addition, @var{library} can
17146 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
17147 all of those cases, the compiler is passed @option{-lfoo}. However,
17148 @var{library} cannot be a shell variable; it must be a literal name.
17151 @defmac AC_HAVE_POUNDBANG
17152 @acindex{HAVE_POUNDBANG}
17153 @code{AC_SYS_INTERPRETER} (different calling convention)
17156 @defmac AC_HEADER_CHECK
17157 @acindex{HEADER_CHECK}
17158 @code{AC_CHECK_HEADER}
17161 @defmac AC_HEADER_EGREP
17162 @acindex{HEADER_EGREP}
17163 @code{AC_EGREP_HEADER}
17166 @defmac AC_HELP_STRING
17167 @acindex{HELP_STRING}
17168 @code{AS_HELP_STRING}
17171 @defmac AC_INIT (@var{unique-file-in-source-dir})
17173 Formerly @code{AC_INIT} used to have a single argument, and was
17178 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
17187 @defmac AC_INT_16_BITS
17188 @acindex{INT_16_BITS}
17189 @cvindex INT_16_BITS
17190 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
17191 Use @samp{AC_CHECK_SIZEOF(int)} instead.
17194 @defmac AC_IRIX_SUN
17196 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
17197 @code{LIBS}. If you were using it to get @code{getmntent}, use
17198 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
17199 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
17200 getpwnam)}. Up to Autoconf 2.13, it used to be
17203 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
17207 now it is defined as
17211 AC_CHECK_LIB([sun], [getpwnam])
17217 Same as @samp{AC_LANG([C])}.
17220 @defmac AC_LANG_CPLUSPLUS
17221 @acindex{LANG_CPLUSPLUS}
17222 Same as @samp{AC_LANG([C++])}.
17225 @defmac AC_LANG_FORTRAN77
17226 @acindex{LANG_FORTRAN77}
17227 Same as @samp{AC_LANG([Fortran 77])}.
17230 @defmac AC_LANG_RESTORE
17231 @acindex{LANG_RESTORE}
17232 Select the @var{language} that is saved on the top of the stack, as set
17233 by @code{AC_LANG_SAVE}, remove it from the stack, and call
17234 @code{AC_LANG(@var{language})}.
17237 @defmac AC_LANG_SAVE
17238 @acindex{LANG_SAVE}
17239 Remember the current language (as set by @code{AC_LANG}) on a stack.
17240 The current language does not change. @code{AC_LANG_PUSH} is preferred.
17243 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
17244 @acindex{LINK_FILES}
17245 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
17249 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
17257 AC_CONFIG_LINKS([host.h:config/$machine.h
17258 object.h:config/$obj_format.h])
17264 @code{AC_PROG_LN_S}
17267 @defmac AC_LONG_64_BITS
17268 @acindex{LONG_64_BITS}
17269 @cvindex LONG_64_BITS
17270 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
17271 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
17274 @defmac AC_LONG_DOUBLE
17275 @acindex{LONG_DOUBLE}
17276 If the C compiler supports a working @code{long double} type with more
17277 range or precision than the @code{double} type, define
17278 @code{HAVE_LONG_DOUBLE}.
17280 You should use @code{AC_TYPE_LONG_DOUBLE} or
17281 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
17284 @defmac AC_LONG_FILE_NAMES
17285 @acindex{LONG_FILE_NAMES}
17286 @code{AC_SYS_LONG_FILE_NAMES}
17289 @defmac AC_MAJOR_HEADER
17290 @acindex{MAJOR_HEADER}
17291 @code{AC_HEADER_MAJOR}
17294 @defmac AC_MEMORY_H
17296 @cvindex NEED_MEMORY_H
17297 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
17298 defined in @file{memory.h}. Today it is equivalent to
17299 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
17300 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
17306 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
17307 environment and sets @code{MINGW32}.
17310 @defmac AC_MINUS_C_MINUS_O
17311 @acindex{MINUS_C_MINUS_O}
17312 @code{AC_PROG_CC_C_O}
17317 @code{AC_FUNC_MMAP}
17322 @code{AC_TYPE_MODE_T}
17328 Defined the output variable @code{OBJEXT} based on the output of the
17329 compiler, after .c files have been excluded. Typically set to @samp{o}
17330 if Posix, @samp{obj} if a @acronym{DOS} variant.
17331 Now the compiler checking macros handle
17332 this automatically.
17335 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
17337 Make M4 print a message to the standard error output warning that
17338 @var{this-macro-name} is obsolete, and giving the file and line number
17339 where it was called. @var{this-macro-name} should be the name of the
17340 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
17341 it is printed at the end of the warning message; for example, it can be
17342 a suggestion for what to use instead of @var{this-macro-name}.
17347 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
17350 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
17351 services to the user.
17356 @code{AC_TYPE_OFF_T}
17359 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
17361 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
17362 interface is equivalent to:
17366 AC_CONFIG_FILES(@var{file}@dots{})
17367 AC_CONFIG_COMMANDS([default],
17368 @var{extra-cmds}, @var{init-cmds})
17374 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
17375 @acindex{OUTPUT_COMMANDS}
17376 Specify additional shell commands to run at the end of
17377 @file{config.status}, and shell commands to initialize any variables
17378 from @command{configure}. This macro may be called multiple times. It is
17379 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
17381 Here is an unrealistic example:
17385 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
17387 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
17391 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
17392 additional key, an important difference is that
17393 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
17394 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
17395 can safely be given macro calls as arguments:
17398 AC_CONFIG_COMMANDS(foo, [my_FOO()])
17402 Conversely, where one level of quoting was enough for literal strings
17403 with @code{AC_OUTPUT_COMMANDS}, you need two with
17404 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
17408 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
17409 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
17416 @code{AC_TYPE_PID_T}
17421 @code{AC_PREFIX_PROGRAM}
17424 @defmac AC_PROGRAMS_CHECK
17425 @acindex{PROGRAMS_CHECK}
17426 @code{AC_CHECK_PROGS}
17429 @defmac AC_PROGRAMS_PATH
17430 @acindex{PROGRAMS_PATH}
17431 @code{AC_PATH_PROGS}
17434 @defmac AC_PROGRAM_CHECK
17435 @acindex{PROGRAM_CHECK}
17436 @code{AC_CHECK_PROG}
17439 @defmac AC_PROGRAM_EGREP
17440 @acindex{PROGRAM_EGREP}
17441 @code{AC_EGREP_CPP}
17444 @defmac AC_PROGRAM_PATH
17445 @acindex{PROGRAM_PATH}
17446 @code{AC_PATH_PROG}
17449 @defmac AC_REMOTE_TAPE
17450 @acindex{REMOTE_TAPE}
17451 removed because of limited usefulness
17454 @defmac AC_RESTARTABLE_SYSCALLS
17455 @acindex{RESTARTABLE_SYSCALLS}
17456 @code{AC_SYS_RESTARTABLE_SYSCALLS}
17459 @defmac AC_RETSIGTYPE
17460 @acindex{RETSIGTYPE}
17461 @code{AC_TYPE_SIGNAL}
17466 removed because of limited usefulness
17469 @defmac AC_SCO_INTL
17472 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
17473 macro used to do this:
17476 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
17480 Now it just calls @code{AC_FUNC_STRFTIME} instead.
17483 @defmac AC_SETVBUF_REVERSED
17484 @acindex{SETVBUF_REVERSED}
17485 @code{AC_FUNC_SETVBUF_REVERSED}
17488 @defmac AC_SET_MAKE
17490 @code{AC_PROG_MAKE_SET}
17493 @defmac AC_SIZEOF_TYPE
17494 @acindex{SIZEOF_TYPE}
17495 @code{AC_CHECK_SIZEOF}
17500 @code{AC_TYPE_SIZE_T}
17503 @defmac AC_STAT_MACROS_BROKEN
17504 @acindex{STAT_MACROS_BROKEN}
17505 @code{AC_HEADER_STAT}
17508 @defmac AC_STDC_HEADERS
17509 @acindex{STDC_HEADERS}
17510 @code{AC_HEADER_STDC}
17515 @code{AC_FUNC_STRCOLL}
17518 @defmac AC_ST_BLKSIZE
17519 @acindex{ST_BLKSIZE}
17520 @code{AC_CHECK_MEMBERS}
17523 @defmac AC_ST_BLOCKS
17524 @acindex{ST_BLOCKS}
17525 @code{AC_STRUCT_ST_BLOCKS}
17530 @code{AC_CHECK_MEMBERS}
17533 @defmac AC_SYS_RESTARTABLE_SYSCALLS
17534 @acindex{SYS_RESTARTABLE_SYSCALLS}
17535 @cvindex HAVE_RESTARTABLE_SYSCALLS
17536 If the system automatically restarts a system call that is interrupted
17537 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
17538 not check whether system calls are restarted in general---it checks whether a
17539 signal handler installed with @code{signal} (but not @code{sigaction})
17540 causes system calls to be restarted. It does not check whether system calls
17541 can be restarted when interrupted by signals that have no handler.
17543 These days portable programs should use @code{sigaction} with
17544 @code{SA_RESTART} if they want restartable system calls. They should
17545 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
17546 system call is restartable is a dynamic issue, not a configuration-time
17550 @defmac AC_SYS_SIGLIST_DECLARED
17551 @acindex{SYS_SIGLIST_DECLARED}
17552 @code{AC_DECL_SYS_SIGLIST}
17555 @defmac AC_TEST_CPP
17557 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
17560 @defmac AC_TEST_PROGRAM
17561 @acindex{TEST_PROGRAM}
17562 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
17565 @defmac AC_TIMEZONE
17567 @code{AC_STRUCT_TIMEZONE}
17570 @defmac AC_TIME_WITH_SYS_TIME
17571 @acindex{TIME_WITH_SYS_TIME}
17572 @code{AC_HEADER_TIME}
17575 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17576 @acindex{TRY_COMPILE}
17581 [AC_LANG_PROGRAM([[@var{includes}]],
17582 [[@var{function-body}]])],
17583 [@var{action-if-true}],
17584 [@var{action-if-false}])
17588 @xref{Running the Compiler}.
17590 This macro double quotes both @var{includes} and @var{function-body}.
17592 For C and C++, @var{includes} is any @code{#include} statements needed
17593 by the code in @var{function-body} (@var{includes} is ignored if
17594 the currently selected language is Fortran or Fortran 77). The compiler
17595 and compilation flags are determined by the current language
17596 (@pxref{Language Choice}).
17599 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
17605 [AC_LANG_SOURCE([[@var{input}]])],
17606 [@var{action-if-true}],
17607 [@var{action-if-false}])
17611 @xref{Running the Preprocessor}.
17613 This macro double quotes the @var{input}.
17616 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
17622 [AC_LANG_PROGRAM([[@var{includes}]],
17623 [[@var{function-body}]])],
17624 [@var{action-if-true}],
17625 [@var{action-if-false}])
17629 @xref{Running the Compiler}.
17631 This macro double quotes both @var{includes} and @var{function-body}.
17633 Depending on the current language (@pxref{Language Choice}), create a
17634 test program to see whether a function whose body consists of
17635 @var{function-body} can be compiled and linked. If the file compiles
17636 and links successfully, run shell commands @var{action-if-found},
17637 otherwise run @var{action-if-not-found}.
17639 This macro double quotes both @var{includes} and @var{function-body}.
17641 For C and C++, @var{includes} is any @code{#include} statements needed
17642 by the code in @var{function-body} (@var{includes} is ignored if
17643 the currently selected language is Fortran or Fortran 77). The compiler
17644 and compilation flags are determined by the current language
17645 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17646 @code{LIBS} are used for linking.
17649 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17650 @acindex{TRY_LINK_FUNC}
17651 This macro is equivalent to
17652 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17653 [@var{action-if-found}], [@var{action-if-not-found}])}.
17656 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17662 [AC_LANG_SOURCE([[@var{program}]])],
17663 [@var{action-if-true}],
17664 [@var{action-if-false}],
17665 [@var{action-if-cross-compiling}])
17674 @code{AC_TYPE_UID_T}
17677 @defmac AC_UNISTD_H
17679 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17685 Define @code{USG} if the @acronym{BSD} string functions are defined in
17686 @file{strings.h}. You should no longer depend upon @code{USG}, but on
17687 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17690 @defmac AC_UTIME_NULL
17691 @acindex{UTIME_NULL}
17692 @code{AC_FUNC_UTIME_NULL}
17695 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17696 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17697 If the cache file is inconsistent with the current host, target and
17698 build system types, it used to execute @var{cmd} or print a default
17699 error message. This is now handled by default.
17702 @defmac AC_VERBOSE (@var{result-description})
17704 @code{AC_MSG_RESULT}.
17709 @code{AC_FUNC_VFORK}
17714 @code{AC_FUNC_VPRINTF}
17719 @code{AC_FUNC_WAIT3}
17727 @defmac AC_WORDS_BIGENDIAN
17728 @acindex{WORDS_BIGENDIAN}
17729 @code{AC_C_BIGENDIAN}
17732 @defmac AC_XENIX_DIR
17733 @acindex{XENIX_DIR}
17735 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17736 Xenix. Also, if @file{dirent.h} is being checked for, added
17737 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
17738 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17739 running @sc{xenix} on which you should not depend:
17742 AC_MSG_CHECKING([for Xenix])
17743 AC_EGREP_CPP([yes],
17744 [#if defined M_XENIX && !defined M_UNIX
17747 [AC_MSG_RESULT([yes]); XENIX=yes],
17748 [AC_MSG_RESULT([no]); XENIX=])
17752 @defmac AC_YYTEXT_POINTER
17753 @acindex{YYTEXT_POINTER}
17754 @code{AC_DECL_YYTEXT}
17758 @section Upgrading From Version 1
17759 @cindex Upgrading autoconf
17760 @cindex Autoconf upgrading
17762 Autoconf version 2 is mostly backward compatible with version 1.
17763 However, it introduces better ways to do some things, and doesn't
17764 support some of the ugly things in version 1. So, depending on how
17765 sophisticated your @file{configure.ac} files are, you might have to do
17766 some manual work in order to upgrade to version 2. This chapter points
17767 out some problems to watch for when upgrading. Also, perhaps your
17768 @command{configure} scripts could benefit from some of the new features in
17769 version 2; the changes are summarized in the file @file{NEWS} in the
17770 Autoconf distribution.
17773 * Changed File Names:: Files you might rename
17774 * Changed Makefiles:: New things to put in @file{Makefile.in}
17775 * Changed Macros:: Macro calls you might replace
17776 * Changed Results:: Changes in how to check test results
17777 * Changed Macro Writing:: Better ways to write your own macros
17780 @node Changed File Names
17781 @subsection Changed File Names
17783 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17784 in a particular package's source directory), you must rename it to
17785 @file{acsite.m4}. @xref{autoconf Invocation}.
17787 If you distribute @file{install.sh} with your package, rename it to
17788 @file{install-sh} so @code{make} builtin rules don't inadvertently
17789 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
17790 looks for the script under both names, but it is best to use the new name.
17792 If you were using @file{config.h.top}, @file{config.h.bot}, or
17793 @file{acconfig.h}, you still can, but you have less clutter if you
17794 use the @code{AH_} macros. @xref{Autoheader Macros}.
17796 @node Changed Makefiles
17797 @subsection Changed Makefiles
17799 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17800 your @file{Makefile.in} files, so they can take advantage of the values
17801 of those variables in the environment when @command{configure} is run.
17802 Doing this isn't necessary, but it's a convenience for users.
17804 Also add @samp{@@configure_input@@} in a comment to each input file for
17805 @code{AC_OUTPUT}, so that the output files contain a comment saying
17806 they were produced by @command{configure}. Automatically selecting the
17807 right comment syntax for all the kinds of files that people call
17808 @code{AC_OUTPUT} on became too much work.
17810 Add @file{config.log} and @file{config.cache} to the list of files you
17811 remove in @code{distclean} targets.
17813 If you have the following in @file{Makefile.in}:
17816 prefix = /usr/local
17817 exec_prefix = $(prefix)
17821 you must change it to:
17824 prefix = @@prefix@@
17825 exec_prefix = @@exec_prefix@@
17829 The old behavior of replacing those variables without @samp{@@}
17830 characters around them has been removed.
17832 @node Changed Macros
17833 @subsection Changed Macros
17835 Many of the macros were renamed in Autoconf version 2. You can still
17836 use the old names, but the new ones are clearer, and it's easier to find
17837 the documentation for them. @xref{Obsolete Macros}, for a table showing the
17838 new names for the old macros. Use the @command{autoupdate} program to
17839 convert your @file{configure.ac} to using the new macro names.
17840 @xref{autoupdate Invocation}.
17842 Some macros have been superseded by similar ones that do the job better,
17843 but are not call-compatible. If you get warnings about calling obsolete
17844 macros while running @command{autoconf}, you may safely ignore them, but
17845 your @command{configure} script generally works better if you follow
17846 the advice that is printed about what to replace the obsolete macros with. In
17847 particular, the mechanism for reporting the results of tests has
17848 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17849 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17850 looks better if you switch to @code{AC_MSG_CHECKING} and
17851 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
17852 in conjunction with cache variables. @xref{Caching Results}.
17856 @node Changed Results
17857 @subsection Changed Results
17859 If you were checking the results of previous tests by examining the
17860 shell variable @code{DEFS}, you need to switch to checking the values of
17861 the cache variables for those tests. @code{DEFS} no longer exists while
17862 @command{configure} is running; it is only created when generating output
17863 files. This difference from version 1 is because properly quoting the
17864 contents of that variable turned out to be too cumbersome and
17865 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
17868 For example, here is a @file{configure.ac} fragment written for Autoconf
17872 AC_HAVE_FUNCS(syslog)
17874 *-DHAVE_SYSLOG*) ;;
17875 *) # syslog is not in the default libraries. See if it's in some other.
17877 for lib in bsd socket inet; do
17878 AC_CHECKING(for syslog in -l$lib)
17879 LIBS="-l$lib $saved_LIBS"
17880 AC_HAVE_FUNCS(syslog)
17882 *-DHAVE_SYSLOG*) break ;;
17890 Here is a way to write it for version 2:
17893 AC_CHECK_FUNCS([syslog])
17894 if test $ac_cv_func_syslog = no; then
17895 # syslog is not in the default libraries. See if it's in some other.
17896 for lib in bsd socket inet; do
17897 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17898 LIBS="-l$lib $LIBS"; break])
17903 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17904 backslashes before quotes, you need to remove them. It now works
17905 predictably, and does not treat quotes (except back quotes) specially.
17906 @xref{Setting Output Variables}.
17908 All of the Boolean shell variables set by Autoconf macros now use
17909 @samp{yes} for the true value. Most of them use @samp{no} for false,
17910 though for backward compatibility some use the empty string instead. If
17911 you were relying on a shell variable being set to something like 1 or
17912 @samp{t} for true, you need to change your tests.
17914 @node Changed Macro Writing
17915 @subsection Changed Macro Writing
17917 When defining your own macros, you should now use @code{AC_DEFUN}
17918 instead of @code{define}. @code{AC_DEFUN} automatically calls
17919 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17920 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17921 messages on the screen. There's no actual harm in continuing to use the
17922 older way, but it's less convenient and attractive. @xref{Macro
17925 You probably looked at the macros that came with Autoconf as a guide for
17926 how to do things. It would be a good idea to take a look at the new
17927 versions of them, as the style is somewhat improved and they take
17928 advantage of some new features.
17930 If you were doing tricky things with undocumented Autoconf internals
17931 (macros, variables, diversions), check whether you need to change
17932 anything to account for changes that have been made. Perhaps you can
17933 even use an officially supported technique in version 2 instead of
17934 kludging. Or perhaps not.
17936 To speed up your locally written feature tests, add caching to them.
17937 See whether any of your tests are of general enough usefulness to
17938 encapsulate them into macros that you can share.
17941 @node Autoconf 2.13
17942 @section Upgrading From Version 2.13
17943 @cindex Upgrading autoconf
17944 @cindex Autoconf upgrading
17946 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17947 suits this section@enddots{}
17950 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17951 However, it introduces better ways to do some things, and doesn't
17952 support some of the ugly things in version 2.13. So, depending on how
17953 sophisticated your @file{configure.ac} files are, you might have to do
17954 some manual work in order to upgrade to version 2.50. This chapter
17955 points out some problems to watch for when upgrading. Also, perhaps
17956 your @command{configure} scripts could benefit from some of the new
17957 features in version 2.50; the changes are summarized in the file
17958 @file{NEWS} in the Autoconf distribution.
17962 * Changed Quotation:: Broken code which used to work
17963 * New Macros:: Interaction with foreign macros
17964 * Hosts and Cross-Compilation:: Bugward compatibility kludges
17965 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
17966 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
17969 @node Changed Quotation
17970 @subsection Changed Quotation
17972 The most important changes are invisible to you: the implementation of
17973 most macros have completely changed. This allowed more factorization of
17974 the code, better error messages, a higher uniformity of the user's
17975 interface etc. Unfortunately, as a side effect, some construct which
17976 used to (miraculously) work might break starting with Autoconf 2.50.
17977 The most common culprit is bad quotation.
17979 For instance, in the following example, the message is not properly
17984 AC_CHECK_HEADERS(foo.h, ,
17985 AC_MSG_ERROR(cannot find foo.h, bailing out))
17990 Autoconf 2.13 simply ignores it:
17993 $ @kbd{autoconf-2.13; ./configure --silent}
17994 creating cache ./config.cache
17995 configure: error: cannot find foo.h
18000 while Autoconf 2.50 produces a broken @file{configure}:
18003 $ @kbd{autoconf-2.50; ./configure --silent}
18004 configure: error: cannot find foo.h
18005 ./configure: exit: bad non-numeric arg `bailing'
18006 ./configure: exit: bad non-numeric arg `bailing'
18010 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
18014 AC_INIT([Example], [1.0], [bug-example@@example.org])
18015 AC_CHECK_HEADERS([foo.h], [],
18016 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
18020 Many many (and many more) Autoconf macros were lacking proper quotation,
18021 including no less than@dots{} @code{AC_DEFUN} itself!
18024 $ @kbd{cat configure.in}
18025 AC_DEFUN([AC_PROG_INSTALL],
18026 [# My own much better version
18031 $ @kbd{autoconf-2.13}
18032 autoconf: Undefined macros:
18033 ***BUG in Autoconf--please report*** AC_FD_MSG
18034 ***BUG in Autoconf--please report*** AC_EPI
18035 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
18036 configure.in:5:AC_PROG_INSTALL
18037 $ @kbd{autoconf-2.50}
18043 @subsection New Macros
18045 @cindex undefined macro
18046 @cindex @code{_m4_divert_diversion}
18048 While Autoconf was relatively dormant in the late 1990s, Automake
18049 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
18050 in 2001, Autoconf provided
18051 versions of these macros, integrated in the @code{AC_} namespace,
18052 instead of @code{AM_}. But in order to ease the upgrading via
18053 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
18055 Unfortunately older versions of Automake (e.g., Automake 1.4)
18056 did not quote the names of these macros.
18057 Therefore, when @command{m4} finds something like
18058 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
18059 @code{AM_TYPE_PTRDIFF_T} is
18060 expanded, replaced with its Autoconf definition.
18062 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
18063 complains, in its own words:
18066 $ @kbd{cat configure.ac}
18067 AC_INIT([Example], [1.0], [bug-example@@example.org])
18069 $ @kbd{aclocal-1.4}
18071 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
18072 aclocal.m4:17: the top level
18073 autom4te: m4 failed with exit status: 1
18077 Modern versions of Automake no longer define most of these
18078 macros, and properly quote the names of the remaining macros.
18079 If you must use an old Automake, do not depend upon macros from Automake
18080 as it is simply not its job
18081 to provide macros (but the one it requires itself):
18084 $ @kbd{cat configure.ac}
18085 AC_INIT([Example], [1.0], [bug-example@@example.org])
18087 $ @kbd{rm aclocal.m4}
18089 autoupdate: `configure.ac' is updated
18090 $ @kbd{cat configure.ac}
18091 AC_INIT([Example], [1.0], [bug-example@@example.org])
18092 AC_CHECK_TYPES([ptrdiff_t])
18093 $ @kbd{aclocal-1.4}
18099 @node Hosts and Cross-Compilation
18100 @subsection Hosts and Cross-Compilation
18101 @cindex Cross compilation
18103 Based on the experience of compiler writers, and after long public
18104 debates, many aspects of the cross-compilation chain have changed:
18108 the relationship between the build, host, and target architecture types,
18111 the command line interface for specifying them to @command{configure},
18114 the variables defined in @command{configure},
18117 the enabling of cross-compilation mode.
18122 The relationship between build, host, and target have been cleaned up:
18123 the chain of default is now simply: target defaults to host, host to
18124 build, and build to the result of @command{config.guess}. Nevertheless,
18125 in order to ease the transition from 2.13 to 2.50, the following
18126 transition scheme is implemented. @emph{Do not rely on it}, as it will
18127 be completely disabled in a couple of releases (we cannot keep it, as it
18128 proves to cause more problems than it cures).
18130 They all default to the result of running @command{config.guess}, unless
18131 you specify either @option{--build} or @option{--host}. In this case,
18132 the default becomes the system type you specified. If you specify both,
18133 and they're different, @command{configure} enters cross compilation
18134 mode, so it doesn't run any tests that require execution.
18136 Hint: if you mean to override the result of @command{config.guess},
18137 prefer @option{--build} over @option{--host}. In the future,
18138 @option{--host} will not override the name of the build system type.
18139 Whenever you specify @option{--host}, be sure to specify @option{--build}
18144 For backward compatibility, @command{configure} accepts a system
18145 type as an option by itself. Such an option overrides the
18146 defaults for build, host, and target system types. The following
18147 configure statement configures a cross toolchain that runs on
18148 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
18149 which is also the build platform.
18152 ./configure --host=alpha-netbsd sparc-gnu
18157 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
18158 and @code{target} had a different semantics before and after the
18159 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
18160 @option{--build} is strictly copied into @code{build_alias}, and is left
18161 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
18162 set to the canonicalized build type. To ease the transition, before,
18163 its contents is the same as that of @code{build_alias}. Do @emph{not}
18164 rely on this broken feature.
18166 For consistency with the backward compatibility scheme exposed above,
18167 when @option{--host} is specified but @option{--build} isn't, the build
18168 system is assumed to be the same as @option{--host}, and
18169 @samp{build_alias} is set to that value. Eventually, this
18170 historically incorrect behavior will go away.
18174 The former scheme to enable cross-compilation proved to cause more harm
18175 than good, in particular, it used to be triggered too easily, leaving
18176 regular end users puzzled in front of cryptic error messages.
18177 @command{configure} could even enter cross-compilation mode only
18178 because the compiler was not functional. This is mainly because
18179 @command{configure} used to try to detect cross-compilation, instead of
18180 waiting for an explicit flag from the user.
18182 Now, @command{configure} enters cross-compilation mode if and only if
18183 @option{--host} is passed.
18185 That's the short documentation. To ease the transition between 2.13 and
18186 its successors, a more complicated scheme is implemented. @emph{Do not
18187 rely on the following}, as it will be removed in the near future.
18189 If you specify @option{--host}, but not @option{--build}, when
18190 @command{configure} performs the first compiler test it tries to run
18191 an executable produced by the compiler. If the execution fails, it
18192 enters cross-compilation mode. This is fragile. Moreover, by the time
18193 the compiler test is performed, it may be too late to modify the
18194 build-system type: other tests may have already been performed.
18195 Therefore, whenever you specify @option{--host}, be sure to specify
18196 @option{--build} too.
18199 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
18203 enters cross-compilation mode. The former interface, which
18204 consisted in setting the compiler to a cross-compiler without informing
18205 @command{configure} is obsolete. For instance, @command{configure}
18206 fails if it can't run the code generated by the specified compiler if you
18207 configure as follows:
18210 ./configure CC=m68k-coff-gcc
18214 @node AC_LIBOBJ vs LIBOBJS
18215 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
18217 Up to Autoconf 2.13, the replacement of functions was triggered via the
18218 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
18219 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
18220 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
18222 This change is mandated by the unification of the @acronym{GNU} Build System
18223 components. In particular, the various fragile techniques used to parse
18224 a @file{configure.ac} are all replaced with the use of traces. As a
18225 consequence, any action must be traceable, which obsoletes critical
18226 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
18227 and it can even be handled gracefully (read, ``without your having to
18228 change something'').
18230 There were two typical uses of @code{LIBOBJS}: asking for a replacement
18231 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
18235 As for function replacement, the fix is immediate: use
18236 @code{AC_LIBOBJ}. For instance:
18239 LIBOBJS="$LIBOBJS fnmatch.o"
18240 LIBOBJS="$LIBOBJS malloc.$ac_objext"
18244 should be replaced with:
18247 AC_LIBOBJ([fnmatch])
18248 AC_LIBOBJ([malloc])
18254 When used with Automake 1.10 or newer, a suitable value for
18255 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
18256 can be referenced from any @file{Makefile.am}. Even without Automake,
18257 arranging for @code{LIBOBJDIR} to be set correctly enables
18258 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
18259 The @code{LIBOBJDIR} feature is experimental.
18262 @node AC_FOO_IFELSE vs AC_TRY_FOO
18263 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
18265 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
18266 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
18267 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
18268 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
18269 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
18270 @code{AC_TRY_RUN}. The motivations where:
18273 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
18274 quoting their arguments;
18277 the combinatoric explosion is solved by decomposing on the one hand the
18278 generation of sources, and on the other hand executing the program;
18281 this scheme helps supporting more languages than plain C and C++.
18284 In addition to the change of syntax, the philosophy has changed too:
18285 while emphasis was put on speed at the expense of accuracy, today's
18286 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
18290 As a perfect example of what is @emph{not} to be done, here is how to
18291 find out whether a header file contains a particular declaration, such
18292 as a typedef, a structure, a structure member, or a function. Use
18293 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
18294 header file; on some systems the symbol might be defined in another
18295 header file that the file you are checking includes.
18297 As a (bad) example, here is how you should not check for C preprocessor
18298 symbols, either defined by header files or predefined by the C
18299 preprocessor: using @code{AC_EGREP_CPP}:
18307 ], is_aix=yes, is_aix=no)
18311 The above example, properly written would (i) use
18312 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
18316 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
18318 error: This isn't AIX!
18327 @c ============================= Generating Test Suites with Autotest
18329 @node Using Autotest
18330 @chapter Generating Test Suites with Autotest
18335 @strong{N.B.: This section describes an experimental feature which will
18336 be part of Autoconf in a forthcoming release. Although we believe
18337 Autotest is stabilizing, this documentation describes an interface which
18338 might change in the future: do not depend upon Autotest without
18339 subscribing to the Autoconf mailing lists.}
18342 It is paradoxical that portable projects depend on nonportable tools
18343 to run their test suite. Autoconf by itself is the paragon of this
18344 problem: although it aims at perfectly portability, up to 2.13 its
18345 test suite was using Deja@acronym{GNU}, a rich and complex testing
18346 framework, but which is far from being standard on Posix systems.
18347 Worse yet, it was likely to be missing on the most fragile platforms,
18348 the very platforms that are most likely to torture Autoconf and
18349 exhibit deficiencies.
18351 To circumvent this problem, many package maintainers have developed their
18352 own testing framework, based on simple shell scripts whose sole outputs
18353 are exit status values describing whether the test succeeded. Most of
18354 these tests share common patterns, and this can result in lots of
18355 duplicated code and tedious maintenance.
18357 Following exactly the same reasoning that yielded to the inception of
18358 Autoconf, Autotest provides a test suite generation framework, based on
18359 M4 macros building a portable shell script. The suite itself is
18360 equipped with automatic logging and tracing facilities which greatly
18361 diminish the interaction with bug reporters, and simple timing reports.
18363 Autoconf itself has been using Autotest for years, and we do attest that
18364 it has considerably improved the strength of the test suite and the
18365 quality of bug reports. Other projects are known to use some generation
18366 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
18367 them with different needs, and this usage has validated Autotest as a general
18370 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
18371 interactive tool testing, which is probably its main limitation.
18374 * Using an Autotest Test Suite:: Autotest and the user
18375 * Writing Testsuites:: Autotest macros
18376 * testsuite Invocation:: Running @command{testsuite} scripts
18377 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
18380 @node Using an Autotest Test Suite
18381 @section Using an Autotest Test Suite
18384 * testsuite Scripts:: The concepts of Autotest
18385 * Autotest Logs:: Their contents
18388 @node testsuite Scripts
18389 @subsection @command{testsuite} Scripts
18391 @cindex @command{testsuite}
18393 Generating testing or validation suites using Autotest is rather easy.
18394 The whole validation suite is held in a file to be processed through
18395 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
18396 produce a stand-alone Bourne shell script which then gets distributed.
18397 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
18398 the installer's end.
18401 Each test of the validation suite should be part of some test group. A
18402 @dfn{test group} is a sequence of interwoven tests that ought to be
18403 executed together, usually because one test in the group creates data
18404 files than a later test in the same group needs to read. Complex test
18405 groups make later debugging more tedious. It is much better to
18406 keep only a few tests per test group. Ideally there is only one test
18409 For all but the simplest packages, some file such as @file{testsuite.at}
18410 does not fully hold all test sources, as these are often easier to
18411 maintain in separate files. Each of these separate files holds a single
18412 test group, or a sequence of test groups all addressing some common
18413 functionality in the package. In such cases, @file{testsuite.at}
18414 merely initializes the validation suite, and sometimes does elementary
18415 health checking, before listing include statements for all other test
18416 files. The special file @file{package.m4}, containing the
18417 identification of the package, is automatically included if found.
18419 A convenient alternative consists in moving all the global issues
18420 (local Autotest macros, elementary health checking, and @code{AT_INIT}
18421 invocation) into the file @code{local.at}, and making
18422 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
18423 suites. In such case, generating the whole test suite or pieces of it
18424 is only a matter of choosing the @command{autom4te} command line
18427 The validation scripts that Autotest produces are by convention called
18428 @command{testsuite}. When run, @command{testsuite} executes each test
18429 group in turn, producing only one summary line per test to say if that
18430 particular test succeeded or failed. At end of all tests, summarizing
18431 counters get printed. One debugging directory is left for each test
18432 group which failed, if any: such directories are named
18433 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
18434 the test group, and they include:
18437 @item a debugging script named @file{run} which reruns the test in
18438 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
18439 of debugging scripts has the purpose of easing the chase for bugs.
18441 @item all the files created with @code{AT_DATA}
18443 @item a log of the run, named @file{testsuite.log}
18446 In the ideal situation, none of the tests fail, and consequently no
18447 debugging directory is left behind for validation.
18449 It often happens in practice that individual tests in the validation
18450 suite need to get information coming out of the configuration process.
18451 Some of this information, common for all validation suites, is provided
18452 through the file @file{atconfig}, automatically created by
18453 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
18454 testing environment specifically needs, you might prepare an optional
18455 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
18456 The configuration process produces @file{atconfig} and @file{atlocal}
18457 out of these two input files, and these two produced files are
18458 automatically read by the @file{testsuite} script.
18460 Here is a diagram showing the relationship between files.
18463 Files used in preparing a software package for distribution:
18468 subfile-1.at ->. [local.at] ---->+
18470 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
18476 Files used in configuring a software package:
18481 [atlocal.in] --> config.status* --<
18487 Files created during the test suite execution:
18490 atconfig -->. .--> testsuite.log
18494 [atlocal] ->' `--> [testsuite.dir]
18498 @node Autotest Logs
18499 @subsection Autotest Logs
18501 When run, the test suite creates a log file named after itself, e.g., a
18502 test suite named @command{testsuite} creates @file{testsuite.log}. It
18503 contains a lot of information, usually more than maintainers actually
18504 need, but therefore most of the time it contains all that is needed:
18507 @item command line arguments
18508 @c akim s/to consist in/to consist of/
18509 A bad but unfortunately widespread habit consists of
18510 setting environment variables before the command, such as in
18511 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
18512 know this change, hence (i) it cannot report it to you, and (ii)
18513 it cannot preserve the value of @code{CC} for subsequent runs.
18514 Autoconf faced exactly the same problem, and solved it by asking
18515 users to pass the variable definitions as command line arguments.
18516 Autotest requires this rule, too, but has no means to enforce it; the log
18517 then contains a trace of the variables that were changed by the user.
18519 @item @file{ChangeLog} excerpts
18520 The topmost lines of all the @file{ChangeLog} files found in the source
18521 hierarchy. This is especially useful when bugs are reported against
18522 development versions of the package, since the version string does not
18523 provide sufficient information to know the exact state of the sources
18524 the user compiled. Of course, this relies on the use of a
18527 @item build machine
18528 Running a test suite in a cross-compile environment is not an easy task,
18529 since it would mean having the test suite run on a machine @var{build},
18530 while running programs on a machine @var{host}. It is much simpler to
18531 run both the test suite and the programs on @var{host}, but then, from
18532 the point of view of the test suite, there remains a single environment,
18533 @var{host} = @var{build}. The log contains relevant information on the
18534 state of the build machine, including some important environment
18536 @c FIXME: How about having an M4sh macro to say `hey, log the value
18537 @c of `@dots{}'? This would help both Autoconf and Autotest.
18539 @item tested programs
18540 The absolute file name and answers to @option{--version} of the tested
18541 programs (see @ref{Writing Testsuites}, @code{AT_TESTED}).
18543 @item configuration log
18544 The contents of @file{config.log}, as created by @command{configure},
18545 are appended. It contains the configuration flags and a detailed report
18546 on the configuration itself.
18550 @node Writing Testsuites
18551 @section Writing @file{testsuite.at}
18553 The @file{testsuite.at} is a Bourne shell script making use of special
18554 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
18555 its beginning followed by one call to @code{m4_include} per source file
18556 for tests. Each such included file, or the remainder of
18557 @file{testsuite.at} if include files are not used, contain a sequence of
18558 test groups. Each test group begins with a call to @code{AT_SETUP},
18559 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
18560 and then completes with a call to @code{AT_CLEANUP}.
18562 @defmac AT_INIT (@ovar{name})
18564 @c FIXME: Not clear, plus duplication of the information.
18565 Initialize Autotest. Giving a @var{name} to the test suite is
18566 encouraged if your package includes several test suites. In any case,
18567 the test suite always displays the package name and version. It also
18568 inherits the package bug report address.
18571 @defmac AT_COPYRIGHT (@var{copyright-notice})
18572 @atindex{COPYRIGHT}
18573 @cindex Copyright Notice
18574 State that, in addition to the Free Software Foundation's copyright on
18575 the Autotest macros, parts of your test suite are covered by
18576 @var{copyright-notice}.
18578 The @var{copyright-notice} shows up in both the head of
18579 @command{testsuite} and in @samp{testsuite --version}.
18582 @defmac AT_TESTED (@var{executables})
18584 Log the file name and answer to @option{--version} of each program in
18585 space-separated list @var{executables}. Several invocations register
18586 new executables, in other words, don't fear registering one program
18590 Autotest test suites rely on @env{PATH} to find the tested program.
18591 This avoids the need to generate absolute names of the various tools, and
18592 makes it possible to test installed programs. Therefore, knowing which
18593 programs are being exercised is crucial to understanding problems in
18594 the test suite itself, or its occasional misuses. It is a good idea to
18595 also subscribe foreign programs you depend upon, to avoid incompatible
18600 @defmac AT_SETUP (@var{test-group-name})
18602 This macro starts a group of related tests, all to be executed in the
18603 same subshell. It accepts a single argument, which holds a few words
18604 (no more than about 30 or 40 characters) quickly describing the purpose
18605 of the test group being started.
18608 @defmac AT_KEYWORDS (@var{keywords})
18610 Associate the space-separated list of @var{keywords} to the enclosing
18611 test group. This makes it possible to run ``slices'' of the test suite.
18612 For instance, if some of your test groups exercise some @samp{foo}
18613 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
18614 @samp{./testsuite -k foo} to run exclusively these test groups. The
18615 @var{title} of the test group is automatically recorded to
18616 @code{AT_KEYWORDS}.
18618 Several invocations within a test group accumulate new keywords. In
18619 other words, don't fear registering the same keyword several times in a
18623 @defmac AT_CAPTURE_FILE (@var{file})
18624 @atindex{CAPTURE_FILE}
18625 If the current test group fails, log the contents of @var{file}.
18626 Several identical calls within one test group have no additional effect.
18629 @defmac AT_XFAIL_IF (@var{shell-condition})
18631 Determine whether the test is expected to fail because it is a known
18632 bug (for unsupported features, you should skip the test).
18633 @var{shell-condition} is a shell expression such as a @code{test}
18634 command; you can instantiate this macro many times from within the
18635 same test group, and one of the conditions is enough to turn
18636 the test into an expected failure.
18641 End the current test group.
18646 @defmac AT_DATA (@var{file}, @var{contents})
18648 Initialize an input data @var{file} with given @var{contents}. Of
18649 course, the @var{contents} have to be properly quoted between square
18650 brackets to protect against included commas or spurious M4
18651 expansion. The contents ought to end with an end of line.
18654 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18656 Execute a test by performing given shell @var{commands}. These commands
18657 should normally exit with @var{status}, while producing expected
18658 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
18659 status 77, then the whole test group is skipped. Otherwise, if this test
18660 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18661 commands @var{run-if-pass}.
18663 The @var{commands} @emph{must not} redirect the standard output, nor the
18666 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18667 the corresponding value is not checked.
18669 The special value @samp{expout} for @var{stdout} means the expected
18670 output of the @var{commands} is the content of the file @file{expout}.
18671 If @var{stdout} is @samp{stdout}, then the standard output of the
18672 @var{commands} is available for further tests in the file @file{stdout}.
18673 Similarly for @var{stderr} with @samp{experr} and @samp{stderr}.
18677 @node testsuite Invocation
18678 @section Running @command{testsuite} Scripts
18679 @cindex @command{testsuite}
18681 Autotest test suites support the following arguments:
18686 Display the list of options and exit successfully.
18690 Display the version of the test suite and exit successfully.
18694 Remove all the files the test suite might have created and exit. Meant
18695 for @code{clean} Make targets.
18699 List all the tests (or only the selection), including their possible
18705 By default all tests are performed (or described with
18706 @option{--list}) in the default environment first silently, then
18707 verbosely, but the environment, set of tests, and verbosity level can be
18711 @item @var{variable}=@var{value}
18712 Set the environment @var{variable} to @var{value}. Use this rather
18713 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18714 different environment.
18716 @cindex @code{AUTOTEST_PATH}
18717 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18718 to @env{PATH}. Relative directory names (not starting with
18719 @samp{/}) are considered to be relative to the top level of the
18720 package being built. All directories are made absolute, first
18721 starting from the top level @emph{build} tree, then from the
18722 @emph{source} tree. For instance @samp{./testsuite
18723 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18724 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18725 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18729 @itemx @var{number}-@var{number}
18730 @itemx @var{number}-
18731 @itemx -@var{number}
18732 Add the corresponding test groups, with obvious semantics, to the
18735 @item --keywords=@var{keywords}
18736 @itemx -k @var{keywords}
18737 Add to the selection the test groups with title or keywords (arguments
18738 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18739 of the comma separated list @var{keywords}, case-insensitively. Use
18740 @samp{!} immediately before the keyword to invert the selection for this
18741 keyword. By default, the keywords match whole words; enclose them in
18742 @samp{.*} to also match parts of words.
18744 For example, running
18747 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18751 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18752 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA},
18756 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18760 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18761 containing @samp{FUNC}.
18765 If any test fails, immediately abort testing. It implies
18766 @option{--debug}: post test group clean up, and top-level logging
18767 are inhibited. This option is meant for the full test
18768 suite, it is not really useful for generated debugging scripts.
18772 Force more verbosity in the detailed output of what is being done. This
18773 is the default for debugging scripts.
18777 Do not remove the files after a test group was performed ---but they are
18778 still removed @emph{before}, therefore using this option is sane when
18779 running several test groups. Create debugging scripts. Do not
18780 overwrite the top-level
18781 log (in order to preserve supposedly existing full log file). This is
18782 the default for debugging scripts, but it can also be useful to debug
18783 the testsuite itself.
18787 Trigger shell tracing of the test groups.
18791 @node Making testsuite Scripts
18792 @section Making @command{testsuite} Scripts
18794 For putting Autotest into movement, you need some configuration and
18795 makefile machinery. We recommend, at least if your package uses deep or
18796 shallow hierarchies, that you use @file{tests/} as the name of the
18797 directory holding all your tests and their makefile. Here is a
18798 check list of things to do.
18803 @cindex @file{package.m4}
18804 Make sure to create the file @file{package.m4}, which defines the
18805 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
18806 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18807 address to which bug reports should be sent. For sake of completeness,
18808 we suggest that you also define @code{AT_PACKAGE_NAME},
18809 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18810 @xref{Initializing configure}, for a description of these variables. We
18811 suggest the following makefile excerpt:
18814 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18816 echo '# Signature of the current package.'; \
18817 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
18818 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
18819 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
18820 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
18821 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18822 @} >'$(srcdir)/package.m4'
18826 Be sure to distribute @file{package.m4} and to put it into the source
18827 hierarchy: the test suite ought to be shipped!
18830 Invoke @code{AC_CONFIG_TESTDIR}.
18832 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18833 @acindex{CONFIG_TESTDIR}
18834 An Autotest test suite is to be configured in @var{directory}. This
18835 macro requires the instantiation of @file{@var{directory}/atconfig} from
18836 @file{@var{directory}/atconfig.in}, and sets the default
18837 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18841 Still within @file{configure.ac}, as appropriate, ensure that some
18842 @code{AC_CONFIG_FILES} command includes substitution for
18843 @file{tests/atlocal}.
18846 The @file{tests/Makefile.in} should be modified so the validation in
18847 your package is triggered by @samp{make check}. An example is provided
18851 With Automake, here is a minimal example about how to link @samp{make
18852 check} with a validation suite.
18855 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18856 TESTSUITE = $(srcdir)/testsuite
18858 check-local: atconfig atlocal $(TESTSUITE)
18859 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18861 installcheck-local: atconfig atlocal $(TESTSUITE)
18862 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18866 test ! -f '$(TESTSUITE)' || \
18867 $(SHELL) '$(TESTSUITE)' --clean
18869 AUTOTEST = $(AUTOM4TE) --language=autotest
18870 $(TESTSUITE): $(srcdir)/testsuite.at
18871 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18875 You might want to list explicitly the dependencies, i.e., the list of
18876 the files @file{testsuite.at} includes.
18878 With strict Autoconf, you might need to add lines inspired from the
18884 atconfig: $(top_builddir)/config.status
18885 cd $(top_builddir) && \
18886 $(SHELL) ./config.status $(subdir)/$@@
18888 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18889 cd $(top_builddir) && \
18890 $(SHELL) ./config.status $(subdir)/$@@
18894 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18897 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18898 within your makefile, you can fine-tune test suite execution with this variable,
18902 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18907 @c =============================== Frequent Autoconf Questions, with answers
18910 @chapter Frequent Autoconf Questions, with answers
18912 Several questions about Autoconf come up occasionally. Here some of them
18916 * Distributing:: Distributing @command{configure} scripts
18917 * Why GNU M4:: Why not use the standard M4?
18918 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
18919 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
18920 * Defining Directories:: Passing @code{datadir} to program
18921 * Autom4te Cache:: What is it? Can I remove it?
18922 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
18926 @section Distributing @command{configure} Scripts
18930 What are the restrictions on distributing @command{configure}
18931 scripts that Autoconf generates? How does that affect my
18932 programs that use them?
18935 There are no restrictions on how the configuration scripts that Autoconf
18936 produces may be distributed or used. In Autoconf version 1, they were
18937 covered by the @acronym{GNU} General Public License. We still encourage
18938 software authors to distribute their work under terms like those of the
18939 @acronym{GPL}, but doing so is not required to use Autoconf.
18941 Of the other files that might be used with @command{configure},
18942 @file{config.h.in} is under whatever copyright you use for your
18943 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
18944 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18945 @command{configure} script, which permits you to distribute them under the
18946 same terms as the rest of your package. @file{install-sh} is from the X
18947 Consortium and is not copyrighted.
18950 @section Why Require @acronym{GNU} M4?
18953 Why does Autoconf require @acronym{GNU} M4?
18956 Many M4 implementations have hard-coded limitations on the size and
18957 number of macros that Autoconf exceeds. They also lack several
18958 builtin macros that it would be difficult to get along without in a
18959 sophisticated application like Autoconf, including:
18969 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
18971 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18972 M4 is simple to configure and install, it seems reasonable to require
18973 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
18974 other free software already have most of the @acronym{GNU} utilities
18975 installed, since they prefer them.
18977 @node Bootstrapping
18978 @section How Can I Bootstrap?
18982 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
18983 @command{configure} script, how do I bootstrap? It seems like a chicken
18987 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
18988 @command{configure} script produced by Autoconf, Autoconf is not required
18989 in order to run the script and install @acronym{GNU} M4. Autoconf is only
18990 required if you want to change the M4 @command{configure} script, which few
18991 people have to do (mainly its maintainer).
18993 @node Why Not Imake
18994 @section Why Not Imake?
18998 Why not use Imake instead of @command{configure} scripts?
19001 Several people have written addressing this question, so I include
19002 adaptations of their explanations here.
19004 The following answer is based on one written by Richard Pixley:
19007 Autoconf generated scripts frequently work on machines that it has
19008 never been set up to handle before. That is, it does a good job of
19009 inferring a configuration for a new system. Imake cannot do this.
19011 Imake uses a common database of host specific data. For X11, this makes
19012 sense because the distribution is made as a collection of tools, by one
19013 central authority who has control over the database.
19015 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
19016 maintainer; these maintainers are scattered across the world. Using a
19017 common database would be a maintenance nightmare. Autoconf may appear
19018 to be this kind of database, but in fact it is not. Instead of listing
19019 host dependencies, it lists program requirements.
19021 If you view the @acronym{GNU} suite as a collection of native tools, then the
19022 problems are similar. But the @acronym{GNU} development tools can be
19023 configured as cross tools in almost any host+target permutation. All of
19024 these configurations can be installed concurrently. They can even be
19025 configured to share host independent files across hosts. Imake doesn't
19026 address these issues.
19028 Imake templates are a form of standardization. The @acronym{GNU} coding
19029 standards address the same issues without necessarily imposing the same
19034 Here is some further explanation, written by Per Bothner:
19037 One of the advantages of Imake is that it easy to generate large
19038 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
19039 However, @code{cpp} is not programmable: it has limited conditional
19040 facilities, and no looping. And @code{cpp} cannot inspect its
19043 All of these problems are solved by using @code{sh} instead of
19044 @code{cpp}. The shell is fully programmable, has macro substitution,
19045 can execute (or source) other shell scripts, and can inspect its
19050 Paul Eggert elaborates more:
19053 With Autoconf, installers need not assume that Imake itself is already
19054 installed and working well. This may not seem like much of an advantage
19055 to people who are accustomed to Imake. But on many hosts Imake is not
19056 installed or the default installation is not working well, and requiring
19057 Imake to install a package hinders the acceptance of that package on
19058 those hosts. For example, the Imake template and configuration files
19059 might not be installed properly on a host, or the Imake build procedure
19060 might wrongly assume that all source files are in one big directory
19061 tree, or the Imake configuration might assume one compiler whereas the
19062 package or the installer needs to use another, or there might be a
19063 version mismatch between the Imake expected by the package and the Imake
19064 supported by the host. These problems are much rarer with Autoconf,
19065 where each package comes with its own independent configuration
19068 Also, Imake often suffers from unexpected interactions between
19069 @command{make} and the installer's C preprocessor. The fundamental problem
19070 here is that the C preprocessor was designed to preprocess C programs,
19071 not makefiles. This is much less of a problem with Autoconf,
19072 which uses the general-purpose preprocessor M4, and where the
19073 package's author (rather than the installer) does the preprocessing in a
19078 Finally, Mark Eichin notes:
19081 Imake isn't all that extensible, either. In order to add new features to
19082 Imake, you need to provide your own project template, and duplicate most
19083 of the features of the existing one. This means that for a sophisticated
19084 project, using the vendor-provided Imake templates fails to provide any
19085 leverage---since they don't cover anything that your own project needs
19086 (unless it is an X11 program).
19088 On the other side, though:
19090 The one advantage that Imake has over @command{configure}:
19091 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
19092 than @file{Makefile.in} files. There is a fix to this, however---at least
19093 for the Kerberos V5 tree, we've modified things to call in common
19094 @file{post.in} and @file{pre.in} makefile fragments for the
19095 entire tree. This means that a lot of common things don't have to be
19096 duplicated, even though they normally are in @command{configure} setups.
19100 @node Defining Directories
19101 @section How Do I @code{#define} Installation Directories?
19104 My program needs library files, installed in @code{datadir} and
19108 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
19109 [Define to the read-only architecture-independent
19117 #define DATADIR "$@{prefix@}/share"
19121 As already explained, this behavior is on purpose, mandated by the
19122 @acronym{GNU} Coding Standards, see @ref{Installation Directory
19123 Variables}. There are several means to achieve a similar goal:
19127 Do not use @code{AC_DEFINE} but use your makefile to pass the
19128 actual value of @code{datadir} via compilation flags.
19129 @xref{Installation Directory Variables}, for the details.
19132 This solution can be simplified when compiling a program: you may either
19133 extend the @code{CPPFLAGS}:
19136 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
19140 or create a dedicated header file:
19143 DISTCLEANFILES = datadir.h
19144 datadir.h: Makefile
19145 echo '#define DATADIR "$(datadir)"' >$@@
19149 Use @code{AC_DEFINE} but have @command{configure} compute the literal
19150 value of @code{datadir} and others. Many people have wrapped macros to
19151 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
19152 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
19155 This solution does not conform to the @acronym{GNU} Coding Standards.
19158 Note that all the previous solutions hard wire the absolute name of
19159 these directories in the executables, which is not a good property. You
19160 may try to compute the names relative to @code{prefix}, and try to
19161 find @code{prefix} at runtime, this way your package is relocatable.
19162 Some macros are already available to address this issue: see
19163 @code{adl_COMPUTE_RELATIVE_PATHS} and
19164 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
19165 @uref{http://autoconf-archive.cryp.to/,
19166 Autoconf Macro Archive}.
19170 @node Autom4te Cache
19171 @section What is @file{autom4te.cache}?
19174 What is this directory @file{autom4te.cache}? Can I safely remove it?
19177 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
19178 role and is read by many tools: @command{autoconf} to create
19179 @file{configure}, @command{autoheader} to create @file{config.h.in},
19180 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
19181 check the completeness of @file{configure.ac}, @command{autoreconf} to
19182 check the @acronym{GNU} Build System components that are used. To
19183 ``read @file{configure.ac}'' actually means to compile it with M4,
19184 which can be a long process for complex @file{configure.ac}.
19186 This is why all these tools, instead of running directly M4, invoke
19187 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
19188 a specific demand, stores additional information in
19189 @file{autom4te.cache} for future runs. For instance, if you run
19190 @command{autoconf}, behind the scenes, @command{autom4te} also
19191 stores information for the other tools, so that when you invoke
19192 @command{autoheader} or @command{automake} etc., reprocessing
19193 @file{configure.ac} is not needed. The speed up is frequently of 30%,
19194 and is increasing with the size of @file{configure.ac}.
19196 But it is and remains being simply a cache: you can safely remove it.
19201 Can I permanently get rid of it?
19204 The creation of this cache can be disabled from
19205 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
19206 details. You should be aware that disabling the cache slows down the
19207 Autoconf test suite by 40%. The more @acronym{GNU} Build System
19208 components are used, the more the cache is useful; for instance
19209 running @samp{autoreconf -f} on the Core Utilities is twice slower without
19210 the cache @emph{although @option{--force} implies that the cache is
19211 not fully exploited}, and eight times slower than without
19215 @node Present But Cannot Be Compiled
19216 @section Header Present But Cannot Be Compiled
19218 The most important guideline to bear in mind when checking for
19219 features is to mimic as much as possible the intended use.
19220 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
19221 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
19222 the preprocessor, instead of the compiler, to check for headers. As a
19223 result, incompatibilities between headers went unnoticed during
19224 configuration, and maintainers finally had to deal with this issue
19227 As of Autoconf 2.56 both checks are performed, and @code{configure}
19228 complains loudly if the compiler and the preprocessor do not agree.
19229 For the time being the result used is that of the preprocessor, to give
19230 maintainers time to adjust their @file{configure.ac}, but in the
19231 future, only the compiler will be considered.
19233 Consider the following example:
19236 $ @kbd{cat number.h}
19237 typedef int number;
19239 const number pi = 3;
19240 $ @kbd{cat configure.ac}
19241 AC_INIT([Example], [1.0], [bug-example@@example.org])
19242 AC_CHECK_HEADERS([pi.h])
19243 $ @kbd{autoconf -Wall}
19244 $ @kbd{./configure}
19245 checking for gcc... gcc
19246 checking for C compiler default output file name... a.out
19247 checking whether the C compiler works... yes
19248 checking whether we are cross compiling... no
19249 checking for suffix of executables...
19250 checking for suffix of object files... o
19251 checking whether we are using the GNU C compiler... yes
19252 checking whether gcc accepts -g... yes
19253 checking for gcc option to accept ISO C89... none needed
19254 checking how to run the C preprocessor... gcc -E
19255 checking for grep that handles long lines and -e... grep
19256 checking for egrep... grep -E
19257 checking for ANSI C header files... yes
19258 checking for sys/types.h... yes
19259 checking for sys/stat.h... yes
19260 checking for stdlib.h... yes
19261 checking for string.h... yes
19262 checking for memory.h... yes
19263 checking for strings.h... yes
19264 checking for inttypes.h... yes
19265 checking for stdint.h... yes
19266 checking for unistd.h... yes
19267 checking pi.h usability... no
19268 checking pi.h presence... yes
19269 configure: WARNING: pi.h: present but cannot be compiled
19270 configure: WARNING: pi.h: check for missing prerequisite headers?
19271 configure: WARNING: pi.h: see the Autoconf documentation
19272 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
19273 configure: WARNING: pi.h: proceeding with the preprocessor's result
19274 configure: WARNING: pi.h: in the future, the compiler will take precedence
19275 configure: WARNING: ## -------------------------------------- ##
19276 configure: WARNING: ## Report this to bug-example@@example.org ##
19277 configure: WARNING: ## -------------------------------------- ##
19278 checking for pi.h... yes
19282 The proper way the handle this case is using the fourth argument
19283 (@pxref{Generic Headers}):
19286 $ @kbd{cat configure.ac}
19287 AC_INIT([Example], [1.0], [bug-example@@example.org])
19288 AC_CHECK_HEADERS([number.h pi.h], [], [],
19289 [[#ifdef HAVE_NUMBER_H
19290 # include <number.h>
19293 $ @kbd{autoconf -Wall}
19294 $ @kbd{./configure}
19295 checking for gcc... gcc
19296 checking for C compiler default output... a.out
19297 checking whether the C compiler works... yes
19298 checking whether we are cross compiling... no
19299 checking for suffix of executables...
19300 checking for suffix of object files... o
19301 checking whether we are using the GNU C compiler... yes
19302 checking whether gcc accepts -g... yes
19303 checking for gcc option to accept ANSI C... none needed
19304 checking for number.h... yes
19305 checking for pi.h... yes
19308 See @ref{Particular Headers}, for a list of headers with their
19311 @c ===================================================== History of Autoconf.
19314 @chapter History of Autoconf
19315 @cindex History of autoconf
19317 You may be wondering, Why was Autoconf originally written? How did it
19318 get into its present form? (Why does it look like gorilla spit?) If
19319 you're not wondering, then this chapter contains no information useful
19320 to you, and you might as well skip it. If you @emph{are} wondering,
19321 then let there be light@enddots{}
19324 * Genesis:: Prehistory and naming of @command{configure}
19325 * Exodus:: The plagues of M4 and Perl
19326 * Leviticus:: The priestly code of portability arrives
19327 * Numbers:: Growth and contributors
19328 * Deuteronomy:: Approaching the promises of easy configuration
19334 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
19335 Free Software Foundation. As they were ported to more platforms and
19336 more programs were added, the number of @option{-D} options that users
19337 had to select in the makefile (around 20) became burdensome.
19338 Especially for me---I had to test each new release on a bunch of
19339 different systems. So I wrote a little shell script to guess some of
19340 the correct settings for the fileutils package, and released it as part
19341 of fileutils 2.0. That @command{configure} script worked well enough that
19342 the next month I adapted it (by hand) to create similar @command{configure}
19343 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
19344 also adapted one of my scripts for his @acronym{CVS} revision control system.
19346 Later that summer, I learned that Richard Stallman and Richard Pixley
19347 were developing similar scripts to use in the @acronym{GNU} compiler tools;
19348 so I adapted my @command{configure} scripts to support their evolving
19349 interface: using the file name @file{Makefile.in} as the templates;
19350 adding @samp{+srcdir}, the first option (of many); and creating
19351 @file{config.status} files.
19356 As I got feedback from users, I incorporated many improvements, using
19357 Emacs to search and replace, cut and paste, similar changes in each of
19358 the scripts. As I adapted more @acronym{GNU} utilities packages to use
19359 @command{configure} scripts, updating them all by hand became impractical.
19360 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
19361 mail saying that the @command{configure} scripts were great, and asking if
19362 I had a tool for generating them that I could send him. No, I thought,
19363 but I should! So I started to work out how to generate them. And the
19364 journey from the slavery of hand-written @command{configure} scripts to the
19365 abundance and ease of Autoconf began.
19367 Cygnus @command{configure}, which was being developed at around that time,
19368 is table driven; it is meant to deal mainly with a discrete number of
19369 system types with a small number of mainly unguessable features (such as
19370 details of the object file format). The automatic configuration system
19371 that Brian Fox had developed for Bash takes a similar approach. For
19372 general use, it seems to me a hopeless cause to try to maintain an
19373 up-to-date database of which features each variant of each operating
19374 system has. It's easier and more reliable to check for most features on
19375 the fly---especially on hybrid systems that people have hacked on
19376 locally or that have patches from vendors installed.
19378 I considered using an architecture similar to that of Cygnus
19379 @command{configure}, where there is a single @command{configure} script that
19380 reads pieces of @file{configure.in} when run. But I didn't want to have
19381 to distribute all of the feature tests with every package, so I settled
19382 on having a different @command{configure} made from each
19383 @file{configure.in} by a preprocessor. That approach also offered more
19384 control and flexibility.
19386 I looked briefly into using the Metaconfig package, by Larry Wall,
19387 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
19388 reasons. The @command{Configure} scripts it produces are interactive,
19389 which I find quite inconvenient; I didn't like the ways it checked for
19390 some features (such as library functions); I didn't know that it was
19391 still being maintained, and the @command{Configure} scripts I had
19392 seen didn't work on many modern systems (such as System V R4 and NeXT);
19393 it wasn't flexible in what it could do in response to a feature's
19394 presence or absence; I found it confusing to learn; and it was too big
19395 and complex for my needs (I didn't realize then how much Autoconf would
19396 eventually have to grow).
19398 I considered using Perl to generate my style of @command{configure}
19399 scripts, but decided that M4 was better suited to the job of simple
19400 textual substitutions: it gets in the way less, because output is
19401 implicit. Plus, everyone already has it. (Initially I didn't rely on
19402 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
19403 University of Maryland had recently been putting M4 front ends on
19404 several programs, including @code{tvtwm}, and I was interested in trying
19405 out a new language.
19410 Since my @command{configure} scripts determine the system's capabilities
19411 automatically, with no interactive user intervention, I decided to call
19412 the program that generates them Autoconfig. But with a version number
19413 tacked on, that name would be too long for old Unix file systems,
19414 so I shortened it to Autoconf.
19416 In the fall of 1991 I called together a group of fellow questers after
19417 the Holy Grail of portability (er, that is, alpha testers) to give me
19418 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
19419 and continued to add features and improve the techniques used in the
19420 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
19421 with the idea of making an Autoconf shell script to run M4
19422 and check for unresolved macro calls; Richard Pixley, who suggested
19423 running the compiler instead of searching the file system to find
19424 include files and symbols, for more accurate results; Karl Berry, who
19425 got Autoconf to configure @TeX{} and added the macro index to the
19426 documentation; and Ian Lance Taylor, who added support for creating a C
19427 header file as an alternative to putting @option{-D} options in a
19428 makefile, so he could use Autoconf for his @acronym{UUCP} package.
19429 The alpha testers cheerfully adjusted their files again and again as the
19430 names and calling conventions of the Autoconf macros changed from
19431 release to release. They all contributed many specific checks, great
19432 ideas, and bug fixes.
19437 In July 1992, after months of alpha testing, I released Autoconf 1.0,
19438 and converted many @acronym{GNU} packages to use it. I was surprised by how
19439 positive the reaction to it was. More people started using it than I
19440 could keep track of, including people working on software that wasn't
19441 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
19442 Autoconf continued to improve rapidly, as many people using the
19443 @command{configure} scripts reported problems they encountered.
19445 Autoconf turned out to be a good torture test for M4 implementations.
19446 Unix M4 started to dump core because of the length of the
19447 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
19448 M4 as well. Eventually, we realized that we needed to use some
19449 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
19450 particular, has an impoverished set of builtin macros; the System V
19451 version is better, but still doesn't provide everything we need.
19453 More development occurred as people put Autoconf under more stresses
19454 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
19455 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
19456 invalid arguments. Jim Blandy bravely coerced it into configuring
19457 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
19458 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
19459 @command{autoheader} script to automate the creation of C header file
19460 templates, and added a @option{--verbose} option to @command{configure}.
19461 Noah Friedman added the @option{--autoconf-dir} option and
19462 @code{AC_MACRODIR} environment variable. (He also coined the term
19463 @dfn{autoconfiscate} to mean ``adapt a software package to use
19464 Autoconf''.) Roland and Noah improved the quoting protection in
19465 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
19466 dealing with portability problems from February through June, 1993.
19469 @section Deuteronomy
19471 A long wish list for major features had accumulated, and the effect of
19472 several years of patching by various people had left some residual
19473 cruft. In April 1994, while working for Cygnus Support, I began a major
19474 revision of Autoconf. I added most of the features of the Cygnus
19475 @command{configure} that Autoconf had lacked, largely by adapting the
19476 relevant parts of Cygnus @command{configure} with the help of david zuhn
19477 and Ken Raeburn. These features include support for using
19478 @file{config.sub}, @file{config.guess}, @option{--host}, and
19479 @option{--target}; making links to files; and running @command{configure}
19480 scripts in subdirectories. Adding these features enabled Ken to convert
19481 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
19484 I added more features in response to other peoples' requests. Many
19485 people had asked for @command{configure} scripts to share the results of
19486 the checks between runs, because (particularly when configuring a large
19487 source tree, like Cygnus does) they were frustratingly slow. Mike
19488 Haertel suggested adding site-specific initialization scripts. People
19489 distributing software that had to unpack on MS-DOS asked for a way to
19490 override the @file{.in} extension on the file names, which produced file
19491 names like @file{config.h.in} containing two dots. Jim Avera did an
19492 extensive examination of the problems with quoting in @code{AC_DEFINE}
19493 and @code{AC_SUBST}; his insights led to significant improvements.
19494 Richard Stallman asked that compiler output be sent to @file{config.log}
19495 instead of @file{/dev/null}, to help people debug the Emacs
19496 @command{configure} script.
19498 I made some other changes because of my dissatisfaction with the quality
19499 of the program. I made the messages showing results of the checks less
19500 ambiguous, always printing a result. I regularized the names of the
19501 macros and cleaned up coding style inconsistencies. I added some
19502 auxiliary utilities that I had developed to help convert source code
19503 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
19504 the macros not interrupt each others' messages. (That feature revealed
19505 some performance bottlenecks in @acronym{GNU} M4, which he hastily
19506 corrected!) I reorganized the documentation around problems people want
19507 to solve. And I began a test suite, because experience had shown that
19508 Autoconf has a pronounced tendency to regress when we change it.
19510 Again, several alpha testers gave invaluable feedback, especially
19511 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
19514 Finally, version 2.0 was ready. And there was much rejoicing. (And I
19515 have free time again. I think. Yeah, right.)
19518 @c ========================================================== Appendices
19520 @node Copying This Manual
19521 @appendix Copying This Manual
19525 * GNU Free Documentation License:: License for copying this manual
19534 * Environment Variable Index:: Index of environment variables used
19535 * Output Variable Index:: Index of variables set in output files
19536 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
19537 * Autoconf Macro Index:: Index of Autoconf macros
19538 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
19539 * Autotest Macro Index:: Index of Autotest macros
19540 * Program & Function Index:: Index of those with portability problems
19541 * Concept Index:: General index
19544 @node Environment Variable Index
19545 @appendixsec Environment Variable Index
19547 This is an alphabetical list of the environment variables that Autoconf
19552 @node Output Variable Index
19553 @appendixsec Output Variable Index
19555 This is an alphabetical list of the variables that Autoconf can
19556 substitute into files that it creates, typically one or more
19557 makefiles. @xref{Setting Output Variables}, for more information
19558 on how this is done.
19562 @node Preprocessor Symbol Index
19563 @appendixsec Preprocessor Symbol Index
19565 This is an alphabetical list of the C preprocessor symbols that the
19566 Autoconf macros define. To work with Autoconf, C source code needs to
19567 use these names in @code{#if} or @code{#ifdef} directives.
19571 @node Autoconf Macro Index
19572 @appendixsec Autoconf Macro Index
19574 This is an alphabetical list of the Autoconf macros.
19575 @ifset shortindexflag
19576 To make the list easier to use, the macros are listed without their
19577 preceding @samp{AC_}.
19582 @node M4 Macro Index
19583 @appendixsec M4 Macro Index
19585 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
19586 @ifset shortindexflag
19587 To make the list easier to use, the macros are listed without their
19588 preceding @samp{m4_} or @samp{AS_}.
19593 @node Autotest Macro Index
19594 @appendixsec Autotest Macro Index
19596 This is an alphabetical list of the Autotest macros.
19597 @ifset shortindexflag
19598 To make the list easier to use, the macros are listed without their
19599 preceding @samp{AT_}.
19604 @node Program & Function Index
19605 @appendixsec Program and Function Index
19607 This is an alphabetical list of the programs and functions which
19608 portability is discussed in this document.
19612 @node Concept Index
19613 @appendixsec Concept Index
19615 This is an alphabetical list of the files, tools, and concepts
19616 introduced in this document.
19622 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
19623 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
19624 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
19625 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
19626 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
19627 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
19628 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
19629 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
19630 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
19631 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
19632 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
19633 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
19634 @c LocalWords: distclean uninstall noindent versioning Tromey dir
19635 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
19636 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
19637 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
19638 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
19639 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
19640 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
19641 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
19642 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
19643 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19644 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19645 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19646 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19647 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19648 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19649 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19650 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19651 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19652 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19653 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19654 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19655 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19656 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19657 @c LocalWords: SETGID getloadavg nlist GETMNTENT irix
19658 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19659 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19660 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19661 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19662 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19663 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19664 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19665 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19666 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS GCC's kB
19667 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19668 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19669 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19670 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19671 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19672 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae conftest AXP str
19673 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19674 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19675 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19676 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19677 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19678 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19679 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19680 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19681 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19682 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19683 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
19684 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19685 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19686 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19687 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19688 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19689 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19690 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
19691 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19692 @c LocalWords: sparc Proulx nbar nfoo maxdepth acdilrtu TWG mc
19693 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19694 @c LocalWords: fooXXXXXX Unicos utimes hpux hppa unescaped
19695 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19696 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19697 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19698 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19699 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19700 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19701 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19702 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19703 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19704 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19705 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19706 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19707 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19708 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19709 @c LocalWords: GOBJC OTP ERLC erl valloc decr dumpdef errprint incr
19710 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
19711 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19712 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
19713 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
19715 @c Local Variables:
19717 @c ispell-local-dictionary: "american"
19718 @c indent-tabs-mode: nil
19719 @c whitespace-check-buffer-indent: nil