« back to all changes in this revision
Viewing changes to doc/autoconf.texi
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Ben Pfaff
- Date: 2002-03-27 21:52:33 UTC
- Revision ID: james.westby@ubuntu.com-20020327215233-r3gmxall0x27s306
Tags: upstream-2.53
Import upstream version 2.53
- files added:
- bin
- config
- doc
- lib
- lib/Autom4te
- lib/autoconf
- lib/autoscan
- lib/autotest
- lib/emacs
- lib/m4sugar
- man
- tests
added
removed
doc/autoconf.texi
1
\input texinfo @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename autoconf.info
4
@settitle Autoconf
5
6
@finalout
7
@setchapternewpage odd
8
@setcontentsaftertitlepage
9
10
@include version.texi
11
12
@c A simple macro for optional variables.
13
@macro ovar{varname}
14
@r{[}@var{\varname\}@r{]}
15
@end macro
16
17
@c A simple macro for optional variables with a default value.
18
@macro dvar{varname, default}
19
@r{[}@var{\varname\} = @samp{\default\}@r{]}
20
@end macro
21
22
@c I don't like the way URL are displayed in TeX with @uref.
23
@ifhtml
24
@macro href{url, title}
25
@uref{\url\, \title\}
26
@end macro
27
@end ifhtml
28
@ifnothtml
29
@macro href{url, title}
30
\title\@footnote{\title\, @url{\url\}.}
31
@end macro
32
@end ifnothtml
33
34
35
@dircategory GNU admin
36
@direntry
37
* Autoconf: (autoconf). Create source code configuration scripts
38
@end direntry
39
40
@dircategory Individual utilities
41
@direntry
42
* autoscan: (autoconf)autoscan Invocation.
43
Semi-automatic @file{configure.ac} writing
44
* ifnames: (autoconf)ifnames Invocation.
45
Listing the conditionals in source code
46
* autoconf: (autoconf)autoconf Invocation.
47
How to create configuration scripts
48
* autoreconf: (autoconf)autoreconf Invocation.
49
Remaking multiple @command{configure} scripts
50
* configure: (autoconf)configure Invocation.
51
Configuring a package
52
* config.status: (autoconf)config.status Invocation.
53
Recreating a configuration
54
* testsuite: (autoconf)testsuite Invocation.
55
Running an Autotest test suite
56
@end direntry
57
58
@ifinfo
59
Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie.
60
61
This file documents the GNU Autoconf package for creating scripts to
62
configure source code packages using templates and an @code{m4} macro
63
package.
64
65
Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002
66
Free Software Foundation, Inc.
67
68
Permission is granted to copy, distribute and/or modify this document
69
under the terms of the GNU Free Documentation License, Version 1.1
70
or any later version published by the Free Software Foundation;
71
with no Invariant Sections, with no
72
Front-Cover Texts, and with no Back-Cover Texts.
73
A copy of the license is included in the section entitled ``GNU
74
Free Documentation License''.
75
@end ifinfo
76
77
@titlepage
78
@title Autoconf
79
@subtitle Creating Automatic Configuration Scripts
80
@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION}
81
@subtitle @value{UPDATED}
82
@author David MacKenzie
83
@author Ben Elliston
84
@author Akim Demaille
85
@c I think I've rewritten all of Noah and Roland's contributions by now.
86
87
@page
88
@vskip 0pt plus 1filll
89
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
90
2001, 2002 Free Software Foundation, Inc.
91
92
Permission is granted to copy, distribute and/or modify this document
93
under the terms of the GNU Free Documentation License, Version 1.1
94
or any later version published by the Free Software Foundation;
95
with no Invariant Sections, with no
96
Front-Cover Texts, and with no Back-Cover Texts.
97
A copy of the license is included in the section entitled ``GNU
98
Free Documentation License''.
99
@end titlepage
100
101
@c Define an environment variable index.
102
@defcodeindex ev
103
@c Define an output variable index.
104
@defcodeindex ov
105
@c Define a CPP variable index.
106
@defcodeindex cv
107
@c Define an Autoconf macro index that @defmac doesn't write to.
108
@defcodeindex ac
109
@c Define an Autotest macro index that @defmac doesn't write to.
110
@defcodeindex at
111
@c Define an M4sugar macro index that @defmac doesn't write to.
112
@defcodeindex ms
113
@c Define an index for *foreign* programs: `mv' etc. Used for the
114
@c portability sections and so on.
115
@defindex pr
116
117
@c Define an index for functions: `alloca' etc. Used for the
118
@c portability sections and so on. We can't use `fn' (aka `fnindex),
119
@c since `@defmac' goes into it => we'd get all the macros too.
120
121
@c FIXME: Aaarg! It seems there are too many indices for TeX :(
122
@c
123
@c ! No room for a new @write .
124
@c l.112 @defcodeindex fu
125
@c
126
@c so don't define yet another one :( Just put some tags before each
127
@c @prindex which is actually a @funindex.
128
@c
129
@c @defcodeindex fu
130
@c
131
@c
132
@c @c Put the programs and functions into their own index.
133
@c @syncodeindex fu pr
134
135
136
@ifnottex
137
@node Top
138
@top Autoconf
139
@end ifnottex
140
141
@ifinfo
142
This file documents the GNU Autoconf package for creating scripts to
143
configure source code packages using templates and the GNU M4 macro
144
package. This is edition @value{EDITION}, for Autoconf version
145
@value{VERSION}.
146
147
@end ifinfo
148
149
@c The master menu, created with texinfo-master-menu, goes here.
150
151
@menu
152
* Introduction:: Autoconf's purpose, strengths, and weaknesses
153
* The GNU build system:: A set of tools for portable software packages
154
* Making configure Scripts:: How to organize and produce Autoconf scripts
155
* Setup:: Initialization and output
156
* Existing Tests:: Macros that check for particular features
157
* Writing Tests:: How to write new feature checks
158
* Results:: What to do with results from feature checks
159
* Programming in M4:: Layers on top of which Autoconf is written
160
* Writing Autoconf Macros:: Adding new macros to Autoconf
161
* Portable Shell:: Shell script portability pitfalls
162
* Manual Configuration:: Selecting features that can't be guessed
163
* Site Configuration:: Local defaults for @command{configure}
164
* Running configure scripts:: How to use the Autoconf output
165
* config.status Invocation:: Recreating a configuration
166
* Obsolete Constructs:: Kept for backward compatibility
167
* Using Autotest:: Creating portable test suites
168
* Questions:: Questions about Autoconf, with answers
169
* History:: History of Autoconf
170
* Copying This Manual:: How to make copies of this manual
171
* Indices:: Indices of symbols, concepts, etc.
172
173
@detailmenu
174
--- The Detailed Node Listing ---
175
176
The GNU build system
177
178
* Automake:: Escaping Makefile hell
179
* Libtool:: Building libraries portably
180
* Pointers:: More info on the GNU build system
181
182
Making @command{configure} Scripts
183
184
* Writing configure.ac:: What to put in an Autoconf input file
185
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
186
* ifnames Invocation:: Listing the conditionals in source code
187
* autoconf Invocation:: How to create configuration scripts
188
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
189
190
Writing @file{configure.ac}
191
192
* Shell Script Compiler:: Autoconf as solution of a problem
193
* Autoconf Language:: Programming in Autoconf
194
* configure.ac Layout:: Standard organization of configure.ac
195
196
Initialization and Output Files
197
198
* Initializing configure:: Option processing etc.
199
* Notices:: Copyright, version numbers in @command{configure}
200
* Input:: Where Autoconf should find files
201
* Output:: Outputting results from the configuration
202
* Configuration Actions:: Preparing the output based on results
203
* Configuration Files:: Creating output files
204
* Makefile Substitutions:: Using output variables in @file{Makefile}s
205
* Configuration Headers:: Creating a configuration header file
206
* Configuration Commands:: Running arbitrary instantiation commands
207
* Configuration Links:: Links depending from the configuration
208
* Subdirectories:: Configuring independent packages together
209
* Default Prefix:: Changing the default installation prefix
210
211
Substitutions in Makefiles
212
213
* Preset Output Variables:: Output variables that are always set
214
* Installation Directory Variables:: Other preset output variables
215
* Build Directories:: Supporting multiple concurrent compiles
216
* Automatic Remaking:: Makefile rules for configuring
217
218
Configuration Header Files
219
220
* Header Templates:: Input for the configuration headers
221
* autoheader Invocation:: How to create configuration templates
222
* Autoheader Macros:: How to specify CPP templates
223
224
Existing Tests
225
226
* Common Behavior:: Macros' standard schemes
227
* Alternative Programs:: Selecting between alternative programs
228
* Files:: Checking for the existence of files
229
* Libraries:: Library archives that might be missing
230
* Library Functions:: C library functions that might be missing
231
* Header Files:: Header files that might be missing
232
* Declarations:: Declarations that may be missing
233
* Structures:: Structures or members that might be missing
234
* Types:: Types that might be missing
235
* Compilers and Preprocessors:: Checking for compiling programs
236
* System Services:: Operating system services
237
* UNIX Variants:: Special kludges for specific UNIX variants
238
239
Common Behavior
240
241
* Standard Symbols:: Symbols defined by the macros
242
* Default Includes:: Includes used by the generic macros
243
244
Alternative Programs
245
246
* Particular Programs:: Special handling to find certain programs
247
* Generic Programs:: How to find other programs
248
249
Library Functions
250
251
* Function Portability:: Pitfalls with usual functions
252
* Particular Functions:: Special handling to find certain functions
253
* Generic Functions:: How to find other functions
254
255
Header Files
256
257
* Particular Headers:: Special handling to find certain headers
258
* Generic Headers:: How to find other headers
259
260
Declarations
261
262
* Particular Declarations:: Macros to check for certain declarations
263
* Generic Declarations:: How to find other declarations
264
265
Structures
266
267
* Particular Structures:: Macros to check for certain structure members
268
* Generic Structures:: How to find other structure members
269
270
Types
271
272
* Particular Types:: Special handling to find certain types
273
* Generic Types:: How to find other types
274
275
Compilers and Preprocessors
276
277
* Specific Compiler Characteristics:: Some portability issues
278
* Generic Compiler Characteristics:: Language independent tests
279
* C Compiler:: Checking its characteristics
280
* C++ Compiler:: Likewise
281
* Fortran 77 Compiler:: Likewise
282
283
Writing Tests
284
285
* Examining Declarations:: Detecting header files and declarations
286
* Examining Syntax:: Detecting language syntax features
287
* Examining Libraries:: Detecting functions and global variables
288
* Run Time:: Testing for run-time features
289
* Systemology:: A zoology of operating systems
290
* Multiple Cases:: Tests for several possible values
291
* Language Choice:: Selecting which language to use for testing
292
293
Checking Run Time Behavior
294
295
* Test Programs:: Running test programs
296
* Guidelines:: General rules for writing test programs
297
* Test Functions:: Avoiding pitfalls in test programs
298
299
Results of Tests
300
301
* Defining Symbols:: Defining C preprocessor symbols
302
* Setting Output Variables:: Replacing variables in output files
303
* Caching Results:: Speeding up subsequent @command{configure} runs
304
* Printing Messages:: Notifying @command{configure} users
305
306
Caching Results
307
308
* Cache Variable Names:: Shell variables used in caches
309
* Cache Files:: Files @command{configure} uses for caching
310
* Cache Checkpointing:: Loading and saving the cache file
311
312
Programming in M4
313
314
* M4 Quotation:: Protecting macros from unwanted expansion
315
* Invoking autom4te:: The Autoconf executables backbone
316
* Programming in M4sugar:: Convenient pure M4 macros
317
* Programming in M4sh:: Common Shell Constructs
318
319
M4 Quotation
320
321
* Active Characters:: Characters that change the behavior of m4
322
* One Macro Call:: Quotation and one macro call
323
* Quotation and Nested Macros:: Macros calling macros
324
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
325
* Quadrigraphs:: Another way to escape special characters
326
* Quotation Rule Of Thumb:: One parenthesis, one quote
327
328
Programming in M4sugar
329
330
* Redefined M4 Macros:: M4 builtins changed in M4sugar
331
* Evaluation Macros:: More quotation and evaluation control
332
* Forbidden Patterns:: Catching unexpanded macros
333
334
Writing Autoconf Macros
335
336
* Macro Definitions:: Basic format of an Autoconf macro
337
* Macro Names:: What to call your new macros
338
* Reporting Messages:: Notifying @command{autoconf} users
339
* Dependencies Between Macros:: What to do when macros depend on other macros
340
* Obsoleting Macros:: Warning about old ways of doing things
341
* Coding Style:: Writing Autoconf macros @`a la Autoconf
342
343
Dependencies Between Macros
344
345
* Prerequisite Macros:: Ensuring required information
346
* Suggested Ordering:: Warning about possible ordering problems
347
348
Portable Shell Programming
349
350
* Shellology:: A zoology of shells
351
* Here-Documents:: Quirks and tricks
352
* File Descriptors:: FDs and redirections
353
* File System Conventions:: File- and pathnames
354
* Shell Substitutions:: Variable and command expansions
355
* Assignments:: Varying side effects of assignments
356
* Special Shell Variables:: Variables you should not change
357
* Limitations of Builtins:: Portable use of not so portable /bin/sh
358
* Limitations of Usual Tools:: Portable use of portable tools
359
* Limitations of Make:: Portable Makefiles
360
361
Manual Configuration
362
363
* Specifying Names:: Specifying the system type
364
* Canonicalizing:: Getting the canonical system type
365
* Using System Type:: What to do with the system type
366
367
Site Configuration
368
369
* External Software:: Working with other optional software
370
* Package Options:: Selecting optional features
371
* Pretty Help Strings:: Formating help string
372
* Site Details:: Configuring site details
373
* Transforming Names:: Changing program names when installing
374
* Site Defaults:: Giving @command{configure} local defaults
375
376
Transforming Program Names When Installing
377
378
* Transformation Options:: @command{configure} options to transform names
379
* Transformation Examples:: Sample uses of transforming names
380
* Transformation Rules:: @file{Makefile} uses of transforming names
381
382
Running @command{configure} Scripts
383
384
* Basic Installation:: Instructions for typical cases
385
* Compilers and Options:: Selecting compilers and optimization
386
* Multiple Architectures:: Compiling for multiple architectures at once
387
* Installation Names:: Installing in different directories
388
* Optional Features:: Selecting optional features
389
* System Type:: Specifying the system type
390
* Sharing Defaults:: Setting site-wide defaults for @command{configure}
391
* Defining Variables:: Specifying the compiler etc.
392
* configure Invocation:: Changing how @command{configure} runs
393
394
Obsolete Constructs
395
396
* Obsolete config.status Use:: Different calling convention
397
* acconfig.h:: Additional entries in @file{config.h.in}
398
* autoupdate Invocation:: Automatic update of @file{configure.ac}
399
* Obsolete Macros:: Backward compatibility macros
400
* Autoconf 1:: Tips for upgrading your files
401
* Autoconf 2.13:: Some fresher tips
402
403
Upgrading From Version 1
404
405
* Changed File Names:: Files you might rename
406
* Changed Makefiles:: New things to put in @file{Makefile.in}
407
* Changed Macros:: Macro calls you might replace
408
* Changed Results:: Changes in how to check test results
409
* Changed Macro Writing:: Better ways to write your own macros
410
411
Upgrading From Version 2.13
412
413
* Changed Quotation:: Broken code which used to work
414
* New Macros:: Interaction with foreign macros
415
* Hosts and Cross-Compilation:: Bugward compatibility kludges
416
* AC_LIBOBJ vs. LIBOBJS::
417
418
Generating Test Suites with Autotest
419
420
* Using an Autotest Test Suite:: Autotest and the user
421
* Writing testsuite.at:: Autotest macros
422
* testsuite Invocation:: Running @command{testsuite} scripts
423
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
424
425
Using an Autotest Test Suite
426
427
* testsuite Scripts:: The concepts of Autotest
428
* Autotest Logs:: Their contents
429
430
Questions About Autoconf
431
432
* Distributing:: Distributing @command{configure} scripts
433
* Why GNU m4:: Why not use the standard M4?
434
* Bootstrapping:: Autoconf and GNU M4 require each other?
435
* Why Not Imake:: Why GNU uses @command{configure} instead of Imake
436
437
History of Autoconf
438
439
* Genesis:: Prehistory and naming of @command{configure}
440
* Exodus:: The plagues of M4 and Perl
441
* Leviticus:: The priestly code of portability arrives
442
* Numbers:: Growth and contributors
443
* Deuteronomy:: Approaching the promises of easy configuration
444
445
Copying This Manual
446
447
* GNU Free Documentation License:: License for copying this manual
448
449
Indices
450
451
* Environment Variable Index:: Index of environment variables used
452
* Output Variable Index:: Index of variables set in output files
453
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
454
* Autoconf Macro Index:: Index of Autoconf macros
455
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
456
* Autotest Macro Index:: Index of Autotest macros
457
* Program & Function Index:: Index of those with portability problems
458
* Concept Index:: General index
459
460
@end detailmenu
461
@end menu
462
463
@c ============================================================= Introduction.
464
465
@node Introduction
466
@chapter Introduction
467
468
@flushright
469
A physicist, an engineer, and a computer scientist were discussing the
470
nature of God. ``Surely a Physicist,'' said the physicist, ``because
471
early in the Creation, God made Light; and you know, Maxwell's
472
equations, the dual nature of electromagnetic waves, the relativistic
473
consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because
474
before making Light, God split the Chaos into Land and Water; it takes a
475
hell of an engineer to handle that big amount of mud, and orderly
476
separation of solids from liquids@dots{}'' The computer scientist
477
shouted: ``And the Chaos, where do you think it was coming from, hmm?''
478
479
---Anonymous
480
@end flushright
481
@c (via Franc,ois Pinard)
482
483
Autoconf is a tool for producing shell scripts that automatically
484
configure software source code packages to adapt to many kinds of
485
@sc{unix}-like systems. The configuration scripts produced by Autoconf
486
are independent of Autoconf when they are run, so their users do not
487
need to have Autoconf.
488
489
The configuration scripts produced by Autoconf require no manual user
490
intervention when run; they do not normally even need an argument
491
specifying the system type. Instead, they individually test for the
492
presence of each feature that the software package they are for might need.
493
(Before each check, they print a one-line message stating what they are
494
checking for, so the user doesn't get too bored while waiting for the
495
script to finish.) As a result, they deal well with systems that are
496
hybrids or customized from the more common @sc{unix} variants. There is
497
no need to maintain files that list the features supported by each
498
release of each variant of @sc{unix}.
499
500
For each software package that Autoconf is used with, it creates a
501
configuration script from a template file that lists the system features
502
that the package needs or can use. After the shell code to recognize
503
and respond to a system feature has been written, Autoconf allows it to
504
be shared by many software packages that can use (or need) that feature.
505
If it later turns out that the shell code needs adjustment for some
506
reason, it needs to be changed in only one place; all of the
507
configuration scripts can be regenerated automatically to take advantage
508
of the updated code.
509
510
The Metaconfig package is similar in purpose to Autoconf, but the
511
scripts it produces require manual user intervention, which is quite
512
inconvenient when configuring large source trees. Unlike Metaconfig
513
scripts, Autoconf scripts can support cross-compiling, if some care is
514
taken in writing them.
515
516
Autoconf does not solve all problems related to making portable software
517
packages---for a more complete solution, it should be used in concert
518
with other GNU build tools like Automake and Libtool. These other tools
519
take on jobs like the creation of a portable, recursive @file{Makefile}
520
with all of the standard targets, linking of shared libraries, and so
521
on. @xref{The GNU build system}, for more information.
522
523
Autoconf imposes some restrictions on the names of macros used with
524
@code{#if} in C programs (@pxref{Preprocessor Symbol Index}).
525
526
Autoconf requires @sc{gnu} M4 in order to generate the scripts. It uses
527
features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3,
528
do not have. You must use version 1.4 or later of @sc{gnu} M4.
529
530
@xref{Autoconf 1}, for information about upgrading from version 1.
531
@xref{History}, for the story of Autoconf's development.
532
@xref{Questions}, for answers to some common questions about Autoconf.
533
534
535
See the @href{http://www.gnu.org/software/autoconf/autoconf.html,
536
Autoconf web page} for up-to-date information, details on the mailing
537
lists, pointers to a list of known bugs, etc.
538
539
Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing
540
list}.
541
542
Bug reports should be preferably submitted to the
543
@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf,
544
Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the
545
Autoconf Bugs mailing list}. If possible, first check that your bug is
546
not already solved in current development versions, and that it has not
547
been reported yet. Be sure to include all the needed information and a
548
short @file{configure.ac} that demonstrates the problem.
549
550
Autoconf's development tree is accessible via @sc{cvs}; see the Autoconf
551
web page for details. There is also a
552
@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web
553
interface to the Autoconf development tree}. Patches relative to the
554
current @sc{cvs} version can be sent for review to the
555
@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}.
556
557
Because of its mission, Autoconf includes only a set of often-used
558
macros that have already demonstrated their usefulness. Nevertheless,
559
if you wish to share your macros, or find existing ones, see the
560
@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro
561
Archive}, which is kindly run by @email{simons@@computer.org,
562
Peter Simons}.
563
564
565
@c ================================================= The GNU build system
566
567
@node The GNU build system
568
@chapter The GNU build system
569
570
Autoconf solves an important problem---reliable discovery of
571
system-specific build and runtime information---but this is only one
572
piece of the puzzle for the development of portable software. To this
573
end, the GNU project has developed a suite of integrated utilities to
574
finish the job Autoconf started: the GNU build system, whose most
575
important components are Autoconf, Automake, and Libtool. In this
576
chapter, we introduce you to those tools, point you to sources of more
577
information, and try to convince you to use the entire GNU build system
578
for your software.
579
580
@menu
581
* Automake:: Escaping Makefile hell
582
* Libtool:: Building libraries portably
583
* Pointers:: More info on the GNU build system
584
@end menu
585
586
@node Automake
587
@section Automake
588
589
The ubiquity of @code{make} means that a @code{Makefile} is almost the
590
only viable way to distribute automatic build rules for software, but
591
one quickly runs into @code{make}'s numerous limitations. Its lack of
592
support for automatic dependency tracking, recursive builds in
593
subdirectories, reliable timestamps (e.g. for network filesystems), and
594
so on, mean that developers must painfully (and often incorrectly)
595
reinvent the wheel for each project. Portability is non-trivial, thanks
596
to the quirks of @code{make} on many systems. On top of all this is the
597
manual labor required to implement the many standard targets that users
598
have come to expect (@code{make install}, @code{make distclean},
599
@code{make uninstall}, etc.). Since you are, of course, using Autoconf,
600
you also have to insert repetitive code in your @code{Makefile.in} to
601
recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions
602
provided by @command{configure}. Into this mess steps @dfn{Automake}.
603
@cindex Automake
604
605
Automake allows you to specify your build needs in a @code{Makefile.am}
606
file with a vastly simpler and more powerful syntax than that of a plain
607
@code{Makefile}, and then generates a portable @code{Makefile.in} for
608
use with Autoconf. For example, the @code{Makefile.am} to build and
609
install a simple ``Hello world'' program might look like:
610
611
@example
612
bin_PROGRAMS = hello
613
hello_SOURCES = hello.c
614
@end example
615
616
@noindent
617
The resulting @code{Makefile.in} (~400 lines) automatically supports all
618
the standard targets, the substitutions provided by Autoconf, automatic
619
dependency tracking, @code{VPATH} building, and so on. @code{make} will
620
build the @code{hello} program, and @code{make install} will install it
621
in @file{/usr/local/bin} (or whatever prefix was given to
622
@command{configure}, if not @file{/usr/local}).
623
624
Automake may require that additional tools be present on the
625
@emph{developer's} machine. For example, the @code{Makefile.in} that
626
the developer works with may not be portable (e.g. it might use special
627
features of your compiler to automatically generate dependency
628
information). Running @code{make dist}, however, produces a
629
@file{hello-1.0.tar.gz} package (or whatever the program/version is)
630
with a @code{Makefile.in} that will work on any system.
631
632
The benefits of Automake increase for larger packages (especially ones
633
with subdirectories), but even for small programs the added convenience
634
and portability can be substantial. And that's not all@dots{}
635
636
@node Libtool
637
@section Libtool
638
639
Very often, one wants to build not only programs, but libraries, so that
640
other programs can benefit from the fruits of your labor. Ideally, one
641
would like to produce @emph{shared} (dynamically-linked) libraries,
642
which can be used by multiple programs without duplication on disk or in
643
memory and can be updated independently of the linked programs.
644
Producing shared libraries portably, however, is the stuff of
645
nightmares---each system has its own incompatible tools, compiler flags,
646
and magic incantations. Fortunately, GNU provides a solution:
647
@dfn{Libtool}.
648
@cindex Libtool
649
650
Libtool handles all the requirements of building shared libraries for
651
you, and at this time seems to be the @emph{only} way to do so with any
652
portability. It also handles many other headaches, such as: the
653
interaction of @code{Makefile} rules with the variable suffixes of
654
shared libraries, linking reliably to shared libraries before they are
655
installed by the superuser, and supplying a consistent versioning system
656
(so that different versions of a library can be installed or upgraded
657
without breaking binary compatibility). Although Libtool, like
658
Autoconf, can be used on its own, it is most simply utilized in
659
conjunction with Automake---there, Libtool is used automatically
660
whenever shared libraries are needed, and you need not know its syntax.
661
662
@node Pointers
663
@section Pointers
664
665
Developers who are used to the simplicity of @code{make} for small
666
projects on a single system might be daunted at the prospect of learning
667
to use Automake and Autoconf. As your software is distributed to more
668
and more users, however, you will otherwise quickly find yourself
669
putting lots of effort into reinventing the services that the GNU build
670
tools provide, and making the same mistakes that they once made and
671
overcame. (Besides, since you're already learning Autoconf, Automake
672
will be a piece of cake.)
673
674
There are a number of places that you can go to for more information on
675
the GNU build tools.
676
677
@itemize @minus
678
679
@item Web
680
681
The home pages for
682
@href{http://www.gnu.org/software/autoconf/,Autoconf},
683
@href{http://www.gnu.org/software/automake/,Automake}, and
684
@href{http://www.gnu.org/software/libtool/,Libtool}.
685
686
@item Automake Manual
687
688
@xref{Top,,Automake,automake,GNU Automake}, for more
689
information on Automake.
690
691
@item Books
692
693
The book @cite{GNU Autoconf, Automake and Libtool}@footnote{@cite{GNU
694
Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston,
695
T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.}
696
describes the complete GNU build environment. You can also find the
697
entire book on-line at @href{http://sources.redhat.com/autobook/,``The
698
Goat Book'' home page}.
699
700
@item Tutorials and Examples
701
702
The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page}
703
maintains links to a number of Autoconf/Automake tutorials online, and
704
also links to the @href{http://www.gnu.org/software/ac-archive/,
705
Autoconf Macro Archive}.
706
707
@end itemize
708
709
@c ================================================= Making configure Scripts.
710
711
@node Making configure Scripts
712
@chapter Making @command{configure} Scripts
713
@cindex @file{aclocal.m4}
714
@cindex @command{configure}
715
716
The configuration scripts that Autoconf produces are by convention
717
called @command{configure}. When run, @command{configure} creates several
718
files, replacing configuration parameters in them with appropriate
719
values. The files that @command{configure} creates are:
720
721
@itemize @minus
722
@item
723
one or more @file{Makefile} files, one in each subdirectory of the
724
package (@pxref{Makefile Substitutions});
725
726
@item
727
optionally, a C header file, the name of which is configurable,
728
containing @code{#define} directives (@pxref{Configuration Headers});
729
730
@item
731
a shell script called @file{config.status} that, when run, will recreate
732
the files listed above (@pxref{config.status Invocation});
733
734
@item
735
an optional shell script normally called @file{config.cache}
736
(created when using @samp{configure --config-cache}) that
737
saves the results of running many of the tests (@pxref{Cache Files});
738
739
@item
740
a file called @file{config.log} containing any messages produced by
741
compilers, to help debugging if @command{configure} makes a mistake.
742
@end itemize
743
744
@cindex @file{configure.in}
745
@cindex @file{configure.ac}
746
To create a @command{configure} script with Autoconf, you need to write an
747
Autoconf input file @file{configure.ac} (or @file{configure.in}) and run
748
@command{autoconf} on it. If you write your own feature tests to
749
supplement those that come with Autoconf, you might also write files
750
called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header
751
file to contain @code{#define} directives, you might also run
752
@command{autoheader}, and you will distribute the generated file
753
@file{config.h.in} with the package.
754
755
Here is a diagram showing how the files that can be used in
756
configuration are produced. Programs that are executed are suffixed by
757
@samp{*}. Optional files are enclosed in square brackets (@samp{[]}).
758
@command{autoconf} and @command{autoheader} also read the installed Autoconf
759
macro files (by reading @file{autoconf.m4}).
760
761
@noindent
762
Files used in preparing a software package for distribution:
763
@example
764
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
765
766
@group
767
configure.ac --.
768
| .------> autoconf* -----> configure
769
[aclocal.m4] --+---+
770
| `-----> [autoheader*] --> [config.h.in]
771
[acsite.m4] ---'
772
@end group
773
774
Makefile.in -------------------------------> Makefile.in
775
@end example
776
777
@noindent
778
Files used in configuring a software package:
779
@example
780
@group
781
.-------------> [config.cache]
782
configure* ------------+-------------> config.log
783
|
784
[config.h.in] -. v .-> [config.h] -.
785
+--> config.status* -+ +--> make*
786
Makefile.in ---' `-> Makefile ---'
787
@end group
788
@end example
789
790
@menu
791
* Writing configure.ac:: What to put in an Autoconf input file
792
* autoscan Invocation:: Semi-automatic @file{configure.ac} writing
793
* ifnames Invocation:: Listing the conditionals in source code
794
* autoconf Invocation:: How to create configuration scripts
795
* autoreconf Invocation:: Remaking multiple @command{configure} scripts
796
@end menu
797
798
@node Writing configure.ac
799
@section Writing @file{configure.ac}
800
801
To produce a @command{configure} script for a software package, create a
802
file called @file{configure.ac} that contains invocations of the
803
Autoconf macros that test the system features your package needs or can
804
use. Autoconf macros already exist to check for many features; see
805
@ref{Existing Tests}, for their descriptions. For most other features,
806
you can use Autoconf template macros to produce custom checks; see
807
@ref{Writing Tests}, for information about them. For especially tricky
808
or specialized features, @file{configure.ac} might need to contain some
809
hand-crafted shell commands; see @ref{Portable Shell}. The
810
@command{autoscan} program can give you a good start in writing
811
@file{configure.ac} (@pxref{autoscan Invocation}, for more information).
812
813
Previous versions of Autoconf promoted the name @file{configure.in},
814
which is somewhat ambiguous (the tool needed to produce this file is not
815
described by its extension), and introduces a slight confusion with
816
@file{config.h.in} and so on (for which @samp{.in} means ``to be
817
processed by @command{configure}''). Using @file{configure.ac} is now
818
preferred.
819
820
@menu
821
* Shell Script Compiler:: Autoconf as solution of a problem
822
* Autoconf Language:: Programming in Autoconf
823
* configure.ac Layout:: Standard organization of configure.ac
824
@end menu
825
826
@node Shell Script Compiler
827
@subsection A Shell Script Compiler
828
829
Just as for any other computer language, in order to properly program
830
@file{configure.ac} in Autoconf you must understand @emph{what} problem
831
the language tries to address and @emph{how} it does so.
832
833
The problem Autoconf addresses is that the world is a mess. After all,
834
you are using Autoconf in order to have your package compile easily on
835
all sorts of different systems, some of them being extremely hostile.
836
Autoconf itself bears the price for these differences: @command{configure}
837
must run on all those systems, and thus @command{configure} must limit itself
838
to their lowest common denominator of features.
839
840
Naturally, you might then think of shell scripts; who needs
841
@command{autoconf}? A set of properly written shell functions is enough to
842
make it easy to write @command{configure} scripts by hand. Sigh!
843
Unfortunately, shell functions do not belong to the least common
844
denominator; therefore, where you would like to define a function and
845
use it ten times, you would instead need to copy its body ten times.
846
847
So, what is really needed is some kind of compiler, @command{autoconf},
848
that takes an Autoconf program, @file{configure.ac}, and transforms it
849
into a portable shell script, @command{configure}.
850
851
How does @command{autoconf} perform this task?
852
853
There are two obvious possibilities: creating a brand new language or
854
extending an existing one. The former option is very attractive: all
855
sorts of optimizations could easily be implemented in the compiler and
856
many rigorous checks could be performed on the Autoconf program
857
(e.g. rejecting any non-portable construct). Alternatively, you can
858
extend an existing language, such as the @code{sh} (Bourne shell)
859
language.
860
861
Autoconf does the latter: it is a layer on top of @code{sh}. It was
862
therefore most convenient to implement @command{autoconf} as a macro
863
expander: a program that repeatedly performs @dfn{macro expansions} on
864
text input, replacing macro calls with macro bodies and producing a pure
865
@code{sh} script in the end. Instead of implementing a dedicated
866
Autoconf macro expander, it is natural to use an existing
867
general-purpose macro language, such as M4, and implement the extensions
868
as a set of M4 macros.
869
870
871
@node Autoconf Language
872
@subsection The Autoconf Language
873
@cindex quotation
874
875
The Autoconf language is very different from many other computer
876
languages because it treats actual code the same as plain text. Whereas
877
in C, for instance, data and instructions have very different syntactic
878
status, in Autoconf their status is rigorously the same. Therefore, we
879
need a means to distinguish literal strings from text to be expanded:
880
quotation.
881
882
When calling macros that take arguments, there must not be any blank
883
space between the macro name and the open parenthesis. Arguments should
884
be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be
885
separated by commas. Any leading spaces in arguments are ignored,
886
unless they are quoted. You may safely leave out the quotes when the
887
argument is simple text, but @emph{always} quote complex arguments such
888
as other macro calls. This rule applies recursively for every macro
889
call, including macros called from other macros.
890
891
For instance:
892
893
@example
894
AC_CHECK_HEADER([stdio.h],
895
[AC_DEFINE([HAVE_STDIO_H])],
896
[AC_MSG_ERROR([Sorry, can't do anything for you])])
897
@end example
898
899
@noindent
900
is quoted properly. You may safely simplify its quotation to:
901
902
@example
903
AC_CHECK_HEADER(stdio.h,
904
[AC_DEFINE(HAVE_STDIO_H)],
905
[AC_MSG_ERROR([Sorry, can't do anything for you])])
906
@end example
907
908
@noindent
909
Notice that the argument of @code{AC_MSG_ERROR} is still quoted;
910
otherwise, its comma would have been interpreted as an argument separator.
911
912
The following example is wrong and dangerous, as it is underquoted:
913
914
@example
915
AC_CHECK_HEADER(stdio.h,
916
AC_DEFINE(HAVE_STDIO_H),
917
AC_MSG_ERROR([Sorry, can't do anything for you]))
918
@end example
919
920
In other cases, you may have to use text that also resembles a macro
921
call. You must quote that text even when it is not passed as a macro
922
argument:
923
924
@example
925
echo "Hard rock was here! --[AC_DC]"
926
@end example
927
928
@noindent
929
which will result in
930
931
@example
932
echo "Hard rock was here! --AC_DC"
933
@end example
934
935
@noindent
936
When you use the same text in a macro argument, you must therefore have
937
an extra quotation level (since one is stripped away by the macro
938
substitution). In general, then, it is a good idea to @emph{use double
939
quoting for all literal string arguments}:
940
941
@example
942
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
943
@end example
944
945
You are now able to understand one of the constructs of Autoconf that
946
has been continually misunderstood@dots{} The rule of thumb is that
947
@emph{whenever you expect macro expansion, expect quote expansion};
948
i.e., expect one level of quotes to be lost. For instance:
949
950
@example
951
AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])])
952
@end example
953
954
@noindent
955
is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is
956
@samp{char b[10];} and will be expanded once, which results in
957
@samp{char b10;}. (There was an idiom common in Autoconf's past to
958
address this issue via the M4 @code{changequote} primitive, but do not
959
use it!) Let's take a closer look: the author meant the first argument
960
to be understood as a literal, and therefore it must be quoted twice:
961
962
@example
963
AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])])
964
@end example
965
966
@noindent
967
Voil@`a, you actually produce @samp{char b[10];} this time!
968
969
The careful reader will notice that, according to these guidelines, the
970
``properly'' quoted @code{AC_CHECK_HEADER} example above is actually
971
lacking three pairs of quotes! Nevertheless, for the sake of readability,
972
double quotation of literals is used only where needed in this manual.
973
974
Some macros take optional arguments, which this documentation represents
975
as @ovar{arg} (not to be confused with the quote characters). You may
976
just leave them empty, or use @samp{[]} to make the emptiness of the
977
argument explicit, or you may simply omit the trailing commas. The
978
three lines below are equivalent:
979
980
@example
981
AC_CHECK_HEADERS(stdio.h, [], [], [])
982
AC_CHECK_HEADERS(stdio.h,,,)
983
AC_CHECK_HEADERS(stdio.h)
984
@end example
985
986
It is best to put each macro call on its own line in
987
@file{configure.ac}. Most of the macros don't add extra newlines; they
988
rely on the newline after the macro call to terminate the commands.
989
This approach makes the generated @command{configure} script a little
990
easier to read by not inserting lots of blank lines. It is generally
991
safe to set shell variables on the same line as a macro call, because
992
the shell allows assignments without intervening newlines.
993
994
You can include comments in @file{configure.ac} files by starting them
995
with the @samp{#}. For example, it is helpful to begin
996
@file{configure.ac} files with a line like this:
997
998
@example
999
# Process this file with autoconf to produce a configure script.
1000
@end example
1001
1002
@node configure.ac Layout
1003
@subsection Standard @file{configure.ac} Layout
1004
1005
The order in which @file{configure.ac} calls the Autoconf macros is not
1006
important, with a few exceptions. Every @file{configure.ac} must
1007
contain a call to @code{AC_INIT} before the checks, and a call to
1008
@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros
1009
rely on other macros having been called first, because they check
1010
previously set values of some variables to decide what to do. These
1011
macros are noted in the individual descriptions (@pxref{Existing
1012
Tests}), and they also warn you when @command{configure} is created if they
1013
are called out of order.
1014
1015
To encourage consistency, here is a suggested order for calling the
1016
Autoconf macros. Generally speaking, the things near the end of this
1017
list are those that could depend on things earlier in it. For example,
1018
library functions could be affected by types and libraries.
1019
1020
@display
1021
@group
1022
Autoconf requirements
1023
@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})}
1024
information on the package
1025
checks for programs
1026
checks for libraries
1027
checks for header files
1028
checks for types
1029
checks for structures
1030
checks for compiler characteristics
1031
checks for library functions
1032
checks for system services
1033
@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})}
1034
@code{AC_OUTPUT}
1035
@end group
1036
@end display
1037
1038
1039
@node autoscan Invocation
1040
@section Using @command{autoscan} to Create @file{configure.ac}
1041
@cindex @command{autoscan}
1042
1043
The @command{autoscan} program can help you create and/or maintain a
1044
@file{configure.ac} file for a software package. @command{autoscan}
1045
examines source files in the directory tree rooted at a directory given
1046
as a command line argument, or the current directory if none is given.
1047
It searches the source files for common portability problems and creates
1048
a file @file{configure.scan} which is a preliminary @file{configure.ac}
1049
for that package, and checks a possibly existing @file{configure.ac} for
1050
completeness.
1051
1052
When using @command{autoscan} to create a @file{configure.ac}, you
1053
should manually examine @file{configure.scan} before renaming it to
1054
@file{configure.ac}; it will probably need some adjustments.
1055
Occasionally, @command{autoscan} outputs a macro in the wrong order
1056
relative to another macro, so that @command{autoconf} produces a warning;
1057
you need to move such macros manually. Also, if you want the package to
1058
use a configuration header file, you must add a call to
1059
@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might
1060
also have to change or add some @code{#if} directives to your program in
1061
order to make it work with Autoconf (@pxref{ifnames Invocation}, for
1062
information about a program that can help with that job).
1063
1064
When using @command{autoscan} to maintain a @file{configure.ac}, simply
1065
consider adding its suggestions. The file @file{autoscan.log} will
1066
contain detailed information on why a macro is requested.
1067
1068
@command{autoscan} uses several data files (installed along with Autoconf)
1069
to determine which macros to output when it finds particular symbols in
1070
a package's source files. These data files all have the same format:
1071
each line consists of a symbol, whitespace, and the Autoconf macro to
1072
output if that symbol is encountered. Lines starting with @samp{#} are
1073
comments.
1074
1075
@command{autoscan} accepts the following options:
1076
1077
@table @option
1078
@item --help
1079
@itemx -h
1080
Print a summary of the command line options and exit.
1081
1082
@item --version
1083
@itemx -V
1084
Print the version number of Autoconf and exit.
1085
1086
@item --verbose
1087
@itemx -v
1088
Print the names of the files it examines and the potentially interesting
1089
symbols it finds in them. This output can be voluminous.
1090
1091
@item --include=@var{dir}
1092
@itemx -I @var{dir}
1093
Also look for input files in @var{dir}. Multiple invocations
1094
accumulate. Directories are browsed from last to first.
1095
@end table
1096
1097
@node ifnames Invocation
1098
@section Using @command{ifnames} to List Conditionals
1099
@cindex @command{ifnames}
1100
1101
@command{ifnames} can help you write @file{configure.ac} for a software
1102
package. It prints the identifiers that the package already uses in C
1103
preprocessor conditionals. If a package has already been set up to have
1104
some portability, @command{ifnames} can thus help you figure out what its
1105
@command{configure} needs to check for. It may help fill in some gaps in a
1106
@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan
1107
Invocation}).
1108
1109
@command{ifnames} scans all of the C source files named on the command line
1110
(or the standard input, if none are given) and writes to the standard
1111
output a sorted list of all the identifiers that appear in those files
1112
in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef}
1113
directives. It prints each identifier on a line, followed by a
1114
space-separated list of the files in which that identifier occurs.
1115
1116
@noindent
1117
@command{ifnames} accepts the following options:
1118
1119
@table @option
1120
@item --help
1121
@itemx -h
1122
Print a summary of the command line options and exit.
1123
1124
@item --version
1125
@itemx -V
1126
Print the version number of Autoconf and exit.
1127
@end table
1128
1129
@node autoconf Invocation
1130
@section Using @command{autoconf} to Create @command{configure}
1131
@cindex @command{autoconf}
1132
1133
To create @command{configure} from @file{configure.ac}, run the
1134
@command{autoconf} program with no arguments. @command{autoconf} processes
1135
@file{configure.ac} with the @code{m4} macro processor, using the
1136
Autoconf macros. If you give @command{autoconf} an argument, it reads that
1137
file instead of @file{configure.ac} and writes the configuration script
1138
to the standard output instead of to @command{configure}. If you give
1139
@command{autoconf} the argument @option{-}, it reads from the standard
1140
input instead of @file{configure.ac} and writes the configuration script
1141
to the standard output.
1142
1143
The Autoconf macros are defined in several files. Some of the files are
1144
distributed with Autoconf; @command{autoconf} reads them first. Then it
1145
looks for the optional file @file{acsite.m4} in the directory that
1146
contains the distributed Autoconf macro files, and for the optional file
1147
@file{aclocal.m4} in the current directory. Those files can contain
1148
your site's or the package's own Autoconf macro definitions
1149
(@pxref{Writing Autoconf Macros}, for more information). If a macro is
1150
defined in more than one of the files that @command{autoconf} reads, the
1151
last definition it reads overrides the earlier ones.
1152
1153
@command{autoconf} accepts the following options:
1154
1155
@table @option
1156
@item --help
1157
@itemx -h
1158
Print a summary of the command line options and exit.
1159
1160
@item --version
1161
@itemx -V
1162
Print the version number of Autoconf and exit.
1163
1164
@item --verbose
1165
@itemx -v
1166
Report processing steps.
1167
1168
@item --debug
1169
@itemx -d
1170
Don't remove the temporary files.
1171
1172
@item --force
1173
@itemx -f
1174
Remake @file{configure} even if newer than its input files.
1175
1176
@item --include=@var{dir}
1177
@itemx -I @var{dir}
1178
Also look for input files in @var{dir}. Multiple invocations
1179
accumulate. Directories are browsed from last to first.
1180
1181
@item --output=@var{file}
1182
@itemx -o @var{file}
1183
Save output (script or trace) to @var{file}. The file @option{-} stands
1184
for the standard output.
1185
1186
@item --warnings=@var{category}
1187
@itemx -W @var{category}
1188
@evindex WARNINGS
1189
Report the warnings related to @var{category} (which can actually be a
1190
comma separated list). @xref{Reporting Messages}, macro
1191
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
1192
values include:
1193
1194
@table @samp
1195
@item all
1196
report all the warnings
1197
1198
@item none
1199
report none
1200
1201
@item error
1202
treats warnings as errors
1203
1204
@item no-@var{category}
1205
disable warnings falling into @var{category}
1206
@end table
1207
1208
Warnings about @samp{syntax} are enabled by default, and the environment
1209
variable @code{WARNINGS}, a comma separated list of categories, is
1210
honored. @command{autoconf -W @var{category}} will actually
1211
behave as if you had run:
1212
1213
@example
1214
autoconf --warnings=syntax,$WARNINGS,@var{category}
1215
@end example
1216
1217
@noindent
1218
If you want to disable @command{autoconf}'s defaults and @code{WARNINGS},
1219
but (for example) enable the warnings about obsolete constructs, you
1220
would use @option{-W none,obsolete}.
1221
1222
@cindex Back trace
1223
@cindex Macro invocation stack
1224
@command{autoconf} displays a back trace for errors, but not for
1225
warnings; if you want them, just pass @option{-W error}. For instance,
1226
on this @file{configure.ac}:
1227
1228
@example
1229
AC_DEFUN([INNER],
1230
[AC_TRY_RUN([exit (0)])])
1231
1232
AC_DEFUN([OUTER],
1233
[INNER])
1234
1235
AC_INIT
1236
OUTER
1237
@end example
1238
1239
@noindent
1240
you get:
1241
1242
@example
1243
$ @kbd{autoconf -Wcross}
1244
configure.ac:8: warning: AC_TRY_RUN called without default \
1245
to allow cross compiling
1246
$ @kbd{autoconf -Wcross,error}
1247
configure.ac:8: error: AC_TRY_RUN called without default \
1248
to allow cross compiling
1249
acgeneral.m4:3044: AC_TRY_RUN is expanded from...
1250
configure.ac:2: INNER is expanded from...
1251
configure.ac:5: OUTER is expanded from...
1252
configure.ac:8: the top level
1253
@end example
1254
1255
@item --trace=@var{macro}[:@var{format}]
1256
@itemx -t @var{macro}[:@var{format}]
1257
Do not create the @command{configure} script, but list the calls to
1258
@var{macro} according to the @var{format}. Multiple @option{--trace}
1259
arguments can be used to list several macros. Multiple @option{--trace}
1260
arguments for a single macro are not cumulative; instead, you should
1261
just make @var{format} as long as needed.
1262
1263
The @var{format} is a regular string, with newlines if desired, and
1264
several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see
1265
below for details on the @var{format}.
1266
1267
@item --initialization
1268
@itemx -i
1269
By default, @option{--trace} does not trace the initialization of the
1270
Autoconf macros (typically the @code{AC_DEFUN} definitions). This
1271
results in a noticeable speedup, but can be disabled by this option.
1272
@end table
1273
1274
1275
It is often necessary to check the content of a @file{configure.ac}
1276
file, but parsing it yourself is extremely fragile and error-prone. It
1277
is suggested that you rely upon @option{--trace} to scan
1278
@file{configure.ac}.
1279
1280
The @var{format} of @option{--trace} can use the following special
1281
escapes:
1282
1283
@table @samp
1284
@item $$
1285
The character @samp{$}.
1286
1287
@item $f
1288
The filename from which @var{macro} is called.
1289
1290
@item $l
1291
The line number from which @var{macro} is called.
1292
1293
@item $d
1294
The depth of the @var{macro} call. This is an M4 technical detail that
1295
you probably don't want to know about.
1296
1297
@item $n
1298
The name of the @var{macro}.
1299
1300
@item $@var{num}
1301
The @var{num}th argument of the call to @var{macro}.
1302
1303
@item $@@
1304
@itemx $@var{sep}@@
1305
@itemx $@{@var{separator}@}@@
1306
All the arguments passed to @var{macro}, separated by the character
1307
@var{sep} or the string @var{separator} (@samp{,} by default). Each
1308
argument is quoted, i.e. enclosed in a pair of square brackets.
1309
1310
@item $*
1311
@itemx $@var{sep}*
1312
@itemx $@{@var{separator}@}*
1313
As above, but the arguments are not quoted.
1314
1315
@item $%
1316
@itemx $@var{sep}%
1317
@itemx $@{@var{separator}@}%
1318
As above, but the arguments are not quoted, all new line characters in
1319
the arguments are smashed, and the default separator is @samp{:}.
1320
1321
The escape @samp{$%} produces single-line trace outputs (unless you put
1322
newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
1323
not.
1324
@end table
1325
1326
For instance, to find the list of variables that are substituted, use:
1327
1328
@example
1329
@group
1330
$ @kbd{autoconf -t AC_SUBST}
1331
configure.ac:2:AC_SUBST:ECHO_C
1332
configure.ac:2:AC_SUBST:ECHO_N
1333
configure.ac:2:AC_SUBST:ECHO_T
1334
@i{More traces deleted}
1335
@end group
1336
@end example
1337
1338
@noindent
1339
The example below highlights the difference between @samp{$@@},
1340
@samp{$*}, and @strong{$%}.
1341
1342
@example
1343
@group
1344
$ @kbd{cat configure.ac}
1345
AC_DEFINE(This, is, [an
1346
[example]])
1347
$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@}
1348
*: $*
1349
$: $%'
1350
@@: [This],[is],[an
1351
[example]]
1352
*: This,is,an
1353
[example]
1354
$: This:is:an [example]
1355
@end group
1356
@end example
1357
1358
@noindent
1359
The @var{format} gives you a lot of freedom:
1360
1361
@example
1362
@group
1363
$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'}
1364
$ac_subst@{"ECHO_C"@} = "configure.ac:2";
1365
$ac_subst@{"ECHO_N"@} = "configure.ac:2";
1366
$ac_subst@{"ECHO_T"@} = "configure.ac:2";
1367
@i{More traces deleted}
1368
@end group
1369
@end example
1370
1371
@noindent
1372
A long @var{separator} can be used to improve the readability of complex
1373
structures, and to ease its parsing (for instance when no single
1374
character is suitable as a separator)):
1375
1376
@example
1377
@group
1378
$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'}
1379
ACLOCAL|:::::|aclocal|:::::|$missing_dir
1380
AUTOCONF|:::::|autoconf|:::::|$missing_dir
1381
AUTOMAKE|:::::|automake|:::::|$missing_dir
1382
@i{More traces deleted}
1383
@end group
1384
@end example
1385
1386
@node autoreconf Invocation
1387
@section Using @command{autoreconf} to Update @command{configure} Scripts
1388
@cindex @command{autoreconf}
1389
1390
Installing the various components of the @sc{gnu} Build System can be
1391
tedious: running @command{gettextize}, @command{automake} etc. in each
1392
directory. It may be needed either because some tools such as
1393
@command{automake} have been updated on your system, or because some of
1394
the sources such as @file{configure.ac} have been updated, or finally,
1395
simply in order to install the @sc{gnu} Build System in a fresh tree.
1396
1397
It runs @command{autoconf}, @command{autoheader}, @command{aclocal},
1398
@command{automake}, @command{libtoolize}, and @command{gettextize} (when
1399
appropriate) repeatedly to update the @sc{gnu} Build System in specified
1400
directories, and their subdirectories (@pxref{Subdirectories}). By
1401
default, it only remakes those files that are older than their sources.
1402
1403
If you install a new version of some tools, you can make
1404
@command{autoreconf} remake @emph{all} of the files by giving it the
1405
@option{--force} option.
1406
1407
@xref{Automatic Remaking}, for @file{Makefile} rules to automatically
1408
remake @command{configure} scripts when their source files change. That
1409
method handles the timestamps of configuration header templates
1410
properly, but does not pass @option{--autoconf-dir=@var{dir}} or
1411
@option{--localdir=@var{dir}}.
1412
1413
@noindent
1414
@command{autoreconf} accepts the following options:
1415
1416
@table @option
1417
@item --help
1418
@itemx -h
1419
Print a summary of the command line options and exit.
1420
1421
@item --version
1422
@itemx -V
1423
Print the version number of Autoconf and exit.
1424
1425
@item --verbose
1426
Print the name of each directory where @command{autoreconf} runs
1427
@command{autoconf} (and @command{autoheader}, if appropriate).
1428
1429
@item --debug
1430
@itemx -d
1431
Don't remove the temporary files.
1432
1433
@item --force
1434
@itemx -f
1435
Remake even @file{configure} scripts and configuration headers that are
1436
newer than their input files (@file{configure.ac} and, if present,
1437
@file{aclocal.m4}).
1438
1439
@item --install
1440
@itemx -i
1441
Copy missing auxiliary files. This option is similar to the option
1442
@code{--add-missing} in @command{automake}.
1443
1444
@item --symlink
1445
@itemx -s
1446
Instead of copying missing auxiliary files, install symbolic links.
1447
1448
@item --include=@var{dir}
1449
@itemx -I @var{dir}
1450
Also look for input files in @var{dir}. Multiple invocations
1451
accumulate. Directories are browsed from last to first.
1452
@end table
1453
1454
1455
@c ========================================= Initialization and Output Files.
1456
1457
@node Setup
1458
@chapter Initialization and Output Files
1459
1460
Autoconf-generated @command{configure} scripts need some information about
1461
how to initialize, such as how to find the package's source files; and
1462
about the output files to produce. The following sections describe
1463
initialization and the creation of output files.
1464
1465
@menu
1466
* Initializing configure:: Option processing etc.
1467
* Notices:: Copyright, version numbers in @command{configure}
1468
* Input:: Where Autoconf should find files
1469
* Output:: Outputting results from the configuration
1470
* Configuration Actions:: Preparing the output based on results
1471
* Configuration Files:: Creating output files
1472
* Makefile Substitutions:: Using output variables in @file{Makefile}s
1473
* Configuration Headers:: Creating a configuration header file
1474
* Configuration Commands:: Running arbitrary instantiation commands
1475
* Configuration Links:: Links depending from the configuration
1476
* Subdirectories:: Configuring independent packages together
1477
* Default Prefix:: Changing the default installation prefix
1478
@end menu
1479
1480
@node Initializing configure
1481
@section Initializing @command{configure}
1482
1483
Every @command{configure} script must call @code{AC_INIT} before doing
1484
anything else. The only other required macro is @code{AC_OUTPUT}
1485
(@pxref{Output}).
1486
1487
@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname})
1488
@acindex INIT
1489
Process any command-line arguments and perform various initializations
1490
and verifications.
1491
1492
Set the name of the @var{package} and its @var{version}. These are
1493
typically used in @option{--version} support, including that of
1494
@command{configure}. The optional argument @var{bug-report} should be
1495
the email to which users should send bug reports. The package
1496
@var{tarname} differs from @var{package}: the latter designates the full
1497
package name (e.g., @samp{GNU Autoconf}), while the latter is meant for
1498
distribution tar ball names (e.g., @samp{autoconf}). It defaults to
1499
@var{package} once @samp{GNU } strip, lower cased, and all non
1500
alphanumeric character mapped onto @samp{-}.
1501
1502
It is preferable that these arguments be static, i.e., there should not
1503
be any shell computation, but they can be computed by M4. The following
1504
M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables (e.g.,
1505
@code{PACKAGE_NAME}), and preprocessor symbols (e.g.,
1506
@code{PACKAGE_NAME}) are then defined:
1507
1508
@table @asis
1509
@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME}
1510
@acindex PACKAGE_NAME
1511
@ovindex PACKAGE_NAME
1512
@cvindex PACKAGE_NAME
1513
Exactly @var{package}.
1514
1515
@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME}
1516
@acindex PACKAGE_TARNAME
1517
@ovindex PACKAGE_TARNAME
1518
@cvindex PACKAGE_TARNAME
1519
Exactly @var{tarname}.
1520
1521
@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
1522
@acindex PACKAGE_VERSION
1523
@ovindex PACKAGE_VERSION
1524
@cvindex PACKAGE_VERSION
1525
Exactly @var{version}.
1526
1527
@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING}
1528
@acindex PACKAGE_STRING
1529
@ovindex PACKAGE_STRING
1530
@cvindex PACKAGE_STRING
1531
Exactly @samp{@var{package} @var{version}}.
1532
1533
@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT}
1534
@acindex PACKAGE_BUGREPORT
1535
@ovindex PACKAGE_BUGREPORT
1536
@cvindex PACKAGE_BUGREPORT
1537
Exactly @var{bug-report}.
1538
@end table
1539
@end defmac
1540
1541
1542
@node Notices
1543
@section Notices in @command{configure}
1544
1545
The following macros manage version numbers for @command{configure}
1546
scripts. Using them is optional.
1547
1548
@c FIXME: AC_PREREQ should not be here
1549
@defmac AC_PREREQ (@var{version})
1550
@acindex PREREQ
1551
@cindex Version
1552
Ensure that a recent enough version of Autoconf is being used. If the
1553
version of Autoconf being used to create @command{configure} is earlier
1554
than @var{version}, print an error message to the standard error output
1555
and do not create @command{configure}. For example:
1556
1557
@example
1558
AC_PREREQ(@value{VERSION})
1559
@end example
1560
1561
This macro is the only macro that may be used before @code{AC_INIT}, but
1562
for consistency, you are invited not to do so.
1563
@end defmac
1564
1565
@defmac AC_COPYRIGHT (@var{copyright-notice})
1566
@acindex COPYRIGHT
1567
@cindex Copyright Notice
1568
State that, in addition to the Free Software Foundation's copyright on
1569
the Autoconf macros, parts of your @command{configure} are covered by the
1570
@var{copyright-notice}.
1571
1572
The @var{copyright-notice} will show up in both the head of
1573
@command{configure} and in @samp{configure --version}.
1574
@end defmac
1575
1576
1577
@defmac AC_REVISION (@var{revision-info})
1578
@acindex REVISION
1579
@cindex Revision
1580
Copy revision stamp @var{revision-info} into the @command{configure}
1581
script, with any dollar signs or double-quotes removed. This macro lets
1582
you put a revision stamp from @file{configure.ac} into @command{configure}
1583
without @sc{rcs} or @code{cvs} changing it when you check in
1584
@command{configure}. That way, you can determine easily which revision of
1585
@file{configure.ac} a particular @command{configure} corresponds to.
1586
1587
For example, this line in @file{configure.ac}:
1588
1589
@c The asis prevents RCS from changing the example in the manual.
1590
@example
1591
AC_REVISION($@asis{Revision: 1.30 }$)
1592
@end example
1593
1594
@noindent
1595
produces this in @command{configure}:
1596
1597
@example
1598
#! /bin/sh
1599
# From configure.ac Revision: 1.30
1600
@end example
1601
@end defmac
1602
1603
1604
@node Input
1605
@section Finding @command{configure} Input
1606
1607
1608
@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir})
1609
@acindex CONFIG_SRCDIR
1610
@var{unique-file-in-source-dir} is some file that is in the package's
1611
source directory; @command{configure} checks for this file's existence to
1612
make sure that the directory that it is told contains the source code in
1613
fact does. Occasionally people accidentally specify the wrong directory
1614
with @option{--srcdir}; this is a safety check. @xref{configure
1615
Invocation}, for more information.
1616
@end defmac
1617
1618
1619
@c FIXME: Remove definitively once --install explained.
1620
@c
1621
@c Small packages may store all their macros in @code{aclocal.m4}. As the
1622
@c set of macros grows, or for maintenance reasons, a maintainer may prefer
1623
@c to split the macros in several files. In this case, Autoconf must be
1624
@c told which files to load, and in which order.
1625
@c
1626
@c @defmac AC_INCLUDE (@var{file}@dots{})
1627
@c @acindex INCLUDE
1628
@c @c FIXME: There is no longer shell globbing.
1629
@c Read the macro definitions that appear in the listed files. A list of
1630
@c space-separated filenames or shell globbing patterns is expected. The
1631
@c files will be read in the order they're listed.
1632
@c
1633
@c Because the order of definition of macros is important (only the last
1634
@c definition of a macro is used), beware that it is @code{AC_INIT} that
1635
@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that
1636
@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within
1637
@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in
1638
@c the latter case, non-macro lines from included files may end up in the
1639
@c @file{configure} script, whereas in the former case, they'd be discarded
1640
@c just like any text that appear before @code{AC_INIT}.
1641
@c @end defmac
1642
1643
Packages that do manual configuration or use the @code{install} program
1644
might need to tell @command{configure} where to find some other shell
1645
scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places
1646
it looks are correct for most cases.
1647
1648
@defmac AC_CONFIG_AUX_DIR (@var{dir})
1649
@acindex CONFIG_AUX_DIR
1650
Use the auxiliary build tools (e.g., @file{install-sh},
1651
@file{config.sub}, @file{config.guess}, Cygnus @command{configure},
1652
Automake and Libtool scripts etc.) that are in directory @var{dir}.
1653
These are auxiliary files used in configuration. @var{dir} can be
1654
either absolute or relative to @file{@var{srcdir}}. The default is
1655
@file{@var{srcdir}} or @file{@var{srcdir}/..} or
1656
@file{@var{srcdir}/../..}, whichever is the first that contains
1657
@file{install-sh}. The other files are not checked for, so that using
1658
@code{AC_PROG_INSTALL} does not automatically require distributing the
1659
other auxiliary files. It checks for @file{install.sh} also, but that
1660
name is obsolete because some @command{make} have a rule that creates
1661
@file{install} from it if there is no @file{Makefile}.
1662
@end defmac
1663
1664
1665
@node Output
1666
@section Outputting Files
1667
1668
Every Autoconf script, e.g., @file{configure.ac}, should finish by
1669
calling @code{AC_OUTPUT}. It is the macro that generates
1670
@file{config.status}, which will create the @file{Makefile}s and any
1671
other files resulting from configuration. The only required macro is
1672
@code{AC_INIT} (@pxref{Input}).
1673
1674
@defmac AC_OUTPUT
1675
@acindex OUTPUT
1676
@cindex Instantiation
1677
Generate @file{config.status} and launch it. Call this macro once, at
1678
the end of @file{configure.ac}.
1679
1680
@file{config.status} will take all the configuration actions: all the
1681
output files (see @ref{Configuration Files}, macro
1682
@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers},
1683
macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration
1684
Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see
1685
@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories
1686
to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS})
1687
are honored.
1688
@end defmac
1689
1690
Historically, the usage of @code{AC_OUTPUT} was somewhat different.
1691
@xref{Obsolete Macros}, for a description of the arguments that
1692
@code{AC_OUTPUT} used to support.
1693
1694
1695
If you run @code{make} on subdirectories, you should run it using the
1696
@code{make} variable @code{MAKE}. Most versions of @code{make} set
1697
@code{MAKE} to the name of the @code{make} program plus any options it
1698
was given. (But many do not include in it the values of any variables
1699
set on the command line, so those are not passed on automatically.)
1700
Some old versions of @code{make} do not set this variable. The
1701
following macro allows you to use it even with those versions.
1702
1703
@defmac AC_PROG_MAKE_SET
1704
@acindex PROG_MAKE_SET
1705
@ovindex SET_MAKE
1706
If @code{make} predefines the variable @code{MAKE}, define output
1707
variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE}
1708
to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}.
1709
@end defmac
1710
1711
To use this macro, place a line like this in each @file{Makefile.in}
1712
that runs @code{MAKE} on other directories:
1713
1714
@example
1715
@@SET_MAKE@@
1716
@end example
1717
1718
1719
1720
@node Configuration Actions
1721
@section Taking Configuration Actions
1722
1723
@file{configure} is designed so that it appears to do everything itself,
1724
but there is actually a hidden slave: @file{config.status}.
1725
@file{configure} is in charge of examining your system, but it is
1726
@file{config.status} that actually takes the proper actions based on the
1727
results of @file{configure}. The most typical task of
1728
@file{config.status} is to @emph{instantiate} files.
1729
1730
This section describes the common behavior of the four standard
1731
instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS},
1732
@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all
1733
have this prototype:
1734
1735
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
1736
@c awful.
1737
@example
1738
AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}])
1739
@end example
1740
1741
@noindent
1742
where the arguments are:
1743
1744
@table @var
1745
@item @var{tag}@dots{}
1746
A whitespace-separated list of tags, which are typically the names of
1747
the files to instantiate.
1748
1749
You are encouraged to use literals as @var{tags}. In particular, you
1750
should avoid
1751
1752
@example
1753
@dots{} && my_foos="$my_foos fooo"
1754
@dots{} && my_foos="$my_foos foooo"
1755
AC_CONFIG_FOOS($my_foos)
1756
@end example
1757
1758
@noindent
1759
and use this instead:
1760
1761
@example
1762
@dots{} && AC_CONFIG_FOOS(fooo)
1763
@dots{} && AC_CONFIG_FOOS(foooo)
1764
@end example
1765
1766
The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use
1767
special @var{tag}s: they may have the form @samp{@var{output}} or
1768
@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated
1769
from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}).
1770
1771
For instance
1772
@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for
1773
the creation of @file{Makefile} that will be the expansion of the
1774
output variables in the concatenation of @file{boiler/top.mk} and
1775
@file{boiler/bot.mk}.
1776
1777
The special value @samp{-} might be used to denote the standard output
1778
when used in @var{output}, or the standard input when used in the
1779
@var{inputs}. You most probably don't need to use this in
1780
@file{configure.ac}, but it is convenient when using the command line
1781
interface of @file{./config.status}, see @ref{config.status Invocation},
1782
for more details.
1783
1784
The @var{inputs} may be absolute or relative filenames. In the latter
1785
case they are first looked for in the build tree, and then in the source
1786
tree.
1787
1788
@item commands
1789
Shell commands output literally into @file{config.status}, and
1790
associated with a tag that the user can use to tell @file{config.status}
1791
which the commands to run. The commands are run each time a @var{tag}
1792
request is given to @file{config.status}; typically, each time the file
1793
@file{@var{tag}} is created.
1794
1795
The variable set during the execution of @command{configure} are
1796
@emph{not} available here: you first need to set them via the
1797
@var{init-cmds}. Nonetheless the following variables are precomputed:
1798
1799
@table @code
1800
@item srcdir
1801
The path from the top build directory to the top source directory. This
1802
is what @command{configure}'s option @option{--srcdir} sets.
1803
1804
@item ac_top_srcdir
1805
The path from the current build directory to the top source directory.
1806
1807
1808
@item ac_top_builddir
1809
The path from the current build directory to the top build directory.
1810
It can be empty, or else ends with a slash, so that you may concatenate
1811
it.
1812
1813
@item ac_srcdir
1814
The path from the current build directory to the corresponding source
1815
directory.
1816
@end table
1817
1818
@noindent
1819
The @dfn{current} directory refers to the directory (or
1820
pseudo-directory) containing the input part of @var{tags}. For
1821
instance, running
1822
1823
@example
1824
AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}])
1825
@end example
1826
1827
@noindent
1828
with @option{--srcdir=../package} produces the following values:
1829
1830
@example
1831
# Argument of --srcdir
1832
srcdir='../package'
1833
# Reversing deep/dir
1834
ac_top_builddir='../../'
1835
# Concatenation of $ac_top_builddir and srcdir
1836
ac_top_srcdir='../../../package'
1837
# Concatenation of $ac_top_srcdir and deep/dir
1838
ac_srcdir='../../../package/deep/dir'
1839
@end example
1840
1841
@noindent
1842
independently of @samp{in/in.in}.
1843
1844
@item init-cmds
1845
Shell commands output @emph{unquoted} near the beginning of
1846
@file{config.status}, and executed each time @file{config.status} runs
1847
(regardless of the tag). Because they are unquoted, for example,
1848
@samp{$var} will be output as the value of @code{var}. @var{init-cmds}
1849
is typically used by @file{configure} to give @file{config.status} some
1850
variables it needs to run the @var{commands}.
1851
1852
You should be extremely cautious in your variable names: all the
1853
@var{init-cmds} share the same name space and may overwrite each other
1854
in unpredictable ways. Sorry@dots{}
1855
@end table
1856
1857
All these macros can be called multiple times, with different
1858
@var{tag}s, of course!
1859
1860
1861
@node Configuration Files
1862
@section Creating Configuration Files
1863
1864
Be sure to read the previous section, @ref{Configuration Actions}.
1865
1866
@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds})
1867
@acindex CONFIG_FILES
1868
Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input
1869
file (by default @file{@var{file}.in}), substituting the output variable
1870
values.
1871
@c Before we used to have this feature, which was later rejected
1872
@c because it complicates the write of Makefiles:
1873
@c If the file would be unchanged, it is left untouched, to preserve
1874
@c timestamp.
1875
This macro is one of the instantiating macros, see @ref{Configuration
1876
Actions}. @xref{Makefile Substitutions}, for more information on using
1877
output variables. @xref{Setting Output Variables}, for more information
1878
on creating them. This macro creates the directory that the file is in
1879
if it doesn't exist. Usually, @file{Makefile}s are created this way,
1880
but other files, such as @file{.gdbinit}, can be specified as well.
1881
1882
Typical calls to @code{AC_CONFIG_FILES} look like this:
1883
1884
@example
1885
AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile])
1886
AC_CONFIG_FILES([autoconf], [chmod +x autoconf])
1887
@end example
1888
1889
You can override an input file name by appending to @var{file} a
1890
colon-separated list of input files. Examples:
1891
1892
@example
1893
AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
1894
[lib/Makefile:boiler/lib.mk])
1895
@end example
1896
1897
@noindent
1898
Doing this allows you to keep your file names acceptable to MS-DOS, or
1899
to prepend and/or append boilerplate to the file.
1900
@end defmac
1901
1902
1903
1904
@node Makefile Substitutions
1905
@section Substitutions in Makefiles
1906
1907
Each subdirectory in a distribution that contains something to be
1908
compiled or installed should come with a file @file{Makefile.in}, from
1909
which @command{configure} will create a @file{Makefile} in that directory.
1910
To create a @file{Makefile}, @command{configure} performs a simple variable
1911
substitution, replacing occurrences of @samp{@@@var{variable}@@} in
1912
@file{Makefile.in} with the value that @command{configure} has determined
1913
for that variable. Variables that are substituted into output files in
1914
this way are called @dfn{output variables}. They are ordinary shell
1915
variables that are set in @command{configure}. To make @command{configure}
1916
substitute a particular variable into the output files, the macro
1917
@code{AC_SUBST} must be called with that variable name as an argument.
1918
Any occurrences of @samp{@@@var{variable}@@} for other variables are
1919
left unchanged. @xref{Setting Output Variables}, for more information
1920
on creating output variables with @code{AC_SUBST}.
1921
1922
A software package that uses a @command{configure} script should be
1923
distributed with a file @file{Makefile.in}, but no @file{Makefile}; that
1924
way, the user has to properly configure the package for the local system
1925
before compiling it.
1926
1927
@xref{Makefile Conventions,, Makefile Conventions, standards, The
1928
GNU Coding Standards}, for more information on what to put in
1929
@file{Makefile}s.
1930
1931
@menu
1932
* Preset Output Variables:: Output variables that are always set
1933
* Installation Directory Variables:: Other preset output variables
1934
* Build Directories:: Supporting multiple concurrent compiles
1935
* Automatic Remaking:: Makefile rules for configuring
1936
@end menu
1937
1938
@node Preset Output Variables
1939
@subsection Preset Output Variables
1940
1941
Some output variables are preset by the Autoconf macros. Some of the
1942
Autoconf macros set additional output variables, which are mentioned in
1943
the descriptions for those macros. @xref{Output Variable Index}, for a
1944
complete list of output variables. @xref{Installation Directory
1945
Variables}, for the list of the preset ones related to installation
1946
directories. Below are listed the other preset ones. They all are
1947
precious variables (@pxref{Setting Output Variables},
1948
@code{AC_ARG_VAR}).
1949
1950
@c Just say no to ASCII sorting! We're humans, not computers.
1951
@c These variables are listed as they would be in a dictionary:
1952
@c actor
1953
@c Actress
1954
@c actress
1955
1956
@defvar CFLAGS
1957
@ovindex CFLAGS
1958
Debugging and optimization options for the C compiler. If it is not set
1959
in the environment when @command{configure} runs, the default value is set
1960
when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure}
1961
uses this variable when compiling programs to test for C features.
1962
@end defvar
1963
1964
@defvar configure_input
1965
@ovindex configure_input
1966
A comment saying that the file was generated automatically by
1967
@command{configure} and giving the name of the input file.
1968
@code{AC_OUTPUT} adds a comment line containing this variable to the top
1969
of every @file{Makefile} it creates. For other files, you should
1970
reference this variable in a comment at the top of each input file. For
1971
example, an input shell script should begin like this:
1972
1973
@example
1974
#! /bin/sh
1975
# @@configure_input@@
1976
@end example
1977
1978
@noindent
1979
The presence of that line also reminds people editing the file that it
1980
needs to be processed by @command{configure} in order to be used.
1981
@end defvar
1982
1983
@defvar CPPFLAGS
1984
@ovindex CPPFLAGS
1985
Header file search directory (@option{-I@var{dir}}) and any other
1986
miscellaneous options for the C and C++ preprocessors and compilers. If
1987
it is not set in the environment when @command{configure} runs, the default
1988
value is empty. @command{configure} uses this variable when compiling or
1989
preprocessing programs to test for C and C++ features.
1990
@end defvar
1991
1992
@defvar CXXFLAGS
1993
@ovindex CXXFLAGS
1994
Debugging and optimization options for the C++ compiler. If it is not
1995
set in the environment when @command{configure} runs, the default value is
1996
set when you call @code{AC_PROG_CXX} (or empty if you don't).
1997
@command{configure} uses this variable when compiling programs to test for
1998
C++ features.
1999
@end defvar
2000
2001
@defvar DEFS
2002
@ovindex DEFS
2003
@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS}
2004
is called, @command{configure} replaces @samp{@@DEFS@@} with
2005
@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This
2006
variable is not defined while @command{configure} is performing its tests,
2007
only when creating the output files. @xref{Setting Output Variables}, for
2008
how to check the results of previous tests.
2009
@end defvar
2010
2011
@defvar ECHO_C
2012
@defvarx ECHO_N
2013
@defvarx ECHO_T
2014
@ovindex ECHO_C
2015
@ovindex ECHO_N
2016
@ovindex ECHO_T
2017
How does one suppress the trailing newline from @code{echo} for
2018
question-answer message pairs? These variables provide a way:
2019
2020
@example
2021
echo $ECHO_N "And the winner is... $ECHO_C"
2022
sleep 100000000000
2023
echo "$@{ECHO_T@}dead."
2024
@end example
2025
2026
@noindent
2027
Some old and uncommon @code{echo} implementations offer no means to
2028
achieve this, in which case @code{ECHO_T} is set to tab. You might not
2029
want to use it.
2030
@end defvar
2031
2032
@defvar FFLAGS
2033
@ovindex FFLAGS
2034
Debugging and optimization options for the Fortran 77 compiler. If it
2035
is not set in the environment when @command{configure} runs, the default
2036
value is set when you call @code{AC_PROG_F77} (or empty if you don't).
2037
@command{configure} uses this variable when compiling programs to test for
2038
Fortran 77 features.
2039
@end defvar
2040
2041
@defvar LDFLAGS
2042
@ovindex LDFLAGS
2043
Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous
2044
options for the linker. Don't use this variable to pass library names
2045
(@option{-l}) to the linker, use @code{LIBS} instead. If it is not set
2046
in the environment when @command{configure} runs, the default value is empty.
2047
@command{configure} uses this variable when linking programs to test for
2048
C, C++ and Fortran 77 features.
2049
@end defvar
2050
2051
@defvar LIBS
2052
@ovindex LIBS
2053
@option{-l} options to pass to the linker. The default value is empty,
2054
but some Autoconf macros may prepend extra libraries to this variable if
2055
those libraries are found and provide necessary functions, see
2056
@ref{Libraries}. @command{configure} uses this variable when linking
2057
programs to test for C, C++ and Fortran 77 features.
2058
@end defvar
2059
2060
@defvar builddir
2061
@ovindex builddir
2062
Rigorously equal to @samp{.}. Added for symmetry only.
2063
@end defvar
2064
2065
@defvar abs_builddir
2066
@ovindex abs_builddir
2067
Absolute path of @code{builddir}.
2068
@end defvar
2069
2070
@defvar top_builddir
2071
@ovindex top_builddir
2072
The relative path to the top-level of the current build tree. In the
2073
top-level directory, this is the same as @code{srcbuild}.
2074
@end defvar
2075
2076
@defvar abs_top_builddir
2077
@ovindex abs_top_builddir
2078
Absolute path of @code{top_builddir}.
2079
@end defvar
2080
2081
@defvar srcdir
2082
@ovindex srcdir
2083
The relative path to the directory that contains the source code for
2084
that @file{Makefile}.
2085
@end defvar
2086
2087
@defvar abs_srcdir
2088
@ovindex abs_srcdir
2089
Absolute path of @code{srcdir}.
2090
@end defvar
2091
2092
@defvar top_srcdir
2093
@ovindex top_srcdir
2094
The relative path to the top-level source code directory for the
2095
package. In the top-level directory, this is the same as @code{srcdir}.
2096
@end defvar
2097
2098
@defvar abs_top_srcdir
2099
@ovindex abs_top_srcdir
2100
Absolute path of @code{top_srcdir}.
2101
@end defvar
2102
2103
@node Installation Directory Variables
2104
@subsection Installation Directory Variables
2105
2106
The following variables specify the directories where the package will
2107
be installed, see @ref{Directory Variables,, Variables for Installation
2108
Directories, standards, The GNU Coding Standards}, for more information.
2109
See the end of this section for details on when and how to use these
2110
variables.
2111
2112
@defvar bindir
2113
@ovindex bindir
2114
The directory for installing executables that users run.
2115
@end defvar
2116
2117
@defvar datadir
2118
@ovindex datadir
2119
The directory for installing read-only architecture-independent data.
2120
@end defvar
2121
2122
@defvar exec_prefix
2123
@ovindex exec_prefix
2124
The installation prefix for architecture-dependent files. By default
2125
it's the same as @var{prefix}. You should avoid installing anything
2126
directly to @var{exec_prefix}. However, the default value for
2127
directories containing architecture-dependent files should be relative
2128
to @var{exec_prefix}.
2129
@end defvar
2130
2131
@defvar includedir
2132
@ovindex includedir
2133
The directory for installing C header files.
2134
@end defvar
2135
2136
@defvar infodir
2137
@ovindex infodir
2138
The directory for installing documentation in Info format.
2139
@end defvar
2140
2141
@defvar libdir
2142
@ovindex libdir
2143
The directory for installing object code libraries.
2144
@end defvar
2145
2146
@defvar libexecdir
2147
@ovindex libexecdir
2148
The directory for installing executables that other programs run.
2149
@end defvar
2150
2151
@defvar localstatedir
2152
@ovindex localstatedir
2153
The directory for installing modifiable single-machine data.
2154
@end defvar
2155
2156
@defvar mandir
2157
@ovindex mandir
2158
The top-level directory for installing documentation in man format.
2159
@end defvar
2160
2161
@defvar oldincludedir
2162
@ovindex oldincludedir
2163
The directory for installing C header files for non-gcc compilers.
2164
@end defvar
2165
2166
@defvar prefix
2167
@ovindex prefix
2168
The common installation prefix for all files. If @var{exec_prefix}
2169
is defined to a different value, @var{prefix} is used only for
2170
architecture-independent files.
2171
@end defvar
2172
2173
@defvar sbindir
2174
@ovindex sbindir
2175
The directory for installing executables that system
2176
administrators run.
2177
@end defvar
2178
2179
@defvar sharedstatedir
2180
@ovindex sharedstatedir
2181
The directory for installing modifiable architecture-independent data.
2182
@end defvar
2183
2184
@defvar sysconfdir
2185
@ovindex sysconfdir
2186
The directory for installing read-only single-machine data.
2187
@end defvar
2188
2189
2190
Most of these variables have values that rely on @code{prefix} or
2191
@code{exec_prefix}. It is deliberate that the directory output
2192
variables keep them unexpanded: typically @samp{@@datadir@@} will be
2193
replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}.
2194
2195
This behavior is mandated by the @sc{gnu} coding standards, so that when
2196
the user runs:
2197
2198
@table @samp
2199
@item make
2200
she can still specify a different prefix from the one specified to
2201
@command{configure}, in which case, if needed, the package shall hard
2202
code dependencies corresponding to the make-specified prefix.
2203
2204
@item make install
2205
she can specify a different installation location, in which case the
2206
package @emph{must} still depend on the location which was compiled in
2207
(i.e., never recompile when @samp{make install} is run). This is an
2208
extremely important feature, as many people may decide to install all
2209
the files of a package grouped together, and then install links from
2210
the final locations to there.
2211
@end table
2212
2213
In order to support these features, it is essential that @code{datadir}
2214
remains being defined as @samp{$@{prefix@}/share} to depend upon the
2215
current value of @code{prefix}.
2216
2217
A corollary is that you should not use these variables except in
2218
Makefiles. For instance, instead of trying to evaluate @code{datadir}
2219
in @file{configure} and hardcoding it in Makefiles using
2220
e.g. @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add
2221
@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}.
2222
2223
Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace
2224
@code{datadir} and friends in your shell scripts and other files, rather
2225
let @command{make} manage their replacement. For instance Autoconf
2226
ships templates of its shell scripts ending with @samp{.sh}, and uses
2227
this Makefile snippet:
2228
2229
@example
2230
.sh:
2231
rm -f $@@ $@@.tmp
2232
sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp
2233
chmod +x $@@.tmp
2234
mv $@@.tmp $@@
2235
@end example
2236
2237
Three things are noteworthy:
2238
2239
@table @samp
2240
@item @@datadir\@@
2241
The backslash prevents @command{configure} from replacing
2242
@samp{@@datadir@@} in the sed expression itself.
2243
2244
@item $(pkgdatadir)
2245
Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable
2246
instead.
2247
2248
@item ,
2249
Don't use @samp{/} in the sed expression(s) since most probably the
2250
variables you use, such as @samp{$(pkgdatadir)}, will contain
2251
some.
2252
@end table
2253
2254
2255
@node Build Directories
2256
@subsection Build Directories
2257
2258
You can support compiling a software package for several architectures
2259
simultaneously from the same copy of the source code. The object files
2260
for each architecture are kept in their own directory.
2261
2262
To support doing this, @code{make} uses the @code{VPATH} variable to
2263
find the files that are in the source directory. @sc{gnu} @code{make}
2264
and most other recent @code{make} programs can do this. Older
2265
@code{make} programs do not support @code{VPATH}; when using them, the
2266
source code must be in the same directory as the object files.
2267
2268
To support @code{VPATH}, each @file{Makefile.in} should contain two
2269
lines that look like:
2270
2271
@example
2272
srcdir = @@srcdir@@
2273
VPATH = @@srcdir@@
2274
@end example
2275
2276
Do not set @code{VPATH} to the value of another variable, for example
2277
@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do
2278
variable substitutions on the value of @code{VPATH}.
2279
2280
@command{configure} substitutes in the correct value for @code{srcdir} when
2281
it produces @file{Makefile}.
2282
2283
Do not use the @code{make} variable @code{$<}, which expands to the
2284
file name of the file in the source directory (found with @code{VPATH}),
2285
except in implicit rules. (An implicit rule is one such as @samp{.c.o},
2286
which tells how to create a @file{.o} file from a @file{.c} file.) Some
2287
versions of @code{make} do not set @code{$<} in explicit rules; they
2288
expand it to an empty value.
2289
2290
Instead, @file{Makefile} command lines should always refer to source
2291
files by prefixing them with @samp{$(srcdir)/}. For example:
2292
2293
@example
2294
time.info: time.texinfo
2295
$(MAKEINFO) $(srcdir)/time.texinfo
2296
@end example
2297
2298
@node Automatic Remaking
2299
@subsection Automatic Remaking
2300
2301
You can put rules like the following in the top-level @file{Makefile.in}
2302
for a package to automatically update the configuration information when
2303
you change the configuration files. This example includes all of the
2304
optional files, such as @file{aclocal.m4} and those related to
2305
configuration header files. Omit from the @file{Makefile.in} rules for
2306
any of these files that your package does not use.
2307
2308
The @samp{$(srcdir)/} prefix is included because of limitations in the
2309
@code{VPATH} mechanism.
2310
2311
The @file{stamp-} files are necessary because the timestamps of
2312
@file{config.h.in} and @file{config.h} will not be changed if remaking
2313
them does not change their contents. This feature avoids unnecessary
2314
recompilation. You should include the file @file{stamp-h.in} your
2315
package's distribution, so @command{make} will consider
2316
@file{config.h.in} up to date. Don't use @command{touch}
2317
(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using
2318
@command{date} would cause needless differences, hence @sc{cvs}
2319
conflicts etc.).
2320
2321
@example
2322
@group
2323
$(srcdir)/configure: configure.ac aclocal.m4
2324
cd $(srcdir) && autoconf
2325
2326
# autoheader might not change config.h.in, so touch a stamp file.
2327
$(srcdir)/config.h.in: stamp-h.in
2328
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
2329
cd $(srcdir) && autoheader
2330
echo timestamp > $(srcdir)/stamp-h.in
2331
2332
config.h: stamp-h
2333
stamp-h: config.h.in config.status
2334
./config.status
2335
2336
Makefile: Makefile.in config.status
2337
./config.status
2338
2339
config.status: configure
2340
./config.status --recheck
2341
@end group
2342
@end example
2343
2344
@noindent
2345
(Be careful if you copy these lines directly into your Makefile, as you
2346
will need to convert the indented lines to start with the tab character.)
2347
2348
In addition, you should use @samp{AC_CONFIG_FILES([stamp-h], [echo
2349
timestamp > stamp-h])} so @file{config.status} will ensure that
2350
@file{config.h} is considered up to date. @xref{Output}, for more
2351
information about @code{AC_OUTPUT}.
2352
2353
@xref{config.status Invocation}, for more examples of handling
2354
configuration-related dependencies.
2355
2356
@node Configuration Headers
2357
@section Configuration Header Files
2358
@cindex Configuration Header
2359
@cindex @file{config.h}
2360
2361
When a package tests more than a few C preprocessor symbols, the command
2362
lines to pass @option{-D} options to the compiler can get quite long.
2363
This causes two problems. One is that the @code{make} output is hard to
2364
visually scan for errors. More seriously, the command lines can exceed
2365
the length limits of some operating systems. As an alternative to
2366
passing @option{-D} options to the compiler, @command{configure} scripts can
2367
create a C header file containing @samp{#define} directives. The
2368
@code{AC_CONFIG_HEADERS} macro selects this kind of output. It should
2369
be called right after @code{AC_INIT}.
2370
2371
The package should @samp{#include} the configuration header file before
2372
any other header files, to prevent inconsistencies in declarations (for
2373
example, if it redefines @code{const}). Use @samp{#include <config.h>}
2374
instead of @samp{#include "config.h"}, and pass the C compiler a
2375
@option{-I.} option (or @option{-I..}; whichever directory contains
2376
@file{config.h}). That way, even if the source directory is configured
2377
itself (perhaps to make a distribution), other build directories can
2378
also be configured without finding the @file{config.h} from the source
2379
directory.
2380
2381
@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds})
2382
@acindex CONFIG_HEADERS
2383
@cvindex HAVE_CONFIG_H
2384
This macro is one of the instantiating macros, see @ref{Configuration
2385
Actions}. Make @code{AC_OUTPUT} create the file(s) in the
2386
whitespace-separated list @var{header} containing C preprocessor
2387
@code{#define} statements, and replace @samp{@@DEFS@@} in generated
2388
files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}.
2389
The usual name for @var{header} is @file{config.h}.
2390
2391
If @var{header} already exists and its contents are identical to what
2392
@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows
2393
some changes in configuration without needlessly causing object files
2394
that depend on the header file to be recompiled.
2395
2396
Usually the input file is named @file{@var{header}.in}; however, you can
2397
override the input file name by appending to @var{header}, a
2398
colon-separated list of input files. Examples:
2399
2400
@example
2401
AC_CONFIG_HEADERS([config.h:config.hin])
2402
AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post])
2403
@end example
2404
2405
@noindent
2406
Doing this allows you to keep your file names acceptable to MS-DOS, or
2407
to prepend and/or append boilerplate to the file.
2408
@end defmac
2409
2410
@xref{Configuration Actions}, for more details on @var{header}.
2411
2412
@menu
2413
* Header Templates:: Input for the configuration headers
2414
* autoheader Invocation:: How to create configuration templates
2415
* Autoheader Macros:: How to specify CPP templates
2416
@end menu
2417
2418
@node Header Templates
2419
@subsection Configuration Header Templates
2420
@cindex Configuration Header Template
2421
@cindex @file{config.h.in}
2422
2423
Your distribution should contain a template file that looks as you want
2424
the final header file to look, including comments, with @code{#undef}
2425
statements which are used as hooks. For example, suppose your
2426
@file{configure.ac} makes these calls:
2427
2428
@example
2429
AC_CONFIG_HEADERS([conf.h])
2430
AC_CHECK_HEADERS([unistd.h])
2431
@end example
2432
2433
@noindent
2434
Then you could have code like the following in @file{conf.h.in}. On
2435
systems that have @file{unistd.h}, @command{configure} will @samp{#define}
2436
@samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be
2437
commented out (in case the system predefines that symbol).
2438
2439
@example
2440
@group
2441
/* Define as 1 if you have unistd.h. */
2442
#undef HAVE_UNISTD_H
2443
@end group
2444
@end example
2445
2446
You can then decode the configuration header using the preprocessor
2447
directives:
2448
2449
@example
2450
@group
2451
#include <conf.h>
2452
2453
#if HAVE_UNISTD_H
2454
# include <unistd.h>
2455
#else
2456
/* We are in trouble. */
2457
#endif
2458
@end group
2459
@end example
2460
2461
The use of old form templates, with @samp{#define} instead of
2462
@samp{#undef} is strongly discouraged.
2463
2464
Since it is a tedious task to keep a template header up to date, you may
2465
use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
2466
2467
2468
@node autoheader Invocation
2469
@subsection Using @command{autoheader} to Create @file{config.h.in}
2470
@cindex @command{autoheader}
2471
2472
The @command{autoheader} program can create a template file of C
2473
@samp{#define} statements for @command{configure} to use. If
2474
@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})},
2475
@command{autoheader} creates @file{@var{file}.in}; if multiple file
2476
arguments are given, the first one is used. Otherwise,
2477
@command{autoheader} creates @file{config.h.in}.
2478
2479
In order to do its job, @command{autoheader} needs you to document all
2480
of the symbols that you might use; i.e., there must be at least one
2481
@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third
2482
argument for each symbol (@pxref{Defining Symbols}). An additional
2483
constraint is that the first argument of @code{AC_DEFINE} must be a
2484
literal. Note that all symbols defined by Autoconf's built-in tests are
2485
already documented properly; you only need to document those that you
2486
define yourself.
2487
2488
You might wonder why @command{autoheader} is needed: after all, why
2489
would @command{configure} need to ``patch'' a @file{config.h.in} to
2490
produce a @file{config.h} instead of just creating @file{config.h} from
2491
scratch? Well, when everything rocks, the answer is just that we are
2492
wasting our time maintaining @command{autoheader}: generating
2493
@file{config.h} directly is all that is needed. When things go wrong,
2494
however, you'll be thankful for the existence of @command{autoheader}.
2495
2496
The fact that the symbols are documented is important in order to
2497
@emph{check} that @file{config.h} makes sense. The fact that there is a
2498
well defined list of symbols that should be @code{#define}'d (or not) is
2499
also important for people who are porting packages to environments where
2500
@command{configure} cannot be run: they just have to @emph{fill in the
2501
blanks}.
2502
2503
But let's come back to the point: @command{autoheader}'s invocation@dots{}
2504
2505
If you give @command{autoheader} an argument, it uses that file instead
2506
of @file{configure.ac} and writes the header file to the standard output
2507
instead of to @file{config.h.in}. If you give @command{autoheader} an
2508
argument of @option{-}, it reads the standard input instead of
2509
@file{configure.ac} and writes the header file to the standard output.
2510
2511
@command{autoheader} accepts the following options:
2512
2513
@table @option
2514
@item --help
2515
@itemx -h
2516
Print a summary of the command line options and exit.
2517
2518
@item --version
2519
@itemx -V
2520
Print the version number of Autoconf and exit.
2521
2522
@item --verbose
2523
@itemx -v
2524
Report processing steps.
2525
2526
@item --debug
2527
@itemx -d
2528
Don't remove the temporary files.
2529
2530
@item --force
2531
@itemx -f
2532
Remake the template file even if newer than its input files.
2533
2534
@item --include=@var{dir}
2535
@itemx -I @var{dir}
2536
Also look for input files in @var{dir}. Multiple invocations accumulate.
2537
Directories are browsed from last to first.
2538
2539
@item --warnings=@var{category}
2540
@itemx -W @var{category}
2541
@evindex WARNINGS
2542
Report the warnings related to @var{category} (which can actually be a
2543
comma separated list). Current categories include:
2544
2545
@table @samp
2546
@item obsolete
2547
report the uses of obsolete constructs
2548
2549
@item all
2550
report all the warnings
2551
2552
@item none
2553
report none
2554
2555
@item error
2556
treats warnings as errors
2557
2558
@item no-@var{category}
2559
disable warnings falling into @var{category}
2560
@end table
2561
2562
@end table
2563
2564
2565
2566
@node Autoheader Macros
2567
@subsection Autoheader Macros
2568
2569
@command{autoheader} scans @file{configure.ac} and figures out which C
2570
preprocessor symbols it might define. It knows how to generate
2571
templates for symbols defined by @code{AC_CHECK_HEADERS},
2572
@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional
2573
symbol, you must define a template for it. If there are missing
2574
templates, @command{autoheader} fails with an error message.
2575
2576
The simplest way to create a template for a @var{symbol} is to supply
2577
the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see
2578
@ref{Defining Symbols}. You may also use one of the following macros.
2579
2580
@defmac AH_VERBATIM (@var{key}, @var{template})
2581
@acindex AH_VERBATIM
2582
@acindex VERBATIM
2583
Tell @command{autoheader} to include the @var{template} as-is in the header
2584
template file. This @var{template} is associated with the @var{key},
2585
which is used to sort all the different templates and guarantee their
2586
uniqueness. It should be the symbol that can be @code{AC_DEFINE}'d.
2587
2588
For example:
2589
2590
@example
2591
AH_VERBATIM([_GNU_SOURCE],
2592
[/* Enable GNU extensions on systems that have them. */
2593
#ifndef _GNU_SOURCE
2594
# define _GNU_SOURCE
2595
#endif])
2596
@end example
2597
@end defmac
2598
2599
2600
@defmac AH_TEMPLATE (@var{key}, @var{description})
2601
@acindex AH_TEMPLATE
2602
@acindex TEMPLATE
2603
Tell @command{autoheader} to generate a template for @var{key}. This macro
2604
generates standard templates just like @code{AC_DEFINE} when a
2605
@var{description} is given.
2606
2607
For example:
2608
2609
@example
2610
AH_TEMPLATE([CRAY_STACKSEG_END],
2611
[Define to one of _getb67, GETB67, getb67
2612
for Cray-2 and Cray-YMP systems. This
2613
function is required for alloca.c support
2614
on those systems.])
2615
@end example
2616
2617
@noindent
2618
will generate the following template, with the description properly
2619
justified.
2620
2621
@example
2622
/* Define to one of _getb67, GETB67, getb67 for Cray-2 and
2623
Cray-YMP systems. This function is required for alloca.c
2624
support on those systems. */
2625
#undef CRAY_STACKSEG_END
2626
@end example
2627
@end defmac
2628
2629
2630
@defmac AH_TOP (@var{text})
2631
@acindex AH_TOP
2632
@acindex TOP
2633
Include @var{text} at the top of the header template file.
2634
@end defmac
2635
2636
2637
@defmac AH_BOTTOM (@var{text})
2638
@acindex AH_BOTTOM
2639
@acindex BOTTOM
2640
Include @var{text} at the bottom of the header template file.
2641
@end defmac
2642
2643
2644
@node Configuration Commands
2645
@section Running Arbitrary Configuration Commands
2646
2647
You execute arbitrary commands either before, during and after
2648
@file{config.status} is run. The three following macros accumulate the
2649
commands to run when they are called multiple times.
2650
@code{AC_CONFIG_COMMANDS} replaces the obsolete macro
2651
@code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details.
2652
2653
@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2654
@acindex CONFIG_COMMANDS
2655
Specify additional shell commands to run at the end of
2656
@file{config.status}, and shell commands to initialize any variables
2657
from @command{configure}. Associate the commands to the @var{tag}. Since
2658
typically the @var{cmds} create a file, @var{tag} should naturally be
2659
the name of that file. This macro is one of the instantiating macros,
2660
see @ref{Configuration Actions}.
2661
2662
Here is an unrealistic example:
2663
@example
2664
fubar=42
2665
AC_CONFIG_COMMANDS([fubar],
2666
[echo this is extra $fubar, and so on.],
2667
[fubar=$fubar])
2668
@end example
2669
2670
Here is a better one:
2671
@example
2672
AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp])
2673
@end example
2674
@end defmac
2675
2676
@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
2677
@acindex OUTPUT_COMMANDS_PRE
2678
Execute the @var{cmds} right before creating @file{config.status}. A
2679
typical use is computing values derived from variables built during the
2680
execution of @command{configure}:
2681
2682
@example
2683
AC_CONFIG_COMMANDS_PRE(
2684
[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'`
2685
AC_SUBST(LTLIBOBJS)])
2686
@end example
2687
@end defmac
2688
2689
@defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
2690
@acindex OUTPUT_COMMANDS_POST
2691
Execute the @var{cmds} right after creating @file{config.status}.
2692
@end defmac
2693
2694
2695
2696
2697
@node Configuration Links
2698
@section Creating Configuration Links
2699
2700
You may find it convenient to create links whose destinations depend upon
2701
results of tests. One can use @code{AC_CONFIG_COMMANDS} but the
2702
creation of relative symbolic links can be delicate when the package is
2703
built in another directory than its sources.
2704
2705
@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds})
2706
@acindex CONFIG_LINKS
2707
@cindex Links
2708
Make @code{AC_OUTPUT} link each of the existing files @var{source} to
2709
the corresponding link name @var{dest}. Makes a symbolic link if
2710
possible, otherwise a hard link. The @var{dest} and @var{source} names
2711
should be relative to the top level source or build directory. This
2712
macro is one of the instantiating macros, see @ref{Configuration
2713
Actions}.
2714
2715
For example, this call:
2716
2717
@example
2718
AC_CONFIG_LINKS(host.h:config/$machine.h
2719
object.h:config/$obj_format.h)
2720
@end example
2721
2722
@noindent
2723
creates in the current directory @file{host.h} as a link to
2724
@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a
2725
link to @file{@var{srcdir}/config/$obj_format.h}.
2726
2727
The tempting value @samp{.} for @var{dest} is invalid: it makes it
2728
impossible for @samp{config.status} to guess the links to establish.
2729
2730
One can then run:
2731
@example
2732
./config.status host.h object.h
2733
@end example
2734
@noindent
2735
to create the links.
2736
@end defmac
2737
2738
2739
2740
@node Subdirectories
2741
@section Configuring Other Packages in Subdirectories
2742
2743
In most situations, calling @code{AC_OUTPUT} is sufficient to produce
2744
@file{Makefile}s in subdirectories. However, @command{configure} scripts
2745
that control more than one independent package can use
2746
@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other
2747
packages in subdirectories.
2748
2749
@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{})
2750
@acindex CONFIG_SUBDIRS
2751
@ovindex subdirs
2752
Make @code{AC_OUTPUT} run @command{configure} in each subdirectory
2753
@var{dir} in the given whitespace-separated list. Each @var{dir} should
2754
be a literal, i.e., please do not use:
2755
2756
@example
2757
if test "$package_foo_enabled" = yes; then
2758
$my_subdirs="$my_subdirs foo"
2759
fi
2760
AC_CONFIG_SUBDIRS($my_subdirs)
2761
@end example
2762
2763
@noindent
2764
because this prevents @samp{./configure --help=recursive} from
2765
displaying the options of the package @code{foo}. Rather, you should
2766
write:
2767
2768
@example
2769
if test "$package_foo_enabled" = yes; then
2770
AC_CONFIG_SUBDIRS(foo)
2771
fi
2772
@end example
2773
2774
If a given @var{dir} is not found, an error is reported: if the
2775
subdirectory is optional, write:
2776
2777
@example
2778
if test -d $srcdir/foo; then
2779
AC_CONFIG_SUBDIRS(foo)
2780
fi
2781
@end example
2782
2783
If a given @var{dir} contains @command{configure.gnu}, it is run instead
2784
of @command{configure}. This is for packages that might use a
2785
non-autoconf script @command{Configure}, which can't be called through a
2786
wrapper @command{configure} since it would be the same file on
2787
case-insensitive filesystems. Likewise, if a @var{dir} contains
2788
@file{configure.ac} but no @command{configure}, the Cygnus
2789
@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used.
2790
2791
The subdirectory @command{configure} scripts are given the same command
2792
line options that were given to this @command{configure} script, with minor
2793
changes if needed, which include:
2794
2795
@itemize @minus
2796
@item
2797
adjusting a relative path for the cache file;
2798
2799
@item
2800
adjusting a relative path for the source directory;
2801
2802
@item
2803
propagating the current value of @code{$prefix}, including if it was
2804
defaulted, and if default values of the top level and of sub directory
2805
@file{configure} differ.
2806
@end itemize
2807
2808
This macro also sets the output variable @code{subdirs} to the list of
2809
directories @samp{@var{dir} @dots{}}. @file{Makefile} rules can use
2810
this variable to determine which subdirectories to recurse into. This
2811
macro may be called multiple times.
2812
@end defmac
2813
2814
@node Default Prefix
2815
@section Default Prefix
2816
2817
By default, @command{configure} sets the prefix for files it installs to
2818
@file{/usr/local}. The user of @command{configure} can select a different
2819
prefix using the @option{--prefix} and @option{--exec-prefix} options.
2820
There are two ways to change the default: when creating
2821
@command{configure}, and when running it.
2822
2823
Some software packages might want to install in a directory besides
2824
@file{/usr/local} by default. To accomplish that, use the
2825
@code{AC_PREFIX_DEFAULT} macro.
2826
2827
@defmac AC_PREFIX_DEFAULT (@var{prefix})
2828
@acindex PREFIX_DEFAULT
2829
Set the default installation prefix to @var{prefix} instead of
2830
@file{/usr/local}.
2831
@end defmac
2832
2833
It may be convenient for users to have @command{configure} guess the
2834
installation prefix from the location of a related program that they
2835
have already installed. If you wish to do that, you can call
2836
@code{AC_PREFIX_PROGRAM}.
2837
2838
@defmac AC_PREFIX_PROGRAM (@var{program})
2839
@acindex PREFIX_PROGRAM
2840
If the user did not specify an installation prefix (using the
2841
@option{--prefix} option), guess a value for it by looking for
2842
@var{program} in @code{PATH}, the way the shell does. If @var{program}
2843
is found, set the prefix to the parent of the directory containing
2844
@var{program}; otherwise leave the prefix specified in
2845
@file{Makefile.in} unchanged. For example, if @var{program} is
2846
@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc},
2847
set the prefix to @file{/usr/local/gnu}.
2848
@end defmac
2849
2850
2851
2852
@c ======================================================== Existing tests
2853
2854
@node Existing Tests
2855
@chapter Existing Tests
2856
2857
These macros test for particular system features that packages might
2858
need or want to use. If you need to test for a kind of feature that
2859
none of these macros check for, you can probably do it by calling
2860
primitive test macros with appropriate arguments (@pxref{Writing
2861
Tests}).
2862
2863
These tests print messages telling the user which feature they're
2864
checking for, and what they find. They cache their results for future
2865
@command{configure} runs (@pxref{Caching Results}).
2866
2867
Some of these macros set output variables. @xref{Makefile
2868
Substitutions}, for how to get their values. The phrase ``define
2869
@var{name}'' is used below as a shorthand to mean ``define C
2870
preprocessor symbol @var{name} to the value 1''. @xref{Defining
2871
Symbols}, for how to get those symbol definitions into your program.
2872
2873
@menu
2874
* Common Behavior:: Macros' standard schemes
2875
* Alternative Programs:: Selecting between alternative programs
2876
* Files:: Checking for the existence of files
2877
* Libraries:: Library archives that might be missing
2878
* Library Functions:: C library functions that might be missing
2879
* Header Files:: Header files that might be missing
2880
* Declarations:: Declarations that may be missing
2881
* Structures:: Structures or members that might be missing
2882
* Types:: Types that might be missing
2883
* Compilers and Preprocessors:: Checking for compiling programs
2884
* System Services:: Operating system services
2885
* UNIX Variants:: Special kludges for specific UNIX variants
2886
@end menu
2887
2888
@node Common Behavior
2889
@section Common Behavior
2890
2891
Much effort has been expended to make Autoconf easy to learn. The most
2892
obvious way to reach this goal is simply to enforce standard interfaces
2893
and behaviors, avoiding exceptions as much as possible. Because of
2894
history and inertia, unfortunately, there are still too many exceptions
2895
in Autoconf; nevertheless, this section describes some of the common
2896
rules.
2897
2898
@menu
2899
* Standard Symbols:: Symbols defined by the macros
2900
* Default Includes:: Includes used by the generic macros
2901
@end menu
2902
2903
@node Standard Symbols
2904
@subsection Standard Symbols
2905
2906
All the generic macros that @code{AC_DEFINE} a symbol as a result of
2907
their test transform their @var{argument}s to a standard alphabet.
2908
First, @var{argument} is converted to upper case and any asterisks
2909
(@samp{*}) are each converted to @samp{P}. Any remaining characters
2910
that are not alphanumeric are converted to underscores.
2911
2912
For instance,
2913
2914
@example
2915
AC_CHECK_TYPES(struct $Expensive*)
2916
@end example
2917
2918
@noindent
2919
will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check
2920
succeeds.
2921
2922
2923
@node Default Includes
2924
@subsection Default Includes
2925
@cindex Includes, default
2926
2927
Several tests depend upon a set of header files. Since these headers
2928
are not universally available, tests actually have to provide a set of
2929
protected includes, such as:
2930
2931
@example
2932
@group
2933
#if TIME_WITH_SYS_TIME
2934
# include <sys/time.h>
2935
# include <time.h>
2936
#else
2937
# if HAVE_SYS_TIME_H
2938
# include <sys/time.h>
2939
# else
2940
# include <time.h>
2941
# endif
2942
#endif
2943
@end group
2944
@end example
2945
2946
@noindent
2947
Unless you know exactly what you are doing, you should avoid using
2948
unconditional includes, and check the existence of the headers you
2949
include beforehand (@pxref{Header Files}).
2950
2951
Most generic macros provide the following default set of includes:
2952
2953
@example
2954
@group
2955
#include <stdio.h>
2956
#if HAVE_SYS_TYPES_H
2957
# include <sys/types.h>
2958
#endif
2959
#if HAVE_SYS_STAT_H
2960
# include <sys/stat.h>
2961
#endif
2962
#if STDC_HEADERS
2963
# include <stdlib.h>
2964
# include <stddef.h>
2965
#else
2966
# if HAVE_STDLIB_H
2967
# include <stdlib.h>
2968
# endif
2969
#endif
2970
#if HAVE_STRING_H
2971
# if !STDC_HEADERS && HAVE_MEMORY_H
2972
# include <memory.h>
2973
# endif
2974
# include <string.h>
2975
#endif
2976
#if HAVE_STRINGS_H
2977
# include <strings.h>
2978
#endif
2979
#if HAVE_INTTYPES_H
2980
# include <inttypes.h>
2981
#else
2982
# if HAVE_STDINT_H
2983
# include <stdint.h>
2984
# endif
2985
#endif
2986
#if HAVE_UNISTD_H
2987
# include <unistd.h>
2988
#endif
2989
@end group
2990
@end example
2991
2992
If the default includes are used, then Autoconf will automatically check
2993
for the presence of these headers and their compatibility, i.e., you
2994
don't need to run @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h}
2995
etc.
2996
2997
These headers are checked for in the same order as they are included.
2998
For instance, on some systems @file{string.h} and @file{strings.h} both
2999
exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but
3000
@code{HAVE_STRINGS_H} won't.
3001
3002
@node Alternative Programs
3003
@section Alternative Programs
3004
@cindex Programs, checking
3005
3006
These macros check for the presence or behavior of particular programs.
3007
They are used to choose between several alternative programs and to
3008
decide what to do once one has been chosen. If there is no macro
3009
specifically defined to check for a program you need, and you don't need
3010
to check for any special properties of it, then you can use one of the
3011
general program-check macros.
3012
3013
@menu
3014
* Particular Programs:: Special handling to find certain programs
3015
* Generic Programs:: How to find other programs
3016
@end menu
3017
3018
@node Particular Programs
3019
@subsection Particular Program Checks
3020
3021
These macros check for particular programs---whether they exist, and
3022
in some cases whether they support certain features.
3023
3024
@defmac AC_PROG_AWK
3025
@acindex PROG_AWK
3026
@ovindex AWK
3027
Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
3028
order, and set output variable @code{AWK} to the first one that is found.
3029
It tries @code{gawk} first because that is reported to be the
3030
best implementation.
3031
@end defmac
3032
3033
3034
@defmac AC_PROG_INSTALL
3035
@acindex PROG_INSTALL
3036
@ovindex INSTALL
3037
@ovindex INSTALL_PROGRAM
3038
@ovindex INSTALL_DATA
3039
@ovindex INSTALL_SCRIPT
3040
Set output variable @code{INSTALL} to the path of a @sc{bsd} compatible
3041
@code{install} program, if one is found in the current @code{PATH}.
3042
Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c},
3043
checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its
3044
default directories) to determine @var{dir} (@pxref{Output}). Also set
3045
the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to
3046
@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}.
3047
3048
This macro screens out various instances of @code{install} known not to
3049
work. It prefers to find a C program rather than a shell script, for
3050
speed. Instead of @file{install-sh}, it can also use @file{install.sh},
3051
but that name is obsolete because some @code{make} programs have a rule
3052
that creates @file{install} from it if there is no @file{Makefile}.
3053
3054
Autoconf comes with a copy of @file{install-sh} that you can use. If
3055
you use @code{AC_PROG_INSTALL}, you must include either
3056
@file{install-sh} or @file{install.sh} in your distribution, or
3057
@command{configure} will produce an error message saying it can't find
3058
them---even if the system you're on has a good @code{install} program.
3059
This check is a safety measure to prevent you from accidentally leaving
3060
that file out, which would prevent your package from installing on
3061
systems that don't have a @sc{bsd}-compatible @code{install} program.
3062
3063
If you need to use your own installation program because it has features
3064
not found in standard @code{install} programs, there is no reason to use
3065
@code{AC_PROG_INSTALL}; just put the file name of your program into your
3066
@file{Makefile.in} files.
3067
@end defmac
3068
3069
@defmac AC_PROG_LEX
3070
@acindex PROG_LEX
3071
@ovindex LEX
3072
@ovindex LEXLIB
3073
@cvindex YYTEXT_POINTER
3074
@ovindex LEX_OUTPUT_ROOT
3075
If @code{flex} is found, set output variable @code{LEX} to @samp{flex}
3076
and @code{LEXLIB} to @option{-lfl}, if that library is in a standard
3077
place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to
3078
@option{-ll}.
3079
3080
Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead
3081
of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to
3082
the base of the file name that the lexer generates; usually
3083
@file{lex.yy}, but sometimes something else. These results vary
3084
according to whether @code{lex} or @code{flex} is being used.
3085
3086
You are encouraged to use Flex in your sources, since it is both more
3087
pleasant to use than plain Lex and the C source it produces is portable.
3088
In order to ensure portability, however, you must either provide a
3089
function @code{yywrap} or, if you don't use it (e.g., your scanner has
3090
no @samp{#include}-like feature), simply include a @samp{%noyywrap}
3091
statement in the scanner's source. Once this done, the scanner is
3092
portable (unless @emph{you} felt free to use nonportable constructs) and
3093
does not depend on any library. In this case, and in this case only, it
3094
is suggested that you use this Autoconf snippet:
3095
3096
@example
3097
AC_PROG_LEX
3098
if test "$LEX" != flex; then
3099
LEX="$SHELL $missing_dir/missing flex"
3100
AC_SUBST(LEX_OUTPUT_ROOT, lex.yy)
3101
AC_SUBST(LEXLIB, '')
3102
fi
3103
@end example
3104
3105
The shell script @command{missing} can be found in the Automake
3106
distribution.
3107
3108
To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes
3109
(indirectly) this macro twice, which will cause an annoying but benign
3110
``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions
3111
of Automake will fix this issue, meanwhile, just ignore this message.
3112
@end defmac
3113
3114
@defmac AC_PROG_LN_S
3115
@acindex PROG_LN_S
3116
@ovindex LN_S
3117
If @samp{ln -s} works on the current file system (the operating system
3118
and file system support symbolic links), set the output variable
3119
@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set
3120
@code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}.
3121
3122
If you make a link a directory other than the current directory, its
3123
meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely
3124
create links using @samp{$(LN_S)}, either find out which form is used
3125
and adjust the arguments, or always invoke @code{ln} in the directory
3126
where the link is to be created.
3127
3128
In other words, it does not work to do:
3129
@example
3130
$(LN_S) foo /x/bar
3131
@end example
3132
3133
Instead, do:
3134
3135
@example
3136
(cd /x && $(LN_S) foo bar)
3137
@end example
3138
@end defmac
3139
3140
@defmac AC_PROG_RANLIB
3141
@acindex PROG_RANLIB
3142
@ovindex RANLIB
3143
Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib}
3144
is found, and otherwise to @samp{:} (do nothing).
3145
@end defmac
3146
3147
@defmac AC_PROG_YACC
3148
@acindex PROG_YACC
3149
@ovindex YACC
3150
If @code{bison} is found, set output variable @code{YACC} to @samp{bison
3151
-y}. Otherwise, if @code{byacc} is found, set @code{YACC} to
3152
@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}.
3153
@end defmac
3154
3155
@node Generic Programs
3156
@subsection Generic Program and File Checks
3157
3158
These macros are used to find programs not covered by the ``particular''
3159
test macros. If you need to check the behavior of a program as well as
3160
find out whether it is present, you have to write your own test for it
3161
(@pxref{Writing Tests}). By default, these macros use the environment
3162
variable @code{PATH}. If you need to check for a program that might not
3163
be in the user's @code{PATH}, you can pass a modified path to use
3164
instead, like this:
3165
3166
@example
3167
AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd],
3168
[$PATH:/usr/libexec:/usr/sbin:/usr/etc:etc])
3169
@end example
3170
3171
You are strongly encouraged to declare the @var{variable} passed to
3172
@code{AC_CHECK_PROG} etc. as precious, @xref{Setting Output Variables},
3173
@code{AC_ARG_VAR}, for more details.
3174
3175
@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject})
3176
@acindex CHECK_PROG
3177
Check whether program @var{prog-to-check-for} exists in @code{PATH}. If
3178
it is found, set @var{variable} to @var{value-if-found}, otherwise to
3179
@var{value-if-not-found}, if given. Always pass over @var{reject} (an
3180
absolute file name) even if it is the first found in the search path; in
3181
that case, set @var{variable} using the absolute file name of the
3182
@var{prog-to-check-for} found that is not @var{reject}. If
3183
@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for
3184
@var{variable}.
3185
@end defmac
3186
3187
@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3188
@acindex CHECK_PROGS
3189
Check for each program in the whitespace-separated list
3190
@var{progs-to-check-for} exists on the @code{PATH}. If it is found, set
3191
@var{variable} to the name of that program. Otherwise, continue
3192
checking the next program in the list. If none of the programs in the
3193
list are found, set @var{variable} to @var{value-if-not-found}; if
3194
@var{value-if-not-found} is not specified, the value of @var{variable}
3195
is not changed. Calls @code{AC_SUBST} for @var{variable}.
3196
@end defmac
3197
3198
@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3199
@acindex CHECK_TOOL
3200
Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for}
3201
with a prefix of the host type as determined by
3202
@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}).
3203
For example, if the user runs @samp{configure --host=i386-gnu}, then
3204
this call:
3205
@example
3206
AC_CHECK_TOOL(RANLIB, ranlib, :)
3207
@end example
3208
@noindent
3209
sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in
3210
@code{PATH}, or otherwise to @samp{ranlib} if that program exists in
3211
@code{PATH}, or to @samp{:} if neither program exists.
3212
@end defmac
3213
3214
@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3215
@acindex CHECK_TOOLS
3216
Like @code{AC_CHECK_TOOL}, each of the tools in the list
3217
@var{progs-to-check-for} are checked with a prefix of the host type as
3218
determined by @code{AC_CANONICAL_HOST}, followed by a dash
3219
(@pxref{Canonicalizing}). If none of the tools can be found with a
3220
prefix, then the first one without a prefix is used. If a tool is found,
3221
set @var{variable} to the name of that program. If none of the tools in
3222
the list are found, set @var{variable} to @var{value-if-not-found}; if
3223
@var{value-if-not-found} is not specified, the value of @var{variable}
3224
is not changed. Calls @code{AC_SUBST} for @var{variable}.
3225
@end defmac
3226
3227
@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3228
@acindex PATH_PROG
3229
Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire
3230
path of @var{prog-to-check-for} if found.
3231
@end defmac
3232
3233
@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3234
@acindex PATH_PROGS
3235
Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
3236
are found, set @var{variable} to the entire path of the program
3237
found.
3238
@end defmac
3239
3240
@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path})
3241
@acindex PATH_TOOL
3242
Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire
3243
path of the program if it is found.
3244
@end defmac
3245
3246
3247
@node Files
3248
@section Files
3249
@cindex File, checking
3250
3251
You might also need to check for the existence of files. Before using
3252
these macros, ask yourself whether a run time test might not be a better
3253
solution. Be aware that, like most Autoconf macros, they test a feature
3254
of the host machine, and therefore, they die when cross-compiling.
3255
3256
@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found})
3257
@acindex CHECK_FILE
3258
Check whether file @var{file} exists on the native system. If it is
3259
found, execute @var{action-if-found}, otherwise do
3260
@var{action-if-not-found}, if given.
3261
@end defmac
3262
3263
@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found})
3264
@acindex CHECK_FILES
3265
Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}.
3266
Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols})
3267
for each file found.
3268
@end defmac
3269
3270
3271
@node Libraries
3272
@section Library Files
3273
@cindex Library, checking
3274
3275
The following macros check for the presence of certain C, C++ or Fortran
3276
77 library archive files.
3277
3278
@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3279
@acindex CHECK_LIB
3280
Depending on the current language(@pxref{Language Choice}), try to
3281
ensure that the C, C++, or Fortran 77 function @var{function} is
3282
available by checking whether a test program can be linked with the
3283
library @var{library} to get the function. @var{library} is the base
3284
name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as
3285
the @var{library} argument.
3286
3287
@var{action-if-found} is a list of shell commands to run if the link
3288
with the library succeeds; @var{action-if-not-found} is a list of shell
3289
commands to run if the link fails. If @var{action-if-found} is not
3290
specified, the default action will prepend @option{-l@var{library}} to
3291
@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all
3292
capitals). This macro is intended to support building of @code{LIBS} in
3293
a right-to-left (least-dependent to most-dependent) fashion such that
3294
library dependencies are satisfied as a natural side-effect of
3295
consecutive tests. Some linkers are very sensitive to library ordering
3296
so the order in which @code{LIBS} is generated is important to reliable
3297
detection of libraries.
3298
3299
If linking with @var{library} results in unresolved symbols that would
3300
be resolved by linking with additional libraries, give those libraries
3301
as the @var{other-libraries} argument, separated by spaces:
3302
e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3303
that @var{library} is present, because linking the test program will
3304
always fail with unresolved symbols. The @var{other-libraries} argument
3305
should be limited to cases where it is desirable to test for one library
3306
in the presence of another that is not already in @code{LIBS}.
3307
@end defmac
3308
3309
3310
@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
3311
@acindex SEARCH_LIBS
3312
Search for a library defining @var{function} if it's not already
3313
available. This equates to calling @code{AC_TRY_LINK_FUNC} first
3314
with no libraries, then for each library listed in @var{search-libs}.
3315
3316
Add @option{-l@var{library}} to @code{LIBS} for the first library found
3317
to contain @var{function}, and run @var{action-if-found}. If the
3318
function is not found, run @var{action-if-not-found}.
3319
3320
If linking with @var{library} results in unresolved symbols that would
3321
be resolved by linking with additional libraries, give those libraries
3322
as the @var{other-libraries} argument, separated by spaces:
3323
e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect
3324
that @var{function} is present, because linking the test program will
3325
always fail with unresolved symbols.
3326
@end defmac
3327
3328
3329
3330
@node Library Functions
3331
@section Library Functions
3332
3333
The following macros check for particular C library functions.
3334
If there is no macro specifically defined to check for a function you need,
3335
and you don't need to check for any special properties of
3336
it, then you can use one of the general function-check macros.
3337
3338
@menu
3339
* Function Portability:: Pitfalls with usual functions
3340
* Particular Functions:: Special handling to find certain functions
3341
* Generic Functions:: How to find other functions
3342
@end menu
3343
3344
@node Function Portability
3345
@subsection Portability of C Functions
3346
3347
Most usual functions can either be missing, or be buggy, or be limited
3348
on some architectures. This section tries to make an inventory of these
3349
portability issues. By definition, this list will always require
3350
additions. Please help us keeping it as complete as possible.
3351
3352
@table @asis
3353
@item @code{snprintf}
3354
@c @fuindex snprintf
3355
@prindex @code{snprintf}
3356
@c @fuindex vsnprintf
3357
@prindex @code{vsnprintf}
3358
The ISO C99 standard says that if the output array isn't big enough and
3359
if no other errors occur, @code{snprintf} and @code{vsnprintf} truncate
3360
the output and return the number of bytes that ought to have been
3361
produced. Some older systems return the truncated length (e.g., GNU C
3362
Library 2.0.x or IRIX 6.5), some a negative value (e.g., earlier GNU C
3363
Library versions), and some the buffer length without truncation (e.g.,
3364
32-bit Solaris 7). Also, some buggy older systems ignore the length and
3365
overrun the buffer (e.g., 64-bit Solaris 7).
3366
3367
@item @code{sprintf}
3368
@c @fuindex sprintf
3369
@prindex @code{sprintf}
3370
@c @fuindex vsprintf
3371
@prindex @code{vsprintf}
3372
The ISO C standard says @code{sprintf} and @code{vsprintf} return the
3373
number of bytes written, but on some old systems (SunOS 4 for
3374
instance) they return the buffer pointer instead.
3375
3376
@item @code{sscanf}
3377
@c @fuindex sscanf
3378
@prindex @code{sscanf}
3379
On various old systems, e.g. HP-UX 9, @code{sscanf} requires that its
3380
input string is writable (though it doesn't actually change it). This
3381
can be a problem when using @command{gcc} since it normally puts
3382
constant strings in read-only memory
3383
(@pxref{Incompatibilities,Incompatibilities of GCC,,gcc,Using and
3384
Porting the GNU Compiler Collection}). Apparently in some cases even
3385
having format strings read-only can be a problem.
3386
3387
@item @code{strnlen}
3388
@c @fuindex strnlen
3389
@prindex @code{strnlen}
3390
AIX 4.3 provides a broken version which produces funny results:
3391
3392
@example
3393
strnlen ("foobar", 0) = 0
3394
strnlen ("foobar", 1) = 3
3395
strnlen ("foobar", 2) = 2
3396
strnlen ("foobar", 3) = 1
3397
strnlen ("foobar", 4) = 0
3398
strnlen ("foobar", 5) = 6
3399
strnlen ("foobar", 6) = 6
3400
strnlen ("foobar", 7) = 6
3401
strnlen ("foobar", 8) = 6
3402
strnlen ("foobar", 9) = 6
3403
@end example
3404
3405
@item @code{unlink}
3406
@c @fuindex unlink
3407
@prindex @code{unlink}
3408
The @sc{posix} spec says that @code{unlink} causes the given files to be
3409
removed only after there are no more open file handles for it. Not all
3410
OS's support this behaviour though. So even on systems that provide
3411
@code{unlink}, you cannot portably assume it is OK to call it on files
3412
that are open. For example, on Windows 9x and ME, such a call would fail;
3413
on DOS it could even lead to file system corruption, as the file might end
3414
up being written to after the OS has removed it.
3415
3416
@item @code{va_copy}
3417
@c @fuindex va_copy
3418
@prindex @code{va_copy}
3419
The ISO C99 standard provides @code{va_copy} for copying
3420
@code{va_list} variables. It may be available in older environments
3421
too, though possibly as @code{__va_copy} (eg. @command{gcc} in strict
3422
C89 mode). These can be tested with @code{#ifdef}. A fallback to
3423
@code{memcpy (&dst, &src, sizeof(va_list))} will give maximum
3424
portability.
3425
3426
@item @code{va_list}
3427
@c @fuindex va_list
3428
@prindex @code{va_list}
3429
@code{va_list} is not necessarily just a pointer. It can be a
3430
@code{struct} (eg. @command{gcc} on Alpha), which means @code{NULL} is
3431
not portable. Or it can be an array (eg. @command{gcc} in some
3432
PowerPC configurations), which means as a function parameter it can be
3433
effectively call-by-reference and library routines might modify the
3434
value back in the caller (eg. @code{vsnprintf} in the GNU C Library
3435
2.1).
3436
3437
@item Signed @code{>>}
3438
Normally the C @code{>>} right shift of a signed type replicates the
3439
high bit, giving a so-called ``arithmetic'' shift. But care should be
3440
taken since the ISO C standard doesn't require that behaviour. On those
3441
few processors without a native arithmetic shift (for instance Cray
3442
vector systems) zero bits may be shifted in, the same as a shift of an
3443
unsigned type.
3444
@end table
3445
3446
3447
@node Particular Functions
3448
@subsection Particular Function Checks
3449
@cindex Function, checking
3450
3451
These macros check for particular C functions---whether they exist, and
3452
in some cases how they respond when given certain arguments.
3453
3454
@defmac AC_FUNC_ALLOCA
3455
@acindex FUNC_ALLOCA
3456
@cvindex C_ALLOCA
3457
@cvindex HAVE_ALLOCA_H
3458
@ovindex ALLOCA
3459
@c @fuindex alloca
3460
@prindex @code{alloca}
3461
Check how to get @code{alloca}. Tries to get a builtin version by
3462
checking for @file{alloca.h} or the predefined C preprocessor macros
3463
@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h},
3464
it defines @code{HAVE_ALLOCA_H}.
3465
3466
If those attempts fail, it looks for the function in the standard C
3467
library. If any of those methods succeed, it defines
3468
@code{HAVE_ALLOCA}. Otherwise, it sets the output variable
3469
@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so
3470
programs can periodically call @samp{alloca(0)} to garbage collect).
3471
This variable is separate from @code{LIBOBJS} so multiple programs can
3472
share the value of @code{ALLOCA} without needing to create an actual
3473
library, in case only some of them use the code in @code{LIBOBJS}.
3474
3475
This macro does not try to get @code{alloca} from the System V R3
3476
@file{libPW} or the System V R4 @file{libucb} because those libraries
3477
contain some incompatible functions that cause trouble. Some versions
3478
do not even contain @code{alloca} or contain a buggy version. If you
3479
still want to use their @code{alloca}, use @code{ar} to extract
3480
@file{alloca.o} from them instead of compiling @file{alloca.c}.
3481
3482
Source files that use @code{alloca} should start with a piece of code
3483
like the following, to declare it properly. In some versions of AIX,
3484
the declaration of @code{alloca} must precede everything else except for
3485
comments and preprocessor directives. The @code{#pragma} directive is
3486
indented so that pre-@sc{ansi} C compilers will ignore it, rather than
3487
choke on it.
3488
3489
@example
3490
@group
3491
/* AIX requires this to be the first thing in the file. */
3492
#ifndef __GNUC__
3493
# if HAVE_ALLOCA_H
3494
# include <alloca.h>
3495
# else
3496
# ifdef _AIX
3497
#pragma alloca
3498
# else
3499
# ifndef alloca /* predefined by HP cc +Olibcalls */
3500
char *alloca ();
3501
# endif
3502
# endif
3503
# endif
3504
#endif
3505
@end group
3506
@end example
3507
@end defmac
3508
3509
@defmac AC_FUNC_CHOWN
3510
@acindex FUNC_CHOWN
3511
@c @fuindex chown
3512
@prindex @code{chown}
3513
If the @code{chown} function is available and works (in particular, it
3514
should accept @option{-1} for @code{uid} and @code{gid}), define
3515
@code{HAVE_CHOWN}.
3516
@end defmac
3517
3518
3519
@defmac AC_FUNC_CLOSEDIR_VOID
3520
@acindex FUNC_CLOSEDIR_VOID
3521
@cvindex CLOSEDIR_VOID
3522
@c @fuindex closedir
3523
@prindex @code{closedir}
3524
If the @code{closedir} function does not return a meaningful value,
3525
define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its
3526
return value for an error indicator.
3527
@end defmac
3528
3529
@defmac AC_FUNC_ERROR_AT_LINE
3530
@acindex FUNC_ERROR_AT_LINE
3531
@c @fuindex error_at_line
3532
@prindex @code{error_at_line}
3533
If the @code{error_at_line} function is not found, require an
3534
@code{AC_LIBOBJ} replacement of @samp{error}.
3535
@end defmac
3536
3537
@defmac AC_FUNC_FNMATCH
3538
@acindex FUNC_FNMATCH
3539
@c @fuindex fnmatch
3540
@prindex @code{fnmatch}
3541
If the @code{fnmatch} function is available and works (unlike the one on
3542
Solaris 2.4), define @code{HAVE_FNMATCH}.
3543
@end defmac
3544
3545
@defmac AC_FUNC_FORK
3546
@acindex FUNC_FORK
3547
@cvindex HAVE_VFORK_H
3548
@cvindex HAVE_WORKING_FORK
3549
@cvindex HAVE_WORKING_VFORK
3550
@cvindex vfork
3551
@c @fuindex fork
3552
@prindex @code{fork}
3553
@c @fuindex vfork
3554
@prindex @code{vfork}
3555
This macro checks for the @code{fork} and @code{vfork} functions. If a
3556
working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro
3557
checks whether @code{fork} is just a stub by trying to run it.
3558
3559
If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working
3560
@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise,
3561
define @code{vfork} to be @code{fork} for backward compatibility with
3562
previous versions of @command{autoconf}. This macro checks for several known
3563
errors in implementations of @code{vfork} and considers the system to not
3564
have a working @code{vfork} if it detects any of them. It is not considered
3565
to be an implementation error if a child's invocation of @code{signal}
3566
modifies the parent's signal handler, since child processes rarely change
3567
their signal handlers.
3568
3569
Since this macro defines @code{vfork} only for backward compatibility with
3570
previous versions of @command{autoconf} you're encouraged to define it
3571
yourself in new code:
3572
@example
3573
@group
3574
#if !HAVE_WORKING_VFORK
3575
# define vfork fork
3576
#endif
3577
@end group
3578
@end example
3579
@end defmac
3580
3581
@defmac AC_FUNC_FSEEKO
3582
@acindex FUNC_FSEEKO
3583
@cvindex _LARGEFILE_SOURCE
3584
@c @fuindex fseeko
3585
@prindex @code{fseeko}
3586
If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}.
3587
Define @code{_LARGEFILE_SOURCE} if necessary.
3588
@end defmac
3589
3590
@defmac AC_FUNC_GETGROUPS
3591
@acindex FUNC_GETGROUPS
3592
@ovindex GETGROUPS_LIBS
3593
@c @fuindex getgroups
3594
@prindex @code{getgroups}
3595
If the @code{getgroups} function is available and works (unlike on
3596
Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define
3597
@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries
3598
needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}.
3599
@end defmac
3600
3601
@defmac AC_FUNC_GETLOADAVG
3602
@acindex FUNC_GETLOADAVG
3603
@cvindex SVR4
3604
@cvindex DGUX
3605
@cvindex UMAX
3606
@cvindex UMAX4_3
3607
@cvindex NLIST_STRUCT
3608
@cvindex NLIST_NAME_UNION
3609
@cvindex GETLODAVG_PRIVILEGED
3610
@cvindex NEED_SETGID
3611
@cvindex C_GETLOADAVG
3612
@ovindex LIBOBJS
3613
@ovindex NEED_SETGID
3614
@ovindex KMEM_GROUP
3615
@ovindex GETLOADAVG_LIBS
3616
@c @fuindex getloadavg
3617
@prindex @code{getloadavg}
3618
Check how to get the system load averages. If the system has the
3619
@code{getloadavg} function, define @code{HAVE_GETLOADAVG}, and set
3620
@code{GETLOADAVG_LIBS} to any libraries needed to get that function.
3621
Also add @code{GETLOADAVG_LIBS} to @code{LIBS}.
3622
3623
Otherwise, require an @code{AC_LIBOBJ} replacement (@file{getloadavg.c})
3624
of @samp{getloadavg}, and possibly define several other C preprocessor
3625
macros and output variables:
3626
3627
@enumerate
3628
@item
3629
Define @code{C_GETLOADAVG}.
3630
3631
@item
3632
Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on
3633
those systems.
3634
3635
@item
3636
If @file{nlist.h} is found, define @code{NLIST_STRUCT}.
3637
3638
@item
3639
If @samp{struct nlist} has an @samp{n_un.n_name} member, define
3640
@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol
3641
@code{NLIST_NAME_UNION} is still defined, but do not depend upon it.
3642
3643
@item
3644
Programs may need to be installed setgid (or setuid) for
3645
@code{getloadavg} to work. In this case, define
3646
@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID}
3647
to @samp{true} (and otherwise to @samp{false}), and set
3648
@code{KMEM_GROUP} to the name of the group that should own the installed
3649
program.
3650
@end enumerate
3651
@end defmac
3652
3653
@defmac AC_FUNC_GETMNTENT
3654
@acindex FUNC_GETMNTENT
3655
@cvindex HAVE_GETMNTENT
3656
@c @fuindex getmntent
3657
@prindex @code{getmntent}
3658
Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen}
3659
libraries, for Irix 4, PTX, and Unixware, respectively. Then, if
3660
@code{getmntent} is available, define @code{HAVE_GETMNTENT}.
3661
@end defmac
3662
3663
@defmac AC_FUNC_GETPGRP
3664
@acindex FUNC_GETPGRP
3665
@cvindex GETPGRP_VOID
3666
@c @fuindex getpgid
3667
@c @fuindex getpgrp
3668
@prindex @code{getpgid}
3669
@prindex @code{getpgrp}
3670
Define @code{GETPGRP_VOID} if it is an error to pass 0 to
3671
@code{getpgrp}; this is the @sc{posix.1} behavior. On older BSD
3672
systems, you must pass 0 to @code{getpgrp}, as it takes an argument and
3673
behaves like @sc{posix.1}'s @code{getpgid}.
3674
3675
@example
3676
#if GETPGRP_VOID
3677
pid = getpgrp ();
3678
#else
3679
pid = getpgrp (0);
3680
#endif
3681
@end example
3682
3683
This macro does not check whether
3684
@code{getpgrp} exists at all; if you need to work in that situation,
3685
first call @code{AC_CHECK_FUNC} for @code{getpgrp}.
3686
@end defmac
3687
3688
@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
3689
@acindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK
3690
@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK
3691
@c @fuindex lstat
3692
@prindex @code{lstat}
3693
If @file{link} is a symbolic link, then @code{lstat} should treat
3694
@file{link/} the same as @file{link/.}. However, many older
3695
@code{lstat} implementations incorrectly ignore trailing slashes.
3696
3697
It is safe to assume that if @code{lstat} incorrectly ignores
3698
trailing slashes, then other symbolic-link-aware functions like
3699
@code{unlink} and @code{unlink} also incorrectly ignore trailing slashes.
3700
3701
If @code{lstat} behaves properly, define
3702
@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an
3703
@code{AC_LIBOBJ} replacement of @code{lstat}.
3704
@end defmac
3705
3706
@defmac AC_FUNC_MALLOC
3707
@acindex FUNC_MALLOC
3708
@c @fuindex malloc
3709
@prindex @code{malloc}
3710
If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid
3711
pointer), define @code{HAVE_MALLOC}.
3712
@end defmac
3713
3714
@defmac AC_FUNC_MEMCMP
3715
@acindex FUNC_MEMCMP
3716
@ovindex LIBOBJS
3717
@c @fuindex memcmp
3718
@prindex @code{memcmp}
3719
If the @code{memcmp} function is not available, or does not work on
3720
8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16
3721
bytes or more and with at least one buffer not starting on a 4-byte
3722
boundary (such as the one on NeXT x86 OpenStep), require an
3723
@code{AC_LIBOBJ} replacement for @samp{memcmp}.
3724
@end defmac
3725
3726
@defmac AC_FUNC_MKTIME
3727
@acindex FUNC_MKTIME
3728
@ovindex LIBOBJS
3729
@c @fuindex mktime
3730
@prindex @code{mktime}
3731
If the @code{mktime} function is not available, or does not work
3732
correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}.
3733
@end defmac
3734
3735
@defmac AC_FUNC_MMAP
3736
@acindex FUNC_MMAP
3737
@cvindex HAVE_MMAP
3738
@c @fuindex mmap
3739
@prindex @code{mmap}
3740
If the @code{mmap} function exists and works correctly, define
3741
@code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped
3742
memory.
3743
@end defmac
3744
3745
@defmac AC_FUNC_OBSTACK
3746
@acindex FUNC_OBSTACK
3747
@cvindex HAVE_OBSTACK
3748
@cindex obstack
3749
If the obstacks are found, define @code{HAVE_OBSTACK}, else require an
3750
@code{AC_LIBOBJ} replacement for @samp{obstack}.
3751
@end defmac
3752
3753
@defmac AC_FUNC_SELECT_ARGTYPES
3754
@acindex FUNC_SELECT_ARGTYPES
3755
@cvindex SELECT_TYPE_ARG1
3756
@cvindex SELECT_TYPE_ARG234
3757
@cvindex SELECT_TYPE_ARG5
3758
@c @fuindex select
3759
@prindex @code{select}
3760
Determines the correct type to be passed for each of the
3761
@code{select} function's arguments, and defines those types
3762
in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and
3763
@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults
3764
to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *},
3765
and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}.
3766
@end defmac
3767
3768
@defmac AC_FUNC_SETPGRP
3769
@acindex FUNC_SETPGRP
3770
@cvindex SETPGRP_VOID
3771
@c @fuindex setpgrp
3772
@prindex @code{setpgrp}
3773
If @code{setpgrp} takes no argument (the @sc{posix.1} version), define
3774
@code{SETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes
3775
two process IDs as arguments. This macro does not check whether
3776
@code{setpgrp} exists at all; if you need to work in that situation,
3777
first call @code{AC_CHECK_FUNC} for @code{setpgrp}.
3778
@end defmac
3779
3780
@defmac AC_FUNC_STAT
3781
@defmacx AC_FUNC_LSTAT
3782
@acindex FUNC_STAT
3783
@acindex FUNC_LSTAT
3784
@cvindex HAVE_STAT_EMPTY_STRING_BUG
3785
@cvindex HAVE_LSTAT_EMPTY_STRING_BUG
3786
@c @fuindex stat
3787
@prindex @code{stat}
3788
@c @fuindex lstat
3789
@prindex @code{lstat}
3790
Determine whether @code{stat} or @code{lstat} have the bug that it
3791
succeeds when given the zero-length file name argument. The @code{stat}
3792
and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do
3793
this.
3794
3795
If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or
3796
@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ}
3797
replacement of it.
3798
@end defmac
3799
3800
@defmac AC_FUNC_SETVBUF_REVERSED
3801
@acindex FUNC_SETVBUF_REVERSED
3802
@cvindex SETVBUF_REVERSED
3803
@c @fuindex setvbuf
3804
@prindex @code{setvbuf}
3805
If @code{setvbuf} takes the buffering type as its second argument and
3806
the buffer pointer as the third, instead of the other way around, define
3807
@code{SETVBUF_REVERSED}.
3808
@end defmac
3809
3810
@defmac AC_FUNC_STRCOLL
3811
@acindex FUNC_STRCOLL
3812
@cvindex HAVE_STRCOLL
3813
@c @fuindex strcoll
3814
@prindex @code{strcoll}
3815
If the @code{strcoll} function exists and works correctly, define
3816
@code{HAVE_STRCOLL}. This does a bit more than
3817
@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect
3818
definitions of @code{strcoll} that should not be used.
3819
@end defmac
3820
3821
@defmac AC_FUNC_STRTOD
3822
@acindex FUNC_STRTOD
3823
@ovindex POW_LIB
3824
@c @fuindex strtod
3825
@prindex @code{strtod}
3826
If the @code{strtod} function does not exist or doesn't work correctly,
3827
ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case,
3828
because @file{strtod.c} is likely to need @samp{pow}, set the output
3829
variable @code{POW_LIB} to the extra library needed.
3830
@end defmac
3831
3832
@defmac AC_FUNC_STRERROR_R
3833
@acindex FUNC_STRERROR_R
3834
@cvindex HAVE_STRERROR_R
3835
@cvindex HAVE_DECL_STRERROR_R
3836
@cvindex STRERROR_R_CHAR_P
3837
@c @fuindex strerror_r
3838
@prindex @code{strerror_r}
3839
If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if
3840
it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a
3841
@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it
3842
returns an @code{int} error number. The Thread-Safe Functions option of
3843
@sc{posix-200x} requires @code{strerror_r} to return @code{int}, but
3844
many systems (including, for example, version 2.2.4 of the GNU C
3845
Library) return a @code{char *} value that is not necessarily equal to
3846
the buffer argument.
3847
@end defmac
3848
3849
@defmac AC_FUNC_STRFTIME
3850
@acindex FUNC_STRFTIME
3851
@cvindex HAVE_STRFTIME
3852
@c @fuindex strftime
3853
@prindex @code{strftime}
3854
Check for @code{strftime} in the @file{intl} library, for SCO @sc{unix}.
3855
Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}.
3856
@end defmac
3857
3858
@defmac AC_FUNC_STRNLEN
3859
@acindex FUNC_STRNLEN
3860
@cvindex HAVE_STRNLEN
3861
@c @fuindex strnlen
3862
@prindex @code{strnlen}
3863
Check for a working @code{strnlen}, and ask for its replacement. Some
3864
architectures are know to provide broken versions of @code{strnlen}, such
3865
as AIX 4.3.
3866
@end defmac
3867
3868
@defmac AC_FUNC_UTIME_NULL
3869
@acindex FUNC_UTIME_NULL
3870
@cvindex HAVE_UTIME_NULL
3871
@c @fuindex utime
3872
@prindex @code{utime}
3873
If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to
3874
the present, define @code{HAVE_UTIME_NULL}.
3875
@end defmac
3876
3877
@defmac AC_FUNC_VPRINTF
3878
@acindex FUNC_VPRINTF
3879
@cvindex HAVE_VPRINTF
3880
@cvindex HAVE_DOPRNT
3881
@c @fuindex vprintf
3882
@prindex @code{vprintf}
3883
If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if
3884
@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf}
3885
is available, you may assume that @code{vfprintf} and @code{vsprintf}
3886
are also available.)
3887
@end defmac
3888
3889
@node Generic Functions
3890
@subsection Generic Function Checks
3891
3892
These macros are used to find functions not covered by the ``particular''
3893
test macros. If the functions might be in libraries other than the
3894
default C library, first call @code{AC_CHECK_LIB} for those libraries.
3895
If you need to check the behavior of a function as well as find out
3896
whether it is present, you have to write your own test for
3897
it (@pxref{Writing Tests}).
3898
3899
@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
3900
@acindex CHECK_FUNC
3901
If C function @var{function} is available, run shell commands
3902
@var{action-if-found}, otherwise @var{action-if-not-found}. If you just
3903
want to define a symbol if the function is available, consider using
3904
@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C
3905
linkage even when @code{AC_LANG(C++)} has been called, since C is more
3906
standardized than C++. (@pxref{Language Choice}, for more information
3907
about selecting the language for checks.)
3908
@end defmac
3909
3910
@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found})
3911
@acindex CHECK_FUNCS
3912
@cvindex HAVE_@var{function}
3913
For each @var{function} in the whitespace-separated argument list,
3914
define @code{HAVE_@var{function}} (in all capitals) if it is available.
3915
If @var{action-if-found} is given, it is additional shell code to
3916
execute when one of the functions is found. You can give it a value of
3917
@samp{break} to break out of the loop on the first match. If
3918
@var{action-if-not-found} is given, it is executed when one of the
3919
functions is not found.
3920
@end defmac
3921
3922
Autoconf follows a philosophy that was formed over the years by those
3923
who have struggled for portability: isolate the portability issues in
3924
specific files, and then program as if you were in a @sc{posix}
3925
environment. Some functions may be missing or unfixable, and your
3926
package must be ready to replace them.
3927
3928
Use the first three of the following macros to specify a function to be
3929
replaced, and the last one (@code{AC_REPLACE_FUNCS}) to check for and
3930
replace the function if needed.
3931
3932
@defmac AC_LIBOBJ (@var{function})
3933
@acindex LIBOBJ
3934
@ovindex LIBOBJS
3935
Specify that @samp{@var{function}.c} must be included in the executables
3936
to replace a missing or broken implementation of @var{function}.
3937
3938
Technically, it adds @samp{@var{function}.$ac_objext} to the output
3939
variable @code{LIBOBJS} and calls @code{AC_LIBSOURCE} for
3940
@samp{@var{function}.c}. You should not directly change @code{LIBOBJS},
3941
since this is not traceable.
3942
@end defmac
3943
3944
@defmac AC_LIBSOURCE (@var{file})
3945
@acindex LIBSOURCE
3946
Specify that @var{file} might be needed to compile the project. If you
3947
need to know what files might be needed by a @file{configure.ac}, you
3948
should trace @code{AC_LIBSOURCE}. @var{file} must be a literal.
3949
3950
This macro is called automatically from @code{AC_LIBOBJ}, but you must
3951
call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In
3952
that case, since shell variables cannot be traced statically, you must
3953
pass to @code{AC_LIBSOURCE} any possible files that the shell variable
3954
might cause @code{AC_LIBOBJ} to need. For example, if you want to pass
3955
a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either
3956
@code{"foo"} or @code{"bar"}, you should do:
3957
3958
@example
3959
AC_LIBSOURCE(foo.c)
3960
AC_LIBSOURCE(bar.c)
3961
AC_LIBOBJ($foo_or_bar)
3962
@end example
3963
3964
@noindent
3965
There is usually a way to avoid this, however, and you are encouraged to
3966
simply call @code{AC_LIBOBJ} with literal arguments.
3967
3968
Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with
3969
slightly different semantics: the old macro took the function name,
3970
e.g. @code{foo}, as its argument rather than the file name.
3971
@end defmac
3972
3973
@defmac AC_LIBSOURCES (@var{files})
3974
@acindex LIBSOURCES
3975
Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a
3976
comma-separated M4 list. Thus, the above example might be rewritten:
3977
3978
@example
3979
AC_LIBSOURCES([foo.c, bar.c])
3980
AC_LIBOBJ($foo_or_bar)
3981
@end example
3982
@end defmac
3983
3984
@defmac AC_REPLACE_FUNCS (@var{function}@dots{})
3985
@acindex REPLACE_FUNCS
3986
@ovindex LIBOBJS
3987
Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as
3988
@var{action-if-not-found}. You can declare your replacement function by
3989
enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the
3990
system has the function, it probably declares it in a header file you
3991
should be including, so you shouldn't redeclare it lest your declaration
3992
conflict.
3993
@end defmac
3994
3995
@node Header Files
3996
@section Header Files
3997
@cindex Header, checking
3998
3999
The following macros check for the presence of certain C header files.
4000
If there is no macro specifically defined to check for a header file you need,
4001
and you don't need to check for any special properties of
4002
it, then you can use one of the general header-file check macros.
4003
4004
@menu
4005
* Particular Headers:: Special handling to find certain headers
4006
* Generic Headers:: How to find other headers
4007
@end menu
4008
4009
@node Particular Headers
4010
@subsection Particular Header Checks
4011
4012
These macros check for particular system header files---whether they
4013
exist, and in some cases whether they declare certain symbols.
4014
4015
@defmac AC_HEADER_DIRENT
4016
@acindex HEADER_DIRENT
4017
@cvindex HAVE_DIRENT_H
4018
@cvindex HAVE_NDIR_H
4019
@cvindex HAVE_SYS_DIR_H
4020
@cvindex HAVE_SYS_NDIR_H
4021
Check for the following header files. For the first one that is
4022
found and defines @samp{DIR}, define the listed C preprocessor macro:
4023
4024
@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}}
4025
@item @file{dirent.h} @tab @code{HAVE_DIRENT_H}
4026
@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H}
4027
@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H}
4028
@item @file{ndir.h} @tab @code{HAVE_NDIR_H}
4029
@end multitable
4030
4031
The directory-library declarations in your source code should look
4032
something like the following:
4033
4034
@example
4035
@group
4036
#if HAVE_DIRENT_H
4037
# include <dirent.h>
4038
# define NAMLEN(dirent) strlen((dirent)->d_name)
4039
#else
4040
# define dirent direct
4041
# define NAMLEN(dirent) (dirent)->d_namlen
4042
# if HAVE_SYS_NDIR_H
4043
# include <sys/ndir.h>
4044
# endif
4045
# if HAVE_SYS_DIR_H
4046
# include <sys/dir.h>
4047
# endif
4048
# if HAVE_NDIR_H
4049
# include <ndir.h>
4050
# endif
4051
#endif
4052
@end group
4053
@end example
4054
4055
Using the above declarations, the program would declare variables to be
4056
of type @code{struct dirent}, not @code{struct direct}, and would access
4057
the length of a directory entry name by passing a pointer to a
4058
@code{struct dirent} to the @code{NAMLEN} macro.
4059
4060
This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries.
4061
@end defmac
4062
4063
@defmac AC_HEADER_MAJOR
4064
@acindex HEADER_MAJOR
4065
@cvindex MAJOR_IN_MKDEV
4066
@cvindex MAJOR_IN_SYSMACROS
4067
If @file{sys/types.h} does not define @code{major}, @code{minor}, and
4068
@code{makedev}, but @file{sys/mkdev.h} does, define
4069
@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define
4070
@code{MAJOR_IN_SYSMACROS}.
4071
@end defmac
4072
4073
4074
@defmac AC_HEADER_STAT
4075
@acindex HEADER_STAT
4076
@acindex STAT_MACROS_BROKEN
4077
If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in
4078
@file{sys/stat.h} do not work properly (returning false positives),
4079
define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV,
4080
Amdahl UTS and Motorola System V/88.
4081
@end defmac
4082
4083
4084
@defmac AC_HEADER_STDC
4085
@acindex HEADER_STDC
4086
@cvindex STDC_HEADERS
4087
Define @code{STDC_HEADERS} if the system has @sc{ansi} C header files.
4088
Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h},
4089
@file{string.h}, and @file{float.h}; if the system has those, it
4090
probably has the rest of the @sc{ansi} C header files. This macro also
4091
checks whether @file{string.h} declares @code{memchr} (and thus
4092
presumably the other @code{mem} functions), whether @file{stdlib.h}
4093
declare @code{free} (and thus presumably @code{malloc} and other related
4094
functions), and whether the @file{ctype.h} macros work on characters
4095
with the high bit set, as @sc{ansi} C requires.
4096
4097
Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether
4098
the system has @sc{ansi}-compliant header files (and probably C library
4099
functions) because many systems that have GCC do not have @sc{ansi} C
4100
header files.
4101
4102
On systems without @sc{ansi} C headers, there is so much variation that
4103
it is probably easier to declare the functions you use than to figure
4104
out exactly what the system header files declare. Some systems contain
4105
a mix of functions @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but
4106
lack @samp{memmove}; some define the @sc{bsd} functions as macros in
4107
@file{string.h} or @file{strings.h}; some have only the @sc{bsd}
4108
functions but @file{string.h}; some declare the memory functions in
4109
@file{memory.h}, some in @file{string.h}; etc. It is probably
4110
sufficient to check for one string function and one memory function; if
4111
the library has the @sc{ansi} versions of those then it probably has
4112
most of the others. If you put the following in @file{configure.ac}:
4113
4114
@example
4115
AC_HEADER_STDC
4116
AC_CHECK_FUNCS(strchr memcpy)
4117
@end example
4118
4119
@noindent
4120
then, in your code, you can put declarations like this:
4121
4122
@example
4123
@group
4124
#if STDC_HEADERS
4125
# include <string.h>
4126
#else
4127
# if !HAVE_STRCHR
4128
# define strchr index
4129
# define strrchr rindex
4130
# endif
4131
char *strchr (), *strrchr ();
4132
# if !HAVE_MEMCPY
4133
# define memcpy(d, s, n) bcopy ((s), (d), (n))
4134
# define memmove(d, s, n) bcopy ((s), (d), (n))
4135
# endif
4136
#endif
4137
@end group
4138
@end example
4139
4140
@noindent
4141
If you use a function like @code{memchr}, @code{memset}, @code{strtok},
4142
or @code{strspn}, which have no @sc{bsd} equivalent, then macros won't
4143
suffice; you must provide an implementation of each function. An easy
4144
way to incorporate your implementations only when needed (since the ones
4145
in system C libraries may be hand optimized) is to, taking @code{memchr}
4146
for example, put it in @file{memchr.c} and use
4147
@samp{AC_REPLACE_FUNCS(memchr)}.
4148
@end defmac
4149
4150
@defmac AC_HEADER_SYS_WAIT
4151
@acindex HEADER_SYS_WAIT
4152
@cvindex HAVE_SYS_WAIT_H
4153
If @file{sys/wait.h} exists and is compatible with @sc{posix.1}, define
4154
@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h}
4155
does not exist, or if it uses the old @sc{bsd} @code{union wait} instead
4156
of @code{int} to store a status value. If @file{sys/wait.h} is not
4157
@sc{posix.1} compatible, then instead of including it, define the
4158
@sc{posix.1} macros with their usual interpretations. Here is an
4159
example:
4160
4161
@example
4162
@group
4163
#include <sys/types.h>
4164
#if HAVE_SYS_WAIT_H
4165
# include <sys/wait.h>
4166
#endif
4167
#ifndef WEXITSTATUS
4168
# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8)
4169
#endif
4170
#ifndef WIFEXITED
4171
# define WIFEXITED(stat_val) (((stat_val) & 255) == 0)
4172
#endif
4173
@end group
4174
@end example
4175
@end defmac
4176
4177
@cvindex _POSIX_VERSION
4178
@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on
4179
@sc{posix.1} systems. If there is no @file{unistd.h}, it is definitely
4180
not a @sc{posix.1} system. However, some non-@sc{posix.1} systems do
4181
have @file{unistd.h}.
4182
4183
The way to check if the system supports @sc{posix.1} is:
4184
4185
@example
4186
@group
4187
#if HAVE_UNISTD_H
4188
# include <sys/types.h>
4189
# include <unistd.h>
4190
#endif
4191
4192
#ifdef _POSIX_VERSION
4193
/* Code for POSIX.1 systems. */
4194
#endif
4195
@end group
4196
@end example
4197
4198
@defmac AC_HEADER_TIME
4199
@acindex HEADER_TIME
4200
@cvindex TIME_WITH_SYS_TIME
4201
If a program may include both @file{time.h} and @file{sys/time.h},
4202
define @code{TIME_WITH_SYS_TIME}. On some older systems,
4203
@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not
4204
protected against multiple inclusion, so programs should not explicitly
4205
include both files. This macro is useful in programs that use, for
4206
example, @code{struct timeval} or @code{struct timezone} as well as
4207
@code{struct tm}. It is best used in conjunction with
4208
@code{HAVE_SYS_TIME_H}, which can be checked for using
4209
@code{AC_CHECK_HEADERS(sys/time.h)}.
4210
4211
@example
4212
@group
4213
#if TIME_WITH_SYS_TIME
4214
# include <sys/time.h>
4215
# include <time.h>
4216
#else
4217
# if HAVE_SYS_TIME_H
4218
# include <sys/time.h>
4219
# else
4220
# include <time.h>
4221
# endif
4222
#endif
4223
@end group
4224
@end example
4225
@end defmac
4226
4227
4228
@defmac AC_HEADER_TIOCGWINSZ
4229
@acindex HEADER_TIOCGWINSZ
4230
@cvindex GWINSZ_IN_SYS_IOCTL
4231
@c FIXME: I need clarifications from Jim.
4232
If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4233
define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4234
found in @file{<termios.h>}.
4235
4236
Use:
4237
4238
@example
4239
@group
4240
#if HAVE_TERMIOS_H
4241
# include <termios.h>
4242
#endif
4243
4244
#if GWINSZ_IN_SYS_IOCTL
4245
# include <sys/ioctl.h>
4246
#endif
4247
@end group
4248
@end example
4249
@end defmac
4250
4251
@node Generic Headers
4252
@subsection Generic Header Checks
4253
4254
These macros are used to find system header files not covered by the
4255
``particular'' test macros. If you need to check the contents of a header
4256
as well as find out whether it is present, you have to write your own
4257
test for it (@pxref{Writing Tests}).
4258
4259
@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4260
@acindex CHECK_HEADER
4261
If the system header file @var{header-file} is usable, execute shell
4262
commands @var{action-if-found}, otherwise execute
4263
@var{action-if-not-found}. If you just want to define a symbol if the
4264
header file is available, consider using @code{AC_CHECK_HEADERS}
4265
instead.
4266
4267
The meaning of ``usable'' depends upon the content of @var{includes}:
4268
4269
@table @asis
4270
@item if @var{includes} is empty
4271
check whether
4272
4273
@example
4274
@var{header-file}
4275
@end example
4276
4277
@noindent
4278
can be @emph{preprocessed} without error.
4279
4280
@item if @var{include} is set
4281
Check whether
4282
4283
@example
4284
@var{includes}
4285
#include <@var{header-file}>
4286
@end example
4287
4288
@noindent
4289
can be @emph{compiled} without error. You may use
4290
@code{AC_CHECK_HEADER} (and @code{AC_CHECK_HEADERS}) to check whether
4291
two headers are compatible.
4292
@end table
4293
4294
You may pass any kind of dummy content for @var{includes}, such as a
4295
single space, a comment, to check whether @var{header-file} compiles
4296
with success.
4297
@end defmac
4298
4299
@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4300
@acindex CHECK_HEADERS
4301
@cvindex HAVE_@var{header}
4302
For each given system header file @var{header-file} in the
4303
whitespace-separated argument list that exists, define
4304
@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found}
4305
is given, it is additional shell code to execute when one of the header
4306
files is found. You can give it a value of @samp{break} to break out of
4307
the loop on the first match. If @var{action-if-not-found} is given, it
4308
is executed when one of the header files is not found.
4309
4310
Be sure to read the documentation of @code{AC_CHECK_HEADER} to
4311
understand the influence of @var{includes}.
4312
@end defmac
4313
4314
@node Declarations
4315
@section Declarations
4316
@cindex Declaration, checking
4317
4318
The following macros check for the declaration of variables and
4319
functions. If there is no macro specifically defined to check for a
4320
symbol you need, then you can use the general macros (@pxref{Generic
4321
Declarations}) or, for more complex tests, you may use
4322
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
4323
4324
@menu
4325
* Particular Declarations:: Macros to check for certain declarations
4326
* Generic Declarations:: How to find other declarations
4327
@end menu
4328
4329
@node Particular Declarations
4330
@subsection Particular Declaration Checks
4331
4332
The following macros check for certain declarations.
4333
4334
@defmac AC_DECL_SYS_SIGLIST
4335
@acindex DECL_SYS_SIGLIST
4336
@cvindex SYS_SIGLIST_DECLARED
4337
Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist}
4338
is declared in a system header file, either @file{signal.h} or
4339
@file{unistd.h}.
4340
@end defmac
4341
4342
@node Generic Declarations
4343
@subsection Generic Declaration Checks
4344
4345
These macros are used to find declarations not covered by the ``particular''
4346
test macros.
4347
4348
@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4349
@acindex CHECK_DECL
4350
If @var{symbol} (a function or a variable) is not declared in
4351
@var{includes} and a declaration is needed, run the shell commands
4352
@var{action-if-not-found}, otherwise @var{action-if-found}. If no
4353
@var{includes} are specified, the default includes are used
4354
(@pxref{Default Includes}).
4355
4356
This macro actually tests whether it is valid to use @var{symbol} as an
4357
r-value, not if it is really declared, because it is much safer to avoid
4358
introducing extra declarations when they are not needed.
4359
@end defmac
4360
4361
@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4362
@acindex CHECK_DECLS
4363
@cvindex HAVE_DECL_@var{symbol}
4364
For each of the @var{symbols} (@emph{comma}-separated list), define
4365
@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if
4366
@var{symbol} is declared, otherwise to @samp{0}. If
4367
@var{action-if-not-found} is given, it is additional shell code to
4368
execute when one of the function declarations is needed, otherwise
4369
@var{action-if-found} is executed.
4370
4371
This macro uses an m4 list as first argument:
4372
@example
4373
AC_CHECK_DECLS(strdup)
4374
AC_CHECK_DECLS([strlen])
4375
AC_CHECK_DECLS([malloc, realloc, calloc, free])
4376
@end example
4377
4378
Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
4379
declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead
4380
of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are
4381
@emph{sure} that the check was performed, use
4382
@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf:
4383
4384
@example
4385
#if !HAVE_DECL_SYMBOL
4386
extern char *symbol;
4387
#endif
4388
@end example
4389
4390
@noindent
4391
If the test may have not been performed, however, because it is safer
4392
@emph{not} to declare a symbol than to use a declaration that conflicts
4393
with the system's one, you should use:
4394
4395
@example
4396
#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC
4397
char *malloc (size_t *s);
4398
#endif
4399
@end example
4400
4401
@noindent
4402
You fall into the second category only in extreme situations: either
4403
your files may be used without being configured, or they are used during
4404
the configuration. In most cases the traditional approach is enough.
4405
@end defmac
4406
4407
4408
@node Structures
4409
@section Structures
4410
@cindex Structure, checking
4411
4412
The following macros check for the presence of certain members in C
4413
structures. If there is no macro specifically defined to check for a
4414
member you need, then you can use the general structure-member macro
4415
(@pxref{Generic Structures}) or, for more complex tests, you may use
4416
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}).
4417
4418
@menu
4419
* Particular Structures:: Macros to check for certain structure members
4420
* Generic Structures:: How to find other structure members
4421
@end menu
4422
4423
@node Particular Structures
4424
@subsection Particular Structure Checks
4425
4426
The following macros check for certain structures or structure members.
4427
4428
@defmac AC_STRUCT_ST_BLKSIZE
4429
@acindex STRUCT_ST_BLKSIZE
4430
@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE
4431
@cvindex HAVE_ST_BLKSIZE
4432
If @code{struct stat} contains an @code{st_blksize} member, define
4433
@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name,
4434
@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in
4435
the future. This macro is obsoleted, and should be replaced by
4436
4437
@example
4438
AC_CHECK_MEMBERS([struct stat.st_blksize])
4439
@end example
4440
@end defmac
4441
4442
@defmac AC_STRUCT_ST_BLOCKS
4443
@acindex STRUCT_ST_BLOCKS
4444
@cvindex HAVE_STRUCT_STAT_ST_BLOCKS
4445
@cvindex HAVE_ST_BLOCKS
4446
@ovindex LIBOBJS
4447
If @code{struct stat} contains an @code{st_blocks} member, define
4448
@code{HAVE_STRUCT STAT_ST_BLOCKS}. Otherwise, require an
4449
@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name,
4450
@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the
4451
future.
4452
@end defmac
4453
4454
@defmac AC_STRUCT_ST_RDEV
4455
@acindex STRUCT_ST_RDEV
4456
@cvindex HAVE_ST_RDEV
4457
@cvindex HAVE_STRUCT_STAT_ST_RDEV
4458
If @code{struct stat} contains an @code{st_rdev} member, define
4459
@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro,
4460
@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported
4461
in the future. Actually, even the new macro is obsolete, and should be
4462
replaced by:
4463
@example
4464
AC_CHECK_MEMBERS([struct stat.st_rdev])
4465
@end example
4466
@end defmac
4467
4468
@defmac AC_STRUCT_TM
4469
@acindex STRUCT_TM
4470
@cvindex TM_IN_SYS_TIME
4471
If @file{time.h} does not define @code{struct tm}, define
4472
@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h}
4473
had better define @code{struct tm}.
4474
@end defmac
4475
4476
@defmac AC_STRUCT_TIMEZONE
4477
@acindex STRUCT_TIMEZONE
4478
@cvindex HAVE_TM_ZONE
4479
@cvindex HAVE_TZNAME
4480
Figure out how to get the current timezone. If @code{struct tm} has a
4481
@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the
4482
obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array
4483
@code{tzname} is found, define @code{HAVE_TZNAME}.
4484
@end defmac
4485
4486
@node Generic Structures
4487
@subsection Generic Structure Checks
4488
4489
These macros are used to find structure members not covered by the
4490
``particular'' test macros.
4491
4492
@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4493
@acindex CHECK_MEMBER
4494
Check whether @var{member} is a member of the aggregate @var{aggregate}.
4495
If no @var{includes} are specified, the default includes are used
4496
(@pxref{Default Includes}).
4497
4498
@example
4499
AC_CHECK_MEMBER(struct passwd.pw_gecos,,
4500
[AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
4501
[#include <pwd.h>])
4502
@end example
4503
4504
You can use this macro for sub-members:
4505
4506
@example
4507
AC_CHECK_MEMBER(struct top.middle.bot)
4508
@end example
4509
@end defmac
4510
4511
@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4512
@acindex CHECK_MEMBERS
4513
Check for the existence of each @samp{@var{aggregate}.@var{member}} of
4514
@var{members} using the previous macro. When @var{member} belongs to
4515
@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all
4516
capitals, with spaces and dots replaced by underscores).
4517
4518
This macro uses m4 lists:
4519
@example
4520
AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
4521
@end example
4522
@end defmac
4523
4524
4525
@node Types
4526
@section Types
4527
4528
The following macros check for C types, either builtin or typedefs. If
4529
there is no macro specifically defined to check for a type you need, and
4530
you don't need to check for any special properties of it, then you can
4531
use a general type-check macro.
4532
4533
@menu
4534
* Particular Types:: Special handling to find certain types
4535
* Generic Types:: How to find other types
4536
@end menu
4537
4538
@node Particular Types
4539
@subsection Particular Type Checks
4540
4541
These macros check for particular C types in @file{sys/types.h},
4542
@file{stdlib.h} and others, if they exist.
4543
4544
@defmac AC_TYPE_GETGROUPS
4545
@acindex TYPE_GETGROUPS
4546
@cvindex GETGROUPS_T
4547
Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int}
4548
is the base type of the array argument to @code{getgroups}.
4549
@end defmac
4550
4551
@defmac AC_TYPE_MODE_T
4552
@acindex TYPE_MODE_T
4553
@cvindex mode_t
4554
Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}.
4555
@end defmac
4556
4557
@defmac AC_TYPE_OFF_T
4558
@acindex TYPE_OFF_T
4559
@cvindex off_t
4560
Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}.
4561
@end defmac
4562
4563
@defmac AC_TYPE_PID_T
4564
@acindex TYPE_PID_T
4565
@cvindex pid_t
4566
Equivalent to @samp{AC_CHECK_TYPE(pid_t, int)}.
4567
@end defmac
4568
4569
@defmac AC_TYPE_SIGNAL
4570
@acindex TYPE_SIGNAL
4571
@cvindex RETSIGTYPE
4572
If @file{signal.h} declares @code{signal} as returning a pointer to a
4573
function returning @code{void}, define @code{RETSIGTYPE} to be
4574
@code{void}; otherwise, define it to be @code{int}.
4575
4576
Define signal handlers as returning type @code{RETSIGTYPE}:
4577
4578
@example
4579
@group
4580
RETSIGTYPE
4581
hup_handler ()
4582
@{
4583
@dots{}
4584
@}
4585
@end group
4586
@end example
4587
@end defmac
4588
4589
@defmac AC_TYPE_SIZE_T
4590
@acindex TYPE_SIZE_T
4591
@cvindex size_t
4592
Equivalent to @samp{AC_CHECK_TYPE(size_t, unsigned)}.
4593
@end defmac
4594
4595
@defmac AC_TYPE_UID_T
4596
@acindex TYPE_UID_T
4597
@cvindex uid_t
4598
@cvindex gid_t
4599
If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and
4600
@code{gid_t} to be @code{int}.
4601
@end defmac
4602
4603
@node Generic Types
4604
@subsection Generic Type Checks
4605
4606
These macros are used to check for types not covered by the ``particular''
4607
test macros.
4608
4609
@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4610
@acindex CHECK_TYPE
4611
Check whether @var{type} is defined. It may be a compiler builtin type
4612
or defined by the @var{includes} (@pxref{Default Includes}).
4613
@end defmac
4614
4615
4616
@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes})
4617
@acindex CHECK_TYPES
4618
For each @var{type} of the @var{types} that is defined, define
4619
@code{HAVE_@var{type}} (in all capitals). If no @var{includes} are
4620
specified, the default includes are used (@pxref{Default Includes}). If
4621
@var{action-if-found} is given, it is additional shell code to execute
4622
when one of the types is found. If @var{action-if-not-found} is given,
4623
it is executed when one of the types is not found.
4624
4625
This macro uses m4 lists:
4626
@example
4627
AC_CHECK_TYPES(ptrdiff_t)
4628
AC_CHECK_TYPES([unsigned long long, uintmax_t])
4629
@end example
4630
4631
@end defmac
4632
4633
Autoconf, up to 2.13, used to provide to another version of
4634
@code{AC_CHECK_TYPE}, broken by design. In order to keep backward
4635
compatibility, a simple heuristics, quite safe but not totally, is
4636
implemented. In case of doubt, read the documentation of the former
4637
@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}.
4638
4639
4640
@node Compilers and Preprocessors
4641
@section Compilers and Preprocessors
4642
4643
@ovindex EXEEXT
4644
All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX},
4645
@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on
4646
the output of the 1compiler, typically to the empty string if Unix and
4647
@samp{.exe} if Win32 or OS/2.
4648
4649
@ovindex OBJEXT
4650
They also define the output variable @code{OBJEXT} based on the
4651
output of the compiler, after .c files have been excluded, typically
4652
to @samp{o} if Unix, @samp{obj} if Win32.
4653
4654
If the compiler being used does not produce executables, they fail. If
4655
the executables can't be run, and cross-compilation is not enabled, they
4656
fail too. @xref{Manual Configuration}, for more on support for cross
4657
compiling.
4658
4659
@menu
4660
* Specific Compiler Characteristics:: Some portability issues
4661
* Generic Compiler Characteristics:: Language independent tests
4662
* C Compiler:: Checking its characteristics
4663
* C++ Compiler:: Likewise
4664
* Fortran 77 Compiler:: Likewise
4665
@end menu
4666
4667
@node Specific Compiler Characteristics
4668
@subsection Specific Compiler Characteristics
4669
4670
Some compilers exhibit different behaviors.
4671
4672
@table @asis
4673
@item Static/Dynamic Expressions
4674
Autoconf relies on a trick to extract one bit of information from the C
4675
compiler: using negative array sizes. For instance the following
4676
excerpt of a C source demonstrates how to test whether @samp{int}s are 4
4677
bytes long:
4678
4679
@example
4680
int
4681
main (void)
4682
@{
4683
static int test_array [sizeof (int) == 4 ? 1 : -1];
4684
test_array [0] = 0
4685
return 0;
4686
@}
4687
@end example
4688
4689
@noindent
4690
To our knowledge, there is a single compiler that does not support this
4691
trick: the HP C compilers (the real one, not only the ``bundled'') on
4692
HP-UX 11.00:
4693
4694
@example
4695
$ @kbd{cc -c -Ae +O2 +Onolimit conftest.c}
4696
cc: "conftest.c": error 1879: Variable-length arrays cannot \
4697
have static storage.
4698
@end example
4699
4700
Autoconf works around this problem by casting @code{sizeof (int)} to
4701
@code{long} before comparing it.
4702
@end table
4703
4704
@node Generic Compiler Characteristics
4705
@subsection Generic Compiler Characteristics
4706
4707
@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes})
4708
@acindex CHECK_SIZEOF
4709
Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the
4710
size in bytes of @var{type}. If @samp{type} is unknown, it gets a size
4711
of 0. If no @var{includes} are specified, the default includes are used
4712
(@pxref{Default Includes}). If you provide @var{include}, make sure to
4713
include @file{stdio.h} which is required for this macro to run.
4714
4715
This macro now works even when cross-compiling. The @var{unused}
4716
argument was used when cross-compiling.
4717
4718
For example, the call
4719
4720
@example
4721
AC_CHECK_SIZEOF(int *)
4722
@end example
4723
4724
@noindent
4725
defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
4726
@end defmac
4727
4728
4729
@node C Compiler
4730
@subsection C Compiler Characteristics
4731
4732
@defmac AC_PROG_CC (@ovar{compiler-search-list})
4733
@acindex PROG_CC
4734
@ovindex CC
4735
@ovindex CFLAGS
4736
Determine a C compiler to use. If @code{CC} is not already set in the
4737
environment, check for @code{gcc} and @code{cc}, then for other C
4738
compilers. Set output variable @code{CC} to the name of the compiler
4739
found.
4740
4741
This macro may, however, be invoked with an optional first argument
4742
which, if specified, must be a space separated list of C compilers to
4743
search for. This just gives the user an opportunity to specify an
4744
alternative search list for the C compiler. For example, if you didn't
4745
like the default order, then you could invoke @code{AC_PROG_CC} like
4746
this:
4747
4748
@example
4749
AC_PROG_CC(cl egcs gcc cc)
4750
@end example
4751
4752
If using the @sc{gnu} C compiler, set shell variable @code{GCC} to
4753
@samp{yes}. If output variable @code{CFLAGS} was not already set, set
4754
it to @option{-g -O2} for the @sc{gnu} C compiler (@option{-O2} on systems
4755
where GCC does not accept @option{-g}), or @option{-g} for other compilers.
4756
@end defmac
4757
4758
@defmac AC_PROG_CC_C_O
4759
@acindex PROG_CC_C_O
4760
@cvindex NO_MINUS_C_MINUS_O
4761
If the C compiler does not accept the @option{-c} and @option{-o} options
4762
simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually
4763
tests both the compiler found by @code{AC_PROG_CC}, and, if different,
4764
the first @code{cc} in the path. The test fails if one fails. This
4765
macro was created for @sc{gnu} Make to choose the default C compilation
4766
rule.
4767
@end defmac
4768
4769
@defmac AC_PROG_CC_STDC
4770
@acindex PROG_CC_STDC
4771
@ovindex CC
4772
If the C compiler is not in @sc{ansi} C mode by default, try to add an
4773
option to output variable @code{CC} to make it so. This macro tries
4774
various options that select @sc{ansi} C on some system or another. It
4775
considers the compiler to be in @sc{ansi} C mode if it handles function
4776
prototypes correctly.
4777
4778
If you use this macro, you should check after calling it whether the C
4779
compiler has been set to accept @sc{ansi} C; if not, the shell variable
4780
@code{ac_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source
4781
code in @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by
4782
using the program @code{ansi2knr}, which comes with Automake.
4783
@end defmac
4784
4785
4786
@defmac AC_PROG_CPP
4787
@acindex PROG_CPP
4788
@ovindex CPP
4789
Set output variable @code{CPP} to a command that runs the
4790
C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used.
4791
It is only portable to run @code{CPP} on files with a @file{.c}
4792
extension.
4793
4794
If the current language is C (@pxref{Language Choice}), many of the
4795
specific test macros use the value of @code{CPP} indirectly by calling
4796
@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or
4797
@code{AC_EGREP_CPP}.
4798
4799
Some preprocessors don't indicate missing include files by the error
4800
status. For such preprocessors an internal variable is set that causes
4801
other macros to check the standard error from the preprocessor and
4802
consider the test failed if any warnings have been reported.
4803
@end defmac
4804
4805
4806
The following macros check for C compiler or machine architecture
4807
features. To check for characteristics not listed here, use
4808
@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN}
4809
(@pxref{Run Time})
4810
4811
@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown})
4812
@acindex C_BIGENDIAN
4813
@cvindex WORDS_BIGENDIAN
4814
@cindex Endianness
4815
If words are stored with the most significant byte first (like Motorola
4816
and SPARC CPUs), execute @var{action-if-true}. If words are stored with
4817
the less significant byte first (like Intel and VAX CPUs), execute
4818
@var{action-if-false}.
4819
4820
This macro runs a test-case if endianness cannot be determined from the
4821
system header files. When cross-compiling the test-case is not run but
4822
grep'ed for some magic values. @var{action-if-unknown} is executed if
4823
the latter case fails to determine the byte sex of the host system.
4824
4825
The default for @var{action-if-true} is to define
4826
@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do
4827
nothing. And finally, the default for @var{action-if-unknown} is to
4828
abort configure and tell the installer which variable he should preset
4829
to bypass this test.
4830
@end defmac
4831
4832
@defmac AC_C_CONST
4833
@acindex C_CONST
4834
@cvindex const
4835
If the C compiler does not fully support the @sc{ansi} C qualifier
4836
@code{const}, define @code{const} to be empty. Some C compilers that do
4837
not define @code{__STDC__} do support @code{const}; some compilers that
4838
define @code{__STDC__} do not completely support @code{const}. Programs
4839
can simply use @code{const} as if every C compiler supported it; for
4840
those that don't, the @file{Makefile} or configuration header file will
4841
define it as empty.
4842
4843
Occasionally installers use a C++ compiler to compile C code, typically
4844
because they lack a C compiler. This causes problems with @code{const},
4845
because C and C++ treat @code{const} differently. For example:
4846
4847
@example
4848
const int foo;
4849
@end example
4850
4851
@noindent
4852
is valid in C but not in C++. These differences unfortunately cannot be
4853
papered over by defining @code{const} to be empty.
4854
4855
If @command{autoconf} detects this situation, it leaves @code{const} alone,
4856
as this generally yields better results in practice. However, using a
4857
C++ compiler to compile C code is not recommended or supported, and
4858
installers who run into trouble in this area should get a C compiler
4859
like GCC to compile their C code.
4860
@end defmac
4861
4862
@defmac AC_C_VOLATILE
4863
@acindex C_VOLATILE
4864
@cvindex volatile
4865
If the C compiler does not understand the keyword @code{volatile},
4866
define @code{volatile} to be empty. Programs can simply use
4867
@code{volatile} as if every C compiler supported it; for those that do
4868
not, the @file{Makefile} or configuration header will define it as
4869
empty.
4870
4871
If the correctness of your program depends on the semantics of
4872
@code{volatile}, simply defining it to be empty does, in a sense, break
4873
your code. However, given that the compiler does not support
4874
@code{volatile}, you are at its mercy anyway. At least your
4875
program will compile, when it wouldn't before.
4876
4877
In general, the @code{volatile} keyword is a feature of @sc{ansi} C, so
4878
you might expect that @code{volatile} is available only when
4879
@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does
4880
support volatile, but does not defined @code{__STDC__}.
4881
@end defmac
4882
4883
@defmac AC_C_INLINE
4884
@acindex C_INLINE
4885
@cvindex inline
4886
If the C compiler supports the keyword @code{inline}, do nothing.
4887
Otherwise define @code{inline} to @code{__inline__} or @code{__inline}
4888
if it accepts one of those, otherwise define @code{inline} to be empty.
4889
@end defmac
4890
4891
@defmac AC_C_CHAR_UNSIGNED
4892
@acindex C_CHAR_UNSIGNED
4893
@cvindex __CHAR_UNSIGNED__
4894
If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__},
4895
unless the C compiler predefines it.
4896
@end defmac
4897
4898
@defmac AC_C_LONG_DOUBLE
4899
@acindex C_LONG_DOUBLE
4900
@cvindex HAVE_LONG_DOUBLE
4901
If the C compiler supports a working @code{long double} type with more
4902
range or precision than the @code{double} type, define
4903
@code{HAVE_LONG_DOUBLE}.
4904
@end defmac
4905
4906
@defmac AC_C_STRINGIZE
4907
@acindex C_STRINGIZE
4908
@cvindex HAVE_STRINGIZE
4909
If the C preprocessor supports the stringizing operator, define
4910
@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is
4911
found in macros such as this:
4912
4913
@example
4914
#define x(y) #y
4915
@end example
4916
@end defmac
4917
4918
@defmac AC_C_PROTOTYPES
4919
@acindex C_PROTOTYPES
4920
@cvindex PROTOTYPES
4921
@cvindex __PROTOTYPES
4922
@cvindex PARAMS
4923
Check to see if function prototypes are understood by the compiler. If
4924
so, define @code{PROTOTYPES} and @code{__PROTOTYPES}.
4925
In the case the compiler does not handle
4926
prototypes, you should use @code{ansi2knr}, which comes with the
4927
Automake distribution, to unprotoize function definitions. For
4928
function prototypes, you should first define @code{PARAMS}:
4929
4930
@example
4931
#ifndef PARAMS
4932
# if PROTOTYPES
4933
# define PARAMS(protos) protos
4934
# else /* no PROTOTYPES */
4935
# define PARAMS(protos) ()
4936
# endif /* no PROTOTYPES */
4937
#endif
4938
@end example
4939
4940
@noindent
4941
then use it this way:
4942
4943
@example
4944
size_t my_strlen PARAMS ((const char *));
4945
@end example
4946
@end defmac
4947
4948
This macro also defines @code{__PROTOTYPES}; this is for the benefit of
4949
header files that cannot use macros that infringe on user name space.
4950
4951
@defmac AC_PROG_GCC_TRADITIONAL
4952
@acindex PROG_GCC_TRADITIONAL
4953
@ovindex CC
4954
Add @option{-traditional} to output variable @code{CC} if using the
4955
@sc{gnu} C compiler and @code{ioctl} does not work properly without
4956
@option{-traditional}. That usually happens when the fixed header files
4957
have not been installed on an old system. Since recent versions of the
4958
@sc{gnu} C compiler fix the header files automatically when installed,
4959
this is becoming a less prevalent problem.
4960
@end defmac
4961
4962
4963
@node C++ Compiler
4964
@subsection C++ Compiler Characteristics
4965
4966
4967
@defmac AC_PROG_CXX (@ovar{compiler-search-list})
4968
@acindex PROG_CXX
4969
@ovindex CXX
4970
@ovindex CXXFLAGS
4971
Determine a C++ compiler to use. Check if the environment variable
4972
@code{CXX} or @code{CCC} (in that order) is set; if so, then set output
4973
variable @code{CXX} to its value.
4974
4975
Otherwise, if the macro is invoked without an argument, then search for
4976
a C++ compiler under the likely names (first @code{g++} and @code{c++}
4977
then other names). If none of those checks succeed, then as a last
4978
resort set @code{CXX} to @code{g++}.
4979
4980
This macro may, however, be invoked with an optional first argument
4981
which, if specified, must be a space separated list of C++ compilers to
4982
search for. This just gives the user an opportunity to specify an
4983
alternative search list for the C++ compiler. For example, if you
4984
didn't like the default order, then you could invoke @code{AC_PROG_CXX}
4985
like this:
4986
4987
@example
4988
AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc)
4989
@end example
4990
4991
If using the @sc{gnu} C++ compiler, set shell variable @code{GXX} to
4992
@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set
4993
it to @option{-g -O2} for the @sc{gnu} C++ compiler (@option{-O2} on
4994
systems where G++ does not accept @option{-g}), or @option{-g} for other
4995
compilers.
4996
@end defmac
4997
4998
@defmac AC_PROG_CXXCPP
4999
@acindex PROG_CXXCPP
5000
@ovindex CXXCPP
5001
Set output variable @code{CXXCPP} to a command that runs the C++
5002
preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used.
5003
It is only portable to run @code{CXXCPP} on files with a @file{.c},
5004
@file{.C}, or @file{.cc} extension.
5005
5006
If the current language is C++ (@pxref{Language Choice}), many of the
5007
specific test macros use the value of @code{CXXCPP} indirectly by
5008
calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER},
5009
@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}.
5010
5011
Some preprocessors don't indicate missing include files by the error
5012
status. For such preprocessors an internal variable is set that causes
5013
other macros to check the standard error from the preprocessor and
5014
consider the test failed if any warnings have been reported. However,
5015
it is not known whether such broken preprocessors exist for C++.
5016
@end defmac
5017
5018
5019
5020
@node Fortran 77 Compiler
5021
@subsection Fortran 77 Compiler Characteristics
5022
5023
@defmac AC_PROG_F77 (@ovar{compiler-search-list})
5024
@acindex PROG_FORTRAN
5025
@ovindex F77
5026
@ovindex FFLAGS
5027
Determine a Fortran 77 compiler to use. If @code{F77} is not already
5028
set in the environment, then check for @code{g77} and @code{f77}, and
5029
then some other names. Set the output variable @code{F77} to the name
5030
of the compiler found.
5031
5032
This macro may, however, be invoked with an optional first argument
5033
which, if specified, must be a space separated list of Fortran 77
5034
compilers to search for. This just gives the user an opportunity to
5035
specify an alternative search list for the Fortran 77 compiler. For
5036
example, if you didn't like the default order, then you could invoke
5037
@code{AC_PROG_F77} like this:
5038
5039
@example
5040
AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90)
5041
@end example
5042
5043
If using @code{g77} (the @sc{gnu} Fortran 77 compiler), then
5044
@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}.
5045
If the output variable @code{FFLAGS} was not already set in the
5046
environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2}
5047
where @code{g77} does not accept @option{-g}). Otherwise, set
5048
@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers.
5049
@end defmac
5050
5051
@defmac AC_PROG_F77_C_O
5052
@acindex PROG_F77_C_O
5053
@cvindex F77_NO_MINUS_C_MINUS_O
5054
Test if the Fortran 77 compiler accepts the options @option{-c} and
5055
@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it
5056
does not.
5057
@end defmac
5058
5059
5060
The following macros check for Fortran 77 compiler characteristics. To
5061
check for characteristics not listed here, use @code{AC_TRY_COMPILE}
5062
(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}),
5063
making sure to first set the current language to Fortran 77
5064
@code{AC_LANG(Fortran 77)} (@pxref{Language Choice}).
5065
5066
5067
@defmac AC_F77_LIBRARY_LDFLAGS
5068
@acindex F77_LIBRARY_LDFLAGS
5069
@ovindex FLIBS
5070
Determine the linker flags (e.g. @option{-L} and @option{-l}) for the
5071
@dfn{Fortran 77 intrinsic and run-time libraries} that are required to
5072
successfully link a Fortran 77 program or shared library. The output
5073
variable @code{FLIBS} is set to these flags.
5074
5075
This macro is intended to be used in those situations when it is
5076
necessary to mix, e.g. C++ and Fortran 77 source code into a single
5077
program or shared library (@pxref{Mixing Fortran 77 With C and C++,,,
5078
automake, GNU Automake}).
5079
5080
For example, if object files from a C++ and Fortran 77 compiler must be
5081
linked together, then the C++ compiler/linker must be used for linking
5082
(since special C++-ish things need to happen at link time like calling
5083
global constructors, instantiating templates, enabling exception
5084
support, etc.).
5085
5086
However, the Fortran 77 intrinsic and run-time libraries must be linked
5087
in as well, but the C++ compiler/linker doesn't know by default how to
5088
add these Fortran 77 libraries. Hence, the macro
5089
@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77
5090
libraries.
5091
5092
The macro @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} will probably
5093
also be necessary to link C/C++ with Fortran; see below.
5094
@end defmac
5095
5096
5097
@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found})
5098
@acindex F77_DUMMY_MAIN
5099
@cvindex F77_DUMMY_MAIN
5100
With many compilers, the Fortran libraries detected by
5101
@code{AC_F77_LIBRARY_LDFLAGS} provide their own @code{main} entry
5102
function that initializes things like Fortran I/O, and which then calls
5103
a user-provided entry function named e.g. @code{MAIN__} to run the
5104
user's program. The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN}
5105
macro figures out how to deal with this interaction.
5106
5107
When using Fortran for purely numerical functions (no I/O, etcetera),
5108
users often prefer to provide their own @code{main} and skip the Fortran
5109
library initializations. In this case, however, one may still need to
5110
provide a dummy @code{MAIN__} routine in order to prevent linking errors
5111
on some systems. @code{AC_F77_DUMMY_MAIN} detects whether any such
5112
routine is @emph{required} for linking, and what its name is; the shell
5113
variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no
5114
solution was found, and @code{none} when no such dummy main is needed.
5115
5116
By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the
5117
name of this routine (e.g. @code{MAIN__}) @emph{if} it is required.
5118
@ovar{action-if-not-found} defaults to exiting with an error.
5119
5120
In order to link with Fortran routines, the user's C/C++ program should
5121
then include the following code to define the dummy main if it is
5122
needed:
5123
5124
@example
5125
#ifdef F77_DUMMY_MAIN
5126
# ifdef __cplusplus
5127
extern "C"
5128
# endif
5129
int F77_DUMMY_MAIN() @{ return 1; @}
5130
#endif
5131
@end example
5132
5133
Note that @code{AC_F77_DUMMY_MAIN} is called automatically from
5134
@code{AC_F77_WRAPPERS}; there is generally no need to call it explicitly
5135
unless one wants to change the default actions.
5136
@end defmac
5137
5138
@defmac AC_F77_MAIN
5139
@acindex F77_MAIN
5140
@cvindex F77_MAIN
5141
As discussed above for @code{AC_F77_DUMMY_MAIN}, many Fortran libraries
5142
allow you to provide an entry point called e.g. @code{MAIN__} instead of
5143
the usual @code{main}, which is then called by a @code{main} function in
5144
the Fortran libraries that initializes things like Fortran I/O. The
5145
@code{AC_F77_MAIN} macro detects whether it is @emph{possible} to
5146
utilize such an alternate main function, and defines @code{F77_MAIN} to
5147
the name of the function. (If no alternate main function name is found,
5148
@code{F77_MAIN} is simply defined to @code{main}.)
5149
5150
Thus, when calling Fortran routines from C that perform things like I/O,
5151
one should use this macro and name the "main" function @code{F77_MAIN}
5152
instead of @code{main}.
5153
@end defmac
5154
5155
@defmac AC_F77_WRAPPERS
5156
@acindex F77_WRAPPERS
5157
@cvindex F77_FUNC
5158
@cvindex F77_FUNC_
5159
Defines C macros @code{F77_FUNC(name,NAME)} and
5160
@code{F77_FUNC_(name,NAME)} to properly mangle the names of C/C++
5161
identifiers, and identifiers with underscores, respectively, so that
5162
they match the name-mangling scheme used by the Fortran 77 compiler.
5163
5164
Fortran 77 is case-insensitive, and in order to achieve this the Fortran
5165
77 compiler converts all identifiers into a canonical case and format.
5166
To call a Fortran 77 subroutine from C or to write a C function that is
5167
callable from Fortran 77, the C program must explicitly use identifiers
5168
in the format expected by the Fortran 77 compiler. In order to do this,
5169
one simply wraps all C identifiers in one of the macros provided by
5170
@code{AC_F77_WRAPPERS}. For example, suppose you have the following
5171
Fortran 77 subroutine:
5172
5173
@example
5174
subroutine foobar(x,y)
5175
double precision x, y
5176
y = 3.14159 * x
5177
return
5178
end
5179
@end example
5180
5181
You would then declare its prototype in C or C++ as:
5182
5183
@example
5184
#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR)
5185
#ifdef __cplusplus
5186
extern "C" /* prevent C++ name mangling */
5187
#endif
5188
void FOOBAR_F77(double *x, double *y);
5189
@end example
5190
5191
Note that we pass both the lowercase and uppercase versions of the
5192
function name to @code{F77_FUNC} so that it can select the right one.
5193
Note also that all parameters to Fortran 77 routines are passed as
5194
pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, GNU
5195
Automake}).
5196
5197
Although Autoconf tries to be intelligent about detecting the
5198
name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77
5199
compilers that it doesn't support yet. In this case, the above code
5200
will generate a compile-time error, but some other behavior
5201
(e.g. disabling Fortran-related features) can be induced by checking
5202
whether the @code{F77_FUNC} macro is defined.
5203
5204
Now, to call that routine from a C program, we would do something like:
5205
5206
@example
5207
@{
5208
double x = 2.7183, y;
5209
FOOBAR_F77(&x, &y);
5210
@}
5211
@end example
5212
5213
If the Fortran 77 identifier contains an underscore
5214
(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of
5215
@code{F77_FUNC} (with the same arguments). This is because some Fortran
5216
77 compilers mangle names differently if they contain an underscore.
5217
@end defmac
5218
5219
@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar})
5220
@acindex F77_FUNC
5221
Given an identifier @var{name}, set the shell variable @var{shellvar} to
5222
hold the mangled version @var{name} according to the rules of the
5223
Fortran 77 linker (see also @code{AC_F77_WRAPPERS}). @var{shellvar} is
5224
optional; if it is not supplied, the shell variable will be simply
5225
@var{name}. The purpose of this macro is to give the caller a way to
5226
access the name-mangling information other than through the C
5227
preprocessor as above; for example, to call Fortran routines from some
5228
language other than C/C++.
5229
@end defmac
5230
5231
@node System Services
5232
@section System Services
5233
5234
The following macros check for operating system services or capabilities.
5235
5236
@defmac AC_PATH_X
5237
@acindex PATH_X
5238
Try to locate the X Window System include files and libraries. If the
5239
user gave the command line options @option{--x-includes=@var{dir}} and
5240
@option{--x-libraries=@var{dir}}, use those directories. If either or
5241
both were not given, get the missing values by running @code{xmkmf} on a
5242
trivial @file{Imakefile} and examining the @file{Makefile} that it
5243
produces. If that fails (such as if @code{xmkmf} is not present), look
5244
for them in several directories where they often reside. If either
5245
method is successful, set the shell variables @code{x_includes} and
5246
@code{x_libraries} to their locations, unless they are in directories
5247
the compiler searches by default.
5248
5249
If both methods fail, or the user gave the command line option
5250
@option{--without-x}, set the shell variable @code{no_x} to @samp{yes};
5251
otherwise set it to the empty string.
5252
@end defmac
5253
5254
@defmac AC_PATH_XTRA
5255
@acindex PATH_XTRA
5256
@ovindex X_CFLAGS
5257
@ovindex X_LIBS
5258
@ovindex X_EXTRA_LIBS
5259
@ovindex X_PRE_LIBS
5260
@cvindex X_DISPLAY_MISSING
5261
An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags
5262
that X needs to output variable @code{X_CFLAGS}, and the X linker flags
5263
to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not
5264
available.
5265
5266
This macro also checks for special libraries that some systems need in
5267
order to compile X programs. It adds any that the system needs to
5268
output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6
5269
libraries that need to be linked with before @option{-lX11}, and adds
5270
any found to the output variable @code{X_PRE_LIBS}.
5271
5272
@c This is an incomplete kludge. Make a real way to do it.
5273
@c If you need to check for other X functions or libraries yourself, then
5274
@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to
5275
@c @code{LIBS} temporarily, like this: (FIXME - add example)
5276
@end defmac
5277
5278
@defmac AC_SYS_INTERPRETER
5279
@acindex SYS_INTERPRETER
5280
Check whether the system supports starting scripts with a line of the
5281
form @samp{#! /bin/csh} to select the interpreter to use for the script.
5282
After running this macro, shell code in @command{configure.ac} can check
5283
the shell variable @code{interpval}; it will be set to @samp{yes}
5284
if the system supports @samp{#!}, @samp{no} if not.
5285
@end defmac
5286
5287
@defmac AC_SYS_LARGEFILE
5288
@acindex SYS_LARGEFILE
5289
@cvindex _FILE_OFFSET_BITS
5290
@cvindex _LARGE_FILES
5291
@ovindex CC
5292
Arrange for
5293
@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html,
5294
large-file support}. On some hosts, one must use special compiler
5295
options to build programs that can access large files. Append any such
5296
options to the output variable @code{CC}. Define
5297
@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary.
5298
5299
Large-file support can be disabled by configuring with the
5300
@option{--disable-largefile} option.
5301
5302
If you use this macro, check that your program works even when
5303
@code{off_t} is longer than @code{long}, since this is common when
5304
large-file support is enabled. For example, it is not correct to print
5305
an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld",
5306
(long) X)}.
5307
@end defmac
5308
5309
@defmac AC_SYS_LONG_FILE_NAMES
5310
@acindex SYS_LONG_FILE_NAMES
5311
@cvindex HAVE_LONG_FILE_NAMES
5312
If the system supports file names longer than 14 characters, define
5313
@code{HAVE_LONG_FILE_NAMES}.
5314
@end defmac
5315
5316
@defmac AC_SYS_POSIX_TERMIOS
5317
@acindex SYS_POSIX_TERMIOS
5318
@cindex POSIX termios headers
5319
@cindex termios POSIX headers
5320
Check to see if POSIX termios headers and functions are available on the
5321
system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
5322
@samp{yes}. If not, set the variable to @samp{no}.
5323
@end defmac
5324
5325
@node UNIX Variants
5326
@section UNIX Variants
5327
5328
The following macros check for certain operating systems that need
5329
special treatment for some programs, due to exceptional oddities in
5330
their header files or libraries. These macros are warts; they will be
5331
replaced by a more systematic approach, based on the functions they make
5332
available or the environments they provide.
5333
5334
@defmac AC_AIX
5335
@acindex AIX
5336
@cvindex _ALL_SOURCE
5337
If on AIX, define @code{_ALL_SOURCE}. Allows the use of some @sc{bsd}
5338
functions. Should be called before any macros that run the C compiler.
5339
@end defmac
5340
5341
@defmac AC_ISC_POSIX
5342
@acindex ISC_POSIX
5343
@ovindex LIBS
5344
For @sc{interactive unix} (@sc{isc}), add @option{-lcposix} to output
5345
variable @code{LIBS} if necessary for @sc{posix} facilities. Call this
5346
after @code{AC_PROG_CC} and before any other macros that use @sc{posix}
5347
interfaces. @sc{interactive unix} is no longer sold, and Sun says that
5348
they will drop support for it on 2006-07-23, so this macro is becoming
5349
obsolescent.
5350
@end defmac
5351
5352
@defmac AC_MINIX
5353
@acindex MINIX
5354
@cvindex _MINIX
5355
@cvindex _POSIX_SOURCE
5356
@cvindex _POSIX_1_SOURCE
5357
If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define
5358
@code{_POSIX_1_SOURCE} to be 2. This allows the use of @sc{posix}
5359
facilities. Should be called before any macros that run the C compiler.
5360
@end defmac
5361
5362
5363
5364
5365
@c ========================================================= Writing Tests
5366
5367
@node Writing Tests
5368
@chapter Writing Tests
5369
5370
If the existing feature tests don't do something you need, you have to
5371
write new ones. These macros are the building blocks. They provide
5372
ways for other macros to check whether various kinds of features are
5373
available and report the results.
5374
5375
This chapter contains some suggestions and some of the reasons why the
5376
existing tests are written the way they are. You can also learn a lot
5377
about how to write Autoconf tests by looking at the existing ones. If
5378
something goes wrong in one or more of the Autoconf tests, this
5379
information can help you understand the assumptions behind them, which
5380
might help you figure out how to best solve the problem.
5381
5382
These macros check the output of the C compiler system. They do
5383
not cache the results of their tests for future use (@pxref{Caching
5384
Results}), because they don't know enough about the information they are
5385
checking for to generate a cache variable name. They also do not print
5386
any messages, for the same reason. The checks for particular kinds of C
5387
features call these macros and do cache their results and print messages
5388
about what they're checking for.
5389
5390
When you write a feature test that could be applicable to more than one
5391
software package, the best thing to do is encapsulate it in a new macro.
5392
@xref{Writing Autoconf Macros}, for how to do that.
5393
5394
@menu
5395
* Examining Declarations:: Detecting header files and declarations
5396
* Examining Syntax:: Detecting language syntax features
5397
* Examining Libraries:: Detecting functions and global variables
5398
* Run Time:: Testing for run-time features
5399
* Systemology:: A zoology of operating systems
5400
* Multiple Cases:: Tests for several possible values
5401
* Language Choice:: Selecting which language to use for testing
5402
@end menu
5403
5404
@node Examining Declarations
5405
@section Examining Declarations
5406
5407
The macro @code{AC_TRY_CPP} is used to check whether particular header
5408
files exist. You can check for one at a time, or more than one if you
5409
need several header files to all exist for some purpose.
5410
5411
@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false})
5412
@acindex TRY_CPP
5413
If the preprocessor produces no error messages while processing the
5414
@var{input} (typically includes), run shell commands
5415
@var{action-if-true}. Otherwise run shell commands
5416
@var{action-if-false}. Beware that @var{input} is double quoted. Shell
5417
variable, back quote, and backslash substitutions are performed on
5418
@var{input}.
5419
5420
This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because
5421
@option{-g}, @option{-O}, etc. are not valid options to many C
5422
preprocessors.
5423
@end defmac
5424
5425
Here is how to find out whether a header file contains a particular
5426
declaration, such as a typedef, a structure, a structure member, or a
5427
function. Use @code{AC_EGREP_HEADER} instead of running @code{grep}
5428
directly on the header file; on some systems the symbol might be defined
5429
in another header file that the file you are checking @samp{#include}s.
5430
5431
@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found})
5432
@acindex EGREP_HEADER
5433
If the output of running the preprocessor on the system header file
5434
@var{header-file} matches the @code{egrep} regular expression
5435
@var{pattern}, execute shell commands @var{action-if-found}, otherwise
5436
execute @var{action-if-not-found}.
5437
@end defmac
5438
5439
To check for C preprocessor symbols, either defined by header files or
5440
predefined by the C preprocessor, use @code{AC_EGREP_CPP}. Here is an
5441
example of the latter:
5442
5443
@example
5444
AC_EGREP_CPP(yes,
5445
[#ifdef _AIX
5446
yes
5447
#endif
5448
], is_aix=yes, is_aix=no)
5449
@end example
5450
5451
@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found})
5452
@acindex EGREP_CPP
5453
@var{program} is the text of a C or C++ program, on which shell
5454
variable, back quote, and backslash substitutions are performed. If the
5455
output of running the preprocessor on @var{program} matches the
5456
@code{egrep} regular expression @var{pattern}, execute shell commands
5457
@var{action-if-found}, otherwise execute @var{action-if-not-found}.
5458
5459
This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending
5460
on which language is current, @pxref{Language Choice}), if it hasn't
5461
been called already.
5462
@end defmac
5463
5464
@node Examining Syntax
5465
@section Examining Syntax
5466
5467
To check for a syntax feature of the C, C++ or Fortran 77 compiler, such
5468
as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to
5469
try to compile a small program that uses that feature. You can also use
5470
it to check for structures and structure members that are not present on
5471
all systems.
5472
5473
@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
5474
@acindex TRY_COMPILE
5475
Create a test program in the current language (@pxref{Language Choice})
5476
to see whether a function whose body consists of @var{function-body} can
5477
be compiled. If the file compiles successfully, run shell commands
5478
@var{action-if-found}, otherwise run @var{action-if-not-found}.
5479
5480
This macro double quotes both @var{includes} and @var{function-body}.
5481
5482
For C and C++, @var{includes} is any @code{#include} statements needed
5483
by the code in @var{function-body} (@var{includes} will be ignored if
5484
the currently selected language is Fortran 77). This macro also uses
5485
@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
5486
selected language, as well as @code{CPPFLAGS}, when compiling. If
5487
Fortran 77 is the currently selected language then @code{FFLAGS} will be
5488
used when compiling.
5489
5490
This macro does not try to link; use @code{AC_TRY_LINK} if you need to
5491
do that (@pxref{Examining Libraries}).
5492
@end defmac
5493
5494
@node Examining Libraries
5495
@section Examining Libraries
5496
5497
To check for a library, a function, or a global variable, Autoconf
5498
@command{configure} scripts try to compile and link a small program that
5499
uses it. This is unlike Metaconfig, which by default uses @code{nm}
5500
or @code{ar} on the C library to try to figure out which functions are
5501
available. Trying to link with the function is usually a more reliable
5502
approach because it avoids dealing with the variations in the options
5503
and output formats of @code{nm} and @code{ar} and in the location of the
5504
standard libraries. It also allows configuring for cross-compilation or
5505
checking a function's runtime behavior if needed. On the other hand, it
5506
can be slower than scanning the libraries once.
5507
5508
A few systems have linkers that do not return a failure exit status when
5509
there are unresolved functions in the link. This bug makes the
5510
configuration scripts produced by Autoconf unusable on those systems.
5511
However, some of them can be given options that make the exit status
5512
correct. This is a problem that Autoconf does not currently handle
5513
automatically. If users encounter this problem, they might be able to
5514
solve it by setting @code{LDFLAGS} in the environment to pass whatever
5515
options the linker needs (for example, @option{-Wl,-dn} on @sc{mips
5516
risc/os}).
5517
5518
@code{AC_TRY_LINK} is used to compile test programs to test for
5519
functions and global variables. It is also used by @code{AC_CHECK_LIB}
5520
to check for libraries (@pxref{Libraries}), by adding the library being
5521
checked for to @code{LIBS} temporarily and trying to link a small
5522
program.
5523
5524
@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-found}, @ovar{action-if-not-found})
5525
@acindex TRY_LINK
5526
Depending on the current language (@pxref{Language Choice}), create a
5527
test program to see whether a function whose body consists of
5528
@var{function-body} can be compiled and linked. If the file compiles
5529
and links successfully, run shell commands @var{action-if-found},
5530
otherwise run @var{action-if-not-found}.
5531
5532
This macro double quotes both @var{includes} and @var{function-body}.
5533
5534
For C and C++, @var{includes} is any @code{#include} statements needed
5535
by the code in @var{function-body} (@var{includes} will be ignored if
5536
the currently selected language is Fortran 77). This macro also uses
5537
@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently
5538
selected language, as well as @code{CPPFLAGS}, when compiling. If
5539
Fortran 77 is the currently selected language then @code{FFLAGS} will be
5540
used when compiling. However, both @code{LDFLAGS} and @code{LIBS} will
5541
be used during linking in all cases.
5542
@end defmac
5543
5544
@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found})
5545
@acindex TRY_LINK_FUNC
5546
Depending on the current language (@pxref{Language Choice}), create a
5547
test program to see whether a program whose body consists of
5548
a prototype of and a call to @var{function} can be compiled and linked.
5549
5550
If the file compiles and links successfully, run shell commands
5551
@var{action-if-found}, otherwise run @var{action-if-not-found}.
5552
@end defmac
5553
5554
5555
5556
@node Run Time
5557
@section Checking Run Time Behavior
5558
5559
Sometimes you need to find out how a system performs at run time, such
5560
as whether a given function has a certain capability or bug. If you
5561
can, make such checks when your program runs instead of when it is
5562
configured. You can check for things like the machine's endianness when
5563
your program initializes itself.
5564
5565
If you really need to test for a run-time behavior while configuring,
5566
you can write a test program to determine the result, and compile and
5567
run it using @code{AC_TRY_RUN}. Avoid running test programs if
5568
possible, because this prevents people from configuring your package for
5569
cross-compiling.
5570
5571
@menu
5572
* Test Programs:: Running test programs
5573
* Guidelines:: General rules for writing test programs
5574
* Test Functions:: Avoiding pitfalls in test programs
5575
@end menu
5576
5577
@node Test Programs
5578
@subsection Running Test Programs
5579
5580
Use the following macro if you need to test run-time behavior of the
5581
system while configuring.
5582
5583
@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling})
5584
@acindex TRY_RUN
5585
If @var{program} compiles and links successfully and returns an exit
5586
status of 0 when executed, run shell commands @var{action-if-true}.
5587
Otherwise, run shell commands @var{action-if-false}.
5588
5589
This macro double quotes @var{program}, the text of a program in the
5590
current language (@pxref{Language Choice}), on which shell variable and
5591
back quote substitutions are performed. This macro uses @code{CFLAGS}
5592
or @code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS}
5593
when compiling.
5594
5595
If the C compiler being used does not produce executables that run on
5596
the system where @command{configure} is being run, then the test program is
5597
not run. If the optional shell commands @var{action-if-cross-compiling}
5598
are given, they are run instead. Otherwise, @command{configure} prints
5599
an error message and exits.
5600
5601
In the @var{action-if-false} section, the exit status of the program is
5602
available in the shell variable @samp{$?}, but be very careful to limit
5603
yourself to positive values smaller than 127; bigger values shall be
5604
saved into a file by the @var{program}. Note also that you have simply
5605
no guarantee that this exit status is issued by the @var{program}, or by
5606
the failure of its compilation. In other words, use this feature if
5607
sadist only, it was reestablished because the Autoconf maintainers grew
5608
tired of receiving ``bug reports''.
5609
@end defmac
5610
5611
Try to provide a pessimistic default value to use when cross-compiling
5612
makes run-time tests impossible. You do this by passing the optional
5613
last argument to @code{AC_TRY_RUN}. @command{autoconf} prints a warning
5614
message when creating @command{configure} each time it encounters a call to
5615
@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument
5616
given. You may ignore the warning, though users will not be able to
5617
configure your package for cross-compiling. A few of the macros
5618
distributed with Autoconf produce this warning message.
5619
5620
To configure for cross-compiling you can also choose a value for those
5621
parameters based on the canonical system name (@pxref{Manual
5622
Configuration}). Alternatively, set up a test results cache file with
5623
the correct values for the host system (@pxref{Caching Results}).
5624
5625
To provide a default for calls of @code{AC_TRY_RUN} that are embedded in
5626
other macros, including a few of the ones that come with Autoconf, you
5627
can call @code{AC_PROG_CC} before running them. Then, if the shell
5628
variable @code{cross_compiling} is set to @samp{yes}, use an alternate
5629
method to get the results instead of calling the macros.
5630
5631
5632
@node Guidelines
5633
@subsection Guidelines for Test Programs
5634
5635
Test programs should not write anything to the standard output. They
5636
should return 0 if the test succeeds, nonzero otherwise, so that success
5637
can be distinguished easily from a core dump or other failure;
5638
segmentation violations and other failures produce a nonzero exit
5639
status. Test programs should @code{exit}, not @code{return}, from
5640
@code{main}, because on some systems (old Suns, at least) the argument
5641
to @code{return} in @code{main} is ignored.
5642
5643
Test programs can use @code{#if} or @code{#ifdef} to check the values of
5644
preprocessor macros defined by tests that have already run. For
5645
example, if you call @code{AC_HEADER_STDC}, then later on in
5646
@file{configure.ac} you can have a test program that includes an
5647
@sc{ansi} C header file conditionally:
5648
5649
@example
5650
@group
5651
#if STDC_HEADERS
5652
# include <stdlib.h>
5653
#endif
5654
@end group
5655
@end example
5656
5657
If a test program needs to use or create a data file, give it a name
5658
that starts with @file{conftest}, such as @file{conftest.data}. The
5659
@command{configure} script cleans up by running @samp{rm -rf conftest*}
5660
after running test programs and if the script is interrupted.
5661
5662
@node Test Functions
5663
@subsection Test Functions
5664
5665
Function declarations in test programs should have a prototype
5666
conditionalized for C++. In practice, though, test programs rarely need
5667
functions that take arguments.
5668
5669
@example
5670
#ifdef __cplusplus
5671
foo (int i)
5672
#else
5673
foo (i) int i;
5674
#endif
5675
@end example
5676
5677
Functions that test programs declare should also be conditionalized for
5678
C++, which requires @samp{extern "C"} prototypes. Make sure to not
5679
include any header files containing clashing prototypes.
5680
5681
@example
5682
#ifdef __cplusplus
5683
extern "C" void *malloc (size_t);
5684
#else
5685
char *malloc ();
5686
#endif
5687
@end example
5688
5689
If a test program calls a function with invalid parameters (just to see
5690
whether it exists), organize the program to ensure that it never invokes
5691
that function. You can do this by calling it in another function that is
5692
never invoked. You can't do it by putting it after a call to
5693
@code{exit}, because GCC version 2 knows that @code{exit} never returns
5694
and optimizes out any code that follows it in the same block.
5695
5696
If you include any header files, make sure to call the functions
5697
relevant to them with the correct number of arguments, even if they are
5698
just 0, to avoid compilation errors due to prototypes. GCC version 2
5699
has internal prototypes for several functions that it automatically
5700
inlines; for example, @code{memcpy}. To avoid errors when checking for
5701
them, either pass them the correct number of arguments or redeclare them
5702
with a different return type (such as @code{char}).
5703
5704
@node Systemology
5705
@section Systemology
5706
5707
This section aims at presenting some systems and pointers to
5708
documentation. It may help you addressing particular problems reported
5709
by users.
5710
5711
@table @asis
5712
@item @sc{qnx 4.25}
5713
@cindex @sc{qnx 4.25}
5714
@c FIXME: Please, if you feel like writing something more precise,
5715
@c it'd be great. In particular, I can't understand the difference with
5716
@c QNX Neutrino.
5717
@sc{qnx} is a realtime operating system running on Intel architecture
5718
meant to be scalable from the small embedded systems to hundred
5719
processor super-computer. It claims to be @sc{posix} certified. More
5720
information is available on the @href{www.qnx.com, @sc{qnx} home page},
5721
including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx}
5722
man pages}.
5723
@end table
5724
5725
5726
@node Multiple Cases
5727
@section Multiple Cases
5728
5729
Some operations are accomplished in several possible ways, depending on
5730
the @sc{unix} variant. Checking for them essentially requires a ``case
5731
statement''. Autoconf does not directly provide one; however, it is
5732
easy to simulate by using a shell variable to keep track of whether a
5733
way to perform the operation has been found yet.
5734
5735
Here is an example that uses the shell variable @code{fstype} to keep
5736
track of whether the remaining cases need to be checked.
5737
5738
@example
5739
@group
5740
AC_MSG_CHECKING([how to get file system type])
5741
fstype=no
5742
# The order of these tests is important.
5743
AC_TRY_CPP([#include <sys/statvfs.h>
5744
#include <sys/fstyp.h>],
5745
[AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4])
5746
if test $fstype = no; then
5747
AC_TRY_CPP([#include <sys/statfs.h>
5748
#include <sys/fstyp.h>],
5749
[AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3])
5750
fi
5751
if test $fstype = no; then
5752
AC_TRY_CPP([#include <sys/statfs.h>
5753
#include <sys/vmount.h>],
5754
[AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX])
5755
fi
5756
# (more cases omitted here)
5757
AC_MSG_RESULT([$fstype])
5758
@end group
5759
@end example
5760
5761
@node Language Choice
5762
@section Language Choice
5763
@cindex Language
5764
5765
Autoconf-generated @command{configure} scripts check for the C compiler and
5766
its features by default. Packages that use other programming languages
5767
(maybe more than one, e.g. C and C++) need to test features of the
5768
compilers for the respective languages. The following macros determine
5769
which programming language is used in the subsequent tests in
5770
@file{configure.ac}.
5771
5772
@defmac AC_LANG (@var{language})
5773
Do compilation tests using the compiler, preprocessor and file
5774
extensions for the specified @var{language}.
5775
5776
Supported languages are:
5777
5778
@table @samp
5779
@item C
5780
Do compilation tests using @code{CC} and @code{CPP} and use extension
5781
@file{.c} for test programs.
5782
5783
@item C++
5784
Do compilation tests using @code{CXX} and @code{CXXCPP} and use
5785
extension @file{.C} for test programs.
5786
5787
@item Fortran 77
5788
Do compilation tests using @code{F77} and use extension @file{.f} for
5789
test programs.
5790
@end table
5791
@end defmac
5792
5793
@defmac AC_LANG_PUSH (@var{language})
5794
@acindex LANG_PUSH
5795
Remember the current language (as set by @code{AC_LANG}) on a stack, and
5796
then select the @var{language}. Use this macro and @code{AC_LANG_POP}
5797
in macros that need to temporarily switch to a particular language.
5798
@end defmac
5799
5800
@defmac AC_LANG_POP (@ovar{language})
5801
@acindex LANG_POP
5802
Select the language that is saved on the top of the stack, as set by
5803
@code{AC_LANG_PUSH}, and remove it from the stack.
5804
5805
If given, @var{language} specifies the language we just @emph{quit}. It
5806
is a good idea to specify it when it's known (which should be the
5807
case@dots{}), since Autoconf will detect inconsistencies.
5808
5809
@example
5810
AC_LANG_PUSH(Fortran 77)
5811
# Perform some tests on Fortran 77.
5812
# ...
5813
AC_LANG_POP(Fortran 77)
5814
@end example
5815
@end defmac
5816
5817
@defmac AC_REQUIRE_CPP
5818
@acindex REQUIRE_CPP
5819
Ensure that whichever preprocessor would currently be used for tests has
5820
been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an
5821
argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP},
5822
depending on which language is current.
5823
@end defmac
5824
5825
5826
5827
@c ====================================================== Results of Tests.
5828
5829
@node Results
5830
@chapter Results of Tests
5831
5832
Once @command{configure} has determined whether a feature exists, what can
5833
it do to record that information? There are four sorts of things it can
5834
do: define a C preprocessor symbol, set a variable in the output files,
5835
save the result in a cache file for future @command{configure} runs, and
5836
print a message letting the user know the result of the test.
5837
5838
@menu
5839
* Defining Symbols:: Defining C preprocessor symbols
5840
* Setting Output Variables:: Replacing variables in output files
5841
* Caching Results:: Speeding up subsequent @command{configure} runs
5842
* Printing Messages:: Notifying @command{configure} users
5843
@end menu
5844
5845
@node Defining Symbols
5846
@section Defining C Preprocessor Symbols
5847
5848
A common action to take in response to a feature test is to define a C
5849
preprocessor symbol indicating the results of the test. That is done by
5850
calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}.
5851
5852
By default, @code{AC_OUTPUT} places the symbols defined by these macros
5853
into the output variable @code{DEFS}, which contains an option
5854
@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in
5855
Autoconf version 1, there is no variable @code{DEFS} defined while
5856
@command{configure} is running. To check whether Autoconf macros have
5857
already defined a certain C preprocessor symbol, test the value of the
5858
appropriate cache variable, as in this example:
5859
5860
@example
5861
AC_CHECK_FUNC(vprintf, [AC_DEFINE(HAVE_VPRINTF)])
5862
if test "$ac_cv_func_vprintf" != yes; then
5863
AC_CHECK_FUNC(_doprnt, [AC_DEFINE(HAVE_DOPRNT)])
5864
fi
5865
@end example
5866
5867
If @code{AC_CONFIG_HEADERS} has been called, then instead of creating
5868
@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the
5869
correct values into @code{#define} statements in a template file.
5870
@xref{Configuration Headers}, for more information about this kind of
5871
output.
5872
5873
@defmac AC_DEFINE (@var{variable}, @ovar{value}, @ovar{description})
5874
@acindex DEFINE
5875
Define C preprocessor variable @var{variable}. If @var{value} is given,
5876
set @var{variable} to that value (verbatim), otherwise set it to 1.
5877
@var{value} should not contain literal newlines, and if you are not
5878
using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#}
5879
characters, as @code{make} tends to eat them. To use a shell variable
5880
(which you need to do in order to define a value containing the M4 quote
5881
characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
5882
@var{description} is only useful if you are using
5883
@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into
5884
the generated @file{config.h.in} as the comment before the macro define.
5885
The following example defines the C preprocessor variable
5886
@code{EQUATION} to be the string constant @samp{"$a > $b"}:
5887
5888
@example
5889
AC_DEFINE(EQUATION, "$a > $b")
5890
@end example
5891
@end defmac
5892
5893
@defmac AC_DEFINE_UNQUOTED (@var{variable}, @ovar{value}, @ovar{description})
5894
@acindex DEFINE_UNQUOTED
5895
Like @code{AC_DEFINE}, but three shell expansions are
5896
performed---once---on @var{variable} and @var{value}: variable expansion
5897
(@samp{$}), command substitution (@samp{`}), and backslash escaping
5898
(@samp{\}). Single and double quote characters in the value have no
5899
special meaning. Use this macro instead of @code{AC_DEFINE} when
5900
@var{variable} or @var{value} is a shell variable. Examples:
5901
5902
@example
5903
AC_DEFINE_UNQUOTED(config_machfile, "$machfile")
5904
AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups)
5905
AC_DEFINE_UNQUOTED($ac_tr_hdr)
5906
@end example
5907
@end defmac
5908
5909
Due to the syntactical bizarreness of the Bourne shell, do not use
5910
semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}
5911
calls from other macro calls or shell code; that can cause syntax errors
5912
in the resulting @command{configure} script. Use either spaces or
5913
newlines. That is, do this:
5914
5915
@example
5916
AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"])
5917
@end example
5918
5919
@noindent
5920
or this:
5921
5922
@example
5923
AC_CHECK_HEADER(elf.h,
5924
[AC_DEFINE(SVR4)
5925
LIBS="$LIBS -lelf"])
5926
@end example
5927
5928
@noindent
5929
instead of this:
5930
5931
@example
5932
AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"])
5933
@end example
5934
5935
@node Setting Output Variables
5936
@section Setting Output Variables
5937
5938
Another way to record the results of tests is to set @dfn{output
5939
variables}, which are shell variables whose values are substituted into
5940
files that @command{configure} outputs. The two macros below create new
5941
output variables. @xref{Preset Output Variables}, for a list of output
5942
variables that are always available.
5943
5944
@defmac AC_SUBST (@var{variable}, @ovar{value})
5945
@acindex SUBST
5946
Create an output variable from a shell variable. Make @code{AC_OUTPUT}
5947
substitute the variable @var{variable} into output files (typically one
5948
or more @file{Makefile}s). This means that @code{AC_OUTPUT} will
5949
replace instances of @samp{@@@var{variable}@@} in input files with the
5950
value that the shell variable @var{variable} has when @code{AC_OUTPUT}
5951
is called. This value of @var{variable} should not contain literal
5952
newlines.
5953
5954
If @var{value} is given, in addition assign it to @samp{variable}.
5955
@end defmac
5956
5957
@defmac AC_SUBST_FILE (@var{variable})
5958
@acindex SUBST_FILE
5959
Another way to create an output variable from a shell variable. Make
5960
@code{AC_OUTPUT} insert (without substitutions) the contents of the file
5961
named by shell variable @var{variable} into output files. This means
5962
that @code{AC_OUTPUT} will replace instances of
5963
@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in})
5964
with the contents of the file that the shell variable @var{variable}
5965
names when @code{AC_OUTPUT} is called. Set the variable to
5966
@file{/dev/null} for cases that do not have a file to insert.
5967
5968
This macro is useful for inserting @file{Makefile} fragments containing
5969
special dependencies or other @code{make} directives for particular host
5970
or target types into @file{Makefile}s. For example, @file{configure.ac}
5971
could contain:
5972
5973
@example
5974
AC_SUBST_FILE(host_frag)
5975
host_frag=$srcdir/conf/sun4.mh
5976
@end example
5977
5978
@noindent
5979
and then a @file{Makefile.in} could contain:
5980
5981
@example
5982
@@host_frag@@
5983
@end example
5984
@end defmac
5985
5986
@cindex Previous Variable
5987
@cindex Variable, Precious
5988
Running @command{configure} in different environments can be extremely
5989
dangerous. If for instance the user runs @samp{CC=bizarre-cc
5990
./configure}, then the cache, @file{config.h} and many other output
5991
files will depend upon @command{bizarre-cc} being the C compiler. If
5992
for some reason the user runs @command{/configure} again, or if it is
5993
run via @samp{./config.status --recheck}, (@xref{Automatic Remaking},
5994
and @pxref{config.status Invocation}), then the configuration can be
5995
inconsistent, composed of results depending upon two different
5996
compilers.
5997
5998
Such variables are named @dfn{precious variables}, and can be declared
5999
as such by @code{AC_ARG_VAR}.
6000
6001
@defmac AC_ARG_VAR (@var{variable}, @var{description})
6002
@acindex ARG_VAR
6003
Declare @var{variable} is a precious variable, and include its
6004
@var{description} in the variable section of @samp{./configure --help}.
6005
6006
Being precious means that
6007
@itemize @minus
6008
@item
6009
@var{variable} is @code{AC_SUBST}'d.
6010
6011
@item
6012
@var{variable} is kept in the cache including if it was not specified on
6013
the @samp{./configure} command line. Indeed, while @command{configure}
6014
can notice the definition of @code{CC} in @samp{./configure
6015
CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc
6016
./configure}, which, unfortunately, is what most users do.
6017
6018
@item
6019
@var{variable} is checked for consistency between two
6020
@command{configure} runs. For instance:
6021
6022
@example
6023
$ @kbd{./configure --silent --config-cache}
6024
$ @kbd{CC=cc ./configure --silent --config-cache}
6025
configure: error: `CC' was not set in the previous run
6026
configure: error: changes in the environment can compromise \
6027
the build
6028
configure: error: run `make distclean' and/or \
6029
`rm config.cache' and start over
6030
@end example
6031
6032
@noindent
6033
and similarly if the variable is unset, or if its content is changed.
6034
6035
6036
@item
6037
@var{variable} is kept during automatic reconfiguration
6038
(@pxref{config.status Invocation}) as if it had been passed as a command
6039
line argument, including when no cache is used:
6040
6041
@example
6042
$ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent}
6043
$ @kbd{./config.status --recheck}
6044
running /bin/sh ./configure undeclared_var=raboof --silent \
6045
CC=/usr/bin/cc --no-create --no-recursion
6046
@end example
6047
@end itemize
6048
@end defmac
6049
6050
6051
@node Caching Results
6052
@section Caching Results
6053
@cindex Cache
6054
6055
To avoid checking for the same features repeatedly in various
6056
@command{configure} scripts (or in repeated runs of one script),
6057
@command{configure} can optionally save the results of many checks in a
6058
@dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script
6059
runs with caching enabled and finds a cache file, it reads the results
6060
of previous runs from the cache and avoids rerunning those checks. As a
6061
result, @command{configure} can then run much faster than if it had to
6062
perform all of the checks every time.
6063
6064
@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it})
6065
@acindex CACHE_VAL
6066
Ensure that the results of the check identified by @var{cache-id} are
6067
available. If the results of the check were in the cache file that was
6068
read, and @command{configure} was not given the @option{--quiet} or
6069
@option{--silent} option, print a message saying that the result was
6070
cached; otherwise, run the shell commands @var{commands-to-set-it}. If
6071
the shell commands are run to determine the value, the value will be
6072
saved in the cache file just before @command{configure} creates its output
6073
files. @xref{Cache Variable Names}, for how to choose the name of the
6074
@var{cache-id} variable.
6075
6076
The @var{commands-to-set-it} @emph{must have no side effects} except for
6077
setting the variable @var{cache-id}, see below.
6078
@end defmac
6079
6080
@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it})
6081
@acindex CACHE_CHECK
6082
A wrapper for @code{AC_CACHE_VAL} that takes care of printing the
6083
messages. This macro provides a convenient shorthand for the most
6084
common way to use these macros. It calls @code{AC_MSG_CHECKING} for
6085
@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and
6086
@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}.
6087
6088
The @var{commands-to-set-it} @emph{must have no side effects} except for
6089
setting the variable @var{cache-id}, see below.
6090
@end defmac
6091
6092
It is very common to find buggy macros using @code{AC_CACHE_VAL} or
6093
@code{AC_CACHE_CHECK}, because people are tempted to call
6094
@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that
6095
@emph{follows} the call to @code{AC_CACHE_VAL} should call
6096
@code{AC_DEFINE}, by examining the value of the cache variable. For
6097
instance, the following macro is broken:
6098
6099
@example
6100
@group
6101
AC_DEFUN([AC_SHELL_TRUE],
6102
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
6103
[ac_cv_shell_true_works=no
6104
true && ac_cv_shell_true_works=yes
6105
if test $ac_cv_shell_true_works = yes; then
6106
AC_DEFINE([TRUE_WORKS], 1
6107
[Define if `true(1)' works properly.])
6108
fi])
6109
])
6110
@end group
6111
@end example
6112
6113
@noindent
6114
This fails if the cache is enabled: the second time this macro is run,
6115
@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation
6116
is:
6117
6118
@example
6119
@group
6120
AC_DEFUN([AC_SHELL_TRUE],
6121
[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works],
6122
[ac_cv_shell_true_works=no
6123
true && ac_cv_shell_true_works=yes])
6124
if test $ac_cv_shell_true_works = yes; then
6125
AC_DEFINE([TRUE_WORKS], 1
6126
[Define if `true(1)' works properly.])
6127
fi
6128
])
6129
@end group
6130
@end example
6131
6132
Also, @var{commands-to-set-it} should not print any messages, for
6133
example with @code{AC_MSG_CHECKING}; do that before calling
6134
@code{AC_CACHE_VAL}, so the messages are printed regardless of whether
6135
the results of the check are retrieved from the cache or determined by
6136
running the shell commands.
6137
6138
@menu
6139
* Cache Variable Names:: Shell variables used in caches
6140
* Cache Files:: Files @command{configure} uses for caching
6141
* Cache Checkpointing:: Loading and saving the cache file
6142
@end menu
6143
6144
@node Cache Variable Names
6145
@subsection Cache Variable Names
6146
@cindex Cache variable
6147
6148
The names of cache variables should have the following format:
6149
6150
@example
6151
@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options}
6152
@end example
6153
6154
@noindent
6155
for example, @samp{ac_cv_header_stat_broken} or
6156
@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are:
6157
6158
@table @asis
6159
@item @var{package-prefix}
6160
An abbreviation for your package or organization; the same prefix you
6161
begin local Autoconf macros with, except lowercase by convention.
6162
For cache values used by the distributed Autoconf macros, this value is
6163
@samp{ac}.
6164
6165
@item @code{_cv_}
6166
Indicates that this shell variable is a cache value. This string
6167
@emph{must} be present in the variable name, including the leading
6168
underscore.
6169
6170
@item @var{value-type}
6171
A convention for classifying cache values, to produce a rational naming
6172
system. The values used in Autoconf are listed in @ref{Macro Names}.
6173
6174
@item @var{specific-value}
6175
Which member of the class of cache values this test applies to.
6176
For example, which function (@samp{alloca}), program (@samp{gcc}), or
6177
output variable (@samp{INSTALL}).
6178
6179
@item @var{additional-options}
6180
Any particular behavior of the specific member that this test applies to.
6181
For example, @samp{broken} or @samp{set}. This part of the name may
6182
be omitted if it does not apply.
6183
@end table
6184
6185
The values assigned to cache variables may not contain newlines.
6186
Usually, their values will be boolean (@samp{yes} or @samp{no}) or the
6187
names of files or functions; so this is not an important restriction.
6188
6189
@node Cache Files
6190
@subsection Cache Files
6191
6192
A cache file is a shell script that caches the results of configure
6193
tests run on one system so they can be shared between configure scripts
6194
and configure runs. It is not useful on other systems. If its contents
6195
are invalid for some reason, the user may delete or edit it.
6196
6197
By default, @command{configure} uses no cache file (technically, it uses
6198
@option{--cache-file=/dev/null}), to avoid problems caused by accidental
6199
use of stale cache files.
6200
6201
To enable caching, @command{configure} accepts @option{--config-cache} (or
6202
@option{-C}) to cache results in the file @file{config.cache}.
6203
Alternatively, @option{--cache-file=@var{file}} specifies that
6204
@var{file} be the cache file. The cache file is created if it does not
6205
exist already. When @command{configure} calls @command{configure} scripts in
6206
subdirectories, it uses the @option{--cache-file} argument so that they
6207
share the same cache. @xref{Subdirectories}, for information on
6208
configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro.
6209
6210
@file{config.status} only pays attention to the cache file if it is
6211
given the @option{--recheck} option, which makes it rerun
6212
@command{configure}.
6213
6214
It is wrong to try to distribute cache files for particular system types.
6215
There is too much room for error in doing that, and too much
6216
administrative overhead in maintaining them. For any features that
6217
can't be guessed automatically, use the standard method of the canonical
6218
system type and linking files (@pxref{Manual Configuration}).
6219
6220
The site initialization script can specify a site-wide cache file to
6221
use, instead of the usual per-program cache. In this case, the cache
6222
file will gradually accumulate information whenever someone runs a new
6223
@command{configure} script. (Running @command{configure} merges the new cache
6224
results with the existing cache file.) This may cause problems,
6225
however, if the system configuration (e.g. the installed libraries or
6226
compilers) changes and the stale cache file is not deleted.
6227
6228
@node Cache Checkpointing
6229
@subsection Cache Checkpointing
6230
6231
If your configure script, or a macro called from configure.ac, happens
6232
to abort the configure process, it may be useful to checkpoint the cache
6233
a few times at key points using @code{AC_CACHE_SAVE}. Doing so will
6234
reduce the amount of time it takes to re-run the configure script with
6235
(hopefully) the error that caused the previous abort corrected.
6236
6237
@c FIXME: Do we really want to document this guy?
6238
@defmac AC_CACHE_LOAD
6239
@acindex CACHE_LOAD
6240
Loads values from existing cache file, or creates a new cache file if a
6241
cache file is not found. Called automatically from @code{AC_INIT}.
6242
@end defmac
6243
6244
@defmac AC_CACHE_SAVE
6245
@acindex CACHE_SAVE
6246
Flushes all cached values to the cache file. Called automatically from
6247
@code{AC_OUTPUT}, but it can be quite useful to call
6248
@code{AC_CACHE_SAVE} at key points in configure.ac.
6249
@end defmac
6250
6251
For instance:
6252
6253
@example
6254
@r{ @dots{} AC_INIT, etc. @dots{}}
6255
@group
6256
# Checks for programs.
6257
AC_PROG_CC
6258
AC_PROG_GCC_TRADITIONAL
6259
@r{ @dots{} more program checks @dots{}}
6260
AC_CACHE_SAVE
6261
@end group
6262
6263
@group
6264
# Checks for libraries.
6265
AC_CHECK_LIB(nsl, gethostbyname)
6266
AC_CHECK_LIB(socket, connect)
6267
@r{ @dots{} more lib checks @dots{}}
6268
AC_CACHE_SAVE
6269
@end group
6270
6271
@group
6272
# Might abort...
6273
AM_PATH_GTK(1.0.2,, [AC_MSG_ERROR([GTK not in path])])
6274
AM_PATH_GTKMM(0.9.5,, [AC_MSG_ERROR([GTK not in path])])
6275
@end group
6276
@r{ @dots{} AC_OUTPUT, etc. @dots{}}
6277
@end example
6278
6279
@node Printing Messages
6280
@section Printing Messages
6281
@cindex Messages, from @command{configure}
6282
6283
@command{configure} scripts need to give users running them several kinds
6284
of information. The following macros print messages in ways appropriate
6285
for each kind. The arguments to all of them get enclosed in shell
6286
double quotes, so the shell performs variable and back-quote
6287
substitution on them.
6288
6289
These macros are all wrappers around the @code{echo} shell command.
6290
@command{configure} scripts should rarely need to run @code{echo} directly
6291
to print messages for the user. Using these macros makes it easy to
6292
change how and when each kind of message is printed; such changes need
6293
only be made to the macro definitions and all of the callers will change
6294
automatically.
6295
6296
To diagnose static issues, i.e., when @command{autoconf} is run, see
6297
@ref{Reporting Messages}.
6298
6299
@defmac AC_MSG_CHECKING (@var{feature-description})
6300
@acindex MSG_CHECKING
6301
Notify the user that @command{configure} is checking for a particular
6302
feature. This macro prints a message that starts with @samp{checking }
6303
and ends with @samp{...} and no newline. It must be followed by a call
6304
to @code{AC_MSG_RESULT} to print the result of the check and the
6305
newline. The @var{feature-description} should be something like
6306
@samp{whether the Fortran compiler accepts C++ comments} or @samp{for
6307
c89}.
6308
6309
This macro prints nothing if @command{configure} is run with the
6310
@option{--quiet} or @option{--silent} option.
6311
@end defmac
6312
6313
@defmac AC_MSG_RESULT (@var{result-description})
6314
@acindex MSG_RESULT
6315
Notify the user of the results of a check. @var{result-description} is
6316
almost always the value of the cache variable for the check, typically
6317
@samp{yes}, @samp{no}, or a file name. This macro should follow a call
6318
to @code{AC_MSG_CHECKING}, and the @var{result-description} should be
6319
the completion of the message printed by the call to
6320
@code{AC_MSG_CHECKING}.
6321
6322
This macro prints nothing if @command{configure} is run with the
6323
@option{--quiet} or @option{--silent} option.
6324
@end defmac
6325
6326
@defmac AC_MSG_NOTICE (@var{message})
6327
@acindex MSG_NOTICE
6328
Deliver the @var{message} to the user. It is useful mainly to print a
6329
general description of the overall purpose of a group of feature checks,
6330
e.g.,
6331
6332
@example
6333
AC_MSG_NOTICE([checking if stack overflow is detectable])
6334
@end example
6335
6336
This macro prints nothing if @command{configure} is run with the
6337
@option{--quiet} or @option{--silent} option.
6338
@end defmac
6339
6340
@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status})
6341
@acindex MSG_ERROR
6342
Notify the user of an error that prevents @command{configure} from
6343
completing. This macro prints an error message to the standard error
6344
output and exits @command{configure} with @var{exit-status} (1 by default).
6345
@var{error-description} should be something like @samp{invalid value
6346
$HOME for \$HOME}.
6347
6348
The @var{error-description} should start with a lower-case letter, and
6349
``cannot'' is preferred to ``can't''.
6350
@end defmac
6351
6352
@defmac AC_MSG_WARN (@var{problem-description})
6353
@acindex MSG_WARN
6354
Notify the @command{configure} user of a possible problem. This macro
6355
prints the message to the standard error output; @command{configure}
6356
continues running afterward, so macros that call @code{AC_MSG_WARN} should
6357
provide a default (back-up) behavior for the situations they warn about.
6358
@var{problem-description} should be something like @samp{ln -s seems to
6359
make hard links}.
6360
@end defmac
6361
6362
6363
6364
@c ====================================================== Programming in M4.
6365
6366
@node Programming in M4
6367
@chapter Programming in M4
6368
6369
Autoconf is written on top of two layers: @dfn{M4sugar}, which provides
6370
convenient macros for pure M4 programming, and @dfn{M4sh}, which
6371
provides macros dedicated to shell script generation.
6372
6373
As of this version of Autoconf, these two layers are still experimental,
6374
and their interface might change in the future. As a matter of fact,
6375
@emph{anything that is not documented must not be used}.
6376
6377
@menu
6378
* M4 Quotation:: Protecting macros from unwanted expansion
6379
* Invoking autom4te:: The Autoconf executables backbone
6380
* Programming in M4sugar:: Convenient pure M4 macros
6381
* Programming in M4sh:: Common Shell Constructs
6382
@end menu
6383
6384
@node M4 Quotation
6385
@section M4 Quotation
6386
@cindex quotation
6387
6388
@c FIXME: Grmph, yet another quoting myth: quotation has *never*
6389
@c prevented `expansion' of $1. Unless it refers to the expansion
6390
@c of the value of $1? Anyway, we need a rewrite here@dots{}
6391
6392
The most common brokenness of existing macros is an improper quotation.
6393
This section, which users of Autoconf can skip, but which macro writers
6394
@emph{must} read, first justifies the quotation scheme that was chosen
6395
for Autoconf and then ends with a rule of thumb. Understanding the
6396
former helps one to follow the latter.
6397
6398
@menu
6399
* Active Characters:: Characters that change the behavior of m4
6400
* One Macro Call:: Quotation and one macro call
6401
* Quotation and Nested Macros:: Macros calling macros
6402
* Changequote is Evil:: Worse than INTERCAL: M4 + changequote
6403
* Quadrigraphs:: Another way to escape special characters
6404
* Quotation Rule Of Thumb:: One parenthesis, one quote
6405
@end menu
6406
6407
@node Active Characters
6408
@subsection Active Characters
6409
6410
To fully understand where proper quotation is important, you first need
6411
to know what are the special characters in Autoconf: @samp{#} introduces
6412
a comment inside which no macro expansion is performed, @samp{,}
6413
separates arguments, @samp{[} and @samp{]} are the quotes themselves,
6414
and finally @samp{(} and @samp{)} (which @code{m4} tries to match by
6415
pairs).
6416
6417
In order to understand the delicate case of macro calls, we first have
6418
to present some obvious failures. Below they are ``obvious-ified'',
6419
although you find them in real life, they are usually in disguise.
6420
6421
Comments, introduced by a hash and running up to the newline, are opaque
6422
tokens to the top level: active characters are turned off, and there is
6423
no macro expansion:
6424
6425
@example
6426
# define([def], ine)
6427
@result{}# define([def], ine)
6428
@end example
6429
6430
Each time there can be a macro expansion, there is a quotation
6431
expansion; i.e., one level of quotes is stripped:
6432
6433
@example
6434
int tab[10];
6435
@result{}int tab10;
6436
[int tab[10];]
6437
@result{}int tab[10];
6438
@end example
6439
6440
Without this in mind, the reader will try hopelessly to use her macro
6441
@code{array}:
6442
6443
@example
6444
define([array], [int tab[10];])
6445
array
6446
@result{}int tab10;
6447
[array]
6448
@result{}array
6449
@end example
6450
6451
@noindent
6452
How can you correctly output the intended results@footnote{Using
6453
@code{defn}.}?
6454
6455
6456
@node One Macro Call
6457
@subsection One Macro Call
6458
6459
Let's proceed on the interaction between active characters and macros
6460
with this small macro, which just returns its first argument:
6461
6462
@example
6463
define([car], [$1])
6464
@end example
6465
6466
@noindent
6467
The two pairs of quotes above are not part of the arguments of
6468
@code{define}; rather, they are understood by the top level when it
6469
tries to find the arguments of @code{define}. Therefore, it is
6470
equivalent to write:
6471
6472
@example
6473
define(car, $1)
6474
@end example
6475
6476
@noindent
6477
But, while it is acceptable for a @file{configure.ac} to avoid unneeded
6478
quotes, it is bad practice for Autoconf macros which must both be more
6479
robust and also advocate perfect style.
6480
6481
At the top level, there are only two possible quotings: either you
6482
quote or you don't:
6483
6484
@example
6485
car(foo, bar, baz)
6486
@result{}foo
6487
[car(foo, bar, baz)]
6488
@result{}car(foo, bar, baz)
6489
@end example
6490
6491
Let's pay attention to the special characters:
6492
6493
@example
6494
car(#)
6495
@error{}EOF in argument list
6496
@end example
6497
6498
The closing parenthesis is hidden in the comment; with a hypothetical
6499
quoting, the top level understood it this way:
6500
6501
@example
6502
car([#)]
6503
@end example
6504
6505
@noindent
6506
Proper quotation, of course, fixes the problem:
6507
6508
@example
6509
car([#])
6510
@result{}#
6511
@end example
6512
6513
The reader will easily understand the following examples:
6514
6515
@example
6516
car(foo, bar)
6517
@result{}foo
6518
car([foo, bar])
6519
@result{}foo, bar
6520
car((foo, bar))
6521
@result{}(foo, bar)
6522
car([(foo], [bar)])
6523
@result{}(foo
6524
car([], [])
6525
@result{}
6526
car([[]], [[]])
6527
@result{}[]
6528
@end example
6529
6530
With this in mind, we can explore the cases where macros invoke
6531
macros@dots{}
6532
6533
6534
@node Quotation and Nested Macros
6535
@subsection Quotation and Nested Macros
6536
6537
The examples below use the following macros:
6538
6539
@example
6540
define([car], [$1])
6541
define([active], [ACT, IVE])
6542
define([array], [int tab[10]])
6543
@end example
6544
6545
Each additional embedded macro call introduces other possible
6546
interesting quotations:
6547
6548
@example
6549
car(active)
6550
@result{}ACT
6551
car([active])
6552
@result{}ACT, IVE
6553
car([[active]])
6554
@result{}active
6555
@end example
6556
6557
In the first case, the top level looks for the arguments of @code{car},
6558
and finds @samp{active}. Because @code{m4} evaluates its arguments
6559
before applying the macro, @samp{active} is expanded, which results in:
6560
6561
@example
6562
car(ACT, IVE)
6563
@result{}ACT
6564
@end example
6565
6566
@noindent
6567
In the second case, the top level gives @samp{active} as first and only
6568
argument of @code{car}, which results in:
6569
6570
@example
6571
active
6572
@result{}ACT, IVE
6573
@end example
6574
6575
@noindent
6576
i.e., the argument is evaluated @emph{after} the macro that invokes it.
6577
In the third case, @code{car} receives @samp{[active]}, which results in:
6578
6579
@example
6580
[active]
6581
@result{}active
6582
@end example
6583
6584
@noindent
6585
exactly as we already saw above.
6586
6587
The example above, applied to a more realistic example, gives:
6588
6589
@example
6590
car(int tab[10];)
6591
@result{}int tab10;
6592
car([int tab[10];])
6593
@result{}int tab10;
6594
car([[int tab[10];]])
6595
@result{}int tab[10];
6596
@end example
6597
6598
@noindent
6599
Huh? The first case is easily understood, but why is the second wrong,
6600
and the third right? To understand that, you must know that after
6601
@code{m4} expands a macro, the resulting text is immediately subjected
6602
to macro expansion and quote removal. This means that the quote removal
6603
occurs twice---first before the argument is passed to the @code{car}
6604
macro, and second after the @code{car} macro expands to the first
6605
argument.
6606
6607
As the author of the Autoconf macro @code{car}, you then consider it to
6608
be incorrect that your users have to double-quote the arguments of
6609
@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for
6610
quoted car:
6611
6612
@example
6613
define([qar], [[$1]])
6614
@end example
6615
6616
@noindent
6617
and check that @code{qar} is properly fixed:
6618
6619
@example
6620
qar([int tab[10];])
6621
@result{}int tab[10];
6622
@end example
6623
6624
@noindent
6625
Ahhh! That's much better.
6626
6627
But note what you've done: now that the arguments are literal strings,
6628
if the user wants to use the results of expansions as arguments, she has
6629
to use an @emph{unquoted} macro call:
6630
6631
@example
6632
qar(active)
6633
@result{}ACT
6634
@end example
6635
6636
@noindent
6637
where she wanted to reproduce what she used to do with @code{car}:
6638
6639
@example
6640
car([active])
6641
@result{}ACT, IVE
6642
@end example
6643
6644
@noindent
6645
Worse yet: she wants to use a macro that produces a set of @code{cpp}
6646
macros:
6647
6648
@example
6649
define([my_includes], [#include <stdio.h>])
6650
car([my_includes])
6651
@result{}#include <stdio.h>
6652
qar(my_includes)
6653
@error{}EOF in argument list
6654
@end example
6655
6656
This macro, @code{qar}, because it double quotes its arguments, forces
6657
its users to leave their macro calls unquoted, which is dangerous.
6658
Commas and other active symbols are interpreted by @code{m4} before
6659
they are given to the macro, often not in the way the users expect.
6660
Also, because @code{qar} behaves differently from the other macros,
6661
it's an exception that should be avoided in Autoconf.
6662
6663
@node Changequote is Evil
6664
@subsection @code{changequote} is Evil
6665
6666
The temptation is often high to bypass proper quotation, in particular
6667
when it's late at night. Then, many experienced Autoconf hackers
6668
finally surrender to the dark side of the force and use the ultimate
6669
weapon: @code{changequote}.
6670
6671
The M4 builtin @code{changequote} belongs to a set of primitives that
6672
allow one to adjust the syntax of the language to adjust it to her
6673
needs. For instance, by default M4 uses @samp{`} and @samp{'} as
6674
quotes, but in the context of shell programming (and actually of most
6675
programming languages), it's about the worst choice one can make:
6676
because of strings and back quoted expression in shell (such as
6677
@samp{'this'} and @samp{`that`}), because of literal characters in usual
6678
programming language (as in @samp{'0'}), there are many unbalanced
6679
@samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if
6680
not impossible. In order to make M4 useful in such a context, its
6681
designers have equipped it with @code{changequote}, which makes it
6682
possible to chose another pair of quotes. M4sugar, M4sh, Autoconf, and
6683
Autotest all have chosen to use @samp{[} and @samp{]}. Not especially
6684
because they are unlikely characters, but @emph{because they are
6685
characters unlikely to be unbalanced}.
6686
6687
There are other magic primitives, such as @code{changecom} to specify
6688
what syntactic forms are comments (it is common to see
6689
@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages),
6690
@code{changeword} and @code{changesyntax} to change other syntactic
6691
details (such as the character to denote the n-th argument, @samp{$} by
6692
default, the parenthesis around arguments etc.).
6693
6694
These primitives are really meant to make M4 more useful for specific
6695
domains: they should be considered like command line options:
6696
@option{--quotes}, @option{--comments}, @option{--words}, and
6697
@code{--syntax}. Nevertheless, they are implemented as M4 builtins, as
6698
it makes M4 libraries self contained (no need for additional options).
6699
6700
There lies the problem...
6701
6702
@sp 1
6703
6704
The problem is that it is then tempting to use them in the middle of an
6705
M4 script, as opposed to its initialization. This, if not carefully
6706
thought, can lead to disastrous effects: @emph{you are changing the
6707
language in the middle of the execution}. Changing and restoring the
6708
syntax is often not enough: if you happened to invoke macros in between,
6709
these macros will be lost, as the current syntax will probably not be
6710
the one they were implemented with.
6711
6712
@c FIXME: I've been looking for a short, real case example, but I
6713
@c lost them all :(
6714
6715
6716
@node Quadrigraphs
6717
@subsection Quadrigraphs
6718
@cindex quadrigraphs
6719
@cindex @samp{@@<:@@}
6720
@cindex @samp{@@:>@@}
6721
@cindex @samp{@@S|@@}
6722
@cindex @samp{@@%:@@}
6723
@cindex @samp{@@&t@@}
6724
6725
When writing an autoconf macro you may occasionally need to generate
6726
special characters that are difficult to express with the standard
6727
autoconf quoting rules. For example, you may need to output the regular
6728
expression @samp{[^[]}, which matches any character other than @samp{[}.
6729
This expression contains unbalanced brackets so it cannot be put easily
6730
into an M4 macro.
6731
6732
You can work around this problem by using one of the following
6733
@dfn{quadrigraphs}:
6734
6735
@table @samp
6736
@item @@<:@@
6737
@samp{[}
6738
@item @@:>@@
6739
@samp{]}
6740
@item @@S|@@
6741
@samp{$}
6742
@item @@%:@@
6743
@samp{#}
6744
@item @@&t@@
6745
Expands to nothing.
6746
@end table
6747
6748
Quadrigraphs are replaced at a late stage of the translation process,
6749
after @command{m4} is run, so they do not get in the way of M4 quoting.
6750
For example, the string @samp{^@@<:@@}, independently of its quotation,
6751
will appear as @samp{^[} in the output.
6752
6753
The empty quadrigraph can be used:
6754
6755
@itemize @minus
6756
@item to mark explicitly trailing spaces
6757
6758
Trailing spaces are smashed by @command{autom4te}. This is a feature.
6759
6760
@item to produce other quadrigraphs
6761
6762
For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}.
6763
6764
@item to escape @emph{occurrences} of forbidden patterns
6765
6766
For instance you might want to mention @code{AC_FOO} is a comment, while
6767
still being sure that @command{autom4te} will still catch unexpanded
6768
@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}.
6769
@end itemize
6770
6771
The name @samp{@@&t@@} was suggested by Paul Eggert:
6772
6773
@quotation
6774
I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my
6775
own invention, but the @samp{t} came from the source code of the
6776
@sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame),
6777
and which used @samp{mt} to denote the empty string. In C, it would
6778
have looked like something like:
6779
6780
@example
6781
char const mt[] = "";
6782
@end example
6783
6784
@noindent
6785
but of course the source code was written in Algol 68.
6786
6787
I don't know where he got @samp{mt} from: it could have been his own
6788
invention, and I suppose it could have been a common pun around the
6789
Cambridge University computer lab at the time.
6790
@end quotation
6791
6792
@node Quotation Rule Of Thumb
6793
@subsection Quotation Rule Of Thumb
6794
6795
To conclude, the quotation rule of thumb is:
6796
6797
@center @emph{One pair of quotes per pair of parentheses.}
6798
6799
Never over-quote, never under-quote, in particular in the definition of
6800
macros. In the few places where the macros need to use brackets
6801
(usually in C program text or regular expressions), properly quote
6802
@emph{the arguments}!
6803
6804
It is common to read Autoconf programs with snippets like:
6805
6806
@example
6807
AC_TRY_LINK(
6808
changequote(<<, >>)dnl
6809
<<#include <time.h>
6810
#ifndef tzname /* For SGI. */
6811
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
6812
#endif>>,
6813
changequote([, ])dnl
6814
[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no)
6815
@end example
6816
6817
@noindent
6818
which is incredibly useless since @code{AC_TRY_LINK} is @emph{already}
6819
double quoting, so you just need:
6820
6821
@example
6822
AC_TRY_LINK(
6823
[#include <time.h>
6824
#ifndef tzname /* For SGI. */
6825
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
6826
#endif],
6827
[atoi (*tzname);],
6828
[ac_cv_var_tzname=yes],
6829
[ac_cv_var_tzname=no])
6830
@end example
6831
6832
@noindent
6833
The M4-fluent reader will note that these two examples are rigorously
6834
equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)}
6835
and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these
6836
quotes are not part of the arguments!
6837
6838
Simplified, the example above is just doing this:
6839
6840
@example
6841
changequote(<<, >>)dnl
6842
<<[]>>
6843
changequote([, ])dnl
6844
@end example
6845
6846
@noindent
6847
instead of simply:
6848
6849
@example
6850
[[]]
6851
@end example
6852
6853
6854
With macros that do not double quote their arguments (which is the
6855
rule), double-quote the (risky) literals:
6856
6857
@example
6858
AC_LINK_IFELSE([AC_LANG_PROGRAM(
6859
[[#include <time.h>
6860
#ifndef tzname /* For SGI. */
6861
extern char *tzname[]; /* RS6000 and others reject char **tzname. */
6862
#endif]],
6863
[atoi (*tzname);])],
6864
[ac_cv_var_tzname=yes],
6865
[ac_cv_var_tzname=no])
6866
@end example
6867
6868
See @xref{Quadrigraphs}, for what to do if you run into a hopeless case
6869
where quoting does not suffice.
6870
6871
When you create a @command{configure} script using newly written macros,
6872
examine it carefully to check whether you need to add more quotes in
6873
your macros. If one or more words have disappeared in the @code{m4}
6874
output, you need more quotes. When in doubt, quote.
6875
6876
However, it's also possible to put on too many layers of quotes. If
6877
this happens, the resulting @command{configure} script will contain
6878
unexpanded macros. The @command{autoconf} program checks for this problem
6879
by doing @samp{grep AC_ configure}.
6880
6881
@node Invoking autom4te
6882
@section Invoking @command{autom4te}
6883
6884
The Autoconf suite, including M4sugar, M4sh, and Autotest in addition to
6885
Autoconf per se, heavily rely on M4. All these different uses revealed
6886
common needs factored into a layer over @command{m4}:
6887
@command{autom4te}@footnote{
6888
@c
6889
Yet another great name for Lars J. Aas.
6890
@c
6891
}.
6892
6893
@command{autom4te} should basically considered as a replacement of
6894
@command{m4} itself. In particular, its handling of command line
6895
arguments is modeled after M4's:
6896
6897
@example
6898
autom4te @var{options} @var{files}
6899
@end example
6900
6901
@noindent
6902
where the @var{files} are directly passed to @command{m4}. In addition
6903
to the regular expansion, it handles the replacement of the quadrigraphs
6904
(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the
6905
output. It supports an extended syntax for the @var{files}:
6906
6907
@table @file
6908
@item @var{file}.m4f
6909
This file is an M4 frozen file. Note that @emph{all the previous files
6910
are ignored}. See the option @option{--melt} for the rationale.
6911
6912
@item @var{file}?
6913
If found in the library path, the @var{file} is included for expansion,
6914
otherwise it is ignored instead of triggering a failure.
6915
@end table
6916
6917
@sp 1
6918
6919
Of course, it supports the Autoconf common subset of options:
6920
6921
@table @option
6922
@item --help
6923
@itemx -h
6924
Print a summary of the command line options and exit.
6925
6926
@item --version
6927
@itemx -V
6928
Print the version number of Autoconf and exit.
6929
6930
@item --verbose
6931
@itemx -v
6932
Report processing steps.
6933
6934
@item --debug
6935
@itemx -d
6936
Don't remove the temporary files and be even more verbose.
6937
6938
@item --include=@var{dir}
6939
@itemx -I @var{dir}
6940
Also look for input files in @var{dir}. Multiple invocations
6941
accumulate. Contrary to M4 but in agreement with common sense,
6942
directories are browsed from last to first.
6943
6944
@item --output=@var{file}
6945
@itemx -o @var{file}
6946
Save output (script or trace) to @var{file}. The file @option{-} stands
6947
for the standard output.
6948
@end table
6949
6950
@sp 1
6951
6952
As an extension of @command{m4}, it includes the following options:
6953
6954
@table @option
6955
@item --warnings=@var{category}
6956
@itemx -W @var{category}
6957
@evindex WARNINGS
6958
@c FIXME: Point to the M4sugar macros, not Autoconf's.
6959
Report the warnings related to @var{category} (which can actually be a
6960
comma separated list). @xref{Reporting Messages}, macro
6961
@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special
6962
values include:
6963
6964
@table @samp
6965
@item all
6966
report all the warnings
6967
6968
@item none
6969
report none
6970
6971
@item error
6972
treats warnings as errors
6973
6974
@item no-@var{category}
6975
disable warnings falling into @var{category}
6976
@end table
6977
6978
Warnings about @samp{syntax} are enabled by default, and the environment
6979
variable @code{WARNINGS}, a comma separated list of categories, is
6980
honored. @command{autom4te -W @var{category}} will actually
6981
behave as if you had run:
6982
6983
@example
6984
autom4te --warnings=syntax,$WARNINGS,@var{category}
6985
@end example
6986
6987
@noindent
6988
If you want to disable @command{autom4te}'s defaults and
6989
@code{WARNINGS}, but (for example) enable the warnings about obsolete
6990
constructs, you would use @option{-W none,obsolete}.
6991
6992
@cindex Back trace
6993
@cindex Macro invocation stack
6994
@command{autom4te} displays a back trace for errors, but not for
6995
warnings; if you want them, just pass @option{-W error}. For instance,
6996
on this @file{configure.ac}:
6997
6998
@example
6999
AC_DEFUN([INNER],
7000
[AC_TRY_RUN([exit (0)])])
7001
7002
AC_DEFUN([OUTER],
7003
[INNER])
7004
7005
AC_INIT
7006
OUTER
7007
@end example
7008
7009
@noindent
7010
you get:
7011
7012
@example
7013
$ @kbd{autom4te -l autoconf -Wcross}
7014
configure.ac:8: warning: AC_TRY_RUN called without default \
7015
to allow cross compiling
7016
$ @kbd{autom4te -l autoconf -Wcross,error}
7017
configure.ac:8: error: AC_TRY_RUN called without default \
7018
to allow cross compiling
7019
acgeneral.m4:3044: AC_TRY_RUN is expanded from...
7020
configure.ac:2: INNER is expanded from...
7021
configure.ac:5: OUTER is expanded from...
7022
configure.ac:8: the top level
7023
@end example
7024
7025
@item --melt
7026
@itemx -m
7027
Do not use frozen files. Any argument @code{@var{file}.m4f} will be
7028
replaced with @code{@var{file}.m4}. This helps tracing the macros which
7029
are executed only when the files are frozen, typically
7030
@code{m4_define}. For instance, running:
7031
7032
@example
7033
autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4
7034
@end example
7035
7036
@noindent
7037
is roughly equivalent to running:
7038
7039
@example
7040
m4 1.m4 2.m4 3.m4 4.m4 input.m4
7041
@end example
7042
7043
@noindent
7044
while
7045
7046
@example
7047
autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4
7048
@end example
7049
7050
@noindent
7051
is equivalent to:
7052
7053
@example
7054
m4 --reload-state=4.m4f input.m4
7055
@end example
7056
7057
@item --freeze
7058
@itemx -f
7059
Produce a frozen state file. @command{autom4te} freezing is stricter
7060
than M4's: it must produce no warnings, and no output other than empty
7061
lines (a line with white spaces is @emph{not} empty) and comments
7062
(starting with @samp{#}). Please, note that contrary to @command{m4},
7063
this options takes no argument:
7064
7065
@example
7066
autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f
7067
@end example
7068
7069
@noindent
7070
corresponds to
7071
7072
@example
7073
m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f
7074
@end example
7075
7076
@item --mode=@var{octal-mode}
7077
@itemx -m @var{octal-mode}
7078
Set the mode of the non traces output to @var{octal-mode}. By default,
7079
@samp{0666}.
7080
@end table
7081
7082
@sp 1
7083
7084
@cindex @file{autom4te.cache}
7085
As another additional feature over @command{m4}, @command{autom4te}
7086
caches its results. GNU M4 is able to produce a regular output and
7087
traces at the same time. Traces are heavily used in the GNU Build
7088
System: @command{autoheader} uses them to build @file{config.h.in},
7089
@command{autoreconf} to determine what GNU Build System components are
7090
used, @command{automake} to ``parse'' @file{configure.ac} etc. To save
7091
the long runs of @command{m4}, traces are cached while performing
7092
regular expansion, and conversely. This cache is (actually, the caches
7093
are) stored in the directory @file{autom4te.cache}. @emph{It can safely
7094
be removed} at any moment (especially if for some reason
7095
@command{autom4te} considers it is trashed).
7096
7097
@table @option
7098
@item --force
7099
@itemx -f
7100
Do not consider the cache (but update it anyway).
7101
@end table
7102
7103
@sp 1
7104
7105
Because traces are so important to the GNU Build System,
7106
@command{autom4te} provides high level tracing features as compared to
7107
M4, and helps exploiting the cache:
7108
7109
@table @option
7110
@item --trace=@var{macro}[:@var{format}]
7111
@itemx -t @var{macro}[:@var{format}]
7112
Trace the invocations to @var{macro} according to the @var{format}.
7113
Multiple @option{--trace} arguments can be used to list several macros.
7114
Multiple @option{--trace} arguments for a single macro are not
7115
cumulative; instead, you should just make @var{format} as long as
7116
needed.
7117
7118
The @var{format} is a regular string, with newlines if desired, and
7119
several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can
7120
use the following special escapes:
7121
7122
@table @samp
7123
@item $$
7124
The character @samp{$}.
7125
7126
@item $f
7127
The filename from which @var{macro} is called.
7128
7129
@item $l
7130
The line number from which @var{macro} is called.
7131
7132
@item $d
7133
The depth of the @var{macro} call. This is an M4 technical detail that
7134
you probably don't want to know about.
7135
7136
@item $n
7137
The name of the @var{macro}.
7138
7139
@item $@var{num}
7140
The @var{num}th argument of the call to @var{macro}.
7141
7142
@item $@@
7143
@itemx $@var{sep}@@
7144
@itemx $@{@var{separator}@}@@
7145
All the arguments passed to @var{macro}, separated by the character
7146
@var{sep} or the string @var{separator} (@samp{,} by default). Each
7147
argument is quoted, i.e. enclosed in a pair of square brackets.
7148
7149
@item $*
7150
@itemx $@var{sep}*
7151
@itemx $@{@var{separator}@}*
7152
As above, but the arguments are not quoted.
7153
7154
@item $%
7155
@itemx $@var{sep}%
7156
@itemx $@{@var{separator}@}%
7157
As above, but the arguments are not quoted, all new line characters in
7158
the arguments are smashed, and the default separator is @samp{:}.
7159
7160
The escape @samp{$%} produces single-line trace outputs (unless you put
7161
newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do
7162
not.
7163
@end table
7164
7165
@xref{autoconf Invocation}, for examples of trace uses.
7166
7167
@item --preselect=@var{macro}
7168
@itemx -p @var{macro}
7169
Cache the traces of @var{macro}, but do not enable traces. This is
7170
especially important to save cpu cycles in the future. For instance,
7171
when invoked, @command{autoconf} preselects all the macros that
7172
@command{autoheader}, @code{automake}, @code{autoreconf} etc. will
7173
trace, so that running @command{m4} is not needed to trace them: the
7174
cache suffices. This results in a huge speed-up.
7175
@end table
7176
7177
@sp 1
7178
7179
@cindex Autom4te Library
7180
Finally, @command{autom4te} introduces the concept of @dfn{Autom4te
7181
libraries}. They consists in a powerful yet extremely simple feature:
7182
sets of combined command line arguments:
7183
7184
@table @option
7185
@item --language=@var{language}
7186
@itemx -l =@var{language}
7187
Use the @var{language} Autom4te library. Current languages include:
7188
7189
@table @code
7190
@item M4sugar
7191
create M4sugar output.
7192
7193
@item M4sh
7194
create M4sh executable shell scripts.
7195
7196
@item Autotest
7197
create Autotest executable test suites.
7198
7199
@item Autoconf
7200
create Autoconf executable configure scripts.
7201
@end table
7202
@end table
7203
7204
@cindex @file{autom4te.cfg}
7205
As an example, if Autoconf is installed in its default location,
7206
@file{/usr/local}, running @samp{autom4te -l m4sugar foo.m4} is strictly
7207
equivalent to running @samp{autom4te --include /usr/local/share/autoconf
7208
m4sugar/m4sugar.m4f --warning syntax foo.m4}. Recursive expansion
7209
applies: running @samp{autom4te -l m4sh foo.m4}, is the same as
7210
@samp{autom4te --language M4sugar m4sugar/m4sh.m4f foo.m4}, i.e.,
7211
@samp{autom4te --include /usr/local/share/autoconf m4sugar/m4sugar.m4f
7212
m4sugar/m4sh.m4f --mode 777 foo.m4}. The definition of the languages is
7213
stored in @file{autom4te.cfg}.
7214
7215
7216
@node Programming in M4sugar
7217
@section Programming in M4sugar
7218
7219
@cindex M4sugar
7220
M4 by itself provides only a small, but sufficient, set of all-purpose
7221
macros. M4sugar introduces additional generic macros. Its name was
7222
coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
7223
M4sugar''.
7224
7225
@menu
7226
* Redefined M4 Macros:: M4 builtins changed in M4sugar
7227
* Evaluation Macros:: More quotation and evaluation control
7228
* Forbidden Patterns:: Catching unexpanded macros
7229
@end menu
7230
7231
@node Redefined M4 Macros
7232
@subsection Redefined M4 Macros
7233
7234
With a few exceptions, all the M4 native macros are moved in the
7235
@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
7236
@code{m4_define} etc.
7237
7238
Some M4 macros are redefined, and are slightly incompatible with their
7239
native equivalent.
7240
7241
@defmac dnl
7242
@msindex dnl
7243
This macro kept its original name: no @code{m4_dnl} is defined.
7244
@end defmac
7245
7246
@defmac m4_defn (@var{macro})
7247
@msindex defn
7248
Contrary to the M4 builtin, this macro fails if @var{macro} is not
7249
defined. See @code{m4_undefine}.
7250
@end defmac
7251
7252
@defmac m4_exit (@var{exit-status})
7253
@msindex m4_exit
7254
This macro corresponds to @code{m4exit}.
7255
@end defmac
7256
7257
@defmac m4_if (@var{comment})
7258
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal})
7259
@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, ...)
7260
@msindex m4_if
7261
This macro corresponds to @code{ifelse}.
7262
@end defmac
7263
7264
@defmac m4_undefine (@var{macro})
7265
@msindex undefine
7266
Contrary to the M4 builtin, this macro fails if @var{macro} is not
7267
defined. Use
7268
7269
@example
7270
m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])])
7271
@end example
7272
7273
@noindent
7274
to recover the behavior of the builtin.
7275
@end defmac
7276
7277
@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
7278
@msindex bpatsubst
7279
This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
7280
is kept for future versions of M4sh, on top of @sc{gnu} M4 which will
7281
provide extended regular expression syntax via @code{epatsubst}.
7282
@end defmac
7283
7284
@defmac m4_popdef (@var{macro})
7285
@msindex defn
7286
Contrary to the M4 builtin, this macro fails if @var{macro} is not
7287
defined. See @code{m4_undefine}.
7288
@end defmac
7289
7290
@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
7291
@msindex bregexp
7292
This macro corresponds to @code{regexp}. The name @code{m4_regexp}
7293
is kept for future versions of M4sh, on top of @sc{gnu} M4 which will
7294
provide extended regular expression syntax via @code{eregexp}.
7295
@end defmac
7296
7297
@defmac m4_wrap (@var{text})
7298
@msindex m4_wrap
7299
This macro corresponds to @code{m4wrap}.
7300
7301
You are encouraged to end @var{text} with @samp{[]}, so that there are
7302
no risks that two consecutive invocations of @code{m4_wrap} result in an
7303
unexpected pasting of tokens, as in
7304
7305
@example
7306
m4_define([foo], [Foo])
7307
m4_define([bar], [Bar])
7308
m4_define([foobar], [FOOBAR])
7309
m4_wrap([bar])
7310
m4_wrap([foo])
7311
@result{}FOOBAR
7312
@end example
7313
@end defmac
7314
7315
@node Evaluation Macros
7316
@subsection Evaluation Macros
7317
7318
The following macros give some control over the order of the evaluation
7319
by adding or removing levels of quotes. They are meant for hard core M4
7320
programmers.
7321
7322
@defmac m4_dquote (@var{arg1}, ...)
7323
@msindex dquote
7324
Return the arguments as a quoted list of quoted arguments.
7325
@end defmac
7326
7327
@defmac m4_quote (@var{arg1}, ...)
7328
@msindex quote
7329
Return the arguments as a single entity, i.e., wrap them into a pair of
7330
quotes.
7331
@end defmac
7332
7333
The following example aims at emphasing the difference between (i), not
7334
using these macros, (ii), using @code{m4_quote}, and (iii), using
7335
@code{m4_dquote}.
7336
7337
@example
7338
$ @kbd{cat example.m4}
7339
# Over quote, so that quotes are visible.
7340
m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]])
7341
m4_divert(0)dnl
7342
show(a, b)
7343
show(m4_quote(a, b))
7344
show(m4_dquote(a, b))
7345
$ @kbd{autom4te -l m4sugar example.m4}
7346
$1 = a, $@@ = [a],[b]
7347
$1 = a,b, $@@ = [a,b]
7348
$1 = [a],[b], $@@ = [[a],[b]]
7349
@end example
7350
7351
7352
7353
@node Forbidden Patterns
7354
@subsection Forbidden Patterns
7355
7356
M4sugar provides a means to define suspicious patterns, patterns
7357
describing tokens which should not be found in the output. For
7358
instance, if an Autoconf @file{configure} script includes tokens such as
7359
@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went
7360
wrong (typically a macro was not evaluated because of over quotation).
7361
7362
M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
7363
7364
@defmac m4_pattern_forbid (@var{pattern})
7365
@msindex pattern_forbid
7366
Declare no token matching @var{pattern} must be found in the output.
7367
Comments are not checked; this can be a problem if, for instance, you
7368
have some macro left unexpanded after an @samp{#include}. No consensus
7369
is currently found in the Autoconf community, as some people consider it
7370
should be valid to name macros in comments (which doesn't makes sense to
7371
the author of this documentation, as @samp{#}-comments should document
7372
the output, not the input, documented vy @samp{dnl}-comments).
7373
@end defmac
7374
7375
Of course, you might encounter exceptions to these generic rules, for
7376
instance you might have to refer to @samp{$m4_flags}.
7377
7378
@defmac m4_pattern_allow (@var{pattern})
7379
@msindex pattern_allow
7380
Any token matching @var{pattern} is allowed, including if it matches an
7381
@code{m4_pattern_forbid} pattern.
7382
@end defmac
7383
7384
@node Programming in M4sh
7385
@section Programming in M4sh
7386
7387
@c FIXME: Eventually will become a chapter, as it is not related to
7388
@c programming in M4 per se.
7389
7390
M4sh provides portable alternatives for some common shell constructs
7391
that unfortunately are not portable in practice.
7392
7393
@defmac AS_DIRNAME (@var{pathname})
7394
@msindex DIRNAME
7395
Return the directory portion of @var{pathname}, using the algorithm
7396
required by @sc{posix}. @xref{Limitations of Usual Tools}, for more
7397
details about what this returns and why it is more portable than the
7398
@command{dirname} command.
7399
@end defmac
7400
7401
@c=================================================== Writing Autoconf Macros.
7402
7403
@node Writing Autoconf Macros
7404
@chapter Writing Autoconf Macros
7405
7406
When you write a feature test that could be applicable to more than one
7407
software package, the best thing to do is encapsulate it in a new macro.
7408
Here are some instructions and guidelines for writing Autoconf macros.
7409
7410
@menu
7411
* Macro Definitions:: Basic format of an Autoconf macro
7412
* Macro Names:: What to call your new macros
7413
* Reporting Messages:: Notifying @command{autoconf} users
7414
* Dependencies Between Macros:: What to do when macros depend on other macros
7415
* Obsoleting Macros:: Warning about old ways of doing things
7416
* Coding Style:: Writing Autoconf macros @`a la Autoconf
7417
@end menu
7418
7419
@node Macro Definitions
7420
@section Macro Definitions
7421
7422
@acindex DEFUN
7423
Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
7424
similar to the M4 builtin @code{m4_define} macro. In addition to
7425
defining a macro, @code{AC_DEFUN} adds to it some code that is used to
7426
constrain the order in which macros are called (@pxref{Prerequisite
7427
Macros}).
7428
7429
An Autoconf macro definition looks like this:
7430
7431
@example
7432
AC_DEFUN(@var{macro-name}, @var{macro-body})
7433
@end example
7434
7435
You can refer to any arguments passed to the macro as @samp{$1},
7436
@samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info,
7437
GNU m4}, for more complete information on writing M4 macros.
7438
7439
Be sure to properly quote both the @var{macro-body} @emph{and} the
7440
@var{macro-name} to avoid any problems if the macro happens to have
7441
been previously defined.
7442
7443
Each macro should have a header comment that gives its prototype, and a
7444
brief description. When arguments have default values, display them in
7445
the prototype. For example:
7446
7447
@example
7448
# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
7449
# --------------------------------------
7450
m4_define([AC_MSG_ERROR],
7451
[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}])
7452
@end example
7453
7454
Comments about the macro should be left in the header comment. Most
7455
other comments will make their way into @file{configure}, so just keep
7456
using @samp{#} to introduce comments.
7457
7458
@cindex @code{dnl}
7459
If you have some very special comments about pure M4 code, comments
7460
that make no sense in @file{configure} and in the header comment, then
7461
use the builtin @code{dnl}: it causes @code{m4} to discard the text
7462
through the next newline.
7463
7464
Keep in mind that @code{dnl} is rarely needed to introduce comments;
7465
@code{dnl} is more useful to get rid of the newlines following macros
7466
that produce no output, such as @code{AC_REQUIRE}.
7467
7468
7469
@node Macro Names
7470
@section Macro Names
7471
7472
All of the Autoconf macros have all-uppercase names starting with
7473
@samp{AC_} to prevent them from accidentally conflicting with other
7474
text. All shell variables that they use for internal purposes have
7475
mostly-lowercase names starting with @samp{ac_}. To ensure that your
7476
macros don't conflict with present or future Autoconf macros, you should
7477
prefix your own macro names and any shell variables they use with some
7478
other sequence. Possibilities include your initials, or an abbreviation
7479
for the name of your organization or software package.
7480
7481
Most of the Autoconf macros' names follow a structured naming convention
7482
that indicates the kind of feature check by the name. The macro names
7483
consist of several words, separated by underscores, going from most
7484
general to most specific. The names of their cache variables use the
7485
same convention (@pxref{Cache Variable Names}, for more information on
7486
them).
7487
7488
The first word of the name after @samp{AC_} usually tells the category
7489
of feature being tested. Here are the categories used in Autoconf for
7490
specific test macros, the kind of macro that you are more likely to
7491
write. They are also used for cache variables, in all-lowercase. Use
7492
them where applicable; where they're not, invent your own categories.
7493
7494
@table @code
7495
@item C
7496
C language builtin features.
7497
@item DECL
7498
Declarations of C variables in header files.
7499
@item FUNC
7500
Functions in libraries.
7501
@item GROUP
7502
@sc{unix} group owners of files.
7503
@item HEADER
7504
Header files.
7505
@item LIB
7506
C libraries.
7507
@item PATH
7508
The full path names to files, including programs.
7509
@item PROG
7510
The base names of programs.
7511
@item MEMBER
7512
Members of aggregates.
7513
@item SYS
7514
Operating system features.
7515
@item TYPE
7516
C builtin or declared types.
7517
@item VAR
7518
C variables in libraries.
7519
@end table
7520
7521
After the category comes the name of the particular feature being
7522
tested. Any further words in the macro name indicate particular aspects
7523
of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
7524
behavior of the @code{utime} function when called with a @code{NULL}
7525
pointer.
7526
7527
An internal macro should have a name that starts with an underscore;
7528
Autoconf internals should therefore start with @samp{_AC_}.
7529
Additionally, a macro that is an internal subroutine of another macro
7530
should have a name that starts with an underscore and the name of that
7531
other macro, followed by one or more words saying what the internal
7532
macro does. For example, @code{AC_PATH_X} has internal macros
7533
@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}.
7534
7535
@node Reporting Messages
7536
@section Reporting Messages
7537
@cindex Messages, from @command{autoconf}
7538
7539
When macros statically diagnose abnormal situations, benign or fatal,
7540
they should report them using these macros. For dynamic issues, i.e.,
7541
when @command{configure} is run, see @ref{Printing Messages}.
7542
7543
@defmac AC_DIAGNOSE (@var{category}, @var{message})
7544
@acindex DIAGNOSE
7545
Report @var{message} as a warning (or as an error if requested by the
7546
user) if it falls into the @var{category}. You are encouraged to use
7547
standard categories, which currently include:
7548
7549
@table @samp
7550
@item all
7551
messages that don't fall into one of the following category. Use of an
7552
empty @var{category} is equivalent.
7553
7554
@item cross
7555
related to cross compilation issues.
7556
7557
@item obsolete
7558
use of an obsolete construct.
7559
7560
@item syntax
7561
dubious syntactic constructs, incorrectly ordered macro calls.
7562
@end table
7563
@end defmac
7564
7565
@defmac AC_WARNING (@var{message})
7566
@acindex WARNING
7567
Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
7568
strongly encouraged to use a finer grained category.
7569
@end defmac
7570
7571
@defmac AC_FATAL (@var{message})
7572
@acindex FATAL
7573
Report a severe error @var{message}, and have @command{autoconf} die.
7574
@end defmac
7575
7576
When the user runs @samp{autoconf -W error}, warnings from
7577
@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
7578
@ref{autoconf Invocation}.
7579
7580
@node Dependencies Between Macros
7581
@section Dependencies Between Macros
7582
7583
Some Autoconf macros depend on other macros having been called first in
7584
order to work correctly. Autoconf provides a way to ensure that certain
7585
macros are called if needed and a way to warn the user if macros are
7586
called in an order that might cause incorrect operation.
7587
7588
@menu
7589
* Prerequisite Macros:: Ensuring required information
7590
* Suggested Ordering:: Warning about possible ordering problems
7591
@end menu
7592
7593
@node Prerequisite Macros
7594
@subsection Prerequisite Macros
7595
7596
A macro that you write might need to use values that have previously
7597
been computed by other macros. For example, @code{AC_DECL_YYTEXT}
7598
examines the output of @code{flex} or @code{lex}, so it depends on
7599
@code{AC_PROG_LEX} having been called first to set the shell variable
7600
@code{LEX}.
7601
7602
Rather than forcing the user of the macros to keep track of the
7603
dependencies between them, you can use the @code{AC_REQUIRE} macro to do
7604
it automatically. @code{AC_REQUIRE} can ensure that a macro is only
7605
called if it is needed, and only called once.
7606
7607
@defmac AC_REQUIRE (@var{macro-name})
7608
@acindex REQUIRE
7609
If the M4 macro @var{macro-name} has not already been called, call it
7610
(without any arguments). Make sure to quote @var{macro-name} with
7611
square brackets. @var{macro-name} must have been defined using
7612
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
7613
that it has been called.
7614
7615
@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it
7616
must not be called from the top level.
7617
@end defmac
7618
7619
@code{AC_REQUIRE} is often misunderstood. It really implements
7620
dependencies between macros in the sense that if one macro depends upon
7621
another, the latter will be expanded @emph{before} the body of the
7622
former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the
7623
body of @code{FOO}. For instance, this definition of macros:
7624
7625
@example
7626
@group
7627
AC_DEFUN([TRAVOLTA],
7628
[test "$body_temparature_in_celsius" -gt "38" &&
7629
dance_floor=occupied])
7630
AC_DEFUN([NEWTON_JOHN],
7631
[test "$hair_style" = "curly" &&
7632
dance_floor=occupied])
7633
@end group
7634
7635
@group
7636
AC_DEFUN([RESERVE_DANCE_FLOOR],
7637
[if date | grep '^Sat.*pm' >/dev/null 2>&1; then
7638
AC_REQUIRE([TRAVOLTA])
7639
AC_REQUIRE([NEWTON_JOHN])
7640
fi])
7641
@end group
7642
@end example
7643
7644
@noindent
7645
with this @file{configure.ac}
7646
7647
@example
7648
AC_INIT
7649
RESERVE_DANCE_FLOOR
7650
if test "$dance_floor" = occupied; then
7651
AC_MSG_ERROR([cannot pick up here, let's move])
7652
fi
7653
@end example
7654
7655
@noindent
7656
will not leave you with a better chance to meet a kindred soul at
7657
other times than Saturday night since it expands into:
7658
7659
@example
7660
@group
7661
test "$body_temperature_in_Celsius" -gt "38" &&
7662
dance_floor=occupied
7663
test "$hair_style" = "curly" &&
7664
dance_floor=occupied
7665
fi
7666
if date | grep '^Sat.*pm' >/dev/null 2>&1; then
7667
7668
7669
fi
7670
@end group
7671
@end example
7672
7673
This behavior was chosen on purpose: (i) it prevents messages in
7674
required macros from interrupting the messages in the requiring macros;
7675
(ii) it avoids bad surprises when shell conditionals are used, as in:
7676
7677
@example
7678
@group
7679
if @dots{}; then
7680
AC_REQUIRE([SOME_CHECK])
7681
fi
7682
@dots{}
7683
SOME_CHECK
7684
@end group
7685
@end example
7686
7687
7688
You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a
7689
macro. You can use @code{dnl} to avoid the empty lines they leave.
7690
7691
@node Suggested Ordering
7692
@subsection Suggested Ordering
7693
7694
Some macros should be run before another macro if both are called, but
7695
neither @emph{requires} that the other be called. For example, a macro
7696
that changes the behavior of the C compiler should be called before any
7697
macros that run the C compiler. Many of these dependencies are noted in
7698
the documentation.
7699
7700
Autoconf provides the @code{AC_BEFORE} macro to warn users when macros
7701
with this kind of dependency appear out of order in a
7702
@file{configure.ac} file. The warning occurs when creating
7703
@command{configure} from @file{configure.ac}, not when running
7704
@command{configure}.
7705
7706
For example, @code{AC_PROG_CPP} checks whether the C compiler
7707
can run the C preprocessor when given the @option{-E} option. It should
7708
therefore be called after any macros that change which C compiler is
7709
being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains:
7710
7711
@example
7712
AC_BEFORE([$0], [AC_PROG_CPP])dnl
7713
@end example
7714
7715
@noindent
7716
This warns the user if a call to @code{AC_PROG_CPP} has already occurred
7717
when @code{AC_PROG_CC} is called.
7718
7719
@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name})
7720
@acindex BEFORE
7721
Make @code{m4} print a warning message to the standard error output if
7722
@var{called-macro-name} has already been called. @var{this-macro-name}
7723
should be the name of the macro that is calling @code{AC_BEFORE}. The
7724
macro @var{called-macro-name} must have been defined using
7725
@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate
7726
that it has been called.
7727
@end defmac
7728
7729
@node Obsoleting Macros
7730
@section Obsoleting Macros
7731
7732
Configuration and portability technology has evolved over the years.
7733
Often better ways of solving a particular problem are developed, or
7734
ad-hoc approaches are systematized. This process has occurred in many
7735
parts of Autoconf. One result is that some of the macros are now
7736
considered @dfn{obsolete}; they still work, but are no longer considered
7737
the best thing to do, hence they should be replaced with more modern
7738
macros. Ideally, @command{autoupdate} should substitute the old macro calls
7739
with their modern implementation.
7740
7741
Autoconf provides a simple means to obsolete a macro.
7742
7743
@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message})
7744
@acindex DEFUN
7745
@acindex AU_DEFUN
7746
Define @var{old-macro} as @var{implementation}. The only difference
7747
with @code{AC_DEFUN} is that the user will be warned that
7748
@var{old-macro} is now obsolete.
7749
7750
If she then uses @command{autoupdate}, the call to @var{old-macro} will be
7751
replaced by the modern @var{implementation}. The additional
7752
@var{message} is then printed.
7753
@end defmac
7754
7755
@node Coding Style
7756
@section Coding Style
7757
7758
The Autoconf macros follow a strict coding style. You are encouraged to
7759
follow this style, especially if you intend to distribute your macro,
7760
either by contributing it to Autoconf itself, or via other means.
7761
7762
The first requirement is to pay great attention to the quotation, for
7763
more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
7764
7765
Do not try to invent new interfaces. It is likely that there is a macro
7766
in Autoconf that resembles the macro you are defining: try to stick to
7767
this existing interface (order of arguments, default values, etc.). We
7768
@emph{are} conscious that some of these interfaces are not perfect;
7769
nevertheless, when harmless, homogeneity should be preferred over
7770
creativity.
7771
7772
Be careful about clashes both between M4 symbols and between shell
7773
variables.
7774
7775
If you stick to the suggested M4 naming scheme (@pxref{Macro Names}),
7776
you are unlikely to generate conflicts. Nevertheless, when you need to
7777
set a special value, @emph{avoid using a regular macro name}; rather,
7778
use an ``impossible'' name. For instance, up to version 2.13, the macro
7779
@code{AC_SUBST} used to remember what @var{symbol}s were already defined
7780
by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name.
7781
But since there is a macro named @code{AC_SUBST_FILE}, it was just
7782
impossible to @samp{AC_SUBST(FILE)}! In this case,
7783
@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should
7784
have been used (yes, with the parentheses)@dots{}or better yet, high-level
7785
macros such as @code{AC_EXPAND_ONCE}.
7786
7787
No Autoconf macro should ever enter the user-variable name space; i.e.,
7788
except for the variables that are the actual result of running the
7789
macro, all shell variables should start with @code{ac_}. In
7790
addition, small macros or any macro that is likely to be embedded in
7791
other macros should be careful not to use obvious names.
7792
7793
@cindex @code{dnl}
7794
Do not use @code{dnl} to introduce comments: most of the comments you
7795
are likely to write are either header comments which are not output
7796
anyway, or comments that should make their way into @file{configure}.
7797
There are exceptional cases where you do want to comment special M4
7798
constructs, in which case @code{dnl} is right, but keep in mind that it
7799
is unlikely.
7800
7801
M4 ignores the leading spaces before each argument, use this feature to
7802
indent in such a way that arguments are (more or less) aligned with the
7803
opening parenthesis of the macro being called. For instance, instead of
7804
7805
@example
7806
AC_CACHE_CHECK(for EMX OS/2 environment,
7807
ac_cv_emxos2,
7808
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])],
7809
[ac_cv_emxos2=yes], [ac_cv_emxos2=no])])
7810
@end example
7811
7812
@noindent
7813
write
7814
7815
@example
7816
AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
7817
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
7818
[ac_cv_emxos2=yes],
7819
[ac_cv_emxos2=no])])
7820
@end example
7821
7822
@noindent
7823
or even
7824
7825
@example
7826
AC_CACHE_CHECK([for EMX OS/2 environment],
7827
[ac_cv_emxos2],
7828
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([],
7829
[return __EMX__;])],
7830
[ac_cv_emxos2=yes],
7831
[ac_cv_emxos2=no])])
7832
@end example
7833
7834
When using @code{AC_TRY_RUN} or any macro that cannot work when
7835
cross-compiling, provide a pessimistic value (typically @samp{no}).
7836
7837
Feel free to use various tricks to prevent auxiliary tools, such as
7838
syntax-highlighting editors, from behaving improperly. For instance,
7839
instead of:
7840
7841
@example
7842
m4_bpatsubst([$1], [$"])
7843
@end example
7844
7845
@noindent
7846
use
7847
7848
@example
7849
m4_bpatsubst([$1], [$""])
7850
@end example
7851
7852
@noindent
7853
so that Emacsen do not open a endless ``string'' at the first quote.
7854
For the same reasons, avoid:
7855
7856
@example
7857
test $[#] != 0
7858
@end example
7859
7860
@noindent
7861
and use:
7862
7863
@example
7864
test $[@@%:@@] != 0
7865
@end example
7866
7867
@noindent
7868
Otherwise, the closing bracket would be hidden inside a @samp{#}-comment,
7869
breaking the bracket-matching highlighting from Emacsen. Note the
7870
preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do
7871
not escape when it is unneeded. Common examples of useless quotation
7872
are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}),
7873
etc. If you add portability issues to the picture, you'll prefer
7874
@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something
7875
better than hacking Autoconf @code{:-)}.
7876
7877
When using @command{sed}, don't use @option{-e} except for indenting
7878
purpose. With the @code{s} command, the preferred separator is @samp{/}
7879
unless @samp{/} itself is used in the command, in which case you should
7880
use @samp{,}.
7881
7882
@xref{Macro Definitions}, for details on how to define a macro. If a
7883
macro doesn't use @code{AC_REQUIRE} and it is expected to never be the
7884
object of an @code{AC_REQUIRE} directive, then use @code{define}. In
7885
case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE}
7886
statements should be at the beginning of the macro, @code{dnl}'ed.
7887
7888
You should not rely on the number of arguments: instead of checking
7889
whether an argument is missing, test that it is not empty. It provides
7890
both a simpler and a more predictable interface to the user, and saves
7891
room for further arguments.
7892
7893
Unless the macro is short, try to leave the closing @samp{])} at the
7894
beginning of a line, followed by a comment that repeats the name of the
7895
macro being defined. This introduces an additional newline in
7896
@command{configure}; normally, that is not a problem, but if you want to
7897
remove it you can use @samp{[]dnl} on the last line. You can similarly
7898
use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl}
7899
is recommended instead of @samp{dnl} to ensure that M4 does not
7900
interpret the @samp{dnl} as being attached to the preceding text or
7901
macro output. For example, instead of:
7902
7903
@example
7904
AC_DEFUN([AC_PATH_X],
7905
[AC_MSG_CHECKING([for X])
7906
AC_REQUIRE_CPP()
7907
@r{# @dots{}omitted@dots{}}
7908
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
7909
fi])
7910
@end example
7911
7912
@noindent
7913
you would write:
7914
7915
@example
7916
AC_DEFUN([AC_PATH_X],
7917
[AC_REQUIRE_CPP()[]dnl
7918
AC_MSG_CHECKING([for X])
7919
@r{# @dots{}omitted@dots{}}
7920
AC_MSG_RESULT([libraries $x_libraries, headers $x_includes])
7921
fi[]dnl
7922
])# AC_PATH_X
7923
@end example
7924
7925
If the macro is long, try to split it into logical chunks. Typically,
7926
macros that check for a bug in a function and prepare its
7927
@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform
7928
this setup. Do not hesitate to introduce auxiliary macros to factor
7929
your code.
7930
7931
In order to highlight the recommended coding style, here is a macro
7932
written the old way:
7933
7934
@example
7935
dnl Check for EMX on OS/2.
7936
dnl _AC_EMXOS2
7937
AC_DEFUN(_AC_EMXOS2,
7938
[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2,
7939
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)],
7940
ac_cv_emxos2=yes, ac_cv_emxos2=no)])
7941
test "$ac_cv_emxos2" = yes && EMXOS2=yes])
7942
@end example
7943
7944
@noindent
7945
and the new way:
7946
7947
@example
7948
# _AC_EMXOS2
7949
# ----------
7950
# Check for EMX on OS/2.
7951
define([_AC_EMXOS2],
7952
[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2],
7953
[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])],
7954
[ac_cv_emxos2=yes],
7955
[ac_cv_emxos2=no])])
7956
test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl
7957
])# _AC_EMXOS2
7958
@end example
7959
7960
7961
7962
7963
@c ============================================= Portable Shell Programming
7964
7965
@node Portable Shell
7966
@chapter Portable Shell Programming
7967
7968
When writing your own checks, there are some shell-script programming
7969
techniques you should avoid in order to make your code portable. The
7970
Bourne shell and upward-compatible shells like the Korn shell and Bash
7971
have evolved over the years, but to prevent trouble, do not take
7972
advantage of features that were added after @sc{unix} version 7, circa
7973
1977. You should not use shell functions, aliases, negated character
7974
classes, or other features that are not found in all Bourne-compatible
7975
shells; restrict yourself to the lowest common denominator. Even
7976
@code{unset} is not supported by all shells! Also, include a space
7977
after the exclamation point in interpreter specifications, like this:
7978
7979
@example
7980
#! /usr/bin/perl
7981
@end example
7982
7983
@noindent
7984
If you omit the space before the path, then 4.2@sc{bsd} based systems
7985
(such as Sequent DYNIX) will ignore the line, because they interpret
7986
@samp{#! /} as a 4-byte magic number. Some old systems have quite
7987
small limits on the length of the @samp{#!} line too, for instance 32
7988
bytes (not including the newline) on SunOS 4.
7989
7990
The set of external programs you should run in a @command{configure} script
7991
is fairly small. @xref{Utilities in Makefiles,, Utilities in
7992
Makefiles, standards, GNU Coding Standards}, for the list. This
7993
restriction allows users to start out with a fairly small set of
7994
programs and build the rest, avoiding too many interdependencies between
7995
packages.
7996
7997
Some of these external utilities have a portable subset of features; see
7998
@ref{Limitations of Usual Tools}.
7999
8000
@menu
8001
* Shellology:: A zoology of shells
8002
* Here-Documents:: Quirks and tricks
8003
* File Descriptors:: FDs and redirections
8004
* File System Conventions:: File- and pathnames
8005
* Shell Substitutions:: Variable and command expansions
8006
* Assignments:: Varying side effects of assignments
8007
* Special Shell Variables:: Variables you should not change
8008
* Limitations of Builtins:: Portable use of not so portable /bin/sh
8009
* Limitations of Usual Tools:: Portable use of portable tools
8010
* Limitations of Make:: Portable Makefiles
8011
@end menu
8012
8013
@node Shellology
8014
@section Shellology
8015
8016
There are several families of shells, most prominently the Bourne
8017
family and the C shell family which are deeply incompatible. If you
8018
want to write portable shell scripts, avoid members of the C shell
8019
family.
8020
8021
Below we describe some of the members of the Bourne shell family.
8022
8023
@table @asis
8024
@item Ash
8025
@cindex Ash
8026
@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a
8027
light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are
8028
fixed in the 0.3.x series, but portable shell scripts should workaround
8029
them, since version 0.2 is still shipped with many @sc{gnu}/Linux
8030
distributions.
8031
8032
To be compatible with Ash 0.2:
8033
8034
@itemize @minus
8035
@item
8036
don't use @samp{$?} after expanding empty or unset variables:
8037
8038
@example
8039
foo=
8040
false
8041
$foo
8042
echo "Don't use it: $?"
8043
@end example
8044
8045
@item
8046
don't use command substitution within variable expansion:
8047
8048
@example
8049
cat $@{FOO=`bar`@}
8050
@end example
8051
8052
@item
8053
beware that single builtin substitutions are not performed by a sub
8054
shell, hence their effect applies to the current shell! @xref{Shell
8055
Substitutions}, item ``Command Substitution''.
8056
@end itemize
8057
8058
@item Bash
8059
@cindex Bash
8060
To detect whether you are running @command{bash}, test if
8061
@code{BASH_VERSION} is set. To disable its extensions and require
8062
@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX
8063
Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for
8064
details.
8065
8066
@item Bash 2.05 and later
8067
@cindex Bash 2.05 and later
8068
Versions 2.05 and later of @command{bash} use a different format for the
8069
output of the @command{set} builtin, designed to make evaluating this
8070
output easier. However, this output is not compatible with earlier
8071
versions of @command{bash} (or with many other shells, probably). So if
8072
you use @command{bash} 2.05 or higher to execute @command{configure},
8073
you'll need to use @command{bash} 2.05 for all other build tasks as well.
8074
8075
@item @command{/usr/xpg4/bin/sh} on Solaris
8076
@prindex @command{/usr/xpg4/bin/sh} on Solaris
8077
The @sc{posix}-compliant Bourne shell on a Solaris system is
8078
@command{/usr/xpg4/bin/sh} and is part of an extra optional package.
8079
There is no extra charge for this package, but it is also not part of a
8080
minimal OS install and therefore some folks may not have it.
8081
8082
@item Zsh
8083
@cindex Zsh
8084
To detect whether you are running @command{zsh}, test if
8085
@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not}
8086
compatible with the Bourne shell: you have to run @samp{emulate sh} and
8087
set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility,
8088
zsh, The Z Shell Manual}, for details.
8089
8090
Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3.
8091
@end table
8092
8093
The following discussion between Russ Allbery and Robert Lipe is worth
8094
reading:
8095
8096
@noindent
8097
Russ Allbery:
8098
8099
@quotation
8100
The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell
8101
leads to a permanent deadlock. Vendors don't want to break user's
8102
existant shell scripts, and there are some corner cases in the Bourne
8103
shell that are not completely compatible with a @sc{posix} shell. Thus,
8104
vendors who have taken this route will @emph{never} (OK@dots{}``never say
8105
never'') replace the Bourne shell (as @command{/bin/sh}) with a
8106
@sc{posix} shell.
8107
@end quotation
8108
8109
@noindent
8110
Robert Lipe:
8111
8112
@quotation
8113
This is exactly the problem. While most (at least most System V's) do
8114
have a Bourne shell that accepts shell functions most vendor
8115
@command{/bin/sh} programs are not the @sc{posix} shell.
8116
8117
So while most modern systems do have a shell _somewhere_ that meets the
8118
@sc{posix} standard, the challenge is to find it.
8119
@end quotation
8120
8121
@node Here-Documents
8122
@section Here-Documents
8123
8124
Don't rely on @samp{\} being preserved just because it has no special
8125
meaning together with the next symbol. in the native @command{/bin/sh}
8126
on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with
8127
unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\}
8128
use @samp{\\} to get @samp{\}.
8129
8130
With OpenBSD 2.7's @command{/bin/sh}
8131
8132
@example
8133
@group
8134
$ @kbd{cat <<EOF
8135
> \" \\
8136
> EOF}
8137
" \
8138
@end group
8139
@end example
8140
8141
@noindent
8142
and with Bash:
8143
8144
@example
8145
@group
8146
bash-2.04$ @kbd{cat <<EOF
8147
> \" \\
8148
> EOF}
8149
\" \
8150
@end group
8151
@end example
8152
8153
8154
Many older shells (including the Bourne shell) implement here-documents
8155
inefficiently. Users can generally speed things up by using a faster
8156
shell, e.g., by using the command @samp{bash ./configure} rather than
8157
plain @samp{./configure}.
8158
8159
Some shells can be extremely inefficient when there are a lot of
8160
here-documents inside a single statement. For instance if your
8161
@file{configure.ac} includes something like:
8162
8163
@example
8164
@group
8165
if <cross_compiling>; then
8166
assume this and that
8167
else
8168
check this
8169
check that
8170
check something else
8171
@dots{}
8172
on and on forever
8173
@dots{}
8174
fi
8175
@end group
8176
@end example
8177
8178
A shell parses the whole @code{if}/@code{fi} construct, creating
8179
temporary files for each here document in it. Some shells create links
8180
for such here-documents on every @code{fork}, so that the clean-up code
8181
they had installed correctly removes them. It is creating the links
8182
that the shell can take forever.
8183
8184
Moving the tests out of the @code{if}/@code{fi}, or creating multiple
8185
@code{if}/@code{fi} constructs, would improve the performance
8186
significantly. Anyway, this kind of construct is not exactly the
8187
typical use of Autoconf. In fact, it's even not recommended, because M4
8188
macros can't look into shell conditionals, so we may fail to expand a
8189
macro when it was expanded before in a conditional path, and the
8190
condition turned out to be false at run-time, and we end up not
8191
executing the macro at all.
8192
8193
@node File Descriptors
8194
@section File Descriptors
8195
8196
Some file descriptors shall not be used, since some systems, admittedly
8197
arcane, use them for special purpose:
8198
8199
@display
8200
3 --- some systems may open it to @samp{/dev/tty}.
8201
4 --- used on the Kubota Titan.
8202
@end display
8203
8204
Don't redirect several times the same file descriptor, as you are doomed
8205
to failure under Ultrix.
8206
8207
@example
8208
ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995
8209
UWS V4.4 (Rev. 11)
8210
$ @kbd{eval 'echo matter >fullness' >void}
8211
illegal io
8212
$ @kbd{eval '(echo matter >fullness)' >void}
8213
illegal io
8214
$ @kbd{(eval '(echo matter >fullness)') >void}
8215
Ambiguous output redirect.
8216
@end example
8217
8218
@noindent
8219
In each case the expected result is of course @file{fullness} containing
8220
@samp{matter} and @file{void} being empty.
8221
8222
Don't try to redirect the standard error of a command substitution: it
8223
must be done @emph{inside} the command substitution: when running
8224
@samp{: `cd /zorglub` 2>/dev/null} expect the error message to
8225
escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly.
8226
8227
It is worth noting that Zsh (but not Ash nor Bash) makes it possible
8228
in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}.
8229
8230
Most shells, if not all (including Bash, Zsh, Ash), output traces on
8231
stderr, even for sub-shells. This might result in undesired content
8232
if you meant to capture the standard-error output of the inner command:
8233
8234
@example
8235
$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'}
8236
$ @kbd{cat stderr}
8237
+ eval echo foo >&2
8238
+ echo foo
8239
foo
8240
$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'}
8241
$ @kbd{cat stderr}
8242
+ eval 'echo foo >&2'
8243
foo
8244
$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'}
8245
@i{# Traces on startup files deleted here.}
8246
$ @kbd{cat stderr}
8247
+zsh:1> eval echo foo >&2
8248
+zsh:1> echo foo
8249
foo
8250
@end example
8251
8252
@noindent
8253
You'll appreciate the various levels of detail@dots{}
8254
8255
One workaround is to grep out uninteresting lines, hoping not to remove
8256
good ones@dots{}
8257
8258
Don't try to move/delete open files, such as in @samp{exec >foo; mv foo
8259
bar}, see @xref{Limitations of Builtins}, @command{mv} for more details.
8260
8261
@node File System Conventions
8262
@section File System Conventions
8263
8264
While @command{autoconf} and friends will usually be run on some Unix
8265
variety, it can and will be used on other systems, most notably @sc{dos}
8266
variants. This impacts several assumptions regarding file and
8267
path names.
8268
8269
@noindent
8270
For example, the following code:
8271
8272
@example
8273
case $foo_dir in
8274
/*) # Absolute
8275
;;
8276
*)
8277
foo_dir=$dots$foo_dir ;;
8278
esac
8279
@end example
8280
8281
@noindent
8282
will fail to properly detect absolute paths on those systems, because
8283
they can use a drivespec, and will usually use a backslash as directory
8284
separator. The canonical way to check for absolute paths is:
8285
8286
@example
8287
case $foo_dir in
8288
[\\/]* | ?:[\\/]* ) # Absolute
8289
;;
8290
*)
8291
foo_dir=$dots$foo_dir ;;
8292
esac
8293
@end example
8294
8295
@noindent
8296
Make sure you quote the brackets if appropriate and keep the backslash as
8297
first character (@pxref{Limitations of Builtins}).
8298
8299
Also, because the colon is used as part of a drivespec, these systems don't
8300
use it as path separator. When creating or accessing paths, use the
8301
@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this
8302
to the appropriate value (@samp{:} or @samp{;}) when it starts up.
8303
8304
File names need extra care as well. While @sc{dos}-based environments
8305
that are Unixy enough to run @command{autoconf} (such as DJGPP) will
8306
usually be able to handle long file names properly, there are still
8307
limitations that can seriously break packages. Several of these issues
8308
can be easily detected by the
8309
@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk}
8310
package.
8311
8312
A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to
8313
indicate where they apply: @sc{sfn} means the issues are only relevant to
8314
plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn}
8315
identifies problems that exist even under Windows.
8316
8317
@table @asis
8318
@item No multiple dots (@sc{sfn})
8319
@sc{dos} cannot handle multiple dots in filenames. This is an especially
8320
important thing to remember when building a portable configure script,
8321
as @command{autoconf} uses a .in suffix for template files.
8322
8323
This is perfectly OK on Unices:
8324
8325
@example
8326
AC_CONFIG_HEADER(config.h)
8327
AC_CONFIG_FILES([source.c foo.bar])
8328
AC_OUTPUT
8329
@end example
8330
8331
@noindent
8332
but it causes problems on @sc{dos}, as it requires @samp{config.h.in},
8333
@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable
8334
to @sc{dos}-based environments, you should use this instead:
8335
8336
@example
8337
AC_CONFIG_HEADER(config.h:config.hin)
8338
AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
8339
AC_OUTPUT
8340
@end example
8341
8342
@item No leading dot (@sc{sfn})
8343
@sc{dos} cannot handle filenames that start with a dot. This is usually
8344
not a very important issue for @command{autoconf}.
8345
8346
@item Case insensitivity (@sc{lfn})
8347
@sc{dos} is case insensitive, so you cannot, for example, have both a
8348
file called @samp{INSTALL} and a directory called @samp{install}. This
8349
also affects @command{make}; if there's a file called @samp{INSTALL} in
8350
the directory, @command{make install} will do nothing (unless the
8351
@samp{install} target is marked as PHONY).
8352
8353
@item The 8+3 limit (@sc{sfn})
8354
Because the @sc{dos} file system only stores the first 8 characters of
8355
the filename and the first 3 of the extension, those must be unique.
8356
That means that @file{foobar-part1.c}, @file{foobar-part2.c} and
8357
@file{foobar-prettybird.c} all resolve to the same filename
8358
(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and
8359
@file{foo.bartender}.
8360
8361
Note: This is not usually a problem under Windows, as it uses numeric
8362
tails in the short version of filenames to make them unique. However, a
8363
registry setting can turn this behaviour off. While this makes it
8364
possible to share file trees containing long file names between @sc{sfn}
8365
and @sc{lfn} environments, it also means the above problem applies there
8366
as well.
8367
8368
@item Invalid characters
8369
Some characters are invalid in @sc{dos} filenames, and should therefore
8370
be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\},
8371
@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}.
8372
In a @sc{sfn} environment, other characters are also invalid. These
8373
include @samp{+}, @samp{,}, @samp{[} and @samp{]}.
8374
@end table
8375
8376
@node Shell Substitutions
8377
@section Shell Substitutions
8378
8379
Contrary to a persistent urban legend, the Bourne shell does not
8380
systematically split variables and backquoted expressions, in particular
8381
on the right-hand side of assignments and in the argument of @code{case}.
8382
For instance, the following code:
8383
8384
@example
8385
case "$given_srcdir" in
8386
.) top_srcdir="`echo "$dots" | sed 's,/$,,'`"
8387
*) top_srcdir="$dots$given_srcdir" ;;
8388
esac
8389
@end example
8390
8391
@noindent
8392
is more readable when written as:
8393
8394
@example
8395
case $given_srcdir in
8396
.) top_srcdir=`echo "$dots" | sed 's,/$,,'`
8397
*) top_srcdir=$dots$given_srcdir ;;
8398
esac
8399
@end example
8400
8401
@noindent
8402
and in fact it is even @emph{more} portable: in the first case of the
8403
first attempt, the computation of @code{top_srcdir} is not portable,
8404
since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}.
8405
Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"}
8406
the same way. There is just no portable way to use double-quoted
8407
strings inside double-quoted backquoted expressions (pfew!).
8408
8409
@table @code
8410
@item $@@
8411
@cindex @samp{"$@@"}
8412
One of the most famous shell-portability issues is related to
8413
@samp{"$@@"}: when there are no positional arguments, it is supposed to
8414
be equivalent to nothing. But some shells, for instance under Digital
8415
Unix 4.0 and 5.0, will then replace it with an empty argument. To be
8416
portable, use @samp{$@{1+"$@@"@}}.
8417
8418
@item $@{@var{var}:-@var{value}@}
8419
@cindex $@{@var{var}:-@var{value}@}
8420
Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the
8421
colon for any shell substitution, and complain and die.
8422
8423
@item $@{@var{var}=@var{literal}@}
8424
@cindex $@{@var{var}=@var{literal}@}
8425
Be sure to quote:
8426
8427
@example
8428
: $@{var='Some words'@}
8429
@end example
8430
8431
@noindent
8432
otherwise some shells, such as on Digital Unix V 5.0, will die because
8433
of a ``bad substitution''.
8434
8435
Solaris' @command{/bin/sh} has a frightening bug in its interpretation
8436
of this. Imagine you need set a variable to a string containing
8437
@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh}
8438
when the affected variable was already set. This bug can be exercised
8439
by running:
8440
8441
@example
8442
$ @kbd{unset foo}
8443
$ @kbd{foo=$@{foo='@}'@}}
8444
$ @kbd{echo $foo}
8445
@}
8446
$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is}
8447
$ @kbd{echo $foo}
8448
@}
8449
$ @kbd{foo=$@{foo='@}'@}}
8450
$ @kbd{echo $foo}
8451
@}@}
8452
^ ugh!
8453
@end example
8454
8455
It seems that @samp{@}} is interpreted as matching @samp{$@{}, even
8456
though it is enclosed in single quotes. The problem doesn't happen
8457
using double quotes.
8458
8459
@item $@{@var{var}=@var{expanded-value}@}
8460
@cindex $@{@var{var}=@var{expanded-value}@}
8461
On Ultrix,
8462
running
8463
8464
@example
8465
default="yu,yaa"
8466
: $@{var="$default"@}
8467
@end example
8468
8469
@noindent
8470
will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of
8471
each char will be set. You won't observe the phenomenon using a simple
8472
@samp{echo $var} since apparently the shell resets the 8th bit when it
8473
expands $var. Here are two means to make this shell confess its sins:
8474
8475
@example
8476
$ @kbd{cat -v <<EOF
8477
$var
8478
EOF}
8479
@end example
8480
8481
@noindent
8482
and
8483
8484
@example
8485
$ @kbd{set | grep '^var=' | cat -v}
8486
@end example
8487
8488
One classic incarnation of this bug is:
8489
8490
@example
8491
default="a b c"
8492
: $@{list="$default"@}
8493
for c in $list; do
8494
echo $c
8495
done
8496
@end example
8497
8498
@noindent
8499
You'll get @samp{a b c} on a single line. Why? Because there are no
8500
spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th
8501
bit set, hence no IFS splitting is performed!!!
8502
8503
One piece of good news is that Ultrix works fine with @samp{:
8504
$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is
8505
then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of
8506
@var{default}!
8507
8508
The portable way out consists in using a double assignment, to switch
8509
the 8th bit twice on Ultrix:
8510
8511
@example
8512
list=$@{list="$default"@}
8513
@end example
8514
8515
@noindent
8516
@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety,
8517
use:
8518
8519
@example
8520
test "$@{var+set@}" = set || var=@var{@{value@}}
8521
@end example
8522
8523
8524
@item `@var{commands}`
8525
@cindex `@var{commands}`
8526
@cindex Command Substitution
8527
While in general it makes no sense, do not substitute a single builtin
8528
with side effects as Ash 0.2, trying to optimize, does not fork a
8529
sub-shell to perform the command.
8530
8531
For instance, if you wanted to check that @command{cd} is silent, do not
8532
use @samp{test -z "`cd /`"} because the following can happen:
8533
8534
@example
8535
$ @kbd{pwd}
8536
/tmp
8537
$ @kbd{test -n "`cd /`" && pwd}
8538
/
8539
@end example
8540
8541
@noindent
8542
The result of @samp{foo=`exit 1`} is left as an exercise to the reader.
8543
8544
8545
@item $(@var{commands})
8546
@cindex $(@var{commands})
8547
This construct is meant to replace @samp{`@var{commands}`}; they can be
8548
nested while this is impossible to do portably with back quotes.
8549
Unfortunately it is not yet widely supported. Most notably, even recent
8550
releases of Solaris don't support it:
8551
8552
@example
8553
$ @kbd{showrev -c /bin/sh | grep version}
8554
Command version: SunOS 5.8 Generic 109324-02 February 2001
8555
$ @kbd{echo $(echo blah)}
8556
syntax error: `(' unexpected
8557
@end example
8558
8559
@noindent
8560
nor does @sc{irix} 6.5's Bourne shell:
8561
@example
8562
$ @kbd{uname -a}
8563
IRIX firebird-image 6.5 07151432 IP22
8564
$ @kbd{echo $(echo blah)}
8565
$(echo blah)
8566
@end example
8567
@end table
8568
8569
8570
@node Assignments
8571
@section Assignments
8572
8573
When setting several variables in a row, be aware that the order of the
8574
evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo}
8575
gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use
8576
@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
8577
8578
Don't rely on the exit status of an assignment: Ash 0.2 does not change
8579
the status and propagates that of the last statement:
8580
8581
@example
8582
$ @kbd{false || foo=bar; echo $?}
8583
1
8584
$ @kbd{false || foo=`:`; echo $?}
8585
0
8586
@end example
8587
8588
@noindent
8589
and to make things even worse, @sc{qnx 4.25} just sets the exit status
8590
to 0 in any case:
8591
8592
@example
8593
$ @kbd{foo=`exit 1`; echo $?}
8594
0
8595
@end example
8596
8597
To assign default values, follow this algorithm:
8598
8599
@enumerate
8600
@item
8601
If the default value is a literal and does not contain any closing
8602
brace, use:
8603
8604
@example
8605
: $@{var='my literal'@}
8606
@end example
8607
8608
@item
8609
If the default value contains no closing brace, has to be expanded, and
8610
the variable being initialized will never be IFS-split (i.e., it's not a
8611
list), then use:
8612
8613
@example
8614
: $@{var="$default"@}
8615
@end example
8616
8617
@item
8618
If the default value contains no closing brace, has to be expanded, and
8619
the variable being initialized will be IFS-split (i.e., it's a list),
8620
then use:
8621
8622
@example
8623
var=$@{var="$default"@}
8624
@end example
8625
8626
@item
8627
If the default value contains a closing brace, then use:
8628
8629
@example
8630
test "$@{var+set@}" = set || var='$@{indirection@}'
8631
@end example
8632
@end enumerate
8633
8634
In most cases @samp{var=$@{var="$default"@}} is fine, but in case of
8635
doubt, just use the latter. @xref{Shell Substitutions}, items
8636
@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}}
8637
for the rationale.
8638
8639
8640
@node Special Shell Variables
8641
@section Special Shell Variables
8642
8643
Some shell variables should not be used, since they can have a deep
8644
influence on the behavior of the shell. In order to recover a sane
8645
behavior from the shell, some variables should be unset, but
8646
@command{unset} is not portable (@pxref{Limitations of Builtins}) and a
8647
fallback value is needed. We list these values below.
8648
8649
@c Alphabetical order, case insensitive, `A' before `a'.
8650
@table @code
8651
@item CDPATH
8652
@evindex CDPATH
8653
When this variable is set @code{cd} is verbose, so idioms such as
8654
@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path
8655
twice.
8656
8657
@c FIXME: Which shells? How do they behave?
8658
Setting @code{CDPATH} to the empty value is not enough for most shells.
8659
A simple path separator is enough except for @code{zsh}, which prefers a
8660
leading dot:
8661
8662
@example
8663
zsh-3.1.6$ @kbd{mkdir foo && (CDPATH=: cd foo)}
8664
/tmp/foo
8665
zsh-3.1.6$ @kbd{(CDPATH=:. cd foo)}
8666
/tmp/foo
8667
zsh-3.1.6$ @kbd{(CDPATH=.: cd foo)}
8668
zsh-3.1.6$
8669
@end example
8670
8671
@noindent
8672
(of course we could just @command{unset} @code{CDPATH}, since it also
8673
behaves properly if set to the empty string).
8674
8675
Life wouldn't be so much fun if @command{bash} and @command{zsh} had the
8676
same behavior:
8677
8678
@example
8679
bash-2.02$ @kbd{mkdir foo && (CDPATH=: cd foo)}
8680
bash-2.02$ @kbd{(CDPATH=:. cd foo)}
8681
bash-2.02$ @kbd{(CDPATH=.: cd foo)}
8682
/tmp/foo
8683
@end example
8684
8685
Of course, even better style would be to use @code{PATH_SEPARATOR} instead
8686
of a @samp{:}.
8687
Therefore, a portable solution to neutralize @code{CDPATH} is
8688
8689
@example
8690
CDPATH=$@{ZSH_VERSION+.@}$PATH_SEPARATOR
8691
@end example
8692
8693
@noindent
8694
Note that since @command{zsh} supports @command{unset}, you may unset
8695
@code{CDPATH} using @code{PATH_SEPARATOR} as a fallback, see
8696
@ref{Limitations of Builtins}.
8697
8698
@item IFS
8699
@evindex IFS
8700
Don't set the first character of @code{IFS} to backslash. Indeed,
8701
Bourne shells use the first character (backslash) when joining the
8702
components in @samp{"$@@"} and some shells then re-interpret (!) the
8703
backslash escapes, so you can end up with backspace and other strange
8704
characters.
8705
8706
@item LANG
8707
@itemx LC_ALL
8708
@itemx LC_COLLATE
8709
@itemx LC_CTYPE
8710
@itemx LC_MESSAGES
8711
@itemx LC_NUMERIC
8712
@itemx LC_TIME
8713
@evindex LANG
8714
@evindex LC_ALL
8715
@evindex LC_COLLATE
8716
@evindex LC_CTYPE
8717
@evindex LC_MESSAGES
8718
@evindex LC_NUMERIC
8719
@evindex LC_TIME
8720
8721
Autoconf-generated scripts normally set all these variables to
8722
@samp{C} because so much configuration code assumes the C locale and
8723
@sc{posix} requires that @env{LC_ALL} be set to @samp{C} if the C
8724
locale is desired. However, some older, nonstandard systems (notably
8725
@sc{sco}) break if @env{LC_ALL} is set to @samp{C}, so when running on
8726
these systems Autoconf-generated scripts first try to unset the
8727
variables instead.
8728
8729
@item LANGUAGE
8730
@evindex LANGUAGE
8731
8732
@env{LANGUAGE} is not specified by @sc{posix}, but it is a @sc{gnu}
8733
extension that overrides @env{LC_ALL} in some cases, so
8734
Autoconf-generated scripts set it too.
8735
8736
@item LINENO
8737
@evindex LINENO
8738
Most modern shells provide the current line number in @code{LINENO}.
8739
Its value is the line number of the beginning of the current command.
8740
Autoconf attempts to execute @command{configure} with a modern shell.
8741
If no such shell is available, it attempts to implement @code{LINENO}
8742
with a Sed prepass that replaces the each instance of the string
8743
@code{$LINENO} (not followed by an alphanumeric character) with the
8744
line's number.
8745
8746
You should not rely on @code{LINENO} within @command{eval}, as the
8747
behavior differs in practice. Also, the possibility of the Sed
8748
prepass means that you should not rely on @code{$LINENO} when quoted,
8749
when in here-documents, or when in long commands that cross line
8750
boundaries. Subshells should be OK, though. In the following
8751
example, lines 1, 6, and 9 are portable, but the other instances of
8752
@code{LINENO} are not:
8753
8754
@example
8755
@group
8756
$ @kbd{cat lineno}
8757
echo 1. $LINENO
8758
cat <<EOF
8759
3. $LINENO
8760
4. $LINENO
8761
EOF
8762
( echo 6. $LINENO )
8763
eval 'echo 7. $LINENO'
8764
echo 8. '$LINENO'
8765
echo 9. $LINENO '
8766
10.' $LINENO
8767
@end group
8768
@group
8769
$ @kbd{bash-2.05 lineno}
8770
1. 1
8771
3. 2
8772
4. 2
8773
6. 6
8774
7. 1
8775
8. $LINENO
8776
9. 9
8777
10. 9
8778
@end group
8779
@group
8780
$ @kbd{zsh-3.0.6 lineno}
8781
1. 1
8782
3. 2
8783
4. 2
8784
6. 6
8785
7. 7
8786
8. $LINENO
8787
9. 9
8788
10. 9
8789
@end group
8790
@group
8791
$ @kbd{pdksh-5.2.14 lineno}
8792
1. 1
8793
3. 2
8794
4. 2
8795
6. 6
8796
7. 0
8797
8. $LINENO
8798
9. 9
8799
10. 9
8800
@end group
8801
@group
8802
$ @kbd{sed '=' <lineno |}
8803
> @kbd{ sed '}
8804
> @kbd{ N}
8805
> @kbd{ s,$,-,}
8806
> @kbd{ : loop}
8807
> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,}
8808
> @kbd{ t loop}
8809
> @kbd{ s,-$,,}
8810
> @kbd{ s,^[0-9]*\n,,}
8811
> @kbd{ ' |}
8812
> @kbd{ sh}
8813
1. 1
8814
3. 3
8815
4. 4
8816
6. 6
8817
7. 7
8818
8. 8
8819
9. 9
8820
10. 10
8821
@end group
8822
@end example
8823
8824
8825
@item NULLCMD
8826
@evindex NULLCMD
8827
When executing the command @samp{>foo}, @command{zsh} executes
8828
@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is
8829
@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode,
8830
sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD},
8831
your script might be suspended waiting for data on its standard input.
8832
8833
@item status
8834
@evindex status
8835
This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6),
8836
hence read-only. Do not use it.
8837
8838
@item PATH_SEPARATOR
8839
@evindex PATH_SEPARATOR
8840
If it is not set, @command{configure} will detect the appropriate path
8841
separator for the build system and set the @code{PATH_SEPARATOR} output
8842
variable accordingly.
8843
8844
On DJGPP systems, the @code{PATH_SEPARATOR} environment variable can be
8845
set to either @samp{:} or @samp{;} to control the path separator
8846
@command{bash} uses to set up certain environment variables (such as
8847
@code{PATH}). Since this only works inside @command{bash}, you want
8848
@command{configure} to detect the regular @sc{dos} path separator
8849
(@samp{;}), so it can be safely substituted in files that may not support
8850
@samp{;} as path separator. So it is recommended to either unset this
8851
variable or set it to @samp{;}.
8852
8853
@item RANDOM
8854
@evindex RANDOM
8855
Many shells provide @code{RANDOM}, a variable that returns a different
8856
integer when used. Most of the time, its value does not change when it
8857
is not used, but on @sc{irix 6.5} the value changes all the time. This
8858
can be observed by using @command{set}.
8859
@end table
8860
8861
8862
@node Limitations of Builtins
8863
@section Limitations of Shell Builtins
8864
8865
No, no, we are serious: some shells do have limitations! :)
8866
8867
You should always keep in mind that any built-in or command may support
8868
options, and therefore have a very different behavior with arguments
8869
starting with a dash. For instance, the innocent @samp{echo "$word"}
8870
can give unexpected results when @code{word} starts with a dash. It is
8871
often possible to avoid this problem using @samp{echo "x$word"}, taking
8872
the @samp{x} into account later in the pipe.
8873
8874
@table @asis
8875
@item @command{.}
8876
@prindex @command{.}
8877
Use @command{.} only with regular files (use @samp{test -f}). Bash
8878
2.03, for instance, chokes on @samp{. /dev/null}. Also, remember that
8879
@command{.} uses @env{PATH} if its argument contains no slashes, so if
8880
you want to use @command{.} on a file @file{foo} in the current
8881
directory, you must use @samp{. ./foo}.
8882
8883
@item @command{!}
8884
@prindex @command{!}
8885
You can't use @command{!}, you'll have to rewrite your code.
8886
8887
8888
@item @command{break}
8889
@c ------------------
8890
@prindex @command{break}
8891
The use of @samp{break 2}, etcetera, is safe.
8892
8893
8894
@item @command{case}
8895
@c -----------------
8896
@prindex @command{case}
8897
You don't need to quote the argument; no splitting is performed.
8898
8899
You don't need the final @samp{;;}, but you should use it.
8900
8901
Because of a bug in its @code{fnmatch}, @command{bash} fails to properly
8902
handle backslashes in character classes:
8903
8904
@example
8905
bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac}
8906
bash-2.02$
8907
@end example
8908
8909
@noindent
8910
This is extremely unfortunate, since you are likely to use this code to
8911
handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this
8912
bug, always put the backslash first:
8913
8914
@example
8915
bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac}
8916
OK
8917
bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac}
8918
OK
8919
@end example
8920
8921
Some shells, such as Ash 0.3.8, are confused by empty
8922
@code{case}/@code{esac}:
8923
8924
@example
8925
ash-0.3.8 $ @kbd{case foo in esac;}
8926
@error{}Syntax error: ";" unexpected (expecting ")")
8927
@end example
8928
8929
Many shells still do not support parenthesized cases, which is a pity
8930
for those of us using tools that rely on balanced parentheses. For
8931
instance, Solaris 2.8's Bourne shell:
8932
8933
@example
8934
$ @kbd{case foo in (foo) echo foo;; esac}
8935
@error{}syntax error: `(' unexpected
8936
@end example
8937
8938
8939
@item @command{echo}
8940
@c -----------------
8941
@prindex @command{echo}
8942
The simple @code{echo} is probably the most surprising source of
8943
portability troubles. It is not possible to use @samp{echo} portably
8944
unless both options and escape sequences are omitted. New applications
8945
which are not aiming at portability should use @samp{printf} instead of
8946
@samp{echo}.
8947
8948
Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N}
8949
etc. for a means to simulate @option{-c}.
8950
8951
Do not use backslashes in the arguments, as there is no consensus on
8952
their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of
8953
Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris'
8954
@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1.
8955
Please note that the problem is truly @command{echo}: all the shells
8956
understand @samp{'\n'} as the string composed of a backslash and an
8957
@samp{n}.
8958
8959
Because of these problems, do not pass a string containing arbitrary
8960
characters to @command{echo}. For example, @samp{echo "$foo"} is safe
8961
if you know that @var{foo}'s value cannot contain backslashes and cannot
8962
start with @samp{-}, but otherwise you should use a here-document like
8963
this:
8964
8965
@example
8966
cat <<EOF
8967
$foo
8968
EOF
8969
@end example
8970
8971
8972
@item @command{exit}
8973
@c -----------------
8974
@prindex @command{exit}
8975
The default value of @command{exit} is supposed to be @code{$?};
8976
unfortunately, some shells, such as the DJGPP port of Bash 2.04, just
8977
perform @samp{exit 0}.
8978
8979
@example
8980
bash-2.04$ @kbd{foo=`exit 1` || echo fail}
8981
fail
8982
bash-2.04$ @kbd{foo=`(exit 1)` || echo fail}
8983
fail
8984
bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail}
8985
bash-2.04$
8986
@end example
8987
8988
Using @samp{exit $?} restores the expected behavior.
8989
8990
Some shell scripts, such as those generated by @command{autoconf}, use a
8991
trap to clean up before exiting. If the last shell command exited with
8992
nonzero status, the trap also exits with nonzero status so that the
8993
invoker can tell that an error occurred.
8994
8995
Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit
8996
trap ignores the @code{exit} command's status. In these shells, a trap
8997
cannot determine whether it was invoked by plain @code{exit} or by
8998
@code{exit 1}. Instead of calling @code{exit} directly, use the
8999
@code{AC_MSG_ERROR} macro that has a workaround for this problem.
9000
9001
9002
@item @command{export}
9003
@c -------------------
9004
@prindex @command{export}
9005
The builtin @command{export} dubs @dfn{environment variable} a shell
9006
variable. Each update of exported variables corresponds to an update of
9007
the environment variables. Conversely, each environment variable
9008
received by the shell when it is launched should be imported as a shell
9009
variable marked as exported.
9010
9011
Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5
9012
and DU 4.0, forget to @command{export} the environment variables they
9013
receive. As a result, two variables are coexisting: the environment
9014
variable and the shell variable. The following code demonstrates this
9015
failure:
9016
9017
@example
9018
#! /bin/sh
9019
echo $FOO
9020
FOO=bar
9021
echo $FOO
9022
exec /bin/sh $0
9023
@end example
9024
9025
@noindent
9026
when run with @samp{FOO=foo} in the environment, these shells will print
9027
alternately @samp{foo} and @samp{bar}, although it should only print
9028
@samp{foo} and then a sequence of @samp{bar}s.
9029
9030
Therefore you should @command{export} again each environment variable
9031
that you update.
9032
9033
9034
@item @command{false}
9035
@c ------------------
9036
@prindex @command{false}
9037
Don't expect @command{false} to exit with status 1: in the native Bourne
9038
shell of Solaris 8, it exits with status 255.
9039
9040
9041
@item @command{for}
9042
@c ----------------
9043
@prindex @command{for}
9044
To loop over positional arguments, use:
9045
9046
@example
9047
for arg
9048
do
9049
echo "$arg"
9050
done
9051
@end example
9052
9053
@noindent
9054
You may @emph{not} leave the @code{do} on the same line as @code{for},
9055
since some shells improperly grok:
9056
9057
@example
9058
for arg; do
9059
echo "$arg"
9060
done
9061
@end example
9062
9063
If you want to explicitly refer to the positional arguments, given the
9064
@samp{$@@} bug (@pxref{Shell Substitutions}), use:
9065
9066
@example
9067
for arg in $@{1+"$@@"@}; do
9068
echo "$arg"
9069
done
9070
@end example
9071
9072
@item @command{if}
9073
@c ---------------
9074
@prindex @command{if}
9075
Using @samp{!} is not portable. Instead of:
9076
9077
@example
9078
if ! cmp -s file file.new; then
9079
mv file.new file
9080
fi
9081
@end example
9082
9083
@noindent
9084
use:
9085
9086
@example
9087
if cmp -s file file.new; then :; else
9088
mv file.new file
9089
fi
9090
@end example
9091
9092
There are shells that do not reset the exit status from an @command{if}:
9093
9094
@example
9095
$ @kbd{if (exit 42); then true; fi; echo $?}
9096
42
9097
@end example
9098
9099
@noindent
9100
whereas a proper shell should have printed @samp{0}. This is especially
9101
bad in Makefiles since it produces false failures. This is why properly
9102
written Makefiles, such as Automake's, have such hairy constructs:
9103
9104
@example
9105
if test -f "$file"; then
9106
install "$file" "$dest"
9107
else
9108
:
9109
fi
9110
@end example
9111
9112
9113
@item @command{set}
9114
@c ----------------
9115
@prindex @command{set}
9116
This builtin faces the usual problem with arguments starting with a
9117
dash. Modern shells such as Bash or Zsh understand @option{--} to specify
9118
the end of the options (any argument after @option{--} is a parameters,
9119
even @samp{-x} for instance), but most shells simply stop the option
9120
processing as soon as a non-option argument is found. Therefore, use
9121
@samp{dummy} or simply @samp{x} to end the option processing, and use
9122
@command{shift} to pop it out:
9123
9124
@example
9125
set x $my_list; shift
9126
@end example
9127
9128
9129
@item @command{shift}
9130
@c ------------------
9131
@prindex @command{shift}
9132
Not only is @command{shift}ing a bad idea when there is nothing left to
9133
shift, but in addition it is not portable: the shell of @sc{mips
9134
risc/os} 4.52 refuses to do it.
9135
9136
9137
@item @command{source}
9138
@c -------------------
9139
@prindex @command{source}
9140
This command is not portable, as @sc{posix} does not require it; use
9141
@command{.} instead.
9142
9143
9144
@item @command{test}
9145
@c -----------------
9146
@prindex @command{test}
9147
The @code{test} program is the way to perform many file and string
9148
tests. It is often invoked by the alternate name @samp{[}, but using
9149
that name in Autoconf code is asking for trouble since it is an M4 quote
9150
character.
9151
9152
If you need to make multiple checks using @code{test}, combine them with
9153
the shell operators @samp{&&} and @samp{||} instead of using the
9154
@code{test} operators @option{-a} and @option{-o}. On System V, the
9155
precedence of @option{-a} and @option{-o} is wrong relative to the unary
9156
operators; consequently, @sc{posix} does not specify them, so using them
9157
is nonportable. If you combine @samp{&&} and @samp{||} in the same
9158
statement, keep in mind that they have equal precedence.
9159
9160
You may use @samp{!} with @command{test}, but not with @command{if}:
9161
@samp{test ! -r foo || exit 1}.
9162
9163
9164
@item @command{test} (files)
9165
@c -------------------------
9166
To enable @command{configure} scripts to support cross-compilation, they
9167
shouldn't do anything that tests features of the build system instead of
9168
the host system. But occasionally you may find it necessary to check
9169
whether some arbitrary file exists. To do so, use @samp{test -f} or
9170
@samp{test -r}. Do not use @samp{test -x}, because @sc{4.3bsd} does not
9171
have it. Do not use @samp{test -e} either, because Solaris 2.5 does not
9172
have it.
9173
9174
@item @command{test} (strings)
9175
@c ---------------------------
9176
Avoid @samp{test "@var{string}"}, in particular if @var{string} might
9177
start with a dash, since @code{test} might interpret its argument as an
9178
option (e.g., @samp{@var{string} = "-n"}).
9179
9180
Contrary to a common belief, @samp{test -n @var{string}} and @samp{test
9181
-z @var{string}} @strong{are} portable, nevertheless many shells (such
9182
as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have
9183
bizarre precedence and may be confused if @var{string} looks like an
9184
operator:
9185
9186
@example
9187
$ @kbd{test -n =}
9188
test: argument expected
9189
@end example
9190
9191
If there are risks, use @samp{test "x@var{string}" = x} or @samp{test
9192
"x@var{string}" != x} instead.
9193
9194
It is frequent to find variations of the following idiom:
9195
9196
@example
9197
test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" &&
9198
@var{action}
9199
@end example
9200
9201
@noindent
9202
to take an action when a token matches a given pattern. Such constructs
9203
should always be avoided by using:
9204
9205
@example
9206
echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 &&
9207
@var{action}
9208
@end example
9209
9210
@noindent
9211
Use @code{case} where possible since it is faster, being a shell builtin:
9212
9213
9214
@example
9215
case $ac_feature in
9216
*[!-a-zA-Z0-9_]*) @var{action};;
9217
esac
9218
@end example
9219
9220
Alas, negated character classes are probably not portable, although no
9221
shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]}
9222
(when in interactive mode, @command{zsh} is confused by the
9223
@samp{[!@dots{}]} syntax and looks for an event in its history because of
9224
@samp{!}). Many shells do not support the alternative syntax
9225
@samp{[^@dots{}]} (Solaris, Digital Unix, etc.).
9226
9227
One solution can be:
9228
9229
@example
9230
expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
9231
@var{action}
9232
@end example
9233
9234
@noindent
9235
or better yet
9236
9237
@example
9238
expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
9239
@var{action}
9240
@end example
9241
9242
@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo
9243
"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
9244
@samp{@var{foo}} contains backslashes.
9245
9246
9247
@item @command{trap}
9248
@c -----------------
9249
@prindex @command{trap}
9250
It is safe to trap at least the signals 1, 2, 13 and 15. You can also
9251
trap 0, i.e., have the @command{trap} run when the script ends (either via an
9252
explicit @command{exit}, or the end of the script).
9253
9254
Although @sc{posix} is not absolutely clear on this point, it is widely
9255
admitted that when entering the trap @samp{$?} should be set to the exit
9256
status of the last command run before the trap. The ambiguity can be
9257
summarized as: ``when the trap is launched by an @command{exit}, what is
9258
the @emph{last} command run: that before @command{exit}, or
9259
@command{exit} itself?''
9260
9261
Bash considers @command{exit} to be the last command, while Zsh and
9262
Solaris 8 @command{sh} consider that when the trap is run it is
9263
@emph{still} in the @command{exit}, hence it is the previous exit status
9264
that the trap receives:
9265
9266
@example
9267
$ @kbd{cat trap.sh}
9268
trap 'echo $?' 0
9269
(exit 42); exit 0
9270
$ @kbd{zsh trap.sh}
9271
42
9272
$ @kbd{bash trap.sh}
9273
0
9274
@end example
9275
9276
The portable solution is then simple: when you want to @samp{exit 42},
9277
run @samp{(exit 42); exit 42}, the first @command{exit} being used to
9278
set the exit status to 42 for Zsh, and the second to trigger the trap
9279
and pass 42 as exit status for Bash.
9280
9281
The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0
9282
by empty lines if the code is inside @command{trap}.
9283
9284
@example
9285
$ @kbd{trap 'false}
9286
9287
echo $?' 0
9288
$ @kbd{exit}
9289
0
9290
@end example
9291
9292
@noindent
9293
Fortunately, this bug only affects @command{trap}.
9294
9295
@item @command{true}
9296
@c -----------------
9297
@prindex @command{true}
9298
@prindex @command{:}
9299
Don't worry: as far as we know @command{true} is portable.
9300
Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the
9301
portable shell community tends to prefer using @command{:}. This has a
9302
funny side effect: when asked whether @command{false} is more portable
9303
than @command{true} Alexandre Oliva answered:
9304
9305
@quotation
9306
In a sense, yes, because if it doesn't exist, the shell will produce an
9307
exit status of failure, which is correct for @command{false}, but not
9308
for @command{true}.
9309
@end quotation
9310
9311
9312
@item @command{unset}
9313
@c ------------------
9314
@prindex @command{unset}
9315
You cannot assume the support of @command{unset}, nevertheless, because
9316
it is extremely useful to disable embarrassing variables such as
9317
@code{CDPATH}, you can test for its existence and use
9318
it @emph{provided} you give a neutralizing value when @command{unset} is
9319
not supported:
9320
9321
@example
9322
if (unset FOO) >/dev/null 2>&1; then
9323
unset=unset
9324
else
9325
unset=false
9326
fi
9327
$unset CDPATH || CDPATH=:
9328
@end example
9329
9330
@xref{Special Shell Variables}, for some neutralizing values. Also, see
9331
@ref{Limitations of Builtins}, documentation of @command{export}, for
9332
the case of environment variables.
9333
@end table
9334
9335
@node Limitations of Usual Tools
9336
@section Limitations of Usual Tools
9337
9338
The small set of tools you can expect to find on any machine can still
9339
include some limitations you should be aware of.
9340
9341
@table @asis
9342
@item @command{awk}
9343
@c ----------------
9344
@prindex @command{awk}
9345
Don't leave white spaces before the parentheses in user functions calls,
9346
@sc{gnu} awk will reject it:
9347
9348
@example
9349
$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
9350
BEGIN @{ die () @}'}
9351
gawk: cmd. line:2: BEGIN @{ die () @}
9352
gawk: cmd. line:2: ^ parse error
9353
$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @}
9354
BEGIN @{ die() @}'}
9355
Aaaaarg!
9356
@end example
9357
9358
If you want your program to be deterministic, don't depend on @code{for}
9359
on arrays:
9360
9361
@example
9362
$ @kbd{cat for.awk}
9363
END @{
9364
arr["foo"] = 1
9365
arr["bar"] = 1
9366
for (i in arr)
9367
print i
9368
@}
9369
$ @kbd{gawk -f for.awk </dev/null}
9370
foo
9371
bar
9372
$ @kbd{nawk -f for.awk </dev/null}
9373
bar
9374
foo
9375
@end example
9376
9377
Some AWK, such as HPUX 11.0's native one, have regex engines fragile to
9378
inner anchors:
9379
9380
@example
9381
$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'}
9382
$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'}
9383
bar
9384
$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'}
9385
xfoo
9386
$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'}
9387
bar
9388
@end example
9389
9390
@noindent
9391
Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/},
9392
or use a simple test to reject such AWK.
9393
9394
9395
@item @command{cat}
9396
@c ----------------
9397
@prindex @command{cat}
9398
Don't rely on any option. The option @option{-v}, which displays
9399
non-printing characters, @emph{seems} portable, though.
9400
9401
9402
@item @command{cc}
9403
@c ---------------
9404
When a compilation such as @samp{cc foo.c -o foo} fails, some compilers
9405
(such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}.
9406
9407
HP-UX @command{cc} doesn't accept @file{.S} files to preprocess and
9408
assemble. @samp{cc -c foo.S} will appear to succeed, but in fact does
9409
nothing.
9410
9411
9412
@item @command{cmp}
9413
@c ----------------
9414
@prindex @command{cmp}
9415
@command{cmp} performs a raw data comparison of two files, while
9416
@command{diff} compares two text files. Therefore, if you might compare
9417
DOS files, even if only checking whether two files are different, use
9418
@command{diff} to avoid spurious differences due to differences of
9419
newline encoding.
9420
9421
9422
@item @command{cp}
9423
@c ---------------
9424
@prindex @command{cp}
9425
@c This is thanks to Ian.
9426
SunOS @command{cp} does not support @option{-f}, although its
9427
@command{mv} does. It's possible to deduce why @command{mv} and
9428
@command{cp} are different with respect to @option{-f}. @command{mv}
9429
prompts by default before overwriting a read-only file. @command{cp}
9430
does not. Therefore, @command{mv} requires a @option{-f} option, but
9431
@command{cp} does not. @command{mv} and @command{cp} behave differently
9432
with respect to read-only files because the simplest form of
9433
@command{cp} cannot overwrite a read-only file, but the simplest form of
9434
@command{mv} can. This is because @command{cp} opens the target for
9435
write access, whereas @command{mv} simply calls @code{link} (or, in
9436
newer systems, @code{rename}).
9437
@c Ian said: ``I don't think -p or -r are portable''!!! How can you live
9438
@c without -r???
9439
9440
9441
@item @command{date}
9442
@c -----------------
9443
@prindex @command{date}
9444
Some versions of @command{date} do not recognize special % directives,
9445
and unfortunately, instead of complaining, they just pass them through,
9446
and exit with success:
9447
9448
@example
9449
$ @kbd{uname -a}
9450
OSF1 medusa.sis.pasteur.fr V5.1 732 alpha
9451
$ @kbd{date "+%s"}
9452
%s
9453
@end example
9454
9455
9456
@item @command{diff}
9457
@c -----------------
9458
@prindex @command{diff}
9459
Option @option{-u} is nonportable.
9460
9461
Some implementations, such as Tru64's, fail when comparing to
9462
@file{/dev/null}. Use an empty file instead.
9463
9464
9465
@item @command{dirname}
9466
@c --------------------
9467
@prindex @command{dirname}
9468
Not all hosts have a working @command{dirname}, and you should instead
9469
use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example:
9470
9471
@example
9472
dir=`dirname "$file"` # This is not portable.
9473
dir=`AS_DIRNAME(["$file"])` # This is more portable.
9474
@end example
9475
9476
@noindent
9477
This handles a few subtleties in the standard way required by
9478
@sc{posix}. For example, under UN*X, should @samp{dirname //1} give
9479
@samp{/}? Paul Eggert answers:
9480
9481
@quotation
9482
No, under some older flavors of Unix, leading @samp{//} is a special
9483
path name: it refers to a ``super-root'' and is used to access other
9484
machines' files. Leading @samp{///}, @samp{////}, etc. are equivalent
9485
to @samp{/}; but leading @samp{//} is special. I think this tradition
9486
started with Apollo Domain/OS, an OS that is still in use on some older
9487
hosts.
9488
9489
@sc{posix} allows but does not require the special treatment for @samp{//}.
9490
It says that the behavior of dirname on path names of the form
9491
@samp{//([^/]+/*)?} is implementation defined. In these cases, GNU
9492
@command{dirname} returns @samp{/}, but it's more portable to return
9493
@samp{//} as this works even on those older flavors of Unix.
9494
@end quotation
9495
9496
9497
@item @command{egrep}
9498
@c ------------------
9499
@prindex @command{egrep}
9500
The empty alternative is not portable, use @samp{?} instead. For
9501
instance with Digital Unix v5.0:
9502
9503
@example
9504
> printf "foo\n|foo\n" | egrep '^(|foo|bar)$'
9505
|foo
9506
> printf "bar\nbar|\n" | egrep '^(foo|bar|)$'
9507
bar|
9508
> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$'
9509
foo
9510
|bar
9511
@end example
9512
9513
@command{egrep} also suffers the limitations of @command{grep}.
9514
9515
9516
@item @command{expr}
9517
@c -----------------
9518
@prindex @command{expr}
9519
No @command{expr} keyword starts with @samp{x}, so use @samp{expr
9520
x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from
9521
misinterpreting @var{word}.
9522
9523
Don't use @code{length}, @code{substr}, @code{match} and @code{index}.
9524
9525
@item @command{expr} (@samp{|})
9526
@prindex @command{expr} (@samp{|})
9527
You can use @samp{|}. Although @sc{posix} does require that @samp{expr
9528
''} return the empty string, it does not specify the result when you
9529
@samp{|} together the empty string (or zero) with the empty string. For
9530
example:
9531
9532
@example
9533
expr '' \| ''
9534
@end example
9535
9536
@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this
9537
case, but traditional Unix returns @samp{0} (Solaris is one such
9538
example). In the latest @sc{posix} draft, the specification has been
9539
changed to match traditional Unix's behavior (which is bizarre, but it's
9540
too late to fix this). Please note that the same problem does arise
9541
when the empty string results from a computation, as in:
9542
9543
@example
9544
expr bar : foo \| foo : bar
9545
@end example
9546
9547
@noindent
9548
Avoid this portability problem by avoiding the empty string.
9549
9550
9551
@item @command{expr} (@samp{:})
9552
@c ----------------------------
9553
@prindex @command{expr}
9554
Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are
9555
not supported on Solaris.
9556
9557
The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a :
9558
b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string.
9559
In practice, it outputs the empty string on most platforms, but portable
9560
scripts should not assume this. For instance, the @sc{qnx} 4.25 native
9561
@command{expr} returns @samp{0}.
9562
9563
You may believe that one means to get a uniform behavior would be to use
9564
the empty string as a default value:
9565
9566
@example
9567
expr a : b \| ''
9568
@end example
9569
9570
@noindent
9571
unfortunately this behaves exactly as the original expression, see the
9572
@samp{@command{expr} (@samp{:})} entry for more information.
9573
9574
Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and
9575
Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes
9576
@command{expr} to fail if the matched substring is longer than 120
9577
bytes. In this case, you might want to fall back on @samp{echo|sed} if
9578
@command{expr} fails.
9579
9580
Don't leave, there is some more!
9581
9582
The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to
9583
the empty string, has a funny behavior in its exit status: it's always 1
9584
when parentheses are used!
9585
9586
@example
9587
$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"}
9588
0: 1
9589
$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"}
9590
1: 0
9591
9592
$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"}
9593
1: a
9594
$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"}
9595
1: 0
9596
@end example
9597
9598
@noindent
9599
In practice this can be a big problem if you are ready to catch failures
9600
of @command{expr} programs with some other method (such as using
9601
@command{sed}), since you may get twice the result. For instance
9602
9603
@example
9604
$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'}
9605
@end example
9606
9607
@noindent
9608
will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25. A
9609
simple work around consists in testing @command{expr} and use a variable
9610
set to @command{expr} or to @command{false} according to the result.
9611
9612
9613
@item @command{find}
9614
@c -----------------
9615
The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1,
9616
NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it.
9617
9618
The replacement of @samp{@{@}} is guaranteed only if the argument is
9619
exactly @emph{@{@}}, not if it's only a part of an argument. For
9620
instance on DU, and HP-UX 10.20 and HP-UX 11:
9621
9622
@example
9623
$ @kbd{touch foo}
9624
$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;}
9625
@{@}-@{@}
9626
@end example
9627
9628
@noindent
9629
while @sc{gnu} @command{find} reports @samp{./foo-./foo}.
9630
9631
9632
@item @command{grep}
9633
@c -----------------
9634
@prindex @command{grep}
9635
Don't use @samp{grep -s} to suppress output, because @samp{grep -s} on
9636
System V does not suppress output, only error messages. Instead,
9637
redirect the standard output and standard error (in case the file
9638
doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit
9639
status of @code{grep} to determine whether it found a match.
9640
9641
Don't use multiple regexps with @option{-e}, as some @code{grep} will only
9642
honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway,
9643
Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use
9644
alternation and @code{egrep}.
9645
9646
9647
@item @command{ln}
9648
@c ---------------
9649
@prindex @command{ln}
9650
@cindex Symbolic links
9651
Don't rely on @command{ln} having a @option{-f} option. Symbolic links
9652
are not available on old systems, use @samp{ln} as a fall back.
9653
9654
For versions of the DJGPP before 2.04, @command{ln} emulates soft links
9655
for executables by generating a stub that in turn calls the real
9656
program. This feature also works with nonexistent files like in the
9657
Unix spec. So @samp{ln -s file link} will generate @file{link.exe},
9658
which will attempt to call @file{file.exe} if run. But this feature only
9659
works for executables, so @samp{cp -p} is used instead for these
9660
systems. DJGPP versions 2.04 and later have full symlink support.
9661
9662
9663
@item @command{mv}
9664
@c ---------------
9665
@prindex @command{mv}
9666
@cindex Moving open files
9667
The only portable options are @option{-f} and @option{-i}.
9668
9669
Moving individual files between file systems is portable (it was in V6),
9670
but it is not always atomic: when doing @samp{mv new existing}, there's
9671
a critical section where neither the old nor the new version of
9672
@file{existing} actually exists.
9673
9674
Moving directories across mount points is not portable, use @command{cp}
9675
and @command{rm}.
9676
9677
Moving/Deleting open files isn't portable. The following can't be done
9678
on DOS/WIN32:
9679
9680
@example
9681
exec > foo
9682
mv foo bar
9683
@end example
9684
9685
@noindent
9686
nor can
9687
9688
@example
9689
exec > foo
9690
rm -f foo
9691
@end example
9692
9693
@item @command{sed}
9694
@c ----------------
9695
@prindex @command{sed}
9696
Patterns should not include the separator (unless escaped), even as part
9697
of a character class. In conformance with @sc{posix}, the Cray
9698
@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}.
9699
9700
Sed scripts should not use branch labels longer than 8 characters and
9701
should not contain comments.
9702
9703
Don't include extra @samp{;}, as some @command{sed}, such as NetBSD
9704
1.4.2's, try to interpret the second as a command:
9705
9706
@example
9707
$ @kbd{echo a | sed 's/x/x/;;s/x/x/'}
9708
sed: 1: "s/x/x/;;s/x/x/": invalid command code ;
9709
@end example
9710
9711
Input should have reasonably long lines, since some @command{sed} have
9712
an input buffer limited to 4000 bytes.
9713
9714
Alternation, @samp{\|}, is common but @sc{posix}.2 does not require its
9715
support, so it should be avoided in portable scripts. Solaris 8
9716
@command{sed} does not support alternation; e.g. @samp{sed '/a\|b/d'}
9717
deletes only lines that contain the literal string @samp{a|b}.
9718
9719
Anchors (@samp{^} and @samp{$}) inside groups are not portable.
9720
9721
Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is
9722
quite portable to modern hosts, but is not supported by some older
9723
@command{sed} implementations like SVR3.
9724
9725
Of course the option @option{-e} is portable, but it is not needed. No
9726
valid Sed program can start with a dash, so it does not help
9727
disambiguating. Its sole usefulness is helping enforcing indenting as
9728
in:
9729
9730
@example
9731
sed -e @var{instruction-1} \
9732
-e @var{instruction-2}
9733
@end example
9734
9735
@noindent
9736
as opposed to
9737
9738
@example
9739
sed @var{instruction-1};@var{instruction-2}
9740
@end example
9741
9742
Contrary to yet another urban legend, you may portably use @samp{&} in
9743
the replacement part of the @code{s} command to mean ``what was
9744
matched''. All descendents of Bell Lab's V7 @command{sed} (at least; we
9745
don't have first hand experience with older @command{sed}s) have
9746
supported it.
9747
9748
9749
@item @command{sed} (@samp{t})
9750
@c ---------------------------
9751
@prindex @command{sed} (@samp{t})
9752
Some old systems have @command{sed} that ``forget'' to reset their
9753
@samp{t} flag when starting a new cycle. For instance on @sc{mips
9754
risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed}
9755
script (the line numbers are not actual part of the texts):
9756
9757
@example
9758
s/keep me/kept/g # a
9759
t end # b
9760
s/.*/deleted/g # c
9761
: end # d
9762
@end example
9763
9764
@noindent
9765
on
9766
9767
@example
9768
delete me # 1
9769
delete me # 2
9770
keep me # 3
9771
delete me # 4
9772
@end example
9773
9774
@noindent
9775
you get
9776
9777
@example
9778
deleted
9779
delete me
9780
kept
9781
deleted
9782
@end example
9783
9784
@noindent
9785
instead of
9786
9787
@example
9788
deleted
9789
deleted
9790
kept
9791
deleted
9792
@end example
9793
9794
Why? When processing 1, a matches, therefore sets the t flag, b jumps to
9795
d, and the output is produced. When processing line 2, the t flag is
9796
still set (this is the bug). Line a fails to match, but @command{sed}
9797
is not supposed to clear the t flag when a substitution fails. Line b
9798
sees that the flag is set, therefore it clears it, and jumps to d, hence
9799
you get @samp{delete me} instead of @samp{deleted}. When processing 3 t
9800
is clear, a matches, so the flag is set, hence b clears the flags and
9801
jumps. Finally, since the flag is clear, 4 is processed properly.
9802
9803
There are two things one should remind about @samp{t} in @command{sed}.
9804
Firstly, always remember that @samp{t} jumps if @emph{some} substitution
9805
succeeded, not only the immediately preceding substitution, therefore,
9806
always use a fake @samp{t clear; : clear} to reset the t flag where
9807
indeed.
9808
9809
Secondly, you cannot rely on @command{sed} to clear the flag at each new
9810
cycle.
9811
9812
One portable implementation of the script above is:
9813
9814
@example
9815
t clear
9816
: clear
9817
s/keep me/kept/g
9818
t end
9819
s/.*/deleted/g
9820
: end
9821
@end example
9822
9823
@item @command{touch}
9824
@c ------------------
9825
@prindex @command{touch}
9826
On some old @sc{bsd} systems, @command{touch} or any command that
9827
results in an empty file does not update the timestamps, so use a
9828
command like @code{echo} as a workaround.
9829
9830
GNU @command{touch} 3.16r (and presumably all before that) fails to work
9831
on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume.
9832
9833
@end table
9834
9835
9836
@node Limitations of Make
9837
@section Limitations of Make
9838
9839
Make itself suffers a great number of limitations, only a few of which
9840
being listed here. First of all, remember that since commands are
9841
executed by the shell, all its weaknesses are inherited@dots{}
9842
9843
@table @asis
9844
@item @code{$<}
9845
@sc{posix} says that the @samp{$<} construct in makefiles can be used
9846
only in inference rules and in the @samp{.DEFAULT} rule; its meaning in
9847
ordinary rules is unspecified. Solaris 8's @command{make} for instance
9848
will replace it with the argument.
9849
9850
@item Leading underscore in macro names
9851
Some Make don't support leading underscores in macro names, such as on
9852
NEWS-OS 4.2R.
9853
9854
@example
9855
$ @kbd{cat Makefile}
9856
_am_include = #
9857
_am_quote =
9858
all:; @@echo this is test
9859
$ @kbd{make}
9860
Make: Must be a separator on rules line 2. Stop.
9861
$ @kbd{cat Makefile2}
9862
am_include = #
9863
am_quote =
9864
all:; @@echo this is test
9865
$ @kbd{make -f Makefile2}
9866
this is test
9867
@end example
9868
9869
@item @code{VPATH}
9870
@cindex @code{VPATH}
9871
Don't use it! For instance any assignment to @code{VPATH} causes Sun
9872
@command{make} to only execute the first set of double-colon rules.
9873
@end table
9874
9875
9876
9877
9878
@c ================================================== Manual Configuration
9879
9880
@node Manual Configuration
9881
@chapter Manual Configuration
9882
9883
A few kinds of features can't be guessed automatically by running test
9884
programs. For example, the details of the object-file format, or
9885
special options that need to be passed to the compiler or linker. You
9886
can check for such features using ad-hoc means, such as having
9887
@command{configure} check the output of the @code{uname} program, or
9888
looking for libraries that are unique to particular systems. However,
9889
Autoconf provides a uniform method for handling unguessable features.
9890
9891
@menu
9892
* Specifying Names:: Specifying the system type
9893
* Canonicalizing:: Getting the canonical system type
9894
* Using System Type:: What to do with the system type
9895
@end menu
9896
9897
@node Specifying Names
9898
@section Specifying the System Type
9899
9900
Like other @sc{gnu} @command{configure} scripts, Autoconf-generated
9901
@command{configure} scripts can make decisions based on a canonical name
9902
for the system type, which has the form:
9903
@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be
9904
@samp{@var{system}} or @samp{@var{kernel}-@var{system}}
9905
9906
@command{configure} can usually guess the canonical name for the type of
9907
system it's running on. To do so it runs a script called
9908
@command{config.guess}, which infers the name using the @code{uname}
9909
command or symbols predefined by the C preprocessor.
9910
9911
Alternately, the user can specify the system type with command line
9912
arguments to @command{configure}. Doing so is necessary when
9913
cross-compiling. In the most complex case of cross-compiling, three
9914
system types are involved. The options to specify them are:
9915
9916
@table @option
9917
@item --build=@var{build-type}
9918
the type of system on which the package is being configured and
9919
compiled. It defaults to the result of running @command{config.guess}.
9920
9921
@item --host=@var{host-type}
9922
@ovindex cross_compiling
9923
the type of system on which the package will run. By default it is the
9924
same as the build machine. Specifying it enables the cross-compilation
9925
mode.
9926
9927
@item --target=@var{target-type}
9928
the type of system for which any compiler tools in the package will
9929
produce code (rarely needed). By default, it is the same as host.
9930
@end table
9931
9932
If you mean to override the result of @command{config.guess}, use
9933
@option{--build}, not @option{--host}, since the latter enables
9934
cross-compilation. For historical reasons, passing @option{--host} also
9935
changes the build type. Therefore, whenever you specify @code{--host},
9936
be sure to specify @code{--build} too. This will be fixed in the
9937
future.
9938
9939
@example
9940
./configure --build=i686-pc-linux-gnu --host=m68k-coff
9941
@end example
9942
9943
@noindent
9944
will enter cross-compilation mode, but @command{configure} will fail if it
9945
can't run the code generated by the specified compiler if you configure
9946
as follows:
9947
9948
@example
9949
./configure CC=m68k-coff-gcc
9950
@end example
9951
9952
@cindex @command{config.sub}
9953
@command{configure} recognizes short aliases for many system types; for
9954
example, @samp{decstation} can be used instead of
9955
@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called
9956
@command{config.sub} to canonicalize system type aliases.
9957
9958
This section deliberately omits the description of the obsolete
9959
interface, see @ref{Hosts and Cross-Compilation}.
9960
9961
9962
@node Canonicalizing
9963
@section Getting the Canonical System Type
9964
9965
The following macros make the system type available to @command{configure}
9966
scripts.
9967
9968
@ovindex build_alias
9969
@ovindex host_alias
9970
@ovindex target_alias
9971
9972
The variables @samp{build_alias}, @samp{host_alias}, and
9973
@samp{target_alias} are always exactly the arguments of @option{--build},
9974
@option{--host}, and @option{--target}; in particular, they are left empty
9975
if the user did not use them, even if the corresponding
9976
@code{AC_CANONICAL} macro was run. Any configure script may use these
9977
variables anywhere. These are the variables that should be used when in
9978
interaction with the user.
9979
9980
If you need to recognize some special environments based on their system
9981
type, run the following macros to get canonical system names. These
9982
variables are not set before the macro call.
9983
9984
If you use these macros, you must distribute @command{config.guess} and
9985
@command{config.sub} along with your source code. @xref{Output}, for
9986
information about the @code{AC_CONFIG_AUX_DIR} macro which you can use
9987
to control in which directory @command{configure} looks for those scripts.
9988
9989
9990
@defmac AC_CANONICAL_BUILD
9991
@acindex CANONICAL_BUILD
9992
@ovindex build
9993
@ovindex build_cpu
9994
@ovindex build_vendor
9995
@ovindex build_os
9996
Compute the canonical build-system type variable, @code{build}, and its
9997
three individual parts @code{build_cpu}, @code{build_vendor}, and
9998
@code{build_os}.
9999
10000
If @option{--build} was specified, then @code{build} is the
10001
canonicalization of @code{build_alias} by @command{config.sub},
10002
otherwise it is determined by the shell script @command{config.guess}.
10003
@end defmac
10004
10005
@defmac AC_CANONICAL_HOST
10006
@acindex CANONICAL_HOST
10007
@ovindex host
10008
@ovindex host_cpu
10009
@ovindex host_vendor
10010
@ovindex host_os
10011
Compute the canonical host-system type variable, @code{host}, and its
10012
three individual parts @code{host_cpu}, @code{host_vendor}, and
10013
@code{host_os}.
10014
10015
If @option{--host} was specified, then @code{host} is the
10016
canonicalization of @code{host_alias} by @command{config.sub},
10017
otherwise it defaults to @code{build}.
10018
@end defmac
10019
10020
@defmac AC_CANONICAL_TARGET
10021
@acindex CANONICAL_TARGET
10022
@ovindex target
10023
@ovindex target_cpu
10024
@ovindex target_vendor
10025
@ovindex target_os
10026
Compute the canonical target-system type variable, @code{target}, and its
10027
three individual parts @code{target_cpu}, @code{target_vendor}, and
10028
@code{target_os}.
10029
10030
If @option{--target} was specified, then @code{target} is the
10031
canonicalization of @code{target_alias} by @command{config.sub},
10032
otherwise it defaults to @code{host}.
10033
@end defmac
10034
10035
Note that there can be artifacts due to the backward compatibility
10036
code. @xref{Hosts and Cross-Compilation}, for more.
10037
10038
@node Using System Type
10039
@section Using the System Type
10040
10041
How do you use a canonical system type? Usually, you use it in one or
10042
more @code{case} statements in @file{configure.ac} to select
10043
system-specific C files. Then, using @code{AC_CONFIG_LINKS}, link those
10044
files which have names based on the system name, to generic names, such
10045
as @file{host.h} or @file{target.c} (@pxref{Configuration Links}). The
10046
@code{case} statement patterns can use shell wild cards to group several
10047
cases together, like in this fragment:
10048
10049
@example
10050
case $target in
10051
i386-*-mach* | i386-*-gnu*)
10052
obj_format=aout emulation=mach bfd_gas=yes ;;
10053
i960-*-bout) obj_format=bout ;;
10054
esac
10055
@end example
10056
10057
@noindent
10058
and later in @file{configure.ac}, use:
10059
10060
@example
10061
AC_CONFIG_LINKS(host.h:config/$machine.h
10062
object.h:config/$obj_format.h)
10063
@end example
10064
10065
Note that the above example uses @code{$target} because it's taken from
10066
a tool which can be built on some architecture (@code{$build}), run on
10067
another (@code{$host}), but yet handle data for a third architecture
10068
(@code{$target}). Such tools are usually part of a compiler suite, they
10069
generate code for a specific @code{$target}.
10070
10071
However @code{$target} should be meaningless for most packages. If you
10072
want to base a decision on the system where your program will be run,
10073
make sure you use the @code{$host} variable, as in the following
10074
excerpt:
10075
10076
@example
10077
case $host in
10078
*-*-msdos* | *-*-go32* | *-*-mingw32* | *-*-cygwin* | *-*-windows*)
10079
MUMBLE_INIT="mumble.ini"
10080
;;
10081
*)
10082
MUMBLE_INIT=".mumbleinit"
10083
;;
10084
esac
10085
AC_SUBST([MUMBLE_INIT])
10086
@end example
10087
10088
You can also use the host system type to find cross-compilation tools.
10089
@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL}
10090
macro which does that.
10091
10092
10093
@c ===================================================== Site Configuration.
10094
10095
@node Site Configuration
10096
@chapter Site Configuration
10097
10098
@command{configure} scripts support several kinds of local configuration
10099
decisions. There are ways for users to specify where external software
10100
packages are, include or exclude optional features, install programs
10101
under modified names, and set default values for @command{configure}
10102
options.
10103
10104
@menu
10105
* External Software:: Working with other optional software
10106
* Package Options:: Selecting optional features
10107
* Pretty Help Strings:: Formating help string
10108
* Site Details:: Configuring site details
10109
* Transforming Names:: Changing program names when installing
10110
* Site Defaults:: Giving @command{configure} local defaults
10111
@end menu
10112
10113
@node External Software
10114
@section Working With External Software
10115
10116
Some packages require, or can optionally use, other software packages
10117
that are already installed. The user can give @command{configure}
10118
command line options to specify which such external software to use.
10119
The options have one of these forms:
10120
10121
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
10122
@c awful.
10123
@example
10124
--with-@var{package}[=@var{arg}]
10125
--without-@var{package}
10126
@end example
10127
10128
For example, @option{--with-gnu-ld} means work with the @sc{gnu} linker
10129
instead of some other linker. @option{--with-x} means work with The X
10130
Window System.
10131
10132
The user can give an argument by following the package name with
10133
@samp{=} and the argument. Giving an argument of @samp{no} is for
10134
packages that are used by default; it says to @emph{not} use the
10135
package. An argument that is neither @samp{yes} nor @samp{no} could
10136
include a name or number of a version of the other package, to specify
10137
more precisely which other package this program is supposed to work
10138
with. If no argument is given, it defaults to @samp{yes}.
10139
@option{--without-@var{package}} is equivalent to
10140
@option{--with-@var{package}=no}.
10141
10142
@command{configure} scripts do not complain about
10143
@option{--with-@var{package}} options that they do not support. This
10144
behavior permits configuring a source tree containing multiple packages
10145
with a top-level @command{configure} script when the packages support
10146
different options, without spurious error messages about options that
10147
some of the packages support. An unfortunate side effect is that option
10148
spelling errors are not diagnosed. No better approach to this problem
10149
has been suggested so far.
10150
10151
For each external software package that may be used, @file{configure.ac}
10152
should call @code{AC_ARG_WITH} to detect whether the @command{configure}
10153
user asked to use it. Whether each package is used or not by default,
10154
and which arguments are valid, is up to you.
10155
10156
@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
10157
@acindex ARG_WITH
10158
If the user gave @command{configure} the option @option{--with-@var{package}}
10159
or @option{--without-@var{package}}, run shell commands
10160
@var{action-if-given}. If neither option was given, run shell commands
10161
@var{action-if-not-given}. The name @var{package} indicates another
10162
software package that this program should work with. It should consist
10163
only of alphanumeric characters and dashes.
10164
10165
The option's argument is available to the shell commands
10166
@var{action-if-given} in the shell variable @code{withval}, which is
10167
actually just the value of the shell variable @code{with_@var{package}},
10168
with any @option{-} characters changed into @samp{_}. You may use that
10169
variable instead, if you wish.
10170
10171
The argument @var{help-string} is a description of the option that
10172
looks like this:
10173
@example
10174
--with-readline support fancy command line editing
10175
@end example
10176
10177
@noindent
10178
@var{help-string} may be more than one line long, if more detail is
10179
needed. Just make sure the columns line up in @samp{configure --help}.
10180
Avoid tabs in the help string. You'll need to enclose it in @samp{[}
10181
and @samp{]} in order to produce the leading spaces.
10182
10183
You should format your @var{help-string} with the macro
10184
@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
10185
@end defmac
10186
10187
@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given})
10188
@acindex WITH
10189
This is an obsolete version of @code{AC_ARG_WITH} that does not
10190
support providing a help string.
10191
@end defmac
10192
10193
@node Package Options
10194
@section Choosing Package Options
10195
10196
If a software package has optional compile-time features, the user can
10197
give @command{configure} command line options to specify whether to
10198
compile them. The options have one of these forms:
10199
10200
@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something
10201
@c awful.
10202
@example
10203
--enable-@var{feature}[=@var{arg}]
10204
--disable-@var{feature}
10205
@end example
10206
10207
These options allow users to choose which optional features to build and
10208
install. @option{--enable-@var{feature}} options should never make a
10209
feature behave differently or cause one feature to replace another.
10210
They should only cause parts of the program to be built rather than left
10211
out.
10212
10213
The user can give an argument by following the feature name with
10214
@samp{=} and the argument. Giving an argument of @samp{no} requests
10215
that the feature @emph{not} be made available. A feature with an
10216
argument looks like @option{--enable-debug=stabs}. If no argument is
10217
given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is
10218
equivalent to @option{--enable-@var{feature}=no}.
10219
10220
@command{configure} scripts do not complain about
10221
@option{--enable-@var{feature}} options that they do not support.
10222
This behavior permits configuring a source tree containing multiple
10223
packages with a top-level @command{configure} script when the packages
10224
support different options, without spurious error messages about options
10225
that some of the packages support.
10226
An unfortunate side effect is that option spelling errors are not diagnosed.
10227
No better approach to this problem has been suggested so far.
10228
10229
For each optional feature, @file{configure.ac} should call
10230
@code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked
10231
to include it. Whether each feature is included or not by default, and
10232
which arguments are valid, is up to you.
10233
10234
@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given})
10235
@acindex ARG_ENABLE
10236
If the user gave @command{configure} the option
10237
@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run
10238
shell commands @var{action-if-given}. If neither option was given, run
10239
shell commands @var{action-if-not-given}. The name @var{feature}
10240
indicates an optional user-level facility. It should consist only of
10241
alphanumeric characters and dashes.
10242
10243
The option's argument is available to the shell commands
10244
@var{action-if-given} in the shell variable @code{enableval}, which is
10245
actually just the value of the shell variable
10246
@code{enable_@var{feature}}, with any @option{-} characters changed into
10247
@samp{_}. You may use that variable instead, if you wish. The
10248
@var{help-string} argument is like that of @code{AC_ARG_WITH}
10249
(@pxref{External Software}).
10250
10251
You should format your @var{help-string} with the macro
10252
@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}).
10253
@end defmac
10254
10255
@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given})
10256
@acindex ENABLE
10257
This is an obsolete version of @code{AC_ARG_ENABLE} that does not
10258
support providing a help string.
10259
@end defmac
10260
10261
10262
@node Pretty Help Strings
10263
@section Making Your Help Strings Look Pretty
10264
10265
Properly formatting the @samp{help strings} which are used in
10266
@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE}
10267
(@pxref{Package Options}) can be challenging. Specifically, you want
10268
your own @samp{help strings} to line up in the appropriate columns of
10269
@samp{configure --help} just like the standard Autoconf @samp{help
10270
strings} do. This is the purpose of the @code{AC_HELP_STRING} macro.
10271
10272
@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side})
10273
@acindex HELP_STRING
10274
10275
Expands into an help string that looks pretty when the user executes
10276
@samp{configure --help}. It is typically used in @code{AC_ARG_WITH}
10277
(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package
10278
Options}). The following example will make this clearer.
10279
10280
@example
10281
AC_DEFUN(TEST_MACRO,
10282
[AC_ARG_WITH(foo,
10283
AC_HELP_STRING([--with-foo],
10284
[use foo (default is NO)]),
10285
ac_cv_use_foo=$withval, ac_cv_use_foo=no),
10286
AC_CACHE_CHECK(whether to use foo,
10287
ac_cv_use_foo, ac_cv_use_foo=no)])
10288
@end example
10289
10290
Please note that the call to @code{AC_HELP_STRING} is @strong{unquoted}.
10291
Then the last few lines of @samp{configure --help} will appear like
10292
this:
10293
10294
@example
10295
--enable and --with options recognized:
10296
--with-foo use foo (default is NO)
10297
@end example
10298
10299
The @code{AC_HELP_STRING} macro is particularly helpful when the
10300
@var{left-hand-side} and/or @var{right-hand-side} are composed of macro
10301
arguments, as shown in the following example.
10302
10303
@example
10304
AC_DEFUN(MY_ARG_WITH,
10305
[AC_ARG_WITH([$1],
10306
AC_HELP_STRING([--with-$1], [use $1 (default is $2)]),
10307
ac_cv_use_$1=$withval, ac_cv_use_$1=no),
10308
AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)])
10309
@end example
10310
@end defmac
10311
10312
10313
@node Site Details
10314
@section Configuring Site Details
10315
10316
Some software packages require complex site-specific information. Some
10317
examples are host names to use for certain services, company names, and
10318
email addresses to contact. Since some configuration scripts generated
10319
by Metaconfig ask for such information interactively, people sometimes
10320
wonder how to get that information in Autoconf-generated configuration
10321
scripts, which aren't interactive.
10322
10323
Such site configuration information should be put in a file that is
10324
edited @emph{only by users}, not by programs. The location of the file
10325
can either be based on the @code{prefix} variable, or be a standard
10326
location such as the user's home directory. It could even be specified
10327
by an environment variable. The programs should examine that file at
10328
run time, rather than at compile time. Run time configuration is more
10329
convenient for users and makes the configuration process simpler than
10330
getting the information while configuring. @xref{Directory Variables,,
10331
Variables for Installation Directories, standards, GNU Coding
10332
Standards}, for more information on where to put data files.
10333
10334
@node Transforming Names
10335
@section Transforming Program Names When Installing
10336
10337
Autoconf supports changing the names of programs when installing them.
10338
In order to use these transformations, @file{configure.ac} must call the
10339
macro @code{AC_ARG_PROGRAM}.
10340
10341
@defmac AC_ARG_PROGRAM
10342
@acindex ARG_PROGRAM
10343
@ovindex program_transform_name
10344
Place in output variable @code{program_transform_name} a sequence of
10345
@code{sed} commands for changing the names of installed programs.
10346
10347
If any of the options described below are given to @command{configure},
10348
program names are transformed accordingly. Otherwise, if
10349
@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value
10350
is given, the target type followed by a dash is used as a prefix.
10351
Otherwise, no program name transformation is done.
10352
@end defmac
10353
10354
@menu
10355
* Transformation Options:: @command{configure} options to transform names
10356
* Transformation Examples:: Sample uses of transforming names
10357
* Transformation Rules:: @file{Makefile} uses of transforming names
10358
@end menu
10359
10360
@node Transformation Options
10361
@subsection Transformation Options
10362
10363
You can specify name transformations by giving @command{configure} these
10364
command line options:
10365
10366
@table @option
10367
@item --program-prefix=@var{prefix}
10368
prepend @var{prefix} to the names;
10369
10370
@item --program-suffix=@var{suffix}
10371
append @var{suffix} to the names;
10372
10373
@item --program-transform-name=@var{expression}
10374
perform @code{sed} substitution @var{expression} on the names.
10375
@end table
10376
10377
@node Transformation Examples
10378
@subsection Transformation Examples
10379
10380
These transformations are useful with programs that can be part of a
10381
cross-compilation development environment. For example, a
10382
cross-assembler running on a Sun 4 configured with
10383
@option{--target=i960-vxworks} is normally installed as
10384
@file{i960-vxworks-as}, rather than @file{as}, which could be confused
10385
with a native Sun 4 assembler.
10386
10387
You can force a program name to begin with @file{g}, if you don't want
10388
@sc{gnu} programs installed on your system to shadow other programs with
10389
the same name. For example, if you configure @sc{gnu} @code{diff} with
10390
@option{--program-prefix=g}, then when you run @samp{make install} it is
10391
installed as @file{/usr/local/bin/gdiff}.
10392
10393
As a more sophisticated example, you could use
10394
10395
@example
10396
--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/'
10397
@end example
10398
@noindent
10399
10400
to prepend @samp{g} to most of the program names in a source tree,
10401
excepting those like @code{gdb} that already have one and those like
10402
@code{less} and @code{lesskey} that aren't @sc{gnu} programs. (That is
10403
assuming that you have a source tree containing those programs that is
10404
set up to use this feature.)
10405
10406
One way to install multiple versions of some programs simultaneously is
10407
to append a version number to the name of one or both. For example, if
10408
you want to keep Autoconf version 1 around for awhile, you can configure
10409
Autoconf version 2 using @option{--program-suffix=2} to install the
10410
programs as @file{/usr/local/bin/autoconf2},
10411
@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention
10412
that only the binaries are renamed, therefore you'd have problems with
10413
the library files which might overlap.
10414
10415
@node Transformation Rules
10416
@subsection Transformation Rules
10417
10418
Here is how to use the variable @code{program_transform_name} in a
10419
@file{Makefile.in}:
10420
10421
@example
10422
PROGRAMS = cp ls rm
10423
transform = @@program_transform_name@@
10424
install:
10425
for p in $(PROGRAMS); do \
10426
$(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \
10427
sed '$(transform)'`; \
10428
done
10429
10430
uninstall:
10431
for p in $(PROGRAMS); do \
10432
rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \
10433
done
10434
@end example
10435
10436
It is guaranteed that @code{program_transform_name} is never empty, and
10437
that there are no useless separators. Therefore you may safely embed
10438
@code{program_transform_name} within a sed program using @samp{;}:
10439
10440
@example
10441
transform = @@program_transform_name@@
10442
transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
10443
@end example
10444
10445
Whether to do the transformations on documentation files (Texinfo or
10446
@code{man}) is a tricky question; there seems to be no perfect answer,
10447
due to the several reasons for name transforming. Documentation is not
10448
usually particular to a specific architecture, and Texinfo files do not
10449
conflict with system documentation. But they might conflict with
10450
earlier versions of the same files, and @code{man} pages sometimes do
10451
conflict with system documentation. As a compromise, it is probably
10452
best to do name transformations on @code{man} pages but not on Texinfo
10453
manuals.
10454
10455
@node Site Defaults
10456
@section Setting Site Defaults
10457
10458
Autoconf-generated @command{configure} scripts allow your site to provide
10459
default values for some configuration values. You do this by creating
10460
site- and system-wide initialization files.
10461
10462
@evindex CONFIG_SITE
10463
If the environment variable @command{CONFIG_SITE} is set, @command{configure}
10464
uses its value as the name of a shell script to read. Otherwise, it
10465
reads the shell script @file{@var{prefix}/share/config.site} if it exists,
10466
then @file{@var{prefix}/etc/config.site} if it exists. Thus,
10467
settings in machine-specific files override those in machine-independent
10468
ones in case of conflict.
10469
10470
Site files can be arbitrary shell scripts, but only certain kinds of
10471
code are really appropriate to be in them. Because @command{configure}
10472
reads any cache file after it has read any site files, a site file can
10473
define a default cache file to be shared between all Autoconf-generated
10474
@command{configure} scripts run on that system (@pxref{Cache Files}). If
10475
you set a default cache file in a site file, it is a good idea to also
10476
set the output variable @code{CC} in that site file, because the cache
10477
file is only valid for a particular compiler, but many systems have
10478
several available.
10479
10480
You can examine or override the value set by a command line option to
10481
@command{configure} in a site file; options set shell variables that have
10482
the same names as the options, with any dashes turned into underscores.
10483
The exceptions are that @option{--without-} and @option{--disable-} options
10484
are like giving the corresponding @option{--with-} or @option{--enable-}
10485
option and the value @samp{no}. Thus, @option{--cache-file=localcache}
10486
sets the variable @code{cache_file} to the value @samp{localcache};
10487
@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable
10488
@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the
10489
variable @code{prefix} to the value @samp{/usr}; etc.
10490
10491
Site files are also good places to set default values for other output
10492
variables, such as @code{CFLAGS}, if you need to give them non-default
10493
values: anything you would normally do, repetitively, on the command
10494
line. If you use non-default values for @var{prefix} or
10495
@var{exec_prefix} (wherever you locate the site file), you can set them
10496
in the site file if you specify it with the @command{CONFIG_SITE}
10497
environment variable.
10498
10499
You can set some cache values in the site file itself. Doing this is
10500
useful if you are cross-compiling, so it is impossible to check features
10501
that require running a test program. You could ``prime the cache'' by
10502
setting those values correctly for that system in
10503
@file{@var{prefix}/etc/config.site}. To find out the names of the cache
10504
variables you need to set, look for shell variables with @samp{_cv_} in
10505
their names in the affected @command{configure} scripts, or in the Autoconf
10506
M4 source code for those macros.
10507
10508
The cache file is careful to not override any variables set in the site
10509
files. Similarly, you should not override command-line options in the
10510
site files. Your code should check that variables such as @code{prefix}
10511
and @code{cache_file} have their default values (as set near the top of
10512
@command{configure}) before changing them.
10513
10514
Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The
10515
command @samp{configure --prefix=/usr/share/local/gnu} would read this
10516
file (if @command{CONFIG_SITE} is not set to a different file).
10517
10518
@example
10519
# config.site for configure
10520
#
10521
# Change some defaults.
10522
test "$prefix" = NONE && prefix=/usr/share/local/gnu
10523
test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu
10524
test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var
10525
test "$localstatedir" = '$prefix/var' && localstatedir=/var
10526
10527
# Give Autoconf 2.x generated configure scripts a shared default
10528
# cache file for feature test results, architecture-specific.
10529
if test "$cache_file" = /dev/null; then
10530
cache_file="$prefix/var/config.cache"
10531
# A cache file is only valid for one C compiler.
10532
CC=gcc
10533
fi
10534
@end example
10535
10536
10537
@c ============================================== Running configure Scripts.
10538
10539
@node Running configure scripts
10540
@chapter Running @command{configure} Scripts
10541
@cindex @command{configure}
10542
10543
Below are instructions on how to configure a package that uses a
10544
@command{configure} script, suitable for inclusion as an @file{INSTALL}
10545
file in the package. A plain-text version of @file{INSTALL} which you
10546
may use comes with Autoconf.
10547
10548
@menu
10549
* Basic Installation:: Instructions for typical cases
10550
* Compilers and Options:: Selecting compilers and optimization
10551
* Multiple Architectures:: Compiling for multiple architectures at once
10552
* Installation Names:: Installing in different directories
10553
* Optional Features:: Selecting optional features
10554
* System Type:: Specifying the system type
10555
* Sharing Defaults:: Setting site-wide defaults for @command{configure}
10556
* Defining Variables:: Specifying the compiler etc.
10557
* configure Invocation:: Changing how @command{configure} runs
10558
@end menu
10559
10560
@set autoconf
10561
@include install.texi
10562
10563
10564
@c ============================================== Recreating a Configuration
10565
10566
@node config.status Invocation
10567
@chapter Recreating a Configuration
10568
@cindex @command{config.status}
10569
10570
The @command{configure} script creates a file named @file{config.status},
10571
which actually configures, @dfn{instantiates}, the template files. It
10572
also records the configuration options that were specified when the
10573
package was last configured in case reconfiguring is needed.
10574
10575
Synopsis:
10576
@example
10577
./config.status @var{option}@dots{} [@var{file}@dots{}]
10578
@end example
10579
10580
It configures the @var{files}, if none are specified, all the templates
10581
are instantiated. The files must be specified without their
10582
dependencies, as in
10583
10584
@example
10585
./config.status foobar
10586
@end example
10587
10588
@noindent
10589
not
10590
10591
@example
10592
./config.status foobar:foo.in:bar.in
10593
@end example
10594
10595
The supported @var{option}s are:
10596
10597
@table @option
10598
@item --help
10599
@itemx -h
10600
Print a summary of the command line options, the list of the template
10601
files and exit.
10602
10603
@item --version
10604
@itemx -V
10605
Print the version number of Autoconf and exit.
10606
10607
@item --debug
10608
@itemx -d
10609
Don't remove the temporary files.
10610
10611
@item --file=@var{file}[:@var{template}]
10612
Require that @var{file} be instantiated as if
10613
@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both
10614
@var{file} and @var{template} may be @samp{-} in which case the standard
10615
output and/or standard input, respectively, is used. If a
10616
@var{template} filename is relative, it is first looked for in the build
10617
tree, and then in the source tree. @xref{Configuration Actions}, for
10618
more details.
10619
10620
This option and the following ones provide one way for separately
10621
distributed packages to share the values computed by @command{configure}.
10622
Doing so can be useful if some of the packages need a superset of the
10623
features that one of them, perhaps a common library, does. These
10624
options allow a @file{config.status} file to create files other than the
10625
ones that its @file{configure.ac} specifies, so it can be used for a
10626
different package.
10627
10628
@item --header=@var{file}[:@var{template}]
10629
Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}.
10630
10631
@item --recheck
10632
Ask @file{config.status} to update itself and exit (no instantiation).
10633
This option is useful if you change @command{configure}, so that the
10634
results of some tests might be different from the previous run. The
10635
@option{--recheck} option re-runs @command{configure} with the same arguments
10636
you used before, plus the @option{--no-create} option, which prevents
10637
@command{configure} from running @file{config.status} and creating
10638
@file{Makefile} and other files, and the @option{--no-recursion} option,
10639
which prevents @command{configure} from running other @command{configure}
10640
scripts in subdirectories. (This is so other @file{Makefile} rules can
10641
run @file{config.status} when it changes; @pxref{Automatic Remaking},
10642
for an example).
10643
@end table
10644
10645
@file{config.status} checks several optional environment variables that
10646
can alter its behavior:
10647
10648
@defvar CONFIG_SHELL
10649
@evindex CONFIG_SHELL
10650
The shell with which to run @command{configure} for the @option{--recheck}
10651
option. It must be Bourne-compatible. The default is a shell that
10652
supports @env{LINENO} if available, and @file{/bin/sh} otherwise.
10653
@end defvar
10654
10655
@defvar CONFIG_STATUS
10656
@evindex CONFIG_STATUS
10657
The file name to use for the shell script that records the
10658
configuration. The default is @file{./config.status}. This variable is
10659
useful when one package uses parts of another and the @command{configure}
10660
scripts shouldn't be merged because they are maintained separately.
10661
@end defvar
10662
10663
You can use @file{./config.status} in your Makefiles. For example, in
10664
the dependencies given above (@pxref{Automatic Remaking}),
10665
@file{config.status} is run twice when @file{configure.ac} has changed.
10666
If that bothers you, you can make each run only regenerate the files for
10667
that rule:
10668
@example
10669
@group
10670
config.h: stamp-h
10671
stamp-h: config.h.in config.status
10672
./config.status config.h
10673
echo > stamp-h
10674
10675
Makefile: Makefile.in config.status
10676
./config.status Makefile
10677
@end group
10678
@end example
10679
10680
The calling convention of @file{config.status} has changed, see
10681
@ref{Obsolete config.status Use}, for details.
10682
10683
10684
@c =================================================== Obsolete Constructs
10685
10686
@node Obsolete Constructs
10687
@chapter Obsolete Constructs
10688
10689
Autoconf changes, and throughout the years some constructs are obsoleted.
10690
Most of the changes involve the macros, but the tools themselves, or
10691
even some concepts, are now considered obsolete.
10692
10693
You may completely skip this chapter if you are new to Autoconf, its
10694
intention is mainly to help maintainers updating their packages by
10695
understanding how to move to more modern constructs.
10696
10697
@menu
10698
* Obsolete config.status Use:: Different calling convention
10699
* acconfig.h:: Additional entries in @file{config.h.in}
10700
* autoupdate Invocation:: Automatic update of @file{configure.ac}
10701
* Obsolete Macros:: Backward compatibility macros
10702
* Autoconf 1:: Tips for upgrading your files
10703
* Autoconf 2.13:: Some fresher tips
10704
@end menu
10705
10706
@node Obsolete config.status Use
10707
@section Obsolete @file{config.status} Invocation
10708
10709
@file{config.status} now supports arguments to specify the files to
10710
instantiate, see @ref{config.status Invocation}, for more details.
10711
Before, environment variables had to be used.
10712
10713
@defvar CONFIG_COMMANDS
10714
@evindex CONFIG_COMMANDS
10715
The tags of the commands to execute. The default is the arguments given
10716
to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in
10717
@file{configure.ac}.
10718
@end defvar
10719
10720
@defvar CONFIG_FILES
10721
@evindex CONFIG_FILES
10722
The files in which to perform @samp{@@@var{variable}@@} substitutions.
10723
The default is the arguments given to @code{AC_OUTPUT} and
10724
@code{AC_CONFIG_FILES} in @file{configure.ac}.
10725
@end defvar
10726
10727
@defvar CONFIG_HEADERS
10728
@evindex CONFIG_HEADERS
10729
The files in which to substitute C @code{#define} statements. The
10730
default is the arguments given to @code{AC_CONFIG_HEADERS}; if that
10731
macro was not called, @file{config.status} ignores this variable.
10732
@end defvar
10733
10734
@defvar CONFIG_LINKS
10735
@evindex CONFIG_LINKS
10736
The symbolic links to establish. The default is the arguments given to
10737
@code{AC_CONFIG_LINKS}; if that macro was not called,
10738
@file{config.status} ignores this variable.
10739
@end defvar
10740
10741
In @ref{config.status Invocation}, using this old interface, the example
10742
would be:
10743
10744
@example
10745
@group
10746
config.h: stamp-h
10747
stamp-h: config.h.in config.status
10748
CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \
10749
CONFIG_HEADERS=config.h ./config.status
10750
echo > stamp-h
10751
10752
Makefile: Makefile.in config.status
10753
CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \
10754
CONFIG_FILES=Makefile ./config.status
10755
@end group
10756
@end example
10757
10758
@noindent
10759
(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is
10760
no need to set @command{CONFIG_HEADERS} in the @code{make} rules, equally
10761
for @command{CONFIG_COMMANDS} etc.)
10762
10763
10764
@node acconfig.h
10765
@section @file{acconfig.h}
10766
10767
@cindex @file{acconfig.h}
10768
@cindex @file{config.h.top}
10769
@cindex @file{config.h.bot}
10770
10771
In order to produce @file{config.h.in}, @command{autoheader} needs to
10772
build or to find templates for each symbol. Modern releases of Autoconf
10773
use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
10774
Macros}), but in older releases a file, @file{acconfig.h}, contained the
10775
list of needed templates. @command{autoheader} copies comments and
10776
@code{#define} and @code{#undef} statements from @file{acconfig.h} in
10777
the current directory, if present. This file used to be mandatory if
10778
you @code{AC_DEFINE} any additional symbols.
10779
10780
Modern releases of Autoconf also provide @code{AH_TOP} and
10781
@code{AH_BOTTOM} if you need to prepend/append some information to
10782
@file{config.h.in}. Ancient versions of Autoconf had a similar feature:
10783
if @file{./acconfig.h} contains the string @samp{@@TOP@@},
10784
@command{autoheader} copies the lines before the line containing
10785
@samp{@@TOP@@} into the top of the file that it generates. Similarly,
10786
if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
10787
@command{autoheader} copies the lines after that line to the end of the
10788
file it generates. Either or both of those strings may be omitted. An
10789
even older alternate way to produce the same effect in jurasik versions
10790
of Autoconf is to create the files @file{@var{file}.top} (typically
10791
@file{config.h.top}) and/or @file{@var{file}.bot} in the current
10792
directory. If they exist, @command{autoheader} copies them to the
10793
beginning and end, respectively, of its output.
10794
10795
In former versions of Autoconf, the files used in preparing a software
10796
package for distribution were:
10797
@example
10798
@group
10799
configure.ac --. .------> autoconf* -----> configure
10800
+---+
10801
[aclocal.m4] --+ `---.
10802
[acsite.m4] ---' |
10803
+--> [autoheader*] -> [config.h.in]
10804
[acconfig.h] ----. |
10805
+-----'
10806
[config.h.top] --+
10807
[config.h.bot] --'
10808
@end group
10809
@end example
10810
10811
Use only the @code{AH_} macros, @file{configure.ac} should be
10812
self-contained, and should not depend upon @file{acconfig.h} etc.
10813
10814
10815
@node autoupdate Invocation
10816
@section Using @command{autoupdate} to Modernize @file{configure.ac}
10817
@cindex @command{autoupdate}
10818
10819
The @command{autoupdate} program updates a @file{configure.ac} file that
10820
calls Autoconf macros by their old names to use the current macro names.
10821
In version 2 of Autoconf, most of the macros were renamed to use a more
10822
uniform and descriptive naming scheme. @xref{Macro Names}, for a
10823
description of the new scheme. Although the old names still work
10824
(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding
10825
new names), you can make your @file{configure.ac} files more readable
10826
and make it easier to use the current Autoconf documentation if you
10827
update them to use the new macro names.
10828
10829
@evindex SIMPLE_BACKUP_SUFFIX
10830
If given no arguments, @command{autoupdate} updates @file{configure.ac},
10831
backing up the original version with the suffix @file{~} (or the value
10832
of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is
10833
set). If you give @command{autoupdate} an argument, it reads that file
10834
instead of @file{configure.ac} and writes the updated file to the
10835
standard output.
10836
10837
@noindent
10838
@command{autoupdate} accepts the following options:
10839
10840
@table @option
10841
@item --help
10842
@itemx -h
10843
Print a summary of the command line options and exit.
10844
10845
@item --version
10846
@itemx -V
10847
Print the version number of Autoconf and exit.
10848
10849
@item --verbose
10850
@itemx -v
10851
Report processing steps.
10852
10853
@item --debug
10854
@itemx -d
10855
Don't remove the temporary files.
10856
10857
@item --force
10858
@itemx -f
10859
Force the update even if the file has not changed. Disregard the cache.
10860
10861
@item --include=@var{dir}
10862
@itemx -I @var{dir}
10863
Also look for input files in @var{dir}. Multiple invocations accumulate.
10864
Directories are browsed from last to first.
10865
@end table
10866
10867
@node Obsolete Macros
10868
@section Obsolete Macros
10869
10870
Several macros are obsoleted in Autoconf, for various reasons (typically
10871
they failed to quote properly, couldn't be extended for more recent
10872
issues etc.). They are still supported, but deprecated: their use
10873
should be avoided.
10874
10875
During the jump from Autoconf version 1 to version 2, most of the
10876
macros were renamed to use a more uniform and descriptive naming scheme,
10877
but their signature did not change. @xref{Macro Names}, for a
10878
description of the new naming scheme. Below, there is just the mapping
10879
from old names to new names for these macros, the reader is invited to
10880
refer to the definition of the new macro for the signature and the
10881
description.
10882
10883
@defmac AC_ALLOCA
10884
@acindex ALLOCA
10885
@code{AC_FUNC_ALLOCA}
10886
@end defmac
10887
10888
@defmac AC_ARG_ARRAY
10889
@acindex ARG_ARRAY
10890
removed because of limited usefulness
10891
@end defmac
10892
10893
@defmac AC_C_CROSS
10894
@acindex C_CROSS
10895
This macro is obsolete; it does nothing.
10896
@end defmac
10897
10898
@defmac AC_CANONICAL_SYSTEM
10899
@acindex CANONICAL_SYSTEM
10900
Determine the system type and set output variables to the names of the
10901
canonical system types. @xref{Canonicalizing}, for details about the
10902
variables this macro sets.
10903
10904
The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or
10905
@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on
10906
the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two
10907
other macros.
10908
@end defmac
10909
10910
@defmac AC_CHAR_UNSIGNED
10911
@acindex CHAR_UNSIGNED
10912
@code{AC_C_CHAR_UNSIGNED}
10913
@end defmac
10914
10915
@defmac AC_CHECK_TYPE (@var{type}, @var{default})
10916
@acindex CHECK_TYPE
10917
Autoconf, up to 2.13, used to provide this version of
10918
@code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although
10919
it is a member of the @code{CHECK} clan, singular sub-family, it does
10920
more than just checking. Second, missing types are not
10921
@code{typedef}'d, they are @code{#define}'d, which can lead to
10922
incompatible code in the case of pointer types.
10923
10924
This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see
10925
@ref{Generic Types}, for the description of the current macro.
10926
10927
If the type @var{type} is not defined, define it to be the C (or C++)
10928
builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}.
10929
10930
This macro is equivalent to:
10931
10932
@example
10933
AC_CHECK_TYPE([@var{type}],
10934
[AC_DEFINE([@var{type}], [@var{default}],
10935
[Define to `@var{default}' if <sys/types.h>
10936
does not define.])])
10937
@end example
10938
10939
In order to keep backward compatibility, the two versions of
10940
@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics:
10941
10942
@enumerate
10943
@item
10944
If there are three or four arguments, the modern version is used.
10945
10946
@item
10947
If the second argument appears to be a C or C++ type, then the
10948
obsolete version is used. This happens if the argument is a C or C++
10949
@emph{builtin} type or a C identifier ending in @samp{_t}, optionally
10950
followed by one of @samp{[(* } and then by a string of zero or more
10951
characters taken from the set @samp{[]()* _a-zA-Z0-9}.
10952
10953
@item
10954
If the second argument is spelled with the alphabet of valid C and C++
10955
types, the user is warned and the modern version is used.
10956
10957
@item
10958
Otherwise, the modern version is used.
10959
@end enumerate
10960
10961
@noindent
10962
You are encouraged either to use a valid builtin type, or to use the
10963
equivalent modern code (see above), or better yet, to use
10964
@code{AC_CHECK_TYPES} together with
10965
10966
@example
10967
#if !HAVE_LOFF_T
10968
typedef loff_t off_t;
10969
#endif
10970
@end example
10971
@end defmac
10972
@c end of AC_CHECK_TYPE
10973
10974
@defmac AC_CHECKING (@var{feature-description})
10975
@acindex CHECKING
10976
Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}.
10977
@end defmac
10978
10979
@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found})
10980
@acindex COMPILE_CHECK
10981
This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining
10982
Libraries}), with the addition that it prints @samp{checking for
10983
@var{echo-text}} to the standard output first, if @var{echo-text} is
10984
non-empty. Use @code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead
10985
to print messages (@pxref{Printing Messages}).
10986
@end defmac
10987
10988
@defmac AC_CONST
10989
@acindex CONST
10990
@code{AC_C_CONST}
10991
@end defmac
10992
10993
@defmac AC_CROSS_CHECK
10994
@acindex CROSS_CHECK
10995
Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing
10996
@code{:-)}.
10997
@end defmac
10998
10999
@defmac AC_CYGWIN
11000
@acindex CYGWIN
11001
Check for the Cygwin environment in which case the shell variable
11002
@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified
11003
means to check the nature of the host is using
11004
@code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as:
11005
11006
@example
11007
AC_REQUIRE([AC_CANONICAL_HOST])[]dnl
11008
case $host_os in
11009
*cygwin* ) CYGWIN=yes;;
11010
* ) CYGWIN=no;;
11011
esac
11012
@end example
11013
11014
Beware that the variable @code{CYGWIN} has a very special meaning when
11015
running CygWin32, and should not be changed. That's yet another reason
11016
not to use this macro.
11017
@end defmac
11018
11019
@defmac AC_DECL_YYTEXT
11020
@acindex DECL_YYTEXT
11021
Does nothing, now integrated in @code{AC_PROG_LEX}.
11022
@end defmac
11023
11024
@defmac AC_DIR_HEADER
11025
@acindex DIR_HEADER
11026
@cvindex DIRENT
11027
@cvindex SYSNDIR
11028
@cvindex SYSDIR
11029
@cvindex NDIR
11030
Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT},
11031
but defines a different set of C preprocessor macros to indicate which
11032
header file is found:
11033
11034
@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}}
11035
@item Header @tab Old Symbol @tab New Symbol
11036
@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H}
11037
@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H}
11038
@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H}
11039
@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H}
11040
@end multitable
11041
@end defmac
11042
11043
@defmac AC_DYNIX_SEQ
11044
@acindex DYNIX_SEQ
11045
If on Dynix/PTX (Sequent @sc{unix}), add @option{-lseq} to output variable
11046
@code{LIBS}. This macro used to be defined as
11047
11048
@example
11049
AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS")
11050
@end example
11051
11052
@noindent
11053
now it is just @code{AC_FUNC_GETMNTENT}.
11054
@end defmac
11055
11056
@defmac AC_EXEEXT
11057
@acindex EXEEXT
11058
@ovindex EXEEXT
11059
Defined the output variable @code{EXEEXT} based on the output of the
11060
compiler, which is now done automatically. Typically set to empty
11061
string if Unix and @samp{.exe} if Win32 or OS/2.
11062
@end defmac
11063
11064
@defmac AC_EMXOS2
11065
@acindex EMXOS2
11066
Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2
11067
and sets @code{EMXOS2}.
11068
@end defmac
11069
11070
@defmac AC_ERROR
11071
@acindex ERROR
11072
@code{AC_MSG_ERROR}
11073
@end defmac
11074
11075
@defmac AC_FIND_X
11076
@acindex FIND_X
11077
@code{AC_PATH_X}
11078
@end defmac
11079
11080
@defmac AC_FIND_XTRA
11081
@acindex FIND_XTRA
11082
@code{AC_PATH_XTRA}
11083
@end defmac
11084
11085
@defmac AC_FUNC_CHECK
11086
@acindex FUNC_CHECK
11087
@code{AC_CHECK_FUNC}
11088
@end defmac
11089
11090
@defmac AC_FUNC_WAIT3
11091
@acindex FUNC_WAIT3
11092
@cvindex HAVE_WAIT3
11093
If @code{wait3} is found and fills in the contents of its third argument
11094
(a @samp{struct rusage *}), which HP-UX does not do, define
11095
@code{HAVE_WAIT3}.
11096
11097
These days portable programs should use @code{waitpid}, not
11098
@code{wait3}, as @code{wait3} is being removed from the Open Group
11099
standards, and will not appear in the next revision of POSIX.
11100
@end defmac
11101
11102
@defmac AC_GCC_TRADITIONAL
11103
@acindex GCC_TRADITIONAL
11104
@code{AC_PROG_GCC_TRADITIONAL}
11105
@end defmac
11106
11107
@defmac AC_GETGROUPS_T
11108
@acindex GETGROUPS_T
11109
@code{AC_TYPE_GETGROUPS}
11110
@end defmac
11111
11112
@defmac AC_GETLOADAVG
11113
@acindex GETLOADAVG
11114
@code{AC_FUNC_GETLOADAVG}
11115
@end defmac
11116
11117
@defmac AC_HAVE_FUNCS
11118
@acindex HAVE_FUNCS
11119
@code{AC_CHECK_FUNCS}
11120
@end defmac
11121
11122
@defmac AC_HAVE_HEADERS
11123
@acindex HAVE_HEADERS
11124
@code{AC_CHECK_HEADERS}
11125
@end defmac
11126
11127
@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries})
11128
@acindex HAVE_LIBRARY
11129
This macro is equivalent to calling @code{AC_CHECK_LIB} with a
11130
@var{function} argument of @code{main}. In addition, @var{library} can
11131
be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In
11132
all of those cases, the compiler is passed @option{-lfoo}. However,
11133
@var{library} cannot be a shell variable; it must be a literal name.
11134
@end defmac
11135
11136
@defmac AC_HAVE_POUNDBANG
11137
@acindex HAVE_POUNDBANG
11138
@code{AC_SYS_INTERPRETER} (different calling convention)
11139
@end defmac
11140
11141
@defmac AC_HEADER_CHECK
11142
@acindex HEADER_CHECK
11143
@code{AC_CHECK_HEADER}
11144
@end defmac
11145
11146
@defmac AC_HEADER_EGREP
11147
@acindex HEADER_EGREP
11148
@code{AC_EGREP_HEADER}
11149
@end defmac
11150
11151
@defmac AC_INIT (@var{unique-file-in-source-dir})
11152
@acindex INIT
11153
Formerly @code{AC_INIT} used to have a single argument, and was
11154
equivalent to:
11155
11156
@example
11157
AC_INIT
11158
AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir})
11159
@end example
11160
@end defmac
11161
11162
@defmac AC_INLINE
11163
@acindex INLINE
11164
@code{AC_C_INLINE}
11165
@end defmac
11166
11167
@defmac AC_INT_16_BITS
11168
@acindex INT_16_BITS
11169
@cvindex INT_16_BITS
11170
If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}.
11171
Use @samp{AC_CHECK_SIZEOF(int)} instead.
11172
@end defmac
11173
11174
@defmac AC_IRIX_SUN
11175
@acindex IRIX_SUN
11176
If on IRIX (Silicon Graphics @sc{unix}), add @option{-lsun} to output
11177
@code{LIBS}. If you were using it to get @code{getmntent}, use
11178
@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions
11179
of the password and group functions, use @samp{AC_CHECK_LIB(sun,
11180
getpwnam)}. Up to Autoconf 2.13, it used to be
11181
11182
@example
11183
AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS")
11184
@end example
11185
11186
@noindent
11187
now it is defined as
11188
11189
@example
11190
AC_FUNC_GETMNTENT
11191
AC_CHECK_LIB(sun, getpwnam)
11192
@end example
11193
@end defmac
11194
11195
@defmac AC_LANG_C
11196
@acindex LANG_C
11197
Same as @samp{AC_LANG(C)}.
11198
@end defmac
11199
11200
@defmac AC_LANG_CPLUSPLUS
11201
@acindex LANG_CPLUSPLUS
11202
Same as @samp{AC_LANG(C++)}.
11203
@end defmac
11204
11205
@defmac AC_LANG_FORTRAN77
11206
@acindex LANG_FORTRAN77
11207
Same as @samp{AC_LANG(Fortran 77)}.
11208
@end defmac
11209
11210
@defmac AC_LANG_RESTORE
11211
@acindex LANG_RESTORE
11212
Select the @var{language} that is saved on the top of the stack, as set
11213
by @code{AC_LANG_SAVE}, remove it from the stack, and call
11214
@code{AC_LANG(@var{language})}.
11215
@end defmac
11216
11217
@defmac AC_LANG_SAVE
11218
@acindex LANG_SAVE
11219
Remember the current language (as set by @code{AC_LANG}) on a stack.
11220
The current language does not change. @code{AC_LANG_PUSH} is preferred.
11221
@end defmac
11222
11223
@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{})
11224
@acindex LINK_FILES
11225
This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated
11226
version of:
11227
11228
@example
11229
AC_LINK_FILES(config/$machine.h config/$obj_format.h,
11230
host.h object.h)
11231
@end example
11232
11233
@noindent
11234
is:
11235
11236
@example
11237
AC_CONFIG_LINKS(host.h:config/$machine.h
11238
object.h:config/$obj_format.h)
11239
@end example
11240
@end defmac
11241
11242
@defmac AC_LN_S
11243
@acindex LN_S
11244
@code{AC_PROG_LN_S}
11245
@end defmac
11246
11247
@defmac AC_LONG_64_BITS
11248
@acindex LONG_64_BITS
11249
@cvindex LONG_64_BITS
11250
Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide.
11251
Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead.
11252
@end defmac
11253
11254
@defmac AC_LONG_DOUBLE
11255
@acindex LONG_DOUBLE
11256
@code{AC_C_LONG_DOUBLE}
11257
@end defmac
11258
11259
@defmac AC_LONG_FILE_NAMES
11260
@acindex LONG_FILE_NAMES
11261
@code{AC_SYS_LONG_FILE_NAMES}
11262
@end defmac
11263
11264
@defmac AC_MAJOR_HEADER
11265
@acindex MAJOR_HEADER
11266
@code{AC_HEADER_MAJOR}
11267
@end defmac
11268
11269
@defmac AC_MEMORY_H
11270
@acindex MEMORY_H
11271
@cvindex NEED_MEMORY_H
11272
Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were
11273
defined in @file{memory.h}. Today it is equivalent to
11274
@samp{AC_CHECK_HEADERS(memory.h)}. Adjust your code to depend upon
11275
@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @xref{Standard
11276
Symbols}.
11277
@end defmac
11278
11279
@defmac AC_MINGW32
11280
@acindex MINGW32
11281
Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler
11282
environment and sets @code{MINGW32}.
11283
@end defmac
11284
11285
@defmac AC_MINUS_C_MINUS_O
11286
@acindex MINUS_C_MINUS_O
11287
@code{AC_PROG_CC_C_O}
11288
@end defmac
11289
11290
@defmac AC_MMAP
11291
@acindex MMAP
11292
@code{AC_FUNC_MMAP}
11293
@end defmac
11294
11295
@defmac AC_MODE_T
11296
@acindex MODE_T
11297
@code{AC_TYPE_MODE_T}
11298
@end defmac
11299
11300
@defmac AC_OBJEXT
11301
@acindex OBJEXT
11302
@ovindex OBJEXT
11303
Defined the output variable @code{OBJEXT} based on the output of the
11304
compiler, after .c files have been excluded. Typically set to @samp{o}
11305
if Unix, @samp{obj} if Win32. Now the compiler checking macros handle
11306
this automatically.
11307
@end defmac
11308
11309
@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion})
11310
@acindex OBSOLETE
11311
Make @code{m4} print a message to the standard error output warning that
11312
@var{this-macro-name} is obsolete, and giving the file and line number
11313
where it was called. @var{this-macro-name} should be the name of the
11314
macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given,
11315
it is printed at the end of the warning message; for example, it can be
11316
a suggestion for what to use instead of @var{this-macro-name}.
11317
11318
For instance
11319
11320
@example
11321
AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
11322
@end example
11323
11324
You are encouraged to use @code{AU_DEFUN} instead, since it gives better
11325
services to the user.
11326
@end defmac
11327
11328
@defmac AC_OFF_T
11329
@acindex OFF_T
11330
@code{AC_TYPE_OFF_T}
11331
@end defmac
11332
11333
@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds})
11334
@acindex OUTPUT
11335
The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted
11336
interface is equivalent to:
11337
11338
@example
11339
@group
11340
AC_CONFIG_FILES(@var{file}@dots{})
11341
AC_CONFIG_COMMANDS([default],
11342
@var{extra-cmds}, @var{init-cmds})
11343
AC_OUTPUT
11344
@end group
11345
@end example
11346
@end defmac
11347
11348
@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds})
11349
@acindex OUTPUT_COMMANDS
11350
Specify additional shell commands to run at the end of
11351
@file{config.status}, and shell commands to initialize any variables
11352
from @command{configure}. This macro may be called multiple times. It is
11353
obsolete, replaced by @code{AC_CONFIG_COMMANDS}.
11354
11355
Here is an unrealistic example:
11356
11357
@example
11358
fubar=27
11359
AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.],
11360
[fubar=$fubar])
11361
AC_OUTPUT_COMMANDS([echo this is another, extra, bit],
11362
[echo init bit])
11363
@end example
11364
11365
Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an
11366
additional key, an important difference is that
11367
@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while
11368
@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS}
11369
can safely be given macro calls as arguments:
11370
11371
@example
11372
AC_CONFIG_COMMANDS(foo, [my_FOO()])
11373
@end example
11374
11375
@noindent
11376
conversely, where one level of quoting was enough for literal strings
11377
with @code{AC_OUTPUT_COMMANDS}, you need two with
11378
@code{AC_CONFIG_COMMANDS}. The following lines are equivalent:
11379
11380
@example
11381
@group
11382
AC_OUTPUT_COMMANDS([echo "Square brackets: []"])
11383
AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
11384
@end group
11385
@end example
11386
@end defmac
11387
11388
@defmac AC_PID_T
11389
@acindex PID_T
11390
@code{AC_TYPE_PID_T}
11391
@end defmac
11392
11393
@defmac AC_PREFIX
11394
@acindex PREFIX
11395
@code{AC_PREFIX_PROGRAM}
11396
@end defmac
11397
11398
@defmac AC_PROGRAMS_CHECK
11399
@acindex PROGRAMS_CHECK
11400
@code{AC_CHECK_PROGS}
11401
@end defmac
11402
11403
@defmac AC_PROGRAMS_PATH
11404
@acindex PROGRAMS_PATH
11405
@code{AC_PATH_PROGS}
11406
@end defmac
11407
11408
@defmac AC_PROGRAM_CHECK
11409
@acindex PROGRAM_CHECK
11410
@code{AC_CHECK_PROG}
11411
@end defmac
11412
11413
@defmac AC_PROGRAM_EGREP
11414
@acindex PROGRAM_EGREP
11415
@code{AC_EGREP_CPP}
11416
@end defmac
11417
11418
@defmac AC_PROGRAM_PATH
11419
@acindex PROGRAM_PATH
11420
@code{AC_PATH_PROG}
11421
@end defmac
11422
11423
@defmac AC_REMOTE_TAPE
11424
@acindex REMOTE_TAPE
11425
removed because of limited usefulness
11426
@end defmac
11427
11428
@defmac AC_RESTARTABLE_SYSCALLS
11429
@acindex RESTARTABLE_SYSCALLS
11430
@code{AC_SYS_RESTARTABLE_SYSCALLS}
11431
@end defmac
11432
11433
@defmac AC_RETSIGTYPE
11434
@acindex RETSIGTYPE
11435
@code{AC_TYPE_SIGNAL}
11436
@end defmac
11437
11438
@defmac AC_RSH
11439
@acindex RSH
11440
Removed because of limited usefulness.
11441
@end defmac
11442
11443
@defmac AC_SCO_INTL
11444
@acindex SCO_INTL
11445
@ovindex LIBS
11446
If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}. This
11447
macro used to
11448
11449
@example
11450
AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS")
11451
@end example
11452
11453
@noindent
11454
now it just calls @code{AC_FUNC_STRFTIME} instead.
11455
@end defmac
11456
11457
@defmac AC_SETVBUF_REVERSED
11458
@acindex SETVBUF_REVERSED
11459
@code{AC_FUNC_SETVBUF_REVERSED}
11460
@end defmac
11461
11462
@defmac AC_SET_MAKE
11463
@acindex SET_MAKE
11464
@code{AC_PROG_MAKE_SET}
11465
@end defmac
11466
11467
@defmac AC_SIZEOF_TYPE
11468
@acindex SIZEOF_TYPE
11469
@code{AC_CHECK_SIZEOF}
11470
@end defmac
11471
11472
@defmac AC_SIZE_T
11473
@acindex SIZE_T
11474
@code{AC_TYPE_SIZE_T}
11475
@end defmac
11476
11477
@defmac AC_STAT_MACROS_BROKEN
11478
@acindex STAT_MACROS_BROKEN
11479
@code{AC_HEADER_STAT}
11480
@end defmac
11481
11482
@defmac AC_STDC_HEADERS
11483
@acindex STDC_HEADERS
11484
@code{AC_HEADER_STDC}
11485
@end defmac
11486
11487
@defmac AC_STRCOLL
11488
@acindex STRCOLL
11489
@code{AC_FUNC_STRCOLL}
11490
@end defmac
11491
11492
@defmac AC_ST_BLKSIZE
11493
@acindex ST_BLKSIZE
11494
@code{AC_STRUCT_ST_BLKSIZE}
11495
@end defmac
11496
11497
@defmac AC_ST_BLOCKS
11498
@acindex ST_BLOCKS
11499
@code{AC_STRUCT_ST_BLOCKS}
11500
@end defmac
11501
11502
@defmac AC_ST_RDEV
11503
@acindex ST_RDEV
11504
@code{AC_STRUCT_ST_RDEV}
11505
@end defmac
11506
11507
@defmac AC_SYS_RESTARTABLE_SYSCALLS
11508
@acindex SYS_RESTARTABLE_SYSCALLS
11509
@cvindex HAVE_RESTARTABLE_SYSCALLS
11510
If the system automatically restarts a system call that is interrupted
11511
by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does
11512
not check if system calls are restarted in general--it tests whether a
11513
signal handler installed with @code{signal} (but not @code{sigaction})
11514
causes system calls to be restarted. It does not test if system calls
11515
can be restarted when interrupted by signals that have no handler.
11516
11517
These days portable programs should use @code{sigaction} with
11518
@code{SA_RESTART} if they want restartable system calls. They should
11519
not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a
11520
system call is restartable is a dynamic issue, not a configuration-time
11521
issue.
11522
@end defmac
11523
11524
@defmac AC_SYS_SIGLIST_DECLARED
11525
@acindex SYS_SIGLIST_DECLARED
11526
@code{AC_DECL_SYS_SIGLIST}
11527
@end defmac
11528
11529
@defmac AC_TEST_CPP
11530
@acindex TEST_CPP
11531
@code{AC_TRY_CPP}
11532
@end defmac
11533
11534
@defmac AC_TEST_PROGRAM
11535
@acindex TEST_PROGRAM
11536
@code{AC_TRY_RUN}
11537
@end defmac
11538
11539
@defmac AC_TIMEZONE
11540
@acindex TIMEZONE
11541
@code{AC_STRUCT_TIMEZONE}
11542
@end defmac
11543
11544
@defmac AC_TIME_WITH_SYS_TIME
11545
@acindex TIME_WITH_SYS_TIME
11546
@code{AC_HEADER_TIME}
11547
@end defmac
11548
11549
@defmac AC_UID_T
11550
@acindex UID_T
11551
@code{AC_TYPE_UID_T}
11552
@end defmac
11553
11554
@defmac AC_UNISTD_H
11555
@acindex UNISTD_H
11556
Same as @samp{AC_CHECK_HEADERS(unistd.h)}.
11557
@end defmac
11558
11559
@defmac AC_USG
11560
@acindex USG
11561
@cvindex USG
11562
Define @code{USG} if the @sc{bsd} string functions are defined in
11563
@file{strings.h}. You should no longer depend upon @code{USG}, but on
11564
@code{HAVE_STRING_H}, see @xref{Standard Symbols}.
11565
@end defmac
11566
11567
@defmac AC_UTIME_NULL
11568
@acindex UTIME_NULL
11569
@code{AC_FUNC_UTIME_NULL}
11570
@end defmac
11571
11572
@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd})
11573
@acindex VALIDATE_CACHED_SYSTEM_TUPLE
11574
If the cache file is inconsistent with the current host, target and
11575
build system types, it used to execute @var{cmd} or print a default
11576
error message.
11577
11578
This is now handled by default.
11579
@end defmac
11580
11581
@defmac AC_VERBOSE (@var{result-description})
11582
@acindex VERBOSE
11583
@code{AC_MSG_RESULT}.
11584
@end defmac
11585
11586
@defmac AC_VFORK
11587
@acindex VFORK
11588
@code{AC_FUNC_VFORK}
11589
@end defmac
11590
11591
@defmac AC_VPRINTF
11592
@acindex VPRINTF
11593
@code{AC_FUNC_VPRINTF}
11594
@end defmac
11595
11596
@defmac AC_WAIT3
11597
@acindex WAIT3
11598
@code{AC_FUNC_WAIT3}
11599
@end defmac
11600
11601
@defmac AC_WARN
11602
@acindex WARN
11603
@code{AC_MSG_WARN}
11604
@end defmac
11605
11606
@defmac AC_WORDS_BIGENDIAN
11607
@acindex WORDS_BIGENDIAN
11608
@code{AC_C_BIGENDIAN}
11609
@end defmac
11610
11611
@defmac AC_XENIX_DIR
11612
@acindex XENIX_DIR
11613
@ovindex LIBS
11614
This macro used to add @option{-lx} to output variable @code{LIBS} if on
11615
Xenix. Also, if @file{dirent.h} is being checked for, added
11616
@option{-ldir} to @code{LIBS}. Now it is merely an alias of
11617
@code{AC_HEADER_DIRENT} instead, plus some code to detect whether
11618
running @sc{xenix} on which you should not depend:
11619
11620
@example
11621
AC_MSG_CHECKING([for Xenix])
11622
AC_EGREP_CPP(yes,
11623
[#if defined M_XENIX && !defined M_UNIX
11624
yes
11625
#endif],
11626
[AC_MSG_RESULT([yes]); XENIX=yes],
11627
[AC_MSG_RESULT([no]); XENIX=])
11628
@end example
11629
@end defmac
11630
11631
@defmac AC_YYTEXT_POINTER
11632
@acindex YYTEXT_POINTER
11633
@code{AC_DECL_YYTEXT}
11634
@end defmac
11635
11636
@node Autoconf 1
11637
@section Upgrading From Version 1
11638
11639
Autoconf version 2 is mostly backward compatible with version 1.
11640
However, it introduces better ways to do some things, and doesn't
11641
support some of the ugly things in version 1. So, depending on how
11642
sophisticated your @file{configure.ac} files are, you might have to do
11643
some manual work in order to upgrade to version 2. This chapter points
11644
out some problems to watch for when upgrading. Also, perhaps your
11645
@command{configure} scripts could benefit from some of the new features in
11646
version 2; the changes are summarized in the file @file{NEWS} in the
11647
Autoconf distribution.
11648
11649
@menu
11650
* Changed File Names:: Files you might rename
11651
* Changed Makefiles:: New things to put in @file{Makefile.in}
11652
* Changed Macros:: Macro calls you might replace
11653
* Changed Results:: Changes in how to check test results
11654
* Changed Macro Writing:: Better ways to write your own macros
11655
@end menu
11656
11657
@node Changed File Names
11658
@subsection Changed File Names
11659
11660
If you have an @file{aclocal.m4} installed with Autoconf (as opposed to
11661
in a particular package's source directory), you must rename it to
11662
@file{acsite.m4}. @xref{autoconf Invocation}.
11663
11664
If you distribute @file{install.sh} with your package, rename it to
11665
@file{install-sh} so @code{make} builtin rules won't inadvertently
11666
create a file called @file{install} from it. @code{AC_PROG_INSTALL}
11667
looks for the script under both names, but it is best to use the new name.
11668
11669
If you were using @file{config.h.top}, @file{config.h.bot}, or
11670
@file{acconfig.h}, you still can, but you will have less clutter if you
11671
use the @code{AH_} macros. @xref{Autoheader Macros}.
11672
11673
@node Changed Makefiles
11674
@subsection Changed Makefiles
11675
11676
Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in
11677
your @file{Makefile.in} files, so they can take advantage of the values
11678
of those variables in the environment when @command{configure} is run.
11679
Doing this isn't necessary, but it's a convenience for users.
11680
11681
Also add @samp{@@configure_input@@} in a comment to each input file for
11682
@code{AC_OUTPUT}, so that the output files will contain a comment saying
11683
they were produced by @command{configure}. Automatically selecting the
11684
right comment syntax for all the kinds of files that people call
11685
@code{AC_OUTPUT} on became too much work.
11686
11687
Add @file{config.log} and @file{config.cache} to the list of files you
11688
remove in @code{distclean} targets.
11689
11690
If you have the following in @file{Makefile.in}:
11691
11692
@example
11693
prefix = /usr/local
11694
exec_prefix = $(prefix)
11695
@end example
11696
11697
@noindent
11698
you must change it to:
11699
11700
@example
11701
prefix = @@prefix@@
11702
exec_prefix = @@exec_prefix@@
11703
@end example
11704
11705
@noindent
11706
The old behavior of replacing those variables without @samp{@@}
11707
characters around them has been removed.
11708
11709
@node Changed Macros
11710
@subsection Changed Macros
11711
11712
Many of the macros were renamed in Autoconf version 2. You can still
11713
use the old names, but the new ones are clearer, and it's easier to find
11714
the documentation for them. @xref{Obsolete Macros}, for a table showing the
11715
new names for the old macros. Use the @command{autoupdate} program to
11716
convert your @file{configure.ac} to using the new macro names.
11717
@xref{autoupdate Invocation}.
11718
11719
Some macros have been superseded by similar ones that do the job better,
11720
but are not call-compatible. If you get warnings about calling obsolete
11721
macros while running @command{autoconf}, you may safely ignore them, but
11722
your @command{configure} script will generally work better if you follow
11723
the advice it prints about what to replace the obsolete macros with. In
11724
particular, the mechanism for reporting the results of tests has
11725
changed. If you were using @code{echo} or @code{AC_VERBOSE} (perhaps
11726
via @code{AC_COMPILE_CHECK}), your @command{configure} script's output will
11727
look better if you switch to @code{AC_MSG_CHECKING} and
11728
@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best
11729
in conjunction with cache variables. @xref{Caching Results}.
11730
11731
11732
11733
@node Changed Results
11734
@subsection Changed Results
11735
11736
If you were checking the results of previous tests by examining the
11737
shell variable @code{DEFS}, you need to switch to checking the values of
11738
the cache variables for those tests. @code{DEFS} no longer exists while
11739
@command{configure} is running; it is only created when generating output
11740
files. This difference from version 1 is because properly quoting the
11741
contents of that variable turned out to be too cumbersome and
11742
inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache
11743
Variable Names}.
11744
11745
For example, here is a @file{configure.ac} fragment written for Autoconf
11746
version 1:
11747
11748
@example
11749
AC_HAVE_FUNCS(syslog)
11750
case "$DEFS" in
11751
*-DHAVE_SYSLOG*) ;;
11752
*) # syslog is not in the default libraries. See if it's in some other.
11753
saved_LIBS="$LIBS"
11754
for lib in bsd socket inet; do
11755
AC_CHECKING(for syslog in -l$lib)
11756
LIBS="$saved_LIBS -l$lib"
11757
AC_HAVE_FUNCS(syslog)
11758
case "$DEFS" in
11759
*-DHAVE_SYSLOG*) break ;;
11760
*) ;;
11761
esac
11762
LIBS="$saved_LIBS"
11763
done ;;
11764
esac
11765
@end example
11766
11767
Here is a way to write it for version 2:
11768
11769
@example
11770
AC_CHECK_FUNCS(syslog)
11771
if test $ac_cv_func_syslog = no; then
11772
# syslog is not in the default libraries. See if it's in some other.
11773
for lib in bsd socket inet; do
11774
AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG)
11775
LIBS="$LIBS -l$lib"; break])
11776
done
11777
fi
11778
@end example
11779
11780
If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding
11781
backslashes before quotes, you need to remove them. It now works
11782
predictably, and does not treat quotes (except back quotes) specially.
11783
@xref{Setting Output Variables}.
11784
11785
All of the boolean shell variables set by Autoconf macros now use
11786
@samp{yes} for the true value. Most of them use @samp{no} for false,
11787
though for backward compatibility some use the empty string instead. If
11788
you were relying on a shell variable being set to something like 1 or
11789
@samp{t} for true, you need to change your tests.
11790
11791
@node Changed Macro Writing
11792
@subsection Changed Macro Writing
11793
11794
When defining your own macros, you should now use @code{AC_DEFUN}
11795
instead of @code{define}. @code{AC_DEFUN} automatically calls
11796
@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE}
11797
do not interrupt other macros, to prevent nested @samp{checking@dots{}}
11798
messages on the screen. There's no actual harm in continuing to use the
11799
older way, but it's less convenient and attractive. @xref{Macro
11800
Definitions}.
11801
11802
You probably looked at the macros that came with Autoconf as a guide for
11803
how to do things. It would be a good idea to take a look at the new
11804
versions of them, as the style is somewhat improved and they take
11805
advantage of some new features.
11806
11807
If you were doing tricky things with undocumented Autoconf internals
11808
(macros, variables, diversions), check whether you need to change
11809
anything to account for changes that have been made. Perhaps you can
11810
even use an officially supported technique in version 2 instead of
11811
kludging. Or perhaps not.
11812
11813
To speed up your locally written feature tests, add caching to them.
11814
See whether any of your tests are of general enough usefulness to
11815
encapsulate into macros that you can share.
11816
11817
11818
@node Autoconf 2.13
11819
@section Upgrading From Version 2.13
11820
11821
The introduction of the previous section (@pxref{Autoconf 1}) perfectly
11822
suits this section...
11823
11824
@quotation
11825
Autoconf version 2.50 is mostly backward compatible with version 2.13.
11826
However, it introduces better ways to do some things, and doesn't
11827
support some of the ugly things in version 2.13. So, depending on how
11828
sophisticated your @file{configure.ac} files are, you might have to do
11829
some manual work in order to upgrade to version 2.50. This chapter
11830
points out some problems to watch for when upgrading. Also, perhaps
11831
your @command{configure} scripts could benefit from some of the new
11832
features in version 2.50; the changes are summarized in the file
11833
@file{NEWS} in the Autoconf distribution.
11834
@end quotation
11835
11836
@menu
11837
* Changed Quotation:: Broken code which used to work
11838
* New Macros:: Interaction with foreign macros
11839
* Hosts and Cross-Compilation:: Bugward compatibility kludges
11840
* AC_LIBOBJ vs. LIBOBJS:: LIBOBJS is a forbidden token
11841
@end menu
11842
11843
@node Changed Quotation
11844
@subsection Changed Quotation
11845
11846
The most important changes are invisible to you: the implementation of
11847
most macros have completely changed. This allowed more factorization of
11848
the code, better error messages, a higher uniformity of the user's
11849
interface etc. Unfortunately, as a side effect, some construct which
11850
used to (miraculously) work might break starting with Autoconf 2.50.
11851
The most common culprit is bad quotation.
11852
11853
For instance, in the following example, the message is not properly
11854
quoted:
11855
11856
@example
11857
AC_INIT
11858
AC_CHECK_HEADERS(foo.h,,
11859
AC_MSG_ERROR(cannot find foo.h, bailing out))
11860
AC_OUTPUT
11861
@end example
11862
11863
@noindent
11864
Autoconf 2.13 simply ignores it:
11865
11866
@example
11867
$ @kbd{autoconf-2.13; ./configure --silent}
11868
creating cache ./config.cache
11869
configure: error: cannot find foo.h
11870
$
11871
@end example
11872
11873
@noindent
11874
while Autoconf 2.50 will produce a broken @file{configure}:
11875
11876
@example
11877
$ @kbd{autoconf-2.50; ./configure --silent}
11878
configure: error: cannot find foo.h
11879
./configure: exit: bad non-numeric arg `bailing'
11880
./configure: exit: bad non-numeric arg `bailing'
11881
$
11882
@end example
11883
11884
The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation
11885
too!
11886
11887
@example
11888
AC_INIT
11889
AC_CHECK_HEADERS(foo.h,,
11890
[AC_MSG_ERROR([cannot find foo.h, bailing out])])
11891
AC_OUTPUT
11892
@end example
11893
11894
Many many (and many more) Autoconf macros were lacking proper quotation,
11895
including no less than... @code{AC_DEFUN} itself!
11896
11897
@example
11898
$ @kbd{cat configure.in}
11899
AC_DEFUN([AC_PROG_INSTALL],
11900
[# My own much better version
11901
])
11902
AC_INIT
11903
AC_PROG_INSTALL
11904
AC_OUTPUT
11905
$ @kbd{autoconf-2.13}
11906
autoconf: Undefined macros:
11907
***BUG in Autoconf--please report*** AC_FD_MSG
11908
***BUG in Autoconf--please report*** AC_EPI
11909
configure.in:1:AC_DEFUN([AC_PROG_INSTALL],
11910
configure.in:5:AC_PROG_INSTALL
11911
$ @kbd{autoconf-2.50}
11912
$
11913
@end example
11914
11915
11916
@node New Macros
11917
@subsection New Macros
11918
11919
@cindex @code{undefined macro: _m4_divert_diversion}
11920
11921
Because Autoconf has been dormant for years, Automake provided
11922
Autoconf-like macros for a while. Autoconf 2.50 now provides better
11923
versions of these macros, integrated in the @code{AC_} namespace,
11924
instead of @code{AM_}. But in order to ease the upgrading via
11925
@command{autoupdate}, bindings to such @code{AM_} macros are provided.
11926
11927
Unfortunately Automake did not quote the name of these macros!
11928
Therefore, when @command{m4} finds something like
11929
@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)} in @file{aclocal.m4},
11930
@code{AM_TYPE_PTRDIFF_T} is
11931
expanded, replaced with its Autoconf definition.
11932
11933
Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will
11934
complain, in its own words:
11935
11936
@example
11937
$ @kbd{cat configure.in}
11938
AC_INIT
11939
AM_TYPE_PTRDIFF_T
11940
$ @kbd{aclocal-1.4}
11941
$ @kbd{autoconf}
11942
./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion
11943
actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from...
11944
./aclocal.m4:17: the top level
11945
$
11946
@end example
11947
11948
Future versions of Automake will simply no longer define most of these
11949
macros, and will properly quote the names of the remaining macros.
11950
But you don't have to wait for it to happen to do the right thing right
11951
now: do not depend upon macros from Automake as it is simply not its job
11952
to provide macros (but the one it requires by itself):
11953
11954
@example
11955
$ @kbd{cat configure.in}
11956
AC_INIT
11957
AM_TYPE_PTRDIFF_T
11958
$ @kbd{rm aclocal.m4}
11959
$ @kbd{autoupdate}
11960
autoupdate: `configure.in' is updated
11961
$ @kbd{cat configure.in}
11962
AC_INIT
11963
AC_CHECK_TYPES([ptrdiff_t])
11964
$ @kbd{aclocal-1.4}
11965
$ @kbd{autoconf}
11966
$
11967
@end example
11968
11969
11970
@node Hosts and Cross-Compilation
11971
@subsection Hosts and Cross-Compilation
11972
11973
Based on the experience of compiler writers, and after long public
11974
debates, many aspects of the cross-compilation chain have changed:
11975
11976
@itemize @minus
11977
@item
11978
the relationship between the build, host, and target architecture types,
11979
11980
@item
11981
the command line interface for specifying them to @command{configure},
11982
11983
@item
11984
the variables defined in @command{configure},
11985
11986
@item
11987
the enabling of cross-compilation mode.
11988
@end itemize
11989
11990
@sp 1
11991
11992
The relationship between build, host, and target have been cleaned up:
11993
the chain of default is now simply: target defaults to host, host to
11994
build, and build to the result of @command{config.guess}. Nevertheless,
11995
in order to ease the transition from 2.13 to 2.50, the following
11996
transition scheme is implemented. @emph{Do not rely on it}, as it will
11997
be completely disabled in a couple of releases (we cannot keep it, as it
11998
proves to cause more problems than to cure).
11999
12000
They all default to the result of running @command{config.guess}, unless
12001
you specify either @option{--build} or @option{--host}. In this case,
12002
the default becomes the system type you specified. If you specify both,
12003
and they're different, @command{configure} will enter cross compilation
12004
mode, so it won't run any tests that require execution.
12005
12006
Hint: if you mean to override the result of @command{config.guess},
12007
prefer @option{--build} over @option{--host}. In the future,
12008
@option{--host} will not override the name of the build system type.
12009
Whenever you specify @code{--host}, be sure to specify @code{--build}
12010
too.
12011
12012
@sp 1
12013
12014
For backward compatibility, @command{configure} will accept a system
12015
type as an option by itself. Such an option will override the defaults
12016
for build, host and target system types. The following configure
12017
statement will configure a cross toolchain that will run on NetBSD/alpha
12018
but generate code for GNU Hurd/sparc, which is also the build platform.
12019
12020
@example
12021
./configure --host=alpha-netbsd sparc-gnu
12022
@end example
12023
12024
@sp 1
12025
12026
In Autoconf, the variables @code{build}, @code{host}, and @code{target}
12027
had a different semantics before and after the invocation of
12028
@code{AC_CANONICAL_BUILD} etc. Now, the argument of @option{--build} is
12029
strictly copied into @code{build_alias}, and is left empty otherwise.
12030
After the @code{AC_CANONICAL_BUILD}, @code{build} is set to the
12031
canonicalized build type. To ease the transition, before, its contents
12032
is the same as that of @code{build_alias}. Do @emph{not} rely on this
12033
broken feature.
12034
12035
For consistency with the backward compatibility scheme exposed above,
12036
when @option{--host} is specified by @option{--build} isn't, the build
12037
system will be assumed to be the same as @option{--host}, and
12038
@samp{build_alias} will be set to that value. Eventually, this
12039
historically incorrect behavior will go away.
12040
12041
@sp 1
12042
12043
The former scheme to enable cross-compilation proved to cause more harm
12044
than good, in particular, it used to be triggered too easily, leaving
12045
regular end users puzzled in front of cryptic error messages.
12046
@command{configure} could even enter cross-compilation mode, only
12047
because the compiler was not functional. This is mainly because
12048
@command{configure} used to try to detect cross-compilation, instead of
12049
waiting for an explicit flag from the user.
12050
12051
Now, @command{configure} enters cross-compilation mode iff
12052
@option{--host} is passed.
12053
12054
That's the short documentation. To ease the transition between 2.13 and
12055
its successors, a more complicated scheme is implemented. @emph{Do not
12056
rely on the following}, as it will be removed in a near future.
12057
12058
If you specify @option{--host}, but not @option{--build}, when
12059
@command{configure} performs the first compiler test it will try to run
12060
an executable produced by the compiler. If the execution fails, it will
12061
enter cross-compilation mode. This is fragile. Moreover, by the time
12062
the compiler test is performed, it may be too late to modify the
12063
build-system type: other tests may have already been performed.
12064
Therefore, whenever you specify @code{--host}, be sure to specify
12065
@code{--build} too.
12066
12067
@example
12068
./configure --build=i686-pc-linux-gnu --host=m68k-coff
12069
@end example
12070
12071
@noindent
12072
will enter cross-compilation mode. The former interface, which
12073
consisted in setting the compiler to a cross-compiler without informing
12074
@command{configure} is obsolete. For instance, @command{configure} will
12075
fail if it can't run the code generated by the specified compiler if you
12076
configure as follows:
12077
12078
@example
12079
./configure CC=m68k-coff-gcc
12080
@end example
12081
12082
12083
@node AC_LIBOBJ vs. LIBOBJS
12084
@subsection @code{AC_LIBOBJ} vs. @code{LIBOBJS}
12085
12086
Up to Autoconf 2.13, the replacement of functions was triggered via the
12087
variable @code{LIBOBJS}. Since Autoconf 2.50, the macro
12088
@code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}).
12089
Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error.
12090
12091
This change is mandated by the unification of the GNU Build System
12092
components. In particular, the various fragile techniques used to parse
12093
a @file{configure.ac} are all replaced with the use of traces. As a
12094
consequence, any action must be traceable, which obsoletes critical
12095
variable assignments. Fortunately, @code{LIBOBJS} was the only problem.
12096
12097
At the time this documentation is written, Automake does not rely on
12098
traces yet, but this is planed for a near future. Nevertheless, to
12099
ease the transition, and to guarantee this future Automake release will
12100
be able to use Autoconf 2.53, using @code{LIBOBJS} directly will make
12101
@command{autoconf} fail. But note that the output, @command{configure},
12102
is correct and fully functional: you have some delay to adjust your
12103
source.
12104
12105
There are two typical uses of @code{LIBOBJS}: asking for a replacement
12106
function, and adjusting @code{LIBOBJS} for Automake and/or Libtool.
12107
12108
@sp 1
12109
12110
As for function replacement, the fix is immediate: use
12111
@code{AC_LIBOBJ}. For instance:
12112
12113
@example
12114
LIBOBJS="$LIBOBJS fnmatch.o"
12115
LIBOBJS="$LIBOBJS malloc.$ac_objext"
12116
@end example
12117
12118
@noindent
12119
should be replaced with:
12120
12121
@example
12122
AC_LIBOBJ([fnmatch])
12123
AC_LIBOBJ([malloc])
12124
@end example
12125
12126
@sp 1
12127
12128
When asked for automatic de-ANSI-fication, Automake needs
12129
@code{LIBOBJS}'ed filenames to have @samp{$U} appended to the
12130
base names. Libtool requires the definition of @code{LTLIBOBJS}, which
12131
suffixes are mapped to @samp{.lo}. Although Autoconf provides them with
12132
means to free the user to do that by herself, by the time of this
12133
writing, none do. Therefore, it is common to see @file{configure.ac}
12134
end with:
12135
12136
@example
12137
# This is necessary so that .o files in LIBOBJS are also built via
12138
# the ANSI2KNR-filtering rules.
12139
LIBOBJS=`echo "$LIBOBJS" | sed 's/\.o /\$U.o /g;s/\.o$/\$U.o/'`
12140
LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/\.lo/g'`
12141
AC_SUBST(LTLIBOBJS)
12142
@end example
12143
12144
@noindent
12145
First, note that this code is @emph{wrong}, because @samp{.o} is not the
12146
only possible extension@footnote{
12147
@c
12148
Yet another reason why assigning @code{LIBOBJS} directly is discouraged.
12149
@c
12150
}! Because the token @code{LIBOBJS} is now
12151
forbidden, you will have to replace this snippet with:
12152
12153
@example
12154
# This is necessary so that .o files in LIBOBJS are also built via
12155
# the ANSI2KNR-filtering rules.
12156
LIB@@&t@@OBJS=`echo "$LIB@@&t@@OBJS" |
12157
sed 's,\.[[^.]]* ,$U&,g;s,\.[[^.]]*$,$U&,'`
12158
LTLIBOBJS=`echo "$LIB@@&t@@OBJS" |
12159
sed 's,\.[[^.]]* ,.lo ,g;s,\.[[^.]]*$,.lo,'`
12160
AC_SUBST(LTLIBOBJS)
12161
@end example
12162
12163
@noindent
12164
Unfortunately, @command{autoupdate} cannot help here, since... this is
12165
not a macro! Of course, first make sure your release of Automake and/or
12166
Libtool still requires these.
12167
12168
@c ============================= Generating Test Suites with Autotest
12169
12170
@node Using Autotest
12171
@chapter Generating Test Suites with Autotest
12172
12173
@cindex Autotest
12174
12175
@display
12176
@strong{Note: This section describes an experimental feature which will
12177
be part of Autoconf in a forthcoming release. Although we believe
12178
Autotest is stabilizing, this documentation describes an interface which
12179
might change in the future: do not depend upon Autotest without
12180
subscribing to the Autoconf mailing lists.}
12181
@end display
12182
12183
It is paradoxical that portable projects depend on nonportable tools to
12184
run their test suite. Autoconf by itself is the paragon of this
12185
problem: although it aims at perfectly portability, up to 2.13, its test
12186
suite was using DejaGNU, a rich and complex testing framework, but which
12187
is far from being standard on Unix systems. Worse yet, it was likely to
12188
be missing on the most fragile platforms, the very platforms that are
12189
most likely to torture Autoconf and exhibit deficiencies.
12190
12191
To circumvent this problem many package maintainers have developed their
12192
own testing framework, based on simple shell scripts whose sole output
12193
are their exit status: the test succeeded, or failed. In addition, most
12194
of these tests share some common patterns, what results in lots of
12195
duplicated code, tedious maintenance etc.
12196
12197
Following exactly the same reasoning that yielded to the inception of
12198
Autoconf, Autotest provides a test suite generation frame work, based on
12199
M4 macros, building a portable shell script. The suite itself is
12200
equipped with automatic logging and tracing facilities which greatly
12201
diminish the interaction with bug reporters, and simple timing reports.
12202
12203
Autoconf itself has been using Autotest for years, and we do attest that
12204
it has considerably improved the strength of the test suite, and the
12205
quality of bug reports. Other projects are known to use some generation
12206
of Autotest, such as Bison, Free Recode, Free Wdiff, GNU Tar, each of
12207
them having different needs, what slowly polishes Autotest as a general
12208
testing framework.
12209
12210
Nonetheless, compared to DejaGNU, Autotest is inadequate for interactive
12211
tool testing, which is probably its main limitation.
12212
12213
@menu
12214
* Using an Autotest Test Suite:: Autotest and the user
12215
* Writing testsuite.at:: Autotest macros
12216
* testsuite Invocation:: Running @command{testsuite} scripts
12217
* Making testsuite Scripts:: Using autom4te to create @command{testsuite}
12218
@end menu
12219
12220
@node Using an Autotest Test Suite
12221
@section Using an Autotest Test Suite
12222
12223
@menu
12224
* testsuite Scripts:: The concepts of Autotest
12225
* Autotest Logs:: Their contents
12226
@end menu
12227
12228
@node testsuite Scripts
12229
@subsection @command{testsuite} Scripts
12230
12231
@cindex @command{testsuite}
12232
12233
Generating testing or validation suites using Autotest is rather easy.
12234
The whole validation suite is held in a file to be processed through
12235
@command{autom4te}, itself using GNU @code{m4} under the scene, to
12236
produce a stand-alone Bourne shell script which then gets distributed.
12237
Neither @command{autom4te} nor GNU @code{m4} are not needed anymore at
12238
the installer end.
12239
12240
@cindex test group
12241
Each test of the validation suite should be part of some test group. A
12242
@dfn{test group} is a sequence of interwoven tests that ought to be
12243
executed together, usually because one test in the group creates data
12244
files than a later test in the same group needs to read. Complex test
12245
groups make later debugging more tedious. It is much better keeping
12246
keep only a few tests per test group, and if you can put only one test
12247
per test group, this is just ideal.
12248
12249
For all but the simplest packages, some file such as @file{testsuite.at}
12250
does not fully hold all test sources, as these are often easier to
12251
maintain in separate files. Each of these separate files holds a single
12252
test group, or a sequence of test groups all addressing some common
12253
functionality in the package. In such cases, file @file{testsuite.at}
12254
only initializes the whole validation suite, and sometimes do elementary
12255
health checking, before listing include statements for all other test
12256
files. The special file @file{package.m4}, containing the
12257
identification of the package, is automatically included if found.
12258
12259
The validation scripts that Autotest produces are by convention called
12260
@command{testsuite}. When run, @command{testsuite} executes each test
12261
group in turn, producing only one summary line per test to say if that
12262
particular test succeeded or failed. At end of all tests, summarizing
12263
counters get printed. If any test failed, one debugging script gets
12264
automatically generated for each test group which failed. These
12265
debugging scripts are named @file{testsuite.@var{nn}}, where @var{nn} is
12266
the sequence number of the test group. In the ideal situation, none of
12267
the tests fail, and consequently, no debugging script is generated out
12268
of validation.
12269
12270
The automatic generation of debugging scripts for failed test has the
12271
purpose of easing the chase for bugs.
12272
12273
It often happens in practice that individual tests in the validation
12274
suite need to get information coming out of the configuration process.
12275
Some of this information, common for all validation suites, is provided
12276
through the file @file{atconfig}, automatically created by
12277
@code{AC_CONFIG_TESTDIR}. For configuration informations which your
12278
testing environment specifically needs, you might prepare an optional
12279
file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}.
12280
The configuration process produces @file{atconfig} and @file{atlocal}
12281
out of these two input files, and these two produced files are
12282
automatically read by the @file{testsuite} script.
12283
12284
Here is a diagram showing the relationship between files.
12285
12286
@noindent
12287
Files used in preparing a software package for distribution:
12288
12289
@example
12290
subfile-1.at ->.
12291
... \
12292
subfile-i.at ---->-- testsuite.at -->.
12293
... / \
12294
subfile-n.at ->' >-- autom4te* -->testsuite
12295
/
12296
[package.m4] ->'
12297
@end example
12298
12299
@noindent
12300
Files used in configuring a software package:
12301
12302
@example
12303
.--> atconfig
12304
/
12305
[atlocal.in] --> config.status* --<
12306
\
12307
`--> [atlocal]
12308
@end example
12309
12310
@noindent
12311
Files created during the test suite execution:
12312
12313
@example
12314
atconfig -->. .--> testsuite.log
12315
\ /
12316
>-- testsuite* --<
12317
/ \
12318
[atlocal] ->' `--> [testsuite.@var{nn}*]
12319
@end example
12320
12321
12322
@node Autotest Logs
12323
@subsection Autotest Logs
12324
12325
When run, the test suite creates a log file named after itself, e.g., a
12326
test suite named @command{testsuite} creates @file{testsuite.log}. It
12327
contains a lot of information, usually more than maintainers actually
12328
need, but therefore most of the time it contains all that is needed:
12329
12330
@table @asis
12331
@item command line arguments
12332
@c akim s/to consist in/to consist of/
12333
A very bad Unix habit which is unfortunately wide spread consists of
12334
setting environment variables before the command, such as in
12335
@samp{CC=my-home-grown-cc ./testsuite}. This results in the test suite
12336
not knowing this change, hence (i) it can't report it to you, and (ii)
12337
it cannot preserve the value of @code{CC} for subsequent runs@footnote{
12338
@c
12339
When a failure occurs, the test suite is rerun, verbosely, and the user
12340
is asked to ``play'' with this failure to provide better information.
12341
It is important to keep the same environment between the first run, and
12342
bug-tracking runs.
12343
@c
12344
}. Autoconf faced exactly the same problem, and solved it by asking
12345
users to pass the variable definitions as command line arguments.
12346
Autotest requires this rule too, but has no means to enforce it; the log
12347
then contains a trace of the variables the user changed.
12348
12349
@item @file{ChangeLog} excerpts
12350
The topmost lines of all the @file{ChangeLog}s found in the source
12351
hierarchy. This is especially useful when bugs are reported against
12352
development versions of the package, since the version string does not
12353
provide sufficient information to know the exact state of the sources
12354
the user compiled. Of course this relies on the use of a
12355
@file{ChangeLog}.
12356
12357
@item build machine
12358
Running a test suite in a cross-compile environment is not an easy task,
12359
since it would mean having the test suite run on a machine @var{build},
12360
while running programs on a machine @var{host}. It is much simpler to
12361
run both the test suite and the programs on @var{host}, but then, from
12362
the point of view of the test suite, there remains a single environment,
12363
@var{host} = @var{build}. The log contains relevant information on the
12364
state of the build machine, including some important environment
12365
variables.
12366
@c FIXME: How about having an M4sh macro to say `hey, log the value
12367
@c of `...'? This would help both Autoconf and Autotest.
12368
12369
@item tested programs
12370
The absolute path and answers to @option{--version} of the tested
12371
programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}).
12372
12373
@item configuration log
12374
The contents of @file{config.log}, as created by @command{configure},
12375
are appended. It contains the configuration flags and a detailed report
12376
on the configuration itself.
12377
@end table
12378
12379
12380
@node Writing testsuite.at
12381
@section Writing @file{testsuite.at}
12382
12383
The @file{testsuite.at} is a Bourne shell script making use of special
12384
Autotest M4 macros. It often contains a call to @code{AT_INIT} nears
12385
its beginning followed by one call to @code{m4_include} per source file
12386
for tests. Each such included file, or the remainder of
12387
@file{testsuite.at} if include files are not used, contain a sequence of
12388
test groups. Each test group begins with one call to @code{AT_SETUP},
12389
it contains an arbitrary number of shell commands or calls to
12390
@code{AT_CHECK}, and it completes with one call to @code{AT_CLEANUP}.
12391
12392
@defmac AT_INIT (@ovar{name})
12393
@atindex INIT
12394
@c FIXME: Not clear, plus duplication of the information.
12395
Initialize Autotest. Giving a @var{name} to the test suite is
12396
encouraged if your package includes several test suites. In any case,
12397
the test suite always displays the package name and version. It also
12398
inherits the package bug report address.
12399
@end defmac
12400
12401
@defmac AT_TESTED (@var{executables})
12402
@atindex TESTED
12403
Log the path and answer to @option{--version} of each program in
12404
space-separated list @var{executables}. Several invocations register
12405
new executables, in other words, don't fear registering one program
12406
several times.
12407
@end defmac
12408
12409
Autotest test suites rely on the @code{PATH} to find the tested program.
12410
This saves from generating the absolute paths to the various tools, and
12411
makes it possible to test installed programs. Therefore, knowing what
12412
programs are being exercised is crucial to understand some problems in
12413
the test suite itself, or its occasional misuses. It is a good idea to
12414
also subscribe foreign programs you depend upon, to ease incompatibility
12415
diagnostics.
12416
12417
@sp 1
12418
12419
@defmac AT_SETUP (@var{test-group-name})
12420
@atindex SETUP
12421
This macro starts a group of related tests, all to be executed in the
12422
same subshell. It accepts a single argument, which holds a few words
12423
(no more than about 30 or 40 characters) quickly describing the purpose
12424
of the test group being started.
12425
@end defmac
12426
12427
@defmac AT_KEYWORDS (@var{keywords})
12428
@atindex KEYWORDS
12429
Associate the space-separated list of @var{keywords} to the enclosing
12430
test group. This makes it possible to run ``slices'' of the test suite.
12431
For instance if some of your test groups exercise some @samp{foo}
12432
feature, then using @samp{AT_KEYWORDS(foo)} lets you run
12433
@samp{./testsuite -k foo} to run exclusively these test groups. The
12434
@var{title} of the test group is automatically recorded to
12435
@code{AT_KEYWORDS}.
12436
12437
Several invocations within a test group accumulate new keywords. In
12438
other words, don't fear registering several times the same keyword in a
12439
test group.
12440
@end defmac
12441
12442
@defmac AT_CLEANUP
12443
@atindex CLEANUP
12444
End the current test group.
12445
@end defmac
12446
12447
@sp 1
12448
12449
@defmac AT_DATA (@var{file}, @var{contents})
12450
@atindex DATA
12451
Initialize an input data @var{file} with given @var{contents}. Of
12452
course, the @var{contents} have to be properly quoted between square
12453
brackets to protect against included commas or spurious @code{m4}
12454
expansion. The contents ought to end with an end of line.
12455
@end defmac
12456
12457
@defmac AT_CHECK (@var{commands}, @dvar{status, @samp{0}}, @ovar{stdout}, @ovar{stderr})
12458
@atindex CHECK
12459
Execute a test by performing given shell @var{commands}. These commands
12460
should normally exit with @var{status}, while producing expected
12461
@var{stdout} and @var{stderr} contents. If @var{commands} exit with
12462
status 77, then the whole test group is skipped.
12463
12464
The @var{commands} @emph{must not} redirect the standard output, nor the
12465
standard error.
12466
12467
If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then
12468
the corresponding value is not checked.
12469
12470
The special value @samp{expout} for @var{stdout} means the expected
12471
output of the @var{commands} is the content of the file @file{expout}.
12472
If @var{stdout} is @samp{stdout}, then the standard output of the
12473
@var{commands} is available for further tests in the file @file{stdout}.
12474
Similarly for @var{stderr} with @samp{expout} and @samp{stderr}.
12475
@end defmac
12476
12477
12478
@node testsuite Invocation
12479
@section Running @command{testsuite} Scripts
12480
@cindex @command{testsuite}
12481
12482
Autotest test suites support the following arguments:
12483
12484
@table @samp
12485
@item --help
12486
@itemx -h
12487
Display the list of options and exit successfully.
12488
12489
@item --version
12490
@itemx -V
12491
Display the version of the test suite and exit successfully.
12492
12493
@item --clean
12494
@itemx -c
12495
Remove all the files the test suite might have created and exit. Meant
12496
for @code{clean} Makefile targets.
12497
12498
@item --list
12499
@itemx -l
12500
List all the tests (or only the selection), including their possible
12501
keywords.
12502
@end table
12503
12504
@sp 1
12505
12506
By default all the tests are performed (or described with
12507
@option{--list}) in the default environment first silently, then
12508
verbosely, but the environment, set of tests, and verbosity level can be
12509
tuned:
12510
12511
@table @samp
12512
@item @var{variable}=@var{value}
12513
Set the environment @var{variable} to @var{value}. Do not run
12514
@samp{FOO=foo ./testsuite} as debugging scripts would then run in a
12515
different environment.
12516
12517
@cindex @code{AUTOTEST_PATH}
12518
The variable @code{AUTOTEST_PATH} specifies the testing path to prepend
12519
to @code{PATH}. It handles specially relative paths (not starting with
12520
@samp{/}): they are considered to be relative to the top level of the
12521
package being built. All the directories are made absolute, first
12522
starting from the top level @emph{build} tree, then from the
12523
@emph{source} tree. For instance @samp{./testsuite
12524
AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built
12525
in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and
12526
then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to
12527
@code{PATH}.
12528
12529
@item @var{number}
12530
@itemx @var{number}-@var{number}
12531
@itemx @var{number}-
12532
@itemx -@var{number}
12533
Add the corresponding test groups, with obvious semantics, to the
12534
selection.
12535
12536
@item --keywords=@var{keywords}
12537
@itemx -k @var{keywords}
12538
Add to the selection the test groups which title or keywords (arguments
12539
to @code{AT_SETUP} or @code{AT_KEYWORDS}) match @emph{all} the keywords
12540
of the comma separated list @var{keywords}.
12541
12542
Running @samp{./testsuite -k autoupdate,FUNC} will select all the tests
12543
tagged with @samp{autoupdate} @emph{and} @samp{FUNC} (as in
12544
@samp{AC_CHECK_FUNC}, @samp{AC_FUNC_FNMATCH} etc.) while
12545
@samp{./testsuite -k autoupdate -k FUNC} runs all the tests tagged with
12546
@samp{autoupdate} @emph{or} @samp{FUNC}.
12547
12548
@item --errexit
12549
@itemx -e
12550
If any test fails, immediately abort testing. It implies
12551
@option{--debug}: post test group clean up, debugging script generation,
12552
and logging are inhibited. This option is meant for the full test
12553
suite, it is not really useful for generated debugging scripts.
12554
12555
@item --verbose
12556
@itemx -v
12557
Force more verbosity in the detailed output of what is being done. This
12558
is the default for debugging scripts.
12559
12560
@item --debug
12561
@itemx -d
12562
Do not remove the files after a test group was performed ---but they are
12563
still removed @emph{before}, therefore using this option is sane when
12564
running several test groups. Do not create debugging scripts. Do not
12565
log (in order to preserve supposedly existing full log file). This is
12566
the default for debugging scripts.
12567
12568
@item --trace
12569
@itemx -x
12570
Trigger shell tracing of the test groups.
12571
@end table
12572
12573
12574
@node Making testsuite Scripts
12575
@section Making @command{testsuite} Scripts
12576
12577
For putting Autotest into movement, you need some configuration and
12578
Makefile machinery. We recommend, at least if your package uses deep or
12579
shallow hierarchies, that you use @file{tests/} as the name of the
12580
directory holding all your tests and their @file{Makefile}. Here is a
12581
check list of things to do.
12582
12583
@itemize @minus
12584
12585
@item
12586
@cindex @file{package.m4}
12587
Make sure to create the file @file{package.m4}, which defines the
12588
identity of the package. It must define @code{AT_PACKAGE_STRING}, the
12589
full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the
12590
address to which bug reports should be sent. For sake of completeness,
12591
we suggest that you also define @code{AT_PACKAGE_NAME},
12592
@code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}.
12593
@xref{Initializing configure}, for a description of these variables. We
12594
suggest the following Makefile excerpt:
12595
12596
@smallexample
12597
$(srcdir)/package.m4: $(top_srcdir)/configure.ac
12598
@{ \
12599
echo '# Signature of the current package.'; \
12600
echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \
12601
echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \
12602
echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \
12603
echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \
12604
echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \
12605
@} >$(srcdir)/package.m4
12606
@end smallexample
12607
12608
@noindent
12609
Be sure to distribute @file{package.m4} and to put it into the source
12610
hierarchy: the test suite ought to be shipped!
12611
12612
@item
12613
@c FIXME: This macro should become part of Autoconf. AC_AUTOTEST_PATH?
12614
Use the @code{AT_CONFIG} macro from within file @file{configure.ac}.
12615
This macro accepts one argument, which is the directory, relative to the
12616
test directory, where the executables are prepared.
12617
12618
@item
12619
Still within @file{configure.ac}, ensure that some
12620
@code{AC_CONFIG_FILES} command includes substitution for
12621
@file{tests/atconfig} and also, as appropriate, @file{tests/atlocal}.
12622
12623
@item
12624
The @file{tests/Makefile.in} should be modified so the validation in
12625
your package is triggered by @samp{make check}. An example is provided
12626
below.
12627
12628
@end itemize
12629
12630
With Automake, here is a minimal example about how to link @samp{make
12631
check} with a validation suite.
12632
12633
@example
12634
EXTRA_DIST = testsuite.at testsuite
12635
TESTSUITE = $(srcdir)/testsuite
12636
check-local: atconfig atlocal $(TESTSUITE)
12637
$(SHELL) $(TESTSUITE)
12638
12639
AUTOTEST = $(AUTOM4TE) --language=autotest
12640
$(TESTSUITE): $(srcdir)/testsuite.at
12641
$(AUTOTEST) -I $(srcdir) $@.at -o $@.tmp
12642
mv $@.tmp $@
12643
@end example
12644
12645
You might want to list explicitly the dependencies, i.e., the list of
12646
the files @file{testsuite.at} includes.
12647
12648
With strict Autoconf, you might need to add lines inspired from the
12649
following:
12650
12651
@example
12652
subdir = tests
12653
12654
atconfig: $(top_builddir)/config.status
12655
cd $(top_builddir) && \
12656
$(SHELL) ./config.status $(subdir)/$@
12657
12658
atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status
12659
cd $(top_builddir) && \
12660
$(SHELL) ./config.status $(subdir)/$@
12661
@end example
12662
12663
@noindent
12664
and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)}
12665
distributed.
12666
12667
12668
12669
@c ================================================ Questions About Autoconf.
12670
12671
@node Questions
12672
@chapter Questions About Autoconf
12673
12674
Several questions about Autoconf come up occasionally. Here some of them
12675
are addressed.
12676
12677
@menu
12678
* Distributing:: Distributing @command{configure} scripts
12679
* Why GNU m4:: Why not use the standard M4?
12680
* Bootstrapping:: Autoconf and GNU M4 require each other?
12681
* Why Not Imake:: Why GNU uses @command{configure} instead of Imake
12682
@end menu
12683
12684
@node Distributing
12685
@section Distributing @command{configure} Scripts
12686
12687
@display
12688
What are the restrictions on distributing @command{configure}
12689
scripts that Autoconf generates? How does that affect my
12690
programs that use them?
12691
@end display
12692
12693
There are no restrictions on how the configuration scripts that Autoconf
12694
produces may be distributed or used. In Autoconf version 1, they were
12695
covered by the @sc{gnu} General Public License. We still encourage
12696
software authors to distribute their work under terms like those of the
12697
GPL, but doing so is not required to use Autoconf.
12698
12699
Of the other files that might be used with @command{configure},
12700
@file{config.h.in} is under whatever copyright you use for your
12701
@file{configure.ac}. @file{config.sub} and @file{config.guess} have an
12702
exception to the GPL when they are used with an Autoconf-generated
12703
@command{configure} script, which permits you to distribute them under the
12704
same terms as the rest of your package. @file{install-sh} is from the X
12705
Consortium and is not copyrighted.
12706
12707
@node Why GNU m4
12708
@section Why Require GNU M4?
12709
12710
@display
12711
Why does Autoconf require @sc{gnu} M4?
12712
@end display
12713
12714
Many M4 implementations have hard-coded limitations on the size and
12715
number of macros that Autoconf exceeds. They also lack several
12716
builtin macros that it would be difficult to get along without in a
12717
sophisticated application like Autoconf, including:
12718
12719
@example
12720
m4_builtin
12721
m4_indir
12722
m4_bpatsubst
12723
__file__
12724
__line__
12725
@end example
12726
12727
Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses
12728
frozen state files.
12729
12730
Since only software maintainers need to use Autoconf, and since @sc{gnu}
12731
M4 is simple to configure and install, it seems reasonable to require
12732
@sc{gnu} M4 to be installed also. Many maintainers of @sc{gnu} and
12733
other free software already have most of the @sc{gnu} utilities
12734
installed, since they prefer them.
12735
12736
@node Bootstrapping
12737
@section How Can I Bootstrap?
12738
12739
@display
12740
If Autoconf requires @sc{gnu} M4 and @sc{gnu} M4 has an Autoconf
12741
@command{configure} script, how do I bootstrap? It seems like a chicken
12742
and egg problem!
12743
@end display
12744
12745
This is a misunderstanding. Although @sc{gnu} M4 does come with a
12746
@command{configure} script produced by Autoconf, Autoconf is not required
12747
in order to run the script and install @sc{gnu} M4. Autoconf is only
12748
required if you want to change the M4 @command{configure} script, which few
12749
people have to do (mainly its maintainer).
12750
12751
@node Why Not Imake
12752
@section Why Not Imake?
12753
12754
@display
12755
Why not use Imake instead of @command{configure} scripts?
12756
@end display
12757
12758
Several people have written addressing this question, so I include
12759
adaptations of their explanations here.
12760
12761
The following answer is based on one written by Richard Pixley:
12762
12763
@quotation
12764
Autoconf generated scripts frequently work on machines that it has
12765
never been set up to handle before. That is, it does a good job of
12766
inferring a configuration for a new system. Imake cannot do this.
12767
12768
Imake uses a common database of host specific data. For X11, this makes
12769
sense because the distribution is made as a collection of tools, by one
12770
central authority who has control over the database.
12771
12772
@sc{gnu} tools are not released this way. Each @sc{gnu} tool has a
12773
maintainer; these maintainers are scattered across the world. Using a
12774
common database would be a maintenance nightmare. Autoconf may appear
12775
to be this kind of database, but in fact it is not. Instead of listing
12776
host dependencies, it lists program requirements.
12777
12778
If you view the @sc{gnu} suite as a collection of native tools, then the
12779
problems are similar. But the @sc{gnu} development tools can be
12780
configured as cross tools in almost any host+target permutation. All of
12781
these configurations can be installed concurrently. They can even be
12782
configured to share host independent files across hosts. Imake doesn't
12783
address these issues.
12784
12785
Imake templates are a form of standardization. The @sc{gnu} coding
12786
standards address the same issues without necessarily imposing the same
12787
restrictions.
12788
@end quotation
12789
12790
12791
Here is some further explanation, written by Per Bothner:
12792
12793
@quotation
12794
One of the advantages of Imake is that it easy to generate large
12795
Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms.
12796
However, @code{cpp} is not programmable: it has limited conditional
12797
facilities, and no looping. And @code{cpp} cannot inspect its
12798
environment.
12799
12800
All of these problems are solved by using @code{sh} instead of
12801
@code{cpp}. The shell is fully programmable, has macro substitution,
12802
can execute (or source) other shell scripts, and can inspect its
12803
environment.
12804
@end quotation
12805
12806
12807
Paul Eggert elaborates more:
12808
12809
@quotation
12810
With Autoconf, installers need not assume that Imake itself is already
12811
installed and working well. This may not seem like much of an advantage
12812
to people who are accustomed to Imake. But on many hosts Imake is not
12813
installed or the default installation is not working well, and requiring
12814
Imake to install a package hinders the acceptance of that package on
12815
those hosts. For example, the Imake template and configuration files
12816
might not be installed properly on a host, or the Imake build procedure
12817
might wrongly assume that all source files are in one big directory
12818
tree, or the Imake configuration might assume one compiler whereas the
12819
package or the installer needs to use another, or there might be a
12820
version mismatch between the Imake expected by the package and the Imake
12821
supported by the host. These problems are much rarer with Autoconf,
12822
where each package comes with its own independent configuration
12823
processor.
12824
12825
Also, Imake often suffers from unexpected interactions between
12826
@code{make} and the installer's C preprocessor. The fundamental problem
12827
here is that the C preprocessor was designed to preprocess C programs,
12828
not @file{Makefile}s. This is much less of a problem with Autoconf,
12829
which uses the general-purpose preprocessor @code{m4}, and where the
12830
package's author (rather than the installer) does the preprocessing in a
12831
standard way.
12832
@end quotation
12833
12834
12835
Finally, Mark Eichin notes:
12836
12837
@quotation
12838
Imake isn't all that extensible, either. In order to add new features to
12839
Imake, you need to provide your own project template, and duplicate most
12840
of the features of the existing one. This means that for a sophisticated
12841
project, using the vendor-provided Imake templates fails to provide any
12842
leverage---since they don't cover anything that your own project needs
12843
(unless it is an X11 program).
12844
12845
On the other side, though:
12846
12847
The one advantage that Imake has over @command{configure}:
12848
@file{Imakefile}s tend to be much shorter (likewise, less redundant)
12849
than @file{Makefile.in}s. There is a fix to this, however---at least
12850
for the Kerberos V5 tree, we've modified things to call in common
12851
@file{post.in} and @file{pre.in} @file{Makefile} fragments for the
12852
entire tree. This means that a lot of common things don't have to be
12853
duplicated, even though they normally are in @command{configure} setups.
12854
@end quotation
12855
12856
12857
12858
12859
@c ===================================================== History of Autoconf.
12860
12861
@node History
12862
@chapter History of Autoconf
12863
12864
You may be wondering, Why was Autoconf originally written? How did it
12865
get into its present form? (Why does it look like gorilla spit?) If
12866
you're not wondering, then this chapter contains no information useful
12867
to you, and you might as well skip it. If you @emph{are} wondering,
12868
then let there be light@dots{}
12869
12870
@menu
12871
* Genesis:: Prehistory and naming of @command{configure}
12872
* Exodus:: The plagues of M4 and Perl
12873
* Leviticus:: The priestly code of portability arrives
12874
* Numbers:: Growth and contributors
12875
* Deuteronomy:: Approaching the promises of easy configuration
12876
@end menu
12877
12878
@node Genesis
12879
@section Genesis
12880
12881
In June 1991 I was maintaining many of the @sc{gnu} utilities for the
12882
Free Software Foundation. As they were ported to more platforms and
12883
more programs were added, the number of @option{-D} options that users
12884
had to select in the @file{Makefile} (around 20) became burdensome.
12885
Especially for me---I had to test each new release on a bunch of
12886
different systems. So I wrote a little shell script to guess some of
12887
the correct settings for the fileutils package, and released it as part
12888
of fileutils 2.0. That @command{configure} script worked well enough that
12889
the next month I adapted it (by hand) to create similar @command{configure}
12890
scripts for several other @sc{gnu} utilities packages. Brian Berliner
12891
also adapted one of my scripts for his @sc{cvs} revision control system.
12892
12893
Later that summer, I learned that Richard Stallman and Richard Pixley
12894
were developing similar scripts to use in the @sc{gnu} compiler tools;
12895
so I adapted my @command{configure} scripts to support their evolving
12896
interface: using the file name @file{Makefile.in} as the templates;
12897
adding @samp{+srcdir}, the first option (of many); and creating
12898
@file{config.status} files.
12899
12900
@node Exodus
12901
@section Exodus
12902
12903
As I got feedback from users, I incorporated many improvements, using
12904
Emacs to search and replace, cut and paste, similar changes in each of
12905
the scripts. As I adapted more @sc{gnu} utilities packages to use
12906
@command{configure} scripts, updating them all by hand became impractical.
12907
Rich Murphey, the maintainer of the @sc{gnu} graphics utilities, sent me
12908
mail saying that the @command{configure} scripts were great, and asking if
12909
I had a tool for generating them that I could send him. No, I thought,
12910
but I should! So I started to work out how to generate them. And the
12911
journey from the slavery of hand-written @command{configure} scripts to the
12912
abundance and ease of Autoconf began.
12913
12914
Cygnus @command{configure}, which was being developed at around that time,
12915
is table driven; it is meant to deal mainly with a discrete number of
12916
system types with a small number of mainly unguessable features (such as
12917
details of the object file format). The automatic configuration system
12918
that Brian Fox had developed for Bash takes a similar approach. For
12919
general use, it seems to me a hopeless cause to try to maintain an
12920
up-to-date database of which features each variant of each operating
12921
system has. It's easier and more reliable to check for most features on
12922
the fly---especially on hybrid systems that people have hacked on
12923
locally or that have patches from vendors installed.
12924
12925
I considered using an architecture similar to that of Cygnus
12926
@command{configure}, where there is a single @command{configure} script that
12927
reads pieces of @file{configure.in} when run. But I didn't want to have
12928
to distribute all of the feature tests with every package, so I settled
12929
on having a different @command{configure} made from each
12930
@file{configure.in} by a preprocessor. That approach also offered more
12931
control and flexibility.
12932
12933
I looked briefly into using the Metaconfig package, by Larry Wall,
12934
Harlan Stenn, and Raphael Manfredi, but I decided not to for several
12935
reasons. The @command{Configure} scripts it produces are interactive,
12936
which I find quite inconvenient; I didn't like the ways it checked for
12937
some features (such as library functions); I didn't know that it was
12938
still being maintained, and the @command{Configure} scripts I had
12939
seen didn't work on many modern systems (such as System V R4 and NeXT);
12940
it wasn't very flexible in what it could do in response to a feature's
12941
presence or absence; I found it confusing to learn; and it was too big
12942
and complex for my needs (I didn't realize then how much Autoconf would
12943
eventually have to grow).
12944
12945
I considered using Perl to generate my style of @command{configure}
12946
scripts, but decided that M4 was better suited to the job of simple
12947
textual substitutions: it gets in the way less, because output is
12948
implicit. Plus, everyone already has it. (Initially I didn't rely on
12949
the @sc{gnu} extensions to M4.) Also, some of my friends at the
12950
University of Maryland had recently been putting M4 front ends on
12951
several programs, including @code{tvtwm}, and I was interested in trying
12952
out a new language.
12953
12954
@node Leviticus
12955
@section Leviticus
12956
12957
Since my @command{configure} scripts determine the system's capabilities
12958
automatically, with no interactive user intervention, I decided to call
12959
the program that generates them Autoconfig. But with a version number
12960
tacked on, that name would be too long for old @sc{unix} file systems,
12961
so I shortened it to Autoconf.
12962
12963
In the fall of 1991 I called together a group of fellow questers after
12964
the Holy Grail of portability (er, that is, alpha testers) to give me
12965
feedback as I encapsulated pieces of my handwritten scripts in M4 macros
12966
and continued to add features and improve the techniques used in the
12967
checks. Prominent among the testers were Fran@,cois Pinard, who came up
12968
with the idea of making an @file{autoconf} shell script to run @code{m4}
12969
and check for unresolved macro calls; Richard Pixley, who suggested
12970
running the compiler instead of searching the file system to find
12971
include files and symbols, for more accurate results; Karl Berry, who
12972
got Autoconf to configure @TeX{} and added the macro index to the
12973
documentation; and Ian Lance Taylor, who added support for creating a C
12974
header file as an alternative to putting @option{-D} options in a
12975
@file{Makefile}, so he could use Autoconf for his @sc{uucp} package.
12976
The alpha testers cheerfully adjusted their files again and again as the
12977
names and calling conventions of the Autoconf macros changed from
12978
release to release. They all contributed many specific checks, great
12979
ideas, and bug fixes.
12980
12981
@node Numbers
12982
@section Numbers
12983
12984
In July 1992, after months of alpha testing, I released Autoconf 1.0,
12985
and converted many @sc{gnu} packages to use it. I was surprised by how
12986
positive the reaction to it was. More people started using it than I
12987
could keep track of, including people working on software that wasn't
12988
part of the @sc{gnu} Project (such as TCL, FSP, and Kerberos V5).
12989
Autoconf continued to improve rapidly, as many people using the
12990
@command{configure} scripts reported problems they encountered.
12991
12992
Autoconf turned out to be a good torture test for M4 implementations.
12993
@sc{unix} @code{m4} started to dump core because of the length of the
12994
macros that Autoconf defined, and several bugs showed up in @sc{gnu}
12995
@code{m4} as well. Eventually, we realized that we needed to use some
12996
features that only @sc{gnu} M4 has. 4.3@sc{bsd} @code{m4}, in
12997
particular, has an impoverished set of builtin macros; the System V
12998
version is better, but still doesn't provide everything we need.
12999
13000
More development occurred as people put Autoconf under more stresses
13001
(and to uses I hadn't anticipated). Karl Berry added checks for X11.
13002
david zuhn contributed C++ support. Fran@,cois Pinard made it diagnose
13003
invalid arguments. Jim Blandy bravely coerced it into configuring
13004
@sc{gnu} Emacs, laying the groundwork for several later improvements.
13005
Roland McGrath got it to configure the @sc{gnu} C Library, wrote the
13006
@command{autoheader} script to automate the creation of C header file
13007
templates, and added a @option{--verbose} option to @command{configure}.
13008
Noah Friedman added the @option{--autoconf-dir} option and
13009
@code{AC_MACRODIR} environment variable. (He also coined the term
13010
@dfn{autoconfiscate} to mean ``adapt a software package to use
13011
Autoconf''.) Roland and Noah improved the quoting protection in
13012
@code{AC_DEFINE} and fixed many bugs, especially when I got sick of
13013
dealing with portability problems from February through June, 1993.
13014
13015
@node Deuteronomy
13016
@section Deuteronomy
13017
13018
A long wish list for major features had accumulated, and the effect of
13019
several years of patching by various people had left some residual
13020
cruft. In April 1994, while working for Cygnus Support, I began a major
13021
revision of Autoconf. I added most of the features of the Cygnus
13022
@command{configure} that Autoconf had lacked, largely by adapting the
13023
relevant parts of Cygnus @command{configure} with the help of david zuhn
13024
and Ken Raeburn. These features include support for using
13025
@file{config.sub}, @file{config.guess}, @option{--host}, and
13026
@option{--target}; making links to files; and running @command{configure}
13027
scripts in subdirectories. Adding these features enabled Ken to convert
13028
@sc{gnu} @code{as}, and Rob Savoye to convert DejaGNU, to using
13029
Autoconf.
13030
13031
I added more features in response to other peoples' requests. Many
13032
people had asked for @command{configure} scripts to share the results of
13033
the checks between runs, because (particularly when configuring a large
13034
source tree, like Cygnus does) they were frustratingly slow. Mike
13035
Haertel suggested adding site-specific initialization scripts. People
13036
distributing software that had to unpack on MS-DOS asked for a way to
13037
override the @file{.in} extension on the file names, which produced file
13038
names like @file{config.h.in} containing two dots. Jim Avera did an
13039
extensive examination of the problems with quoting in @code{AC_DEFINE}
13040
and @code{AC_SUBST}; his insights led to significant improvements.
13041
Richard Stallman asked that compiler output be sent to @file{config.log}
13042
instead of @file{/dev/null}, to help people debug the Emacs
13043
@command{configure} script.
13044
13045
I made some other changes because of my dissatisfaction with the quality
13046
of the program. I made the messages showing results of the checks less
13047
ambiguous, always printing a result. I regularized the names of the
13048
macros and cleaned up coding style inconsistencies. I added some
13049
auxiliary utilities that I had developed to help convert source code
13050
packages to use Autoconf. With the help of Fran@,cois Pinard, I made
13051
the macros not interrupt each others' messages. (That feature revealed
13052
some performance bottlenecks in @sc{gnu} @code{m4}, which he hastily
13053
corrected!) I reorganized the documentation around problems people want
13054
to solve. And I began a test suite, because experience had shown that
13055
Autoconf has a pronounced tendency to regress when we change it.
13056
13057
Again, several alpha testers gave invaluable feedback, especially
13058
Fran@,cois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn,
13059
and Mark Eichin.
13060
13061
Finally, version 2.0 was ready. And there was much rejoicing. (And I
13062
have free time again. I think. Yeah, right.)
13063
13064
13065
@c ========================================================== Appendices
13066
13067
@node Copying This Manual
13068
@appendix Copying This Manual
13069
13070
@menu
13071
* GNU Free Documentation License:: License for copying this manual
13072
@end menu
13073
13074
@include fdl.texi
13075
13076
@node Indices
13077
@appendix Indices
13078
13079
@menu
13080
* Environment Variable Index:: Index of environment variables used
13081
* Output Variable Index:: Index of variables set in output files
13082
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
13083
* Autoconf Macro Index:: Index of Autoconf macros
13084
* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
13085
* Autotest Macro Index:: Index of Autotest macros
13086
* Program & Function Index:: Index of those with portability problems
13087
* Concept Index:: General index
13088
@end menu
13089
13090
@node Environment Variable Index
13091
@appendixsec Environment Variable Index
13092
13093
This is an alphabetical list of the environment variables that Autoconf
13094
checks.
13095
13096
@printindex ev
13097
13098
@node Output Variable Index
13099
@appendixsec Output Variable Index
13100
13101
This is an alphabetical list of the variables that Autoconf can
13102
substitute into files that it creates, typically one or more
13103
@file{Makefile}s. @xref{Setting Output Variables}, for more information
13104
on how this is done.
13105
13106
@printindex ov
13107
13108
@node Preprocessor Symbol Index
13109
@appendixsec Preprocessor Symbol Index
13110
13111
This is an alphabetical list of the C preprocessor symbols that the
13112
Autoconf macros define. To work with Autoconf, C source code needs to
13113
use these names in @code{#if} directives.
13114
13115
@printindex cv
13116
13117
@node Autoconf Macro Index
13118
@appendixsec Autoconf Macro Index
13119
13120
This is an alphabetical list of the Autoconf macros. To make the list
13121
easier to use, the macros are listed without their preceding @samp{AC_}.
13122
13123
@printindex ac
13124
13125
@node M4 Macro Index
13126
@appendixsec M4 Macro Index
13127
13128
This is an alphabetical list of the M4, M4sugar, and M4sh macros. To
13129
make the list easier to use, the macros are listed without their
13130
preceding @samp{m4_} or @samp{AS_}.
13131
13132
@printindex ms
13133
13134
@node Autotest Macro Index
13135
@appendixsec Autotest Macro Index
13136
13137
This is an alphabetical list of the Autotest macros. To make the list
13138
easier to use, the macros are listed without their preceding @samp{AT_}.
13139
13140
@printindex at
13141
13142
@node Program & Function Index
13143
@appendixsec Program and Function Index
13144
13145
This is an alphabetical list of the programs and functions which
13146
portability is discussed in this document.
13147
13148
@printindex pr
13149
13150
@node Concept Index
13151
@appendixsec Concept Index
13152
13153
This is an alphabetical list of the files, tools, and concepts
13154
introduced in this document.
13155
13156
@printindex cp
13157
13158
@contents
13159
@bye
13160
13161
@c Local Variables:
13162
@c ispell-local-dictionary: "american"
13163
@c End:
Loggerhead is a web-based interface for Breezy
Version: 2.0.1