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 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: (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 configure.ac:: 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 * configure.ac Layout:: Standard organization of @file{configure.ac}
302 Initialization and Output Files
304 * Initializing configure:: Option processing etc.
305 * Notices:: Copyright, version numbers in @command{configure}
306 * Input:: Where Autoconf should find files
307 * Output:: Outputting results from the configuration
308 * Configuration Actions:: Preparing the output based on results
309 * Configuration Files:: Creating output files
310 * Makefile Substitutions:: Using output variables in makefiles
311 * Configuration Headers:: Creating a configuration header file
312 * Configuration Commands:: Running arbitrary instantiation commands
313 * Configuration Links:: Links depending on the configuration
314 * Subdirectories:: Configuring independent packages together
315 * Default Prefix:: Changing the default installation prefix
317 Substitutions in Makefiles
319 * Preset Output Variables:: Output variables that are always set
320 * Installation Directory Variables:: Other preset output variables
321 * Changed Directory Variables:: Warnings about @file{datarootdir}
322 * Build Directories:: Supporting multiple concurrent compiles
323 * Automatic Remaking:: Makefile rules for configuring
325 Configuration Header Files
327 * Header Templates:: Input for the configuration headers
328 * autoheader Invocation:: How to create configuration templates
329 * Autoheader Macros:: How to specify CPP templates
333 * Common Behavior:: Macros' standard schemes
334 * Alternative Programs:: Selecting between alternative programs
335 * Files:: Checking for the existence of files
336 * Libraries:: Library archives that might be missing
337 * Library Functions:: C library functions that might be missing
338 * Header Files:: Header files that might be missing
339 * Declarations:: Declarations that may be missing
340 * Structures:: Structures or members that might be missing
341 * Types:: Types that might be missing
342 * Compilers and Preprocessors:: Checking for compiling programs
343 * System Services:: Operating system services
344 * Posix Variants:: Special kludges for specific Posix variants
345 * Erlang Libraries:: Checking for the existence of Erlang libraries
349 * Standard Symbols:: Symbols defined by the macros
350 * Default Includes:: Includes used by the generic macros
354 * Particular Programs:: Special handling to find certain programs
355 * Generic Programs:: How to find other programs
359 * Function Portability:: Pitfalls with usual functions
360 * Particular Functions:: Special handling to find certain functions
361 * Generic Functions:: How to find other functions
365 * Header Portability:: Collected knowledge on common headers
366 * Particular Headers:: Special handling to find certain headers
367 * Generic Headers:: How to find other headers
371 * Particular Declarations:: Macros to check for certain declarations
372 * Generic Declarations:: How to find other declarations
376 * Particular Structures:: Macros to check for certain structure members
377 * Generic Structures:: How to find other structure members
381 * Particular Types:: Special handling to find certain types
382 * Generic Types:: How to find other types
384 Compilers and Preprocessors
386 * Specific Compiler Characteristics:: Some portability issues
387 * Generic Compiler Characteristics:: Language independent tests and features
388 * C Compiler:: Checking its characteristics
389 * C++ Compiler:: Likewise
390 * Objective C Compiler:: Likewise
391 * Erlang Compiler and Interpreter:: Likewise
392 * Fortran Compiler:: Likewise
396 * Language Choice:: Selecting which language to use for testing
397 * Writing Test Programs:: Forging source files for compilers
398 * Running the Preprocessor:: Detecting preprocessor symbols
399 * Running the Compiler:: Detecting language or header features
400 * Running the Linker:: Detecting library features
401 * Runtime:: Testing for runtime features
402 * Systemology:: A zoology of operating systems
403 * Multiple Cases:: Tests for several possible values
405 Writing Test Programs
407 * Guidelines:: General rules for writing test programs
408 * Test Functions:: Avoiding pitfalls in test programs
409 * Generating Sources:: Source program boilerplate
413 * Defining Symbols:: Defining C preprocessor symbols
414 * Setting Output Variables:: Replacing variables in output files
415 * Special Chars in Variables:: Characters to beware of in variables
416 * Caching Results:: Speeding up subsequent @command{configure} runs
417 * Printing Messages:: Notifying @command{configure} users
421 * Cache Variable Names:: Shell variables used in caches
422 * Cache Files:: Files @command{configure} uses for caching
423 * Cache Checkpointing:: Loading and saving the cache file
427 * M4 Quotation:: Protecting macros from unwanted expansion
428 * Using autom4te:: The Autoconf executables backbone
429 * Programming in M4sugar:: Convenient pure M4 macros
430 * Programming in M4sh:: Common shell Constructs
431 * File Descriptor Macros:: File descriptor macros for input and output
435 * Active Characters:: Characters that change the behavior of M4
436 * One Macro Call:: Quotation and one macro call
437 * Quotation and Nested Macros:: Macros calling macros
438 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
439 * Quadrigraphs:: Another way to escape special characters
440 * Quotation Rule Of Thumb:: One parenthesis, one quote
442 Using @command{autom4te}
444 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
445 * Customizing autom4te:: Customizing the Autoconf package
447 Programming in M4sugar
449 * Redefined M4 Macros:: M4 builtins changed in M4sugar
450 * Looping constructs:: Iteration in M4
451 * Evaluation Macros:: More quotation and evaluation control
452 * Text processing Macros:: String manipulation in M4
453 * Forbidden Patterns:: Catching unexpanded macros
455 Writing Autoconf Macros
457 * Macro Definitions:: Basic format of an Autoconf macro
458 * Macro Names:: What to call your new macros
459 * Reporting Messages:: Notifying @command{autoconf} users
460 * Dependencies Between Macros:: What to do when macros depend on other macros
461 * Obsoleting Macros:: Warning about old ways of doing things
462 * Coding Style:: Writing Autoconf macros @`a la Autoconf
464 Dependencies Between Macros
466 * Prerequisite Macros:: Ensuring required information
467 * Suggested Ordering:: Warning about possible ordering problems
468 * One-Shot Macros:: Ensuring a macro is called only once
470 Portable Shell Programming
472 * Shellology:: A zoology of shells
473 * Here-Documents:: Quirks and tricks
474 * File Descriptors:: FDs and redirections
475 * File System Conventions:: File names
476 * Shell Substitutions:: Variable and command expansions
477 * Assignments:: Varying side effects of assignments
478 * Parentheses:: Parentheses in shell scripts
479 * Slashes:: Slashes in shell scripts
480 * Special Shell Variables:: Variables you should not change
481 * Limitations of Builtins:: Portable use of not so portable /bin/sh
482 * Limitations of Usual Tools:: Portable use of portable tools
484 Portable Make Programming
486 * $< in Ordinary Make Rules:: $< in ordinary rules
487 * Failure in Make Rules:: Failing portably in rules
488 * Special Chars in Names:: Special Characters in Macro Names
489 * Backslash-Newline-Newline:: Empty last lines in macro definitions
490 * Backslash-Newline Comments:: Spanning comments across line boundaries
491 * Long Lines in Makefiles:: Line length limitations
492 * Macros and Submakes:: @code{make macro=value} and submakes
493 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
494 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
495 * Comments in Make Rules:: Other problems with Make comments
496 * obj/ and Make:: Don't name a subdirectory @file{obj}
497 * make -k Status:: Exit status of @samp{make -k}
498 * VPATH and Make:: @code{VPATH} woes
499 * Single Suffix Rules:: Single suffix rules and separated dependencies
500 * Timestamps and Make:: Subsecond timestamp resolution
502 @code{VPATH} and Make
504 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
505 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
506 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
507 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
508 * Make Target Lookup:: More details about @code{VPATH} lookup
510 Portable C and C++ Programming
512 * Varieties of Unportability:: How to make your programs unportable
513 * Integer Overflow:: When integers get too large
514 * Null Pointers:: Properties of null pointers
515 * Buffer Overruns:: Subscript errors and the like
516 * Volatile Objects:: @code{volatile} and signals
517 * Floating Point Portability:: Portable floating-point arithmetic
518 * Exiting Portably:: Exiting and the exit status
522 * Specifying Names:: Specifying the system type
523 * Canonicalizing:: Getting the canonical system type
524 * Using System Type:: What to do with the system type
528 * Help Formatting:: Customizing @samp{configure --help}
529 * External Software:: Working with other optional software
530 * Package Options:: Selecting optional features
531 * Pretty Help Strings:: Formatting help string
532 * Site Details:: Configuring site details
533 * Transforming Names:: Changing program names when installing
534 * Site Defaults:: Giving @command{configure} local defaults
536 Transforming Program Names When Installing
538 * Transformation Options:: @command{configure} options to transform names
539 * Transformation Examples:: Sample uses of transforming names
540 * Transformation Rules:: Makefile uses of transforming names
542 Running @command{configure} Scripts
544 * Basic Installation:: Instructions for typical cases
545 * Compilers and Options:: Selecting compilers and optimization
546 * Multiple Architectures:: Compiling for multiple architectures at once
547 * Installation Names:: Installing in different directories
548 * Optional Features:: Selecting optional features
549 * System Type:: Specifying the system type
550 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
551 * Defining Variables:: Specifying the compiler etc.
552 * configure Invocation:: Changing how @command{configure} runs
556 * Obsolete config.status Use:: Different calling convention
557 * acconfig.h:: Additional entries in @file{config.h.in}
558 * autoupdate Invocation:: Automatic update of @file{configure.ac}
559 * Obsolete Macros:: Backward compatibility macros
560 * Autoconf 1:: Tips for upgrading your files
561 * Autoconf 2.13:: Some fresher tips
563 Upgrading From Version 1
565 * Changed File Names:: Files you might rename
566 * Changed Makefiles:: New things to put in @file{Makefile.in}
567 * Changed Macros:: Macro calls you might replace
568 * Changed Results:: Changes in how to check test results
569 * Changed Macro Writing:: Better ways to write your own macros
571 Upgrading From Version 2.13
573 * Changed Quotation:: Broken code which used to work
574 * New Macros:: Interaction with foreign macros
575 * Hosts and Cross-Compilation:: Bugward compatibility kludges
576 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
577 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
579 Generating Test Suites with Autotest
581 * Using an Autotest Test Suite:: Autotest and the user
582 * Writing testsuite.at:: Autotest macros
583 * testsuite Invocation:: Running @command{testsuite} scripts
584 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
586 Using an Autotest Test Suite
588 * testsuite Scripts:: The concepts of Autotest
589 * Autotest Logs:: Their contents
591 Frequent Autoconf Questions, with answers
593 * Distributing:: Distributing @command{configure} scripts
594 * Why GNU M4:: Why not use the standard M4?
595 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
596 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
597 * Defining Directories:: Passing @code{datadir} to program
598 * autom4te.cache:: What is it? Can I remove it?
599 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
603 * Genesis:: Prehistory and naming of @command{configure}
604 * Exodus:: The plagues of M4 and Perl
605 * Leviticus:: The priestly code of portability arrives
606 * Numbers:: Growth and contributors
607 * Deuteronomy:: Approaching the promises of easy configuration
611 * GNU Free Documentation License:: License for copying this manual
615 * Environment Variable Index:: Index of environment variables used
616 * Output Variable Index:: Index of variables set in output files
617 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
618 * Autoconf Macro Index:: Index of Autoconf macros
619 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
620 * Autotest Macro Index:: Index of Autotest macros
621 * Program & Function Index:: Index of those with portability problems
622 * Concept Index:: General index
627 @c ============================================================= Introduction.
630 @chapter Introduction
634 A physicist, an engineer, and a computer scientist were discussing the
635 nature of God. ``Surely a Physicist,'' said the physicist, ``because
636 early in the Creation, God made Light; and you know, Maxwell's
637 equations, the dual nature of electromagnetic waves, the relativistic
638 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
639 before making Light, God split the Chaos into Land and Water; it takes a
640 hell of an engineer to handle that big amount of mud, and orderly
641 separation of solids from liquids@dots{}'' The computer scientist
642 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
646 @c (via Franc,ois Pinard)
648 Autoconf is a tool for producing shell scripts that automatically
649 configure software source code packages to adapt to many kinds of
650 Posix-like systems. The configuration scripts produced by Autoconf
651 are independent of Autoconf when they are run, so their users do not
652 need to have Autoconf.
654 The configuration scripts produced by Autoconf require no manual user
655 intervention when run; they do not normally even need an argument
656 specifying the system type. Instead, they individually test for the
657 presence of each feature that the software package they are for might need.
658 (Before each check, they print a one-line message stating what they are
659 checking for, so the user doesn't get too bored while waiting for the
660 script to finish.) As a result, they deal well with systems that are
661 hybrids or customized from the more common Posix variants. There is
662 no need to maintain files that list the features supported by each
663 release of each variant of Posix.
665 For each software package that Autoconf is used with, it creates a
666 configuration script from a template file that lists the system features
667 that the package needs or can use. After the shell code to recognize
668 and respond to a system feature has been written, Autoconf allows it to
669 be shared by many software packages that can use (or need) that feature.
670 If it later turns out that the shell code needs adjustment for some
671 reason, it needs to be changed in only one place; all of the
672 configuration scripts can be regenerated automatically to take advantage
675 The Metaconfig package is similar in purpose to Autoconf, but the
676 scripts it produces require manual user intervention, which is quite
677 inconvenient when configuring large source trees. Unlike Metaconfig
678 scripts, Autoconf scripts can support cross-compiling, if some care is
679 taken in writing them.
681 Autoconf does not solve all problems related to making portable
682 software packages---for a more complete solution, it should be used in
683 concert with other @acronym{GNU} build tools like Automake and
684 Libtool. These other tools take on jobs like the creation of a
685 portable, recursive makefile with all of the standard targets,
686 linking of shared libraries, and so on. @xref{The GNU Build System},
687 for more information.
689 Autoconf imposes some restrictions on the names of macros used with
690 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
692 Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
693 features that some versions of M4, including @acronym{GNU} M4 1.3,
694 do not have. You should use version 1.4.5 or later of @acronym{GNU} M4.
696 @xref{Autoconf 1}, for information about upgrading from version 1.
697 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
698 for answers to some common questions about Autoconf.
700 See the @uref{http://www.gnu.org/software/autoconf/,
701 Autoconf web page} for up-to-date information, details on the mailing
702 lists, pointers to a list of known bugs, etc.
704 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
705 list}. Past suggestions are
706 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
708 Mail bug reports to @email{bug-autoconf@@gnu.org, the
709 Autoconf Bugs mailing list}. Past bug reports are
710 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
712 If possible, first check that your bug is
713 not already solved in current development versions, and that it has not
714 been reported yet. Be sure to include all the needed information and a
715 short @file{configure.ac} that demonstrates the problem.
717 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
718 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
719 Summary} for details. Patches relative to the
720 current @acronym{CVS} version can be sent for review to the
721 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
723 @uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}.
725 Because of its mission, the Autoconf package itself
726 includes only a set of often-used
727 macros that have already demonstrated their usefulness. Nevertheless,
728 if you wish to share your macros, or find existing ones, see the
729 @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
730 Archive}, which is kindly run by @email{simons@@cryp.to,
734 @c ================================================= The GNU Build System
736 @node The GNU Build System
737 @chapter The @acronym{GNU} Build System
738 @cindex @acronym{GNU} build system
740 Autoconf solves an important problem---reliable discovery of
741 system-specific build and runtime information---but this is only one
742 piece of the puzzle for the development of portable software. To this
743 end, the @acronym{GNU} project has developed a suite of integrated
744 utilities to finish the job Autoconf started: the @acronym{GNU} build
745 system, whose most important components are Autoconf, Automake, and
746 Libtool. In this chapter, we introduce you to those tools, point you
747 to sources of more information, and try to convince you to use the
748 entire @acronym{GNU} build system for your software.
751 * Automake:: Escaping makefile hell
752 * Gnulib:: The @acronym{GNU} portability library
753 * Libtool:: Building libraries portably
754 * Pointers:: More info on the @acronym{GNU} build system
760 The ubiquity of @command{make} means that a makefile is almost the
761 only viable way to distribute automatic build rules for software, but
762 one quickly runs into its numerous limitations. Its lack of
763 support for automatic dependency tracking, recursive builds in
764 subdirectories, reliable timestamps (e.g., for network file systems), and
765 so on, mean that developers must painfully (and often incorrectly)
766 reinvent the wheel for each project. Portability is non-trivial, thanks
767 to the quirks of @command{make} on many systems. On top of all this is the
768 manual labor required to implement the many standard targets that users
769 have come to expect (@code{make install}, @code{make distclean},
770 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
771 you also have to insert repetitive code in your @code{Makefile.in} to
772 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
773 provided by @command{configure}. Into this mess steps @dfn{Automake}.
776 Automake allows you to specify your build needs in a @code{Makefile.am}
777 file with a vastly simpler and more powerful syntax than that of a plain
778 makefile, and then generates a portable @code{Makefile.in} for
779 use with Autoconf. For example, the @code{Makefile.am} to build and
780 install a simple ``Hello world'' program might look like:
784 hello_SOURCES = hello.c
788 The resulting @code{Makefile.in} (~400 lines) automatically supports all
789 the standard targets, the substitutions provided by Autoconf, automatic
790 dependency tracking, @code{VPATH} building, and so on. @command{make}
791 builds the @code{hello} program, and @code{make install} installs it
792 in @file{/usr/local/bin} (or whatever prefix was given to
793 @command{configure}, if not @file{/usr/local}).
795 The benefits of Automake increase for larger packages (especially ones
796 with subdirectories), but even for small programs the added convenience
797 and portability can be substantial. And that's not all@enddots{}
802 @acronym{GNU} software has a well-deserved reputation for running on
803 many different types of systems. While our primary goal is to write
804 software for the @acronym{GNU} system, many users and developers have
805 been introduced to us through the systems that they were already using.
808 Gnulib is a central location for common @acronym{GNU} code, intended to
809 be shared among free software packages. Its components are typically
810 shared at the source level, rather than being a library that gets built,
811 installed, and linked against. The idea is to copy files from Gnulib
812 into your own source tree. There is no distribution tarball; developers
813 should just grab source modules from the repository. The source files
814 are available online, under various licenses, mostly @acronym{GNU}
815 @acronym{GPL} or @acronym{GNU} @acronym{LGPL}.
817 Gnulib modules typically contain C source code along with Autoconf
818 macros used to configure the source code. For example, the Gnulib
819 @code{stdbool} module implements a @file{stdbool.h} header that nearly
820 conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}.
821 This module contains a source file for the replacement header, along
822 with an Autoconf macro that arranges to use the replacement header on
823 old-fashioned systems.
828 Often, one wants to build not only programs, but libraries, so that
829 other programs can benefit from the fruits of your labor. Ideally, one
830 would like to produce @emph{shared} (dynamically linked) libraries,
831 which can be used by multiple programs without duplication on disk or in
832 memory and can be updated independently of the linked programs.
833 Producing shared libraries portably, however, is the stuff of
834 nightmares---each system has its own incompatible tools, compiler flags,
835 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
839 Libtool handles all the requirements of building shared libraries for
840 you, and at this time seems to be the @emph{only} way to do so with any
841 portability. It also handles many other headaches, such as: the
842 interaction of Make rules with the variable suffixes of
843 shared libraries, linking reliably with shared libraries before they are
844 installed by the superuser, and supplying a consistent versioning system
845 (so that different versions of a library can be installed or upgraded
846 without breaking binary compatibility). Although Libtool, like
847 Autoconf, can be used without Automake, it is most simply utilized in
848 conjunction with Automake---there, Libtool is used automatically
849 whenever shared libraries are needed, and you need not know its syntax.
854 Developers who are used to the simplicity of @command{make} for small
855 projects on a single system might be daunted at the prospect of
856 learning to use Automake and Autoconf. As your software is
857 distributed to more and more users, however, you otherwise
858 quickly find yourself putting lots of effort into reinventing the
859 services that the @acronym{GNU} build tools provide, and making the
860 same mistakes that they once made and overcame. (Besides, since
861 you're already learning Autoconf, Automake is a piece of cake.)
863 There are a number of places that you can go to for more information on
864 the @acronym{GNU} build tools.
871 @uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf},
872 @uref{http://www.gnu.org/@/software/@/automake/, Automake},
873 @uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and
874 @uref{http://www.gnu.org/@/software/@/libtool/, Libtool}.
876 @item Automake Manual
878 @xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more
879 information on Automake.
883 The book @cite{@acronym{GNU} Autoconf, Automake and
884 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
885 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
886 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
887 build environment. You can also find
888 @uref{http://sources.redhat.com/@/autobook/, the entire book on-line}.
892 @c ================================================= Making configure Scripts.
894 @node Making configure Scripts
895 @chapter Making @command{configure} Scripts
896 @cindex @file{aclocal.m4}
897 @cindex @command{configure}
899 The configuration scripts that Autoconf produces are by convention
900 called @command{configure}. When run, @command{configure} creates several
901 files, replacing configuration parameters in them with appropriate
902 values. The files that @command{configure} creates are:
906 one or more @file{Makefile} files, usually one in each subdirectory of the
907 package (@pxref{Makefile Substitutions});
910 optionally, a C header file, the name of which is configurable,
911 containing @code{#define} directives (@pxref{Configuration Headers});
914 a shell script called @file{config.status} that, when run, recreates
915 the files listed above (@pxref{config.status Invocation});
918 an optional shell script normally called @file{config.cache}
919 (created when using @samp{configure --config-cache}) that
920 saves the results of running many of the tests (@pxref{Cache Files});
923 a file called @file{config.log} containing any messages produced by
924 compilers, to help debugging if @command{configure} makes a mistake.
927 @cindex @file{configure.in}
928 @cindex @file{configure.ac}
929 To create a @command{configure} script with Autoconf, you need to write an
930 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
931 @command{autoconf} on it. If you write your own feature tests to
932 supplement those that come with Autoconf, you might also write files
933 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
934 file to contain @code{#define} directives, you might also run
935 @command{autoheader}, and you can distribute the generated file
936 @file{config.h.in} with the package.
938 Here is a diagram showing how the files that can be used in
939 configuration are produced. Programs that are executed are suffixed by
940 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
941 @command{autoconf} and @command{autoheader} also read the installed Autoconf
942 macro files (by reading @file{autoconf.m4}).
945 Files used in preparing a software package for distribution:
947 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
951 | .------> autoconf* -----> configure
953 | `-----> [autoheader*] --> [config.h.in]
957 Makefile.in -------------------------------> Makefile.in
961 Files used in configuring a software package:
964 .-------------> [config.cache]
965 configure* ------------+-------------> config.log
967 [config.h.in] -. v .-> [config.h] -.
968 +--> config.status* -+ +--> make*
969 Makefile.in ---' `-> Makefile ---'
974 * Writing configure.ac:: What to put in an Autoconf input file
975 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
976 * ifnames Invocation:: Listing the conditionals in source code
977 * autoconf Invocation:: How to create configuration scripts
978 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
981 @node Writing configure.ac
982 @section Writing @file{configure.ac}
984 To produce a @command{configure} script for a software package, create a
985 file called @file{configure.ac} that contains invocations of the
986 Autoconf macros that test the system features your package needs or can
987 use. Autoconf macros already exist to check for many features; see
988 @ref{Existing Tests}, for their descriptions. For most other features,
989 you can use Autoconf template macros to produce custom checks; see
990 @ref{Writing Tests}, for information about them. For especially tricky
991 or specialized features, @file{configure.ac} might need to contain some
992 hand-crafted shell commands; see @ref{Portable Shell}. The
993 @command{autoscan} program can give you a good start in writing
994 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
996 Previous versions of Autoconf promoted the name @file{configure.in},
997 which is somewhat ambiguous (the tool needed to process this file is not
998 described by its extension), and introduces a slight confusion with
999 @file{config.h.in} and so on (for which @samp{.in} means ``to be
1000 processed by @command{configure}''). Using @file{configure.ac} is now
1004 * Shell Script Compiler:: Autoconf as solution of a problem
1005 * Autoconf Language:: Programming in Autoconf
1006 * configure.ac Layout:: Standard organization of @file{configure.ac}
1009 @node Shell Script Compiler
1010 @subsection A Shell Script Compiler
1012 Just as for any other computer language, in order to properly program
1013 @file{configure.ac} in Autoconf you must understand @emph{what} problem
1014 the language tries to address and @emph{how} it does so.
1016 The problem Autoconf addresses is that the world is a mess. After all,
1017 you are using Autoconf in order to have your package compile easily on
1018 all sorts of different systems, some of them being extremely hostile.
1019 Autoconf itself bears the price for these differences: @command{configure}
1020 must run on all those systems, and thus @command{configure} must limit itself
1021 to their lowest common denominator of features.
1023 Naturally, you might then think of shell scripts; who needs
1024 @command{autoconf}? A set of properly written shell functions is enough to
1025 make it easy to write @command{configure} scripts by hand. Sigh!
1026 Unfortunately, shell functions do not belong to the least common
1027 denominator; therefore, where you would like to define a function and
1028 use it ten times, you would instead need to copy its body ten times.
1030 So, what is really needed is some kind of compiler, @command{autoconf},
1031 that takes an Autoconf program, @file{configure.ac}, and transforms it
1032 into a portable shell script, @command{configure}.
1034 How does @command{autoconf} perform this task?
1036 There are two obvious possibilities: creating a brand new language or
1037 extending an existing one. The former option is attractive: all
1038 sorts of optimizations could easily be implemented in the compiler and
1039 many rigorous checks could be performed on the Autoconf program
1040 (e.g., rejecting any non-portable construct). Alternatively, you can
1041 extend an existing language, such as the @code{sh} (Bourne shell)
1044 Autoconf does the latter: it is a layer on top of @code{sh}. It was
1045 therefore most convenient to implement @command{autoconf} as a macro
1046 expander: a program that repeatedly performs @dfn{macro expansions} on
1047 text input, replacing macro calls with macro bodies and producing a pure
1048 @code{sh} script in the end. Instead of implementing a dedicated
1049 Autoconf macro expander, it is natural to use an existing
1050 general-purpose macro language, such as M4, and implement the extensions
1051 as a set of M4 macros.
1054 @node Autoconf Language
1055 @subsection The Autoconf Language
1058 The Autoconf language differs from many other computer
1059 languages because it treats actual code the same as plain text. Whereas
1060 in C, for instance, data and instructions have different syntactic
1061 status, in Autoconf their status is rigorously the same. Therefore, we
1062 need a means to distinguish literal strings from text to be expanded:
1065 When calling macros that take arguments, there must not be any white
1066 space between the macro name and the open parenthesis. Arguments should
1067 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
1068 separated by commas. Any leading blanks or newlines in arguments are ignored,
1069 unless they are quoted. You should always quote an argument that
1070 might contain a macro name, comma, parenthesis, or a leading blank or
1071 newline. This rule applies recursively for every macro
1072 call, including macros called from other macros.
1077 AC_CHECK_HEADER([stdio.h],
1078 [AC_DEFINE([HAVE_STDIO_H], [1],
1079 [Define to 1 if you have <stdio.h>.])],
1080 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1084 is quoted properly. You may safely simplify its quotation to:
1087 AC_CHECK_HEADER([stdio.h],
1088 [AC_DEFINE([HAVE_STDIO_H], 1,
1089 [Define to 1 if you have <stdio.h>.])],
1090 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1094 because @samp{1} cannot contain a macro call. Here, the argument of
1095 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1096 interpreted as an argument separator. Also, the second and third arguments
1097 of @samp{AC_CHECK_HEADER} must be quoted, since they contain
1098 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1099 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1100 if you unwisely defined a macro with a name like @samp{Define} or
1101 @samp{stdio} then they would need quoting. Cautious Autoconf users
1102 would keep the quotes, but many Autoconf users find such precautions
1103 annoying, and would rewrite the example as follows:
1106 AC_CHECK_HEADER(stdio.h,
1107 [AC_DEFINE(HAVE_STDIO_H, 1,
1108 [Define to 1 if you have <stdio.h>.])],
1109 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1113 This is safe, so long as you adopt good naming conventions and do not
1114 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1115 @samp{h}. Though it is also safe here to omit the quotes around
1116 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1117 message strings are more likely to inadvertently contain commas.
1119 The following example is wrong and dangerous, as it is underquoted:
1122 AC_CHECK_HEADER(stdio.h,
1123 AC_DEFINE(HAVE_STDIO_H, 1,
1124 Define to 1 if you have <stdio.h>.),
1125 AC_MSG_ERROR([Sorry, can't do anything for you]))
1128 In other cases, you may have to use text that also resembles a macro
1129 call. You must quote that text even when it is not passed as a macro
1133 echo "Hard rock was here! --[AC_DC]"
1140 echo "Hard rock was here! --AC_DC"
1144 When you use the same text in a macro argument, you must therefore have
1145 an extra quotation level (since one is stripped away by the macro
1146 substitution). In general, then, it is a good idea to @emph{use double
1147 quoting for all literal string arguments}:
1150 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1153 You are now able to understand one of the constructs of Autoconf that
1154 has been continually misunderstood@dots{} The rule of thumb is that
1155 @emph{whenever you expect macro expansion, expect quote expansion};
1156 i.e., expect one level of quotes to be lost. For instance:
1159 AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])])
1163 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1164 @samp{char b[10];} and is expanded once, which results in
1165 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1166 address this issue via the M4 @code{changequote} primitive, but do not
1167 use it!) Let's take a closer look: the author meant the first argument
1168 to be understood as a literal, and therefore it must be quoted twice:
1171 AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])])
1175 Voil@`a, you actually produce @samp{char b[10];} this time!
1177 On the other hand, descriptions (e.g., the last parameter of
1178 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1179 are subject to line breaking, for example---and should not be double quoted.
1180 Even if these descriptions are short and are not actually broken, double
1181 quoting them yields weird results.
1183 Some macros take optional arguments, which this documentation represents
1184 as @ovar{arg} (not to be confused with the quote characters). You may
1185 just leave them empty, or use @samp{[]} to make the emptiness of the
1186 argument explicit, or you may simply omit the trailing commas. The
1187 three lines below are equivalent:
1190 AC_CHECK_HEADERS([stdio.h], [], [], [])
1191 AC_CHECK_HEADERS([stdio.h],,,)
1192 AC_CHECK_HEADERS([stdio.h])
1195 It is best to put each macro call on its own line in
1196 @file{configure.ac}. Most of the macros don't add extra newlines; they
1197 rely on the newline after the macro call to terminate the commands.
1198 This approach makes the generated @command{configure} script a little
1199 easier to read by not inserting lots of blank lines. It is generally
1200 safe to set shell variables on the same line as a macro call, because
1201 the shell allows assignments without intervening newlines.
1203 You can include comments in @file{configure.ac} files by starting them
1204 with the @samp{#}. For example, it is helpful to begin
1205 @file{configure.ac} files with a line like this:
1208 # Process this file with autoconf to produce a configure script.
1211 @node configure.ac Layout
1212 @subsection Standard @file{configure.ac} Layout
1214 The order in which @file{configure.ac} calls the Autoconf macros is not
1215 important, with a few exceptions. Every @file{configure.ac} must
1216 contain a call to @code{AC_INIT} before the checks, and a call to
1217 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1218 rely on other macros having been called first, because they check
1219 previously set values of some variables to decide what to do. These
1220 macros are noted in the individual descriptions (@pxref{Existing
1221 Tests}), and they also warn you when @command{configure} is created if they
1222 are called out of order.
1224 To encourage consistency, here is a suggested order for calling the
1225 Autoconf macros. Generally speaking, the things near the end of this
1226 list are those that could depend on things earlier in it. For example,
1227 library functions could be affected by types and libraries.
1231 Autoconf requirements
1232 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1233 information on the package
1235 checks for libraries
1236 checks for header files
1238 checks for structures
1239 checks for compiler characteristics
1240 checks for library functions
1241 checks for system services
1242 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1248 @node autoscan Invocation
1249 @section Using @command{autoscan} to Create @file{configure.ac}
1250 @cindex @command{autoscan}
1252 The @command{autoscan} program can help you create and/or maintain a
1253 @file{configure.ac} file for a software package. @command{autoscan}
1254 examines source files in the directory tree rooted at a directory given
1255 as a command line argument, or the current directory if none is given.
1256 It searches the source files for common portability problems and creates
1257 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1258 for that package, and checks a possibly existing @file{configure.ac} for
1261 When using @command{autoscan} to create a @file{configure.ac}, you
1262 should manually examine @file{configure.scan} before renaming it to
1263 @file{configure.ac}; it probably needs some adjustments.
1264 Occasionally, @command{autoscan} outputs a macro in the wrong order
1265 relative to another macro, so that @command{autoconf} produces a warning;
1266 you need to move such macros manually. Also, if you want the package to
1267 use a configuration header file, you must add a call to
1268 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1269 also have to change or add some @code{#if} directives to your program in
1270 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1271 information about a program that can help with that job).
1273 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1274 consider adding its suggestions. The file @file{autoscan.log}
1275 contains detailed information on why a macro is requested.
1277 @command{autoscan} uses several data files (installed along with Autoconf)
1278 to determine which macros to output when it finds particular symbols in
1279 a package's source files. These data files all have the same format:
1280 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1281 output if that symbol is encountered. Lines starting with @samp{#} are
1284 @command{autoscan} accepts the following options:
1289 Print a summary of the command line options and exit.
1293 Print the version number of Autoconf and exit.
1297 Print the names of the files it examines and the potentially interesting
1298 symbols it finds in them. This output can be voluminous.
1300 @item --include=@var{dir}
1302 Append @var{dir} to the include path. Multiple invocations accumulate.
1304 @item --prepend-include=@var{dir}
1306 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1309 @node ifnames Invocation
1310 @section Using @command{ifnames} to List Conditionals
1311 @cindex @command{ifnames}
1313 @command{ifnames} can help you write @file{configure.ac} for a software
1314 package. It prints the identifiers that the package already uses in C
1315 preprocessor conditionals. If a package has already been set up to have
1316 some portability, @command{ifnames} can thus help you figure out what its
1317 @command{configure} needs to check for. It may help fill in some gaps in a
1318 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1321 @command{ifnames} scans all of the C source files named on the command line
1322 (or the standard input, if none are given) and writes to the standard
1323 output a sorted list of all the identifiers that appear in those files
1324 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1325 directives. It prints each identifier on a line, followed by a
1326 space-separated list of the files in which that identifier occurs.
1329 @command{ifnames} accepts the following options:
1334 Print a summary of the command line options and exit.
1338 Print the version number of Autoconf and exit.
1341 @node autoconf Invocation
1342 @section Using @command{autoconf} to Create @command{configure}
1343 @cindex @command{autoconf}
1345 To create @command{configure} from @file{configure.ac}, run the
1346 @command{autoconf} program with no arguments. @command{autoconf} processes
1347 @file{configure.ac} with the M4 macro processor, using the
1348 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1349 file instead of @file{configure.ac} and writes the configuration script
1350 to the standard output instead of to @command{configure}. If you give
1351 @command{autoconf} the argument @option{-}, it reads from the standard
1352 input instead of @file{configure.ac} and writes the configuration script
1353 to the standard output.
1355 The Autoconf macros are defined in several files. Some of the files are
1356 distributed with Autoconf; @command{autoconf} reads them first. Then it
1357 looks for the optional file @file{acsite.m4} in the directory that
1358 contains the distributed Autoconf macro files, and for the optional file
1359 @file{aclocal.m4} in the current directory. Those files can contain
1360 your site's or the package's own Autoconf macro definitions
1361 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1362 defined in more than one of the files that @command{autoconf} reads, the
1363 last definition it reads overrides the earlier ones.
1365 @command{autoconf} accepts the following options:
1370 Print a summary of the command line options and exit.
1374 Print the version number of Autoconf and exit.
1378 Report processing steps.
1382 Don't remove the temporary files.
1386 Remake @file{configure} even if newer than its input files.
1388 @item --include=@var{dir}
1390 Append @var{dir} to the include path. Multiple invocations accumulate.
1392 @item --prepend-include=@var{dir}
1394 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1396 @item --output=@var{file}
1397 @itemx -o @var{file}
1398 Save output (script or trace) to @var{file}. The file @option{-} stands
1399 for the standard output.
1401 @item --warnings=@var{category}
1402 @itemx -W @var{category}
1404 Report the warnings related to @var{category} (which can actually be a
1405 comma separated list). @xref{Reporting Messages}, macro
1406 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1411 report all the warnings
1417 treats warnings as errors
1419 @item no-@var{category}
1420 disable warnings falling into @var{category}
1423 Warnings about @samp{syntax} are enabled by default, and the environment
1424 variable @env{WARNINGS}, a comma separated list of categories, is
1425 honored as well. Passing @option{-W @var{category}} actually behaves as if
1426 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1427 you want to disable the defaults and @env{WARNINGS}, but (for example)
1428 enable the warnings about obsolete constructs, you would use @option{-W
1432 @cindex Macro invocation stack
1433 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1434 displays a back trace for errors, but not for warnings; if you want
1435 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1438 @item --trace=@var{macro}[:@var{format}]
1439 @itemx -t @var{macro}[:@var{format}]
1440 Do not create the @command{configure} script, but list the calls to
1441 @var{macro} according to the @var{format}. Multiple @option{--trace}
1442 arguments can be used to list several macros. Multiple @option{--trace}
1443 arguments for a single macro are not cumulative; instead, you should
1444 just make @var{format} as long as needed.
1446 The @var{format} is a regular string, with newlines if desired, and
1447 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1448 @ref{autom4te Invocation}, for details on the @var{format}.
1450 @item --initialization
1452 By default, @option{--trace} does not trace the initialization of the
1453 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1454 results in a noticeable speedup, but can be disabled by this option.
1458 It is often necessary to check the content of a @file{configure.ac}
1459 file, but parsing it yourself is extremely fragile and error-prone. It
1460 is suggested that you rely upon @option{--trace} to scan
1461 @file{configure.ac}. For instance, to find the list of variables that
1462 are substituted, use:
1466 $ @kbd{autoconf -t AC_SUBST}
1467 configure.ac:2:AC_SUBST:ECHO_C
1468 configure.ac:2:AC_SUBST:ECHO_N
1469 configure.ac:2:AC_SUBST:ECHO_T
1470 @i{More traces deleted}
1475 The example below highlights the difference between @samp{$@@},
1476 @samp{$*}, and @samp{$%}.
1480 $ @kbd{cat configure.ac}
1481 AC_DEFINE(This, is, [an
1483 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1490 %: This:is:an [example]
1495 The @var{format} gives you a lot of freedom:
1499 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1500 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1501 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1502 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1503 @i{More traces deleted}
1508 A long @var{separator} can be used to improve the readability of complex
1509 structures, and to ease their parsing (for instance when no single
1510 character is suitable as a separator):
1514 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1515 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1516 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1517 AUTOMAKE|:::::|automake|:::::|$missing_dir
1518 @i{More traces deleted}
1522 @node autoreconf Invocation
1523 @section Using @command{autoreconf} to Update @command{configure} Scripts
1524 @cindex @command{autoreconf}
1526 Installing the various components of the @acronym{GNU} Build System can be
1527 tedious: running @command{autopoint} for Gettext, @command{automake} for
1528 @file{Makefile.in} etc.@: in each directory. It may be needed either
1529 because some tools such as @command{automake} have been updated on your
1530 system, or because some of the sources such as @file{configure.ac} have
1531 been updated, or finally, simply in order to install the @acronym{GNU} Build
1532 System in a fresh tree.
1534 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1535 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1536 @command{autopoint} (when appropriate) repeatedly to update the
1537 @acronym{GNU} Build System in the specified directories and their
1538 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1539 those files that are older than their sources.
1541 If you install a new version of some tool, you can make
1542 @command{autoreconf} remake @emph{all} of the files by giving it the
1543 @option{--force} option.
1545 @xref{Automatic Remaking}, for Make rules to automatically
1546 remake @command{configure} scripts when their source files change. That
1547 method handles the timestamps of configuration header templates
1548 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1549 @option{--localdir=@var{dir}}.
1552 @cindex @command{autopoint}
1553 Gettext supplies the @command{autopoint} command to add translation
1554 infrastructure to a source package. If you use @command{autopoint},
1555 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1556 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1557 Invocation, , Invoking the @code{autopoint} Program, gettext,
1558 @acronym{GNU} @code{gettext} utilities}, for further details.
1561 @command{autoreconf} accepts the following options:
1566 Print a summary of the command line options and exit.
1570 Print the version number of Autoconf and exit.
1573 Print the name of each directory @command{autoreconf} examines and the
1574 commands it runs. If given two or more times, pass @option{--verbose}
1575 to subordinate tools that support it.
1579 Don't remove the temporary files.
1583 Remake even @file{configure} scripts and configuration headers that are
1584 newer than their input files (@file{configure.ac} and, if present,
1589 Install the missing auxiliary files in the package. By default, files
1590 are copied; this can be changed with @option{--symlink}.
1592 If deemed appropriate, this option triggers calls to
1593 @samp{automake --add-missing},
1594 @samp{libtoolize}, @samp{autopoint}, etc.
1596 @item --no-recursive
1597 Do not rebuild files in subdirectories to configure (see @ref{Subdirectories},
1598 macro @code{AC_CONFIG_SUBDIRS}).
1602 When used with @option{--install}, install symbolic links to the missing
1603 auxiliary files instead of copying them.
1607 When the directories were configured, update the configuration by
1608 running @samp{./config.status --recheck && ./config.status}, and then
1611 @item --include=@var{dir}
1613 Append @var{dir} to the include path. Multiple invocations accumulate.
1614 Passed on to @command{autoconf} and @command{autoheader} internally.
1616 @item --prepend-include=@var{dir}
1618 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1619 Passed on to @command{autoconf} and @command{autoheader} internally.
1621 @item --warnings=@var{category}
1622 @itemx -W @var{category}
1624 Report the warnings related to @var{category} (which can actually be a
1625 comma separated list).
1629 related to cross compilation issues.
1632 report the uses of obsolete constructs.
1638 dubious syntactic constructs.
1641 report all the warnings
1647 treats warnings as errors
1649 @item no-@var{category}
1650 disable warnings falling into @var{category}
1653 Warnings about @samp{syntax} are enabled by default, and the environment
1654 variable @env{WARNINGS}, a comma separated list of categories, is
1655 honored as well. Passing @option{-W @var{category}} actually behaves as if
1656 you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If
1657 you want to disable the defaults and @env{WARNINGS}, but (for example)
1658 enable the warnings about obsolete constructs, you would use @option{-W
1662 If you want @command{autoreconf} to pass flags that are not listed here
1663 on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}.
1665 @c ========================================= Initialization and Output Files.
1668 @chapter Initialization and Output Files
1670 Autoconf-generated @command{configure} scripts need some information about
1671 how to initialize, such as how to find the package's source files and
1672 about the output files to produce. The following sections describe the
1673 initialization and the creation of output files.
1676 * Initializing configure:: Option processing etc.
1677 * Notices:: Copyright, version numbers in @command{configure}
1678 * Input:: Where Autoconf should find files
1679 * Output:: Outputting results from the configuration
1680 * Configuration Actions:: Preparing the output based on results
1681 * Configuration Files:: Creating output files
1682 * Makefile Substitutions:: Using output variables in makefiles
1683 * Configuration Headers:: Creating a configuration header file
1684 * Configuration Commands:: Running arbitrary instantiation commands
1685 * Configuration Links:: Links depending on the configuration
1686 * Subdirectories:: Configuring independent packages together
1687 * Default Prefix:: Changing the default installation prefix
1690 @node Initializing configure
1691 @section Initializing @command{configure}
1693 Every @command{configure} script must call @code{AC_INIT} before doing
1694 anything else. The only other required macro is @code{AC_OUTPUT}
1697 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1699 Process any command-line arguments and perform various initializations
1702 Set the name of the @var{package} and its @var{version}. These are
1703 typically used in @option{--version} support, including that of
1704 @command{configure}. The optional argument @var{bug-report} should be
1705 the email to which users should send bug reports. The package
1706 @var{tarname} differs from @var{package}: the latter designates the full
1707 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1708 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1709 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1710 other than alphanumerics and underscores are changed to @samp{-}.
1712 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1713 there should not be any shell computation, but they can be computed by
1716 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1717 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1718 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1721 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1722 @acindex{PACKAGE_NAME}
1723 @ovindex PACKAGE_NAME
1724 @cvindex PACKAGE_NAME
1725 Exactly @var{package}.
1727 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1728 @acindex{PACKAGE_TARNAME}
1729 @ovindex PACKAGE_TARNAME
1730 @cvindex PACKAGE_TARNAME
1731 Exactly @var{tarname}.
1733 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1734 @acindex{PACKAGE_VERSION}
1735 @ovindex PACKAGE_VERSION
1736 @cvindex PACKAGE_VERSION
1737 Exactly @var{version}.
1739 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1740 @acindex{PACKAGE_STRING}
1741 @ovindex PACKAGE_STRING
1742 @cvindex PACKAGE_STRING
1743 Exactly @samp{@var{package} @var{version}}.
1745 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1746 @acindex{PACKAGE_BUGREPORT}
1747 @ovindex PACKAGE_BUGREPORT
1748 @cvindex PACKAGE_BUGREPORT
1749 Exactly @var{bug-report}.
1753 If your @command{configure} script does its own option processing, it
1754 should inspect @samp{$@@} or @samp{$*} immediately after calling
1755 @code{AC_INIT}, because other Autoconf macros liberally use the
1756 @command{set} command to process strings, and this has the side effect
1757 of updating @samp{$@@} and @samp{$*}. However, we suggest that you use
1758 standard macros like @code{AC_ARG_ENABLE} instead of attempting to
1759 implement your own option processing. @xref{Site Configuration}.
1763 @section Notices in @command{configure}
1764 @cindex Notices in @command{configure}
1766 The following macros manage version numbers for @command{configure}
1767 scripts. Using them is optional.
1769 @c FIXME: AC_PREREQ should not be here
1770 @defmac AC_PREREQ (@var{version})
1773 Ensure that a recent enough version of Autoconf is being used. If the
1774 version of Autoconf being used to create @command{configure} is
1775 earlier than @var{version}, print an error message to the standard
1776 error output and exit with failure (exit status is 63). For example:
1779 AC_PREREQ([@value{VERSION}])
1782 This macro is the only macro that may be used before @code{AC_INIT}, but
1783 for consistency, you are invited not to do so.
1786 @defmac AC_COPYRIGHT (@var{copyright-notice})
1788 @cindex Copyright Notice
1789 State that, in addition to the Free Software Foundation's copyright on
1790 the Autoconf macros, parts of your @command{configure} are covered by the
1791 @var{copyright-notice}.
1793 The @var{copyright-notice} shows up in both the head of
1794 @command{configure} and in @samp{configure --version}.
1798 @defmac AC_REVISION (@var{revision-info})
1801 Copy revision stamp @var{revision-info} into the @command{configure}
1802 script, with any dollar signs or double-quotes removed. This macro lets
1803 you put a revision stamp from @file{configure.ac} into @command{configure}
1804 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1805 @command{configure}. That way, you can determine easily which revision of
1806 @file{configure.ac} a particular @command{configure} corresponds to.
1808 For example, this line in @file{configure.ac}:
1810 @c The asis prevents RCS from changing the example in the manual.
1812 AC_REVISION([$@asis{Revision: 1.30 }$])
1816 produces this in @command{configure}:
1820 # From configure.ac Revision: 1.30
1826 @section Finding @command{configure} Input
1829 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1830 @acindex{CONFIG_SRCDIR}
1831 @var{unique-file-in-source-dir} is some file that is in the package's
1832 source directory; @command{configure} checks for this file's existence to
1833 make sure that the directory that it is told contains the source code in
1834 fact does. Occasionally people accidentally specify the wrong directory
1835 with @option{--srcdir}; this is a safety check. @xref{configure
1836 Invocation}, for more information.
1840 @c FIXME: Remove definitively once --install explained.
1842 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1843 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1844 @c to split the macros in several files. In this case, Autoconf must be
1845 @c told which files to load, and in which order.
1847 @c @defmac AC_INCLUDE (@var{file}@dots{})
1848 @c @acindex{INCLUDE}
1849 @c @c FIXME: There is no longer shell globbing.
1850 @c Read the macro definitions that appear in the listed files. A list of
1851 @c space-separated file names or shell globbing patterns is expected. The
1852 @c files are read in the order they're listed.
1854 @c Because the order of definition of macros is important (only the last
1855 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1856 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1857 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1858 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1859 @c the latter case, non-macro lines from included files may end up in the
1860 @c @file{configure} script, whereas in the former case, they'd be discarded
1861 @c just like any text that appear before @code{AC_INIT}.
1864 Packages that do manual configuration or use the @command{install} program
1865 might need to tell @command{configure} where to find some other shell
1866 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1867 it looks are correct for most cases.
1869 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1870 @acindex{CONFIG_AUX_DIR}
1871 Use the auxiliary build tools (e.g., @file{install-sh},
1872 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1873 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1874 These are auxiliary files used in configuration. @var{dir} can be
1875 either absolute or relative to @file{@var{srcdir}}. The default is
1876 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1877 @file{@var{srcdir}/../..}, whichever is the first that contains
1878 @file{install-sh}. The other files are not checked for, so that using
1879 @code{AC_PROG_INSTALL} does not automatically require distributing the
1880 other auxiliary files. It checks for @file{install.sh} also, but that
1881 name is obsolete because some @code{make} have a rule that creates
1882 @file{install} from it if there is no makefile.
1884 The auxiliary directory is commonly named @file{build-aux}.
1885 If you need portability to @acronym{DOS} variants, do not name the
1886 auxiliary directory @file{aux}. @xref{File System Conventions}.
1889 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1890 @acindex{REQUIRE_AUX_FILE}
1891 Declares that @var{file} is expected in the directory defined above. In
1892 Autoconf proper, this macro does nothing: its sole purpose is to be
1893 traced by third-party tools to produce a list of expected auxiliary
1894 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1895 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1896 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1899 Similarly, packages that use @command{aclocal} should declare where
1900 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1902 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1903 @acindex{CONFIG_MACRO_DIR}
1904 Future versions of @command{autopoint}, @command{libtoolize},
1905 @command{aclocal} and @command{autoreconf} will use directory
1906 @var{dir} as the location of additional local Autoconf macros. Be
1907 sure to call this macro directly from @file{configure.ac} so that
1908 tools that install macros for @command{aclocal} can find the
1909 declaration before @option{--trace} can be called safely.
1914 @section Outputting Files
1915 @cindex Outputting files
1917 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1918 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1919 @file{config.status}, which in turn creates the makefiles and any
1920 other files resulting from configuration. This is the only required
1921 macro besides @code{AC_INIT} (@pxref{Input}).
1925 @cindex Instantiation
1926 Generate @file{config.status} and launch it. Call this macro once, at
1927 the end of @file{configure.ac}.
1929 @file{config.status} performs all the configuration actions: all the
1930 output files (see @ref{Configuration Files}, macro
1931 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1932 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1933 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1934 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1935 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1938 The location of your @code{AC_OUTPUT} invocation is the exact point
1939 where configuration actions are taken: any code afterwards is
1940 executed by @code{configure} once @command{config.status} was run. If
1941 you want to bind actions to @command{config.status} itself
1942 (independently of whether @command{configure} is being run), see
1943 @ref{Configuration Commands, , Running Arbitrary Configuration
1947 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1948 @xref{Obsolete Macros}, for a description of the arguments that
1949 @code{AC_OUTPUT} used to support.
1952 If you run @command{make} in subdirectories, you should run it using the
1953 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1954 @code{MAKE} to the name of the @command{make} program plus any options it
1955 was given. (But many do not include in it the values of any variables
1956 set on the command line, so those are not passed on automatically.)
1957 Some old versions of @command{make} do not set this variable. The
1958 following macro allows you to use it even with those versions.
1960 @defmac AC_PROG_MAKE_SET
1961 @acindex{PROG_MAKE_SET}
1963 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1964 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1965 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1966 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1970 If you use this macro, place a line like this in each @file{Makefile.in}
1971 that runs @code{MAKE} on other directories:
1979 @node Configuration Actions
1980 @section Performing Configuration Actions
1981 @cindex Configuration actions
1983 @file{configure} is designed so that it appears to do everything itself,
1984 but there is actually a hidden slave: @file{config.status}.
1985 @file{configure} is in charge of examining your system, but it is
1986 @file{config.status} that actually takes the proper actions based on the
1987 results of @file{configure}. The most typical task of
1988 @file{config.status} is to @emph{instantiate} files.
1990 This section describes the common behavior of the four standard
1991 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1992 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1993 have this prototype:
1995 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1998 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
2002 where the arguments are:
2006 A blank-or-newline-separated list of tags, which are typically the names of
2007 the files to instantiate.
2009 You are encouraged to use literals as @var{tags}. In particular, you
2013 @dots{} && my_foos="$my_foos fooo"
2014 @dots{} && my_foos="$my_foos foooo"
2015 AC_CONFIG_FOOS([$my_foos])
2019 and use this instead:
2022 @dots{} && AC_CONFIG_FOOS([fooo])
2023 @dots{} && AC_CONFIG_FOOS([foooo])
2026 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
2027 special @var{tag} values: they may have the form @samp{@var{output}} or
2028 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
2029 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
2031 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
2032 for example, asks for
2033 the creation of the file @file{Makefile} that contains the expansion of the
2034 output variables in the concatenation of @file{boiler/top.mk} and
2035 @file{boiler/bot.mk}.
2037 The special value @samp{-} might be used to denote the standard output
2038 when used in @var{output}, or the standard input when used in the
2039 @var{inputs}. You most probably don't need to use this in
2040 @file{configure.ac}, but it is convenient when using the command line
2041 interface of @file{./config.status}, see @ref{config.status Invocation},
2044 The @var{inputs} may be absolute or relative file names. In the latter
2045 case they are first looked for in the build tree, and then in the source
2049 Shell commands output literally into @file{config.status}, and
2050 associated with a tag that the user can use to tell @file{config.status}
2051 which the commands to run. The commands are run each time a @var{tag}
2052 request is given to @file{config.status}, typically each time the file
2053 @file{@var{tag}} is created.
2055 The variables set during the execution of @command{configure} are
2056 @emph{not} available here: you first need to set them via the
2057 @var{init-cmds}. Nonetheless the following variables are precomputed:
2061 The name of the top source directory, assuming that the working
2062 directory is the top build directory. This
2063 is what the @command{configure} option @option{--srcdir} sets.
2066 The name of the top source directory, assuming that the working
2067 directory is the current build directory.
2070 @item ac_top_build_prefix
2071 The name of the top build directory, assuming that the working
2072 directory is the current build directory.
2073 It can be empty, or else ends with a slash, so that you may concatenate
2077 The name of the corresponding source directory, assuming that the
2078 working directory is the current build directory.
2082 The @dfn{current} directory refers to the directory (or
2083 pseudo-directory) containing the input part of @var{tags}. For
2087 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
2091 with @option{--srcdir=../package} produces the following values:
2094 # Argument of --srcdir
2096 # Reversing deep/dir
2097 ac_top_build_prefix='../../'
2098 # Concatenation of $ac_top_build_prefix and srcdir
2099 ac_top_srcdir='../../../package'
2100 # Concatenation of $ac_top_srcdir and deep/dir
2101 ac_srcdir='../../../package/deep/dir'
2105 independently of @samp{in/in.in}.
2108 Shell commands output @emph{unquoted} near the beginning of
2109 @file{config.status}, and executed each time @file{config.status} runs
2110 (regardless of the tag). Because they are unquoted, for example,
2111 @samp{$var} is output as the value of @code{var}. @var{init-cmds}
2112 is typically used by @file{configure} to give @file{config.status} some
2113 variables it needs to run the @var{commands}.
2115 You should be extremely cautious in your variable names: all the
2116 @var{init-cmds} share the same name space and may overwrite each other
2117 in unpredictable ways. Sorry@enddots{}
2120 All these macros can be called multiple times, with different
2121 @var{tag} values, of course!
2124 @node Configuration Files
2125 @section Creating Configuration Files
2126 @cindex Creating configuration files
2127 @cindex Configuration file creation
2129 Be sure to read the previous section, @ref{Configuration Actions}.
2131 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2132 @acindex{CONFIG_FILES}
2133 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2134 file (by default @file{@var{file}.in}), substituting the output variable
2136 @c Before we used to have this feature, which was later rejected
2137 @c because it complicates the writing of makefiles:
2138 @c If the file would be unchanged, it is left untouched, to preserve
2140 This macro is one of the instantiating macros; see @ref{Configuration
2141 Actions}. @xref{Makefile Substitutions}, for more information on using
2142 output variables. @xref{Setting Output Variables}, for more information
2143 on creating them. This macro creates the directory that the file is in
2144 if it doesn't exist. Usually, makefiles are created this way,
2145 but other files, such as @file{.gdbinit}, can be specified as well.
2147 Typical calls to @code{AC_CONFIG_FILES} look like this:
2150 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2151 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2154 You can override an input file name by appending to @var{file} a
2155 colon-separated list of input files. Examples:
2158 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2159 [lib/Makefile:boiler/lib.mk])
2163 Doing this allows you to keep your file names acceptable to
2164 @acronym{DOS} variants, or
2165 to prepend and/or append boilerplate to the file.
2170 @node Makefile Substitutions
2171 @section Substitutions in Makefiles
2172 @cindex Substitutions in makefiles
2173 @cindex Makefile substitutions
2175 Each subdirectory in a distribution that contains something to be
2176 compiled or installed should come with a file @file{Makefile.in}, from
2177 which @command{configure} creates a file @file{Makefile} in that directory.
2178 To create @file{Makefile}, @command{configure} performs a simple variable
2179 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2180 @file{Makefile.in} with the value that @command{configure} has determined
2181 for that variable. Variables that are substituted into output files in
2182 this way are called @dfn{output variables}. They are ordinary shell
2183 variables that are set in @command{configure}. To make @command{configure}
2184 substitute a particular variable into the output files, the macro
2185 @code{AC_SUBST} must be called with that variable name as an argument.
2186 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2187 left unchanged. @xref{Setting Output Variables}, for more information
2188 on creating output variables with @code{AC_SUBST}.
2190 A software package that uses a @command{configure} script should be
2191 distributed with a file @file{Makefile.in}, but no makefile; that
2192 way, the user has to properly configure the package for the local system
2193 before compiling it.
2195 @xref{Makefile Conventions, , Makefile Conventions, standards, The
2196 @acronym{GNU} Coding Standards}, for more information on what to put in
2200 * Preset Output Variables:: Output variables that are always set
2201 * Installation Directory Variables:: Other preset output variables
2202 * Changed Directory Variables:: Warnings about @file{datarootdir}
2203 * Build Directories:: Supporting multiple concurrent compiles
2204 * Automatic Remaking:: Makefile rules for configuring
2207 @node Preset Output Variables
2208 @subsection Preset Output Variables
2209 @cindex Output variables
2211 Some output variables are preset by the Autoconf macros. Some of the
2212 Autoconf macros set additional output variables, which are mentioned in
2213 the descriptions for those macros. @xref{Output Variable Index}, for a
2214 complete list of output variables. @xref{Installation Directory
2215 Variables}, for the list of the preset ones related to installation
2216 directories. Below are listed the other preset ones. They all are
2217 precious variables (@pxref{Setting Output Variables},
2220 @c Just say no to ASCII sorting! We're humans, not computers.
2221 @c These variables are listed as they would be in a dictionary:
2228 Debugging and optimization options for the C compiler. If it is not set
2229 in the environment when @command{configure} runs, the default value is set
2230 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2231 uses this variable when compiling or linking programs to test for C features.
2233 If a compiler option affects only the behavior of the preprocessor
2234 (e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS}
2235 instead. If it affects only the linker (e.g., @option{-L
2236 @var{directory}}), it should be put into @code{LDFLAGS} instead. If it
2237 affects only the compiler proper, @code{CFLAGS} is the natural home for
2238 it. If an option affects multiple phases of the compiler, though,
2239 matters get tricky. One approach to put such options directly into
2240 @code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both
2241 @code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}.
2245 @defvar configure_input
2246 @ovindex configure_input
2247 A comment saying that the file was generated automatically by
2248 @command{configure} and giving the name of the input file.
2249 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2250 of every makefile it creates. For other files, you should
2251 reference this variable in a comment at the top of each input file. For
2252 example, an input shell script should begin like this:
2256 # @@configure_input@@
2260 The presence of that line also reminds people editing the file that it
2261 needs to be processed by @command{configure} in order to be used.
2266 Preprocessor options for the C, C++, and Objective C preprocessors and
2268 it is not set in the environment when @command{configure} runs, the default
2269 value is empty. @command{configure} uses this variable when preprocessing
2270 or compiling programs to test for C, C++, and Objective C features.
2272 This variable's contents should contain options like @option{-I},
2273 @option{-D}, and @option{-U} that affect only the behavior of the
2274 preprocessor. Please see the explanation of @code{CFLAGS} for what you
2275 can do if an option affects other phases of the compiler as well.
2277 Currently, @command{configure} always links as part of a single
2278 invocation of the compiler that also preprocesses and compiles, so it
2279 uses this variable also when linking programs. However, it is unwise to
2280 depend on this behavior because the @acronym{GNU} coding standards do
2281 not require it and many packages do not use @code{CPPFLAGS} when linking
2284 @xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS}
2290 Debugging and optimization options for the C++ compiler. It acts like
2291 @code{CFLAGS}, but for C++ instead of C.
2296 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2297 is called, @command{configure} replaces @samp{@@DEFS@@} with
2298 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2299 variable is not defined while @command{configure} is performing its tests,
2300 only when creating the output files. @xref{Setting Output Variables}, for
2301 how to check the results of previous tests.
2310 How does one suppress the trailing newline from @command{echo} for
2311 question-answer message pairs? These variables provide a way:
2314 echo $ECHO_N "And the winner is... $ECHO_C"
2316 echo "$@{ECHO_T@}dead."
2320 Some old and uncommon @command{echo} implementations offer no means to
2321 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2327 Debugging and optimization options for the Erlang compiler. If it is not set
2328 in the environment when @command{configure} runs, the default value is empty.
2329 @command{configure} uses this variable when compiling
2330 programs to test for Erlang features.
2335 Debugging and optimization options for the Fortran compiler. If it
2336 is not set in the environment when @command{configure} runs, the default
2337 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2338 @command{configure} uses this variable when compiling or linking
2339 programs to test for Fortran features.
2344 Debugging and optimization options for the Fortran 77 compiler. If it
2345 is not set in the environment when @command{configure} runs, the default
2346 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2347 @command{configure} uses this variable when compiling or linking
2348 programs to test for Fortran 77 features.
2353 Options for the linker. If it is not set
2354 in the environment when @command{configure} runs, the default value is empty.
2355 @command{configure} uses this variable when linking programs to test for
2356 C, C++, Objective C, and Fortran features.
2358 This variable's contents should contain options like @option{-s} and
2359 @option{-L} that affect only the behavior of the linker. Please see the
2360 explanation of @code{CFLAGS} for what you can do if an option also
2361 affects other phases of the compiler.
2363 Don't use this variable to pass library names
2364 (@option{-l}) to the linker; use @code{LIBS} instead.
2369 @option{-l} options to pass to the linker. The default value is empty,
2370 but some Autoconf macros may prepend extra libraries to this variable if
2371 those libraries are found and provide necessary functions, see
2372 @ref{Libraries}. @command{configure} uses this variable when linking
2373 programs to test for C, C++, and Fortran features.
2378 Debugging and optimization options for the Objective C compiler. It
2379 acts like @code{CFLAGS}, but for Objective C instead of C.
2384 Rigorously equal to @samp{.}. Added for symmetry only.
2387 @defvar abs_builddir
2388 @ovindex abs_builddir
2389 Absolute name of @code{builddir}.
2392 @defvar top_builddir
2393 @ovindex top_builddir
2394 The relative name of the top level of the current build tree. In the
2395 top-level directory, this is the same as @code{builddir}.
2398 @defvar abs_top_builddir
2399 @ovindex abs_top_builddir
2400 Absolute name of @code{top_builddir}.
2405 The relative name of the directory that contains the source code for
2411 Absolute name of @code{srcdir}.
2416 The relative name of the top-level source code directory for the
2417 package. In the top-level directory, this is the same as @code{srcdir}.
2420 @defvar abs_top_srcdir
2421 @ovindex abs_top_srcdir
2422 Absolute name of @code{top_srcdir}.
2425 @node Installation Directory Variables
2426 @subsection Installation Directory Variables
2427 @cindex Installation directories
2428 @cindex Directories, installation
2430 The following variables specify the directories for
2431 package installation, see @ref{Directory Variables, , Variables for
2432 Installation Directories, standards, The @acronym{GNU} Coding
2433 Standards}, for more information. See the end of this section for
2434 details on when and how to use these variables.
2438 The directory for installing executables that users run.
2443 The directory for installing idiosyncratic read-only
2444 architecture-independent data.
2448 @ovindex datarootdir
2449 The root of the directory tree for read-only architecture-independent
2455 The directory for installing documentation files (other than Info and
2461 The directory for installing documentation files in DVI format.
2465 @ovindex exec_prefix
2466 The installation prefix for architecture-dependent files. By default
2467 it's the same as @var{prefix}. You should avoid installing anything
2468 directly to @var{exec_prefix}. However, the default value for
2469 directories containing architecture-dependent files should be relative
2470 to @var{exec_prefix}.
2475 The directory for installing HTML documentation.
2480 The directory for installing C header files.
2485 The directory for installing documentation in Info format.
2490 The directory for installing object code libraries.
2495 The directory for installing executables that other programs run.
2500 The directory for installing locale-dependent but
2501 architecture-independent data, such as message catalogs. This directory
2502 usually has a subdirectory per locale.
2505 @defvar localstatedir
2506 @ovindex localstatedir
2507 The directory for installing modifiable single-machine data.
2512 The top-level directory for installing documentation in man format.
2515 @defvar oldincludedir
2516 @ovindex oldincludedir
2517 The directory for installing C header files for non-@acronym{GCC} compilers.
2522 The directory for installing PDF documentation.
2527 The common installation prefix for all files. If @var{exec_prefix}
2528 is defined to a different value, @var{prefix} is used only for
2529 architecture-independent files.
2534 The directory for installing PostScript documentation.
2539 The directory for installing executables that system
2543 @defvar sharedstatedir
2544 @ovindex sharedstatedir
2545 The directory for installing modifiable architecture-independent data.
2550 The directory for installing read-only single-machine data.
2554 Most of these variables have values that rely on @code{prefix} or
2555 @code{exec_prefix}. It is deliberate that the directory output
2556 variables keep them unexpanded: typically @samp{@@datarootdir@@} is
2557 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2558 @samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}.
2560 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2565 she can still specify a different prefix from the one specified to
2566 @command{configure}, in which case, if needed, the package should hard
2567 code dependencies corresponding to the make-specified prefix.
2570 she can specify a different installation location, in which case the
2571 package @emph{must} still depend on the location which was compiled in
2572 (i.e., never recompile when @samp{make install} is run). This is an
2573 extremely important feature, as many people may decide to install all
2574 the files of a package grouped together, and then install links from
2575 the final locations to there.
2578 In order to support these features, it is essential that
2579 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2580 depend upon the current value of @code{prefix}.
2582 A corollary is that you should not use these variables except in
2583 makefiles. For instance, instead of trying to evaluate @code{datadir}
2584 in @file{configure} and hard-coding it in makefiles using
2585 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2587 @option{-DDATADIR='$(datadir)'} to your makefile's definition of
2588 @code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake).
2590 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2591 @code{datadir} and friends in your shell scripts and other files; instead,
2592 let @command{make} manage their replacement. For instance Autoconf
2593 ships templates of its shell scripts ending with @samp{.in}, and uses a
2594 makefile snippet similar to the following to build scripts like
2595 @command{autoheader} and @command{autom4te}:
2600 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2601 -e 's|@@prefix[@@]|$(prefix)|g'
2605 autoheader autom4te: Makefile
2607 $(edit) '$(srcdir)/$@@.in' >$@@.tmp
2614 autoheader: $(srcdir)/autoheader.in
2615 autom4te: $(srcdir)/autom4te.in
2619 Some details are noteworthy:
2622 @item @samp{@@datadir[@@]}
2623 The brackets prevent @command{configure} from replacing
2624 @samp{@@datadir@@} in the Sed expression itself.
2625 Brackets are preferable to a backslash here, since
2626 Posix says @samp{\@@} is not portable.
2628 @item @samp{$(pkgdatadir)}
2629 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2633 Don't use @samp{/} in the Sed expressions that replace file names since
2635 variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}.
2636 Use a shell metacharacter instead, such as @samp{|}.
2638 @item special characters
2639 File names, file name components, and the value of @code{VPATH} should
2640 not contain shell metacharacters or white
2641 space. @xref{Special Chars in Variables}.
2643 @item dependency on @file{Makefile}
2644 Since @code{edit} uses values that depend on the configuration specific
2645 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2646 the output depends on @file{Makefile}, not @file{configure.ac}.
2649 The main rule is generic, and uses @samp{$@@} extensively to
2650 avoid the need for multiple copies of the rule.
2652 @item Separated dependencies and single suffix rules
2653 You can't use them! The above snippet cannot be (portably) rewritten
2657 autoconf autoheader: Makefile
2667 @xref{Single Suffix Rules}, for details.
2669 @item @samp{$(srcdir)}
2670 Be sure to specify the name of the source directory,
2671 otherwise the package won't support separated builds.
2674 For the more specific installation of Erlang libraries, the following variables
2677 @defvar ERLANG_INSTALL_LIB_DIR
2678 @ovindex ERLANG_INSTALL_LIB_DIR
2679 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
2680 The common parent directory of Erlang library installation directories.
2681 This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR}
2682 macro in @file{configure.ac}.
2685 @defvar ERLANG_INSTALL_LIB_DIR_@var{library}
2686 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
2687 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
2688 The installation directory for Erlang library @var{library}.
2689 This variable is set by calling the
2690 @samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}}
2691 macro in @file{configure.ac}.
2694 @xref{Erlang Libraries}, for details.
2697 @node Changed Directory Variables
2698 @subsection Changed Directory Variables
2699 @cindex @file{datarootdir}
2701 In Autoconf 2.60, the set of directory variables has changed, and the
2702 defaults of some variables have been adjusted
2703 (@pxref{Installation Directory Variables}) to changes in the
2704 @acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and
2705 @file{mandir} are now expressed in terms of @file{datarootdir}. If you are
2706 upgrading from an earlier Autoconf version, you may need to adjust your files
2707 to ensure that the directory variables are substituted correctly
2708 (@pxref{Defining Directories}), and that a definition of @file{datarootdir} is
2709 in place. For example, in a @file{Makefile.in}, adding
2712 datarootdir = @@datarootdir@@
2716 is usually sufficient. If you use Automake to create @file{Makefile.in},
2717 it will add this for you.
2719 To help with the transition, Autoconf warns about files that seem to use
2720 @code{datarootdir} without defining it. In some cases, it then expands
2721 the value of @code{$datarootdir} in substitutions of the directory
2722 variables. The following example shows such a warning:
2725 $ @kbd{cat configure.ac}
2727 AC_CONFIG_FILES([Makefile])
2729 $ @kbd{cat Makefile.in}
2731 datadir = @@datadir@@
2734 configure: creating ./config.status
2735 config.status: creating Makefile
2736 config.status: WARNING:
2737 Makefile.in seems to ignore the --datarootdir setting
2738 $ @kbd{cat Makefile}
2740 datadir = $@{prefix@}/share
2743 Usually one can easily change the file to accommodate both older and newer
2747 $ @kbd{cat Makefile.in}
2749 datarootdir = @@datarootdir@@
2750 datadir = @@datadir@@
2752 configure: creating ./config.status
2753 config.status: creating Makefile
2754 $ @kbd{cat Makefile}
2756 datarootdir = $@{prefix@}/share
2757 datadir = $@{datarootdir@}
2760 @acindex{DATAROOTDIR_CHECKED}
2761 In some cases, however, the checks may not be able to detect that a suitable
2762 initialization of @code{datarootdir} is in place, or they may fail to detect
2763 that such an initialization is necessary in the output file. If, after
2764 auditing your package, there are still spurious @file{configure} warnings about
2765 @code{datarootdir}, you may add the line
2768 AC_DEFUN([AC_DATAROOTDIR_CHECKED])
2772 to your @file{configure.ac} to disable the warnings. This is an exception
2773 to the usual rule that you should not define a macro whose name begins with
2774 @code{AC_} (@pxref{Macro Names}).
2778 @node Build Directories
2779 @subsection Build Directories
2780 @cindex Build directories
2781 @cindex Directories, build
2783 You can support compiling a software package for several architectures
2784 simultaneously from the same copy of the source code. The object files
2785 for each architecture are kept in their own directory.
2787 To support doing this, @command{make} uses the @code{VPATH} variable to
2788 find the files that are in the source directory. @acronym{GNU} Make
2789 and most other recent @command{make} programs can do this. Older
2790 @command{make} programs do not support @code{VPATH}; when using them, the
2791 source code must be in the same directory as the object files.
2793 To support @code{VPATH}, each @file{Makefile.in} should contain two
2794 lines that look like:
2801 Do not set @code{VPATH} to the value of another variable, for example
2802 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2803 variable substitutions on the value of @code{VPATH}.
2805 @command{configure} substitutes the correct value for @code{srcdir} when
2806 it produces @file{Makefile}.
2808 Do not use the @code{make} variable @code{$<}, which expands to the
2809 file name of the file in the source directory (found with @code{VPATH}),
2810 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2811 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2812 versions of @command{make} do not set @code{$<} in explicit rules; they
2813 expand it to an empty value.
2815 Instead, Make command lines should always refer to source
2816 files by prefixing them with @samp{$(srcdir)/}. For example:
2819 time.info: time.texinfo
2820 $(MAKEINFO) '$(srcdir)/time.texinfo'
2823 @node Automatic Remaking
2824 @subsection Automatic Remaking
2825 @cindex Automatic remaking
2826 @cindex Remaking automatically
2828 You can put rules like the following in the top-level @file{Makefile.in}
2829 for a package to automatically update the configuration information when
2830 you change the configuration files. This example includes all of the
2831 optional files, such as @file{aclocal.m4} and those related to
2832 configuration header files. Omit from the @file{Makefile.in} rules for
2833 any of these files that your package does not use.
2835 The @samp{$(srcdir)/} prefix is included because of limitations in the
2836 @code{VPATH} mechanism.
2838 The @file{stamp-} files are necessary because the timestamps of
2839 @file{config.h.in} and @file{config.h} are not changed if remaking
2840 them does not change their contents. This feature avoids unnecessary
2841 recompilation. You should include the file @file{stamp-h.in} your
2842 package's distribution, so that @command{make} considers
2843 @file{config.h.in} up to date. Don't use @command{touch}
2844 (@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
2845 @command{date} would cause needless differences, hence @acronym{CVS}
2850 $(srcdir)/configure: configure.ac aclocal.m4
2851 cd '$(srcdir)' && autoconf
2853 # autoheader might not change config.h.in, so touch a stamp file.
2854 $(srcdir)/config.h.in: stamp-h.in
2855 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2856 cd '$(srcdir)' && autoheader
2857 echo timestamp > '$(srcdir)/stamp-h.in'
2860 stamp-h: config.h.in config.status
2863 Makefile: Makefile.in config.status
2866 config.status: configure
2867 ./config.status --recheck
2872 (Be careful if you copy these lines directly into your makefile, as you
2873 need to convert the indented lines to start with the tab character.)
2875 In addition, you should use
2878 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2882 so @file{config.status} ensures that @file{config.h} is considered up to
2883 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2885 @xref{config.status Invocation}, for more examples of handling
2886 configuration-related dependencies.
2888 @node Configuration Headers
2889 @section Configuration Header Files
2890 @cindex Configuration Header
2891 @cindex @file{config.h}
2893 When a package contains more than a few tests that define C preprocessor
2894 symbols, the command lines to pass @option{-D} options to the compiler
2895 can get quite long. This causes two problems. One is that the
2896 @command{make} output is hard to visually scan for errors. More
2897 seriously, the command lines can exceed the length limits of some
2898 operating systems. As an alternative to passing @option{-D} options to
2899 the compiler, @command{configure} scripts can create a C header file
2900 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2901 macro selects this kind of output. Though it can be called anywhere
2902 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2903 it right after @code{AC_INIT}.
2905 The package should @samp{#include} the configuration header file before
2906 any other header files, to prevent inconsistencies in declarations (for
2907 example, if it redefines @code{const}).
2909 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2910 option (or @option{-I..}; whichever directory contains @file{config.h}).
2911 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2912 the directory of the currently read file, i.e., the source directory, not
2913 the build directory.
2915 With the appropriate @option{-I} option, you can use
2916 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2917 because in the rare case when the source directory contains another
2918 @file{config.h}, the build directory should be searched first.
2921 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2922 @acindex{CONFIG_HEADERS}
2923 @cvindex HAVE_CONFIG_H
2924 This macro is one of the instantiating macros; see @ref{Configuration
2925 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2926 blank-or-newline-separated list @var{header} containing C preprocessor
2927 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2928 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2929 The usual name for @var{header} is @file{config.h}.
2931 If @var{header} already exists and its contents are identical to what
2932 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2933 making some changes in the configuration without needlessly causing
2934 object files that depend on the header file to be recompiled.
2936 Usually the input file is named @file{@var{header}.in}; however, you can
2937 override the input file name by appending to @var{header} a
2938 colon-separated list of input files. Examples:
2941 AC_CONFIG_HEADERS([config.h:config.hin])
2942 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2946 Doing this allows you to keep your file names acceptable to
2947 @acronym{DOS} variants, or
2948 to prepend and/or append boilerplate to the file.
2953 This macro is defined as the name of the first declared config header
2954 and undefined if no config headers have been declared up to this point.
2955 A third-party macro may, for example, require use of a config header
2956 without invoking AC_CONFIG_HEADERS twice, like this:
2959 AC_CONFIG_COMMANDS_PRE(
2960 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2965 @xref{Configuration Actions}, for more details on @var{header}.
2968 * Header Templates:: Input for the configuration headers
2969 * autoheader Invocation:: How to create configuration templates
2970 * Autoheader Macros:: How to specify CPP templates
2973 @node Header Templates
2974 @subsection Configuration Header Templates
2975 @cindex Configuration Header Template
2976 @cindex Header templates
2977 @cindex @file{config.h.in}
2979 Your distribution should contain a template file that looks as you want
2980 the final header file to look, including comments, with @code{#undef}
2981 statements which are used as hooks. For example, suppose your
2982 @file{configure.ac} makes these calls:
2985 AC_CONFIG_HEADERS([conf.h])
2986 AC_CHECK_HEADERS([unistd.h])
2990 Then you could have code like the following in @file{conf.h.in}. On
2991 systems that have @file{unistd.h}, @command{configure} defines
2992 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is
2993 commented out (in case the system predefines that symbol).
2997 /* Define as 1 if you have unistd.h. */
2998 #undef HAVE_UNISTD_H
3002 Pay attention that @samp{#undef} is in the first column, and there is
3003 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
3004 then decode the configuration header using the preprocessor directives:
3011 # include <unistd.h>
3013 /* We are in trouble. */
3018 The use of old form templates, with @samp{#define} instead of
3019 @samp{#undef} is strongly discouraged. Similarly with old templates
3020 with comments on the same line as the @samp{#undef}. Anyway, putting
3021 comments in preprocessor macros has never been a good idea.
3023 Since it is a tedious task to keep a template header up to date, you may
3024 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
3027 @node autoheader Invocation
3028 @subsection Using @command{autoheader} to Create @file{config.h.in}
3029 @cindex @command{autoheader}
3031 The @command{autoheader} program can create a template file of C
3032 @samp{#define} statements for @command{configure} to use. If
3033 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
3034 @command{autoheader} creates @file{@var{file}.in}; if multiple file
3035 arguments are given, the first one is used. Otherwise,
3036 @command{autoheader} creates @file{config.h.in}.
3038 In order to do its job, @command{autoheader} needs you to document all
3039 of the symbols that you might use. Typically this is done via an
3040 @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument
3041 is a literal symbol and whose third argument describes the symbol
3042 (@pxref{Defining Symbols}). Alternatively, you can use
3043 @code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a
3044 suitable input file for a subsequent configuration header file.
3045 Symbols defined by Autoconf's builtin tests are already documented properly;
3046 you need to document only those that you
3049 You might wonder why @command{autoheader} is needed: after all, why
3050 would @command{configure} need to ``patch'' a @file{config.h.in} to
3051 produce a @file{config.h} instead of just creating @file{config.h} from
3052 scratch? Well, when everything rocks, the answer is just that we are
3053 wasting our time maintaining @command{autoheader}: generating
3054 @file{config.h} directly is all that is needed. When things go wrong,
3055 however, you'll be thankful for the existence of @command{autoheader}.
3057 The fact that the symbols are documented is important in order to
3058 @emph{check} that @file{config.h} makes sense. The fact that there is a
3059 well-defined list of symbols that should be defined (or not) is
3060 also important for people who are porting packages to environments where
3061 @command{configure} cannot be run: they just have to @emph{fill in the
3064 But let's come back to the point: the invocation of @command{autoheader}@dots{}
3066 If you give @command{autoheader} an argument, it uses that file instead
3067 of @file{configure.ac} and writes the header file to the standard output
3068 instead of to @file{config.h.in}. If you give @command{autoheader} an
3069 argument of @option{-}, it reads the standard input instead of
3070 @file{configure.ac} and writes the header file to the standard output.
3072 @command{autoheader} accepts the following options:
3077 Print a summary of the command line options and exit.
3081 Print the version number of Autoconf and exit.
3085 Report processing steps.
3089 Don't remove the temporary files.
3093 Remake the template file even if newer than its input files.
3095 @item --include=@var{dir}
3097 Append @var{dir} to the include path. Multiple invocations accumulate.
3099 @item --prepend-include=@var{dir}
3101 Prepend @var{dir} to the include path. Multiple invocations accumulate.
3103 @item --warnings=@var{category}
3104 @itemx -W @var{category}
3106 Report the warnings related to @var{category} (which can actually be a
3107 comma separated list). Current categories include:
3111 report the uses of obsolete constructs
3114 report all the warnings
3120 treats warnings as errors
3122 @item no-@var{category}
3123 disable warnings falling into @var{category}
3130 @node Autoheader Macros
3131 @subsection Autoheader Macros
3132 @cindex Autoheader macros
3134 @command{autoheader} scans @file{configure.ac} and figures out which C
3135 preprocessor symbols it might define. It knows how to generate
3136 templates for symbols defined by @code{AC_CHECK_HEADERS},
3137 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
3138 symbol, you must define a template for it. If there are missing
3139 templates, @command{autoheader} fails with an error message.
3141 The simplest way to create a template for a @var{symbol} is to supply
3142 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
3143 @ref{Defining Symbols}. You may also use one of the following macros.
3145 @defmac AH_VERBATIM (@var{key}, @var{template})
3147 Tell @command{autoheader} to include the @var{template} as-is in the header
3148 template file. This @var{template} is associated with the @var{key},
3149 which is used to sort all the different templates and guarantee their
3150 uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}.
3155 AH_VERBATIM([_GNU_SOURCE],
3156 [/* Enable GNU extensions on systems that have them. */
3158 # define _GNU_SOURCE
3164 @defmac AH_TEMPLATE (@var{key}, @var{description})
3166 Tell @command{autoheader} to generate a template for @var{key}. This macro
3167 generates standard templates just like @code{AC_DEFINE} when a
3168 @var{description} is given.
3173 AH_TEMPLATE([CRAY_STACKSEG_END],
3174 [Define to one of _getb67, GETB67, getb67
3175 for Cray-2 and Cray-YMP systems. This
3176 function is required for alloca.c support
3181 generates the following template, with the description properly
3185 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
3186 Cray-YMP systems. This function is required for alloca.c
3187 support on those systems. */
3188 #undef CRAY_STACKSEG_END
3193 @defmac AH_TOP (@var{text})
3195 Include @var{text} at the top of the header template file.
3199 @defmac AH_BOTTOM (@var{text})
3201 Include @var{text} at the bottom of the header template file.
3205 @node Configuration Commands
3206 @section Running Arbitrary Configuration Commands
3207 @cindex Configuration commands
3208 @cindex Commands for configuration
3210 You can execute arbitrary commands before, during, and after
3211 @file{config.status} is run. The three following macros accumulate the
3212 commands to run when they are called multiple times.
3213 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
3214 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
3216 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3217 @acindex{CONFIG_COMMANDS}
3218 Specify additional shell commands to run at the end of
3219 @file{config.status}, and shell commands to initialize any variables
3220 from @command{configure}. Associate the commands with @var{tag}.
3221 Since typically the @var{cmds} create a file, @var{tag} should
3222 naturally be the name of that file. If needed, the directory hosting
3223 @var{tag} is created. This macro is one of the instantiating macros;
3224 see @ref{Configuration Actions}.
3226 Here is an unrealistic example:
3229 AC_CONFIG_COMMANDS([fubar],
3230 [echo this is extra $fubar, and so on.],
3234 Here is a better one:
3236 AC_CONFIG_COMMANDS([timestamp], [date >timestamp])
3240 The following two macros look similar, but in fact they are not of the same
3241 breed: they are executed directly by @file{configure}, so you cannot use
3242 @file{config.status} to rerun them.
3244 @c Yet it is good to leave them here. The user sees them together and
3245 @c decides which best fits their needs.
3247 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
3248 @acindex{CONFIG_COMMANDS_PRE}
3249 Execute the @var{cmds} right before creating @file{config.status}.
3251 This macro presents the last opportunity to call @code{AC_SUBST},
3252 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3255 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3256 @acindex{CONFIG_COMMANDS_POST}
3257 Execute the @var{cmds} right after creating @file{config.status}.
3263 @node Configuration Links
3264 @section Creating Configuration Links
3265 @cindex Configuration links
3266 @cindex Links for configuration
3268 You may find it convenient to create links whose destinations depend upon
3269 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3270 creation of relative symbolic links can be delicate when the package is
3271 built in a directory different from the source directory.
3273 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3274 @acindex{CONFIG_LINKS}
3276 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3277 the corresponding link name @var{dest}. Makes a symbolic link if
3278 possible, otherwise a hard link if possible, otherwise a copy. The
3279 @var{dest} and @var{source} names should be relative to the top level
3280 source or build directory. This macro is one of the instantiating
3281 macros; see @ref{Configuration Actions}.
3283 For example, this call:
3286 AC_CONFIG_LINKS([host.h:config/$machine.h
3287 object.h:config/$obj_format.h])
3291 creates in the current directory @file{host.h} as a link to
3292 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3293 link to @file{@var{srcdir}/config/$obj_format.h}.
3295 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3296 impossible for @samp{config.status} to guess the links to establish.
3300 ./config.status host.h object.h
3303 to create the links.
3308 @node Subdirectories
3309 @section Configuring Other Packages in Subdirectories
3310 @cindex Configure subdirectories
3311 @cindex Subdirectory configure
3313 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3314 makefiles in subdirectories. However, @command{configure} scripts
3315 that control more than one independent package can use
3316 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3317 packages in subdirectories.
3319 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3320 @acindex{CONFIG_SUBDIRS}
3322 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3323 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3324 be a literal, i.e., please do not use:
3327 if test "$package_foo_enabled" = yes; then
3328 $my_subdirs="$my_subdirs foo"
3330 AC_CONFIG_SUBDIRS([$my_subdirs])
3334 because this prevents @samp{./configure --help=recursive} from
3335 displaying the options of the package @code{foo}. Instead, you should
3339 if test "$package_foo_enabled" = yes; then
3340 AC_CONFIG_SUBDIRS([foo])
3344 If a given @var{dir} is not found, an error is reported: if the
3345 subdirectory is optional, write:
3348 if test -d "$srcdir/foo"; then
3349 AC_CONFIG_SUBDIRS([foo])
3353 @c NB: Yes, below we mean configure.in, not configure.ac.
3354 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3355 of @command{configure}. This is for packages that might use a
3356 non-Autoconf script @command{Configure}, which can't be called through a
3357 wrapper @command{configure} since it would be the same file on
3358 case-insensitive file systems. Likewise, if a @var{dir} contains
3359 @file{configure.in} but no @command{configure}, the Cygnus
3360 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3362 The subdirectory @command{configure} scripts are given the same command
3363 line options that were given to this @command{configure} script, with minor
3364 changes if needed, which include:
3368 adjusting a relative name for the cache file;
3371 adjusting a relative name for the source directory;
3374 propagating the current value of @code{$prefix}, including if it was
3375 defaulted, and if the default values of the top level and of the subdirectory
3376 @file{configure} differ.
3379 This macro also sets the output variable @code{subdirs} to the list of
3380 directories @samp{@var{dir} @dots{}}. Make rules can use
3381 this variable to determine which subdirectories to recurse into.
3383 This macro may be called multiple times.
3386 @node Default Prefix
3387 @section Default Prefix
3388 @cindex Install prefix
3389 @cindex Prefix for install
3391 By default, @command{configure} sets the prefix for files it installs to
3392 @file{/usr/local}. The user of @command{configure} can select a different
3393 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3394 There are two ways to change the default: when creating
3395 @command{configure}, and when running it.
3397 Some software packages might want to install in a directory other than
3398 @file{/usr/local} by default. To accomplish that, use the
3399 @code{AC_PREFIX_DEFAULT} macro.
3401 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3402 @acindex{PREFIX_DEFAULT}
3403 Set the default installation prefix to @var{prefix} instead of
3407 It may be convenient for users to have @command{configure} guess the
3408 installation prefix from the location of a related program that they
3409 have already installed. If you wish to do that, you can call
3410 @code{AC_PREFIX_PROGRAM}.
3412 @defmac AC_PREFIX_PROGRAM (@var{program})
3413 @acindex{PREFIX_PROGRAM}
3414 If the user did not specify an installation prefix (using the
3415 @option{--prefix} option), guess a value for it by looking for
3416 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3417 is found, set the prefix to the parent of the directory containing
3418 @var{program}, else default the prefix as described above
3419 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3420 @var{program} is @code{gcc} and the @env{PATH} contains
3421 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3426 @c ======================================================== Existing tests
3428 @node Existing Tests
3429 @chapter Existing Tests
3431 These macros test for particular system features that packages might
3432 need or want to use. If you need to test for a kind of feature that
3433 none of these macros check for, you can probably do it by calling
3434 primitive test macros with appropriate arguments (@pxref{Writing
3437 These tests print messages telling the user which feature they're
3438 checking for, and what they find. They cache their results for future
3439 @command{configure} runs (@pxref{Caching Results}).
3441 Some of these macros set output variables. @xref{Makefile
3442 Substitutions}, for how to get their values. The phrase ``define
3443 @var{name}'' is used below as a shorthand to mean ``define the C
3444 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3445 Symbols}, for how to get those symbol definitions into your program.
3448 * Common Behavior:: Macros' standard schemes
3449 * Alternative Programs:: Selecting between alternative programs
3450 * Files:: Checking for the existence of files
3451 * Libraries:: Library archives that might be missing
3452 * Library Functions:: C library functions that might be missing
3453 * Header Files:: Header files that might be missing
3454 * Declarations:: Declarations that may be missing
3455 * Structures:: Structures or members that might be missing
3456 * Types:: Types that might be missing
3457 * Compilers and Preprocessors:: Checking for compiling programs
3458 * System Services:: Operating system services
3459 * Posix Variants:: Special kludges for specific Posix variants
3460 * Erlang Libraries:: Checking for the existence of Erlang libraries
3463 @node Common Behavior
3464 @section Common Behavior
3465 @cindex Common autoconf behavior
3467 Much effort has been expended to make Autoconf easy to learn. The most
3468 obvious way to reach this goal is simply to enforce standard interfaces
3469 and behaviors, avoiding exceptions as much as possible. Because of
3470 history and inertia, unfortunately, there are still too many exceptions
3471 in Autoconf; nevertheless, this section describes some of the common
3475 * Standard Symbols:: Symbols defined by the macros
3476 * Default Includes:: Includes used by the generic macros
3479 @node Standard Symbols
3480 @subsection Standard Symbols
3481 @cindex Standard symbols
3483 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3484 their test transform their @var{argument} values to a standard alphabet.
3485 First, @var{argument} is converted to upper case and any asterisks
3486 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3487 that are not alphanumeric are converted to underscores.
3492 AC_CHECK_TYPES([struct $Expensive*])
3496 defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3500 @node Default Includes
3501 @subsection Default Includes
3502 @cindex Default includes
3503 @cindex Includes, default
3505 Several tests depend upon a set of header files. Since these headers
3506 are not universally available, tests actually have to provide a set of
3507 protected includes, such as:
3511 #if TIME_WITH_SYS_TIME
3512 # include <sys/time.h>
3515 # if HAVE_SYS_TIME_H
3516 # include <sys/time.h>
3525 Unless you know exactly what you are doing, you should avoid using
3526 unconditional includes, and check the existence of the headers you
3527 include beforehand (@pxref{Header Files}).
3529 Most generic macros use the following macro to provide the default set
3532 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3533 @acindex{INCLUDES_DEFAULT}
3534 Expand to @var{include-directives} if defined, otherwise to:
3539 #if HAVE_SYS_TYPES_H
3540 # include <sys/types.h>
3543 # include <sys/stat.h>
3546 # include <stdlib.h>
3547 # include <stddef.h>
3550 # include <stdlib.h>
3554 # if !STDC_HEADERS && HAVE_MEMORY_H
3555 # include <memory.h>
3557 # include <string.h>
3560 # include <strings.h>
3563 # include <inttypes.h>
3566 # include <stdint.h>
3569 # include <unistd.h>
3574 If the default includes are used, then check for the presence of these
3575 headers and their compatibility, i.e., you don't need to run
3576 @code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc.
3578 These headers are checked for in the same order as they are included.
3579 For instance, on some systems @file{string.h} and @file{strings.h} both
3580 exist, but conflict. Then @code{HAVE_STRING_H} is defined, not
3581 @code{HAVE_STRINGS_H}.
3584 @node Alternative Programs
3585 @section Alternative Programs
3586 @cindex Programs, checking
3588 These macros check for the presence or behavior of particular programs.
3589 They are used to choose between several alternative programs and to
3590 decide what to do once one has been chosen. If there is no macro
3591 specifically defined to check for a program you need, and you don't need
3592 to check for any special properties of it, then you can use one of the
3593 general program-check macros.
3596 * Particular Programs:: Special handling to find certain programs
3597 * Generic Programs:: How to find other programs
3600 @node Particular Programs
3601 @subsection Particular Program Checks
3603 These macros check for particular programs---whether they exist, and
3604 in some cases whether they support certain features.
3609 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3610 order, and set output variable @code{AWK} to the first one that is found.
3611 It tries @code{gawk} first because that is reported to be the
3612 best implementation.
3615 @defmac AC_PROG_GREP
3618 Look for the best available @code{grep} or @code{ggrep} that accepts the
3619 longest input lines possible, and that supports multiple @option{-e} options.
3620 Set the output variable @code{GREP} to whatever is chosen.
3621 @xref{Limitations of Usual Tools}, for more information about
3622 portability problems with the @command{grep} command family.
3625 @defmac AC_PROG_EGREP
3626 @acindex{PROG_EGREP}
3628 Check whether @code{$GREP -E} works, or else look for the best available
3629 @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
3630 Set the output variable @code{EGREP} to whatever is chosen.
3633 @defmac AC_PROG_FGREP
3634 @acindex{PROG_FGREP}
3636 Check whether @code{$GREP -F} works, or else look for the best available
3637 @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
3638 Set the output variable @code{FGREP} to whatever is chosen.
3641 @defmac AC_PROG_INSTALL
3642 @acindex{PROG_INSTALL}
3644 @ovindex INSTALL_PROGRAM
3645 @ovindex INSTALL_DATA
3646 @ovindex INSTALL_SCRIPT
3647 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3648 @command{install} program, if one is found in the current @env{PATH}.
3649 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3650 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3651 default directories) to determine @var{dir} (@pxref{Output}). Also set
3652 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3653 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3655 This macro screens out various instances of @command{install} known not to
3656 work. It prefers to find a C program rather than a shell script, for
3657 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3658 but that name is obsolete because some @command{make} programs have a rule
3659 that creates @file{install} from it if there is no makefile.
3661 Autoconf comes with a copy of @file{install-sh} that you can use. If
3662 you use @code{AC_PROG_INSTALL}, you must include either
3663 @file{install-sh} or @file{install.sh} in your distribution; otherwise
3664 @command{configure} produces an error message saying it can't find
3665 them---even if the system you're on has a good @command{install} program.
3666 This check is a safety measure to prevent you from accidentally leaving
3667 that file out, which would prevent your package from installing on
3668 systems that don't have a @acronym{BSD}-compatible @command{install} program.
3670 If you need to use your own installation program because it has features
3671 not found in standard @command{install} programs, there is no reason to use
3672 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3673 @file{Makefile.in} files.
3676 @defmac AC_PROG_MKDIR_P
3677 @acindex{AC_PROG_MKDIR_P}
3679 Set output variable @code{MKDIR_P} to a program that ensures that for
3680 each argument, a directory named by this argument exists, creating it
3681 and its parent directories if needed, and without race conditions when
3682 two instances of the program attempt to make the same directory at
3683 nearly the same time.
3685 This macro uses the @samp{mkdir -p} command if possible. Otherwise, it
3686 falls back on invoking @command{install-sh} with the @option{-d} option,
3687 so your package should
3688 contain @file{install-sh} as described under @code{AC_PROG_INSTALL}.
3689 An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10
3690 is vulnerable to race conditions, so if you want to support parallel
3692 different packages into the same directory you need to make sure you
3693 have an up-to-date @file{install-sh}. In particular, be careful about
3694 using @samp{autoreconf -if} if your Automake predates Automake 1.10.
3696 This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming
3697 in M4sh}), but it sets an output variable intended for use in other
3698 files, whereas @code{AS_MKDIR_P} is intended for use in scripts like
3699 @command{configure}. Also, @code{AS_MKDIR_P} does not accept options,
3700 but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile
3701 might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible
3702 directory, and conversely a makefile should use @code{$(MKDIR_P) --
3703 $(FOO)} if @var{FOO} might yield a value that begins with @samp{-}.
3704 Finally, @code{AS_MKDIR_P} does not check for race condition
3705 vulnerability, whereas @code{AC_PROG_MKDIR_P} does.
3712 @cvindex YYTEXT_POINTER
3713 @ovindex LEX_OUTPUT_ROOT
3714 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3715 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3716 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3719 Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3720 of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3721 the base of the file name that the lexer generates; usually
3722 @file{lex.yy}, but sometimes something else. These results vary
3723 according to whether @code{lex} or @code{flex} is being used.
3725 You are encouraged to use Flex in your sources, since it is both more
3726 pleasant to use than plain Lex and the C source it produces is portable.
3727 In order to ensure portability, however, you must either provide a
3728 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3729 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3730 statement in the scanner's source. Once this done, the scanner is
3731 portable (unless @emph{you} felt free to use nonportable constructs) and
3732 does not depend on any library. In this case, and in this case only, it
3733 is suggested that you use this Autoconf snippet:
3737 if test "$LEX" != flex; then
3738 LEX="$SHELL $missing_dir/missing flex"
3739 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3740 AC_SUBST([LEXLIB], [''])
3744 The shell script @command{missing} can be found in the Automake
3747 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3748 (indirectly) this macro twice, which causes an annoying but benign
3749 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3750 of Automake will fix this issue; meanwhile, just ignore this message.
3752 As part of running the test, this macro may delete any file in the
3753 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3756 @defmac AC_PROG_LN_S
3759 If @samp{ln -s} works on the current file system (the operating system
3760 and file system support symbolic links), set the output variable
3761 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3762 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3764 If you make a link in a directory other than the current directory, its
3765 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3766 create links using @samp{$(LN_S)}, either find out which form is used
3767 and adjust the arguments, or always invoke @code{ln} in the directory
3768 where the link is to be created.
3770 In other words, it does not work to do:
3778 (cd /x && $(LN_S) foo bar)
3782 @defmac AC_PROG_RANLIB
3783 @acindex{PROG_RANLIB}
3785 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3786 is found, and otherwise to @samp{:} (do nothing).
3792 Set output variable @code{SED} to a Sed implementation that conforms to
3793 Posix and does not have arbitrary length limits. Report an error if no
3794 acceptable Sed is found. @xref{Limitations of Usual Tools}, for more
3795 information about portability problems with Sed.
3798 @defmac AC_PROG_YACC
3801 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3802 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3803 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3806 @node Generic Programs
3807 @subsection Generic Program and File Checks
3809 These macros are used to find programs not covered by the ``particular''
3810 test macros. If you need to check the behavior of a program as well as
3811 find out whether it is present, you have to write your own test for it
3812 (@pxref{Writing Tests}). By default, these macros use the environment
3813 variable @env{PATH}. If you need to check for a program that might not
3814 be in the user's @env{PATH}, you can pass a modified path to use
3818 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3819 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3822 You are strongly encouraged to declare the @var{variable} passed to
3823 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3824 @code{AC_ARG_VAR}, for more details.
3826 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3827 @acindex{CHECK_PROG}
3828 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3829 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3830 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3831 absolute file name) even if it is the first found in the search path; in
3832 that case, set @var{variable} using the absolute file name of the
3833 @var{prog-to-check-for} found that is not @var{reject}. If
3834 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3838 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3839 @acindex{CHECK_PROGS}
3840 Check for each program in the blank-separated list
3841 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3842 @var{variable} to the name of that program. Otherwise, continue
3843 checking the next program in the list. If none of the programs in the
3844 list are found, set @var{variable} to @var{value-if-not-found}; if
3845 @var{value-if-not-found} is not specified, the value of @var{variable}
3846 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3849 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3850 @acindex{CHECK_TARGET_TOOL}
3851 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3852 with a prefix of the target type as determined by
3853 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3854 If the tool cannot be found with a prefix, and if the build and target
3855 types are equal, then it is also searched for without a prefix.
3857 As noted in @ref{Specifying Names, , Specifying the system type}, the
3858 target is rarely specified, because most of the time it is the same
3859 as the host: it is the type of system for which any compiler tool in
3860 the package produces code. What this macro looks for is,
3861 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3862 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3863 uses to produce objects, archives or executables}.
3866 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3867 @acindex{CHECK_TOOL}
3868 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3869 with a prefix of the host type as determined by
3870 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3871 For example, if the user runs @samp{configure --host=i386-gnu}, then
3874 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3877 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3878 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3879 @env{PATH}, or to @samp{:} if neither program exists.
3881 In the future, when cross-compiling this macro will @emph{only}
3882 accept program names that are prefixed with the host type.
3883 For more information, see @ref{Specifying Names, , Specifying the
3887 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3888 @acindex{CHECK_TARGET_TOOLS}
3889 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3890 @var{progs-to-check-for} are checked with a prefix of the target type as
3891 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3892 (@pxref{Canonicalizing}). If none of the tools can be found with a
3893 prefix, and if the build and target types are equal, then the first one
3894 without a prefix is used. If a tool is found, set @var{variable} to
3895 the name of that program. If none of the tools in the list are found,
3896 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3897 is not specified, the value of @var{variable} is not changed. Calls
3898 @code{AC_SUBST} for @var{variable}.
3901 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3902 @acindex{CHECK_TOOLS}
3903 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3904 @var{progs-to-check-for} are checked with a prefix of the host type as
3905 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3906 (@pxref{Canonicalizing}). If none of the tools can be found with a
3907 prefix, then the first one without a prefix is used. If a tool is found,
3908 set @var{variable} to the name of that program. If none of the tools in
3909 the list are found, set @var{variable} to @var{value-if-not-found}; if
3910 @var{value-if-not-found} is not specified, the value of @var{variable}
3911 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3913 In the future, when cross-compiling this macro will @emph{not}
3914 accept program names that are not prefixed with the host type.
3917 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3919 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3920 name of @var{prog-to-check-for} if found.
3923 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3924 @acindex{PATH_PROGS}
3925 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3926 are found, set @var{variable} to the absolute name of the program
3930 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3931 @acindex{PATH_TARGET_TOOL}
3932 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3933 name of the program if it is found.
3936 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3938 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3939 name of the program if it is found.
3941 In the future, when cross-compiling this macro will @emph{not}
3942 accept program names that are not prefixed with the host type.
3948 @cindex File, checking
3950 You might also need to check for the existence of files. Before using
3951 these macros, ask yourself whether a runtime test might not be a better
3952 solution. Be aware that, like most Autoconf macros, they test a feature
3953 of the host machine, and therefore, they die when cross-compiling.
3955 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3956 @acindex{CHECK_FILE}
3957 Check whether file @var{file} exists on the native system. If it is
3958 found, execute @var{action-if-found}, otherwise do
3959 @var{action-if-not-found}, if given.
3962 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3963 @acindex{CHECK_FILES}
3964 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3965 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3966 for each file found.
3971 @section Library Files
3972 @cindex Library, checking
3974 The following macros check for the presence of certain C, C++, or Fortran
3975 library archive files.
3977 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3979 Test whether the library @var{library} is available by trying to link
3980 a test program that calls function @var{function} with the library.
3981 @var{function} should be a function provided by the library.
3983 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3984 the @var{library} argument.
3986 @var{action-if-found} is a list of shell commands to run if the link
3987 with the library succeeds; @var{action-if-not-found} is a list of shell
3988 commands to run if the link fails. If @var{action-if-found} is not
3989 specified, the default action prepends @option{-l@var{library}} to
3990 @code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all
3991 capitals). This macro is intended to support building @code{LIBS} in
3992 a right-to-left (least-dependent to most-dependent) fashion such that
3993 library dependencies are satisfied as a natural side effect of
3994 consecutive tests. Linkers are sensitive to library ordering
3995 so the order in which @code{LIBS} is generated is important to reliable
3996 detection of libraries.
3998 If linking with @var{library} results in unresolved symbols that would
3999 be resolved by linking with additional libraries, give those libraries
4000 as the @var{other-libraries} argument, separated by spaces:
4001 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4002 that @var{library} is present, because linking the test program
4003 always fails with unresolved symbols. The @var{other-libraries} argument
4004 should be limited to cases where it is desirable to test for one library
4005 in the presence of another that is not already in @code{LIBS}.
4007 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
4008 in some common cases. Many standard functions like @code{gethostbyname}
4009 appear the standard C library on some hosts, and in special libraries
4010 like @code{nsl} on other hosts. On some hosts the special libraries
4011 contain variant implementations that you may not want to use. These
4012 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
4013 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
4017 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
4018 @acindex{SEARCH_LIBS}
4019 Search for a library defining @var{function} if it's not already
4020 available. This equates to calling
4021 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
4022 no libraries, then for each library listed in @var{search-libs}.
4024 Add @option{-l@var{library}} to @code{LIBS} for the first library found
4025 to contain @var{function}, and run @var{action-if-found}. If the
4026 function is not found, run @var{action-if-not-found}.
4028 If linking with @var{library} results in unresolved symbols that would
4029 be resolved by linking with additional libraries, give those libraries
4030 as the @var{other-libraries} argument, separated by spaces:
4031 e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect
4032 that @var{function} is present, because linking the test program
4033 always fails with unresolved symbols.
4038 @node Library Functions
4039 @section Library Functions
4041 The following macros check for particular C library functions.
4042 If there is no macro specifically defined to check for a function you need,
4043 and you don't need to check for any special properties of
4044 it, then you can use one of the general function-check macros.
4047 * Function Portability:: Pitfalls with usual functions
4048 * Particular Functions:: Special handling to find certain functions
4049 * Generic Functions:: How to find other functions
4052 @node Function Portability
4053 @subsection Portability of C Functions
4054 @cindex Portability of C functions
4055 @cindex C function portability
4057 Most usual functions can either be missing, or be buggy, or be limited
4058 on some architectures. This section tries to make an inventory of these
4059 portability issues. By definition, this list always requires
4060 additions. Please help us keeping it as complete as possible.
4065 @prindex @code{exit}
4066 On ancient hosts, @code{exit} returned @code{int}.
4067 This is because @code{exit} predates @code{void}, and there was a long
4068 tradition of it returning @code{int}.
4070 On current hosts, the problem more likely is that @code{exit} is not
4071 declared, due to C++ problems of some sort or another. For this reason
4072 we suggest that test programs not invoke @code{exit}, but return from
4073 @code{main} instead.
4077 @prindex @code{free}
4078 The C standard says a call @code{free (NULL)} does nothing, but
4079 some old systems don't support this (e.g., NextStep).
4085 @prindex @code{isinf}
4086 @prindex @code{isnan}
4087 The C99 standard says that @code{isinf} and @code{isnan} are
4088 macros. On some systems just macros are available
4089 (e.g., @acronym{HP-UX} and Solaris 10), on
4090 some systems both macros and functions (e.g., glibc 2.3.2), and on some
4091 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
4092 these functions are declared in nonstandard headers like
4093 @code{<sunmath.h>} and defined in non-default libraries like
4094 @option{-lm} or @option{-lsunmath}.
4096 The C99 @code{isinf} and @code{isnan} macros work correctly with
4097 @code{long double} arguments, but pre-C99 systems that use functions
4098 typically assume @code{double} arguments. On such a system,
4099 @code{isinf} incorrectly returns true for a finite @code{long double}
4100 argument that is outside the range of @code{double}.
4102 To work around this porting mess, you can use code like the following.
4109 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
4110 : sizeof (x) == sizeof (double) ? isnan_d (x) \
4112 static inline int isnan_f (float x) @{ return x != x; @}
4113 static inline int isnan_d (double x) @{ return x != x; @}
4114 static inline int isnan_ld (long double x) @{ return x != x; @}
4119 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
4120 : sizeof (x) == sizeof (double) ? isinf_d (x) \
4122 static inline int isinf_f (float x) @{ return isnan (x - x); @}
4123 static inline int isinf_d (double x) @{ return isnan (x - x); @}
4124 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
4128 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
4129 compilers that lack the @code{inline} keyword. Some optimizing
4130 compilers mishandle these definitions, but systems with that bug
4131 typically have missing or broken @code{isnan} functions anyway, so it's
4132 probably not worth worrying about.
4136 @prindex @code{malloc}
4137 The C standard says a call @code{malloc (0)} is implementation
4138 dependent. It can return either @code{NULL} or a new non-null pointer.
4139 The latter is more common (e.g., the @acronym{GNU} C Library) but is by
4140 no means universal. @code{AC_FUNC_MALLOC}
4141 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
4145 @prindex @code{putenv}
4146 Posix prefers @code{setenv} to @code{putenv}; among other things,
4147 @code{putenv} is not required of all Posix implementations, but
4150 Posix specifies that @code{putenv} puts the given string directly in
4151 @code{environ}, but some systems make a copy of it instead (e.g.,
4152 glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might
4153 not free it, causing a memory leak (e.g., Free@acronym{BSD} 4).
4155 On some systems @code{putenv ("FOO")} removes @samp{FOO} from the
4156 environment, but this is not standard usage and it dumps core
4157 on some systems (e.g., AIX).
4159 On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the
4160 environment, rather than inserting it with an empty value.
4162 @item @code{realloc}
4164 @prindex @code{realloc}
4165 The C standard says a call @code{realloc (NULL, size)} is equivalent
4166 to @code{malloc (size)}, but some old systems don't support this (e.g.,
4169 @item @code{signal} handler
4171 @prindex @code{signal}
4172 Normally @code{signal} takes a handler function with a return type of
4173 @code{void}, but some old systems required @code{int} instead. Any
4174 actual @code{int} value returned is not used; this is only a
4175 difference in the function prototype demanded.
4177 All systems we know of in current use return @code{void}. The
4178 @code{int} was to support K&R C, where of course @code{void} is not
4179 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
4180 used to establish the correct type in all cases.
4182 @item @code{snprintf}
4183 @c @fuindex snprintf
4184 @prindex @code{snprintf}
4185 @c @fuindex vsnprintf
4186 @prindex @code{vsnprintf}
4187 The C99 standard says that if the output array isn't big enough
4188 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
4189 truncate the output and return the number of bytes that ought to have
4190 been produced. Some older systems return the truncated length (e.g.,
4191 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
4192 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
4193 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
4194 older systems ignore the length and overrun the buffer (e.g., 64-bit
4197 @item @code{sprintf}
4199 @prindex @code{sprintf}
4200 @c @fuindex vsprintf
4201 @prindex @code{vsprintf}
4202 The C standard says @code{sprintf} and @code{vsprintf} return the
4203 number of bytes written. On some ancient systems (SunOS 4 for
4204 instance) they return the buffer pointer instead, but these no
4205 longer need to be worried about.
4209 @prindex @code{sscanf}
4210 On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its
4211 input string be writable (though it doesn't actually change it). This
4212 can be a problem when using @command{gcc} since it normally puts
4213 constant strings in read-only memory (@pxref{Incompatibilities,
4214 Incompatibilities of @acronym{GCC}, , gcc, Using and
4215 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
4216 having format strings read-only can be a problem.
4218 @item @code{strerror_r}
4219 @c @fuindex strerror_r
4220 @prindex @code{strerror_r}
4221 Posix specifies that @code{strerror_r} returns an @code{int}, but many
4222 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
4223 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
4224 can detect which is in use (@pxref{Particular Functions}).
4226 @item @code{strnlen}
4228 @prindex @code{strnlen}
4229 @acronym{AIX} 4.3 provides a broken version which produces the
4233 strnlen ("foobar", 0) = 0
4234 strnlen ("foobar", 1) = 3
4235 strnlen ("foobar", 2) = 2
4236 strnlen ("foobar", 3) = 1
4237 strnlen ("foobar", 4) = 0
4238 strnlen ("foobar", 5) = 6
4239 strnlen ("foobar", 6) = 6
4240 strnlen ("foobar", 7) = 6
4241 strnlen ("foobar", 8) = 6
4242 strnlen ("foobar", 9) = 6
4245 @item @code{sysconf}
4247 @prindex @code{sysconf}
4248 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX}
4249 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
4254 @prindex @code{unlink}
4255 The Posix spec says that @code{unlink} causes the given file to be
4256 removed only after there are no more open file handles for it. Some
4257 non-Posix hosts have trouble with this requirement, though,
4258 and some @acronym{DOS} variants even corrupt the file system.
4260 @item @code{unsetenv}
4261 @c @fuindex unsetenv
4262 @prindex @code{unsetenv}
4263 On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO}
4264 can be removed with a call @code{putenv ("FOO=")}, as described under
4265 @code{putenv} above.
4267 @item @code{va_copy}
4269 @prindex @code{va_copy}
4270 The C99 standard provides @code{va_copy} for copying
4271 @code{va_list} variables. It may be available in older environments
4272 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
4273 pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to
4274 @code{memcpy (&dst, &src, sizeof (va_list))} gives maximum
4277 @item @code{va_list}
4279 @prindex @code{va_list}
4280 @code{va_list} is not necessarily just a pointer. It can be a
4281 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
4282 not portable. Or it can be an array (e.g., @command{gcc} in some
4283 PowerPC configurations), which means as a function parameter it can be
4284 effectively call-by-reference and library routines might modify the
4285 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
4288 @item Signed @code{>>}
4289 Normally the C @code{>>} right shift of a signed type replicates the
4290 high bit, giving a so-called ``arithmetic'' shift. But care should be
4291 taken since Standard C doesn't require that behavior. On those
4292 few processors without a native arithmetic shift (for instance Cray
4293 vector systems) zero bits may be shifted in, the same as a shift of an
4296 @item Integer @code{/}
4297 C divides signed integers by truncating their quotient toward zero,
4298 yielding the same result as Fortran. However, before C99 the standard
4299 allowed C implementations to take the floor or ceiling of the quotient
4300 in some cases. Hardly any implementations took advantage of this
4301 freedom, though, and it's probably not worth worrying about this issue
4306 @node Particular Functions
4307 @subsection Particular Function Checks
4308 @cindex Function, checking
4310 These macros check for particular C functions---whether they exist, and
4311 in some cases how they respond when given certain arguments.
4313 @defmac AC_FUNC_ALLOCA
4314 @acindex{FUNC_ALLOCA}
4316 @cvindex HAVE_ALLOCA_H
4319 @prindex @code{alloca}
4321 Check how to get @code{alloca}. Tries to get a builtin version by
4322 checking for @file{alloca.h} or the predefined C preprocessor macros
4323 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4324 it defines @code{HAVE_ALLOCA_H}.
4326 If those attempts fail, it looks for the function in the standard C
4327 library. If any of those methods succeed, it defines
4328 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4329 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4330 @code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to
4331 garbage collect). This variable is separate from @code{LIBOBJS} so
4332 multiple programs can share the value of @code{ALLOCA} without needing
4333 to create an actual library, in case only some of them use the code in
4334 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4335 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4337 This macro does not try to get @code{alloca} from the System V R3
4338 @file{libPW} or the System V R4 @file{libucb} because those libraries
4339 contain some incompatible functions that cause trouble. Some versions
4340 do not even contain @code{alloca} or contain a buggy version. If you
4341 still want to use their @code{alloca}, use @code{ar} to extract
4342 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4344 Source files that use @code{alloca} should start with a piece of code
4345 like the following, to declare it properly.
4350 # include <alloca.h>
4351 #elif defined __GNUC__
4352 # define alloca __builtin_alloca
4354 # define alloca __alloca
4355 #elif defined _MSC_VER
4356 # include <malloc.h>
4357 # define alloca _alloca
4359 # include <stddef.h>
4363 void *alloca (size_t);
4369 @defmac AC_FUNC_CHOWN
4370 @acindex{FUNC_CHOWN}
4372 @prindex @code{chown}
4373 If the @code{chown} function is available and works (in particular, it
4374 should accept @option{-1} for @code{uid} and @code{gid}), define
4379 @defmac AC_FUNC_CLOSEDIR_VOID
4380 @acindex{FUNC_CLOSEDIR_VOID}
4381 @cvindex CLOSEDIR_VOID
4382 @c @fuindex closedir
4383 @prindex @code{closedir}
4384 If the @code{closedir} function does not return a meaningful value,
4385 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4386 return value for an error indicator.
4388 Currently this test is implemented by running a test program. When
4389 cross compiling the pessimistic assumption that @code{closedir} does not
4390 return a meaningful value is made.
4392 This macro is obsolescent, as @code{closedir} returns a meaningful value
4393 on current systems. New programs need not use this macro.
4396 @defmac AC_FUNC_ERROR_AT_LINE
4397 @acindex{FUNC_ERROR_AT_LINE}
4398 @c @fuindex error_at_line
4399 @prindex @code{error_at_line}
4400 If the @code{error_at_line} function is not found, require an
4401 @code{AC_LIBOBJ} replacement of @samp{error}.
4404 @defmac AC_FUNC_FNMATCH
4405 @acindex{FUNC_FNMATCH}
4407 @prindex @code{fnmatch}
4408 If the @code{fnmatch} function conforms to Posix, define
4409 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4410 the bugs in Solaris 2.4.
4412 Unlike the other specific
4413 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4414 broken/missing @code{fnmatch}. This is for historical reasons.
4415 See @code{AC_REPLACE_FNMATCH} below.
4418 @defmac AC_FUNC_FNMATCH_GNU
4419 @acindex{FUNC_FNMATCH_GNU}
4421 @prindex @code{fnmatch}
4422 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4423 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4424 implementation bugs, for example, the bugs in the @acronym{GNU} C
4428 @defmac AC_FUNC_FORK
4430 @cvindex HAVE_VFORK_H
4431 @cvindex HAVE_WORKING_FORK
4432 @cvindex HAVE_WORKING_VFORK
4435 @prindex @code{fork}
4437 @prindex @code{vfork}
4439 This macro checks for the @code{fork} and @code{vfork} functions. If a
4440 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4441 checks whether @code{fork} is just a stub by trying to run it.
4443 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4444 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4445 define @code{vfork} to be @code{fork} for backward compatibility with
4446 previous versions of @command{autoconf}. This macro checks for several known
4447 errors in implementations of @code{vfork} and considers the system to not
4448 have a working @code{vfork} if it detects any of them. It is not considered
4449 to be an implementation error if a child's invocation of @code{signal}
4450 modifies the parent's signal handler, since child processes rarely change
4451 their signal handlers.
4453 Since this macro defines @code{vfork} only for backward compatibility with
4454 previous versions of @command{autoconf} you're encouraged to define it
4455 yourself in new code:
4458 #if !HAVE_WORKING_VFORK
4465 @defmac AC_FUNC_FSEEKO
4466 @acindex{FUNC_FSEEKO}
4467 @cvindex _LARGEFILE_SOURCE
4469 @prindex @code{fseeko}
4470 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4471 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4472 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4473 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4474 largefile-sensitive systems where @code{off_t} does not default to a
4478 @defmac AC_FUNC_GETGROUPS
4479 @acindex{FUNC_GETGROUPS}
4480 @ovindex GETGROUPS_LIBS
4481 @c @fuindex getgroups
4482 @prindex @code{getgroups}
4483 If the @code{getgroups} function is available and works (unlike on
4484 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4485 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4486 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4489 @defmac AC_FUNC_GETLOADAVG
4490 @acindex{FUNC_GETLOADAVG}
4495 @cvindex HAVE_NLIST_H
4496 @cvindex NLIST_NAME_UNION
4497 @cvindex GETLODAVG_PRIVILEGED
4498 @cvindex NEED_SETGID
4499 @cvindex C_GETLOADAVG
4501 @ovindex NEED_SETGID
4503 @ovindex GETLOADAVG_LIBS
4504 @c @fuindex getloadavg
4505 @prindex @code{getloadavg}
4506 Check how to get the system load averages. To perform its tests
4507 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4508 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4509 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4511 If the system has the @code{getloadavg} function, define
4512 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4513 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4514 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4515 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4516 possibly define several other C preprocessor macros and output
4521 Define @code{C_GETLOADAVG}.
4524 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4529 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4532 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4533 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4534 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4537 Programs may need to be installed set-group-ID (or set-user-ID) for
4538 @code{getloadavg} to work. In this case, define
4539 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4540 to @samp{true} (and otherwise to @samp{false}), and set
4541 @code{KMEM_GROUP} to the name of the group that should own the installed
4546 @defmac AC_FUNC_GETMNTENT
4547 @acindex{FUNC_GETMNTENT}
4548 @cvindex HAVE_GETMNTENT
4549 @c @fuindex getmntent
4550 @prindex @code{getmntent}
4551 Check for @code{getmntent} in the standard C library, and then in the
4552 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4553 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4554 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4557 @defmac AC_FUNC_GETPGRP
4558 @acindex{FUNC_GETPGRP}
4559 @cvindex GETPGRP_VOID
4562 @prindex @code{getpgid}
4563 @prindex @code{getpgrp}
4564 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4565 @code{getpgrp}; this is the Posix behavior. On older @acronym{BSD}
4566 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4567 behaves like Posix's @code{getpgid}.
4577 This macro does not check whether
4578 @code{getpgrp} exists at all; if you need to work in that situation,
4579 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4581 This macro is obsolescent, as current systems have a @code{getpgrp}
4582 whose signature conforms to Posix. New programs need not use this macro.
4585 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4586 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4587 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4589 @prindex @code{lstat}
4590 If @file{link} is a symbolic link, then @code{lstat} should treat
4591 @file{link/} the same as @file{link/.}. However, many older
4592 @code{lstat} implementations incorrectly ignore trailing slashes.
4594 It is safe to assume that if @code{lstat} incorrectly ignores
4595 trailing slashes, then other symbolic-link-aware functions like
4596 @code{unlink} also incorrectly ignore trailing slashes.
4598 If @code{lstat} behaves properly, define
4599 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4600 @code{AC_LIBOBJ} replacement of @code{lstat}.
4603 @defmac AC_FUNC_MALLOC
4604 @acindex{FUNC_MALLOC}
4605 @cvindex HAVE_MALLOC
4608 @prindex @code{malloc}
4609 If the @code{malloc} function is compatible with the @acronym{GNU} C
4610 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4611 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4612 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4613 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4614 native @code{malloc} is not used in the main project.
4616 Typically, the replacement file @file{malloc.c} should look like (note
4617 the @samp{#undef malloc}):
4621 # include <config.h>
4625 #include <sys/types.h>
4629 /* Allocate an N-byte block of memory from the heap.
4630 If N is zero, allocate a 1-byte block. */
4633 rpl_malloc (size_t n)
4642 @defmac AC_FUNC_MEMCMP
4643 @acindex{FUNC_MEMCMP}
4646 @prindex @code{memcmp}
4647 If the @code{memcmp} function is not available, or does not work on
4648 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4649 bytes or more and with at least one buffer not starting on a 4-byte
4650 boundary (such as the one on NeXT x86 OpenStep), require an
4651 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4653 This macro is obsolescent, as current systems have a working
4654 @code{memcmp}. New programs need not use this macro.
4657 @defmac AC_FUNC_MBRTOWC
4658 @acindex{FUNC_MBRTOWC}
4659 @cvindex HAVE_MBRTOWC
4661 @prindex @code{mbrtowc}
4662 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4663 type @code{mbstate_t} are properly declared.
4666 @defmac AC_FUNC_MKTIME
4667 @acindex{FUNC_MKTIME}
4670 @prindex @code{mktime}
4671 If the @code{mktime} function is not available, or does not work
4672 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4673 For the purposes of this test, @code{mktime} should conform to the
4674 Posix standard and should be the inverse of
4678 @defmac AC_FUNC_MMAP
4682 @prindex @code{mmap}
4683 If the @code{mmap} function exists and works correctly, define
4684 @code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped
4688 @defmac AC_FUNC_OBSTACK
4689 @acindex{FUNC_OBSTACK}
4690 @cvindex HAVE_OBSTACK
4692 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4693 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4696 @defmac AC_FUNC_REALLOC
4697 @acindex{FUNC_REALLOC}
4698 @cvindex HAVE_REALLOC
4701 @prindex @code{realloc}
4702 If the @code{realloc} function is compatible with the @acronym{GNU} C
4703 library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a
4704 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4705 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4706 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4707 the native @code{realloc} is not used in the main project. See
4708 @code{AC_FUNC_MALLOC} for details.
4711 @defmac AC_FUNC_SELECT_ARGTYPES
4712 @acindex{FUNC_SELECT_ARGTYPES}
4713 @cvindex SELECT_TYPE_ARG1
4714 @cvindex SELECT_TYPE_ARG234
4715 @cvindex SELECT_TYPE_ARG5
4717 @prindex @code{select}
4718 Determines the correct type to be passed for each of the
4719 @code{select} function's arguments, and defines those types
4720 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4721 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4722 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4723 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4725 This macro is obsolescent, as current systems have a @code{select} whose
4726 signature conforms to Posix. New programs need not use this macro.
4729 @defmac AC_FUNC_SETPGRP
4730 @acindex{FUNC_SETPGRP}
4731 @cvindex SETPGRP_VOID
4733 @prindex @code{setpgrp}
4734 If @code{setpgrp} takes no argument (the Posix version), define
4735 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4736 two process IDs as arguments. This macro does not check whether
4737 @code{setpgrp} exists at all; if you need to work in that situation,
4738 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4740 This macro is obsolescent, as current systems have a @code{setpgrp}
4741 whose signature conforms to Posix. New programs need not use this macro.
4744 @defmac AC_FUNC_STAT
4745 @defmacx AC_FUNC_LSTAT
4747 @acindex{FUNC_LSTAT}
4748 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4749 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4751 @prindex @code{stat}
4753 @prindex @code{lstat}
4754 Determine whether @code{stat} or @code{lstat} have the bug that it
4755 succeeds when given the zero-length file name as argument. The @code{stat}
4756 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4759 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4760 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4763 These macros are obsolescent, as no current systems have the bug.
4764 New programs need not use these macros.
4767 @defmac AC_FUNC_SETVBUF_REVERSED
4768 @acindex{FUNC_SETVBUF_REVERSED}
4769 @cvindex SETVBUF_REVERSED
4771 @prindex @code{setvbuf}
4772 If @code{setvbuf} takes the buffering type as its second argument and
4773 the buffer pointer as the third, instead of the other way around, define
4774 @code{SETVBUF_REVERSED}.
4776 This macro is obsolescent, as no current systems have the bug.
4777 New programs need not use this macro.
4780 @defmac AC_FUNC_STRCOLL
4781 @acindex{FUNC_STRCOLL}
4782 @cvindex HAVE_STRCOLL
4784 @prindex @code{strcoll}
4785 If the @code{strcoll} function exists and works correctly, define
4786 @code{HAVE_STRCOLL}. This does a bit more than
4787 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4788 definitions of @code{strcoll} that should not be used.
4791 @defmac AC_FUNC_STRERROR_R
4792 @acindex{FUNC_STRERROR_R}
4793 @cvindex HAVE_STRERROR_R
4794 @cvindex HAVE_DECL_STRERROR_R
4795 @cvindex STRERROR_R_CHAR_P
4796 @c @fuindex strerror_r
4797 @prindex @code{strerror_r}
4798 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4799 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4800 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4801 returns an @code{int} error number. The Thread-Safe Functions option of
4802 Posix requires @code{strerror_r} to return @code{int}, but
4803 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4804 Library) return a @code{char *} value that is not necessarily equal to
4805 the buffer argument.
4808 @defmac AC_FUNC_STRFTIME
4809 @acindex{FUNC_STRFTIME}
4810 @cvindex HAVE_STRFTIME
4811 @c @fuindex strftime
4812 @prindex @code{strftime}
4813 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4814 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4816 This macro is obsolescent, as no current systems require the @file{intl}
4817 library for @code{strftime}. New programs need not use this macro.
4820 @defmac AC_FUNC_STRTOD
4821 @acindex{FUNC_STRTOD}
4824 @prindex @code{strtod}
4825 If the @code{strtod} function does not exist or doesn't work correctly,
4826 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4827 because @file{strtod.c} is likely to need @samp{pow}, set the output
4828 variable @code{POW_LIB} to the extra library needed.
4831 @defmac AC_FUNC_STRTOLD
4832 @acindex{FUNC_STRTOLD}
4833 @prindex @code{strtold}
4834 If the @code{strtold} function exists and conforms to C99, define
4835 @code{HAVE_STRTOLD}.
4838 @defmac AC_FUNC_STRNLEN
4839 @acindex{FUNC_STRNLEN}
4840 @cvindex HAVE_STRNLEN
4842 @prindex @code{strnlen}
4843 If the @code{strnlen} function is not available, or is buggy (like the one
4844 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4847 @defmac AC_FUNC_UTIME_NULL
4848 @acindex{FUNC_UTIME_NULL}
4849 @cvindex HAVE_UTIME_NULL
4851 @prindex @code{utime}
4852 If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to
4853 the present, define @code{HAVE_UTIME_NULL}.
4855 This macro is obsolescent, as all current systems have a @code{utime}
4856 that behaves this way. New programs need not use this macro.
4859 @defmac AC_FUNC_VPRINTF
4860 @acindex{FUNC_VPRINTF}
4861 @cvindex HAVE_VPRINTF
4862 @cvindex HAVE_DOPRNT
4864 @prindex @code{vprintf}
4865 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4866 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4867 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4868 are also available.)
4870 This macro is obsolescent, as all current systems have @code{vprintf}.
4871 New programs need not use this macro.
4874 @defmac AC_REPLACE_FNMATCH
4875 @acindex{REPLACE_FNMATCH}
4877 @prindex @code{fnmatch}
4878 @hdrindex{fnmatch.h}
4879 If the @code{fnmatch} function does not conform to Posix (see
4880 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4882 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4883 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4884 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4885 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4886 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4887 included in place of the system @code{<fnmatch.h>}.
4892 @node Generic Functions
4893 @subsection Generic Function Checks
4895 These macros are used to find functions not covered by the ``particular''
4896 test macros. If the functions might be in libraries other than the
4897 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4898 If you need to check the behavior of a function as well as find out
4899 whether it is present, you have to write your own test for
4900 it (@pxref{Writing Tests}).
4902 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4903 @acindex{CHECK_FUNC}
4904 If C function @var{function} is available, run shell commands
4905 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4906 want to define a symbol if the function is available, consider using
4907 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4908 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4909 standardized than C++. (@pxref{Language Choice}, for more information
4910 about selecting the language for checks.)
4913 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4914 @acindex{CHECK_FUNCS}
4915 @cvindex HAVE_@var{function}
4916 For each @var{function} enumerated in the blank-or-newline-separated argument
4917 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4918 If @var{action-if-found} is given, it is additional shell code to
4919 execute when one of the functions is found. You can give it a value of
4920 @samp{break} to break out of the loop on the first match. If
4921 @var{action-if-not-found} is given, it is executed when one of the
4922 functions is not found.
4925 @defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{})
4926 @acindex{CHECK_FUNCS_ONCE}
4927 @cvindex HAVE_@var{function}
4928 For each @var{function} enumerated in the blank-or-newline-separated argument
4929 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4930 This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the
4931 checking code at most once, so that @command{configure} is smaller and
4932 faster; but the checks cannot be conditionalized and are always done once,
4933 early during the @command{configure} run.
4938 Autoconf follows a philosophy that was formed over the years by those
4939 who have struggled for portability: isolate the portability issues in
4940 specific files, and then program as if you were in a Posix
4941 environment. Some functions may be missing or unfixable, and your
4942 package must be ready to replace them.
4944 Suitable replacements for many such problem functions are available from
4945 Gnulib (@pxref{Gnulib}).
4947 @defmac AC_LIBOBJ (@var{function})
4950 Specify that @samp{@var{function}.c} must be included in the executables
4951 to replace a missing or broken implementation of @var{function}.
4953 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4954 variable @code{LIBOBJS} if it is not already in, and calls
4955 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4956 directly change @code{LIBOBJS}, since this is not traceable.
4959 @defmac AC_LIBSOURCE (@var{file})
4961 Specify that @var{file} might be needed to compile the project. If you
4962 need to know what files might be needed by a @file{configure.ac}, you
4963 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4965 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4966 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4967 that case, since shell variables cannot be traced statically, you must
4968 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4969 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4970 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4971 @code{"foo"} or @code{"bar"}, you should do:
4974 AC_LIBSOURCE([foo.c])
4975 AC_LIBSOURCE([bar.c])
4976 AC_LIBOBJ([$foo_or_bar])
4980 There is usually a way to avoid this, however, and you are encouraged to
4981 simply call @code{AC_LIBOBJ} with literal arguments.
4983 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4984 slightly different semantics: the old macro took the function name,
4985 e.g., @code{foo}, as its argument rather than the file name.
4988 @defmac AC_LIBSOURCES (@var{files})
4989 @acindex{LIBSOURCES}
4990 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
4991 comma-separated M4 list. Thus, the above example might be rewritten:
4994 AC_LIBSOURCES([foo.c, bar.c])
4995 AC_LIBOBJ([$foo_or_bar])
4999 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
5000 @acindex{CONFIG_LIBOBJ_DIR}
5001 Specify that @code{AC_LIBOBJ} replacement files are to be found in
5002 @var{directory}, a name relative to the top level of the
5003 source tree. The replacement directory defaults to @file{.}, the top
5004 level directory, and the most typical value is @file{lib}, corresponding
5005 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
5007 @command{configure} might need to know the replacement directory for the
5008 following reasons: (i) some checks use the replacement files, (ii) some
5009 macros bypass broken system headers by installing links to the
5010 replacement headers (iii) when used in conjunction with Automake,
5011 within each makefile, @var{directory} is used as a relative path
5012 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
5013 @code{LTLIBOBJS}, etc.
5018 It is common to merely check for the existence of a function, and ask
5019 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
5020 a convenient shorthand.
5022 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
5023 @acindex{REPLACE_FUNCS}
5025 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
5026 @var{action-if-not-found}. You can declare your replacement function by
5027 enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the
5028 system has the function, it probably declares it in a header file you
5029 should be including, so you shouldn't redeclare it lest your declaration
5034 @section Header Files
5035 @cindex Header, checking
5037 The following macros check for the presence of certain C header files.
5038 If there is no macro specifically defined to check for a header file you need,
5039 and you don't need to check for any special properties of
5040 it, then you can use one of the general header-file check macros.
5043 * Header Portability:: Collected knowledge on common headers
5044 * Particular Headers:: Special handling to find certain headers
5045 * Generic Headers:: How to find other headers
5048 @node Header Portability
5049 @subsection Portability of Headers
5050 @cindex Portability of headers
5051 @cindex Header portability
5053 This section tries to collect knowledge about common headers, and the
5054 problems they cause. By definition, this list always requires
5055 additions. Please help us keeping it as complete as possible.
5059 @item @file{limits.h}
5060 C99 says that @file{limits.h} defines @code{LLONG_MIN},
5061 @code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99
5062 environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not
5065 @item @file{inttypes.h} vs.@: @file{stdint.h}
5066 @hdrindex{inttypes.h}
5068 The C99 standard says that @file{inttypes.h} includes
5069 @file{stdint.h}, so there's no need to include @file{stdint.h}
5070 separately in a standard environment. Some implementations have
5071 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
5072 know of any implementation that has @file{stdint.h} but not
5075 @item @file{linux/irda.h}
5076 @hdrindex{linux/irda.h}
5077 It requires @file{linux/types.h} and @file{sys/socket.h}.
5079 @item @file{linux/random.h}
5080 @hdrindex{linux/random.h}
5081 It requires @file{linux/types.h}.
5083 @item @file{net/if.h}
5085 On Darwin, this file requires that @file{sys/socket.h} be included
5086 beforehand. One should run:
5089 AC_CHECK_HEADERS([sys/socket.h])
5090 AC_CHECK_HEADERS([net/if.h], [], [],
5093 # include <stdlib.h>
5094 # include <stddef.h>
5097 # include <stdlib.h>
5100 #if HAVE_SYS_SOCKET_H
5101 # include <sys/socket.h>
5106 @item @file{netinet/if_ether.h}
5107 @hdrindex{netinet/if_ether.h}
5108 On Darwin, this file requires that @file{stdio.h} and
5109 @file{sys/socket.h} be included beforehand. One should run:
5112 AC_CHECK_HEADERS([sys/socket.h])
5113 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
5116 # include <stdlib.h>
5117 # include <stddef.h>
5120 # include <stdlib.h>
5123 #if HAVE_SYS_SOCKET_H
5124 # include <sys/socket.h>
5129 @item @file{stdint.h}
5130 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
5132 @item @file{stdlib.h}
5134 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
5136 @item @file{sys/mount.h}
5137 @hdrindex{sys/mount.h}
5138 On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4,
5139 @file{sys/params.h} is a prerequisite.
5141 @item @file{sys/ptem.h}
5142 @hdrindex{sys/ptem.h}
5143 On Solaris 8, @file{sys/stream.h} is a prerequisite.
5145 @item @file{sys/socket.h}
5146 @hdrindex{sys/socket.h}
5147 On Darwin, @file{stdlib.h} is a prerequisite.
5149 @item @file{sys/ucred.h}
5150 @hdrindex{sys/ucred.h}
5151 On Tru64 5.1, @file{sys/types.h} is a prerequisite.
5153 @item @file{X11/extensions/scrnsaver.h}
5154 @hdrindex{X11/extensions/scrnsaver.h}
5155 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
5156 so required that you might not even consider looking for it.
5159 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
5160 [[#include <X11/Xlib.h>
5166 @node Particular Headers
5167 @subsection Particular Header Checks
5169 These macros check for particular system header files---whether they
5170 exist, and in some cases whether they declare certain symbols.
5172 @defmac AC_HEADER_ASSERT
5173 @acindex{HEADER_ASSERT}
5176 Check whether to enable assertions in the style of @file{assert.h}.
5177 Assertions are enabled by default, but the user can override this by
5178 invoking @command{configure} with the @option{--disable-assert} option.
5181 @defmac AC_HEADER_DIRENT
5182 @acindex{HEADER_DIRENT}
5183 @cvindex HAVE_DIRENT_H
5184 @cvindex HAVE_NDIR_H
5185 @cvindex HAVE_SYS_DIR_H
5186 @cvindex HAVE_SYS_NDIR_H
5188 @hdrindex{sys/ndir.h}
5189 @hdrindex{sys/dir.h}
5191 Check for the following header files. For the first one that is
5192 found and defines @samp{DIR}, define the listed C preprocessor macro:
5194 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
5195 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
5196 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
5197 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
5198 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
5201 The directory-library declarations in your source code should look
5202 something like the following:
5206 #include <sys/types.h>
5207 #ifdef HAVE_DIRENT_H
5208 # include <dirent.h>
5209 # define NAMLEN(dirent) strlen ((dirent)->d_name)
5211 # define dirent direct
5212 # define NAMLEN(dirent) ((dirent)->d_namlen)
5213 # if HAVE_SYS_NDIR_H
5214 # include <sys/ndir.h>
5217 # include <sys/dir.h>
5226 Using the above declarations, the program would declare variables to be
5227 of type @code{struct dirent}, not @code{struct direct}, and would access
5228 the length of a directory entry name by passing a pointer to a
5229 @code{struct dirent} to the @code{NAMLEN} macro.
5231 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
5233 This macro is obsolescent, as all current systems with directory
5234 libraries have @code{<dirent.h>}. New programs need not use this macro.
5236 Also see @code{AC_STRUCT_DIRENT_D_INO} and
5237 @code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}).
5240 @defmac AC_HEADER_MAJOR
5241 @acindex{HEADER_MAJOR}
5242 @cvindex MAJOR_IN_MKDEV
5243 @cvindex MAJOR_IN_SYSMACROS
5244 @hdrindex{sys/mkdev.h}
5245 @hdrindex{sys/sysmacros.h}
5246 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
5247 @code{makedev}, but @file{sys/mkdev.h} does, define
5248 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
5249 @code{MAJOR_IN_SYSMACROS}.
5252 @defmac AC_HEADER_RESOLV
5253 @acindex{HEADER_RESOLV}
5254 @cvindex HAVE_RESOLV_H
5256 Checks for header @file{resolv.h}, checking for prerequisites first.
5257 To properly use @file{resolv.h}, your code should contain something like
5261 #if HAVE_SYS_TYPES_H
5262 # include <sys/types.h>
5264 #ifdef HAVE_NETINET_IN_H
5265 # include <netinet/in.h> /* inet_ functions / structs */
5267 #ifdef HAVE_ARPA_NAMESER_H
5268 # include <arpa/nameser.h> /* DNS HEADER struct */
5277 @defmac AC_HEADER_STAT
5278 @acindex{HEADER_STAT}
5279 @cvindex STAT_MACROS_BROKEN
5280 @hdrindex{sys/stat.h}
5281 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
5282 @file{sys/stat.h} do not work properly (returning false positives),
5283 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
5284 Amdahl UTS and Motorola System V/88.
5286 This macro is obsolescent, as no current systems have the bug.
5287 New programs need not use this macro.
5290 @defmac AC_HEADER_STDBOOL
5291 @acindex{HEADER_STDBOOL}
5292 @cvindex HAVE_STDBOOL_H
5294 @hdrindex{stdbool.h}
5296 If @file{stdbool.h} exists and conforms to C99, define
5297 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
5298 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
5299 @file{system.h} could contain the following code:
5303 # include <stdbool.h>
5309 # define _Bool signed char
5315 # define __bool_true_false_are_defined 1
5319 Alternatively you can use the @samp{stdbool} package of Gnulib
5320 (@pxref{Gnulib}); it packages the above code into a replacement header
5321 and contains a few other bells and whistles.
5326 @defmac AC_HEADER_STDC
5327 @acindex{HEADER_STDC}
5328 @cvindex STDC_HEADERS
5334 Define @code{STDC_HEADERS} if the system has C header files
5335 conforming to @acronym{ANSI} C89 (@acronym{ISO} C90).
5336 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
5337 @file{string.h}, and @file{float.h}; if the system has those, it
5338 probably has the rest of the C89 header files. This macro also
5339 checks whether @file{string.h} declares @code{memchr} (and thus
5340 presumably the other @code{mem} functions), whether @file{stdlib.h}
5341 declare @code{free} (and thus presumably @code{malloc} and other related
5342 functions), and whether the @file{ctype.h} macros work on characters
5343 with the high bit set, as the C standard requires.
5345 If you use this macro, your code can refer to @code{STDC_HEADERS} to
5346 determine whether the system has conforming header files (and probably C
5349 This macro is obsolescent, as current systems have conforming header
5350 files. New programs need not use this macro.
5353 @hdrindex{strings.h}
5354 Nowadays @file{string.h} is part of the C standard and declares functions like
5355 @code{strcpy}, and @file{strings.h} is standardized by Posix and declares
5356 @acronym{BSD} functions like @code{bcopy}; but
5357 historically, string functions were a major sticking point in this area.
5358 If you still want to worry about portability to ancient systems without
5359 standard headers, there is so much variation
5360 that it is probably easier to declare the functions you use than to
5361 figure out exactly what the system header files declare. Some ancient systems
5362 contained a mix of functions from the C standard and from @acronym{BSD};
5363 some were mostly standard but lacked @samp{memmove}; some defined the
5364 @acronym{BSD} functions as macros in @file{string.h} or
5365 @file{strings.h}; some had only the @acronym{BSD} functions but
5366 @file{string.h}; some declared the memory functions in @file{memory.h},
5367 some in @file{string.h}; etc. It is probably sufficient to check for
5368 one string function and one memory function; if the library had the
5369 standard versions of those then it probably had most of the others.
5370 If you put the following in @file{configure.ac}:
5373 # This example is obsolescent.
5374 # Nowadays you can omit these macro calls.
5376 AC_CHECK_FUNCS([strchr memcpy])
5380 then, in your code, you can use declarations like this:
5384 /* This example is obsolescent.
5385 Nowadays you can just #include <string.h>. */
5387 # include <string.h>
5390 # define strchr index
5391 # define strrchr rindex
5393 char *strchr (), *strrchr ();
5395 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5396 # define memmove(d, s, n) bcopy ((s), (d), (n))
5403 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5404 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't
5405 suffice to port to ancient hosts; you must provide an implementation of
5406 each function. An easy
5407 way to incorporate your implementations only when needed (since the ones
5408 in system C libraries may be hand optimized) is to, taking @code{memchr}
5409 for example, put it in @file{memchr.c} and use
5410 @samp{AC_REPLACE_FUNCS([memchr])}.
5413 @defmac AC_HEADER_SYS_WAIT
5414 @acindex{HEADER_SYS_WAIT}
5415 @cvindex HAVE_SYS_WAIT_H
5416 @hdrindex{sys/wait.h}
5417 If @file{sys/wait.h} exists and is compatible with Posix, define
5418 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5419 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5420 of @code{int} to store a status value. If @file{sys/wait.h} is not
5421 Posix compatible, then instead of including it, define the
5422 Posix macros with their usual interpretations. Here is an
5427 #include <sys/types.h>
5429 # include <sys/wait.h>
5432 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5435 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5441 This macro is obsolescent, as current systems are compatible with Posix.
5442 New programs need not use this macro.
5445 @cvindex _POSIX_VERSION
5447 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5448 Posix systems. If there is no @file{unistd.h}, it is definitely
5449 not a Posix system. However, some non-Posix systems do
5450 have @file{unistd.h}.
5452 The way to check whether the system supports Posix is:
5457 # include <sys/types.h>
5458 # include <unistd.h>
5461 #ifdef _POSIX_VERSION
5462 /* Code for Posix systems. */
5467 @defmac AC_HEADER_TIME
5468 @acindex{HEADER_TIME}
5469 @cvindex TIME_WITH_SYS_TIME
5471 @hdrindex{sys/time.h}
5472 If a program may include both @file{time.h} and @file{sys/time.h},
5473 define @code{TIME_WITH_SYS_TIME}. On some ancient systems,
5474 @file{sys/time.h} included @file{time.h}, but @file{time.h} was not
5475 protected against multiple inclusion, so programs could not explicitly
5476 include both files. This macro is useful in programs that use, for
5477 example, @code{struct timeval} as well as
5478 @code{struct tm}. It is best used in conjunction with
5479 @code{HAVE_SYS_TIME_H}, which can be checked for using
5480 @code{AC_CHECK_HEADERS([sys/time.h])}.
5484 #if TIME_WITH_SYS_TIME
5485 # include <sys/time.h>
5488 # if HAVE_SYS_TIME_H
5489 # include <sys/time.h>
5498 This macro is obsolescent, as current systems can include both files
5499 when they exist. New programs need not use this macro.
5503 @defmac AC_HEADER_TIOCGWINSZ
5504 @acindex{HEADER_TIOCGWINSZ}
5505 @cvindex GWINSZ_IN_SYS_IOCTL
5506 @hdrindex{sys/ioctl.h}
5507 @hdrindex{termios.h}
5508 @c FIXME: I need clarifications from Jim.
5509 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5510 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5511 found in @file{<termios.h>}.
5518 # include <termios.h>
5521 #if GWINSZ_IN_SYS_IOCTL
5522 # include <sys/ioctl.h>
5528 @node Generic Headers
5529 @subsection Generic Header Checks
5531 These macros are used to find system header files not covered by the
5532 ``particular'' test macros. If you need to check the contents of a header
5533 as well as find out whether it is present, you have to write your own
5534 test for it (@pxref{Writing Tests}).
5536 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5537 @acindex{CHECK_HEADER}
5538 If the system header file @var{header-file} is compilable, execute shell
5539 commands @var{action-if-found}, otherwise execute
5540 @var{action-if-not-found}. If you just want to define a symbol if the
5541 header file is available, consider using @code{AC_CHECK_HEADERS}
5544 For compatibility issues with older versions of Autoconf, please read
5548 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5549 @acindex{CHECK_HEADERS}
5550 @cvindex HAVE_@var{header}
5551 For each given system header file @var{header-file} in the
5552 blank-separated argument list that exists, define
5553 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5554 is given, it is additional shell code to execute when one of the header
5555 files is found. You can give it a value of @samp{break} to break out of
5556 the loop on the first match. If @var{action-if-not-found} is given, it
5557 is executed when one of the header files is not found.
5559 For compatibility issues with older versions of Autoconf, please read
5563 Previous versions of Autoconf merely checked whether the header was
5564 accepted by the preprocessor. This was changed because the old test was
5565 inappropriate for typical uses. Headers are typically used to compile,
5566 not merely to preprocess, and the old behavior sometimes accepted
5567 headers that clashed at compile-time. If you need to check whether a
5568 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5569 (@pxref{Running the Preprocessor}).
5571 This scheme, which improves the robustness of the test, also requires
5572 that you make sure that headers that must be included before the
5573 @var{header-file} be part of the @var{includes}, (@pxref{Default
5574 Includes}). If looking for @file{bar.h}, which requires that
5575 @file{foo.h} be included before if it exists, we suggest the following
5579 AC_CHECK_HEADERS([foo.h])
5580 AC_CHECK_HEADERS([bar.h], [], [],
5587 The following variant generates smaller, faster @command{configure}
5588 files if you do not need the full power of @code{AC_CHECK_HEADERS}.
5590 @defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{})
5591 @acindex{CHECK_HEADERS_ONCE}
5592 @cvindex HAVE_@var{header}
5593 For each given system header file @var{header-file} in the
5594 blank-separated argument list that exists, define
5595 @code{HAVE_@var{header-file}} (in all capitals).
5596 This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the
5597 checking code at most once, so that @command{configure} is smaller and
5598 faster; but the checks cannot be conditionalized and are always done once,
5599 early during the @command{configure} run.
5603 @section Declarations
5604 @cindex Declaration, checking
5606 The following macros check for the declaration of variables and
5607 functions. If there is no macro specifically defined to check for a
5608 symbol you need, then you can use the general macros (@pxref{Generic
5609 Declarations}) or, for more complex tests, you may use
5610 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5613 * Particular Declarations:: Macros to check for certain declarations
5614 * Generic Declarations:: How to find other declarations
5617 @node Particular Declarations
5618 @subsection Particular Declaration Checks
5620 There are no specific macros for declarations.
5622 @node Generic Declarations
5623 @subsection Generic Declaration Checks
5625 These macros are used to find declarations not covered by the ``particular''
5628 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5629 @acindex{CHECK_DECL}
5630 If @var{symbol} (a function or a variable) is not declared in
5631 @var{includes} and a declaration is needed, run the shell commands
5632 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5633 @var{includes} are specified, the default includes are used
5634 (@pxref{Default Includes}).
5636 This macro actually tests whether it is valid to use @var{symbol} as an
5637 r-value, not if it is really declared, because it is much safer to avoid
5638 introducing extra declarations when they are not needed.
5641 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5642 @acindex{CHECK_DECLS}
5643 @cvindex HAVE_DECL_@var{symbol}
5644 For each of the @var{symbols} (@emph{comma}-separated list), define
5645 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5646 @var{symbol} is declared, otherwise to @samp{0}. If
5647 @var{action-if-not-found} is given, it is additional shell code to
5648 execute when one of the function declarations is needed, otherwise
5649 @var{action-if-found} is executed.
5651 This macro uses an M4 list as first argument:
5653 AC_CHECK_DECLS([strdup])
5654 AC_CHECK_DECLS([strlen])
5655 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5658 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5659 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5660 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5661 @emph{sure} that the check was performed, use
5662 @code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
5665 #if !HAVE_DECL_SYMBOL
5666 extern char *symbol;
5671 If the test may have not been performed, however, because it is safer
5672 @emph{not} to declare a symbol than to use a declaration that conflicts
5673 with the system's one, you should use:
5676 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5677 void *malloc (size_t *s);
5682 You fall into the second category only in extreme situations: either
5683 your files may be used without being configured, or they are used during
5684 the configuration. In most cases the traditional approach is enough.
5687 @defmac AC_CHECK_DECLS_ONCE (@var{symbols})
5688 @acindex{CHECK_DECLS_ONCE}
5689 @cvindex HAVE_DECL_@var{symbol}
5690 For each of the @var{symbols} (@emph{comma}-separated list), define
5691 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5692 @var{symbol} is declared in the default include files, otherwise to
5693 @samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It
5694 generates the checking code at most once, so that @command{configure} is
5695 smaller and faster; but the checks cannot be conditionalized and are
5696 always done once, early during the @command{configure} run.
5702 @cindex Structure, checking
5704 The following macros check for the presence of certain members in C
5705 structures. If there is no macro specifically defined to check for a
5706 member you need, then you can use the general structure-member macros
5707 (@pxref{Generic Structures}) or, for more complex tests, you may use
5708 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5711 * Particular Structures:: Macros to check for certain structure members
5712 * Generic Structures:: How to find other structure members
5715 @node Particular Structures
5716 @subsection Particular Structure Checks
5718 The following macros check for certain structures or structure members.
5720 @defmac AC_STRUCT_DIRENT_D_INO
5721 @acindex{STRUCT_DIRENT_D_INO}
5722 @cvindex HAVE_STRUCT_DIRENT_D_INO
5723 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5724 Headers}). Then, if @code{struct dirent} contains a @code{d_ino}
5725 member, define @code{HAVE_STRUCT_DIRENT_D_INO}.
5727 @code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of
5728 @code{d_ino}, not whether its contents are always reliable.
5729 Traditionally, a zero @code{d_ino} indicated a deleted directory entry,
5730 though current systems hide this detail from the user and never return
5731 zero @code{d_ino} values.
5732 Many current systems report an incorrect @code{d_ino} for a directory
5733 entry that is a mount point.
5736 @defmac AC_STRUCT_DIRENT_D_TYPE
5737 @acindex{STRUCT_DIRENT_D_TYPE}
5738 @cvindex HAVE_STRUCT_DIRENT_D_TYPE
5739 Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular
5740 Headers}). Then, if @code{struct dirent} contains a @code{d_type}
5741 member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}.
5744 @defmac AC_STRUCT_ST_BLKSIZE
5745 @acindex{STRUCT_ST_BLKSIZE}
5746 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5747 @cvindex HAVE_ST_BLKSIZE
5748 If @code{struct stat} contains an @code{st_blksize} member, define
5749 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5750 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5751 the future. This macro is obsoleted, and should be replaced by
5754 AC_CHECK_MEMBERS([struct stat.st_blksize])
5758 @defmac AC_STRUCT_ST_BLOCKS
5759 @acindex{STRUCT_ST_BLOCKS}
5760 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5761 @cvindex HAVE_ST_BLOCKS
5763 If @code{struct stat} contains an @code{st_blocks} member, define
5764 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5765 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5766 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5770 @defmac AC_STRUCT_ST_RDEV
5771 @acindex{STRUCT_ST_RDEV}
5772 @cvindex HAVE_ST_RDEV
5773 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5774 If @code{struct stat} contains an @code{st_rdev} member, define
5775 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5776 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5777 in the future. Actually, even the new macro is obsolete and should be
5780 AC_CHECK_MEMBERS([struct stat.st_rdev])
5784 @defmac AC_STRUCT_TM
5786 @cvindex TM_IN_SYS_TIME
5788 @hdrindex{sys/time.h}
5789 If @file{time.h} does not define @code{struct tm}, define
5790 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5791 had better define @code{struct tm}.
5793 This macro is obsolescent, as @file{time.h} defines @code{struct tm} in
5794 current systems. New programs need not use this macro.
5797 @defmac AC_STRUCT_TIMEZONE
5798 @acindex{STRUCT_TIMEZONE}
5799 @cvindex HAVE_TM_ZONE
5800 @cvindex HAVE_TZNAME
5801 Figure out how to get the current timezone. If @code{struct tm} has a
5802 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5803 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5804 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5805 define @code{HAVE_DECL_TZNAME}.
5808 @node Generic Structures
5809 @subsection Generic Structure Checks
5811 These macros are used to find structure members not covered by the
5812 ``particular'' test macros.
5814 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5815 @acindex{CHECK_MEMBER}
5816 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5817 If no @var{includes} are specified, the default includes are used
5818 (@pxref{Default Includes}).
5821 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5822 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5826 You can use this macro for submembers:
5829 AC_CHECK_MEMBER(struct top.middle.bot)
5833 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5834 @acindex{CHECK_MEMBERS}
5835 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5836 @var{members} using the previous macro. When @var{member} belongs to
5837 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5838 capitals, with spaces and dots replaced by underscores). If
5839 @var{action-if-found} is given, it is executed for each of the found
5840 members. If @var{action-if-not-found} is given, it is executed for each
5841 of the members that could not be found.
5843 This macro uses M4 lists:
5845 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5855 The following macros check for C types, either builtin or typedefs. If
5856 there is no macro specifically defined to check for a type you need, and
5857 you don't need to check for any special properties of it, then you can
5858 use a general type-check macro.
5861 * Particular Types:: Special handling to find certain types
5862 * Generic Types:: How to find other types
5865 @node Particular Types
5866 @subsection Particular Type Checks
5868 @hdrindex{sys/types.h}
5871 @hdrindex{inttypes.h}
5872 These macros check for particular C types in @file{sys/types.h},
5873 @file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they
5876 The Gnulib @code{stdint} module is an alternate way to define many of
5877 these symbols; it is useful if you prefer your code to assume a
5878 C99-or-better environment. @xref{Gnulib}.
5880 @defmac AC_TYPE_GETGROUPS
5881 @acindex{TYPE_GETGROUPS}
5882 @cvindex GETGROUPS_T
5883 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5884 is the base type of the array argument to @code{getgroups}.
5887 @defmac AC_TYPE_INT8_T
5888 @acindex{TYPE_INT8_T}
5889 @cvindex HAVE_INT8_T
5891 If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t},
5892 define @code{HAVE_INT8_T}. Otherwise, define @code{int8_t} to a signed
5893 integer type that is exactly 8 bits wide and that uses two's complement
5894 representation, if such a type exists.
5897 @defmac AC_TYPE_INT16_T
5898 @acindex{TYPE_INT16_T}
5899 @cvindex HAVE_INT16_T
5901 This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers.
5904 @defmac AC_TYPE_INT32_T
5905 @acindex{TYPE_INT32_T}
5906 @cvindex HAVE_INT32_T
5908 This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers.
5911 @defmac AC_TYPE_INT64_T
5912 @acindex{TYPE_INT64_T}
5913 @cvindex HAVE_INT64_T
5915 This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers.
5918 @defmac AC_TYPE_INTMAX_T
5919 @acindex{TYPE_INTMAX_T}
5920 @cvindex HAVE_INTMAX_T
5922 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t},
5923 define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the
5924 widest signed integer type.
5927 @defmac AC_TYPE_INTPTR_T
5928 @acindex{TYPE_INTPTR_T}
5929 @cvindex HAVE_INTPTR_T
5931 If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t},
5932 define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a
5933 signed integer type wide enough to hold a pointer, if such a type
5937 @defmac AC_TYPE_LONG_DOUBLE
5938 @acindex{TYPE_LONG_DOUBLE}
5939 @cvindex HAVE_LONG_DOUBLE
5940 If the C compiler supports a working @code{long double} type, define
5941 @code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the
5942 same range and precision as @code{double}.
5945 @defmac AC_TYPE_LONG_DOUBLE_WIDER
5946 @acindex{TYPE_LONG_DOUBLE_WIDER}
5947 @cvindex HAVE_LONG_DOUBLE_WIDER
5948 If the C compiler supports a working @code{long double} type with more
5949 range or precision than the @code{double} type, define
5950 @code{HAVE_LONG_DOUBLE_WIDER}.
5953 @defmac AC_TYPE_LONG_LONG_INT
5954 @acindex{TYPE_LONG_LONG_INT}
5955 @cvindex HAVE_LONG_LONG_INT
5956 If the C compiler supports a working @code{long long int} type, define
5957 @code{HAVE_LONG_LONG_INT}.
5960 @defmac AC_TYPE_MBSTATE_T
5961 @acindex{TYPE_MBSTATE_T}
5964 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5965 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5966 @code{<wchar.h>} does not declare it.
5969 @defmac AC_TYPE_MODE_T
5970 @acindex{TYPE_MODE_T}
5972 Define @code{mode_t} to a suitable type, if standard headers do not
5976 @defmac AC_TYPE_OFF_T
5977 @acindex{TYPE_OFF_T}
5979 Define @code{off_t} to a suitable type, if standard headers do not
5983 @defmac AC_TYPE_PID_T
5984 @acindex{TYPE_PID_T}
5986 Define @code{pid_t} to a suitable type, if standard headers do not
5990 @defmac AC_TYPE_SIGNAL
5991 @acindex{TYPE_SIGNAL}
5994 If @file{signal.h} declares @code{signal} as returning a pointer to a
5995 function returning @code{void}, define @code{RETSIGTYPE} to be
5996 @code{void}; otherwise, define it to be @code{int}.
5998 Define signal handlers as returning type @code{RETSIGTYPE}:
6011 @defmac AC_TYPE_SIZE_T
6012 @acindex{TYPE_SIZE_T}
6014 Define @code{size_t} to a suitable type, if standard headers do not
6018 @defmac AC_TYPE_SSIZE_T
6019 @acindex{TYPE_SSIZE_T}
6021 Define @code{ssize_t} to a suitable type, if standard headers do not
6025 @defmac AC_TYPE_UID_T
6026 @acindex{TYPE_UID_T}
6029 Define @code{uid_t} and @code{gid_t} to suitable types, if standard
6030 headers do not define them.
6033 @defmac AC_TYPE_UINT8_T
6034 @acindex{TYPE_UINT8_T}
6035 @cvindex HAVE_UINT8_T
6037 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t},
6038 define @code{HAVE_UINT8_T}. Otherwise, define @code{uint8_t} to an
6039 unsigned integer type that is exactly 8 bits wide, if such a type
6043 @defmac AC_TYPE_UINT16_T
6044 @acindex{TYPE_UINT16_T}
6045 @cvindex HAVE_UINT16_T
6047 This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers.
6050 @defmac AC_TYPE_UINT32_T
6051 @acindex{TYPE_UINT32_T}
6052 @cvindex HAVE_UINT32_T
6054 This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers.
6057 @defmac AC_TYPE_UINT64_T
6058 @acindex{TYPE_UINT64_T}
6059 @cvindex HAVE_UINT64_T
6061 This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers.
6064 @defmac AC_TYPE_UINTMAX_T
6065 @acindex{TYPE_UINTMAX_T}
6066 @cvindex HAVE_UINTMAX_T
6068 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t},
6069 define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the
6070 widest unsigned integer type.
6073 @defmac AC_TYPE_UINTPTR_T
6074 @acindex{TYPE_UINTPTR_T}
6075 @cvindex HAVE_UINTPTR_T
6077 If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t},
6078 define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an
6079 unsigned integer type wide enough to hold a pointer, if such a type
6083 @defmac AC_TYPE_UNSIGNED_LONG_LONG_INT
6084 @acindex{TYPE_UNSIGNED_LONG_LONG_INT}
6085 @cvindex HAVE_UNSIGNED_LONG_LONG_INT
6086 If the C compiler supports a working @code{unsigned long long int} type,
6087 define @code{HAVE_UNSIGNED_LONG_LONG_INT}.
6091 @subsection Generic Type Checks
6093 These macros are used to check for types not covered by the ``particular''
6096 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6097 @acindex{CHECK_TYPE}
6098 Check whether @var{type} is defined. It may be a compiler builtin type
6099 or defined by the @var{includes} (@pxref{Default Includes}).
6103 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
6104 @acindex{CHECK_TYPES}
6105 For each @var{type} of the @var{types} that is defined, define
6106 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
6107 specified, the default includes are used (@pxref{Default Includes}). If
6108 @var{action-if-found} is given, it is additional shell code to execute
6109 when one of the types is found. If @var{action-if-not-found} is given,
6110 it is executed when one of the types is not found.
6112 This macro uses M4 lists:
6114 AC_CHECK_TYPES([ptrdiff_t])
6115 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
6120 Autoconf, up to 2.13, used to provide to another version of
6121 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
6122 compatibility, a simple heuristics, quite safe but not totally, is
6123 implemented. In case of doubt, read the documentation of the former
6124 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
6127 @node Compilers and Preprocessors
6128 @section Compilers and Preprocessors
6130 @cindex Preprocessors
6133 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
6134 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
6135 the output of the compiler, typically to the empty string if
6136 Posix and @samp{.exe} if a @acronym{DOS} variant.
6139 They also define the output variable @code{OBJEXT} based on the
6140 output of the compiler, after @file{.c} files have been excluded, typically
6141 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
6143 If the compiler being used does not produce executables, the tests fail. If
6144 the executables can't be run, and cross-compilation is not enabled, they
6145 fail too. @xref{Manual Configuration}, for more on support for cross
6149 * Specific Compiler Characteristics:: Some portability issues
6150 * Generic Compiler Characteristics:: Language independent tests and features
6151 * C Compiler:: Checking its characteristics
6152 * C++ Compiler:: Likewise
6153 * Objective C Compiler:: Likewise
6154 * Erlang Compiler and Interpreter:: Likewise
6155 * Fortran Compiler:: Likewise
6158 @node Specific Compiler Characteristics
6159 @subsection Specific Compiler Characteristics
6161 Some compilers exhibit different behaviors.
6164 @item Static/Dynamic Expressions
6165 Autoconf relies on a trick to extract one bit of information from the C
6166 compiler: using negative array sizes. For instance the following
6167 excerpt of a C source demonstrates how to test whether @samp{int} objects are 4
6171 static int test_array[sizeof (int) == 4 ? 1 : -1];
6175 To our knowledge, there is a single compiler that does not support this
6176 trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on
6177 @acronym{HP-UX} 11.00.
6178 They incorrectly reject the above program with the diagnostic
6179 ``Variable-length arrays cannot have static storage.''
6180 This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)},
6181 not from the @code{? 1 : -1}, and
6182 Autoconf works around this problem by casting @code{sizeof (int)} to
6183 @code{long int} before comparing it.
6186 @node Generic Compiler Characteristics
6187 @subsection Generic Compiler Characteristics
6189 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
6190 @acindex{CHECK_SIZEOF}
6191 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
6192 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6193 of 0. If no @var{includes} are specified, the default includes are used
6194 (@pxref{Default Includes}).
6196 This macro now works even when cross-compiling. The @var{unused}
6197 argument was used when cross-compiling.
6199 For example, the call
6202 AC_CHECK_SIZEOF([int *])
6206 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
6209 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
6210 @acindex{CHECK_ALIGNOF}
6211 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
6212 alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size
6213 of 0. If no @var{includes} are specified, the default includes are used
6214 (@pxref{Default Includes}).
6217 @defmac AC_COMPUTE_INT (@var{message}, @var{cache-id}, @var{expression}, @dvar{includes, default-includes}, @ovar{if-fails})
6218 @acindex{COMPUTE_INT}
6219 Compute the value of the integer @var{expression} in @var{cache-id}. The
6220 value should fit in an initializer in a C variable of type @code{signed
6221 long}. To support cross compilation (in which case, the macro only works on
6222 hosts that use twos-complement arithmetic), it should be possible to evaluate
6223 the expression at compile-time. If no @var{includes} are specified, the default
6224 includes are used (@pxref{Default Includes}).
6226 The macro also takes care of checking if the result is already in the
6227 cache, and of reporting the test on the standard output
6228 with @code{AC_MSG_CHECKING} (which prints @var{message}) and
6229 @code{AC_MSG_RESULT}.
6231 If the value cannot be determined correctly, the code in @var{if-fails}
6232 is executed. The @var{if-fails} commands @emph{must have no side effects}
6233 except for possibly setting the variable @var{cache-id}.
6234 @xref{Caching Results}, for more information.
6237 @defmac AC_LANG_WERROR
6238 @acindex{LANG_WERROR}
6239 Normally Autoconf ignores warnings generated by the compiler, linker, and
6240 preprocessor. If this macro is used, warnings count as fatal
6241 errors for the current language. This macro is useful when the
6242 results of configuration are used where warnings are unacceptable; for
6243 instance, if parts of a program are built with the @acronym{GCC}
6245 option. If the whole program is built using @option{-Werror} it is
6246 often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS},
6251 @subsection C Compiler Characteristics
6253 The following macros provide ways to find and exercise a C Compiler.
6254 There are a few constructs that ought to be avoided, but do not deserve
6255 being checked for, since they can easily be worked around.
6258 @item Don't use lines containing solitary backslashes
6259 They tickle a bug in the @acronym{HP-UX} C compiler (checked on
6260 @acronym{HP-UX} 10.20,
6261 11.00, and 11i). When given the following source:
6266 * A comment with backslash-newlines in it. %@{ %@} *\
6270 " A string with backslash-newlines in it %@{ %@} \\
6272 char apostrophe = '\\
6280 the compiler incorrectly fails with the diagnostics ``Non-terminating
6281 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
6282 Removing the lines with solitary backslashes solves the problem.
6284 @item Don't compile several files at once if output matters to you
6285 Some compilers, such as @acronym{HP}'s, report names of files being
6286 compiled when given more than one file operand. For instance:
6295 This can cause problems if you observe the output of the compiler to
6296 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
6297 b.o} solves the issue.
6299 @item Don't rely on @code{#error} failing
6300 The @sc{irix} C compiler does not fail when #error is preprocessed; it
6301 simply emits a diagnostic and continues, exiting successfully. So,
6302 instead of an error directive like @code{#error "Unsupported word size"}
6303 it is more portable to use an invalid directive like @code{#Unsupported
6304 word size} in Autoconf tests. In ordinary source code, @code{#error} is
6305 OK, since installers with inadequate compilers like @sc{irix} can simply
6306 examine these compilers' diagnostic output.
6308 @item Don't rely on correct @code{#line} support
6309 On Solaris, @command{c89} (at least Sun C 5.3 through 5.8)
6310 diagnoses @code{#line} directives whose line
6311 numbers are greater than 32767. Nothing in Posix
6312 makes this invalid. That is why Autoconf stopped issuing
6313 @code{#line} directives.
6316 @defmac AC_PROG_CC (@ovar{compiler-search-list})
6320 Determine a C compiler to use. If @code{CC} is not already set in the
6321 environment, check for @code{gcc} and @code{cc}, then for other C
6322 compilers. Set output variable @code{CC} to the name of the compiler
6325 This macro may, however, be invoked with an optional first argument
6326 which, if specified, must be a blank-separated list of C compilers to
6327 search for. This just gives the user an opportunity to specify an
6328 alternative search list for the C compiler. For example, if you didn't
6329 like the default order, then you could invoke @code{AC_PROG_CC} like
6333 AC_PROG_CC([gcc cl cc])
6336 If the C compiler does not handle function prototypes correctly by
6337 default, try to add an option to output variable @code{CC} to make it
6338 so. This macro tries various options that select standard-conformance
6339 modes on various systems.
6341 After calling this macro you can check whether the C compiler has been
6342 set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell
6344 @code{ac_cv_prog_cc_c89} is set to @samp{no}. See also
6345 @code{AC_C_PROTOTYPES} below.
6347 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
6348 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
6349 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
6350 where @acronym{GCC} does not accept @option{-g}), or @option{-g} for
6354 @defmac AC_PROG_CC_C_O
6355 @acindex{PROG_CC_C_O}
6356 @cvindex NO_MINUS_C_MINUS_O
6357 If the C compiler does not accept the @option{-c} and @option{-o} options
6358 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
6359 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
6360 the first @code{cc} in the path. The test fails if one fails. This
6361 macro was created for @acronym{GNU} Make to choose the default C compilation
6369 Set output variable @code{CPP} to a command that runs the
6370 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
6371 It is only portable to run @code{CPP} on files with a @file{.c}
6374 Some preprocessors don't indicate missing include files by the error
6375 status. For such preprocessors an internal variable is set that causes
6376 other macros to check the standard error from the preprocessor and
6377 consider the test failed if any warnings have been reported.
6378 For most preprocessors, though, warnings do not cause include-file
6379 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
6382 @defmac AC_PROG_CPP_WERROR
6383 @acindex{PROG_CPP_WERROR}
6385 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
6386 preprocessor as errors even if the preprocessor exit status indicates
6387 success. This is useful for avoiding headers that generate mandatory
6388 warnings, such as deprecation notices.
6392 The following macros check for C compiler or machine architecture
6393 features. To check for characteristics not listed here, use
6394 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6395 @code{AC_RUN_IFELSE} (@pxref{Runtime}).
6397 @defmac AC_PROG_CC_STDC
6398 @acindex{PROG_CC_STDC}
6399 If the C compiler cannot compile @acronym{ISO} Standard C (currently
6400 C99), try to add an option to output variable @code{CC} to make it work.
6401 If the compiler does not support C99, fall back to supporting
6402 @acronym{ANSI} C89 (@acronym{ISO} C90).
6404 After calling this macro you can check whether the C compiler has been
6405 set to accept Standard C; if not, the shell variable
6406 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
6409 @defmac AC_PROG_CC_C89
6410 @acindex{PROG_CC_C89}
6411 If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by
6412 default, try to add an option to output variable @code{CC} to make it
6413 so. This macro tries various options that select @acronym{ANSI} C89 on
6414 some system or another. It considers the compiler to be in
6415 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
6417 After calling this macro you can check whether the C compiler has been
6418 set to accept @acronym{ANSI} C89; if not, the shell variable
6419 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
6421 This macro is called automatically by @code{AC_PROG_CC}.
6424 @defmac AC_PROG_CC_C99
6425 @acindex{PROG_CC_C99}
6426 If the C compiler is not in C99 mode by default, try to add an
6427 option to output variable @code{CC} to make it so. This macro tries
6428 various options that select C99 on some system or another. It
6429 considers the compiler to be in C99 mode if it handles @code{_Bool},
6430 flexible arrays, @code{inline}, @code{long long int}, mixed code and
6431 declarations, named initialization of structs, @code{restrict}, varargs
6432 macros, variable declarations in @code{for} loops and variable length
6435 After calling this macro you can check whether the C compiler has been
6436 set to accept C99; if not, the shell variable
6437 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
6440 @defmac AC_C_BACKSLASH_A
6441 @acindex{HAVE_C_BACKSLASH_A}
6442 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
6445 This macro is obsolescent, as current C compilers understand @samp{\a}.
6446 New programs need not use this macro.
6449 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
6450 @acindex{C_BIGENDIAN}
6451 @cvindex WORDS_BIGENDIAN
6453 If words are stored with the most significant byte first (like Motorola
6454 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
6455 the least significant byte first (like Intel and VAX CPUs), execute
6456 @var{action-if-false}.
6458 This macro runs a test-case if endianness cannot be determined from the
6459 system header files. When cross-compiling, the test-case is not run but
6460 grep'ed for some magic values. @var{action-if-unknown} is executed if
6461 the latter case fails to determine the byte sex of the host system.
6463 The default for @var{action-if-true} is to define
6464 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
6465 nothing. And finally, the default for @var{action-if-unknown} is to
6466 abort configure and tell the installer which variable he should preset
6467 to bypass this test.
6473 If the C compiler does not fully support the @code{const} keyword,
6474 define @code{const} to be empty. Some C compilers that do
6475 not define @code{__STDC__} do support @code{const}; some compilers that
6476 define @code{__STDC__} do not completely support @code{const}. Programs
6477 can simply use @code{const} as if every C compiler supported it; for
6478 those that don't, the makefile or configuration header file
6479 defines it as empty.
6481 Occasionally installers use a C++ compiler to compile C code, typically
6482 because they lack a C compiler. This causes problems with @code{const},
6483 because C and C++ treat @code{const} differently. For example:
6490 is valid in C but not in C++. These differences unfortunately cannot be
6491 papered over by defining @code{const} to be empty.
6493 If @command{autoconf} detects this situation, it leaves @code{const} alone,
6494 as this generally yields better results in practice. However, using a
6495 C++ compiler to compile C code is not recommended or supported, and
6496 installers who run into trouble in this area should get a C compiler
6497 like @acronym{GCC} to compile their C code.
6499 This macro is obsolescent, as current C compilers support @code{const}.
6500 New programs need not use this macro.
6503 @defmac AC_C_RESTRICT
6504 @acindex{C_RESTRICT}
6506 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
6507 If it recognizes only a variant spelling (@code{__restrict},
6508 @code{__restrict__}, or @code{_Restrict}), then define
6509 @code{restrict} to that.
6510 Otherwise, define @code{restrict} to be empty.
6511 Thus, programs may simply use @code{restrict} as if every C compiler
6512 supported it; for those that do not, the makefile
6513 or configuration header defines it away.
6515 Although support in C++ for the @code{restrict} keyword is not
6516 required, several C++ compilers do accept the keyword.
6517 This macro works for them, too.
6520 @defmac AC_C_VOLATILE
6521 @acindex{C_VOLATILE}
6523 If the C compiler does not understand the keyword @code{volatile},
6524 define @code{volatile} to be empty. Programs can simply use
6525 @code{volatile} as if every C compiler supported it; for those that do
6526 not, the makefile or configuration header defines it as
6529 If the correctness of your program depends on the semantics of
6530 @code{volatile}, simply defining it to be empty does, in a sense, break
6531 your code. However, given that the compiler does not support
6532 @code{volatile}, you are at its mercy anyway. At least your
6533 program compiles, when it wouldn't before.
6534 @xref{Volatile Objects}, for more about @code{volatile}.
6536 In general, the @code{volatile} keyword is a standard C feature, so
6537 you might expect that @code{volatile} is available only when
6538 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
6539 support volatile, but does not define @code{__STDC__}.
6541 This macro is obsolescent, as current C compilers support @code{volatile}.
6542 New programs need not use this macro.
6548 If the C compiler supports the keyword @code{inline}, do nothing.
6549 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
6550 if it accepts one of those, otherwise define @code{inline} to be empty.
6553 @defmac AC_C_CHAR_UNSIGNED
6554 @acindex{C_CHAR_UNSIGNED}
6555 @cvindex __CHAR_UNSIGNED__
6556 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
6557 unless the C compiler predefines it.
6560 @defmac AC_C_STRINGIZE
6561 @acindex{C_STRINGIZE}
6562 @cvindex HAVE_STRINGIZE
6563 If the C preprocessor supports the stringizing operator, define
6564 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
6565 found in macros such as this:
6571 This macro is obsolescent, as current C compilers support the
6572 stringizing operator. New programs need not use this macro.
6577 @cvindex HAVE_TYPEOF
6579 If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either
6581 through a different spelling of the keyword (e.g., @code{__typeof__}),
6582 define @code{HAVE_TYPEOF}. If the support is available only through a
6583 different spelling, define @code{typeof} to that spelling.
6586 @defmac AC_C_PROTOTYPES
6587 @acindex{C_PROTOTYPES}
6589 @cvindex __PROTOTYPES
6591 If function prototypes are understood by the compiler (as determined by
6592 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
6593 Defining @code{__PROTOTYPES} is for the benefit of
6594 header files that cannot use macros that infringe on user name space.
6596 This macro is obsolescent, as current C compilers support prototypes.
6597 New programs need not use this macro.
6600 @defmac AC_PROG_GCC_TRADITIONAL
6601 @acindex{PROG_GCC_TRADITIONAL}
6603 Add @option{-traditional} to output variable @code{CC} if using the
6604 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6605 @option{-traditional}. That usually happens when the fixed header files
6606 have not been installed on an old system.
6608 This macro is obsolescent, since current versions of the @acronym{GNU} C
6609 compiler fix the header files automatically when installed.
6614 @subsection C++ Compiler Characteristics
6617 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6621 Determine a C++ compiler to use. Check whether the environment variable
6622 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6623 variable @code{CXX} to its value.
6625 Otherwise, if the macro is invoked without an argument, then search for
6626 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6627 then other names). If none of those checks succeed, then as a last
6628 resort set @code{CXX} to @code{g++}.
6630 This macro may, however, be invoked with an optional first argument
6631 which, if specified, must be a blank-separated list of C++ compilers to
6632 search for. This just gives the user an opportunity to specify an
6633 alternative search list for the C++ compiler. For example, if you
6634 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6638 AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++])
6641 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6642 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6643 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6644 systems where G++ does not accept @option{-g}), or @option{-g} for other
6648 @defmac AC_PROG_CXXCPP
6649 @acindex{PROG_CXXCPP}
6651 Set output variable @code{CXXCPP} to a command that runs the C++
6652 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6653 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6654 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6656 Some preprocessors don't indicate missing include files by the error
6657 status. For such preprocessors an internal variable is set that causes
6658 other macros to check the standard error from the preprocessor and
6659 consider the test failed if any warnings have been reported. However,
6660 it is not known whether such broken preprocessors exist for C++.
6663 @defmac AC_PROG_CXX_C_O
6664 @acindex{PROG_CXX_C_O}
6665 @cvindex CXX_NO_MINUS_C_MINUS_O
6666 Test whether the C++ compiler accepts the options @option{-c} and
6667 @option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O},
6672 @node Objective C Compiler
6673 @subsection Objective C Compiler Characteristics
6676 @defmac AC_PROG_OBJC (@ovar{compiler-search-list})
6680 Determine an Objective C compiler to use. If @code{OBJC} is not already
6681 set in the environment, check for Objective C compilers. Set output
6682 variable @code{OBJC} to the name of the compiler found.
6684 This macro may, however, be invoked with an optional first argument
6685 which, if specified, must be a blank-separated list of Objective C compilers to
6686 search for. This just gives the user an opportunity to specify an
6687 alternative search list for the Objective C compiler. For example, if you
6688 didn't like the default order, then you could invoke @code{AC_PROG_OBJC}
6692 AC_PROG_OBJC([gcc objcc objc])
6695 If using the @acronym{GNU} Objective C compiler, set shell variable
6696 @code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not
6697 already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C
6698 compiler (@option{-O2} on systems where @command{gcc} does not accept
6699 @option{-g}), or @option{-g} for other compilers.
6702 @defmac AC_PROG_OBJCCPP
6703 @acindex{PROG_OBJCCPP}
6705 Set output variable @code{OBJCCPP} to a command that runs the Objective C
6706 preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used.
6710 @node Erlang Compiler and Interpreter
6711 @subsection Erlang Compiler and Interpreter Characteristics
6714 Autoconf defines the following macros for determining paths to the essential
6715 Erlang/OTP programs:
6717 @defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path})
6718 @acindex{ERLANG_PATH_ERLC}
6721 Determine an Erlang compiler to use. If @code{ERLC} is not already set in the
6722 environment, check for @command{erlc}. Set output variable @code{ERLC} to the
6723 complete path of the compiler command found. In addition, if @code{ERLCFLAGS}
6724 is not set in the environment, set it to an empty value.
6726 The two optional arguments have the same meaning as the two last arguments of
6727 macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For
6728 example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin}
6732 AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin])
6736 @defmac AC_ERLANG_NEED_ERLC (@ovar{path})
6737 @acindex{ERLANG_NEED_ERLC}
6738 A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an
6739 error message and exits the @command{configure} script if the @command{erlc}
6740 program is not found.
6743 @defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path})
6744 @acindex{ERLANG_PATH_ERL}
6746 Determine an Erlang interpreter to use. If @code{ERL} is not already set in the
6747 environment, check for @command{erl}. Set output variable @code{ERL} to the
6748 complete path of the interpreter command found.
6750 The two optional arguments have the same meaning as the two last arguments of
6751 macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For
6752 example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin}
6756 AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin])
6760 @defmac AC_ERLANG_NEED_ERL (@ovar{path})
6761 @acindex{ERLANG_NEED_ERL}
6762 A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an
6763 error message and exits the @command{configure} script if the @command{erl}
6764 program is not found.
6768 @node Fortran Compiler
6769 @subsection Fortran Compiler Characteristics
6773 The Autoconf Fortran support is divided into two categories: legacy
6774 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6775 The former are intended for traditional Fortran 77 code, and have output
6776 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6777 are for newer programs that can (or must) compile under the newer
6778 Fortran standards, and have output variables like @code{FC},
6779 @code{FCFLAGS}, and @code{FCLIBS}.
6781 Except for two new macros @code{AC_FC_SRCEXT} and
6782 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6783 behave almost identically, and so they are documented together in this
6787 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6791 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6792 set in the environment, then check for @code{g77} and @code{f77}, and
6793 then some other names. Set the output variable @code{F77} to the name
6794 of the compiler found.
6796 This macro may, however, be invoked with an optional first argument
6797 which, if specified, must be a blank-separated list of Fortran 77
6798 compilers to search for. This just gives the user an opportunity to
6799 specify an alternative search list for the Fortran 77 compiler. For
6800 example, if you didn't like the default order, then you could invoke
6801 @code{AC_PROG_F77} like this:
6804 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6807 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6808 set the shell variable @code{G77} to @samp{yes}.
6809 If the output variable @code{FFLAGS} was not already set in the
6810 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6811 where @code{g77} does not accept @option{-g}). Otherwise, set
6812 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6815 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6819 Determine a Fortran compiler to use. If @code{FC} is not already set in
6820 the environment, then @code{dialect} is a hint to indicate what Fortran
6821 dialect to search for; the default is to search for the newest available
6822 dialect. Set the output variable @code{FC} to the name of the compiler
6825 By default, newer dialects are preferred over older dialects, but if
6826 @code{dialect} is specified then older dialects are preferred starting
6827 with the specified dialect. @code{dialect} can currently be one of
6828 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6829 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6830 and no attempt is made to guarantee that a particular language standard
6831 is actually supported. Thus, it is preferable that you avoid the
6832 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6833 the latest Fortran standard.
6835 This macro may, alternatively, be invoked with an optional first argument
6836 which, if specified, must be a blank-separated list of Fortran
6837 compilers to search for, just as in @code{AC_PROG_F77}.
6839 If the output variable @code{FCFLAGS} was not already set in the
6840 environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or
6841 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6842 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6845 @defmac AC_PROG_F77_C_O
6846 @defmacx AC_PROG_FC_C_O
6847 @acindex{PROG_F77_C_O}
6848 @acindex{PROG_FC_C_O}
6849 @cvindex F77_NO_MINUS_C_MINUS_O
6850 @cvindex FC_NO_MINUS_C_MINUS_O
6851 Test whether the Fortran compiler accepts the options @option{-c} and
6852 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6853 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6856 The following macros check for Fortran compiler characteristics.
6857 To check for characteristics not listed here, use
6858 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6859 @code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the
6860 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6861 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6864 @defmac AC_F77_LIBRARY_LDFLAGS
6865 @defmacx AC_FC_LIBRARY_LDFLAGS
6866 @acindex{F77_LIBRARY_LDFLAGS}
6868 @acindex{FC_LIBRARY_LDFLAGS}
6870 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6871 @dfn{Fortran intrinsic and runtime libraries} that are required to
6872 successfully link a Fortran program or shared library. The output
6873 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6874 should be included after @code{LIBS} when linking).
6876 This macro is intended to be used in those situations when it is
6877 necessary to mix, e.g., C++ and Fortran source code in a single
6878 program or shared library (@pxref{Mixing Fortran 77 With C and C++, , ,
6879 automake, @acronym{GNU} Automake}).
6881 For example, if object files from a C++ and Fortran compiler must be
6882 linked together, then the C++ compiler/linker must be used for linking
6883 (since special C++-ish things need to happen at link time like calling
6884 global constructors, instantiating templates, enabling exception
6887 However, the Fortran intrinsic and runtime libraries must be linked in
6888 as well, but the C++ compiler/linker doesn't know by default how to add
6889 these Fortran 77 libraries. Hence, this macro was created to determine
6890 these Fortran libraries.
6892 The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6893 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to
6894 link C/C++ with Fortran; see below.
6897 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6898 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6899 @acindex{F77_DUMMY_MAIN}
6900 @cvindex F77_DUMMY_MAIN
6901 With many compilers, the Fortran libraries detected by
6902 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6903 their own @code{main} entry function that initializes things like
6904 Fortran I/O, and which then calls a user-provided entry function named
6905 (say) @code{MAIN__} to run the user's program. The
6906 @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or
6907 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with
6910 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6911 one prefers to provide one's own @code{main} and skip the Fortran
6912 library initializations. In this case, however, one may still need to
6913 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6914 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6915 detects whether any such routine is @emph{required} for linking, and
6916 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6917 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6918 was found, and @code{none} when no such dummy main is needed.
6920 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6921 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6922 @emph{if} it is required. @var{action-if-not-found} defaults to
6923 exiting with an error.
6925 In order to link with Fortran routines, the user's C/C++ program should
6926 then include the following code to define the dummy main if it is
6930 #ifdef F77_DUMMY_MAIN
6934 int F77_DUMMY_MAIN() @{ return 1; @}
6938 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6940 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6941 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6942 explicitly unless one wants to change the default actions.
6951 As discussed above, many Fortran libraries allow you to provide an entry
6952 point called (say) @code{MAIN__} instead of the usual @code{main}, which
6953 is then called by a @code{main} function in the Fortran libraries that
6954 initializes things like Fortran I/O@. The
6955 @code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is
6956 @emph{possible} to utilize such an alternate main function, and defines
6957 @code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no
6958 alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are
6959 simply defined to @code{main}.)
6961 Thus, when calling Fortran routines from C that perform things like I/O,
6962 one should use this macro and name the "main" function
6963 @code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}.
6966 @defmac AC_F77_WRAPPERS
6967 @defmacx AC_FC_WRAPPERS
6968 @acindex{F77_WRAPPERS}
6971 @acindex{FC_WRAPPERS}
6974 Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)},
6975 @code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly
6976 mangle the names of C/C++ identifiers, and identifiers with underscores,
6977 respectively, so that they match the name-mangling scheme used by the
6980 Fortran is case-insensitive, and in order to achieve this the Fortran
6981 compiler converts all identifiers into a canonical case and format. To
6982 call a Fortran subroutine from C or to write a C function that is
6983 callable from Fortran, the C program must explicitly use identifiers in
6984 the format expected by the Fortran compiler. In order to do this, one
6985 simply wraps all C identifiers in one of the macros provided by
6986 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
6987 you have the following Fortran 77 subroutine:
6990 subroutine foobar (x, y)
6991 double precision x, y
6997 You would then declare its prototype in C or C++ as:
7000 #define FOOBAR_F77 F77_FUNC (foobar, FOOBAR)
7002 extern "C" /* prevent C++ name mangling */
7004 void FOOBAR_F77(double *x, double *y);
7007 Note that we pass both the lowercase and uppercase versions of the
7008 function name to @code{F77_FUNC} so that it can select the right one.
7009 Note also that all parameters to Fortran 77 routines are passed as
7010 pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU}
7013 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
7015 Although Autoconf tries to be intelligent about detecting the
7016 name-mangling scheme of the Fortran compiler, there may be Fortran
7017 compilers that it doesn't support yet. In this case, the above code
7018 generates a compile-time error, but some other behavior
7019 (e.g., disabling Fortran-related features) can be induced by checking
7020 whether @code{F77_FUNC} or @code{FC_FUNC} is defined.
7022 Now, to call that routine from a C program, we would do something like:
7026 double x = 2.7183, y;
7027 FOOBAR_F77 (&x, &y);
7031 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
7032 you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of
7033 @code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is
7034 because some Fortran compilers mangle names differently if they contain
7038 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
7039 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
7042 Given an identifier @var{name}, set the shell variable @var{shellvar} to
7043 hold the mangled version @var{name} according to the rules of the
7044 Fortran linker (see also @code{AC_F77_WRAPPERS} or
7045 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
7046 supplied, the shell variable is simply @var{name}. The purpose of
7047 this macro is to give the caller a way to access the name-mangling
7048 information other than through the C preprocessor as above, for example,
7049 to call Fortran routines from some language other than C/C++.
7052 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
7054 By default, the @code{FC} macros perform their tests using a @file{.f}
7055 extension for source-code files. Some compilers, however, only enable
7056 newer language features for appropriately named files, e.g., Fortran 90
7057 features only for @file{.f90} files. On the other hand, some other
7058 compilers expect all source files to end in @file{.f} and require
7059 special flags to support other file name extensions. The
7060 @code{AC_FC_SRCEXT} macro deals with both of these issues.
7062 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
7063 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
7064 contain the dot). If any special compiler flags are needed for this, it
7065 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
7066 extension and these flags are then used for all subsequent @code{FC} tests
7067 (until @code{AC_FC_SRCEXT} is called again).
7069 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
7070 @file{.f90} extension in future tests, and it would set a
7071 @code{FCFLAGS_f90} output variable with any extra flags that are needed
7072 to compile such files.
7074 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
7075 @code{FCFLAGS}, for two reasons based on the limitations of some
7076 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
7077 time, so files with different extensions must be compiled separately.
7078 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
7079 the source-code file name when compiling. So, continuing the example
7080 above, you might compile a @file{foo.f90} file in your makefile with the
7085 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90'
7088 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
7089 extension, it calls @var{action-if-success} (defaults to nothing). If
7090 it fails, and cannot find a way to make the @code{FC} compiler accept such
7091 files, it calls @var{action-if-failure} (defaults to exiting with an
7096 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
7097 @acindex{FC_FREEFORM}
7099 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
7100 (@code{$FC}) allows free-format source code (as opposed to the older
7101 fixed-format style from Fortran 77). If necessary, it may add some
7102 additional flags to @code{FCFLAGS}.
7104 This macro is most important if you are using the default @file{.f}
7105 extension, since many compilers interpret this extension as indicating
7106 fixed-format source unless an additional flag is supplied. If you
7107 specify a different extension with @code{AC_FC_SRCEXT}, such as
7108 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily
7109 succeeds without modifying @code{FCFLAGS}.
7111 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
7112 calls @var{action-if-success} (defaults to nothing). If it fails, it
7113 calls @var{action-if-failure} (defaults to exiting with an error
7117 @node System Services
7118 @section System Services
7120 The following macros check for operating system services or capabilities.
7125 @cindex X Window System
7126 Try to locate the X Window System include files and libraries. If the
7127 user gave the command line options @option{--x-includes=@var{dir}} and
7128 @option{--x-libraries=@var{dir}}, use those directories.
7130 If either or both were not given, get the missing values by running
7131 @code{xmkmf} (or an executable pointed to by the @code{XMKMF}
7132 environment variable) on a trivial @file{Imakefile} and examining the
7133 makefile that it produces. Setting @code{XMKMF} to @samp{false}
7134 disables this method.
7136 If this method fails to find the X Window System, @command{configure}
7137 looks for the files in several directories where they often reside.
7138 If either method is successful, set the shell variables
7139 @code{x_includes} and @code{x_libraries} to their locations, unless they
7140 are in directories the compiler searches by default.
7142 If both methods fail, or the user gave the command line option
7143 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
7144 otherwise set it to the empty string.
7147 @defmac AC_PATH_XTRA
7151 @ovindex X_EXTRA_LIBS
7153 @cvindex X_DISPLAY_MISSING
7154 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
7155 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
7156 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
7159 This macro also checks for special libraries that some systems need in
7160 order to compile X programs. It adds any that the system needs to
7161 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
7162 libraries that need to be linked with before @option{-lX11}, and adds
7163 any found to the output variable @code{X_PRE_LIBS}.
7165 @c This is an incomplete kludge. Make a real way to do it.
7166 @c If you need to check for other X functions or libraries yourself, then
7167 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
7168 @c @code{LIBS} temporarily, like this: (FIXME - add example)
7171 @defmac AC_SYS_INTERPRETER
7172 @acindex{SYS_INTERPRETER}
7173 Check whether the system supports starting scripts with a line of the
7174 form @samp{#!/bin/sh} to select the interpreter to use for the script.
7175 After running this macro, shell code in @file{configure.ac} can check
7176 the shell variable @code{interpval}; it is set to @samp{yes}
7177 if the system supports @samp{#!}, @samp{no} if not.
7180 @defmac AC_SYS_LARGEFILE
7181 @acindex{SYS_LARGEFILE}
7182 @cvindex _FILE_OFFSET_BITS
7183 @cvindex _LARGE_FILES
7185 @cindex Large file support
7188 @uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html,
7189 large-file support}. On some hosts, one must use special compiler
7190 options to build programs that can access large files. Append any such
7191 options to the output variable @code{CC}. Define
7192 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
7194 Large-file support can be disabled by configuring with the
7195 @option{--disable-largefile} option.
7197 If you use this macro, check that your program works even when
7198 @code{off_t} is wider than @code{long int}, since this is common when
7199 large-file support is enabled. For example, it is not correct to print
7200 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
7203 The LFS introduced the @code{fseeko} and @code{ftello} functions to
7204 replace their C counterparts @code{fseek} and @code{ftell} that do not
7205 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
7206 prototypes available when using them and large-file support is
7210 @defmac AC_SYS_LONG_FILE_NAMES
7211 @acindex{SYS_LONG_FILE_NAMES}
7212 @cvindex HAVE_LONG_FILE_NAMES
7213 If the system supports file names longer than 14 characters, define
7214 @code{HAVE_LONG_FILE_NAMES}.
7217 @defmac AC_SYS_POSIX_TERMIOS
7218 @acindex{SYS_POSIX_TERMIOS}
7219 @cindex Posix termios headers
7220 @cindex termios Posix headers
7221 Check to see if the Posix termios headers and functions are available on the
7222 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
7223 @samp{yes}. If not, set the variable to @samp{no}.
7226 @node Posix Variants
7227 @section Posix Variants
7229 The following macros check for certain operating systems that need
7230 special treatment for some programs, due to exceptional oddities in
7231 their header files or libraries. These macros are warts; they will be
7232 replaced by a more systematic approach, based on the functions they make
7233 available or the environments they provide.
7237 @cvindex _ALL_SOURCE
7238 If on @acronym{AIX}, define @code{_ALL_SOURCE}.
7239 Allows the use of some @acronym{BSD}
7240 functions. Should be called before any macros that run the C compiler.
7243 @defmac AC_GNU_SOURCE
7244 @acindex{GNU_SOURCE}
7245 @cvindex _GNU_SOURCE
7246 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
7247 Allows the use of some @acronym{GNU} functions. Should be called
7248 before any macros that run the C compiler.
7251 @defmac AC_ISC_POSIX
7254 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
7255 variable @code{LIBS} if necessary for Posix facilities. Call this
7256 after @code{AC_PROG_CC} and before any other macros that use Posix
7257 interfaces. @sc{interactive} Unix is no longer sold, and Sun says that
7258 they will drop support for it on 2006-07-23, so this macro is becoming
7265 @cvindex _POSIX_SOURCE
7266 @cvindex _POSIX_1_SOURCE
7267 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
7268 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
7269 facilities. Should be called before any macros that run the C compiler.
7272 @defmac AC_USE_SYSTEM_EXTENSIONS
7273 @acindex{USE_SYSTEM_EXTENSIONS}
7274 @cvindex _ALL_SOURCE
7275 @cvindex _GNU_SOURCE
7277 @cvindex _POSIX_1_SOURCE
7278 @cvindex _POSIX_PTHREAD_SEMANTICS
7279 @cvindex _POSIX_SOURCE
7280 @cvindex __EXTENSIONS__
7281 If possible, enable extensions to Posix on hosts that normally disable
7282 the extensions, typically due to standards-conformance namespace issues.
7283 This may involve defining @code{__EXTENSIONS__} and
7284 @code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris. This
7285 macro also has the combined effects of @code{AC_GNU_SOURCE},
7286 @code{AC_AIX}, and @code{AC_MINIX}.
7290 @node Erlang Libraries
7291 @section Erlang Libraries
7292 @cindex Erlang, Library, checking
7294 The following macros check for an installation of Erlang/OTP, and for the
7295 presence of certain Erlang libraries. All those macros require the
7296 configuration of an Erlang interpreter and an Erlang compiler
7297 (@pxref{Erlang Compiler and Interpreter}).
7299 @defmac AC_ERLANG_SUBST_ROOT_DIR
7300 @acindex{ERLANG_SUBST_ROOT_DIR}
7301 @ovindex ERLANG_ROOT_DIR
7303 Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory
7304 in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0}
7305 function). The result of this test is cached if caching is enabled when running
7306 @command{configure}.
7309 @defmac AC_ERLANG_SUBST_LIB_DIR
7310 @acindex{ERLANG_SUBST_LIB_DIR}
7311 @ovindex ERLANG_LIB_DIR
7313 Set the output variable @code{ERLANG_LIB_DIR} to the path of the library
7314 directory of Erlang/OTP (as returned by Erlang's
7315 @code{code:lib_dir/0} function), which subdirectories each contain an installed
7316 Erlang/OTP library. The result of this test is cached if caching is enabled
7317 when running @command{configure}.
7320 @defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found})
7321 @acindex{ERLANG_CHECK_LIB}
7322 @ovindex ERLANG_LIB_DIR_@var{library}
7324 Test whether the Erlang/OTP library @var{library} is installed by calling
7325 Erlang's @code{code:lib_dir/1} function. The result of this test is cached if
7326 caching is enabled when running @command{configure}. @var{action-if-found} is a
7327 list of shell commands to run if the library is installed;
7328 @var{action-if-not-found} is a list of shell commands to run if it is not.
7329 Additionally, if the library is installed, the output variable
7330 @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the library
7331 installation directory. For example, to check if library @code{stdlib} is
7335 AC_ERLANG_CHECK_LIB([stdlib],
7336 [echo "stdlib is installed in $ERLANG_LIB_DIR_stdlib"],
7337 [AC_MSG_ERROR([stdlib was not found!])])
7341 In addition to the above macros, which test installed Erlang libraries, the
7342 following macros determine the paths to the directories into which newly built
7343 Erlang libraries are to be installed:
7345 @defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR
7346 @acindex{ERLANG_SUBST_INSTALL_LIB_DIR}
7347 @ovindex ERLANG_INSTALL_LIB_DIR
7349 Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into
7350 which every built Erlang library should be installed in a separate subdirectory.
7351 If this variable is not set in the environment when @command{configure} runs,
7352 its default value is @code{$ERLANG_LIB_DIR}, which value is set by the
7353 @code{AC_ERLANG_SUBST_LIB_DIR} macro.
7356 @defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version})
7357 @acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR}
7358 @ovindex ERLANG_INSTALL_LIB_DIR_@var{library}
7360 Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the
7361 directory into which the built Erlang library @var{library} version
7362 @var{version} should be installed. If this variable is not set in the
7363 environment when @command{configure} runs, its default value is
7364 @samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the
7365 @code{ERLANG_INSTALL_LIB_DIR} variable being set by the
7366 @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro.
7373 @c ========================================================= Writing Tests
7376 @chapter Writing Tests
7378 If the existing feature tests don't do something you need, you have to
7379 write new ones. These macros are the building blocks. They provide
7380 ways for other macros to check whether various kinds of features are
7381 available and report the results.
7383 This chapter contains some suggestions and some of the reasons why the
7384 existing tests are written the way they are. You can also learn a lot
7385 about how to write Autoconf tests by looking at the existing ones. If
7386 something goes wrong in one or more of the Autoconf tests, this
7387 information can help you understand the assumptions behind them, which
7388 might help you figure out how to best solve the problem.
7390 These macros check the output of the compiler system of the current
7391 language (@pxref{Language Choice}). They do not cache the results of
7392 their tests for future use (@pxref{Caching Results}), because they don't
7393 know enough about the information they are checking for to generate a
7394 cache variable name. They also do not print any messages, for the same
7395 reason. The checks for particular kinds of features call these macros
7396 and do cache their results and print messages about what they're
7399 When you write a feature test that could be applicable to more than one
7400 software package, the best thing to do is encapsulate it in a new macro.
7401 @xref{Writing Autoconf Macros}, for how to do that.
7404 * Language Choice:: Selecting which language to use for testing
7405 * Writing Test Programs:: Forging source files for compilers
7406 * Running the Preprocessor:: Detecting preprocessor symbols
7407 * Running the Compiler:: Detecting language or header features
7408 * Running the Linker:: Detecting library features
7409 * Runtime:: Testing for runtime features
7410 * Systemology:: A zoology of operating systems
7411 * Multiple Cases:: Tests for several possible values
7414 @node Language Choice
7415 @section Language Choice
7418 Autoconf-generated @command{configure} scripts check for the C compiler and
7419 its features by default. Packages that use other programming languages
7420 (maybe more than one, e.g., C and C++) need to test features of the
7421 compilers for the respective languages. The following macros determine
7422 which programming language is used in the subsequent tests in
7423 @file{configure.ac}.
7425 @defmac AC_LANG (@var{language})
7426 Do compilation tests using the compiler, preprocessor, and file
7427 extensions for the specified @var{language}.
7429 Supported languages are:
7433 Do compilation tests using @code{CC} and @code{CPP} and use extension
7434 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
7435 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
7438 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
7439 extension @file{.C} for test programs. Use compilation flags:
7440 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
7441 @code{CXXFLAGS} with @code{CXX}.
7444 Do compilation tests using @code{F77} and use extension @file{.f} for
7445 test programs. Use compilation flags: @code{FFLAGS}.
7448 Do compilation tests using @code{FC} and use extension @file{.f} (or
7449 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
7450 compilation flags: @code{FCFLAGS}.
7456 Compile and execute tests using @code{ERLC} and @code{ERL} and use extension
7457 @file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}.
7460 Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use
7461 extension @file{.m} for test programs. Use compilation flags:
7462 @code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and
7463 @code{OBJCFLAGS} with @code{OBJC}.
7467 @defmac AC_LANG_PUSH (@var{language})
7469 Remember the current language (as set by @code{AC_LANG}) on a stack, and
7470 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
7471 in macros that need to temporarily switch to a particular language.
7474 @defmac AC_LANG_POP (@ovar{language})
7476 Select the language that is saved on the top of the stack, as set by
7477 @code{AC_LANG_PUSH}, and remove it from the stack.
7479 If given, @var{language} specifies the language we just @emph{quit}. It
7480 is a good idea to specify it when it's known (which should be the
7481 case@dots{}), since Autoconf detects inconsistencies.
7484 AC_LANG_PUSH([Fortran 77])
7485 # Perform some tests on Fortran 77.
7487 AC_LANG_POP([Fortran 77])
7491 @defmac AC_LANG_ASSERT (@var{language})
7492 @acindex{LANG_ASSERT} Check statically that the current language is
7493 @var{language}. You should use this in your language specific macros
7494 to avoid that they be called with an inappropriate language.
7496 This macro runs only at @command{autoconf} time, and incurs no cost at
7497 @command{configure} time. Sadly enough and because Autoconf is a two
7498 layer language @footnote{Because M4 is not aware of Sh code,
7499 especially conditionals, some optimizations that look nice statically
7500 may produce incorrect results at runtime.}, the macros
7501 @code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'',
7502 therefore as much as possible you ought to avoid using them to wrap
7503 your code, rather, require from the user to run the macro with a
7504 correct current language, and check it with @code{AC_LANG_ASSERT}.
7505 And anyway, that may help the user understand she is running a Fortran
7506 macro while expecting a result about her Fortran 77 compiler@dots{}
7510 @defmac AC_REQUIRE_CPP
7511 @acindex{REQUIRE_CPP}
7512 Ensure that whichever preprocessor would currently be used for tests has
7513 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
7514 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
7515 depending on which language is current.
7519 @node Writing Test Programs
7520 @section Writing Test Programs
7522 Autoconf tests follow a common scheme: feed some program with some
7523 input, and most of the time, feed a compiler with some source file.
7524 This section is dedicated to these source samples.
7527 * Guidelines:: General rules for writing test programs
7528 * Test Functions:: Avoiding pitfalls in test programs
7529 * Generating Sources:: Source program boilerplate
7533 @subsection Guidelines for Test Programs
7535 The most important rule to follow when writing testing samples is:
7537 @center @emph{Look for realism.}
7539 This motto means that testing samples must be written with the same
7540 strictness as real programs are written. In particular, you should
7541 avoid ``shortcuts'' and simplifications.
7543 Don't just play with the preprocessor if you want to prepare a
7544 compilation. For instance, using @command{cpp} to check whether a header is
7545 functional might let your @command{configure} accept a header which
7546 causes some @emph{compiler} error. Do not hesitate to check a header with
7547 other headers included before, especially required headers.
7549 Make sure the symbols you use are properly defined, i.e., refrain for
7550 simply declaring a function yourself instead of including the proper
7553 Test programs should not write to standard output. They
7554 should exit with status 0 if the test succeeds, and with status 1
7555 otherwise, so that success
7556 can be distinguished easily from a core dump or other failure;
7557 segmentation violations and other failures produce a nonzero exit
7558 status. Unless you arrange for @code{exit} to be declared, test
7559 programs should @code{return}, not @code{exit}, from @code{main},
7560 because on many systems @code{exit} is not declared by default.
7562 Test programs can use @code{#if} or @code{#ifdef} to check the values of
7563 preprocessor macros defined by tests that have already run. For
7564 example, if you call @code{AC_HEADER_STDBOOL}, then later on in
7565 @file{configure.ac} you can have a test program that includes
7566 @file{stdbool.h} conditionally:
7571 # include <stdbool.h>
7576 If a test program needs to use or create a data file, give it a name
7577 that starts with @file{conftest}, such as @file{conftest.data}. The
7578 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
7579 after running test programs and if the script is interrupted.
7581 @node Test Functions
7582 @subsection Test Functions
7584 These days it's safe to assume support for function prototypes
7585 (introduced in C89).
7587 Functions that test programs declare should also be conditionalized for
7588 C++, which requires @samp{extern "C"} prototypes. Make sure to not
7589 include any header files containing clashing prototypes.
7595 void *valloc (size_t);
7598 If a test program calls a function with invalid parameters (just to see
7599 whether it exists), organize the program to ensure that it never invokes
7600 that function. You can do this by calling it in another function that is
7601 never invoked. You can't do it by putting it after a call to
7602 @code{exit}, because @acronym{GCC} version 2 knows that @code{exit}
7604 and optimizes out any code that follows it in the same block.
7606 If you include any header files, be sure to call the functions
7607 relevant to them with the correct number of arguments, even if they are
7608 just 0, to avoid compilation errors due to prototypes. @acronym{GCC}
7610 has internal prototypes for several functions that it automatically
7611 inlines; for example, @code{memcpy}. To avoid errors when checking for
7612 them, either pass them the correct number of arguments or redeclare them
7613 with a different return type (such as @code{char}).
7616 @node Generating Sources
7617 @subsection Generating Sources
7619 Autoconf provides a set of macros that can be used to generate test
7620 source files. They are written to be language generic, i.e., they
7621 actually depend on the current language (@pxref{Language Choice}) to
7622 ``format'' the output properly.
7625 @defmac AC_LANG_CONFTEST (@var{source})
7626 @acindex{LANG_CONFTEST}
7627 Save the @var{source} text in the current test source file:
7628 @file{conftest.@var{extension}} where the @var{extension} depends on the
7631 Note that the @var{source} is evaluated exactly once, like regular
7632 Autoconf macro arguments, and therefore (i) you may pass a macro
7633 invocation, (ii) if not, be sure to double quote if needed.
7636 @defmac AC_LANG_SOURCE (@var{source})
7637 @acindex{LANG_SOURCE}
7638 Expands into the @var{source}, with the definition of
7639 all the @code{AC_DEFINE} performed so far.
7642 For instance executing (observe the double quotation!):
7645 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7646 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7647 [Greetings string.])
7650 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
7651 gcc -E -dD -o - conftest.c
7661 #define PACKAGE_NAME "Hello"
7662 #define PACKAGE_TARNAME "hello"
7663 #define PACKAGE_VERSION "1.0"
7664 #define PACKAGE_STRING "Hello 1.0"
7665 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7666 #define HELLO_WORLD "Hello, World\n"
7668 const char hw[] = "Hello, World\n";
7671 When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions
7672 are not automatically translated into constants in the source code by this
7675 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
7676 @acindex{LANG_PROGRAM}
7677 Expands into a source file which consists of the @var{prologue}, and
7678 then @var{body} as body of the main function (e.g., @code{main} in
7679 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
7686 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7687 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7688 [Greetings string.])
7690 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7691 [[fputs (hw, stdout);]])])
7692 gcc -E -dD -o - conftest.c
7702 #define PACKAGE_NAME "Hello"
7703 #define PACKAGE_TARNAME "hello"
7704 #define PACKAGE_VERSION "1.0"
7705 #define PACKAGE_STRING "Hello 1.0"
7706 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
7707 #define HELLO_WORLD "Hello, World\n"
7709 const char hw[] = "Hello, World\n";
7719 In Erlang tests, the created source file is that of an Erlang module called
7720 @code{conftest} (@file{conftest.erl}). This module defines and exports at least
7721 one @code{start/0} function, which is called to perform the test. The
7722 @var{prologue} is optional code that is inserted between the module header and
7723 the @code{start/0} function definition. @var{body} is the body of the
7724 @code{start/0} function without the final period (@pxref{Runtime}, about
7725 constraints on this function's behavior).
7730 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7733 [AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]],
7734 [[io:format("~s~n", [?HELLO_WORLD])]])])
7744 -define(HELLO_WORLD, "Hello, world!").
7746 io:format("~s~n", [?HELLO_WORLD])
7750 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
7752 Expands into a source file which consists of the @var{prologue}, and
7753 then a call to the @var{function} as body of the main function (e.g.,
7754 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
7755 of the latter are available.
7757 This function will probably be replaced in the future by a version
7758 which would enable specifying the arguments. The use of this macro is
7759 not encouraged, as it violates strongly the typing system.
7761 This macro cannot be used for Erlang tests.
7764 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
7765 @acindex{LANG_FUNC_LINK_TRY}
7766 Expands into a source file which uses the @var{function} in the body of
7767 the main function (e.g., @code{main} in C). Since it uses
7768 @code{AC_LANG_PROGRAM}, the features of the latter are available.
7770 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
7771 It is considered to be severely broken, and in the future will be
7772 removed in favor of actual function calls (with properly typed
7775 This macro cannot be used for Erlang tests.
7778 @node Running the Preprocessor
7779 @section Running the Preprocessor
7781 Sometimes one might need to run the preprocessor on some source file.
7782 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
7783 your project, not merely run the preprocessor on it; therefore you
7784 certainly want to run the compiler, not the preprocessor. Resist the
7785 temptation of following the easiest path.
7787 Nevertheless, if you need to run the preprocessor, then use
7788 @code{AC_PREPROC_IFELSE}.
7790 The macros described in this section cannot be used for tests in Erlang or
7791 Fortran, since those languages require no preprocessor.
7793 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7794 @acindex{PREPROC_IFELSE}
7795 Run the preprocessor of the current language (@pxref{Language Choice})
7796 on the @var{input}, run the shell commands @var{action-if-true} on
7797 success, @var{action-if-false} otherwise. The @var{input} can be made
7798 by @code{AC_LANG_PROGRAM} and friends.
7800 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
7801 @option{-g}, @option{-O}, etc.@: are not valid options to many C
7804 It is customary to report unexpected failures with
7805 @code{AC_MSG_FAILURE}.
7811 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
7812 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
7813 [Greetings string.])
7815 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
7816 [[fputs (hw, stdout);]])],
7817 [AC_MSG_RESULT([OK])],
7818 [AC_MSG_FAILURE([unexpected preprocessor failure])])
7825 checking for gcc... gcc
7826 checking for C compiler default output file name... a.out
7827 checking whether the C compiler works... yes
7828 checking whether we are cross compiling... no
7829 checking for suffix of executables...
7830 checking for suffix of object files... o
7831 checking whether we are using the GNU C compiler... yes
7832 checking whether gcc accepts -g... yes
7833 checking for gcc option to accept ISO C89... none needed
7834 checking how to run the C preprocessor... gcc -E
7840 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7841 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7842 it impossible to use it to elaborate sources. You are encouraged to
7843 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7844 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7845 to run the @emph{preprocessor} and not the compiler?
7847 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7848 @acindex{EGREP_HEADER}
7849 If the output of running the preprocessor on the system header file
7850 @var{header-file} matches the extended regular expression
7851 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7852 execute @var{action-if-not-found}.
7855 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7857 @var{program} is the text of a C or C++ program, on which shell
7858 variable, back quote, and backslash substitutions are performed. If the
7859 output of running the preprocessor on @var{program} matches the
7860 extended regular expression @var{pattern}, execute shell commands
7861 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7866 @node Running the Compiler
7867 @section Running the Compiler
7869 To check for a syntax feature of the current language's (@pxref{Language
7870 Choice}) compiler, such as whether it recognizes a certain keyword, or
7871 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7872 to compile a small program that uses that feature.
7874 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7875 @acindex{COMPILE_IFELSE}
7876 Run the compiler and compilation flags of the current language
7877 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7878 @var{action-if-true} on success, @var{action-if-false} otherwise. The
7879 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7881 It is customary to report unexpected failures with
7882 @code{AC_MSG_FAILURE}. This macro does not try to link; use
7883 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7888 For tests in Erlang, the @var{input} must be the source code of a module named
7889 @code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam}
7890 file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is
7891 recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure
7892 that the Erlang module has the right name.
7894 @node Running the Linker
7895 @section Running the Linker
7897 To check for a library, a function, or a global variable, Autoconf
7898 @command{configure} scripts try to compile and link a small program that
7899 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
7900 @code{ar} on the C library to try to figure out which functions are
7901 available. Trying to link with the function is usually a more reliable
7902 approach because it avoids dealing with the variations in the options
7903 and output formats of @code{nm} and @code{ar} and in the location of the
7904 standard libraries. It also allows configuring for cross-compilation or
7905 checking a function's runtime behavior if needed. On the other hand,
7906 it can be slower than scanning the libraries once, but accuracy is more
7907 important than speed.
7909 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7910 functions and global variables. It is also used by @code{AC_CHECK_LIB}
7911 to check for libraries (@pxref{Libraries}), by adding the library being
7912 checked for to @code{LIBS} temporarily and trying to link a small
7916 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
7917 @acindex{LINK_IFELSE}
7918 Run the compiler (and compilation flags) and the linker of the current
7919 language (@pxref{Language Choice}) on the @var{input}, run the shell
7920 commands @var{action-if-true} on success, @var{action-if-false}
7921 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7924 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7925 current compilation flags.
7927 It is customary to report unexpected failures with
7928 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
7929 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}).
7932 The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang
7933 programs are interpreted and do not require linking.
7938 @section Checking Runtime Behavior
7940 Sometimes you need to find out how a system performs at runtime, such
7941 as whether a given function has a certain capability or bug. If you
7942 can, make such checks when your program runs instead of when it is
7943 configured. You can check for things like the machine's endianness when
7944 your program initializes itself.
7946 If you really need to test for a runtime behavior while configuring,
7947 you can write a test program to determine the result, and compile and
7948 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
7949 possible, because this prevents people from configuring your package for
7952 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
7953 @acindex{RUN_IFELSE}
7954 If @var{program} compiles and links successfully and returns an exit
7955 status of 0 when executed, run shell commands @var{action-if-true}.
7956 Otherwise, run shell commands @var{action-if-false}.
7958 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7959 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7960 compilation flags of the current language (@pxref{Language Choice}).
7962 If the compiler being used does not produce executables that run on the
7963 system where @command{configure} is being run, then the test program is
7964 not run. If the optional shell commands @var{action-if-cross-compiling}
7965 are given, they are run instead. Otherwise, @command{configure} prints
7966 an error message and exits.
7968 In the @var{action-if-false} section, the failing exit status is
7969 available in the shell variable @samp{$?}. This exit status might be
7970 that of a failed compilation, or it might be that of a failed program
7973 It is customary to report unexpected failures with
7974 @code{AC_MSG_FAILURE}.
7977 Try to provide a pessimistic default value to use when cross-compiling
7978 makes runtime tests impossible. You do this by passing the optional
7979 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
7980 warning message when creating @command{configure} each time it
7981 encounters a call to @code{AC_RUN_IFELSE} with no
7982 @var{action-if-cross-compiling} argument given. You may ignore the
7983 warning, though users cannot configure your package for
7984 cross-compiling. A few of the macros distributed with Autoconf produce
7985 this warning message.
7987 To configure for cross-compiling you can also choose a value for those
7988 parameters based on the canonical system name (@pxref{Manual
7989 Configuration}). Alternatively, set up a test results cache file with
7990 the correct values for the host system (@pxref{Caching Results}).
7992 @ovindex cross_compiling
7993 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
7994 in other macros, including a few of the ones that come with Autoconf,
7995 you can test whether the shell variable @code{cross_compiling} is set to
7996 @samp{yes}, and then use an alternate method to get the results instead
7997 of calling the macros.
7999 A C or C++ runtime test should be portable.
8000 @xref{Portable C and C++}.
8002 Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1}
8003 function: the given status code is used to determine the success of the test
8004 (status is @code{0}) or its failure (status is different than @code{0}), as
8005 explained above. It must be noted that data output through the standard output
8006 (e.g., using @code{io:format/2}) may be truncated when halting the VM.
8007 Therefore, if a test must output configuration information, it is recommended
8008 to create and to output data into the temporary file named @file{conftest.out},
8009 using the functions of module @code{file}. The @code{conftest.out} file is
8010 automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a
8011 simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is:
8014 AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org])
8018 [AC_LANG_PROGRAM([], [dnl
8019 file:write_file("conftest.out", code:lib_dir()),
8021 [echo "code:lib_dir() returned: `cat conftest.out`"],
8022 [AC_MSG_FAILURE([test Erlang program execution failed])])
8027 @section Systemology
8030 This section aims at presenting some systems and pointers to
8031 documentation. It may help you addressing particular problems reported
8034 @uref{http://www.opengroup.org/susv3, Posix-conforming systems} are
8035 derived from the @uref{http://www.bell-labs.com/history/unix/, Unix
8038 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
8039 contains a table correlating the features of various Posix-conforming
8040 systems. @uref{http://www.levenez.com/unix/, Unix History} is a
8041 simplified diagram of how many Unix systems were derived from each
8044 @uref{http://heirloom.sourceforge.net/, The Heirloom Project}
8045 provides some variants of traditional implementations of Unix utilities.
8050 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
8051 case-preserving, but case insensitive. This can cause nasty problems,
8052 since for instance the installation attempt for a package having an
8053 @file{INSTALL} file can result in @samp{make install} report that
8054 nothing was to be done!
8056 That's all dependent on whether the file system is a UFS (case
8057 sensitive) or HFS+ (case preserving). By default Apple wants you to
8058 install the OS on HFS+. Unfortunately, there are some pieces of
8059 software which really need to be built on UFS@. We may want to rebuild
8060 Darwin to have both UFS and HFS+ available (and put the /local/build
8063 @item @acronym{QNX} 4.25
8064 @cindex @acronym{QNX} 4.25
8065 @c FIXME: Please, if you feel like writing something more precise,
8066 @c it'd be great. In particular, I can't understand the difference with
8068 @acronym{QNX} is a realtime operating system running on Intel architecture
8069 meant to be scalable from the small embedded systems to the hundred
8070 processor super-computer. It claims to be Posix certified. More
8071 information is available on the
8072 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
8076 @uref{http://h30097.www3.hp.com/@/docs/,
8077 Documentation of several versions of Tru64} is available in different
8080 @item Unix version 7
8081 @cindex Unix version 7
8083 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
8084 time-sharing system'' but we use the more-common name ``Unix version 7''.
8085 Documentation is available in the
8086 @uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}.
8087 Previous versions of Unix are called ``Unix version 6'', etc., but
8088 they were not as widely used.
8092 @node Multiple Cases
8093 @section Multiple Cases
8095 Some operations are accomplished in several possible ways, depending on
8096 the OS variant. Checking for them essentially requires a ``case
8097 statement''. Autoconf does not directly provide one; however, it is
8098 easy to simulate by using a shell variable to keep track of whether a
8099 way to perform the operation has been found yet.
8101 Here is an example that uses the shell variable @code{fstype} to keep
8102 track of whether the remaining cases need to be checked.
8106 AC_MSG_CHECKING([how to get file system type])
8108 # The order of these tests is important.
8109 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
8110 #include <sys/fstyp.h>]])],
8111 [AC_DEFINE([FSTYPE_STATVFS], [1],
8112 [Define if statvfs exists.])
8114 if test $fstype = no; then
8115 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8116 #include <sys/fstyp.h>]])],
8117 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
8118 [Define if USG statfs.])
8121 if test $fstype = no; then
8122 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
8123 #include <sys/vmount.h>]])]),
8124 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
8125 [Define if AIX statfs.])
8128 # (more cases omitted here)
8129 AC_MSG_RESULT([$fstype])
8133 @c ====================================================== Results of Tests.
8136 @chapter Results of Tests
8138 Once @command{configure} has determined whether a feature exists, what can
8139 it do to record that information? There are four sorts of things it can
8140 do: define a C preprocessor symbol, set a variable in the output files,
8141 save the result in a cache file for future @command{configure} runs, and
8142 print a message letting the user know the result of the test.
8145 * Defining Symbols:: Defining C preprocessor symbols
8146 * Setting Output Variables:: Replacing variables in output files
8147 * Special Chars in Variables:: Characters to beware of in variables
8148 * Caching Results:: Speeding up subsequent @command{configure} runs
8149 * Printing Messages:: Notifying @command{configure} users
8152 @node Defining Symbols
8153 @section Defining C Preprocessor Symbols
8155 A common action to take in response to a feature test is to define a C
8156 preprocessor symbol indicating the results of the test. That is done by
8157 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
8159 By default, @code{AC_OUTPUT} places the symbols defined by these macros
8160 into the output variable @code{DEFS}, which contains an option
8161 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
8162 Autoconf version 1, there is no variable @code{DEFS} defined while
8163 @command{configure} is running. To check whether Autoconf macros have
8164 already defined a certain C preprocessor symbol, test the value of the
8165 appropriate cache variable, as in this example:
8168 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
8169 [Define if vprintf exists.])])
8170 if test "$ac_cv_func_vprintf" != yes; then
8171 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
8172 [Define if _doprnt exists.])])
8176 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
8177 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
8178 correct values into @code{#define} statements in a template file.
8179 @xref{Configuration Headers}, for more information about this kind of
8182 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
8183 @defmacx AC_DEFINE (@var{variable})
8185 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
8186 @var{value} should not contain literal newlines, and if you are not
8187 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
8188 characters, as @command{make} tends to eat them. To use a shell variable,
8189 use @code{AC_DEFINE_UNQUOTED} instead.
8190 @var{description} is only useful if you are using
8191 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
8192 the generated @file{config.h.in} as the comment before the macro define.
8193 The following example defines the C preprocessor variable
8194 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
8197 AC_DEFINE([EQUATION], ["$a > $b"],
8201 If neither @var{value} nor @var{description} are given, then
8202 @var{value} defaults to 1 instead of to the empty string. This is for
8203 backwards compatibility with older versions of Autoconf, but this usage
8204 is obsolescent and may be withdrawn in future versions of Autoconf.
8206 If the @var{variable} is a literal string, it is passed to
8207 @code{m4_pattern_allow} (@pxref{Forbidden Patterns}).
8210 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
8211 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
8212 @acindex{DEFINE_UNQUOTED}
8213 Like @code{AC_DEFINE}, but three shell expansions are
8214 performed---once---on @var{variable} and @var{value}: variable expansion
8215 (@samp{$}), command substitution (@samp{`}), and backslash escaping
8216 (@samp{\}). Single and double quote characters in the value have no
8217 special meaning. Use this macro instead of @code{AC_DEFINE} when
8218 @var{variable} or @var{value} is a shell variable. Examples:
8221 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
8222 [Configuration machine file.])
8223 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
8224 [getgroups return type.])
8225 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
8226 [Translated header name.])
8230 Due to a syntactical bizarreness of the Bourne shell, do not use
8231 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
8232 calls from other macro calls or shell code; that can cause syntax errors
8233 in the resulting @command{configure} script. Use either blanks or
8234 newlines. That is, do this:
8237 AC_CHECK_HEADER([elf.h],
8238 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
8245 AC_CHECK_HEADER([elf.h],
8246 [AC_DEFINE([SVR4], [1], [System V Release 4])
8247 LIBS="-lelf $LIBS"])
8254 AC_CHECK_HEADER([elf.h],
8255 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
8258 @node Setting Output Variables
8259 @section Setting Output Variables
8260 @cindex Output variables
8262 Another way to record the results of tests is to set @dfn{output
8263 variables}, which are shell variables whose values are substituted into
8264 files that @command{configure} outputs. The two macros below create new
8265 output variables. @xref{Preset Output Variables}, for a list of output
8266 variables that are always available.
8268 @defmac AC_SUBST (@var{variable}, @ovar{value})
8270 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
8271 substitute the variable @var{variable} into output files (typically one
8272 or more makefiles). This means that @code{AC_OUTPUT}
8273 replaces instances of @samp{@@@var{variable}@@} in input files with the
8274 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
8275 is called. The value can contain newlines.
8276 The substituted value is not rescanned for more output variables;
8277 occurrences of @samp{@@@var{variable}@@} in the value are inserted
8278 literally into the output file. (The algorithm uses the special marker
8279 @code{|#_!!_#|} internally, so the substituted value cannot contain
8282 If @var{value} is given, in addition assign it to @var{variable}.
8284 The string @var{variable} is passed to @code{m4_pattern_allow}
8285 (@pxref{Forbidden Patterns}).
8288 @defmac AC_SUBST_FILE (@var{variable})
8289 @acindex{SUBST_FILE}
8290 Another way to create an output variable from a shell variable. Make
8291 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
8292 named by shell variable @var{variable} into output files. This means
8293 that @code{AC_OUTPUT} replaces instances of
8294 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
8295 with the contents of the file that the shell variable @var{variable}
8296 names when @code{AC_OUTPUT} is called. Set the variable to
8297 @file{/dev/null} for cases that do not have a file to insert.
8298 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
8299 line by itself, optionally surrounded by spaces and tabs. The
8300 substitution replaces the whole line, including the spaces, tabs, and
8301 the terminating newline.
8303 This macro is useful for inserting makefile fragments containing
8304 special dependencies or other @code{make} directives for particular host
8305 or target types into makefiles. For example, @file{configure.ac}
8309 AC_SUBST_FILE([host_frag])
8310 host_frag=$srcdir/conf/sun4.mh
8314 and then a @file{Makefile.in} could contain:
8320 The string @var{variable} is passed to @code{m4_pattern_allow}
8321 (@pxref{Forbidden Patterns}).
8324 @cindex Previous Variable
8325 @cindex Variable, Precious
8326 Running @command{configure} in varying environments can be extremely
8327 dangerous. If for instance the user runs @samp{CC=bizarre-cc
8328 ./configure}, then the cache, @file{config.h}, and many other output
8329 files depend upon @command{bizarre-cc} being the C compiler. If
8330 for some reason the user runs @command{./configure} again, or if it is
8331 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
8332 and @pxref{config.status Invocation}), then the configuration can be
8333 inconsistent, composed of results depending upon two different
8336 Environment variables that affect this situation, such as @samp{CC}
8337 above, are called @dfn{precious variables}, and can be declared as such
8338 by @code{AC_ARG_VAR}.
8340 @defmac AC_ARG_VAR (@var{variable}, @var{description})
8342 Declare @var{variable} is a precious variable, and include its
8343 @var{description} in the variable section of @samp{./configure --help}.
8345 Being precious means that
8348 @var{variable} is substituted via @code{AC_SUBST}.
8351 The value of @var{variable} when @command{configure} was launched is
8352 saved in the cache, including if it was not specified on the command
8353 line but via the environment. Indeed, while @command{configure} can
8354 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
8355 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
8356 which, unfortunately, is what most users do.
8358 We emphasize that it is the @emph{initial} value of @var{variable} which
8359 is saved, not that found during the execution of @command{configure}.
8360 Indeed, specifying @samp{./configure FOO=foo} and letting
8361 @samp{./configure} guess that @code{FOO} is @code{foo} can be two
8365 @var{variable} is checked for consistency between two
8366 @command{configure} runs. For instance:
8369 $ @kbd{./configure --silent --config-cache}
8370 $ @kbd{CC=cc ./configure --silent --config-cache}
8371 configure: error: `CC' was not set in the previous run
8372 configure: error: changes in the environment can compromise \
8374 configure: error: run `make distclean' and/or \
8375 `rm config.cache' and start over
8379 and similarly if the variable is unset, or if its content is changed.
8383 @var{variable} is kept during automatic reconfiguration
8384 (@pxref{config.status Invocation}) as if it had been passed as a command
8385 line argument, including when no cache is used:
8388 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
8389 $ @kbd{./config.status --recheck}
8390 running /bin/sh ./configure undeclared_var=raboof --silent \
8391 CC=/usr/bin/cc --no-create --no-recursion
8396 @node Special Chars in Variables
8397 @section Special Characters in Output Variables
8398 @cindex Output variables, special characters in
8400 Many output variables are intended to be evaluated both by
8401 @command{make} and by the shell. Some characters are expanded
8402 differently in these two contexts, so to avoid confusion these
8403 variables' values should not contain any of the following characters:
8406 " # $ & ' ( ) * ; < > ? [ \ ^ ` |
8409 Also, these variables' values should neither contain newlines, nor start
8410 with @samp{~}, nor contain white space or @samp{:} immediately followed
8411 by @samp{~}. The values can contain nonempty sequences of white space
8412 characters like tabs and spaces, but each such sequence might
8413 arbitrarily be replaced by a single space during substitution.
8415 These restrictions apply both to the values that @command{configure}
8416 computes, and to the values set directly by the user. For example, the
8417 following invocations of @command{configure} are problematic, since they
8418 attempt to use special characters within @code{CPPFLAGS} and white space
8419 within @code{$(srcdir)}:
8422 CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure'
8424 '../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"'
8427 @node Caching Results
8428 @section Caching Results
8431 To avoid checking for the same features repeatedly in various
8432 @command{configure} scripts (or in repeated runs of one script),
8433 @command{configure} can optionally save the results of many checks in a
8434 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
8435 runs with caching enabled and finds a cache file, it reads the results
8436 of previous runs from the cache and avoids rerunning those checks. As a
8437 result, @command{configure} can then run much faster than if it had to
8438 perform all of the checks every time.
8440 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
8442 Ensure that the results of the check identified by @var{cache-id} are
8443 available. If the results of the check were in the cache file that was
8444 read, and @command{configure} was not given the @option{--quiet} or
8445 @option{--silent} option, print a message saying that the result was
8446 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
8447 the shell commands are run to determine the value, the value is
8448 saved in the cache file just before @command{configure} creates its output
8449 files. @xref{Cache Variable Names}, for how to choose the name of the
8450 @var{cache-id} variable.
8452 The @var{commands-to-set-it} @emph{must have no side effects} except for
8453 setting the variable @var{cache-id}, see below.
8456 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
8457 @acindex{CACHE_CHECK}
8458 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
8459 messages. This macro provides a convenient shorthand for the most
8460 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
8461 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
8462 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
8464 The @var{commands-to-set-it} @emph{must have no side effects} except for
8465 setting the variable @var{cache-id}, see below.
8468 It is common to find buggy macros using @code{AC_CACHE_VAL} or
8469 @code{AC_CACHE_CHECK}, because people are tempted to call
8470 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
8471 @emph{follows} the call to @code{AC_CACHE_VAL} should call
8472 @code{AC_DEFINE}, by examining the value of the cache variable. For
8473 instance, the following macro is broken:
8477 AC_DEFUN([AC_SHELL_TRUE],
8478 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8479 [ac_cv_shell_true_works=no
8480 (true) 2>/dev/null && ac_cv_shell_true_works=yes
8481 if test "$ac_cv_shell_true_works" = yes; then
8482 AC_DEFINE([TRUE_WORKS], [1],
8483 [Define if `true(1)' works properly.])
8490 This fails if the cache is enabled: the second time this macro is run,
8491 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
8496 AC_DEFUN([AC_SHELL_TRUE],
8497 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
8498 [ac_cv_shell_true_works=no
8499 (true) 2>/dev/null && ac_cv_shell_true_works=yes])
8500 if test "$ac_cv_shell_true_works" = yes; then
8501 AC_DEFINE([TRUE_WORKS], [1],
8502 [Define if `true(1)' works properly.])
8508 Also, @var{commands-to-set-it} should not print any messages, for
8509 example with @code{AC_MSG_CHECKING}; do that before calling
8510 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
8511 the results of the check are retrieved from the cache or determined by
8512 running the shell commands.
8515 * Cache Variable Names:: Shell variables used in caches
8516 * Cache Files:: Files @command{configure} uses for caching
8517 * Cache Checkpointing:: Loading and saving the cache file
8520 @node Cache Variable Names
8521 @subsection Cache Variable Names
8522 @cindex Cache variable
8524 The names of cache variables should have the following format:
8527 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
8531 for example, @samp{ac_cv_header_stat_broken} or
8532 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
8535 @item @var{package-prefix}
8536 An abbreviation for your package or organization; the same prefix you
8537 begin local Autoconf macros with, except lowercase by convention.
8538 For cache values used by the distributed Autoconf macros, this value is
8542 Indicates that this shell variable is a cache value. This string
8543 @emph{must} be present in the variable name, including the leading
8546 @item @var{value-type}
8547 A convention for classifying cache values, to produce a rational naming
8548 system. The values used in Autoconf are listed in @ref{Macro Names}.
8550 @item @var{specific-value}
8551 Which member of the class of cache values this test applies to.
8552 For example, which function (@samp{alloca}), program (@samp{gcc}), or
8553 output variable (@samp{INSTALL}).
8555 @item @var{additional-options}
8556 Any particular behavior of the specific member that this test applies to.
8557 For example, @samp{broken} or @samp{set}. This part of the name may
8558 be omitted if it does not apply.
8561 The values assigned to cache variables may not contain newlines.
8562 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
8563 names of files or functions; so this is not an important restriction.
8566 @subsection Cache Files
8568 A cache file is a shell script that caches the results of configure
8569 tests run on one system so they can be shared between configure scripts
8570 and configure runs. It is not useful on other systems. If its contents
8571 are invalid for some reason, the user may delete or edit it.
8573 By default, @command{configure} uses no cache file,
8574 to avoid problems caused by accidental
8575 use of stale cache files.
8577 To enable caching, @command{configure} accepts @option{--config-cache} (or
8578 @option{-C}) to cache results in the file @file{config.cache}.
8579 Alternatively, @option{--cache-file=@var{file}} specifies that
8580 @var{file} be the cache file. The cache file is created if it does not
8581 exist already. When @command{configure} calls @command{configure} scripts in
8582 subdirectories, it uses the @option{--cache-file} argument so that they
8583 share the same cache. @xref{Subdirectories}, for information on
8584 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
8586 @file{config.status} only pays attention to the cache file if it is
8587 given the @option{--recheck} option, which makes it rerun
8588 @command{configure}.
8590 It is wrong to try to distribute cache files for particular system types.
8591 There is too much room for error in doing that, and too much
8592 administrative overhead in maintaining them. For any features that
8593 can't be guessed automatically, use the standard method of the canonical
8594 system type and linking files (@pxref{Manual Configuration}).
8596 The site initialization script can specify a site-wide cache file to
8597 use, instead of the usual per-program cache. In this case, the cache
8598 file gradually accumulates information whenever someone runs a new
8599 @command{configure} script. (Running @command{configure} merges the new cache
8600 results with the existing cache file.) This may cause problems,
8601 however, if the system configuration (e.g., the installed libraries or
8602 compilers) changes and the stale cache file is not deleted.
8604 @node Cache Checkpointing
8605 @subsection Cache Checkpointing
8607 If your configure script, or a macro called from @file{configure.ac}, happens
8608 to abort the configure process, it may be useful to checkpoint the cache
8609 a few times at key points using @code{AC_CACHE_SAVE}. Doing so
8610 reduces the amount of time it takes to rerun the configure script with
8611 (hopefully) the error that caused the previous abort corrected.
8613 @c FIXME: Do we really want to document this guy?
8614 @defmac AC_CACHE_LOAD
8615 @acindex{CACHE_LOAD}
8616 Loads values from existing cache file, or creates a new cache file if a
8617 cache file is not found. Called automatically from @code{AC_INIT}.
8620 @defmac AC_CACHE_SAVE
8621 @acindex{CACHE_SAVE}
8622 Flushes all cached values to the cache file. Called automatically from
8623 @code{AC_OUTPUT}, but it can be quite useful to call
8624 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
8630 @r{ @dots{} AC_INIT, etc. @dots{}}
8632 # Checks for programs.
8635 @r{ @dots{} more program checks @dots{}}
8640 # Checks for libraries.
8641 AC_CHECK_LIB([nsl], [gethostbyname])
8642 AC_CHECK_LIB([socket], [connect])
8643 @r{ @dots{} more lib checks @dots{}}
8648 # Might abort@dots{}
8649 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
8650 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
8652 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
8655 @node Printing Messages
8656 @section Printing Messages
8657 @cindex Messages, from @command{configure}
8659 @command{configure} scripts need to give users running them several kinds
8660 of information. The following macros print messages in ways appropriate
8661 for each kind. The arguments to all of them get enclosed in shell
8662 double quotes, so the shell performs variable and back-quote
8663 substitution on them.
8665 These macros are all wrappers around the @command{echo} shell command.
8666 They direct output to the appropriate file descriptor (@pxref{File
8667 Descriptor Macros}).
8668 @command{configure} scripts should rarely need to run @command{echo} directly
8669 to print messages for the user. Using these macros makes it easy to
8670 change how and when each kind of message is printed; such changes need
8671 only be made to the macro definitions and all the callers change
8674 To diagnose static issues, i.e., when @command{autoconf} is run, see
8675 @ref{Reporting Messages}.
8677 @defmac AC_MSG_CHECKING (@var{feature-description})
8678 @acindex{MSG_CHECKING}
8679 Notify the user that @command{configure} is checking for a particular
8680 feature. This macro prints a message that starts with @samp{checking }
8681 and ends with @samp{...} and no newline. It must be followed by a call
8682 to @code{AC_MSG_RESULT} to print the result of the check and the
8683 newline. The @var{feature-description} should be something like
8684 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
8687 This macro prints nothing if @command{configure} is run with the
8688 @option{--quiet} or @option{--silent} option.
8691 @defmac AC_MSG_RESULT (@var{result-description})
8692 @acindex{MSG_RESULT}
8693 Notify the user of the results of a check. @var{result-description} is
8694 almost always the value of the cache variable for the check, typically
8695 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
8696 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
8697 the completion of the message printed by the call to
8698 @code{AC_MSG_CHECKING}.
8700 This macro prints nothing if @command{configure} is run with the
8701 @option{--quiet} or @option{--silent} option.
8704 @defmac AC_MSG_NOTICE (@var{message})
8705 @acindex{MSG_NOTICE}
8706 Deliver the @var{message} to the user. It is useful mainly to print a
8707 general description of the overall purpose of a group of feature checks,
8711 AC_MSG_NOTICE([checking if stack overflow is detectable])
8714 This macro prints nothing if @command{configure} is run with the
8715 @option{--quiet} or @option{--silent} option.
8718 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
8720 Notify the user of an error that prevents @command{configure} from
8721 completing. This macro prints an error message to the standard error
8722 output and exits @command{configure} with @var{exit-status} (1 by default).
8723 @var{error-description} should be something like @samp{invalid value
8726 The @var{error-description} should start with a lower-case letter, and
8727 ``cannot'' is preferred to ``can't''.
8730 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
8731 @acindex{MSG_FAILURE}
8732 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
8733 prevents @command{configure} from completing @emph{and} that additional
8734 details are provided in @file{config.log}. This is typically used when
8735 abnormal results are found during a compilation.
8738 @defmac AC_MSG_WARN (@var{problem-description})
8740 Notify the @command{configure} user of a possible problem. This macro
8741 prints the message to the standard error output; @command{configure}
8742 continues running afterward, so macros that call @code{AC_MSG_WARN} should
8743 provide a default (back-up) behavior for the situations they warn about.
8744 @var{problem-description} should be something like @samp{ln -s seems to
8750 @c ====================================================== Programming in M4.
8752 @node Programming in M4
8753 @chapter Programming in M4
8756 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
8757 convenient macros for pure M4 programming, and @dfn{M4sh}, which
8758 provides macros dedicated to shell script generation.
8760 As of this version of Autoconf, these two layers are still experimental,
8761 and their interface might change in the future. As a matter of fact,
8762 @emph{anything that is not documented must not be used}.
8765 * M4 Quotation:: Protecting macros from unwanted expansion
8766 * Using autom4te:: The Autoconf executables backbone
8767 * Programming in M4sugar:: Convenient pure M4 macros
8768 * Programming in M4sh:: Common shell Constructs
8769 * File Descriptor Macros:: File descriptor macros for input and output
8773 @section M4 Quotation
8774 @cindex M4 quotation
8777 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
8778 @c prevented `expansion' of $1. Unless it refers to the expansion
8779 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
8781 The most common problem with existing macros is an improper quotation.
8782 This section, which users of Autoconf can skip, but which macro writers
8783 @emph{must} read, first justifies the quotation scheme that was chosen
8784 for Autoconf and then ends with a rule of thumb. Understanding the
8785 former helps one to follow the latter.
8788 * Active Characters:: Characters that change the behavior of M4
8789 * One Macro Call:: Quotation and one macro call
8790 * Quotation and Nested Macros:: Macros calling macros
8791 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
8792 * Quadrigraphs:: Another way to escape special characters
8793 * Quotation Rule Of Thumb:: One parenthesis, one quote
8796 @node Active Characters
8797 @subsection Active Characters
8799 To fully understand where proper quotation is important, you first need
8800 to know what the special characters are in Autoconf: @samp{#} introduces
8801 a comment inside which no macro expansion is performed, @samp{,}
8802 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
8803 and finally @samp{(} and @samp{)} (which M4 tries to match by
8806 In order to understand the delicate case of macro calls, we first have
8807 to present some obvious failures. Below they are ``obvious-ified'',
8808 but when you find them in real life, they are usually in disguise.
8810 Comments, introduced by a hash and running up to the newline, are opaque
8811 tokens to the top level: active characters are turned off, and there is
8815 # define([def], ine)
8816 @result{}# define([def], ine)
8819 Each time there can be a macro expansion, there is a quotation
8820 expansion, i.e., one level of quotes is stripped:
8826 @result{}int tab[10];
8829 Without this in mind, the reader might try hopelessly to use her macro
8833 define([array], [int tab[10];])
8841 How can you correctly output the intended results@footnote{Using
8845 @node One Macro Call
8846 @subsection One Macro Call
8848 Let's proceed on the interaction between active characters and macros
8849 with this small macro, which just returns its first argument:
8856 The two pairs of quotes above are not part of the arguments of
8857 @code{define}; rather, they are understood by the top level when it
8858 tries to find the arguments of @code{define}. Therefore, assuming
8859 @code{car} is not already defined, it is equivalent to write:
8866 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
8867 quotes, it is bad practice for Autoconf macros which must both be more
8868 robust and also advocate perfect style.
8870 At the top level, there are only two possibilities: either you
8876 [car(foo, bar, baz)]
8877 @result{}car(foo, bar, baz)
8880 Let's pay attention to the special characters:
8884 @error{}EOF in argument list
8887 The closing parenthesis is hidden in the comment; with a hypothetical
8888 quoting, the top level understood it this way:
8895 Proper quotation, of course, fixes the problem:
8902 Here are more examples:
8925 With this in mind, we can explore the cases where macros invoke
8929 @node Quotation and Nested Macros
8930 @subsection Quotation and Nested Macros
8932 The examples below use the following macros:
8936 define([active], [ACT, IVE])
8937 define([array], [int tab[10]])
8940 Each additional embedded macro call introduces other possible
8941 interesting quotations:
8952 In the first case, the top level looks for the arguments of @code{car},
8953 and finds @samp{active}. Because M4 evaluates its arguments
8954 before applying the macro, @samp{active} is expanded, which results in:
8962 In the second case, the top level gives @samp{active} as first and only
8963 argument of @code{car}, which results in:
8971 i.e., the argument is evaluated @emph{after} the macro that invokes it.
8972 In the third case, @code{car} receives @samp{[active]}, which results in:
8980 exactly as we already saw above.
8982 The example above, applied to a more realistic example, gives:
8989 car([[int tab[10];]])
8990 @result{}int tab[10];
8994 Huh? The first case is easily understood, but why is the second wrong,
8995 and the third right? To understand that, you must know that after
8996 M4 expands a macro, the resulting text is immediately subjected
8997 to macro expansion and quote removal. This means that the quote removal
8998 occurs twice---first before the argument is passed to the @code{car}
8999 macro, and second after the @code{car} macro expands to the first
9002 As the author of the Autoconf macro @code{car}, you then consider it to
9003 be incorrect that your users have to double-quote the arguments of
9004 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
9008 define([qar], [[$1]])
9012 and check that @code{qar} is properly fixed:
9016 @result{}int tab[10];
9020 Ahhh! That's much better.
9022 But note what you've done: now that the arguments are literal strings,
9023 if the user wants to use the results of expansions as arguments, she has
9024 to use an @emph{unquoted} macro call:
9032 where she wanted to reproduce what she used to do with @code{car}:
9040 Worse yet: she wants to use a macro that produces a set of @code{cpp}
9044 define([my_includes], [#include <stdio.h>])
9046 @result{}#include <stdio.h>
9048 @error{}EOF in argument list
9051 This macro, @code{qar}, because it double quotes its arguments, forces
9052 its users to leave their macro calls unquoted, which is dangerous.
9053 Commas and other active symbols are interpreted by M4 before
9054 they are given to the macro, often not in the way the users expect.
9055 Also, because @code{qar} behaves differently from the other macros,
9056 it's an exception that should be avoided in Autoconf.
9058 @node Changequote is Evil
9059 @subsection @code{changequote} is Evil
9060 @cindex @code{changequote}
9062 The temptation is often high to bypass proper quotation, in particular
9063 when it's late at night. Then, many experienced Autoconf hackers
9064 finally surrender to the dark side of the force and use the ultimate
9065 weapon: @code{changequote}.
9067 The M4 builtin @code{changequote} belongs to a set of primitives that
9068 allow one to adjust the syntax of the language to adjust it to one's
9069 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
9070 quotes, but in the context of shell programming (and actually of most
9071 programming languages), that's about the worst choice one can make:
9072 because of strings and back-quoted expressions in shell code (such as
9073 @samp{'this'} and @samp{`that`}), because of literal characters in usual
9074 programming languages (as in @samp{'0'}), there are many unbalanced
9075 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
9076 not impossible. In order to make M4 useful in such a context, its
9077 designers have equipped it with @code{changequote}, which makes it
9078 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
9079 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
9080 because they are unlikely characters, but @emph{because they are
9081 characters unlikely to be unbalanced}.
9083 There are other magic primitives, such as @code{changecom} to specify
9084 what syntactic forms are comments (it is common to see
9085 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
9086 @code{changeword} and @code{changesyntax} to change other syntactic
9087 details (such as the character to denote the @var{n}th argument, @samp{$} by
9088 default, the parenthesis around arguments, etc.).
9090 These primitives are really meant to make M4 more useful for specific
9091 domains: they should be considered like command line options:
9092 @option{--quotes}, @option{--comments}, @option{--words}, and
9093 @option{--syntax}. Nevertheless, they are implemented as M4 builtins, as
9094 it makes M4 libraries self contained (no need for additional options).
9096 There lies the problem@enddots{}
9100 The problem is that it is then tempting to use them in the middle of an
9101 M4 script, as opposed to its initialization. This, if not carefully
9102 thought out, can lead to disastrous effects: @emph{you are changing the
9103 language in the middle of the execution}. Changing and restoring the
9104 syntax is often not enough: if you happened to invoke macros in between,
9105 these macros are lost, as the current syntax is probably not
9106 the one they were implemented with.
9108 @c FIXME: I've been looking for a short, real case example, but I
9113 @subsection Quadrigraphs
9114 @cindex quadrigraphs
9115 @cindex @samp{@@S|@@}
9116 @cindex @samp{@@&t@@}
9117 @c Info cannot handle `:' in index entries.
9118 @c @cindex @samp{@@<:@@}
9119 @c @cindex @samp{@@:>@@}
9120 @c @cindex @samp{@@%:@@}
9122 When writing an Autoconf macro you may occasionally need to generate
9123 special characters that are difficult to express with the standard
9124 Autoconf quoting rules. For example, you may need to output the regular
9125 expression @samp{[^[]}, which matches any character other than @samp{[}.
9126 This expression contains unbalanced brackets so it cannot be put easily
9129 You can work around this problem by using one of the following
9145 Quadrigraphs are replaced at a late stage of the translation process,
9146 after @command{m4} is run, so they do not get in the way of M4 quoting.
9147 For example, the string @samp{^@@<:@@}, independently of its quotation,
9148 appears as @samp{^[} in the output.
9150 The empty quadrigraph can be used:
9153 @item to mark trailing spaces explicitly
9155 Trailing spaces are smashed by @command{autom4te}. This is a feature.
9157 @item to produce other quadrigraphs
9159 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
9161 @item to escape @emph{occurrences} of forbidden patterns
9163 For instance you might want to mention @code{AC_FOO} in a comment, while
9164 still being sure that @command{autom4te} still catches unexpanded
9165 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
9168 The name @samp{@@&t@@} was suggested by Paul Eggert:
9171 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
9172 own invention, but the @samp{t} came from the source code of the
9173 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
9174 and which used @samp{mt} to denote the empty string. In C, it would
9175 have looked like something like:
9178 char const mt[] = "";
9182 but of course the source code was written in Algol 68.
9184 I don't know where he got @samp{mt} from: it could have been his own
9185 invention, and I suppose it could have been a common pun around the
9186 Cambridge University computer lab at the time.
9189 @node Quotation Rule Of Thumb
9190 @subsection Quotation Rule Of Thumb
9192 To conclude, the quotation rule of thumb is:
9194 @center @emph{One pair of quotes per pair of parentheses.}
9196 Never over-quote, never under-quote, in particular in the definition of
9197 macros. In the few places where the macros need to use brackets
9198 (usually in C program text or regular expressions), properly quote
9199 @emph{the arguments}!
9201 It is common to read Autoconf programs with snippets like:
9205 changequote(<<, >>)dnl
9207 #ifndef tzname /* For SGI. */
9208 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9210 changequote([, ])dnl
9211 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
9215 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
9216 double quoting, so you just need:
9221 #ifndef tzname /* For SGI. */
9222 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9225 [ac_cv_var_tzname=yes],
9226 [ac_cv_var_tzname=no])
9230 The M4-fluent reader might note that these two examples are rigorously
9231 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
9232 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
9233 quotes are not part of the arguments!
9235 Simplified, the example above is just doing this:
9238 changequote(<<, >>)dnl
9240 changequote([, ])dnl
9250 With macros that do not double quote their arguments (which is the
9251 rule), double-quote the (risky) literals:
9254 AC_LINK_IFELSE([AC_LANG_PROGRAM(
9256 #ifndef tzname /* For SGI. */
9257 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
9259 [atoi (*tzname);])],
9260 [ac_cv_var_tzname=yes],
9261 [ac_cv_var_tzname=no])
9264 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
9265 should be using @code{AC_LINK_IFELSE} instead.
9267 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
9268 where quoting does not suffice.
9270 When you create a @command{configure} script using newly written macros,
9271 examine it carefully to check whether you need to add more quotes in
9272 your macros. If one or more words have disappeared in the M4
9273 output, you need more quotes. When in doubt, quote.
9275 However, it's also possible to put on too many layers of quotes. If
9276 this happens, the resulting @command{configure} script may contain
9277 unexpanded macros. The @command{autoconf} program checks for this problem
9278 by looking for the string @samp{AC_} in @file{configure}. However, this
9279 heuristic does not work in general: for example, it does not catch
9280 overquoting in @code{AC_DEFINE} descriptions.
9283 @c ---------------------------------------- Using autom4te
9285 @node Using autom4te
9286 @section Using @command{autom4te}
9288 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
9289 to Autoconf per se, heavily rely on M4. All these different uses
9290 revealed common needs factored into a layer over M4:
9291 @command{autom4te}@footnote{
9293 Yet another great name from Lars J. Aas.
9297 @command{autom4te} is a preprocessor that is like @command{m4}.
9298 It supports M4 extensions designed for use in tools like Autoconf.
9301 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
9302 * Customizing autom4te:: Customizing the Autoconf package
9305 @node autom4te Invocation
9306 @subsection Invoking @command{autom4te}
9308 The command line arguments are modeled after M4's:
9311 autom4te @var{options} @var{files}
9316 where the @var{files} are directly passed to @command{m4}. By default,
9317 @acronym{GNU} M4 is found during configuration, but the environment
9319 @env{M4} can be set to tell @command{autom4te} where to look. In addition
9320 to the regular expansion, it handles the replacement of the quadrigraphs
9321 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
9322 output. It supports an extended syntax for the @var{files}:
9325 @item @var{file}.m4f
9326 This file is an M4 frozen file. Note that @emph{all the previous files
9327 are ignored}. See the option @option{--melt} for the rationale.
9330 If found in the library path, the @var{file} is included for expansion,
9331 otherwise it is ignored instead of triggering a failure.
9336 Of course, it supports the Autoconf common subset of options:
9341 Print a summary of the command line options and exit.
9345 Print the version number of Autoconf and exit.
9349 Report processing steps.
9353 Don't remove the temporary files and be even more verbose.
9355 @item --include=@var{dir}
9357 Also look for input files in @var{dir}. Multiple invocations
9360 @item --output=@var{file}
9361 @itemx -o @var{file}
9362 Save output (script or trace) to @var{file}. The file @option{-} stands
9363 for the standard output.
9368 As an extension of @command{m4}, it includes the following options:
9371 @item --warnings=@var{category}
9372 @itemx -W @var{category}
9374 @c FIXME: Point to the M4sugar macros, not Autoconf's.
9375 Report the warnings related to @var{category} (which can actually be a
9376 comma separated list). @xref{Reporting Messages}, macro
9377 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
9382 report all the warnings
9388 treats warnings as errors
9390 @item no-@var{category}
9391 disable warnings falling into @var{category}
9394 Warnings about @samp{syntax} are enabled by default, and the environment
9395 variable @env{WARNINGS}, a comma separated list of categories, is
9396 honored. @samp{autom4te -W @var{category}} actually
9397 behaves as if you had run:
9400 autom4te --warnings=syntax,$WARNINGS,@var{category}
9404 For example, if you want to disable defaults and @env{WARNINGS}
9405 of @command{autom4te}, but enable the warnings about obsolete
9406 constructs, you would use @option{-W none,obsolete}.
9409 @cindex Macro invocation stack
9410 @command{autom4te} displays a back trace for errors, but not for
9411 warnings; if you want them, just pass @option{-W error}.
9415 Do not use frozen files. Any argument @code{@var{file}.m4f} is
9416 replaced by @code{@var{file}.m4}. This helps tracing the macros which
9417 are executed only when the files are frozen, typically
9418 @code{m4_define}. For instance, running:
9421 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
9425 is roughly equivalent to running:
9428 m4 1.m4 2.m4 3.m4 4.m4 input.m4
9435 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
9442 m4 --reload-state=4.m4f input.m4
9447 Produce a frozen state file. @command{autom4te} freezing is stricter
9448 than M4's: it must produce no warnings, and no output other than empty
9449 lines (a line with white space is @emph{not} empty) and comments
9450 (starting with @samp{#}). Unlike @command{m4}'s similarly-named option,
9451 this option takes no argument:
9454 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
9461 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
9464 @item --mode=@var{octal-mode}
9465 @itemx -m @var{octal-mode}
9466 Set the mode of the non-traces output to @var{octal-mode}; by default
9472 @cindex @file{autom4te.cache}
9473 As another additional feature over @command{m4}, @command{autom4te}
9474 caches its results. @acronym{GNU} M4 is able to produce a regular
9475 output and traces at the same time. Traces are heavily used in the
9476 @acronym{GNU} Build System: @command{autoheader} uses them to build
9477 @file{config.h.in}, @command{autoreconf} to determine what
9478 @acronym{GNU} Build System components are used, @command{automake} to
9479 ``parse'' @file{configure.ac} etc. To avoid recomputation,
9480 traces are cached while performing regular expansion,
9481 and conversely. This cache is (actually, the caches are) stored in
9482 the directory @file{autom4te.cache}. @emph{It can safely be removed}
9483 at any moment (especially if for some reason @command{autom4te}
9484 considers it is trashed).
9487 @item --cache=@var{directory}
9488 @itemx -C @var{directory}
9489 Specify the name of the directory where the result should be cached.
9490 Passing an empty value disables caching. Be sure to pass a relative
9491 file name, as for the time being, global caches are not supported.
9494 Don't cache the results.
9498 If a cache is used, consider it obsolete (but update it anyway).
9503 Because traces are so important to the @acronym{GNU} Build System,
9504 @command{autom4te} provides high level tracing features as compared to
9505 M4, and helps exploiting the cache:
9508 @item --trace=@var{macro}[:@var{format}]
9509 @itemx -t @var{macro}[:@var{format}]
9510 Trace the invocations of @var{macro} according to the @var{format}.
9511 Multiple @option{--trace} arguments can be used to list several macros.
9512 Multiple @option{--trace} arguments for a single macro are not
9513 cumulative; instead, you should just make @var{format} as long as
9516 The @var{format} is a regular string, with newlines if desired, and
9517 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
9518 use the following special escapes:
9522 The character @samp{$}.
9525 The file name from which @var{macro} is called.
9528 The line number from which @var{macro} is called.
9531 The depth of the @var{macro} call. This is an M4 technical detail that
9532 you probably don't want to know about.
9535 The name of the @var{macro}.
9538 The @var{num}th argument of the call to @var{macro}.
9542 @itemx $@{@var{separator}@}@@
9543 All the arguments passed to @var{macro}, separated by the character
9544 @var{sep} or the string @var{separator} (@samp{,} by default). Each
9545 argument is quoted, i.e., enclosed in a pair of square brackets.
9549 @itemx $@{@var{separator}@}*
9550 As above, but the arguments are not quoted.
9554 @itemx $@{@var{separator}@}%
9555 As above, but the arguments are not quoted, all new line characters in
9556 the arguments are smashed, and the default separator is @samp{:}.
9558 The escape @samp{$%} produces single-line trace outputs (unless you put
9559 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
9563 @xref{autoconf Invocation}, for examples of trace uses.
9565 @item --preselect=@var{macro}
9566 @itemx -p @var{macro}
9567 Cache the traces of @var{macro}, but do not enable traces. This is
9568 especially important to save CPU cycles in the future. For instance,
9569 when invoked, @command{autoconf} preselects all the macros that
9570 @command{autoheader}, @command{automake}, @command{autoreconf}, etc.,
9571 trace, so that running @command{m4} is not needed to trace them: the
9572 cache suffices. This results in a huge speed-up.
9577 @cindex Autom4te Library
9578 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
9579 libraries}. They consists in a powerful yet extremely simple feature:
9580 sets of combined command line arguments:
9583 @item --language=@var{language}
9584 @itemx -l @var{language}
9585 Use the @var{language} Autom4te library. Current languages include:
9589 create M4sugar output.
9592 create M4sh executable shell scripts.
9595 create Autotest executable test suites.
9597 @item Autoconf-without-aclocal-m4
9598 create Autoconf executable configure scripts without
9599 reading @file{aclocal.m4}.
9602 create Autoconf executable configure scripts. This language inherits
9603 all the characteristics of @code{Autoconf-without-aclocal-m4} and
9604 additionally reads @file{aclocal.m4}.
9607 @item --prepend-include=@var{dir}
9609 Prepend directory @var{dir} to the search path. This is used to include
9610 the language-specific files before any third-party macros.
9614 @cindex @file{autom4te.cfg}
9615 As an example, if Autoconf is installed in its default location,
9616 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
9617 strictly equivalent to the command:
9620 autom4te --prepend-include /usr/local/share/autoconf \
9621 m4sugar/m4sugar.m4f --warnings syntax foo.m4
9625 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
9626 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
9630 autom4te --prepend-include /usr/local/share/autoconf \
9631 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
9635 The definition of the languages is stored in @file{autom4te.cfg}.
9637 @node Customizing autom4te
9638 @subsection Customizing @command{autom4te}
9640 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
9641 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
9642 as found in the directory from which @command{autom4te} is run). The
9643 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
9644 then @file{./.autom4te.cfg}, and finally the command line arguments.
9646 In these text files, comments are introduced with @code{#}, and empty
9647 lines are ignored. Customization is performed on a per-language basis,
9648 wrapped in between a @samp{begin-language: "@var{language}"},
9649 @samp{end-language: "@var{language}"} pair.
9651 Customizing a language stands for appending options (@pxref{autom4te
9652 Invocation}) to the current definition of the language. Options, and
9653 more generally arguments, are introduced by @samp{args:
9654 @var{arguments}}. You may use the traditional shell syntax to quote the
9657 As an example, to disable Autoconf caches (@file{autom4te.cache})
9658 globally, include the following lines in @file{~/.autom4te.cfg}:
9661 ## ------------------ ##
9662 ## User Preferences. ##
9663 ## ------------------ ##
9665 begin-language: "Autoconf-without-aclocal-m4"
9667 end-language: "Autoconf-without-aclocal-m4"
9671 @node Programming in M4sugar
9672 @section Programming in M4sugar
9675 M4 by itself provides only a small, but sufficient, set of all-purpose
9676 macros. M4sugar introduces additional generic macros. Its name was
9677 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
9681 * Redefined M4 Macros:: M4 builtins changed in M4sugar
9682 * Looping constructs:: Iteration in M4
9683 * Evaluation Macros:: More quotation and evaluation control
9684 * Text processing Macros:: String manipulation in M4
9685 * Forbidden Patterns:: Catching unexpanded macros
9688 @node Redefined M4 Macros
9689 @subsection Redefined M4 Macros
9712 With a few exceptions, all the M4 native macros are moved in the
9713 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
9714 @code{m4_define} etc.
9716 Some M4 macros are redefined, and are slightly incompatible with their
9721 This macro kept its original name: no @code{m4_dnl} is defined.
9724 @defmac m4_defn (@var{macro})
9726 Unlike the M4 builtin, this macro fails if @var{macro} is not
9727 defined. See @code{m4_undefine}.
9730 @defmac m4_exit (@var{exit-status})
9732 This macro corresponds to @code{m4exit}.
9735 @defmac m4_if (@var{comment})
9736 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
9737 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
9739 This macro corresponds to @code{ifelse}.
9742 @defmac m4_include (@var{file})
9743 @defmacx m4_sinclude (@var{file})
9746 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
9749 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
9751 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
9752 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9753 provide extended regular expression syntax via @code{epatsubst}.
9756 @defmac m4_popdef (@var{macro})
9758 Unlike the M4 builtin, this macro fails if @var{macro} is not
9759 defined. See @code{m4_undefine}.
9762 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
9764 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
9765 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
9766 provide extended regular expression syntax via @code{eregexp}.
9769 @defmac m4_wrap (@var{text})
9771 This macro corresponds to @code{m4wrap}.
9773 Posix requires arguments of multiple @code{m4wrap} calls to be
9774 reprocessed at @acronym{EOF} in the same order as the original calls.
9775 @acronym{GNU} M4 versions through 1.4.x, however, reprocess them in
9776 reverse order. Your code should not depend on the order.
9778 Also, Posix requires @code{m4wrap} to ignore its second and succeeding
9779 arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the
9780 arguments with intervening spaces. Your code should not pass more than
9783 You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected
9784 token pasting between consecutive invocations of @code{m4_wrap}, as in:
9787 m4_define([foo], [bar])
9788 m4_define([foofoo], [OUCH])
9795 @defmac m4_undefine (@var{macro})
9797 Unlike the M4 builtin, this macro fails if @var{macro} is not
9801 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
9805 to recover the behavior of the builtin.
9810 @node Looping constructs
9811 @subsection Looping constructs
9813 The following macros implement loops in M4.
9815 @defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression})
9817 Loop over the numeric values between @var{first} and @var{last}
9818 including bounds by increments of @var{step}. For each iteration,
9819 expand @var{expression} with the numeric value assigned to @var{var}.
9820 If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending
9821 on the order of the limits. If given, @var{step} has to match this
9825 @defmac m4_foreach (@var{var}, @var{list}, @var{expression})
9827 Loop over the comma-separated M4 list @var{list}, assigning each value
9828 to @var{var}, and expand @var{expression}. The following example
9832 m4_foreach([myvar], [[foo], [bar, baz]],
9839 @defmac m4_foreach_w (@var{var}, @var{list}, @var{expression})
9841 Loop over the white-space-separated list @var{list}, assigning each value
9842 to @var{var}, and expand @var{expression}.
9844 The deprecated macro @code{AC_FOREACH} is an alias of
9845 @code{m4_foreach_w}.
9850 @node Evaluation Macros
9851 @subsection Evaluation Macros
9853 The following macros give some control over the order of the evaluation
9854 by adding or removing levels of quotes. They are meant for hard-core M4
9857 @defmac m4_dquote (@var{arg1}, @dots{})
9859 Return the arguments as a quoted list of quoted arguments.
9862 @defmac m4_quote (@var{arg1}, @dots{})
9864 Return the arguments as a single entity, i.e., wrap them into a pair of
9868 The following example aims at emphasizing the difference between (i), not
9869 using these macros, (ii), using @code{m4_quote}, and (iii), using
9873 $ @kbd{cat example.m4}
9874 # Overquote, so that quotes are visible.
9875 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
9878 show(m4_quote(a, b))
9879 show(m4_dquote(a, b))
9880 $ @kbd{autom4te -l m4sugar example.m4}
9881 $1 = a, $@@ = [a],[b]
9882 $1 = a,b, $@@ = [a,b]
9883 $1 = [a],[b], $@@ = [[a],[b]]
9888 @node Text processing Macros
9889 @subsection Text processing Macros
9891 The following macros may be used to manipulate strings in M4.
9892 They are not intended for casual use.
9894 @defmac m4_re_escape (@var{string})
9896 Backslash-escape all characters in @var{string} that are active in
9900 @defmac m4_tolower (@var{string})
9901 @defmacx m4_toupper (@var{string})
9904 Return @var{string} with letters converted to upper or lower case,
9908 @defmac m4_split (@var{string}, @ovar{regexp})
9910 Split @var{string} into an M4 list of elements quoted by @samp{[} and
9911 @samp{]}, while keeping white space at the beginning and at the end.
9912 If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
9913 If @var{string} is empty, the result is an empty list.
9916 @defmac m4_normalize (@var{string})
9918 Remove leading and trailing spaces and tabs, sequences of
9919 backslash-then-newline, and replace multiple spaces and tabs with a
9923 @defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
9924 @defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator})
9926 @msindex{append_uniq}
9927 Redefine @var{macro-name} to its former contents with @var{separator}
9928 and @var{string} added at the end. If @var{macro-name} was undefined
9929 before (but not if it was defined but empty), then no @var{separator} is
9930 added. @code{m4_append} can be used to grow strings, and
9931 @code{m4_append_uniq} to grow strings without duplicating substrings.
9936 @node Forbidden Patterns
9937 @subsection Forbidden Patterns
9938 @cindex Forbidden patterns
9939 @cindex Patterns, forbidden
9941 M4sugar provides a means to define suspicious patterns, patterns
9942 describing tokens which should not be found in the output. For
9943 instance, if an Autoconf @file{configure} script includes tokens such as
9944 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
9945 wrong (typically a macro was not evaluated because of overquotation).
9947 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
9949 @defmac m4_pattern_forbid (@var{pattern})
9950 @msindex{pattern_forbid}
9951 Declare that no token matching @var{pattern} must be found in the output.
9952 Comments are not checked; this can be a problem if, for instance, you
9953 have some macro left unexpanded after an @samp{#include}. No consensus
9954 is currently found in the Autoconf community, as some people consider it
9955 should be valid to name macros in comments (which doesn't make sense to
9956 the author of this documentation, as @samp{#}-comments should document
9957 the output, not the input, documented by @samp{dnl} comments).
9960 Of course, you might encounter exceptions to these generic rules, for
9961 instance you might have to refer to @samp{$m4_flags}.
9963 @defmac m4_pattern_allow (@var{pattern})
9964 @msindex{pattern_allow}
9965 Any token matching @var{pattern} is allowed, including if it matches an
9966 @code{m4_pattern_forbid} pattern.
9969 @node Programming in M4sh
9970 @section Programming in M4sh
9972 @c FIXME: Eventually will become a chapter, as it is not related to
9973 @c programming in M4 per se.
9975 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
9976 scripts. This name was coined by Lars J. Aas, who notes that,
9977 according to the Webster's Revised Unabridged Dictionary (1913):
9980 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
9981 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
9985 A mass of mixed ingredients reduced to a soft pulpy state by beating or
9989 A mixture of meal or bran and water fed to animals.
9992 A mess; trouble. [Obs.] --Beau.@: & Fl.
9997 For the time being, it is not mature enough to be widely used.
9999 M4sh provides portable alternatives for some common shell constructs
10000 that unfortunately are not portable in practice.
10002 @c Deprecated, to be replaced by a better API
10004 @defmac AS_BASENAME (@var{file-name})
10006 Output the non-directory portion of @var{file-name}. For example,
10007 if @code{$file} is @samp{/one/two/three}, the command
10008 @code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}.
10012 @defmac AS_BOURNE_COMPATIBLE
10013 @asindex{BOURNE_COMPATIBLE}
10014 Set up the shell to be more compatible with the Bourne shell as
10015 standardized by Posix, if possible. This may involve setting
10016 environment variables, or setting options, or similar
10017 implementation-specific actions.
10020 @defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default})
10022 Expand into a shell @samp{case} statement, where @var{word} is matched
10023 against one or more patterns. @var{if-matched} is run if the
10024 corresponding pattern matched @var{word}, else @var{default} is run.
10027 @defmac AS_DIRNAME (@var{file-name})
10029 Output the directory portion of @var{file-name}. For example,
10030 if @code{$file} is @samp{/one/two/three}, the command
10031 @code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}.
10034 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
10036 Run shell code @var{test1}. If @var{test1} exits with a zero status then
10037 run shell code @var{run-if-true1}, else examine further tests. If no test
10038 exits with a zero status, run shell code @var{run-if-false}, with
10039 simplifications if either @var{run-if-true1} or @var{run-if-false1}
10040 is empty. For example,
10043 AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])],
10044 [test "$foo" != no], [HANDLE_FOO([maybe])],
10045 [echo foo not specified])
10049 ensures any required macros of @code{HANDLE_FOO}
10050 are expanded before the first test.
10053 @defmac AS_MKDIR_P (@var{file-name})
10055 Make the directory @var{file-name}, including intervening directories
10056 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
10057 except that it is portable to older versions of @command{mkdir} that
10058 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
10059 succeeds if @var{file-name} is a symbolic link to an existing directory,
10060 even though Posix is unclear whether @samp{mkdir -p} should
10061 succeed in that case. If creation of @var{file-name} fails, exit the
10064 Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}).
10067 @defmac AS_SHELL_SANITIZE
10068 @asindex{SHELL_SANITIZE}
10069 Initialize the shell suitably for @code{configure} scripts. This has
10070 the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other
10071 environment variables for predictable results from configuration tests.
10072 For example, it sets @env{LC_ALL} to change to the default C locale.
10073 @xref{Special Shell Variables}.
10076 @defmac AS_TR_CPP (@var{expression})
10078 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
10082 # This outputs "#define HAVE_CHAR_P 1".
10084 echo "#define AS_TR_CPP([HAVE_$type]) 1"
10088 @defmac AS_TR_SH (@var{expression})
10090 Transform @var{expression} into a valid shell variable name. For example:
10093 # This outputs "Have it!".
10094 header="sys/some file.h"
10095 AS_TR_SH([HAVE_$header])=yes
10096 if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
10100 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
10101 @asindex{SET_CATFILE}
10102 Set the shell variable @var{var} to @var{dir}/@var{file}, but
10103 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
10104 @var{file} is absolute, etc.).
10108 @node File Descriptor Macros
10109 @section File Descriptor Macros
10111 @cindex standard input
10112 @cindex file descriptors
10113 @cindex descriptors
10114 @cindex low-level output
10115 @cindex output, low-level
10117 The following macros define file descriptors used to output messages
10118 (or input values) from @file{configure} scripts.
10122 echo "$wombats found" >&AS_MESSAGE_LOG_FD
10123 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
10124 read kangaroos <&AS_ORIGINAL_STDIN_FD`
10128 However doing so is seldom needed, because Autoconf provides higher
10129 level macros as described below.
10131 @defmac AS_MESSAGE_FD
10132 @asindex{MESSAGE_FD}
10133 The file descriptor for @samp{checking for...} messages and results.
10134 Normally this directs messages to the standard output, however when
10135 @command{configure} is run with the @option{-q} option, messages sent to
10136 @code{AS_MESSAGE_FD} are discarded.
10138 If you want to display some messages, consider using one of the printing
10139 macros (@pxref{Printing Messages}) instead. Copies of messages output
10140 via these macros are also recorded in @file{config.log}.
10143 @defmac AS_MESSAGE_LOG_FD
10144 @asindex{MESSAGE_LOG_FD}
10146 The file descriptor for messages logged to @file{config.log}. Macros
10147 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
10148 Compiler}), redirect all output to this descriptor. You may want to do
10149 so if you develop such a low-level macro.
10152 @defmac AS_ORIGINAL_STDIN_FD
10153 @asindex{ORIGINAL_STDIN_FD}
10154 The file descriptor for the original standard input.
10156 When @command{configure} runs, it may accidentally execute an
10157 interactive command that has the same name as the non-interactive meant
10158 to be used or checked. If the standard input was the terminal, such
10159 interactive programs would cause @command{configure} to stop, pending
10160 some user input. Therefore @command{configure} redirects its standard
10161 input from @file{/dev/null} during its initialization. This is not
10162 normally a problem, since @command{configure} normally does not need
10165 In the extreme case where your @file{configure} script really needs to
10166 obtain some values from the original standard input, you can read them
10167 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
10171 @c =================================================== Writing Autoconf Macros.
10173 @node Writing Autoconf Macros
10174 @chapter Writing Autoconf Macros
10176 When you write a feature test that could be applicable to more than one
10177 software package, the best thing to do is encapsulate it in a new macro.
10178 Here are some instructions and guidelines for writing Autoconf macros.
10181 * Macro Definitions:: Basic format of an Autoconf macro
10182 * Macro Names:: What to call your new macros
10183 * Reporting Messages:: Notifying @command{autoconf} users
10184 * Dependencies Between Macros:: What to do when macros depend on other macros
10185 * Obsoleting Macros:: Warning about old ways of doing things
10186 * Coding Style:: Writing Autoconf macros @`a la Autoconf
10189 @node Macro Definitions
10190 @section Macro Definitions
10193 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
10194 similar to the M4 builtin @code{m4_define} macro. In addition to
10195 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
10196 constrain the order in which macros are called (@pxref{Prerequisite
10199 An Autoconf macro definition looks like this:
10202 AC_DEFUN(@var{macro-name}, @var{macro-body})
10205 You can refer to any arguments passed to the macro as @samp{$1},
10206 @samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info,
10207 @acronym{GNU} M4}, for more complete information on writing M4 macros.
10209 Be sure to properly quote both the @var{macro-body} @emph{and} the
10210 @var{macro-name} to avoid any problems if the macro happens to have
10211 been previously defined.
10213 Each macro should have a header comment that gives its prototype, and a
10214 brief description. When arguments have default values, display them in
10215 the prototype. For example:
10218 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
10219 # --------------------------------------
10220 m4_define([AC_MSG_ERROR],
10221 [@{ AS_MESSAGE([error: $1], [2])
10222 exit m4_default([$2], [1]); @}])
10225 Comments about the macro should be left in the header comment. Most
10226 other comments make their way into @file{configure}, so just keep
10227 using @samp{#} to introduce comments.
10230 If you have some special comments about pure M4 code, comments
10231 that make no sense in @file{configure} and in the header comment, then
10232 use the builtin @code{dnl}: it causes M4 to discard the text
10233 through the next newline.
10235 Keep in mind that @code{dnl} is rarely needed to introduce comments;
10236 @code{dnl} is more useful to get rid of the newlines following macros
10237 that produce no output, such as @code{AC_REQUIRE}.
10241 @section Macro Names
10243 All of the Autoconf macros have all-uppercase names starting with
10244 @samp{AC_} to prevent them from accidentally conflicting with other
10245 text. All shell variables that they use for internal purposes have
10246 mostly-lowercase names starting with @samp{ac_}. To ensure that your
10247 macros don't conflict with present or future Autoconf macros, you should
10248 prefix your own macro names and any shell variables they use with some
10249 other sequence. Possibilities include your initials, or an abbreviation
10250 for the name of your organization or software package.
10252 Most of the Autoconf macros' names follow a structured naming convention
10253 that indicates the kind of feature check by the name. The macro names
10254 consist of several words, separated by underscores, going from most
10255 general to most specific. The names of their cache variables use the
10256 same convention (@pxref{Cache Variable Names}, for more information on
10259 The first word of the name after @samp{AC_} usually tells the category
10260 of the feature being tested. Here are the categories used in Autoconf for
10261 specific test macros, the kind of macro that you are more likely to
10262 write. They are also used for cache variables, in all-lowercase. Use
10263 them where applicable; where they're not, invent your own categories.
10267 C language builtin features.
10269 Declarations of C variables in header files.
10271 Functions in libraries.
10273 Posix group owners of files.
10279 Absolute names of files, including programs.
10281 The base names of programs.
10283 Members of aggregates.
10285 Operating system features.
10287 C builtin or declared types.
10289 C variables in libraries.
10292 After the category comes the name of the particular feature being
10293 tested. Any further words in the macro name indicate particular aspects
10294 of the feature. For example, @code{AC_FUNC_FNMATCH_GNU} checks whether
10295 the @code{fnmatch} function supports @acronym{GNU} extensions.
10297 An internal macro should have a name that starts with an underscore;
10298 Autoconf internals should therefore start with @samp{_AC_}.
10299 Additionally, a macro that is an internal subroutine of another macro
10300 should have a name that starts with an underscore and the name of that
10301 other macro, followed by one or more words saying what the internal
10302 macro does. For example, @code{AC_PATH_X} has internal macros
10303 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
10305 @node Reporting Messages
10306 @section Reporting Messages
10307 @cindex Messages, from @command{autoconf}
10309 When macros statically diagnose abnormal situations, benign or fatal,
10310 they should report them using these macros. For dynamic issues, i.e.,
10311 when @command{configure} is run, see @ref{Printing Messages}.
10313 @defmac AC_DIAGNOSE (@var{category}, @var{message})
10315 Report @var{message} as a warning (or as an error if requested by the
10316 user) if warnings of the @var{category} are turned on. You are
10317 encouraged to use standard categories, which currently include:
10321 messages that don't fall into one of the following categories. Use of an
10322 empty @var{category} is equivalent.
10325 related to cross compilation issues.
10328 use of an obsolete construct.
10331 dubious syntactic constructs, incorrectly ordered macro calls.
10335 @defmac AC_WARNING (@var{message})
10337 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
10338 strongly encouraged to use a finer grained category.
10341 @defmac AC_FATAL (@var{message})
10343 Report a severe error @var{message}, and have @command{autoconf} die.
10346 When the user runs @samp{autoconf -W error}, warnings from
10347 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
10348 @ref{autoconf Invocation}.
10350 @node Dependencies Between Macros
10351 @section Dependencies Between Macros
10352 @cindex Dependencies between macros
10354 Some Autoconf macros depend on other macros having been called first in
10355 order to work correctly. Autoconf provides a way to ensure that certain
10356 macros are called if needed and a way to warn the user if macros are
10357 called in an order that might cause incorrect operation.
10360 * Prerequisite Macros:: Ensuring required information
10361 * Suggested Ordering:: Warning about possible ordering problems
10362 * One-Shot Macros:: Ensuring a macro is called only once
10365 @node Prerequisite Macros
10366 @subsection Prerequisite Macros
10367 @cindex Prerequisite macros
10368 @cindex Macros, prerequisites
10370 A macro that you write might need to use values that have previously
10371 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
10372 examines the output of @code{flex} or @code{lex}, so it depends on
10373 @code{AC_PROG_LEX} having been called first to set the shell variable
10376 Rather than forcing the user of the macros to keep track of the
10377 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
10378 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
10379 called if it is needed, and only called once.
10381 @defmac AC_REQUIRE (@var{macro-name})
10383 If the M4 macro @var{macro-name} has not already been called, call it
10384 (without any arguments). Make sure to quote @var{macro-name} with
10385 square brackets. @var{macro-name} must have been defined using
10386 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10387 that it has been called.
10389 @code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it
10390 must not be called from the top level.
10393 @code{AC_REQUIRE} is often misunderstood. It really implements
10394 dependencies between macros in the sense that if one macro depends upon
10395 another, the latter is expanded @emph{before} the body of the
10396 former. To be more precise, the required macro is expanded before
10397 the outermost defined macro in the current expansion stack.
10398 In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of
10399 @code{FOO}. For instance, this definition of macros:
10403 AC_DEFUN([TRAVOLTA],
10404 [test "$body_temperature_in_celsius" -gt "38" &&
10405 dance_floor=occupied])
10406 AC_DEFUN([NEWTON_JOHN],
10407 [test "$hair_style" = "curly" &&
10408 dance_floor=occupied])
10412 AC_DEFUN([RESERVE_DANCE_FLOOR],
10413 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10414 AC_REQUIRE([TRAVOLTA])
10415 AC_REQUIRE([NEWTON_JOHN])
10421 with this @file{configure.ac}
10424 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
10425 RESERVE_DANCE_FLOOR
10426 if test "$dance_floor" = occupied; then
10427 AC_MSG_ERROR([cannot pick up here, let's move])
10432 does not leave you with a better chance to meet a kindred soul at
10433 other times than Saturday night since it expands into:
10437 test "$body_temperature_in_Celsius" -gt "38" &&
10438 dance_floor=occupied
10439 test "$hair_style" = "curly" &&
10440 dance_floor=occupied
10442 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
10449 This behavior was chosen on purpose: (i) it prevents messages in
10450 required macros from interrupting the messages in the requiring macros;
10451 (ii) it avoids bad surprises when shell conditionals are used, as in:
10456 AC_REQUIRE([SOME_CHECK])
10463 The helper macros @code{AS_IF} and @code{AS_CASE} may be used to
10464 enforce expansion of required macros outside of shell conditional
10465 constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls
10466 at the beginning of a macro. You can use @code{dnl} to avoid the empty
10469 @node Suggested Ordering
10470 @subsection Suggested Ordering
10471 @cindex Macros, ordering
10472 @cindex Ordering macros
10474 Some macros should be run before another macro if both are called, but
10475 neither @emph{requires} that the other be called. For example, a macro
10476 that changes the behavior of the C compiler should be called before any
10477 macros that run the C compiler. Many of these dependencies are noted in
10480 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
10481 with this kind of dependency appear out of order in a
10482 @file{configure.ac} file. The warning occurs when creating
10483 @command{configure} from @file{configure.ac}, not when running
10484 @command{configure}.
10486 For example, @code{AC_PROG_CPP} checks whether the C compiler
10487 can run the C preprocessor when given the @option{-E} option. It should
10488 therefore be called after any macros that change which C compiler is
10489 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
10492 AC_BEFORE([$0], [AC_PROG_CPP])dnl
10496 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
10497 when @code{AC_PROG_CC} is called.
10499 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
10501 Make M4 print a warning message to the standard error output if
10502 @var{called-macro-name} has already been called. @var{this-macro-name}
10503 should be the name of the macro that is calling @code{AC_BEFORE}. The
10504 macro @var{called-macro-name} must have been defined using
10505 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
10506 that it has been called.
10509 @node One-Shot Macros
10510 @subsection One-Shot Macros
10511 @cindex One-shot macros
10512 @cindex Macros, called once
10514 Some macros should be called only once, either because calling them
10515 multiple time is unsafe, or because it is bad style. For instance
10516 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
10517 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
10518 sense to run these expensive checks more than once. Such one-shot
10519 macros can be defined using @code{AC_DEFUN_ONCE}.
10521 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
10522 @acindex{DEFUN_ONCE}
10524 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
10525 Definitions}), and emit a warning any time the macro is called more than
10529 Obviously it is not sensible to evaluate a macro defined by
10530 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}.
10531 Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite
10534 @node Obsoleting Macros
10535 @section Obsoleting Macros
10536 @cindex Obsoleting macros
10537 @cindex Macros, obsoleting
10539 Configuration and portability technology has evolved over the years.
10540 Often better ways of solving a particular problem are developed, or
10541 ad-hoc approaches are systematized. This process has occurred in many
10542 parts of Autoconf. One result is that some of the macros are now
10543 considered @dfn{obsolete}; they still work, but are no longer considered
10544 the best thing to do, hence they should be replaced with more modern
10545 macros. Ideally, @command{autoupdate} should replace the old macro calls
10546 with their modern implementation.
10548 Autoconf provides a simple means to obsolete a macro.
10550 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
10552 Define @var{old-macro} as @var{implementation}. The only difference
10553 with @code{AC_DEFUN} is that the user is warned that
10554 @var{old-macro} is now obsolete.
10556 If she then uses @command{autoupdate}, the call to @var{old-macro} is
10557 replaced by the modern @var{implementation}. @var{message} should
10558 include information on what to do after running @command{autoupdate};
10559 @command{autoupdate} prints it as a warning, and includes it
10560 in the updated @file{configure.ac} file.
10562 The details of this macro are hairy: if @command{autoconf} encounters an
10563 @code{AU_DEFUN}ed macro, all macros inside its second argument are expanded
10564 as usual. However, when @command{autoupdate} is run, only M4 and M4sugar
10565 macros are expanded here, while all other macros are disabled and
10566 appear literally in the updated @file{configure.ac}.
10569 @defmac AU_ALIAS (@var{old-name}, @var{new-name})
10571 Used if the @var{old-name} is to be replaced by a call to @var{new-macro}
10572 with the same parameters. This happens for example if the macro was renamed.
10576 @section Coding Style
10577 @cindex Coding style
10579 The Autoconf macros follow a strict coding style. You are encouraged to
10580 follow this style, especially if you intend to distribute your macro,
10581 either by contributing it to Autoconf itself, or via other means.
10583 The first requirement is to pay great attention to the quotation. For
10584 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
10586 Do not try to invent new interfaces. It is likely that there is a macro
10587 in Autoconf that resembles the macro you are defining: try to stick to
10588 this existing interface (order of arguments, default values, etc.). We
10589 @emph{are} conscious that some of these interfaces are not perfect;
10590 nevertheless, when harmless, homogeneity should be preferred over
10593 Be careful about clashes both between M4 symbols and between shell
10596 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
10597 you are unlikely to generate conflicts. Nevertheless, when you need to
10598 set a special value, @emph{avoid using a regular macro name}; rather,
10599 use an ``impossible'' name. For instance, up to version 2.13, the macro
10600 @code{AC_SUBST} used to remember what @var{symbol} macros were already defined
10601 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
10602 But since there is a macro named @code{AC_SUBST_FILE}, it was just
10603 impossible to @samp{AC_SUBST(FILE)}! In this case,
10604 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
10605 have been used (yes, with the parentheses).
10606 @c or better yet, high-level macros such as @code{m4_expand_once}
10608 No Autoconf macro should ever enter the user-variable name space; i.e.,
10609 except for the variables that are the actual result of running the
10610 macro, all shell variables should start with @code{ac_}. In
10611 addition, small macros or any macro that is likely to be embedded in
10612 other macros should be careful not to use obvious names.
10615 Do not use @code{dnl} to introduce comments: most of the comments you
10616 are likely to write are either header comments which are not output
10617 anyway, or comments that should make their way into @file{configure}.
10618 There are exceptional cases where you do want to comment special M4
10619 constructs, in which case @code{dnl} is right, but keep in mind that it
10622 M4 ignores the leading blanks and newlines before each argument.
10623 Use this feature to
10624 indent in such a way that arguments are (more or less) aligned with the
10625 opening parenthesis of the macro being called. For instance, instead of
10628 AC_CACHE_CHECK(for EMX OS/2 environment,
10630 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
10631 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
10638 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10639 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10640 [ac_cv_emxos2=yes],
10641 [ac_cv_emxos2=no])])
10648 AC_CACHE_CHECK([for EMX OS/2 environment],
10650 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
10651 [return __EMX__;])],
10652 [ac_cv_emxos2=yes],
10653 [ac_cv_emxos2=no])])
10656 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
10657 cross-compiling, provide a pessimistic value (typically @samp{no}).
10659 Feel free to use various tricks to prevent auxiliary tools, such as
10660 syntax-highlighting editors, from behaving improperly. For instance,
10664 m4_bpatsubst([$1], [$"])
10671 m4_bpatsubst([$1], [$""])
10675 so that Emacsen do not open an endless ``string'' at the first quote.
10676 For the same reasons, avoid:
10686 test $[@@%:@@] != 0
10690 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
10691 breaking the bracket-matching highlighting from Emacsen. Note the
10692 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
10693 not escape when it is unnecessary. Common examples of useless quotation
10694 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
10695 etc. If you add portability issues to the picture, you'll prefer
10696 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
10697 better than hacking Autoconf @code{:-)}.
10699 When using @command{sed}, don't use @option{-e} except for indenting
10700 purposes. With the @code{s} and @code{y} commands, the preferred
10701 separator is @samp{/} unless @samp{/} itself might appear in the pattern
10702 or replacement, in which case you should use @samp{|}, or optionally
10703 @samp{,} if you know the pattern and replacement cannot contain a file
10704 name. If none of these characters will do, choose a printable character
10705 that cannot appear in the pattern or replacement. Characters from the
10706 set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or
10707 replacement might contain a file name, since they have special meaning
10708 to the shell and are less likely to occur in file names.
10710 @xref{Macro Definitions}, for details on how to define a macro. If a
10711 macro doesn't use @code{AC_REQUIRE}, is expected to never be the object
10712 of an @code{AC_REQUIRE} directive, and macros required by other macros
10713 inside arguments do not need to be expanded before this macro, then
10714 use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}.
10715 All the @code{AC_REQUIRE} statements should be at the beginning of the
10716 macro, and each statement should be followed by @code{dnl}.
10718 You should not rely on the number of arguments: instead of checking
10719 whether an argument is missing, test that it is not empty. It provides
10720 both a simpler and a more predictable interface to the user, and saves
10721 room for further arguments.
10723 Unless the macro is short, try to leave the closing @samp{])} at the
10724 beginning of a line, followed by a comment that repeats the name of the
10725 macro being defined. This introduces an additional newline in
10726 @command{configure}; normally, that is not a problem, but if you want to
10727 remove it you can use @samp{[]dnl} on the last line. You can similarly
10728 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
10729 is recommended instead of @samp{dnl} to ensure that M4 does not
10730 interpret the @samp{dnl} as being attached to the preceding text or
10731 macro output. For example, instead of:
10734 AC_DEFUN([AC_PATH_X],
10735 [AC_MSG_CHECKING([for X])
10737 @r{# @dots{}omitted@dots{}}
10738 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10746 AC_DEFUN([AC_PATH_X],
10747 [AC_REQUIRE_CPP()[]dnl
10748 AC_MSG_CHECKING([for X])
10749 @r{# @dots{}omitted@dots{}}
10750 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
10755 If the macro is long, try to split it into logical chunks. Typically,
10756 macros that check for a bug in a function and prepare its
10757 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
10758 this setup. Do not hesitate to introduce auxiliary macros to factor
10761 In order to highlight the recommended coding style, here is a macro
10762 written the old way:
10765 dnl Check for EMX on OS/2.
10767 AC_DEFUN(_AC_EMXOS2,
10768 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
10769 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
10770 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
10771 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
10780 # Check for EMX on OS/2.
10781 m4_define([_AC_EMXOS2],
10782 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
10783 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
10784 [ac_cv_emxos2=yes],
10785 [ac_cv_emxos2=no])])
10786 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
10793 @c ============================================= Portable Shell Programming
10795 @node Portable Shell
10796 @chapter Portable Shell Programming
10797 @cindex Portable shell programming
10799 When writing your own checks, there are some shell-script programming
10800 techniques you should avoid in order to make your code portable. The
10801 Bourne shell and upward-compatible shells like the Korn shell and Bash
10802 have evolved over the years, but to prevent trouble, do not take
10803 advantage of features that were added after Unix version 7, circa
10804 1977 (@pxref{Systemology}).
10806 You should not use shell functions, aliases, negated character
10807 classes, or other features that are not found in all Bourne-compatible
10808 shells; restrict yourself to the lowest common denominator. Even
10809 @code{unset} is not supported by all shells!
10811 Some ancient systems have quite
10812 small limits on the length of the @samp{#!} line; for instance, 32
10813 bytes (not including the newline) on SunOS 4.
10814 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
10815 required a single space between the @samp{#!} and the @samp{/}.
10816 However, these ancient systems are no longer of practical concern.
10818 The set of external programs you should run in a @command{configure} script
10819 is fairly small. @xref{Utilities in Makefiles, , Utilities in
10820 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
10821 restriction allows users to start out with a fairly small set of
10822 programs and build the rest, avoiding too many interdependencies between
10825 Some of these external utilities have a portable subset of features; see
10826 @ref{Limitations of Usual Tools}.
10828 There are other sources of documentation about shells. The
10829 specification for the Posix
10830 @uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell
10831 Command Language}, though more generous than the restrictive shell
10832 subset described above, is fairly portable nowadays. Also please see
10833 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}.
10836 * Shellology:: A zoology of shells
10837 * Here-Documents:: Quirks and tricks
10838 * File Descriptors:: FDs and redirections
10839 * File System Conventions:: File names
10840 * Shell Substitutions:: Variable and command expansions
10841 * Assignments:: Varying side effects of assignments
10842 * Parentheses:: Parentheses in shell scripts
10843 * Slashes:: Slashes in shell scripts
10844 * Special Shell Variables:: Variables you should not change
10845 * Limitations of Builtins:: Portable use of not so portable /bin/sh
10846 * Limitations of Usual Tools:: Portable use of portable tools
10850 @section Shellology
10853 There are several families of shells, most prominently the Bourne family
10854 and the C shell family which are deeply incompatible. If you want to
10855 write portable shell scripts, avoid members of the C shell family. The
10856 @uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the
10857 Shell difference FAQ} includes a small history of Posix shells, and a
10858 comparison between several of them.
10860 Below we describe some of the members of the Bourne shell family.
10865 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
10866 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
10867 bugs that are fixed in the 0.3.x series, but portable shell scripts
10868 should work around them, since version 0.2 is still shipped with many
10869 @acronym{GNU}/Linux distributions.
10871 To be compatible with Ash 0.2:
10875 don't use @samp{$?} after expanding empty or unset variables,
10876 or at the start of an @command{eval}:
10882 echo "Do not use it: $?"
10884 eval 'echo "Do not use it: $?"'
10888 don't use command substitution within variable expansion:
10895 beware that single builtin substitutions are not performed by a
10896 subshell, hence their effect applies to the current shell! @xref{Shell
10897 Substitutions}, item ``Command Substitution''.
10902 To detect whether you are running Bash, test whether
10903 @code{BASH_VERSION} is set. To require
10904 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
10905 Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
10906 Manual}, for details.
10908 @item Bash 2.05 and later
10909 @cindex Bash 2.05 and later
10910 Versions 2.05 and later of Bash use a different format for the
10911 output of the @command{set} builtin, designed to make evaluating its
10912 output easier. However, this output is not compatible with earlier
10913 versions of Bash (or with many other shells, probably). So if
10914 you use Bash 2.05 or higher to execute @command{configure},
10915 you'll need to use Bash 2.05 for all other build tasks as well.
10920 @prindex @samp{ksh}
10921 @prindex @samp{ksh88}
10922 @prindex @samp{ksh93}
10923 The Korn shell is compatible with the Bourne family and it mostly
10924 conforms to Posix. It has two major variants commonly
10925 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
10926 release. It is usually called @command{ksh}, but is called @command{sh}
10927 on some hosts if you set your path appropriately.
10929 Solaris systems have three variants:
10930 @prindex @command{/usr/bin/ksh} on Solaris
10931 @command{/usr/bin/ksh} is @samp{ksh88}; it is
10932 standard on Solaris 2.0 and later.
10933 @prindex @command{/usr/xpg4/bin/sh} on Solaris
10934 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
10935 @samp{ksh88}; it is standard on Solaris 9 and later.
10936 @prindex @command{/usr/dt/bin/dtksh} on Solaris
10937 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
10938 Variants that are not standard may be parts of optional
10939 packages. There is no extra charge for these packages, but they are
10940 not part of a minimal OS install and therefore some installations may
10943 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
10944 is also available as @command{/usr/bin/posix/sh}. If the environment
10945 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
10946 the standard shell conform to Posix.
10949 @prindex @samp{pdksh}
10950 A public-domain clone of the Korn shell called @command{pdksh} is widely
10951 available: it has most of the @samp{ksh88} features along with a few of
10952 its own. It usually sets @code{KSH_VERSION}, except if invoked as
10953 @command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require
10954 Posix compatibility by running @samp{set -o posix}. Unfortunately, with
10955 @command{pdksh} 5.2.14 (the latest stable version as of February 2006)
10956 Posix mode is buggy and causes @command{pdksh} to depart from Posix in
10957 at least one respect:
10960 $ @kbd{echo "`echo \"hello\"`"}
10962 $ @kbd{set -o posix}
10963 $ @kbd{echo "`echo \"hello\"`"}
10967 The last line of output contains spurious quotes. This is yet another
10968 reason why portable shell code should not contain
10969 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
10974 To detect whether you are running @command{zsh}, test whether
10975 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
10976 compatible with the Bourne shell: you must execute @samp{emulate sh},
10977 and for @command{zsh} versions before 3.1.6-dev-18 you must also
10978 set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility,
10979 zsh, The Z Shell Manual}, for details.
10981 The default Mac OS X @command{sh} was originally Zsh; it was changed to
10982 Bash in Mac OS X 10.2.
10985 The following discussion between Russ Allbery and Robert Lipe is worth
10992 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
10993 leads to a permanent deadlock. Vendors don't want to break users'
10994 existing shell scripts, and there are some corner cases in the Bourne
10995 shell that are not completely compatible with a Posix shell. Thus,
10996 vendors who have taken this route will @emph{never} (OK@dots{}``never say
10997 never'') replace the Bourne shell (as @command{/bin/sh}) with a
11005 This is exactly the problem. While most (at least most System V's) do
11006 have a Bourne shell that accepts shell functions most vendor
11007 @command{/bin/sh} programs are not the Posix shell.
11009 So while most modern systems do have a shell @emph{somewhere} that meets the
11010 Posix standard, the challenge is to find it.
11013 @node Here-Documents
11014 @section Here-Documents
11015 @cindex Here-documents
11016 @cindex Shell here-documents
11018 Don't rely on @samp{\} being preserved just because it has no special
11019 meaning together with the next symbol. In the native @command{sh}
11020 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
11021 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
11022 use @samp{\\} to get @samp{\}.
11024 With Open@acronym{BSD} 2.7's @command{sh}
11040 bash-2.04$ @kbd{cat <<EOF
11047 Some shells mishandle large here-documents: for example,
11048 Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are
11049 derived from Korn shell version M-12/28/93d, mishandle braced variable
11050 expansion that crosses a 1024- or 4096-byte buffer boundary
11051 within a here-document. Only the part of the variable name after the boundary
11052 is used. For example, @code{$@{variable@}} could be replaced by the expansion
11053 of @code{$@{ble@}}. If the end of the variable name is aligned with the block
11054 boundary, the shell reports an error, as if you used @code{$@{@}}.
11055 Instead of @code{$@{variable-default@}}, the shell may expand
11056 @code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often
11057 be worked around by omitting the braces: @code{$variable}. The bug was fixed in
11058 @samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were
11059 still shipping older versions with the bug.
11061 Many older shells (including the Bourne shell) implement here-documents
11062 inefficiently. In particular, some shells can be extremely inefficient when
11063 a single statement contains many here-documents. For instance if your
11064 @file{configure.ac} includes something like:
11068 if <cross_compiling>; then
11069 assume this and that
11073 check something else
11081 A shell parses the whole @code{if}/@code{fi} construct, creating
11082 temporary files for each here-document in it. Some shells create links
11083 for such here-documents on every @code{fork}, so that the clean-up code
11084 they had installed correctly removes them. It is creating the links
11085 that can take the shell forever.
11087 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
11088 @code{if}/@code{fi} constructs, would improve the performance
11089 significantly. Anyway, this kind of construct is not exactly the
11090 typical use of Autoconf. In fact, it's even not recommended, because M4
11091 macros can't look into shell conditionals, so we may fail to expand a
11092 macro when it was expanded before in a conditional path, and the
11093 condition turned out to be false at runtime, and we end up not
11094 executing the macro at all.
11096 @node File Descriptors
11097 @section File Descriptors
11098 @cindex Descriptors
11099 @cindex File descriptors
11100 @cindex Shell file descriptors
11102 Most shells, if not all (including Bash, Zsh, Ash), output traces on
11103 stderr, even for subshells. This might result in undesirable content
11104 if you meant to capture the standard-error output of the inner command:
11107 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
11109 + eval echo foo >&2
11112 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
11114 + eval 'echo foo >&2'
11117 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
11118 @i{# Traces on startup files deleted here.}
11120 +zsh:1> eval echo foo >&2
11126 One workaround is to grep out uninteresting lines, hoping not to remove
11129 If you intend to redirect both standard error and standard output,
11130 redirect standard output first. This works better with @acronym{HP-UX},
11131 since its shell mishandles tracing if standard error is redirected
11135 $ @kbd{sh -x -c ': 2>err >out'}
11137 + 2> err $ @kbd{cat err}
11141 Don't try to redirect the standard error of a command substitution. It
11142 must be done @emph{inside} the command substitution. When running
11143 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
11144 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
11146 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
11147 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
11149 Don't redirect the same file descriptor several times, as you are doomed
11150 to failure under Ultrix.
11153 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
11155 $ @kbd{eval 'echo matter >fullness' >void}
11157 $ @kbd{eval '(echo matter >fullness)' >void}
11159 $ @kbd{(eval '(echo matter >fullness)') >void}
11160 Ambiguous output redirect.
11164 In each case the expected result is of course @file{fullness} containing
11165 @samp{matter} and @file{void} being empty.
11167 Don't rely on file descriptors 0, 1, and 2 remaining closed in a
11168 subsidiary program. If any of these descriptors is closed, the
11169 operating system may open an unspecified file for the descriptor in the
11170 new process image. Posix says this may be done only if the subsidiary
11171 program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for
11174 Don't rely on open file descriptors being open in child processes. In
11175 @command{ksh}, file descriptors above 2 which are opened using
11176 @samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as
11177 that involved in the fork-and-exec which runs a program or script).
11178 Thus, using @command{sh}, we have:
11181 $ @kbd{cat ./descrips}
11203 Within the process which runs the @samp{descrips} script, file
11204 descriptor 5 is closed.
11206 @acronym{DOS} variants cannot rename or remove open files, such as in
11207 @samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is
11208 perfectly portable among Posix hosts.
11210 A few ancient systems reserved some file descriptors. By convention,
11211 file descriptor 3 was opened to @file{/dev/tty} when you logged into
11212 Eighth Edition (1985) through Tenth Edition Unix (1989). File
11213 descriptor 4 had a special use on the Stardent/Kubota Titan (circa
11214 1990), though we don't now remember what it was. Both these systems are
11215 obsolete, so it's now safe to treat file descriptors 3 and 4 like any
11216 other file descriptors.
11218 @node File System Conventions
11219 @section File System Conventions
11220 @cindex File system conventions
11222 Autoconf uses shell-script processing extensively, so the file names
11223 that it processes should not contain characters that are special to the
11224 shell. Special characters include space, tab, newline, @sc{nul}, and
11228 " # $ & ' ( ) * ; < = > ? [ \ ` |
11231 Also, file names should not begin with @samp{~} or @samp{-}, and should
11232 contain neither @samp{-} immediately after @samp{/} nor @samp{~}
11233 immediately after @samp{:}. On Posix-like platforms, directory names
11234 should not contain @samp{:}, as this runs afoul of @samp{:} used as the
11237 These restrictions apply not only to the files that you distribute, but
11238 also to the absolute file names of your source, build, and destination
11241 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
11242 they should be avoided.
11244 Posix lets implementations treat leading @file{//} specially, but
11245 requires leading @file{///} and beyond to be equivalent to @file{/}.
11246 Most Unix variants treat @file{//} like @file{/}. However, some treat
11247 @file{//} as a ``super-root'' that can provide access to files that are
11248 not otherwise reachable from @file{/}. The super-root tradition began
11249 with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
11252 While @command{autoconf} and friends are usually run on some Posix
11253 variety, they can be used on other systems, most notably @acronym{DOS}
11254 variants. This impacts several assumptions regarding file names.
11257 For example, the following code:
11264 foo_dir=$dots$foo_dir ;;
11269 fails to properly detect absolute file names on those systems, because
11270 they can use a drivespec, and usually use a backslash as directory
11271 separator. If you want to be portable to @acronym{DOS} variants (at the
11272 price of rejecting valid but oddball Posix file names like @file{a:\b}),
11273 you can check for absolute file names like this:
11277 [\\/]* | ?:[\\/]* ) # Absolute
11280 foo_dir=$dots$foo_dir ;;
11285 Make sure you quote the brackets if appropriate and keep the backslash as
11286 first character (@pxref{Limitations of Builtins}).
11288 Also, because the colon is used as part of a drivespec, these systems don't
11289 use it as path separator. When creating or accessing paths, you can use the
11290 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
11291 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
11293 File names need extra care as well. While @acronym{DOS} variants
11294 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP})
11295 are usually able to handle long file names properly, there are still
11296 limitations that can seriously break packages. Several of these issues
11297 can be easily detected by the
11298 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
11301 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
11302 indicate where they apply: @sc{sfn} means the issues are only relevant to
11303 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
11304 variants, while @sc{lfn} identifies problems that exist even under
11305 Microsoft Windows variants.
11308 @item No multiple dots (@sc{sfn})
11309 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
11310 important thing to remember when building a portable configure script,
11311 as @command{autoconf} uses a .in suffix for template files.
11313 This is perfectly OK on Posix variants:
11316 AC_CONFIG_HEADERS([config.h])
11317 AC_CONFIG_FILES([source.c foo.bar])
11322 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
11323 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
11324 to @acronym{DOS}-based environments, you should use this instead:
11327 AC_CONFIG_HEADERS([config.h:config.hin])
11328 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
11332 @item No leading dot (@sc{sfn})
11333 @acronym{DOS} cannot handle file names that start with a dot. This is usually
11334 not important for @command{autoconf}.
11336 @item Case insensitivity (@sc{lfn})
11337 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
11338 file called @samp{INSTALL} and a directory called @samp{install}. This
11339 also affects @command{make}; if there's a file called @samp{INSTALL} in
11340 the directory, @samp{make install} does nothing (unless the
11341 @samp{install} target is marked as PHONY).
11343 @item The 8+3 limit (@sc{sfn})
11344 Because the @acronym{DOS} file system only stores the first 8 characters of
11345 the file name and the first 3 of the extension, those must be unique.
11346 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
11347 @file{foobar-prettybird.c} all resolve to the same file name
11348 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
11349 @file{foo.bartender}.
11351 The 8+3 limit is not usually a problem under Microsoft Windows, as it
11353 tails in the short version of file names to make them unique. However, a
11354 registry setting can turn this behavior off. While this makes it
11355 possible to share file trees containing long file names between @sc{sfn}
11356 and @sc{lfn} environments, it also means the above problem applies there
11359 @item Invalid characters (@sc{lfn})
11360 Some characters are invalid in @acronym{DOS} file names, and should therefore
11361 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
11362 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
11363 In a @sc{sfn} environment, other characters are also invalid. These
11364 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
11366 @item Invalid names (@sc{lfn})
11367 Some @acronym{DOS} file names are reserved, and cause problems if you
11368 try to use files with those names. These names include @file{CON},
11369 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
11370 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
11371 File names are case insensitive, so even names like
11372 @file{aux/config.guess} are disallowed.
11376 @node Shell Substitutions
11377 @section Shell Substitutions
11378 @cindex Shell substitutions
11380 Contrary to a persistent urban legend, the Bourne shell does not
11381 systematically split variables and back-quoted expressions, in particular
11382 on the right-hand side of assignments and in the argument of @code{case}.
11383 For instance, the following code:
11386 case "$given_srcdir" in
11387 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
11388 *) top_srcdir="$dots$given_srcdir" ;;
11393 is more readable when written as:
11396 case $given_srcdir in
11397 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
11398 *) top_srcdir=$dots$given_srcdir ;;
11403 and in fact it is even @emph{more} portable: in the first case of the
11404 first attempt, the computation of @code{top_srcdir} is not portable,
11405 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
11406 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
11407 the same way. There is just no portable way to use double-quoted
11408 strings inside double-quoted back-quoted expressions (pfew!).
11412 @cindex @samp{"$@@"}
11413 One of the most famous shell-portability issues is related to
11414 @samp{"$@@"}. When there are no positional arguments, Posix says
11415 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
11416 original Unix version 7 Bourne shell treated it as equivalent to
11417 @samp{""} instead, and this behavior survives in later implementations
11418 like Digital Unix 5.0.
11420 The traditional way to work around this portability problem is to use
11421 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
11422 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
11423 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
11426 zsh $ @kbd{emulate sh}
11427 zsh $ @kbd{for i in "$@@"; do echo $i; done}
11430 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
11437 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
11438 @samp{"$@@"} because of the portability problems mentioned above.
11439 One workaround relies on Zsh's ``global aliases'' to convert
11440 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
11443 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
11446 A more conservative workaround is to avoid @samp{"$@@"} if it is
11447 possible that there may be no positional arguments. For example,
11451 cat conftest.c "$@@"
11454 you can use this instead:
11458 0) cat conftest.c;;
11459 *) cat conftest.c "$@@";;
11463 Autoconf macros often use the @command{set} command to update
11464 @samp{$@@}, so if you are writing shell code intended for
11465 @command{configure} you should not assume that the value of @samp{$@@}
11466 persists for any length of time.
11470 @cindex positional parameters
11471 The 10th, 11th, @dots{} positional parameters can be accessed only after
11472 a @code{shift}. The 7th Edition shell reported an error if given
11473 @code{$@{10@}}, and
11474 Solaris 10 @command{/bin/sh} still acts that way:
11477 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
11478 $ @kbd{echo $@{10@}}
11482 @item $@{@var{var}:-@var{value}@}
11483 @c Info cannot handle `:' in index entries.
11484 @c @cindex $@{@var{var}:-@var{value}@}
11485 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
11486 colon for any shell substitution, and complain and die.
11488 @item $@{@var{var}=@var{literal}@}
11489 @cindex $@{@var{var}=@var{literal}@}
11493 : $@{var='Some words'@}
11497 otherwise some shells, such as on Digital Unix V 5.0, die because
11498 of a ``bad substitution''.
11502 Solaris @command{/bin/sh} has a frightening bug in its interpretation
11503 of this. Imagine you need set a variable to a string containing
11504 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
11505 when the affected variable was already set. This bug can be exercised
11510 $ @kbd{foo=$@{foo='@}'@}}
11513 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
11516 $ @kbd{foo=$@{foo='@}'@}}
11522 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
11523 though it is enclosed in single quotes. The problem doesn't happen
11524 using double quotes.
11526 @item $@{@var{var}=@var{expanded-value}@}
11527 @cindex $@{@var{var}=@var{expanded-value}@}
11533 : $@{var="$default"@}
11537 sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
11538 each char is set. You don't observe the phenomenon using a simple
11539 @samp{echo $var} since apparently the shell resets the 8th bit when it
11540 expands $var. Here are two means to make this shell confess its sins:
11543 $ @kbd{cat -v <<EOF
11552 $ @kbd{set | grep '^var=' | cat -v}
11555 One classic incarnation of this bug is:
11559 : $@{list="$default"@}
11566 You'll get @samp{a b c} on a single line. Why? Because there are no
11567 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
11568 bit set, hence no IFS splitting is performed!!!
11570 One piece of good news is that Ultrix works fine with @samp{:
11571 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
11572 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
11575 The portable way out consists in using a double assignment, to switch
11576 the 8th bit twice on Ultrix:
11579 list=$@{list="$default"@}
11583 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
11587 test "$@{var+set@}" = set || var=@var{@{value@}}
11591 @item `@var{commands}`
11592 @cindex `@var{commands}`
11593 @cindex Command Substitution
11594 Posix requires shells to trim all trailing newlines from command
11595 output before substituting it, so assignments like
11596 @samp{dir=`echo "$file" | tr a A`} do not work as expected if
11597 @samp{$file} ends in a newline.
11599 While in general it makes no sense, do not substitute a single builtin
11600 with side effects, because Ash 0.2, trying to optimize, does not fork a
11601 subshell to perform the command.
11603 For instance, if you wanted to check that @command{cd} is silent, do not
11604 use @samp{test -z "`cd /`"} because the following can happen:
11609 $ @kbd{test -z "`cd /`" && pwd}
11614 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
11616 The MSYS shell leaves a stray byte in the expansion of a double-quoted
11617 command substitution of a native program, if the end of the substution
11618 is not aligned with the end of the double quote. This may be worked
11619 around by inserting another pair of quotes:
11622 $ @kbd{echo "`printf 'foo\r\n'` bar" > broken}
11623 $ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken}
11624 - broken differ: char 4, line 1
11628 @item $(@var{commands})
11629 @cindex $(@var{commands})
11630 This construct is meant to replace @samp{`@var{commands}`},
11631 and it has most of the problems listed under @code{`@var{commands}`}.
11633 This construct can be
11634 nested while this is impossible to do portably with back quotes.
11635 Unfortunately it is not yet universally supported. Most notably, even recent
11636 releases of Solaris don't support it:
11639 $ @kbd{showrev -c /bin/sh | grep version}
11640 Command version: SunOS 5.10 Generic 121004-01 Oct 2005
11641 $ @kbd{echo $(echo blah)}
11642 syntax error: `(' unexpected
11646 nor does @sc{irix} 6.5's Bourne shell:
11649 IRIX firebird-image 6.5 07151432 IP22
11650 $ @kbd{echo $(echo blah)}
11654 If you do use @samp{$(@var{commands})}, make sure that the commands
11655 do not start with a parenthesis, as that would cause confusion with
11656 a different notation @samp{$((@var{expression}))} that in modern
11657 shells is an arithmetic expression not a command. To avoid the
11658 confusion, insert a space between the two opening parentheses.
11660 Avoid @var{commands} that contain unbalanced parentheses in
11661 here-documents, comments, or case statement patterns, as many shells
11662 mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh}
11663 5.2.14, and Zsh 4.2.6 all mishandle the following valid command:
11666 echo $(case x in x) echo hello;; esac)
11671 Always quote @samp{^}, otherwise traditional shells such as
11672 @command{/bin/sh} on Solaris 10 treat this like @samp{|}.
11678 @section Assignments
11679 @cindex Shell assignments
11681 When setting several variables in a row, be aware that the order of the
11682 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
11683 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
11685 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
11687 Don't rely on the following to find @file{subdir/program}:
11690 PATH=subdir$PATH_SEPARATOR$PATH program
11694 as this does not work with Zsh 3.0.6. Use something like this
11698 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
11701 Don't rely on the exit status of an assignment: Ash 0.2 does not change
11702 the status and propagates that of the last statement:
11705 $ @kbd{false || foo=bar; echo $?}
11707 $ @kbd{false || foo=`:`; echo $?}
11712 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
11716 $ @kbd{foo=`exit 1`; echo $?}
11720 To assign default values, follow this algorithm:
11724 If the default value is a literal and does not contain any closing
11728 : $@{var='my literal'@}
11732 If the default value contains no closing brace, has to be expanded, and
11733 the variable being initialized is not intended to be IFS-split
11734 (i.e., it's not a list), then use:
11737 : $@{var="$default"@}
11741 If the default value contains no closing brace, has to be expanded, and
11742 the variable being initialized is intended to be IFS-split (i.e., it's a list),
11746 var=$@{var="$default"@}
11750 If the default value contains a closing brace, then use:
11753 test "$@{var+set@}" = set || var="has a '@}'"
11757 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
11758 doubt, just use the last form. @xref{Shell Substitutions}, items
11759 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
11763 @section Parentheses in Shell Scripts
11764 @cindex Shell parentheses
11766 Beware of two opening parentheses in a row, as some shell
11767 implementations mishandle them. For example, @samp{pdksh} 5.2.14
11768 misparses the following code:
11771 if ((true) || false); then
11777 To work around this problem, insert a space between the two opening
11778 parentheses. There is a similar problem and workaround with
11779 @samp{$((}; see @ref{Shell Substitutions}.
11781 Posix requires support for @code{case} patterns with opening
11782 parentheses like this:
11786 (*.c) echo "C source code";;
11791 but the @code{(} in this example is not portable to many older Bourne
11792 shell implementations. It can be omitted safely.
11795 @section Slashes in Shell Scripts
11796 @cindex Shell slashes
11798 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
11799 arguments that contain two trailing slashes:
11802 $ @kbd{echo / // /// //// .// //.}
11805 $ @kbd{eval "echo \$x"}
11808 $ @kbd{echo abc | tr -t ab //}
11814 However, our understanding is that patches are available, so perhaps
11815 it's not worth worrying about working around this horrendous bug.
11817 @node Special Shell Variables
11818 @section Special Shell Variables
11819 @cindex Shell variables
11820 @cindex Special shell variables
11822 Some shell variables should not be used, since they can have a deep
11823 influence on the behavior of the shell. In order to recover a sane
11824 behavior from the shell, some variables should be unset, but
11825 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
11826 fallback value is needed.
11828 As a general rule, shell variable names containing a lower-case letter
11829 are safe; you can define and use these variables without worrying about
11830 their effect on the underlying system, and without worrying about
11831 whether the shell changes them unexpectedly. (The exception is the
11832 shell variable @code{status}, as described below.)
11834 Here is a list of names that are known to cause trouble. This list is
11835 not exhaustive, but you should be safe if you avoid the name
11836 @code{status} and names containing only upper-case letters and
11839 @c Alphabetical order, case insensitive, `A' before `a'.
11842 Many shells reserve @samp{$_} for various purposes, e.g., the name of
11843 the last command executed.
11847 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
11848 the standard shell conform to Posix.
11849 Autoconf-generated scripts export this variable when they start up.
11853 When this variable is set it specifies a list of directories to search
11854 when invoking @code{cd} with a relative file name that did not start
11855 with @samp{./} or @samp{../}. Posix
11856 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
11857 is used successfully, @code{cd} prints the resulting absolute
11858 file name. Unfortunately this output can break idioms like
11859 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
11860 Also, many shells do not conform to this part of Posix; for
11861 example, @command{zsh} prints the result only if a directory name
11862 other than @file{.} was chosen from @env{CDPATH}.
11864 In practice the shells that have this problem also support
11865 @command{unset}, so you can work around the problem as follows:
11868 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
11871 You can also avoid output by ensuring that your directory name is
11872 absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}.
11874 Autoconf-generated scripts automatically unset @env{CDPATH} if
11875 possible, so you need not worry about this problem in those scripts.
11879 In the MKS shell, case statements and file name generation are
11880 case-insensitive unless @env{DUALCASE} is nonzero.
11881 Autoconf-generated scripts export this variable when they start up.
11895 These variables should not matter for shell scripts, since they are
11896 supposed to affect only interactive shells. However, at least one
11897 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
11898 whether it is interactive, which means that (for example) a @env{PS1}
11899 with a side effect can unexpectedly modify @samp{$?}. To work around
11900 this bug, Autoconf-generated scripts do something like this:
11903 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
11911 Long ago, shell scripts inherited @env{IFS} from the environment,
11912 but this caused many problems so modern shells ignore any environment
11913 settings for @env{IFS}.
11915 Don't set the first character of @code{IFS} to backslash. Indeed,
11916 Bourne shells use the first character (backslash) when joining the
11917 components in @samp{"$@@"} and some shells then reinterpret (!)@: the
11918 backslash escapes, so you can end up with backspace and other strange
11921 The proper value for @code{IFS} (in regular code, not when performing
11922 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
11923 especially important, as it is used to join the arguments in @samp{$*};
11924 however, note that traditional shells, but also bash-2.04, fail to adhere
11925 to this and join with a space anyway.
11937 @evindex LC_COLLATE
11939 @evindex LC_MESSAGES
11940 @evindex LC_MONETARY
11941 @evindex LC_NUMERIC
11944 Autoconf-generated scripts normally set all these variables to
11945 @samp{C} because so much configuration code assumes the C locale and
11946 Posix requires that locale environment variables be set to
11947 @samp{C} if the C locale is desired. However, some older, nonstandard
11948 systems (notably @acronym{SCO}) break if locale environment variables
11949 are set to @samp{C}, so when running on these systems
11950 Autoconf-generated scripts unset the variables instead.
11955 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
11956 extension that overrides @env{LC_ALL} in some cases, so
11957 Autoconf-generated scripts set it too.
11960 @itemx LC_IDENTIFICATION
11961 @itemx LC_MEASUREMENT
11964 @itemx LC_TELEPHONE
11965 @evindex LC_ADDRESS
11966 @evindex LC_IDENTIFICATION
11967 @evindex LC_MEASUREMENT
11970 @evindex LC_TELEPHONE
11972 These locale environment variables are @acronym{GNU} extensions. They
11973 are treated like their Posix brethren (@env{LC_COLLATE},
11974 etc.)@: as described above.
11977 Most modern shells provide the current line number in @code{LINENO}.
11978 Its value is the line number of the beginning of the current command.
11979 Autoconf attempts to execute @command{configure} with a shell that
11980 supports @code{LINENO}.
11981 If no such shell is available, it attempts to implement @code{LINENO}
11982 with a Sed prepass that replaces each instance of the string
11983 @code{$LINENO} (not followed by an alphanumeric character) with the
11986 You should not rely on @code{LINENO} within @command{eval}, as the
11987 behavior differs in practice. Also, the possibility of the Sed
11988 prepass means that you should not rely on @code{$LINENO} when quoted,
11989 when in here-documents, or when in long commands that cross line
11990 boundaries. Subshells should be OK, though. In the following
11991 example, lines 1, 6, and 9 are portable, but the other instances of
11992 @code{LINENO} are not:
12002 ( echo 6. $LINENO )
12003 eval 'echo 7. $LINENO'
12009 $ @kbd{bash-2.05 lineno}
12020 $ @kbd{zsh-3.0.6 lineno}
12031 $ @kbd{pdksh-5.2.14 lineno}
12042 $ @kbd{sed '=' <lineno |}
12048 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
12051 > @kbd{ s,^[0-9]*\n,,}
12067 When executing the command @samp{>foo}, @command{zsh} executes
12068 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
12069 compatibility mode and the @command{zsh} version is newer
12070 than 3.1.6-dev-18. If you are using an older @command{zsh}
12071 and forget to set @env{NULLCMD},
12072 your script might be suspended waiting for data on its standard input.
12074 @item PATH_SEPARATOR
12075 @evindex PATH_SEPARATOR
12076 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
12077 variable can be set to either @samp{:} or @samp{;} to control the path
12078 separator Bash uses to set up certain environment variables (such as
12079 @env{PATH}). You can set this variable to @samp{;} if you want
12080 @command{configure} to use @samp{;} as a separator; this might be useful
12081 if you plan to use non-Posix shells to execute files. @xref{File System
12082 Conventions}, for more information about @code{PATH_SEPARATOR}.
12086 Posix 1003.1-2001 requires that @command{cd} and
12087 @command{pwd} must update the @env{PWD} environment variable to point
12088 to the logical name of the current directory, but traditional shells
12089 do not support this. This can cause confusion if one shell instance
12090 maintains @env{PWD} but a subsidiary and different shell does not know
12091 about @env{PWD} and executes @command{cd}; in this case @env{PWD}
12092 points to the wrong directory. Use @samp{`pwd`} rather than
12096 Many shells provide @code{RANDOM}, a variable that returns a different
12097 integer each time it is used. Most of the time, its value does not
12098 change when it is not used, but on @sc{irix} 6.5 the value changes all
12099 the time. This can be observed by using @command{set}. It is common
12100 practice to use @code{$RANDOM} as part of a file name, but code
12101 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
12104 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
12105 hence read-only. Do not use it.
12108 @node Limitations of Builtins
12109 @section Limitations of Shell Builtins
12110 @cindex Shell builtins
12111 @cindex Limitations of shell builtins
12113 No, no, we are serious: some shells do have limitations! :)
12115 You should always keep in mind that any builtin or command may support
12116 options, and therefore differ in behavior with arguments
12117 starting with a dash. For instance, the innocent @samp{echo "$word"}
12118 can give unexpected results when @code{word} starts with a dash. It is
12119 often possible to avoid this problem using @samp{echo "x$word"}, taking
12120 the @samp{x} into account later in the pipe.
12124 @prindex @command{.}
12125 Use @command{.} only with regular files (use @samp{test -f}). Bash
12126 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
12127 @command{.} uses @env{PATH} if its argument contains no slashes, so if
12128 you want to use @command{.} on a file @file{foo} in the current
12129 directory, you must use @samp{. ./foo}.
12132 @prindex @command{!}
12133 The Unix version 7 shell did not support
12134 negating the exit status of commands with @command{!}, and this feature
12135 is still absent from some shells (e.g., Solaris @command{/bin/sh}).
12136 Shell code like this:
12139 if ! cmp file1 file2 >/dev/null 2>&1; then
12140 echo files differ or trouble
12144 is therefore not portable in practice. Typically it is easy to rewrite
12148 cmp file1 file2 >/dev/null 2>&1 ||
12149 echo files differ or trouble
12152 More generally, one can always rewrite @samp{! @var{command}} as:
12155 if @var{command}; then (exit 1); else :; fi
12158 @item @command{break}
12159 @c ------------------
12160 @prindex @command{break}
12161 The use of @samp{break 2} etc.@: is safe.
12164 @item @command{case}
12165 @c -----------------
12166 @prindex @command{case}
12167 You don't need to quote the argument; no splitting is performed.
12169 You don't need the final @samp{;;}, but you should use it.
12171 Because of a bug in its @code{fnmatch}, Bash fails to properly
12172 handle backslashes in character classes:
12175 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
12180 This is extremely unfortunate, since you are likely to use this code to
12181 handle Posix or @sc{ms-dos} absolute file names. To work around this
12182 bug, always put the backslash first:
12185 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
12187 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
12191 Many Bourne shells cannot handle closing brackets in character classes
12194 Some shells also have problems with backslash escaping in case you do not want
12195 to match the backslash: both a backslash and the escaped character match this
12196 pattern. To work around this, specify the character class in a variable, so
12197 that quote removal does not apply afterwards, and the special characters don't
12198 have to be backslash-escaped:
12201 $ @kbd{case '\' in [\<]) echo OK;; esac}
12203 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
12207 Even with this, Solaris @command{ksh} matches a backslash if the set
12209 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
12211 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
12212 a closing parenthesis if not specified in a character class:
12215 $ @kbd{case foo in *\)*) echo fail ;; esac}
12217 $ @kbd{case foo in *')'*) echo fail ;; esac}
12221 Some shells, such as Ash 0.3.8, are confused by an empty
12222 @code{case}/@code{esac}:
12225 ash-0.3.8 $ @kbd{case foo in esac;}
12226 @error{}Syntax error: ";" unexpected (expecting ")")
12229 Many shells still do not support parenthesized cases, which is a pity
12230 for those of us using tools that rely on balanced parentheses. For
12231 instance, Solaris @command{/bin/sh}:
12234 $ @kbd{case foo in (foo) echo foo;; esac}
12235 @error{}syntax error: `(' unexpected
12241 @prindex @command{cd}
12242 Posix 1003.1-2001 requires that @command{cd} must support
12243 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12244 with @option{-L} being the default. However, traditional shells do
12245 not support these options, and their @command{cd} command has the
12246 @option{-P} behavior.
12248 Portable scripts should assume neither option is supported, and should
12249 assume neither behavior is the default. This can be a bit tricky,
12250 since the Posix default behavior means that, for example,
12251 @samp{ls ..} and @samp{cd ..} may refer to different directories if
12252 the current logical directory is a symbolic link. It is safe to use
12253 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
12254 Also, Autoconf-generated scripts check for this problem when computing
12255 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
12256 so it is safe to @command{cd} to these variables.
12258 See @xref{Special Shell Variables}, for portability problems involving
12259 @command{cd} and the @env{CDPATH} environment variable.
12260 Also please see the discussion of the @command{pwd} command.
12263 @item @command{echo}
12264 @c -----------------
12265 @prindex @command{echo}
12266 The simple @command{echo} is probably the most surprising source of
12267 portability troubles. It is not possible to use @samp{echo} portably
12268 unless both options and escape sequences are omitted. New applications
12269 which are not aiming at portability should use @samp{printf} instead of
12272 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
12273 etc.@: for a means to simulate @option{-n}.
12275 Do not use backslashes in the arguments, as there is no consensus on
12276 their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of
12277 Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1.
12278 The problem is truly @command{echo}: all the shells
12279 understand @samp{'\n'} as the string composed of a backslash and an
12282 Because of these problems, do not pass a string containing arbitrary
12283 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
12284 if you know that @var{foo}'s value cannot contain backslashes and cannot
12285 start with @samp{-}, but otherwise you should use a here-document like
12295 @item @command{eval}
12296 @c -----------------
12297 @prindex @command{eval}
12298 The @command{eval} command is useful in limited circumstances, e.g.,
12299 using commands like @samp{eval table_$key=\$value} and @samp{eval
12300 value=table_$key} to simulate a hash table when the key is known to be
12301 alphanumeric. However, @command{eval} is tricky to use on arbitrary
12302 arguments, even when it is implemented correctly.
12304 It is obviously unwise to use @samp{eval $cmd} if the string value of
12305 @samp{cmd} was derived from an untrustworthy source. But even if the
12306 string value is valid, @samp{eval $cmd} might not work as intended,
12307 since it causes field splitting and file name expansion to occur twice,
12308 once for the @command{eval} and once for the command itself. It is
12309 therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd}
12310 has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the
12311 equivalent of @samp{cat test;.c} if there happens to be a file named
12312 @file{test;.c} in the current directory; and this in turn
12313 mistakenly attempts to invoke @command{cat} on the file @file{test} and
12314 then execute the command @command{.c}. To avoid this problem, use
12315 @samp{eval "$cmd"} rather than @samp{eval $cmd}.
12317 However, suppose that you want to output the text of the evaluated
12318 command just before executing it. Assuming the previous example,
12319 @samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but
12320 this output doesn't show the user that @samp{test;.c} is the actual name
12321 of the copied file. Conversely, @samp{eval "echo Executing: $cmd"}
12322 works on this example, but it fails with @samp{cmd='cat foo >bar'},
12323 since it mistakenly replaces the contents of @file{bar} by the
12324 string @samp{cat foo}. No simple, general, and portable solution to
12325 this problem is known.
12327 You should also be wary of common bugs in @command{eval} implementations.
12328 In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8
12329 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
12330 4.2.5), the arguments of @samp{eval} are evaluated in a context where
12331 @samp{$?} is 0, so they exhibit behavior like this:
12334 $ @kbd{false; eval 'echo $?'}
12338 The correct behavior here is to output a nonzero value,
12339 but portable scripts should not rely on this.
12341 You should not rely on @code{LINENO} within @command{eval}.
12342 @xref{Special Shell Variables}.
12344 @item @command{exit}
12345 @c -----------------
12346 @prindex @command{exit}
12347 The default value of @command{exit} is supposed to be @code{$?};
12348 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
12349 perform @samp{exit 0}.
12352 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
12354 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
12356 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
12360 Using @samp{exit $?} restores the expected behavior.
12362 Some shell scripts, such as those generated by @command{autoconf}, use a
12363 trap to clean up before exiting. If the last shell command exited with
12364 nonzero status, the trap also exits with nonzero status so that the
12365 invoker can tell that an error occurred.
12367 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
12368 trap ignores the @code{exit} command's argument. In these shells, a trap
12369 cannot determine whether it was invoked by plain @code{exit} or by
12370 @code{exit 1}. Instead of calling @code{exit} directly, use the
12371 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
12374 @item @command{export}
12375 @c -------------------
12376 @prindex @command{export}
12377 The builtin @command{export} dubs a shell variable @dfn{environment
12378 variable}. Each update of exported variables corresponds to an update
12379 of the environment variables. Conversely, each environment variable
12380 received by the shell when it is launched should be imported as a shell
12381 variable marked as exported.
12383 Alas, many shells, such as Solaris @command{/bin/sh},
12384 @sc{irix} 6.3, @sc{irix} 5.2,
12385 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
12386 @command{export} the environment variables they receive. As a result,
12387 two variables coexist: the environment variable and the shell
12388 variable. The following code demonstrates this failure:
12399 when run with @samp{FOO=foo} in the environment, these shells print
12400 alternately @samp{foo} and @samp{bar}, although they should print only
12401 @samp{foo} and then a sequence of @samp{bar}s.
12403 Therefore you should @command{export} again each environment variable
12407 @item @command{false}
12408 @c ------------------
12409 @prindex @command{false}
12410 Don't expect @command{false} to exit with status 1: in native
12411 Solaris @file{/bin/false} exits with status 255.
12414 @item @command{for}
12415 @c ----------------
12416 @prindex @command{for}
12417 To loop over positional arguments, use:
12427 You may @emph{not} leave the @code{do} on the same line as @code{for},
12428 since some shells improperly grok:
12436 If you want to explicitly refer to the positional arguments, given the
12437 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
12440 for arg in $@{1+"$@@"@}; do
12446 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
12447 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
12448 item @samp{$@@}, for more.
12453 @prindex @command{if}
12454 Using @samp{!} is not portable. Instead of:
12457 if ! cmp -s file file.new; then
12466 if cmp -s file file.new; then :; else
12471 There are shells that do not reset the exit status from an @command{if}:
12474 $ @kbd{if (exit 42); then true; fi; echo $?}
12479 whereas a proper shell should have printed @samp{0}. This is especially
12480 bad in makefiles since it produces false failures. This is why properly
12481 written makefiles, such as Automake's, have such hairy constructs:
12484 if test -f "$file"; then
12485 install "$file" "$dest"
12492 @item @command{printf}
12493 @c ------------------
12494 @prindex @command{printf}
12495 A format string starting with a @samp{-} can cause problems.
12496 Bash (e.g., 2.05b) interprets it as an options argument and
12497 gives an error. And @samp{--} to mark the end of options is not good
12498 in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that
12499 literally as the format string. Putting the @samp{-} in a @samp{%c}
12500 or @samp{%s} is probably the easiest way to avoid doubt,
12507 @item @command{read}
12508 @c ------------------
12509 @prindex @command{read}
12510 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
12513 @item @command{pwd}
12514 @c ----------------
12515 @prindex @command{pwd}
12516 With modern shells, plain @command{pwd} outputs a ``logical''
12517 directory name, some of whose components may be symbolic links. These
12518 directory names are in contrast to ``physical'' directory names, whose
12519 components are all directories.
12521 Posix 1003.1-2001 requires that @command{pwd} must support
12522 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
12523 with @option{-L} being the default. However, traditional shells do
12524 not support these options, and their @command{pwd} command has the
12525 @option{-P} behavior.
12527 Portable scripts should assume neither option is supported, and should
12528 assume neither behavior is the default. Also, on many hosts
12529 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
12530 does not require this behavior and portable scripts should not rely on
12533 Typically it's best to use plain @command{pwd}. On modern hosts this
12534 outputs logical directory names, which have the following advantages:
12538 Logical names are what the user specified.
12540 Physical names may not be portable from one installation
12541 host to another due to network file system gymnastics.
12543 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
12544 some parent directory, but plain @command{pwd} cannot fail for this
12548 Also please see the discussion of the @command{cd} command.
12551 @item @command{set}
12552 @c ----------------
12553 @prindex @command{set}
12554 With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without
12555 any options) does not sort its output.
12557 The @command{set} builtin faces the usual problem with arguments starting with a
12558 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
12559 the end of the options (any argument after @option{--} is a parameter,
12560 even @samp{-x} for instance), but many traditional shells (e.g., Solaris
12561 10 @command{/bin/sh}) simply stop option
12562 processing as soon as a non-option argument is found. Therefore, use
12563 @samp{dummy} or simply @samp{x} to end the option processing, and use
12564 @command{shift} to pop it out:
12567 set x $my_list; shift
12570 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
12571 longer requires support for this command, and in traditional shells
12572 @samp{set - $my_list} resets the @option{-v} and @option{-x} options, which
12573 makes scripts harder to debug.
12575 Some nonstandard shells do not recognize more than one option
12576 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
12577 better to combine them:
12583 The @acronym{BSD} shell has had several problems with the @option{-e}
12584 option, partly because @acronym{BSD} @command{make} traditionally used
12585 @option{-e} even though this was incompatible with Posix
12586 (@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD}
12587 shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and
12588 @samp{case} when @option{-e} was in effect, causing the shell to exit
12589 unexpectedly in some cases. This was particularly a problem with
12590 makefiles, and led to circumlocutions like @samp{sh -c 'test -f file ||
12591 touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'}
12592 wrapper works around the bug.
12594 Even relatively-recent versions of the @acronym{BSD} shell (e.g.,
12595 Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within
12596 @samp{&&} fails inside a compound statement. For example:
12602 test -n "$foo" && exit 1
12605 test -n "$foo" && exit 1
12611 does not print @samp{two}. One workaround is to use @samp{if test -n
12612 "$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}.
12613 Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}.
12616 @item @command{shift}
12617 @c ------------------
12618 @prindex @command{shift}
12619 Not only is @command{shift}ing a bad idea when there is nothing left to
12620 shift, but in addition it is not portable: the shell of @acronym{MIPS
12621 RISC/OS} 4.52 refuses to do it.
12623 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
12624 and it is also absent in many pre-Posix shells.
12627 @item @command{source}
12628 @c -------------------
12629 @prindex @command{source}
12630 This command is not portable, as Posix does not require it; use
12631 @command{.} instead.
12634 @item @command{test}
12635 @c -----------------
12636 @prindex @command{test}
12637 The @code{test} program is the way to perform many file and string
12638 tests. It is often invoked by the alternate name @samp{[}, but using
12639 that name in Autoconf code is asking for trouble since it is an M4 quote
12642 If you need to make multiple checks using @code{test}, combine them with
12643 the shell operators @samp{&&} and @samp{||} instead of using the
12644 @code{test} operators @option{-a} and @option{-o}. On System V, the
12645 precedence of @option{-a} and @option{-o} is wrong relative to the unary
12646 operators; consequently, Posix does not specify them, so using them
12647 is nonportable. If you combine @samp{&&} and @samp{||} in the same
12648 statement, keep in mind that they have equal precedence.
12650 It is safe to use @samp{!} as a @command{test} operator. For example,
12651 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
12652 -d foo; @dots{}} is not.
12655 @item @command{test} (files)
12656 @c -------------------------
12657 To enable @command{configure} scripts to support cross-compilation, they
12658 shouldn't do anything that tests features of the build system instead of
12659 the host system. But occasionally you may find it necessary to check
12660 whether some arbitrary file exists. To do so, use @samp{test -f} or
12661 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
12662 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
12663 lacks it. To test for symbolic links on systems that have them, use
12664 @samp{test -h} rather than @samp{test -L}; either form conforms to
12665 Posix 1003.1-2001, but older shells like Solaris 8
12666 @code{/bin/sh} support only @option{-h}.
12668 @item @command{test} (strings)
12669 @c ---------------------------
12670 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
12671 start with a dash, since @code{test} might interpret its argument as an
12672 option (e.g., @samp{@var{string} = "-n"}).
12674 Contrary to a common belief, @samp{test -n @var{string}} and
12675 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
12676 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
12677 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
12678 @var{string} looks like an operator:
12682 test: argument expected
12685 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
12686 "x@var{string}" != x} instead.
12688 It is common to find variations of the following idiom:
12691 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
12696 to take an action when a token matches a given pattern. Such constructs
12697 should always be avoided by using:
12700 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
12705 Use @code{case} where possible since it is faster, being a shell builtin:
12709 case $ac_feature in
12710 *[!-a-zA-Z0-9_]*) @var{action};;
12714 Alas, negated character classes are probably not portable, although no
12715 shell is known to not support the Posix syntax @samp{[!@dots{}]}
12716 (when in interactive mode, @command{zsh} is confused by the
12717 @samp{[!@dots{}]} syntax and looks for an event in its history because of
12718 @samp{!}). Many shells do not support the alternative syntax
12719 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
12721 One solution can be:
12724 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12732 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
12736 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
12737 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
12738 @samp{@var{foo}} contains backslashes.
12741 @item @command{trap}
12742 @c -----------------
12743 @prindex @command{trap}
12744 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
12745 trap 0, i.e., have the @command{trap} run when the script ends (either via an
12746 explicit @command{exit}, or the end of the script).
12748 Posix says that @samp{trap - 1 2 13 15} resets the traps for the
12749 specified signals to their default values, but many common shells (e.g.,
12750 Solaris @command{/bin/sh}) misinterpret this and attempt to execute a
12751 ``command'' named @command{-} when the specified conditions arise.
12752 There is no portable workaround, except for @samp{trap - 0}, for which
12753 @samp{trap '' 0} is a portable substitute.
12755 Although Posix is not absolutely clear on this point, it is widely
12756 admitted that when entering the trap @samp{$?} should be set to the exit
12757 status of the last command run before the trap. The ambiguity can be
12758 summarized as: ``when the trap is launched by an @command{exit}, what is
12759 the @emph{last} command run: that before @command{exit}, or
12760 @command{exit} itself?''
12762 Bash considers @command{exit} to be the last command, while Zsh and
12763 Solaris @command{/bin/sh} consider that when the trap is run it is
12764 @emph{still} in the @command{exit}, hence it is the previous exit status
12765 that the trap receives:
12768 $ @kbd{cat trap.sh}
12771 $ @kbd{zsh trap.sh}
12773 $ @kbd{bash trap.sh}
12777 The portable solution is then simple: when you want to @samp{exit 42},
12778 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
12779 set the exit status to 42 for Zsh, and the second to trigger the trap
12780 and pass 42 as exit status for Bash.
12782 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
12783 reset to 0 by empty lines if the code is inside @command{trap}.
12786 $ @kbd{trap 'false}
12794 Fortunately, this bug only affects @command{trap}.
12796 @item @command{true}
12797 @c -----------------
12798 @prindex @command{true}
12799 @c Info cannot handle `:' in index entries.
12800 @c @prindex @command{:}
12801 Don't worry: as far as we know @command{true} is portable.
12802 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
12803 portable shell community tends to prefer using @command{:}. This has a
12804 funny side effect: when asked whether @command{false} is more portable
12805 than @command{true} Alexandre Oliva answered:
12808 In a sense, yes, because if it doesn't exist, the shell will produce an
12809 exit status of failure, which is correct for @command{false}, but not
12810 for @command{true}.
12814 @item @command{unset}
12815 @c ------------------
12816 @prindex @command{unset}
12817 You cannot assume the support of @command{unset}. Nevertheless, because
12818 it is extremely useful to disable embarrassing variables such as
12819 @code{PS1}, you can test for its existence and use
12820 it @emph{provided} you give a neutralizing value when @command{unset} is
12824 if (unset FOO) >/dev/null 2>&1; then
12829 $unset PS1 || PS1='$ '
12832 @xref{Special Shell Variables}, for some neutralizing values. Also, see
12833 @ref{Limitations of Builtins}, documentation of @command{export}, for
12834 the case of environment variables.
12837 @node Limitations of Usual Tools
12838 @section Limitations of Usual Tools
12839 @cindex Limitations of usual tools
12841 The small set of tools you can expect to find on any machine can still
12842 include some limitations you should be aware of.
12848 Don't leave white space before the opening parenthesis in a user function call.
12849 Posix does not allow this and @acronym{GNU} Awk rejects it:
12852 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12853 BEGIN @{ die () @}'}
12854 gawk: cmd. line:2: BEGIN @{ die () @}
12855 gawk: cmd. line:2: ^ parse error
12856 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
12857 BEGIN @{ die() @}'}
12861 If you want your program to be deterministic, don't depend on @code{for}
12865 $ @kbd{cat for.awk}
12872 $ @kbd{gawk -f for.awk </dev/null}
12875 $ @kbd{nawk -f for.awk </dev/null}
12880 Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors:
12883 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
12884 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
12886 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
12888 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
12893 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
12894 or use a simple test to reject such implementations.
12896 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the
12897 length of regular expressions and literal strings in an Awk program.
12899 Traditional Awk implementations derived from Unix version 7, such as
12900 Solaris @command{/bin/awk}, have many limitations and do not
12901 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
12902 Programs}) finds you an Awk that doesn't have these problems, but if
12903 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
12906 Traditional Awk does not support multidimensional arrays or user-defined
12909 Traditional Awk does not support the @option{-v} option. You can use
12910 assignments after the program instead, e.g., @command{$AWK '@{print v
12911 $1@}' v=x}; however, don't forget that such assignments are not
12912 evaluated until they are encountered (e.g., after any @code{BEGIN}
12915 Traditional Awk does not support the keywords @code{delete} or @code{do}.
12917 Traditional Awk does not support the expressions
12918 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
12919 or @code{@var{a}^=@var{b}}.
12921 Traditional Awk does not support the predefined @code{CONVFMT} variable.
12923 Traditional Awk supports only the predefined functions @code{exp},
12924 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
12925 @code{sqrt}, and @code{substr}.
12927 Traditional Awk @code{getline} is not at all compatible with Posix;
12930 Traditional Awk @code{split} supports only two arguments.
12932 Traditional Awk has a limit of 99
12933 fields in a record. You may be able to circumvent this problem by using
12937 @item @command{basename}
12938 @c ---------------------
12939 @prindex @command{basename}
12940 Not all hosts have a working @command{basename}.
12941 You can use @command{expr} instead.
12943 @c AS_BASENAME is to be replaced by a better API.
12945 Not all hosts have a working @command{basename}, and you should instead
12946 use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by
12947 @command{expr} if you need to strip a suffix. For example:
12950 a=`basename "$aname"` # This is not portable.
12951 a=`AS_BASENAME(["$aname"])` # This is more portable.
12953 # This is not portable.
12954 c=`basename "$cname" .c`
12956 # This is more portable.
12957 c=`AS_BASENAME(["$cname"])`
12959 ?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;;
12965 @item @command{cat}
12966 @c ----------------
12967 @prindex @command{cat}
12968 Don't rely on any option.
12973 @prindex @command{cc}
12974 The command @samp{cc -c foo.c} traditionally produces an object file
12975 named @file{foo.o}. Most compilers allow @option{-c} to be combined
12976 with @option{-o} to specify a different object file name, but
12977 Posix does not require this combination and a few compilers
12978 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
12979 tests for this feature with @code{AC_PROG_CC_C_O}.
12981 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
12982 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
12984 @acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and
12985 assemble. @samp{cc -c foo.S} appears to succeed, but in fact does
12988 The default executable, produced by @samp{cc foo.c}, can be
12991 @item @file{a.out} --- usual Posix convention.
12992 @item @file{b.out} --- i960 compilers (including @command{gcc}).
12993 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
12994 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
12995 @item @file{foo.exe} --- various MS-DOS compilers.
12998 The C compiler's traditional name is @command{cc}, but other names like
12999 @command{gcc} are common. Posix 1003.1-2001 specifies the
13000 name @command{c99}, but older Posix editions specified
13001 @command{c89} and anyway these standard names are rarely used in
13002 practice. Typically the C compiler is invoked from makefiles that use
13003 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
13007 @item @command{chmod}
13008 @c ------------------
13009 @prindex @command{chmod}
13010 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
13011 instead, for two reasons. First, plain @option{-w} does not necessarily
13012 make the file unwritable, since it does not affect mode bits that
13013 correspond to bits in the file mode creation mask. Second,
13014 Posix says that the @option{-w} might be interpreted as an
13015 implementation-specific option, not as a mode; Posix suggests
13016 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
13017 @samp{--} does not work on some older hosts.
13020 @item @command{cmp}
13021 @c ----------------
13022 @prindex @command{cmp}
13023 @command{cmp} performs a raw data comparison of two files, while
13024 @command{diff} compares two text files. Therefore, if you might compare
13025 DOS files, even if only checking whether two files are different, use
13026 @command{diff} to avoid spurious differences due to differences of
13032 @prindex @command{cp}
13033 Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as
13034 obsolescent and its behavior on special files is implementation-defined.
13035 Use @option{-R} instead. On @acronym{GNU} hosts the two options
13036 are equivalent, but on Solaris hosts (for example) @command{cp -r}
13037 reads from pipes instead of replicating them.
13039 Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow
13040 trailing slashes at the end of nonexistent destination directories. To
13041 avoid this problem, omit the trailing slashes. For example, use
13042 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
13043 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
13045 @c This is thanks to Ian.
13046 The ancient SunOS 4 @command{cp} does not support @option{-f}, although
13047 its @command{mv} does.
13049 @cindex timestamp resolution
13050 Traditionally, file timestamps had 1-second resolution, and @samp{cp
13051 -p} copied the timestamps exactly. However, many modern file systems
13052 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
13053 -p} implementations truncate timestamps when copying files, so this
13054 can result in the destination file appearing to be older than the
13055 source. The exact amount of truncation depends on the resolution of
13056 the system calls that @command{cp} uses; traditionally this was
13057 @code{utime}, which has 1-second resolution, but some newer
13058 @command{cp} implementations use @code{utimes}, which has
13059 1-microsecond resolution. These newer implementations include @acronym{GNU}
13060 Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
13061 later. Unfortunately as of January 2006 there is still no system
13062 call to set timestamps to the full nanosecond resolution.
13064 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
13065 ownerships. But whether it actually does copy ownerships or not is a
13066 system dependent policy decision implemented by the kernel. If the
13067 kernel allows it then it happens. If the kernel does not allow it then
13068 it does not happen. It is not something @command{cp} itself has control
13071 In Unix System V any user can chown files to any other user, and System
13072 V also has a non-sticky @file{/tmp}. That probably derives from the
13073 heritage of System V in a business environment without hostile users.
13074 @acronym{BSD} changed this
13075 to be a more secure model where only root can @command{chown} files and
13076 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
13077 of @acronym{BSD} in a campus environment.
13079 @acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but
13080 can be configured to allow a System V style @command{chown}. On the
13081 other hand, @acronym{HP-UX} follows System V, but can
13082 be configured to use the modern security model and disallow
13083 @command{chown}. Since it is an administrator-configurable parameter
13084 you can't use the name of the kernel as an indicator of the behavior.
13088 @item @command{date}
13089 @c -----------------
13090 @prindex @command{date}
13091 Some versions of @command{date} do not recognize special @samp{%} directives,
13092 and unfortunately, instead of complaining, they just pass them through,
13093 and exit with success:
13097 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
13103 @item @command{diff}
13104 @c -----------------
13105 @prindex @command{diff}
13106 Option @option{-u} is nonportable.
13108 Some implementations, such as Tru64's, fail when comparing to
13109 @file{/dev/null}. Use an empty file instead.
13112 @item @command{dirname}
13113 @c --------------------
13114 @prindex @command{dirname}
13115 Not all hosts have a working @command{dirname}, and you should instead
13116 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
13119 dir=`dirname "$file"` # This is not portable.
13120 dir=`AS_DIRNAME(["$file"])` # This is more portable.
13124 @item @command{egrep}
13125 @c ------------------
13126 @prindex @command{egrep}
13127 Posix 1003.1-2001 no longer requires @command{egrep},
13128 but many older hosts do not yet support the Posix
13129 replacement @code{grep -E}. Also, some traditional implementations do
13130 not work on long input lines. To work around these problems, invoke
13131 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
13133 Portable extended regular expressions should use @samp{\} only to escape
13134 characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}}
13135 is not portable, even though it typically matches @samp{@}}.
13137 The empty alternative is not portable. Use @samp{?} instead. For
13138 instance with Digital Unix v5.0:
13141 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
13143 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
13145 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
13150 @command{$EGREP} also suffers the limitations of @command{grep}.
13152 @item @command{expr}
13153 @c -----------------
13154 @prindex @command{expr}
13155 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
13156 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
13157 misinterpreting @var{word}.
13159 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
13161 @item @command{expr} (@samp{|})
13162 @prindex @command{expr} (@samp{|})
13163 You can use @samp{|}. Although Posix does require that @samp{expr
13164 ''} return the empty string, it does not specify the result when you
13165 @samp{|} together the empty string (or zero) with the empty string. For
13172 Posix 1003.2-1992 returns the empty string
13173 for this case, but traditional Unix returns @samp{0} (Solaris is
13174 one such example). In Posix 1003.1-2001, the specification was
13175 changed to match traditional Unix's behavior (which is
13176 bizarre, but it's too late to fix this). Please note that the same
13177 problem does arise when the empty string results from a computation,
13181 expr bar : foo \| foo : bar
13185 Avoid this portability problem by avoiding the empty string.
13188 @item @command{expr} (@samp{:})
13189 @c ----------------------------
13190 @prindex @command{expr}
13191 Portable @command{expr} regular expressions should use @samp{\} to
13192 escape only characters in the string @samp{$()*.0123456789[\^n@{@}}.
13193 For example, alternation, @samp{\|}, is common but Posix does not
13194 require its support, so it should be avoided in portable scripts.
13195 Similarly, @samp{\+} and @samp{\?} should be avoided.
13197 Portable @command{expr} regular expressions should not begin with
13198 @samp{^}. Patterns are automatically anchored so leading @samp{^} is
13201 The Posix standard is ambiguous as to whether
13202 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
13203 In practice, it outputs the empty string on most platforms, but portable
13204 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
13205 @command{expr} returns @samp{0}.
13207 One might think that a way to get a uniform behavior would be to use
13208 the empty string as a default value:
13211 expr a : '\(b\)' \| ''
13215 Unfortunately this behaves exactly as the original expression; see the
13216 @command{expr} (@samp{|}) entry for more information.
13218 Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and
13219 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
13220 @command{expr} to fail if the matched substring is longer than 120
13221 bytes. In this case, you might want to fall back on @samp{echo|sed} if
13222 @command{expr} fails. Nowadays this is of practical importance only for
13223 the rare installer who mistakenly puts @file{/usr/ucb} before
13224 @file{/usr/bin} in @env{PATH}.
13226 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
13227 some cases. For example, the command
13229 expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'
13233 outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
13234 This particular case can be worked around by substituting @samp{[^--]}
13237 Don't leave, there is some more!
13239 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
13240 the empty string, has a funny behavior in its exit status: it's always 1
13241 when parentheses are used!
13244 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
13246 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
13249 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
13251 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
13256 In practice this can be a big problem if you are ready to catch failures
13257 of @command{expr} programs with some other method (such as using
13258 @command{sed}), since you may get twice the result. For instance
13261 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
13265 outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
13266 simple workaround consists of testing @command{expr} and using a variable
13267 set to @command{expr} or to @command{false} according to the result.
13269 Tru64 @command{expr} incorrectly treats the result as a number, if it
13270 can be interpreted that way:
13273 $ @kbd{expr 00001 : '.*\(...\)'}
13278 @item @command{fgrep}
13279 @c ------------------
13280 @prindex @command{fgrep}
13281 Posix 1003.1-2001 no longer requires @command{fgrep},
13282 but many older hosts do not yet support the Posix
13283 replacement @code{grep -F}. Also, some traditional implementations do
13284 not work on long input lines. To work around these problems, invoke
13285 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
13288 @item @command{find}
13289 @c -----------------
13290 @prindex @command{find}
13291 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
13292 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
13293 commands do not understand it.
13295 The replacement of @samp{@{@}} is guaranteed only if the argument is
13296 exactly @emph{@{@}}, not if it's only a part of an argument. For
13297 instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11:
13301 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
13306 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
13309 @item @command{grep}
13310 @c -----------------
13311 @prindex @command{grep}
13312 Portable scripts can rely on the @command{grep} options @option{-c},
13313 @option{-l}, @option{-n}, and @option{-v}, but should avoid other
13314 options. For example, don't use @option{-w}, as Posix does not require
13315 it and Irix 6.5.16m's @command{grep} does not support it. Also,
13316 portable scripts should not combine @option{-c} with @option{-l},
13317 as Posix does not allow this.
13319 Some of the options required by Posix are not portable in practice.
13320 Don't use @samp{grep -q} to suppress output, because many @command{grep}
13321 implementations (e.g., Solaris) do not support @option{-q}.
13322 Don't use @samp{grep -s} to suppress output either, because Posix
13323 says @option{-s} does not suppress output, only some error messages;
13324 also, the @option{-s} option of traditional @command{grep} behaved
13325 like @option{-q} does in most modern implementations. Instead,
13326 redirect the standard output and standard error (in case the file
13327 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
13328 status of @code{grep} to determine whether it found a match.
13330 Some traditional @command{grep} implementations do not work on long
13331 input lines. On AIX the default @code{grep} silently truncates long
13332 lines on the input before matching.
13334 Also, many implementations do not support multiple regexps
13335 with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris)
13336 or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To
13337 work around these problems, invoke @code{AC_PROG_GREP} and then use
13340 Another possible workaround for the multiple @option{-e} problem is to
13341 separate the patterns by newlines, for example:
13349 except that this fails with traditional @command{grep}
13350 implementations and with Open@acronym{BSD} 3.8 @command{grep}.
13352 Traditional @command{grep} implementations (e.g., Solaris) do not
13353 support the @option{-E} or @option{-F} options. To work around these
13354 problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and
13355 similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are
13356 willing to require support for Posix @command{grep}, your script should
13357 not use both @option{-E} and @option{-F}, since Posix does not allow
13360 Portable @command{grep} regular expressions should use @samp{\} only to
13361 escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example,
13362 alternation, @samp{\|}, is common but Posix does not require its
13363 support in basic regular expressions, so it should be avoided in
13364 portable scripts. Solaris @command{grep} does not support it.
13365 Similarly, @samp{\+} and @samp{\?} should be avoided.
13368 @item @command{join}
13369 @c -----------------
13370 @prindex @command{join}
13371 Solaris 8 @command{join} has bugs when the second operand is standard
13372 input, and when standard input is a pipe. For example, the following
13373 shell script causes Solaris 8 @command{join} to loop forever:
13380 cat file | join file -
13383 Use @samp{join - file} instead.
13388 @prindex @command{ln}
13389 @cindex Symbolic links
13390 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
13391 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
13393 For versions of the @acronym{DJGPP} before 2.04,
13394 @command{ln} emulates symbolic links
13395 to executables by generating a stub that in turn calls the real
13396 program. This feature also works with nonexistent files like in the
13397 Posix spec. So @samp{ln -s file link} generates @file{link.exe},
13398 which attempts to call @file{file.exe} if run. But this feature only
13399 works for executables, so @samp{cp -p} is used instead for these
13400 systems. @acronym{DJGPP} versions 2.04 and later have full support
13401 for symbolic links.
13406 @prindex @command{ls}
13407 @cindex Listing directories
13408 The portable options are @option{-acdilrtu}. Current practice is for
13409 @option{-l} to output both owner and group, even though ancient versions
13410 of @command{ls} omitted the group.
13412 On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found}
13413 to standard output if @file{foo} did not exist. Hence a shell command
13414 like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it
13415 was equivalent to @samp{sources='*.c not found'} in the absence of
13416 @samp{.c} files. This is no longer a practical problem, since current
13417 @command{ls} implementations send diagnostics to standard error.
13419 @item @command{mkdir}
13420 @c ------------------
13421 @prindex @command{mkdir}
13422 @cindex Making directories
13423 No @command{mkdir} option is portable to older systems. Instead of
13424 @samp{mkdir -p @var{file-name}}, you should use use
13425 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh})
13426 or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}).
13428 Posix does not clearly specify whether @samp{mkdir -p foo}
13429 should succeed when @file{foo} is a symbolic link to an already-existing
13430 directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir}
13431 succeeds, but Solaris @command{mkdir} fails.
13433 Traditional @code{mkdir -p} implementations suffer from race conditions.
13434 For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c}
13435 at the same time, both processes might detect that @file{a} is missing,
13436 one might create @file{a}, then the other might try to create @file{a}
13437 and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core
13438 Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0,
13439 Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be
13440 race-free when two processes invoke @code{mkdir -p} simultaneously, but
13441 earlier versions are vulnerable. Solaris @command{mkdir} is still
13442 vulnerable as of Solaris 10, and other traditional Unix systems are
13443 probably vulnerable too. This possible race is harmful in parallel
13444 builds when several Make rules call @code{mkdir -p} to
13445 construct directories. You may use
13446 @code{install-sh -d} as a safe replacement, provided this script is
13447 recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is
13448 OK, but copies from older versions are vulnerable.
13451 @item @command{mktemp}
13452 @c -------------------
13453 @prindex @command{mktemp}
13454 @cindex Creating temporary files
13455 Shell scripts can use temporary files safely with @command{mktemp}, but
13456 it does not exist on all systems. A portable way to create a safe
13457 temporary file name is to create a temporary directory with mode 700 and
13458 use a file inside this directory. Both methods prevent attackers from
13459 gaining control, though @command{mktemp} is far less likely to fail
13460 gratuitously under attack.
13462 Here is sample code to create a new temporary directory safely:
13465 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
13466 # Use mktemp if possible; otherwise fall back on mkdir,
13467 # with $RANDOM to make collisions less likely.
13471 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
13473 test -n "$tmp" && test -d "$tmp"
13475 tmp=$TMPDIR/foo$$-$RANDOM
13476 (umask 077 && mkdir "$tmp")
13483 @prindex @command{mv}
13484 @cindex Moving open files
13485 The only portable options are @option{-f} and @option{-i}.
13487 Moving individual files between file systems is portable (it was in Unix
13489 but it is not always atomic: when doing @samp{mv new existing}, there's
13490 a critical section where neither the old nor the new version of
13491 @file{existing} actually exists.
13493 On some systems moving files from @file{/tmp} can sometimes cause
13494 undesirable (but perfectly valid) warnings, even if you created these
13495 files. This is because @file{/tmp} belongs to a group that ordinary
13496 users are not members of, and files created in @file{/tmp} inherit
13497 the group of @file{/tmp}. When the file is copied, @command{mv} issues
13498 a diagnostic without failing:
13501 $ @kbd{touch /tmp/foo}
13502 $ @kbd{mv /tmp/foo .}
13503 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
13511 This annoying behavior conforms to Posix, unfortunately.
13513 Moving directories across mount points is not portable, use @command{cp}
13516 @acronym{DOS} variants cannot rename or remove open files, and do not
13517 support commands like @samp{mv foo bar >foo}, even though this is
13518 perfectly portable among Posix hosts.
13523 @prindex @command{od}
13525 In Mac OS X 10.3, @command{od} does not support the
13526 standard Posix options @option{-A}, @option{-j}, @option{-N}, or
13527 @option{-t}, or the @acronym{XSI} option @option{-s}. The only
13528 supported Posix option is @option{-v}, and the only supported
13529 @acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD}
13530 @command{hexdump} program can be used instead.
13532 This problem no longer exists in Mac OS X 10.4.3.
13537 @prindex @command{rm}
13538 The @option{-f} and @option{-r} options are portable.
13540 A file might not be be removed even if its parent directory is writable
13541 and searchable. Many Posix hosts cannot remove a mount point, a named
13542 stream, a working directory, or a last link to a file that is being
13545 @acronym{DOS} variants cannot rename or remove open files, and do not
13546 support commands like @samp{rm foo >foo}, even though this is
13547 perfectly portable among Posix hosts.
13550 @item @command{sed}
13551 @c ----------------
13552 @prindex @command{sed}
13553 Patterns should not include the separator (unless escaped), even as part
13554 of a character class. In conformance with Posix, the Cray
13555 @command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
13557 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does
13558 not require support for empty patterns, and Unicos 9 @command{sed} rejects
13561 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
13563 Sed scripts should not use branch labels longer than 8 characters and
13564 should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands
13565 (not counting @samp{:} commands) and
13566 48 labels, which can not be circumvented by using more than one script
13567 file. It can execute up to 19 reads with the @samp{r} command per cycle.
13568 Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of
13569 about 6000 bytes for the internal representation of commands.
13571 Avoid redundant @samp{;}, as some @command{sed} implementations, such as
13572 Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second
13573 @samp{;} as a command:
13576 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
13577 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
13580 Input should not have unreasonably long lines, since some @command{sed}
13581 implementations have an input buffer limited to 4000 bytes.
13583 Portable @command{sed} regular expressions should use @samp{\} only to escape
13584 characters in the string @samp{$()*.0123456789[\^n@{@}}. For example,
13585 alternation, @samp{\|}, is common but Posix does not require its
13586 support, so it should be avoided in portable scripts. Solaris
13587 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
13588 deletes only lines that contain the literal string @samp{a|b}.
13589 Similarly, @samp{\+} and @samp{\?} should be avoided.
13591 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
13593 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
13594 quite portable to current hosts, but was not supported by some ancient
13595 @command{sed} implementations like SVR3.
13597 Some @command{sed} implementations, e.g., Solaris,
13598 restrict the special role of the asterisk to one-character regular expressions.
13599 This may lead to unexpected behavior:
13602 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
13604 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
13608 The @option{-e} option is portable, so long as its argument
13609 does not begin with @samp{a}, @samp{c}, or @samp{i}
13610 (as this runs afoul of a Tru64 5.1 bug).
13611 Some people prefer to use @samp{-e}:
13614 sed -e '@var{command-1}' \
13615 -e '@var{command-2}'
13619 as opposed to the equivalent:
13629 The following usage is sometimes equivalent:
13632 sed '@var{command-1};@var{command-2}'
13635 but Posix says that this use of a semicolon has undefined effect if
13636 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
13637 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
13638 should use semicolon only with simple scripts that do not use these
13641 Commands inside @{ @} brackets are further restricted. Posix says that
13642 they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that
13643 each command must be followed immediately by a newline, without any
13644 intervening blanks or semicolons. The closing bracket must be alone on
13645 a line, other than white space preceding or following it.
13647 Contrary to yet another urban legend, you may portably use @samp{&} in
13648 the replacement part of the @code{s} command to mean ``what was
13649 matched''. All descendants of Unix version 7 @command{sed}
13651 don't have first hand experience with older @command{sed} implementations) have
13654 Posix requires that you must not have any white space between
13655 @samp{!} and the following command. It is OK to have blanks between
13656 the address and the @samp{!}. For instance, on Solaris:
13659 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
13660 @error{}Unrecognized command: /bar/ ! p
13661 $ @kbd{echo "foo" | sed -n '/bar/! p'}
13662 @error{}Unrecognized command: /bar/! p
13663 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
13667 Posix also says that you should not combine @samp{!} and @samp{;}. If
13668 you use @samp{!}, it is best to put it on a command that is delimited by
13669 newlines rather than @samp{;}.
13671 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
13672 @samp{w} commands be followed by exactly one space before their argument.
13673 On the other hand, no white space is allowed between @samp{:} and the
13674 subsequent label name.
13676 If a sed script is specified on the command line and ends in an
13677 @samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text
13678 should be followed by a newline. Otherwise some @command{sed}
13679 implementations (e.g., OpenBSD 3.9) do not append a newline to the
13682 Many @command{sed} implementations (e.g., MacOS X 10.4, OpenBSD 3.9, Solaris 10
13683 @command{/usr/ucb/sed}) strip leading white space from the text of
13684 @samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to
13685 work around this incompatibility with Posix:
13688 $ @kbd{echo flushleft | sed 'a\}
13693 $ @kbd{echo foo | sed 'a\}
13701 @item @command{sed} (@samp{t})
13702 @c ---------------------------
13703 @prindex @command{sed} (@samp{t})
13704 Some old systems have @command{sed} that ``forget'' to reset their
13705 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
13706 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
13707 script (the line numbers are not actual part of the texts):
13710 s/keep me/kept/g # a
13746 Why? When processing line 1, (c) matches, therefore sets the @samp{t}
13747 flag, and the output is produced. When processing
13748 line 2, the @samp{t} flag is still set (this is the bug). Command (a)
13749 fails to match, but @command{sed} is not supposed to clear the @samp{t}
13750 flag when a substitution fails. Command (b) sees that the flag is set,
13751 therefore it clears it, and jumps to (d), hence you get @samp{delete me}
13752 instead of @samp{deleted}. When processing line (3), @samp{t} is clear,
13753 (a) matches, so the flag is set, hence (b) clears the flags and jumps.
13754 Finally, since the flag is clear, line 4 is processed properly.
13756 There are two things one should remember about @samp{t} in @command{sed}.
13757 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
13758 succeeded, not only the immediately preceding substitution. Therefore,
13759 always use a fake @samp{t clear} followed by a @samp{:clear} on the next
13760 line, to reset the @samp{t} flag where needed.
13762 Secondly, you cannot rely on @command{sed} to clear the flag at each new
13765 One portable implementation of the script above is:
13776 @item @command{touch}
13777 @c ------------------
13778 @prindex @command{touch}
13779 @cindex timestamp resolution
13780 If you specify the desired timestamp (e.g., with the @option{-r}
13781 option), @command{touch} typically uses the @code{utime} or
13782 @code{utimes} system call, which can result in the same kind of
13783 timestamp truncation problems that @samp{cp -p} has.
13785 On ancient @acronym{BSD} systems, @command{touch} or any command that
13786 results in an empty file does not update the timestamps, so use a
13787 command like @command{echo} as a workaround.
13789 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
13790 fails to work on SunOS 4.1.3 when the empty file is on an
13791 @acronym{NFS}-mounted 4.2 volume.
13792 However, these problems are no longer of practical concern.
13797 @node Portable Make
13798 @chapter Portable Make Programming
13799 @prindex @command{make}
13800 @cindex Limitations of @command{make}
13802 Writing portable makefiles is an art. Since a makefile's commands are
13803 executed by the shell, you must consider the shell portability issues
13804 already mentioned. However, other issues are specific to @command{make}
13808 * $< in Ordinary Make Rules:: $< in ordinary rules
13809 * Failure in Make Rules:: Failing portably in rules
13810 * Special Chars in Names:: Special Characters in Macro Names
13811 * Backslash-Newline-Newline:: Empty last lines in macro definitions
13812 * Backslash-Newline Comments:: Spanning comments across line boundaries
13813 * Long Lines in Makefiles:: Line length limitations
13814 * Macros and Submakes:: @code{make macro=value} and submakes
13815 * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues
13816 * The Make Macro SHELL:: @code{$(SHELL)} portability issues
13817 * Comments in Make Rules:: Other problems with Make comments
13818 * obj/ and Make:: Don't name a subdirectory @file{obj}
13819 * make -k Status:: Exit status of @samp{make -k}
13820 * VPATH and Make:: @code{VPATH} woes
13821 * Single Suffix Rules:: Single suffix rules and separated dependencies
13822 * Timestamps and Make:: Subsecond timestamp resolution
13825 @node $< in Ordinary Make Rules
13826 @section @code{$<} in Ordinary Make Rules
13828 Posix says that the @samp{$<} construct in makefiles can be
13829 used only in inference rules and in the @samp{.DEFAULT} rule; its
13830 meaning in ordinary rules is unspecified. Solaris @command{make}
13831 for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and
13832 later) @command{make} diagnoses these uses and errors out.
13834 @node Failure in Make Rules
13835 @section Failure in Make Rules
13837 Since 1992 Posix has required that @command{make} must invoke
13838 each command with the equivalent of a @samp{sh -c} subshell. However,
13839 many @command{make} implementations, including @acronym{BSD} make through 2004,
13840 use @samp{sh -e -c} instead, and the @option{-e} option causes the
13841 subshell to exit immediately if a subsidiary simple-command fails. For
13842 example, the command @samp{touch T; rm -f U} always attempts to
13843 remove @file{U} with Posix make, but incompatible
13844 @command{make} implementations skip the @command{rm} if the
13845 @command{touch} fails. One way to work around this is to reword the
13846 affected simple-commands so that they always succeed, e.g., @samp{touch
13848 However, even this approach can run into common bugs in @acronym{BSD}
13849 implementations of the @option{-e} option of @command{sh} and
13850 @command{set} (@pxref{Limitations of Builtins}), so if you are worried
13851 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
13852 complicated @command{make} actions into separate scripts.
13854 @node Special Chars in Names
13855 @section Special Characters in Make Macro Names
13857 Posix limits macro names to nonempty strings containing only
13858 @acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many
13859 @command{make} implementations allow a wider variety of characters, but
13860 portable makefiles should avoid them. It is portable to start a name
13861 with a special character, e.g., @samp{$(.FOO)}.
13863 Some ancient @command{make} implementations don't support leading
13864 underscores in macro names. An example is @acronym{NEWS-OS} 4.2R.
13867 $ @kbd{cat Makefile}
13870 all:; @@echo this is test
13872 Make: Must be a separator on rules line 2. Stop.
13873 $ @kbd{cat Makefile2}
13876 all:; @@echo this is test
13877 $ @kbd{make -f Makefile2}
13882 However, this problem is no longer of practical concern.
13884 @node Backslash-Newline-Newline
13885 @section Backslash-Newline-Newline in Make Macro Values
13887 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
13888 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
13889 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
13890 On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines
13891 following a backslash, continuing to the next non-empty line. For
13905 shows @code{FOO} equal to @code{one BAR = two}. Other implementations
13906 sensibly let a backslash continue only to the immediately following
13909 @node Backslash-Newline Comments
13910 @section Backslash-Newline in Make Comments
13912 According to Posix, Make comments start with @code{#}
13913 and continue until an unescaped newline is reached.
13916 $ @kbd{cat Makefile}
13923 $ @kbd{make} # GNU make
13928 However this is not always the case. Some implementations
13929 discard everything from @code{#} through the end of the line, ignoring any
13930 trailing backslash.
13933 $ @kbd{pmake} # BSD make
13934 "Makefile", line 3: Need an operator
13935 Fatal errors encountered -- cannot continue
13939 Therefore, if you want to comment out a multi-line definition, prefix each
13940 line with @code{#}, not only the first.
13948 @node Long Lines in Makefiles
13949 @section Long Lines in Makefiles
13951 Tru64 5.1's @command{make} has been reported to crash when given a
13952 makefile with lines longer than around 20 kB. Earlier versions are
13953 reported to exit with @code{Line too long} diagnostics.
13955 @node Macros and Submakes
13956 @section @code{make macro=value} and Submakes
13958 A command-line variable definition such as @code{foo=bar} overrides any
13959 definition of @code{foo} in a makefile. Some @command{make}
13960 implementations (such as @acronym{GNU} @command{make}) propagate this
13961 override to subsidiary invocations of @command{make}. Some other
13962 implementations do not pass the substitution along to submakes.
13965 $ @kbd{cat Makefile}
13972 $ @kbd{make foo=bar} # GNU make 3.79.1
13975 make[1]: Entering directory `/home/adl'
13977 make[1]: Leaving directory `/home/adl'
13978 $ @kbd{pmake foo=bar} # BSD make
13984 You have a few possibilities if you do want the @code{foo=bar} override
13985 to propagate to submakes. One is to use the @option{-e}
13986 option, which causes all environment variables to have precedence over
13987 the makefile macro definitions, and declare foo as an environment
13991 $ @kbd{env foo=bar make -e}
13994 The @option{-e} option is propagated to submakes automatically,
13995 and since the environment is inherited between @command{make}
13996 invocations, the @code{foo} macro is overridden in
13997 submakes as expected.
13999 This syntax (@code{foo=bar make -e}) is portable only when used
14000 outside of a makefile, for instance from a script or from the
14001 command line. When run inside a @command{make} rule, @acronym{GNU}
14002 @command{make} 3.80 and prior versions forget to propagate the
14003 @option{-e} option to submakes.
14005 Moreover, using @option{-e} could have unexpected side effects if your
14006 environment contains some other macros usually defined by the
14007 makefile. (See also the note about @code{make -e} and @code{SHELL}
14010 Another way to propagate overrides to submakes is to do it
14011 manually, from your makefile:
14017 $(MAKE) foo=$(foo) two
14022 You need to foresee all macros that a user might want to override if
14025 @node The Make Macro MAKEFLAGS
14026 @section The Make Macro MAKEFLAGS
14027 @cindex @code{MAKEFLAGS} and @command{make}
14028 @cindex @command{make} and @code{MAKEFLAGS}
14030 Posix requires @command{make} to use @code{MAKEFLAGS} to affect the
14031 current and recursive invocations of make, but allows implementations
14032 several formats for the variable. It is tricky to parse
14033 @code{$MAKEFLAGS} to determine whether @option{-s} for silent execution
14034 or @option{-k} for continued execution are in effect. For example, you
14035 cannot assume that the first space-separated word in @code{$MAKEFLAGS}
14036 contains single-letter options, since in the Cygwin version of
14037 @acronym{GNU} @command{make} it is either @option{--unix} or
14038 @option{--win32} with the second word containing single-letter options.
14041 $ @kbd{cat Makefile}
14043 @@echo MAKEFLAGS = $(MAKEFLAGS)
14047 MAKEFLAGS = --unix -k
14050 @node The Make Macro SHELL
14051 @section The Make Macro @code{SHELL}
14052 @cindex @code{SHELL} and @command{make}
14053 @cindex @command{make} and @code{SHELL}
14055 Posix-compliant @command{make} internally uses the @code{$(SHELL)}
14056 macro to spawn shell processes and execute Make rules. This
14057 is a builtin macro supplied by @command{make}, but it can be modified
14058 by a makefile or by a command-line argument.
14060 Not all @command{make} implementations define this @code{SHELL} macro.
14062 @command{make} is an example; this implementation always uses
14063 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
14064 your makefiles. If you use Autoconf, do
14070 Do not force @code{SHELL = /bin/sh} because that is not correct
14071 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
14072 its @acronym{GNU} @code{make} port sees such a setting it enters a special
14073 emulation mode where features like pipes and redirections are emulated
14074 on top of DOS's @command{command.com}. Unfortunately this emulation is
14075 incomplete; for instance it does not handle command substitutions.
14076 On @acronym{DJGPP} @code{SHELL} should point to Bash.
14078 Posix-compliant @command{make} should never acquire the value of
14079 $(SHELL) from the environment, even when @code{make -e} is used
14080 (otherwise, think about what would happen to your rules if
14081 @code{SHELL=/bin/tcsh}).
14083 However not all @command{make} implementations have this exception.
14084 For instance it's not surprising that Tru64 @command{make} doesn't
14085 protect @code{SHELL}, since it doesn't use it.
14088 $ @kbd{cat Makefile}
14094 $ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make
14097 $ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
14102 @node Comments in Make Rules
14103 @section Comments in Make Rules
14104 @cindex Comments in @file{Makefile} rules
14105 @cindex @file{Makefile} rules and comments
14107 Never put comments in a rule.
14109 Some @command{make} treat anything starting with a tab as a command for
14110 the current rule, even if the tab is immediately followed by a @code{#}.
14111 The @command{make} from Tru64 Unix V5.1 is one of them. The following
14112 makefile runs @code{# foo} through the shell.
14119 @node obj/ and Make
14120 @section The @file{obj/} Subdirectory and Make
14121 @cindex @file{obj/}, subdirectory
14122 @cindex @acronym{BSD} @command{make} and @file{obj/}
14124 Never name one of your subdirectories @file{obj/} if you don't like
14127 If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it
14128 before reading the makefile. Hence the makefile in the
14129 current directory is not read.
14132 $ @kbd{cat Makefile}
14135 $ @kbd{cat obj/Makefile}
14138 $ @kbd{make} # GNU make
14141 $ @kbd{pmake} # BSD make
14146 @node make -k Status
14147 @section Exit Status of @code{make -k}
14148 @cindex @code{make -k}
14150 Do not rely on the exit status of @code{make -k}. Some implementations
14151 reflect whether they encountered an error in their exit status; other
14152 implementations always succeed.
14155 $ @kbd{cat Makefile}
14158 $ @kbd{make -k; echo exit status: $?} # GNU make
14160 make: *** [all] Error 1
14162 $ @kbd{pmake -k; echo exit status: $?} # BSD make
14164 *** Error code 1 (continuing)
14168 @node VPATH and Make
14169 @section @code{VPATH} and Make
14170 @cindex @code{VPATH}
14172 Posix does not specify the semantics of @code{VPATH}. Typically,
14173 @command{make} supports @code{VPATH}, but its implementation is not
14176 Autoconf and Automake support makefiles whose usages of @code{VPATH} are
14177 portable to recent-enough popular implementations of @command{make}, but
14178 to keep the resulting makefiles portable, a package's makefile
14179 prototypes must take the following issues into account. These issues
14180 are complicated and are often poorly understood, and installers who use
14181 @code{VPATH} should expect to find many bugs in this area. If you use
14182 @code{VPATH}, the simplest way to avoid these portability bugs is to
14183 stick with @acronym{GNU} @command{make}, since it is the most
14184 commonly-used @command{make} among Autoconf users.
14186 Here are some known issues with some @code{VPATH}
14190 * VPATH and Double-colon:: Problems with @samp{::} on ancient hosts
14191 * $< in Explicit Rules:: @code{$<} does not work in ordinary rules
14192 * Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris
14193 * Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64
14194 * Make Target Lookup:: More details about @code{VPATH} lookup
14197 @node VPATH and Double-colon
14198 @subsection @code{VPATH} and Double-colon Rules
14199 @cindex @code{VPATH} and double-colon rules
14200 @cindex double-colon rules and @code{VPATH}
14202 With ancient versions of Sun @command{make},
14203 any assignment to @code{VPATH} causes @command{make} to execute only
14204 the first set of double-colon rules.
14205 However, this problem is no longer of practical concern.
14207 @node $< in Explicit Rules
14208 @subsection @code{$<} Not Supported in Explicit Rules
14209 @cindex explicit rules, @code{$<}, and @code{VPATH}
14210 @cindex @code{$<}, explicit rules, and @code{VPATH}
14211 @cindex @code{VPATH}, explicit rules, and @code{$<}
14213 Using @code{$<} in explicit rules is not portable.
14214 The prerequisite file must be named explicitly in the rule. If you want
14215 to find the prerequisite via a @code{VPATH} search, you have to code the
14216 whole thing manually. @xref{Build Directories}.
14218 @node Automatic Rule Rewriting
14219 @subsection Automatic Rule Rewriting
14220 @cindex @code{VPATH} and automatic rule rewriting
14221 @cindex automatic rule rewriting and @code{VPATH}
14223 Some @command{make} implementations, such as Solaris and Tru64,
14224 search for prerequisites in @code{VPATH} and
14225 then rewrite each occurrence as a plain word in the rule.
14229 # This isn't portable to GNU make.
14236 executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is
14237 found in @file{../pkg/src}.
14239 However, this rule leads to real problems in practice. For example, if
14240 the source directory contains an ordinary file named @file{test} that is
14241 used in a dependency, Solaris @command{make} rewrites commands like
14242 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
14243 @dots{}}, which is typically undesirable. To avoid this problem,
14244 portable makefiles should never mention a source file whose name is that
14245 of a shell keyword like @file{until} or a shell command like
14246 @command{cat} or @command{gcc} or @command{test}.
14248 Because of these problems @acronym{GNU} @command{make} and many other
14249 @command{make} implementations do not rewrite commands, so portable
14251 search @code{VPATH} manually. It is tempting to write this:
14254 # This isn't portable to Solaris make.
14257 cp `test -f if.c || echo $(VPATH)/`if.c f.c
14261 However, the ``prerequisite rewriting'' still applies here. So if
14262 @file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make}
14266 cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c
14277 and thus fails. Oops.
14279 A simple workaround, and good practice anyway, is to use @samp{$?} and
14280 @samp{$@@} when possible:
14289 but this does not generalize well to commands with multiple
14290 prerequisites. A more general workaround is to rewrite the rule so that
14291 the prerequisite @file{if.c} never appears as a plain word. For
14292 example, these three rules would be safe, assuming @file{if.c} is in
14293 @file{../pkg/src} and the other files are in the working directory:
14298 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@
14300 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@
14302 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@
14305 Things get worse when your prerequisites are in a macro.
14309 HEADERS = f.h g.h h.h
14310 install-HEADERS: $(HEADERS)
14311 for i in $(HEADERS); do \
14312 $(INSTALL) -m 644 \
14313 `test -f $$i || echo $(VPATH)/`$$i \
14314 $(DESTDIR)$(includedir)/$$i; \
14318 The above @code{install-HEADERS} rule is not Solaris-proof because @code{for
14319 i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;}
14320 where @code{f.h} and @code{g.h} are plain words and are hence
14321 subject to @code{VPATH} adjustments.
14323 If the three files are in @file{../pkg/src}, the rule is run as:
14326 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
14328 `test -f $i || echo ../pkg/src/`$i \
14329 /usr/local/include/$i; \
14333 where the two first @command{install} calls fail. For instance,
14334 consider the @code{f.h} installation:
14338 `test -f ../pkg/src/f.h || \
14341 /usr/local/include/../pkg/src/f.h;
14350 /usr/local/include/../pkg/src/f.h;
14353 Note that the manual @code{VPATH} search did not cause any problems here;
14354 however this command installs @file{f.h} in an incorrect directory.
14356 Trying to quote @code{$(HEADERS)} in some way, as we did for
14357 @code{foo.c} a few makefiles ago, does not help:
14360 install-HEADERS: $(HEADERS)
14361 headers='$(HEADERS)'; \
14362 for i in $$headers; do \
14363 $(INSTALL) -m 644 \
14364 `test -f $$i || echo $(VPATH)/`$$i \
14365 $(DESTDIR)$(includedir)/$$i; \
14369 Now, @code{headers='$(HEADERS)'} macroexpands to:
14372 headers='f.h g.h h.h'
14376 but @code{g.h} is still a plain word. (As an aside, the idiom
14377 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
14378 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
14379 syntax error on @code{for i in;}.)
14381 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
14385 HEADERS = f.h g.h h.h
14386 install-HEADERS: $(HEADERS)
14387 headers='$(HEADERS)'; \
14388 for i in $$headers; do \
14389 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
14390 $(INSTALL) -m 644 \
14391 `test -f $$i || echo $(VPATH)/`$$i \
14392 $(DESTDIR)$(includedir)/$$i; \
14396 Automake does something similar. However the above hack works only if
14397 the files listed in @code{HEADERS} are in the current directory or a
14398 subdirectory; they should not be in an enclosing directory. If we had
14399 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
14400 build with Tru64 @command{make}. The reason is that not only does
14401 Tru64 @command{make} rewrite dependencies, but it also simplifies
14402 them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of
14403 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
14404 a leading @file{../pkg/src/} component.
14406 The following example makes the behavior of Tru64 @command{make}
14410 $ @kbd{cat Makefile}
14422 Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64
14423 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
14424 directory does not even exist, this just means that the simplification
14425 occurred before the file was checked for.)
14427 For the record here is how SunOS 4 @command{make} behaves on this
14432 make: Fatal error: Don't know how to make target `../foo'
14440 @node Tru64 Directory Magic
14441 @subsection Tru64 @command{make} Creates Prerequisite Directories Magically
14442 @cindex @code{VPATH} and prerequisite directories
14443 @cindex prerequisite directories and @code{VPATH}
14445 When a prerequisite is a subdirectory of @code{VPATH}, Tru64
14446 @command{make} creates it in the current directory.
14449 $ @kbd{mkdir -p foo/bar build}
14451 $ @kbd{cat >Makefile <<END
14460 This can yield unexpected results if a rule uses a manual @code{VPATH}
14461 search as presented before.
14466 command `test -d foo/bar || echo ../`foo/bar
14469 The above @command{command} is run on the empty @file{foo/bar}
14470 directory that was created in the current directory.
14472 @node Make Target Lookup
14473 @subsection Make Target Lookup
14474 @cindex @code{VPATH}, resolving target pathnames
14476 @acronym{GNU} @command{make} uses a complex algorithm to decide when it
14477 should use files found via a @code{VPATH} search. @xref{Search
14478 Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make
14481 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
14482 file name found during the @code{VPATH} search for this target, and
14483 builds the file locally using the file name given in the makefile.
14484 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
14485 file name found during the @code{VPATH} search.
14487 Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are
14488 easier to describe: the file name found during the @code{VPATH} search
14489 is used whether the target needs to be rebuilt or not. Therefore
14490 new files are created locally, but existing files are updated at their
14491 @code{VPATH} location.
14493 Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however,
14495 @code{VPATH} search for a dependency that has an explicit rule.
14496 This is extremely annoying.
14498 When attempting a @code{VPATH} build for an autoconfiscated package
14499 (e.g., @code{mkdir build && cd build && ../configure}), this means
14501 @command{make} builds everything locally in the @file{build}
14502 directory, while @acronym{BSD} @command{make} builds new files locally and
14503 updates existing files in the source directory.
14506 $ @kbd{cat Makefile}
14509 foo.x bar.x: newer.x
14510 @@echo Building $@@
14511 $ @kbd{touch ../bar.x}
14512 $ @kbd{touch ../newer.x}
14513 $ @kbd{make} # GNU make
14516 $ @kbd{pmake} # NetBSD make
14519 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14522 $ @kbd{tmake} # Tru64 make
14525 $ @kbd{touch ../bar.x}
14526 $ @kbd{make} # GNU make
14528 $ @kbd{pmake} # NetBSD make
14530 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14533 $ @kbd{tmake} # Tru64 make
14538 Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its
14539 VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64
14540 @command{make} always
14541 update @file{bar.x}, even when @file{../bar.x} is up to date.
14543 Another point worth mentioning is that once @acronym{GNU} @command{make} has
14544 decided to ignore a @code{VPATH} file name (e.g., it ignored
14545 @file{../bar.x} in the above example) it continues to ignore it when
14546 the target occurs as a prerequisite of another rule.
14548 The following example shows that @acronym{GNU} @command{make} does not look up
14549 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
14550 because it ignored the @code{VPATH} result of @file{bar.x} while running
14551 the @code{bar.x: newer.x} rule.
14554 $ @kbd{cat Makefile}
14558 @@echo Building $@@
14562 $ @kbd{touch ../bar.x}
14563 $ @kbd{touch ../newer.x}
14564 $ @kbd{make} # GNU make
14567 cp: cannot stat `bar.x': No such file or directory
14568 make: *** [bar.y] Error 1
14569 $ @kbd{pmake} # NetBSD make
14573 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14574 echo Building bar.x
14576 cp: cannot stat `bar.x': No such file or directory
14578 $ @kbd{tmake} # Tru64 make
14580 cp: bar.x: No such file or directory
14584 Note that if you drop away the command from the @code{bar.x: newer.x}
14585 rule, @acronym{GNU} @command{make} magically starts to work: it
14586 knows that @code{bar.x} hasn't been updated, therefore it doesn't
14587 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
14588 uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD}
14592 $ @kbd{cat Makefile}
14599 $ @kbd{touch ../bar.x}
14600 $ @kbd{touch ../newer.x}
14601 $ @kbd{make} # GNU make
14604 $ @kbd{pmake} # NetBSD make
14607 $ @kbd{fmake} # FreeBSD make, OpenBSD make
14609 cp: cannot stat `bar.x': No such file or directory
14611 $ @kbd{tmake} # Tru64 make
14615 It seems the sole solution that would please every @command{make}
14616 implementation is to never rely on @code{VPATH} searches for targets.
14617 In other words, @code{VPATH} should be reserved to unbuilt sources.
14620 @node Single Suffix Rules
14621 @section Single Suffix Rules and Separated Dependencies
14622 @cindex Single Suffix Inference Rule
14623 @cindex Rule, Single Suffix Inference
14624 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
14625 (@samp{.from.to:}), but which @emph{destination} suffix is empty
14628 @cindex Separated Dependencies
14629 @dfn{Separated dependencies} simply refers to listing the prerequisite
14630 of a target, without defining a rule. Usually one can list on the one
14631 hand side, the rules, and on the other hand side, the dependencies.
14633 Solaris @command{make} does not support separated dependencies for
14634 targets defined by single suffix rules:
14637 $ @kbd{cat Makefile}
14642 $ @kbd{touch foo.in}
14649 while @acronym{GNU} Make does:
14655 Makefile foo foo.in
14658 Note it works without the @samp{foo: foo.in} dependency.
14661 $ @kbd{cat Makefile}
14670 and it works with double suffix inference rules:
14673 $ @kbd{cat Makefile}
14675 .SUFFIXES: .in .out
14682 As a result, in such a case, you have to write target rules.
14684 @node Timestamps and Make
14685 @section Timestamp Resolution and Make
14686 @cindex timestamp resolution
14687 Traditionally, file timestamps had 1-second resolution, and
14688 @command{make} used those timestamps to determine whether one file was
14689 newer than the other. However, many modern file systems have
14690 timestamps with 1-nanosecond resolution. Some @command{make}
14691 implementations look at the entire timestamp; others ignore the
14692 fractional part, which can lead to incorrect results. Normally this
14693 is not a problem, but in some extreme cases you may need to use tricks
14694 like @samp{sleep 1} to work around timestamp truncation bugs.
14696 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
14697 file timestamps to their full resolutions (@pxref{Limitations of Usual
14698 Tools}). Hence you should be wary of rules like this:
14705 as @file{dest} often appears to be older than @file{src} after the
14706 timestamp is truncated, and this can cause @command{make} to do
14707 needless rework the next time it is invoked. To work around this
14708 problem, you can use a timestamp file, e.g.:
14719 @c ======================================== Portable C and C++ Programming
14721 @node Portable C and C++
14722 @chapter Portable C and C++ Programming
14723 @cindex Portable C and C++ programming
14725 C and C++ programs often use low-level features of the underlying
14726 system, and therefore are often more difficult to make portable to other
14729 Several standards have been developed to help make your programs more
14730 portable. If you write programs with these standards in mind, you can
14731 have greater confidence that your programs work on a wide variety
14732 of systems. @xref{Standards, , Language Standards Supported by
14733 @acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection
14734 (@acronym{GCC})}, for a list of C-related
14735 standards. Many programs also assume the
14736 @uref{http://www.opengroup.org/susv3, Posix standard}.
14738 Some old code is written to be portable to K&R C, which predates any C
14739 standard. K&R C compilers are no longer of practical interest, though,
14740 and the rest of section assumes at least C89, the first C standard.
14742 Program portability is a huge topic, and this section can only briefly
14743 introduce common pitfalls. @xref{System Portability, , Portability
14744 between System Types, standards, @acronym{GNU} Coding Standards}, for
14748 * Varieties of Unportability:: How to make your programs unportable
14749 * Integer Overflow:: When integers get too large
14750 * Null Pointers:: Properties of null pointers
14751 * Buffer Overruns:: Subscript errors and the like
14752 * Volatile Objects:: @code{volatile} and signals
14753 * Floating Point Portability:: Portable floating-point arithmetic
14754 * Exiting Portably:: Exiting and the exit status
14757 @node Varieties of Unportability
14758 @section Varieties of Unportability
14759 @cindex portability
14761 Autoconf tests and ordinary programs often need to test what is allowed
14762 on a system, and therefore they may need to deliberately exceed the
14763 boundaries of what the standards allow, if only to see whether an
14764 optional feature is present. When you write such a program, you should
14765 keep in mind the difference between constraints, unspecified behavior,
14766 and undefined behavior.
14768 In C, a @dfn{constraint} is a rule that the compiler must enforce. An
14769 example constraint is that C programs must not declare a bit-field with
14770 negative width. Tests can therefore reliably assume that programs with
14771 negative-width bit-fields are rejected by a compiler that conforms
14774 @dfn{Unspecified behavior} is valid behavior, where the standard allows
14775 multiple possibilities. For example, the order of evaluation of
14776 function arguments is unspecified. Some unspecified behavior is
14777 @dfn{implementation-defined}, i.e., documented by the implementation,
14778 but since Autoconf tests cannot read the documentation they cannot
14779 distinguish between implementation-defined and other unspecified
14780 behavior. It is common for Autoconf tests to probe implementations to
14781 determine otherwise-unspecified behavior.
14783 @dfn{Undefined behavior} is invalid behavior, where the standard allows
14784 the implementation to do anything it pleases. For example,
14785 dereferencing a null pointer leads to undefined behavior. If possible,
14786 test programs should avoid undefined behavior, since a program with
14787 undefined behavior might succeed on a test that should fail.
14789 The above rules apply to programs that are intended to conform to the
14790 standard. However, strictly-conforming programs are quite rare, since
14791 the standards are so limiting. A major goal of Autoconf is to support
14792 programs that use implementation features not described by the standard,
14793 and it is fairly common for test programs to violate the above rules, if
14794 the programs work well enough in practice.
14796 @node Integer Overflow
14797 @section Integer Overflow
14798 @cindex overflow, arithmetic
14800 In C, signed integer overflow leads to undefined behavior. However,
14801 many programs and Autoconf tests assume that signed integer overflow after
14802 addition, subtraction, or multiplication silently
14803 wraps around modulo a power of two, using two's complement arithmetic,
14804 so long as you cast the resulting value
14805 to an integer type or store it into an integer variable. Such programs
14806 are portable to the vast majority of modern platforms. However, signed
14807 integer division is not always harmless: for example, on CPUs of the
14808 i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal
14809 which by default terminates the program. Worse, taking the remainder
14810 of these two values typically yields the same signal on these CPUs,
14811 even though the C standard requires @code{INT_MIN % -1} to yield zero
14812 because the expression does not overflow.
14814 @acronym{GCC} users might consider using the
14815 @option{-ftrapv} option if they are worried about porting their code to
14816 the rare platforms where signed integer overflow does not wrap around
14817 after addition, subtraction, or multiplication.
14819 Unsigned integer overflow reliably wraps around modulo the word size.
14820 This is guaranteed by the C standard and is portable in practice.
14822 @node Null Pointers
14823 @section Properties of Null Pointers
14824 @cindex null pointers
14826 Most modern hosts reliably fail when you attempt to dereference a null
14829 On almost all modern hosts, null pointers use an all-bits-zero internal
14830 representation, so you can reliably use @code{memset} with 0 to set all
14831 the pointers in an array to null values.
14833 If @code{p} is a null pointer to an object type, the C expression
14834 @code{p + 0} always evaluates to @code{p} on modern hosts, even though
14835 the standard says that it has undefined behavior.
14837 @node Buffer Overruns
14838 @section Buffer Overruns and Subscript Errors
14839 @cindex buffer overruns
14841 Buffer overruns and subscript errors are the most common dangerous
14842 errors in C programs. They result in undefined behavior because storing
14843 outside an array typically modifies storage that is used by some other
14844 object, and most modern systems lack runtime checks to catch these
14845 errors. Programs should not rely on buffer overruns being caught.
14847 There is one exception to the usual rule that a portable program cannot
14848 address outside an array. In C, it is valid to compute the address just
14849 past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements,
14850 so long as you do not dereference the resulting pointer. But it is not
14851 valid to compute the address just before an object, e.g., @code{&a[-1]};
14852 nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On
14853 most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not
14854 reliable in general, and it is usually easy enough to avoid the
14855 potential portability problem, e.g., by allocating an extra unused array
14856 element at the start or end.
14858 @uref{http://valgrind.org/, Valgrind} can catch many overruns.
14860 users might also consider using the @option{-fmudflap} option to catch
14863 Buffer overruns are usually caused by off-by-one errors, but there are
14864 more subtle ways to get them.
14866 Using @code{int} values to index into an array or compute array sizes
14867 causes problems on typical 64-bit hosts where an array index might
14868 be @math{2^31} or larger. Index values of type @code{size_t} avoid this
14869 problem, but cannot be negative. Index values of type @code{ptrdiff_t}
14870 are signed, and are wide enough in practice.
14872 If you add or multiply two numbers to calculate an array size, e.g.,
14873 @code{malloc (x * sizeof y + z)}, havoc ensues if the addition or
14874 multiplication overflows.
14876 Many implementations of the @code{alloca} function silently misbehave
14877 and can generate buffer overflows if given sizes that are too large.
14878 The size limits are implementation dependent, but are at least 4000
14879 bytes on all platforms that we know about.
14881 The standard functions @code{asctime}, @code{asctime_r}, @code{ctime},
14882 @code{ctime_r}, and @code{gets} are prone to buffer overflows, and
14883 portable code should not use them unless the inputs are known to be
14884 within certain limits. The time-related functions can overflow their
14885 buffers if given timestamps out of range (e.g., a year less than -999
14886 or greater than 9999). Time-related buffer overflows cannot happen with
14887 recent-enough versions of the @acronym{GNU} C library, but are possible
14889 implementations. The @code{gets} function is the worst, since it almost
14890 invariably overflows its buffer when presented with an input line larger
14893 @node Volatile Objects
14894 @section Volatile Objects
14895 @cindex volatile objects
14897 The keyword @code{volatile} is often misunderstood in portable code.
14898 Its use inhibits some memory-access optimizations, but programmers often
14899 wish that it had a different meaning than it actually does.
14901 @code{volatile} was designed for code that accesses special objects like
14902 memory-mapped device registers whose contents spontaneously change.
14903 Such code is inherently low-level, and it is difficult to specify
14904 portably what @code{volatile} means in these cases. The C standard
14905 says, ``What constitutes an access to an object that has
14906 volatile-qualified type is implementation-defined,'' so in theory each
14907 implementation is supposed to fill in the gap by documenting what
14908 @code{volatile} means for that implementation. In practice, though,
14909 this documentation is usually absent or incomplete.
14911 One area of confusion is the distinction between objects defined with
14912 volatile types, and volatile lvalues. From the C standard's point of
14913 view, an object defined with a volatile type has externally visible
14914 behavior. You can think of such objects as having little oscilloscope
14915 probes attached to them, so that the user can observe some properties of
14916 accesses to them, just as the user can observe data written to output
14917 files. However, the standard does not make it clear whether users can
14918 observe accesses by volatile lvalues to ordinary objects. For example:
14921 /* Declare and access a volatile object.
14922 Accesses to X are "visible" to users. */
14923 static int volatile x;
14926 /* Access two ordinary objects via a volatile lvalue.
14927 It's not clear whether accesses to *P are "visible". */
14929 int *z = malloc (sizeof (int));
14937 Programmers often wish that @code{volatile} meant ``Perform the memory
14938 access here and now, without merging several memory accesses, without
14939 changing the memory word size, and without reordering.'' But the C
14940 standard does not require this. For objects defined with a volatile
14941 type, accesses must be done before the next sequence point; but
14942 otherwise merging, reordering, and word-size change is allowed. Worse,
14943 it is not clear from the standard whether volatile lvalues provide more
14944 guarantees in general than nonvolatile lvalues, if the underlying
14945 objects are ordinary.
14947 Even when accessing objects defined with a volatile type,
14948 the C standard allows only
14949 extremely limited signal handlers: the behavior is undefined if a signal
14950 handler reads any nonlocal object, or writes to any nonlocal object
14951 whose type is not @code{sig_atomic_t volatile}, or calls any standard
14952 library function other than @code{abort}, @code{signal}, and (if C99)
14953 @code{_Exit}. Hence C compilers need not worry about a signal handler
14954 disturbing ordinary computation, unless the computation accesses a
14955 @code{sig_atomic_t volatile} lvalue that is not a local variable.
14956 (There is an obscure exception for accesses via a pointer to a volatile
14957 character, since it may point into part of a @code{sig_atomic_t
14958 volatile} object.) Posix
14959 adds to the list of library functions callable from a portable signal
14960 handler, but otherwise is like the C standard in this area.
14962 Some C implementations allow memory-access optimizations within each
14963 translation unit, such that actual behavior agrees with the behavior
14964 required by the standard only when calling a function in some other
14965 translation unit, and a signal handler acts like it was called from a
14966 different translation unit. The C standard hints that in these
14967 implementations, objects referred to by signal handlers ``would require
14968 explicit specification of @code{volatile} storage, as well as other
14969 implementation-defined restrictions.'' But unfortunately even for this
14970 special case these other restrictions are often not documented well.
14971 @xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the
14972 @acronym{GNU} Compiler Collection (@acronym{GCC})}, for some
14973 restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, ,
14974 Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some
14975 restrictions imposed by the @acronym{GNU} C library. Restrictions
14976 differ on other platforms.
14978 If possible, it is best to use a signal handler that fits within the
14979 limits imposed by the C and Posix standards.
14981 If this is not practical, you can try the following rules of thumb. A
14982 signal handler should access only volatile lvalues, preferably lvalues
14983 that refer to objects defined with a volatile type, and should not
14984 assume that the accessed objects have an internally consistent state
14985 if they are larger than a machine word. Furthermore, installers
14986 should employ compilers and compiler options that are commonly used
14987 for building operating system kernels, because kernels often need more
14988 from @code{volatile} than the C Standard requires, and installers who
14989 compile an application in a similar environment can sometimes benefit
14990 from the extra constraints imposed by kernels on compilers.
14991 Admittedly we are handwaving somewhat here, as there are few
14992 guarantees in this area; the rules of thumb may help to fix some bugs
14993 but there is a good chance that they will not fix them all.
14995 For @code{volatile}, C++ has the same problems that C does.
14996 Multithreaded applications have even more problems with @code{volatile},
14997 but they are beyond the scope of this section.
14999 The bottom line is that using @code{volatile} typically hurts
15000 performance but should not hurt correctness. In some cases its use
15001 does help correctness, but these cases are often so poorly understood
15002 that all too often adding @code{volatile} to a data structure merely
15003 alleviates some symptoms of a bug while not fixing the bug in general.
15005 @node Floating Point Portability
15006 @section Floating Point Portability
15007 @cindex floating point
15009 Almost all modern systems use IEEE-754 floating point, and it is safe to
15010 assume IEEE-754 in most portable code these days. For more information,
15011 please see David Goldberg's classic paper
15012 @uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer
15013 Scientist Should Know About Floating-Point Arithmetic}.
15015 @node Exiting Portably
15016 @section Exiting Portably
15017 @cindex exiting portably
15019 A C or C++ program can exit with status @var{N} by returning
15020 @var{N} from the @code{main} function. Portable programs are supposed
15021 to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with
15022 status @code{EXIT_FAILURE} to fail, but in practice it is portable to
15023 fail by exiting with status 1, and test programs that assume Posix can
15024 fail by exiting with status values from 1 through 255. Programs on
15025 SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero
15026 status when @code{main} returned nonzero, but ancient systems like these
15027 are no longer of practical concern.
15029 A program can also exit with status @var{N} by passing @var{N} to the
15030 @code{exit} function, and a program can fail by calling the @code{abort}
15031 function. If a program is specialized to just some platforms, it can fail
15032 by calling functions specific to those platforms, e.g., @code{_exit}
15033 (Posix) and @code{_Exit} (C99). However, like other functions, an exit
15034 function should be declared, typically by including a header. For
15035 example, if a C program calls @code{exit}, it should include @file{stdlib.h}
15036 either directly or via the default includes (@pxref{Default Includes}).
15038 A program can fail due to undefined behavior such as dereferencing a null
15039 pointer, but this is not recommended as undefined behavior allows an
15040 implementation to do whatever it pleases and this includes exiting
15044 @c ================================================== Manual Configuration
15046 @node Manual Configuration
15047 @chapter Manual Configuration
15049 A few kinds of features can't be guessed automatically by running test
15050 programs. For example, the details of the object-file format, or
15051 special options that need to be passed to the compiler or linker. You
15052 can check for such features using ad-hoc means, such as having
15053 @command{configure} check the output of the @code{uname} program, or
15054 looking for libraries that are unique to particular systems. However,
15055 Autoconf provides a uniform method for handling unguessable features.
15058 * Specifying Names:: Specifying the system type
15059 * Canonicalizing:: Getting the canonical system type
15060 * Using System Type:: What to do with the system type
15063 @node Specifying Names
15064 @section Specifying the System Type
15065 @cindex System type
15067 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
15068 @command{configure} scripts can make decisions based on a canonical name
15069 for the system type, which has the form:
15070 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
15071 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
15073 @command{configure} can usually guess the canonical name for the type of
15074 system it's running on. To do so it runs a script called
15075 @command{config.guess}, which infers the name using the @code{uname}
15076 command or symbols predefined by the C preprocessor.
15078 Alternately, the user can specify the system type with command line
15079 arguments to @command{configure}. Doing so is necessary when
15080 cross-compiling. In the most complex case of cross-compiling, three
15081 system types are involved. The options to specify them are:
15084 @item --build=@var{build-type}
15085 the type of system on which the package is being configured and
15086 compiled. It defaults to the result of running @command{config.guess}.
15088 @item --host=@var{host-type}
15089 the type of system on which the package runs. By default it is the
15090 same as the build machine. Specifying it enables the cross-compilation
15093 @item --target=@var{target-type}
15094 the type of system for which any compiler tools in the package
15095 produce code (rarely needed). By default, it is the same as host.
15098 If you mean to override the result of @command{config.guess}, use
15099 @option{--build}, not @option{--host}, since the latter enables
15100 cross-compilation. For historical reasons, passing @option{--host} also
15101 changes the build type. Therefore, whenever you specify @option{--host},
15102 be sure to specify @option{--build} too; this will be fixed in the
15103 future. So, to enter cross-compilation mode, use a command like this
15106 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15110 Note that if you do not specify @option{--host}, @command{configure}
15111 fails if it can't run the code generated by the specified compiler. For
15112 example, configuring as follows fails:
15115 ./configure CC=m68k-coff-gcc
15118 In the future, when cross-compiling Autoconf will @emph{not}
15119 accept tools (compilers, linkers, assemblers) whose name is not
15120 prefixed with the host type. The only case when this may be
15121 useful is when you really are not cross-compiling, but only
15122 building for a least-common-denominator architecture: an example
15123 is building for @code{i386-pc-linux-gnu} while running on an
15124 @code{i686-pc-linux-gnu} architecture. In this case, some particular
15125 pairs might be similar enough to let you get away with the system
15126 compilers, but in general the compiler might make bogus assumptions
15127 on the host: if you know what you are doing, please create symbolic
15128 links from the host compiler to the build compiler.
15130 @cindex @command{config.sub}
15131 @command{configure} recognizes short aliases for many system types; for
15132 example, @samp{decstation} can be used instead of
15133 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
15134 @command{config.sub} to canonicalize system type aliases.
15136 This section deliberately omits the description of the obsolete
15137 interface; see @ref{Hosts and Cross-Compilation}.
15140 @node Canonicalizing
15141 @section Getting the Canonical System Type
15142 @cindex System type
15143 @cindex Canonical system type
15145 The following macros make the system type available to @command{configure}
15148 @ovindex build_alias
15149 @ovindex host_alias
15150 @ovindex target_alias
15152 The variables @samp{build_alias}, @samp{host_alias}, and
15153 @samp{target_alias} are always exactly the arguments of @option{--build},
15154 @option{--host}, and @option{--target}; in particular, they are left empty
15155 if the user did not use them, even if the corresponding
15156 @code{AC_CANONICAL} macro was run. Any configure script may use these
15157 variables anywhere. These are the variables that should be used when in
15158 interaction with the user.
15160 If you need to recognize some special environments based on their system
15161 type, run the following macros to get canonical system names. These
15162 variables are not set before the macro call.
15164 If you use these macros, you must distribute @command{config.guess} and
15165 @command{config.sub} along with your source code. @xref{Output}, for
15166 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
15167 to control in which directory @command{configure} looks for those scripts.
15170 @defmac AC_CANONICAL_BUILD
15171 @acindex{CANONICAL_BUILD}
15174 @ovindex build_vendor
15176 Compute the canonical build-system type variable, @code{build}, and its
15177 three individual parts @code{build_cpu}, @code{build_vendor}, and
15180 If @option{--build} was specified, then @code{build} is the
15181 canonicalization of @code{build_alias} by @command{config.sub},
15182 otherwise it is determined by the shell script @command{config.guess}.
15185 @defmac AC_CANONICAL_HOST
15186 @acindex{CANONICAL_HOST}
15189 @ovindex host_vendor
15191 Compute the canonical host-system type variable, @code{host}, and its
15192 three individual parts @code{host_cpu}, @code{host_vendor}, and
15195 If @option{--host} was specified, then @code{host} is the
15196 canonicalization of @code{host_alias} by @command{config.sub},
15197 otherwise it defaults to @code{build}.
15200 @defmac AC_CANONICAL_TARGET
15201 @acindex{CANONICAL_TARGET}
15203 @ovindex target_cpu
15204 @ovindex target_vendor
15206 Compute the canonical target-system type variable, @code{target}, and its
15207 three individual parts @code{target_cpu}, @code{target_vendor}, and
15210 If @option{--target} was specified, then @code{target} is the
15211 canonicalization of @code{target_alias} by @command{config.sub},
15212 otherwise it defaults to @code{host}.
15215 Note that there can be artifacts due to the backward compatibility
15216 code. See @xref{Hosts and Cross-Compilation}, for more.
15218 @node Using System Type
15219 @section Using the System Type
15221 In @file{configure.ac} the system type is generally used by one or more
15222 @code{case} statements to select system-specifics. Shell wildcards can
15223 be used to match a group of system types.
15225 For example, an extra assembler code object file could be chosen, giving
15226 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
15227 following would be used in a makefile to add the object to a
15228 program or library.
15232 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
15233 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
15236 AC_SUBST([CYCLE_OBJ])
15239 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
15240 to select variant source files, for example optimized code for some
15241 CPUs. The configured CPU type doesn't always indicate exact CPU types,
15242 so some runtime capability checks may be necessary too.
15246 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
15247 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
15248 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
15252 The host system type can also be used to find cross-compilation tools
15253 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
15255 The above examples all show @samp{$host}, since this is where the code
15256 is going to run. Only rarely is it necessary to test @samp{$build}
15257 (which is where the build is being done).
15259 Whenever you're tempted to use @samp{$host} it's worth considering
15260 whether some sort of probe would be better. New system types come along
15261 periodically or previously missing features are added. Well-written
15262 probes can adapt themselves to such things, but hard-coded lists of
15263 names can't. Here are some guidelines,
15267 Availability of libraries and library functions should always be checked
15270 Variant behavior of system calls is best identified with runtime tests
15271 if possible, but bug workarounds or obscure difficulties might have to
15272 be driven from @samp{$host}.
15274 Assembler code is inevitably highly CPU-specific and is best selected
15275 according to @samp{$host_cpu}.
15277 Assembler variations like underscore prefix on globals or ELF versus
15278 COFF type directives are however best determined by probing, perhaps
15279 even examining the compiler output.
15282 @samp{$target} is for use by a package creating a compiler or similar.
15283 For ordinary packages it's meaningless and should not be used. It
15284 indicates what the created compiler should generate code for, if it can
15285 cross-compile. @samp{$target} generally selects various hard-coded CPU
15286 and system conventions, since usually the compiler or tools under
15287 construction themselves determine how the target works.
15290 @c ===================================================== Site Configuration.
15292 @node Site Configuration
15293 @chapter Site Configuration
15295 @command{configure} scripts support several kinds of local configuration
15296 decisions. There are ways for users to specify where external software
15297 packages are, include or exclude optional features, install programs
15298 under modified names, and set default values for @command{configure}
15302 * Help Formatting:: Customizing @samp{configure --help}
15303 * External Software:: Working with other optional software
15304 * Package Options:: Selecting optional features
15305 * Pretty Help Strings:: Formatting help string
15306 * Site Details:: Configuring site details
15307 * Transforming Names:: Changing program names when installing
15308 * Site Defaults:: Giving @command{configure} local defaults
15311 @node Help Formatting
15312 @section Controlling Help Output
15314 Users consult @samp{configure --help} to learn of configuration
15315 decisions specific to your package. By default, @command{configure}
15316 breaks this output into sections for each type of option; within each
15317 section, help strings appear in the order @file{configure.ac} defines
15323 --enable-bar include bar
15330 @defmac AC_PRESERVE_HELP_ORDER
15331 @acindex{PRESERVE_HELP_ORDER}
15333 Request an alternate @option{--help} format, in which options of all
15334 types appear together, in the order defined. Call this macro before any
15335 @code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}.
15338 Optional Features and Packages:
15340 --enable-bar include bar
15346 @node External Software
15347 @section Working With External Software
15348 @cindex External software
15350 Some packages require, or can optionally use, other software packages
15351 that are already installed. The user can give @command{configure}
15352 command line options to specify which such external software to use.
15353 The options have one of these forms:
15355 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15358 --with-@var{package}[=@var{arg}]
15359 --without-@var{package}
15362 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
15363 instead of some other linker. @option{--with-x} means work with The X
15366 The user can give an argument by following the package name with
15367 @samp{=} and the argument. Giving an argument of @samp{no} is for
15368 packages that are used by default; it says to @emph{not} use the
15369 package. An argument that is neither @samp{yes} nor @samp{no} could
15370 include a name or number of a version of the other package, to specify
15371 more precisely which other package this program is supposed to work
15372 with. If no argument is given, it defaults to @samp{yes}.
15373 @option{--without-@var{package}} is equivalent to
15374 @option{--with-@var{package}=no}.
15376 @command{configure} scripts do not complain about
15377 @option{--with-@var{package}} options that they do not support. This
15378 behavior permits configuring a source tree containing multiple packages
15379 with a top-level @command{configure} script when the packages support
15380 different options, without spurious error messages about options that
15381 some of the packages support. An unfortunate side effect is that option
15382 spelling errors are not diagnosed. No better approach to this problem
15383 has been suggested so far.
15385 For each external software package that may be used, @file{configure.ac}
15386 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
15387 user asked to use it. Whether each package is used or not by default,
15388 and which arguments are valid, is up to you.
15390 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15392 If the user gave @command{configure} the option @option{--with-@var{package}}
15393 or @option{--without-@var{package}}, run shell commands
15394 @var{action-if-given}. If neither option was given, run shell commands
15395 @var{action-if-not-given}. The name @var{package} indicates another
15396 software package that this program should work with. It should consist
15397 only of alphanumeric characters and dashes.
15399 The option's argument is available to the shell commands
15400 @var{action-if-given} in the shell variable @code{withval}, which is
15401 actually just the value of the shell variable @code{with_@var{package}},
15402 with any @option{-} characters changed into @samp{_}. You may use that
15403 variable instead, if you wish.
15405 The argument @var{help-string} is a description of the option that
15408 --with-readline support fancy command line editing
15412 @var{help-string} may be more than one line long, if more detail is
15413 needed. Just make sure the columns line up in @samp{configure
15414 --help}. Avoid tabs in the help string. You'll need to enclose the
15415 help string in @samp{[} and @samp{]} in order to produce the leading
15418 You should format your @var{help-string} with the macro
15419 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15421 The following example shows how to use the @code{AC_ARG_WITH} macro in
15422 a common situation. You want to let the user decide whether to enable
15423 support for an external library (e.g., the readline library); if the user
15424 specified neither @option{--with-readline} nor @option{--without-readline},
15425 you want to enable support for readline only if the library is available
15428 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15430 AC_ARG_WITH([readline],
15431 [AS_HELP_STRING([--with-readline],
15432 [support fancy command line editing @@<:@@default=check@@:>@@])],
15434 [with_readline=check])
15437 AS_IF([test "x$with_readline" != xno],
15438 [AC_CHECK_LIB([readline], [main],
15439 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15440 AC_DEFINE([HAVE_LIBREADLINE], [1],
15441 [Define if you have libreadline])
15443 [if test "x$with_readline" != xcheck; then
15445 [--with-readline was given, but test for readline failed])
15450 The next example shows how to use @code{AC_ARG_WITH} to give the user the
15451 possibility to enable support for the readline library, in case it is still
15452 experimental and not well tested, and is therefore disabled by default.
15454 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15456 AC_ARG_WITH([readline],
15457 [AS_HELP_STRING([--with-readline],
15458 [enable experimental support for readline])],
15460 [with_readline=no])
15463 AS_IF([test "x$with_readline" != xno],
15464 [AC_CHECK_LIB([readline], [main],
15465 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15466 AC_DEFINE([HAVE_LIBREADLINE], [1],
15467 [Define if you have libreadline])
15470 [--with-readline was given, but test for readline failed])],
15474 The last example shows how to use @code{AC_ARG_WITH} to give the user the
15475 possibility to disable support for the readline library, given that it is
15476 an important feature and that it should be enabled by default.
15478 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
15480 AC_ARG_WITH([readline],
15481 [AS_HELP_STRING([--without-readline],
15482 [disable support for readline])],
15484 [with_readline=yes])
15487 AS_IF([test "x$with_readline" != xno],
15488 [AC_CHECK_LIB([readline], [main],
15489 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
15490 AC_DEFINE([HAVE_LIBREADLINE], [1],
15491 [Define if you have libreadline])
15494 [readline test failed (--without-readline to disable)])],
15498 These three examples can be easily adapted to the case where
15499 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
15500 @ref{Package Options}).
15503 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
15505 This is an obsolete version of @code{AC_ARG_WITH} that does not
15506 support providing a help string.
15509 @node Package Options
15510 @section Choosing Package Options
15511 @cindex Package options
15512 @cindex Options, package
15514 If a software package has optional compile-time features, the user can
15515 give @command{configure} command line options to specify whether to
15516 compile them. The options have one of these forms:
15518 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
15521 --enable-@var{feature}[=@var{arg}]
15522 --disable-@var{feature}
15525 These options allow users to choose which optional features to build and
15526 install. @option{--enable-@var{feature}} options should never make a
15527 feature behave differently or cause one feature to replace another.
15528 They should only cause parts of the program to be built rather than left
15531 The user can give an argument by following the feature name with
15532 @samp{=} and the argument. Giving an argument of @samp{no} requests
15533 that the feature @emph{not} be made available. A feature with an
15534 argument looks like @option{--enable-debug=stabs}. If no argument is
15535 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
15536 equivalent to @option{--enable-@var{feature}=no}.
15538 @command{configure} scripts do not complain about
15539 @option{--enable-@var{feature}} options that they do not support.
15540 This behavior permits configuring a source tree containing multiple
15541 packages with a top-level @command{configure} script when the packages
15542 support different options, without spurious error messages about options
15543 that some of the packages support.
15544 An unfortunate side effect is that option spelling errors are not diagnosed.
15545 No better approach to this problem has been suggested so far.
15547 For each optional feature, @file{configure.ac} should call
15548 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
15549 to include it. Whether each feature is included or not by default, and
15550 which arguments are valid, is up to you.
15552 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
15553 @acindex{ARG_ENABLE}
15554 If the user gave @command{configure} the option
15555 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
15556 shell commands @var{action-if-given}. If neither option was given, run
15557 shell commands @var{action-if-not-given}. The name @var{feature}
15558 indicates an optional user-level facility. It should consist only of
15559 alphanumeric characters and dashes.
15561 The option's argument is available to the shell commands
15562 @var{action-if-given} in the shell variable @code{enableval}, which is
15563 actually just the value of the shell variable
15564 @code{enable_@var{feature}}, with any @option{-} characters changed into
15565 @samp{_}. You may use that variable instead, if you wish. The
15566 @var{help-string} argument is like that of @code{AC_ARG_WITH}
15567 (@pxref{External Software}).
15569 You should format your @var{help-string} with the macro
15570 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
15572 See the examples suggested with the definition of @code{AC_ARG_WITH}
15573 (@pxref{External Software}) to get an idea of possible applications of
15574 @code{AC_ARG_ENABLE}.
15577 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
15579 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
15580 support providing a help string.
15584 @node Pretty Help Strings
15585 @section Making Your Help Strings Look Pretty
15586 @cindex Help strings
15588 Properly formatting the @samp{help strings} which are used in
15589 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
15590 (@pxref{Package Options}) can be challenging. Specifically, you want
15591 your own @samp{help strings} to line up in the appropriate columns of
15592 @samp{configure --help} just like the standard Autoconf @samp{help
15593 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
15595 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
15596 @acindex{HELP_STRING}
15598 Expands into an help string that looks pretty when the user executes
15599 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
15600 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
15601 Options}). The following example makes this clearer.
15605 [AS_HELP_STRING([--with-foo],
15606 [use foo (default is no)])],
15607 [use_foo=$withval],
15611 The second argument of @code{AS_HELP_STRING} is
15612 not a literal, and should not be double quoted.
15613 @xref{Autoconf Language}, for a more detailed explanation.
15614 Then the last few lines of @samp{configure --help} appear like
15618 --enable and --with options recognized:
15619 --with-foo use foo (default is no)
15622 The @code{AS_HELP_STRING} macro is particularly helpful when the
15623 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
15624 arguments, as shown in the following example.
15627 AC_DEFUN([MY_ARG_WITH],
15629 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
15630 [use_[]$1=$withval],
15637 @section Configuring Site Details
15638 @cindex Site details
15640 Some software packages require complex site-specific information. Some
15641 examples are host names to use for certain services, company names, and
15642 email addresses to contact. Since some configuration scripts generated
15643 by Metaconfig ask for such information interactively, people sometimes
15644 wonder how to get that information in Autoconf-generated configuration
15645 scripts, which aren't interactive.
15647 Such site configuration information should be put in a file that is
15648 edited @emph{only by users}, not by programs. The location of the file
15649 can either be based on the @code{prefix} variable, or be a standard
15650 location such as the user's home directory. It could even be specified
15651 by an environment variable. The programs should examine that file at
15652 runtime, rather than at compile time. Runtime configuration is more
15653 convenient for users and makes the configuration process simpler than
15654 getting the information while configuring. @xref{Directory Variables, ,
15655 Variables for Installation Directories, standards, @acronym{GNU} Coding
15656 Standards}, for more information on where to put data files.
15658 @node Transforming Names
15659 @section Transforming Program Names When Installing
15660 @cindex Transforming program names
15661 @cindex Program names, transforming
15663 Autoconf supports changing the names of programs when installing them.
15664 In order to use these transformations, @file{configure.ac} must call the
15665 macro @code{AC_ARG_PROGRAM}.
15667 @defmac AC_ARG_PROGRAM
15668 @acindex{ARG_PROGRAM}
15669 @ovindex program_transform_name
15670 Place in output variable @code{program_transform_name} a sequence of
15671 @code{sed} commands for changing the names of installed programs.
15673 If any of the options described below are given to @command{configure},
15674 program names are transformed accordingly. Otherwise, if
15675 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
15676 is given, the target type followed by a dash is used as a prefix.
15677 Otherwise, no program name transformation is done.
15681 * Transformation Options:: @command{configure} options to transform names
15682 * Transformation Examples:: Sample uses of transforming names
15683 * Transformation Rules:: Makefile uses of transforming names
15686 @node Transformation Options
15687 @subsection Transformation Options
15689 You can specify name transformations by giving @command{configure} these
15690 command line options:
15693 @item --program-prefix=@var{prefix}
15694 prepend @var{prefix} to the names;
15696 @item --program-suffix=@var{suffix}
15697 append @var{suffix} to the names;
15699 @item --program-transform-name=@var{expression}
15700 perform @code{sed} substitution @var{expression} on the names.
15703 @node Transformation Examples
15704 @subsection Transformation Examples
15706 These transformations are useful with programs that can be part of a
15707 cross-compilation development environment. For example, a
15708 cross-assembler running on a Sun 4 configured with
15709 @option{--target=i960-vxworks} is normally installed as
15710 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
15711 with a native Sun 4 assembler.
15713 You can force a program name to begin with @file{g}, if you don't want
15714 @acronym{GNU} programs installed on your system to shadow other programs with
15715 the same name. For example, if you configure @acronym{GNU} @code{diff} with
15716 @option{--program-prefix=g}, then when you run @samp{make install} it is
15717 installed as @file{/usr/local/bin/gdiff}.
15719 As a more sophisticated example, you could use
15722 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
15726 to prepend @samp{g} to most of the program names in a source tree,
15727 excepting those like @code{gdb} that already have one and those like
15728 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
15729 assuming that you have a source tree containing those programs that is
15730 set up to use this feature.)
15732 One way to install multiple versions of some programs simultaneously is
15733 to append a version number to the name of one or both. For example, if
15734 you want to keep Autoconf version 1 around for awhile, you can configure
15735 Autoconf version 2 using @option{--program-suffix=2} to install the
15736 programs as @file{/usr/local/bin/autoconf2},
15737 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
15738 that only the binaries are renamed, therefore you'd have problems with
15739 the library files which might overlap.
15741 @node Transformation Rules
15742 @subsection Transformation Rules
15744 Here is how to use the variable @code{program_transform_name} in a
15745 @file{Makefile.in}:
15748 PROGRAMS = cp ls rm
15749 transform = @@program_transform_name@@
15751 for p in $(PROGRAMS); do \
15752 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
15753 sed '$(transform)'`; \
15757 for p in $(PROGRAMS); do \
15758 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
15762 It is guaranteed that @code{program_transform_name} is never empty, and
15763 that there are no useless separators. Therefore you may safely embed
15764 @code{program_transform_name} within a sed program using @samp{;}:
15767 transform = @@program_transform_name@@
15768 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
15771 Whether to do the transformations on documentation files (Texinfo or
15772 @code{man}) is a tricky question; there seems to be no perfect answer,
15773 due to the several reasons for name transforming. Documentation is not
15774 usually particular to a specific architecture, and Texinfo files do not
15775 conflict with system documentation. But they might conflict with
15776 earlier versions of the same files, and @code{man} pages sometimes do
15777 conflict with system documentation. As a compromise, it is probably
15778 best to do name transformations on @code{man} pages but not on Texinfo
15781 @node Site Defaults
15782 @section Setting Site Defaults
15783 @cindex Site defaults
15785 Autoconf-generated @command{configure} scripts allow your site to provide
15786 default values for some configuration values. You do this by creating
15787 site- and system-wide initialization files.
15789 @evindex CONFIG_SITE
15790 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
15791 uses its value as the name of a shell script to read. Otherwise, it
15792 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
15793 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
15794 settings in machine-specific files override those in machine-independent
15795 ones in case of conflict.
15797 Site files can be arbitrary shell scripts, but only certain kinds of
15798 code are really appropriate to be in them. Because @command{configure}
15799 reads any cache file after it has read any site files, a site file can
15800 define a default cache file to be shared between all Autoconf-generated
15801 @command{configure} scripts run on that system (@pxref{Cache Files}). If
15802 you set a default cache file in a site file, it is a good idea to also
15803 set the output variable @code{CC} in that site file, because the cache
15804 file is only valid for a particular compiler, but many systems have
15807 You can examine or override the value set by a command line option to
15808 @command{configure} in a site file; options set shell variables that have
15809 the same names as the options, with any dashes turned into underscores.
15810 The exceptions are that @option{--without-} and @option{--disable-} options
15811 are like giving the corresponding @option{--with-} or @option{--enable-}
15812 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
15813 sets the variable @code{cache_file} to the value @samp{localcache};
15814 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
15815 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
15816 variable @code{prefix} to the value @samp{/usr}; etc.
15818 Site files are also good places to set default values for other output
15819 variables, such as @code{CFLAGS}, if you need to give them non-default
15820 values: anything you would normally do, repetitively, on the command
15821 line. If you use non-default values for @var{prefix} or
15822 @var{exec_prefix} (wherever you locate the site file), you can set them
15823 in the site file if you specify it with the @code{CONFIG_SITE}
15824 environment variable.
15826 You can set some cache values in the site file itself. Doing this is
15827 useful if you are cross-compiling, where it is impossible to check features
15828 that require running a test program. You could ``prime the cache'' by
15829 setting those values correctly for that system in
15830 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
15831 variables you need to set, look for shell variables with @samp{_cv_} in
15832 their names in the affected @command{configure} scripts, or in the Autoconf
15833 M4 source code for those macros.
15835 The cache file is careful to not override any variables set in the site
15836 files. Similarly, you should not override command-line options in the
15837 site files. Your code should check that variables such as @code{prefix}
15838 and @code{cache_file} have their default values (as set near the top of
15839 @command{configure}) before changing them.
15841 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
15842 command @samp{configure --prefix=/usr/share/local/gnu} would read this
15843 file (if @code{CONFIG_SITE} is not set to a different file).
15846 # config.site for configure
15848 # Change some defaults.
15849 test "$prefix" = NONE && prefix=/usr/share/local/gnu
15850 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
15851 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
15852 test "$localstatedir" = '$prefix/var' && localstatedir=/var
15854 # Give Autoconf 2.x generated configure scripts a shared default
15855 # cache file for feature test results, architecture-specific.
15856 if test "$cache_file" = /dev/null; then
15857 cache_file="$prefix/var/config.cache"
15858 # A cache file is only valid for one C compiler.
15864 @c ============================================== Running configure Scripts.
15866 @node Running configure Scripts
15867 @chapter Running @command{configure} Scripts
15868 @cindex @command{configure}
15870 Below are instructions on how to configure a package that uses a
15871 @command{configure} script, suitable for inclusion as an @file{INSTALL}
15872 file in the package. A plain-text version of @file{INSTALL} which you
15873 may use comes with Autoconf.
15876 * Basic Installation:: Instructions for typical cases
15877 * Compilers and Options:: Selecting compilers and optimization
15878 * Multiple Architectures:: Compiling for multiple architectures at once
15879 * Installation Names:: Installing in different directories
15880 * Optional Features:: Selecting optional features
15881 * System Type:: Specifying the system type
15882 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
15883 * Defining Variables:: Specifying the compiler etc.
15884 * configure Invocation:: Changing how @command{configure} runs
15888 @include install.texi
15891 @c ============================================== Recreating a Configuration
15893 @node config.status Invocation
15894 @chapter Recreating a Configuration
15895 @cindex @command{config.status}
15897 The @command{configure} script creates a file named @file{config.status},
15898 which actually configures, @dfn{instantiates}, the template files. It
15899 also records the configuration options that were specified when the
15900 package was last configured in case reconfiguring is needed.
15904 ./config.status @var{option}@dots{} [@var{file}@dots{}]
15907 It configures the @var{files}; if none are specified, all the templates
15908 are instantiated. The files must be specified without their
15909 dependencies, as in
15912 ./config.status foobar
15919 ./config.status foobar:foo.in:bar.in
15922 The supported options are:
15927 Print a summary of the command line options, the list of the template
15932 Print the version number of Autoconf and the configuration settings,
15938 Do not print progress messages.
15942 Don't remove the temporary files.
15944 @item --file=@var{file}[:@var{template}]
15945 Require that @var{file} be instantiated as if
15946 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
15947 @var{file} and @var{template} may be @samp{-} in which case the standard
15948 output and/or standard input, respectively, is used. If a
15949 @var{template} file name is relative, it is first looked for in the build
15950 tree, and then in the source tree. @xref{Configuration Actions}, for
15953 This option and the following ones provide one way for separately
15954 distributed packages to share the values computed by @command{configure}.
15955 Doing so can be useful if some of the packages need a superset of the
15956 features that one of them, perhaps a common library, does. These
15957 options allow a @file{config.status} file to create files other than the
15958 ones that its @file{configure.ac} specifies, so it can be used for a
15961 @item --header=@var{file}[:@var{template}]
15962 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
15965 Ask @file{config.status} to update itself and exit (no instantiation).
15966 This option is useful if you change @command{configure}, so that the
15967 results of some tests might be different from the previous run. The
15968 @option{--recheck} option reruns @command{configure} with the same arguments
15969 you used before, plus the @option{--no-create} option, which prevents
15970 @command{configure} from running @file{config.status} and creating
15971 @file{Makefile} and other files, and the @option{--no-recursion} option,
15972 which prevents @command{configure} from running other @command{configure}
15973 scripts in subdirectories. (This is so other Make rules can
15974 run @file{config.status} when it changes; @pxref{Automatic Remaking},
15978 @file{config.status} checks several optional environment variables that
15979 can alter its behavior:
15981 @defvar CONFIG_SHELL
15982 @evindex CONFIG_SHELL
15983 The shell with which to run @command{configure} for the @option{--recheck}
15984 option. It must be Bourne-compatible. The default is a shell that
15985 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
15986 Invoking @command{configure} by hand bypasses this setting, so you may
15987 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
15988 to insure that the same shell is used everywhere. The absolute name of the
15989 shell should be passed.
15992 @defvar CONFIG_STATUS
15993 @evindex CONFIG_STATUS
15994 The file name to use for the shell script that records the
15995 configuration. The default is @file{./config.status}. This variable is
15996 useful when one package uses parts of another and the @command{configure}
15997 scripts shouldn't be merged because they are maintained separately.
16000 You can use @file{./config.status} in your makefiles. For example, in
16001 the dependencies given above (@pxref{Automatic Remaking}),
16002 @file{config.status} is run twice when @file{configure.ac} has changed.
16003 If that bothers you, you can make each run only regenerate the files for
16008 stamp-h: config.h.in config.status
16009 ./config.status config.h
16012 Makefile: Makefile.in config.status
16013 ./config.status Makefile
16017 The calling convention of @file{config.status} has changed; see
16018 @ref{Obsolete config.status Use}, for details.
16021 @c =================================================== Obsolete Constructs
16023 @node Obsolete Constructs
16024 @chapter Obsolete Constructs
16025 @cindex Obsolete constructs
16027 Autoconf changes, and throughout the years some constructs have been
16028 obsoleted. Most of the changes involve the macros, but in some cases
16029 the tools themselves, or even some concepts, are now considered
16032 You may completely skip this chapter if you are new to Autoconf. Its
16033 intention is mainly to help maintainers updating their packages by
16034 understanding how to move to more modern constructs.
16037 * Obsolete config.status Use:: Different calling convention
16038 * acconfig.h:: Additional entries in @file{config.h.in}
16039 * autoupdate Invocation:: Automatic update of @file{configure.ac}
16040 * Obsolete Macros:: Backward compatibility macros
16041 * Autoconf 1:: Tips for upgrading your files
16042 * Autoconf 2.13:: Some fresher tips
16045 @node Obsolete config.status Use
16046 @section Obsolete @file{config.status} Invocation
16048 @file{config.status} now supports arguments to specify the files to
16049 instantiate; see @ref{config.status Invocation}, for more details.
16050 Before, environment variables had to be used.
16052 @defvar CONFIG_COMMANDS
16053 @evindex CONFIG_COMMANDS
16054 The tags of the commands to execute. The default is the arguments given
16055 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
16056 @file{configure.ac}.
16059 @defvar CONFIG_FILES
16060 @evindex CONFIG_FILES
16061 The files in which to perform @samp{@@@var{variable}@@} substitutions.
16062 The default is the arguments given to @code{AC_OUTPUT} and
16063 @code{AC_CONFIG_FILES} in @file{configure.ac}.
16066 @defvar CONFIG_HEADERS
16067 @evindex CONFIG_HEADERS
16068 The files in which to substitute C @code{#define} statements. The
16069 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
16070 macro was not called, @file{config.status} ignores this variable.
16073 @defvar CONFIG_LINKS
16074 @evindex CONFIG_LINKS
16075 The symbolic links to establish. The default is the arguments given to
16076 @code{AC_CONFIG_LINKS}; if that macro was not called,
16077 @file{config.status} ignores this variable.
16080 In @ref{config.status Invocation}, using this old interface, the example
16086 stamp-h: config.h.in config.status
16087 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
16088 CONFIG_HEADERS=config.h ./config.status
16091 Makefile: Makefile.in config.status
16092 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
16093 CONFIG_FILES=Makefile ./config.status
16098 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
16099 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
16100 for @code{CONFIG_COMMANDS}, etc.)
16104 @section @file{acconfig.h}
16106 @cindex @file{acconfig.h}
16107 @cindex @file{config.h.top}
16108 @cindex @file{config.h.bot}
16110 In order to produce @file{config.h.in}, @command{autoheader} needs to
16111 build or to find templates for each symbol. Modern releases of Autoconf
16112 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
16113 Macros}), but in older releases a file, @file{acconfig.h}, contained the
16114 list of needed templates. @command{autoheader} copied comments and
16115 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
16116 the current directory, if present. This file used to be mandatory if
16117 you @code{AC_DEFINE} any additional symbols.
16119 Modern releases of Autoconf also provide @code{AH_TOP} and
16120 @code{AH_BOTTOM} if you need to prepend/append some information to
16121 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
16122 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
16123 @command{autoheader} copies the lines before the line containing
16124 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
16125 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
16126 @command{autoheader} copies the lines after that line to the end of the
16127 file it generates. Either or both of those strings may be omitted. An
16128 even older alternate way to produce the same effect in ancient versions
16129 of Autoconf is to create the files @file{@var{file}.top} (typically
16130 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
16131 directory. If they exist, @command{autoheader} copies them to the
16132 beginning and end, respectively, of its output.
16134 In former versions of Autoconf, the files used in preparing a software
16135 package for distribution were:
16138 configure.ac --. .------> autoconf* -----> configure
16140 [aclocal.m4] --+ `---.
16142 +--> [autoheader*] -> [config.h.in]
16143 [acconfig.h] ----. |
16150 Using only the @code{AH_} macros, @file{configure.ac} should be
16151 self-contained, and should not depend upon @file{acconfig.h} etc.
16154 @node autoupdate Invocation
16155 @section Using @command{autoupdate} to Modernize @file{configure.ac}
16156 @cindex @command{autoupdate}
16158 The @command{autoupdate} program updates a @file{configure.ac} file that
16159 calls Autoconf macros by their old names to use the current macro names.
16160 In version 2 of Autoconf, most of the macros were renamed to use a more
16161 uniform and descriptive naming scheme. @xref{Macro Names}, for a
16162 description of the new scheme. Although the old names still work
16163 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
16164 new names), you can make your @file{configure.ac} files more readable
16165 and make it easier to use the current Autoconf documentation if you
16166 update them to use the new macro names.
16168 @evindex SIMPLE_BACKUP_SUFFIX
16169 If given no arguments, @command{autoupdate} updates @file{configure.ac},
16170 backing up the original version with the suffix @file{~} (or the value
16171 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
16172 set). If you give @command{autoupdate} an argument, it reads that file
16173 instead of @file{configure.ac} and writes the updated file to the
16177 @command{autoupdate} accepts the following options:
16182 Print a summary of the command line options and exit.
16186 Print the version number of Autoconf and exit.
16190 Report processing steps.
16194 Don't remove the temporary files.
16198 Force the update even if the file has not changed. Disregard the cache.
16200 @item --include=@var{dir}
16201 @itemx -I @var{dir}
16202 Also look for input files in @var{dir}. Multiple invocations accumulate.
16203 Directories are browsed from last to first.
16206 @node Obsolete Macros
16207 @section Obsolete Macros
16209 Several macros are obsoleted in Autoconf, for various reasons (typically
16210 they failed to quote properly, couldn't be extended for more recent
16211 issues, etc.). They are still supported, but deprecated: their use
16214 During the jump from Autoconf version 1 to version 2, most of the
16215 macros were renamed to use a more uniform and descriptive naming scheme,
16216 but their signature did not change. @xref{Macro Names}, for a
16217 description of the new naming scheme. Below, if there is just the mapping
16218 from old names to new names for these macros, the reader is invited to
16219 refer to the definition of the new macro for the signature and the
16224 @code{AC_FUNC_ALLOCA}
16227 @defmac AC_ARG_ARRAY
16228 @acindex{ARG_ARRAY}
16229 removed because of limited usefulness
16234 This macro is obsolete; it does nothing.
16237 @defmac AC_C_LONG_DOUBLE
16238 @acindex{C_LONG_DOUBLE}
16239 @cvindex HAVE_LONG_DOUBLE
16240 If the C compiler supports a working @code{long double} type with more
16241 range or precision than the @code{double} type, define
16242 @code{HAVE_LONG_DOUBLE}.
16244 You should use @code{AC_TYPE_LONG_DOUBLE} or
16245 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16248 @defmac AC_CANONICAL_SYSTEM
16249 @acindex{CANONICAL_SYSTEM}
16250 Determine the system type and set output variables to the names of the
16251 canonical system types. @xref{Canonicalizing}, for details about the
16252 variables this macro sets.
16254 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
16255 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
16256 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
16260 @defmac AC_CHAR_UNSIGNED
16261 @acindex{CHAR_UNSIGNED}
16262 @code{AC_C_CHAR_UNSIGNED}
16265 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
16266 @acindex{CHECK_TYPE}
16267 Autoconf, up to 2.13, used to provide this version of
16268 @code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although
16269 it is a member of the @code{CHECK} clan, it does
16270 more than just checking. Secondly, missing types are defined
16271 using @code{#define}, not @code{typedef}, and this can lead to
16272 problems in the case of pointer types.
16274 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
16275 @ref{Generic Types}, for the description of the current macro.
16277 If the type @var{type} is not defined, define it to be the C (or C++)
16278 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
16280 This macro is equivalent to:
16283 AC_CHECK_TYPE([@var{type}], [],
16284 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
16285 [Define to `@var{default}'
16286 if <sys/types.h> does not define.])])
16289 In order to keep backward compatibility, the two versions of
16290 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
16294 If there are three or four arguments, the modern version is used.
16297 If the second argument appears to be a C or C++ type, then the
16298 obsolete version is used. This happens if the argument is a C or C++
16299 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
16300 followed by one of @samp{[(* } and then by a string of zero or more
16301 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
16304 If the second argument is spelled with the alphabet of valid C and C++
16305 types, the user is warned and the modern version is used.
16308 Otherwise, the modern version is used.
16312 You are encouraged either to use a valid builtin type, or to use the
16313 equivalent modern code (see above), or better yet, to use
16314 @code{AC_CHECK_TYPES} together with
16318 typedef loff_t off_t;
16322 @c end of AC_CHECK_TYPE
16324 @defmac AC_CHECKING (@var{feature-description})
16326 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
16329 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false})
16330 @acindex{COMPILE_CHECK}
16331 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
16332 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
16333 addition that it prints @samp{checking for @var{echo-text}} to the
16334 standard output first, if @var{echo-text} is non-empty. Use
16335 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
16336 messages (@pxref{Printing Messages}).
16344 @defmac AC_CROSS_CHECK
16345 @acindex{CROSS_CHECK}
16346 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
16352 Check for the Cygwin environment in which case the shell variable
16353 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
16354 means to check the nature of the host is using
16355 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
16358 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
16360 *cygwin* ) CYGWIN=yes;;
16365 Beware that the variable @code{CYGWIN} has a special meaning when
16366 running Cygwin, and should not be changed. That's yet another reason
16367 not to use this macro.
16370 @defmac AC_DECL_SYS_SIGLIST
16371 @acindex{DECL_SYS_SIGLIST}
16372 @cvindex SYS_SIGLIST_DECLARED
16376 AC_CHECK_DECLS([sys_siglist], [], [],
16377 [#include <signal.h>
16378 /* NetBSD declares sys_siglist in unistd.h. */
16380 # include <unistd.h>
16386 @defmac AC_DECL_YYTEXT
16387 @acindex{DECL_YYTEXT}
16388 Does nothing, now integrated in @code{AC_PROG_LEX}.
16391 @defmac AC_DIR_HEADER
16392 @acindex{DIR_HEADER}
16397 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
16398 but defines a different set of C preprocessor macros to indicate which
16399 header file is found:
16401 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
16402 @item Header @tab Old Symbol @tab New Symbol
16403 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
16404 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
16405 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
16406 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
16410 @defmac AC_DYNIX_SEQ
16411 @acindex{DYNIX_SEQ}
16412 If on DYNIX/ptx, add @option{-lseq} to output variable
16413 @code{LIBS}. This macro used to be defined as
16416 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
16420 now it is just @code{AC_FUNC_GETMNTENT}.
16426 Defined the output variable @code{EXEEXT} based on the output of the
16427 compiler, which is now done automatically. Typically set to empty
16428 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
16433 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
16434 and sets @code{EMXOS2}.
16439 @code{AC_MSG_ERROR}
16447 @defmac AC_FIND_XTRA
16448 @acindex{FIND_XTRA}
16449 @code{AC_PATH_XTRA}
16454 @code{m4_foreach_w}
16457 @defmac AC_FUNC_CHECK
16458 @acindex{FUNC_CHECK}
16459 @code{AC_CHECK_FUNC}
16462 @defmac AC_FUNC_WAIT3
16463 @acindex{FUNC_WAIT3}
16464 @cvindex HAVE_WAIT3
16465 If @code{wait3} is found and fills in the contents of its third argument
16466 (a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define
16469 These days portable programs should use @code{waitpid}, not
16470 @code{wait3}, as @code{wait3} has been removed from Posix.
16473 @defmac AC_GCC_TRADITIONAL
16474 @acindex{GCC_TRADITIONAL}
16475 @code{AC_PROG_GCC_TRADITIONAL}
16478 @defmac AC_GETGROUPS_T
16479 @acindex{GETGROUPS_T}
16480 @code{AC_TYPE_GETGROUPS}
16483 @defmac AC_GETLOADAVG
16484 @acindex{GETLOADAVG}
16485 @code{AC_FUNC_GETLOADAVG}
16488 @defmac AC_HAVE_FUNCS
16489 @acindex{HAVE_FUNCS}
16490 @code{AC_CHECK_FUNCS}
16493 @defmac AC_HAVE_HEADERS
16494 @acindex{HAVE_HEADERS}
16495 @code{AC_CHECK_HEADERS}
16498 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
16499 @acindex{HAVE_LIBRARY}
16500 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
16501 @var{function} argument of @code{main}. In addition, @var{library} can
16502 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
16503 all of those cases, the compiler is passed @option{-lfoo}. However,
16504 @var{library} cannot be a shell variable; it must be a literal name.
16507 @defmac AC_HAVE_POUNDBANG
16508 @acindex{HAVE_POUNDBANG}
16509 @code{AC_SYS_INTERPRETER} (different calling convention)
16512 @defmac AC_HEADER_CHECK
16513 @acindex{HEADER_CHECK}
16514 @code{AC_CHECK_HEADER}
16517 @defmac AC_HEADER_EGREP
16518 @acindex{HEADER_EGREP}
16519 @code{AC_EGREP_HEADER}
16522 @defmac AC_HELP_STRING
16523 @acindex{HELP_STRING}
16524 @code{AS_HELP_STRING}
16527 @defmac AC_INIT (@var{unique-file-in-source-dir})
16529 Formerly @code{AC_INIT} used to have a single argument, and was
16534 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
16543 @defmac AC_INT_16_BITS
16544 @acindex{INT_16_BITS}
16545 @cvindex INT_16_BITS
16546 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
16547 Use @samp{AC_CHECK_SIZEOF(int)} instead.
16550 @defmac AC_IRIX_SUN
16552 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
16553 @code{LIBS}. If you were using it to get @code{getmntent}, use
16554 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
16555 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
16556 getpwnam)}. Up to Autoconf 2.13, it used to be
16559 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
16563 now it is defined as
16567 AC_CHECK_LIB([sun], [getpwnam])
16573 Same as @samp{AC_LANG([C])}.
16576 @defmac AC_LANG_CPLUSPLUS
16577 @acindex{LANG_CPLUSPLUS}
16578 Same as @samp{AC_LANG([C++])}.
16581 @defmac AC_LANG_FORTRAN77
16582 @acindex{LANG_FORTRAN77}
16583 Same as @samp{AC_LANG([Fortran 77])}.
16586 @defmac AC_LANG_RESTORE
16587 @acindex{LANG_RESTORE}
16588 Select the @var{language} that is saved on the top of the stack, as set
16589 by @code{AC_LANG_SAVE}, remove it from the stack, and call
16590 @code{AC_LANG(@var{language})}.
16593 @defmac AC_LANG_SAVE
16594 @acindex{LANG_SAVE}
16595 Remember the current language (as set by @code{AC_LANG}) on a stack.
16596 The current language does not change. @code{AC_LANG_PUSH} is preferred.
16599 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
16600 @acindex{LINK_FILES}
16601 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
16605 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
16613 AC_CONFIG_LINKS([host.h:config/$machine.h
16614 object.h:config/$obj_format.h])
16620 @code{AC_PROG_LN_S}
16623 @defmac AC_LONG_64_BITS
16624 @acindex{LONG_64_BITS}
16625 @cvindex LONG_64_BITS
16626 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
16627 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
16630 @defmac AC_LONG_DOUBLE
16631 @acindex{LONG_DOUBLE}
16632 If the C compiler supports a working @code{long double} type with more
16633 range or precision than the @code{double} type, define
16634 @code{HAVE_LONG_DOUBLE}.
16636 You should use @code{AC_TYPE_LONG_DOUBLE} or
16637 @code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}.
16640 @defmac AC_LONG_FILE_NAMES
16641 @acindex{LONG_FILE_NAMES}
16642 @code{AC_SYS_LONG_FILE_NAMES}
16645 @defmac AC_MAJOR_HEADER
16646 @acindex{MAJOR_HEADER}
16647 @code{AC_HEADER_MAJOR}
16650 @defmac AC_MEMORY_H
16652 @cvindex NEED_MEMORY_H
16653 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
16654 defined in @file{memory.h}. Today it is equivalent to
16655 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
16656 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
16662 Similar to @code{AC_CYGWIN} but checks for the MinGW compiler
16663 environment and sets @code{MINGW32}.
16666 @defmac AC_MINUS_C_MINUS_O
16667 @acindex{MINUS_C_MINUS_O}
16668 @code{AC_PROG_CC_C_O}
16673 @code{AC_FUNC_MMAP}
16678 @code{AC_TYPE_MODE_T}
16684 Defined the output variable @code{OBJEXT} based on the output of the
16685 compiler, after .c files have been excluded. Typically set to @samp{o}
16686 if Posix, @samp{obj} if a @acronym{DOS} variant.
16687 Now the compiler checking macros handle
16688 this automatically.
16691 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
16693 Make M4 print a message to the standard error output warning that
16694 @var{this-macro-name} is obsolete, and giving the file and line number
16695 where it was called. @var{this-macro-name} should be the name of the
16696 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
16697 it is printed at the end of the warning message; for example, it can be
16698 a suggestion for what to use instead of @var{this-macro-name}.
16703 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
16706 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
16707 services to the user.
16712 @code{AC_TYPE_OFF_T}
16715 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
16717 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
16718 interface is equivalent to:
16722 AC_CONFIG_FILES(@var{file}@dots{})
16723 AC_CONFIG_COMMANDS([default],
16724 @var{extra-cmds}, @var{init-cmds})
16730 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
16731 @acindex{OUTPUT_COMMANDS}
16732 Specify additional shell commands to run at the end of
16733 @file{config.status}, and shell commands to initialize any variables
16734 from @command{configure}. This macro may be called multiple times. It is
16735 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
16737 Here is an unrealistic example:
16741 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
16743 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
16747 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
16748 additional key, an important difference is that
16749 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
16750 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
16751 can safely be given macro calls as arguments:
16754 AC_CONFIG_COMMANDS(foo, [my_FOO()])
16758 Conversely, where one level of quoting was enough for literal strings
16759 with @code{AC_OUTPUT_COMMANDS}, you need two with
16760 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
16764 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
16765 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
16772 @code{AC_TYPE_PID_T}
16777 @code{AC_PREFIX_PROGRAM}
16780 @defmac AC_PROGRAMS_CHECK
16781 @acindex{PROGRAMS_CHECK}
16782 @code{AC_CHECK_PROGS}
16785 @defmac AC_PROGRAMS_PATH
16786 @acindex{PROGRAMS_PATH}
16787 @code{AC_PATH_PROGS}
16790 @defmac AC_PROGRAM_CHECK
16791 @acindex{PROGRAM_CHECK}
16792 @code{AC_CHECK_PROG}
16795 @defmac AC_PROGRAM_EGREP
16796 @acindex{PROGRAM_EGREP}
16797 @code{AC_EGREP_CPP}
16800 @defmac AC_PROGRAM_PATH
16801 @acindex{PROGRAM_PATH}
16802 @code{AC_PATH_PROG}
16805 @defmac AC_REMOTE_TAPE
16806 @acindex{REMOTE_TAPE}
16807 removed because of limited usefulness
16810 @defmac AC_RESTARTABLE_SYSCALLS
16811 @acindex{RESTARTABLE_SYSCALLS}
16812 @code{AC_SYS_RESTARTABLE_SYSCALLS}
16815 @defmac AC_RETSIGTYPE
16816 @acindex{RETSIGTYPE}
16817 @code{AC_TYPE_SIGNAL}
16822 removed because of limited usefulness
16825 @defmac AC_SCO_INTL
16828 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
16829 macro used to do this:
16832 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
16836 Now it just calls @code{AC_FUNC_STRFTIME} instead.
16839 @defmac AC_SETVBUF_REVERSED
16840 @acindex{SETVBUF_REVERSED}
16841 @code{AC_FUNC_SETVBUF_REVERSED}
16844 @defmac AC_SET_MAKE
16846 @code{AC_PROG_MAKE_SET}
16849 @defmac AC_SIZEOF_TYPE
16850 @acindex{SIZEOF_TYPE}
16851 @code{AC_CHECK_SIZEOF}
16856 @code{AC_TYPE_SIZE_T}
16859 @defmac AC_STAT_MACROS_BROKEN
16860 @acindex{STAT_MACROS_BROKEN}
16861 @code{AC_HEADER_STAT}
16864 @defmac AC_STDC_HEADERS
16865 @acindex{STDC_HEADERS}
16866 @code{AC_HEADER_STDC}
16871 @code{AC_FUNC_STRCOLL}
16874 @defmac AC_ST_BLKSIZE
16875 @acindex{ST_BLKSIZE}
16876 @code{AC_CHECK_MEMBERS}
16879 @defmac AC_ST_BLOCKS
16880 @acindex{ST_BLOCKS}
16881 @code{AC_STRUCT_ST_BLOCKS}
16886 @code{AC_CHECK_MEMBERS}
16889 @defmac AC_SYS_RESTARTABLE_SYSCALLS
16890 @acindex{SYS_RESTARTABLE_SYSCALLS}
16891 @cvindex HAVE_RESTARTABLE_SYSCALLS
16892 If the system automatically restarts a system call that is interrupted
16893 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
16894 not check whether system calls are restarted in general---it checks whether a
16895 signal handler installed with @code{signal} (but not @code{sigaction})
16896 causes system calls to be restarted. It does not check whether system calls
16897 can be restarted when interrupted by signals that have no handler.
16899 These days portable programs should use @code{sigaction} with
16900 @code{SA_RESTART} if they want restartable system calls. They should
16901 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
16902 system call is restartable is a dynamic issue, not a configuration-time
16906 @defmac AC_SYS_SIGLIST_DECLARED
16907 @acindex{SYS_SIGLIST_DECLARED}
16908 @code{AC_DECL_SYS_SIGLIST}
16911 @defmac AC_TEST_CPP
16913 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
16916 @defmac AC_TEST_PROGRAM
16917 @acindex{TEST_PROGRAM}
16918 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
16921 @defmac AC_TIMEZONE
16923 @code{AC_STRUCT_TIMEZONE}
16926 @defmac AC_TIME_WITH_SYS_TIME
16927 @acindex{TIME_WITH_SYS_TIME}
16928 @code{AC_HEADER_TIME}
16931 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16932 @acindex{TRY_COMPILE}
16937 [AC_LANG_PROGRAM([[@var{includes}]],
16938 [[@var{function-body}]])],
16939 [@var{action-if-true}],
16940 [@var{action-if-false}])
16944 @xref{Running the Compiler}.
16946 This macro double quotes both @var{includes} and @var{function-body}.
16948 For C and C++, @var{includes} is any @code{#include} statements needed
16949 by the code in @var{function-body} (@var{includes} is ignored if
16950 the currently selected language is Fortran or Fortran 77). The compiler
16951 and compilation flags are determined by the current language
16952 (@pxref{Language Choice}).
16955 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
16961 [AC_LANG_SOURCE([[@var{input}]])],
16962 [@var{action-if-true}],
16963 [@var{action-if-false}])
16967 @xref{Running the Preprocessor}.
16969 This macro double quotes the @var{input}.
16972 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false})
16978 [AC_LANG_PROGRAM([[@var{includes}]],
16979 [[@var{function-body}]])],
16980 [@var{action-if-true}],
16981 [@var{action-if-false}])
16985 @xref{Running the Compiler}.
16987 This macro double quotes both @var{includes} and @var{function-body}.
16989 Depending on the current language (@pxref{Language Choice}), create a
16990 test program to see whether a function whose body consists of
16991 @var{function-body} can be compiled and linked. If the file compiles
16992 and links successfully, run shell commands @var{action-if-found},
16993 otherwise run @var{action-if-not-found}.
16995 This macro double quotes both @var{includes} and @var{function-body}.
16997 For C and C++, @var{includes} is any @code{#include} statements needed
16998 by the code in @var{function-body} (@var{includes} is ignored if
16999 the currently selected language is Fortran or Fortran 77). The compiler
17000 and compilation flags are determined by the current language
17001 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
17002 @code{LIBS} are used for linking.
17005 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
17006 @acindex{TRY_LINK_FUNC}
17007 This macro is equivalent to
17008 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])],
17009 [@var{action-if-found}], [@var{action-if-not-found}])}.
17012 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
17018 [AC_LANG_SOURCE([[@var{program}]])],
17019 [@var{action-if-true}],
17020 [@var{action-if-false}],
17021 [@var{action-if-cross-compiling}])
17030 @code{AC_TYPE_UID_T}
17033 @defmac AC_UNISTD_H
17035 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
17041 Define @code{USG} if the @acronym{BSD} string functions are defined in
17042 @file{strings.h}. You should no longer depend upon @code{USG}, but on
17043 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
17046 @defmac AC_UTIME_NULL
17047 @acindex{UTIME_NULL}
17048 @code{AC_FUNC_UTIME_NULL}
17051 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
17052 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
17053 If the cache file is inconsistent with the current host, target and
17054 build system types, it used to execute @var{cmd} or print a default
17055 error message. This is now handled by default.
17058 @defmac AC_VERBOSE (@var{result-description})
17060 @code{AC_MSG_RESULT}.
17065 @code{AC_FUNC_VFORK}
17070 @code{AC_FUNC_VPRINTF}
17075 @code{AC_FUNC_WAIT3}
17083 @defmac AC_WORDS_BIGENDIAN
17084 @acindex{WORDS_BIGENDIAN}
17085 @code{AC_C_BIGENDIAN}
17088 @defmac AC_XENIX_DIR
17089 @acindex{XENIX_DIR}
17091 This macro used to add @option{-lx} to output variable @code{LIBS} if on
17092 Xenix. Also, if @file{dirent.h} is being checked for, added
17093 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
17094 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
17095 running @sc{xenix} on which you should not depend:
17098 AC_MSG_CHECKING([for Xenix])
17099 AC_EGREP_CPP([yes],
17100 [#if defined M_XENIX && !defined M_UNIX
17103 [AC_MSG_RESULT([yes]); XENIX=yes],
17104 [AC_MSG_RESULT([no]); XENIX=])
17108 @defmac AC_YYTEXT_POINTER
17109 @acindex{YYTEXT_POINTER}
17110 @code{AC_DECL_YYTEXT}
17114 @section Upgrading From Version 1
17115 @cindex Upgrading autoconf
17116 @cindex Autoconf upgrading
17118 Autoconf version 2 is mostly backward compatible with version 1.
17119 However, it introduces better ways to do some things, and doesn't
17120 support some of the ugly things in version 1. So, depending on how
17121 sophisticated your @file{configure.ac} files are, you might have to do
17122 some manual work in order to upgrade to version 2. This chapter points
17123 out some problems to watch for when upgrading. Also, perhaps your
17124 @command{configure} scripts could benefit from some of the new features in
17125 version 2; the changes are summarized in the file @file{NEWS} in the
17126 Autoconf distribution.
17129 * Changed File Names:: Files you might rename
17130 * Changed Makefiles:: New things to put in @file{Makefile.in}
17131 * Changed Macros:: Macro calls you might replace
17132 * Changed Results:: Changes in how to check test results
17133 * Changed Macro Writing:: Better ways to write your own macros
17136 @node Changed File Names
17137 @subsection Changed File Names
17139 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
17140 in a particular package's source directory), you must rename it to
17141 @file{acsite.m4}. @xref{autoconf Invocation}.
17143 If you distribute @file{install.sh} with your package, rename it to
17144 @file{install-sh} so @code{make} builtin rules don't inadvertently
17145 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
17146 looks for the script under both names, but it is best to use the new name.
17148 If you were using @file{config.h.top}, @file{config.h.bot}, or
17149 @file{acconfig.h}, you still can, but you have less clutter if you
17150 use the @code{AH_} macros. @xref{Autoheader Macros}.
17152 @node Changed Makefiles
17153 @subsection Changed Makefiles
17155 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
17156 your @file{Makefile.in} files, so they can take advantage of the values
17157 of those variables in the environment when @command{configure} is run.
17158 Doing this isn't necessary, but it's a convenience for users.
17160 Also add @samp{@@configure_input@@} in a comment to each input file for
17161 @code{AC_OUTPUT}, so that the output files contain a comment saying
17162 they were produced by @command{configure}. Automatically selecting the
17163 right comment syntax for all the kinds of files that people call
17164 @code{AC_OUTPUT} on became too much work.
17166 Add @file{config.log} and @file{config.cache} to the list of files you
17167 remove in @code{distclean} targets.
17169 If you have the following in @file{Makefile.in}:
17172 prefix = /usr/local
17173 exec_prefix = $(prefix)
17177 you must change it to:
17180 prefix = @@prefix@@
17181 exec_prefix = @@exec_prefix@@
17185 The old behavior of replacing those variables without @samp{@@}
17186 characters around them has been removed.
17188 @node Changed Macros
17189 @subsection Changed Macros
17191 Many of the macros were renamed in Autoconf version 2. You can still
17192 use the old names, but the new ones are clearer, and it's easier to find
17193 the documentation for them. @xref{Obsolete Macros}, for a table showing the
17194 new names for the old macros. Use the @command{autoupdate} program to
17195 convert your @file{configure.ac} to using the new macro names.
17196 @xref{autoupdate Invocation}.
17198 Some macros have been superseded by similar ones that do the job better,
17199 but are not call-compatible. If you get warnings about calling obsolete
17200 macros while running @command{autoconf}, you may safely ignore them, but
17201 your @command{configure} script generally works better if you follow
17202 the advice that is printed about what to replace the obsolete macros with. In
17203 particular, the mechanism for reporting the results of tests has
17204 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
17205 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output
17206 looks better if you switch to @code{AC_MSG_CHECKING} and
17207 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
17208 in conjunction with cache variables. @xref{Caching Results}.
17212 @node Changed Results
17213 @subsection Changed Results
17215 If you were checking the results of previous tests by examining the
17216 shell variable @code{DEFS}, you need to switch to checking the values of
17217 the cache variables for those tests. @code{DEFS} no longer exists while
17218 @command{configure} is running; it is only created when generating output
17219 files. This difference from version 1 is because properly quoting the
17220 contents of that variable turned out to be too cumbersome and
17221 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
17224 For example, here is a @file{configure.ac} fragment written for Autoconf
17228 AC_HAVE_FUNCS(syslog)
17230 *-DHAVE_SYSLOG*) ;;
17231 *) # syslog is not in the default libraries. See if it's in some other.
17233 for lib in bsd socket inet; do
17234 AC_CHECKING(for syslog in -l$lib)
17235 LIBS="-l$lib $saved_LIBS"
17236 AC_HAVE_FUNCS(syslog)
17238 *-DHAVE_SYSLOG*) break ;;
17246 Here is a way to write it for version 2:
17249 AC_CHECK_FUNCS([syslog])
17250 if test $ac_cv_func_syslog = no; then
17251 # syslog is not in the default libraries. See if it's in some other.
17252 for lib in bsd socket inet; do
17253 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
17254 LIBS="-l$lib $LIBS"; break])
17259 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
17260 backslashes before quotes, you need to remove them. It now works
17261 predictably, and does not treat quotes (except back quotes) specially.
17262 @xref{Setting Output Variables}.
17264 All of the Boolean shell variables set by Autoconf macros now use
17265 @samp{yes} for the true value. Most of them use @samp{no} for false,
17266 though for backward compatibility some use the empty string instead. If
17267 you were relying on a shell variable being set to something like 1 or
17268 @samp{t} for true, you need to change your tests.
17270 @node Changed Macro Writing
17271 @subsection Changed Macro Writing
17273 When defining your own macros, you should now use @code{AC_DEFUN}
17274 instead of @code{define}. @code{AC_DEFUN} automatically calls
17275 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
17276 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
17277 messages on the screen. There's no actual harm in continuing to use the
17278 older way, but it's less convenient and attractive. @xref{Macro
17281 You probably looked at the macros that came with Autoconf as a guide for
17282 how to do things. It would be a good idea to take a look at the new
17283 versions of them, as the style is somewhat improved and they take
17284 advantage of some new features.
17286 If you were doing tricky things with undocumented Autoconf internals
17287 (macros, variables, diversions), check whether you need to change
17288 anything to account for changes that have been made. Perhaps you can
17289 even use an officially supported technique in version 2 instead of
17290 kludging. Or perhaps not.
17292 To speed up your locally written feature tests, add caching to them.
17293 See whether any of your tests are of general enough usefulness to
17294 encapsulate them into macros that you can share.
17297 @node Autoconf 2.13
17298 @section Upgrading From Version 2.13
17299 @cindex Upgrading autoconf
17300 @cindex Autoconf upgrading
17302 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
17303 suits this section@enddots{}
17306 Autoconf version 2.50 is mostly backward compatible with version 2.13.
17307 However, it introduces better ways to do some things, and doesn't
17308 support some of the ugly things in version 2.13. So, depending on how
17309 sophisticated your @file{configure.ac} files are, you might have to do
17310 some manual work in order to upgrade to version 2.50. This chapter
17311 points out some problems to watch for when upgrading. Also, perhaps
17312 your @command{configure} scripts could benefit from some of the new
17313 features in version 2.50; the changes are summarized in the file
17314 @file{NEWS} in the Autoconf distribution.
17318 * Changed Quotation:: Broken code which used to work
17319 * New Macros:: Interaction with foreign macros
17320 * Hosts and Cross-Compilation:: Bugward compatibility kludges
17321 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
17322 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
17325 @node Changed Quotation
17326 @subsection Changed Quotation
17328 The most important changes are invisible to you: the implementation of
17329 most macros have completely changed. This allowed more factorization of
17330 the code, better error messages, a higher uniformity of the user's
17331 interface etc. Unfortunately, as a side effect, some construct which
17332 used to (miraculously) work might break starting with Autoconf 2.50.
17333 The most common culprit is bad quotation.
17335 For instance, in the following example, the message is not properly
17340 AC_CHECK_HEADERS(foo.h, ,
17341 AC_MSG_ERROR(cannot find foo.h, bailing out))
17346 Autoconf 2.13 simply ignores it:
17349 $ @kbd{autoconf-2.13; ./configure --silent}
17350 creating cache ./config.cache
17351 configure: error: cannot find foo.h
17356 while Autoconf 2.50 produces a broken @file{configure}:
17359 $ @kbd{autoconf-2.50; ./configure --silent}
17360 configure: error: cannot find foo.h
17361 ./configure: exit: bad non-numeric arg `bailing'
17362 ./configure: exit: bad non-numeric arg `bailing'
17366 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
17370 AC_INIT([Example], [1.0], [bug-example@@example.org])
17371 AC_CHECK_HEADERS([foo.h], [],
17372 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
17376 Many many (and many more) Autoconf macros were lacking proper quotation,
17377 including no less than@dots{} @code{AC_DEFUN} itself!
17380 $ @kbd{cat configure.in}
17381 AC_DEFUN([AC_PROG_INSTALL],
17382 [# My own much better version
17387 $ @kbd{autoconf-2.13}
17388 autoconf: Undefined macros:
17389 ***BUG in Autoconf--please report*** AC_FD_MSG
17390 ***BUG in Autoconf--please report*** AC_EPI
17391 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
17392 configure.in:5:AC_PROG_INSTALL
17393 $ @kbd{autoconf-2.50}
17399 @subsection New Macros
17401 @cindex undefined macro
17402 @cindex @code{_m4_divert_diversion}
17404 While Autoconf was relatively dormant in the late 1990s, Automake
17405 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
17406 in 2001, Autoconf provided
17407 versions of these macros, integrated in the @code{AC_} namespace,
17408 instead of @code{AM_}. But in order to ease the upgrading via
17409 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
17411 Unfortunately older versions of Automake (e.g., Automake 1.4)
17412 did not quote the names of these macros.
17413 Therefore, when @command{m4} finds something like
17414 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
17415 @code{AM_TYPE_PTRDIFF_T} is
17416 expanded, replaced with its Autoconf definition.
17418 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and
17419 complains, in its own words:
17422 $ @kbd{cat configure.ac}
17423 AC_INIT([Example], [1.0], [bug-example@@example.org])
17425 $ @kbd{aclocal-1.4}
17427 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
17428 aclocal.m4:17: the top level
17429 autom4te: m4 failed with exit status: 1
17433 Modern versions of Automake no longer define most of these
17434 macros, and properly quote the names of the remaining macros.
17435 If you must use an old Automake, do not depend upon macros from Automake
17436 as it is simply not its job
17437 to provide macros (but the one it requires itself):
17440 $ @kbd{cat configure.ac}
17441 AC_INIT([Example], [1.0], [bug-example@@example.org])
17443 $ @kbd{rm aclocal.m4}
17445 autoupdate: `configure.ac' is updated
17446 $ @kbd{cat configure.ac}
17447 AC_INIT([Example], [1.0], [bug-example@@example.org])
17448 AC_CHECK_TYPES([ptrdiff_t])
17449 $ @kbd{aclocal-1.4}
17455 @node Hosts and Cross-Compilation
17456 @subsection Hosts and Cross-Compilation
17457 @cindex Cross compilation
17459 Based on the experience of compiler writers, and after long public
17460 debates, many aspects of the cross-compilation chain have changed:
17464 the relationship between the build, host, and target architecture types,
17467 the command line interface for specifying them to @command{configure},
17470 the variables defined in @command{configure},
17473 the enabling of cross-compilation mode.
17478 The relationship between build, host, and target have been cleaned up:
17479 the chain of default is now simply: target defaults to host, host to
17480 build, and build to the result of @command{config.guess}. Nevertheless,
17481 in order to ease the transition from 2.13 to 2.50, the following
17482 transition scheme is implemented. @emph{Do not rely on it}, as it will
17483 be completely disabled in a couple of releases (we cannot keep it, as it
17484 proves to cause more problems than it cures).
17486 They all default to the result of running @command{config.guess}, unless
17487 you specify either @option{--build} or @option{--host}. In this case,
17488 the default becomes the system type you specified. If you specify both,
17489 and they're different, @command{configure} enters cross compilation
17490 mode, so it doesn't run any tests that require execution.
17492 Hint: if you mean to override the result of @command{config.guess},
17493 prefer @option{--build} over @option{--host}. In the future,
17494 @option{--host} will not override the name of the build system type.
17495 Whenever you specify @option{--host}, be sure to specify @option{--build}
17500 For backward compatibility, @command{configure} accepts a system
17501 type as an option by itself. Such an option overrides the
17502 defaults for build, host, and target system types. The following
17503 configure statement configures a cross toolchain that runs on
17504 Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc,
17505 which is also the build platform.
17508 ./configure --host=alpha-netbsd sparc-gnu
17513 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
17514 and @code{target} had a different semantics before and after the
17515 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
17516 @option{--build} is strictly copied into @code{build_alias}, and is left
17517 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
17518 set to the canonicalized build type. To ease the transition, before,
17519 its contents is the same as that of @code{build_alias}. Do @emph{not}
17520 rely on this broken feature.
17522 For consistency with the backward compatibility scheme exposed above,
17523 when @option{--host} is specified but @option{--build} isn't, the build
17524 system is assumed to be the same as @option{--host}, and
17525 @samp{build_alias} is set to that value. Eventually, this
17526 historically incorrect behavior will go away.
17530 The former scheme to enable cross-compilation proved to cause more harm
17531 than good, in particular, it used to be triggered too easily, leaving
17532 regular end users puzzled in front of cryptic error messages.
17533 @command{configure} could even enter cross-compilation mode only
17534 because the compiler was not functional. This is mainly because
17535 @command{configure} used to try to detect cross-compilation, instead of
17536 waiting for an explicit flag from the user.
17538 Now, @command{configure} enters cross-compilation mode if and only if
17539 @option{--host} is passed.
17541 That's the short documentation. To ease the transition between 2.13 and
17542 its successors, a more complicated scheme is implemented. @emph{Do not
17543 rely on the following}, as it will be removed in the near future.
17545 If you specify @option{--host}, but not @option{--build}, when
17546 @command{configure} performs the first compiler test it tries to run
17547 an executable produced by the compiler. If the execution fails, it
17548 enters cross-compilation mode. This is fragile. Moreover, by the time
17549 the compiler test is performed, it may be too late to modify the
17550 build-system type: other tests may have already been performed.
17551 Therefore, whenever you specify @option{--host}, be sure to specify
17552 @option{--build} too.
17555 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
17559 enters cross-compilation mode. The former interface, which
17560 consisted in setting the compiler to a cross-compiler without informing
17561 @command{configure} is obsolete. For instance, @command{configure}
17562 fails if it can't run the code generated by the specified compiler if you
17563 configure as follows:
17566 ./configure CC=m68k-coff-gcc
17570 @node AC_LIBOBJ vs LIBOBJS
17571 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
17573 Up to Autoconf 2.13, the replacement of functions was triggered via the
17574 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
17575 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
17576 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
17578 This change is mandated by the unification of the @acronym{GNU} Build System
17579 components. In particular, the various fragile techniques used to parse
17580 a @file{configure.ac} are all replaced with the use of traces. As a
17581 consequence, any action must be traceable, which obsoletes critical
17582 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
17583 and it can even be handled gracefully (read, ``without your having to
17584 change something'').
17586 There were two typical uses of @code{LIBOBJS}: asking for a replacement
17587 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
17591 As for function replacement, the fix is immediate: use
17592 @code{AC_LIBOBJ}. For instance:
17595 LIBOBJS="$LIBOBJS fnmatch.o"
17596 LIBOBJS="$LIBOBJS malloc.$ac_objext"
17600 should be replaced with:
17603 AC_LIBOBJ([fnmatch])
17604 AC_LIBOBJ([malloc])
17610 When used with Automake 1.10 or newer, a suitable value for
17611 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
17612 can be referenced from any @file{Makefile.am}. Even without Automake,
17613 arranging for @code{LIBOBJDIR} to be set correctly enables
17614 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
17615 The @code{LIBOJBDIR} feature is experimental.
17618 @node AC_FOO_IFELSE vs AC_TRY_FOO
17619 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
17621 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
17622 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
17623 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
17624 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
17625 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
17626 @code{AC_TRY_RUN}. The motivations where:
17629 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
17630 quoting their arguments;
17633 the combinatoric explosion is solved by decomposing on the one hand the
17634 generation of sources, and on the other hand executing the program;
17637 this scheme helps supporting more languages than plain C and C++.
17640 In addition to the change of syntax, the philosophy has changed too:
17641 while emphasis was put on speed at the expense of accuracy, today's
17642 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
17646 As a perfect example of what is @emph{not} to be done, here is how to
17647 find out whether a header file contains a particular declaration, such
17648 as a typedef, a structure, a structure member, or a function. Use
17649 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
17650 header file; on some systems the symbol might be defined in another
17651 header file that the file you are checking includes.
17653 As a (bad) example, here is how you should not check for C preprocessor
17654 symbols, either defined by header files or predefined by the C
17655 preprocessor: using @code{AC_EGREP_CPP}:
17663 ], is_aix=yes, is_aix=no)
17667 The above example, properly written would (i) use
17668 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
17672 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
17673 [[#if !defined _AIX
17674 error: This isn't AIX!
17683 @c ============================= Generating Test Suites with Autotest
17685 @node Using Autotest
17686 @chapter Generating Test Suites with Autotest
17691 @strong{N.B.: This section describes an experimental feature which will
17692 be part of Autoconf in a forthcoming release. Although we believe
17693 Autotest is stabilizing, this documentation describes an interface which
17694 might change in the future: do not depend upon Autotest without
17695 subscribing to the Autoconf mailing lists.}
17698 It is paradoxical that portable projects depend on nonportable tools
17699 to run their test suite. Autoconf by itself is the paragon of this
17700 problem: although it aims at perfectly portability, up to 2.13 its
17701 test suite was using Deja@acronym{GNU}, a rich and complex testing
17702 framework, but which is far from being standard on Posix systems.
17703 Worse yet, it was likely to be missing on the most fragile platforms,
17704 the very platforms that are most likely to torture Autoconf and
17705 exhibit deficiencies.
17707 To circumvent this problem, many package maintainers have developed their
17708 own testing framework, based on simple shell scripts whose sole outputs
17709 are exit status values describing whether the test succeeded. Most of
17710 these tests share common patterns, and this can result in lots of
17711 duplicated code and tedious maintenance.
17713 Following exactly the same reasoning that yielded to the inception of
17714 Autoconf, Autotest provides a test suite generation framework, based on
17715 M4 macros building a portable shell script. The suite itself is
17716 equipped with automatic logging and tracing facilities which greatly
17717 diminish the interaction with bug reporters, and simple timing reports.
17719 Autoconf itself has been using Autotest for years, and we do attest that
17720 it has considerably improved the strength of the test suite and the
17721 quality of bug reports. Other projects are known to use some generation
17722 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
17723 them with different needs, and this usage has validated Autotest as a general
17726 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
17727 interactive tool testing, which is probably its main limitation.
17730 * Using an Autotest Test Suite:: Autotest and the user
17731 * Writing testsuite.at:: Autotest macros
17732 * testsuite Invocation:: Running @command{testsuite} scripts
17733 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
17736 @node Using an Autotest Test Suite
17737 @section Using an Autotest Test Suite
17740 * testsuite Scripts:: The concepts of Autotest
17741 * Autotest Logs:: Their contents
17744 @node testsuite Scripts
17745 @subsection @command{testsuite} Scripts
17747 @cindex @command{testsuite}
17749 Generating testing or validation suites using Autotest is rather easy.
17750 The whole validation suite is held in a file to be processed through
17751 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
17752 produce a stand-alone Bourne shell script which then gets distributed.
17753 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
17754 the installer's end.
17757 Each test of the validation suite should be part of some test group. A
17758 @dfn{test group} is a sequence of interwoven tests that ought to be
17759 executed together, usually because one test in the group creates data
17760 files than a later test in the same group needs to read. Complex test
17761 groups make later debugging more tedious. It is much better to
17762 keep only a few tests per test group. Ideally there is only one test
17765 For all but the simplest packages, some file such as @file{testsuite.at}
17766 does not fully hold all test sources, as these are often easier to
17767 maintain in separate files. Each of these separate files holds a single
17768 test group, or a sequence of test groups all addressing some common
17769 functionality in the package. In such cases, @file{testsuite.at}
17770 merely initializes the validation suite, and sometimes does elementary
17771 health checking, before listing include statements for all other test
17772 files. The special file @file{package.m4}, containing the
17773 identification of the package, is automatically included if found.
17775 A convenient alternative consists in moving all the global issues
17776 (local Autotest macros, elementary health checking, and @code{AT_INIT}
17777 invocation) into the file @code{local.at}, and making
17778 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
17779 suites. In such case, generating the whole test suite or pieces of it
17780 is only a matter of choosing the @command{autom4te} command line
17783 The validation scripts that Autotest produces are by convention called
17784 @command{testsuite}. When run, @command{testsuite} executes each test
17785 group in turn, producing only one summary line per test to say if that
17786 particular test succeeded or failed. At end of all tests, summarizing
17787 counters get printed. One debugging directory is left for each test
17788 group which failed, if any: such directories are named
17789 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
17790 the test group, and they include:
17793 @item a debugging script named @file{run} which reruns the test in
17794 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
17795 of debugging scripts has the purpose of easing the chase for bugs.
17797 @item all the files created with @code{AT_DATA}
17799 @item a log of the run, named @file{testsuite.log}
17802 In the ideal situation, none of the tests fail, and consequently no
17803 debugging directory is left behind for validation.
17805 It often happens in practice that individual tests in the validation
17806 suite need to get information coming out of the configuration process.
17807 Some of this information, common for all validation suites, is provided
17808 through the file @file{atconfig}, automatically created by
17809 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
17810 testing environment specifically needs, you might prepare an optional
17811 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
17812 The configuration process produces @file{atconfig} and @file{atlocal}
17813 out of these two input files, and these two produced files are
17814 automatically read by the @file{testsuite} script.
17816 Here is a diagram showing the relationship between files.
17819 Files used in preparing a software package for distribution:
17824 subfile-1.at ->. [local.at] ---->+
17826 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
17832 Files used in configuring a software package:
17837 [atlocal.in] --> config.status* --<
17843 Files created during the test suite execution:
17846 atconfig -->. .--> testsuite.log
17850 [atlocal] ->' `--> [testsuite.dir]
17854 @node Autotest Logs
17855 @subsection Autotest Logs
17857 When run, the test suite creates a log file named after itself, e.g., a
17858 test suite named @command{testsuite} creates @file{testsuite.log}. It
17859 contains a lot of information, usually more than maintainers actually
17860 need, but therefore most of the time it contains all that is needed:
17863 @item command line arguments
17864 @c akim s/to consist in/to consist of/
17865 A bad but unfortunately widespread habit consists of
17866 setting environment variables before the command, such as in
17867 @samp{CC=my-home-grown-cc ./testsuite}. The test suite does not
17868 know this change, hence (i) it cannot report it to you, and (ii)
17869 it cannot preserve the value of @code{CC} for subsequent runs.
17870 Autoconf faced exactly the same problem, and solved it by asking
17871 users to pass the variable definitions as command line arguments.
17872 Autotest requires this rule, too, but has no means to enforce it; the log
17873 then contains a trace of the variables that were changed by the user.
17875 @item @file{ChangeLog} excerpts
17876 The topmost lines of all the @file{ChangeLog} files found in the source
17877 hierarchy. This is especially useful when bugs are reported against
17878 development versions of the package, since the version string does not
17879 provide sufficient information to know the exact state of the sources
17880 the user compiled. Of course, this relies on the use of a
17883 @item build machine
17884 Running a test suite in a cross-compile environment is not an easy task,
17885 since it would mean having the test suite run on a machine @var{build},
17886 while running programs on a machine @var{host}. It is much simpler to
17887 run both the test suite and the programs on @var{host}, but then, from
17888 the point of view of the test suite, there remains a single environment,
17889 @var{host} = @var{build}. The log contains relevant information on the
17890 state of the build machine, including some important environment
17892 @c FIXME: How about having an M4sh macro to say `hey, log the value
17893 @c of `@dots{}'? This would help both Autoconf and Autotest.
17895 @item tested programs
17896 The absolute file name and answers to @option{--version} of the tested
17897 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
17899 @item configuration log
17900 The contents of @file{config.log}, as created by @command{configure},
17901 are appended. It contains the configuration flags and a detailed report
17902 on the configuration itself.
17906 @node Writing testsuite.at
17907 @section Writing @file{testsuite.at}
17909 The @file{testsuite.at} is a Bourne shell script making use of special
17910 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
17911 its beginning followed by one call to @code{m4_include} per source file
17912 for tests. Each such included file, or the remainder of
17913 @file{testsuite.at} if include files are not used, contain a sequence of
17914 test groups. Each test group begins with a call to @code{AT_SETUP},
17915 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
17916 and then completes with a call to @code{AT_CLEANUP}.
17918 @defmac AT_INIT (@ovar{name})
17920 @c FIXME: Not clear, plus duplication of the information.
17921 Initialize Autotest. Giving a @var{name} to the test suite is
17922 encouraged if your package includes several test suites. In any case,
17923 the test suite always displays the package name and version. It also
17924 inherits the package bug report address.
17927 @defmac AT_COPYRIGHT (@var{copyright-notice})
17928 @atindex{COPYRIGHT}
17929 @cindex Copyright Notice
17930 State that, in addition to the Free Software Foundation's copyright on
17931 the Autotest macros, parts of your test suite are covered by
17932 @var{copyright-notice}.
17934 The @var{copyright-notice} shows up in both the head of
17935 @command{testsuite} and in @samp{testsuite --version}.
17938 @defmac AT_TESTED (@var{executables})
17940 Log the file name and answer to @option{--version} of each program in
17941 space-separated list @var{executables}. Several invocations register
17942 new executables, in other words, don't fear registering one program
17946 Autotest test suites rely on @env{PATH} to find the tested program.
17947 This avoids the need to generate absolute names of the various tools, and
17948 makes it possible to test installed programs. Therefore, knowing which
17949 programs are being exercised is crucial to understanding problems in
17950 the test suite itself, or its occasional misuses. It is a good idea to
17951 also subscribe foreign programs you depend upon, to avoid incompatible
17956 @defmac AT_SETUP (@var{test-group-name})
17958 This macro starts a group of related tests, all to be executed in the
17959 same subshell. It accepts a single argument, which holds a few words
17960 (no more than about 30 or 40 characters) quickly describing the purpose
17961 of the test group being started.
17964 @defmac AT_KEYWORDS (@var{keywords})
17966 Associate the space-separated list of @var{keywords} to the enclosing
17967 test group. This makes it possible to run ``slices'' of the test suite.
17968 For instance, if some of your test groups exercise some @samp{foo}
17969 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
17970 @samp{./testsuite -k foo} to run exclusively these test groups. The
17971 @var{title} of the test group is automatically recorded to
17972 @code{AT_KEYWORDS}.
17974 Several invocations within a test group accumulate new keywords. In
17975 other words, don't fear registering the same keyword several times in a
17979 @defmac AT_CAPTURE_FILE (@var{file})
17980 @atindex{CAPTURE_FILE}
17981 If the current test group fails, log the contents of @var{file}.
17982 Several identical calls within one test group have no additional effect.
17985 @defmac AT_XFAIL_IF (@var{shell-condition})
17987 Determine whether the test is expected to fail because it is a known
17988 bug (for unsupported features, you should skip the test).
17989 @var{shell-condition} is a shell expression such as a @code{test}
17990 command; you can instantiate this macro many times from within the
17991 same test group, and one of the conditions is enough to turn
17992 the test into an expected failure.
17997 End the current test group.
18002 @defmac AT_DATA (@var{file}, @var{contents})
18004 Initialize an input data @var{file} with given @var{contents}. Of
18005 course, the @var{contents} have to be properly quoted between square
18006 brackets to protect against included commas or spurious M4
18007 expansion. The contents ought to end with an end of line.
18010 @defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass})
18012 Execute a test by performing given shell @var{commands}. These commands
18013 should normally exit with @var{status}, while producing expected
18014 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
18015 status 77, then the whole test group is skipped. Otherwise, if this test
18016 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
18017 commands @var{run-if-pass}.
18019 The @var{commands} @emph{must not} redirect the standard output, nor the
18022 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
18023 the corresponding value is not checked.
18025 The special value @samp{expout} for @var{stdout} means the expected
18026 output of the @var{commands} is the content of the file @file{expout}.
18027 If @var{stdout} is @samp{stdout}, then the standard output of the
18028 @var{commands} is available for further tests in the file @file{stdout}.
18029 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
18033 @node testsuite Invocation
18034 @section Running @command{testsuite} Scripts
18035 @cindex @command{testsuite}
18037 Autotest test suites support the following arguments:
18042 Display the list of options and exit successfully.
18046 Display the version of the test suite and exit successfully.
18050 Remove all the files the test suite might have created and exit. Meant
18051 for @code{clean} Make targets.
18055 List all the tests (or only the selection), including their possible
18061 By default all tests are performed (or described with
18062 @option{--list}) in the default environment first silently, then
18063 verbosely, but the environment, set of tests, and verbosity level can be
18067 @item @var{variable}=@var{value}
18068 Set the environment @var{variable} to @var{value}. Use this rather
18069 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
18070 different environment.
18072 @cindex @code{AUTOTEST_PATH}
18073 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
18074 to @env{PATH}. Relative directory names (not starting with
18075 @samp{/}) are considered to be relative to the top level of the
18076 package being built. All directories are made absolute, first
18077 starting from the top level @emph{build} tree, then from the
18078 @emph{source} tree. For instance @samp{./testsuite
18079 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
18080 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
18081 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
18085 @itemx @var{number}-@var{number}
18086 @itemx @var{number}-
18087 @itemx -@var{number}
18088 Add the corresponding test groups, with obvious semantics, to the
18091 @item --keywords=@var{keywords}
18092 @itemx -k @var{keywords}
18093 Add to the selection the test groups with title or keywords (arguments
18094 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
18095 of the comma separated list @var{keywords}, case-insensitively. Use
18096 @samp{!} immediately before the keyword to invert the selection for this
18097 keyword. By default, the keywords match whole words; enclose them in
18098 @samp{.*} to also match parts of words.
18100 For example, running
18103 @kbd{./testsuite -k 'autoupdate,.*FUNC.*'}
18107 selects all tests tagged @samp{autoupdate} @emph{and} with tags
18108 containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH},
18112 @kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'}
18116 selects all tests not tagged @samp{autoupdate} @emph{or} with tags
18117 containing @samp{FUNC}.
18121 If any test fails, immediately abort testing. It implies
18122 @option{--debug}: post test group clean up, and top-level logging
18123 are inhibited. This option is meant for the full test
18124 suite, it is not really useful for generated debugging scripts.
18128 Force more verbosity in the detailed output of what is being done. This
18129 is the default for debugging scripts.
18133 Do not remove the files after a test group was performed ---but they are
18134 still removed @emph{before}, therefore using this option is sane when
18135 running several test groups. Create debugging scripts. Do not
18136 overwrite the top-level
18137 log (in order to preserve supposedly existing full log file). This is
18138 the default for debugging scripts, but it can also be useful to debug
18139 the testsuite itself.
18143 Trigger shell tracing of the test groups.
18147 @node Making testsuite Scripts
18148 @section Making @command{testsuite} Scripts
18150 For putting Autotest into movement, you need some configuration and
18151 makefile machinery. We recommend, at least if your package uses deep or
18152 shallow hierarchies, that you use @file{tests/} as the name of the
18153 directory holding all your tests and their makefile. Here is a
18154 check list of things to do.
18159 @cindex @file{package.m4}
18160 Make sure to create the file @file{package.m4}, which defines the
18161 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
18162 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
18163 address to which bug reports should be sent. For sake of completeness,
18164 we suggest that you also define @code{AT_PACKAGE_NAME},
18165 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
18166 @xref{Initializing configure}, for a description of these variables. We
18167 suggest the following makefile excerpt:
18170 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
18172 echo '# Signature of the current package.'; \
18173 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
18174 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
18175 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
18176 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
18177 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
18178 @} >'$(srcdir)/package.m4'
18182 Be sure to distribute @file{package.m4} and to put it into the source
18183 hierarchy: the test suite ought to be shipped!
18186 Invoke @code{AC_CONFIG_TESTDIR}.
18188 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory})
18189 @acindex{CONFIG_TESTDIR}
18190 An Autotest test suite is to be configured in @var{directory}. This
18191 macro requires the instantiation of @file{@var{directory}/atconfig} from
18192 @file{@var{directory}/atconfig.in}, and sets the default
18193 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
18197 Still within @file{configure.ac}, as appropriate, ensure that some
18198 @code{AC_CONFIG_FILES} command includes substitution for
18199 @file{tests/atlocal}.
18202 The @file{tests/Makefile.in} should be modified so the validation in
18203 your package is triggered by @samp{make check}. An example is provided
18207 With Automake, here is a minimal example about how to link @samp{make
18208 check} with a validation suite.
18211 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
18212 TESTSUITE = $(srcdir)/testsuite
18214 check-local: atconfig atlocal $(TESTSUITE)
18215 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS)
18217 installcheck-local: atconfig atlocal $(TESTSUITE)
18218 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \
18222 test ! -f '$(TESTSUITE)' || \
18223 $(SHELL) '$(TESTSUITE)' --clean
18225 AUTOTEST = $(AUTOM4TE) --language=autotest
18226 $(TESTSUITE): $(srcdir)/testsuite.at
18227 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at
18231 You might want to list explicitly the dependencies, i.e., the list of
18232 the files @file{testsuite.at} includes.
18234 With strict Autoconf, you might need to add lines inspired from the
18240 atconfig: $(top_builddir)/config.status
18241 cd $(top_builddir) && \
18242 $(SHELL) ./config.status $(subdir)/$@@
18244 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
18245 cd $(top_builddir) && \
18246 $(SHELL) ./config.status $(subdir)/$@@
18250 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
18253 With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS}
18254 within your makefile, you can fine-tune test suite execution with this variable,
18258 make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
18263 @c =============================== Frequent Autoconf Questions, with answers
18266 @chapter Frequent Autoconf Questions, with answers
18268 Several questions about Autoconf come up occasionally. Here some of them
18272 * Distributing:: Distributing @command{configure} scripts
18273 * Why GNU M4:: Why not use the standard M4?
18274 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
18275 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
18276 * Defining Directories:: Passing @code{datadir} to program
18277 * autom4te.cache:: What is it? Can I remove it?
18278 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
18282 @section Distributing @command{configure} Scripts
18286 What are the restrictions on distributing @command{configure}
18287 scripts that Autoconf generates? How does that affect my
18288 programs that use them?
18291 There are no restrictions on how the configuration scripts that Autoconf
18292 produces may be distributed or used. In Autoconf version 1, they were
18293 covered by the @acronym{GNU} General Public License. We still encourage
18294 software authors to distribute their work under terms like those of the
18295 @acronym{GPL}, but doing so is not required to use Autoconf.
18297 Of the other files that might be used with @command{configure},
18298 @file{config.h.in} is under whatever copyright you use for your
18299 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
18300 exception to the @acronym{GPL} when they are used with an Autoconf-generated
18301 @command{configure} script, which permits you to distribute them under the
18302 same terms as the rest of your package. @file{install-sh} is from the X
18303 Consortium and is not copyrighted.
18306 @section Why Require @acronym{GNU} M4?
18309 Why does Autoconf require @acronym{GNU} M4?
18312 Many M4 implementations have hard-coded limitations on the size and
18313 number of macros that Autoconf exceeds. They also lack several
18314 builtin macros that it would be difficult to get along without in a
18315 sophisticated application like Autoconf, including:
18325 Autoconf requires version 1.4.5 or later of @acronym{GNU} M4.
18327 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
18328 M4 is simple to configure and install, it seems reasonable to require
18329 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
18330 other free software already have most of the @acronym{GNU} utilities
18331 installed, since they prefer them.
18333 @node Bootstrapping
18334 @section How Can I Bootstrap?
18338 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
18339 @command{configure} script, how do I bootstrap? It seems like a chicken
18343 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
18344 @command{configure} script produced by Autoconf, Autoconf is not required
18345 in order to run the script and install @acronym{GNU} M4. Autoconf is only
18346 required if you want to change the M4 @command{configure} script, which few
18347 people have to do (mainly its maintainer).
18349 @node Why Not Imake
18350 @section Why Not Imake?
18354 Why not use Imake instead of @command{configure} scripts?
18357 Several people have written addressing this question, so I include
18358 adaptations of their explanations here.
18360 The following answer is based on one written by Richard Pixley:
18363 Autoconf generated scripts frequently work on machines that it has
18364 never been set up to handle before. That is, it does a good job of
18365 inferring a configuration for a new system. Imake cannot do this.
18367 Imake uses a common database of host specific data. For X11, this makes
18368 sense because the distribution is made as a collection of tools, by one
18369 central authority who has control over the database.
18371 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
18372 maintainer; these maintainers are scattered across the world. Using a
18373 common database would be a maintenance nightmare. Autoconf may appear
18374 to be this kind of database, but in fact it is not. Instead of listing
18375 host dependencies, it lists program requirements.
18377 If you view the @acronym{GNU} suite as a collection of native tools, then the
18378 problems are similar. But the @acronym{GNU} development tools can be
18379 configured as cross tools in almost any host+target permutation. All of
18380 these configurations can be installed concurrently. They can even be
18381 configured to share host independent files across hosts. Imake doesn't
18382 address these issues.
18384 Imake templates are a form of standardization. The @acronym{GNU} coding
18385 standards address the same issues without necessarily imposing the same
18390 Here is some further explanation, written by Per Bothner:
18393 One of the advantages of Imake is that it easy to generate large
18394 makefiles using the @samp{#include} and macro mechanisms of @command{cpp}.
18395 However, @code{cpp} is not programmable: it has limited conditional
18396 facilities, and no looping. And @code{cpp} cannot inspect its
18399 All of these problems are solved by using @code{sh} instead of
18400 @code{cpp}. The shell is fully programmable, has macro substitution,
18401 can execute (or source) other shell scripts, and can inspect its
18406 Paul Eggert elaborates more:
18409 With Autoconf, installers need not assume that Imake itself is already
18410 installed and working well. This may not seem like much of an advantage
18411 to people who are accustomed to Imake. But on many hosts Imake is not
18412 installed or the default installation is not working well, and requiring
18413 Imake to install a package hinders the acceptance of that package on
18414 those hosts. For example, the Imake template and configuration files
18415 might not be installed properly on a host, or the Imake build procedure
18416 might wrongly assume that all source files are in one big directory
18417 tree, or the Imake configuration might assume one compiler whereas the
18418 package or the installer needs to use another, or there might be a
18419 version mismatch between the Imake expected by the package and the Imake
18420 supported by the host. These problems are much rarer with Autoconf,
18421 where each package comes with its own independent configuration
18424 Also, Imake often suffers from unexpected interactions between
18425 @command{make} and the installer's C preprocessor. The fundamental problem
18426 here is that the C preprocessor was designed to preprocess C programs,
18427 not makefiles. This is much less of a problem with Autoconf,
18428 which uses the general-purpose preprocessor M4, and where the
18429 package's author (rather than the installer) does the preprocessing in a
18434 Finally, Mark Eichin notes:
18437 Imake isn't all that extensible, either. In order to add new features to
18438 Imake, you need to provide your own project template, and duplicate most
18439 of the features of the existing one. This means that for a sophisticated
18440 project, using the vendor-provided Imake templates fails to provide any
18441 leverage---since they don't cover anything that your own project needs
18442 (unless it is an X11 program).
18444 On the other side, though:
18446 The one advantage that Imake has over @command{configure}:
18447 @file{Imakefile} files tend to be much shorter (likewise, less redundant)
18448 than @file{Makefile.in} files. There is a fix to this, however---at least
18449 for the Kerberos V5 tree, we've modified things to call in common
18450 @file{post.in} and @file{pre.in} makefile fragments for the
18451 entire tree. This means that a lot of common things don't have to be
18452 duplicated, even though they normally are in @command{configure} setups.
18456 @node Defining Directories
18457 @section How Do I @code{#define} Installation Directories?
18460 My program needs library files, installed in @code{datadir} and
18464 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
18465 [Define to the read-only architecture-independent
18473 #define DATADIR "$@{prefix@}/share"
18477 As already explained, this behavior is on purpose, mandated by the
18478 @acronym{GNU} Coding Standards, see @ref{Installation Directory
18479 Variables}. There are several means to achieve a similar goal:
18483 Do not use @code{AC_DEFINE} but use your makefile to pass the
18484 actual value of @code{datadir} via compilation flags.
18485 @xref{Installation Directory Variables}, for the details.
18488 This solution can be simplified when compiling a program: you may either
18489 extend the @code{CPPFLAGS}:
18492 CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@
18496 or create a dedicated header file:
18499 DISTCLEANFILES = datadir.h
18500 datadir.h: Makefile
18501 echo '#define DATADIR "$(datadir)"' >$@@
18505 Use @code{AC_DEFINE} but have @command{configure} compute the literal
18506 value of @code{datadir} and others. Many people have wrapped macros to
18507 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
18508 the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro
18511 This solution does not conform to the @acronym{GNU} Coding Standards.
18514 Note that all the previous solutions hard wire the absolute name of
18515 these directories in the executables, which is not a good property. You
18516 may try to compute the names relative to @code{prefix}, and try to
18517 find @code{prefix} at runtime, this way your package is relocatable.
18518 Some macros are already available to address this issue: see
18519 @code{adl_COMPUTE_RELATIVE_PATHS} and
18520 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
18521 @uref{http://autoconf-archive.cryp.to/,
18522 Autoconf Macro Archive}.
18526 @node autom4te.cache
18527 @section What is @file{autom4te.cache}?
18530 What is this directory @file{autom4te.cache}? Can I safely remove it?
18533 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
18534 role and is read by many tools: @command{autoconf} to create
18535 @file{configure}, @command{autoheader} to create @file{config.h.in},
18536 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
18537 check the completeness of @file{configure.ac}, @command{autoreconf} to
18538 check the @acronym{GNU} Build System components that are used. To
18539 ``read @file{configure.ac}'' actually means to compile it with M4,
18540 which can be a long process for complex @file{configure.ac}.
18542 This is why all these tools, instead of running directly M4, invoke
18543 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
18544 a specific demand, stores additional information in
18545 @file{autom4te.cache} for future runs. For instance, if you run
18546 @command{autoconf}, behind the scenes, @command{autom4te} also
18547 stores information for the other tools, so that when you invoke
18548 @command{autoheader} or @command{automake} etc., reprocessing
18549 @file{configure.ac} is not needed. The speed up is frequently of 30%,
18550 and is increasing with the size of @file{configure.ac}.
18552 But it is and remains being simply a cache: you can safely remove it.
18557 Can I permanently get rid of it?
18560 The creation of this cache can be disabled from
18561 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
18562 details. You should be aware that disabling the cache slows down the
18563 Autoconf test suite by 40%. The more @acronym{GNU} Build System
18564 components are used, the more the cache is useful; for instance
18565 running @samp{autoreconf -f} on the Core Utilities is twice slower without
18566 the cache @emph{although @option{--force} implies that the cache is
18567 not fully exploited}, and eight times slower than without
18571 @node Present But Cannot Be Compiled
18572 @section Header Present But Cannot Be Compiled
18574 The most important guideline to bear in mind when checking for
18575 features is to mimic as much as possible the intended use.
18576 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
18577 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
18578 the preprocessor, instead of the compiler, to check for headers. As a
18579 result, incompatibilities between headers went unnoticed during
18580 configuration, and maintainers finally had to deal with this issue
18583 As of Autoconf 2.56 both checks are performed, and @code{configure}
18584 complains loudly if the compiler and the preprocessor do not agree.
18585 For the time being the result used is that of the preprocessor, to give
18586 maintainers time to adjust their @file{configure.ac}, but in the
18587 future, only the compiler will be considered.
18589 Consider the following example:
18592 $ @kbd{cat number.h}
18593 typedef int number;
18595 const number pi = 3;
18596 $ @kbd{cat configure.ac}
18597 AC_INIT([Example], [1.0], [bug-example@@example.org])
18598 AC_CHECK_HEADERS([pi.h])
18599 $ @kbd{autoconf -Wall}
18600 $ @kbd{./configure}
18601 checking for gcc... gcc
18602 checking for C compiler default output file name... a.out
18603 checking whether the C compiler works... yes
18604 checking whether we are cross compiling... no
18605 checking for suffix of executables...
18606 checking for suffix of object files... o
18607 checking whether we are using the GNU C compiler... yes
18608 checking whether gcc accepts -g... yes
18609 checking for gcc option to accept ISO C89... none needed
18610 checking how to run the C preprocessor... gcc -E
18611 checking for grep that handles long lines and -e... grep
18612 checking for egrep... grep -E
18613 checking for ANSI C header files... yes
18614 checking for sys/types.h... yes
18615 checking for sys/stat.h... yes
18616 checking for stdlib.h... yes
18617 checking for string.h... yes
18618 checking for memory.h... yes
18619 checking for strings.h... yes
18620 checking for inttypes.h... yes
18621 checking for stdint.h... yes
18622 checking for unistd.h... yes
18623 checking pi.h usability... no
18624 checking pi.h presence... yes
18625 configure: WARNING: pi.h: present but cannot be compiled
18626 configure: WARNING: pi.h: check for missing prerequisite headers?
18627 configure: WARNING: pi.h: see the Autoconf documentation
18628 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
18629 configure: WARNING: pi.h: proceeding with the preprocessor's result
18630 configure: WARNING: pi.h: in the future, the compiler will take precedence
18631 configure: WARNING: ## -------------------------------------- ##
18632 configure: WARNING: ## Report this to bug-example@@example.org ##
18633 configure: WARNING: ## -------------------------------------- ##
18634 checking for pi.h... yes
18638 The proper way the handle this case is using the fourth argument
18639 (@pxref{Generic Headers}):
18642 $ @kbd{cat configure.ac}
18643 AC_INIT([Example], [1.0], [bug-example@@example.org])
18644 AC_CHECK_HEADERS([number.h pi.h], [], [],
18645 [[#if HAVE_NUMBER_H
18646 # include <number.h>
18649 $ @kbd{autoconf -Wall}
18650 $ @kbd{./configure}
18651 checking for gcc... gcc
18652 checking for C compiler default output... a.out
18653 checking whether the C compiler works... yes
18654 checking whether we are cross compiling... no
18655 checking for suffix of executables...
18656 checking for suffix of object files... o
18657 checking whether we are using the GNU C compiler... yes
18658 checking whether gcc accepts -g... yes
18659 checking for gcc option to accept ANSI C... none needed
18660 checking for number.h... yes
18661 checking for pi.h... yes
18664 See @ref{Particular Headers}, for a list of headers with their
18667 @c ===================================================== History of Autoconf.
18670 @chapter History of Autoconf
18671 @cindex History of autoconf
18673 You may be wondering, Why was Autoconf originally written? How did it
18674 get into its present form? (Why does it look like gorilla spit?) If
18675 you're not wondering, then this chapter contains no information useful
18676 to you, and you might as well skip it. If you @emph{are} wondering,
18677 then let there be light@enddots{}
18680 * Genesis:: Prehistory and naming of @command{configure}
18681 * Exodus:: The plagues of M4 and Perl
18682 * Leviticus:: The priestly code of portability arrives
18683 * Numbers:: Growth and contributors
18684 * Deuteronomy:: Approaching the promises of easy configuration
18690 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
18691 Free Software Foundation. As they were ported to more platforms and
18692 more programs were added, the number of @option{-D} options that users
18693 had to select in the makefile (around 20) became burdensome.
18694 Especially for me---I had to test each new release on a bunch of
18695 different systems. So I wrote a little shell script to guess some of
18696 the correct settings for the fileutils package, and released it as part
18697 of fileutils 2.0. That @command{configure} script worked well enough that
18698 the next month I adapted it (by hand) to create similar @command{configure}
18699 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
18700 also adapted one of my scripts for his @acronym{CVS} revision control system.
18702 Later that summer, I learned that Richard Stallman and Richard Pixley
18703 were developing similar scripts to use in the @acronym{GNU} compiler tools;
18704 so I adapted my @command{configure} scripts to support their evolving
18705 interface: using the file name @file{Makefile.in} as the templates;
18706 adding @samp{+srcdir}, the first option (of many); and creating
18707 @file{config.status} files.
18712 As I got feedback from users, I incorporated many improvements, using
18713 Emacs to search and replace, cut and paste, similar changes in each of
18714 the scripts. As I adapted more @acronym{GNU} utilities packages to use
18715 @command{configure} scripts, updating them all by hand became impractical.
18716 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
18717 mail saying that the @command{configure} scripts were great, and asking if
18718 I had a tool for generating them that I could send him. No, I thought,
18719 but I should! So I started to work out how to generate them. And the
18720 journey from the slavery of hand-written @command{configure} scripts to the
18721 abundance and ease of Autoconf began.
18723 Cygnus @command{configure}, which was being developed at around that time,
18724 is table driven; it is meant to deal mainly with a discrete number of
18725 system types with a small number of mainly unguessable features (such as
18726 details of the object file format). The automatic configuration system
18727 that Brian Fox had developed for Bash takes a similar approach. For
18728 general use, it seems to me a hopeless cause to try to maintain an
18729 up-to-date database of which features each variant of each operating
18730 system has. It's easier and more reliable to check for most features on
18731 the fly---especially on hybrid systems that people have hacked on
18732 locally or that have patches from vendors installed.
18734 I considered using an architecture similar to that of Cygnus
18735 @command{configure}, where there is a single @command{configure} script that
18736 reads pieces of @file{configure.in} when run. But I didn't want to have
18737 to distribute all of the feature tests with every package, so I settled
18738 on having a different @command{configure} made from each
18739 @file{configure.in} by a preprocessor. That approach also offered more
18740 control and flexibility.
18742 I looked briefly into using the Metaconfig package, by Larry Wall,
18743 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
18744 reasons. The @command{Configure} scripts it produces are interactive,
18745 which I find quite inconvenient; I didn't like the ways it checked for
18746 some features (such as library functions); I didn't know that it was
18747 still being maintained, and the @command{Configure} scripts I had
18748 seen didn't work on many modern systems (such as System V R4 and NeXT);
18749 it wasn't flexible in what it could do in response to a feature's
18750 presence or absence; I found it confusing to learn; and it was too big
18751 and complex for my needs (I didn't realize then how much Autoconf would
18752 eventually have to grow).
18754 I considered using Perl to generate my style of @command{configure}
18755 scripts, but decided that M4 was better suited to the job of simple
18756 textual substitutions: it gets in the way less, because output is
18757 implicit. Plus, everyone already has it. (Initially I didn't rely on
18758 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
18759 University of Maryland had recently been putting M4 front ends on
18760 several programs, including @code{tvtwm}, and I was interested in trying
18761 out a new language.
18766 Since my @command{configure} scripts determine the system's capabilities
18767 automatically, with no interactive user intervention, I decided to call
18768 the program that generates them Autoconfig. But with a version number
18769 tacked on, that name would be too long for old Unix file systems,
18770 so I shortened it to Autoconf.
18772 In the fall of 1991 I called together a group of fellow questers after
18773 the Holy Grail of portability (er, that is, alpha testers) to give me
18774 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
18775 and continued to add features and improve the techniques used in the
18776 checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up
18777 with the idea of making an Autoconf shell script to run M4
18778 and check for unresolved macro calls; Richard Pixley, who suggested
18779 running the compiler instead of searching the file system to find
18780 include files and symbols, for more accurate results; Karl Berry, who
18781 got Autoconf to configure @TeX{} and added the macro index to the
18782 documentation; and Ian Lance Taylor, who added support for creating a C
18783 header file as an alternative to putting @option{-D} options in a
18784 makefile, so he could use Autoconf for his @acronym{UUCP} package.
18785 The alpha testers cheerfully adjusted their files again and again as the
18786 names and calling conventions of the Autoconf macros changed from
18787 release to release. They all contributed many specific checks, great
18788 ideas, and bug fixes.
18793 In July 1992, after months of alpha testing, I released Autoconf 1.0,
18794 and converted many @acronym{GNU} packages to use it. I was surprised by how
18795 positive the reaction to it was. More people started using it than I
18796 could keep track of, including people working on software that wasn't
18797 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
18798 Autoconf continued to improve rapidly, as many people using the
18799 @command{configure} scripts reported problems they encountered.
18801 Autoconf turned out to be a good torture test for M4 implementations.
18802 Unix M4 started to dump core because of the length of the
18803 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
18804 M4 as well. Eventually, we realized that we needed to use some
18805 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
18806 particular, has an impoverished set of builtin macros; the System V
18807 version is better, but still doesn't provide everything we need.
18809 More development occurred as people put Autoconf under more stresses
18810 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
18811 david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose
18812 invalid arguments. Jim Blandy bravely coerced it into configuring
18813 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
18814 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
18815 @command{autoheader} script to automate the creation of C header file
18816 templates, and added a @option{--verbose} option to @command{configure}.
18817 Noah Friedman added the @option{--autoconf-dir} option and
18818 @code{AC_MACRODIR} environment variable. (He also coined the term
18819 @dfn{autoconfiscate} to mean ``adapt a software package to use
18820 Autoconf''.) Roland and Noah improved the quoting protection in
18821 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
18822 dealing with portability problems from February through June, 1993.
18825 @section Deuteronomy
18827 A long wish list for major features had accumulated, and the effect of
18828 several years of patching by various people had left some residual
18829 cruft. In April 1994, while working for Cygnus Support, I began a major
18830 revision of Autoconf. I added most of the features of the Cygnus
18831 @command{configure} that Autoconf had lacked, largely by adapting the
18832 relevant parts of Cygnus @command{configure} with the help of david zuhn
18833 and Ken Raeburn. These features include support for using
18834 @file{config.sub}, @file{config.guess}, @option{--host}, and
18835 @option{--target}; making links to files; and running @command{configure}
18836 scripts in subdirectories. Adding these features enabled Ken to convert
18837 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
18840 I added more features in response to other peoples' requests. Many
18841 people had asked for @command{configure} scripts to share the results of
18842 the checks between runs, because (particularly when configuring a large
18843 source tree, like Cygnus does) they were frustratingly slow. Mike
18844 Haertel suggested adding site-specific initialization scripts. People
18845 distributing software that had to unpack on MS-DOS asked for a way to
18846 override the @file{.in} extension on the file names, which produced file
18847 names like @file{config.h.in} containing two dots. Jim Avera did an
18848 extensive examination of the problems with quoting in @code{AC_DEFINE}
18849 and @code{AC_SUBST}; his insights led to significant improvements.
18850 Richard Stallman asked that compiler output be sent to @file{config.log}
18851 instead of @file{/dev/null}, to help people debug the Emacs
18852 @command{configure} script.
18854 I made some other changes because of my dissatisfaction with the quality
18855 of the program. I made the messages showing results of the checks less
18856 ambiguous, always printing a result. I regularized the names of the
18857 macros and cleaned up coding style inconsistencies. I added some
18858 auxiliary utilities that I had developed to help convert source code
18859 packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made
18860 the macros not interrupt each others' messages. (That feature revealed
18861 some performance bottlenecks in @acronym{GNU} M4, which he hastily
18862 corrected!) I reorganized the documentation around problems people want
18863 to solve. And I began a test suite, because experience had shown that
18864 Autoconf has a pronounced tendency to regress when we change it.
18866 Again, several alpha testers gave invaluable feedback, especially
18867 Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
18870 Finally, version 2.0 was ready. And there was much rejoicing. (And I
18871 have free time again. I think. Yeah, right.)
18874 @c ========================================================== Appendices
18876 @node Copying This Manual
18877 @appendix Copying This Manual
18881 * GNU Free Documentation License:: License for copying this manual
18890 * Environment Variable Index:: Index of environment variables used
18891 * Output Variable Index:: Index of variables set in output files
18892 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
18893 * Autoconf Macro Index:: Index of Autoconf macros
18894 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
18895 * Autotest Macro Index:: Index of Autotest macros
18896 * Program & Function Index:: Index of those with portability problems
18897 * Concept Index:: General index
18900 @node Environment Variable Index
18901 @appendixsec Environment Variable Index
18903 This is an alphabetical list of the environment variables that Autoconf
18908 @node Output Variable Index
18909 @appendixsec Output Variable Index
18911 This is an alphabetical list of the variables that Autoconf can
18912 substitute into files that it creates, typically one or more
18913 makefiles. @xref{Setting Output Variables}, for more information
18914 on how this is done.
18918 @node Preprocessor Symbol Index
18919 @appendixsec Preprocessor Symbol Index
18921 This is an alphabetical list of the C preprocessor symbols that the
18922 Autoconf macros define. To work with Autoconf, C source code needs to
18923 use these names in @code{#if} directives.
18927 @node Autoconf Macro Index
18928 @appendixsec Autoconf Macro Index
18930 This is an alphabetical list of the Autoconf macros.
18931 @ifset shortindexflag
18932 To make the list easier to use, the macros are listed without their
18933 preceding @samp{AC_}.
18938 @node M4 Macro Index
18939 @appendixsec M4 Macro Index
18941 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
18942 @ifset shortindexflag
18943 To make the list easier to use, the macros are listed without their
18944 preceding @samp{m4_} or @samp{AS_}.
18949 @node Autotest Macro Index
18950 @appendixsec Autotest Macro Index
18952 This is an alphabetical list of the Autotest macros.
18953 @ifset shortindexflag
18954 To make the list easier to use, the macros are listed without their
18955 preceding @samp{AT_}.
18960 @node Program & Function Index
18961 @appendixsec Program and Function Index
18963 This is an alphabetical list of the programs and functions which
18964 portability is discussed in this document.
18968 @node Concept Index
18969 @appendixsec Concept Index
18971 This is an alphabetical list of the files, tools, and concepts
18972 introduced in this document.
18978 @c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage
18979 @c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx
18980 @c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn
18981 @c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu
18982 @c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME
18983 @c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames
18984 @c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs
18985 @c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm
18986 @c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois
18987 @c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn
18988 @c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake
18989 @c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons
18990 @c LocalWords: distclean uninstall noindent versioning Tromey dir
18991 @c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST
18992 @c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize
18993 @c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG
18994 @c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd
18995 @c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS
18996 @c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC
18997 @c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd
18998 @c LocalWords: includedir infodir libexecdir localedir localstatedir mandir
18999 @c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir
19000 @c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd
19001 @c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar
19002 @c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES
19003 @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy
19004 @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD
19005 @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX
19006 @c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof
19007 @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW
19008 @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef
19009 @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC
19010 @c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK
19011 @c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc
19012 @c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM
19013 @c LocalWords: GETLODAVG SETGID getloadavg nlist GETMNTENT irix
19014 @c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT
19015 @c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime
19016 @c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval
19017 @c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll
19018 @c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF
19019 @c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert
19020 @c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable
19021 @c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS
19022 @c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB
19023 @c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm
19024 @c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS
19025 @c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable
19026 @c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw
19027 @c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid
19028 @c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str
19029 @c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX
19030 @c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC
19031 @c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx
19032 @c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS
19033 @c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs
19034 @c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se
19035 @c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK
19036 @c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io
19037 @c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting
19038 @c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote
19039 @c LocalWords: bregexp Overquote overquotation meisch maisch meische maische
19040 @c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius
19041 @c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh
19042 @c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn
19043 @c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa
19044 @c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA
19045 @c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc
19046 @c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp
19047 @c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM
19048 @c LocalWords: sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc
19049 @c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os
19050 @c LocalWords: fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped
19051 @c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg
19052 @c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline
19053 @c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin
19054 @c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC
19055 @c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix
19056 @c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn
19057 @c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL
19058 @c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er
19059 @c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl
19060 @c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn
19061 @c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn
19062 @c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec
19063 @c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS
19064 @c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln
19065 @c LocalWords: GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr
19066 @c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt
19067 @c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN
19068 @c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck
19069 @c LocalWords: LIBREADLINE lreadline lncurses libreadline
19071 @c Local Variables:
19073 @c ispell-local-dictionary: "american"