1 \input texinfo @c -*-texinfo-*-
2 @comment ========================================================
3 @comment %**start of header
4 @setfilename autoconf.info
8 @setcontentsaftertitlepage
11 @c @ovar(ARG, DEFAULT)
12 @c -------------------
13 @c The ARG is an optional argument. To be used for macro arguments in
14 @c their documentation (@defmac).
16 @r{[}@var{\varname\}@r{]}
19 @c @dvar(ARG, DEFAULT)
20 @c -------------------
21 @c The ARG is an optional argument, defaulting to DEFAULT. To be used
22 @c for macro arguments in their documentation (@defmac).
23 @macro dvar{varname, default}
24 @r{[}@var{\varname\} = @samp{\default\}@r{]}
27 @c Handling the indexes with Texinfo yields several different problems.
29 @c Because we want to drop out the AC_ part of the macro names in the
30 @c printed manual, but not in the other outputs, we need a layer above
31 @c the usual @acindex{} etc. That's why we first define indexes such as
32 @c acx meant to become the macro @acindex. First of all, using ``ac_''
33 @c does not work with makeinfo, and using ``ac1'' doesn't work with TeX.
34 @c So use something more regular ``acx''. Then you finish with a printed
35 @c index saying ``index is not existent''. Of course: you ought to use
36 @c two letters :( So you use capitals.
38 @c Second, when defining a macro in the TeX world, following spaces are
39 @c eaten. But then, since we embed @acxindex commands that use the end
40 @c of line as an end marker, the whole things wrecks itself. So make
41 @c sure you do *force* an additional end of line, add a ``@c''.
43 @c Finally, you might want to get rid of TeX expansion, using --expand
44 @c with texi2dvi. But then you wake up an old problem: we use macros
45 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
47 @c Define an environment variable index.
49 @c Define an output variable index.
51 @c Define a CPP variable index.
53 @c Define an Autoconf macro index that @defmac doesn't write to.
55 @c Define an Autotest macro index that @defmac doesn't write to.
57 @c Define an M4sugar macro index that @defmac doesn't write to.
59 @c Define an index for *foreign* programs: `mv' etc. Used for the
60 @c portability sections and so on.
65 @c Shall we factor AC_ out of the Autoconf macro index etc.?
72 @c Registering an AC_\MACRO\.
79 @ifclear shortindexflag
87 @c Registering an AH_\MACRO\.
95 @c Registering an AS_\MACRO\.
102 @ifclear shortindexflag
103 @macro asindex{macro}
110 @c Registering an AT_\MACRO\.
111 @ifset shortindexflag
112 @macro atindex{macro}
117 @ifclear shortindexflag
118 @macro atindex{macro}
125 @c Registering an AU_\MACRO\.
126 @macro auindex{macro}
133 @c Indexing a header.
134 @macro hdrindex{macro}
135 @prindex @file{\macro\}
141 @c Registering an m4_\MACRO\.
142 @ifset shortindexflag
143 @macro msindex{macro}
148 @ifclear shortindexflag
149 @macro msindex{macro}
155 @c Define an index for functions: `alloca' etc. Used for the
156 @c portability sections and so on. We can't use `fn' (aka `fnindex),
157 @c since `@defmac' goes into it => we'd get all the macros too.
159 @c FIXME: Aaarg! It seems there are too many indices for TeX :(
161 @c ! No room for a new @write .
162 @c l.112 @defcodeindex fu
164 @c so don't define yet another one :( Just put some tags before each
165 @c @prindex which is actually a @funindex.
170 @c @c Put the programs and functions into their own index.
171 @c @syncodeindex fu pr
173 @comment %**end of header
174 @comment ========================================================
178 This manual is for @acronym{GNU} Autoconf
179 (version @value{VERSION}, @value{UPDATED}),
180 a package for creating scripts to configure source code packages using
181 templates and an M4 macro package.
183 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
184 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
187 Permission is granted to copy, distribute and/or modify this document
188 under the terms of the @acronym{GNU} Free Documentation License,
189 Version 1.2 or any later version published by the Free Software
190 Foundation; with no Invariant Sections, with the Front-Cover texts
191 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
192 (a) below. A copy of the license is included in the section entitled
193 ``@acronym{GNU} Free Documentation License.''
195 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
196 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
197 published by the Free Software Foundation raise funds for
198 @acronym{GNU} development.''
204 @dircategory Software development
206 * Autoconf: (autoconf). Create source code configuration scripts.
209 @dircategory Individual utilities
211 * autoscan: (autoconf)autoscan Invocation.
212 Semi-automatic @file{configure.ac} writing
213 * ifnames: (autoconf)ifnames Invocation. Listing conditionals in source.
214 * autoconf: (autoconf)autoconf Invocation.
215 How to create configuration scripts
216 * autoreconf: (autoconf)autoreconf Invocation.
217 Remaking multiple @command{configure} scripts
218 * autoheader: (autoconf)autoheader Invocation.
219 How to create configuration templates
220 * autom4te: (autoconf)autom4te Invocation.
221 The Autoconf executables backbone
222 * configure: (autoconf)configure Invocation. Configuring a package.
223 * autoupdate: (autoconf)autoupdate Invocation.
224 Automatic update of @file{configure.ac}
225 * config.status: (autoconf)config.status Invocation. Recreating configurations.
226 * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite.
231 @subtitle Creating Automatic Configuration Scripts
232 @subtitle for version @value{VERSION}, @value{UPDATED}
233 @author David MacKenzie
235 @author Akim Demaille
237 @vskip 0pt plus 1filll
250 @c The master menu, created with texinfo-master-menu, goes here.
253 * Introduction:: Autoconf's purpose, strengths, and weaknesses
254 * The GNU Build System:: A set of tools for portable software packages
255 * Making configure Scripts:: How to organize and produce Autoconf scripts
256 * Setup:: Initialization and output
257 * Existing Tests:: Macros that check for particular features
258 * Writing Tests:: How to write new feature checks
259 * Results:: What to do with results from feature checks
260 * Programming in M4:: Layers on top of which Autoconf is written
261 * Writing Autoconf Macros:: Adding new macros to Autoconf
262 * Portable Shell:: Shell script portability pitfalls
263 * Manual Configuration:: Selecting features that can't be guessed
264 * Site Configuration:: Local defaults for @command{configure}
265 * Running configure Scripts:: How to use the Autoconf output
266 * config.status Invocation:: Recreating a configuration
267 * Obsolete Constructs:: Kept for backward compatibility
268 * Using Autotest:: Creating portable test suites
269 * FAQ:: Frequent Autoconf Questions, with answers
270 * History:: History of Autoconf
271 * Copying This Manual:: How to make copies of this manual
272 * Indices:: Indices of symbols, concepts, etc.
275 --- The Detailed Node Listing ---
277 The @acronym{GNU} Build System
279 * Automake:: Escaping Makefile hell
280 * Libtool:: Building libraries portably
281 * Pointers:: More info on the @acronym{GNU} build system
283 Making @command{configure} Scripts
285 * Writing configure.ac:: What to put in an Autoconf input file
286 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
287 * ifnames Invocation:: Listing the conditionals in source code
288 * autoconf Invocation:: How to create configuration scripts
289 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
291 Writing @file{configure.ac}
293 * Shell Script Compiler:: Autoconf as solution of a problem
294 * Autoconf Language:: Programming in Autoconf
295 * configure.ac Layout:: Standard organization of @file{configure.ac}
297 Initialization and Output Files
299 * Initializing configure:: Option processing etc.
300 * Notices:: Copyright, version numbers in @command{configure}
301 * Input:: Where Autoconf should find files
302 * Output:: Outputting results from the configuration
303 * Configuration Actions:: Preparing the output based on results
304 * Configuration Files:: Creating output files
305 * Makefile Substitutions:: Using output variables in @file{Makefile}s
306 * Configuration Headers:: Creating a configuration header file
307 * Configuration Commands:: Running arbitrary instantiation commands
308 * Configuration Links:: Links depending on the configuration
309 * Subdirectories:: Configuring independent packages together
310 * Default Prefix:: Changing the default installation prefix
312 Substitutions in Makefiles
314 * Preset Output Variables:: Output variables that are always set
315 * Installation Directory Variables:: Other preset output variables
316 * Build Directories:: Supporting multiple concurrent compiles
317 * Automatic Remaking:: Makefile rules for configuring
319 Configuration Header Files
321 * Header Templates:: Input for the configuration headers
322 * autoheader Invocation:: How to create configuration templates
323 * Autoheader Macros:: How to specify CPP templates
327 * Common Behavior:: Macros' standard schemes
328 * Alternative Programs:: Selecting between alternative programs
329 * Files:: Checking for the existence of files
330 * Libraries:: Library archives that might be missing
331 * Library Functions:: C library functions that might be missing
332 * Header Files:: Header files that might be missing
333 * Declarations:: Declarations that may be missing
334 * Structures:: Structures or members that might be missing
335 * Types:: Types that might be missing
336 * Compilers and Preprocessors:: Checking for compiling programs
337 * System Services:: Operating system services
338 * Posix Variants:: Special kludges for specific Posix variants
342 * Standard Symbols:: Symbols defined by the macros
343 * Default Includes:: Includes used by the generic macros
347 * Particular Programs:: Special handling to find certain programs
348 * Generic Programs:: How to find other programs
352 * Function Portability:: Pitfalls with usual functions
353 * Particular Functions:: Special handling to find certain functions
354 * Generic Functions:: How to find other functions
358 * Header Portability:: Collected knowledge on common headers
359 * Particular Headers:: Special handling to find certain headers
360 * Generic Headers:: How to find other headers
364 * Particular Declarations:: Macros to check for certain declarations
365 * Generic Declarations:: How to find other declarations
369 * Particular Structures:: Macros to check for certain structure members
370 * Generic Structures:: How to find other structure members
374 * Particular Types:: Special handling to find certain types
375 * Generic Types:: How to find other types
377 Compilers and Preprocessors
379 * Specific Compiler Characteristics:: Some portability issues
380 * Generic Compiler Characteristics:: Language independent tests and features
381 * C Compiler:: Checking its characteristics
382 * C++ Compiler:: Likewise
383 * Fortran Compiler:: Likewise
387 * Language Choice:: Selecting which language to use for testing
388 * Writing Test Programs:: Forging source files for compilers
389 * Running the Preprocessor:: Detecting preprocessor symbols
390 * Running the Compiler:: Detecting language or header features
391 * Running the Linker:: Detecting library features
392 * Run Time:: Testing for run-time features
393 * Systemology:: A zoology of operating systems
394 * Multiple Cases:: Tests for several possible values
396 Writing Test Programs
398 * Guidelines:: General rules for writing test programs
399 * Test Functions:: Avoiding pitfalls in test programs
400 * Generating Sources:: Source program boilerplate
404 * Defining Symbols:: Defining C preprocessor symbols
405 * Setting Output Variables:: Replacing variables in output files
406 * Caching Results:: Speeding up subsequent @command{configure} runs
407 * Printing Messages:: Notifying @command{configure} users
411 * Cache Variable Names:: Shell variables used in caches
412 * Cache Files:: Files @command{configure} uses for caching
413 * Cache Checkpointing:: Loading and saving the cache file
417 * M4 Quotation:: Protecting macros from unwanted expansion
418 * Using autom4te:: The Autoconf executables backbone
419 * Programming in M4sugar:: Convenient pure M4 macros
420 * Programming in M4sh:: Common shell Constructs
421 * File Descriptor Macros:: File descriptor macros for input and output
425 * Active Characters:: Characters that change the behavior of M4
426 * One Macro Call:: Quotation and one macro call
427 * Quotation and Nested Macros:: Macros calling macros
428 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
429 * Quadrigraphs:: Another way to escape special characters
430 * Quotation Rule Of Thumb:: One parenthesis, one quote
432 Using @command{autom4te}
434 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
435 * Customizing autom4te:: Customizing the Autoconf package
437 Programming in M4sugar
439 * Redefined M4 Macros:: M4 builtins changed in M4sugar
440 * Evaluation Macros:: More quotation and evaluation control
441 * Forbidden Patterns:: Catching unexpanded macros
443 Writing Autoconf Macros
445 * Macro Definitions:: Basic format of an Autoconf macro
446 * Macro Names:: What to call your new macros
447 * Reporting Messages:: Notifying @command{autoconf} users
448 * Dependencies Between Macros:: What to do when macros depend on other macros
449 * Obsoleting Macros:: Warning about old ways of doing things
450 * Coding Style:: Writing Autoconf macros @`a la Autoconf
452 Dependencies Between Macros
454 * Prerequisite Macros:: Ensuring required information
455 * Suggested Ordering:: Warning about possible ordering problems
456 * One-Shot Macros:: Ensuring a macro is called only once
458 Portable Shell Programming
460 * Shellology:: A zoology of shells
461 * Here-Documents:: Quirks and tricks
462 * File Descriptors:: FDs and redirections
463 * File System Conventions:: File names
464 * Shell Substitutions:: Variable and command expansions
465 * Assignments:: Varying side effects of assignments
466 * Parentheses:: Parentheses in shell scripts
467 * Slashes:: Slashes in shell scripts
468 * Special Shell Variables:: Variables you should not change
469 * Limitations of Builtins:: Portable use of not so portable /bin/sh
470 * Limitations of Usual Tools:: Portable use of portable tools
471 * Limitations of Make:: Portable Makefiles
475 * Specifying Names:: Specifying the system type
476 * Canonicalizing:: Getting the canonical system type
477 * Using System Type:: What to do with the system type
481 * External Software:: Working with other optional software
482 * Package Options:: Selecting optional features
483 * Pretty Help Strings:: Formatting help string
484 * Site Details:: Configuring site details
485 * Transforming Names:: Changing program names when installing
486 * Site Defaults:: Giving @command{configure} local defaults
488 Transforming Program Names When Installing
490 * Transformation Options:: @command{configure} options to transform names
491 * Transformation Examples:: Sample uses of transforming names
492 * Transformation Rules:: @file{Makefile} uses of transforming names
494 Running @command{configure} Scripts
496 * Basic Installation:: Instructions for typical cases
497 * Compilers and Options:: Selecting compilers and optimization
498 * Multiple Architectures:: Compiling for multiple architectures at once
499 * Installation Names:: Installing in different directories
500 * Optional Features:: Selecting optional features
501 * System Type:: Specifying the system type
502 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
503 * Defining Variables:: Specifying the compiler etc.
504 * configure Invocation:: Changing how @command{configure} runs
508 * Obsolete config.status Use:: Different calling convention
509 * acconfig.h:: Additional entries in @file{config.h.in}
510 * autoupdate Invocation:: Automatic update of @file{configure.ac}
511 * Obsolete Macros:: Backward compatibility macros
512 * Autoconf 1:: Tips for upgrading your files
513 * Autoconf 2.13:: Some fresher tips
515 Upgrading From Version 1
517 * Changed File Names:: Files you might rename
518 * Changed Makefiles:: New things to put in @file{Makefile.in}
519 * Changed Macros:: Macro calls you might replace
520 * Changed Results:: Changes in how to check test results
521 * Changed Macro Writing:: Better ways to write your own macros
523 Upgrading From Version 2.13
525 * Changed Quotation:: Broken code which used to work
526 * New Macros:: Interaction with foreign macros
527 * Hosts and Cross-Compilation:: Bugward compatibility kludges
528 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
529 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
531 Generating Test Suites with Autotest
533 * Using an Autotest Test Suite:: Autotest and the user
534 * Writing testsuite.at:: Autotest macros
535 * testsuite Invocation:: Running @command{testsuite} scripts
536 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
538 Using an Autotest Test Suite
540 * testsuite Scripts:: The concepts of Autotest
541 * Autotest Logs:: Their contents
543 Frequent Autoconf Questions, with answers
545 * Distributing:: Distributing @command{configure} scripts
546 * Why GNU m4:: Why not use the standard M4?
547 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
548 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
549 * Defining Directories:: Passing @code{datadir} to program
550 * autom4te.cache:: What is it? Can I remove it?
551 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
555 * Genesis:: Prehistory and naming of @command{configure}
556 * Exodus:: The plagues of M4 and Perl
557 * Leviticus:: The priestly code of portability arrives
558 * Numbers:: Growth and contributors
559 * Deuteronomy:: Approaching the promises of easy configuration
563 * GNU Free Documentation License:: License for copying this manual
567 * Environment Variable Index:: Index of environment variables used
568 * Output Variable Index:: Index of variables set in output files
569 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
570 * Autoconf Macro Index:: Index of Autoconf macros
571 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
572 * Autotest Macro Index:: Index of Autotest macros
573 * Program & Function Index:: Index of those with portability problems
574 * Concept Index:: General index
579 @c ============================================================= Introduction.
582 @chapter Introduction
586 A physicist, an engineer, and a computer scientist were discussing the
587 nature of God. ``Surely a Physicist,'' said the physicist, ``because
588 early in the Creation, God made Light; and you know, Maxwell's
589 equations, the dual nature of electromagnetic waves, the relativistic
590 consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
591 before making Light, God split the Chaos into Land and Water; it takes a
592 hell of an engineer to handle that big amount of mud, and orderly
593 separation of solids from liquids@dots{}'' The computer scientist
594 shouted: ``And the Chaos, where do you think it was coming from, hmm?''
598 @c (via Franc,ois Pinard)
600 Autoconf is a tool for producing shell scripts that automatically
601 configure software source code packages to adapt to many kinds of
602 Posix-like systems. The configuration scripts produced by Autoconf
603 are independent of Autoconf when they are run, so their users do not
604 need to have Autoconf.
606 The configuration scripts produced by Autoconf require no manual user
607 intervention when run; they do not normally even need an argument
608 specifying the system type. Instead, they individually test for the
609 presence of each feature that the software package they are for might need.
610 (Before each check, they print a one-line message stating what they are
611 checking for, so the user doesn't get too bored while waiting for the
612 script to finish.) As a result, they deal well with systems that are
613 hybrids or customized from the more common Posix variants. There is
614 no need to maintain files that list the features supported by each
615 release of each variant of Posix.
617 For each software package that Autoconf is used with, it creates a
618 configuration script from a template file that lists the system features
619 that the package needs or can use. After the shell code to recognize
620 and respond to a system feature has been written, Autoconf allows it to
621 be shared by many software packages that can use (or need) that feature.
622 If it later turns out that the shell code needs adjustment for some
623 reason, it needs to be changed in only one place; all of the
624 configuration scripts can be regenerated automatically to take advantage
627 The Metaconfig package is similar in purpose to Autoconf, but the
628 scripts it produces require manual user intervention, which is quite
629 inconvenient when configuring large source trees. Unlike Metaconfig
630 scripts, Autoconf scripts can support cross-compiling, if some care is
631 taken in writing them.
633 Autoconf does not solve all problems related to making portable
634 software packages---for a more complete solution, it should be used in
635 concert with other @acronym{GNU} build tools like Automake and
636 Libtool. These other tools take on jobs like the creation of a
637 portable, recursive @file{Makefile} with all of the standard targets,
638 linking of shared libraries, and so on. @xref{The GNU Build System},
639 for more information.
641 Autoconf imposes some restrictions on the names of macros used with
642 @code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
644 Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses
645 features that some versions of M4, including @acronym{GNU} M4 1.3,
646 do not have. You should use version 1.4.3 or later of @acronym{GNU} M4.
648 @xref{Autoconf 1}, for information about upgrading from version 1.
649 @xref{History}, for the story of Autoconf's development. @xref{FAQ},
650 for answers to some common questions about Autoconf.
652 See the @uref{http://www.gnu.org/software/autoconf/,
653 Autoconf web page} for up-to-date information, details on the mailing
654 lists, pointers to a list of known bugs, etc.
656 Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
657 list}. Past suggestions are
658 @uref{http://lists.gnu.org/archive/html/autoconf/, archived}.
660 Mail bug reports to @email{bug-autoconf@@gnu.org, the
661 Autoconf Bugs mailing list}. Past bug reports are
662 @uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}.
664 If possible, first check that your bug is
665 not already solved in current development versions, and that it has not
666 been reported yet. Be sure to include all the needed information and a
667 short @file{configure.ac} that demonstrates the problem.
669 Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the
670 @uref{http://savannah.gnu.org/projects/autoconf/, Autoconf
671 Summary} for details. Patches relative to the
672 current @acronym{CVS} version can be sent for review to the
673 @email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
675 @uref{http://lists.gnu.org/archive/html/autoconf-patches/, archived}.
677 Because of its mission, the Autoconf package itself
678 includes only a set of often-used
679 macros that have already demonstrated their usefulness. Nevertheless,
680 if you wish to share your macros, or find existing ones, see the
681 @uref{http://www.gnu.org/software/ac-archive/, @acronym{GNU} Autoconf Macro
682 Archive}, which is kindly run by @email{simons@@cryp.to,
686 @c ================================================= The GNU Build System
688 @node The GNU Build System
689 @chapter The @acronym{GNU} Build System
690 @cindex GNU build system
692 Autoconf solves an important problem---reliable discovery of
693 system-specific build and run-time information---but this is only one
694 piece of the puzzle for the development of portable software. To this
695 end, the @acronym{GNU} project has developed a suite of integrated
696 utilities to finish the job Autoconf started: the @acronym{GNU} build
697 system, whose most important components are Autoconf, Automake, and
698 Libtool. In this chapter, we introduce you to those tools, point you
699 to sources of more information, and try to convince you to use the
700 entire @acronym{GNU} build system for your software.
703 * Automake:: Escaping Makefile hell
704 * Libtool:: Building libraries portably
705 * Pointers:: More info on the @acronym{GNU} build system
711 The ubiquity of @command{make} means that a @file{Makefile} is almost the
712 only viable way to distribute automatic build rules for software, but
713 one quickly runs into @command{make}'s numerous limitations. Its lack of
714 support for automatic dependency tracking, recursive builds in
715 subdirectories, reliable timestamps (e.g., for network file systems), and
716 so on, mean that developers must painfully (and often incorrectly)
717 reinvent the wheel for each project. Portability is non-trivial, thanks
718 to the quirks of @command{make} on many systems. On top of all this is the
719 manual labor required to implement the many standard targets that users
720 have come to expect (@code{make install}, @code{make distclean},
721 @code{make uninstall}, etc.). Since you are, of course, using Autoconf,
722 you also have to insert repetitive code in your @code{Makefile.in} to
723 recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
724 provided by @command{configure}. Into this mess steps @dfn{Automake}.
727 Automake allows you to specify your build needs in a @code{Makefile.am}
728 file with a vastly simpler and more powerful syntax than that of a plain
729 @code{Makefile}, and then generates a portable @code{Makefile.in} for
730 use with Autoconf. For example, the @code{Makefile.am} to build and
731 install a simple ``Hello world'' program might look like:
735 hello_SOURCES = hello.c
739 The resulting @code{Makefile.in} (~400 lines) automatically supports all
740 the standard targets, the substitutions provided by Autoconf, automatic
741 dependency tracking, @code{VPATH} building, and so on. @command{make} will
742 build the @code{hello} program, and @code{make install} will install it
743 in @file{/usr/local/bin} (or whatever prefix was given to
744 @command{configure}, if not @file{/usr/local}).
746 The benefits of Automake increase for larger packages (especially ones
747 with subdirectories), but even for small programs the added convenience
748 and portability can be substantial. And that's not all@enddots{}
753 Very often, one wants to build not only programs, but libraries, so that
754 other programs can benefit from the fruits of your labor. Ideally, one
755 would like to produce @emph{shared} (dynamically linked) libraries,
756 which can be used by multiple programs without duplication on disk or in
757 memory and can be updated independently of the linked programs.
758 Producing shared libraries portably, however, is the stuff of
759 nightmares---each system has its own incompatible tools, compiler flags,
760 and magic incantations. Fortunately, @acronym{GNU} provides a solution:
764 Libtool handles all the requirements of building shared libraries for
765 you, and at this time seems to be the @emph{only} way to do so with any
766 portability. It also handles many other headaches, such as: the
767 interaction of @code{Makefile} rules with the variable suffixes of
768 shared libraries, linking reliably with shared libraries before they are
769 installed by the superuser, and supplying a consistent versioning system
770 (so that different versions of a library can be installed or upgraded
771 without breaking binary compatibility). Although Libtool, like
772 Autoconf, can be used without Automake, it is most simply utilized in
773 conjunction with Automake---there, Libtool is used automatically
774 whenever shared libraries are needed, and you need not know its syntax.
779 Developers who are used to the simplicity of @command{make} for small
780 projects on a single system might be daunted at the prospect of
781 learning to use Automake and Autoconf. As your software is
782 distributed to more and more users, however, you will otherwise
783 quickly find yourself putting lots of effort into reinventing the
784 services that the @acronym{GNU} build tools provide, and making the
785 same mistakes that they once made and overcame. (Besides, since
786 you're already learning Autoconf, Automake will be a piece of cake.)
788 There are a number of places that you can go to for more information on
789 the @acronym{GNU} build tools.
796 @uref{http://www.gnu.org/software/autoconf/, Autoconf},
797 @uref{http://www.gnu.org/software/automake/, Automake}, and
798 @uref{http://www.gnu.org/software/libtool/, Libtool}.
800 @item Automake Manual
802 @xref{Top,,Automake,automake,@acronym{GNU} Automake}, for more
803 information on Automake.
807 The book @cite{@acronym{GNU} Autoconf, Automake and
808 Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool},
809 by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally
810 New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU}
811 build environment. You can also find
812 @uref{http://sources.redhat.com/autobook/, the entire book on-line}.
816 @c ================================================= Making configure Scripts.
818 @node Making configure Scripts
819 @chapter Making @command{configure} Scripts
820 @cindex @file{aclocal.m4}
821 @cindex @command{configure}
823 The configuration scripts that Autoconf produces are by convention
824 called @command{configure}. When run, @command{configure} creates several
825 files, replacing configuration parameters in them with appropriate
826 values. The files that @command{configure} creates are:
830 one or more @file{Makefile} files, usually one in each subdirectory of the
831 package (@pxref{Makefile Substitutions});
834 optionally, a C header file, the name of which is configurable,
835 containing @code{#define} directives (@pxref{Configuration Headers});
838 a shell script called @file{config.status} that, when run, will recreate
839 the files listed above (@pxref{config.status Invocation});
842 an optional shell script normally called @file{config.cache}
843 (created when using @samp{configure --config-cache}) that
844 saves the results of running many of the tests (@pxref{Cache Files});
847 a file called @file{config.log} containing any messages produced by
848 compilers, to help debugging if @command{configure} makes a mistake.
851 @cindex @file{configure.in}
852 @cindex @file{configure.ac}
853 To create a @command{configure} script with Autoconf, you need to write an
854 Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
855 @command{autoconf} on it. If you write your own feature tests to
856 supplement those that come with Autoconf, you might also write files
857 called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
858 file to contain @code{#define} directives, you might also run
859 @command{autoheader}, and you will distribute the generated file
860 @file{config.h.in} with the package.
862 Here is a diagram showing how the files that can be used in
863 configuration are produced. Programs that are executed are suffixed by
864 @samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
865 @command{autoconf} and @command{autoheader} also read the installed Autoconf
866 macro files (by reading @file{autoconf.m4}).
869 Files used in preparing a software package for distribution:
871 your source files --> [autoscan*] --> [configure.scan] --> configure.ac
875 | .------> autoconf* -----> configure
877 | `-----> [autoheader*] --> [config.h.in]
881 Makefile.in -------------------------------> Makefile.in
885 Files used in configuring a software package:
888 .-------------> [config.cache]
889 configure* ------------+-------------> config.log
891 [config.h.in] -. v .-> [config.h] -.
892 +--> config.status* -+ +--> make*
893 Makefile.in ---' `-> Makefile ---'
898 * Writing configure.ac:: What to put in an Autoconf input file
899 * autoscan Invocation:: Semi-automatic @file{configure.ac} writing
900 * ifnames Invocation:: Listing the conditionals in source code
901 * autoconf Invocation:: How to create configuration scripts
902 * autoreconf Invocation:: Remaking multiple @command{configure} scripts
905 @node Writing configure.ac
906 @section Writing @file{configure.ac}
908 To produce a @command{configure} script for a software package, create a
909 file called @file{configure.ac} that contains invocations of the
910 Autoconf macros that test the system features your package needs or can
911 use. Autoconf macros already exist to check for many features; see
912 @ref{Existing Tests}, for their descriptions. For most other features,
913 you can use Autoconf template macros to produce custom checks; see
914 @ref{Writing Tests}, for information about them. For especially tricky
915 or specialized features, @file{configure.ac} might need to contain some
916 hand-crafted shell commands; see @ref{Portable Shell}. The
917 @command{autoscan} program can give you a good start in writing
918 @file{configure.ac} (@pxref{autoscan Invocation}, for more information).
920 Previous versions of Autoconf promoted the name @file{configure.in},
921 which is somewhat ambiguous (the tool needed to process this file is not
922 described by its extension), and introduces a slight confusion with
923 @file{config.h.in} and so on (for which @samp{.in} means ``to be
924 processed by @command{configure}''). Using @file{configure.ac} is now
928 * Shell Script Compiler:: Autoconf as solution of a problem
929 * Autoconf Language:: Programming in Autoconf
930 * configure.ac Layout:: Standard organization of @file{configure.ac}
933 @node Shell Script Compiler
934 @subsection A Shell Script Compiler
936 Just as for any other computer language, in order to properly program
937 @file{configure.ac} in Autoconf you must understand @emph{what} problem
938 the language tries to address and @emph{how} it does so.
940 The problem Autoconf addresses is that the world is a mess. After all,
941 you are using Autoconf in order to have your package compile easily on
942 all sorts of different systems, some of them being extremely hostile.
943 Autoconf itself bears the price for these differences: @command{configure}
944 must run on all those systems, and thus @command{configure} must limit itself
945 to their lowest common denominator of features.
947 Naturally, you might then think of shell scripts; who needs
948 @command{autoconf}? A set of properly written shell functions is enough to
949 make it easy to write @command{configure} scripts by hand. Sigh!
950 Unfortunately, shell functions do not belong to the least common
951 denominator; therefore, where you would like to define a function and
952 use it ten times, you would instead need to copy its body ten times.
954 So, what is really needed is some kind of compiler, @command{autoconf},
955 that takes an Autoconf program, @file{configure.ac}, and transforms it
956 into a portable shell script, @command{configure}.
958 How does @command{autoconf} perform this task?
960 There are two obvious possibilities: creating a brand new language or
961 extending an existing one. The former option is very attractive: all
962 sorts of optimizations could easily be implemented in the compiler and
963 many rigorous checks could be performed on the Autoconf program
964 (e.g., rejecting any non-portable construct). Alternatively, you can
965 extend an existing language, such as the @code{sh} (Bourne shell)
968 Autoconf does the latter: it is a layer on top of @code{sh}. It was
969 therefore most convenient to implement @command{autoconf} as a macro
970 expander: a program that repeatedly performs @dfn{macro expansions} on
971 text input, replacing macro calls with macro bodies and producing a pure
972 @code{sh} script in the end. Instead of implementing a dedicated
973 Autoconf macro expander, it is natural to use an existing
974 general-purpose macro language, such as M4, and implement the extensions
975 as a set of M4 macros.
978 @node Autoconf Language
979 @subsection The Autoconf Language
982 The Autoconf language is very different from many other computer
983 languages because it treats actual code the same as plain text. Whereas
984 in C, for instance, data and instructions have very different syntactic
985 status, in Autoconf their status is rigorously the same. Therefore, we
986 need a means to distinguish literal strings from text to be expanded:
989 When calling macros that take arguments, there must not be any white
990 space between the macro name and the open parenthesis. Arguments should
991 be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
992 separated by commas. Any leading blanks or newlines in arguments are ignored,
993 unless they are quoted. You should always quote an argument that
994 might contain a macro name, comma, parenthesis, or a leading blank or
995 newline. This rule applies recursively for every macro
996 call, including macros called from other macros.
1001 AC_CHECK_HEADER([stdio.h],
1002 [AC_DEFINE([HAVE_STDIO_H], [1],
1003 [Define to 1 if you have <stdio.h>.])],
1004 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1008 is quoted properly. You may safely simplify its quotation to:
1011 AC_CHECK_HEADER([stdio.h],
1012 [AC_DEFINE([HAVE_STDIO_H], 1,
1013 [Define to 1 if you have <stdio.h>.])],
1014 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1018 because @samp{1} cannot contain a macro call. Here, the argument of
1019 @code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be
1020 interpreted as an argument separator. Also, @samp{AC_CHECK_HEADER}'s
1021 second and third arguments must be quoted, since those arguments contain
1022 macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h},
1023 and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but
1024 if you unwisely defined a macro with a name like @samp{Define} or
1025 @samp{stdio} then they would need quoting. Cautious Autoconf users
1026 would keep the quotes, but many Autoconf users find such precautions
1027 annoying, and would rewrite the example as follows:
1030 AC_CHECK_HEADER(stdio.h,
1031 [AC_DEFINE(HAVE_STDIO_H, 1,
1032 [Define to 1 if you have <stdio.h>.])],
1033 [AC_MSG_ERROR([Sorry, can't do anything for you])])
1037 This is safe, so long as you adopt good naming conventions and do not
1038 define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or
1039 @samp{h}. Though it is also safe here to omit the quotes around
1040 @samp{Define to 1 if you have <stdio.h>.} this is not recommended, as
1041 message strings are more likely to inadvertently contain commas.
1043 The following example is wrong and dangerous, as it is underquoted:
1046 AC_CHECK_HEADER(stdio.h,
1047 AC_DEFINE(HAVE_STDIO_H, 1,
1048 Define to 1 if you have <stdio.h>.),
1049 AC_MSG_ERROR([Sorry, can't do anything for you]))
1052 In other cases, you may have to use text that also resembles a macro
1053 call. You must quote that text even when it is not passed as a macro
1057 echo "Hard rock was here! --[AC_DC]"
1061 which will result in
1064 echo "Hard rock was here! --AC_DC"
1068 When you use the same text in a macro argument, you must therefore have
1069 an extra quotation level (since one is stripped away by the macro
1070 substitution). In general, then, it is a good idea to @emph{use double
1071 quoting for all literal string arguments}:
1074 AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
1077 You are now able to understand one of the constructs of Autoconf that
1078 has been continually misunderstood@dots{} The rule of thumb is that
1079 @emph{whenever you expect macro expansion, expect quote expansion};
1080 i.e., expect one level of quotes to be lost. For instance:
1083 AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
1087 is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
1088 @samp{char b[10];} and will be expanded once, which results in
1089 @samp{char b10;}. (There was an idiom common in Autoconf's past to
1090 address this issue via the M4 @code{changequote} primitive, but do not
1091 use it!) Let's take a closer look: the author meant the first argument
1092 to be understood as a literal, and therefore it must be quoted twice:
1095 AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
1099 Voil@`a, you actually produce @samp{char b[10];} this time!
1101 On the other hand, descriptions (e.g., the last parameter of
1102 @code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they
1103 are subject to line breaking, for example---and should not be double quoted.
1104 Even if these descriptions are short and are not actually broken, double
1105 quoting them yields weird results.
1107 Some macros take optional arguments, which this documentation represents
1108 as @ovar{arg} (not to be confused with the quote characters). You may
1109 just leave them empty, or use @samp{[]} to make the emptiness of the
1110 argument explicit, or you may simply omit the trailing commas. The
1111 three lines below are equivalent:
1114 AC_CHECK_HEADERS([stdio.h], [], [], [])
1115 AC_CHECK_HEADERS([stdio.h],,,)
1116 AC_CHECK_HEADERS([stdio.h])
1119 It is best to put each macro call on its own line in
1120 @file{configure.ac}. Most of the macros don't add extra newlines; they
1121 rely on the newline after the macro call to terminate the commands.
1122 This approach makes the generated @command{configure} script a little
1123 easier to read by not inserting lots of blank lines. It is generally
1124 safe to set shell variables on the same line as a macro call, because
1125 the shell allows assignments without intervening newlines.
1127 You can include comments in @file{configure.ac} files by starting them
1128 with the @samp{#}. For example, it is helpful to begin
1129 @file{configure.ac} files with a line like this:
1132 # Process this file with autoconf to produce a configure script.
1135 @node configure.ac Layout
1136 @subsection Standard @file{configure.ac} Layout
1138 The order in which @file{configure.ac} calls the Autoconf macros is not
1139 important, with a few exceptions. Every @file{configure.ac} must
1140 contain a call to @code{AC_INIT} before the checks, and a call to
1141 @code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1142 rely on other macros having been called first, because they check
1143 previously set values of some variables to decide what to do. These
1144 macros are noted in the individual descriptions (@pxref{Existing
1145 Tests}), and they also warn you when @command{configure} is created if they
1146 are called out of order.
1148 To encourage consistency, here is a suggested order for calling the
1149 Autoconf macros. Generally speaking, the things near the end of this
1150 list are those that could depend on things earlier in it. For example,
1151 library functions could be affected by types and libraries.
1155 Autoconf requirements
1156 @code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1157 information on the package
1159 checks for libraries
1160 checks for header files
1162 checks for structures
1163 checks for compiler characteristics
1164 checks for library functions
1165 checks for system services
1166 @code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1172 @node autoscan Invocation
1173 @section Using @command{autoscan} to Create @file{configure.ac}
1174 @cindex @command{autoscan}
1176 The @command{autoscan} program can help you create and/or maintain a
1177 @file{configure.ac} file for a software package. @command{autoscan}
1178 examines source files in the directory tree rooted at a directory given
1179 as a command line argument, or the current directory if none is given.
1180 It searches the source files for common portability problems and creates
1181 a file @file{configure.scan} which is a preliminary @file{configure.ac}
1182 for that package, and checks a possibly existing @file{configure.ac} for
1185 When using @command{autoscan} to create a @file{configure.ac}, you
1186 should manually examine @file{configure.scan} before renaming it to
1187 @file{configure.ac}; it will probably need some adjustments.
1188 Occasionally, @command{autoscan} outputs a macro in the wrong order
1189 relative to another macro, so that @command{autoconf} produces a warning;
1190 you need to move such macros manually. Also, if you want the package to
1191 use a configuration header file, you must add a call to
1192 @code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1193 also have to change or add some @code{#if} directives to your program in
1194 order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1195 information about a program that can help with that job).
1197 When using @command{autoscan} to maintain a @file{configure.ac}, simply
1198 consider adding its suggestions. The file @file{autoscan.log} will
1199 contain detailed information on why a macro is requested.
1201 @command{autoscan} uses several data files (installed along with Autoconf)
1202 to determine which macros to output when it finds particular symbols in
1203 a package's source files. These data files all have the same format:
1204 each line consists of a symbol, one or more blanks, and the Autoconf macro to
1205 output if that symbol is encountered. Lines starting with @samp{#} are
1208 @command{autoscan} accepts the following options:
1213 Print a summary of the command line options and exit.
1217 Print the version number of Autoconf and exit.
1221 Print the names of the files it examines and the potentially interesting
1222 symbols it finds in them. This output can be voluminous.
1224 @item --include=@var{dir}
1226 Append @var{dir} to the include path. Multiple invocations accumulate.
1228 @item --prepend-include=@var{dir}
1230 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1233 @node ifnames Invocation
1234 @section Using @command{ifnames} to List Conditionals
1235 @cindex @command{ifnames}
1237 @command{ifnames} can help you write @file{configure.ac} for a software
1238 package. It prints the identifiers that the package already uses in C
1239 preprocessor conditionals. If a package has already been set up to have
1240 some portability, @command{ifnames} can thus help you figure out what its
1241 @command{configure} needs to check for. It may help fill in some gaps in a
1242 @file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1245 @command{ifnames} scans all of the C source files named on the command line
1246 (or the standard input, if none are given) and writes to the standard
1247 output a sorted list of all the identifiers that appear in those files
1248 in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1249 directives. It prints each identifier on a line, followed by a
1250 space-separated list of the files in which that identifier occurs.
1253 @command{ifnames} accepts the following options:
1258 Print a summary of the command line options and exit.
1262 Print the version number of Autoconf and exit.
1265 @node autoconf Invocation
1266 @section Using @command{autoconf} to Create @command{configure}
1267 @cindex @command{autoconf}
1269 To create @command{configure} from @file{configure.ac}, run the
1270 @command{autoconf} program with no arguments. @command{autoconf} processes
1271 @file{configure.ac} with the M4 macro processor, using the
1272 Autoconf macros. If you give @command{autoconf} an argument, it reads that
1273 file instead of @file{configure.ac} and writes the configuration script
1274 to the standard output instead of to @command{configure}. If you give
1275 @command{autoconf} the argument @option{-}, it reads from the standard
1276 input instead of @file{configure.ac} and writes the configuration script
1277 to the standard output.
1279 The Autoconf macros are defined in several files. Some of the files are
1280 distributed with Autoconf; @command{autoconf} reads them first. Then it
1281 looks for the optional file @file{acsite.m4} in the directory that
1282 contains the distributed Autoconf macro files, and for the optional file
1283 @file{aclocal.m4} in the current directory. Those files can contain
1284 your site's or the package's own Autoconf macro definitions
1285 (@pxref{Writing Autoconf Macros}, for more information). If a macro is
1286 defined in more than one of the files that @command{autoconf} reads, the
1287 last definition it reads overrides the earlier ones.
1289 @command{autoconf} accepts the following options:
1294 Print a summary of the command line options and exit.
1298 Print the version number of Autoconf and exit.
1302 Report processing steps.
1306 Don't remove the temporary files.
1310 Remake @file{configure} even if newer than its input files.
1312 @item --include=@var{dir}
1314 Append @var{dir} to the include path. Multiple invocations accumulate.
1316 @item --prepend-include=@var{dir}
1318 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1320 @item --output=@var{file}
1321 @itemx -o @var{file}
1322 Save output (script or trace) to @var{file}. The file @option{-} stands
1323 for the standard output.
1325 @item --warnings=@var{category}
1326 @itemx -W @var{category}
1328 Report the warnings related to @var{category} (which can actually be a
1329 comma separated list). @xref{Reporting Messages}, macro
1330 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1335 report all the warnings
1341 treats warnings as errors
1343 @item no-@var{category}
1344 disable warnings falling into @var{category}
1347 Warnings about @samp{syntax} are enabled by default, and the environment
1348 variable @env{WARNINGS}, a comma separated list of categories, is
1349 honored as well. Passing @samp{-W @var{category}} will actually behave as if
1350 you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
1351 you want to disable the defaults and @env{WARNINGS}, but (for example)
1352 enable the warnings about obsolete constructs, you would use @option{-W
1356 @cindex Macro invocation stack
1357 Because @command{autoconf} uses @command{autom4te} behind the scenes, it
1358 displays a back trace for errors, but not for warnings; if you want
1359 them, just pass @option{-W error}. @xref{autom4te Invocation}, for some
1362 @item --trace=@var{macro}[:@var{format}]
1363 @itemx -t @var{macro}[:@var{format}]
1364 Do not create the @command{configure} script, but list the calls to
1365 @var{macro} according to the @var{format}. Multiple @option{--trace}
1366 arguments can be used to list several macros. Multiple @option{--trace}
1367 arguments for a single macro are not cumulative; instead, you should
1368 just make @var{format} as long as needed.
1370 The @var{format} is a regular string, with newlines if desired, and
1371 several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1372 @ref{autom4te Invocation}, for details on the @var{format}.
1374 @item --initialization
1376 By default, @option{--trace} does not trace the initialization of the
1377 Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1378 results in a noticeable speedup, but can be disabled by this option.
1382 It is often necessary to check the content of a @file{configure.ac}
1383 file, but parsing it yourself is extremely fragile and error-prone. It
1384 is suggested that you rely upon @option{--trace} to scan
1385 @file{configure.ac}. For instance, to find the list of variables that
1386 are substituted, use:
1390 $ @kbd{autoconf -t AC_SUBST}
1391 configure.ac:2:AC_SUBST:ECHO_C
1392 configure.ac:2:AC_SUBST:ECHO_N
1393 configure.ac:2:AC_SUBST:ECHO_T
1394 @i{More traces deleted}
1399 The example below highlights the difference between @samp{$@@},
1400 @samp{$*}, and @strong{$%}.
1404 $ @kbd{cat configure.ac}
1405 AC_DEFINE(This, is, [an
1407 $ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1414 $: This:is:an [example]
1419 The @var{format} gives you a lot of freedom:
1423 $ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1424 $ac_subst@{"ECHO_C"@} = "configure.ac:2";
1425 $ac_subst@{"ECHO_N"@} = "configure.ac:2";
1426 $ac_subst@{"ECHO_T"@} = "configure.ac:2";
1427 @i{More traces deleted}
1432 A long @var{separator} can be used to improve the readability of complex
1433 structures, and to ease their parsing (for instance when no single
1434 character is suitable as a separator):
1438 $ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1439 ACLOCAL|:::::|aclocal|:::::|$missing_dir
1440 AUTOCONF|:::::|autoconf|:::::|$missing_dir
1441 AUTOMAKE|:::::|automake|:::::|$missing_dir
1442 @i{More traces deleted}
1446 @node autoreconf Invocation
1447 @section Using @command{autoreconf} to Update @command{configure} Scripts
1448 @cindex @command{autoreconf}
1450 Installing the various components of the @acronym{GNU} Build System can be
1451 tedious: running @command{autopoint} for Gettext, @command{automake} for
1452 @file{Makefile.in} etc.@: in each directory. It may be needed either
1453 because some tools such as @command{automake} have been updated on your
1454 system, or because some of the sources such as @file{configure.ac} have
1455 been updated, or finally, simply in order to install the @acronym{GNU} Build
1456 System in a fresh tree.
1458 @command{autoreconf} runs @command{autoconf}, @command{autoheader},
1459 @command{aclocal}, @command{automake}, @command{libtoolize}, and
1460 @command{autopoint} (when appropriate) repeatedly to update the
1461 @acronym{GNU} Build System in the specified directories and their
1462 subdirectories (@pxref{Subdirectories}). By default, it only remakes
1463 those files that are older than their sources.
1465 If you install a new version of some tool, you can make
1466 @command{autoreconf} remake @emph{all} of the files by giving it the
1467 @option{--force} option.
1469 @xref{Automatic Remaking}, for @file{Makefile} rules to automatically
1470 remake @command{configure} scripts when their source files change. That
1471 method handles the timestamps of configuration header templates
1472 properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1473 @option{--localdir=@var{dir}}.
1476 @cindex @command{autopoint}
1477 Gettext supplies the @command{autopoint} command to add translation
1478 infrastructure to a source package. If you use @command{autopoint},
1479 your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and
1480 @code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint
1481 Invocation,, Invoking the @code{autopoint} Program, gettext, GNU
1482 @code{gettext} utilities}, for further details.
1485 @command{autoreconf} accepts the following options:
1490 Print a summary of the command line options and exit.
1494 Print the version number of Autoconf and exit.
1497 Print the name of each directory where @command{autoreconf} runs
1498 @command{autoconf} (and @command{autoheader}, if appropriate).
1502 Don't remove the temporary files.
1506 Remake even @file{configure} scripts and configuration headers that are
1507 newer than their input files (@file{configure.ac} and, if present,
1512 Install the missing auxiliary files in the package. By default, files
1513 are copied; this can be changed with @option{--symlink}.
1515 If deemed appropriate, this option triggers calls to
1516 @samp{automake --add-missing},
1517 @samp{libtoolize}, @samp{autopoint}, etc.
1521 When used with @option{--install}, install symbolic links to the missing
1522 auxiliary files instead of copying them.
1526 When the directories were configured, update the configuration by
1527 running @samp{./config.status --recheck && ./config.status}, and then
1530 @item --include=@var{dir}
1532 Append @var{dir} to the include path. Multiple invocations accumulate.
1534 @item --prepend-include=@var{dir}
1536 Prepend @var{dir} to the include path. Multiple invocations accumulate.
1538 @item --warnings=@var{category}
1539 @itemx -W @var{category}
1541 Report the warnings related to @var{category} (which can actually be a
1542 comma separated list).
1546 related to cross compilation issues.
1549 report the uses of obsolete constructs.
1555 dubious syntactic constructs.
1558 report all the warnings
1564 treats warnings as errors
1566 @item no-@var{category}
1567 disable warnings falling into @var{category}
1570 Warnings about @samp{syntax} are enabled by default, and the environment
1571 variable @env{WARNINGS}, a comma separated list of categories, is
1572 honored as well. Passing @samp{-W @var{category}} will actually behave as if
1573 you had passed @samp{--warnings=syntax,$WARNINGS,@var{category}}. If
1574 you want to disable the defaults and @env{WARNINGS}, but (for example)
1575 enable the warnings about obsolete constructs, you would use @option{-W
1580 @c ========================================= Initialization and Output Files.
1583 @chapter Initialization and Output Files
1585 Autoconf-generated @command{configure} scripts need some information about
1586 how to initialize, such as how to find the package's source files and
1587 about the output files to produce. The following sections describe the
1588 initialization and the creation of output files.
1591 * Initializing configure:: Option processing etc.
1592 * Notices:: Copyright, version numbers in @command{configure}
1593 * Input:: Where Autoconf should find files
1594 * Output:: Outputting results from the configuration
1595 * Configuration Actions:: Preparing the output based on results
1596 * Configuration Files:: Creating output files
1597 * Makefile Substitutions:: Using output variables in @file{Makefile}s
1598 * Configuration Headers:: Creating a configuration header file
1599 * Configuration Commands:: Running arbitrary instantiation commands
1600 * Configuration Links:: Links depending on the configuration
1601 * Subdirectories:: Configuring independent packages together
1602 * Default Prefix:: Changing the default installation prefix
1605 @node Initializing configure
1606 @section Initializing @command{configure}
1608 Every @command{configure} script must call @code{AC_INIT} before doing
1609 anything else. The only other required macro is @code{AC_OUTPUT}
1612 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1614 Process any command-line arguments and perform various initializations
1617 Set the name of the @var{package} and its @var{version}. These are
1618 typically used in @option{--version} support, including that of
1619 @command{configure}. The optional argument @var{bug-report} should be
1620 the email to which users should send bug reports. The package
1621 @var{tarname} differs from @var{package}: the latter designates the full
1622 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
1623 distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1624 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
1625 other than alphanumerics and underscores are changed to @samp{-}.
1627 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
1628 there should not be any shell computation, but they can be computed by
1631 The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables
1632 (e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1633 @code{PACKAGE_NAME}) are defined by @code{AC_INIT}:
1636 @item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1637 @acindex{PACKAGE_NAME}
1638 @ovindex PACKAGE_NAME
1639 @cvindex PACKAGE_NAME
1640 Exactly @var{package}.
1642 @item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1643 @acindex{PACKAGE_TARNAME}
1644 @ovindex PACKAGE_TARNAME
1645 @cvindex PACKAGE_TARNAME
1646 Exactly @var{tarname}.
1648 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1649 @acindex{PACKAGE_VERSION}
1650 @ovindex PACKAGE_VERSION
1651 @cvindex PACKAGE_VERSION
1652 Exactly @var{version}.
1654 @item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1655 @acindex{PACKAGE_STRING}
1656 @ovindex PACKAGE_STRING
1657 @cvindex PACKAGE_STRING
1658 Exactly @samp{@var{package} @var{version}}.
1660 @item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1661 @acindex{PACKAGE_BUGREPORT}
1662 @ovindex PACKAGE_BUGREPORT
1663 @cvindex PACKAGE_BUGREPORT
1664 Exactly @var{bug-report}.
1670 @section Notices in @command{configure}
1671 @cindex Notices in @command{configure}
1673 The following macros manage version numbers for @command{configure}
1674 scripts. Using them is optional.
1676 @c FIXME: AC_PREREQ should not be here
1677 @defmac AC_PREREQ (@var{version})
1680 Ensure that a recent enough version of Autoconf is being used. If the
1681 version of Autoconf being used to create @command{configure} is
1682 earlier than @var{version}, print an error message to the standard
1683 error output and exit with failure (exit status is 63). For example:
1686 AC_PREREQ([@value{VERSION}])
1689 This macro is the only macro that may be used before @code{AC_INIT}, but
1690 for consistency, you are invited not to do so.
1693 @defmac AC_COPYRIGHT (@var{copyright-notice})
1695 @cindex Copyright Notice
1696 State that, in addition to the Free Software Foundation's copyright on
1697 the Autoconf macros, parts of your @command{configure} are covered by the
1698 @var{copyright-notice}.
1700 The @var{copyright-notice} will show up in both the head of
1701 @command{configure} and in @samp{configure --version}.
1705 @defmac AC_REVISION (@var{revision-info})
1708 Copy revision stamp @var{revision-info} into the @command{configure}
1709 script, with any dollar signs or double-quotes removed. This macro lets
1710 you put a revision stamp from @file{configure.ac} into @command{configure}
1711 without @acronym{RCS} or @acronym{CVS} changing it when you check in
1712 @command{configure}. That way, you can determine easily which revision of
1713 @file{configure.ac} a particular @command{configure} corresponds to.
1715 For example, this line in @file{configure.ac}:
1717 @c The asis prevents RCS from changing the example in the manual.
1719 AC_REVISION([$@asis{Revision: 1.30 }$])
1723 produces this in @command{configure}:
1727 # From configure.ac Revision: 1.30
1733 @section Finding @command{configure} Input
1736 @defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1737 @acindex{CONFIG_SRCDIR}
1738 @var{unique-file-in-source-dir} is some file that is in the package's
1739 source directory; @command{configure} checks for this file's existence to
1740 make sure that the directory that it is told contains the source code in
1741 fact does. Occasionally people accidentally specify the wrong directory
1742 with @option{--srcdir}; this is a safety check. @xref{configure
1743 Invocation}, for more information.
1747 @c FIXME: Remove definitively once --install explained.
1749 @c Small packages may store all their macros in @code{aclocal.m4}. As the
1750 @c set of macros grows, or for maintenance reasons, a maintainer may prefer
1751 @c to split the macros in several files. In this case, Autoconf must be
1752 @c told which files to load, and in which order.
1754 @c @defmac AC_INCLUDE (@var{file}@dots{})
1755 @c @acindex{INCLUDE}
1756 @c @c FIXME: There is no longer shell globbing.
1757 @c Read the macro definitions that appear in the listed files. A list of
1758 @c space-separated file names or shell globbing patterns is expected. The
1759 @c files will be read in the order they're listed.
1761 @c Because the order of definition of macros is important (only the last
1762 @c definition of a macro is used), beware that it is @code{AC_INIT} that
1763 @c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1764 @c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1765 @c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1766 @c the latter case, non-macro lines from included files may end up in the
1767 @c @file{configure} script, whereas in the former case, they'd be discarded
1768 @c just like any text that appear before @code{AC_INIT}.
1771 Packages that do manual configuration or use the @code{install} program
1772 might need to tell @command{configure} where to find some other shell
1773 scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1774 it looks are correct for most cases.
1776 @defmac AC_CONFIG_AUX_DIR (@var{dir})
1777 @acindex{CONFIG_AUX_DIR}
1778 Use the auxiliary build tools (e.g., @file{install-sh},
1779 @file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1780 Automake and Libtool scripts, etc.)@: that are in directory @var{dir}.
1781 These are auxiliary files used in configuration. @var{dir} can be
1782 either absolute or relative to @file{@var{srcdir}}. The default is
1783 @file{@var{srcdir}} or @file{@var{srcdir}/..} or
1784 @file{@var{srcdir}/../..}, whichever is the first that contains
1785 @file{install-sh}. The other files are not checked for, so that using
1786 @code{AC_PROG_INSTALL} does not automatically require distributing the
1787 other auxiliary files. It checks for @file{install.sh} also, but that
1788 name is obsolete because some @code{make} have a rule that creates
1789 @file{install} from it if there is no @file{Makefile}.
1791 The auxiliary directory is commonly named @file{build-aux}.
1792 If you need portability to @acronym{DOS} variants, do not name the
1793 auxiliary directory @file{aux}. @xref{File System Conventions}.
1796 @defmac AC_REQUIRE_AUX_FILE (@var{file})
1797 @acindex{REQUIRE_AUX_FILE}
1798 Declares that @var{file} is expected in the directory defined above. In
1799 Autoconf proper, this macro does nothing: its sole purpose is to be
1800 traced by third-party tools to produce a list of expected auxiliary
1801 files. For instance it is called by macros like @code{AC_PROG_INSTALL}
1802 (@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD}
1803 (@pxref{Canonicalizing}) to register the auxiliary files they need.
1806 Similarly, packages that use @command{aclocal} should declare where
1807 local macros can be found using @code{AC_CONFIG_MACRO_DIR}.
1809 @defmac AC_CONFIG_MACRO_DIR (@var{dir})
1810 @acindex{CONFIG_MACRO_DIR}
1811 Future versions of @command{autopoint}, @command{libtoolize},
1812 @command{aclocal} and @command{autoreconf} will use directory
1813 @var{dir} as the location of additional local Autoconf macros. Be
1814 sure to call this macro directly from @file{configure.ac} so that
1815 tools that install macros for @command{aclocal} can find the
1816 declaration before @option{--trace} can be called safely.
1821 @section Outputting Files
1822 @cindex Outputting files
1824 Every Autoconf script, e.g., @file{configure.ac}, should finish by
1825 calling @code{AC_OUTPUT}. That is the macro that generates and runs
1826 @file{config.status}, which will create the @file{Makefile}s and any
1827 other files resulting from configuration. This is the only required
1828 macro besides @code{AC_INIT} (@pxref{Input}).
1832 @cindex Instantiation
1833 Generate @file{config.status} and launch it. Call this macro once, at
1834 the end of @file{configure.ac}.
1836 @file{config.status} will perform all the configuration actions: all the
1837 output files (see @ref{Configuration Files}, macro
1838 @code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1839 macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1840 Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1841 @ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1842 to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1845 The location of your @code{AC_OUTPUT} invocation is the exact point
1846 where configuration actions are taken: any code afterwards will be
1847 executed by @code{configure} once @command{config.status} was run. If
1848 you want to bind actions to @command{config.status} itself
1849 (independently of whether @command{configure} is being run), see
1850 @ref{Configuration Commands, , Running Arbitrary Configuration
1854 Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1855 @xref{Obsolete Macros}, for a description of the arguments that
1856 @code{AC_OUTPUT} used to support.
1859 If you run @command{make} in subdirectories, you should run it using the
1860 @code{make} variable @code{MAKE}. Most versions of @command{make} set
1861 @code{MAKE} to the name of the @command{make} program plus any options it
1862 was given. (But many do not include in it the values of any variables
1863 set on the command line, so those are not passed on automatically.)
1864 Some old versions of @command{make} do not set this variable. The
1865 following macro allows you to use it even with those versions.
1867 @defmac AC_PROG_MAKE_SET
1868 @acindex{PROG_MAKE_SET}
1870 If the Make command, @code{$MAKE} if set or else @samp{make}, predefines
1871 @code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty.
1872 Otherwise, define @code{SET_MAKE} to a macro definition that sets
1873 @code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for
1877 If you use this macro, place a line like this in each @file{Makefile.in}
1878 that runs @code{MAKE} on other directories:
1886 @node Configuration Actions
1887 @section Performing Configuration Actions
1888 @cindex Configuration actions
1890 @file{configure} is designed so that it appears to do everything itself,
1891 but there is actually a hidden slave: @file{config.status}.
1892 @file{configure} is in charge of examining your system, but it is
1893 @file{config.status} that actually takes the proper actions based on the
1894 results of @file{configure}. The most typical task of
1895 @file{config.status} is to @emph{instantiate} files.
1897 This section describes the common behavior of the four standard
1898 instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1899 @code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1900 have this prototype:
1902 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1905 AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1909 where the arguments are:
1912 @item @var{tag}@dots{}
1913 A blank-or-newline-separated list of tags, which are typically the names of
1914 the files to instantiate.
1916 You are encouraged to use literals as @var{tags}. In particular, you
1920 @dots{} && my_foos="$my_foos fooo"
1921 @dots{} && my_foos="$my_foos foooo"
1922 AC_CONFIG_FOOS([$my_foos])
1926 and use this instead:
1929 @dots{} && AC_CONFIG_FOOS([fooo])
1930 @dots{} && AC_CONFIG_FOOS([foooo])
1933 The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
1934 special @var{tag}s: they may have the form @samp{@var{output}} or
1935 @samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
1936 from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
1938 @samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]},
1939 for example, asks for
1940 the creation of @file{Makefile} that will be the expansion of the
1941 output variables in the concatenation of @file{boiler/top.mk} and
1942 @file{boiler/bot.mk}.
1944 The special value @samp{-} might be used to denote the standard output
1945 when used in @var{output}, or the standard input when used in the
1946 @var{inputs}. You most probably don't need to use this in
1947 @file{configure.ac}, but it is convenient when using the command line
1948 interface of @file{./config.status}, see @ref{config.status Invocation},
1951 The @var{inputs} may be absolute or relative file names. In the latter
1952 case they are first looked for in the build tree, and then in the source
1956 Shell commands output literally into @file{config.status}, and
1957 associated with a tag that the user can use to tell @file{config.status}
1958 which the commands to run. The commands are run each time a @var{tag}
1959 request is given to @file{config.status}, typically each time the file
1960 @file{@var{tag}} is created.
1962 The variables set during the execution of @command{configure} are
1963 @emph{not} available here: you first need to set them via the
1964 @var{init-cmds}. Nonetheless the following variables are precomputed:
1968 The name of the top source directory, assuming that the working
1969 directory is the top build directory. This
1970 is what @command{configure}'s option @option{--srcdir} sets.
1973 The name of the top source directory, assuming that the working
1974 directory is the current build directory.
1977 @item ac_top_build_prefix
1978 The name of the top build directory, assuming that the working
1979 directory is the current build directory.
1980 It can be empty, or else ends with a slash, so that you may concatenate
1984 The name of the corresponding source directory, assuming that the
1985 working directory is the current build directory.
1989 The @dfn{current} directory refers to the directory (or
1990 pseudo-directory) containing the input part of @var{tags}. For
1994 AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
1998 with @option{--srcdir=../package} produces the following values:
2001 # Argument of --srcdir
2003 # Reversing deep/dir
2004 ac_top_build_prefix='../../'
2005 # Concatenation of $ac_top_build_prefix and srcdir
2006 ac_top_srcdir='../../../package'
2007 # Concatenation of $ac_top_srcdir and deep/dir
2008 ac_srcdir='../../../package/deep/dir'
2012 independently of @samp{in/in.in}.
2015 Shell commands output @emph{unquoted} near the beginning of
2016 @file{config.status}, and executed each time @file{config.status} runs
2017 (regardless of the tag). Because they are unquoted, for example,
2018 @samp{$var} will be output as the value of @code{var}. @var{init-cmds}
2019 is typically used by @file{configure} to give @file{config.status} some
2020 variables it needs to run the @var{commands}.
2022 You should be extremely cautious in your variable names: all the
2023 @var{init-cmds} share the same name space and may overwrite each other
2024 in unpredictable ways. Sorry@enddots{}
2027 All these macros can be called multiple times, with different
2028 @var{tag}s, of course!
2031 @node Configuration Files
2032 @section Creating Configuration Files
2033 @cindex Creating configuration files
2034 @cindex Configuration file creation
2036 Be sure to read the previous section, @ref{Configuration Actions}.
2038 @defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2039 @acindex{CONFIG_FILES}
2040 Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
2041 file (by default @file{@var{file}.in}), substituting the output variable
2043 @c Before we used to have this feature, which was later rejected
2044 @c because it complicates the write of Makefiles:
2045 @c If the file would be unchanged, it is left untouched, to preserve
2047 This macro is one of the instantiating macros; see @ref{Configuration
2048 Actions}. @xref{Makefile Substitutions}, for more information on using
2049 output variables. @xref{Setting Output Variables}, for more information
2050 on creating them. This macro creates the directory that the file is in
2051 if it doesn't exist. Usually, @file{Makefile}s are created this way,
2052 but other files, such as @file{.gdbinit}, can be specified as well.
2054 Typical calls to @code{AC_CONFIG_FILES} look like this:
2057 AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
2058 AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
2061 You can override an input file name by appending to @var{file} a
2062 colon-separated list of input files. Examples:
2065 AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
2066 [lib/Makefile:boiler/lib.mk])
2070 Doing this allows you to keep your file names acceptable to
2071 @acronym{DOS} variants, or
2072 to prepend and/or append boilerplate to the file.
2077 @node Makefile Substitutions
2078 @section Substitutions in Makefiles
2079 @cindex Substitutions in makefiles
2080 @cindex Makefile substitutions
2082 Each subdirectory in a distribution that contains something to be
2083 compiled or installed should come with a file @file{Makefile.in}, from
2084 which @command{configure} will create a @file{Makefile} in that directory.
2085 To create a @file{Makefile}, @command{configure} performs a simple variable
2086 substitution, replacing occurrences of @samp{@@@var{variable}@@} in
2087 @file{Makefile.in} with the value that @command{configure} has determined
2088 for that variable. Variables that are substituted into output files in
2089 this way are called @dfn{output variables}. They are ordinary shell
2090 variables that are set in @command{configure}. To make @command{configure}
2091 substitute a particular variable into the output files, the macro
2092 @code{AC_SUBST} must be called with that variable name as an argument.
2093 Any occurrences of @samp{@@@var{variable}@@} for other variables are
2094 left unchanged. @xref{Setting Output Variables}, for more information
2095 on creating output variables with @code{AC_SUBST}.
2097 A software package that uses a @command{configure} script should be
2098 distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
2099 way, the user has to properly configure the package for the local system
2100 before compiling it.
2102 @xref{Makefile Conventions,, Makefile Conventions, standards, The
2103 @acronym{GNU} Coding Standards}, for more information on what to put in
2107 * Preset Output Variables:: Output variables that are always set
2108 * Installation Directory Variables:: Other preset output variables
2109 * Build Directories:: Supporting multiple concurrent compiles
2110 * Automatic Remaking:: Makefile rules for configuring
2113 @node Preset Output Variables
2114 @subsection Preset Output Variables
2115 @cindex Output variables
2117 Some output variables are preset by the Autoconf macros. Some of the
2118 Autoconf macros set additional output variables, which are mentioned in
2119 the descriptions for those macros. @xref{Output Variable Index}, for a
2120 complete list of output variables. @xref{Installation Directory
2121 Variables}, for the list of the preset ones related to installation
2122 directories. Below are listed the other preset ones. They all are
2123 precious variables (@pxref{Setting Output Variables},
2126 @c Just say no to ASCII sorting! We're humans, not computers.
2127 @c These variables are listed as they would be in a dictionary:
2134 Debugging and optimization options for the C compiler. If it is not set
2135 in the environment when @command{configure} runs, the default value is set
2136 when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
2137 uses this variable when compiling programs to test for C features.
2140 @defvar configure_input
2141 @ovindex configure_input
2142 A comment saying that the file was generated automatically by
2143 @command{configure} and giving the name of the input file.
2144 @code{AC_OUTPUT} adds a comment line containing this variable to the top
2145 of every @file{Makefile} it creates. For other files, you should
2146 reference this variable in a comment at the top of each input file. For
2147 example, an input shell script should begin like this:
2151 # @@configure_input@@
2155 The presence of that line also reminds people editing the file that it
2156 needs to be processed by @command{configure} in order to be used.
2161 Header file search directory (@option{-I@var{dir}}) and any other
2162 miscellaneous options for the C and C++ preprocessors and compilers. If
2163 it is not set in the environment when @command{configure} runs, the default
2164 value is empty. @command{configure} uses this variable when compiling or
2165 preprocessing programs to test for C and C++ features.
2170 Debugging and optimization options for the C++ compiler. If it is not
2171 set in the environment when @command{configure} runs, the default value is
2172 set when you call @code{AC_PROG_CXX} (or empty if you don't).
2173 @command{configure} uses this variable when compiling programs to test for
2179 @option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2180 is called, @command{configure} replaces @samp{@@DEFS@@} with
2181 @option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2182 variable is not defined while @command{configure} is performing its tests,
2183 only when creating the output files. @xref{Setting Output Variables}, for
2184 how to check the results of previous tests.
2193 How does one suppress the trailing newline from @command{echo} for
2194 question-answer message pairs? These variables provide a way:
2197 echo $ECHO_N "And the winner is... $ECHO_C"
2199 echo "$@{ECHO_T@}dead."
2203 Some old and uncommon @command{echo} implementations offer no means to
2204 achieve this, in which case @code{ECHO_T} is set to tab. You might not
2210 Debugging and optimization options for the Fortran compiler. If it
2211 is not set in the environment when @command{configure} runs, the default
2212 value is set when you call @code{AC_PROG_FC} (or empty if you don't).
2213 @command{configure} uses this variable when compiling programs to test for
2219 Debugging and optimization options for the Fortran 77 compiler. If it
2220 is not set in the environment when @command{configure} runs, the default
2221 value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2222 @command{configure} uses this variable when compiling programs to test for
2223 Fortran 77 features.
2228 Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
2229 options for the linker. Don't use this variable to pass library names
2230 (@option{-l}) to the linker, use @code{LIBS} instead. If it is not set
2231 in the environment when @command{configure} runs, the default value is empty.
2232 @command{configure} uses this variable when linking programs to test for
2233 C, C++, and Fortran features.
2238 @option{-l} options to pass to the linker. The default value is empty,
2239 but some Autoconf macros may prepend extra libraries to this variable if
2240 those libraries are found and provide necessary functions, see
2241 @ref{Libraries}. @command{configure} uses this variable when linking
2242 programs to test for C, C++, and Fortran features.
2247 Rigorously equal to @samp{.}. Added for symmetry only.
2250 @defvar abs_builddir
2251 @ovindex abs_builddir
2252 Absolute name of @code{builddir}.
2255 @defvar top_builddir
2256 @ovindex top_builddir
2257 The relative name of the top level of the current build tree. In the
2258 top-level directory, this is the same as @code{builddir}.
2261 @defvar abs_top_builddir
2262 @ovindex abs_top_builddir
2263 Absolute name of @code{top_builddir}.
2268 The relative name of the directory that contains the source code for
2269 that @file{Makefile}.
2274 Absolute name of @code{srcdir}.
2279 The relative name of the top-level source code directory for the
2280 package. In the top-level directory, this is the same as @code{srcdir}.
2283 @defvar abs_top_srcdir
2284 @ovindex abs_top_srcdir
2285 Absolute name of @code{top_srcdir}.
2288 @node Installation Directory Variables
2289 @subsection Installation Directory Variables
2290 @cindex Installation directories
2291 @cindex Directories, installation
2293 The following variables specify the directories where the package will
2294 be installed, see @ref{Directory Variables,, Variables for
2295 Installation Directories, standards, The @acronym{GNU} Coding
2296 Standards}, for more information. See the end of this section for
2297 details on when and how to use these variables.
2301 The directory for installing executables that users run.
2306 The directory for installing ideosyncratic read-only
2307 architecture-independent data.
2311 @ovindex datarootdir
2312 The root of the directory tree for read-only architecture-independent
2318 The directory for installing documentation files (other than Info and
2324 The directory for installing documentation files in DVI format.
2328 @ovindex exec_prefix
2329 The installation prefix for architecture-dependent files. By default
2330 it's the same as @var{prefix}. You should avoid installing anything
2331 directly to @var{exec_prefix}. However, the default value for
2332 directories containing architecture-dependent files should be relative
2333 to @var{exec_prefix}.
2338 The directory for installing HTML documentation.
2343 The directory for installing C header files.
2348 The directory for installing documentation in Info format.
2353 The directory for installing object code libraries.
2358 The directory for installing executables that other programs run.
2363 The directory for installing locale-dependent but
2364 architecture-independent data, such as message catalogs. This directory
2365 usually has a subdirectory per locale.
2368 @defvar localstatedir
2369 @ovindex localstatedir
2370 The directory for installing modifiable single-machine data.
2375 The top-level directory for installing documentation in man format.
2378 @defvar oldincludedir
2379 @ovindex oldincludedir
2380 The directory for installing C header files for non-GCC compilers.
2385 The directory for installing PDF documentation.
2390 The common installation prefix for all files. If @var{exec_prefix}
2391 is defined to a different value, @var{prefix} is used only for
2392 architecture-independent files.
2397 The directory for installing PostScript documentation.
2402 The directory for installing executables that system
2406 @defvar sharedstatedir
2407 @ovindex sharedstatedir
2408 The directory for installing modifiable architecture-independent data.
2413 The directory for installing read-only single-machine data.
2417 Most of these variables have values that rely on @code{prefix} or
2418 @code{exec_prefix}. It is deliberate that the directory output
2419 variables keep them unexpanded: typically @samp{@@datarootdir@@} will be
2420 replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and
2421 @samp{@@datadir@@} will be replaced by @samp{$@{datarootdir@}}.
2423 This behavior is mandated by the @acronym{GNU} coding standards, so that when
2428 she can still specify a different prefix from the one specified to
2429 @command{configure}, in which case, if needed, the package shall hard
2430 code dependencies corresponding to the make-specified prefix.
2433 she can specify a different installation location, in which case the
2434 package @emph{must} still depend on the location which was compiled in
2435 (i.e., never recompile when @samp{make install} is run). This is an
2436 extremely important feature, as many people may decide to install all
2437 the files of a package grouped together, and then install links from
2438 the final locations to there.
2441 In order to support these features, it is essential that
2442 @code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to
2443 depend upon the current value of @code{prefix}.
2445 A corollary is that you should not use these variables except in
2446 Makefiles. For instance, instead of trying to evaluate @code{datadir}
2447 in @file{configure} and hard-coding it in Makefiles using
2448 e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])},
2450 @samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
2452 Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace
2453 @code{datadir} and friends in your shell scripts and other files, rather
2454 let @command{make} manage their replacement. For instance Autoconf
2455 ships templates of its shell scripts ending with @samp{.in}, and uses a
2456 Makefile snippet similar to:
2461 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \
2462 -e 's|@@prefix[@@]|$(prefix)|g'
2466 autoconf: Makefile $(srcdir)/autoconf.in
2467 rm -f autoconf autoconf.tmp
2468 $(edit) $(srcdir)/autoconf.in >autoconf.tmp
2469 chmod +x autoconf.tmp
2470 mv autoconf.tmp autoconf
2474 autoheader: Makefile $(srcdir)/autoheader.in
2475 rm -f autoheader autoheader.tmp
2476 $(edit) $(srcdir)/autoconf.in >autoheader.tmp
2477 chmod +x autoheader.tmp
2478 mv autoheader.tmp autoheader
2482 Some details are noteworthy:
2486 The brackets prevent @command{configure} from replacing
2487 @samp{@@datadir@@} in the sed expression itself.
2488 Brackets are preferable to a backslash here, since
2489 Posix says @samp{\@@} is not portable.
2492 Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2496 Don't use @samp{/} in the sed expression(s) since most likely the
2497 variables you use, such as @samp{$(pkgdatadir)}, will contain
2500 @item Dependency on @file{Makefile}
2501 Since @code{edit} uses values that depend on the configuration specific
2502 values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth,
2503 the output depends on @file{Makefile}, not @file{configure.ac}.
2505 @item Separated dependencies and Single Suffix Rules
2506 You can't use them! The above snippet cannot be (portably) rewritten
2510 autoconf autoheader: Makefile
2520 @xref{Limitations of Make}, for details.
2522 @item @samp{$(srcdir)}
2523 Be sure to specify the name of the source directory,
2524 otherwise the package won't support separated builds.
2528 @node Build Directories
2529 @subsection Build Directories
2530 @cindex Build directories
2531 @cindex Directories, build
2533 You can support compiling a software package for several architectures
2534 simultaneously from the same copy of the source code. The object files
2535 for each architecture are kept in their own directory.
2537 To support doing this, @command{make} uses the @code{VPATH} variable to
2538 find the files that are in the source directory. @acronym{GNU} Make
2539 and most other recent @command{make} programs can do this. Older
2540 @command{make} programs do not support @code{VPATH}; when using them, the
2541 source code must be in the same directory as the object files.
2543 To support @code{VPATH}, each @file{Makefile.in} should contain two
2544 lines that look like:
2551 Do not set @code{VPATH} to the value of another variable, for example
2552 @samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do
2553 variable substitutions on the value of @code{VPATH}.
2555 @command{configure} substitutes the correct value for @code{srcdir} when
2556 it produces @file{Makefile}.
2558 Do not use the @code{make} variable @code{$<}, which expands to the
2559 file name of the file in the source directory (found with @code{VPATH}),
2560 except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2561 which tells how to create a @file{.o} file from a @file{.c} file.) Some
2562 versions of @command{make} do not set @code{$<} in explicit rules; they
2563 expand it to an empty value.
2565 Instead, @file{Makefile} command lines should always refer to source
2566 files by prefixing them with @samp{$(srcdir)/}. For example:
2569 time.info: time.texinfo
2570 $(MAKEINFO) $(srcdir)/time.texinfo
2573 @node Automatic Remaking
2574 @subsection Automatic Remaking
2575 @cindex Automatic remaking
2576 @cindex Remaking automatically
2578 You can put rules like the following in the top-level @file{Makefile.in}
2579 for a package to automatically update the configuration information when
2580 you change the configuration files. This example includes all of the
2581 optional files, such as @file{aclocal.m4} and those related to
2582 configuration header files. Omit from the @file{Makefile.in} rules for
2583 any of these files that your package does not use.
2585 The @samp{$(srcdir)/} prefix is included because of limitations in the
2586 @code{VPATH} mechanism.
2588 The @file{stamp-} files are necessary because the timestamps of
2589 @file{config.h.in} and @file{config.h} will not be changed if remaking
2590 them does not change their contents. This feature avoids unnecessary
2591 recompilation. You should include the file @file{stamp-h.in} your
2592 package's distribution, so @command{make} will consider
2593 @file{config.h.in} up to date. Don't use @command{touch}
2594 (@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
2595 @command{date} would cause needless differences, hence @acronym{CVS}
2600 $(srcdir)/configure: configure.ac aclocal.m4
2601 cd $(srcdir) && autoconf
2603 # autoheader might not change config.h.in, so touch a stamp file.
2604 $(srcdir)/config.h.in: stamp-h.in
2605 $(srcdir)/stamp-h.in: configure.ac aclocal.m4
2606 cd $(srcdir) && autoheader
2607 echo timestamp > $(srcdir)/stamp-h.in
2610 stamp-h: config.h.in config.status
2613 Makefile: Makefile.in config.status
2616 config.status: configure
2617 ./config.status --recheck
2622 (Be careful if you copy these lines directly into your Makefile, as you
2623 will need to convert the indented lines to start with the tab character.)
2625 In addition, you should use
2628 AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])
2632 so @file{config.status} will ensure that @file{config.h} is considered up to
2633 date. @xref{Output}, for more information about @code{AC_OUTPUT}.
2635 @xref{config.status Invocation}, for more examples of handling
2636 configuration-related dependencies.
2638 @node Configuration Headers
2639 @section Configuration Header Files
2640 @cindex Configuration Header
2641 @cindex @file{config.h}
2643 When a package contains more than a few tests that define C preprocessor
2644 symbols, the command lines to pass @option{-D} options to the compiler
2645 can get quite long. This causes two problems. One is that the
2646 @command{make} output is hard to visually scan for errors. More
2647 seriously, the command lines can exceed the length limits of some
2648 operating systems. As an alternative to passing @option{-D} options to
2649 the compiler, @command{configure} scripts can create a C header file
2650 containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS}
2651 macro selects this kind of output. Though it can be called anywhere
2652 between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
2653 it right after @code{AC_INIT}.
2655 The package should @samp{#include} the configuration header file before
2656 any other header files, to prevent inconsistencies in declarations (for
2657 example, if it redefines @code{const}).
2659 To provide for VPATH builds, remember to pass the C compiler a @option{-I.}
2660 option (or @option{-I..}; whichever directory contains @file{config.h}).
2661 Even if you use @samp{#include "config.h"}, the preprocessor searches only
2662 the directory of the currently read file, ie@. the source directory, not
2663 the build directory.
2665 With the appropriate @option{-I} option, you can use
2666 @samp{#include <config.h>}. Actually, it's a good habit to use it,
2667 because in the rare case when the source directory contains another
2668 @file{config.h}, the build directory should be searched first.
2671 @defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2672 @acindex{CONFIG_HEADERS}
2673 @cvindex HAVE_CONFIG_H
2674 This macro is one of the instantiating macros; see @ref{Configuration
2675 Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2676 blank-or-newline-separated list @var{header} containing C preprocessor
2677 @code{#define} statements, and replace @samp{@@DEFS@@} in generated
2678 files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2679 The usual name for @var{header} is @file{config.h}.
2681 If @var{header} already exists and its contents are identical to what
2682 @code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2683 making some changes in the configuration without needlessly causing
2684 object files that depend on the header file to be recompiled.
2686 Usually the input file is named @file{@var{header}.in}; however, you can
2687 override the input file name by appending to @var{header} a
2688 colon-separated list of input files. Examples:
2691 AC_CONFIG_HEADERS([config.h:config.hin])
2692 AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2696 Doing this allows you to keep your file names acceptable to
2697 @acronym{DOS} variants, or
2698 to prepend and/or append boilerplate to the file.
2703 This macro is defined as the name of the first declared config header
2704 and undefined if no config headers have been declared up to this point.
2705 A third-party macro may, for example, require use of a config header
2706 without invoking AC_CONFIG_HEADERS twice, like this:
2709 AC_CONFIG_COMMANDS_PRE(
2710 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
2715 @xref{Configuration Actions}, for more details on @var{header}.
2718 * Header Templates:: Input for the configuration headers
2719 * autoheader Invocation:: How to create configuration templates
2720 * Autoheader Macros:: How to specify CPP templates
2723 @node Header Templates
2724 @subsection Configuration Header Templates
2725 @cindex Configuration Header Template
2726 @cindex Header templates
2727 @cindex @file{config.h.in}
2729 Your distribution should contain a template file that looks as you want
2730 the final header file to look, including comments, with @code{#undef}
2731 statements which are used as hooks. For example, suppose your
2732 @file{configure.ac} makes these calls:
2735 AC_CONFIG_HEADERS([conf.h])
2736 AC_CHECK_HEADERS([unistd.h])
2740 Then you could have code like the following in @file{conf.h.in}. On
2741 systems that have @file{unistd.h}, @command{configure} will @samp{#define}
2742 @samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be
2743 commented out (in case the system predefines that symbol).
2747 /* Define as 1 if you have unistd.h. */
2748 #undef HAVE_UNISTD_H
2752 Pay attention that @samp{#undef} is in the first column, and there is
2753 nothing after @samp{HAVE_UNISTD_H}, not even white space. You can
2754 then decode the configuration header using the preprocessor directives:
2761 # include <unistd.h>
2763 /* We are in trouble. */
2768 The use of old form templates, with @samp{#define} instead of
2769 @samp{#undef} is strongly discouraged. Similarly with old templates
2770 with comments on the same line as the @samp{#undef}. Anyway, putting
2771 comments in preprocessor macros has never been a good idea.
2773 Since it is a tedious task to keep a template header up to date, you may
2774 use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
2777 @node autoheader Invocation
2778 @subsection Using @command{autoheader} to Create @file{config.h.in}
2779 @cindex @command{autoheader}
2781 The @command{autoheader} program can create a template file of C
2782 @samp{#define} statements for @command{configure} to use. If
2783 @file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
2784 @command{autoheader} creates @file{@var{file}.in}; if multiple file
2785 arguments are given, the first one is used. Otherwise,
2786 @command{autoheader} creates @file{config.h.in}.
2788 In order to do its job, @command{autoheader} needs you to document all
2789 of the symbols that you might use; i.e., there must be at least one
2790 @code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} call with a third
2791 argument for each symbol (@pxref{Defining Symbols}). An additional
2792 constraint is that the first argument of @code{AC_DEFINE} must be a
2793 literal. Note that all symbols defined by Autoconf's builtin tests are
2794 already documented properly; you only need to document those that you
2797 You might wonder why @command{autoheader} is needed: after all, why
2798 would @command{configure} need to ``patch'' a @file{config.h.in} to
2799 produce a @file{config.h} instead of just creating @file{config.h} from
2800 scratch? Well, when everything rocks, the answer is just that we are
2801 wasting our time maintaining @command{autoheader}: generating
2802 @file{config.h} directly is all that is needed. When things go wrong,
2803 however, you'll be thankful for the existence of @command{autoheader}.
2805 The fact that the symbols are documented is important in order to
2806 @emph{check} that @file{config.h} makes sense. The fact that there is a
2807 well-defined list of symbols that should be @code{#define}'d (or not) is
2808 also important for people who are porting packages to environments where
2809 @command{configure} cannot be run: they just have to @emph{fill in the
2812 But let's come back to the point: @command{autoheader}'s invocation@dots{}
2814 If you give @command{autoheader} an argument, it uses that file instead
2815 of @file{configure.ac} and writes the header file to the standard output
2816 instead of to @file{config.h.in}. If you give @command{autoheader} an
2817 argument of @option{-}, it reads the standard input instead of
2818 @file{configure.ac} and writes the header file to the standard output.
2820 @command{autoheader} accepts the following options:
2825 Print a summary of the command line options and exit.
2829 Print the version number of Autoconf and exit.
2833 Report processing steps.
2837 Don't remove the temporary files.
2841 Remake the template file even if newer than its input files.
2843 @item --include=@var{dir}
2845 Append @var{dir} to the include path. Multiple invocations accumulate.
2847 @item --prepend-include=@var{dir}
2849 Prepend @var{dir} to the include path. Multiple invocations accumulate.
2851 @item --warnings=@var{category}
2852 @itemx -W @var{category}
2854 Report the warnings related to @var{category} (which can actually be a
2855 comma separated list). Current categories include:
2859 report the uses of obsolete constructs
2862 report all the warnings
2868 treats warnings as errors
2870 @item no-@var{category}
2871 disable warnings falling into @var{category}
2878 @node Autoheader Macros
2879 @subsection Autoheader Macros
2880 @cindex Autoheader macros
2882 @command{autoheader} scans @file{configure.ac} and figures out which C
2883 preprocessor symbols it might define. It knows how to generate
2884 templates for symbols defined by @code{AC_CHECK_HEADERS},
2885 @code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
2886 symbol, you must define a template for it. If there are missing
2887 templates, @command{autoheader} fails with an error message.
2889 The simplest way to create a template for a @var{symbol} is to supply
2890 the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
2891 @ref{Defining Symbols}. You may also use one of the following macros.
2893 @defmac AH_VERBATIM (@var{key}, @var{template})
2895 Tell @command{autoheader} to include the @var{template} as-is in the header
2896 template file. This @var{template} is associated with the @var{key},
2897 which is used to sort all the different templates and guarantee their
2898 uniqueness. It should be a symbol that can be @code{AC_DEFINE}'d.
2903 AH_VERBATIM([_GNU_SOURCE],
2904 [/* Enable GNU extensions on systems that have them. */
2906 # define _GNU_SOURCE
2912 @defmac AH_TEMPLATE (@var{key}, @var{description})
2914 Tell @command{autoheader} to generate a template for @var{key}. This macro
2915 generates standard templates just like @code{AC_DEFINE} when a
2916 @var{description} is given.
2921 AH_TEMPLATE([CRAY_STACKSEG_END],
2922 [Define to one of _getb67, GETB67, getb67
2923 for Cray-2 and Cray-YMP systems. This
2924 function is required for alloca.c support
2929 will generate the following template, with the description properly
2933 /* Define to one of _getb67, GETB67, getb67 for Cray-2 and
2934 Cray-YMP systems. This function is required for alloca.c
2935 support on those systems. */
2936 #undef CRAY_STACKSEG_END
2941 @defmac AH_TOP (@var{text})
2943 Include @var{text} at the top of the header template file.
2947 @defmac AH_BOTTOM (@var{text})
2949 Include @var{text} at the bottom of the header template file.
2953 @node Configuration Commands
2954 @section Running Arbitrary Configuration Commands
2955 @cindex Configuration commands
2956 @cindex Commands for configuration
2958 You can execute arbitrary commands before, during, and after
2959 @file{config.status} is run. The three following macros accumulate the
2960 commands to run when they are called multiple times.
2961 @code{AC_CONFIG_COMMANDS} replaces the obsolete macro
2962 @code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details.
2964 @defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2965 @acindex{CONFIG_COMMANDS}
2966 Specify additional shell commands to run at the end of
2967 @file{config.status}, and shell commands to initialize any variables
2968 from @command{configure}. Associate the commands with @var{tag}.
2969 Since typically the @var{cmds} create a file, @var{tag} should
2970 naturally be the name of that file. If needed, the directory hosting
2971 @var{tag} is created. This macro is one of the instantiating macros;
2972 see @ref{Configuration Actions}.
2974 Here is an unrealistic example:
2977 AC_CONFIG_COMMANDS([fubar],
2978 [echo this is extra $fubar, and so on.],
2982 Here is a better one:
2984 AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
2988 The following two macros look similar, but in fact they are not of the same
2989 breed: they are executed directly by @file{configure}, so you cannot use
2990 @file{config.status} to re-run them.
2992 @c Yet it is good to leave them here. The user sees them together and
2993 @c decides which best fits their needs.
2995 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
2996 @acindex{CONFIG_COMMANDS_PRE}
2997 Execute the @var{cmds} right before creating @file{config.status}.
2999 This macro presents the last opportunity to call @code{AC_SUBST},
3000 @code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros.
3003 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
3004 @acindex{CONFIG_COMMANDS_POST}
3005 Execute the @var{cmds} right after creating @file{config.status}.
3011 @node Configuration Links
3012 @section Creating Configuration Links
3013 @cindex Configuration links
3014 @cindex Links for configuration
3016 You may find it convenient to create links whose destinations depend upon
3017 results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
3018 creation of relative symbolic links can be delicate when the package is
3019 built in a directory different from the source directory.
3021 @defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
3022 @acindex{CONFIG_LINKS}
3024 Make @code{AC_OUTPUT} link each of the existing files @var{source} to
3025 the corresponding link name @var{dest}. Makes a symbolic link if
3026 possible, otherwise a hard link if possible, otherwise a copy. The
3027 @var{dest} and @var{source} names should be relative to the top level
3028 source or build directory. This macro is one of the instantiating
3029 macros; see @ref{Configuration Actions}.
3031 For example, this call:
3034 AC_CONFIG_LINKS([host.h:config/$machine.h
3035 object.h:config/$obj_format.h])
3039 creates in the current directory @file{host.h} as a link to
3040 @file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
3041 link to @file{@var{srcdir}/config/$obj_format.h}.
3043 The tempting value @samp{.} for @var{dest} is invalid: it makes it
3044 impossible for @samp{config.status} to guess the links to establish.
3048 ./config.status host.h object.h
3051 to create the links.
3056 @node Subdirectories
3057 @section Configuring Other Packages in Subdirectories
3058 @cindex Configure subdirectories
3059 @cindex Subdirectory configure
3061 In most situations, calling @code{AC_OUTPUT} is sufficient to produce
3062 @file{Makefile}s in subdirectories. However, @command{configure} scripts
3063 that control more than one independent package can use
3064 @code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
3065 packages in subdirectories.
3067 @defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
3068 @acindex{CONFIG_SUBDIRS}
3070 Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
3071 @var{dir} in the given blank-or-newline-separated list. Each @var{dir} should
3072 be a literal, i.e., please do not use:
3075 if test "$package_foo_enabled" = yes; then
3076 $my_subdirs="$my_subdirs foo"
3078 AC_CONFIG_SUBDIRS([$my_subdirs])
3082 because this prevents @samp{./configure --help=recursive} from
3083 displaying the options of the package @code{foo}. Rather, you should
3087 if test "$package_foo_enabled" = yes; then
3088 AC_CONFIG_SUBDIRS([foo])
3092 If a given @var{dir} is not found, an error is reported: if the
3093 subdirectory is optional, write:
3096 if test -d $srcdir/foo; then
3097 AC_CONFIG_SUBDIRS([foo])
3101 @c NB: Yes, below we mean configure.in, not configure.ac.
3102 If a given @var{dir} contains @command{configure.gnu}, it is run instead
3103 of @command{configure}. This is for packages that might use a
3104 non-Autoconf script @command{Configure}, which can't be called through a
3105 wrapper @command{configure} since it would be the same file on
3106 case-insensitive file systems. Likewise, if a @var{dir} contains
3107 @file{configure.in} but no @command{configure}, the Cygnus
3108 @command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
3110 The subdirectory @command{configure} scripts are given the same command
3111 line options that were given to this @command{configure} script, with minor
3112 changes if needed, which include:
3116 adjusting a relative name for the cache file;
3119 adjusting a relative name for the source directory;
3122 propagating the current value of @code{$prefix}, including if it was
3123 defaulted, and if the default values of the top level and of the subdirectory
3124 @file{configure} differ.
3127 This macro also sets the output variable @code{subdirs} to the list of
3128 directories @samp{@var{dir} @dots{}}. @file{Makefile} rules can use
3129 this variable to determine which subdirectories to recurse into.
3131 This macro may be called multiple times.
3134 @node Default Prefix
3135 @section Default Prefix
3136 @cindex Install prefix
3137 @cindex Prefix for install
3139 By default, @command{configure} sets the prefix for files it installs to
3140 @file{/usr/local}. The user of @command{configure} can select a different
3141 prefix using the @option{--prefix} and @option{--exec-prefix} options.
3142 There are two ways to change the default: when creating
3143 @command{configure}, and when running it.
3145 Some software packages might want to install in a directory other than
3146 @file{/usr/local} by default. To accomplish that, use the
3147 @code{AC_PREFIX_DEFAULT} macro.
3149 @defmac AC_PREFIX_DEFAULT (@var{prefix})
3150 @acindex{PREFIX_DEFAULT}
3151 Set the default installation prefix to @var{prefix} instead of
3155 It may be convenient for users to have @command{configure} guess the
3156 installation prefix from the location of a related program that they
3157 have already installed. If you wish to do that, you can call
3158 @code{AC_PREFIX_PROGRAM}.
3160 @defmac AC_PREFIX_PROGRAM (@var{program})
3161 @acindex{PREFIX_PROGRAM}
3162 If the user did not specify an installation prefix (using the
3163 @option{--prefix} option), guess a value for it by looking for
3164 @var{program} in @env{PATH}, the way the shell does. If @var{program}
3165 is found, set the prefix to the parent of the directory containing
3166 @var{program}, else default the prefix as described above
3167 (@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if
3168 @var{program} is @code{gcc} and the @env{PATH} contains
3169 @file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}.
3174 @c ======================================================== Existing tests
3176 @node Existing Tests
3177 @chapter Existing Tests
3179 These macros test for particular system features that packages might
3180 need or want to use. If you need to test for a kind of feature that
3181 none of these macros check for, you can probably do it by calling
3182 primitive test macros with appropriate arguments (@pxref{Writing
3185 These tests print messages telling the user which feature they're
3186 checking for, and what they find. They cache their results for future
3187 @command{configure} runs (@pxref{Caching Results}).
3189 Some of these macros set output variables. @xref{Makefile
3190 Substitutions}, for how to get their values. The phrase ``define
3191 @var{name}'' is used below as a shorthand to mean ``define C
3192 preprocessor symbol @var{name} to the value 1''. @xref{Defining
3193 Symbols}, for how to get those symbol definitions into your program.
3196 * Common Behavior:: Macros' standard schemes
3197 * Alternative Programs:: Selecting between alternative programs
3198 * Files:: Checking for the existence of files
3199 * Libraries:: Library archives that might be missing
3200 * Library Functions:: C library functions that might be missing
3201 * Header Files:: Header files that might be missing
3202 * Declarations:: Declarations that may be missing
3203 * Structures:: Structures or members that might be missing
3204 * Types:: Types that might be missing
3205 * Compilers and Preprocessors:: Checking for compiling programs
3206 * System Services:: Operating system services
3207 * Posix Variants:: Special kludges for specific Posix variants
3210 @node Common Behavior
3211 @section Common Behavior
3212 @cindex Common autoconf behavior
3214 Much effort has been expended to make Autoconf easy to learn. The most
3215 obvious way to reach this goal is simply to enforce standard interfaces
3216 and behaviors, avoiding exceptions as much as possible. Because of
3217 history and inertia, unfortunately, there are still too many exceptions
3218 in Autoconf; nevertheless, this section describes some of the common
3222 * Standard Symbols:: Symbols defined by the macros
3223 * Default Includes:: Includes used by the generic macros
3226 @node Standard Symbols
3227 @subsection Standard Symbols
3228 @cindex Standard symbols
3230 All the generic macros that @code{AC_DEFINE} a symbol as a result of
3231 their test transform their @var{argument}s to a standard alphabet.
3232 First, @var{argument} is converted to upper case and any asterisks
3233 (@samp{*}) are each converted to @samp{P}. Any remaining characters
3234 that are not alphanumeric are converted to underscores.
3239 AC_CHECK_TYPES([struct $Expensive*])
3243 will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
3247 @node Default Includes
3248 @subsection Default Includes
3249 @cindex Default includes
3250 @cindex Includes, default
3252 Several tests depend upon a set of header files. Since these headers
3253 are not universally available, tests actually have to provide a set of
3254 protected includes, such as:
3258 #if TIME_WITH_SYS_TIME
3259 # include <sys/time.h>
3262 # if HAVE_SYS_TIME_H
3263 # include <sys/time.h>
3272 Unless you know exactly what you are doing, you should avoid using
3273 unconditional includes, and check the existence of the headers you
3274 include beforehand (@pxref{Header Files}).
3276 Most generic macros use the following macro to provide the default set
3279 @defmac AC_INCLUDES_DEFAULT (@ovar{include-directives})
3280 @acindex{INCLUDES_DEFAULT}
3281 Expand to @var{include-directives} if defined, otherwise to:
3286 #if HAVE_SYS_TYPES_H
3287 # include <sys/types.h>
3290 # include <sys/stat.h>
3293 # include <stdlib.h>
3294 # include <stddef.h>
3297 # include <stdlib.h>
3301 # if !STDC_HEADERS && HAVE_MEMORY_H
3302 # include <memory.h>
3304 # include <string.h>
3307 # include <strings.h>
3310 # include <inttypes.h>
3313 # include <stdint.h>
3316 # include <unistd.h>
3321 If the default includes are used, then check for the presence of these
3322 headers and their compatibility, i.e., you don't need to run
3323 @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h} etc.
3325 These headers are checked for in the same order as they are included.
3326 For instance, on some systems @file{string.h} and @file{strings.h} both
3327 exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but
3328 @code{HAVE_STRINGS_H} won't.
3331 @node Alternative Programs
3332 @section Alternative Programs
3333 @cindex Programs, checking
3335 These macros check for the presence or behavior of particular programs.
3336 They are used to choose between several alternative programs and to
3337 decide what to do once one has been chosen. If there is no macro
3338 specifically defined to check for a program you need, and you don't need
3339 to check for any special properties of it, then you can use one of the
3340 general program-check macros.
3343 * Particular Programs:: Special handling to find certain programs
3344 * Generic Programs:: How to find other programs
3347 @node Particular Programs
3348 @subsection Particular Program Checks
3350 These macros check for particular programs---whether they exist, and
3351 in some cases whether they support certain features.
3356 Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3357 order, and set output variable @code{AWK} to the first one that is found.
3358 It tries @code{gawk} first because that is reported to be the
3359 best implementation.
3362 @defmac AC_PROG_GREP
3365 On AIX the default @code{grep} silently truncates long lines on the
3366 input before matching. On Solaris, @code{/usr/bin/grep} does not
3367 understand the @option{-e} option. On NeXT, @code{grep} understands only a
3368 single @option{-e} option. This macro looks for @sc{gnu} Grep or
3369 else the best available @code{grep} or @code{ggrep} in the user's
3370 @env{PATH} which accepts the longest input lines possible, and which
3371 accepts and respects multiple @option{-e} options. Set the
3372 output variable @code{GREP} to whatever is chosen.
3375 @defmac AC_PROG_EGREP
3376 @acindex{PROG_EGREP}
3378 Check whether @code{$GREP -E} works, or else search the user's
3379 @env{PATH} for @code{egrep}, and @code{gegrep}, in that order, and set
3380 output variable @code{EGREP} to the one that accepts the longest input
3384 @defmac AC_PROG_FGREP
3385 @acindex{PROG_FGREP}
3387 Check whether @code{$GREP -F} works, or else search the user's
3388 @env{PATH} for @code{fgrep}, and @code{gfgrep}, in that order, and set
3389 output variable @code{FGREP} to the one that accepts the longest input
3393 @defmac AC_PROG_INSTALL
3394 @acindex{PROG_INSTALL}
3396 @ovindex INSTALL_PROGRAM
3397 @ovindex INSTALL_DATA
3398 @ovindex INSTALL_SCRIPT
3399 Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible
3400 @code{install} program, if one is found in the current @env{PATH}.
3401 Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3402 checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3403 default directories) to determine @var{dir} (@pxref{Output}). Also set
3404 the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3405 @samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3407 This macro screens out various instances of @code{install} known not to
3408 work. It prefers to find a C program rather than a shell script, for
3409 speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3410 but that name is obsolete because some @command{make} programs have a rule
3411 that creates @file{install} from it if there is no @file{Makefile}.
3413 Autoconf comes with a copy of @file{install-sh} that you can use. If
3414 you use @code{AC_PROG_INSTALL}, you must include either
3415 @file{install-sh} or @file{install.sh} in your distribution, or
3416 @command{configure} will produce an error message saying it can't find
3417 them---even if the system you're on has a good @code{install} program.
3418 This check is a safety measure to prevent you from accidentally leaving
3419 that file out, which would prevent your package from installing on
3420 systems that don't have a @acronym{BSD}-compatible @code{install} program.
3422 If you need to use your own installation program because it has features
3423 not found in standard @code{install} programs, there is no reason to use
3424 @code{AC_PROG_INSTALL}; just put the file name of your program into your
3425 @file{Makefile.in} files.
3432 @cvindex YYTEXT_POINTER
3433 @ovindex LEX_OUTPUT_ROOT
3434 If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3435 and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3436 place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3439 Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3440 of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3441 the base of the file name that the lexer generates; usually
3442 @file{lex.yy}, but sometimes something else. These results vary
3443 according to whether @code{lex} or @code{flex} is being used.
3445 You are encouraged to use Flex in your sources, since it is both more
3446 pleasant to use than plain Lex and the C source it produces is portable.
3447 In order to ensure portability, however, you must either provide a
3448 function @code{yywrap} or, if you don't use it (e.g., your scanner has
3449 no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3450 statement in the scanner's source. Once this done, the scanner is
3451 portable (unless @emph{you} felt free to use nonportable constructs) and
3452 does not depend on any library. In this case, and in this case only, it
3453 is suggested that you use this Autoconf snippet:
3457 if test "$LEX" != flex; then
3458 LEX="$SHELL $missing_dir/missing flex"
3459 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy])
3460 AC_SUBST([LEXLIB], [''])
3464 The shell script @command{missing} can be found in the Automake
3467 To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3468 (indirectly) this macro twice, which will cause an annoying but benign
3469 ``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3470 of Automake will fix this issue; meanwhile, just ignore this message.
3472 As part of running the test, this macro may delete any file in the
3473 configuration directory named @file{lex.yy.c} or @file{lexyy.c}.
3476 @defmac AC_PROG_LN_S
3479 If @samp{ln -s} works on the current file system (the operating system
3480 and file system support symbolic links), set the output variable
3481 @code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3482 @code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}.
3484 If you make a link in a directory other than the current directory, its
3485 meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3486 create links using @samp{$(LN_S)}, either find out which form is used
3487 and adjust the arguments, or always invoke @code{ln} in the directory
3488 where the link is to be created.
3490 In other words, it does not work to do:
3498 (cd /x && $(LN_S) foo bar)
3502 @defmac AC_PROG_RANLIB
3503 @acindex{PROG_RANLIB}
3505 Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3506 is found, and otherwise to @samp{:} (do nothing).
3512 Set output variable @code{SED} to a @code{sed} on @env{PATH} that
3513 truncates as few characters as possible. If @sc{gnu} Sed is found,
3517 @defmac AC_PROG_YACC
3520 If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3521 -y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3522 @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3525 @node Generic Programs
3526 @subsection Generic Program and File Checks
3528 These macros are used to find programs not covered by the ``particular''
3529 test macros. If you need to check the behavior of a program as well as
3530 find out whether it is present, you have to write your own test for it
3531 (@pxref{Writing Tests}). By default, these macros use the environment
3532 variable @env{PATH}. If you need to check for a program that might not
3533 be in the user's @env{PATH}, you can pass a modified path to use
3537 AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3538 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc])
3541 You are strongly encouraged to declare the @var{variable} passed to
3542 @code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables},
3543 @code{AC_ARG_VAR}, for more details.
3545 @defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3546 @acindex{CHECK_PROG}
3547 Check whether program @var{prog-to-check-for} exists in @env{PATH}. If
3548 it is found, set @var{variable} to @var{value-if-found}, otherwise to
3549 @var{value-if-not-found}, if given. Always pass over @var{reject} (an
3550 absolute file name) even if it is the first found in the search path; in
3551 that case, set @var{variable} using the absolute file name of the
3552 @var{prog-to-check-for} found that is not @var{reject}. If
3553 @var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3557 @defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3558 @acindex{CHECK_PROGS}
3559 Check for each program in the blank-separated list
3560 @var{progs-to-check-for} existing in the @env{PATH}. If one is found, set
3561 @var{variable} to the name of that program. Otherwise, continue
3562 checking the next program in the list. If none of the programs in the
3563 list are found, set @var{variable} to @var{value-if-not-found}; if
3564 @var{value-if-not-found} is not specified, the value of @var{variable}
3565 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3568 @defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3569 @acindex{CHECK_TARGET_TOOL}
3570 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3571 with a prefix of the target type as determined by
3572 @code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}).
3573 If the tool cannot be found with a prefix, and if the build and target
3574 types are equal, then it is also searched for without a prefix.
3576 As noted in @ref{Specifying Names, , Specifying the system type}, the
3577 target is rarely specified, because most of the time it is the same
3578 as the host: it is the type of system for which any compiler tools in
3579 the package will produce code. What this macro will look for is,
3580 for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the
3581 compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)}
3582 will use to produce objects, archives or executables}.
3585 @defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3586 @acindex{CHECK_TOOL}
3587 Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3588 with a prefix of the host type as determined by
3589 @code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3590 For example, if the user runs @samp{configure --host=i386-gnu}, then
3593 AC_CHECK_TOOL([RANLIB], [ranlib], [:])
3596 sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3597 @env{PATH}, or otherwise to @samp{ranlib} if that program exists in
3598 @env{PATH}, or to @samp{:} if neither program exists.
3600 In the future, when cross-compiling this macro will @emph{only}
3601 accept program names that are prefixed with the host type.
3602 For more information, see @ref{Specifying Names, , Specifying the
3606 @defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3607 @acindex{CHECK_TARGET_TOOLS}
3608 Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list
3609 @var{progs-to-check-for} are checked with a prefix of the target type as
3610 determined by @code{AC_CANONICAL_TARGET}, followed by a dash
3611 (@pxref{Canonicalizing}). If none of the tools can be found with a
3612 prefix, and if the build and target types are equal, then the first one
3613 without a prefix is used. If a tool is found, set @var{variable} to
3614 the name of that program. If none of the tools in the list are found,
3615 set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found}
3616 is not specified, the value of @var{variable} is not changed. Calls
3617 @code{AC_SUBST} for @var{variable}.
3620 @defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3621 @acindex{CHECK_TOOLS}
3622 Like @code{AC_CHECK_TOOL}, each of the tools in the list
3623 @var{progs-to-check-for} are checked with a prefix of the host type as
3624 determined by @code{AC_CANONICAL_HOST}, followed by a dash
3625 (@pxref{Canonicalizing}). If none of the tools can be found with a
3626 prefix, then the first one without a prefix is used. If a tool is found,
3627 set @var{variable} to the name of that program. If none of the tools in
3628 the list are found, set @var{variable} to @var{value-if-not-found}; if
3629 @var{value-if-not-found} is not specified, the value of @var{variable}
3630 is not changed. Calls @code{AC_SUBST} for @var{variable}.
3632 In the future, when cross-compiling this macro will @emph{not}
3633 accept program names that are not prefixed with the host type.
3636 @defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3638 Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
3639 name of @var{prog-to-check-for} if found.
3642 @defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3643 @acindex{PATH_PROGS}
3644 Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3645 are found, set @var{variable} to the absolute name of the program
3649 @defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3650 @acindex{PATH_TARGET_TOOL}
3651 Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute
3652 name of the program if it is found.
3655 @defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3657 Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute
3658 name of the program if it is found.
3660 In the future, when cross-compiling this macro will @emph{not}
3661 accept program names that are not prefixed with the host type.
3667 @cindex File, checking
3669 You might also need to check for the existence of files. Before using
3670 these macros, ask yourself whether a run-time test might not be a better
3671 solution. Be aware that, like most Autoconf macros, they test a feature
3672 of the host machine, and therefore, they die when cross-compiling.
3674 @defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3675 @acindex{CHECK_FILE}
3676 Check whether file @var{file} exists on the native system. If it is
3677 found, execute @var{action-if-found}, otherwise do
3678 @var{action-if-not-found}, if given.
3681 @defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3682 @acindex{CHECK_FILES}
3683 Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3684 Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3685 for each file found.
3690 @section Library Files
3691 @cindex Library, checking
3693 The following macros check for the presence of certain C, C++, or Fortran
3694 library archive files.
3696 @defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3698 Test whether the library @var{library} is available by trying to link
3699 a test program that calls function @var{function} with the library.
3700 @var{function} should be a function provided by the library.
3702 name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3703 the @var{library} argument.
3705 @var{action-if-found} is a list of shell commands to run if the link
3706 with the library succeeds; @var{action-if-not-found} is a list of shell
3707 commands to run if the link fails. If @var{action-if-found} is not
3708 specified, the default action will prepend @option{-l@var{library}} to
3709 @code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3710 capitals). This macro is intended to support building @code{LIBS} in
3711 a right-to-left (least-dependent to most-dependent) fashion such that
3712 library dependencies are satisfied as a natural side-effect of
3713 consecutive tests. Some linkers are very sensitive to library ordering
3714 so the order in which @code{LIBS} is generated is important to reliable
3715 detection of libraries.
3717 If linking with @var{library} results in unresolved symbols that would
3718 be resolved by linking with additional libraries, give those libraries
3719 as the @var{other-libraries} argument, separated by spaces:
3720 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3721 that @var{library} is present, because linking the test program will
3722 always fail with unresolved symbols. The @var{other-libraries} argument
3723 should be limited to cases where it is desirable to test for one library
3724 in the presence of another that is not already in @code{LIBS}.
3726 @code{AC_CHECK_LIB} requires some care in usage, and should be avoided
3727 in some common cases. Many standard functions like @code{gethostbyname}
3728 appear the standard C library on some hosts, and in special libraries
3729 like @code{nsl} on other hosts. On some hosts the special libraries
3730 contain variant implementations that you may not want to use. These
3731 days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname],
3732 [nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}.
3736 @defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3737 @acindex{SEARCH_LIBS}
3738 Search for a library defining @var{function} if it's not already
3739 available. This equates to calling
3740 @samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with
3741 no libraries, then for each library listed in @var{search-libs}.
3743 Add @option{-l@var{library}} to @code{LIBS} for the first library found
3744 to contain @var{function}, and run @var{action-if-found}. If the
3745 function is not found, run @var{action-if-not-found}.
3747 If linking with @var{library} results in unresolved symbols that would
3748 be resolved by linking with additional libraries, give those libraries
3749 as the @var{other-libraries} argument, separated by spaces:
3750 e.g., @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3751 that @var{function} is present, because linking the test program will
3752 always fail with unresolved symbols.
3757 @node Library Functions
3758 @section Library Functions
3760 The following macros check for particular C library functions.
3761 If there is no macro specifically defined to check for a function you need,
3762 and you don't need to check for any special properties of
3763 it, then you can use one of the general function-check macros.
3766 * Function Portability:: Pitfalls with usual functions
3767 * Particular Functions:: Special handling to find certain functions
3768 * Generic Functions:: How to find other functions
3771 @node Function Portability
3772 @subsection Portability of C Functions
3773 @cindex Portability of C functions
3774 @cindex C function portability
3776 Most usual functions can either be missing, or be buggy, or be limited
3777 on some architectures. This section tries to make an inventory of these
3778 portability issues. By definition, this list will always require
3779 additions. Please help us keeping it as complete as possible.
3784 @prindex @code{exit}
3785 Did you know that, on some older hosts, @code{exit} returns @code{int}?
3786 This is because @code{exit} predates @code{void}, and there was a long
3787 tradition of it returning @code{int}.
3791 @prindex @code{free}
3792 The ISO C99 standard says a call @code{free(NULL)} does nothing, but
3793 some old systems don't support this (e.g., NextStep).
3799 @prindex @code{isinf}
3800 @prindex @code{isnan}
3801 The ISO C99 standard specifies that @code{isinf} and @code{isnan} are
3802 macros. On some systems just macros are available (e.g., HP-UX), on
3803 some systems both macros and functions (e.g., glibc 2.3.2), and on some
3804 systems only functions (e.g., IRIX 6 and Solaris 9). In some cases
3805 these functions are declared in nonstandard headers like
3806 @code{<sunmath.h>} and defined in non-default libraries like
3807 @option{-lm} or @option{-lsunmath}.
3809 The C99 @code{isinf} and @code{isnan} macros work correctly with
3810 @code{long double} arguments, but pre-C99 systems that use functions
3811 typically assume @code{double} arguments. On such a system,
3812 @code{isinf} incorrectly returns true for a finite @code{long double}
3813 argument that is outside the range of @code{double}.
3815 To work around this porting mess, you can use code like the following.
3822 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \
3823 : sizeof (x) == sizeof (double) ? isnan_d (x) \
3825 static inline int isnan_f (float x) @{ return x != x; @}
3826 static inline int isnan_d (double x) @{ return x != x; @}
3827 static inline int isnan_ld (long double x) @{ return x != x; @}
3832 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \
3833 : sizeof (x) == sizeof (double) ? isinf_d (x) \
3835 static inline int isinf_f (float x) @{ return isnan (x - x); @}
3836 static inline int isinf_d (double x) @{ return isnan (x - x); @}
3837 static inline int isinf_ld (long double x) @{ return isnan (x - x); @}
3841 Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on
3842 compilers that lack the @code{inline} keyword. Some optimizing
3843 compilers mishandle these definitions, but systems with that bug
3844 typically have missing or broken @code{isnan} functions anyway, so it's
3845 probably not worth worrying about.
3849 @prindex @code{malloc}
3850 The ISO C99 standard says a call @code{malloc(0)} is implementation
3851 dependent, it may either return @code{NULL} (e.g., OSF 4) or
3852 non-@code{NULL} (e.g., @acronym{GNU} C Library). @code{AC_FUNC_MALLOC}
3853 can be used to insist on non-@code{NULL} (@pxref{Particular Functions}).
3857 @prindex @code{putenv}
3858 Posix prefers @code{setenv} to @code{putenv}; among other things,
3859 @code{putenv} is not required of all Posix implementations, but
3862 Posix specifies that @code{putenv} puts the given string directly in
3863 @code{environ}, but some systems make a copy of it instead (e.g.,
3864 glibc 2.0, or BSD). And when a copy is made, @code{unsetenv} might
3865 not free it, causing a memory leak (e.g., FreeBSD 4).
3867 On some systems @code{putenv("FOO")} removes @samp{FOO} from the
3868 environment, but this is not standard usage and it dumps core
3869 on some systems (e.g., AIX).
3871 On MINGW, a call @code{putenv("FOO=")} removes @samp{FOO} from the
3872 environment, rather than inserting it with an empty value.
3874 @item @code{realloc}
3876 @prindex @code{realloc}
3877 The ISO C99 standard says a call @code{realloc(NULL,size)} is equivalent
3878 to a @code{malloc(size)}, but some old systems don't support this (e.g.,
3881 @item @code{signal} handler
3883 @prindex @code{signal}
3884 Normally @code{signal} takes a handler function with a return type of
3885 @code{void}, but some old systems required @code{int} instead. Any
3886 actual @code{int} value returned is not used, this is only a
3887 difference in the function prototype demanded.
3889 All systems we know of in current use take @code{void}. Presumably
3890 @code{int} was to support K&R C, where of course @code{void} is not
3891 available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be
3892 used to establish the correct type in all cases.
3894 @item @code{snprintf}
3895 @c @fuindex snprintf
3896 @prindex @code{snprintf}
3897 @c @fuindex vsnprintf
3898 @prindex @code{vsnprintf}
3899 The ISO C99 standard says that if the output array isn't big enough
3900 and if no other errors occur, @code{snprintf} and @code{vsnprintf}
3901 truncate the output and return the number of bytes that ought to have
3902 been produced. Some older systems return the truncated length (e.g.,
3903 @acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value
3904 (e.g., earlier @acronym{GNU} C Library versions), and some the buffer
3905 length without truncation (e.g., 32-bit Solaris 7). Also, some buggy
3906 older systems ignore the length and overrun the buffer (e.g., 64-bit
3909 @item @code{sprintf}
3911 @prindex @code{sprintf}
3912 @c @fuindex vsprintf
3913 @prindex @code{vsprintf}
3914 The ISO C standard says @code{sprintf} and @code{vsprintf} return the
3915 number of bytes written, but on some ancient systems (SunOS 4 for
3916 instance) they return the buffer pointer instead.
3920 @prindex @code{sscanf}
3921 On various old systems, e.g., HP-UX 9, @code{sscanf} requires that its
3922 input string be writable (though it doesn't actually change it). This
3923 can be a problem when using @command{gcc} since it normally puts
3924 constant strings in read-only memory
3925 (@pxref{Incompatibilities,Incompatibilities of GCC,,gcc,Using and
3926 Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even
3927 having format strings read-only can be a problem.
3929 @item @code{strerror_r}
3930 @c @fuindex strerror_r
3931 @prindex @code{strerror_r}
3932 Posix specifies that @code{strerror_r} returns an @code{int}, but many
3933 systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a
3934 different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R}
3935 can detect which is in use (@pxref{Particular Functions}).
3937 @item @code{strnlen}
3939 @prindex @code{strnlen}
3940 @acronym{AIX} 4.3 provides a broken version which produces the
3944 strnlen ("foobar", 0) = 0
3945 strnlen ("foobar", 1) = 3
3946 strnlen ("foobar", 2) = 2
3947 strnlen ("foobar", 3) = 1
3948 strnlen ("foobar", 4) = 0
3949 strnlen ("foobar", 5) = 6
3950 strnlen ("foobar", 6) = 6
3951 strnlen ("foobar", 7) = 6
3952 strnlen ("foobar", 8) = 6
3953 strnlen ("foobar", 9) = 6
3956 @item @code{sysconf}
3958 @prindex @code{sysconf}
3959 @code{_SC_PAGESIZE} is standard, but some older systems (e.g., HP-UX
3960 9) have @code{_SC_PAGE_SIZE} instead. This can be tested with
3965 @prindex @code{unlink}
3966 The Posix spec says that @code{unlink} causes the given file to be
3967 removed only after there are no more open file handles for it. Some
3968 non-Posix hosts have trouble with this requirement, though,
3969 and some @acronym{DOS} variants even corrupt the file system.
3971 @item @code{unsetenv}
3972 @c @fuindex unsetenv
3973 @prindex @code{unsetenv}
3974 On MINGW, @code{unsetenv} is not available, but a variable @samp{FOO}
3975 can be removed with a call @code{putenv("FOO=")}, as described under
3976 @code{putenv} above.
3978 @item @code{va_copy}
3980 @prindex @code{va_copy}
3981 The ISO C99 standard provides @code{va_copy} for copying
3982 @code{va_list} variables. It may be available in older environments
3983 too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict
3984 C89 mode). These can be tested with @code{#ifdef}. A fallback to
3985 @code{memcpy (&dst, &src, sizeof(va_list))} will give maximum
3988 @item @code{va_list}
3990 @prindex @code{va_list}
3991 @code{va_list} is not necessarily just a pointer. It can be a
3992 @code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is
3993 not portable. Or it can be an array (e.g., @command{gcc} in some
3994 PowerPC configurations), which means as a function parameter it can be
3995 effectively call-by-reference and library routines might modify the
3996 value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library
3999 @item Signed @code{>>}
4000 Normally the C @code{>>} right shift of a signed type replicates the
4001 high bit, giving a so-called ``arithmetic'' shift. But care should be
4002 taken since the ISO C standard doesn't require that behavior. On those
4003 few processors without a native arithmetic shift (for instance Cray
4004 vector systems) zero bits may be shifted in, the same as a shift of an
4009 @node Particular Functions
4010 @subsection Particular Function Checks
4011 @cindex Function, checking
4013 These macros check for particular C functions---whether they exist, and
4014 in some cases how they respond when given certain arguments.
4016 @defmac AC_FUNC_ALLOCA
4017 @acindex{FUNC_ALLOCA}
4019 @cvindex HAVE_ALLOCA_H
4022 @prindex @code{alloca}
4024 Check how to get @code{alloca}. Tries to get a builtin version by
4025 checking for @file{alloca.h} or the predefined C preprocessor macros
4026 @code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
4027 it defines @code{HAVE_ALLOCA_H}.
4029 If those attempts fail, it looks for the function in the standard C
4030 library. If any of those methods succeed, it defines
4031 @code{HAVE_ALLOCA}. Otherwise, it sets the output variable
4032 @code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines
4033 @code{C_ALLOCA} (so programs can periodically call @samp{alloca(0)} to
4034 garbage collect). This variable is separate from @code{LIBOBJS} so
4035 multiple programs can share the value of @code{ALLOCA} without needing
4036 to create an actual library, in case only some of them use the code in
4037 @code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same
4038 purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}).
4040 This macro does not try to get @code{alloca} from the System V R3
4041 @file{libPW} or the System V R4 @file{libucb} because those libraries
4042 contain some incompatible functions that cause trouble. Some versions
4043 do not even contain @code{alloca} or contain a buggy version. If you
4044 still want to use their @code{alloca}, use @code{ar} to extract
4045 @file{alloca.o} from them instead of compiling @file{alloca.c}.
4047 Source files that use @code{alloca} should start with a piece of code
4048 like the following, to declare it properly.
4053 # include <alloca.h>
4054 #elif defined __GNUC__
4055 # define alloca __builtin_alloca
4057 # define alloca __alloca
4058 #elif defined _MSC_VER
4059 # include <malloc.h>
4060 # define alloca _alloca
4062 # include <stddef.h>
4066 void *alloca (size_t);
4072 @defmac AC_FUNC_CHOWN
4073 @acindex{FUNC_CHOWN}
4075 @prindex @code{chown}
4076 If the @code{chown} function is available and works (in particular, it
4077 should accept @option{-1} for @code{uid} and @code{gid}), define
4082 @defmac AC_FUNC_CLOSEDIR_VOID
4083 @acindex{FUNC_CLOSEDIR_VOID}
4084 @cvindex CLOSEDIR_VOID
4085 @c @fuindex closedir
4086 @prindex @code{closedir}
4087 If the @code{closedir} function does not return a meaningful value,
4088 define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
4089 return value for an error indicator.
4091 Currently this test is implemented by running a test program. When
4092 cross compiling the pessimistic assumption that @code{closedir} does not
4093 return a meaningful value is made.
4096 @defmac AC_FUNC_ERROR_AT_LINE
4097 @acindex{FUNC_ERROR_AT_LINE}
4098 @c @fuindex error_at_line
4099 @prindex @code{error_at_line}
4100 If the @code{error_at_line} function is not found, require an
4101 @code{AC_LIBOBJ} replacement of @samp{error}.
4104 @defmac AC_FUNC_FNMATCH
4105 @acindex{FUNC_FNMATCH}
4107 @prindex @code{fnmatch}
4108 If the @code{fnmatch} function conforms to Posix, define
4109 @code{HAVE_FNMATCH}. Detect common implementation bugs, for example,
4110 the bugs in Solaris 2.4.
4112 Note that for historical reasons, contrary to the other specific
4113 @code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a
4114 broken/missing @code{fnmatch}. See @code{AC_REPLACE_FNMATCH} below.
4117 @defmac AC_FUNC_FNMATCH_GNU
4118 @acindex{FUNC_FNMATCH_GNU}
4120 @prindex @code{fnmatch}
4121 Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test
4122 whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common
4123 implementation bugs, for example, the bugs in the @acronym{GNU} C
4127 @defmac AC_FUNC_FORK
4129 @cvindex HAVE_VFORK_H
4130 @cvindex HAVE_WORKING_FORK
4131 @cvindex HAVE_WORKING_VFORK
4134 @prindex @code{fork}
4136 @prindex @code{vfork}
4138 This macro checks for the @code{fork} and @code{vfork} functions. If a
4139 working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
4140 checks whether @code{fork} is just a stub by trying to run it.
4142 If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
4143 @code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
4144 define @code{vfork} to be @code{fork} for backward compatibility with
4145 previous versions of @command{autoconf}. This macro checks for several known
4146 errors in implementations of @code{vfork} and considers the system to not
4147 have a working @code{vfork} if it detects any of them. It is not considered
4148 to be an implementation error if a child's invocation of @code{signal}
4149 modifies the parent's signal handler, since child processes rarely change
4150 their signal handlers.
4152 Since this macro defines @code{vfork} only for backward compatibility with
4153 previous versions of @command{autoconf} you're encouraged to define it
4154 yourself in new code:
4157 #if !HAVE_WORKING_VFORK
4164 @defmac AC_FUNC_FSEEKO
4165 @acindex{FUNC_FSEEKO}
4166 @cvindex _LARGEFILE_SOURCE
4168 @prindex @code{fseeko}
4169 If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
4170 Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype
4171 visible on some systems (e.g., glibc 2.2). Otherwise linkage problems
4172 may occur when compiling with @code{AC_SYS_LARGEFILE} on
4173 largefile-sensitive systems where @code{off_t} does not default to a
4177 @defmac AC_FUNC_GETGROUPS
4178 @acindex{FUNC_GETGROUPS}
4179 @ovindex GETGROUPS_LIBS
4180 @c @fuindex getgroups
4181 @prindex @code{getgroups}
4182 If the @code{getgroups} function is available and works (unlike on
4183 Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
4184 @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
4185 needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
4188 @defmac AC_FUNC_GETLOADAVG
4189 @acindex{FUNC_GETLOADAVG}
4194 @cvindex HAVE_NLIST_H
4195 @cvindex NLIST_NAME_UNION
4196 @cvindex GETLODAVG_PRIVILEGED
4197 @cvindex NEED_SETGID
4198 @cvindex C_GETLOADAVG
4200 @ovindex NEED_SETGID
4202 @ovindex GETLOADAVG_LIBS
4203 @c @fuindex getloadavg
4204 @prindex @code{getloadavg}
4205 Check how to get the system load averages. To perform its tests
4206 properly, this macro needs the file @file{getloadavg.c}; therefore, be
4207 sure to set the @code{AC_LIBOBJ} replacement directory properly (see
4208 @ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}).
4210 If the system has the @code{getloadavg} function, define
4211 @code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries
4212 necessary to get that function. Also add @code{GETLOADAVG_LIBS} to
4213 @code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for
4214 @samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and
4215 possibly define several other C preprocessor macros and output
4220 Define @code{C_GETLOADAVG}.
4223 Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
4228 If @file{nlist.h} is found, define @code{HAVE_NLIST_H}.
4231 If @samp{struct nlist} has an @samp{n_un.n_name} member, define
4232 @code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
4233 @code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
4236 Programs may need to be installed setgid (or setuid) for
4237 @code{getloadavg} to work. In this case, define
4238 @code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
4239 to @samp{true} (and otherwise to @samp{false}), and set
4240 @code{KMEM_GROUP} to the name of the group that should own the installed
4245 @defmac AC_FUNC_GETMNTENT
4246 @acindex{FUNC_GETMNTENT}
4247 @cvindex HAVE_GETMNTENT
4248 @c @fuindex getmntent
4249 @prindex @code{getmntent}
4250 Check for @code{getmntent} in the standard C library, and then in the
4251 @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
4252 @sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if
4253 @code{getmntent} is available, define @code{HAVE_GETMNTENT}.
4256 @defmac AC_FUNC_GETPGRP
4257 @acindex{FUNC_GETPGRP}
4258 @cvindex GETPGRP_VOID
4261 @prindex @code{getpgid}
4262 @prindex @code{getpgrp}
4263 Define @code{GETPGRP_VOID} if it is an error to pass 0 to
4264 @code{getpgrp}; this is the Posix behavior. On older BSD
4265 systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
4266 behaves like Posix's @code{getpgid}.
4276 This macro does not check whether
4277 @code{getpgrp} exists at all; if you need to work in that situation,
4278 first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
4281 @defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
4282 @acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK}
4283 @cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
4285 @prindex @code{lstat}
4286 If @file{link} is a symbolic link, then @code{lstat} should treat
4287 @file{link/} the same as @file{link/.}. However, many older
4288 @code{lstat} implementations incorrectly ignore trailing slashes.
4290 It is safe to assume that if @code{lstat} incorrectly ignores
4291 trailing slashes, then other symbolic-link-aware functions like
4292 @code{unlink} also incorrectly ignore trailing slashes.
4294 If @code{lstat} behaves properly, define
4295 @code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
4296 @code{AC_LIBOBJ} replacement of @code{lstat}.
4299 @defmac AC_FUNC_MALLOC
4300 @acindex{FUNC_MALLOC}
4301 @cvindex HAVE_MALLOC
4304 @prindex @code{malloc}
4305 If the @code{malloc} function is compatible with the @acronym{GNU} C
4306 library @code{malloc} (i.e., @samp{malloc (0)} returns a valid
4307 pointer), define @code{HAVE_MALLOC} to 1. Otherwise define
4308 @code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4309 @samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the
4310 native @code{malloc} is not used in the main project.
4312 Typically, the replacement file @file{malloc.c} should look like (note
4313 the @samp{#undef malloc}):
4317 # include <config.h>
4321 #include <sys/types.h>
4325 /* Allocate an N-byte block of memory from the heap.
4326 If N is zero, allocate a 1-byte block. */
4329 rpl_malloc (size_t n)
4338 @defmac AC_FUNC_MEMCMP
4339 @acindex{FUNC_MEMCMP}
4342 @prindex @code{memcmp}
4343 If the @code{memcmp} function is not available, or does not work on
4344 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
4345 bytes or more and with at least one buffer not starting on a 4-byte
4346 boundary (such as the one on NeXT x86 OpenStep), require an
4347 @code{AC_LIBOBJ} replacement for @samp{memcmp}.
4350 @defmac AC_FUNC_MBRTOWC
4351 @acindex{FUNC_MBRTOWC}
4352 @cvindex HAVE_MBRTOWC
4354 @prindex @code{mbrtowc}
4355 Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the
4356 type @code{mbstate_t} are properly declared.
4359 @defmac AC_FUNC_MKTIME
4360 @acindex{FUNC_MKTIME}
4363 @prindex @code{mktime}
4364 If the @code{mktime} function is not available, or does not work
4365 correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
4366 For the purposes of this test, @code{mktime} should conform to the
4367 Posix standard and should be the inverse of
4371 @defmac AC_FUNC_MMAP
4375 @prindex @code{mmap}
4376 If the @code{mmap} function exists and works correctly, define
4377 @code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped
4381 @defmac AC_FUNC_OBSTACK
4382 @acindex{FUNC_OBSTACK}
4383 @cvindex HAVE_OBSTACK
4385 If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
4386 @code{AC_LIBOBJ} replacement for @samp{obstack}.
4389 @defmac AC_FUNC_REALLOC
4390 @acindex{FUNC_REALLOC}
4391 @cvindex HAVE_REALLOC
4394 @prindex @code{realloc}
4395 If the @code{realloc} function is compatible with the @acronym{GNU} C
4396 library @code{realloc} (i.e., @samp{realloc (0, 0)} returns a
4397 valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define
4398 @code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for
4399 @samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that
4400 the native @code{realloc} is not used in the main project. See
4401 @code{AC_FUNC_MALLOC} for details.
4404 @defmac AC_FUNC_SELECT_ARGTYPES
4405 @acindex{FUNC_SELECT_ARGTYPES}
4406 @cvindex SELECT_TYPE_ARG1
4407 @cvindex SELECT_TYPE_ARG234
4408 @cvindex SELECT_TYPE_ARG5
4410 @prindex @code{select}
4411 Determines the correct type to be passed for each of the
4412 @code{select} function's arguments, and defines those types
4413 in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
4414 @code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
4415 to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
4416 and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
4419 @defmac AC_FUNC_SETPGRP
4420 @acindex{FUNC_SETPGRP}
4421 @cvindex SETPGRP_VOID
4423 @prindex @code{setpgrp}
4424 If @code{setpgrp} takes no argument (the Posix version), define
4425 @code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes
4426 two process IDs as arguments. This macro does not check whether
4427 @code{setpgrp} exists at all; if you need to work in that situation,
4428 first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
4431 @defmac AC_FUNC_STAT
4432 @defmacx AC_FUNC_LSTAT
4434 @acindex{FUNC_LSTAT}
4435 @cvindex HAVE_STAT_EMPTY_STRING_BUG
4436 @cvindex HAVE_LSTAT_EMPTY_STRING_BUG
4438 @prindex @code{stat}
4440 @prindex @code{lstat}
4441 Determine whether @code{stat} or @code{lstat} have the bug that it
4442 succeeds when given the zero-length file name as argument. The @code{stat}
4443 and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
4446 If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
4447 @code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
4451 @defmac AC_FUNC_SETVBUF_REVERSED
4452 @acindex{FUNC_SETVBUF_REVERSED}
4453 @cvindex SETVBUF_REVERSED
4455 @prindex @code{setvbuf}
4456 If @code{setvbuf} takes the buffering type as its second argument and
4457 the buffer pointer as the third, instead of the other way around, define
4458 @code{SETVBUF_REVERSED}.
4461 @defmac AC_FUNC_STRCOLL
4462 @acindex{FUNC_STRCOLL}
4463 @cvindex HAVE_STRCOLL
4465 @prindex @code{strcoll}
4466 If the @code{strcoll} function exists and works correctly, define
4467 @code{HAVE_STRCOLL}. This does a bit more than
4468 @samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
4469 definitions of @code{strcoll} that should not be used.
4472 @defmac AC_FUNC_STRTOD
4473 @acindex{FUNC_STRTOD}
4476 @prindex @code{strtod}
4477 If the @code{strtod} function does not exist or doesn't work correctly,
4478 ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
4479 because @file{strtod.c} is likely to need @samp{pow}, set the output
4480 variable @code{POW_LIB} to the extra library needed.
4483 @defmac AC_FUNC_STRERROR_R
4484 @acindex{FUNC_STRERROR_R}
4485 @cvindex HAVE_STRERROR_R
4486 @cvindex HAVE_DECL_STRERROR_R
4487 @cvindex STRERROR_R_CHAR_P
4488 @c @fuindex strerror_r
4489 @prindex @code{strerror_r}
4490 If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
4491 it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
4492 @code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
4493 returns an @code{int} error number. The Thread-Safe Functions option of
4494 Posix requires @code{strerror_r} to return @code{int}, but
4495 many systems (including, for example, version 2.2.4 of the @acronym{GNU} C
4496 Library) return a @code{char *} value that is not necessarily equal to
4497 the buffer argument.
4500 @defmac AC_FUNC_STRFTIME
4501 @acindex{FUNC_STRFTIME}
4502 @cvindex HAVE_STRFTIME
4503 @c @fuindex strftime
4504 @prindex @code{strftime}
4505 Check for @code{strftime} in the @file{intl} library, for SCO Unix.
4506 Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
4509 @defmac AC_FUNC_STRNLEN
4510 @acindex{FUNC_STRNLEN}
4511 @cvindex HAVE_STRNLEN
4513 @prindex @code{strnlen}
4514 If the @code{strnlen} function is not available, or is buggy (like the one
4515 from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it.
4518 @defmac AC_FUNC_UTIME_NULL
4519 @acindex{FUNC_UTIME_NULL}
4520 @cvindex HAVE_UTIME_NULL
4522 @prindex @code{utime}
4523 If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
4524 the present, define @code{HAVE_UTIME_NULL}.
4527 @defmac AC_FUNC_VPRINTF
4528 @acindex{FUNC_VPRINTF}
4529 @cvindex HAVE_VPRINTF
4530 @cvindex HAVE_DOPRNT
4532 @prindex @code{vprintf}
4533 If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
4534 @code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
4535 is available, you may assume that @code{vfprintf} and @code{vsprintf}
4536 are also available.)
4539 @defmac AC_REPLACE_FNMATCH
4540 @acindex{REPLACE_FNMATCH}
4542 @prindex @code{fnmatch}
4543 @hdrindex{fnmatch.h}
4544 If the @code{fnmatch} function does not conform to Posix (see
4545 @code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement.
4547 The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h}
4548 in the @code{AC_LIBOBJ} replacement directory are assumed to contain a
4549 copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary,
4550 this source code is compiled as an @code{AC_LIBOBJ} replacement, and the
4551 @file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be
4552 included in place of the system @code{<fnmatch.h>}.
4557 @node Generic Functions
4558 @subsection Generic Function Checks
4560 These macros are used to find functions not covered by the ``particular''
4561 test macros. If the functions might be in libraries other than the
4562 default C library, first call @code{AC_CHECK_LIB} for those libraries.
4563 If you need to check the behavior of a function as well as find out
4564 whether it is present, you have to write your own test for
4565 it (@pxref{Writing Tests}).
4567 @defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
4568 @acindex{CHECK_FUNC}
4569 If C function @var{function} is available, run shell commands
4570 @var{action-if-found}, otherwise @var{action-if-not-found}. If you just
4571 want to define a symbol if the function is available, consider using
4572 @code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
4573 linkage even when @code{AC_LANG(C++)} has been called, since C is more
4574 standardized than C++. (@pxref{Language Choice}, for more information
4575 about selecting the language for checks.)
4578 @defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
4579 @acindex{CHECK_FUNCS}
4580 @cvindex HAVE_@var{function}
4581 For each @var{function} enumerated in the blank-or-newline-separated argument
4582 list, define @code{HAVE_@var{function}} (in all capitals) if it is available.
4583 If @var{action-if-found} is given, it is additional shell code to
4584 execute when one of the functions is found. You can give it a value of
4585 @samp{break} to break out of the loop on the first match. If
4586 @var{action-if-not-found} is given, it is executed when one of the
4587 functions is not found.
4592 Autoconf follows a philosophy that was formed over the years by those
4593 who have struggled for portability: isolate the portability issues in
4594 specific files, and then program as if you were in a Posix
4595 environment. Some functions may be missing or unfixable, and your
4596 package must be ready to replace them.
4598 Suitable replacements for many such problem functions are available from
4599 @uref{http://www.gnu.org/software/gnulib/, Gnulib}, which aims to
4600 provide a centralized repository of such portability functions (among
4601 other things). The source files are available online, under various
4602 licences, mostly GNU GPL or GNU LGPL.
4604 @defmac AC_LIBOBJ (@var{function})
4607 Specify that @samp{@var{function}.c} must be included in the executables
4608 to replace a missing or broken implementation of @var{function}.
4610 Technically, it adds @samp{@var{function}.$ac_objext} to the output
4611 variable @code{LIBOBJS} if it is not already in, and calls
4612 @code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not
4613 directly change @code{LIBOBJS}, since this is not traceable.
4616 @defmac AC_LIBSOURCE (@var{file})
4618 Specify that @var{file} might be needed to compile the project. If you
4619 need to know what files might be needed by a @file{configure.ac}, you
4620 should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
4622 This macro is called automatically from @code{AC_LIBOBJ}, but you must
4623 call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
4624 that case, since shell variables cannot be traced statically, you must
4625 pass to @code{AC_LIBSOURCE} any possible files that the shell variable
4626 might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
4627 a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
4628 @code{"foo"} or @code{"bar"}, you should do:
4631 AC_LIBSOURCE([foo.c])
4632 AC_LIBSOURCE([bar.c])
4633 AC_LIBOBJ([$foo_or_bar])
4637 There is usually a way to avoid this, however, and you are encouraged to
4638 simply call @code{AC_LIBOBJ} with literal arguments.
4640 Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
4641 slightly different semantics: the old macro took the function name,
4642 e.g., @code{foo}, as its argument rather than the file name.
4645 @defmac AC_LIBSOURCES (@var{files})
4646 @acindex{LIBSOURCES}
4647 Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
4648 comma-separated M4 list. Thus, the above example might be rewritten:
4651 AC_LIBSOURCES([foo.c, bar.c])
4652 AC_LIBOBJ([$foo_or_bar])
4656 @defmac AC_CONFIG_LIBOBJ_DIR (@var{directory})
4657 @acindex{CONFIG_LIBOBJ_DIR}
4658 Specify that @code{AC_LIBOBJ} replacement files are to be found in
4659 @var{directory}, a name relative to the top level of the
4660 source tree. The replacement directory defaults to @file{.}, the top
4661 level directory, and the most typical value is @file{lib}, corresponding
4662 to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}.
4664 @command{configure} might need to know the replacement directory for the
4665 following reasons: (i) some checks use the replacement files, (ii) some
4666 macros bypass broken system headers by installing links to the
4667 replacement headers (iii) when used in conjunction with Automake,
4668 within each @file{Makefile}, @var{directory} is used as a relative path
4669 from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and
4670 @code{LTLIBOBJS}, etc.
4675 It is common to merely check for the existence of a function, and ask
4676 for its @code{AC_LIBOBJ} replacement if missing. The following macro is
4677 a convenient shorthand.
4679 @defmac AC_REPLACE_FUNCS (@var{function}@dots{})
4680 @acindex{REPLACE_FUNCS}
4682 Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
4683 @var{action-if-not-found}. You can declare your replacement function by
4684 enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the
4685 system has the function, it probably declares it in a header file you
4686 should be including, so you shouldn't redeclare it lest your declaration
4691 @section Header Files
4692 @cindex Header, checking
4694 The following macros check for the presence of certain C header files.
4695 If there is no macro specifically defined to check for a header file you need,
4696 and you don't need to check for any special properties of
4697 it, then you can use one of the general header-file check macros.
4700 * Header Portability:: Collected knowledge on common headers
4701 * Particular Headers:: Special handling to find certain headers
4702 * Generic Headers:: How to find other headers
4705 @node Header Portability
4706 @subsection Portability of Headers
4707 @cindex Portability of headers
4708 @cindex Header portability
4710 This section tries to collect knowledge about common headers, and the
4711 problems they cause. By definition, this list will always require
4712 additions. Please help us keeping it as complete as possible.
4715 @item @file{inttypes.h} vs.@: @file{stdint.h}
4716 @hdrindex{inttypes.h}
4718 Paul Eggert notes that: ISO C 1999 says that @file{inttypes.h} includes
4719 @file{stdint.h}, so there's no need to include @file{stdint.h}
4720 separately in a standard environment. Many implementations have
4721 @file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't
4722 know of any implementation that has @file{stdint.h} but not
4725 @item @file{linux/irda.h}
4726 @hdrindex{linux/irda.h}
4727 It requires @file{linux/types.h} and @file{sys/socket.h}.
4729 @item @file{linux/random.h}
4730 @hdrindex{linux/random.h}
4731 It requires @file{linux/types.h}.
4733 @item @file{net/if.h}
4735 On Darwin, this file requires that @file{sys/socket.h} be included
4736 beforehand. One should run:
4739 AC_CHECK_HEADERS([sys/socket.h])
4740 AC_CHECK_HEADERS([net/if.h], [], [],
4743 # include <stdlib.h>
4744 # include <stddef.h>
4747 # include <stdlib.h>
4750 #if HAVE_SYS_SOCKET_H
4751 # include <sys/socket.h>
4756 @item @file{netinet/if_ether.h}
4757 @hdrindex{netinet/if_ether.h}
4758 On Darwin, this file requires that @file{stdio.h} and
4759 @file{sys/socket.h} be included beforehand. One should run:
4762 AC_CHECK_HEADERS([sys/socket.h])
4763 AC_CHECK_HEADERS([netinet/if_ether.h], [], [],
4766 # include <stdlib.h>
4767 # include <stddef.h>
4770 # include <stdlib.h>
4773 #if HAVE_SYS_SOCKET_H
4774 # include <sys/socket.h>
4779 @item @file{stdint.h}
4780 See above, item @file{inttypes.h} vs.@: @file{stdint.h}.
4782 @item @file{stdlib.h}
4784 On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite.
4786 @item @file{sys/mount.h}
4787 @hdrindex{sys/mount.h}
4788 On FreeBSD 4.8 on ia32 and using gcc version 2.95.4,
4789 @file{sys/params.h} is a prerequisite.
4791 @item @file{sys/socket.h}
4792 @hdrindex{sys/socket.h}
4793 On Darwin, @file{stdlib.h} is a prerequisite.
4795 @item @file{sys/ucred.h}
4796 @hdrindex{sys/ucred.h}
4797 On HP Tru64 5.1, @file{sys/types.h} is a prerequisite.
4799 @item @file{X11/extensions/scrnsaver.h}
4800 @hdrindex{X11/extensions/scrnsaver.h}
4801 Using XFree86, this header requires @file{X11/Xlib.h}, which is probably
4802 so required that you might not even consider looking for it.
4805 AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [],
4806 [[#include <X11/Xlib.h>
4812 @node Particular Headers
4813 @subsection Particular Header Checks
4815 These macros check for particular system header files---whether they
4816 exist, and in some cases whether they declare certain symbols.
4818 @defmac AC_HEADER_DIRENT
4819 @acindex{HEADER_DIRENT}
4820 @cvindex HAVE_DIRENT_H
4821 @cvindex HAVE_NDIR_H
4822 @cvindex HAVE_SYS_DIR_H
4823 @cvindex HAVE_SYS_NDIR_H
4825 @hdrindex{sys/ndir.h}
4826 @hdrindex{sys/dir.h}
4828 Check for the following header files. For the first one that is
4829 found and defines @samp{DIR}, define the listed C preprocessor macro:
4831 @multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
4832 @item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
4833 @item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
4834 @item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
4835 @item @file{ndir.h} @tab @code{HAVE_NDIR_H}
4838 The directory-library declarations in your source code should look
4839 something like the following:
4844 # include <dirent.h>
4845 # define NAMLEN(dirent) strlen((dirent)->d_name)
4847 # define dirent direct
4848 # define NAMLEN(dirent) (dirent)->d_namlen
4849 # if HAVE_SYS_NDIR_H
4850 # include <sys/ndir.h>
4853 # include <sys/dir.h>
4862 Using the above declarations, the program would declare variables to be
4863 of type @code{struct dirent}, not @code{struct direct}, and would access
4864 the length of a directory entry name by passing a pointer to a
4865 @code{struct dirent} to the @code{NAMLEN} macro.
4867 This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
4870 @defmac AC_HEADER_MAJOR
4871 @acindex{HEADER_MAJOR}
4872 @cvindex MAJOR_IN_MKDEV
4873 @cvindex MAJOR_IN_SYSMACROS
4874 @hdrindex{sys/mkdev.h}
4875 @hdrindex{sys/sysmacros.h}
4876 If @file{sys/types.h} does not define @code{major}, @code{minor}, and
4877 @code{makedev}, but @file{sys/mkdev.h} does, define
4878 @code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
4879 @code{MAJOR_IN_SYSMACROS}.
4882 @defmac AC_HEADER_RESOLV
4883 @acindex{HEADER_RESOLV}
4884 @cvindex HAVE_RESOLV_H
4886 Checks for header @file{resolv.h}, checking for prerequisities first.
4887 To properly use @file{resolv.h}, your code should contain something like
4891 #if HAVE_SYS_TYPES_H
4892 # include <sys/types.h>
4894 #ifdef HAVE_NETINET_IN_H
4895 # include <netinet/in.h> /* inet_ functions / structs */
4897 #ifdef HAVE_ARPA_NAMESER_H
4898 # include <arpa/nameser.h> /* DNS HEADER struct */
4907 @defmac AC_HEADER_STAT
4908 @acindex{HEADER_STAT}
4909 @cvindex STAT_MACROS_BROKEN
4910 @hdrindex{sys/stat.h}
4911 If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in
4912 @file{sys/stat.h} do not work properly (returning false positives),
4913 define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
4914 Amdahl UTS and Motorola System V/88.
4917 @defmac AC_HEADER_STDBOOL
4918 @acindex{HEADER_STDBOOL}
4919 @cvindex HAVE_STDBOOL_H
4921 @hdrindex{stdbool.h}
4923 If @file{stdbool.h} exists and is conformant to C99, define
4924 @code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define
4925 @code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your
4926 @file{system.h} could contain the following code:
4930 # include <stdbool.h>
4936 typedef unsigned char _Bool;
4942 # define __bool_true_false_are_defined 1
4946 Alternatively you can construct an output variable that includes only
4947 those headers and definitions needed. For example:
4952 if test "x$ac_cv_header_stdbool_h" = xyes; then
4954 #include <stdbool.h>
4957 if test "x$ac_cv_type__Bool" != xyes; then
4962 typedef unsigned char _Bool;
4973 #define __bool_true_false_are_defined 1
4980 @defmac AC_HEADER_STDC
4981 @acindex{HEADER_STDC}
4982 @cvindex STDC_HEADERS
4988 Define @code{STDC_HEADERS} if the system has @acronym{ANSI} C header files.
4989 Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
4990 @file{string.h}, and @file{float.h}; if the system has those, it
4991 probably has the rest of the @acronym{ANSI} C header files. This macro also
4992 checks whether @file{string.h} declares @code{memchr} (and thus
4993 presumably the other @code{mem} functions), whether @file{stdlib.h}
4994 declare @code{free} (and thus presumably @code{malloc} and other related
4995 functions), and whether the @file{ctype.h} macros work on characters
4996 with the high bit set, as @acronym{ANSI} C requires.
4998 Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
4999 the system has @acronym{ANSI}-compliant header files (and probably C library
5000 functions) because many systems that have GCC do not have @acronym{ANSI} C
5004 @hdrindex{strings.h}
5005 On systems without @acronym{ANSI} C headers, there is so much variation
5006 that it is probably easier to declare the functions you use than to
5007 figure out exactly what the system header files declare. Some systems
5008 contain a mix of functions from @acronym{ANSI} and @acronym{BSD}; some are
5009 mostly @acronym{ANSI} but lack @samp{memmove}; some define the
5010 @acronym{BSD} functions as macros in @file{string.h} or
5011 @file{strings.h}; some have only the @acronym{BSD} functions but
5012 @file{string.h}; some declare the memory functions in @file{memory.h},
5013 some in @file{string.h}; etc. It is probably sufficient to check for
5014 one string function and one memory function; if the library has the
5015 @acronym{ANSI} versions of those then it probably has most of the others.
5016 If you put the following in @file{configure.ac}:
5020 AC_CHECK_FUNCS([strchr memcpy])
5024 then, in your code, you can use declarations like this:
5029 # include <string.h>
5032 # define strchr index
5033 # define strrchr rindex
5035 char *strchr (), *strrchr ();
5037 # define memcpy(d, s, n) bcopy ((s), (d), (n))
5038 # define memmove(d, s, n) bcopy ((s), (d), (n))
5045 If you use a function like @code{memchr}, @code{memset}, @code{strtok},
5046 or @code{strspn}, which have no @acronym{BSD} equivalent, then macros won't
5047 suffice; you must provide an implementation of each function. An easy
5048 way to incorporate your implementations only when needed (since the ones
5049 in system C libraries may be hand optimized) is to, taking @code{memchr}
5050 for example, put it in @file{memchr.c} and use
5051 @samp{AC_REPLACE_FUNCS([memchr])}.
5054 @defmac AC_HEADER_SYS_WAIT
5055 @acindex{HEADER_SYS_WAIT}
5056 @cvindex HAVE_SYS_WAIT_H
5057 @hdrindex{sys/wait.h}
5058 If @file{sys/wait.h} exists and is compatible with Posix, define
5059 @code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
5060 does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead
5061 of @code{int} to store a status value. If @file{sys/wait.h} is not
5062 Posix compatible, then instead of including it, define the
5063 Posix macros with their usual interpretations. Here is an
5068 #include <sys/types.h>
5070 # include <sys/wait.h>
5073 # define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8)
5076 # define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
5082 @cvindex _POSIX_VERSION
5084 @code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
5085 Posix systems. If there is no @file{unistd.h}, it is definitely
5086 not a Posix system. However, some non-Posix systems do
5087 have @file{unistd.h}.
5089 The way to check whether the system supports Posix is:
5094 # include <sys/types.h>
5095 # include <unistd.h>
5098 #ifdef _POSIX_VERSION
5099 /* Code for Posix systems. */
5104 @defmac AC_HEADER_TIME
5105 @acindex{HEADER_TIME}
5106 @cvindex TIME_WITH_SYS_TIME
5108 @hdrindex{sys/time.h}
5109 If a program may include both @file{time.h} and @file{sys/time.h},
5110 define @code{TIME_WITH_SYS_TIME}. On some older systems,
5111 @file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
5112 protected against multiple inclusion, so programs should not explicitly
5113 include both files. This macro is useful in programs that use, for
5114 example, @code{struct timeval} as well as
5115 @code{struct tm}. It is best used in conjunction with
5116 @code{HAVE_SYS_TIME_H}, which can be checked for using
5117 @code{AC_CHECK_HEADERS([sys/time.h])}.
5121 #if TIME_WITH_SYS_TIME
5122 # include <sys/time.h>
5125 # if HAVE_SYS_TIME_H
5126 # include <sys/time.h>
5136 @defmac AC_HEADER_TIOCGWINSZ
5137 @acindex{HEADER_TIOCGWINSZ}
5138 @cvindex GWINSZ_IN_SYS_IOCTL
5139 @hdrindex{sys/ioctl.h}
5140 @hdrindex{termios.h}
5141 @c FIXME: I need clarifications from Jim.
5142 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
5143 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
5144 found in @file{<termios.h>}.
5151 # include <termios.h>
5154 #if GWINSZ_IN_SYS_IOCTL
5155 # include <sys/ioctl.h>
5161 @node Generic Headers
5162 @subsection Generic Header Checks
5164 These macros are used to find system header files not covered by the
5165 ``particular'' test macros. If you need to check the contents of a header
5166 as well as find out whether it is present, you have to write your own
5167 test for it (@pxref{Writing Tests}).
5169 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5170 @acindex{CHECK_HEADER}
5171 If the system header file @var{header-file} is compilable, execute shell
5172 commands @var{action-if-found}, otherwise execute
5173 @var{action-if-not-found}. If you just want to define a symbol if the
5174 header file is available, consider using @code{AC_CHECK_HEADERS}
5177 For compatibility issues with older versions of Autoconf, please read
5181 @defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5182 @acindex{CHECK_HEADERS}
5183 @cvindex HAVE_@var{header}
5184 For each given system header file @var{header-file} in the
5185 blank-separated argument list that exists, define
5186 @code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
5187 is given, it is additional shell code to execute when one of the header
5188 files is found. You can give it a value of @samp{break} to break out of
5189 the loop on the first match. If @var{action-if-not-found} is given, it
5190 is executed when one of the header files is not found.
5192 For compatibility issues with older versions of Autoconf, please read
5196 Previous versions of Autoconf merely checked whether the header was
5197 accepted by the preprocessor. This was changed because the old test was
5198 inappropriate for typical uses. Headers are typically used to compile,
5199 not merely to preprocess, and the old behavior sometimes accepted
5200 headers that clashed at compile-time. If you need to check whether a
5201 header is preprocessable, you can use @code{AC_PREPROC_IFELSE}
5202 (@pxref{Running the Preprocessor}).
5204 This scheme, which improves the robustness of the test, also requires
5205 that you make sure that headers that must be included before the
5206 @var{header-file} be part of the @var{includes}, (@pxref{Default
5207 Includes}). If looking for @file{bar.h}, which requires that
5208 @file{foo.h} be included before if it exists, we suggest the following
5212 AC_CHECK_HEADERS([foo.h])
5213 AC_CHECK_HEADERS([bar.h], [], [],
5221 @section Declarations
5222 @cindex Declaration, checking
5224 The following macros check for the declaration of variables and
5225 functions. If there is no macro specifically defined to check for a
5226 symbol you need, then you can use the general macros (@pxref{Generic
5227 Declarations}) or, for more complex tests, you may use
5228 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5231 * Particular Declarations:: Macros to check for certain declarations
5232 * Generic Declarations:: How to find other declarations
5235 @node Particular Declarations
5236 @subsection Particular Declaration Checks
5238 There are no specific macros for declarations.
5240 @node Generic Declarations
5241 @subsection Generic Declaration Checks
5243 These macros are used to find declarations not covered by the ``particular''
5246 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5247 @acindex{CHECK_DECL}
5248 If @var{symbol} (a function or a variable) is not declared in
5249 @var{includes} and a declaration is needed, run the shell commands
5250 @var{action-if-not-found}, otherwise @var{action-if-found}. If no
5251 @var{includes} are specified, the default includes are used
5252 (@pxref{Default Includes}).
5254 This macro actually tests whether it is valid to use @var{symbol} as an
5255 r-value, not if it is really declared, because it is much safer to avoid
5256 introducing extra declarations when they are not needed.
5259 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5260 @acindex{CHECK_DECLS}
5261 @cvindex HAVE_DECL_@var{symbol}
5262 For each of the @var{symbols} (@emph{comma}-separated list), define
5263 @code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
5264 @var{symbol} is declared, otherwise to @samp{0}. If
5265 @var{action-if-not-found} is given, it is additional shell code to
5266 execute when one of the function declarations is needed, otherwise
5267 @var{action-if-found} is executed.
5269 This macro uses an m4 list as first argument:
5271 AC_CHECK_DECLS([strdup])
5272 AC_CHECK_DECLS([strlen])
5273 AC_CHECK_DECLS([malloc, realloc, calloc, free])
5276 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
5277 declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
5278 of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
5279 @emph{sure} that the check was performed, use
5280 @code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
5283 #if !HAVE_DECL_SYMBOL
5284 extern char *symbol;
5289 If the test may have not been performed, however, because it is safer
5290 @emph{not} to declare a symbol than to use a declaration that conflicts
5291 with the system's one, you should use:
5294 #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
5295 void *malloc (size_t *s);
5300 You fall into the second category only in extreme situations: either
5301 your files may be used without being configured, or they are used during
5302 the configuration. In most cases the traditional approach is enough.
5308 @cindex Structure, checking
5310 The following macros check for the presence of certain members in C
5311 structures. If there is no macro specifically defined to check for a
5312 member you need, then you can use the general structure-member macros
5313 (@pxref{Generic Structures}) or, for more complex tests, you may use
5314 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}).
5317 * Particular Structures:: Macros to check for certain structure members
5318 * Generic Structures:: How to find other structure members
5321 @node Particular Structures
5322 @subsection Particular Structure Checks
5324 The following macros check for certain structures or structure members.
5326 @defmac AC_STRUCT_ST_BLKSIZE
5327 @acindex{STRUCT_ST_BLKSIZE}
5328 @cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
5329 @cvindex HAVE_ST_BLKSIZE
5330 If @code{struct stat} contains an @code{st_blksize} member, define
5331 @code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
5332 @code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
5333 the future. This macro is obsoleted, and should be replaced by
5336 AC_CHECK_MEMBERS([struct stat.st_blksize])
5340 @defmac AC_STRUCT_ST_BLOCKS
5341 @acindex{STRUCT_ST_BLOCKS}
5342 @cvindex HAVE_STRUCT_STAT_ST_BLOCKS
5343 @cvindex HAVE_ST_BLOCKS
5345 If @code{struct stat} contains an @code{st_blocks} member, define
5346 @code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an
5347 @code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
5348 @code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
5352 @defmac AC_STRUCT_ST_RDEV
5353 @acindex{STRUCT_ST_RDEV}
5354 @cvindex HAVE_ST_RDEV
5355 @cvindex HAVE_STRUCT_STAT_ST_RDEV
5356 If @code{struct stat} contains an @code{st_rdev} member, define
5357 @code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
5358 @code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
5359 in the future. Actually, even the new macro is obsolete and should be
5362 AC_CHECK_MEMBERS([struct stat.st_rdev])
5366 @defmac AC_STRUCT_TM
5368 @cvindex TM_IN_SYS_TIME
5370 @hdrindex{sys/time.h}
5371 If @file{time.h} does not define @code{struct tm}, define
5372 @code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
5373 had better define @code{struct tm}.
5376 @defmac AC_STRUCT_TIMEZONE
5377 @acindex{STRUCT_TIMEZONE}
5378 @cvindex HAVE_TM_ZONE
5379 @cvindex HAVE_TZNAME
5380 Figure out how to get the current timezone. If @code{struct tm} has a
5381 @code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
5382 obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
5383 @code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared,
5384 define @code{HAVE_DECL_TZNAME}.
5387 @node Generic Structures
5388 @subsection Generic Structure Checks
5390 These macros are used to find structure members not covered by the
5391 ``particular'' test macros.
5393 @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5394 @acindex{CHECK_MEMBER}
5395 Check whether @var{member} is a member of the aggregate @var{aggregate}.
5396 If no @var{includes} are specified, the default includes are used
5397 (@pxref{Default Includes}).
5400 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
5401 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
5405 You can use this macro for sub-members:
5408 AC_CHECK_MEMBER(struct top.middle.bot)
5412 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5413 @acindex{CHECK_MEMBERS}
5414 Check for the existence of each @samp{@var{aggregate}.@var{member}} of
5415 @var{members} using the previous macro. When @var{member} belongs to
5416 @var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
5417 capitals, with spaces and dots replaced by underscores). If
5418 @var{action-if-found} is given, it is executed for each of the found
5419 members. If @var{action-if-not-found} is given, it is executed for each
5420 of the members that could not be found.
5422 This macro uses m4 lists:
5424 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
5434 The following macros check for C types, either builtin or typedefs. If
5435 there is no macro specifically defined to check for a type you need, and
5436 you don't need to check for any special properties of it, then you can
5437 use a general type-check macro.
5440 * Particular Types:: Special handling to find certain types
5441 * Generic Types:: How to find other types
5444 @node Particular Types
5445 @subsection Particular Type Checks
5447 @hdrindex{sys/types.h}
5449 These macros check for particular C types in @file{sys/types.h},
5450 @file{stdlib.h} and others, if they exist.
5452 @defmac AC_TYPE_GETGROUPS
5453 @acindex{TYPE_GETGROUPS}
5454 @cvindex GETGROUPS_T
5455 Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
5456 is the base type of the array argument to @code{getgroups}.
5459 @defmac AC_TYPE_MBSTATE_T
5460 @acindex{TYPE_MBSTATE_T}
5463 Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the
5464 @code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if
5465 @code{<wchar.h>} does not declare it.
5468 @defmac AC_TYPE_MODE_T
5469 @acindex{TYPE_MODE_T}
5471 Equivalent to @samp{AC_CHECK_TYPE([mode_t], [int])}.
5474 @defmac AC_TYPE_OFF_T
5475 @acindex{TYPE_OFF_T}
5477 Equivalent to @samp{AC_CHECK_TYPE([off_t], [long int])}.
5480 @defmac AC_TYPE_PID_T
5481 @acindex{TYPE_PID_T}
5483 Equivalent to @samp{AC_CHECK_TYPE([pid_t], [int])}.
5486 @defmac AC_TYPE_SIGNAL
5487 @acindex{TYPE_SIGNAL}
5490 If @file{signal.h} declares @code{signal} as returning a pointer to a
5491 function returning @code{void}, define @code{RETSIGTYPE} to be
5492 @code{void}; otherwise, define it to be @code{int}.
5494 Define signal handlers as returning type @code{RETSIGTYPE}:
5507 @defmac AC_TYPE_SIZE_T
5508 @acindex{TYPE_SIZE_T}
5510 Equivalent to @samp{AC_CHECK_TYPE([size_t], [unsigned int])}.
5513 @defmac AC_TYPE_UID_T
5514 @acindex{TYPE_UID_T}
5517 If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
5518 @code{gid_t} to be @code{int}.
5522 @subsection Generic Type Checks
5524 These macros are used to check for types not covered by the ``particular''
5527 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5528 @acindex{CHECK_TYPE}
5529 Check whether @var{type} is defined. It may be a compiler builtin type
5530 or defined by the @var{includes} (@pxref{Default Includes}).
5534 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
5535 @acindex{CHECK_TYPES}
5536 For each @var{type} of the @var{types} that is defined, define
5537 @code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
5538 specified, the default includes are used (@pxref{Default Includes}). If
5539 @var{action-if-found} is given, it is additional shell code to execute
5540 when one of the types is found. If @var{action-if-not-found} is given,
5541 it is executed when one of the types is not found.
5543 This macro uses m4 lists:
5545 AC_CHECK_TYPES([ptrdiff_t])
5546 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
5551 Autoconf, up to 2.13, used to provide to another version of
5552 @code{AC_CHECK_TYPE}, broken by design. In order to keep backward
5553 compatibility, a simple heuristics, quite safe but not totally, is
5554 implemented. In case of doubt, read the documentation of the former
5555 @code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
5558 @node Compilers and Preprocessors
5559 @section Compilers and Preprocessors
5561 @cindex Preprocessors
5564 All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
5565 @code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
5566 the output of the compiler, typically to the empty string if
5567 Posix and @samp{.exe} if a @acronym{DOS} variant.
5570 They also define the output variable @code{OBJEXT} based on the
5571 output of the compiler, after @file{.c} files have been excluded, typically
5572 to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant.
5574 If the compiler being used does not produce executables, the tests fail. If
5575 the executables can't be run, and cross-compilation is not enabled, they
5576 fail too. @xref{Manual Configuration}, for more on support for cross
5580 * Specific Compiler Characteristics:: Some portability issues
5581 * Generic Compiler Characteristics:: Language independent tests and features
5582 * C Compiler:: Checking its characteristics
5583 * C++ Compiler:: Likewise
5584 * Fortran Compiler:: Likewise
5587 @node Specific Compiler Characteristics
5588 @subsection Specific Compiler Characteristics
5590 Some compilers exhibit different behaviors.
5593 @item Static/Dynamic Expressions
5594 Autoconf relies on a trick to extract one bit of information from the C
5595 compiler: using negative array sizes. For instance the following
5596 excerpt of a C source demonstrates how to test whether @samp{int}s are 4
5603 static int test_array [sizeof (int) == 4 ? 1 : -1];
5610 To our knowledge, there is a single compiler that does not support this
5611 trick: the HP C compilers (the real one, not only the ``bundled'') on
5612 HP-UX 11.00. They incorrectly reject the above program with the diagnostic
5613 ``Variable-length arrays cannot have static storage.''
5614 This bug comes from HP compilers' mishandling of @code{sizeof (int)},
5615 not from the @code{? 1 : -1}, and
5616 Autoconf works around this problem by casting @code{sizeof (int)} to
5617 @code{long int} before comparing it.
5620 @node Generic Compiler Characteristics
5621 @subsection Generic Compiler Characteristics
5623 @defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
5624 @acindex{CHECK_SIZEOF}
5625 Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
5626 size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
5627 of 0. If no @var{includes} are specified, the default includes are used
5628 (@pxref{Default Includes}). If you provide @var{include}, be sure to
5629 include @file{stdio.h} which is required for this macro to run.
5631 This macro now works even when cross-compiling. The @var{unused}
5632 argument was used when cross-compiling.
5634 For example, the call
5637 AC_CHECK_SIZEOF([int *])
5641 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
5644 @defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
5645 @acindex{CHECK_ALIGNOF}
5646 Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the
5647 alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size
5648 of 0. If no @var{includes} are specified, the default includes are used
5649 (@pxref{Default Includes}). If you provide @var{include}, be sure to
5650 include @file{stddef.h} and @file{stdio.h} which are required for this
5651 macro to work correctly.
5654 @defmac AC_LANG_WERROR
5655 @acindex{LANG_WERROR}
5656 Normally Autoconf ignores warnings generated by the compiler, linker, and
5657 preprocessor. If this macro is used, warnings will be treated as fatal
5658 errors instead for the current language. This macro is useful when the
5659 results of configuration will be used where warnings are unacceptable; for
5660 instance, if parts of a program are built with the GCC @samp{-Werror}
5661 option. If the whole program will be built using @samp{-Werror} it is
5662 often simpler to put @samp{-Werror} in the compiler flags (@code{CFLAGS},
5667 @subsection C Compiler Characteristics
5669 The following macros provide ways to find and exercise a C Compiler.
5670 There are a few constructs that ought to be avoided, but do not deserve
5671 being checked for, since they can easily be worked around.
5674 @item Don't use lines containing solitary backslashes
5675 They tickle a bug in the HP-UX C compiler (checked on HP-UX 10.20,
5676 11.00, and 11i). When given the following source:
5681 * A comment with backslash-newlines in it. %@{ %@} *\
5685 " A string with backslash-newlines in it %@{ %@} \\
5687 char apostrophe = '\\
5695 the compiler incorrectly fails with the diagnostics ``Non-terminating
5696 comment at end of file'' and ``Missing @samp{#endif} at end of file.''
5697 Removing the lines with solitary backslashes solves the problem.
5699 @item Don't compile several files at once if output matters to you
5700 Some compilers, such as the HP's, reports the name of the file it is
5701 compiling @emph{when} they are several. For instance:
5710 This can cause problems if you observe the output of the compiler to
5711 detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o
5712 b.o} solves the issue.
5714 @item Don't rely on correct @code{#line} support
5715 On Solaris 8, @command{c89} (Sun WorkShop 6 update 2 C 5.3 Patch
5716 111679-08 2002/05/09)) diagnoses @code{#line} directives whose line
5717 numbers are greater than 32767. In addition, nothing in Posix
5718 makes this invalid. That is why Autoconf stopped issuing
5719 @code{#line} directives.
5722 @defmac AC_PROG_CC (@ovar{compiler-search-list})
5726 Determine a C compiler to use. If @code{CC} is not already set in the
5727 environment, check for @code{gcc} and @code{cc}, then for other C
5728 compilers. Set output variable @code{CC} to the name of the compiler
5731 This macro may, however, be invoked with an optional first argument
5732 which, if specified, must be a blank-separated list of C compilers to
5733 search for. This just gives the user an opportunity to specify an
5734 alternative search list for the C compiler. For example, if you didn't
5735 like the default order, then you could invoke @code{AC_PROG_CC} like
5739 AC_PROG_CC([cl egcs gcc cc])
5742 If the C compiler is not in @acronym{ANSI} mode by default, try to add an
5743 option to output variable @code{CC} to make it so. This macro tries
5744 various options that select @acronym{ANSI} C on some system or another. It
5745 considers the compiler to be in @acronym{ANSI} mode if it handles function
5746 prototypes correctly.
5748 After calling this macro you can check whether the C compiler has been
5749 set to accept @acronym{ANSI} C; if not, the shell variable
5750 @code{ac_cv_prog_cc_c89} is set to @samp{no}. If you wrote your source
5751 code in @acronym{ANSI} C, you can make an un-@acronym{ANSI}fied copy of it by
5752 using the program @code{ansi2knr}, which comes with Automake. See also
5753 under @code{AC_C_PROTOTYPES} below.
5755 If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to
5756 @samp{yes}. If output variable @code{CFLAGS} was not already set, set
5757 it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems
5758 where GCC does not accept @option{-g}), or @option{-g} for other compilers.
5761 @defmac AC_PROG_CC_C_O
5762 @acindex{PROG_CC_C_O}
5763 @cvindex NO_MINUS_C_MINUS_O
5764 If the C compiler does not accept the @option{-c} and @option{-o} options
5765 simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
5766 tests both the compiler found by @code{AC_PROG_CC}, and, if different,
5767 the first @code{cc} in the path. The test fails if one fails. This
5768 macro was created for @acronym{GNU} Make to choose the default C compilation
5776 Set output variable @code{CPP} to a command that runs the
5777 C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
5778 It is only portable to run @code{CPP} on files with a @file{.c}
5781 Some preprocessors don't indicate missing include files by the error
5782 status. For such preprocessors an internal variable is set that causes
5783 other macros to check the standard error from the preprocessor and
5784 consider the test failed if any warnings have been reported.
5785 For most preprocessors, though, warnings do not cause include-file
5786 tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified.
5789 @defmac AC_PROG_CPP_WERROR
5790 @acindex{PROG_CPP_WERROR}
5792 This acts like @code{AC_PROG_CPP}, except it treats warnings from the
5793 preprocessor as errors even if the preprocessor exit status indicates
5794 success. This is useful for avoiding headers that generate mandatory
5795 warnings, such as deprecation notices.
5799 The following macros check for C compiler or machine architecture
5800 features. To check for characteristics not listed here, use
5801 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
5802 @code{AC_RUN_IFELSE} (@pxref{Run Time}).
5804 @defmac AC_PROG_CC_STDC
5805 @acindex{PROG_CC_STDC}
5806 If the C compiler is not able to compile ISO Standard C (currently ISO
5807 C99), try to add an option to output variable @code{CC} to make it so.
5808 If the compiler does not support ISO C99, fall back to supporting
5809 @acronym{ANSI} C89 (ISO C90).
5811 After calling this macro you can check whether the C compiler has been
5812 set to accept ISO Standard C; if not, the shell variable
5813 @code{ac_cv_prog_cc_stdc} is set to @samp{no}.
5816 @defmac AC_PROG_CC_C89
5817 @acindex{PROG_CC_C89}
5818 If the C compiler is not in @acronym{ANSI} C89 (ISO C90) mode by
5819 default, try to add an option to output variable @code{CC} to make it
5820 so. This macro tries various options that select @acronym{ANSI} C89 on
5821 some system or another. It considers the compiler to be in
5822 @acronym{ANSI} C89 mode if it handles function prototypes correctly.
5824 After calling this macro you can check whether the C compiler has been
5825 set to accept @acronym{ANSI} C89; if not, the shell variable
5826 @code{ac_cv_prog_cc_c89} is set to @samp{no}.
5828 This macro is called automatically by @code{AC_PROG_CC}.
5831 @defmac AC_PROG_CC_C99
5832 @acindex{PROG_CC_C99}
5833 If the C compiler is not in ISO C99 mode by default, try to add an
5834 option to output variable @code{CC} to make it so. This macro tries
5835 various options that select ISO C99 on some system or another. It
5836 considers the compiler to be in ISO C99 mode if it handles @code{_Bool},
5837 flexible arrays, @code{inline}, @code{long long}, mixed code and
5838 declarations, named initialization of structs, @code{restrict}, varargs
5839 macros, variable declarations in @code{for} loops and variable length
5842 After calling this macro you can check whether the C compiler has been
5843 set to accept ISO C99; if not, the shell variable
5844 @code{ac_cv_prog_cc_c99} is set to @samp{no}.
5847 @defmac AC_C_BACKSLASH_A
5848 @acindex{HAVE_C_BACKSLASH_A}
5849 Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands
5853 @defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
5854 @acindex{C_BIGENDIAN}
5855 @cvindex WORDS_BIGENDIAN
5857 If words are stored with the most significant byte first (like Motorola
5858 and SPARC CPUs), execute @var{action-if-true}. If words are stored with
5859 the least significant byte first (like Intel and VAX CPUs), execute
5860 @var{action-if-false}.
5862 This macro runs a test-case if endianness cannot be determined from the
5863 system header files. When cross-compiling, the test-case is not run but
5864 grep'ed for some magic values. @var{action-if-unknown} is executed if
5865 the latter case fails to determine the byte sex of the host system.
5867 The default for @var{action-if-true} is to define
5868 @samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
5869 nothing. And finally, the default for @var{action-if-unknown} is to
5870 abort configure and tell the installer which variable he should preset
5871 to bypass this test.
5877 If the C compiler does not fully support the @acronym{ANSI} C qualifier
5878 @code{const}, define @code{const} to be empty. Some C compilers that do
5879 not define @code{__STDC__} do support @code{const}; some compilers that
5880 define @code{__STDC__} do not completely support @code{const}. Programs
5881 can simply use @code{const} as if every C compiler supported it; for
5882 those that don't, the @file{Makefile} or configuration header file will
5885 Occasionally installers use a C++ compiler to compile C code, typically
5886 because they lack a C compiler. This causes problems with @code{const},
5887 because C and C++ treat @code{const} differently. For example:
5894 is valid in C but not in C++. These differences unfortunately cannot be
5895 papered over by defining @code{const} to be empty.
5897 If @command{autoconf} detects this situation, it leaves @code{const} alone,
5898 as this generally yields better results in practice. However, using a
5899 C++ compiler to compile C code is not recommended or supported, and
5900 installers who run into trouble in this area should get a C compiler
5901 like GCC to compile their C code.
5904 @defmac AC_C_RESTRICT
5905 @acindex{C_RESTRICT}
5907 If the C compiler recognizes the @code{restrict} keyword, don't do anything.
5908 If it recognizes only a variant spelling (@code{__restrict},
5909 @code{__restrict__}, or @code{_Restrict}), then define
5910 @code{restrict} to that.
5911 Otherwise, define @code{restrict} to be empty.
5912 Thus, programs may simply use @code{restrict} as if every C compiler
5913 supported it; for those that do not, the @file{Makefile}
5914 or configuration header defines it away.
5916 Although support in C++ for the @code{restrict} keyword is not
5917 required, several C++ compilers do accept the keyword.
5918 This macro works for them, too.
5921 @defmac AC_C_VOLATILE
5922 @acindex{C_VOLATILE}
5924 If the C compiler does not understand the keyword @code{volatile},
5925 define @code{volatile} to be empty. Programs can simply use
5926 @code{volatile} as if every C compiler supported it; for those that do
5927 not, the @file{Makefile} or configuration header will define it as
5930 If the correctness of your program depends on the semantics of
5931 @code{volatile}, simply defining it to be empty does, in a sense, break
5932 your code. However, given that the compiler does not support
5933 @code{volatile}, you are at its mercy anyway. At least your
5934 program will compile, when it wouldn't before.
5936 In general, the @code{volatile} keyword is a feature of @acronym{ANSI} C, so
5937 you might expect that @code{volatile} is available only when
5938 @code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
5939 support volatile, but does not define @code{__STDC__}.
5945 If the C compiler supports the keyword @code{inline}, do nothing.
5946 Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
5947 if it accepts one of those, otherwise define @code{inline} to be empty.
5950 @defmac AC_C_CHAR_UNSIGNED
5951 @acindex{C_CHAR_UNSIGNED}
5952 @cvindex __CHAR_UNSIGNED__
5953 If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
5954 unless the C compiler predefines it.
5957 @defmac AC_C_LONG_DOUBLE
5958 @acindex{C_LONG_DOUBLE}
5959 @cvindex HAVE_LONG_DOUBLE
5960 If the C compiler supports a working @code{long double} type with more
5961 range or precision than the @code{double} type, define
5962 @code{HAVE_LONG_DOUBLE}.
5965 @defmac AC_C_STRINGIZE
5966 @acindex{C_STRINGIZE}
5967 @cvindex HAVE_STRINGIZE
5968 If the C preprocessor supports the stringizing operator, define
5969 @code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
5970 found in macros such as this:
5979 @cvindex HAVE_TYPEOF
5981 If the C compiler supports GCC's @code{typeof} syntax, define
5982 @code{HAVE_TYPEOF}. If the support is available only via a different
5983 spelling of the keyword (e.g., @code{__typeof__}), define @code{typeof}
5987 @defmac AC_C_PROTOTYPES
5988 @acindex{C_PROTOTYPES}
5990 @cvindex __PROTOTYPES
5992 If function prototypes are understood by the compiler (as determined by
5993 @code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}.
5994 In the case the compiler does not handle
5995 prototypes, you should use @code{ansi2knr}, which comes with the
5996 Automake distribution, to unprotoize function definitions. For
5997 function prototypes, you should first define @code{PARAMS}:
6002 # define PARAMS(protos) protos
6003 # else /* no PROTOTYPES */
6004 # define PARAMS(protos) ()
6005 # endif /* no PROTOTYPES */
6010 then use it this way:
6013 size_t my_strlen PARAMS ((const char *));
6017 This macro also defines @code{__PROTOTYPES}; this is for the benefit of
6018 header files that cannot use macros that infringe on user name space.
6020 @defmac AC_PROG_GCC_TRADITIONAL
6021 @acindex{PROG_GCC_TRADITIONAL}
6023 Add @option{-traditional} to output variable @code{CC} if using the
6024 @acronym{GNU} C compiler and @code{ioctl} does not work properly without
6025 @option{-traditional}. That usually happens when the fixed header files
6026 have not been installed on an old system. Since recent versions of the
6027 @acronym{GNU} C compiler fix the header files automatically when installed,
6028 this is becoming a less prevalent problem.
6033 @subsection C++ Compiler Characteristics
6036 @defmac AC_PROG_CXX (@ovar{compiler-search-list})
6040 Determine a C++ compiler to use. Check whether the environment variable
6041 @code{CXX} or @code{CCC} (in that order) is set; if so, then set output
6042 variable @code{CXX} to its value.
6044 Otherwise, if the macro is invoked without an argument, then search for
6045 a C++ compiler under the likely names (first @code{g++} and @code{c++}
6046 then other names). If none of those checks succeed, then as a last
6047 resort set @code{CXX} to @code{g++}.
6049 This macro may, however, be invoked with an optional first argument
6050 which, if specified, must be a blank-separated list of C++ compilers to
6051 search for. This just gives the user an opportunity to specify an
6052 alternative search list for the C++ compiler. For example, if you
6053 didn't like the default order, then you could invoke @code{AC_PROG_CXX}
6057 AC_PROG_CXX([cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc])
6060 If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to
6061 @samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
6062 it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on
6063 systems where G++ does not accept @option{-g}), or @option{-g} for other
6067 @defmac AC_PROG_CXXCPP
6068 @acindex{PROG_CXXCPP}
6070 Set output variable @code{CXXCPP} to a command that runs the C++
6071 preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
6072 It is portable to run @code{CXXCPP} only on files with a @file{.c},
6073 @file{.C}, @file{.cc}, or @file{.cpp} extension.
6075 Some preprocessors don't indicate missing include files by the error
6076 status. For such preprocessors an internal variable is set that causes
6077 other macros to check the standard error from the preprocessor and
6078 consider the test failed if any warnings have been reported. However,
6079 it is not known whether such broken preprocessors exist for C++.
6084 @node Fortran Compiler
6085 @subsection Fortran Compiler Characteristics
6089 The Autoconf Fortran support is divided into two categories: legacy
6090 Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}).
6091 The former are intended for traditional Fortran 77 code, and have output
6092 variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter
6093 are for newer programs that can (or must) compile under the newer
6094 Fortran standards, and have output variables like @code{FC},
6095 @code{FCFLAGS}, and @code{FCLIBS}.
6097 Except for two new macros @code{AC_FC_SRCEXT} and
6098 @code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros
6099 behave almost identically, and so they are documented together in this
6103 @defmac AC_PROG_F77 (@ovar{compiler-search-list})
6107 Determine a Fortran 77 compiler to use. If @code{F77} is not already
6108 set in the environment, then check for @code{g77} and @code{f77}, and
6109 then some other names. Set the output variable @code{F77} to the name
6110 of the compiler found.
6112 This macro may, however, be invoked with an optional first argument
6113 which, if specified, must be a blank-separated list of Fortran 77
6114 compilers to search for. This just gives the user an opportunity to
6115 specify an alternative search list for the Fortran 77 compiler. For
6116 example, if you didn't like the default order, then you could invoke
6117 @code{AC_PROG_F77} like this:
6120 AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90])
6123 If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then
6124 @code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
6125 If the output variable @code{FFLAGS} was not already set in the
6126 environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
6127 where @code{g77} does not accept @option{-g}). Otherwise, set
6128 @code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
6131 @defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect})
6135 Determine a Fortran compiler to use. If @code{FC} is not already set in
6136 the environment, then @code{dialect} is a hint to indicate what Fortran
6137 dialect to search for; the default is to search for the newest available
6138 dialect. Set the output variable @code{FC} to the name of the compiler
6141 By default, newer dialects are preferred over older dialects, but if
6142 @code{dialect} is specified then older dialects are preferred starting
6143 with the specified dialect. @code{dialect} can currently be one of
6144 Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of
6145 which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}),
6146 and no attempt is made to guarantee that a particular language standard
6147 is actually supported. Thus, it is preferable that you avoid the
6148 @code{dialect} option, and use AC_PROG_FC only for code compatible with
6149 the latest Fortran standard.
6151 This macro may, alternatively, be invoked with an optional first argument
6152 which, if specified, must be a blank-separated list of Fortran
6153 compilers to search for, just as in @code{AC_PROG_F77}.
6155 If the output variable @code{FCFLAGS} was not already set in the
6156 environment, then set it to @option{-g -02} for GNU @code{g77} (or
6157 @option{-O2} where @code{g77} does not accept @option{-g}). Otherwise,
6158 set @code{FCFLAGS} to @option{-g} for all other Fortran compilers.
6161 @defmac AC_PROG_F77_C_O
6162 @defmacx AC_PROG_FC_C_O
6163 @acindex{PROG_F77_C_O}
6164 @acindex{PROG_FC_C_O}
6165 @cvindex F77_NO_MINUS_C_MINUS_O
6166 @cvindex FC_NO_MINUS_C_MINUS_O
6167 Test whether the Fortran compiler accepts the options @option{-c} and
6168 @option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or
6169 @code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not.
6172 The following macros check for Fortran compiler characteristics.
6173 To check for characteristics not listed here, use
6174 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or
6175 @code{AC_RUN_IFELSE} (@pxref{Run Time}), making sure to first set the
6176 current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])}
6177 or @code{AC_LANG(Fortran)} (@pxref{Language Choice}).
6180 @defmac AC_F77_LIBRARY_LDFLAGS
6181 @defmacx AC_FC_LIBRARY_LDFLAGS
6182 @acindex{F77_LIBRARY_LDFLAGS}
6184 @acindex{FC_LIBRARY_LDFLAGS}
6186 Determine the linker flags (e.g., @option{-L} and @option{-l}) for the
6187 @dfn{Fortran intrinsic and run-time libraries} that are required to
6188 successfully link a Fortran program or shared library. The output
6189 variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which
6190 should be include after @code{LIBS} when linking).
6192 This macro is intended to be used in those situations when it is
6193 necessary to mix, e.g., C++ and Fortran source code in a single
6194 program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
6195 automake, @acronym{GNU} Automake}).
6197 For example, if object files from a C++ and Fortran compiler must be
6198 linked together, then the C++ compiler/linker must be used for linking
6199 (since special C++-ish things need to happen at link time like calling
6200 global constructors, instantiating templates, enabling exception
6203 However, the Fortran intrinsic and run-time libraries must be linked in
6204 as well, but the C++ compiler/linker doesn't know by default how to add
6205 these Fortran 77 libraries. Hence, this macro was created to determine
6206 these Fortran libraries.
6208 The macros @code{AC_F77_DUMMY_MAIN}/@code{AC_FC_DUMMY_MAIN} or
6209 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} will probably also be necessary to
6210 link C/C++ with Fortran; see below.
6213 @defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6214 @defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
6215 @acindex{F77_DUMMY_MAIN}
6216 @cvindex F77_DUMMY_MAIN
6217 With many compilers, the Fortran libraries detected by
6218 @code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide
6219 their own @code{main} entry function that initializes things like
6220 Fortran I/O, and which then calls a user-provided entry function named
6221 (say) @code{MAIN__} to run the user's program. The
6222 @code{AC_F77_DUMMY_MAIN}/@code{AC_FC_DUMMY_MAIN} or
6223 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro figures out how to deal with
6226 When using Fortran for purely numerical functions (no I/O, etc.)@: often
6227 one prefers to provide one's own @code{main} and skip the Fortran
6228 library initializations. In this case, however, one may still need to
6229 provide a dummy @code{MAIN__} routine in order to prevent linking errors
6230 on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN}
6231 detects whether any such routine is @emph{required} for linking, and
6232 what its name is; the shell variable @code{F77_DUMMY_MAIN} or
6233 @code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution
6234 was found, and @code{none} when no such dummy main is needed.
6236 By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or
6237 @code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__})
6238 @emph{if} it is required. @ovar{action-if-not-found} defaults to
6239 exiting with an error.
6241 In order to link with Fortran routines, the user's C/C++ program should
6242 then include the following code to define the dummy main if it is
6246 #ifdef F77_DUMMY_MAIN
6250 int F77_DUMMY_MAIN() @{ return 1; @}
6254 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6256 Note that this macro is called automatically from @code{AC_F77_WRAPPERS}
6257 or @code{AC_FC_WRAPPERS}; there is generally no need to call it
6258 explicitly unless one wants to change the default actions.
6267 As discussed above, many Fortran libraries allow you to provide an entry
6268 point called (say) @code{MAIN__} instead of the usual @code{main}, which
6269 is then called by a @code{main} function in the Fortran libraries that
6270 initializes things like Fortran I/O@. The
6271 @code{AC_F77_MAIN}/@code{AC_FC_MAIN} macro detects whether it is
6272 @emph{possible} to utilize such an alternate main function, and defines
6273 @code{F77_MAIN}/@code{FC_MAIN} to the name of the function. (If no
6274 alternate main function name is found, @code{F77_MAIN}/@code{FC_MAIN} is
6275 simply defined to @code{main}.)
6277 Thus, when calling Fortran routines from C that perform things like I/O,
6278 one should use this macro and name the "main" function
6279 @code{F77_MAIN}/@code{FC_MAIN} instead of @code{main}.
6282 @defmac AC_F77_WRAPPERS
6283 @defmacx AC_FC_WRAPPERS
6284 @acindex{F77_WRAPPERS}
6287 @acindex{FC_WRAPPERS}
6290 Defines C macros @code{F77_FUNC(name,NAME)}/@code{FC_FUNC(name,NAME)}
6291 and @code{F77_FUNC_(name,NAME)}/@code{FC_FUNC_(name,NAME)} to properly
6292 mangle the names of C/C++ identifiers, and identifiers with underscores,
6293 respectively, so that they match the name-mangling scheme used by the
6296 Fortran is case-insensitive, and in order to achieve this the Fortran
6297 compiler converts all identifiers into a canonical case and format. To
6298 call a Fortran subroutine from C or to write a C function that is
6299 callable from Fortran, the C program must explicitly use identifiers in
6300 the format expected by the Fortran compiler. In order to do this, one
6301 simply wraps all C identifiers in one of the macros provided by
6302 @code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose
6303 you have the following Fortran 77 subroutine:
6306 subroutine foobar(x,y)
6307 double precision x, y
6313 You would then declare its prototype in C or C++ as:
6316 #define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
6318 extern "C" /* prevent C++ name mangling */
6320 void FOOBAR_F77(double *x, double *y);
6323 Note that we pass both the lowercase and uppercase versions of the
6324 function name to @code{F77_FUNC} so that it can select the right one.
6325 Note also that all parameters to Fortran 77 routines are passed as
6326 pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, @acronym{GNU}
6329 (Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.)
6331 Although Autoconf tries to be intelligent about detecting the
6332 name-mangling scheme of the Fortran compiler, there may be Fortran
6333 compilers that it doesn't support yet. In this case, the above code
6334 will generate a compile-time error, but some other behavior
6335 (e.g., disabling Fortran-related features) can be induced by checking
6336 whether the @code{F77_FUNC}/@code{FC_FUNC} macro is defined.
6338 Now, to call that routine from a C program, we would do something like:
6342 double x = 2.7183, y;
6347 If the Fortran identifier contains an underscore (e.g., @code{foo_bar}),
6348 you should use @code{F77_FUNC_}/@code{FC_FUNC_} instead of
6349 @code{F77_FUNC}/@code{FC_FUNC} (with the same arguments). This is
6350 because some Fortran compilers mangle names differently if they contain
6354 @defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
6355 @defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar})
6358 Given an identifier @var{name}, set the shell variable @var{shellvar} to
6359 hold the mangled version @var{name} according to the rules of the
6360 Fortran linker (see also @code{AC_F77_WRAPPERS} or
6361 @code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not
6362 supplied, the shell variable will be simply @var{name}. The purpose of
6363 this macro is to give the caller a way to access the name-mangling
6364 information other than through the C preprocessor as above, for example,
6365 to call Fortran routines from some language other than C/C++.
6368 @defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure})
6370 By default, the @code{FC} macros perform their tests using a @file{.f}
6371 extension for source-code files. Some compilers, however, only enable
6372 newer language features for appropriately named files, e.g., Fortran 90
6373 features only for @file{.f90} files. On the other hand, some other
6374 compilers expect all source files to end in @file{.f} and require
6375 special flags to support other file name extensions. The
6376 @code{AC_FC_SRCEXT} macro deals with both of these issues.
6378 The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files
6379 ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not}
6380 contain the dot). If any special compiler flags are needed for this, it
6381 stores them in the output variable @code{FCFLAGS_}@var{ext}. This
6382 extension and these flags are then used for all subsequent @code{FC} tests
6383 (until @code{AC_FC_SRCEXT} is called again).
6385 For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the
6386 @file{.f90} extension in future tests, and it would set a
6387 @code{FCFLAGS_f90} output variable with any extra flags that are needed
6388 to compile such files.
6390 The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into
6391 @code{FCFLAGS}, for two reasons based on the limitations of some
6392 compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a
6393 time, so files with different extensions must be compiled separately.
6394 Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before
6395 the source-code file name when compiling. So, continuing the example
6396 above, you might compile a @file{foo.f90} file in your Makefile with the
6401 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) foo.f90
6404 If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext}
6405 extension, it calls @ovar{action-if-success} (defaults to nothing). If
6406 it fails, and cannot find a way to make the @code{FC} compiler accept such
6407 files, it calls @ovar{action-if-failure} (defaults to exiting with an
6412 @defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure})
6413 @acindex{FC_FREEFORM}
6415 The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler
6416 (@code{$FC}) allows free-format source code (as opposed to the older
6417 fixed-format style from Fortran 77). If necessary, it may add some
6418 additional flags to @code{FCFLAGS}.
6420 This macro is most important if you are using the default @file{.f}
6421 extension, since many compilers interpret this extension as indicating
6422 fixed-format source unless an additional flag is supplied. If you
6423 specify a different extension with @code{AC_FC_SRCEXT}, such as
6424 @file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} will ordinarily
6425 succeed without modifying @code{FCFLAGS}.
6427 If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it
6428 calls @ovar{action-if-success} (defaults to nothing). If it fails, it
6429 calls @ovar{action-if-failure} (defaults to exiting with an error
6433 @node System Services
6434 @section System Services
6436 The following macros check for operating system services or capabilities.
6440 @cindex X Window System
6441 Try to locate the X Window System include files and libraries. If the
6442 user gave the command line options @option{--x-includes=@var{dir}} and
6443 @option{--x-libraries=@var{dir}}, use those directories. If either or
6444 both were not given, get the missing values by running @code{xmkmf} on a
6445 trivial @file{Imakefile} and examining the @file{Makefile} that it
6446 produces. If that fails (such as if @code{xmkmf} is not present), look
6447 for the files in several directories where they often reside. If either
6448 method is successful, set the shell variables @code{x_includes} and
6449 @code{x_libraries} to their locations, unless they are in directories
6450 the compiler searches by default.
6452 If both methods fail, or the user gave the command line option
6453 @option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
6454 otherwise set it to the empty string.
6457 @defmac AC_PATH_XTRA
6461 @ovindex X_EXTRA_LIBS
6463 @cvindex X_DISPLAY_MISSING
6464 An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
6465 that X needs to output variable @code{X_CFLAGS}, and the X linker flags
6466 to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
6469 This macro also checks for special libraries that some systems need in
6470 order to compile X programs. It adds any that the system needs to
6471 output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
6472 libraries that need to be linked with before @option{-lX11}, and adds
6473 any found to the output variable @code{X_PRE_LIBS}.
6475 @c This is an incomplete kludge. Make a real way to do it.
6476 @c If you need to check for other X functions or libraries yourself, then
6477 @c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
6478 @c @code{LIBS} temporarily, like this: (FIXME - add example)
6481 @defmac AC_SYS_INTERPRETER
6482 @acindex{SYS_INTERPRETER}
6483 Check whether the system supports starting scripts with a line of the
6484 form @samp{#!/bin/sh} to select the interpreter to use for the script.
6485 After running this macro, shell code in @file{configure.ac} can check
6486 the shell variable @code{interpval}; it will be set to @samp{yes}
6487 if the system supports @samp{#!}, @samp{no} if not.
6490 @defmac AC_SYS_LARGEFILE
6491 @acindex{SYS_LARGEFILE}
6492 @cvindex _FILE_OFFSET_BITS
6493 @cvindex _LARGE_FILES
6495 @cindex Large file support
6498 @uref{http://www.unix-systems.org/version2/whatsnew/lfs20mar.html,
6499 large-file support}. On some hosts, one must use special compiler
6500 options to build programs that can access large files. Append any such
6501 options to the output variable @code{CC}. Define
6502 @code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
6504 Large-file support can be disabled by configuring with the
6505 @option{--disable-largefile} option.
6507 If you use this macro, check that your program works even when
6508 @code{off_t} is wider than @code{long int}, since this is common when
6509 large-file support is enabled. For example, it is not correct to print
6510 an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
6513 The LFS introduced the @code{fseeko} and @code{ftello} functions to
6514 replace their C counterparts @code{fseek} and @code{ftell} that do not
6515 use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their
6516 prototypes available when using them and large-file support is
6520 @defmac AC_SYS_LONG_FILE_NAMES
6521 @acindex{SYS_LONG_FILE_NAMES}
6522 @cvindex HAVE_LONG_FILE_NAMES
6523 If the system supports file names longer than 14 characters, define
6524 @code{HAVE_LONG_FILE_NAMES}.
6527 @defmac AC_SYS_POSIX_TERMIOS
6528 @acindex{SYS_POSIX_TERMIOS}
6529 @cindex Posix termios headers
6530 @cindex termios Posix headers
6531 Check to see if the Posix termios headers and functions are available on the
6532 system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to
6533 @samp{yes}. If not, set the variable to @samp{no}.
6536 @node Posix Variants
6537 @section Posix Variants
6539 The following macros check for certain operating systems that need
6540 special treatment for some programs, due to exceptional oddities in
6541 their header files or libraries. These macros are warts; they will be
6542 replaced by a more systematic approach, based on the functions they make
6543 available or the environments they provide.
6547 @cvindex _ALL_SOURCE
6548 If on @acronym{AIX}, define @code{_ALL_SOURCE}. Allows the use of some @acronym{BSD}
6549 functions. Should be called before any macros that run the C compiler.
6552 @defmac AC_GNU_SOURCE
6553 @acindex{GNU_SOURCE}
6554 @cvindex _GNU_SOURCE
6555 If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}.
6556 Allows the use of some @acronym{GNU} functions. Should be called
6557 before any macros that run the C compiler.
6560 @defmac AC_ISC_POSIX
6563 For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output
6564 variable @code{LIBS} if necessary for Posix facilities. Call this
6565 after @code{AC_PROG_CC} and before any other macros that use Posix
6566 interfaces. @sc{interactive} Unix is no longer sold, and Sun says that
6567 they will drop support for it on 2006-07-23, so this macro is becoming
6574 @cvindex _POSIX_SOURCE
6575 @cvindex _POSIX_1_SOURCE
6576 If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
6577 @code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix
6578 facilities. Should be called before any macros that run the C compiler.
6584 @c ========================================================= Writing Tests
6587 @chapter Writing Tests
6589 If the existing feature tests don't do something you need, you have to
6590 write new ones. These macros are the building blocks. They provide
6591 ways for other macros to check whether various kinds of features are
6592 available and report the results.
6594 This chapter contains some suggestions and some of the reasons why the
6595 existing tests are written the way they are. You can also learn a lot
6596 about how to write Autoconf tests by looking at the existing ones. If
6597 something goes wrong in one or more of the Autoconf tests, this
6598 information can help you understand the assumptions behind them, which
6599 might help you figure out how to best solve the problem.
6601 These macros check the output of the compiler system of the current
6602 language (@pxref{Language Choice}). They do not cache the results of
6603 their tests for future use (@pxref{Caching Results}), because they don't
6604 know enough about the information they are checking for to generate a
6605 cache variable name. They also do not print any messages, for the same
6606 reason. The checks for particular kinds of features call these macros
6607 and do cache their results and print messages about what they're
6610 When you write a feature test that could be applicable to more than one
6611 software package, the best thing to do is encapsulate it in a new macro.
6612 @xref{Writing Autoconf Macros}, for how to do that.
6615 * Language Choice:: Selecting which language to use for testing
6616 * Writing Test Programs:: Forging source files for compilers
6617 * Running the Preprocessor:: Detecting preprocessor symbols
6618 * Running the Compiler:: Detecting language or header features
6619 * Running the Linker:: Detecting library features
6620 * Run Time:: Testing for run-time features
6621 * Systemology:: A zoology of operating systems
6622 * Multiple Cases:: Tests for several possible values
6625 @node Language Choice
6626 @section Language Choice
6629 Autoconf-generated @command{configure} scripts check for the C compiler and
6630 its features by default. Packages that use other programming languages
6631 (maybe more than one, e.g., C and C++) need to test features of the
6632 compilers for the respective languages. The following macros determine
6633 which programming language is used in the subsequent tests in
6634 @file{configure.ac}.
6636 @defmac AC_LANG (@var{language})
6637 Do compilation tests using the compiler, preprocessor, and file
6638 extensions for the specified @var{language}.
6640 Supported languages are:
6644 Do compilation tests using @code{CC} and @code{CPP} and use extension
6645 @file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with
6646 @code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}.
6649 Do compilation tests using @code{CXX} and @code{CXXCPP} and use
6650 extension @file{.C} for test programs. Use compilation flags:
6651 @code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and
6652 @code{CXXFLAGS} with @code{CXX}.
6655 Do compilation tests using @code{F77} and use extension @file{.f} for
6656 test programs. Use compilation flags: @code{FFLAGS}.
6659 Do compilation tests using @code{FC} and use extension @file{.f} (or
6660 whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use
6661 compilation flags: @code{FCFLAGS}.
6665 @defmac AC_LANG_PUSH (@var{language})
6667 Remember the current language (as set by @code{AC_LANG}) on a stack, and
6668 then select the @var{language}. Use this macro and @code{AC_LANG_POP}
6669 in macros that need to temporarily switch to a particular language.
6672 @defmac AC_LANG_POP (@ovar{language})
6674 Select the language that is saved on the top of the stack, as set by
6675 @code{AC_LANG_PUSH}, and remove it from the stack.
6677 If given, @var{language} specifies the language we just @emph{quit}. It
6678 is a good idea to specify it when it's known (which should be the
6679 case@dots{}), since Autoconf will detect inconsistencies.
6682 AC_LANG_PUSH([Fortran 77])
6683 # Perform some tests on Fortran 77.
6685 AC_LANG_POP([Fortran 77])
6689 @defmac AC_LANG_ASSERT (@var{language})
6690 @acindex{LANG_ASSERT} Check statically that the current language is
6691 @var{language}. You should use this in your language specific macros
6692 to avoid that they be called with an inappropriate language.
6694 This macro runs only at @command{autoconf} time, and incurs no cost at
6695 @command{configure} time. Sadly enough and because Autoconf is a two
6696 layer language @footnote{Because M4 is not aware of Sh code,
6697 especially conditionals, some optimizations that look nice statically
6698 may produce incorrect results at runtime.}, the macros
6699 @code{AC_LANG_PUSH}/@code{AC_LANG_POP} cannot be ``optimizing'',
6700 therefore as much as possible you ought to avoid using them to wrap
6701 your code, rather, require from the user to run the macro with a
6702 correct current language, and check it with @code{AC_LANG_ASSERT}.
6703 And anyway, that may help the user understand she is running a Fortran
6704 macro while expecting a result about her Fortran 77 compiler@dots{}
6708 @defmac AC_REQUIRE_CPP
6709 @acindex{REQUIRE_CPP}
6710 Ensure that whichever preprocessor would currently be used for tests has
6711 been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
6712 argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
6713 depending on which language is current.
6717 @node Writing Test Programs
6718 @section Writing Test Programs
6720 Autoconf tests follow is common scheme: feeding some program with some
6721 input, and most of the time, feeding a compiler with some source file.
6722 This section is dedicated to these source samples.
6725 * Guidelines:: General rules for writing test programs
6726 * Test Functions:: Avoiding pitfalls in test programs
6727 * Generating Sources:: Source program boilerplate
6731 @subsection Guidelines for Test Programs
6733 The most important rule to follow when writing testing samples is:
6735 @center @emph{Look for realism.}
6737 This motto means that testing samples must be written with the same
6738 strictness as real programs are written. In particular, you should
6739 avoid ``shortcuts'' and simplifications.
6741 Don't just play with the preprocessor if you want to prepare a
6742 compilation. For instance, using @command{cpp} to check whether a header is
6743 functional might let your @command{configure} accept a header which will
6744 cause some @emph{compiler} error. Do not hesitate checking header with
6745 other headers included before, especially required headers.
6747 Make sure the symbols you use are properly defined, i.e., refrain for
6748 simply declaring a function yourself instead of including the proper
6751 Test programs should not write anything to the standard output. They
6752 should return 0 if the test succeeds, nonzero otherwise, so that success
6753 can be distinguished easily from a core dump or other failure;
6754 segmentation violations and other failures produce a nonzero exit
6755 status. Test programs should @code{exit}, not @code{return}, from
6756 @code{main}, because on some systems (old Suns, at least) the argument
6757 to @code{return} in @code{main} is ignored.
6759 Test programs can use @code{#if} or @code{#ifdef} to check the values of
6760 preprocessor macros defined by tests that have already run. For
6761 example, if you call @code{AC_HEADER_STDC}, then later on in
6762 @file{configure.ac} you can have a test program that includes an
6763 @acronym{ANSI} C header file conditionally:
6768 # include <stdlib.h>
6773 If a test program needs to use or create a data file, give it a name
6774 that starts with @file{conftest}, such as @file{conftest.data}. The
6775 @command{configure} script cleans up by running @samp{rm -f -r conftest*}
6776 after running test programs and if the script is interrupted.
6778 @node Test Functions
6779 @subsection Test Functions
6781 Function declarations in test programs should have a prototype
6782 conditionalized for C++. In practice, though, test programs rarely need
6783 functions that take arguments.
6793 Functions that test programs declare should also be conditionalized for
6794 C++, which requires @samp{extern "C"} prototypes. Make sure to not
6795 include any header files containing clashing prototypes.
6799 extern "C" void *malloc (size_t);
6805 If a test program calls a function with invalid parameters (just to see
6806 whether it exists), organize the program to ensure that it never invokes
6807 that function. You can do this by calling it in another function that is
6808 never invoked. You can't do it by putting it after a call to
6809 @code{exit}, because GCC version 2 knows that @code{exit} never returns
6810 and optimizes out any code that follows it in the same block.
6812 If you include any header files, be sure to call the functions
6813 relevant to them with the correct number of arguments, even if they are
6814 just 0, to avoid compilation errors due to prototypes. GCC version 2
6815 has internal prototypes for several functions that it automatically
6816 inlines; for example, @code{memcpy}. To avoid errors when checking for
6817 them, either pass them the correct number of arguments or redeclare them
6818 with a different return type (such as @code{char}).
6821 @node Generating Sources
6822 @subsection Generating Sources
6824 Autoconf provides a set of macros that can be used to generate test
6825 source files. They are written to be language generic, i.e., they
6826 actually depend on the current language (@pxref{Language Choice}) to
6827 ``format'' the output properly.
6830 @defmac AC_LANG_CONFTEST (@var{source})
6831 @acindex{LANG_CONFTEST}
6832 Save the @var{source} text in the current test source file:
6833 @file{conftest.@var{extension}} where the @var{extension} depends on the
6836 Note that the @var{source} is evaluated exactly once, like regular
6837 Autoconf macro arguments, and therefore (i) you may pass a macro
6838 invocation, (ii) if not, be sure to double quote if needed.
6841 @defmac AC_LANG_SOURCE (@var{source})
6842 @acindex{LANG_SOURCE}
6843 Expands into the @var{source}, with the definition of
6844 all the @code{AC_DEFINE} performed so far.
6847 For instance executing (observe the double quotation!):
6850 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
6851 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
6852 [Greetings string.])
6854 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])])
6855 gcc -E -dD -o - conftest.c
6865 #define PACKAGE_NAME "Hello"
6866 #define PACKAGE_TARNAME "hello"
6867 #define PACKAGE_VERSION "1.0"
6868 #define PACKAGE_STRING "Hello 1.0"
6869 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
6870 #define HELLO_WORLD "Hello, World\n"
6872 const char hw[] = "Hello, World\n";
6875 @defmac AC_LANG_PROGRAM (@var{prologue}, @var{body})
6876 @acindex{LANG_PROGRAM}
6877 Expands into a source file which consists of the @var{prologue}, and
6878 then @var{body} as body of the main function (e.g., @code{main} in
6879 C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are
6886 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
6887 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
6888 [Greetings string.])
6890 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
6891 [[fputs (hw, stdout);]])])
6892 gcc -E -dD -o - conftest.c
6902 #define PACKAGE_NAME "Hello"
6903 #define PACKAGE_TARNAME "hello"
6904 #define PACKAGE_VERSION "1.0"
6905 #define PACKAGE_STRING "Hello 1.0"
6906 #define PACKAGE_BUGREPORT "bug-hello@@example.org"
6907 #define HELLO_WORLD "Hello, World\n"
6909 const char hw[] = "Hello, World\n";
6920 @defmac AC_LANG_CALL (@var{prologue}, @var{function})
6922 Expands into a source file which consists of the @var{prologue}, and
6923 then a call to the @var{function} as body of the main function (e.g.,
6924 @code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature
6925 of the latter are available.
6927 This function will probably be replaced in the future by a version
6928 which would enable specifying the arguments. The use of this macro is
6929 not encouraged, as it violates strongly the typing system.
6933 @defmac AC_LANG_FUNC_LINK_TRY (@var{function})
6934 @acindex{LANG_FUNC_LINK_TRY}
6935 Expands into a source file which uses the @var{function} in the body of
6936 the main function (e.g., @code{main} in C). Since it uses
6937 @code{AC_LANG_PROGRAM}, the features of the latter are available.
6939 As @code{AC_LANG_CALL}, this macro is documented only for completeness.
6940 It is considered to be severely broken, and in the future will be
6941 removed in favor of actual function calls (with properly typed
6945 @node Running the Preprocessor
6946 @section Running the Preprocessor
6948 Sometimes one might need to run the preprocessor on some source file.
6949 @emph{Usually it is a bad idea}, as you typically need to @emph{compile}
6950 your project, not merely run the preprocessor on it; therefore you
6951 certainly want to run the compiler, not the preprocessor. Resist the
6952 temptation of following the easiest path.
6954 Nevertheless, if you need to run the preprocessor, then use
6955 @code{AC_PREPROC_IFELSE}.
6957 @defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
6958 @acindex{PREPROC_IFELSE}
6959 Run the preprocessor of the current language (@pxref{Language Choice})
6960 on the @var{input}, run the shell commands @var{action-if-true} on
6961 success, @var{action-if-false} otherwise. The @var{input} can be made
6962 by @code{AC_LANG_PROGRAM} and friends.
6964 This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
6965 @option{-g}, @option{-O}, etc.@: are not valid options to many C
6968 It is customary to report unexpected failures with
6969 @code{AC_MSG_FAILURE}.
6975 AC_INIT([Hello], [1.0], [bug-hello@@example.org])
6976 AC_DEFINE([HELLO_WORLD], ["Hello, World\n"],
6977 [Greetings string.])
6979 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]],
6980 [[fputs (hw, stdout);]])],
6981 [AC_MSG_RESULT([OK])],
6982 [AC_MSG_FAILURE([unexpected preprocessor failure])])
6989 checking for gcc... gcc
6990 checking for C compiler default output file name... a.out
6991 checking whether the C compiler works... yes
6992 checking whether we are cross compiling... no
6993 checking for suffix of executables...
6994 checking for suffix of object files... o
6995 checking whether we are using the GNU C compiler... yes
6996 checking whether gcc accepts -g... yes
6997 checking for gcc option to accept ISO C89... none needed
6998 checking how to run the C preprocessor... gcc -E
7004 The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the
7005 role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making
7006 it impossible to use it to elaborate sources. You are encouraged to
7007 get rid of your old use of the macro @code{AC_TRY_CPP} in favor of
7008 @code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need
7009 to run the @emph{preprocessor} and not the compiler?
7011 @defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
7012 @acindex{EGREP_HEADER}
7013 If the output of running the preprocessor on the system header file
7014 @var{header-file} matches the extended regular expression
7015 @var{pattern}, execute shell commands @var{action-if-found}, otherwise
7016 execute @var{action-if-not-found}.
7019 @defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
7021 @var{program} is the text of a C or C++ program, on which shell
7022 variable, back quote, and backslash substitutions are performed. If the
7023 output of running the preprocessor on @var{program} matches the
7024 extended regular expression @var{pattern}, execute shell commands
7025 @var{action-if-found}, otherwise execute @var{action-if-not-found}.
7030 @node Running the Compiler
7031 @section Running the Compiler
7033 To check for a syntax feature of the current language's (@pxref{Language
7034 Choice}) compiler, such as whether it recognizes a certain keyword, or
7035 simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try
7036 to compile a small program that uses that feature.
7038 @defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
7039 @acindex{COMPILE_IFELSE}
7040 Run the compiler and compilation flags of the current language
7041 (@pxref{Language Choice}) on the @var{input}, run the shell commands
7042 @var{action-if-true} on success, @var{action-if-false} otherwise. The
7043 @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7045 It is customary to report unexpected failures with
7046 @code{AC_MSG_FAILURE}. This macro does not try to link; use
7047 @code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the
7051 @node Running the Linker
7052 @section Running the Linker
7054 To check for a library, a function, or a global variable, Autoconf
7055 @command{configure} scripts try to compile and link a small program that
7056 uses it. This is unlike Metaconfig, which by default uses @code{nm} or
7057 @code{ar} on the C library to try to figure out which functions are
7058 available. Trying to link with the function is usually a more reliable
7059 approach because it avoids dealing with the variations in the options
7060 and output formats of @code{nm} and @code{ar} and in the location of the
7061 standard libraries. It also allows configuring for cross-compilation or
7062 checking a function's run-time behavior if needed. On the other hand,
7063 it can be slower than scanning the libraries once, but accuracy is more
7064 important than speed.
7066 @code{AC_LINK_IFELSE} is used to compile test programs to test for
7067 functions and global variables. It is also used by @code{AC_CHECK_LIB}
7068 to check for libraries (@pxref{Libraries}), by adding the library being
7069 checked for to @code{LIBS} temporarily and trying to link a small
7073 @defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found})
7074 @acindex{LINK_IFELSE}
7075 Run the compiler (and compilation flags) and the linker of the current
7076 language (@pxref{Language Choice}) on the @var{input}, run the shell
7077 commands @var{action-if-true} on success, @var{action-if-false}
7078 otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and
7081 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7082 current compilation flags.
7084 It is customary to report unexpected failures with
7085 @code{AC_MSG_FAILURE}. This macro does not try to execute the program;
7086 use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Run Time}).
7092 @section Checking Run Time Behavior
7094 Sometimes you need to find out how a system performs at run time, such
7095 as whether a given function has a certain capability or bug. If you
7096 can, make such checks when your program runs instead of when it is
7097 configured. You can check for things like the machine's endianness when
7098 your program initializes itself.
7100 If you really need to test for a run-time behavior while configuring,
7101 you can write a test program to determine the result, and compile and
7102 run it using @code{AC_RUN_IFELSE}. Avoid running test programs if
7103 possible, because this prevents people from configuring your package for
7106 @defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{action-if-cross-compiling})
7107 @acindex{RUN_IFELSE}
7108 If @var{program} compiles and links successfully and returns an exit
7109 status of 0 when executed, run shell commands @var{action-if-true}.
7110 Otherwise, run shell commands @var{action-if-false}.
7112 The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends.
7113 @code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the
7114 compilation flags of the current language (@pxref{Language Choice}).
7116 If the compiler being used does not produce executables that run on the
7117 system where @command{configure} is being run, then the test program is
7118 not run. If the optional shell commands @var{action-if-cross-compiling}
7119 are given, they are run instead. Otherwise, @command{configure} prints
7120 an error message and exits.
7122 In the @var{action-if-false} section, the exit status of the program is
7123 available in the shell variable @samp{$?}, but be very careful to limit
7124 yourself to positive values smaller than 127; bigger values should be
7125 saved into a file by the @var{program}. Note also that you have simply
7126 no guarantee that this exit status is issued by the @var{program}, or by
7127 the failure of its compilation. In other words, use this feature if
7128 sadist only, it was reestablished because the Autoconf maintainers grew
7129 tired of receiving ``bug reports''.
7131 It is customary to report unexpected failures with
7132 @code{AC_MSG_FAILURE}.
7135 Try to provide a pessimistic default value to use when cross-compiling
7136 makes run-time tests impossible. You do this by passing the optional
7137 last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a
7138 warning message when creating @command{configure} each time it
7139 encounters a call to @code{AC_RUN_IFELSE} with no
7140 @var{action-if-cross-compiling} argument given. You may ignore the
7141 warning, though users will not be able to configure your package for
7142 cross-compiling. A few of the macros distributed with Autoconf produce
7143 this warning message.
7145 To configure for cross-compiling you can also choose a value for those
7146 parameters based on the canonical system name (@pxref{Manual
7147 Configuration}). Alternatively, set up a test results cache file with
7148 the correct values for the host system (@pxref{Caching Results}).
7150 @ovindex cross_compiling
7151 To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded
7152 in other macros, including a few of the ones that come with Autoconf,
7153 you can test whether the shell variable @code{cross_compiling} is set to
7154 @samp{yes}, and then use an alternate method to get the results instead
7155 of calling the macros.
7159 @section Systemology
7162 This section aims at presenting some systems and pointers to
7163 documentation. It may help you addressing particular problems reported
7166 The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix}
7167 contains a lot of interesting crossed information on various
7168 Posix-conforming systems.
7173 Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be
7174 case-preserving, but case insensitive. This can cause nasty problems,
7175 since for instance the installation attempt for a package having an
7176 @file{INSTALL} file can result in @samp{make install} report that
7177 nothing was to be done!
7179 That's all dependent on whether the file system is a UFS (case
7180 sensitive) or HFS+ (case preserving). By default Apple wants you to
7181 install the OS on HFS+. Unfortunately, there are some pieces of
7182 software which really need to be built on UFS@. We may want to rebuild
7183 Darwin to have both UFS and HFS+ available (and put the /local/build
7186 @item @acronym{QNX} 4.25
7187 @cindex @acronym{QNX} 4.25
7188 @c FIXME: Please, if you feel like writing something more precise,
7189 @c it'd be great. In particular, I can't understand the difference with
7191 @acronym{QNX} is a realtime operating system running on Intel architecture
7192 meant to be scalable from the small embedded systems to the hundred
7193 processor super-computer. It claims to be Posix certified. More
7194 information is available on the
7195 @uref{http://www.qnx.com/, @acronym{QNX} home page}.
7199 @uref{http://h30097.www3.hp.com/docs/,
7200 Documentation of several versions of Tru64} is available in different
7203 @item Unix version 7
7204 @cindex Unix version 7
7206 Officially this was called the ``Seventh Edition'' of ``the @sc{unix}
7207 time-sharing system'' but we use the more-common name ``Unix version 7''.
7208 Documentation is available in the
7209 @uref{http://plan9.bell-labs.com/7thEdMan/, V7 Manual}.
7210 Previous versions of Unix are called ``Unix version 6'', etc., but
7211 they were not as widely used.
7215 @node Multiple Cases
7216 @section Multiple Cases
7218 Some operations are accomplished in several possible ways, depending on
7219 the OS variant. Checking for them essentially requires a ``case
7220 statement''. Autoconf does not directly provide one; however, it is
7221 easy to simulate by using a shell variable to keep track of whether a
7222 way to perform the operation has been found yet.
7224 Here is an example that uses the shell variable @code{fstype} to keep
7225 track of whether the remaining cases need to be checked.
7229 AC_MSG_CHECKING([how to get file system type])
7231 # The order of these tests is important.
7232 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h>
7233 #include <sys/fstyp.h>]])],
7234 [AC_DEFINE([FSTYPE_STATVFS], [1],
7235 [Define if statvfs exists.])
7237 if test $fstype = no; then
7238 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7239 #include <sys/fstyp.h>]])],
7240 [AC_DEFINE([FSTYPE_USG_STATFS], [1],
7241 [Define if USG statfs.])
7244 if test $fstype = no; then
7245 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h>
7246 #include <sys/vmount.h>]])]),
7247 [AC_DEFINE([FSTYPE_AIX_STATFS], [1],
7248 [Define if AIX statfs.])
7251 # (more cases omitted here)
7252 AC_MSG_RESULT([$fstype])
7256 @c ====================================================== Results of Tests.
7259 @chapter Results of Tests
7261 Once @command{configure} has determined whether a feature exists, what can
7262 it do to record that information? There are four sorts of things it can
7263 do: define a C preprocessor symbol, set a variable in the output files,
7264 save the result in a cache file for future @command{configure} runs, and
7265 print a message letting the user know the result of the test.
7268 * Defining Symbols:: Defining C preprocessor symbols
7269 * Setting Output Variables:: Replacing variables in output files
7270 * Caching Results:: Speeding up subsequent @command{configure} runs
7271 * Printing Messages:: Notifying @command{configure} users
7274 @node Defining Symbols
7275 @section Defining C Preprocessor Symbols
7277 A common action to take in response to a feature test is to define a C
7278 preprocessor symbol indicating the results of the test. That is done by
7279 calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
7281 By default, @code{AC_OUTPUT} places the symbols defined by these macros
7282 into the output variable @code{DEFS}, which contains an option
7283 @option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
7284 Autoconf version 1, there is no variable @code{DEFS} defined while
7285 @command{configure} is running. To check whether Autoconf macros have
7286 already defined a certain C preprocessor symbol, test the value of the
7287 appropriate cache variable, as in this example:
7290 AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1],
7291 [Define if vprintf exists.])])
7292 if test "$ac_cv_func_vprintf" != yes; then
7293 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1],
7294 [Define if _doprnt exists.])])
7298 If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
7299 @code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
7300 correct values into @code{#define} statements in a template file.
7301 @xref{Configuration Headers}, for more information about this kind of
7304 @defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description})
7305 @defmacx AC_DEFINE (@var{variable})
7307 Define the C preprocessor variable @var{variable} to @var{value} (verbatim).
7308 @var{value} should not contain literal newlines, and if you are not
7309 using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
7310 characters, as @command{make} tends to eat them. To use a shell variable,
7311 use @code{AC_DEFINE_UNQUOTED} instead.
7312 @var{description} is only useful if you are using
7313 @code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
7314 the generated @file{config.h.in} as the comment before the macro define.
7315 The following example defines the C preprocessor variable
7316 @code{EQUATION} to be the string constant @samp{"$a > $b"}:
7319 AC_DEFINE([EQUATION], ["$a > $b"],
7323 If neither @var{value} nor @var{description} are given, then
7324 @var{value} defaults to 1 instead of to the empty string. This is for
7325 backwards compatibility with older versions of Autoconf, but this usage
7326 is obsolescent and may be withdrawn in future versions of Autoconf.
7329 @defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description})
7330 @defmacx AC_DEFINE_UNQUOTED (@var{variable})
7331 @acindex{DEFINE_UNQUOTED}
7332 Like @code{AC_DEFINE}, but three shell expansions are
7333 performed---once---on @var{variable} and @var{value}: variable expansion
7334 (@samp{$}), command substitution (@samp{`}), and backslash escaping
7335 (@samp{\}). Single and double quote characters in the value have no
7336 special meaning. Use this macro instead of @code{AC_DEFINE} when
7337 @var{variable} or @var{value} is a shell variable. Examples:
7340 AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"],
7341 [Configuration machine file.])
7342 AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups],
7343 [getgroups return type.])
7344 AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1],
7345 [Translated header name.])
7349 Due to a syntactical bizarreness of the Bourne shell, do not use
7350 semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
7351 calls from other macro calls or shell code; that can cause syntax errors
7352 in the resulting @command{configure} script. Use either blanks or
7353 newlines. That is, do this:
7356 AC_CHECK_HEADER([elf.h],
7357 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"])
7364 AC_CHECK_HEADER([elf.h],
7365 [AC_DEFINE([SVR4], [1], [System V Release 4])
7366 LIBS="-lelf $LIBS"])
7373 AC_CHECK_HEADER([elf.h],
7374 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"])
7377 @node Setting Output Variables
7378 @section Setting Output Variables
7379 @cindex Output variables
7381 Another way to record the results of tests is to set @dfn{output
7382 variables}, which are shell variables whose values are substituted into
7383 files that @command{configure} outputs. The two macros below create new
7384 output variables. @xref{Preset Output Variables}, for a list of output
7385 variables that are always available.
7387 @defmac AC_SUBST (@var{variable}, @ovar{value})
7389 Create an output variable from a shell variable. Make @code{AC_OUTPUT}
7390 substitute the variable @var{variable} into output files (typically one
7391 or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
7392 replace instances of @samp{@@@var{variable}@@} in input files with the
7393 value that the shell variable @var{variable} has when @code{AC_OUTPUT}
7394 is called. The value can contain newlines.
7395 The substituted value is not rescanned for more output variables;
7396 occurrences of @samp{@@@var{variable}@@} in the value are inserted
7397 literally into the output file. (The algorithm uses the special marker
7398 @code{|#_!!_#|} internally, so the substituted value cannot contain
7401 If @var{value} is given, in addition assign it to @var{variable}.
7403 The string @var{variable} is passed to @code{m4_pattern_allow}
7404 (@pxref{Forbidden Patterns}).
7407 @defmac AC_SUBST_FILE (@var{variable})
7408 @acindex{SUBST_FILE}
7409 Another way to create an output variable from a shell variable. Make
7410 @code{AC_OUTPUT} insert (without substitutions) the contents of the file
7411 named by shell variable @var{variable} into output files. This means
7412 that @code{AC_OUTPUT} will replace instances of
7413 @samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
7414 with the contents of the file that the shell variable @var{variable}
7415 names when @code{AC_OUTPUT} is called. Set the variable to
7416 @file{/dev/null} for cases that do not have a file to insert.
7417 This substitution occurs only when the @samp{@@@var{variable}@@} is on a
7418 line by itself, optionally surrounded by spaces and tabs. The
7419 substitution replaces the whole line, including the spaces, tabs, and
7420 the terminating newline.
7422 This macro is useful for inserting @file{Makefile} fragments containing
7423 special dependencies or other @code{make} directives for particular host
7424 or target types into @file{Makefile}s. For example, @file{configure.ac}
7428 AC_SUBST_FILE([host_frag])
7429 host_frag=$srcdir/conf/sun4.mh
7433 and then a @file{Makefile.in} could contain:
7439 The string @var{variable} is passed to @code{m4_pattern_allow}
7440 (@pxref{Forbidden Patterns}).
7443 @cindex Previous Variable
7444 @cindex Variable, Precious
7445 Running @command{configure} in varying environments can be extremely
7446 dangerous. If for instance the user runs @samp{CC=bizarre-cc
7447 ./configure}, then the cache, @file{config.h}, and many other output
7448 files will depend upon @command{bizarre-cc} being the C compiler. If
7449 for some reason the user runs @command{./configure} again, or if it is
7450 run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
7451 and @pxref{config.status Invocation}), then the configuration can be
7452 inconsistent, composed of results depending upon two different
7455 Environment variables that affect this situation, such as @samp{CC}
7456 above, are called @dfn{precious variables}, and can be declared as such
7457 by @code{AC_ARG_VAR}.
7459 @defmac AC_ARG_VAR (@var{variable}, @var{description})
7461 Declare @var{variable} is a precious variable, and include its
7462 @var{description} in the variable section of @samp{./configure --help}.
7464 Being precious means that
7467 @var{variable} is @code{AC_SUBST}'d.
7470 The value of @var{variable} when @command{configure} was launched is
7471 saved in the cache, including if it was not specified on the command
7472 line but via the environment. Indeed, while @command{configure} can
7473 notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc},
7474 it is impossible to notice it in @samp{CC=bizarre-cc ./configure},
7475 which, unfortunately, is what most users do.
7477 We emphasize that it is the @emph{initial} value of @var{variable} which
7478 is saved, not that found during the execution of @command{configure}.
7479 Indeed, specifying @samp{./configure FOO=foo} and letting
7480 @samp{./configure} guess that @code{FOO} is @code{foo} can be two very
7484 @var{variable} is checked for consistency between two
7485 @command{configure} runs. For instance:
7488 $ @kbd{./configure --silent --config-cache}
7489 $ @kbd{CC=cc ./configure --silent --config-cache}
7490 configure: error: `CC' was not set in the previous run
7491 configure: error: changes in the environment can compromise \
7493 configure: error: run `make distclean' and/or \
7494 `rm config.cache' and start over
7498 and similarly if the variable is unset, or if its content is changed.
7502 @var{variable} is kept during automatic reconfiguration
7503 (@pxref{config.status Invocation}) as if it had been passed as a command
7504 line argument, including when no cache is used:
7507 $ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
7508 $ @kbd{./config.status --recheck}
7509 running /bin/sh ./configure undeclared_var=raboof --silent \
7510 CC=/usr/bin/cc --no-create --no-recursion
7516 @node Caching Results
7517 @section Caching Results
7520 To avoid checking for the same features repeatedly in various
7521 @command{configure} scripts (or in repeated runs of one script),
7522 @command{configure} can optionally save the results of many checks in a
7523 @dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
7524 runs with caching enabled and finds a cache file, it reads the results
7525 of previous runs from the cache and avoids rerunning those checks. As a
7526 result, @command{configure} can then run much faster than if it had to
7527 perform all of the checks every time.
7529 @defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
7531 Ensure that the results of the check identified by @var{cache-id} are
7532 available. If the results of the check were in the cache file that was
7533 read, and @command{configure} was not given the @option{--quiet} or
7534 @option{--silent} option, print a message saying that the result was
7535 cached; otherwise, run the shell commands @var{commands-to-set-it}. If
7536 the shell commands are run to determine the value, the value will be
7537 saved in the cache file just before @command{configure} creates its output
7538 files. @xref{Cache Variable Names}, for how to choose the name of the
7539 @var{cache-id} variable.
7541 The @var{commands-to-set-it} @emph{must have no side effects} except for
7542 setting the variable @var{cache-id}, see below.
7545 @defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
7546 @acindex{CACHE_CHECK}
7547 A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
7548 messages. This macro provides a convenient shorthand for the most
7549 common way to use these macros. It calls @code{AC_MSG_CHECKING} for
7550 @var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
7551 @var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
7553 The @var{commands-to-set-it} @emph{must have no side effects} except for
7554 setting the variable @var{cache-id}, see below.
7557 It is very common to find buggy macros using @code{AC_CACHE_VAL} or
7558 @code{AC_CACHE_CHECK}, because people are tempted to call
7559 @code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
7560 @emph{follows} the call to @code{AC_CACHE_VAL} should call
7561 @code{AC_DEFINE}, by examining the value of the cache variable. For
7562 instance, the following macro is broken:
7566 AC_DEFUN([AC_SHELL_TRUE],
7567 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
7568 [ac_cv_shell_true_works=no
7569 true && ac_cv_shell_true_works=yes
7570 if test $ac_cv_shell_true_works = yes; then
7571 AC_DEFINE([TRUE_WORKS], [1],
7572 [Define if `true(1)' works properly.])
7579 This fails if the cache is enabled: the second time this macro is run,
7580 @code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
7585 AC_DEFUN([AC_SHELL_TRUE],
7586 [AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
7587 [ac_cv_shell_true_works=no
7588 true && ac_cv_shell_true_works=yes])
7589 if test $ac_cv_shell_true_works = yes; then
7590 AC_DEFINE([TRUE_WORKS], [1],
7591 [Define if `true(1)' works properly.])
7597 Also, @var{commands-to-set-it} should not print any messages, for
7598 example with @code{AC_MSG_CHECKING}; do that before calling
7599 @code{AC_CACHE_VAL}, so the messages are printed regardless of whether
7600 the results of the check are retrieved from the cache or determined by
7601 running the shell commands.
7604 * Cache Variable Names:: Shell variables used in caches
7605 * Cache Files:: Files @command{configure} uses for caching
7606 * Cache Checkpointing:: Loading and saving the cache file
7609 @node Cache Variable Names
7610 @subsection Cache Variable Names
7611 @cindex Cache variable
7613 The names of cache variables should have the following format:
7616 @var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
7620 for example, @samp{ac_cv_header_stat_broken} or
7621 @samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
7624 @item @var{package-prefix}
7625 An abbreviation for your package or organization; the same prefix you
7626 begin local Autoconf macros with, except lowercase by convention.
7627 For cache values used by the distributed Autoconf macros, this value is
7631 Indicates that this shell variable is a cache value. This string
7632 @emph{must} be present in the variable name, including the leading
7635 @item @var{value-type}
7636 A convention for classifying cache values, to produce a rational naming
7637 system. The values used in Autoconf are listed in @ref{Macro Names}.
7639 @item @var{specific-value}
7640 Which member of the class of cache values this test applies to.
7641 For example, which function (@samp{alloca}), program (@samp{gcc}), or
7642 output variable (@samp{INSTALL}).
7644 @item @var{additional-options}
7645 Any particular behavior of the specific member that this test applies to.
7646 For example, @samp{broken} or @samp{set}. This part of the name may
7647 be omitted if it does not apply.
7650 The values assigned to cache variables may not contain newlines.
7651 Usually, their values will be Boolean (@samp{yes} or @samp{no}) or the
7652 names of files or functions; so this is not an important restriction.
7655 @subsection Cache Files
7657 A cache file is a shell script that caches the results of configure
7658 tests run on one system so they can be shared between configure scripts
7659 and configure runs. It is not useful on other systems. If its contents
7660 are invalid for some reason, the user may delete or edit it.
7662 By default, @command{configure} uses no cache file,
7663 to avoid problems caused by accidental
7664 use of stale cache files.
7666 To enable caching, @command{configure} accepts @option{--config-cache} (or
7667 @option{-C}) to cache results in the file @file{config.cache}.
7668 Alternatively, @option{--cache-file=@var{file}} specifies that
7669 @var{file} be the cache file. The cache file is created if it does not
7670 exist already. When @command{configure} calls @command{configure} scripts in
7671 subdirectories, it uses the @option{--cache-file} argument so that they
7672 share the same cache. @xref{Subdirectories}, for information on
7673 configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
7675 @file{config.status} only pays attention to the cache file if it is
7676 given the @option{--recheck} option, which makes it rerun
7677 @command{configure}.
7679 It is wrong to try to distribute cache files for particular system types.
7680 There is too much room for error in doing that, and too much
7681 administrative overhead in maintaining them. For any features that
7682 can't be guessed automatically, use the standard method of the canonical
7683 system type and linking files (@pxref{Manual Configuration}).
7685 The site initialization script can specify a site-wide cache file to
7686 use, instead of the usual per-program cache. In this case, the cache
7687 file will gradually accumulate information whenever someone runs a new
7688 @command{configure} script. (Running @command{configure} merges the new cache
7689 results with the existing cache file.) This may cause problems,
7690 however, if the system configuration (e.g., the installed libraries or
7691 compilers) changes and the stale cache file is not deleted.
7693 @node Cache Checkpointing
7694 @subsection Cache Checkpointing
7696 If your configure script, or a macro called from @file{configure.ac}, happens
7697 to abort the configure process, it may be useful to checkpoint the cache
7698 a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
7699 reduce the amount of time it takes to re-run the configure script with
7700 (hopefully) the error that caused the previous abort corrected.
7702 @c FIXME: Do we really want to document this guy?
7703 @defmac AC_CACHE_LOAD
7704 @acindex{CACHE_LOAD}
7705 Loads values from existing cache file, or creates a new cache file if a
7706 cache file is not found. Called automatically from @code{AC_INIT}.
7709 @defmac AC_CACHE_SAVE
7710 @acindex{CACHE_SAVE}
7711 Flushes all cached values to the cache file. Called automatically from
7712 @code{AC_OUTPUT}, but it can be quite useful to call
7713 @code{AC_CACHE_SAVE} at key points in @file{configure.ac}.
7719 @r{ @dots{} AC_INIT, etc. @dots{}}
7721 # Checks for programs.
7723 AC_PROG_GCC_TRADITIONAL
7724 @r{ @dots{} more program checks @dots{}}
7729 # Checks for libraries.
7730 AC_CHECK_LIB([nsl], [gethostbyname])
7731 AC_CHECK_LIB([socket], [connect])
7732 @r{ @dots{} more lib checks @dots{}}
7737 # Might abort@dots{}
7738 AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])])
7739 AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])])
7741 @r{ @dots{} AC_OUTPUT, etc. @dots{}}
7744 @node Printing Messages
7745 @section Printing Messages
7746 @cindex Messages, from @command{configure}
7748 @command{configure} scripts need to give users running them several kinds
7749 of information. The following macros print messages in ways appropriate
7750 for each kind. The arguments to all of them get enclosed in shell
7751 double quotes, so the shell performs variable and back-quote
7752 substitution on them.
7754 These macros are all wrappers around the @command{echo} shell command,
7755 and will direct output to the appropriate file descriptor (@pxref{File
7756 Descriptor Macros}).
7757 @command{configure} scripts should rarely need to run @command{echo} directly
7758 to print messages for the user. Using these macros makes it easy to
7759 change how and when each kind of message is printed; such changes need
7760 only be made to the macro definitions and all the callers will change
7763 To diagnose static issues, i.e., when @command{autoconf} is run, see
7764 @ref{Reporting Messages}.
7766 @defmac AC_MSG_CHECKING (@var{feature-description})
7767 @acindex{MSG_CHECKING}
7768 Notify the user that @command{configure} is checking for a particular
7769 feature. This macro prints a message that starts with @samp{checking }
7770 and ends with @samp{...} and no newline. It must be followed by a call
7771 to @code{AC_MSG_RESULT} to print the result of the check and the
7772 newline. The @var{feature-description} should be something like
7773 @samp{whether the Fortran compiler accepts C++ comments} or @samp{for
7776 This macro prints nothing if @command{configure} is run with the
7777 @option{--quiet} or @option{--silent} option.
7780 @defmac AC_MSG_RESULT (@var{result-description})
7781 @acindex{MSG_RESULT}
7782 Notify the user of the results of a check. @var{result-description} is
7783 almost always the value of the cache variable for the check, typically
7784 @samp{yes}, @samp{no}, or a file name. This macro should follow a call
7785 to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
7786 the completion of the message printed by the call to
7787 @code{AC_MSG_CHECKING}.
7789 This macro prints nothing if @command{configure} is run with the
7790 @option{--quiet} or @option{--silent} option.
7793 @defmac AC_MSG_NOTICE (@var{message})
7794 @acindex{MSG_NOTICE}
7795 Deliver the @var{message} to the user. It is useful mainly to print a
7796 general description of the overall purpose of a group of feature checks,
7800 AC_MSG_NOTICE([checking if stack overflow is detectable])
7803 This macro prints nothing if @command{configure} is run with the
7804 @option{--quiet} or @option{--silent} option.
7807 @defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
7809 Notify the user of an error that prevents @command{configure} from
7810 completing. This macro prints an error message to the standard error
7811 output and exits @command{configure} with @var{exit-status} (1 by default).
7812 @var{error-description} should be something like @samp{invalid value
7815 The @var{error-description} should start with a lower-case letter, and
7816 ``cannot'' is preferred to ``can't''.
7819 @defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status})
7820 @acindex{MSG_FAILURE}
7821 This @code{AC_MSG_ERROR} wrapper notifies the user of an error that
7822 prevents @command{configure} from completing @emph{and} that additional
7823 details are provided in @file{config.log}. This is typically used when
7824 abnormal results are found during a compilation.
7827 @defmac AC_MSG_WARN (@var{problem-description})
7829 Notify the @command{configure} user of a possible problem. This macro
7830 prints the message to the standard error output; @command{configure}
7831 continues running afterward, so macros that call @code{AC_MSG_WARN} should
7832 provide a default (back-up) behavior for the situations they warn about.
7833 @var{problem-description} should be something like @samp{ln -s seems to
7839 @c ====================================================== Programming in M4.
7841 @node Programming in M4
7842 @chapter Programming in M4
7845 Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
7846 convenient macros for pure M4 programming, and @dfn{M4sh}, which
7847 provides macros dedicated to shell script generation.
7849 As of this version of Autoconf, these two layers are still experimental,
7850 and their interface might change in the future. As a matter of fact,
7851 @emph{anything that is not documented must not be used}.
7854 * M4 Quotation:: Protecting macros from unwanted expansion
7855 * Using autom4te:: The Autoconf executables backbone
7856 * Programming in M4sugar:: Convenient pure M4 macros
7857 * Programming in M4sh:: Common shell Constructs
7858 * File Descriptor Macros:: File descriptor macros for input and output
7862 @section M4 Quotation
7863 @cindex M4 quotation
7866 @c FIXME: Grmph, yet another quoting myth: quotation has *never*
7867 @c prevented `expansion' of $1. Unless it refers to the expansion
7868 @c of the value of $1? Anyway, we need a rewrite here@enddots{}
7870 The most common problem with existing macros is an improper quotation.
7871 This section, which users of Autoconf can skip, but which macro writers
7872 @emph{must} read, first justifies the quotation scheme that was chosen
7873 for Autoconf and then ends with a rule of thumb. Understanding the
7874 former helps one to follow the latter.
7877 * Active Characters:: Characters that change the behavior of M4
7878 * One Macro Call:: Quotation and one macro call
7879 * Quotation and Nested Macros:: Macros calling macros
7880 * Changequote is Evil:: Worse than INTERCAL: M4 + changequote
7881 * Quadrigraphs:: Another way to escape special characters
7882 * Quotation Rule Of Thumb:: One parenthesis, one quote
7885 @node Active Characters
7886 @subsection Active Characters
7888 To fully understand where proper quotation is important, you first need
7889 to know what the special characters are in Autoconf: @samp{#} introduces
7890 a comment inside which no macro expansion is performed, @samp{,}
7891 separates arguments, @samp{[} and @samp{]} are the quotes themselves,
7892 and finally @samp{(} and @samp{)} (which M4 tries to match by
7895 In order to understand the delicate case of macro calls, we first have
7896 to present some obvious failures. Below they are ``obvious-ified'',
7897 but when you find them in real life, they are usually in disguise.
7899 Comments, introduced by a hash and running up to the newline, are opaque
7900 tokens to the top level: active characters are turned off, and there is
7904 # define([def], ine)
7905 @result{}# define([def], ine)
7908 Each time there can be a macro expansion, there is a quotation
7909 expansion, i.e., one level of quotes is stripped:
7915 @result{}int tab[10];
7918 Without this in mind, the reader will try hopelessly to use her macro
7922 define([array], [int tab[10];])
7930 How can you correctly output the intended results@footnote{Using
7934 @node One Macro Call
7935 @subsection One Macro Call
7937 Let's proceed on the interaction between active characters and macros
7938 with this small macro, which just returns its first argument:
7945 The two pairs of quotes above are not part of the arguments of
7946 @code{define}; rather, they are understood by the top level when it
7947 tries to find the arguments of @code{define}. Therefore, assuming
7948 @code{car} is not already defined, it is equivalent to write:
7955 But, while it is acceptable for a @file{configure.ac} to avoid unnecessary
7956 quotes, it is bad practice for Autoconf macros which must both be more
7957 robust and also advocate perfect style.
7959 At the top level, there are only two possibilities: either you
7965 [car(foo, bar, baz)]
7966 @result{}car(foo, bar, baz)
7969 Let's pay attention to the special characters:
7973 @error{}EOF in argument list
7976 The closing parenthesis is hidden in the comment; with a hypothetical
7977 quoting, the top level understood it this way:
7984 Proper quotation, of course, fixes the problem:
7991 Here are more examples:
8014 With this in mind, we can explore the cases where macros invoke
8018 @node Quotation and Nested Macros
8019 @subsection Quotation and Nested Macros
8021 The examples below use the following macros:
8025 define([active], [ACT, IVE])
8026 define([array], [int tab[10]])
8029 Each additional embedded macro call introduces other possible
8030 interesting quotations:
8041 In the first case, the top level looks for the arguments of @code{car},
8042 and finds @samp{active}. Because M4 evaluates its arguments
8043 before applying the macro, @samp{active} is expanded, which results in:
8051 In the second case, the top level gives @samp{active} as first and only
8052 argument of @code{car}, which results in:
8060 i.e., the argument is evaluated @emph{after} the macro that invokes it.
8061 In the third case, @code{car} receives @samp{[active]}, which results in:
8069 exactly as we already saw above.
8071 The example above, applied to a more realistic example, gives:
8078 car([[int tab[10];]])
8079 @result{}int tab[10];
8083 Huh? The first case is easily understood, but why is the second wrong,
8084 and the third right? To understand that, you must know that after
8085 M4 expands a macro, the resulting text is immediately subjected
8086 to macro expansion and quote removal. This means that the quote removal
8087 occurs twice---first before the argument is passed to the @code{car}
8088 macro, and second after the @code{car} macro expands to the first
8091 As the author of the Autoconf macro @code{car}, you then consider it to
8092 be incorrect that your users have to double-quote the arguments of
8093 @code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
8097 define([qar], [[$1]])
8101 and check that @code{qar} is properly fixed:
8105 @result{}int tab[10];
8109 Ahhh! That's much better.
8111 But note what you've done: now that the arguments are literal strings,
8112 if the user wants to use the results of expansions as arguments, she has
8113 to use an @emph{unquoted} macro call:
8121 where she wanted to reproduce what she used to do with @code{car}:
8129 Worse yet: she wants to use a macro that produces a set of @code{cpp}
8133 define([my_includes], [#include <stdio.h>])
8135 @result{}#include <stdio.h>
8137 @error{}EOF in argument list
8140 This macro, @code{qar}, because it double quotes its arguments, forces
8141 its users to leave their macro calls unquoted, which is dangerous.
8142 Commas and other active symbols are interpreted by M4 before
8143 they are given to the macro, often not in the way the users expect.
8144 Also, because @code{qar} behaves differently from the other macros,
8145 it's an exception that should be avoided in Autoconf.
8147 @node Changequote is Evil
8148 @subsection @code{changequote} is Evil
8149 @cindex @code{changequote}
8151 The temptation is often high to bypass proper quotation, in particular
8152 when it's late at night. Then, many experienced Autoconf hackers
8153 finally surrender to the dark side of the force and use the ultimate
8154 weapon: @code{changequote}.
8156 The M4 builtin @code{changequote} belongs to a set of primitives that
8157 allow one to adjust the syntax of the language to adjust it to one's
8158 needs. For instance, by default M4 uses @samp{`} and @samp{'} as
8159 quotes, but in the context of shell programming (and actually of most
8160 programming languages), that's about the worst choice one can make:
8161 because of strings and back-quoted expressions in shell code (such as
8162 @samp{'this'} and @samp{`that`}), because of literal characters in usual
8163 programming languages (as in @samp{'0'}), there are many unbalanced
8164 @samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
8165 not impossible. In order to make M4 useful in such a context, its
8166 designers have equipped it with @code{changequote}, which makes it
8167 possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and
8168 Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
8169 because they are unlikely characters, but @emph{because they are
8170 characters unlikely to be unbalanced}.
8172 There are other magic primitives, such as @code{changecom} to specify
8173 what syntactic forms are comments (it is common to see
8174 @samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
8175 @code{changeword} and @code{changesyntax} to change other syntactic
8176 details (such as the character to denote the @var{n}th argument, @samp{$} by
8177 default, the parenthesis around arguments, etc.).
8179 These primitives are really meant to make M4 more useful for specific
8180 domains: they should be considered like command line options:
8181 @option{--quotes}, @option{--comments}, @option{--words}, and
8182 @code{--syntax}. Nevertheless, they are implemented as M4 builtins, as
8183 it makes M4 libraries self contained (no need for additional options).
8185 There lies the problem@enddots{}
8189 The problem is that it is then tempting to use them in the middle of an
8190 M4 script, as opposed to its initialization. This, if not carefully
8191 thought out, can lead to disastrous effects: @emph{you are changing the
8192 language in the middle of the execution}. Changing and restoring the
8193 syntax is often not enough: if you happened to invoke macros in between,
8194 these macros will be lost, as the current syntax will probably not be
8195 the one they were implemented with.
8197 @c FIXME: I've been looking for a short, real case example, but I
8202 @subsection Quadrigraphs
8203 @cindex quadrigraphs
8204 @cindex @samp{@@S|@@}
8205 @cindex @samp{@@&t@@}
8206 @c Info cannot handle `:' in index entries.
8207 @c @cindex @samp{@@<:@@}
8208 @c @cindex @samp{@@:>@@}
8209 @c @cindex @samp{@@%:@@}
8211 When writing an Autoconf macro you may occasionally need to generate
8212 special characters that are difficult to express with the standard
8213 Autoconf quoting rules. For example, you may need to output the regular
8214 expression @samp{[^[]}, which matches any character other than @samp{[}.
8215 This expression contains unbalanced brackets so it cannot be put easily
8218 You can work around this problem by using one of the following
8234 Quadrigraphs are replaced at a late stage of the translation process,
8235 after @command{m4} is run, so they do not get in the way of M4 quoting.
8236 For example, the string @samp{^@@<:@@}, independently of its quotation,
8237 will appear as @samp{^[} in the output.
8239 The empty quadrigraph can be used:
8242 @item to mark trailing spaces explicitly
8244 Trailing spaces are smashed by @command{autom4te}. This is a feature.
8246 @item to produce other quadrigraphs
8248 For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
8250 @item to escape @emph{occurrences} of forbidden patterns
8252 For instance you might want to mention @code{AC_FOO} in a comment, while
8253 still being sure that @command{autom4te} will still catch unexpanded
8254 @samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
8257 The name @samp{@@&t@@} was suggested by Paul Eggert:
8260 I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
8261 own invention, but the @samp{t} came from the source code of the
8262 @sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
8263 and which used @samp{mt} to denote the empty string. In C, it would
8264 have looked like something like:
8267 char const mt[] = "";
8271 but of course the source code was written in Algol 68.
8273 I don't know where he got @samp{mt} from: it could have been his own
8274 invention, and I suppose it could have been a common pun around the
8275 Cambridge University computer lab at the time.
8278 @node Quotation Rule Of Thumb
8279 @subsection Quotation Rule Of Thumb
8281 To conclude, the quotation rule of thumb is:
8283 @center @emph{One pair of quotes per pair of parentheses.}
8285 Never over-quote, never under-quote, in particular in the definition of
8286 macros. In the few places where the macros need to use brackets
8287 (usually in C program text or regular expressions), properly quote
8288 @emph{the arguments}!
8290 It is common to read Autoconf programs with snippets like:
8294 changequote(<<, >>)dnl
8296 #ifndef tzname /* For SGI. */
8297 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
8299 changequote([, ])dnl
8300 [atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
8304 which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
8305 double quoting, so you just need:
8310 #ifndef tzname /* For SGI. */
8311 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
8314 [ac_cv_var_tzname=yes],
8315 [ac_cv_var_tzname=no])
8319 The M4-fluent reader will note that these two examples are rigorously
8320 equivalent, since M4 swallows both the @samp{changequote(<<, >>)}
8321 and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
8322 quotes are not part of the arguments!
8324 Simplified, the example above is just doing this:
8327 changequote(<<, >>)dnl
8329 changequote([, ])dnl
8339 With macros that do not double quote their arguments (which is the
8340 rule), double-quote the (risky) literals:
8343 AC_LINK_IFELSE([AC_LANG_PROGRAM(
8345 #ifndef tzname /* For SGI. */
8346 extern char *tzname[]; /* RS6000 and others reject char **tzname. */
8348 [atoi (*tzname);])],
8349 [ac_cv_var_tzname=yes],
8350 [ac_cv_var_tzname=no])
8353 Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really
8354 should be using @code{AC_LINK_IFELSE} instead.
8356 @xref{Quadrigraphs}, for what to do if you run into a hopeless case
8357 where quoting does not suffice.
8359 When you create a @command{configure} script using newly written macros,
8360 examine it carefully to check whether you need to add more quotes in
8361 your macros. If one or more words have disappeared in the M4
8362 output, you need more quotes. When in doubt, quote.
8364 However, it's also possible to put on too many layers of quotes. If
8365 this happens, the resulting @command{configure} script may contain
8366 unexpanded macros. The @command{autoconf} program checks for this problem
8367 by looking for the string @samp{AC_} in @file{configure}. However, this
8368 heuristic does not work in general: for example, it does not catch
8369 overquoting in @code{AC_DEFINE} descriptions.
8372 @c ---------------------------------------- Using autom4te
8374 @node Using autom4te
8375 @section Using @command{autom4te}
8377 The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition
8378 to Autoconf per se, heavily rely on M4. All these different uses
8379 revealed common needs factored into a layer over @command{m4}:
8380 @command{autom4te}@footnote{
8382 Yet another great name from Lars J. Aas.
8386 @command{autom4te} is a preprocessor that is like @command{m4}.
8387 It supports M4 extensions designed for use in tools like Autoconf.
8390 * autom4te Invocation:: A @acronym{GNU} M4 wrapper
8391 * Customizing autom4te:: Customizing the Autoconf package
8394 @node autom4te Invocation
8395 @subsection Invoking @command{autom4te}
8397 The command line arguments are modeled after M4's:
8400 autom4te @var{options} @var{files}
8404 where the @var{files} are directly passed to @command{m4}. In addition
8405 to the regular expansion, it handles the replacement of the quadrigraphs
8406 (@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
8407 output. It supports an extended syntax for the @var{files}:
8410 @item @var{file}.m4f
8411 This file is an M4 frozen file. Note that @emph{all the previous files
8412 are ignored}. See the option @option{--melt} for the rationale.
8415 If found in the library path, the @var{file} is included for expansion,
8416 otherwise it is ignored instead of triggering a failure.
8421 Of course, it supports the Autoconf common subset of options:
8426 Print a summary of the command line options and exit.
8430 Print the version number of Autoconf and exit.
8434 Report processing steps.
8438 Don't remove the temporary files and be even more verbose.
8440 @item --include=@var{dir}
8442 Also look for input files in @var{dir}. Multiple invocations
8445 @item --output=@var{file}
8446 @itemx -o @var{file}
8447 Save output (script or trace) to @var{file}. The file @option{-} stands
8448 for the standard output.
8453 As an extension of @command{m4}, it includes the following options:
8456 @item --warnings=@var{category}
8457 @itemx -W @var{category}
8459 @c FIXME: Point to the M4sugar macros, not Autoconf's.
8460 Report the warnings related to @var{category} (which can actually be a
8461 comma separated list). @xref{Reporting Messages}, macro
8462 @code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
8467 report all the warnings
8473 treats warnings as errors
8475 @item no-@var{category}
8476 disable warnings falling into @var{category}
8479 Warnings about @samp{syntax} are enabled by default, and the environment
8480 variable @env{WARNINGS}, a comma separated list of categories, is
8481 honored. @command{autom4te -W @var{category}} will actually
8482 behave as if you had run:
8485 autom4te --warnings=syntax,$WARNINGS,@var{category}
8489 For example, if you want to disable @command{autom4te}'s defaults and
8490 @env{WARNINGS}, but enable the warnings about obsolete
8491 constructs, you would use @option{-W none,obsolete}.
8494 @cindex Macro invocation stack
8495 @command{autom4te} displays a back trace for errors, but not for
8496 warnings; if you want them, just pass @option{-W error}.
8500 Do not use frozen files. Any argument @code{@var{file}.m4f} will be
8501 replaced with @code{@var{file}.m4}. This helps tracing the macros which
8502 are executed only when the files are frozen, typically
8503 @code{m4_define}. For instance, running:
8506 autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
8510 is roughly equivalent to running:
8513 m4 1.m4 2.m4 3.m4 4.m4 input.m4
8520 autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
8527 m4 --reload-state=4.m4f input.m4
8532 Produce a frozen state file. @command{autom4te} freezing is stricter
8533 than M4's: it must produce no warnings, and no output other than empty
8534 lines (a line with white space is @emph{not} empty) and comments
8535 (starting with @samp{#}). Please, note that contrary to @command{m4},
8536 this options takes no argument:
8539 autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
8546 m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
8549 @item --mode=@var{octal-mode}
8550 @itemx -m @var{octal-mode}
8551 Set the mode of the non-traces output to @var{octal-mode}; by default
8557 @cindex @file{autom4te.cache}
8558 As another additional feature over @command{m4}, @command{autom4te}
8559 caches its results. @acronym{GNU} M4 is able to produce a regular
8560 output and traces at the same time. Traces are heavily used in the
8561 @acronym{GNU} Build System: @command{autoheader} uses them to build
8562 @file{config.h.in}, @command{autoreconf} to determine what
8563 @acronym{GNU} Build System components are used, @command{automake} to
8564 ``parse'' @file{configure.ac} etc. To save the long runs of
8565 @command{m4}, traces are cached while performing regular expansion,
8566 and conversely. This cache is (actually, the caches are) stored in
8567 the directory @file{autom4te.cache}. @emph{It can safely be removed}
8568 at any moment (especially if for some reason @command{autom4te}
8569 considers it is trashed).
8572 @item --cache=@var{directory}
8573 @itemx -C @var{directory}
8574 Specify the name of the directory where the result should be cached.
8575 Passing an empty value disables caching. Be sure to pass a relative
8576 file name, as for the time being, global caches are not supported.
8579 Don't cache the results.
8583 If a cache is used, consider it obsolete (but update it anyway).
8588 Because traces are so important to the @acronym{GNU} Build System,
8589 @command{autom4te} provides high level tracing features as compared to
8590 M4, and helps exploiting the cache:
8593 @item --trace=@var{macro}[:@var{format}]
8594 @itemx -t @var{macro}[:@var{format}]
8595 Trace the invocations of @var{macro} according to the @var{format}.
8596 Multiple @option{--trace} arguments can be used to list several macros.
8597 Multiple @option{--trace} arguments for a single macro are not
8598 cumulative; instead, you should just make @var{format} as long as
8601 The @var{format} is a regular string, with newlines if desired, and
8602 several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
8603 use the following special escapes:
8607 The character @samp{$}.
8610 The file name from which @var{macro} is called.
8613 The line number from which @var{macro} is called.
8616 The depth of the @var{macro} call. This is an M4 technical detail that
8617 you probably don't want to know about.
8620 The name of the @var{macro}.
8623 The @var{num}th argument of the call to @var{macro}.
8627 @itemx $@{@var{separator}@}@@
8628 All the arguments passed to @var{macro}, separated by the character
8629 @var{sep} or the string @var{separator} (@samp{,} by default). Each
8630 argument is quoted, i.e., enclosed in a pair of square brackets.
8634 @itemx $@{@var{separator}@}*
8635 As above, but the arguments are not quoted.
8639 @itemx $@{@var{separator}@}%
8640 As above, but the arguments are not quoted, all new line characters in
8641 the arguments are smashed, and the default separator is @samp{:}.
8643 The escape @samp{$%} produces single-line trace outputs (unless you put
8644 newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
8648 @xref{autoconf Invocation}, for examples of trace uses.
8650 @item --preselect=@var{macro}
8651 @itemx -p @var{macro}
8652 Cache the traces of @var{macro}, but do not enable traces. This is
8653 especially important to save CPU cycles in the future. For instance,
8654 when invoked, @command{autoconf} preselects all the macros that
8655 @command{autoheader}, @command{automake}, @command{autoreconf} etc.@: will
8656 trace, so that running @command{m4} is not needed to trace them: the
8657 cache suffices. This results in a huge speed-up.
8662 @cindex Autom4te Library
8663 Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
8664 libraries}. They consists in a powerful yet extremely simple feature:
8665 sets of combined command line arguments:
8668 @item --language=@var{language}
8669 @itemx -l @var{language}
8670 Use the @var{language} Autom4te library. Current languages include:
8674 create M4sugar output.
8677 create M4sh executable shell scripts.
8680 create Autotest executable test suites.
8682 @item Autoconf-without-aclocal-m4
8683 create Autoconf executable configure scripts without
8684 reading @file{aclocal.m4}.
8687 create Autoconf executable configure scripts. This language inherits
8688 all the characteristics of @code{Autoconf-without-aclocal-m4} and will
8689 additionally read @file{aclocal.m4}.
8692 @item --prepend-include=@var{dir}
8694 Prepend directory @var{dir} to the search path. This is used to include
8695 the language-specific files before any third-party macros.
8699 @cindex @file{autom4te.cfg}
8700 As an example, if Autoconf is installed in its default location,
8701 @file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is
8702 strictly equivalent to the command:
8705 autom4te --prepend-include /usr/local/share/autoconf \
8706 m4sugar/m4sugar.m4f --warnings syntax foo.m4
8710 Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4}
8711 is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f
8715 autom4te --prepend-include /usr/local/share/autoconf \
8716 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4
8720 The definition of the languages is stored in @file{autom4te.cfg}.
8722 @node Customizing autom4te
8723 @subsection Customizing @command{autom4te}
8725 One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e.,
8726 as found in the user home directory), and @file{./.autom4te.cfg} (i.e.,
8727 as found in the directory from which @command{autom4te} is run). The
8728 order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg},
8729 then @file{./.autom4te.cfg}, and finally the command line arguments.
8731 In these text files, comments are introduced with @code{#}, and empty
8732 lines are ignored. Customization is performed on a per-language basis,
8733 wrapped in between a @samp{begin-language: "@var{language}"},
8734 @samp{end-language: "@var{language}"} pair.
8736 Customizing a language stands for appending options (@pxref{autom4te
8737 Invocation}) to the current definition of the language. Options, and
8738 more generally arguments, are introduced by @samp{args:
8739 @var{arguments}}. You may use the traditional shell syntax to quote the
8742 As an example, to disable Autoconf caches (@file{autom4te.cache})
8743 globally, include the following lines in @file{~/.autom4te.cfg}:
8746 ## ------------------ ##
8747 ## User Preferences. ##
8748 ## ------------------ ##
8750 begin-language: "Autoconf-without-aclocal-m4"
8752 end-language: "Autoconf-without-aclocal-m4"
8756 @node Programming in M4sugar
8757 @section Programming in M4sugar
8760 M4 by itself provides only a small, but sufficient, set of all-purpose
8761 macros. M4sugar introduces additional generic macros. Its name was
8762 coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
8766 * Redefined M4 Macros:: M4 builtins changed in M4sugar
8767 * Evaluation Macros:: More quotation and evaluation control
8768 * Forbidden Patterns:: Catching unexpanded macros
8771 @node Redefined M4 Macros
8772 @subsection Redefined M4 Macros
8795 With a few exceptions, all the M4 native macros are moved in the
8796 @samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
8797 @code{m4_define} etc.
8799 Some M4 macros are redefined, and are slightly incompatible with their
8804 This macro kept its original name: no @code{m4_dnl} is defined.
8807 @defmac m4_defn (@var{macro})
8809 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8810 defined. See @code{m4_undefine}.
8813 @defmac m4_exit (@var{exit-status})
8815 This macro corresponds to @code{m4exit}.
8818 @defmac m4_if (@var{comment})
8819 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
8820 @defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{})
8822 This macro corresponds to @code{ifelse}.
8825 @defmac m4_include (@var{file})
8826 @defmacx m4_sinclude (@var{file})
8829 Like the M4 builtins, but warn against multiple inclusions of @var{file}.
8832 @defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
8834 This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
8835 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
8836 provide extended regular expression syntax via @code{epatsubst}.
8839 @defmac m4_popdef (@var{macro})
8841 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8842 defined. See @code{m4_undefine}.
8845 @defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
8847 This macro corresponds to @code{regexp}. The name @code{m4_regexp}
8848 is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will
8849 provide extended regular expression syntax via @code{eregexp}.
8852 @defmac m4_wrap (@var{text})
8854 This macro corresponds to @code{m4wrap}.
8856 You are encouraged to end @var{text} with @samp{[]}, so that there are
8857 no risks that two consecutive invocations of @code{m4_wrap} result in an
8858 unexpected pasting of tokens, as in
8861 m4_define([foo], [Foo])
8862 m4_define([bar], [Bar])
8863 m4_define([foobar], [FOOBAR])
8870 @defmac m4_undefine (@var{macro})
8872 Contrary to the M4 builtin, this macro fails if @var{macro} is not
8876 m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
8880 to recover the behavior of the builtin.
8883 @node Evaluation Macros
8884 @subsection Evaluation Macros
8886 The following macros give some control over the order of the evaluation
8887 by adding or removing levels of quotes. They are meant for hard-core M4
8890 @defmac m4_dquote (@var{arg1}, @dots{})
8892 Return the arguments as a quoted list of quoted arguments.
8895 @defmac m4_quote (@var{arg1}, @dots{})
8897 Return the arguments as a single entity, i.e., wrap them into a pair of
8901 The following example aims at emphasizing the difference between (i), not
8902 using these macros, (ii), using @code{m4_quote}, and (iii), using
8906 $ @kbd{cat example.m4}
8907 # Overquote, so that quotes are visible.
8908 m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
8911 show(m4_quote(a, b))
8912 show(m4_dquote(a, b))
8913 $ @kbd{autom4te -l m4sugar example.m4}
8914 $1 = a, $@@ = [a],[b]
8915 $1 = a,b, $@@ = [a,b]
8916 $1 = [a],[b], $@@ = [[a],[b]]
8921 @node Forbidden Patterns
8922 @subsection Forbidden Patterns
8923 @cindex Forbidden patterns
8924 @cindex Patterns, forbidden
8926 M4sugar provides a means to define suspicious patterns, patterns
8927 describing tokens which should not be found in the output. For
8928 instance, if an Autoconf @file{configure} script includes tokens such as
8929 @samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
8930 wrong (typically a macro was not evaluated because of overquotation).
8932 M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
8934 @defmac m4_pattern_forbid (@var{pattern})
8935 @msindex{pattern_forbid}
8936 Declare that no token matching @var{pattern} must be found in the output.
8937 Comments are not checked; this can be a problem if, for instance, you
8938 have some macro left unexpanded after an @samp{#include}. No consensus
8939 is currently found in the Autoconf community, as some people consider it
8940 should be valid to name macros in comments (which doesn't make sense to
8941 the author of this documentation, as @samp{#}-comments should document
8942 the output, not the input, documented by @samp{dnl} comments).
8945 Of course, you might encounter exceptions to these generic rules, for
8946 instance you might have to refer to @samp{$m4_flags}.
8948 @defmac m4_pattern_allow (@var{pattern})
8949 @msindex{pattern_allow}
8950 Any token matching @var{pattern} is allowed, including if it matches an
8951 @code{m4_pattern_forbid} pattern.
8954 @node Programming in M4sh
8955 @section Programming in M4sh
8957 @c FIXME: Eventually will become a chapter, as it is not related to
8958 @c programming in M4 per se.
8960 M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell
8961 scripts. This name was coined by Lars J. Aas, who notes that,
8962 according to the Webster's Revised Unabridged Dictionary (1913):
8965 Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash,
8966 wash, and prob.@: to AS. miscian to mix. See ``Mix''.]
8970 A mass of mixed ingredients reduced to a soft pulpy state by beating or
8974 A mixture of meal or bran and water fed to animals.
8977 A mess; trouble. [Obs.] --Beau.@: & Fl.
8982 For the time being, it is not mature enough to be widely used.
8984 M4sh provides portable alternatives for some common shell constructs
8985 that unfortunately are not portable in practice.
8987 @defmac AS_DIRNAME (@var{file-name})
8989 Return the directory portion of @var{file-name}, using the algorithm
8990 required by Posix. @xref{Limitations of Usual Tools}, for more
8991 details about what this returns and why it is more portable than the
8992 @command{dirname} command.
8995 @defmac AS_IF (@var{test}, @ovar{RUN-IF-TRUE}, @ovar{RUN-IF-FALSE})
8997 Run shell code TEST@. If TEST exits with a zero status then run shell code
8998 RUN-IF-TRUE, else run shell code RUN-IF-FALSE, with simplifications if either
8999 RUN-IF-TRUE or RUN-IF-FALSE is empty.
9002 @defmac AS_MKDIR_P (@var{file-name})
9004 Make the directory @var{file-name}, including intervening directories
9005 as necessary. This is equivalent to @samp{mkdir -p @var{file-name}},
9006 except that it is portable to older versions of @command{mkdir} that
9007 lack support for the @option{-p} option. Also, @code{AS_MKDIR_P}
9008 succeeds if @var{file-name} is a symbolic link to an existing directory,
9009 even though Posix is unclear whether @samp{mkdir -p} should
9010 succeed in that case.
9013 @defmac AS_TR_CPP (@var{expression})
9015 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
9020 $ echo "#define AS_TR_CPP([HAVE_$type]) 1"
9021 #define HAVE_CHAR_P 1
9025 @defmac AS_TR_SH (@var{expression})
9027 Transform @var{expression} into a valid shell variable name. For example:
9030 $ header="sys/some file.h"
9031 $ AS_TR_SH([HAVE_$header])=yes
9032 $ if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi
9037 @defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
9038 @asindex{SET_CATFILE}
9039 Set the shell variable @var{var} to @var{dir}/@var{file}, but
9040 optimizing the common cases (@var{dir} or @var{file} is @samp{.},
9041 @var{file} is absolute, etc.).
9045 @node File Descriptor Macros
9046 @section File Descriptor Macros
9048 @cindex standard input
9049 @cindex file descriptors
9051 @cindex low-level output
9052 @cindex output, low-level
9054 The following macros define file descriptors used to output messages
9055 (or input values) from @file{configure} scripts.
9059 echo "$wombats found" >&AS_MESSAGE_LOG_FD
9060 echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD
9061 read kangaroos <&AS_ORIGINAL_STDIN_FD`
9065 However doing so is seldom needed, because Autoconf provides higher
9066 level macros as described below.
9068 @defmac AS_MESSAGE_FD
9069 @asindex{MESSAGE_FD}
9070 The file descriptor for @samp{checking for...} messages and results.
9071 Normally this directs messages to the standard output, however when
9072 @command{configure} is run with the @code{-q} option, messages sent to
9073 @code{AS_MESSAGE_FD} will be discarded.
9075 If you want to display some messages, consider using one of the printing
9076 macros (@pxref{Printing Messages}) instead. Copies of messages output
9077 via these macros will additionally be recorded in @file{config.log}.
9080 @defmac AS_MESSAGE_LOG_FD
9081 @asindex{MESSAGE_LOG_FD}
9083 The file descriptor for messages logged to @file{config.log}. Macros
9084 that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the
9085 Compiler}), redirect all output to this descriptor. You may want to do
9086 so if you develop such a low-level macro.
9089 @defmac AS_ORIGINAL_STDIN_FD
9090 @asindex{ORIGINAL_STDIN_FD}
9091 The file descriptor for the original standard input.
9093 When @command{configure} runs, it may accidentally execute an
9094 interactive command that has the same name as the non-interactive meant
9095 to be used or checked. If the standard input was the terminal, such
9096 interactive programs would cause @command{configure} to stop, pending
9097 some user input. Therefore @command{configure} redirects its standard
9098 input from @file{/dev/null} during its initialization. This is not
9099 normally a problem, since @command{configure} normally does not need
9102 In the extreme case where your @file{configure} script really needs to
9103 obtain some values from the original standard input, you can read them
9104 explicitly from @code{AS_ORIGINAL_STDIN_FD}.
9108 @c=================================================== Writing Autoconf Macros.
9110 @node Writing Autoconf Macros
9111 @chapter Writing Autoconf Macros
9113 When you write a feature test that could be applicable to more than one
9114 software package, the best thing to do is encapsulate it in a new macro.
9115 Here are some instructions and guidelines for writing Autoconf macros.
9118 * Macro Definitions:: Basic format of an Autoconf macro
9119 * Macro Names:: What to call your new macros
9120 * Reporting Messages:: Notifying @command{autoconf} users
9121 * Dependencies Between Macros:: What to do when macros depend on other macros
9122 * Obsoleting Macros:: Warning about old ways of doing things
9123 * Coding Style:: Writing Autoconf macros @`a la Autoconf
9126 @node Macro Definitions
9127 @section Macro Definitions
9130 Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
9131 similar to the M4 builtin @code{m4_define} macro. In addition to
9132 defining a macro, @code{AC_DEFUN} adds to it some code that is used to
9133 constrain the order in which macros are called (@pxref{Prerequisite
9136 An Autoconf macro definition looks like this:
9139 AC_DEFUN(@var{macro-name}, @var{macro-body})
9142 You can refer to any arguments passed to the macro as @samp{$1},
9143 @samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info,
9144 @acronym{GNU} m4}, for more complete information on writing M4 macros.
9146 Be sure to properly quote both the @var{macro-body} @emph{and} the
9147 @var{macro-name} to avoid any problems if the macro happens to have
9148 been previously defined.
9150 Each macro should have a header comment that gives its prototype, and a
9151 brief description. When arguments have default values, display them in
9152 the prototype. For example:
9155 # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
9156 # --------------------------------------
9157 m4_define([AC_MSG_ERROR],
9158 [@{ AS_MESSAGE([error: $1], [2])
9159 exit m4_default([$2], [1]); @}])
9162 Comments about the macro should be left in the header comment. Most
9163 other comments will make their way into @file{configure}, so just keep
9164 using @samp{#} to introduce comments.
9167 If you have some very special comments about pure M4 code, comments
9168 that make no sense in @file{configure} and in the header comment, then
9169 use the builtin @code{dnl}: it causes M4 to discard the text
9170 through the next newline.
9172 Keep in mind that @code{dnl} is rarely needed to introduce comments;
9173 @code{dnl} is more useful to get rid of the newlines following macros
9174 that produce no output, such as @code{AC_REQUIRE}.
9178 @section Macro Names
9180 All of the Autoconf macros have all-uppercase names starting with
9181 @samp{AC_} to prevent them from accidentally conflicting with other
9182 text. All shell variables that they use for internal purposes have
9183 mostly-lowercase names starting with @samp{ac_}. To ensure that your
9184 macros don't conflict with present or future Autoconf macros, you should
9185 prefix your own macro names and any shell variables they use with some
9186 other sequence. Possibilities include your initials, or an abbreviation
9187 for the name of your organization or software package.
9189 Most of the Autoconf macros' names follow a structured naming convention
9190 that indicates the kind of feature check by the name. The macro names
9191 consist of several words, separated by underscores, going from most
9192 general to most specific. The names of their cache variables use the
9193 same convention (@pxref{Cache Variable Names}, for more information on
9196 The first word of the name after @samp{AC_} usually tells the category
9197 of the feature being tested. Here are the categories used in Autoconf for
9198 specific test macros, the kind of macro that you are more likely to
9199 write. They are also used for cache variables, in all-lowercase. Use
9200 them where applicable; where they're not, invent your own categories.
9204 C language builtin features.
9206 Declarations of C variables in header files.
9208 Functions in libraries.
9210 Posix group owners of files.
9216 Absolute names of files, including programs.
9218 The base names of programs.
9220 Members of aggregates.
9222 Operating system features.
9224 C builtin or declared types.
9226 C variables in libraries.
9229 After the category comes the name of the particular feature being
9230 tested. Any further words in the macro name indicate particular aspects
9231 of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
9232 behavior of the @code{utime} function when called with a @code{NULL}
9235 An internal macro should have a name that starts with an underscore;
9236 Autoconf internals should therefore start with @samp{_AC_}.
9237 Additionally, a macro that is an internal subroutine of another macro
9238 should have a name that starts with an underscore and the name of that
9239 other macro, followed by one or more words saying what the internal
9240 macro does. For example, @code{AC_PATH_X} has internal macros
9241 @code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
9243 @node Reporting Messages
9244 @section Reporting Messages
9245 @cindex Messages, from @command{autoconf}
9247 When macros statically diagnose abnormal situations, benign or fatal,
9248 they should report them using these macros. For dynamic issues, i.e.,
9249 when @command{configure} is run, see @ref{Printing Messages}.
9251 @defmac AC_DIAGNOSE (@var{category}, @var{message})
9253 Report @var{message} as a warning (or as an error if requested by the
9254 user) if warnings of the @var{category} are turned on. You are
9255 encouraged to use standard categories, which currently include:
9259 messages that don't fall into one of the following categories. Use of an
9260 empty @var{category} is equivalent.
9263 related to cross compilation issues.
9266 use of an obsolete construct.
9269 dubious syntactic constructs, incorrectly ordered macro calls.
9273 @defmac AC_WARNING (@var{message})
9275 Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
9276 strongly encouraged to use a finer grained category.
9279 @defmac AC_FATAL (@var{message})
9281 Report a severe error @var{message}, and have @command{autoconf} die.
9284 When the user runs @samp{autoconf -W error}, warnings from
9285 @code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
9286 @ref{autoconf Invocation}.
9288 @node Dependencies Between Macros
9289 @section Dependencies Between Macros
9290 @cindex Dependencies between macros
9292 Some Autoconf macros depend on other macros having been called first in
9293 order to work correctly. Autoconf provides a way to ensure that certain
9294 macros are called if needed and a way to warn the user if macros are
9295 called in an order that might cause incorrect operation.
9298 * Prerequisite Macros:: Ensuring required information
9299 * Suggested Ordering:: Warning about possible ordering problems
9300 * One-Shot Macros:: Ensuring a macro is called only once
9303 @node Prerequisite Macros
9304 @subsection Prerequisite Macros
9305 @cindex Prerequisite macros
9306 @cindex Macros, prerequisites
9308 A macro that you write might need to use values that have previously
9309 been computed by other macros. For example, @code{AC_DECL_YYTEXT}
9310 examines the output of @code{flex} or @code{lex}, so it depends on
9311 @code{AC_PROG_LEX} having been called first to set the shell variable
9314 Rather than forcing the user of the macros to keep track of the
9315 dependencies between them, you can use the @code{AC_REQUIRE} macro to do
9316 it automatically. @code{AC_REQUIRE} can ensure that a macro is only
9317 called if it is needed, and only called once.
9319 @defmac AC_REQUIRE (@var{macro-name})
9321 If the M4 macro @var{macro-name} has not already been called, call it
9322 (without any arguments). Make sure to quote @var{macro-name} with
9323 square brackets. @var{macro-name} must have been defined using
9324 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
9325 that it has been called.
9327 @code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
9328 must not be called from the top level.
9331 @code{AC_REQUIRE} is often misunderstood. It really implements
9332 dependencies between macros in the sense that if one macro depends upon
9333 another, the latter will be expanded @emph{before} the body of the
9334 former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
9335 body of @code{FOO}. For instance, this definition of macros:
9339 AC_DEFUN([TRAVOLTA],
9340 [test "$body_temperature_in_celsius" -gt "38" &&
9341 dance_floor=occupied])
9342 AC_DEFUN([NEWTON_JOHN],
9343 [test "$hair_style" = "curly" &&
9344 dance_floor=occupied])
9348 AC_DEFUN([RESERVE_DANCE_FLOOR],
9349 [if date | grep '^Sat.*pm' >/dev/null 2>&1; then
9350 AC_REQUIRE([TRAVOLTA])
9351 AC_REQUIRE([NEWTON_JOHN])
9357 with this @file{configure.ac}
9360 AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org])
9362 if test "$dance_floor" = occupied; then
9363 AC_MSG_ERROR([cannot pick up here, let's move])
9368 will not leave you with a better chance to meet a kindred soul at
9369 other times than Saturday night since it expands into:
9373 test "$body_temperature_in_Celsius" -gt "38" &&
9374 dance_floor=occupied
9375 test "$hair_style" = "curly" &&
9376 dance_floor=occupied
9378 if date | grep '^Sat.*pm' >/dev/null 2>&1; then
9385 This behavior was chosen on purpose: (i) it prevents messages in
9386 required macros from interrupting the messages in the requiring macros;
9387 (ii) it avoids bad surprises when shell conditionals are used, as in:
9392 AC_REQUIRE([SOME_CHECK])
9400 You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
9401 macro. You can use @code{dnl} to avoid the empty lines they leave.
9403 @node Suggested Ordering
9404 @subsection Suggested Ordering
9405 @cindex Macros, ordering
9406 @cindex Ordering macros
9408 Some macros should be run before another macro if both are called, but
9409 neither @emph{requires} that the other be called. For example, a macro
9410 that changes the behavior of the C compiler should be called before any
9411 macros that run the C compiler. Many of these dependencies are noted in
9414 Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
9415 with this kind of dependency appear out of order in a
9416 @file{configure.ac} file. The warning occurs when creating
9417 @command{configure} from @file{configure.ac}, not when running
9418 @command{configure}.
9420 For example, @code{AC_PROG_CPP} checks whether the C compiler
9421 can run the C preprocessor when given the @option{-E} option. It should
9422 therefore be called after any macros that change which C compiler is
9423 being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
9426 AC_BEFORE([$0], [AC_PROG_CPP])dnl
9430 This warns the user if a call to @code{AC_PROG_CPP} has already occurred
9431 when @code{AC_PROG_CC} is called.
9433 @defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
9435 Make M4 print a warning message to the standard error output if
9436 @var{called-macro-name} has already been called. @var{this-macro-name}
9437 should be the name of the macro that is calling @code{AC_BEFORE}. The
9438 macro @var{called-macro-name} must have been defined using
9439 @code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
9440 that it has been called.
9443 @node One-Shot Macros
9444 @subsection One-Shot Macros
9445 @cindex One-shot macros
9446 @cindex Macros, called once
9448 Some macros should be called only once, either because calling them
9449 multiple time is unsafe, or because it is bad style. For instance
9450 Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins
9451 (@pxref{Canonicalizing}) are evaluated only once, because it makes no
9452 sense to run these expensive checks more than once. Such one-shot
9453 macros can be defined using @code{AC_DEFUN_ONCE}.
9455 @defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body})
9456 @acindex{DEFUN_ONCE}
9458 Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro
9459 Definitions}), and emit a warning any time the macro is called more than
9463 Obviously it is not sensible to evaluate a macro defined by
9464 @code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}, most of the
9465 times you will want to use @code{AC_REQUIRE} (@pxref{Prerequisite
9468 @node Obsoleting Macros
9469 @section Obsoleting Macros
9470 @cindex Obsoleting macros
9471 @cindex Macros, obsoleting
9473 Configuration and portability technology has evolved over the years.
9474 Often better ways of solving a particular problem are developed, or
9475 ad-hoc approaches are systematized. This process has occurred in many
9476 parts of Autoconf. One result is that some of the macros are now
9477 considered @dfn{obsolete}; they still work, but are no longer considered
9478 the best thing to do, hence they should be replaced with more modern
9479 macros. Ideally, @command{autoupdate} should replace the old macro calls
9480 with their modern implementation.
9482 Autoconf provides a simple means to obsolete a macro.
9484 @defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
9486 Define @var{old-macro} as @var{implementation}. The only difference
9487 with @code{AC_DEFUN} is that the user will be warned that
9488 @var{old-macro} is now obsolete.
9490 If she then uses @command{autoupdate}, the call to @var{old-macro} will be
9491 replaced by the modern @var{implementation}. @var{message} should
9492 include information on what to do after running @command{autoupdate};
9493 @command{autoupdate} will print it as a warning, and include it
9494 in the updated @file{configure.ac} file.
9498 @section Coding Style
9499 @cindex Coding style
9501 The Autoconf macros follow a strict coding style. You are encouraged to
9502 follow this style, especially if you intend to distribute your macro,
9503 either by contributing it to Autoconf itself, or via other means.
9505 The first requirement is to pay great attention to the quotation. For
9506 more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
9508 Do not try to invent new interfaces. It is likely that there is a macro
9509 in Autoconf that resembles the macro you are defining: try to stick to
9510 this existing interface (order of arguments, default values, etc.). We
9511 @emph{are} conscious that some of these interfaces are not perfect;
9512 nevertheless, when harmless, homogeneity should be preferred over
9515 Be careful about clashes both between M4 symbols and between shell
9518 If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
9519 you are unlikely to generate conflicts. Nevertheless, when you need to
9520 set a special value, @emph{avoid using a regular macro name}; rather,
9521 use an ``impossible'' name. For instance, up to version 2.13, the macro
9522 @code{AC_SUBST} used to remember what @var{symbol}s were already defined
9523 by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
9524 But since there is a macro named @code{AC_SUBST_FILE}, it was just
9525 impossible to @samp{AC_SUBST(FILE)}! In this case,
9526 @code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
9527 have been used (yes, with the parentheses)@dots{}or better yet, high-level
9528 macros such as @code{AC_EXPAND_ONCE}.
9530 No Autoconf macro should ever enter the user-variable name space; i.e.,
9531 except for the variables that are the actual result of running the
9532 macro, all shell variables should start with @code{ac_}. In
9533 addition, small macros or any macro that is likely to be embedded in
9534 other macros should be careful not to use obvious names.
9537 Do not use @code{dnl} to introduce comments: most of the comments you
9538 are likely to write are either header comments which are not output
9539 anyway, or comments that should make their way into @file{configure}.
9540 There are exceptional cases where you do want to comment special M4
9541 constructs, in which case @code{dnl} is right, but keep in mind that it
9544 M4 ignores the leading blanks and newlines before each argument.
9546 indent in such a way that arguments are (more or less) aligned with the
9547 opening parenthesis of the macro being called. For instance, instead of
9550 AC_CACHE_CHECK(for EMX OS/2 environment,
9552 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
9553 [ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
9560 AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
9561 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
9563 [ac_cv_emxos2=no])])
9570 AC_CACHE_CHECK([for EMX OS/2 environment],
9572 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
9573 [return __EMX__;])],
9575 [ac_cv_emxos2=no])])
9578 When using @code{AC_RUN_IFELSE} or any macro that cannot work when
9579 cross-compiling, provide a pessimistic value (typically @samp{no}).
9581 Feel free to use various tricks to prevent auxiliary tools, such as
9582 syntax-highlighting editors, from behaving improperly. For instance,
9586 m4_bpatsubst([$1], [$"])
9593 m4_bpatsubst([$1], [$""])
9597 so that Emacsen do not open an endless ``string'' at the first quote.
9598 For the same reasons, avoid:
9612 Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
9613 breaking the bracket-matching highlighting from Emacsen. Note the
9614 preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
9615 not escape when it is unnecessary. Common examples of useless quotation
9616 are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
9617 etc. If you add portability issues to the picture, you'll prefer
9618 @samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
9619 better than hacking Autoconf @code{:-)}.
9621 When using @command{sed}, don't use @option{-e} except for indenting
9622 purpose. With the @code{s} command, the preferred separator is @samp{/}
9623 unless @samp{/} itself is used in the command, in which case you should
9626 @xref{Macro Definitions}, for details on how to define a macro. If a
9627 macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
9628 object of an @code{AC_REQUIRE} directive, then use @code{m4_define}. In
9629 case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
9630 statements should be at the beginning of the macro, @code{dnl}'ed.
9632 You should not rely on the number of arguments: instead of checking
9633 whether an argument is missing, test that it is not empty. It provides
9634 both a simpler and a more predictable interface to the user, and saves
9635 room for further arguments.
9637 Unless the macro is short, try to leave the closing @samp{])} at the
9638 beginning of a line, followed by a comment that repeats the name of the
9639 macro being defined. This introduces an additional newline in
9640 @command{configure}; normally, that is not a problem, but if you want to
9641 remove it you can use @samp{[]dnl} on the last line. You can similarly
9642 use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
9643 is recommended instead of @samp{dnl} to ensure that M4 does not
9644 interpret the @samp{dnl} as being attached to the preceding text or
9645 macro output. For example, instead of:
9648 AC_DEFUN([AC_PATH_X],
9649 [AC_MSG_CHECKING([for X])
9651 @r{# @dots{}omitted@dots{}}
9652 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
9660 AC_DEFUN([AC_PATH_X],
9661 [AC_REQUIRE_CPP()[]dnl
9662 AC_MSG_CHECKING([for X])
9663 @r{# @dots{}omitted@dots{}}
9664 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
9669 If the macro is long, try to split it into logical chunks. Typically,
9670 macros that check for a bug in a function and prepare its
9671 @code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
9672 this setup. Do not hesitate to introduce auxiliary macros to factor
9675 In order to highlight the recommended coding style, here is a macro
9676 written the old way:
9679 dnl Check for EMX on OS/2.
9681 AC_DEFUN(_AC_EMXOS2,
9682 [AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
9683 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
9684 ac_cv_emxos2=yes, ac_cv_emxos2=no)])
9685 test "$ac_cv_emxos2" = yes && EMXOS2=yes])
9694 # Check for EMX on OS/2.
9695 m4_define([_AC_EMXOS2],
9696 [AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
9697 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
9699 [ac_cv_emxos2=no])])
9700 test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
9707 @c ============================================= Portable Shell Programming
9709 @node Portable Shell
9710 @chapter Portable Shell Programming
9711 @cindex Portable shell programming
9713 When writing your own checks, there are some shell-script programming
9714 techniques you should avoid in order to make your code portable. The
9715 Bourne shell and upward-compatible shells like the Korn shell and Bash
9716 have evolved over the years, but to prevent trouble, do not take
9717 advantage of features that were added after Unix version 7, circa
9718 1977 (@pxref{Systemology}).
9720 You should not use shell functions, aliases, negated character
9721 classes, or other features that are not found in all Bourne-compatible
9722 shells; restrict yourself to the lowest common denominator. Even
9723 @code{unset} is not supported by all shells!
9725 Some old systems have quite
9726 small limits on the length of the @samp{#!} line; for instance, 32
9727 bytes (not including the newline) on SunOS 4.
9728 A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984)
9729 required a single space between the @samp{#!} and the @samp{/}, but
9730 these are no longer of practical concern.
9732 The set of external programs you should run in a @command{configure} script
9733 is fairly small. @xref{Utilities in Makefiles,, Utilities in
9734 Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This
9735 restriction allows users to start out with a fairly small set of
9736 programs and build the rest, avoiding too many interdependencies between
9739 Some of these external utilities have a portable subset of features; see
9740 @ref{Limitations of Usual Tools}.
9742 There are other sources of documentation about shells. See for instance
9743 @uref{http://www.faqs.org/faqs/unix-faq/shell/, the Shell FAQs}.
9746 * Shellology:: A zoology of shells
9747 * Here-Documents:: Quirks and tricks
9748 * File Descriptors:: FDs and redirections
9749 * File System Conventions:: File names
9750 * Shell Substitutions:: Variable and command expansions
9751 * Assignments:: Varying side effects of assignments
9752 * Parentheses:: Parentheses in shell scripts
9753 * Slashes:: Slashes in shell scripts
9754 * Special Shell Variables:: Variables you should not change
9755 * Limitations of Builtins:: Portable use of not so portable /bin/sh
9756 * Limitations of Usual Tools:: Portable use of portable tools
9757 * Limitations of Make:: Portable Makefiles
9764 There are several families of shells, most prominently the Bourne family
9765 and the C shell family which are deeply incompatible. If you want to
9766 write portable shell scripts, avoid members of the C shell family. The
9767 @uref{http://www.faqs.org/faqs/unix-faq/shell/shell-differences/, the
9768 Shell difference FAQ} includes a small history of Posix shells, and a
9769 comparison between several of them.
9771 Below we describe some of the members of the Bourne shell family.
9776 Ash is often used on @acronym{GNU}/Linux and @acronym{BSD}
9777 systems as a light-weight Bourne-compatible shell. Ash 0.2 has some
9778 bugs that are fixed in the 0.3.x series, but portable shell scripts
9779 should work around them, since version 0.2 is still shipped with many
9780 @acronym{GNU}/Linux distributions.
9782 To be compatible with Ash 0.2:
9786 don't use @samp{$?} after expanding empty or unset variables,
9787 or at the start of an @command{eval}:
9793 echo "Do not use it: $?"
9795 eval 'echo "Do not use it: $?"'
9799 don't use command substitution within variable expansion:
9806 beware that single builtin substitutions are not performed by a
9807 subshell, hence their effect applies to the current shell! @xref{Shell
9808 Substitutions}, item ``Command Substitution''.
9813 To detect whether you are running Bash, test whether
9814 @code{BASH_VERSION} is set. To require
9815 Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX
9816 Mode,, Bash Posix Mode, bash, The @acronym{GNU} Bash Reference
9817 Manual}, for details.
9819 @item Bash 2.05 and later
9820 @cindex Bash 2.05 and later
9821 Versions 2.05 and later of Bash use a different format for the
9822 output of the @command{set} builtin, designed to make evaluating its
9823 output easier. However, this output is not compatible with earlier
9824 versions of Bash (or with many other shells, probably). So if
9825 you use Bash 2.05 or higher to execute @command{configure},
9826 you'll need to use Bash 2.05 for all other build tasks as well.
9832 @prindex @samp{ksh88}
9833 @prindex @samp{ksh93}
9834 The Korn shell is compatible with the Bourne family and it mostly
9835 conforms to Posix. It has two major variants commonly
9836 called @samp{ksh88} and @samp{ksh93}, named after the years of initial
9837 release. It is usually called @command{ksh}, but is called @command{sh}
9838 on some hosts if you set your path appropriately.
9840 Solaris systems have three variants:
9841 @prindex @command{/usr/bin/ksh} on Solaris
9842 @command{/usr/bin/ksh} is @samp{ksh88}; it is
9843 standard on Solaris 2.0 and later.
9844 @prindex @command{/usr/xpg4/bin/sh} on Solaris
9845 @command{/usr/xpg4/bin/sh} is a Posix-compliant variant of
9846 @samp{ksh88}; it is standard on Solaris 9 and later.
9847 @prindex @command{/usr/dt/bin/dtksh} on Solaris
9848 @command{/usr/dt/bin/dtksh} is @samp{ksh93}.
9849 Variants that are not standard may be parts of optional
9850 packages. There is no extra charge for these packages, but they are
9851 not part of a minimal OS install and therefore some installations may
9854 Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh}
9855 is also available as @command{/usr/bin/posix/sh}. If the environment
9856 variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
9857 the standard shell conform to Posix.
9860 @prindex @samp{pdksh}
9861 A public-domain clone of the Korn shell called @command{pdksh} is widely
9862 available: it has most of the @samp{ksh88} features along with a few of
9863 its own. Similarly to Bash, you can detect whether you are
9864 running @command{pdksh} by testing whether @code{KSH_VERSION} is set,
9865 and you can require Posix compatibility by running @samp{set
9866 -o posix}. Unfortunately, with @command{pdksh} 5.2.14 (the latest
9867 stable version as of March 2005) Posix mode is buggy and causes
9868 @command{pdksh} to depart from Posix in at least one respect:
9871 $ echo "`echo \"hello\"`"
9874 $ echo "`echo \"hello\"`"
9878 The last line of output contains spurious quotes. This is yet another
9879 reason why portable shell code should not contain
9880 @code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell
9885 To detect whether you are running @command{zsh}, test whether
9886 @code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
9887 compatible with the Bourne shell: you must execute @samp{emulate sh},
9888 and for @command{zsh} versions before 3.1.6-dev-18 you must also
9889 set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
9890 zsh, The Z Shell Manual}, for details.
9892 Zsh 3.0.8 is the native @command{sh} on Mac OS X 10.0.3.
9895 The following discussion between Russ Allbery and Robert Lipe is worth
9902 The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell
9903 leads to a permanent deadlock. Vendors don't want to break users'
9904 existing shell scripts, and there are some corner cases in the Bourne
9905 shell that are not completely compatible with a Posix shell. Thus,
9906 vendors who have taken this route will @emph{never} (OK@dots{}``never say
9907 never'') replace the Bourne shell (as @command{/bin/sh}) with a
9915 This is exactly the problem. While most (at least most System V's) do
9916 have a Bourne shell that accepts shell functions most vendor
9917 @command{/bin/sh} programs are not the Posix shell.
9919 So while most modern systems do have a shell @emph{somewhere} that meets the
9920 Posix standard, the challenge is to find it.
9923 @node Here-Documents
9924 @section Here-Documents
9925 @cindex Here documents
9926 @cindex Shell here documents
9928 Don't rely on @samp{\} being preserved just because it has no special
9929 meaning together with the next symbol. In the native @command{sh}
9930 on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with
9931 unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
9932 use @samp{\\} to get @samp{\}.
9934 With Open@acronym{BSD} 2.7's @command{sh}
9950 bash-2.04$ @kbd{cat <<EOF
9958 Many older shells (including the Bourne shell) implement here-documents
9959 inefficiently. And some shells mishandle large here-documents: for
9960 example, Solaris @command{dtksh}, which is derived from Korn shell
9961 version M-12/28/93d, mishandles variable expansion that occurs on
9962 1024-byte buffer boundaries within a here-document. Users can generally
9963 fix these problems by using a faster or more reliable shell, e.g., by
9964 using the command @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure} rather
9965 than plain @samp{./configure}.
9967 Some shells can be extremely inefficient when there are a lot of
9968 here-documents inside a single statement. For instance if your
9969 @file{configure.ac} includes something like:
9973 if <cross_compiling>; then
9974 assume this and that
9978 check something else
9986 A shell parses the whole @code{if}/@code{fi} construct, creating
9987 temporary files for each here document in it. Some shells create links
9988 for such here-documents on every @code{fork}, so that the clean-up code
9989 they had installed correctly removes them. It is creating the links
9990 that can take the shell forever.
9992 Moving the tests out of the @code{if}/@code{fi}, or creating multiple
9993 @code{if}/@code{fi} constructs, would improve the performance
9994 significantly. Anyway, this kind of construct is not exactly the
9995 typical use of Autoconf. In fact, it's even not recommended, because M4
9996 macros can't look into shell conditionals, so we may fail to expand a
9997 macro when it was expanded before in a conditional path, and the
9998 condition turned out to be false at run-time, and we end up not
9999 executing the macro at all.
10001 @node File Descriptors
10002 @section File Descriptors
10003 @cindex Descriptors
10004 @cindex File descriptors
10005 @cindex Shell file descriptors
10007 Some file descriptors shall not be used, since some systems, admittedly
10008 arcane, use them for special purpose:
10011 3 --- some systems may open it to @samp{/dev/tty}.
10012 4 --- used on the Kubota Titan.
10015 Don't redirect the same file descriptor several times, as you are doomed
10016 to failure under Ultrix.
10019 ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
10021 $ @kbd{eval 'echo matter >fullness' >void}
10023 $ @kbd{eval '(echo matter >fullness)' >void}
10025 $ @kbd{(eval '(echo matter >fullness)') >void}
10026 Ambiguous output redirect.
10030 In each case the expected result is of course @file{fullness} containing
10031 @samp{matter} and @file{void} being empty.
10033 Don't try to redirect the standard error of a command substitution: it
10034 must be done @emph{inside} the command substitution: when running
10035 @samp{: `cd /zorglub` 2>/dev/null} expect the error message to
10036 escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
10038 It is worth noting that Zsh (but not Ash nor Bash) makes it possible
10039 in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
10041 Most shells, if not all (including Bash, Zsh, Ash), output traces on
10042 stderr, even for sub-shells. This might result in undesirable content
10043 if you meant to capture the standard-error output of the inner command:
10046 $ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
10048 + eval echo foo >&2
10051 $ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
10053 + eval 'echo foo >&2'
10056 $ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
10057 @i{# Traces on startup files deleted here.}
10059 +zsh:1> eval echo foo >&2
10065 You'll appreciate the various levels of detail@enddots{}
10067 One workaround is to grep out uninteresting lines, hoping not to remove
10068 good ones@enddots{}
10070 Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
10071 bar}; see @ref{Limitations of Builtins}, @command{mv} for more details.
10073 Don't rely on open file descriptors being open in child processes. In
10074 @command{ksh}, file descriptors above 2 which are opened using
10075 @samp{exec n>file} are closed by a subsequent @samp{exec} (such as
10076 that involved in the fork-and-exec which runs a program or script).
10077 Thus, using sh, we have:
10096 Within the process which runs the @samp{descrips} script, file
10097 descriptor number 5 is closed.
10099 @node File System Conventions
10100 @section File System Conventions
10101 @cindex File system conventions
10103 Autoconf uses shell-script processing extensively, so the file names
10104 that it processes should not contain characters that are special to the
10105 shell. Special characters include space, tab, newline, @sc{nul}, and
10109 " # $ & ' ( ) * ; < = > ? [ \ ` |
10112 Also, file names should not begin with @samp{~} or @samp{-}, and should
10113 not contain @samp{-} immediately after @samp{/}.
10115 These restrictions apply not only to the files that you distribute, but
10116 also to the absolute file names of your source, build, and destination
10117 directories. Autoconf-generated @command{configure} scripts warn of
10118 violations to the above restrictions.
10120 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
10121 they should be avoided.
10123 While @command{autoconf} and friends will usually be run on some Posix
10124 variety, it can and will be used on other systems, most notably @acronym{DOS}
10125 variants. This impacts several assumptions regarding file names.
10128 For example, the following code:
10135 foo_dir=$dots$foo_dir ;;
10140 will fail to properly detect absolute file names on those systems, because
10141 they can use a drivespec, and will usually use a backslash as directory
10142 separator. If you want to be portable to @acronym{DOS} variants (at the
10143 price of rejecting valid but oddball Posix file names like @file{a:\b}),
10144 you can check for absolute file names like this:
10148 [\\/]* | ?:[\\/]* ) # Absolute
10151 foo_dir=$dots$foo_dir ;;
10156 Make sure you quote the brackets if appropriate and keep the backslash as
10157 first character (@pxref{Limitations of Builtins}).
10159 Also, because the colon is used as part of a drivespec, these systems don't
10160 use it as path separator. When creating or accessing paths, you can use the
10161 @code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
10162 to the appropriate value (@samp{:} or @samp{;}) when it starts up.
10164 File names need extra care as well. While @acronym{DOS} variants
10165 that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP}) will
10166 usually be able to handle long file names properly, there are still
10167 limitations that can seriously break packages. Several of these issues
10168 can be easily detected by the
10169 @uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
10172 A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
10173 indicate where they apply: @sc{sfn} means the issues are only relevant to
10174 plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows
10175 variants, while @sc{lfn} identifies problems that exist even under
10176 Microsoft Windows variants.
10179 @item No multiple dots (@sc{sfn})
10180 @acronym{DOS} cannot handle multiple dots in file names. This is an especially
10181 important thing to remember when building a portable configure script,
10182 as @command{autoconf} uses a .in suffix for template files.
10184 This is perfectly OK on Posix variants:
10187 AC_CONFIG_HEADERS([config.h])
10188 AC_CONFIG_FILES([source.c foo.bar])
10193 but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in},
10194 @samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
10195 to @acronym{DOS}-based environments, you should use this instead:
10198 AC_CONFIG_HEADERS([config.h:config.hin])
10199 AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
10203 @item No leading dot (@sc{sfn})
10204 @acronym{DOS} cannot handle file names that start with a dot. This is usually
10205 not a very important issue for @command{autoconf}.
10207 @item Case insensitivity (@sc{lfn})
10208 @acronym{DOS} is case insensitive, so you cannot, for example, have both a
10209 file called @samp{INSTALL} and a directory called @samp{install}. This
10210 also affects @command{make}; if there's a file called @samp{INSTALL} in
10211 the directory, @samp{make install} will do nothing (unless the
10212 @samp{install} target is marked as PHONY).
10214 @item The 8+3 limit (@sc{sfn})
10215 Because the @acronym{DOS} file system only stores the first 8 characters of
10216 the file name and the first 3 of the extension, those must be unique.
10217 That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
10218 @file{foobar-prettybird.c} all resolve to the same file name
10219 (@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
10220 @file{foo.bartender}.
10222 The 8+3 limit is not usually a problem under Microsoft Windows, as it
10224 tails in the short version of file names to make them unique. However, a
10225 registry setting can turn this behavior off. While this makes it
10226 possible to share file trees containing long file names between @sc{sfn}
10227 and @sc{lfn} environments, it also means the above problem applies there
10230 @item Invalid characters (@sc{lfn})
10231 Some characters are invalid in @acronym{DOS} file names, and should therefore
10232 be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
10233 @samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
10234 In a @sc{sfn} environment, other characters are also invalid. These
10235 include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
10237 @item Invalid names (@sc{lfn})
10238 Some @acronym{DOS} file names are reserved, and cause problems if you
10239 try to use files with those names. These names include @file{CON},
10240 @file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4},
10241 @file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}.
10242 File names are case insensitive, so even names like
10243 @file{aux/config.guess} are disallowed.
10247 @node Shell Substitutions
10248 @section Shell Substitutions
10249 @cindex Shell substitutions
10251 Contrary to a persistent urban legend, the Bourne shell does not
10252 systematically split variables and back-quoted expressions, in particular
10253 on the right-hand side of assignments and in the argument of @code{case}.
10254 For instance, the following code:
10257 case "$given_srcdir" in
10258 .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
10259 *) top_srcdir="$dots$given_srcdir" ;;
10264 is more readable when written as:
10267 case $given_srcdir in
10268 .) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
10269 *) top_srcdir=$dots$given_srcdir ;;
10274 and in fact it is even @emph{more} portable: in the first case of the
10275 first attempt, the computation of @code{top_srcdir} is not portable,
10276 since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
10277 Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
10278 the same way. There is just no portable way to use double-quoted
10279 strings inside double-quoted back-quoted expressions (pfew!).
10283 @cindex @samp{"$@@"}
10284 One of the most famous shell-portability issues is related to
10285 @samp{"$@@"}. When there are no positional arguments, Posix says
10286 that @samp{"$@@"} is supposed to be equivalent to nothing, but the
10287 original Unix version 7 Bourne shell treated it as equivalent to
10288 @samp{""} instead, and this behavior survives in later implementations
10289 like Digital Unix 5.0.
10291 The traditional way to work around this portability problem is to use
10292 @samp{$@{1+"$@@"@}}. Unfortunately this method does not work with
10293 Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating
10294 the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}:
10297 zsh $ @kbd{emulate sh}
10298 zsh $ @kbd{for i in "$@@"; do echo $i; done}
10301 zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done}
10308 Zsh handles plain @samp{"$@@"} properly, but we can't use plain
10309 @samp{"$@@"} because of the portability problems mentioned above.
10310 One workaround relies on Zsh's ``global aliases'' to convert
10311 @samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself:
10314 test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"'
10317 A more conservative workaround is to avoid @samp{"$@@"} if it is
10318 possible that there may be no positional arguments. For example,
10322 cat conftest.c "$@@"
10325 you can use this instead:
10329 0) cat conftest.c;;
10330 *) cat conftest.c "$@@";;
10336 @cindex positional parameters
10337 The 10th, 11th, @dots{} positional parameters can be accessed only after
10338 a @code{shift}. The 7th edition shell reported an error if given @code{$@{10@}};
10339 Solaris 10 @command{/bin/sh} still acts that way:
10342 $ @kbd{set 1 2 3 4 5 6 7 8 9 10}
10343 $ @kbd{echo $@{10@}}
10347 @item $@{@var{var}:-@var{value}@}
10348 @c Info cannot handle `:' in index entries.
10349 @c @cindex $@{@var{var}:-@var{value}@}
10350 Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the
10351 colon for any shell substitution, and complain and die.
10353 @item $@{@var{var}=@var{literal}@}
10354 @cindex $@{@var{var}=@var{literal}@}
10358 : $@{var='Some words'@}
10362 otherwise some shells, such as on Digital Unix V 5.0, will die because
10363 of a ``bad substitution''.
10367 Solaris @command{/bin/sh} has a frightening bug in its interpretation
10368 of this. Imagine you need set a variable to a string containing
10369 @samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh}
10370 when the affected variable was already set. This bug can be exercised
10375 $ @kbd{foo=$@{foo='@}'@}}
10378 $ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
10381 $ @kbd{foo=$@{foo='@}'@}}
10387 It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
10388 though it is enclosed in single quotes. The problem doesn't happen
10389 using double quotes.
10391 @item $@{@var{var}=@var{expanded-value}@}
10392 @cindex $@{@var{var}=@var{expanded-value}@}
10398 : $@{var="$default"@}
10402 will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
10403 each char will be set. You won't observe the phenomenon using a simple
10404 @samp{echo $var} since apparently the shell resets the 8th bit when it
10405 expands $var. Here are two means to make this shell confess its sins:
10408 $ @kbd{cat -v <<EOF
10417 $ @kbd{set | grep '^var=' | cat -v}
10420 One classic incarnation of this bug is:
10424 : $@{list="$default"@}
10431 You'll get @samp{a b c} on a single line. Why? Because there are no
10432 spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
10433 bit set, hence no IFS splitting is performed!!!
10435 One piece of good news is that Ultrix works fine with @samp{:
10436 $@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
10437 then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of
10440 The portable way out consists in using a double assignment, to switch
10441 the 8th bit twice on Ultrix:
10444 list=$@{list="$default"@}
10448 @dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
10452 test "$@{var+set@}" = set || var=@var{@{value@}}
10456 @item `@var{commands}`
10457 @cindex `@var{commands}`
10458 @cindex Command Substitution
10459 Posix requires shells to trim all trailing newlines from command
10460 output before substituting it, so assignments like
10461 @samp{dir=`AS_DIRNAME(["$file"])`} will not work as expected if the
10462 directory of @samp{$file} ends in a newline.
10464 While in general it makes no sense, do not substitute a single builtin
10465 with side effects, because Ash 0.2, trying to optimize, does not fork a
10466 subshell to perform the command.
10468 For instance, if you wanted to check that @command{cd} is silent, do not
10469 use @samp{test -z "`cd /`"} because the following can happen:
10474 $ @kbd{test -z "`cd /`" && pwd}
10479 The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
10482 @item $(@var{commands})
10483 @cindex $(@var{commands})
10484 This construct is meant to replace @samp{`@var{commands}`},
10485 and it has most of the problems listed under @code{`@var{commands}`}.
10487 This construct can be
10488 nested while this is impossible to do portably with back quotes.
10489 Unfortunately it is not yet universally supported. Most notably, even recent
10490 releases of Solaris don't support it:
10493 $ @kbd{showrev -c /bin/sh | grep version}
10494 Command version: SunOS 5.10 Generic January 2005
10495 $ @kbd{echo $(echo blah)}
10496 syntax error: `(' unexpected
10500 nor does @sc{irix} 6.5's Bourne shell:
10503 IRIX firebird-image 6.5 07151432 IP22
10504 $ @kbd{echo $(echo blah)}
10508 If you do use @samp{$(@var{commands})}, make sure that the commands
10509 do not start with a parenthesis, as that would cause confusion with
10510 a different notation @samp{$((@var{expression}))} that in modern
10511 shells is an arithmetic expression not a command. To avoid the
10512 confusion, insert a space between the two opening parentheses.
10518 @section Assignments
10519 @cindex Shell assignments
10521 When setting several variables in a row, be aware that the order of the
10522 evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
10523 gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash.
10525 @samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
10527 Don't rely on the following to find @file{subdir/program}:
10530 PATH=subdir$PATH_SEPARATOR$PATH program
10534 as this does not work with Zsh 3.0.6. Use something like this
10538 (PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program)
10541 Don't rely on the exit status of an assignment: Ash 0.2 does not change
10542 the status and propagates that of the last statement:
10545 $ @kbd{false || foo=bar; echo $?}
10547 $ @kbd{false || foo=`:`; echo $?}
10552 and to make things even worse, @acronym{QNX} 4.25 just sets the exit status
10556 $ @kbd{foo=`exit 1`; echo $?}
10560 To assign default values, follow this algorithm:
10564 If the default value is a literal and does not contain any closing
10568 : $@{var='my literal'@}
10572 If the default value contains no closing brace, has to be expanded, and
10573 the variable being initialized will never be IFS-split (i.e., it's not a
10577 : $@{var="$default"@}
10581 If the default value contains no closing brace, has to be expanded, and
10582 the variable being initialized will be IFS-split (i.e., it's a list),
10586 var=$@{var="$default"@}
10590 If the default value contains a closing brace, then use:
10593 test "$@{var+set@}" = set || var='$@{indirection@}'
10597 In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
10598 doubt, just use the latter. @xref{Shell Substitutions}, items
10599 @samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
10603 @section Parentheses in Shell Scripts
10604 @cindex Shell parentheses
10606 Beware of two opening parentheses in a row, as some shell
10607 implementations mishandle them. For example, @samp{pdksh} 5.2.14
10608 misparses the following code:
10611 if ((true) || false); then
10617 To work around this problem, insert a space between the two opening
10618 parentheses. There is a similar problem and workaround with
10619 @samp{$((}; see @ref{Shell Substitutions}.
10621 Posix requires support for @code{case} patterns with opening
10622 parentheses like this:
10626 (*.c) echo "C source code";;
10631 but the @code{(} in this example is not portable to many older Bourne
10632 shell implementations. It can be omitted safely.
10635 @section Slashes in Shell Scripts
10636 @cindex Shell slashes
10638 Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line
10639 arguments that contain two trailing slashes:
10642 $ echo / // /// //// .// //.
10648 $ echo abc | tr -t ab //
10654 However, our understanding is that patches are available, so perhaps
10655 it's not worth worrying about working around this horrendous bug.
10657 @node Special Shell Variables
10658 @section Special Shell Variables
10659 @cindex Shell variables
10660 @cindex Special shell variables
10662 Some shell variables should not be used, since they can have a deep
10663 influence on the behavior of the shell. In order to recover a sane
10664 behavior from the shell, some variables should be unset, but
10665 @command{unset} is not portable (@pxref{Limitations of Builtins}) and a
10666 fallback value is needed.
10668 As a general rule, shell variable names containing a lower-case letter
10669 are safe; you can define and use these variables without worrying about
10670 their effect on the underlying system, and without worrying about
10671 whether the shell will change them unexpectedly. (The exception is the
10672 shell variable @code{status}, as described below.)
10674 Here is a list of names that are known to cause trouble. This list is
10675 not exhaustive, but you should be safe if you avoid the name
10676 @code{status} and names containing only upper-case letters and
10679 @c Alphabetical order, case insensitive, `A' before `a'.
10682 Many shells reserve @samp{$_} for various purposes, e.g., the name of
10683 the last command executed.
10687 In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of
10688 the standard shell conform to Posix.
10689 Autoconf-generated scripts export this variable when they start up.
10693 When this variable is set it specifies a list of directories to search
10694 when invoking @code{cd} with a relative file name. Posix
10695 1003.1-2001 says that if a nonempty directory name from @env{CDPATH}
10696 is used successfully, @code{cd} prints the resulting absolute
10697 file name. Unfortunately this output can break idioms like
10698 @samp{abs=`cd src && pwd`} because @code{abs} receives the name twice.
10699 Also, many shells do not conform to this part of Posix; for
10700 example, @command{zsh} prints the result only if a directory name
10701 other than @file{.} was chosen from @env{CDPATH}.
10703 In practice the shells that have this problem also support
10704 @command{unset}, so you can work around the problem as follows:
10707 (unset CDPATH) >/dev/null 2>&1 && unset CDPATH
10710 Autoconf-generated scripts automatically unset @env{CDPATH} if
10711 possible, so you need not worry about this problem in those scripts.
10715 In the MKS shell, case statements and file name generation are
10716 case-insensitive unless @env{DUALCASE} is nonzero.
10717 Autoconf-generated scripts export this variable when they start up.
10731 These variables should not matter for shell scripts, since they are
10732 supposed to affect only interactive shells. However, at least one
10733 shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about
10734 whether it is interactive, which means that (for example) a @env{PS1}
10735 with a side effect can unexpectedly modify @samp{$?}. To work around
10736 this bug, Autoconf-generated scripts do something like this:
10739 (unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH
10747 Long ago, shell scripts inherited @env{IFS} from the environment,
10748 but this caused many problems so modern shells ignore any environment
10749 settings for @env{IFS}.
10751 Don't set the first character of @code{IFS} to backslash. Indeed,
10752 Bourne shells use the first character (backslash) when joining the
10753 components in @samp{"$@@"} and some shells then re-interpret (!)@: the
10754 backslash escapes, so you can end up with backspace and other strange
10757 The proper value for @code{IFS} (in regular code, not when performing
10758 splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is
10759 especially important, as it is used to join the arguments in @samp{@@*}.
10771 @evindex LC_COLLATE
10773 @evindex LC_MESSAGES
10774 @evindex LC_MONETARY
10775 @evindex LC_NUMERIC
10778 Autoconf-generated scripts normally set all these variables to
10779 @samp{C} because so much configuration code assumes the C locale and
10780 Posix requires that locale environment variables be set to
10781 @samp{C} if the C locale is desired. However, some older, nonstandard
10782 systems (notably @acronym{SCO}) break if locale environment variables
10783 are set to @samp{C}, so when running on these systems
10784 Autoconf-generated scripts unset the variables instead.
10789 @env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU}
10790 extension that overrides @env{LC_ALL} in some cases, so
10791 Autoconf-generated scripts set it too.
10794 @itemx LC_IDENTIFICATION
10795 @itemx LC_MEASUREMENT
10798 @itemx LC_TELEPHONE
10799 @evindex LC_ADDRESS
10800 @evindex LC_IDENTIFICATION
10801 @evindex LC_MEASUREMENT
10804 @evindex LC_TELEPHONE
10806 These locale environment variables are @acronym{GNU} extensions. They
10807 are treated like their Posix brethren (@env{LC_COLLATE},
10808 etc.)@: as described above.
10811 Most modern shells provide the current line number in @code{LINENO}.
10812 Its value is the line number of the beginning of the current command.
10813 Autoconf attempts to execute @command{configure} with a modern shell.
10814 If no such shell is available, it attempts to implement @code{LINENO}
10815 with a Sed prepass that replaces each instance of the string
10816 @code{$LINENO} (not followed by an alphanumeric character) with the
10819 You should not rely on @code{LINENO} within @command{eval}, as the
10820 behavior differs in practice. Also, the possibility of the Sed
10821 prepass means that you should not rely on @code{$LINENO} when quoted,
10822 when in here-documents, or when in long commands that cross line
10823 boundaries. Subshells should be OK, though. In the following
10824 example, lines 1, 6, and 9 are portable, but the other instances of
10825 @code{LINENO} are not:
10835 ( echo 6. $LINENO )
10836 eval 'echo 7. $LINENO'
10842 $ @kbd{bash-2.05 lineno}
10853 $ @kbd{zsh-3.0.6 lineno}
10864 $ @kbd{pdksh-5.2.14 lineno}
10875 $ @kbd{sed '=' <lineno |}
10881 > @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
10884 > @kbd{ s,^[0-9]*\n,,}
10900 When executing the command @samp{>foo}, @command{zsh} executes
10901 @samp{$NULLCMD >foo} unless it is operating in Bourne shell
10902 compatibility mode and the @command{zsh} version is newer
10903 than 3.1.6-dev-18. If are using an older @command{zsh}
10904 and forget to set @env{NULLCMD},
10905 your script might be suspended waiting for data on its standard input.
10907 @item PATH_SEPARATOR
10908 @evindex PATH_SEPARATOR
10909 On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment
10910 variable can be set to either @samp{:} or @samp{;} to control the path
10911 separator Bash uses to set up certain environment variables (such as
10912 @env{PATH}). You can set this variable to @samp{;} if you want
10913 @command{configure} to use @samp{;} as a separator; this might be useful
10914 if you plan to use non-Posix shells to execute files. @xref{File System
10915 Conventions}, for more information about @code{PATH_SEPARATOR}.
10919 Posix 1003.1-2001 requires that @command{cd} and
10920 @command{pwd} must update the @env{PWD} environment variable to point
10921 to the logical name of the current directory, but traditional shells
10922 do not support this. This can cause confusion if one shell instance
10923 maintains @env{PWD} but a subsidiary and different shell does not know
10924 about @env{PWD} and executes @command{cd}; in this case @env{PWD} will
10925 point to the wrong directory. Use @samp{`pwd`} rather than
10929 Many shells provide @code{RANDOM}, a variable that returns a different
10930 integer each time it is used. Most of the time, its value does not
10931 change when it is not used, but on @sc{irix} 6.5 the value changes all
10932 the time. This can be observed by using @command{set}. It is common
10933 practice to use @code{$RANDOM} as part of a file name, but code
10934 shouldn't rely on @code{$RANDOM} expanding to a nonempty string.
10937 This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
10938 hence read-only. Do not use it.
10941 @node Limitations of Builtins
10942 @section Limitations of Shell Builtins
10943 @cindex Shell builtins
10944 @cindex Limitations of shell builtins
10946 No, no, we are serious: some shells do have limitations! :)
10948 You should always keep in mind that any builtin or command may support
10949 options, and therefore have a very different behavior with arguments
10950 starting with a dash. For instance, the innocent @samp{echo "$word"}
10951 can give unexpected results when @code{word} starts with a dash. It is
10952 often possible to avoid this problem using @samp{echo "x$word"}, taking
10953 the @samp{x} into account later in the pipe.
10957 @prindex @command{.}
10958 Use @command{.} only with regular files (use @samp{test -f}). Bash
10959 2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
10960 @command{.} uses @env{PATH} if its argument contains no slashes, so if
10961 you want to use @command{.} on a file @file{foo} in the current
10962 directory, you must use @samp{. ./foo}.
10965 @prindex @command{!}
10966 The Unix version 7 shell did not support
10967 negating the exit status of commands with @command{!}, and this feature
10968 is still absent from more modern shells (e.g., Solaris @command{/bin/sh}).
10969 Shell code like this:
10972 if ! cmp file1 file2 >/dev/null 2>&1; then
10973 echo files differ or trouble
10977 is therefore not portable in practice. Typically it is easy to rewrite
10981 cmp file1 file2 >/dev/null 2>&1 ||
10982 echo files differ or trouble
10985 More generally, one can always rewrite @samp{! @var{command}} as:
10988 if @var{command}; then (exit 1); else :; fi
10991 @item @command{break}
10992 @c ------------------
10993 @prindex @command{break}
10994 The use of @samp{break 2} etc.@: is safe.
10997 @item @command{case}
10998 @c -----------------
10999 @prindex @command{case}
11000 You don't need to quote the argument; no splitting is performed.
11002 You don't need the final @samp{;;}, but you should use it.
11004 Because of a bug in its @code{fnmatch}, Bash fails to properly
11005 handle backslashes in character classes:
11008 bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
11013 This is extremely unfortunate, since you are likely to use this code to
11014 handle Posix or @sc{ms-dos} absolute file names. To work around this
11015 bug, always put the backslash first:
11018 bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
11020 bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
11024 Many Bourne shells cannot handle closing brackets in character classes
11027 Some shells also have problems with backslash escaping in case you do not want
11028 to match the backslash: both a backslash and the escaped character match this
11029 pattern. To work around this, specify the character class in a variable, so
11030 that quote removal does not apply afterwards, and the special characters don't
11031 have to be backslash-escaped:
11034 $ @kbd{case '\' in [\<]) echo OK;; esac}
11036 $ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac}
11040 Even with this, Solaris @command{ksh} matches a backslash if the set
11042 of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}.
11044 Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches
11045 a closing parenthesis if not specified in a character class:
11048 $ @kbd{case foo in *\)*) echo fail ;; esac}
11050 $ @kbd{case foo in *')'*) echo fail ;; esac}
11054 Some shells, such as Ash 0.3.8, are confused by an empty
11055 @code{case}/@code{esac}:
11058 ash-0.3.8 $ @kbd{case foo in esac;}
11059 @error{}Syntax error: ";" unexpected (expecting ")")
11062 Many shells still do not support parenthesized cases, which is a pity
11063 for those of us using tools that rely on balanced parentheses. For
11064 instance, Solaris @command{/bin/sh}:
11067 $ @kbd{case foo in (foo) echo foo;; esac}
11068 @error{}syntax error: `(' unexpected
11074 @prindex @command{cd}
11075 Posix 1003.1-2001 requires that @command{cd} must support
11076 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
11077 with @option{-L} being the default. However, traditional shells do
11078 not support these options, and their @command{cd} command has the
11079 @option{-P} behavior.
11081 Portable scripts should assume neither option is supported, and should
11082 assume neither behavior is the default. This can be a bit tricky,
11083 since the Posix default behavior means that, for example,
11084 @samp{ls ..} and @samp{cd ..} may refer to different directories if
11085 the current logical directory is a symbolic link. It is safe to use
11086 @command{cd @var{dir}} if @var{dir} contains no @file{..} components.
11087 Also, Autoconf-generated scripts check for this problem when computing
11088 variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}),
11089 so it is safe to @command{cd} to these variables.
11091 Also please see the discussion of the @command{pwd} command.
11094 @item @command{echo}
11095 @c -----------------
11096 @prindex @command{echo}
11097 The simple @command{echo} is probably the most surprising source of
11098 portability troubles. It is not possible to use @samp{echo} portably
11099 unless both options and escape sequences are omitted. New applications
11100 which are not aiming at portability should use @samp{printf} instead of
11103 Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
11104 etc.@: for a means to simulate @option{-n}.
11106 Do not use backslashes in the arguments, as there is no consensus on
11107 their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
11108 Digital Unix 4.0 and @acronym{MIPS RISC/OS} 4.52, answer 2, but the Solaris
11109 @command{/bin/sh}, Bash, and Zsh (in @command{sh} emulation mode) report 1.
11110 Please note that the problem is truly @command{echo}: all the shells
11111 understand @samp{'\n'} as the string composed of a backslash and an
11114 Because of these problems, do not pass a string containing arbitrary
11115 characters to @command{echo}. For example, @samp{echo "$foo"} is safe
11116 if you know that @var{foo}'s value cannot contain backslashes and cannot
11117 start with @samp{-}, but otherwise you should use a here-document like
11127 @item @command{eval}
11128 @c -----------------
11129 @prindex @command{eval}
11130 In some shell implementations (e.g., older @command{ash}, OpenBSD 3.8
11131 @command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh}
11132 4.2.5), the arguments of @samp{eval} are evaluated in a context where
11133 @samp{$?} is 0, so they exhibit behavior like this:
11136 $ false; eval 'echo $?'
11140 The correct behavior here is to output a nonzero value,
11141 but portable scripts should not rely on this.
11143 You should not rely on @code{LINENO} within @command{eval}.
11144 @xref{Special Shell Variables}.
11146 @item @command{exit}
11147 @c -----------------
11148 @prindex @command{exit}
11149 The default value of @command{exit} is supposed to be @code{$?};
11150 unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just
11151 perform @samp{exit 0}.
11154 bash-2.04$ @kbd{foo=`exit 1` || echo fail}
11156 bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
11158 bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
11162 Using @samp{exit $?} restores the expected behavior.
11164 Some shell scripts, such as those generated by @command{autoconf}, use a
11165 trap to clean up before exiting. If the last shell command exited with
11166 nonzero status, the trap also exits with nonzero status so that the
11167 invoker can tell that an error occurred.
11169 Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit
11170 trap ignores the @code{exit} command's argument. In these shells, a trap
11171 cannot determine whether it was invoked by plain @code{exit} or by
11172 @code{exit 1}. Instead of calling @code{exit} directly, use the
11173 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
11176 @item @command{export}
11177 @c -------------------
11178 @prindex @command{export}
11179 The builtin @command{export} dubs a shell variable @dfn{environment
11180 variable}. Each update of exported variables corresponds to an update
11181 of the environment variables. Conversely, each environment variable
11182 received by the shell when it is launched should be imported as a shell
11183 variable marked as exported.
11185 Alas, many shells, such as Solaris @command{/bin/sh},
11186 @sc{irix} 6.3, @sc{irix} 5.2,
11187 @acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to
11188 @command{export} the environment variables they receive. As a result,
11189 two variables coexist: the environment variable and the shell
11190 variable. The following code demonstrates this failure:
11201 when run with @samp{FOO=foo} in the environment, these shells will print
11202 alternately @samp{foo} and @samp{bar}, although it should only print
11203 @samp{foo} and then a sequence of @samp{bar}s.
11205 Therefore you should @command{export} again each environment variable
11209 @item @command{false}
11210 @c ------------------
11211 @prindex @command{false}
11212 Don't expect @command{false} to exit with status 1: in native
11213 Solaris it exits with status 255.
11216 @item @command{for}
11217 @c ----------------
11218 @prindex @command{for}
11219 To loop over positional arguments, use:
11229 You may @emph{not} leave the @code{do} on the same line as @code{for},
11230 since some shells improperly grok:
11238 If you want to explicitly refer to the positional arguments, given the
11239 @samp{$@@} bug (@pxref{Shell Substitutions}), use:
11242 for arg in $@{1+"$@@"@}; do
11248 But keep in mind that Zsh, even in Bourne shell emulation mode, performs
11249 word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions},
11250 item @samp{$@@}, for more.
11255 @prindex @command{if}
11256 Using @samp{!} is not portable. Instead of:
11259 if ! cmp -s file file.new; then
11268 if cmp -s file file.new; then :; else
11273 There are shells that do not reset the exit status from an @command{if}:
11276 $ @kbd{if (exit 42); then true; fi; echo $?}
11281 whereas a proper shell should have printed @samp{0}. This is especially
11282 bad in Makefiles since it produces false failures. This is why properly
11283 written Makefiles, such as Automake's, have such hairy constructs:
11286 if test -f "$file"; then
11287 install "$file" "$dest"
11294 @item @command{printf}
11295 @c ------------------
11296 @prindex @command{printf}
11297 A format string starting with a @samp{-} can cause problems.
11298 Bash (e.g., 2.05b) will interpret it as an options string and
11299 give an error. And @samp{--} to mark the end of options is not good
11300 in the NetBSD Almquist shell (e.g., 0.4.6) which will take that
11301 literally as the format string. Putting the @samp{-} in a @samp{%c}
11302 or @samp{%s} is probably the easiest way to avoid doubt,
11309 @item @command{read}
11310 @c ------------------
11311 @prindex @command{read}
11312 Not all shells support @option{-r} (Solaris @command{/bin/sh} for example).
11315 @item @command{pwd}
11316 @c ----------------
11317 @prindex @command{pwd}
11318 With modern shells, plain @command{pwd} outputs a ``logical''
11319 directory name, some of whose components may be symbolic links. These
11320 directory names are in contrast to ``physical'' directory names, whose
11321 components are all directories.
11323 Posix 1003.1-2001 requires that @command{pwd} must support
11324 the @option{-L} (``logical'') and @option{-P} (``physical'') options,
11325 with @option{-L} being the default. However, traditional shells do
11326 not support these options, and their @command{pwd} command has the
11327 @option{-P} behavior.
11329 Portable scripts should assume neither option is supported, and should
11330 assume neither behavior is the default. Also, on many hosts
11331 @samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix
11332 does not require this behavior and portable scripts should not rely on
11335 Typically it's best to use plain @command{pwd}. On modern hosts this
11336 outputs logical directory names, which have the following advantages:
11340 Logical names are what the user specified.
11342 Physical names may not be portable from one installation
11343 host to another due to network file system gymnastics.
11345 On modern hosts @samp{pwd -P} may fail due to lack of permissions to
11346 some parent directory, but plain @command{pwd} cannot fail for this
11350 Also please see the discussion of the @command{cd} command.
11353 @item @command{set}
11354 @c ----------------
11355 @prindex @command{set}
11356 This builtin faces the usual problem with arguments starting with a
11357 dash. Modern shells such as Bash or Zsh understand @option{--} to specify
11358 the end of the options (any argument after @option{--} is a parameter,
11359 even @samp{-x} for instance), but most shells simply stop the option
11360 processing as soon as a non-option argument is found. Therefore, use
11361 @samp{dummy} or simply @samp{x} to end the option processing, and use
11362 @command{shift} to pop it out:
11365 set x $my_list; shift
11368 Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no
11369 longer requires support for this command, and in traditional shells
11370 @samp{set - $my_list} resets the @samp{-v} and @samp{-x} options, which
11371 makes scripts harder to debug.
11373 Some nonstandard shells do not recognize more than one option
11374 (e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is
11375 better to combine them:
11382 @item @command{shift}
11383 @c ------------------
11384 @prindex @command{shift}
11385 Not only is @command{shift}ing a bad idea when there is nothing left to
11386 shift, but in addition it is not portable: the shell of @acronym{MIPS
11387 RISC/OS} 4.52 refuses to do it.
11389 Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell,
11390 and it is also absent in many pre-POSIX shells.
11393 @item @command{source}
11394 @c -------------------
11395 @prindex @command{source}
11396 This command is not portable, as Posix does not require it; use
11397 @command{.} instead.
11400 @item @command{test}
11401 @c -----------------
11402 @prindex @command{test}
11403 The @code{test} program is the way to perform many file and string
11404 tests. It is often invoked by the alternate name @samp{[}, but using
11405 that name in Autoconf code is asking for trouble since it is an M4 quote
11408 If you need to make multiple checks using @code{test}, combine them with
11409 the shell operators @samp{&&} and @samp{||} instead of using the
11410 @code{test} operators @option{-a} and @option{-o}. On System V, the
11411 precedence of @option{-a} and @option{-o} is wrong relative to the unary
11412 operators; consequently, Posix does not specify them, so using them
11413 is nonportable. If you combine @samp{&&} and @samp{||} in the same
11414 statement, keep in mind that they have equal precedence.
11416 It is safe to use @samp{!} as a @command{test} operator. For example,
11417 @samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test
11418 -d foo; @dots{}} is not.
11421 @item @command{test} (files)
11422 @c -------------------------
11423 To enable @command{configure} scripts to support cross-compilation, they
11424 shouldn't do anything that tests features of the build system instead of
11425 the host system. But occasionally you may find it necessary to check
11426 whether some arbitrary file exists. To do so, use @samp{test -f} or
11427 @samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not
11428 have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh}
11429 lacks it. To test for symbolic links on systems that have them, use
11430 @samp{test -h} rather than @samp{test -L}; either form conforms to
11431 Posix 1003.1-2001, but older shells like Solaris 8
11432 @code{/bin/sh} support only @option{-h}.
11434 @item @command{test} (strings)
11435 @c ---------------------------
11436 Avoid @samp{test "@var{string}"}, in particular if @var{string} might
11437 start with a dash, since @code{test} might interpret its argument as an
11438 option (e.g., @samp{@var{string} = "-n"}).
11440 Contrary to a common belief, @samp{test -n @var{string}} and
11441 @samp{test -z @var{string}} @strong{are} portable. Nevertheless many
11442 shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6,
11443 Digital Unix 4, etc.)@: have bizarre precedence and may be confused if
11444 @var{string} looks like an operator:
11448 test: argument expected
11451 If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
11452 "x@var{string}" != x} instead.
11454 It is common to find variations of the following idiom:
11457 test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
11462 to take an action when a token matches a given pattern. Such constructs
11463 should always be avoided by using:
11466 echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
11471 Use @code{case} where possible since it is faster, being a shell builtin:
11475 case $ac_feature in
11476 *[!-a-zA-Z0-9_]*) @var{action};;
11480 Alas, negated character classes are probably not portable, although no
11481 shell is known to not support the Posix syntax @samp{[!@dots{}]}
11482 (when in interactive mode, @command{zsh} is confused by the
11483 @samp{[!@dots{}]} syntax and looks for an event in its history because of
11484 @samp{!}). Many shells do not support the alternative syntax
11485 @samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
11487 One solution can be:
11490 expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
11498 expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
11502 @samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
11503 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
11504 @samp{@var{foo}} contains backslashes.
11507 @item @command{trap}
11508 @c -----------------
11509 @prindex @command{trap}
11510 It is safe to trap at least the signals 1, 2, 13, and 15. You can also
11511 trap 0, i.e., have the @command{trap} run when the script ends (either via an
11512 explicit @command{exit}, or the end of the script).
11514 Although Posix is not absolutely clear on this point, it is widely
11515 admitted that when entering the trap @samp{$?} should be set to the exit
11516 status of the last command run before the trap. The ambiguity can be
11517 summarized as: ``when the trap is launched by an @command{exit}, what is
11518 the @emph{last} command run: that before @command{exit}, or
11519 @command{exit} itself?''
11521 Bash considers @command{exit} to be the last command, while Zsh and
11522 Solaris @command{/bin/sh} consider that when the trap is run it is
11523 @emph{still} in the @command{exit}, hence it is the previous exit status
11524 that the trap receives:
11527 $ @kbd{cat trap.sh}
11530 $ @kbd{zsh trap.sh}
11532 $ @kbd{bash trap.sh}
11536 The portable solution is then simple: when you want to @samp{exit 42},
11537 run @samp{(exit 42); exit 42}, the first @command{exit} being used to
11538 set the exit status to 42 for Zsh, and the second to trigger the trap
11539 and pass 42 as exit status for Bash.
11541 The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is
11542 reset to 0 by empty lines if the code is inside @command{trap}.
11545 $ @kbd{trap 'false}
11553 Fortunately, this bug only affects @command{trap}.
11555 @item @command{true}
11556 @c -----------------
11557 @prindex @command{true}
11558 @c Info cannot handle `:' in index entries.
11559 @c @prindex @command{:}
11560 Don't worry: as far as we know @command{true} is portable.
11561 Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
11562 portable shell community tends to prefer using @command{:}. This has a
11563 funny side effect: when asked whether @command{false} is more portable
11564 than @command{true} Alexandre Oliva answered:
11567 In a sense, yes, because if it doesn't exist, the shell will produce an
11568 exit status of failure, which is correct for @command{false}, but not
11569 for @command{true}.
11573 @item @command{unset}
11574 @c ------------------
11575 @prindex @command{unset}
11576 You cannot assume the support of @command{unset}. Nevertheless, because
11577 it is extremely useful to disable embarrassing variables such as
11578 @code{PS1}, you can test for its existence and use
11579 it @emph{provided} you give a neutralizing value when @command{unset} is
11583 if (unset FOO) >/dev/null 2>&1; then
11588 $unset PS1 || PS1='$ '
11591 @xref{Special Shell Variables}, for some neutralizing values. Also, see
11592 @ref{Limitations of Builtins}, documentation of @command{export}, for
11593 the case of environment variables.
11596 @node Limitations of Usual Tools
11597 @section Limitations of Usual Tools
11598 @cindex Limitations of usual tools
11600 The small set of tools you can expect to find on any machine can still
11601 include some limitations you should be aware of.
11605 @c ----------------
11607 Don't leave white space before the opening parenthesis in a user function call.
11608 Posix does not allow this and @acronym{GNU} Awk rejects it:
11611 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
11612 BEGIN @{ die () @}'}
11613 gawk: cmd. line:2: BEGIN @{ die () @}
11614 gawk: cmd. line:2: ^ parse error
11615 $ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
11616 BEGIN @{ die() @}'}
11620 If you want your program to be deterministic, don't depend on @code{for}
11624 $ @kbd{cat for.awk}
11631 $ @kbd{gawk -f for.awk </dev/null}
11634 $ @kbd{nawk -f for.awk </dev/null}
11639 Some Awk implementations, such as HPUX 11.0's native one, mishandle anchors:
11642 $ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
11643 $ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
11645 $ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
11647 $ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
11652 Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
11653 or use a simple test to reject such implementations.
11655 @acronym{AIX} version 5.2 has an arbitrary limit of 399 on the the
11656 length of regular expressions and literal strings in an Awk program.
11658 Traditional Awk implementations derived from Unix version 7, such as
11659 Solaris @command{/bin/awk}, have many limitations and do not
11660 conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular
11661 Programs}) will find you an Awk that doesn't have these problems, but if
11662 for some reason you prefer not to use @code{AC_PROG_AWK} you may need to
11665 Traditional Awk does not support multidimensional arrays or user-defined
11668 Traditional Awk does not support the @option{-v} option. You can use
11669 assignments after the program instead, e.g., @command{$AWK '@{print v
11670 $1@}' v=x}; however, don't forget that such assignments are not
11671 evaluated until they are encountered (e.g., after any @code{BEGIN}
11674 Traditional Awk does not support the keywords @code{delete} or @code{do}.
11676 Traditional Awk does not support the expressions
11677 @code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}},
11678 or @code{@var{a}^=@var{b}}.
11680 Traditional Awk does not support the predefined @code{CONVFMT} variable.
11682 Traditional Awk supports only the predefined functions @code{exp},
11683 @code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf},
11684 @code{sqrt}, and @code{substr}.
11686 Traditional Awk @code{getline} is not at all compatible with Posix;
11689 Traditional Awk @code{split} supports only two arguments.
11691 Traditional Awk has a limit of 99
11692 fields in a record. You may be able to circumvent this problem by using
11695 @item @command{cat}
11696 @c ----------------
11697 @prindex @command{cat}
11698 Don't rely on any option.
11703 @prindex @command{cc}
11704 The command @samp{cc -c foo.c} traditionally produces an object file
11705 named @file{foo.o}. Most compilers allow @option{-c} to be combined
11706 with @option{-o} to specify a different object file name, but
11707 Posix does not require this combination and a few compilers
11708 lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make
11709 tests for this feature with @code{AC_PROG_CC_C_O}.
11711 When a compilation such as @samp{cc -o foo foo.c} fails, some compilers
11712 (such as @sc{cds} on Reliant Unix) leave a @file{foo.o}.
11714 HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
11715 assemble. @samp{cc -c foo.S} will appear to succeed, but in fact does
11718 The default executable, produced by @samp{cc foo.c}, can be
11721 @item @file{a.out} --- usual Posix convention.
11722 @item @file{b.out} --- i960 compilers (including @command{gcc}).
11723 @item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}.
11724 @item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS.
11725 @item @file{foo.exe} --- various MS-DOS compilers.
11728 The C compiler's traditional name is @command{cc}, but other names like
11729 @command{gcc} are common. Posix 1003.1-2001 specifies the
11730 name @command{c99}, but older Posix editions specified
11731 @command{c89} and anyway these standard names are rarely used in
11732 practice. Typically the C compiler is invoked from makefiles that use
11733 @samp{$(CC)}, so the value of the @samp{CC} make variable selects the
11737 @item @command{chmod}
11738 @c ------------------
11739 @prindex @command{chmod}
11740 Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file}
11741 instead, for two reasons. First, plain @samp{-w} does not necessarily
11742 make the file unwriteable, since it does not affect mode bits that
11743 correspond to bits in the file mode creation mask. Second,
11744 Posix says that the @samp{-w} might be interpreted as an
11745 implementation-specific option, not as a mode; Posix suggests
11746 using @samp{chmod -- -w file} to avoid this confusion, but unfortunately
11747 @samp{--} does not work on some older hosts.
11750 @item @command{cmp}
11751 @c ----------------
11752 @prindex @command{cmp}
11753 @command{cmp} performs a raw data comparison of two files, while
11754 @command{diff} compares two text files. Therefore, if you might compare
11755 DOS files, even if only checking whether two files are different, use
11756 @command{diff} to avoid spurious differences due to differences of
11762 @prindex @command{cp}
11763 Avoid the @option{-r} option, since its behavior is not specified by
11764 Posix. Use @option{-R} instead. On @acronym{GNU} hosts the two options
11765 are equivalent, but on Solaris hosts (for example) @command{cp -r}
11766 reads from pipes instead of replicating them.
11768 Some @command{cp} implementations (e.g., BSD/OS 4.2) do not allow
11769 trailing slashes at the end of nonexistent destination directories. To
11770 avoid this problem, omit the trailing slashes. For example, use
11771 @samp{cp -R source /tmp/newdir} rather than @samp{cp -R source
11772 /tmp/newdir/} if @file{/tmp/newdir} does not exist.
11774 @c This is thanks to Ian.
11775 SunOS 4 @command{cp} does not support @option{-f}, although its
11776 @command{mv} does. It's possible to deduce why @command{mv} and
11777 @command{cp} are different with respect to @option{-f}. @command{mv}
11778 prompts by default before overwriting a read-only file. @command{cp}
11779 does not. Therefore, @command{mv} requires a @option{-f} option, but
11780 @command{cp} does not. @command{mv} and @command{cp} behave differently
11781 with respect to read-only files because the simplest form of
11782 @command{cp} cannot overwrite a read-only file, but the simplest form of
11783 @command{mv} can. This is because @command{cp} opens the target for
11784 write access, whereas @command{mv} simply calls @code{link} (or, in
11785 newer systems, @code{rename}).
11786 @c Ian said: ``I don't think -p or -r are portable''!!! How can you live
11789 @cindex timestamp resolution
11790 Traditionally, file timestamps had 1-second resolution, and @samp{cp
11791 -p} copied the timestamps exactly. However, many modern file systems
11792 have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp
11793 -p} implementations truncate timestamps when copying files, so this
11794 can result in the destination file appearing to be older than the
11795 source. The exact amount of truncation depends on the resolution of
11796 the system calls that @command{cp} uses; traditionally this was
11797 @code{utime}, which has 1-second resolution, but some newer
11798 @command{cp} implementations use @code{utimes}, which has
11799 1-microsecond resolution. These newer implementations include GNU
11800 coreutils 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or
11801 later. Unfortunately as of June 2005 there is still no system
11802 call to set time stamps to the full nanosecond resolution.
11804 Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy
11805 ownerships. But whether it actually does copy ownerships or not is a
11806 system dependent policy decision implemented by the kernel. If the
11807 kernel allows it then it happens. If the kernel does not allow it then
11808 it does not happen. It is not something @command{cp} itself has control
11811 In SysV any user can chown files to any other user, and SysV also had a
11812 non-sticky @file{/tmp}. That undoubtedly derives from the heritage of
11813 SysV in a business environment without hostile users. BSD changed this
11814 to be a more secure model where only root can @command{chown} files and
11815 a sticky @file{/tmp} is used. That undoubtedly derives from the heritage
11816 of BSD in a campus environment.
11818 Linux by default follows BSD, but it can be configured to allow
11819 @command{chown}. HP-UX as an alternate example follows SysV, but it can
11820 be configured to use the modern security model and disallow
11821 @command{chown}. Since it is an administrator configurable parameter
11822 you can't use the name of the kernel as an indicator of the behavior.
11826 @item @command{date}
11827 @c -----------------
11828 @prindex @command{date}
11829 Some versions of @command{date} do not recognize special % directives,
11830 and unfortunately, instead of complaining, they just pass them through,
11831 and exit with success:
11835 OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
11841 @item @command{diff}
11842 @c -----------------
11843 @prindex @command{diff}
11844 Option @option{-u} is nonportable.
11846 Some implementations, such as Tru64's, fail when comparing to
11847 @file{/dev/null}. Use an empty file instead.
11850 @item @command{dirname}
11851 @c --------------------
11852 @prindex @command{dirname}
11853 Not all hosts have a working @command{dirname}, and you should instead
11854 use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
11857 dir=`dirname "$file"` # This is not portable.
11858 dir=`AS_DIRNAME(["$file"])` # This is more portable.
11861 Unfortunately, neither of the above commands work if @code{$file}'s
11862 directory name ends in newline, since @samp{`@dots{}`} removes all
11866 This handles a few subtleties in the standard way required by
11867 Posix. For example, under UN*X, should @samp{dirname //1} give
11868 @samp{/}? Paul Eggert answers:
11871 No, under some older flavors of Unix, leading @samp{//} is a special
11872 file name: it refers to a ``super-root'' and is used to access other
11873 machines' files. Leading @samp{///}, @samp{////}, etc.@: are equivalent
11874 to @samp{/}; but leading @samp{//} is special. This tradition
11875 started with Apollo Domain/OS, though it has largely died out in practice.
11877 Posix allows but does not require the special treatment for
11878 @samp{//}. It says that the behavior of @command{dirname} on file names of the
11879 form @samp{//([^/]+/*)?} is implementation defined. In these cases,
11880 @acronym{GNU} @command{dirname} returns @samp{/}, but those no-longer-used
11881 flavors of Unix returned @samp{//}.
11885 @item @command{egrep}
11886 @c ------------------
11887 @prindex @command{egrep}
11888 Posix 1003.1-2001 no longer requires @command{egrep},
11889 but many older hosts do not yet support the Posix
11890 replacement @code{grep -E}. Also, some traditional implementations do
11891 not work on long input lines. To work around these problems, invoke
11892 @code{AC_PROG_EGREP} and then use @code{$EGREP}.
11894 The empty alternative is not portable, use @samp{?} instead. For
11895 instance with Digital Unix v5.0:
11898 > printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$'
11900 > printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$'
11902 > printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$'
11907 @command{$EGREP} also suffers the limitations of @command{grep}.
11909 @item @command{expr}
11910 @c -----------------
11911 @prindex @command{expr}
11912 No @command{expr} keyword starts with @samp{X}, so use @samp{expr
11913 X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from
11914 misinterpreting @var{word}.
11916 Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
11918 @item @command{expr} (@samp{|})
11919 @prindex @command{expr} (@samp{|})
11920 You can use @samp{|}. Although Posix does require that @samp{expr
11921 ''} return the empty string, it does not specify the result when you
11922 @samp{|} together the empty string (or zero) with the empty string. For
11929 Posix 1003.2-1992 returns the empty string
11930 for this case, but traditional Unix returns @samp{0} (Solaris is
11931 one such example). In Posix 1003.1-2001, the specification was
11932 changed to match traditional Unix's behavior (which is
11933 bizarre, but it's too late to fix this). Please note that the same
11934 problem does arise when the empty string results from a computation,
11938 expr bar : foo \| foo : bar
11942 Avoid this portability problem by avoiding the empty string.
11945 @item @command{expr} (@samp{:})
11946 @c ----------------------------
11947 @prindex @command{expr}
11948 Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, as they are
11949 not supported on Solaris.
11951 The Posix standard is ambiguous as to whether
11952 @samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string.
11953 In practice, it outputs the empty string on most platforms, but portable
11954 scripts should not assume this. For instance, the @acronym{QNX} 4.25 native
11955 @command{expr} returns @samp{0}.
11957 One might think that a way to get a uniform behavior would be to use
11958 the empty string as a default value:
11961 expr a : '\(b\)' \| ''
11965 Unfortunately this behaves exactly as the original expression; see the
11966 @samp{@command{expr} (@samp{|})} entry for more information.
11968 Older @command{expr} implementations (e.g., SunOS 4 @command{expr} and
11969 Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
11970 @command{expr} to fail if the matched substring is longer than 120
11971 bytes. In this case, you might want to fall back on @samp{echo|sed} if
11972 @command{expr} fails.
11974 On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in
11975 some cases. For example, the command @samp{expr
11976 Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)'} outputs
11977 @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}.
11978 This particular case can be worked around by substituting @samp{[^--]}
11981 Don't leave, there is some more!
11983 The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to
11984 the empty string, has a funny behavior in its exit status: it's always 1
11985 when parentheses are used!
11988 $ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
11990 $ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
11993 $ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
11995 $ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
12000 In practice this can be a big problem if you are ready to catch failures
12001 of @command{expr} programs with some other method (such as using
12002 @command{sed}), since you may get twice the result. For instance
12005 $ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
12009 will output @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A
12010 simple workaround consists in testing @command{expr} and use a variable
12011 set to @command{expr} or to @command{false} according to the result.
12014 @item @command{fgrep}
12015 @c ------------------
12016 @prindex @command{fgrep}
12017 Posix 1003.1-2001 no longer requires @command{fgrep},
12018 but many older hosts do not yet support the Posix
12019 replacement @code{grep -F}. Also, some traditional implementations do
12020 not work on long input lines. To work around these problems, invoke
12021 @code{AC_PROG_FGREP} and then use @code{$FGREP}.
12024 @item @command{find}
12025 @c -----------------
12026 @prindex @command{find}
12027 The option @option{-maxdepth} seems to be @acronym{GNU} specific.
12028 Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find}
12029 commands do not understand it.
12031 The replacement of @samp{@{@}} is guaranteed only if the argument is
12032 exactly @emph{@{@}}, not if it's only a part of an argument. For
12033 instance on DU, and HP-UX 10.20 and HP-UX 11:
12037 $ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
12042 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
12045 @item @command{grep}
12046 @c -----------------
12047 @prindex @command{grep}
12048 Don't use @samp{grep -q} to suppress output, because many @command{grep}
12049 implementations (e.g., Solaris) do not support @option{-q}.
12050 Don't use @samp{grep -s} to suppress output either, because Posix
12051 says @option{-s} does not suppress output, only some error messages;
12052 also, the @option{-s} option of traditional @command{grep} behaved
12053 like @option{-q} does in most modern implementations. Instead,
12054 redirect the standard output and standard error (in case the file
12055 doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
12056 status of @code{grep} to determine whether it found a match.
12058 Some traditional @command{grep} implementations do not work on long
12059 input lines. Also, many implementations do not support multiple regexps
12060 with @option{-e}: they either reject @samp{-e} entirely (e.g., Solaris)
12061 or honor only the last pattern (e.g., @acronym{IRIX} 6.5). To
12062 work around these problems, invoke @code{AC_PROG_GREP} and then use
12065 Another possible workaround for the multiple @samp{-e} problem is to
12066 separate the patterns by newlines, for example:
12073 Alternation, @samp{\|}, is common but Posix does not require its
12074 support in basic regular expressions, so it should be avoided in
12075 portable scripts. Solaris @command{grep} does not support it.
12077 Don't rely on @option{-w}, as Irix 6.5.16m's @command{grep} does not
12081 @item @command{join}
12082 @c -----------------
12083 @prindex @command{join}
12084 Solaris 8 @command{join} has bugs when the second operand is standard
12085 input, and when standard input is a pipe. For example, the following
12086 shell script causes Solaris 8 @command{join} to loop forever:
12093 cat file | join file -
12096 Use @samp{join - file} instead.
12101 @prindex @command{ln}
12102 @cindex Symbolic links
12103 Don't rely on @command{ln} having a @option{-f} option. Symbolic links
12104 are not available on old systems; use @samp{$(LN_S)} as a portable substitute.
12106 For versions of the @acronym{DJGPP} before 2.04,
12107 @command{ln} emulates symbolic links
12108 to executables by generating a stub that in turn calls the real
12109 program. This feature also works with nonexistent files like in the
12110 Posix spec. So @samp{ln -s file link} will generate @file{link.exe},
12111 which will attempt to call @file{file.exe} if run. But this feature only
12112 works for executables, so @samp{cp -p} is used instead for these
12113 systems. @acronym{DJGPP} versions 2.04 and later have full support
12114 for symbolic links.
12119 @prindex @command{ls}
12120 @cindex Listing directories
12121 The portable options are @option{-acdilrtu}. Modern practice is for
12122 @option{-l} to output both owner and group, but traditional
12123 @command{ls} omits the group.
12125 @c From Bruce Lilly:
12129 @c Unix System V (TWG-TCP/IP) (dim.blilly.com)
12133 @c $ /bin/ls a.exe 2>/dev/null
12137 @c fndcmd:fndcmd.sl 1.68
12139 @c Unix dim SYSTEM5 3.51m mc68k
12141 @c It's an AT&T 3B1. See http://www.faqs.org/faqs/3b1-faq/ or any
12142 @c mirror of the 3B1 FAQ. It's actually SVR2.2.
12143 Modern practice is for all diagnostics to go to standard error, but
12144 traditional @samp{ls foo} prints the message @samp{foo not found} to
12145 standard output if @file{foo} does not exist. Be careful when writing
12146 shell commands like @samp{sources=`ls *.c 2>/dev/null`}, since with
12147 traditional @command{ls} this is equivalent to @samp{sources="*.c not
12148 found"} if there are no @samp{.c} files.
12151 @item @command{mkdir}
12152 @c ------------------
12153 @prindex @command{mkdir}
12154 @cindex Making directories
12155 None of @command{mkdir}'s options are portable to older systems. Instead of
12156 @samp{mkdir -p @var{file-name}}, you should use use
12157 @code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh}).
12159 Posix does not clearly specify whether @samp{mkdir -p foo}
12160 should succeed when @file{foo} is a symbolic link to an already-existing
12161 directory. GNU Coreutils 5.1.0 @command{mkdir} succeeds, but Solaris
12162 @command{mkdir} fails.
12164 Not all @code{mkdir -p} implementations are thread-safe. When it is not
12165 and you call @code{mkdir -p a/b} and @code{mkdir -p a/c} at the same
12166 time, both will detect that @file{a/} is missing, one will create
12167 @file{a/}, then the other will try to create @file{a/} and die with a
12168 @code{File exists} error. At least Solaris 10, NetBSD 1.6, and OpenBSD
12169 3.4 have an unsafe @code{mkdir -p}. GNU Coreutils (since Fileutils
12170 version 4.0c), FreeBSD 5.0, and NetBSD-current are known to have a
12171 race-free @code{mkdir -p}. This possible race is harmful in parallel
12172 builds when several @file{Makefile} rules call @code{mkdir -p} to
12173 construct directories. You may use @command{mkinstalldirs} or
12174 @code{install-sh -d} as a safe replacement, provided these scripts are
12175 recent enough (the copies shipped with Automake 1.8.3 are OK, those from
12176 older versions are not thread-safe either).
12179 @item @command{mktemp}
12180 @c -------------------
12181 @prindex @command{mktemp}
12182 @cindex Creating temporary files
12183 Shell scripts can use temporary files safely with @command{mktemp}, but
12184 it does not exist on all systems. A portable way to create a safe
12185 temporary file name is to create a temporary directory with mode 700 and
12186 use a file inside this directory. Both methods prevent attackers from
12187 gaining control, though @command{mktemp} is far less likely to fail
12188 gratuitously under attack.
12190 Here is sample code to create a new temporary directory safely:
12193 # Create a temporary directory $tmp in $TMPDIR (default /tmp).
12194 # Use mktemp if possible; otherwise fall back on mkdir,
12195 # with $RANDOM to make collisions less likely.
12199 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null
12201 test -n "$tmp" && test -d "$tmp"
12203 tmp=$TMPDIR/foo$$-$RANDOM
12204 (umask 077 && mkdir "$tmp")
12211 @prindex @command{mv}
12212 @cindex Moving open files
12213 The only portable options are @option{-f} and @option{-i}.
12215 Moving individual files between file systems is portable (it was in Unix
12217 but it is not always atomic: when doing @samp{mv new existing}, there's
12218 a critical section where neither the old nor the new version of
12219 @file{existing} actually exists.
12221 On some systems moving files from @file{/tmp} can sometimes cause
12222 undesirable (but perfectly valid) warnings, even if you created these
12223 files. This is because @file{/tmp} belongs to a group that ordinary
12224 users are not members of, and files created in @file{/tmp} inherit
12225 @file{/tmp}'s group. When the file is copied, @command{mv} issues
12226 a diagnostic without failing:
12229 $ @kbd{touch /tmp/foo}
12230 $ @kbd{mv /tmp/foo .}
12231 @error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted
12239 This annoying behavior conforms to Posix, unfortunately.
12241 Moving directories across mount points is not portable, use @command{cp}
12244 Moving/Deleting open files isn't portable. The following can't be done
12245 on @acronym{DOS} variants:
12260 @item @command{sed}
12261 @c ----------------
12262 @prindex @command{sed}
12263 Patterns should not include the separator (unless escaped), even as part
12264 of a character class. In conformance with Posix, the Cray
12265 @command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
12267 Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix is
12268 silent on whether they are allowed, and Unicos 9 @command{sed} rejects
12271 Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}.
12273 Sed scripts should not use branch labels longer than 8 characters and
12274 should not contain comments.
12276 Don't include extra @samp{;}, as some @command{sed}, such as Net@acronym{BSD}
12277 1.4.2's, try to interpret the second as a command:
12280 $ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
12281 sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
12284 Input should have reasonably long lines, since some @command{sed} have
12285 an input buffer limited to 4000 bytes.
12287 Alternation, @samp{\|}, is common but Posix does not require its
12288 support, so it should be avoided in portable scripts. Solaris
12289 @command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'}
12290 deletes only lines that contain the literal string @samp{a|b}.
12292 Anchors (@samp{^} and @samp{$}) inside groups are not portable.
12294 Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
12295 quite portable to modern hosts, but is not supported by some older
12296 @command{sed} implementations like SVR3.
12298 Some @command{sed} implementations, e.g., Solaris,
12299 restrict the special role of the asterisk to one-character regular expressions.
12300 This may lead to unexpected behavior:
12303 $ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'}
12305 $ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'}
12309 The @option{-e} option is portable.
12310 Some people prefer to use it:
12313 sed -e '@var{command-1}' \
12314 -e '@var{command-2}'
12318 as opposed to the equivalent:
12328 The following usage is sometimes equivalent:
12331 sed '@var{command-1};@var{command-2}'
12334 but Posix says that this use of a semicolon has undefined effect if
12335 @var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c},
12336 @samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you
12337 should use semicolon only with simple scripts that do not use these
12340 Contrary to yet another urban legend, you may portably use @samp{&} in
12341 the replacement part of the @code{s} command to mean ``what was
12342 matched''. All descendants of Unix version 7 @command{sed}
12344 don't have first hand experience with older @command{sed}s) have
12347 Posix requires that you must not have any white space between
12348 @samp{!} and the following command. It is OK to have blanks between
12349 the address and the @samp{!}. For instance, on Solaris:
12352 $ @kbd{echo "foo" | sed -n '/bar/ ! p'}
12353 @error{}Unrecognized command: /bar/ ! p
12354 $ @kbd{echo "foo" | sed -n '/bar/! p'}
12355 @error{}Unrecognized command: /bar/! p
12356 $ @kbd{echo "foo" | sed -n '/bar/ !p'}
12360 Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and
12361 @samp{w} commands be followed by exactly one space before their argument.
12362 On the other hand, no white space is allowed between @samp{:} and the
12363 subsequent label name.
12365 @item @command{sed} (@samp{t})
12366 @c ---------------------------
12367 @prindex @command{sed} (@samp{t})
12368 Some old systems have @command{sed} that ``forget'' to reset their
12369 @samp{t} flag when starting a new cycle. For instance on @acronym{MIPS
12370 RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed}
12371 script (the line numbers are not actual part of the texts):
12374 s/keep me/kept/g # a
12410 Why? When processing 1, a matches, therefore sets the t flag, b jumps to
12411 d, and the output is produced. When processing line 2, the t flag is
12412 still set (this is the bug). Line a fails to match, but @command{sed}
12413 is not supposed to clear the t flag when a substitution fails. Line b
12414 sees that the flag is set, therefore it clears it, and jumps to d, hence
12415 you get @samp{delete me} instead of @samp{deleted}. When processing 3, t
12416 is clear, a matches, so the flag is set, hence b clears the flags and
12417 jumps. Finally, since the flag is clear, 4 is processed properly.
12419 There are two things one should remember about @samp{t} in @command{sed}.
12420 Firstly, always remember that @samp{t} jumps if @emph{some} substitution
12421 succeeded, not only the immediately preceding substitution. Therefore,
12422 always use a fake @samp{t clear; :clear} to reset the t flag where
12425 Secondly, you cannot rely on @command{sed} to clear the flag at each new
12428 One portable implementation of the script above is:
12439 @item @command{touch}
12440 @c ------------------
12441 @prindex @command{touch}
12442 @cindex timestamp resolution
12443 If you specify the desired timestamp (e.g., with the @option{-r}
12444 option), @command{touch} typically uses the @code{utime} or
12445 @code{utimes} system call, which can result in the same kind of
12446 timestamp truncation problems that @samp{cp -p} has.
12448 On some old @acronym{BSD} systems, @command{touch} or any command that
12449 results in an empty file does not update the timestamps, so use a
12450 command like @command{echo} as a workaround.
12452 @acronym{GNU} @command{touch} 3.16r (and presumably all before that)
12453 fails to work on SunOS 4.1.3 when the empty file is on an
12454 @acronym{NFS}-mounted 4.2 volume.
12459 @node Limitations of Make
12460 @section Limitations of Make
12461 @prindex @command{make}
12462 @cindex Limitations of @command{make}
12464 @command{make} itself suffers a great number of limitations, only a few
12465 of which are listed here. First of all, remember that since commands
12466 are executed by the shell, all its weaknesses are inherited@enddots{}
12471 Posix says that the @samp{$<} construct in makefiles can be
12472 used only in inference rules and in the @samp{.DEFAULT} rule; its
12473 meaning in ordinary rules is unspecified. Solaris @command{make}
12474 for instance will replace it with the empty string. OpenBSD (3.0 and
12475 later) @command{make} will diagnose these uses and error out.
12477 @item Command execution
12478 Since 1992 Posix has required that @command{make} must invoke
12479 each command with the equivalent of a @samp{sh -c} subshell. However,
12480 many @command{make} implementations, including BSD make through 2004,
12481 use @samp{sh -e -c} instead, and the @option{-e} option causes the
12482 subshell to exit immediately if a subsidiary simple-command fails. For
12483 example, the command @samp{touch T; rm -f U} will always attempt to
12484 remove @file{U} with Posix make, but incompatible
12485 @command{make} implementations skip the @command{rm} if the
12486 @command{touch} fails. One way to work around this is to reword the
12487 affected simple-commands so that they always succeed, e.g., @samp{touch
12490 @item Leading underscore in macro names
12491 Some @command{make}s don't support leading underscores in macro names,
12492 such as on NEWS-OS 4.2R.
12495 $ @kbd{cat Makefile}
12498 all:; @@echo this is test
12500 Make: Must be a separator on rules line 2. Stop.
12501 $ @kbd{cat Makefile2}
12504 all:; @@echo this is test
12505 $ @kbd{make -f Makefile2}
12509 @item Trailing backslash in macro
12510 @c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20,
12511 @c but another hppa hpux 10.20 didn't have it. Bob Proulx
12512 @c <bob@proulx.com> thinks it was in hpux 8.0 too.
12513 On some versions of HP-UX, @command{make} will read multiple newlines
12514 following a backslash, continuing to the next non-empty line. For
12528 shows @code{FOO} equal to @code{one BAR = two}. Other @command{make}s
12529 sensibly let a backslash continue only to the immediately following
12532 @item Escaped newline in comments
12534 According to Posix, @file{Makefile} comments start with @code{#}
12535 and continue until an unescaped newline is reached.
12538 % @kbd{cat Makefile}
12545 % @kbd{make} # GNU make
12550 However in Real World this is not always the case. Some implementations
12551 discards anything from @code{#} up to the end of line, ignoring any
12552 trailing backslash.
12555 % @kbd{pmake} # BSD make
12556 "Makefile", line 3: Need an operator
12557 Fatal errors encountered -- cannot continue
12561 Therefore, if you want to comment out a multi-line definition, prefix each
12562 line with @code{#}, not only the first.
12572 OSF/1 4.0d's @command{make} cannot process @file{Makefile}s with lines
12573 longer than 38912 bytes. It exits with a @code{Line too long}
12574 diagnostic. A later version, Tru64 5.1's @command{make} has been
12575 reported to crash with lines around 20 kB.
12577 @item @code{make macro=value} and sub-@command{make}s.
12579 A command-line variable definition such as @code{foo=bar} overrides any
12580 definition of @code{foo} in the @file{Makefile}. Some @command{make}
12581 implementations (such as @acronym{GNU} @command{make}) will propagate this
12582 override to sub-invocations of @command{make}. Some other implementation
12583 will not pass the substitution along to sub-@command{make}s.
12586 % @kbd{cat Makefile}
12593 % @kbd{make foo=bar} # GNU make 3.79.1
12596 make[1]: Entering directory `/home/adl'
12598 make[1]: Leaving directory `/home/adl'
12599 % @kbd{pmake foo=bar} # BSD make
12605 You have a few possibilities if you do want the @code{foo=bar} override
12606 to propagate to sub-@command{make}s. One is to use the @code{-e}
12607 option, which causes all environment variables to have precedence over
12608 the @file{Makefile} macro definitions, and declare foo as an environment
12612 % @kbd{env foo=bar make -e}
12615 The @code{-e} option is propagated to sub-@command{make}s automatically,
12616 and since the environment is inherited between @command{make}
12617 invocations, the @code{foo} macro will be overridden in
12618 sub-@code{make}s as expected.
12620 This syntax (@code{foo=bar make -e}) is portable only when used
12621 outside of a @file{Makefile}, for instance from a script or from the
12622 command line. When run inside a @command{make} rule, GNU
12623 @command{make} 3.80 and prior versions forget to propagate the
12624 @code{-e} option to sub-@command{make}s.
12626 Moreover, using @code{-e} could have unexpected side-effects if your
12627 environment contains some other macros usually defined by the
12628 Makefile. (See also the note about @code{make -e} and @code{SHELL}
12631 Another way to propagate overrides to sub-@command{make}s is to do it
12632 manually, from your @file{Makefile}:
12638 $(MAKE) foo=$(foo) two
12643 You need to foresee all macros that a user might want to override if
12646 @item The @code{SHELL} macro
12647 @cindex @code{SHELL} and @command{make}
12648 @cindex @command{make} and @code{SHELL}
12650 Posix-compliant @command{make}s internally use the @code{$(SHELL)}
12651 macro to spawn shell processes and execute @file{Makefile} rules. This
12652 is a builtin macro supplied by @command{make}, but it can be modified
12653 from the @file{Makefile} or a command-line argument.
12655 Not all @command{make}s will define this @code{SHELL} macro. OSF/Tru64
12656 @command{make} is an example; this implementation will always use
12657 @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in
12658 your @file{Makefile}s. If you use Autoconf, do
12664 Do not force @code{SHELL = /bin/sh} because that is not correct
12665 everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when
12666 its GNU @code{make} port sees such a setting it enters a special
12667 emulation mode where features like pipes and redirections are emulated
12668 on top of DOS's @command{command.com}. Unfortunately this emulation is
12669 incomplete; for instance it does not handle command substitutions.
12670 On @acronym{DJGPP} @code{SHELL} should point to Bash.
12672 Posix-compliant @command{make}s should never acquire the value of
12673 $(SHELL) from the environment, even when @code{make -e} is used
12674 (otherwise, think about what would happen to your rules if
12675 @code{SHELL=/bin/tcsh}).
12677 However not all @command{make} implementations will make this exception.
12678 For instance it's not surprising that OSF/Tru64 @command{make} doesn't
12679 protect @code{SHELL}, since it doesn't use it.
12682 % @kbd{cat Makefile}
12688 % @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # OSF1 V4.0 Make
12691 % @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make
12696 @item Comments in rules
12697 @cindex Comments in @file{Makefile} rules
12698 @cindex @file{Makefile} rules and comments
12700 Never put comments in a rule.
12702 Some @command{make} treat anything starting with a tab as a command for
12703 the current rule, even if the tab is immediately followed by a @code{#}.
12704 The @command{make} from Tru64 Unix V5.1 is one of them. The following
12705 @file{Makefile} will run @code{# foo} through the shell.
12712 @item The @file{obj/} subdirectory.
12713 @cindex @file{obj/}, subdirectory
12714 @cindex BSD @command{make} and @file{obj/}
12716 Never name one of your subdirectories @file{obj/} if you don't like
12719 If an @file{obj/} directory exists, BSD @command{make} will enter it
12720 before reading @file{Makefile}. Hence the @file{Makefile} in the
12721 current directory will not be read.
12724 % @kbd{cat Makefile}
12727 % @kbd{cat obj/Makefile}
12730 % @kbd{make} # GNU make
12733 % @kbd{pmake} # BSD make
12738 @item @code{make -k}
12739 @cindex @code{make -k}
12741 Do not rely on the exit status of @code{make -k}. Some implementations
12742 reflect whether they encountered an error in their exit status; other
12743 implementations always succeed.
12746 % @kbd{cat Makefile}
12749 % @kbd{make -k; echo exit status: $?} # GNU make
12751 make: *** [all] Error 1
12753 % @kbd{pmake -k; echo exit status: $?} # BSD make
12755 *** Error code 1 (continuing)
12760 @cindex @code{VPATH}
12762 There is no @code{VPATH} support specified in Posix. Many
12763 @command{make}s have a form of @code{VPATH} support, but its
12764 implementation is not consistent amongst @command{make}s.
12766 Maybe the best suggestion to give to people who need the @code{VPATH}
12767 feature is to choose a @command{make} implementation and stick to it.
12768 Since the resulting @file{Makefile}s are not portable anyway, better
12769 choose a portable @command{make} (hint, hint).
12771 Here are a couple of known issues with some @code{VPATH}
12776 @item @code{VPATH} and double-colon rules
12777 @cindex @code{VPATH} and double-colon rules
12778 @cindex double-colon rules and @code{VPATH}
12780 Any assignment to @code{VPATH} causes Sun @command{make} to only execute
12781 the first set of double-colon rules. (This comment has been here since
12782 1994 and the context has been lost. It's probably about SunOS 4. If
12783 you can reproduce this, please send us a test case for illustration.)
12785 @item @code{$<} not supported in explicit rules
12786 @cindex explicit rules, @code{$<}, and @code{VPATH}
12787 @cindex @code{$<}, explicit rules, and @code{VPATH}
12788 @cindex @code{VPATH}, explicit rules, and @code{$<}
12790 As said elsewhere, using @code{$<} in explicit rules is not portable.
12791 The prerequisite file must be named explicitly in the rule. If you want
12792 to find the prerequisite via a @code{VPATH} search, you have to code the
12793 whole thing manually. For instance, using the following pattern:
12798 cp `test -f if.c || echo $(VPATH)/`if.c f.c
12801 @item Automatic rule rewriting
12802 @cindex @code{VPATH} and automatic rule rewriting
12803 @cindex automatic rule rewriting and @code{VPATH}
12805 Some @command{make} implementations, such as SunOS 4 @command{make} or
12806 OSF1/Tru64 @command{make}, will search prerequisites in @code{VPATH} and
12807 rewrite all their occurrences in the rule appropriately.
12818 would execute @code{cp ../pkg/src/if.c f.c} if @file{if.c} was
12819 found in @file{../pkg/src}. That sounds great.
12821 However, for the sake of other @command{make} implementations, we can't
12822 rely on this, and we have to search @code{VPATH} manually:
12827 cp `test -f if.c || echo $(VPATH)/`if.c f.c
12831 However the "prerequisite rewriting" still applies here. So if
12832 @file{if.c} is in @file{../pkg/src}, SunOS 4 @command{make} and OSF1/Tru64
12833 @command{make} will execute
12836 @code{cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c}
12847 and thus fails. Oops.
12849 One workaround is to make sure that @file{if.c} never appears as a plain word
12850 in the rule. For instance these three rules would be safe.
12855 cp `test -f ./if.c || echo $(VPATH)/`if.c f.c
12857 cp `test -f 'ig.c' || echo $(VPATH)/`ig.c g.c
12859 cp `test -f "ih.c" || echo $(VPATH)/`ih.c h.c
12862 Things get worse when your prerequisites are in a macro.
12866 HEADERS = f.h g.h h.h
12867 install-HEADERS: $(HEADERS)
12868 for i in $(HEADERS); do \
12869 $(INSTALL) -m 644 \
12870 `test -f $$i || echo $(VPATH)/`$$i \
12871 $(DESTDIR)$(includedir)/$$i; \
12875 The above @code{install-HEADERS} rule is not SunOS-4-proof because @code{for
12876 i in $(HEADERS);} will be expanded as @code{for i in f.h g.h h.h;}
12877 where @code{f.h} and @code{g.h} are plain words and are hence
12878 subject to @code{VPATH} adjustments.
12880 If the three files are in @file{../pkg/src}, the rule is run as:
12883 for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \
12885 `test -f $i || echo ../pkg/src/`$i \
12886 /usr/local/include/$i; \
12890 where the two first @command{install} calls will fail. For instance,
12891 consider the @code{f.h} installation:
12895 `test -f ../pkg/src/f.h || \
12898 /usr/local/include/../pkg/src/f.h;
12906 /usr/local/include/../pkg/src/f.h;
12909 Note that the manual @code{VPATH} search did not cause any problems here;
12910 however this command installs @file{f.h} in an incorrect directory.
12912 Trying to quote @code{$(HEADERS)} in some way, as we did for
12913 @code{foo.c} a few @file{Makefile}s ago, does not help:
12916 install-HEADERS: $(HEADERS)
12917 headers='$(HEADERS)'; \
12918 for i in $$headers; do \
12919 $(INSTALL) -m 644 \
12920 `test -f $$i || echo $(VPATH)/`$$i \
12921 $(DESTDIR)$(includedir)/$$i; \
12925 Now, @code{headers='$(HEADERS)'} macroexpands to:
12928 headers='f.h g.h h.h'
12932 but @code{g.h} is still a plain word. (As an aside, the idiom
12933 @code{headers='$(HEADERS)'; for i in $$headers;} is a good
12934 idea if @code{$(HEADERS)} can be empty, because some shells diagnose a
12935 syntax error on @code{for i in;}.)
12937 One workaround is to strip this unwanted @file{../pkg/src/} prefix manually:
12940 HEADERS = f.h g.h h.h
12941 install-HEADERS: $(HEADERS)
12942 headers='$(HEADERS)'; \
12943 for i in $$headers; do \
12944 i=`expr "$$i" : '$(VPATH)/\(.*\)'`;
12945 $(INSTALL) -m 644 \
12946 `test -f $$i || echo $(VPATH)/`$$i \
12947 $(DESTDIR)$(includedir)/$$i; \
12951 Automake does something similar. However the above hack works only if
12952 the files listed in @code{HEADERS} are in the current directory or a
12953 subdirectory; they should not be in an enclosing directory. If we had
12954 @code{HEADERS = ../f.h}, the above fragment would fail in a VPATH
12955 build with OSF1/Tru64 @command{make}. The reason is that not only does
12956 OSF1/Tru64 @command{make} rewrite dependencies, but it also simplifies
12957 them. Hence @code{../f.h} will become @code{../pkg/f.h} instead of
12958 @code{../pkg/src/../f.h}. This obviously defeats any attempt to strip
12959 a leading @file{../pkg/src/} component.
12961 The following example makes the behavior of OSF1/Tru64 @command{make}
12975 Dependency @file{../foo} was found in @file{sub/../foo}, but OSF1/Tru64
12976 @command{make} simplified it as @file{foo}. (Note that the @file{sub/}
12977 directory does not even exist, this just means that the simplification
12978 occurred before the file was checked for.)
12980 For the record here is how SunOS 4 @command{make} behaves on this
12984 make: Fatal error: Don't know how to make target `../foo'
12992 @item OSF/Tru64 @command{make} creates prerequisite directories magically
12993 @cindex @code{VPATH} and prerequisite directories
12994 @cindex prerequisite directories and @code{VPATH}
12996 When a prerequisite is a sub-directory of @code{VPATH}, Tru64
12997 @command{make} will create it in the current directory.
13000 % @kbd{mkdir -p foo/bar build}
13002 % @kbd{cat >Makefile <<END
13011 This can yield unexpected results if a rule uses a manual @code{VPATH}
13012 search as presented before.
13017 command `test -d foo/bar || echo ../`foo/bar
13020 The above @command{command} will be run on the empty @file{foo/bar}
13021 directory that was created in the current directory.
13023 @item target lookup
13024 @cindex @code{VPATH}, resolving target pathnames
13026 @acronym{GNU} @command{make} uses a rather complex algorithm to decide when it
13027 should use files found via a @code{VPATH} search. @xref{Search
13028 Algorithm,, How Directory Searches are Performed, make, The @acronym{GNU} Make
13031 If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the
13032 file name found during the @code{VPATH} search for this target, and
13033 builds the file locally using the file name given in the @file{Makefile}.
13034 If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the
13035 file name found during the @code{VPATH} search.
13037 Other @command{make} implementations, like NetBSD @command{make}, are
13038 easier to describe: the file name found during the @code{VPATH} search
13039 will be used whether the target needs to be rebuilt or not. Therefore
13040 new files are created locally, but existing files are updated at their
13041 @code{VPATH} location.
13043 OpenBSD and FreeBSD @command{make}s, however, will never perform a
13044 @code{VPATH} search for a dependency which has an explicit rule.
13045 This is extremely annoying.
13047 When attempting a @code{VPATH} build for an autoconfiscated package
13048 (e.g,, @code{mkdir build && cd build && ../configure}), this means the
13050 @command{make} will build everything locally in the @file{build}
13051 directory, while BSD @command{make} will build new files locally and
13052 update existing files in the source directory.
13055 % @kbd{cat Makefile}
13058 foo.x bar.x: newer.x
13059 @@echo Building $@@
13060 % @kbd{touch ../bar.x}
13061 % @kbd{touch ../newer.x}
13062 % @kbd{make} # GNU make
13065 % @kbd{pmake} # NetBSD make
13068 % @kbd{fmake} # FreeBSD make, OpenBSD make
13071 % @kbd{tmake} # Tru64 make
13074 % @kbd{touch ../bar.x}
13075 % @kbd{make} # GNU make
13077 % @kbd{pmake} # NetBSD make
13079 % @kbd{fmake} # FreeBSD make, OpenBSD make
13082 % @kbd{tmake} # Tru64 make
13087 Note how NetBSD @command{make} updates @file{../bar.x} in its VPATH
13088 location, and how FreeBSD, OpenBSD, and Tru64 @command{make} always
13089 update @file{bar.x}, even when @file{../bar.x} is up to date.
13091 Another point worth mentioning is that once @acronym{GNU} @command{make} has
13092 decided to ignore a @code{VPATH} file name (e.g., it ignored
13093 @file{../bar.x} in the above example) it will continue to ignore it when
13094 the target occurs as a prerequisite of another rule.
13096 The following example shows that @acronym{GNU} @command{make} does not look up
13097 @file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule,
13098 because it ignored the @code{VPATH} result of @file{bar.x} while running
13099 the @code{bar.x: newer.x} rule.
13102 % @kbd{cat Makefile}
13106 @@echo Building $@@
13110 % @kbd{touch ../bar.x}
13111 % @kbd{touch ../newer.x}
13112 % @kbd{make} # GNU make
13115 cp: cannot stat `bar.x': No such file or directory
13116 make: *** [bar.y] Error 1
13117 % @kbd{pmake} # NetBSD make
13121 % @kbd{fmake} # FreeBSD make, OpenBSD make
13122 echo Building bar.x
13124 cp: cannot stat `bar.x': No such file or directory
13126 % @kbd{tmake} # Tru64 make
13128 cp: bar.x: No such file or directory
13132 Note that if you drop away the command from the @code{bar.x: newer.x}
13133 rule, @acronym{GNU} @command{make} will magically start to work: it
13134 knows that @code{bar.x} hasn't been updated, therefore it doesn't
13135 discard the result from @code{VPATH} (@file{../bar.x}) in succeeding
13136 uses. Tru64 will also work, but FreeBSD and OpenBSD still don't.
13139 % @kbd{cat Makefile}
13146 % @kbd{touch ../bar.x}
13147 % @kbd{touch ../newer.x}
13148 % @kbd{make} # GNU make
13151 % @kbd{pmake} # NetBSD make
13154 % @kbd{fmake} # FreeBSD make, OpenBSD make
13156 cp: cannot stat `bar.x': No such file or directory
13158 % @kbd{tmake} # Tru64 make
13162 It seems the sole solution that would please every @command{make}
13163 implementation is to never rely on @code{VPATH} searches for targets.
13164 In other words, @code{VPATH} should be reserved to unbuilt sources.
13167 @c end item about VPATH
13169 @item Single Suffix Rules and Separated Dependencies
13170 @cindex Single Suffix Inference Rule
13171 @cindex Rule, Single Suffix Inference
13172 A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule
13173 (@samp{.from.to:}), but which @emph{destination} suffix is empty
13176 @cindex Separated Dependencies
13177 @dfn{Separated dependencies} simply refers to listing the prerequisite
13178 of a target, without defining a rule. Usually one can list on the one
13179 hand side, the rules, and on the other hand side, the dependencies.
13181 Solaris @command{make} does not support separated dependencies for
13182 targets defined by single suffix rules:
13185 $ @kbd{cat Makefile}
13190 $ @kbd{touch foo.in}
13197 while @acronym{GNU} Make does:
13203 Makefile foo foo.in
13206 Note it works without the @samp{foo: foo.in} dependency.
13209 $ @kbd{cat Makefile}
13218 and it works with double suffix inference rules:
13221 $ @kbd{cat Makefile}
13223 .SUFFIXES: .in .out
13230 As a result, in such a case, you have to write target rules.
13232 @item Timestamp Resolution
13233 @cindex timestamp resolution
13234 Traditionally, file timestamps had 1-second resolution, and
13235 @command{make} used those timestamps to determine whether one file was
13236 newer than the other. However, many modern file systems have
13237 timestamps with 1-nanosecond resolution. Some @command{make}
13238 implementations look at the entire timestamp; others ignore the
13239 fractional part, which can lead to incorrect results. Normally this
13240 is not a problem, but in some extreme cases you may need to use tricks
13241 like @samp{sleep 1} to work around timestamp truncation bugs.
13243 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
13244 file timestamps to their full resolutions (@pxref{Limitations of Usual
13245 Tools}). Hence you should be wary of rules like this:
13252 as @file{dest} will often appear to be older than @file{src} after the
13253 timestamp is truncated, and this can cause @command{make} to do
13254 needless rework the next time it is invoked. To work around this
13255 problem, you can use a timestamp file, e.g.:
13268 @c ================================================== Manual Configuration
13270 @node Manual Configuration
13271 @chapter Manual Configuration
13273 A few kinds of features can't be guessed automatically by running test
13274 programs. For example, the details of the object-file format, or
13275 special options that need to be passed to the compiler or linker. You
13276 can check for such features using ad-hoc means, such as having
13277 @command{configure} check the output of the @code{uname} program, or
13278 looking for libraries that are unique to particular systems. However,
13279 Autoconf provides a uniform method for handling unguessable features.
13282 * Specifying Names:: Specifying the system type
13283 * Canonicalizing:: Getting the canonical system type
13284 * Using System Type:: What to do with the system type
13287 @node Specifying Names
13288 @section Specifying the System Type
13289 @cindex System type
13291 Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated
13292 @command{configure} scripts can make decisions based on a canonical name
13293 for the system type, which has the form:
13294 @samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
13295 @samp{@var{system}} or @samp{@var{kernel}-@var{system}}
13297 @command{configure} can usually guess the canonical name for the type of
13298 system it's running on. To do so it runs a script called
13299 @command{config.guess}, which infers the name using the @code{uname}
13300 command or symbols predefined by the C preprocessor.
13302 Alternately, the user can specify the system type with command line
13303 arguments to @command{configure}. Doing so is necessary when
13304 cross-compiling. In the most complex case of cross-compiling, three
13305 system types are involved. The options to specify them are:
13308 @item --build=@var{build-type}
13309 the type of system on which the package is being configured and
13310 compiled. It defaults to the result of running @command{config.guess}.
13312 @item --host=@var{host-type}
13313 the type of system on which the package will run. By default it is the
13314 same as the build machine. Specifying it enables the cross-compilation
13317 @item --target=@var{target-type}
13318 the type of system for which any compiler tools in the package will
13319 produce code (rarely needed). By default, it is the same as host.
13322 If you mean to override the result of @command{config.guess}, use
13323 @option{--build}, not @option{--host}, since the latter enables
13324 cross-compilation. For historical reasons, passing @option{--host} also
13325 changes the build type. Therefore, whenever you specify @code{--host},
13326 be sure to specify @code{--build} too; this will be fixed in the
13327 future. So, to enter cross-compilation mode, use a command like this
13330 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
13334 Note that if you do not specify @option{--host}, @command{configure} will
13335 fail if it can't run the code generated by the specified compiler. For
13336 example, configuring as follows will fail:
13339 ./configure CC=m68k-coff-gcc
13342 In the future, when cross-compiling Autoconf will @emph{not}
13343 accept tools (compilers, linkers, assemblers) whose name is not
13344 prefixed with the host type. The only case when this may be
13345 useful is when you really are not cross-compiling, but only
13346 building for a least-common-denominator architecture: an example
13347 is building for @code{i386-pc-linux-gnu} while running on an
13348 @code{i686-pc-linux-gnu} architecture. In this case, some particular
13349 pairs might be similar enough to let you get away with the system
13350 compilers, but in general the compiler might make bogus assumptions
13351 on the host: if you know what you are doing, please create symbolic
13352 links from the host compiler to the build compiler.
13354 @cindex @command{config.sub}
13355 @command{configure} recognizes short aliases for many system types; for
13356 example, @samp{decstation} can be used instead of
13357 @samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
13358 @command{config.sub} to canonicalize system type aliases.
13360 This section deliberately omits the description of the obsolete
13361 interface; see @ref{Hosts and Cross-Compilation}.
13364 @node Canonicalizing
13365 @section Getting the Canonical System Type
13366 @cindex System type
13367 @cindex Canonical system type
13369 The following macros make the system type available to @command{configure}
13372 @ovindex build_alias
13373 @ovindex host_alias
13374 @ovindex target_alias
13376 The variables @samp{build_alias}, @samp{host_alias}, and
13377 @samp{target_alias} are always exactly the arguments of @option{--build},
13378 @option{--host}, and @option{--target}; in particular, they are left empty
13379 if the user did not use them, even if the corresponding
13380 @code{AC_CANONICAL} macro was run. Any configure script may use these
13381 variables anywhere. These are the variables that should be used when in
13382 interaction with the user.
13384 If you need to recognize some special environments based on their system
13385 type, run the following macros to get canonical system names. These
13386 variables are not set before the macro call.
13388 If you use these macros, you must distribute @command{config.guess} and
13389 @command{config.sub} along with your source code. @xref{Output}, for
13390 information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
13391 to control in which directory @command{configure} looks for those scripts.
13394 @defmac AC_CANONICAL_BUILD
13395 @acindex{CANONICAL_BUILD}
13398 @ovindex build_vendor
13400 Compute the canonical build-system type variable, @code{build}, and its
13401 three individual parts @code{build_cpu}, @code{build_vendor}, and
13404 If @option{--build} was specified, then @code{build} is the
13405 canonicalization of @code{build_alias} by @command{config.sub},
13406 otherwise it is determined by the shell script @command{config.guess}.
13409 @defmac AC_CANONICAL_HOST
13410 @acindex{CANONICAL_HOST}
13413 @ovindex host_vendor
13415 Compute the canonical host-system type variable, @code{host}, and its
13416 three individual parts @code{host_cpu}, @code{host_vendor}, and
13419 If @option{--host} was specified, then @code{host} is the
13420 canonicalization of @code{host_alias} by @command{config.sub},
13421 otherwise it defaults to @code{build}.
13424 @defmac AC_CANONICAL_TARGET
13425 @acindex{CANONICAL_TARGET}
13427 @ovindex target_cpu
13428 @ovindex target_vendor
13430 Compute the canonical target-system type variable, @code{target}, and its
13431 three individual parts @code{target_cpu}, @code{target_vendor}, and
13434 If @option{--target} was specified, then @code{target} is the
13435 canonicalization of @code{target_alias} by @command{config.sub},
13436 otherwise it defaults to @code{host}.
13439 Note that there can be artifacts due to the backward compatibility
13440 code. See @xref{Hosts and Cross-Compilation}, for more.
13442 @node Using System Type
13443 @section Using the System Type
13445 In @file{configure.ac} the system type is generally used by one or more
13446 @code{case} statements to select system-specifics. Shell wildcards can
13447 be used to match a group of system types.
13449 For example, an extra assembler code object file could be chosen, giving
13450 access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the
13451 following would be used in a @file{Makefile} to add the object to a
13452 program or library.
13456 alpha*-*-*) CYCLE_OBJ=rpcc.o ;;
13457 i?86-*-*) CYCLE_OBJ=rdtsc.o ;;
13460 AC_SUBST([CYCLE_OBJ])
13463 @code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way
13464 to select variant source files, for example optimized code for some
13465 CPUs. The configured CPU type doesn't always indicate exact CPU types,
13466 so some run-time capability checks may be necessary too.
13470 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;;
13471 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;;
13472 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;;
13476 The host system type can also be used to find cross-compilation tools
13477 with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}).
13479 The above examples all show @samp{$host}, since this is where the code
13480 is going to run. Only rarely is it necessary to test @samp{$build}
13481 (which is where the build is being done).
13483 Whenever you're tempted to use @samp{$host} it's worth considering
13484 whether some sort of probe would be better. New system types come along
13485 periodically or previously missing features are added. Well-written
13486 probes can adapt themselves to such things, but hard-coded lists of
13487 names won't. Here are some guidelines,
13491 Availability of libraries and library functions should always be checked
13494 Variant behavior of system calls is best identified with runtime tests
13495 if possible, but bug workarounds or obscure difficulties might have to
13496 be driven from @samp{$host}.
13498 Assembler code is inevitably highly CPU-specific and is best selected
13499 according to @samp{$host_cpu}.
13501 Assembler variations like underscore prefix on globals or ELF versus
13502 COFF type directives are however best determined by probing, perhaps
13503 even examining the compiler output.
13506 @samp{$target} is for use by a package creating a compiler or similar.
13507 For ordinary packages it's meaningless and should not be used. It
13508 indicates what the created compiler should generate code for, if it can
13509 cross-compile. @samp{$target} generally selects various hard-coded CPU
13510 and system conventions, since usually the compiler or tools under
13511 construction will themselves determine how the target will work.
13514 @c ===================================================== Site Configuration.
13516 @node Site Configuration
13517 @chapter Site Configuration
13519 @command{configure} scripts support several kinds of local configuration
13520 decisions. There are ways for users to specify where external software
13521 packages are, include or exclude optional features, install programs
13522 under modified names, and set default values for @command{configure}
13526 * External Software:: Working with other optional software
13527 * Package Options:: Selecting optional features
13528 * Pretty Help Strings:: Formatting help string
13529 * Site Details:: Configuring site details
13530 * Transforming Names:: Changing program names when installing
13531 * Site Defaults:: Giving @command{configure} local defaults
13534 @node External Software
13535 @section Working With External Software
13536 @cindex External software
13538 Some packages require, or can optionally use, other software packages
13539 that are already installed. The user can give @command{configure}
13540 command line options to specify which such external software to use.
13541 The options have one of these forms:
13543 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
13546 --with-@var{package}[=@var{arg}]
13547 --without-@var{package}
13550 For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker
13551 instead of some other linker. @option{--with-x} means work with The X
13554 The user can give an argument by following the package name with
13555 @samp{=} and the argument. Giving an argument of @samp{no} is for
13556 packages that are used by default; it says to @emph{not} use the
13557 package. An argument that is neither @samp{yes} nor @samp{no} could
13558 include a name or number of a version of the other package, to specify
13559 more precisely which other package this program is supposed to work
13560 with. If no argument is given, it defaults to @samp{yes}.
13561 @option{--without-@var{package}} is equivalent to
13562 @option{--with-@var{package}=no}.
13564 @command{configure} scripts do not complain about
13565 @option{--with-@var{package}} options that they do not support. This
13566 behavior permits configuring a source tree containing multiple packages
13567 with a top-level @command{configure} script when the packages support
13568 different options, without spurious error messages about options that
13569 some of the packages support. An unfortunate side effect is that option
13570 spelling errors are not diagnosed. No better approach to this problem
13571 has been suggested so far.
13573 For each external software package that may be used, @file{configure.ac}
13574 should call @code{AC_ARG_WITH} to detect whether the @command{configure}
13575 user asked to use it. Whether each package is used or not by default,
13576 and which arguments are valid, is up to you.
13578 @defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
13580 If the user gave @command{configure} the option @option{--with-@var{package}}
13581 or @option{--without-@var{package}}, run shell commands
13582 @var{action-if-given}. If neither option was given, run shell commands
13583 @var{action-if-not-given}. The name @var{package} indicates another
13584 software package that this program should work with. It should consist
13585 only of alphanumeric characters and dashes.
13587 The option's argument is available to the shell commands
13588 @var{action-if-given} in the shell variable @code{withval}, which is
13589 actually just the value of the shell variable @code{with_@var{package}},
13590 with any @option{-} characters changed into @samp{_}. You may use that
13591 variable instead, if you wish.
13593 The argument @var{help-string} is a description of the option that
13596 --with-readline support fancy command line editing
13600 @var{help-string} may be more than one line long, if more detail is
13601 needed. Just make sure the columns line up in @samp{configure
13602 --help}. Avoid tabs in the help string. You'll need to enclose the
13603 help string in @samp{[} and @samp{]} in order to produce the leading
13606 You should format your @var{help-string} with the macro
13607 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
13609 The following example shows how to use the @code{AC_ARG_WITH} macro in
13610 a common situation. You want to let the user decide whether to enable
13611 support for an external library (e.g., the readline library); if the user
13612 specified neither @option{--with-readline} nor @option{--without-readline},
13613 you want to enable support for readline only if the library is available
13616 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
13618 AC_ARG_WITH([readline],
13619 [AS_HELP_STRING([--with-readline],
13620 [support fancy command line editing @@<:@@default=check@@:>@@])],
13622 [with_readline=check])
13625 AS_IF([test "x$with_readline" != xno],
13626 [AC_CHECK_LIB([readline], [main],
13627 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
13628 AC_DEFINE([HAVE_LIBREADLINE], [1],
13629 [Define if you have libreadline])
13631 [if test "x$with_readline" != xcheck; then
13633 [--with-readline was given, but test for readline failed])
13638 The next example shows how to use @code{AC_ARG_WITH} to give the user the
13639 possibility to enable support for the readline library, in case it is still
13640 experimental and not well tested, and is therefore disabled by default.
13642 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
13644 AC_ARG_WITH([readline],
13645 [AS_HELP_STRING([--with-readline],
13646 [enable experimental support for readline])],
13648 [with_readline=no])
13651 AS_IF([test "x$with_readline" != xno],
13652 [AC_CHECK_LIB([readline], [main],
13653 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
13654 AC_DEFINE([HAVE_LIBREADLINE], [1],
13655 [Define if you have libreadline])
13658 [--with-readline was given, but test for readline failed])],
13662 The last example shows how to use @code{AC_ARG_WITH} to give the user the
13663 possibility to disable support for the readline library, given that it is
13664 an important feature and that it should be enabled by default.
13666 @c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved.
13668 AC_ARG_WITH([readline],
13669 [AS_HELP_STRING([--without-readline],
13670 [disable support for readline])],
13672 [with_readline=yes])
13675 AS_IF([test "x$with_readline" != xno],
13676 [AC_CHECK_LIB([readline], [main],
13677 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"])
13678 AC_DEFINE([HAVE_LIBREADLINE], [1],
13679 [Define if you have libreadline])
13682 [readline test failed (--without-readline to disable)])],
13686 These three examples can be easily adapted to the case where
13687 @code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see
13688 @ref{Package Options}).
13691 @defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
13693 This is an obsolete version of @code{AC_ARG_WITH} that does not
13694 support providing a help string.
13697 @node Package Options
13698 @section Choosing Package Options
13699 @cindex Package options
13700 @cindex Options, package
13702 If a software package has optional compile-time features, the user can
13703 give @command{configure} command line options to specify whether to
13704 compile them. The options have one of these forms:
13706 @c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
13709 --enable-@var{feature}[=@var{arg}]
13710 --disable-@var{feature}
13713 These options allow users to choose which optional features to build and
13714 install. @option{--enable-@var{feature}} options should never make a
13715 feature behave differently or cause one feature to replace another.
13716 They should only cause parts of the program to be built rather than left
13719 The user can give an argument by following the feature name with
13720 @samp{=} and the argument. Giving an argument of @samp{no} requests
13721 that the feature @emph{not} be made available. A feature with an
13722 argument looks like @option{--enable-debug=stabs}. If no argument is
13723 given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
13724 equivalent to @option{--enable-@var{feature}=no}.
13726 @command{configure} scripts do not complain about
13727 @option{--enable-@var{feature}} options that they do not support.
13728 This behavior permits configuring a source tree containing multiple
13729 packages with a top-level @command{configure} script when the packages
13730 support different options, without spurious error messages about options
13731 that some of the packages support.
13732 An unfortunate side effect is that option spelling errors are not diagnosed.
13733 No better approach to this problem has been suggested so far.
13735 For each optional feature, @file{configure.ac} should call
13736 @code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
13737 to include it. Whether each feature is included or not by default, and
13738 which arguments are valid, is up to you.
13740 @defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
13741 @acindex{ARG_ENABLE}
13742 If the user gave @command{configure} the option
13743 @option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
13744 shell commands @var{action-if-given}. If neither option was given, run
13745 shell commands @var{action-if-not-given}. The name @var{feature}
13746 indicates an optional user-level facility. It should consist only of
13747 alphanumeric characters and dashes.
13749 The option's argument is available to the shell commands
13750 @var{action-if-given} in the shell variable @code{enableval}, which is
13751 actually just the value of the shell variable
13752 @code{enable_@var{feature}}, with any @option{-} characters changed into
13753 @samp{_}. You may use that variable instead, if you wish. The
13754 @var{help-string} argument is like that of @code{AC_ARG_WITH}
13755 (@pxref{External Software}).
13757 You should format your @var{help-string} with the macro
13758 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).
13760 See the examples suggested with the definition of @code{AC_ARG_WITH}
13761 (@pxref{External Software}) to get an idea of possible utilizations of
13762 @code{AC_ARG_ENABLE}.
13765 @defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
13767 This is an obsolete version of @code{AC_ARG_ENABLE} that does not
13768 support providing a help string.
13772 @node Pretty Help Strings
13773 @section Making Your Help Strings Look Pretty
13774 @cindex Help strings
13776 Properly formatting the @samp{help strings} which are used in
13777 @code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
13778 (@pxref{Package Options}) can be challenging. Specifically, you want
13779 your own @samp{help strings} to line up in the appropriate columns of
13780 @samp{configure --help} just like the standard Autoconf @samp{help
13781 strings} do. This is the purpose of the @code{AS_HELP_STRING} macro.
13783 @defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
13784 @acindex{HELP_STRING}
13786 Expands into an help string that looks pretty when the user executes
13787 @samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
13788 (@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
13789 Options}). The following example will make this clearer.
13793 [AS_HELP_STRING([--with-foo],
13794 [use foo (default is no)])],
13795 [ac_cv_use_foo=$withval],
13796 [ac_cv_use_foo=no])
13799 The second argument of @code{AS_HELP_STRING} is
13800 not a literal, and should not be double quoted.
13801 @xref{Autoconf Language}, for a more detailed explanation.
13802 Then the last few lines of @samp{configure --help} will appear like
13806 --enable and --with options recognized:
13807 --with-foo use foo (default is no)
13810 The @code{AS_HELP_STRING} macro is particularly helpful when the
13811 @var{left-hand-side} and/or @var{right-hand-side} are composed of macro
13812 arguments, as shown in the following example.
13815 AC_DEFUN([MY_ARG_WITH],
13817 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])],
13818 [ac_cv_use_[]$1=$withval],
13819 [ac_cv_use_[]$1=$2])])
13825 @section Configuring Site Details
13826 @cindex Site details
13828 Some software packages require complex site-specific information. Some
13829 examples are host names to use for certain services, company names, and
13830 email addresses to contact. Since some configuration scripts generated
13831 by Metaconfig ask for such information interactively, people sometimes
13832 wonder how to get that information in Autoconf-generated configuration
13833 scripts, which aren't interactive.
13835 Such site configuration information should be put in a file that is
13836 edited @emph{only by users}, not by programs. The location of the file
13837 can either be based on the @code{prefix} variable, or be a standard
13838 location such as the user's home directory. It could even be specified
13839 by an environment variable. The programs should examine that file at
13840 run time, rather than at compile time. Run-time configuration is more
13841 convenient for users and makes the configuration process simpler than
13842 getting the information while configuring. @xref{Directory Variables,,
13843 Variables for Installation Directories, standards, @acronym{GNU} Coding
13844 Standards}, for more information on where to put data files.
13846 @node Transforming Names
13847 @section Transforming Program Names When Installing
13848 @cindex Transforming program names
13849 @cindex Program names, transforming
13851 Autoconf supports changing the names of programs when installing them.
13852 In order to use these transformations, @file{configure.ac} must call the
13853 macro @code{AC_ARG_PROGRAM}.
13855 @defmac AC_ARG_PROGRAM
13856 @acindex{ARG_PROGRAM}
13857 @ovindex program_transform_name
13858 Place in output variable @code{program_transform_name} a sequence of
13859 @code{sed} commands for changing the names of installed programs.
13861 If any of the options described below are given to @command{configure},
13862 program names are transformed accordingly. Otherwise, if
13863 @code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
13864 is given, the target type followed by a dash is used as a prefix.
13865 Otherwise, no program name transformation is done.
13869 * Transformation Options:: @command{configure} options to transform names
13870 * Transformation Examples:: Sample uses of transforming names
13871 * Transformation Rules:: @file{Makefile} uses of transforming names
13874 @node Transformation Options
13875 @subsection Transformation Options
13877 You can specify name transformations by giving @command{configure} these
13878 command line options:
13881 @item --program-prefix=@var{prefix}
13882 prepend @var{prefix} to the names;
13884 @item --program-suffix=@var{suffix}
13885 append @var{suffix} to the names;
13887 @item --program-transform-name=@var{expression}
13888 perform @code{sed} substitution @var{expression} on the names.
13891 @node Transformation Examples
13892 @subsection Transformation Examples
13894 These transformations are useful with programs that can be part of a
13895 cross-compilation development environment. For example, a
13896 cross-assembler running on a Sun 4 configured with
13897 @option{--target=i960-vxworks} is normally installed as
13898 @file{i960-vxworks-as}, rather than @file{as}, which could be confused
13899 with a native Sun 4 assembler.
13901 You can force a program name to begin with @file{g}, if you don't want
13902 @acronym{GNU} programs installed on your system to shadow other programs with
13903 the same name. For example, if you configure @acronym{GNU} @code{diff} with
13904 @option{--program-prefix=g}, then when you run @samp{make install} it is
13905 installed as @file{/usr/local/bin/gdiff}.
13907 As a more sophisticated example, you could use
13910 --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
13914 to prepend @samp{g} to most of the program names in a source tree,
13915 excepting those like @code{gdb} that already have one and those like
13916 @code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is
13917 assuming that you have a source tree containing those programs that is
13918 set up to use this feature.)
13920 One way to install multiple versions of some programs simultaneously is
13921 to append a version number to the name of one or both. For example, if
13922 you want to keep Autoconf version 1 around for awhile, you can configure
13923 Autoconf version 2 using @option{--program-suffix=2} to install the
13924 programs as @file{/usr/local/bin/autoconf2},
13925 @file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
13926 that only the binaries are renamed, therefore you'd have problems with
13927 the library files which might overlap.
13929 @node Transformation Rules
13930 @subsection Transformation Rules
13932 Here is how to use the variable @code{program_transform_name} in a
13933 @file{Makefile.in}:
13936 PROGRAMS = cp ls rm
13937 transform = @@program_transform_name@@
13939 for p in $(PROGRAMS); do \
13940 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
13941 sed '$(transform)'`; \
13945 for p in $(PROGRAMS); do \
13946 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
13950 It is guaranteed that @code{program_transform_name} is never empty, and
13951 that there are no useless separators. Therefore you may safely embed
13952 @code{program_transform_name} within a sed program using @samp{;}:
13955 transform = @@program_transform_name@@
13956 transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
13959 Whether to do the transformations on documentation files (Texinfo or
13960 @code{man}) is a tricky question; there seems to be no perfect answer,
13961 due to the several reasons for name transforming. Documentation is not
13962 usually particular to a specific architecture, and Texinfo files do not
13963 conflict with system documentation. But they might conflict with
13964 earlier versions of the same files, and @code{man} pages sometimes do
13965 conflict with system documentation. As a compromise, it is probably
13966 best to do name transformations on @code{man} pages but not on Texinfo
13969 @node Site Defaults
13970 @section Setting Site Defaults
13971 @cindex Site defaults
13973 Autoconf-generated @command{configure} scripts allow your site to provide
13974 default values for some configuration values. You do this by creating
13975 site- and system-wide initialization files.
13977 @evindex CONFIG_SITE
13978 If the environment variable @code{CONFIG_SITE} is set, @command{configure}
13979 uses its value as the name of a shell script to read. Otherwise, it
13980 reads the shell script @file{@var{prefix}/share/config.site} if it exists,
13981 then @file{@var{prefix}/etc/config.site} if it exists. Thus,
13982 settings in machine-specific files override those in machine-independent
13983 ones in case of conflict.
13985 Site files can be arbitrary shell scripts, but only certain kinds of
13986 code are really appropriate to be in them. Because @command{configure}
13987 reads any cache file after it has read any site files, a site file can
13988 define a default cache file to be shared between all Autoconf-generated
13989 @command{configure} scripts run on that system (@pxref{Cache Files}). If
13990 you set a default cache file in a site file, it is a good idea to also
13991 set the output variable @code{CC} in that site file, because the cache
13992 file is only valid for a particular compiler, but many systems have
13995 You can examine or override the value set by a command line option to
13996 @command{configure} in a site file; options set shell variables that have
13997 the same names as the options, with any dashes turned into underscores.
13998 The exceptions are that @option{--without-} and @option{--disable-} options
13999 are like giving the corresponding @option{--with-} or @option{--enable-}
14000 option and the value @samp{no}. Thus, @option{--cache-file=localcache}
14001 sets the variable @code{cache_file} to the value @samp{localcache};
14002 @option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
14003 @code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
14004 variable @code{prefix} to the value @samp{/usr}; etc.
14006 Site files are also good places to set default values for other output
14007 variables, such as @code{CFLAGS}, if you need to give them non-default
14008 values: anything you would normally do, repetitively, on the command
14009 line. If you use non-default values for @var{prefix} or
14010 @var{exec_prefix} (wherever you locate the site file), you can set them
14011 in the site file if you specify it with the @code{CONFIG_SITE}
14012 environment variable.
14014 You can set some cache values in the site file itself. Doing this is
14015 useful if you are cross-compiling, where it is impossible to check features
14016 that require running a test program. You could ``prime the cache'' by
14017 setting those values correctly for that system in
14018 @file{@var{prefix}/etc/config.site}. To find out the names of the cache
14019 variables you need to set, look for shell variables with @samp{_cv_} in
14020 their names in the affected @command{configure} scripts, or in the Autoconf
14021 M4 source code for those macros.
14023 The cache file is careful to not override any variables set in the site
14024 files. Similarly, you should not override command-line options in the
14025 site files. Your code should check that variables such as @code{prefix}
14026 and @code{cache_file} have their default values (as set near the top of
14027 @command{configure}) before changing them.
14029 Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
14030 command @samp{configure --prefix=/usr/share/local/gnu} would read this
14031 file (if @code{CONFIG_SITE} is not set to a different file).
14034 # config.site for configure
14036 # Change some defaults.
14037 test "$prefix" = NONE && prefix=/usr/share/local/gnu
14038 test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
14039 test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
14040 test "$localstatedir" = '$prefix/var' && localstatedir=/var
14042 # Give Autoconf 2.x generated configure scripts a shared default
14043 # cache file for feature test results, architecture-specific.
14044 if test "$cache_file" = /dev/null; then
14045 cache_file="$prefix/var/config.cache"
14046 # A cache file is only valid for one C compiler.
14052 @c ============================================== Running configure Scripts.
14054 @node Running configure Scripts
14055 @chapter Running @command{configure} Scripts
14056 @cindex @command{configure}
14058 Below are instructions on how to configure a package that uses a
14059 @command{configure} script, suitable for inclusion as an @file{INSTALL}
14060 file in the package. A plain-text version of @file{INSTALL} which you
14061 may use comes with Autoconf.
14064 * Basic Installation:: Instructions for typical cases
14065 * Compilers and Options:: Selecting compilers and optimization
14066 * Multiple Architectures:: Compiling for multiple architectures at once
14067 * Installation Names:: Installing in different directories
14068 * Optional Features:: Selecting optional features
14069 * System Type:: Specifying the system type
14070 * Sharing Defaults:: Setting site-wide defaults for @command{configure}
14071 * Defining Variables:: Specifying the compiler etc.
14072 * configure Invocation:: Changing how @command{configure} runs
14076 @include install.texi
14079 @c ============================================== Recreating a Configuration
14081 @node config.status Invocation
14082 @chapter Recreating a Configuration
14083 @cindex @command{config.status}
14085 The @command{configure} script creates a file named @file{config.status},
14086 which actually configures, @dfn{instantiates}, the template files. It
14087 also records the configuration options that were specified when the
14088 package was last configured in case reconfiguring is needed.
14092 ./config.status @var{option}@dots{} [@var{file}@dots{}]
14095 It configures the @var{files}; if none are specified, all the templates
14096 are instantiated. The files must be specified without their
14097 dependencies, as in
14100 ./config.status foobar
14107 ./config.status foobar:foo.in:bar.in
14110 The supported @var{option}s are:
14115 Print a summary of the command line options, the list of the template
14120 Print the version number of Autoconf and exit.
14125 Do not print progress messages.
14129 Don't remove the temporary files.
14131 @item --file=@var{file}[:@var{template}]
14132 Require that @var{file} be instantiated as if
14133 @samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
14134 @var{file} and @var{template} may be @samp{-} in which case the standard
14135 output and/or standard input, respectively, is used. If a
14136 @var{template} file name is relative, it is first looked for in the build
14137 tree, and then in the source tree. @xref{Configuration Actions}, for
14140 This option and the following ones provide one way for separately
14141 distributed packages to share the values computed by @command{configure}.
14142 Doing so can be useful if some of the packages need a superset of the
14143 features that one of them, perhaps a common library, does. These
14144 options allow a @file{config.status} file to create files other than the
14145 ones that its @file{configure.ac} specifies, so it can be used for a
14148 @item --header=@var{file}[:@var{template}]
14149 Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
14152 Ask @file{config.status} to update itself and exit (no instantiation).
14153 This option is useful if you change @command{configure}, so that the
14154 results of some tests might be different from the previous run. The
14155 @option{--recheck} option re-runs @command{configure} with the same arguments
14156 you used before, plus the @option{--no-create} option, which prevents
14157 @command{configure} from running @file{config.status} and creating
14158 @file{Makefile} and other files, and the @option{--no-recursion} option,
14159 which prevents @command{configure} from running other @command{configure}
14160 scripts in subdirectories. (This is so other @file{Makefile} rules can
14161 run @file{config.status} when it changes; @pxref{Automatic Remaking},
14165 @file{config.status} checks several optional environment variables that
14166 can alter its behavior:
14168 @defvar CONFIG_SHELL
14169 @evindex CONFIG_SHELL
14170 The shell with which to run @command{configure} for the @option{--recheck}
14171 option. It must be Bourne-compatible. The default is a shell that
14172 supports @code{LINENO} if available, and @file{/bin/sh} otherwise.
14173 Invoking @command{configure} by hand bypasses this setting, so you may
14174 need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure}
14175 to insure that the same shell is used everywhere. The absolute name of the
14176 shell should be passed.
14179 @defvar CONFIG_STATUS
14180 @evindex CONFIG_STATUS
14181 The file name to use for the shell script that records the
14182 configuration. The default is @file{./config.status}. This variable is
14183 useful when one package uses parts of another and the @command{configure}
14184 scripts shouldn't be merged because they are maintained separately.
14187 You can use @file{./config.status} in your Makefiles. For example, in
14188 the dependencies given above (@pxref{Automatic Remaking}),
14189 @file{config.status} is run twice when @file{configure.ac} has changed.
14190 If that bothers you, you can make each run only regenerate the files for
14195 stamp-h: config.h.in config.status
14196 ./config.status config.h
14199 Makefile: Makefile.in config.status
14200 ./config.status Makefile
14204 The calling convention of @file{config.status} has changed; see
14205 @ref{Obsolete config.status Use}, for details.
14208 @c =================================================== Obsolete Constructs
14210 @node Obsolete Constructs
14211 @chapter Obsolete Constructs
14212 @cindex Obsolete constructs
14214 Autoconf changes, and throughout the years some constructs have been
14215 obsoleted. Most of the changes involve the macros, but in some cases
14216 the tools themselves, or even some concepts, are now considered
14219 You may completely skip this chapter if you are new to Autoconf. Its
14220 intention is mainly to help maintainers updating their packages by
14221 understanding how to move to more modern constructs.
14224 * Obsolete config.status Use:: Different calling convention
14225 * acconfig.h:: Additional entries in @file{config.h.in}
14226 * autoupdate Invocation:: Automatic update of @file{configure.ac}
14227 * Obsolete Macros:: Backward compatibility macros
14228 * Autoconf 1:: Tips for upgrading your files
14229 * Autoconf 2.13:: Some fresher tips
14232 @node Obsolete config.status Use
14233 @section Obsolete @file{config.status} Invocation
14235 @file{config.status} now supports arguments to specify the files to
14236 instantiate; see @ref{config.status Invocation}, for more details.
14237 Before, environment variables had to be used.
14239 @defvar CONFIG_COMMANDS
14240 @evindex CONFIG_COMMANDS
14241 The tags of the commands to execute. The default is the arguments given
14242 to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
14243 @file{configure.ac}.
14246 @defvar CONFIG_FILES
14247 @evindex CONFIG_FILES
14248 The files in which to perform @samp{@@@var{variable}@@} substitutions.
14249 The default is the arguments given to @code{AC_OUTPUT} and
14250 @code{AC_CONFIG_FILES} in @file{configure.ac}.
14253 @defvar CONFIG_HEADERS
14254 @evindex CONFIG_HEADERS
14255 The files in which to substitute C @code{#define} statements. The
14256 default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
14257 macro was not called, @file{config.status} ignores this variable.
14260 @defvar CONFIG_LINKS
14261 @evindex CONFIG_LINKS
14262 The symbolic links to establish. The default is the arguments given to
14263 @code{AC_CONFIG_LINKS}; if that macro was not called,
14264 @file{config.status} ignores this variable.
14267 In @ref{config.status Invocation}, using this old interface, the example
14273 stamp-h: config.h.in config.status
14274 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
14275 CONFIG_HEADERS=config.h ./config.status
14278 Makefile: Makefile.in config.status
14279 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
14280 CONFIG_FILES=Makefile ./config.status
14285 (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
14286 no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally
14287 for @code{CONFIG_COMMANDS}, etc.)
14291 @section @file{acconfig.h}
14293 @cindex @file{acconfig.h}
14294 @cindex @file{config.h.top}
14295 @cindex @file{config.h.bot}
14297 In order to produce @file{config.h.in}, @command{autoheader} needs to
14298 build or to find templates for each symbol. Modern releases of Autoconf
14299 use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
14300 Macros}), but in older releases a file, @file{acconfig.h}, contained the
14301 list of needed templates. @command{autoheader} copied comments and
14302 @code{#define} and @code{#undef} statements from @file{acconfig.h} in
14303 the current directory, if present. This file used to be mandatory if
14304 you @code{AC_DEFINE} any additional symbols.
14306 Modern releases of Autoconf also provide @code{AH_TOP} and
14307 @code{AH_BOTTOM} if you need to prepend/append some information to
14308 @file{config.h.in}. Ancient versions of Autoconf had a similar feature:
14309 if @file{./acconfig.h} contains the string @samp{@@TOP@@},
14310 @command{autoheader} copies the lines before the line containing
14311 @samp{@@TOP@@} into the top of the file that it generates. Similarly,
14312 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
14313 @command{autoheader} copies the lines after that line to the end of the
14314 file it generates. Either or both of those strings may be omitted. An
14315 even older alternate way to produce the same effect in ancient versions
14316 of Autoconf is to create the files @file{@var{file}.top} (typically
14317 @file{config.h.top}) and/or @file{@var{file}.bot} in the current
14318 directory. If they exist, @command{autoheader} copies them to the
14319 beginning and end, respectively, of its output.
14321 In former versions of Autoconf, the files used in preparing a software
14322 package for distribution were:
14325 configure.ac --. .------> autoconf* -----> configure
14327 [aclocal.m4] --+ `---.
14329 +--> [autoheader*] -> [config.h.in]
14330 [acconfig.h] ----. |
14337 Using only the @code{AH_} macros, @file{configure.ac} should be
14338 self-contained, and should not depend upon @file{acconfig.h} etc.
14341 @node autoupdate Invocation
14342 @section Using @command{autoupdate} to Modernize @file{configure.ac}
14343 @cindex @command{autoupdate}
14345 The @command{autoupdate} program updates a @file{configure.ac} file that
14346 calls Autoconf macros by their old names to use the current macro names.
14347 In version 2 of Autoconf, most of the macros were renamed to use a more
14348 uniform and descriptive naming scheme. @xref{Macro Names}, for a
14349 description of the new scheme. Although the old names still work
14350 (@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
14351 new names), you can make your @file{configure.ac} files more readable
14352 and make it easier to use the current Autoconf documentation if you
14353 update them to use the new macro names.
14355 @evindex SIMPLE_BACKUP_SUFFIX
14356 If given no arguments, @command{autoupdate} updates @file{configure.ac},
14357 backing up the original version with the suffix @file{~} (or the value
14358 of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
14359 set). If you give @command{autoupdate} an argument, it reads that file
14360 instead of @file{configure.ac} and writes the updated file to the
14364 @command{autoupdate} accepts the following options:
14369 Print a summary of the command line options and exit.
14373 Print the version number of Autoconf and exit.
14377 Report processing steps.
14381 Don't remove the temporary files.
14385 Force the update even if the file has not changed. Disregard the cache.
14387 @item --include=@var{dir}
14388 @itemx -I @var{dir}
14389 Also look for input files in @var{dir}. Multiple invocations accumulate.
14390 Directories are browsed from last to first.
14393 @node Obsolete Macros
14394 @section Obsolete Macros
14396 Several macros are obsoleted in Autoconf, for various reasons (typically
14397 they failed to quote properly, couldn't be extended for more recent
14398 issues, etc.). They are still supported, but deprecated: their use
14401 During the jump from Autoconf version 1 to version 2, most of the
14402 macros were renamed to use a more uniform and descriptive naming scheme,
14403 but their signature did not change. @xref{Macro Names}, for a
14404 description of the new naming scheme. Below, if there is just the mapping
14405 from old names to new names for these macros, the reader is invited to
14406 refer to the definition of the new macro for the signature and the
14411 @code{AC_FUNC_ALLOCA}
14414 @defmac AC_ARG_ARRAY
14415 @acindex{ARG_ARRAY}
14416 removed because of limited usefulness
14421 This macro is obsolete; it does nothing.
14424 @defmac AC_CANONICAL_SYSTEM
14425 @acindex{CANONICAL_SYSTEM}
14426 Determine the system type and set output variables to the names of the
14427 canonical system types. @xref{Canonicalizing}, for details about the
14428 variables this macro sets.
14430 The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
14431 @code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
14432 the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
14436 @defmac AC_CHAR_UNSIGNED
14437 @acindex{CHAR_UNSIGNED}
14438 @code{AC_C_CHAR_UNSIGNED}
14441 @defmac AC_CHECK_TYPE (@var{type}, @var{default})
14442 @acindex{CHECK_TYPE}
14443 Autoconf, up to 2.13, used to provide this version of
14444 @code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although
14445 it is a member of the @code{CHECK} clan, singular sub-family, it does
14446 more than just checking. Secondly, missing types are not
14447 @code{typedef}'d, they are @code{#define}'d, which can lead to
14448 incompatible code in the case of pointer types.
14450 This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see
14451 @ref{Generic Types}, for the description of the current macro.
14453 If the type @var{type} is not defined, define it to be the C (or C++)
14454 builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}.
14456 This macro is equivalent to:
14459 AC_CHECK_TYPE([@var{type}], [],
14460 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}],
14461 [Define to `@var{default}'
14462 if <sys/types.h> does not define.])])
14465 In order to keep backward compatibility, the two versions of
14466 @code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
14470 If there are three or four arguments, the modern version is used.
14473 If the second argument appears to be a C or C++ type, then the
14474 obsolete version is used. This happens if the argument is a C or C++
14475 @emph{builtin} type or a C identifier ending in @samp{_t}, optionally
14476 followed by one of @samp{[(* } and then by a string of zero or more
14477 characters taken from the set @samp{[]()* _a-zA-Z0-9}.
14480 If the second argument is spelled with the alphabet of valid C and C++
14481 types, the user is warned and the modern version is used.
14484 Otherwise, the modern version is used.
14488 You are encouraged either to use a valid builtin type, or to use the
14489 equivalent modern code (see above), or better yet, to use
14490 @code{AC_CHECK_TYPES} together with
14494 typedef loff_t off_t;
14498 @c end of AC_CHECK_TYPE
14500 @defmac AC_CHECKING (@var{feature-description})
14502 Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
14505 @defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
14506 @acindex{COMPILE_CHECK}
14507 This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by
14508 @code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the
14509 addition that it prints @samp{checking for @var{echo-text}} to the
14510 standard output first, if @var{echo-text} is non-empty. Use
14511 @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print
14512 messages (@pxref{Printing Messages}).
14520 @defmac AC_CROSS_CHECK
14521 @acindex{CROSS_CHECK}
14522 Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
14528 Check for the Cygwin environment in which case the shell variable
14529 @code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
14530 means to check the nature of the host is using
14531 @code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
14534 AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
14536 *cygwin* ) CYGWIN=yes;;
14541 Beware that the variable @code{CYGWIN} has a very special meaning when
14542 running CygWin32, and should not be changed. That's yet another reason
14543 not to use this macro.
14546 @defmac AC_DECL_SYS_SIGLIST
14547 @acindex{DECL_SYS_SIGLIST}
14548 @cvindex SYS_SIGLIST_DECLARED
14552 AC_CHECK_DECLS([sys_siglist], [], [],
14553 [#include <signal.h>
14554 /* NetBSD declares sys_siglist in unistd.h. */
14556 # include <unistd.h>
14562 @defmac AC_DECL_YYTEXT
14563 @acindex{DECL_YYTEXT}
14564 Does nothing, now integrated in @code{AC_PROG_LEX}.
14567 @defmac AC_DIR_HEADER
14568 @acindex{DIR_HEADER}
14573 Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
14574 but defines a different set of C preprocessor macros to indicate which
14575 header file is found:
14577 @multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
14578 @item Header @tab Old Symbol @tab New Symbol
14579 @item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
14580 @item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
14581 @item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
14582 @item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
14586 @defmac AC_DYNIX_SEQ
14587 @acindex{DYNIX_SEQ}
14588 If on DYNIX/ptx, add @option{-lseq} to output variable
14589 @code{LIBS}. This macro used to be defined as
14592 AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
14596 now it is just @code{AC_FUNC_GETMNTENT}.
14602 Defined the output variable @code{EXEEXT} based on the output of the
14603 compiler, which is now done automatically. Typically set to empty
14604 string if Posix and @samp{.exe} if a @acronym{DOS} variant.
14609 Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
14610 and sets @code{EMXOS2}.
14615 @code{AC_MSG_ERROR}
14623 @defmac AC_FIND_XTRA
14624 @acindex{FIND_XTRA}
14625 @code{AC_PATH_XTRA}
14628 @defmac AC_FUNC_CHECK
14629 @acindex{FUNC_CHECK}
14630 @code{AC_CHECK_FUNC}
14633 @defmac AC_FUNC_WAIT3
14634 @acindex{FUNC_WAIT3}
14635 @cvindex HAVE_WAIT3
14636 If @code{wait3} is found and fills in the contents of its third argument
14637 (a @samp{struct rusage *}), which HP-UX does not do, define
14640 These days portable programs should use @code{waitpid}, not
14641 @code{wait3}, as @code{wait3} has been removed from Posix.
14644 @defmac AC_GCC_TRADITIONAL
14645 @acindex{GCC_TRADITIONAL}
14646 @code{AC_PROG_GCC_TRADITIONAL}
14649 @defmac AC_GETGROUPS_T
14650 @acindex{GETGROUPS_T}
14651 @code{AC_TYPE_GETGROUPS}
14654 @defmac AC_GETLOADAVG
14655 @acindex{GETLOADAVG}
14656 @code{AC_FUNC_GETLOADAVG}
14659 @defmac AC_HAVE_FUNCS
14660 @acindex{HAVE_FUNCS}
14661 @code{AC_CHECK_FUNCS}
14664 @defmac AC_HAVE_HEADERS
14665 @acindex{HAVE_HEADERS}
14666 @code{AC_CHECK_HEADERS}
14669 @defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
14670 @acindex{HAVE_LIBRARY}
14671 This macro is equivalent to calling @code{AC_CHECK_LIB} with a
14672 @var{function} argument of @code{main}. In addition, @var{library} can
14673 be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
14674 all of those cases, the compiler is passed @option{-lfoo}. However,
14675 @var{library} cannot be a shell variable; it must be a literal name.
14678 @defmac AC_HAVE_POUNDBANG
14679 @acindex{HAVE_POUNDBANG}
14680 @code{AC_SYS_INTERPRETER} (different calling convention)
14683 @defmac AC_HEADER_CHECK
14684 @acindex{HEADER_CHECK}
14685 @code{AC_CHECK_HEADER}
14688 @defmac AC_HEADER_EGREP
14689 @acindex{HEADER_EGREP}
14690 @code{AC_EGREP_HEADER}
14693 @defmac AC_HELP_STRING
14694 @acindex{HELP_STRING}
14695 @code{AS_HELP_STRING}
14698 @defmac AC_INIT (@var{unique-file-in-source-dir})
14700 Formerly @code{AC_INIT} used to have a single argument, and was
14705 AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
14714 @defmac AC_INT_16_BITS
14715 @acindex{INT_16_BITS}
14716 @cvindex INT_16_BITS
14717 If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
14718 Use @samp{AC_CHECK_SIZEOF(int)} instead.
14721 @defmac AC_IRIX_SUN
14723 If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output
14724 @code{LIBS}. If you were using it to get @code{getmntent}, use
14725 @code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
14726 of the password and group functions, use @samp{AC_CHECK_LIB(sun,
14727 getpwnam)}. Up to Autoconf 2.13, it used to be
14730 AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
14734 now it is defined as
14738 AC_CHECK_LIB([sun], [getpwnam])
14744 Same as @samp{AC_LANG([C])}.
14747 @defmac AC_LANG_CPLUSPLUS
14748 @acindex{LANG_CPLUSPLUS}
14749 Same as @samp{AC_LANG([C++])}.
14752 @defmac AC_LANG_FORTRAN77
14753 @acindex{LANG_FORTRAN77}
14754 Same as @samp{AC_LANG([Fortran 77])}.
14757 @defmac AC_LANG_RESTORE
14758 @acindex{LANG_RESTORE}
14759 Select the @var{language} that is saved on the top of the stack, as set
14760 by @code{AC_LANG_SAVE}, remove it from the stack, and call
14761 @code{AC_LANG(@var{language})}.
14764 @defmac AC_LANG_SAVE
14765 @acindex{LANG_SAVE}
14766 Remember the current language (as set by @code{AC_LANG}) on a stack.
14767 The current language does not change. @code{AC_LANG_PUSH} is preferred.
14770 @defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
14771 @acindex{LINK_FILES}
14772 This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
14776 AC_LINK_FILES(config/$machine.h config/$obj_format.h,
14784 AC_CONFIG_LINKS([host.h:config/$machine.h
14785 object.h:config/$obj_format.h])
14791 @code{AC_PROG_LN_S}
14794 @defmac AC_LONG_64_BITS
14795 @acindex{LONG_64_BITS}
14796 @cvindex LONG_64_BITS
14797 Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
14798 Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
14801 @defmac AC_LONG_DOUBLE
14802 @acindex{LONG_DOUBLE}
14803 @code{AC_C_LONG_DOUBLE}
14806 @defmac AC_LONG_FILE_NAMES
14807 @acindex{LONG_FILE_NAMES}
14808 @code{AC_SYS_LONG_FILE_NAMES}
14811 @defmac AC_MAJOR_HEADER
14812 @acindex{MAJOR_HEADER}
14813 @code{AC_HEADER_MAJOR}
14816 @defmac AC_MEMORY_H
14818 @cvindex NEED_MEMORY_H
14819 Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
14820 defined in @file{memory.h}. Today it is equivalent to
14821 @samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon
14822 @code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard
14828 Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
14829 environment and sets @code{MINGW32}.
14832 @defmac AC_MINUS_C_MINUS_O
14833 @acindex{MINUS_C_MINUS_O}
14834 @code{AC_PROG_CC_C_O}
14839 @code{AC_FUNC_MMAP}
14844 @code{AC_TYPE_MODE_T}
14850 Defined the output variable @code{OBJEXT} based on the output of the
14851 compiler, after .c files have been excluded. Typically set to @samp{o}
14852 if Posix, @samp{obj} if a @acronym{DOS} variant.
14853 Now the compiler checking macros handle
14854 this automatically.
14857 @defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
14859 Make M4 print a message to the standard error output warning that
14860 @var{this-macro-name} is obsolete, and giving the file and line number
14861 where it was called. @var{this-macro-name} should be the name of the
14862 macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
14863 it is printed at the end of the warning message; for example, it can be
14864 a suggestion for what to use instead of @var{this-macro-name}.
14869 AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
14872 You are encouraged to use @code{AU_DEFUN} instead, since it gives better
14873 services to the user.
14878 @code{AC_TYPE_OFF_T}
14881 @defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
14883 The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted
14884 interface is equivalent to:
14888 AC_CONFIG_FILES(@var{file}@dots{})
14889 AC_CONFIG_COMMANDS([default],
14890 @var{extra-cmds}, @var{init-cmds})
14896 @defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
14897 @acindex{OUTPUT_COMMANDS}
14898 Specify additional shell commands to run at the end of
14899 @file{config.status}, and shell commands to initialize any variables
14900 from @command{configure}. This macro may be called multiple times. It is
14901 obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
14903 Here is an unrealistic example:
14907 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
14909 AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
14913 Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
14914 additional key, an important difference is that
14915 @code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike
14916 @code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
14917 can safely be given macro calls as arguments:
14920 AC_CONFIG_COMMANDS(foo, [my_FOO()])
14924 Conversely, where one level of quoting was enough for literal strings
14925 with @code{AC_OUTPUT_COMMANDS}, you need two with
14926 @code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
14930 AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
14931 AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
14938 @code{AC_TYPE_PID_T}
14943 @code{AC_PREFIX_PROGRAM}
14946 @defmac AC_PROGRAMS_CHECK
14947 @acindex{PROGRAMS_CHECK}
14948 @code{AC_CHECK_PROGS}
14951 @defmac AC_PROGRAMS_PATH
14952 @acindex{PROGRAMS_PATH}
14953 @code{AC_PATH_PROGS}
14956 @defmac AC_PROGRAM_CHECK
14957 @acindex{PROGRAM_CHECK}
14958 @code{AC_CHECK_PROG}
14961 @defmac AC_PROGRAM_EGREP
14962 @acindex{PROGRAM_EGREP}
14963 @code{AC_EGREP_CPP}
14966 @defmac AC_PROGRAM_PATH
14967 @acindex{PROGRAM_PATH}
14968 @code{AC_PATH_PROG}
14971 @defmac AC_REMOTE_TAPE
14972 @acindex{REMOTE_TAPE}
14973 removed because of limited usefulness
14976 @defmac AC_RESTARTABLE_SYSCALLS
14977 @acindex{RESTARTABLE_SYSCALLS}
14978 @code{AC_SYS_RESTARTABLE_SYSCALLS}
14981 @defmac AC_RETSIGTYPE
14982 @acindex{RETSIGTYPE}
14983 @code{AC_TYPE_SIGNAL}
14988 removed because of limited usefulness
14991 @defmac AC_SCO_INTL
14994 If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This
14995 macro used to do this:
14998 AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
15002 Now it just calls @code{AC_FUNC_STRFTIME} instead.
15005 @defmac AC_SETVBUF_REVERSED
15006 @acindex{SETVBUF_REVERSED}
15007 @code{AC_FUNC_SETVBUF_REVERSED}
15010 @defmac AC_SET_MAKE
15012 @code{AC_PROG_MAKE_SET}
15015 @defmac AC_SIZEOF_TYPE
15016 @acindex{SIZEOF_TYPE}
15017 @code{AC_CHECK_SIZEOF}
15022 @code{AC_TYPE_SIZE_T}
15025 @defmac AC_STAT_MACROS_BROKEN
15026 @acindex{STAT_MACROS_BROKEN}
15027 @code{AC_HEADER_STAT}
15030 @defmac AC_STDC_HEADERS
15031 @acindex{STDC_HEADERS}
15032 @code{AC_HEADER_STDC}
15037 @code{AC_FUNC_STRCOLL}
15040 @defmac AC_ST_BLKSIZE
15041 @acindex{ST_BLKSIZE}
15042 @code{AC_CHECK_MEMBERS}
15045 @defmac AC_ST_BLOCKS
15046 @acindex{ST_BLOCKS}
15047 @code{AC_STRUCT_ST_BLOCKS}
15052 @code{AC_CHECK_MEMBERS}
15055 @defmac AC_SYS_RESTARTABLE_SYSCALLS
15056 @acindex{SYS_RESTARTABLE_SYSCALLS}
15057 @cvindex HAVE_RESTARTABLE_SYSCALLS
15058 If the system automatically restarts a system call that is interrupted
15059 by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
15060 not check whether system calls are restarted in general---it checks whether a
15061 signal handler installed with @code{signal} (but not @code{sigaction})
15062 causes system calls to be restarted. It does not check whether system calls
15063 can be restarted when interrupted by signals that have no handler.
15065 These days portable programs should use @code{sigaction} with
15066 @code{SA_RESTART} if they want restartable system calls. They should
15067 not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
15068 system call is restartable is a dynamic issue, not a configuration-time
15072 @defmac AC_SYS_SIGLIST_DECLARED
15073 @acindex{SYS_SIGLIST_DECLARED}
15074 @code{AC_DECL_SYS_SIGLIST}
15077 @defmac AC_TEST_CPP
15079 @code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}.
15082 @defmac AC_TEST_PROGRAM
15083 @acindex{TEST_PROGRAM}
15084 @code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}.
15087 @defmac AC_TIMEZONE
15089 @code{AC_STRUCT_TIMEZONE}
15092 @defmac AC_TIME_WITH_SYS_TIME
15093 @acindex{TIME_WITH_SYS_TIME}
15094 @code{AC_HEADER_TIME}
15097 @defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
15098 @acindex{TRY_COMPILE}
15103 [AC_LANG_PROGRAM([[@var{includes}]],
15104 [[@var{function-body}]])],
15105 [@var{action-if-true}],
15106 [@var{action-if-false}])
15110 @xref{Running the Compiler}.
15112 This macro double quotes both @var{includes} and @var{function-body}.
15114 For C and C++, @var{includes} is any @code{#include} statements needed
15115 by the code in @var{function-body} (@var{includes} will be ignored if
15116 the currently selected language is Fortran or Fortran 77). The compiler
15117 and compilation flags are determined by the current language
15118 (@pxref{Language Choice}).
15121 @defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
15127 [AC_LANG_SOURCE([[@var{input}]])],
15128 [@var{action-if-true}],
15129 [@var{action-if-false}])
15133 @xref{Running the Preprocessor}.
15135 This macro double quotes the @var{input}.
15138 @defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
15144 [AC_LANG_PROGRAM([[@var{includes}]],
15145 [[@var{function-body}]])],
15146 [@var{action-if-true}],
15147 [@var{action-if-false}])
15151 @xref{Running the Compiler}.
15153 This macro double quotes both @var{includes} and @var{function-body}.
15155 Depending on the current language (@pxref{Language Choice}), create a
15156 test program to see whether a function whose body consists of
15157 @var{function-body} can be compiled and linked. If the file compiles
15158 and links successfully, run shell commands @var{action-if-found},
15159 otherwise run @var{action-if-not-found}.
15161 This macro double quotes both @var{includes} and @var{function-body}.
15163 For C and C++, @var{includes} is any @code{#include} statements needed
15164 by the code in @var{function-body} (@var{includes} will be ignored if
15165 the currently selected language is Fortran or Fortran 77). The compiler
15166 and compilation flags are determined by the current language
15167 (@pxref{Language Choice}), and in addition @code{LDFLAGS} and
15168 @code{LIBS} are used for linking.
15171 @defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
15172 @acindex{TRY_LINK_FUNC}
15173 This macro is equivalent to
15174 @samp{AC_LINK_IFELSE([AC_LANG_CALL([[@var{includes}]],
15175 [[@var{function-body}]])], [@var{action-if-true}],
15176 [@var{action-if-false}])}.
15179 @defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
15185 [AC_LANG_SOURCE([[@var{program}]])],
15186 [@var{action-if-true}],
15187 [@var{action-if-false}],
15188 [@var{action-if-cross-compiling}])
15197 @code{AC_TYPE_UID_T}
15200 @defmac AC_UNISTD_H
15202 Same as @samp{AC_CHECK_HEADERS([unistd.h])}.
15208 Define @code{USG} if the @acronym{BSD} string functions are defined in
15209 @file{strings.h}. You should no longer depend upon @code{USG}, but on
15210 @code{HAVE_STRING_H}; see @ref{Standard Symbols}.
15213 @defmac AC_UTIME_NULL
15214 @acindex{UTIME_NULL}
15215 @code{AC_FUNC_UTIME_NULL}
15218 @defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
15219 @acindex{VALIDATE_CACHED_SYSTEM_TUPLE}
15220 If the cache file is inconsistent with the current host, target and
15221 build system types, it used to execute @var{cmd} or print a default
15222 error message. This is now handled by default.
15225 @defmac AC_VERBOSE (@var{result-description})
15227 @code{AC_MSG_RESULT}.
15232 @code{AC_FUNC_VFORK}
15237 @code{AC_FUNC_VPRINTF}
15242 @code{AC_FUNC_WAIT3}
15250 @defmac AC_WORDS_BIGENDIAN
15251 @acindex{WORDS_BIGENDIAN}
15252 @code{AC_C_BIGENDIAN}
15255 @defmac AC_XENIX_DIR
15256 @acindex{XENIX_DIR}
15258 This macro used to add @option{-lx} to output variable @code{LIBS} if on
15259 Xenix. Also, if @file{dirent.h} is being checked for, added
15260 @option{-ldir} to @code{LIBS}. Now it is merely an alias of
15261 @code{AC_HEADER_DIRENT} instead, plus some code to detect whether
15262 running @sc{xenix} on which you should not depend:
15265 AC_MSG_CHECKING([for Xenix])
15266 AC_EGREP_CPP([yes],
15267 [#if defined M_XENIX && !defined M_UNIX
15270 [AC_MSG_RESULT([yes]); XENIX=yes],
15271 [AC_MSG_RESULT([no]); XENIX=])
15275 @defmac AC_YYTEXT_POINTER
15276 @acindex{YYTEXT_POINTER}
15277 @code{AC_DECL_YYTEXT}
15281 @section Upgrading From Version 1
15282 @cindex Upgrading autoconf
15283 @cindex Autoconf upgrading
15285 Autoconf version 2 is mostly backward compatible with version 1.
15286 However, it introduces better ways to do some things, and doesn't
15287 support some of the ugly things in version 1. So, depending on how
15288 sophisticated your @file{configure.ac} files are, you might have to do
15289 some manual work in order to upgrade to version 2. This chapter points
15290 out some problems to watch for when upgrading. Also, perhaps your
15291 @command{configure} scripts could benefit from some of the new features in
15292 version 2; the changes are summarized in the file @file{NEWS} in the
15293 Autoconf distribution.
15296 * Changed File Names:: Files you might rename
15297 * Changed Makefiles:: New things to put in @file{Makefile.in}
15298 * Changed Macros:: Macro calls you might replace
15299 * Changed Results:: Changes in how to check test results
15300 * Changed Macro Writing:: Better ways to write your own macros
15303 @node Changed File Names
15304 @subsection Changed File Names
15306 If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
15307 in a particular package's source directory), you must rename it to
15308 @file{acsite.m4}. @xref{autoconf Invocation}.
15310 If you distribute @file{install.sh} with your package, rename it to
15311 @file{install-sh} so @code{make} builtin rules won't inadvertently
15312 create a file called @file{install} from it. @code{AC_PROG_INSTALL}
15313 looks for the script under both names, but it is best to use the new name.
15315 If you were using @file{config.h.top}, @file{config.h.bot}, or
15316 @file{acconfig.h}, you still can, but you will have less clutter if you
15317 use the @code{AH_} macros. @xref{Autoheader Macros}.
15319 @node Changed Makefiles
15320 @subsection Changed Makefiles
15322 Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
15323 your @file{Makefile.in} files, so they can take advantage of the values
15324 of those variables in the environment when @command{configure} is run.
15325 Doing this isn't necessary, but it's a convenience for users.
15327 Also add @samp{@@configure_input@@} in a comment to each input file for
15328 @code{AC_OUTPUT}, so that the output files will contain a comment saying
15329 they were produced by @command{configure}. Automatically selecting the
15330 right comment syntax for all the kinds of files that people call
15331 @code{AC_OUTPUT} on became too much work.
15333 Add @file{config.log} and @file{config.cache} to the list of files you
15334 remove in @code{distclean} targets.
15336 If you have the following in @file{Makefile.in}:
15339 prefix = /usr/local
15340 exec_prefix = $(prefix)
15344 you must change it to:
15347 prefix = @@prefix@@
15348 exec_prefix = @@exec_prefix@@
15352 The old behavior of replacing those variables without @samp{@@}
15353 characters around them has been removed.
15355 @node Changed Macros
15356 @subsection Changed Macros
15358 Many of the macros were renamed in Autoconf version 2. You can still
15359 use the old names, but the new ones are clearer, and it's easier to find
15360 the documentation for them. @xref{Obsolete Macros}, for a table showing the
15361 new names for the old macros. Use the @command{autoupdate} program to
15362 convert your @file{configure.ac} to using the new macro names.
15363 @xref{autoupdate Invocation}.
15365 Some macros have been superseded by similar ones that do the job better,
15366 but are not call-compatible. If you get warnings about calling obsolete
15367 macros while running @command{autoconf}, you may safely ignore them, but
15368 your @command{configure} script will generally work better if you follow
15369 the advice that is printed about what to replace the obsolete macros with. In
15370 particular, the mechanism for reporting the results of tests has
15371 changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps
15372 via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
15373 look better if you switch to @code{AC_MSG_CHECKING} and
15374 @code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
15375 in conjunction with cache variables. @xref{Caching Results}.
15379 @node Changed Results
15380 @subsection Changed Results
15382 If you were checking the results of previous tests by examining the
15383 shell variable @code{DEFS}, you need to switch to checking the values of
15384 the cache variables for those tests. @code{DEFS} no longer exists while
15385 @command{configure} is running; it is only created when generating output
15386 files. This difference from version 1 is because properly quoting the
15387 contents of that variable turned out to be too cumbersome and
15388 inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
15391 For example, here is a @file{configure.ac} fragment written for Autoconf
15395 AC_HAVE_FUNCS(syslog)
15397 *-DHAVE_SYSLOG*) ;;
15398 *) # syslog is not in the default libraries. See if it's in some other.
15400 for lib in bsd socket inet; do
15401 AC_CHECKING(for syslog in -l$lib)
15402 LIBS="-l$lib $saved_LIBS"
15403 AC_HAVE_FUNCS(syslog)
15405 *-DHAVE_SYSLOG*) break ;;
15413 Here is a way to write it for version 2:
15416 AC_CHECK_FUNCS([syslog])
15417 if test $ac_cv_func_syslog = no; then
15418 # syslog is not in the default libraries. See if it's in some other.
15419 for lib in bsd socket inet; do
15420 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG])
15421 LIBS="-l$lib $LIBS"; break])
15426 If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
15427 backslashes before quotes, you need to remove them. It now works
15428 predictably, and does not treat quotes (except back quotes) specially.
15429 @xref{Setting Output Variables}.
15431 All of the Boolean shell variables set by Autoconf macros now use
15432 @samp{yes} for the true value. Most of them use @samp{no} for false,
15433 though for backward compatibility some use the empty string instead. If
15434 you were relying on a shell variable being set to something like 1 or
15435 @samp{t} for true, you need to change your tests.
15437 @node Changed Macro Writing
15438 @subsection Changed Macro Writing
15440 When defining your own macros, you should now use @code{AC_DEFUN}
15441 instead of @code{define}. @code{AC_DEFUN} automatically calls
15442 @code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
15443 do not interrupt other macros, to prevent nested @samp{checking@dots{}}
15444 messages on the screen. There's no actual harm in continuing to use the
15445 older way, but it's less convenient and attractive. @xref{Macro
15448 You probably looked at the macros that came with Autoconf as a guide for
15449 how to do things. It would be a good idea to take a look at the new
15450 versions of them, as the style is somewhat improved and they take
15451 advantage of some new features.
15453 If you were doing tricky things with undocumented Autoconf internals
15454 (macros, variables, diversions), check whether you need to change
15455 anything to account for changes that have been made. Perhaps you can
15456 even use an officially supported technique in version 2 instead of
15457 kludging. Or perhaps not.
15459 To speed up your locally written feature tests, add caching to them.
15460 See whether any of your tests are of general enough usefulness to
15461 encapsulate them into macros that you can share.
15464 @node Autoconf 2.13
15465 @section Upgrading From Version 2.13
15466 @cindex Upgrading autoconf
15467 @cindex Autoconf upgrading
15469 The introduction of the previous section (@pxref{Autoconf 1}) perfectly
15470 suits this section@enddots{}
15473 Autoconf version 2.50 is mostly backward compatible with version 2.13.
15474 However, it introduces better ways to do some things, and doesn't
15475 support some of the ugly things in version 2.13. So, depending on how
15476 sophisticated your @file{configure.ac} files are, you might have to do
15477 some manual work in order to upgrade to version 2.50. This chapter
15478 points out some problems to watch for when upgrading. Also, perhaps
15479 your @command{configure} scripts could benefit from some of the new
15480 features in version 2.50; the changes are summarized in the file
15481 @file{NEWS} in the Autoconf distribution.
15485 * Changed Quotation:: Broken code which used to work
15486 * New Macros:: Interaction with foreign macros
15487 * Hosts and Cross-Compilation:: Bugward compatibility kludges
15488 * AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token
15489 * AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources
15492 @node Changed Quotation
15493 @subsection Changed Quotation
15495 The most important changes are invisible to you: the implementation of
15496 most macros have completely changed. This allowed more factorization of
15497 the code, better error messages, a higher uniformity of the user's
15498 interface etc. Unfortunately, as a side effect, some construct which
15499 used to (miraculously) work might break starting with Autoconf 2.50.
15500 The most common culprit is bad quotation.
15502 For instance, in the following example, the message is not properly
15507 AC_CHECK_HEADERS(foo.h,,
15508 AC_MSG_ERROR(cannot find foo.h, bailing out))
15513 Autoconf 2.13 simply ignores it:
15516 $ @kbd{autoconf-2.13; ./configure --silent}
15517 creating cache ./config.cache
15518 configure: error: cannot find foo.h
15523 while Autoconf 2.50 will produce a broken @file{configure}:
15526 $ @kbd{autoconf-2.50; ./configure --silent}
15527 configure: error: cannot find foo.h
15528 ./configure: exit: bad non-numeric arg `bailing'
15529 ./configure: exit: bad non-numeric arg `bailing'
15533 The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
15537 AC_INIT([Example], [1.0], [bug-example@@example.org])
15538 AC_CHECK_HEADERS([foo.h], [],
15539 [AC_MSG_ERROR([cannot find foo.h, bailing out])])
15543 Many many (and many more) Autoconf macros were lacking proper quotation,
15544 including no less than@dots{} @code{AC_DEFUN} itself!
15547 $ @kbd{cat configure.in}
15548 AC_DEFUN([AC_PROG_INSTALL],
15549 [# My own much better version
15554 $ @kbd{autoconf-2.13}
15555 autoconf: Undefined macros:
15556 ***BUG in Autoconf--please report*** AC_FD_MSG
15557 ***BUG in Autoconf--please report*** AC_EPI
15558 configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
15559 configure.in:5:AC_PROG_INSTALL
15560 $ @kbd{autoconf-2.50}
15566 @subsection New Macros
15568 @cindex undefined macro
15569 @cindex @code{_m4_divert_diversion}
15571 While Autoconf was relatively dormant in the late 1990s, Automake
15572 provided Autoconf-like macros for a while. Starting with Autoconf 2.50
15573 in 2001, Autoconf provided
15574 versions of these macros, integrated in the @code{AC_} namespace,
15575 instead of @code{AM_}. But in order to ease the upgrading via
15576 @command{autoupdate}, bindings to such @code{AM_} macros are provided.
15578 Unfortunately older versions of Automake (e.g., Automake 1.4)
15579 did not quote the names of these macros.
15580 Therefore, when @command{m4} finds something like
15581 @samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4},
15582 @code{AM_TYPE_PTRDIFF_T} is
15583 expanded, replaced with its Autoconf definition.
15585 Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
15586 complain, in its own words:
15589 $ @kbd{cat configure.ac}
15590 AC_INIT([Example], [1.0], [bug-example@@example.org])
15592 $ @kbd{aclocal-1.4}
15594 aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
15595 aclocal.m4:17: the top level
15596 autom4te: m4 failed with exit status: 1
15600 Modern versions of Automake no longer define most of these
15601 macros, and will properly quote the names of the remaining macros.
15602 If you must use an old Automake, do not depend upon macros from Automake
15603 as it is simply not its job
15604 to provide macros (but the one it requires itself):
15607 $ @kbd{cat configure.ac}
15608 AC_INIT([Example], [1.0], [bug-example@@example.org])
15610 $ @kbd{rm aclocal.m4}
15612 autoupdate: `configure.ac' is updated
15613 $ @kbd{cat configure.ac}
15614 AC_INIT([Example], [1.0], [bug-example@@example.org])
15615 AC_CHECK_TYPES([ptrdiff_t])
15616 $ @kbd{aclocal-1.4}
15622 @node Hosts and Cross-Compilation
15623 @subsection Hosts and Cross-Compilation
15624 @cindex Cross compilation
15626 Based on the experience of compiler writers, and after long public
15627 debates, many aspects of the cross-compilation chain have changed:
15631 the relationship between the build, host, and target architecture types,
15634 the command line interface for specifying them to @command{configure},
15637 the variables defined in @command{configure},
15640 the enabling of cross-compilation mode.
15645 The relationship between build, host, and target have been cleaned up:
15646 the chain of default is now simply: target defaults to host, host to
15647 build, and build to the result of @command{config.guess}. Nevertheless,
15648 in order to ease the transition from 2.13 to 2.50, the following
15649 transition scheme is implemented. @emph{Do not rely on it}, as it will
15650 be completely disabled in a couple of releases (we cannot keep it, as it
15651 proves to cause more problems than it cures).
15653 They all default to the result of running @command{config.guess}, unless
15654 you specify either @option{--build} or @option{--host}. In this case,
15655 the default becomes the system type you specified. If you specify both,
15656 and they're different, @command{configure} will enter cross compilation
15657 mode, so it won't run any tests that require execution.
15659 Hint: if you mean to override the result of @command{config.guess},
15660 prefer @option{--build} over @option{--host}. In the future,
15661 @option{--host} will not override the name of the build system type.
15662 Whenever you specify @code{--host}, be sure to specify @code{--build}
15667 For backward compatibility, @command{configure} will accept a system
15668 type as an option by itself. Such an option will override the
15669 defaults for build, host, and target system types. The following
15670 configure statement will configure a cross toolchain that will run on
15671 Net@acronym{BSD}/alpha but generate code for @acronym{GNU} Hurd/sparc, which is
15672 also the build platform.
15675 ./configure --host=alpha-netbsd sparc-gnu
15680 In Autoconf 2.13 and before, the variables @code{build}, @code{host},
15681 and @code{target} had a different semantics before and after the
15682 invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of
15683 @option{--build} is strictly copied into @code{build_alias}, and is left
15684 empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is
15685 set to the canonicalized build type. To ease the transition, before,
15686 its contents is the same as that of @code{build_alias}. Do @emph{not}
15687 rely on this broken feature.
15689 For consistency with the backward compatibility scheme exposed above,
15690 when @option{--host} is specified but @option{--build} isn't, the build
15691 system will be assumed to be the same as @option{--host}, and
15692 @samp{build_alias} will be set to that value. Eventually, this
15693 historically incorrect behavior will go away.
15697 The former scheme to enable cross-compilation proved to cause more harm
15698 than good, in particular, it used to be triggered too easily, leaving
15699 regular end users puzzled in front of cryptic error messages.
15700 @command{configure} could even enter cross-compilation mode only
15701 because the compiler was not functional. This is mainly because
15702 @command{configure} used to try to detect cross-compilation, instead of
15703 waiting for an explicit flag from the user.
15705 Now, @command{configure} enters cross-compilation mode if and only if
15706 @option{--host} is passed.
15708 That's the short documentation. To ease the transition between 2.13 and
15709 its successors, a more complicated scheme is implemented. @emph{Do not
15710 rely on the following}, as it will be removed in the near future.
15712 If you specify @option{--host}, but not @option{--build}, when
15713 @command{configure} performs the first compiler test it will try to run
15714 an executable produced by the compiler. If the execution fails, it will
15715 enter cross-compilation mode. This is fragile. Moreover, by the time
15716 the compiler test is performed, it may be too late to modify the
15717 build-system type: other tests may have already been performed.
15718 Therefore, whenever you specify @code{--host}, be sure to specify
15719 @code{--build} too.
15722 ./configure --build=i686-pc-linux-gnu --host=m68k-coff
15726 will enter cross-compilation mode. The former interface, which
15727 consisted in setting the compiler to a cross-compiler without informing
15728 @command{configure} is obsolete. For instance, @command{configure} will
15729 fail if it can't run the code generated by the specified compiler if you
15730 configure as follows:
15733 ./configure CC=m68k-coff-gcc
15737 @node AC_LIBOBJ vs LIBOBJS
15738 @subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}
15740 Up to Autoconf 2.13, the replacement of functions was triggered via the
15741 variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
15742 @code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
15743 Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
15745 This change is mandated by the unification of the @acronym{GNU} Build System
15746 components. In particular, the various fragile techniques used to parse
15747 a @file{configure.ac} are all replaced with the use of traces. As a
15748 consequence, any action must be traceable, which obsoletes critical
15749 variable assignments. Fortunately, @code{LIBOBJS} was the only problem,
15750 and it can even be handled gracefully (read, ``without your having to
15751 change something'').
15753 There were two typical uses of @code{LIBOBJS}: asking for a replacement
15754 function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
15758 As for function replacement, the fix is immediate: use
15759 @code{AC_LIBOBJ}. For instance:
15762 LIBOBJS="$LIBOBJS fnmatch.o"
15763 LIBOBJS="$LIBOBJS malloc.$ac_objext"
15767 should be replaced with:
15770 AC_LIBOBJ([fnmatch])
15771 AC_LIBOBJ([malloc])
15778 When asked for automatic de-ANSI-fication, Automake needs
15779 @code{LIBOBJS}'ed file names to have @samp{$U} appended to the base
15780 names. Libtool requires the definition of @code{LTLIBOBJS}, whose
15781 suffixes are mapped to @samp{.lo}. People used to run snippets such as:
15784 # This is necessary so that .o files in LIBOBJS are also built via
15785 # the ANSI2KNR-filtering rules.
15786 LIBOBJS=`echo "$LIBOBJS" | sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
15787 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/\.lo/g'`
15788 AC_SUBST([LTLIBOBJS])
15792 Note that this code is @emph{wrong}, because @samp{.o} is not the only
15793 possible extension@footnote{
15795 Yet another reason why assigning @code{LIBOBJS} directly is discouraged.
15797 }! It should have read:
15800 # This is necessary so that .o files in LIBOBJS are also built via
15801 # the ANSI2KNR-filtering rules.
15802 LIB@@&t@@OBJS=`echo "$LIB@@&t@@OBJS" |
15803 sed 's,\.[[^.]]* ,$U&,g;s,\.[[^.]]*$,$U&,'`
15804 LTLIBOBJS=`echo "$LIB@@&t@@OBJS" |
15805 sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`
15806 AC_SUBST([LTLIBOBJS])
15811 You no longer have to use this: @code{AC_OUTPUT} normalizes
15812 @code{LIBOBJS} and @code{LTLIBOBJS} (hence it works with any version of
15813 Automake and Libtool). Just remove these lines (@command{autoupdate}
15814 cannot handle this task, since this is not a macro).
15816 Note that @code{U} must not be used in your Makefiles.
15819 When used with Automake 1.10 or newer, a suitable value for
15820 @code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS}
15821 can be referenced from any @file{Makefile.am}. Even without Automake,
15822 arranging for @code{LIBOBJDIR} to be set correctly will enable
15823 referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory.
15826 @node AC_FOO_IFELSE vs AC_TRY_FOO
15827 @subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO}
15829 Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE},
15830 @code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and
15831 @code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES},
15832 and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated
15833 @code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and
15834 @code{AC_TRY_RUN}. The motivations where:
15837 a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double
15838 quoting their arguments;
15841 the combinatoric explosion is solved by decomposing on the one hand the
15842 generation of sources, and on the other hand executing the program;
15845 this scheme helps supporting more languages than plain C and C++.
15848 In addition to the change of syntax, the philosphy has changed too:
15849 while emphasis was put on speed at the expense of accuracy, today's
15850 Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the
15854 As a perfect example of what is @emph{not} to be done, here is how to
15855 find out whether a header file contains a particular declaration, such
15856 as a typedef, a structure, a structure member, or a function. Use
15857 @code{AC_EGREP_HEADER} instead of running @code{grep} directly on the
15858 header file; on some systems the symbol might be defined in another
15859 header file that the file you are checking @samp{#include}s.
15861 As a (bad) example, here is how you should not check for C preprocessor
15862 symbols, either defined by header files or predefined by the C
15863 preprocessor: using @code{AC_EGREP_CPP}:
15871 ], is_aix=yes, is_aix=no)
15875 The above example, properly written would (i) use
15876 @code{AC_LANG_PROGRAM}, and (ii) run the compiler:
15880 AC_COMPILE_IFELSE([AC_LANG_PROGRAM(
15881 [[#if !defined _AIX
15882 # error _AIX not defined
15891 @c ============================= Generating Test Suites with Autotest
15893 @node Using Autotest
15894 @chapter Generating Test Suites with Autotest
15899 @strong{N.B.: This section describes an experimental feature which will
15900 be part of Autoconf in a forthcoming release. Although we believe
15901 Autotest is stabilizing, this documentation describes an interface which
15902 might change in the future: do not depend upon Autotest without
15903 subscribing to the Autoconf mailing lists.}
15906 It is paradoxical that portable projects depend on nonportable tools
15907 to run their test suite. Autoconf by itself is the paragon of this
15908 problem: although it aims at perfectly portability, up to 2.13 its
15909 test suite was using Deja@acronym{GNU}, a rich and complex testing
15910 framework, but which is far from being standard on Posix systems.
15911 Worse yet, it was likely to be missing on the most fragile platforms,
15912 the very platforms that are most likely to torture Autoconf and
15913 exhibit deficiencies.
15915 To circumvent this problem, many package maintainers have developed their
15916 own testing framework, based on simple shell scripts whose sole outputs
15917 are exit status values describing whether the test succeeded. Most of
15918 these tests share common patterns, and this can result in lots of
15919 duplicated code and tedious maintenance.
15921 Following exactly the same reasoning that yielded to the inception of
15922 Autoconf, Autotest provides a test suite generation framework, based on
15923 M4 macros building a portable shell script. The suite itself is
15924 equipped with automatic logging and tracing facilities which greatly
15925 diminish the interaction with bug reporters, and simple timing reports.
15927 Autoconf itself has been using Autotest for years, and we do attest that
15928 it has considerably improved the strength of the test suite and the
15929 quality of bug reports. Other projects are known to use some generation
15930 of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of
15931 them with different needs, and this usage has validated Autotest as a general
15934 Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for
15935 interactive tool testing, which is probably its main limitation.
15938 * Using an Autotest Test Suite:: Autotest and the user
15939 * Writing testsuite.at:: Autotest macros
15940 * testsuite Invocation:: Running @command{testsuite} scripts
15941 * Making testsuite Scripts:: Using autom4te to create @command{testsuite}
15944 @node Using an Autotest Test Suite
15945 @section Using an Autotest Test Suite
15948 * testsuite Scripts:: The concepts of Autotest
15949 * Autotest Logs:: Their contents
15952 @node testsuite Scripts
15953 @subsection @command{testsuite} Scripts
15955 @cindex @command{testsuite}
15957 Generating testing or validation suites using Autotest is rather easy.
15958 The whole validation suite is held in a file to be processed through
15959 @command{autom4te}, itself using @acronym{GNU} M4 under the scene, to
15960 produce a stand-alone Bourne shell script which then gets distributed.
15961 Neither @command{autom4te} nor @acronym{GNU} M4 are needed at
15962 the installer's end.
15965 Each test of the validation suite should be part of some test group. A
15966 @dfn{test group} is a sequence of interwoven tests that ought to be
15967 executed together, usually because one test in the group creates data
15968 files than a later test in the same group needs to read. Complex test
15969 groups make later debugging more tedious. It is much better to
15970 keep only a few tests per test group. Ideally there is only one test
15973 For all but the simplest packages, some file such as @file{testsuite.at}
15974 does not fully hold all test sources, as these are often easier to
15975 maintain in separate files. Each of these separate files holds a single
15976 test group, or a sequence of test groups all addressing some common
15977 functionality in the package. In such cases, @file{testsuite.at}
15978 merely initializes the validation suite, and sometimes does elementary
15979 health checking, before listing include statements for all other test
15980 files. The special file @file{package.m4}, containing the
15981 identification of the package, is automatically included if found.
15983 A convenient alternative consists in moving all the global issues
15984 (local Autotest macros, elementary health checking, and @code{AT_INIT}
15985 invocation) into the file @code{local.at}, and making
15986 @file{testsuite.at} be a simple list of @code{m4_include} of sub test
15987 suites. In such case, generating the whole test suite or pieces of it
15988 is only a matter of choosing the @command{autom4te} command line
15991 The validation scripts that Autotest produces are by convention called
15992 @command{testsuite}. When run, @command{testsuite} executes each test
15993 group in turn, producing only one summary line per test to say if that
15994 particular test succeeded or failed. At end of all tests, summarizing
15995 counters get printed. One debugging directory is left for each test
15996 group which failed, if any: such directories are named
15997 @file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of
15998 the test group, and they include:
16001 @item a debugging script named @file{run} which reruns the test in
16002 @dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation
16003 of debugging scripts has the purpose of easing the chase for bugs.
16005 @item all the files created with @code{AT_DATA}
16007 @item a log of the run, named @file{testsuite.log}
16010 In the ideal situation, none of the tests fail, and consequently no
16011 debugging directory is left behind for validation.
16013 It often happens in practice that individual tests in the validation
16014 suite need to get information coming out of the configuration process.
16015 Some of this information, common for all validation suites, is provided
16016 through the file @file{atconfig}, automatically created by
16017 @code{AC_CONFIG_TESTDIR}. For configuration informations which your
16018 testing environment specifically needs, you might prepare an optional
16019 file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
16020 The configuration process produces @file{atconfig} and @file{atlocal}
16021 out of these two input files, and these two produced files are
16022 automatically read by the @file{testsuite} script.
16024 Here is a diagram showing the relationship between files.
16027 Files used in preparing a software package for distribution:
16032 subfile-1.at ->. [local.at] ---->+
16034 subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite
16040 Files used in configuring a software package:
16045 [atlocal.in] --> config.status* --<
16051 Files created during the test suite execution:
16054 atconfig -->. .--> testsuite.log
16058 [atlocal] ->' `--> [testsuite.dir]
16062 @node Autotest Logs
16063 @subsection Autotest Logs
16065 When run, the test suite creates a log file named after itself, e.g., a
16066 test suite named @command{testsuite} creates @file{testsuite.log}. It
16067 contains a lot of information, usually more than maintainers actually
16068 need, but therefore most of the time it contains all that is needed:
16071 @item command line arguments
16072 @c akim s/to consist in/to consist of/
16073 A very bad but unfortunately widespread Posix habit consists of
16074 setting environment variables before the command, such as in
16075 @samp{CC=my-home-grown-cc ./testsuite}. The test suite will not
16076 know this change, hence (i) it cannot report it to you, and (ii)
16077 it cannot preserve the value of @code{CC} for subsequent runs.
16078 Autoconf faced exactly the same problem, and solved it by asking
16079 users to pass the variable definitions as command line arguments.
16080 Autotest requires this rule, too, but has no means to enforce it; the log
16081 then contains a trace of the variables that were changed by the user.
16083 @item @file{ChangeLog} excerpts
16084 The topmost lines of all the @file{ChangeLog}s found in the source
16085 hierarchy. This is especially useful when bugs are reported against
16086 development versions of the package, since the version string does not
16087 provide sufficient information to know the exact state of the sources
16088 the user compiled. Of course, this relies on the use of a
16091 @item build machine
16092 Running a test suite in a cross-compile environment is not an easy task,
16093 since it would mean having the test suite run on a machine @var{build},
16094 while running programs on a machine @var{host}. It is much simpler to
16095 run both the test suite and the programs on @var{host}, but then, from
16096 the point of view of the test suite, there remains a single environment,
16097 @var{host} = @var{build}. The log contains relevant information on the
16098 state of the build machine, including some important environment
16100 @c FIXME: How about having an M4sh macro to say `hey, log the value
16101 @c of `@dots{}'? This would help both Autoconf and Autotest.
16103 @item tested programs
16104 The absolute file name and answers to @option{--version} of the tested
16105 programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
16107 @item configuration log
16108 The contents of @file{config.log}, as created by @command{configure},
16109 are appended. It contains the configuration flags and a detailed report
16110 on the configuration itself.
16114 @node Writing testsuite.at
16115 @section Writing @file{testsuite.at}
16117 The @file{testsuite.at} is a Bourne shell script making use of special
16118 Autotest M4 macros. It often contains a call to @code{AT_INIT} near
16119 its beginning followed by one call to @code{m4_include} per source file
16120 for tests. Each such included file, or the remainder of
16121 @file{testsuite.at} if include files are not used, contain a sequence of
16122 test groups. Each test group begins with a call to @code{AT_SETUP},
16123 then an arbitrary number of shell commands or calls to @code{AT_CHECK},
16124 and then completes with a call to @code{AT_CLEANUP}.
16126 @defmac AT_INIT (@ovar{name})
16128 @c FIXME: Not clear, plus duplication of the information.
16129 Initialize Autotest. Giving a @var{name} to the test suite is
16130 encouraged if your package includes several test suites. In any case,
16131 the test suite always displays the package name and version. It also
16132 inherits the package bug report address.
16135 @defmac AT_COPYRIGHT (@var{copyright-notice})
16136 @atindex{COPYRIGHT}
16137 @cindex Copyright Notice
16138 State that, in addition to the Free Software Foundation's copyright on
16139 the Autotest macros, parts of your test suite are covered by
16140 @var{copyright-notice}.
16142 The @var{copyright-notice} will show up in both the head of
16143 @command{testsuite} and in @samp{testsuite --version}.
16146 @defmac AT_TESTED (@var{executables})
16148 Log the file name and answer to @option{--version} of each program in
16149 space-separated list @var{executables}. Several invocations register
16150 new executables, in other words, don't fear registering one program
16154 Autotest test suites rely on @env{PATH} to find the tested program.
16155 This avoids the need to generate absolute names of the various tools, and
16156 makes it possible to test installed programs. Therefore, knowing which
16157 programs are being exercised is crucial to understanding problems in
16158 the test suite itself, or its occasional misuses. It is a good idea to
16159 also subscribe foreign programs you depend upon, to avoid incompatible
16164 @defmac AT_SETUP (@var{test-group-name})
16166 This macro starts a group of related tests, all to be executed in the
16167 same subshell. It accepts a single argument, which holds a few words
16168 (no more than about 30 or 40 characters) quickly describing the purpose
16169 of the test group being started.
16172 @defmac AT_KEYWORDS (@var{keywords})
16174 Associate the space-separated list of @var{keywords} to the enclosing
16175 test group. This makes it possible to run ``slices'' of the test suite.
16176 For instance, if some of your test groups exercise some @samp{foo}
16177 feature, then using @samp{AT_KEYWORDS(foo)} lets you run
16178 @samp{./testsuite -k foo} to run exclusively these test groups. The
16179 @var{title} of the test group is automatically recorded to
16180 @code{AT_KEYWORDS}.
16182 Several invocations within a test group accumulate new keywords. In
16183 other words, don't fear registering the same keyword several times in a
16187 @defmac AT_CAPTURE_FILE (@var{file})
16188 @atindex{CAPTURE_FILE}
16189 If the current test group fails, log the contents of @var{file}.
16190 Several identical calls within one test group have no additional effect.
16193 @defmac AT_XFAIL_IF (@var{shell-condition})
16195 Determine whether the test is expected to fail because it is a known
16196 bug (for unsupported features, you should skip the test).
16197 @var{shell-condition} is a shell expression such as a @code{test}
16198 command; you can instantiate this macro many times from within the
16199 same test group, and one of the conditions will be enough to turn
16200 the test into an expected failure.
16205 End the current test group.
16210 @defmac AT_DATA (@var{file}, @var{contents})
16212 Initialize an input data @var{file} with given @var{contents}. Of
16213 course, the @var{contents} have to be properly quoted between square
16214 brackets to protect against included commas or spurious M4
16215 expansion. The contents ought to end with an end of line.
16218 @defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @dvar{stdout, @samp{}}, @dvar{stderr, @samp{}}, @ovar{run-if-fail}, @ovar{run-if-pass})
16220 Execute a test by performing given shell @var{commands}. These commands
16221 should normally exit with @var{status}, while producing expected
16222 @var{stdout} and @var{stderr} contents. If @var{commands} exit with
16223 status 77, then the whole test group is skipped. Otherwise, if this test
16224 fails, run shell commands @var{run-if-fail} or, if this test passes, run shell
16225 commands @var{run-if-pass}.
16227 The @var{commands} @emph{must not} redirect the standard output, nor the
16230 If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
16231 the corresponding value is not checked.
16233 The special value @samp{expout} for @var{stdout} means the expected
16234 output of the @var{commands} is the content of the file @file{expout}.
16235 If @var{stdout} is @samp{stdout}, then the standard output of the
16236 @var{commands} is available for further tests in the file @file{stdout}.
16237 Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
16241 @node testsuite Invocation
16242 @section Running @command{testsuite} Scripts
16243 @cindex @command{testsuite}
16245 Autotest test suites support the following arguments:
16250 Display the list of options and exit successfully.
16254 Display the version of the test suite and exit successfully.
16258 Remove all the files the test suite might have created and exit. Meant
16259 for @code{clean} Makefile targets.
16263 List all the tests (or only the selection), including their possible
16269 By default all tests are performed (or described with
16270 @option{--list}) in the default environment first silently, then
16271 verbosely, but the environment, set of tests, and verbosity level can be
16275 @item @var{variable}=@var{value}
16276 Set the environment @var{variable} to @var{value}. Use this rather
16277 than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a
16278 different environment.
16280 @cindex @code{AUTOTEST_PATH}
16281 The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
16282 to @env{PATH}. Relative directory names (not starting with
16283 @samp{/}) are considered to be relative to the top level of the
16284 package being built. All directories are made absolute, first
16285 starting from the top level @emph{build} tree, then from the
16286 @emph{source} tree. For instance @samp{./testsuite
16287 AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
16288 in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
16289 then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
16293 @itemx @var{number}-@var{number}
16294 @itemx @var{number}-
16295 @itemx -@var{number}
16296 Add the corresponding test groups, with obvious semantics, to the
16299 @item --keywords=@var{keywords}
16300 @itemx -k @var{keywords}
16301 Add to the selection the test groups with title or keywords (arguments
16302 to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords
16303 of the comma separated list @var{keywords}.
16305 Running @samp{./testsuite -k autoupdate,FUNC} will select all the tests
16306 tagged with @samp{autoupdate} @emph{and} @samp{FUNC} (as in
16307 @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH}, etc.)@: while
16308 @samp{./testsuite -k autoupdate -k FUNC} will select all tests tagged with
16309 @samp{autoupdate} @emph{or} @samp{FUNC}.
16313 If any test fails, immediately abort testing. It implies
16314 @option{--debug}: post test group clean up, debugging script generation,
16315 and logging are inhibited. This option is meant for the full test
16316 suite, it is not really useful for generated debugging scripts.
16320 Force more verbosity in the detailed output of what is being done. This
16321 is the default for debugging scripts.
16325 Do not remove the files after a test group was performed ---but they are
16326 still removed @emph{before}, therefore using this option is sane when
16327 running several test groups. Do not create debugging scripts. Do not
16328 log (in order to preserve supposedly existing full log file). This is
16329 the default for debugging scripts, but it can also be useful to debug
16330 the testsuite itself.
16334 Trigger shell tracing of the test groups.
16338 @node Making testsuite Scripts
16339 @section Making @command{testsuite} Scripts
16341 For putting Autotest into movement, you need some configuration and
16342 Makefile machinery. We recommend, at least if your package uses deep or
16343 shallow hierarchies, that you use @file{tests/} as the name of the
16344 directory holding all your tests and their @file{Makefile}. Here is a
16345 check list of things to do.
16350 @cindex @file{package.m4}
16351 Make sure to create the file @file{package.m4}, which defines the
16352 identity of the package. It must define @code{AT_PACKAGE_STRING}, the
16353 full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
16354 address to which bug reports should be sent. For sake of completeness,
16355 we suggest that you also define @code{AT_PACKAGE_NAME},
16356 @code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
16357 @xref{Initializing configure}, for a description of these variables. We
16358 suggest the following Makefile excerpt:
16361 $(srcdir)/package.m4: $(top_srcdir)/configure.ac
16363 echo '# Signature of the current package.'; \
16364 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
16365 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
16366 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
16367 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
16368 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
16369 @} >$(srcdir)/package.m4
16373 Be sure to distribute @file{package.m4} and to put it into the source
16374 hierarchy: the test suite ought to be shipped!
16377 Invoke @code{AC_CONFIG_TESTDIR}.
16379 @defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, @var{directory}})
16380 @acindex{CONFIG_TESTDIR}
16381 An Autotest test suite is to be configured in @var{directory}. This
16382 macro requires the instantiation of @file{@var{directory}/atconfig} from
16383 @file{@var{directory}/atconfig.in}, and sets the default
16384 @code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}).
16388 Still within @file{configure.ac}, as appropriate, ensure that some
16389 @code{AC_CONFIG_FILES} command includes substitution for
16390 @file{tests/atlocal}.
16393 The @file{tests/Makefile.in} should be modified so the validation in
16394 your package is triggered by @samp{make check}. An example is provided
16398 With Automake, here is a minimal example about how to link @samp{make
16399 check} with a validation suite.
16402 EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in
16403 TESTSUITE = $(srcdir)/testsuite
16405 check-local: atconfig atlocal $(TESTSUITE)
16406 $(SHELL) $(TESTSUITE) $(TESTSUITEFLAGS)
16408 installcheck-local: atconfig atlocal $(TESTSUITE)
16409 $(SHELL) $(TESTSUITE) AUTOTEST_PATH="$(bindir)" \
16412 AUTOTEST = $(AUTOM4TE) --language=autotest
16413 $(TESTSUITE): $(srcdir)/testsuite.at
16414 $(AUTOTEST) -I $(srcdir) -o $@@.tmp $@@.at
16418 You might want to list explicitly the dependencies, i.e., the list of
16419 the files @file{testsuite.at} includes.
16421 With strict Autoconf, you might need to add lines inspired from the
16427 atconfig: $(top_builddir)/config.status
16428 cd $(top_builddir) && \
16429 $(SHELL) ./config.status $(subdir)/$@@
16431 atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
16432 cd $(top_builddir) && \
16433 $(SHELL) ./config.status $(subdir)/$@@
16437 and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
16442 @c =============================== Frequent Autoconf Questions, with answers
16445 @chapter Frequent Autoconf Questions, with answers
16447 Several questions about Autoconf come up occasionally. Here some of them
16451 * Distributing:: Distributing @command{configure} scripts
16452 * Why GNU m4:: Why not use the standard M4?
16453 * Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other?
16454 * Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake
16455 * Defining Directories:: Passing @code{datadir} to program
16456 * autom4te.cache:: What is it? Can I remove it?
16457 * Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree
16461 @section Distributing @command{configure} Scripts
16465 What are the restrictions on distributing @command{configure}
16466 scripts that Autoconf generates? How does that affect my
16467 programs that use them?
16470 There are no restrictions on how the configuration scripts that Autoconf
16471 produces may be distributed or used. In Autoconf version 1, they were
16472 covered by the @acronym{GNU} General Public License. We still encourage
16473 software authors to distribute their work under terms like those of the
16474 GPL, but doing so is not required to use Autoconf.
16476 Of the other files that might be used with @command{configure},
16477 @file{config.h.in} is under whatever copyright you use for your
16478 @file{configure.ac}. @file{config.sub} and @file{config.guess} have an
16479 exception to the GPL when they are used with an Autoconf-generated
16480 @command{configure} script, which permits you to distribute them under the
16481 same terms as the rest of your package. @file{install-sh} is from the X
16482 Consortium and is not copyrighted.
16485 @section Why Require @acronym{GNU} M4?
16488 Why does Autoconf require @acronym{GNU} M4?
16491 Many M4 implementations have hard-coded limitations on the size and
16492 number of macros that Autoconf exceeds. They also lack several
16493 builtin macros that it would be difficult to get along without in a
16494 sophisticated application like Autoconf, including:
16504 Autoconf requires version 1.4.3 or later of @acronym{GNU} M4.
16506 Since only software maintainers need to use Autoconf, and since @acronym{GNU}
16507 M4 is simple to configure and install, it seems reasonable to require
16508 @acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and
16509 other free software already have most of the @acronym{GNU} utilities
16510 installed, since they prefer them.
16512 @node Bootstrapping
16513 @section How Can I Bootstrap?
16517 If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf
16518 @command{configure} script, how do I bootstrap? It seems like a chicken
16522 This is a misunderstanding. Although @acronym{GNU} M4 does come with a
16523 @command{configure} script produced by Autoconf, Autoconf is not required
16524 in order to run the script and install @acronym{GNU} M4. Autoconf is only
16525 required if you want to change the M4 @command{configure} script, which few
16526 people have to do (mainly its maintainer).
16528 @node Why Not Imake
16529 @section Why Not Imake?
16533 Why not use Imake instead of @command{configure} scripts?
16536 Several people have written addressing this question, so I include
16537 adaptations of their explanations here.
16539 The following answer is based on one written by Richard Pixley:
16542 Autoconf generated scripts frequently work on machines that it has
16543 never been set up to handle before. That is, it does a good job of
16544 inferring a configuration for a new system. Imake cannot do this.
16546 Imake uses a common database of host specific data. For X11, this makes
16547 sense because the distribution is made as a collection of tools, by one
16548 central authority who has control over the database.
16550 @acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a
16551 maintainer; these maintainers are scattered across the world. Using a
16552 common database would be a maintenance nightmare. Autoconf may appear
16553 to be this kind of database, but in fact it is not. Instead of listing
16554 host dependencies, it lists program requirements.
16556 If you view the @acronym{GNU} suite as a collection of native tools, then the
16557 problems are similar. But the @acronym{GNU} development tools can be
16558 configured as cross tools in almost any host+target permutation. All of
16559 these configurations can be installed concurrently. They can even be
16560 configured to share host independent files across hosts. Imake doesn't
16561 address these issues.
16563 Imake templates are a form of standardization. The @acronym{GNU} coding
16564 standards address the same issues without necessarily imposing the same
16569 Here is some further explanation, written by Per Bothner:
16572 One of the advantages of Imake is that it easy to generate large
16573 Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
16574 However, @code{cpp} is not programmable: it has limited conditional
16575 facilities, and no looping. And @code{cpp} cannot inspect its
16578 All of these problems are solved by using @code{sh} instead of
16579 @code{cpp}. The shell is fully programmable, has macro substitution,
16580 can execute (or source) other shell scripts, and can inspect its
16585 Paul Eggert elaborates more:
16588 With Autoconf, installers need not assume that Imake itself is already
16589 installed and working well. This may not seem like much of an advantage
16590 to people who are accustomed to Imake. But on many hosts Imake is not
16591 installed or the default installation is not working well, and requiring
16592 Imake to install a package hinders the acceptance of that package on
16593 those hosts. For example, the Imake template and configuration files
16594 might not be installed properly on a host, or the Imake build procedure
16595 might wrongly assume that all source files are in one big directory
16596 tree, or the Imake configuration might assume one compiler whereas the
16597 package or the installer needs to use another, or there might be a
16598 version mismatch between the Imake expected by the package and the Imake
16599 supported by the host. These problems are much rarer with Autoconf,
16600 where each package comes with its own independent configuration
16603 Also, Imake often suffers from unexpected interactions between
16604 @command{make} and the installer's C preprocessor. The fundamental problem
16605 here is that the C preprocessor was designed to preprocess C programs,
16606 not @file{Makefile}s. This is much less of a problem with Autoconf,
16607 which uses the general-purpose preprocessor M4, and where the
16608 package's author (rather than the installer) does the preprocessing in a
16613 Finally, Mark Eichin notes:
16616 Imake isn't all that extensible, either. In order to add new features to
16617 Imake, you need to provide your own project template, and duplicate most
16618 of the features of the existing one. This means that for a sophisticated
16619 project, using the vendor-provided Imake templates fails to provide any
16620 leverage---since they don't cover anything that your own project needs
16621 (unless it is an X11 program).
16623 On the other side, though:
16625 The one advantage that Imake has over @command{configure}:
16626 @file{Imakefile}s tend to be much shorter (likewise, less redundant)
16627 than @file{Makefile.in}s. There is a fix to this, however---at least
16628 for the Kerberos V5 tree, we've modified things to call in common
16629 @file{post.in} and @file{pre.in} @file{Makefile} fragments for the
16630 entire tree. This means that a lot of common things don't have to be
16631 duplicated, even though they normally are in @command{configure} setups.
16635 @node Defining Directories
16636 @section How Do I @code{#define} Installation Directories?
16639 My program needs library files, installed in @code{datadir} and
16643 AC_DEFINE_UNQUOTED([DATADIR], [$datadir],
16644 [Define to the read-only architecture-independent
16652 #define DATADIR "$@{prefix@}/share"
16656 As already explained, this behavior is on purpose, mandated by the
16657 @acronym{GNU} Coding Standards, see @ref{Installation Directory
16658 Variables}. There are several means to achieve a similar goal:
16662 Do not use @code{AC_DEFINE} but use your @file{Makefile} to pass the
16663 actual value of @code{datadir} via compilation flags, see
16664 @ref{Installation Directory Variables}, for the details.
16667 This solution can be simplified when compiling a program: you may either
16668 extend the @code{CPPFLAGS}:
16671 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
16675 or create a dedicated header file:
16678 DISTCLEANFILES = datadir.h
16679 datadir.h: Makefile
16680 echo '#define DATADIR "$(datadir)"' >$@@
16684 Use @code{AC_DEFINE} but have @command{configure} compute the literal
16685 value of @code{datadir} and others. Many people have wrapped macros to
16686 automate this task. For instance, the macro @code{AC_DEFINE_DIR} from
16687 the @uref{http://www.gnu.org/software/ac-archive/, @acronym{GNU} Autoconf Macro
16690 This solution does not conform to the @acronym{GNU} Coding Standards.
16693 Note that all the previous solutions hard wire the absolute name of
16694 these directories in the executables, which is not a good property. You
16695 may try to compute the names relative to @code{prefix}, and try to
16696 find @code{prefix} at runtime, this way your package is relocatable.
16697 Some macros are already available to address this issue: see
16698 @code{adl_COMPUTE_RELATIVE_PATHS} and
16699 @code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the
16700 @uref{http://www.gnu.org/software/ac-archive/,
16701 @acronym{GNU} Autoconf Macro Archive}.
16705 @node autom4te.cache
16706 @section What is @file{autom4te.cache}?
16709 What is this directory @file{autom4te.cache}? Can I safely remove it?
16712 In the @acronym{GNU} Build System, @file{configure.ac} plays a central
16713 role and is read by many tools: @command{autoconf} to create
16714 @file{configure}, @command{autoheader} to create @file{config.h.in},
16715 @command{automake} to create @file{Makefile.in}, @command{autoscan} to
16716 check the completeness of @file{configure.ac}, @command{autoreconf} to
16717 check the @acronym{GNU} Build System components that are used. To
16718 ``read @file{configure.ac}'' actually means to compile it with M4,
16719 which can be a very long process for complex @file{configure.ac}.
16721 This is why all these tools, instead of running directly M4, invoke
16722 @command{autom4te} (@pxref{autom4te Invocation}) which, while answering to
16723 a specific demand, stores additional information in
16724 @file{autom4te.cache} for future runs. For instance, if you run
16725 @command{autoconf}, behind the scenes, @command{autom4te} will also
16726 store information for the other tools, so that when you invoke
16727 @command{autoheader} or @command{automake} etc., re-processing
16728 @file{configure.ac} is not needed. The speed up is frequently of 30%,
16729 and is increasing with the size of @file{configure.ac}.
16731 But it is and remains being simply a cache: you can safely remove it.
16736 Can I permanently get rid of it?
16739 The creation of this cache can be disabled from
16740 @file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more
16741 details. You should be aware that disabling the cache slows down the
16742 Autoconf test suite by 40%. The more @acronym{GNU} Build System
16743 components are used, the more the cache is useful; for instance
16744 running @samp{autoreconf -f} on the Coreutils is twice slower without
16745 the cache @emph{although @option{--force} implies that the cache is
16746 not fully exploited}, and eight times slower than without
16750 @node Present But Cannot Be Compiled
16751 @section Header Present But Cannot Be Compiled
16753 The most important guideline to bear in mind when checking for
16754 features is to mimic as much as possible the intended use.
16755 Unfortunately, old versions of @code{AC_CHECK_HEADER} and
16756 @code{AC_CHECK_HEADERS} failed to follow this idea, and called
16757 the preprocessor, instead of the compiler, to check for headers. As a
16758 result, incompatibilities between headers went unnoticed during
16759 configuration, and maintainers finally had to deal with this issue
16762 As of Autoconf 2.56 both checks are performed, and @code{configure}
16763 complains loudly if the compiler and the preprocessor do not agree.
16764 For the time being the result used is that of the preprocessor, to give
16765 maintainers time to adjust their @file{configure.ac}, but in the
16766 future, only the compiler will be considered.
16768 Consider the following example:
16771 $ @kbd{cat number.h}
16772 typedef int number;
16774 const number pi = 3;
16775 $ @kbd{cat configure.ac}
16776 AC_INIT([Example], [1.0], [bug-example@@example.org])
16777 AC_CHECK_HEADERS([pi.h])
16778 $ @kbd{autoconf -Wall}
16779 $ @kbd{./configure}
16780 checking for gcc... gcc
16781 checking for C compiler default output file name... a.out
16782 checking whether the C compiler works... yes
16783 checking whether we are cross compiling... no
16784 checking for suffix of executables...
16785 checking for suffix of object files... o
16786 checking whether we are using the GNU C compiler... yes
16787 checking whether gcc accepts -g... yes
16788 checking for gcc option to accept ISO C89... none needed
16789 checking how to run the C preprocessor... gcc -E
16790 checking for grep that handles long lines and -e... grep
16791 checking for egrep... grep -E
16792 checking for ANSI C header files... yes
16793 checking for sys/types.h... yes
16794 checking for sys/stat.h... yes
16795 checking for stdlib.h... yes
16796 checking for string.h... yes
16797 checking for memory.h... yes
16798 checking for strings.h... yes
16799 checking for inttypes.h... yes
16800 checking for stdint.h... yes
16801 checking for unistd.h... yes
16802 checking pi.h usability... no
16803 checking pi.h presence... yes
16804 configure: WARNING: pi.h: present but cannot be compiled
16805 configure: WARNING: pi.h: check for missing prerequisite headers?
16806 configure: WARNING: pi.h: see the Autoconf documentation
16807 configure: WARNING: pi.h: section "Present But Cannot Be Compiled"
16808 configure: WARNING: pi.h: proceeding with the preprocessor's result
16809 configure: WARNING: pi.h: in the future, the compiler will take precedence
16810 configure: WARNING: ## -------------------------------------- ##
16811 configure: WARNING: ## Report this to bug-example@@example.org ##
16812 configure: WARNING: ## -------------------------------------- ##
16813 checking for pi.h... yes
16817 The proper way the handle this case is using the fourth argument
16818 (@pxref{Generic Headers}):
16821 $ @kbd{cat configure.ac}
16822 AC_INIT([Example], [1.0], [bug-example@@example.org])
16823 AC_CHECK_HEADERS([number.h pi.h], [], [],
16824 [[#if HAVE_NUMBER_H
16825 # include <number.h>
16828 $ @kbd{autoconf -Wall}
16829 $ @kbd{./configure}
16830 checking for gcc... gcc
16831 checking for C compiler default output... a.out
16832 checking whether the C compiler works... yes
16833 checking whether we are cross compiling... no
16834 checking for suffix of executables...
16835 checking for suffix of object files... o
16836 checking whether we are using the GNU C compiler... yes
16837 checking whether gcc accepts -g... yes
16838 checking for gcc option to accept ANSI C... none needed
16839 checking for number.h... yes
16840 checking for pi.h... yes
16843 See @ref{Particular Headers}, for a list of headers with their
16846 @c ===================================================== History of Autoconf.
16849 @chapter History of Autoconf
16850 @cindex History of autoconf
16852 You may be wondering, Why was Autoconf originally written? How did it
16853 get into its present form? (Why does it look like gorilla spit?) If
16854 you're not wondering, then this chapter contains no information useful
16855 to you, and you might as well skip it. If you @emph{are} wondering,
16856 then let there be light@enddots{}
16859 * Genesis:: Prehistory and naming of @command{configure}
16860 * Exodus:: The plagues of M4 and Perl
16861 * Leviticus:: The priestly code of portability arrives
16862 * Numbers:: Growth and contributors
16863 * Deuteronomy:: Approaching the promises of easy configuration
16869 In June 1991 I was maintaining many of the @acronym{GNU} utilities for the
16870 Free Software Foundation. As they were ported to more platforms and
16871 more programs were added, the number of @option{-D} options that users
16872 had to select in the @file{Makefile} (around 20) became burdensome.
16873 Especially for me---I had to test each new release on a bunch of
16874 different systems. So I wrote a little shell script to guess some of
16875 the correct settings for the fileutils package, and released it as part
16876 of fileutils 2.0. That @command{configure} script worked well enough that
16877 the next month I adapted it (by hand) to create similar @command{configure}
16878 scripts for several other @acronym{GNU} utilities packages. Brian Berliner
16879 also adapted one of my scripts for his @acronym{CVS} revision control system.
16881 Later that summer, I learned that Richard Stallman and Richard Pixley
16882 were developing similar scripts to use in the @acronym{GNU} compiler tools;
16883 so I adapted my @command{configure} scripts to support their evolving
16884 interface: using the file name @file{Makefile.in} as the templates;
16885 adding @samp{+srcdir}, the first option (of many); and creating
16886 @file{config.status} files.
16891 As I got feedback from users, I incorporated many improvements, using
16892 Emacs to search and replace, cut and paste, similar changes in each of
16893 the scripts. As I adapted more @acronym{GNU} utilities packages to use
16894 @command{configure} scripts, updating them all by hand became impractical.
16895 Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me
16896 mail saying that the @command{configure} scripts were great, and asking if
16897 I had a tool for generating them that I could send him. No, I thought,
16898 but I should! So I started to work out how to generate them. And the
16899 journey from the slavery of hand-written @command{configure} scripts to the
16900 abundance and ease of Autoconf began.
16902 Cygnus @command{configure}, which was being developed at around that time,
16903 is table driven; it is meant to deal mainly with a discrete number of
16904 system types with a small number of mainly unguessable features (such as
16905 details of the object file format). The automatic configuration system
16906 that Brian Fox had developed for Bash takes a similar approach. For
16907 general use, it seems to me a hopeless cause to try to maintain an
16908 up-to-date database of which features each variant of each operating
16909 system has. It's easier and more reliable to check for most features on
16910 the fly---especially on hybrid systems that people have hacked on
16911 locally or that have patches from vendors installed.
16913 I considered using an architecture similar to that of Cygnus
16914 @command{configure}, where there is a single @command{configure} script that
16915 reads pieces of @file{configure.in} when run. But I didn't want to have
16916 to distribute all of the feature tests with every package, so I settled
16917 on having a different @command{configure} made from each
16918 @file{configure.in} by a preprocessor. That approach also offered more
16919 control and flexibility.
16921 I looked briefly into using the Metaconfig package, by Larry Wall,
16922 Harlan Stenn, and Raphael Manfredi, but I decided not to for several
16923 reasons. The @command{Configure} scripts it produces are interactive,
16924 which I find quite inconvenient; I didn't like the ways it checked for
16925 some features (such as library functions); I didn't know that it was
16926 still being maintained, and the @command{Configure} scripts I had
16927 seen didn't work on many modern systems (such as System V R4 and NeXT);
16928 it wasn't very flexible in what it could do in response to a feature's
16929 presence or absence; I found it confusing to learn; and it was too big
16930 and complex for my needs (I didn't realize then how much Autoconf would
16931 eventually have to grow).
16933 I considered using Perl to generate my style of @command{configure}
16934 scripts, but decided that M4 was better suited to the job of simple
16935 textual substitutions: it gets in the way less, because output is
16936 implicit. Plus, everyone already has it. (Initially I didn't rely on
16937 the @acronym{GNU} extensions to M4.) Also, some of my friends at the
16938 University of Maryland had recently been putting M4 front ends on
16939 several programs, including @code{tvtwm}, and I was interested in trying
16940 out a new language.
16945 Since my @command{configure} scripts determine the system's capabilities
16946 automatically, with no interactive user intervention, I decided to call
16947 the program that generates them Autoconfig. But with a version number
16948 tacked on, that name would be too long for old Unix file systems,
16949 so I shortened it to Autoconf.
16951 In the fall of 1991 I called together a group of fellow questers after
16952 the Holy Grail of portability (er, that is, alpha testers) to give me
16953 feedback as I encapsulated pieces of my handwritten scripts in M4 macros
16954 and continued to add features and improve the techniques used in the
16955 checks. Prominent among the testers were Fran@,cois Pinard, who came up
16956 with the idea of making an Autoconf shell script to run M4
16957 and check for unresolved macro calls; Richard Pixley, who suggested
16958 running the compiler instead of searching the file system to find
16959 include files and symbols, for more accurate results; Karl Berry, who
16960 got Autoconf to configure @TeX{} and added the macro index to the
16961 documentation; and Ian Lance Taylor, who added support for creating a C
16962 header file as an alternative to putting @option{-D} options in a
16963 @file{Makefile}, so he could use Autoconf for his @acronym{UUCP} package.
16964 The alpha testers cheerfully adjusted their files again and again as the
16965 names and calling conventions of the Autoconf macros changed from
16966 release to release. They all contributed many specific checks, great
16967 ideas, and bug fixes.
16972 In July 1992, after months of alpha testing, I released Autoconf 1.0,
16973 and converted many @acronym{GNU} packages to use it. I was surprised by how
16974 positive the reaction to it was. More people started using it than I
16975 could keep track of, including people working on software that wasn't
16976 part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5).
16977 Autoconf continued to improve rapidly, as many people using the
16978 @command{configure} scripts reported problems they encountered.
16980 Autoconf turned out to be a good torture test for M4 implementations.
16981 Unix M4 started to dump core because of the length of the
16982 macros that Autoconf defined, and several bugs showed up in @acronym{GNU}
16983 M4 as well. Eventually, we realized that we needed to use some
16984 features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in
16985 particular, has an impoverished set of builtin macros; the System V
16986 version is better, but still doesn't provide everything we need.
16988 More development occurred as people put Autoconf under more stresses
16989 (and to uses I hadn't anticipated). Karl Berry added checks for X11.
16990 david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose
16991 invalid arguments. Jim Blandy bravely coerced it into configuring
16992 @acronym{GNU} Emacs, laying the groundwork for several later improvements.
16993 Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the
16994 @command{autoheader} script to automate the creation of C header file
16995 templates, and added a @option{--verbose} option to @command{configure}.
16996 Noah Friedman added the @option{--autoconf-dir} option and
16997 @code{AC_MACRODIR} environment variable. (He also coined the term
16998 @dfn{autoconfiscate} to mean ``adapt a software package to use
16999 Autoconf''.) Roland and Noah improved the quoting protection in
17000 @code{AC_DEFINE} and fixed many bugs, especially when I got sick of
17001 dealing with portability problems from February through June, 1993.
17004 @section Deuteronomy
17006 A long wish list for major features had accumulated, and the effect of
17007 several years of patching by various people had left some residual
17008 cruft. In April 1994, while working for Cygnus Support, I began a major
17009 revision of Autoconf. I added most of the features of the Cygnus
17010 @command{configure} that Autoconf had lacked, largely by adapting the
17011 relevant parts of Cygnus @command{configure} with the help of david zuhn
17012 and Ken Raeburn. These features include support for using
17013 @file{config.sub}, @file{config.guess}, @option{--host}, and
17014 @option{--target}; making links to files; and running @command{configure}
17015 scripts in subdirectories. Adding these features enabled Ken to convert
17016 @acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using
17019 I added more features in response to other peoples' requests. Many
17020 people had asked for @command{configure} scripts to share the results of
17021 the checks between runs, because (particularly when configuring a large
17022 source tree, like Cygnus does) they were frustratingly slow. Mike
17023 Haertel suggested adding site-specific initialization scripts. People
17024 distributing software that had to unpack on MS-DOS asked for a way to
17025 override the @file{.in} extension on the file names, which produced file
17026 names like @file{config.h.in} containing two dots. Jim Avera did an
17027 extensive examination of the problems with quoting in @code{AC_DEFINE}
17028 and @code{AC_SUBST}; his insights led to significant improvements.
17029 Richard Stallman asked that compiler output be sent to @file{config.log}
17030 instead of @file{/dev/null}, to help people debug the Emacs
17031 @command{configure} script.
17033 I made some other changes because of my dissatisfaction with the quality
17034 of the program. I made the messages showing results of the checks less
17035 ambiguous, always printing a result. I regularized the names of the
17036 macros and cleaned up coding style inconsistencies. I added some
17037 auxiliary utilities that I had developed to help convert source code
17038 packages to use Autoconf. With the help of Fran@,cois Pinard, I made
17039 the macros not interrupt each others' messages. (That feature revealed
17040 some performance bottlenecks in @acronym{GNU} M4, which he hastily
17041 corrected!) I reorganized the documentation around problems people want
17042 to solve. And I began a test suite, because experience had shown that
17043 Autoconf has a pronounced tendency to regress when we change it.
17045 Again, several alpha testers gave invaluable feedback, especially
17046 Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
17049 Finally, version 2.0 was ready. And there was much rejoicing. (And I
17050 have free time again. I think. Yeah, right.)
17053 @c ========================================================== Appendices
17055 @node Copying This Manual
17056 @appendix Copying This Manual
17060 * GNU Free Documentation License:: License for copying this manual
17069 * Environment Variable Index:: Index of environment variables used
17070 * Output Variable Index:: Index of variables set in output files
17071 * Preprocessor Symbol Index:: Index of C preprocessor symbols defined
17072 * Autoconf Macro Index:: Index of Autoconf macros
17073 * M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
17074 * Autotest Macro Index:: Index of Autotest macros
17075 * Program & Function Index:: Index of those with portability problems
17076 * Concept Index:: General index
17079 @node Environment Variable Index
17080 @appendixsec Environment Variable Index
17082 This is an alphabetical list of the environment variables that Autoconf
17087 @node Output Variable Index
17088 @appendixsec Output Variable Index
17090 This is an alphabetical list of the variables that Autoconf can
17091 substitute into files that it creates, typically one or more
17092 @file{Makefile}s. @xref{Setting Output Variables}, for more information
17093 on how this is done.
17097 @node Preprocessor Symbol Index
17098 @appendixsec Preprocessor Symbol Index
17100 This is an alphabetical list of the C preprocessor symbols that the
17101 Autoconf macros define. To work with Autoconf, C source code needs to
17102 use these names in @code{#if} directives.
17106 @node Autoconf Macro Index
17107 @appendixsec Autoconf Macro Index
17109 This is an alphabetical list of the Autoconf macros.
17110 @ifset shortindexflag
17111 To make the list easier to use, the macros are listed without their
17112 preceding @samp{AC_}.
17117 @node M4 Macro Index
17118 @appendixsec M4 Macro Index
17120 This is an alphabetical list of the M4, M4sugar, and M4sh macros.
17121 @ifset shortindexflag
17122 To make the list easier to use, the macros are listed without their
17123 preceding @samp{m4_} or @samp{AS_}.
17128 @node Autotest Macro Index
17129 @appendixsec Autotest Macro Index
17131 This is an alphabetical list of the Autotest macros.
17132 @ifset shortindexflag
17133 To make the list easier to use, the macros are listed without their
17134 preceding @samp{AT_}.
17139 @node Program & Function Index
17140 @appendixsec Program and Function Index
17142 This is an alphabetical list of the programs and functions which
17143 portability is discussed in this document.
17147 @node Concept Index
17148 @appendixsec Concept Index
17150 This is an alphabetical list of the files, tools, and concepts
17151 introduced in this document.
17157 @c Local Variables:
17159 @c ispell-local-dictionary: "american"