« back to all changes in this revision
Viewing changes to doc/automake.texi
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Eric Dorland
- Date: 2008-02-09 21:43:37 UTC
- mfrom: (2.1.1 hardy)
- Revision ID: james.westby@ubuntu.com-20080209214337-rkh2xt99uul53joq
Tags: 1:1.10.1-3
debian/automake.postinst: Bump up the priority to 28 so that it wins
the priority war. This should have happened after etch was
released. (Closes: #464883)
the priority war. This should have happened after etch was
released. (Closes: #464883)
- files added:
- debian/automake.doc-base
- doc
- doc/amhello
- doc/amhello/src
- files modified:
- COPYING
added
removed
doc/automake.texi
1
\input texinfo @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename automake-1.10.info
4
@settitle automake-1.10
5
@setchapternewpage off
6
@c %**end of header
7
8
@include version.texi
9
10
@copying
11
12
This manual is for @acronym{GNU} Automake (version @value{VERSION},
13
@value{UPDATED}), a program that creates GNU standards-compliant
14
Makefiles from template files.
15
16
Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
17
2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
18
19
@quotation
20
Permission is granted to copy, distribute and/or modify this document
21
under the terms of the @acronym{GNU} Free Documentation License,
22
Version 1.2 or any later version published by the Free Software
23
Foundation; with no Invariant Sections, with no Front-Cover texts,
24
and with no Back-Cover Texts. A copy of the license is included in the
25
section entitled ``@acronym{GNU} Free Documentation License.''
26
27
@end quotation
28
@end copying
29
30
@c info Automake points to the Automake package's documentation
31
@c info automake points to the automake script's documentation
32
@c (Autoconf has a similar setup.)
33
@dircategory Software development
34
@direntry
35
* Automake: (automake-1.10). Making GNU standards-compliant Makefiles.
36
@end direntry
37
38
@dircategory Individual utilities
39
@direntry
40
* aclocal: (automake-1.10)Invoking aclocal. Generating aclocal.m4.
41
* automake: (automake-1.10)Invoking Automake. Generating Makefile.in.
42
@end direntry
43
44
@titlepage
45
@title GNU Automake
46
@subtitle For version @value{VERSION}, @value{UPDATED}
47
@author David MacKenzie
48
@author Tom Tromey
49
@author Alexandre Duret-Lutz
50
@page
51
@vskip 0pt plus 1filll
52
@insertcopying
53
@end titlepage
54
55
56
@c We use the following macros to define indices:
57
@c @cindex concepts, and anything that does not fit elsewhere
58
@c @vindex Makefile variables
59
@c @trindex targets
60
@c @acindex Autoconf/Automake/Libtool/M4/... macros
61
@c @opindex tool options
62
63
@c Define an index of configure macros.
64
@defcodeindex ac
65
@c Define an index of options.
66
@defcodeindex op
67
@c Define an index of targets.
68
@defcodeindex tr
69
@c Define an index of commands.
70
@defcodeindex cm
71
72
@c Put the macros in the function index.
73
@syncodeindex ac fn
74
75
@c Put everything else into one index (arbitrarily chosen to be the concept index).
76
@syncodeindex op cp
77
@syncodeindex tr cp
78
@syncodeindex cm cp
79
80
@ifnottex
81
@node Top
82
@comment node-name, next, previous, up
83
@top GNU Automake
84
85
@insertcopying
86
87
@menu
88
* Introduction:: Automake's purpose
89
* Autotools Introduction:: An Introduction to the Autotools
90
* Generalities:: General ideas
91
* Examples:: Some example packages
92
* Invoking Automake:: Creating a Makefile.in
93
* configure:: Scanning configure.ac or configure.in
94
* Directories:: Declaring subdirectories
95
* Programs:: Building programs and libraries
96
* Other objects:: Other derived objects
97
* Other GNU Tools:: Other GNU Tools
98
* Documentation:: Building documentation
99
* Install:: What gets installed
100
* Clean:: What gets cleaned
101
* Dist:: What goes in a distribution
102
* Tests:: Support for test suites
103
* Rebuilding:: Automatic rebuilding of Makefile
104
* Options:: Changing Automake's behavior
105
* Miscellaneous:: Miscellaneous rules
106
* Include:: Including extra files in an Automake template.
107
* Conditionals:: Conditionals
108
* Gnits:: The effect of @option{--gnu} and @option{--gnits}
109
* Cygnus:: The effect of @option{--cygnus}
110
* Not Enough:: When Automake is not Enough
111
* Distributing:: Distributing the Makefile.in
112
* API versioning:: About compatibility between Automake versions
113
* Upgrading:: Upgrading to a Newer Automake Version
114
* FAQ:: Frequently Asked Questions
115
* History:: Notes about the history of Automake
116
* Copying This Manual:: How to make copies of this manual
117
* Indices:: Indices of variables, macros, and concepts
118
119
@detailmenu
120
--- The Detailed Node Listing ---
121
122
An Introduction to the Autotools
123
124
* GNU Build System:: Introducing the GNU Build System
125
* Use Cases:: Use Cases for the GNU Build System
126
* Why Autotools:: How Autotools Help
127
* Hello World:: A Small Hello World Package
128
129
Use Cases for the GNU Build System
130
131
* Basic Installation:: Common installation procedure
132
* Standard Targets:: A list of standard Makefile targets
133
* Standard Directory Variables:: A list of standard directory variables
134
* Standard Configuration Variables:: Using configuration variables
135
* config.site:: Using a config.site file
136
* VPATH Builds:: Parallel build trees
137
* Two-Part Install:: Installing data and programs separately
138
* Cross-Compilation:: Building for other architectures
139
* Renaming:: Renaming programs at install time
140
* DESTDIR:: Building binary packages with DESTDIR
141
* Preparing Distributions:: Rolling out tarballs
142
* Dependency Tracking:: Automatic dependency tracking
143
* Nested Packages:: The GNU Build Systems can be nested
144
145
A Small Hello World
146
147
* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
148
* amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
149
150
General ideas
151
152
* General Operation:: General operation of Automake
153
* Strictness:: Standards conformance checking
154
* Uniform:: The Uniform Naming Scheme
155
* Canonicalization:: How derived variables are named
156
* User Variables:: Variables reserved for the user
157
* Auxiliary Programs:: Programs automake might require
158
159
Some example packages
160
161
* Complete:: A simple example, start to finish
162
* true:: Building true and false
163
164
Scanning @file{configure.ac}
165
166
* Requirements:: Configuration requirements
167
* Optional:: Other things Automake recognizes
168
* Invoking aclocal:: Auto-generating aclocal.m4
169
* Macros:: Autoconf macros supplied with Automake
170
171
Auto-generating aclocal.m4
172
173
* aclocal options:: Options supported by aclocal
174
* Macro search path:: How aclocal finds .m4 files
175
* Extending aclocal:: Writing your own aclocal macros
176
* Local Macros:: Organizing local macros
177
* Serials:: Serial lines in Autoconf macros
178
* Future of aclocal:: aclocal's scheduled death
179
180
Autoconf macros supplied with Automake
181
182
* Public macros:: Macros that you can use.
183
* Obsolete macros:: Macros that you should stop using.
184
* Private macros:: Macros that you should not use.
185
186
Directories
187
188
* Subdirectories:: Building subdirectories recursively
189
* Conditional Subdirectories:: Conditionally not building directories
190
* Alternative:: Subdirectories without recursion
191
* Subpackages:: Nesting packages
192
193
Building Programs and Libraries
194
195
* A Program:: Building a program
196
* A Library:: Building a library
197
* A Shared Library:: Building a Libtool library
198
* Program and Library Variables:: Variables controlling program and
199
library builds
200
* Default _SOURCES:: Default source files
201
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
202
* Program variables:: Variables used when building a program
203
* Yacc and Lex:: Yacc and Lex support
204
* C++ Support:: Compiling C++ sources
205
* Objective C Support:: Compiling Objective C sources
206
* Unified Parallel C Support:: Compiling Unified Parallel C sources
207
* Assembly Support:: Compiling assembly sources
208
* Fortran 77 Support:: Compiling Fortran 77 sources
209
* Fortran 9x Support:: Compiling Fortran 9x sources
210
* Java Support:: Compiling Java sources
211
* Support for Other Languages:: Compiling other languages
212
* ANSI:: Automatic de-ANSI-fication (obsolete)
213
* Dependencies:: Automatic dependency tracking
214
* EXEEXT:: Support for executable extensions
215
216
Building a program
217
218
* Program Sources:: Defining program sources
219
* Linking:: Linking with libraries or extra objects
220
* Conditional Sources:: Handling conditional sources
221
* Conditional Programs:: Building program conditionally
222
223
Building a Shared Library
224
225
* Libtool Concept:: Introducing Libtool
226
* Libtool Libraries:: Declaring Libtool Libraries
227
* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
228
* Conditional Libtool Sources:: Choosing Library Sources Conditionally
229
* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
230
* Libtool Modules:: Building Libtool Modules
231
* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
232
* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
233
* Libtool Issues:: Common Issues Related to Libtool's Use
234
235
Fortran 77 Support
236
237
* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
238
* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
239
* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
240
241
Mixing Fortran 77 With C and C++
242
243
* How the Linker is Chosen:: Automatic linker selection
244
245
Fortran 9x Support
246
247
* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
248
249
Other Derived Objects
250
251
* Scripts:: Executable scripts
252
* Headers:: Header files
253
* Data:: Architecture-independent data files
254
* Sources:: Derived sources
255
256
Built sources
257
258
* Built sources example:: Several ways to handle built sources.
259
260
Other GNU Tools
261
262
* Emacs Lisp:: Emacs Lisp
263
* gettext:: Gettext
264
* Libtool:: Libtool
265
* Java:: Java
266
* Python:: Python
267
268
Building documentation
269
270
* Texinfo:: Texinfo
271
* Man pages:: Man pages
272
273
Miscellaneous Rules
274
275
* Tags:: Interfacing to etags and mkid
276
* Suffixes:: Handling new file extensions
277
* Multilibs:: Support for multilibs.
278
279
When Automake Isn't Enough
280
281
* Extending:: Adding new rules or overriding existing ones.
282
* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
283
284
Frequently Asked Questions about Automake
285
286
* CVS:: CVS and generated files
287
* maintainer-mode:: missing and AM_MAINTAINER_MODE
288
* wildcards:: Why doesn't Automake support wildcards?
289
* limitations on file names:: Limitations on source and installed file names
290
* distcleancheck:: Files left in build directory after distclean
291
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
292
* renamed objects:: Why are object files sometimes renamed?
293
* Per-Object Flags:: How to simulate per-object flags?
294
* Multiple Outputs:: Writing rules for tools with many output files
295
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
296
297
History of Automake
298
299
* Timeline:: The Automake story.
300
* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
301
* Releases:: Statistics about Automake Releases
302
303
Copying This Manual
304
305
* GNU Free Documentation License:: License for copying this manual
306
307
Indices
308
309
* Macro Index:: Index of Autoconf macros
310
* Variable Index:: Index of Makefile variables
311
* General Index:: General index
312
313
@end detailmenu
314
@end menu
315
316
@end ifnottex
317
318
319
@node Introduction
320
@chapter Introduction
321
322
Automake is a tool for automatically generating @file{Makefile.in}s
323
from files called @file{Makefile.am}. Each @file{Makefile.am} is
324
basically a series of @command{make} variable
325
definitions@footnote{These variables are also called @dfn{make macros}
326
in Make terminology, however in this manual we reserve the term
327
@dfn{macro} for Autoconf's macros.}, with rules being thrown in
328
occasionally. The generated @file{Makefile.in}s are compliant with
329
the GNU Makefile standards.
330
331
@cindex GNU Makefile standards
332
333
The GNU Makefile Standards Document
334
(@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
335
is long, complicated, and subject to change. The goal of Automake is to
336
remove the burden of Makefile maintenance from the back of the
337
individual GNU maintainer (and put it on the back of the Automake
338
maintainers).
339
340
The typical Automake input file is simply a series of variable definitions.
341
Each such file is processed to create a @file{Makefile.in}. There
342
should generally be one @file{Makefile.am} per directory of a project.
343
344
@cindex Constraints of Automake
345
@cindex Automake constraints
346
347
Automake does constrain a project in certain ways; for instance, it
348
assumes that the project uses Autoconf (@pxref{Top, , Introduction,
349
autoconf, The Autoconf Manual}), and enforces certain restrictions on
350
the @file{configure.ac} contents@footnote{Older Autoconf versions used
351
@file{configure.in}. Autoconf 2.50 and greater promotes
352
@file{configure.ac} over @file{configure.in}. The rest of this
353
documentation will refer to @file{configure.ac}, but Automake also
354
supports @file{configure.in} for backward compatibility.}.
355
356
@cindex Automake requirements
357
@cindex Requirements, Automake
358
359
Automake requires @command{perl} in order to generate the
360
@file{Makefile.in}s. However, the distributions created by Automake are
361
fully GNU standards-compliant, and do not require @command{perl} in order
362
to be built.
363
364
@cindex Bugs, reporting
365
@cindex Reporting bugs
366
@cindex E-mail, bug reports
367
368
Mail suggestions and bug reports for Automake to
369
@email{bug-automake@@gnu.org}.
370
371
@node Autotools Introduction
372
@chapter An Introduction to the Autotools
373
374
If you are new to Automake, maybe you know that it is part of a set of
375
tools called @emph{The Autotools}. Maybe you've already delved into a
376
package full of files named @file{configure}, @file{configure.ac},
377
@file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
378
some of them claiming to be @emph{generated by} Autoconf or Automake.
379
But the exact purpose of these files and their relations is probably
380
fuzzy. The goal of this chapter is to introduce you to this machinery,
381
to show you how it works and how powerful it is. If you've never
382
installed or seen such a package, do not worry: this chapter will walk
383
you through it.
384
385
If you need some teaching material, more illustrations, or a less
386
@command{automake}-centered continuation, some slides for this
387
introduction are available in Alexandre Duret-Lutz's
388
@uref{http://www-src.lip6.fr/@/~Alexandre.Duret-Lutz/@/autotools.html,
389
Autotools Tutorial}.
390
This chapter is the written version of the first part of his tutorial.
391
392
@menu
393
* GNU Build System:: Introducing the GNU Build System
394
* Use Cases:: Use Cases for the GNU Build System
395
* Why Autotools:: How Autotools Help
396
* Hello World:: A Small Hello World Package
397
@end menu
398
399
@node GNU Build System
400
@section Introducing the GNU Build System
401
@cindex GNU Build System, introduction
402
403
It is a truth universally acknowledged, that a developer in
404
possession of a new package, must be in want of a build system.
405
406
In the Unix world, such a build system is traditionally achieved using
407
the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
408
Manual}). The developer expresses the recipe to build his package in
409
a @file{Makefile}. This file is a set of rules to build the files in
410
the package. For instance the program @file{prog} may be built by
411
running the linker on the files @file{main.o}, @file{foo.o}, and
412
@file{bar.o}; the file @file{main.o} may be built by running the
413
compiler on @file{main.c}; etc. Each time @command{make} is run, it
414
reads @file{Makefile}, checks the existence and modification time of
415
the files mentioned, decides what files need to be built (or rebuilt),
416
and runs the associated commands.
417
418
When a package needs to be built on a different platform than the one
419
it was developed on, its @file{Makefile} usually needs to be adjusted.
420
For instance the compiler may have another name or require more
421
options. In 1991, David J. MacKenzie got tired of customizing
422
@file{Makefile} for the 20 platforms he had to deal with. Instead, he
423
handcrafted a little shell script called @file{configure} to
424
automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
425
autoconf, The Autoconf Manual}). Compiling his package was now
426
as simple as running @code{./configure && make}.
427
428
@cindex GNU Coding Standards
429
430
Today this process has been standardized in the GNU project. The GNU
431
Coding Standards (@pxref{Managing Releases, The Release Process, ,
432
standards, The GNU Coding Standards}) explains how each package of the
433
GNU project should have a @file{configure} script, and the minimal
434
interface it should have. The @file{Makefile} too should follow some
435
established conventions. The result? A unified build system that
436
makes all packages almost indistinguishable by the installer. In its
437
simplest scenario, all the installer has to do is to unpack the
438
package, run @code{./configure && make && make install}, and repeat
439
with the next package to install.
440
441
We call this build system the @dfn{GNU Build System}, since it was
442
grown out of the GNU project. However it is used by a vast number of
443
other packages: following any existing convention has its advantages.
444
445
@cindex Autotools, introduction
446
447
The Autotools are tools that will create a GNU Build System for your
448
package. Autoconf mostly focuses on @file{configure} and Automake on
449
@file{Makefile}s. It is entirely possible to create a GNU Build
450
System without the help of these tools. However it is rather
451
burdensome and error-prone. We will discuss this again after some
452
illustration of the GNU Build System in action.
453
454
@node Use Cases
455
@section Use Cases for the GNU Build System
456
@cindex GNU Build System, use cases
457
@cindex GNU Build System, features
458
@cindex Features of the GNU Build System
459
@cindex Use Cases for the GNU Build System
460
@cindex @file{amhello-1.0.tar.gz}, location
461
@cindex @file{amhello-1.0.tar.gz}, use cases
462
463
In this section we explore several use cases for the GNU Build System.
464
You can replay all these examples on the @file{amhello-1.0.tar.gz}
465
package distributed with Automake. If Automake is installed on your
466
system, you should find a copy of this file in
467
@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
468
@var{prefix} is the installation prefix specified during configuration
469
(@var{prefix} defaults to @file{/usr/local}, however if Automake was
470
installed by some GNU/Linux distribution it most likely has been set
471
to @file{/usr}). If you do not have a copy of Automake installed,
472
you can find a copy of this file inside the @file{doc/} directory of
473
the Automake package.
474
475
Some of the following use cases present features that are in fact
476
extensions to the GNU Build System. Read: they are not specified by
477
the GNU Coding Standards, but they are nonetheless part of the build
478
system created by the Autotools. To keep things simple, we do not
479
point out the difference. Our objective is to show you many of the
480
features that the build system created by the Autotools will offer to
481
you.
482
483
@menu
484
* Basic Installation:: Common installation procedure
485
* Standard Targets:: A list of standard Makefile targets
486
* Standard Directory Variables:: A list of standard directory variables
487
* Standard Configuration Variables:: Using configuration variables
488
* config.site:: Using a config.site file
489
* VPATH Builds:: Parallel build trees
490
* Two-Part Install:: Installing data and programs separately
491
* Cross-Compilation:: Building for other architectures
492
* Renaming:: Renaming programs at install time
493
* DESTDIR:: Building binary packages with DESTDIR
494
* Preparing Distributions:: Rolling out tarballs
495
* Dependency Tracking:: Automatic dependency tracking
496
* Nested Packages:: The GNU Build Systems can be nested
497
@end menu
498
499
@node Basic Installation
500
@subsection Basic Installation
501
@cindex Configuration, basics
502
@cindex Installation, basics
503
@cindex GNU Build System, basics
504
505
The most common installation procedure looks as follows.
506
507
@example
508
~ % @kbd{tar zxf amhello-1.0.tar.gz}
509
~ % @kbd{cd amhello-1.0}
510
~/amhello-1.0 % @kbd{./configure}
511
@dots{}
512
config.status: creating Makefile
513
config.status: creating src/Makefile
514
@dots{}
515
~/amhello-1.0 % @kbd{make}
516
@dots{}
517
~/amhello-1.0 % @kbd{make check}
518
@dots{}
519
~/amhello-1.0 % @kbd{su}
520
Password:
521
/home/adl/amhello-1.0 # @kbd{make install}
522
@dots{}
523
/home/adl/amhello-1.0 # @kbd{exit}
524
~/amhello-1.0 % @kbd{make installcheck}
525
@dots{}
526
@end example
527
528
@cindex Unpacking
529
530
The user first unpacks the package. Here, and in the following
531
examples, we will use the non-portable @code{tar zxf} command for
532
simplicity. On a system without GNU @command{tar} installed, this
533
command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
534
535
The user then enters the newly created directory to run the
536
@file{configure} script. This script probes the system for various
537
features, and finally creates the @file{Makefile}s. In this toy
538
example there are only two @file{Makefile}s, but in real-world projects,
539
there may be many more, usually one @file{Makefile} per directory.
540
541
It is now possible to run @code{make}. This will construct all the
542
programs, libraries, and scripts that need to be constructed for the
543
package. In our example, this compiles the @file{hello} program.
544
All files are constructed in place, in the source tree; we will see
545
later how this can be changed.
546
547
@code{make check} causes the package's tests to be run. This step is
548
not mandatory, but it is often good to make sure the programs that
549
have been built behave as they should, before you decide to install
550
them. Our example does not contain any tests, so running @code{make
551
check} is a no-op.
552
553
@cindex su, before @code{make install}
554
After everything has been built, and maybe tested, it is time to
555
install it on the system. That means copying the programs,
556
libraries, header files, scripts, and other data files from the
557
source directory to their final destination on the system. The
558
command @code{make install} will do that. However, by default
559
everything will be installed in subdirectories of @file{/usr/local}:
560
binaries will go into @file{/usr/local/bin}, libraries will end up in
561
@file{/usr/local/lib}, etc. This destination is usually not writable
562
by any user, so we assume that we have to become root before we can
563
run @code{make install}. In our example, running @code{make install}
564
will copy the program @file{hello} into @file{/usr/local/bin}
565
and @file{README} into @file{/usr/local/share/doc/amhello}.
566
567
A last and optional step is to run @code{make installcheck}. This
568
command may run tests on the installed files. @code{make check} tests
569
the files in the source tree, while @code{make installcheck} tests
570
their installed copies. The tests run by the latter can be different
571
from those run by the former. For instance, there are tests that
572
cannot be run in the source tree. Conversely, some packages are set
573
up so that @code{make installcheck} will run the very same tests as
574
@code{make check}, only on different files (non-installed
575
vs.@: installed). It can make a difference, for instance when the
576
source tree's layout is different from that of the installation.
577
Furthermore it may help to diagnose an incomplete installation.
578
579
Presently most packages do not have any @code{installcheck} tests
580
because the existence of @code{installcheck} is little known, and its
581
usefulness is neglected. Our little toy package is no better: @code{make
582
installcheck} does nothing.
583
584
@node Standard Targets
585
@subsection Standard @file{Makefile} Targets
586
587
So far we have come across four ways to run @command{make} in the GNU
588
Build System: @code{make}, @code{make check}, @code{make install}, and
589
@code{make installcheck}. The words @code{check}, @code{install}, and
590
@code{installcheck}, passed as arguments to @command{make}, are called
591
@dfn{targets}. @code{make} is a shorthand for @code{make all},
592
@code{all} being the default target in the GNU Build System.
593
594
Here is a list of the most useful targets that the GNU Coding Standards
595
specify.
596
597
@table @code
598
@item make all
599
@trindex all
600
Build programs, libraries, documentation, etc.@: (same as @code{make}).
601
@item make install
602
@trindex install
603
Install what needs to be installed, copying the files from the
604
package's tree to system-wide directories.
605
@item make install-strip
606
@trindex install-strip
607
Same as @code{make install}, then strip debugging symbols. Some
608
users like to trade space for useful bug reports@enddots{}
609
@item make uninstall
610
@trindex uninstall
611
The opposite of @code{make install}: erase the installed files.
612
(This needs to be run from the same build tree that was installed.)
613
@item make clean
614
@trindex clean
615
Erase from the build tree the files built by @code{make all}.
616
@item make distclean
617
@trindex distclean
618
Additionally erase anything @code{./configure} created.
619
@item make check
620
@trindex check
621
Run the test suite, if any.
622
@item make installcheck
623
@trindex installcheck
624
Check the installed programs or libraries, if supported.
625
@item make dist
626
@trindex dist
627
Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
628
files.
629
@end table
630
631
@node Standard Directory Variables
632
@subsection Standard Directory Variables
633
@cindex directory variables
634
635
The GNU Coding Standards also specify a hierarchy of variables to
636
denote installation directories. Some of these are:
637
638
@multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
639
@headitem Directory variable @tab Default value
640
@item @code{prefix} @tab @code{/usr/local}
641
@item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
642
@item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
643
@item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
644
@item @w{@ @ @ @ @dots{}}
645
@item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
646
@item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
647
@item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
648
@item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
649
@item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
650
@item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
651
@item @w{@ @ @dots{}}
652
@end multitable
653
654
@c We should provide a complete table somewhere, but not here. The
655
@c complete list of directory variables it too confusing as-is. It
656
@c requires some explanations that are too complicated for this
657
@c introduction. Besides listing directories like localstatedir
658
@c would make the explanations in ``Two-Part Install'' harder.
659
660
Each of these directories has a role which is often obvious from its
661
name. In a package, any installable file will be installed in one of
662
these directories. For instance in @code{amhello-1.0}, the program
663
@file{hello} is to be installed in @var{bindir}, the directory for
664
binaries. The default value for this directory is
665
@file{/usr/local/bin}, but the user can supply a different value when
666
calling @command{configure}. Also the file @file{README} will be
667
installed into @var{docdir}, which defaults to
668
@file{/usr/local/share/doc/amhello}.
669
670
@opindex --prefix
671
672
A user who wishes to install a package on his own account could proceed
673
as follows:
674
675
@example
676
~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
677
@dots{}
678
~/amhello-1.0 % @kbd{make}
679
@dots{}
680
~/amhello-1.0 % @kbd{make install}
681
@dots{}
682
@end example
683
684
This would install @file{~/usr/bin/hello} and
685
@file{~/usr/share/doc/amhello/README}.
686
687
The list of all such directory options is shown by
688
@code{./configure --help}.
689
690
@node Standard Configuration Variables
691
@subsection Standard Configuration Variables
692
@cindex configuration variables, overriding
693
694
The GNU Coding Standards also define a set of standard configuration
695
variables used during the build. Here are some:
696
697
@table @asis
698
@item @code{CC}
699
C compiler command
700
@item @code{CFLAGS}
701
C compiler flags
702
@item @code{CXX}
703
C++ compiler command
704
@item @code{CXXFLAGS}
705
C++ compiler flags
706
@item @code{LDFLAGS}
707
linker flags
708
@item @code{CPPFLAGS}
709
C/C++ preprocessor flags
710
@item @dots{}
711
@end table
712
713
@command{configure} usually does a good job at setting appropriate
714
values for these variables, but there are cases where you may want to
715
override them. For instance you may have several versions of a
716
compiler installed and would like to use another one, you may have
717
header files installed outside the default search path of the
718
compiler, or even libraries out of the way of the linker.
719
720
Here is how one would call @command{configure} to force it to use
721
@command{gcc-3} as C compiler, use header files from
722
@file{~/usr/include} when compiling, and libraries from
723
@file{~/usr/lib} when linking.
724
725
@example
726
~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
727
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
728
@end example
729
730
Again, a full list of these variables appears in the output of
731
@code{./configure --help}.
732
733
@node config.site
734
@subsection Overriding Default Configuration Setting with @file{config.site}
735
@cindex @file{config.site} example
736
737
When installing several packages using the same setup, it can be
738
convenient to create a file to capture common settings.
739
If a file named @file{@var{prefix}/share/config.site} exists,
740
@command{configure} will source it at the beginning of its execution.
741
742
Recall the command from the previous section:
743
744
@example
745
~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
746
CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
747
@end example
748
749
Assuming we are installing many package in @file{~/usr}, and will
750
always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
751
@code{LDFLAGS}, we can automate this by creating the following
752
@file{~/usr/share/config.site} file:
753
754
@example
755
test -z "$CC" && CC=gcc-3
756
test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
757
test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
758
@end example
759
760
Now, any time a @file{configure} script is using the @file{~/usr}
761
prefix, it will execute the above @file{config.site} and define
762
these three variables.
763
764
@example
765
~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
766
configure: loading site script /home/adl/usr/share/config.site
767
@dots{}
768
@end example
769
770
@xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
771
Manual}, for more information about this feature.
772
773
774
@node VPATH Builds
775
@subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
776
@cindex Parallel build trees
777
@cindex VPATH builds
778
@cindex source tree and build tree
779
@cindex build tree and source tree
780
@cindex trees, source vs.@: build
781
782
The GNU Build System distinguishes two trees: the source tree, and
783
the build tree.
784
785
The source tree is rooted in the directory containing
786
@file{configure}. It contains all the sources files (those that are
787
distributed), and may be arranged using several subdirectories.
788
789
The build tree is rooted in the directory in which @file{configure}
790
was run, and is populated with all object files, programs, libraries,
791
and other derived files built from the sources (and hence not
792
distributed). The build tree usually has the same subdirectory layout
793
as the source tree; its subdirectories are created automatically by
794
the build system.
795
796
If @file{configure} is executed in its own directory, the source and
797
build trees are combined: derived files are constructed in the same
798
directories as their sources. This was the case in our first
799
installation example (@pxref{Basic Installation}).
800
801
A common request from users is that they want to confine all derived
802
files to a single directory, to keep their source directories
803
uncluttered. Here is how we could run @file{configure} to build
804
everything in a subdirectory called @file{build/}.
805
806
@example
807
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
808
~ % @kbd{cd amhello-1.0}
809
~/amhello-1.0 % @kbd{mkdir build && cd build}
810
~/amhello-1.0/build % @kbd{../configure}
811
@dots{}
812
~/amhello-1.0/build % @kbd{make}
813
@dots{}
814
@end example
815
816
These setups, where source and build trees are different, are often
817
called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
818
@emph{parallel build} is misleading: the word @emph{parallel} is a
819
reference to the way the build tree shadows the source tree, it is not
820
about some concurrency in the way build commands are run. For this
821
reason we refer to such setups using the name @emph{VPATH builds} in
822
the following. @emph{VPATH} is the name of the @command{make} feature
823
used by the @file{Makefile}s to allow these builds (@pxref{General
824
Search, , @code{VPATH}: Search Path for All Prerequisites, make, The
825
GNU Make Manual}).
826
827
@cindex multiple configurations, example
828
@cindex debug build, example
829
@cindex optimized build, example
830
831
VPATH builds have other interesting uses. One is to build the same
832
sources with multiple configurations. For instance:
833
834
@example
835
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
836
~ % @kbd{cd amhello-1.0}
837
~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
838
~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
839
@dots{}
840
~/amhello-1.0/debug % @kbd{make}
841
@dots{}
842
~/amhello-1.0/debug % cd ../optim
843
~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
844
@dots{}
845
~/amhello-1.0/optim % @kbd{make}
846
@dots{}
847
@end example
848
849
With network file systems, a similar approach can be used to build the
850
same sources on different machines. For instance, suppose that the
851
sources are installed on a directory shared by two hosts: @code{HOST1}
852
and @code{HOST2}, which may be different platforms.
853
854
@example
855
~ % @kbd{cd /nfs/src}
856
/nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
857
@end example
858
859
On the first host, you could create a local build directory:
860
@example
861
[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
862
[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
863
...
864
[HOST1] /tmp/amh % @kbd{make && sudo make install}
865
...
866
@end example
867
868
@noindent
869
(Here we assume the that installer has configured @command{sudo} so it
870
can execute @code{make install} with root privileges; it is more convenient
871
than using @command{su} like in @ref{Basic Installation}).
872
873
On the second host, you would do exactly the same, possibly at
874
the same time:
875
@example
876
[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
877
[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
878
...
879
[HOST2] /tmp/amh % @kbd{make && sudo make install}
880
...
881
@end example
882
883
@cindex read-only source tree
884
@cindex source tree, read-only
885
886
In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
887
directory from being read-only. In fact VPATH builds are also a means
888
of building packages from a read-only medium such as a CD-ROM. (The
889
FSF used to sell CD-ROM with unpacked source code, before the GNU
890
project grew so big.)
891
892
@node Two-Part Install
893
@subsection Two-Part Installation
894
895
In our last example (@pxref{VPATH Builds}), a source tree was shared
896
by two hosts, but compilation and installation were done separately on
897
each host.
898
899
The GNU Build System also supports networked setups where part of the
900
installed files should be shared amongst multiple hosts. It does so
901
by distinguishing architecture-dependent files from
902
architecture-independent files, and providing two @file{Makefile}
903
targets to install each of these classes of files.
904
905
@trindex install-exec
906
@trindex install-data
907
908
These targets are @code{install-exec} for architecture-dependent files
909
and @code{install-data} for architecture-independent files.
910
The command we used up to now, @code{make install}, can be thought of
911
as a shorthand for @code{make install-exec install-data}.
912
913
From the GNU Build System point of view, the distinction between
914
architecture-dependent files and architecture-independent files is
915
based exclusively on the directory variable used to specify their
916
installation destination. In the list of directory variables we
917
provided earlier (@pxref{Standard Directory Variables}), all the
918
variables based on @var{exec-prefix} designate architecture-dependent
919
directories whose files will be installed by @code{make install-exec}.
920
The others designate architecture-independent directories and will
921
serve files installed by @code{make install-data}. @xref{Install},
922
for more details.
923
924
Here is how we could revisit our two-host installation example,
925
assuming that (1) we want to install the package directly in
926
@file{/usr}, and (2) the directory @file{/usr/share} is shared by the
927
two hosts.
928
929
On the first host we would run
930
@example
931
[HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
932
[HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
933
...
934
[HOST1] /tmp/amh % @kbd{make && sudo make install}
935
...
936
@end example
937
938
On the second host, however, we need only install the
939
architecture-specific files.
940
@example
941
[HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
942
[HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
943
...
944
[HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
945
...
946
@end example
947
948
In packages that have installation checks, it would make sense to run
949
@code{make installcheck} (@pxref{Basic Installation}) to verify that
950
the package works correctly despite the apparent partial installation.
951
952
@node Cross-Compilation
953
@subsection Cross-Compilation
954
@cindex cross-compilation
955
956
To @dfn{cross-compile} is to build on one platform a binary that will
957
run on another platform. When speaking of cross-compilation, it is
958
important to distinguish between the @dfn{build platform} on which
959
the compilation is performed, and the @dfn{host platform} on which the
960
resulting executable is expected to run. The following
961
@command{configure} options are used to specify each of them:
962
963
@table @option
964
@item --build=@var{BUILD}
965
@opindex --build=@var{BUILD}
966
The system on which the package is built.
967
@item --host=@var{HOST}
968
@opindex --host=@var{HOST}
969
The system where built programs and libraries will run.
970
@end table
971
972
When the @option{--host} is used, @command{configure} will search for
973
the cross-compiling suite for this platform. Cross-compilation tools
974
commonly have their target architecture as prefix of their name. For
975
instance my cross-compiler for MinGW32 has its binaries called
976
@code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
977
@code{i586-mingw32msvc-as}, etc.
978
979
@cindex MinGW cross-compilation example
980
@cindex cross-compilation example
981
982
Here is how we could build @code{amhello-1.0} for
983
@code{i586-mingw32msvc} on a GNU/Linux PC.
984
985
@smallexample
986
~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
987
checking for a BSD-compatible install... /usr/bin/install -c
988
checking whether build environment is sane... yes
989
checking for gawk... gawk
990
checking whether make sets $(MAKE)... yes
991
checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
992
checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
993
checking for C compiler default output file name... a.exe
994
checking whether the C compiler works... yes
995
checking whether we are cross compiling... yes
996
checking for suffix of executables... .exe
997
checking for suffix of object files... o
998
checking whether we are using the GNU C compiler... yes
999
checking whether i586-mingw32msvc-gcc accepts -g... yes
1000
checking for i586-mingw32msvc-gcc option to accept ANSI C...
1001
@dots{}
1002
~/amhello-1.0 % @kbd{make}
1003
@dots{}
1004
~/amhello-1.0 % @kbd{cd src; file hello.exe}
1005
hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1006
@end smallexample
1007
1008
The @option{--host} and @option{--build} options are usually all we
1009
need for cross-compiling. The only exception is if the package being
1010
built is itself a cross-compiler: we need a third option to specify
1011
its target architecture.
1012
1013
@table @option
1014
@item --target=@var{TARGET}
1015
@opindex --target=@var{TARGET}
1016
When building compiler tools: the system for which the tools will
1017
create output.
1018
@end table
1019
1020
For instance when installing GCC, the GNU Compiler Collection, we can
1021
use @option{--target=@var{TARGET}} to specify that we want to build
1022
GCC as a cross-compiler for @var{TARGET}. Mixing @option{--build} and
1023
@option{--target}, we can actually cross-compile a cross-compiler;
1024
such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1025
1026
@xref{Specifying Names, , Specifying the System Type, autoconf, The
1027
Autoconf Manual}, for more information about these @command{configure}
1028
options.
1029
1030
@node Renaming
1031
@subsection Renaming Programs at Install Time
1032
@cindex Renaming programs
1033
@cindex Transforming program names
1034
@cindex Programs, renaming during installation
1035
1036
The GNU Build System provides means to automatically rename
1037
executables before they are installed. This is especially convenient
1038
when installing a GNU package on a system that already has a
1039
proprietary implementation you do not want to overwrite. For instance,
1040
you may want to install GNU @command{tar} as @command{gtar} so you can
1041
distinguish it from your vendor's @command{tar}.
1042
1043
This can be done using one of these three @command{configure} options.
1044
1045
@table @option
1046
@item --program-prefix=@var{PREFIX}
1047
@opindex --program-prefix=@var{PREFIX}
1048
Prepend @var{PREFIX} to installed program names.
1049
@item --program-suffix=@var{SUFFIX}
1050
@opindex --program-suffix=@var{SUFFIX}
1051
Append @var{SUFFIX} to installed program names.
1052
@item --program-transform-name=@var{PROGRAM}
1053
@opindex --program-transform-name=@var{PROGRAM}
1054
Run @code{sed @var{PROGRAM}} on installed program names.
1055
@end table
1056
1057
The following commands would install @file{hello}
1058
as @file{/usr/local/bin/test-hello}, for instance.
1059
1060
@example
1061
~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1062
@dots{}
1063
~/amhello-1.0 % @kbd{make}
1064
@dots{}
1065
~/amhello-1.0 % @kbd{sudo make install}
1066
@dots{}
1067
@end example
1068
1069
@node DESTDIR
1070
@subsection Building Binary Packages Using DESTDIR
1071
@vindex DESTDIR
1072
1073
The GNU Build System's @code{make install} and @code{make uninstall}
1074
interface does not exactly fit the needs of a system administrator
1075
who has to deploy and upgrade packages on lots of hosts. In other
1076
words, the GNU Build System does not replace a package manager.
1077
1078
Such package managers usually need to know which files have been
1079
installed by a package, so a mere @code{make install} is
1080
inappropriate.
1081
1082
@cindex Staged installation
1083
1084
The @code{DESTDIR} variable can be used to perform a staged
1085
installation. The package should be configured as if it was going to
1086
be installed in its final location (e.g., @code{--prefix /usr}), but
1087
when running @code{make install}, the @code{DESTDIR} should be set to
1088
the absolute name of a directory into which the installation will be
1089
diverted. From this directory it is easy to review which files are
1090
being installed where, and finally copy them to their final location
1091
by some means.
1092
1093
@cindex Binary package
1094
1095
For instance here is how we could create a binary package containing a
1096
snapshot of all the files to be installed.
1097
1098
@example
1099
~/amhello-1.0 % @kbd{./configure --prefix /usr}
1100
@dots{}
1101
~/amhello-1.0 % @kbd{make}
1102
@dots{}
1103
~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1104
@dots{}
1105
~/amhello-1.0 % @kbd{cd ~/inst}
1106
~/inst % @kbd{find . -type f -print > ../files.lst}
1107
~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../file.lst`}
1108
./usr/bin/hello
1109
./usr/share/doc/amhello/README
1110
@end example
1111
1112
After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1113
uncompressed in @file{/} on many hosts. (Using @code{`cat ../file.lst`}
1114
instead of @samp{.} as argument for @command{tar} avoids entries for
1115
each subdirectory in the archive: we would not like @command{tar} to
1116
restore the modification time of @file{/}, @file{/usr/}, etc.)
1117
1118
Note that when building packages for several architectures, it might
1119
be convenient to use @code{make install-data} and @code{make
1120
install-exec} (@pxref{Two-Part Install}) to gather
1121
architecture-independent files in a single package.
1122
1123
@xref{Install}, for more information.
1124
1125
@c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1126
@c UNINSTALL counterparts.
1127
1128
@node Preparing Distributions
1129
@subsection Preparing Distributions
1130
@cindex Preparing distributions
1131
@cindex Packages, preparation
1132
@cindex Distributions, preparation
1133
1134
We have already mentioned @code{make dist}. This target collects all
1135
your source files and the necessary parts of the build system to
1136
create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1137
1138
@cindex @code{distcheck} better than @code{dist}
1139
1140
Another, more useful command is @code{make distcheck}. The
1141
@code{distcheck} target constructs
1142
@file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1143
but it additionally ensures most of the use cases presented so far
1144
work:
1145
1146
@itemize @bullet
1147
@item
1148
It attempts a full compilation of the package (@pxref{Basic
1149
Installation}), unpacking the newly constructed tarball, running
1150
@code{make}, @code{make check}, @code{make install}, as well as
1151
@code{make installcheck}, and even @code{make dist},
1152
@item
1153
it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1154
@item
1155
it makes sure @code{make clean}, @code{make distclean}, and @code{make
1156
uninstall} do not omit any file (@pxref{Standard Targets}),
1157
@item
1158
and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1159
@end itemize
1160
1161
All of these actions are performed in a temporary subdirectory, so
1162
that no root privileges are required.
1163
1164
Releasing a package that fails @code{make distcheck} means that one of
1165
the scenarios we presented will not work and some users will be
1166
disappointed. Therefore it is a good practice to release a package
1167
only after a successful @code{make distcheck}. This of course does
1168
not imply that the package will be flawless, but at least it will
1169
prevent some of the embarrassing errors you may find in packages
1170
released by people who have never heard about @code{distcheck} (like
1171
@code{DESTDIR} not working because of a typo, or a distributed file
1172
being erased by @code{make clean}, or even @code{VPATH} builds not
1173
working).
1174
1175
@xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1176
@code{make distcheck}. @xref{Dist}, for more information about
1177
@code{distcheck}.
1178
1179
@node Dependency Tracking
1180
@subsection Automatic Dependency Tracking
1181
@cindex Dependency tracking
1182
1183
Dependency tracking is performed as a side-effect of compilation.
1184
Each time the build system compiles a source file, it computes its
1185
list of dependencies (in C these are the header files included by the
1186
source being compiled). Later, any time @command{make} is run and a
1187
dependency appears to have changed, the dependent files will be
1188
rebuilt.
1189
1190
When @command{configure} is executed, you can see it probing each
1191
compiler for the dependency mechanism it supports (several mechanisms
1192
can be used):
1193
1194
@example
1195
~/amhello-1.0 % @kbd{./configure --prefix /usr}
1196
@dots{}
1197
checking dependency style of gcc... gcc3
1198
@dots{}
1199
@end example
1200
1201
Because dependencies are only computed as a side-effect of the
1202
compilation, no dependency information exists the first time a package
1203
is built. This is OK because all the files need to be built anyway:
1204
@code{make} does not have to decide which files need to be rebuilt.
1205
In fact, dependency tracking is completely useless for one-time builds
1206
and there is a @command{configure} option to disable this:
1207
1208
@table @option
1209
@item --disable-dependency-tracking
1210
@opindex --disable-dependency-tracking
1211
Speed up one-time builds.
1212
@end table
1213
1214
Some compilers do not offer any practical way to derive the list of
1215
dependencies as a side-effect of the compilation, requiring a separate
1216
run (maybe of another tool) to compute these dependencies. The
1217
performance penalty implied by these methods is important enough to
1218
disable them by default. The option @option{--enable-dependency-tracking}
1219
must be passed to @command{configure} to activate them.
1220
1221
@table @option
1222
@item --enable-dependency-tracking
1223
@opindex --enable-dependency-tracking
1224
Do not reject slow dependency extractors.
1225
@end table
1226
1227
@xref{Dependency Tracking Evolution}, for some discussion about the
1228
different dependency tracking schemes used by Automake over the years.
1229
1230
@node Nested Packages
1231
@subsection Nested Packages
1232
@cindex Nested packages
1233
@cindex Packages, nested
1234
@cindex Subpackages
1235
1236
Although nesting packages isn't something we would recommend to
1237
someone who is discovering the Autotools, it is a nice feature worthy
1238
of mention in this small advertising tour.
1239
1240
Autoconfiscated packages (that means packages whose build system have
1241
been created by Autoconf and friends) can be nested to arbitrary
1242
depth.
1243
1244
A typical setup is that a package A will distribute one of the libraries
1245
it needs in a subdirectory. This library B is a complete package with
1246
its own GNU Build System. The @command{configure} script of A will
1247
run the @command{configure} script of B as part of its execution,
1248
building and installing A will also build and install B. Generating a
1249
distribution for A will also include B.
1250
1251
It is possible to gather several package like this. GCC is a heavy
1252
user of this feature. This gives installers a single package to
1253
configure, build and install, while it allows developers to work on
1254
subpackages independently.
1255
1256
When configuring nested packages, the @command{configure} options
1257
given to the top-level @command{configure} are passed recursively to
1258
nested @command{configure}s. A package that does not understand an
1259
option will ignore it, assuming it is meaningful to some other
1260
package.
1261
1262
@opindex --help=recursive
1263
1264
The command @code{configure --help=recursive} can be used to display
1265
the options supported by all the included packages.
1266
1267
@xref{Subpackages}, for an example setup.
1268
1269
@node Why Autotools
1270
@section How Autotools Help
1271
@cindex Autotools, purpose
1272
1273
There are several reasons why you may not want to implement the GNU
1274
Build System yourself (read: write a @file{configure} script and
1275
@file{Makefile}s yourself).
1276
1277
@itemize @bullet
1278
@item
1279
As we have seen, the GNU Build System has a lot of
1280
features (@pxref{Use Cases}).
1281
Some users may expect features you have not implemented because
1282
you did not need them.
1283
@item
1284
Implementing these features portably is difficult and exhausting.
1285
Think of writing portable shell scripts, and portable
1286
@file{Makefile}s, for systems you may not have handy. @xref{Portable
1287
Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1288
convince yourself.
1289
@item
1290
You will have to upgrade your setup to follow changes to the GNU
1291
Coding Standards.
1292
@end itemize
1293
1294
The GNU Autotools take all this burden off your back and provide:
1295
1296
@itemize @bullet
1297
@item
1298
Tools to create a portable, complete, and self-contained GNU Build
1299
System, from simple instructions.
1300
@emph{Self-contained} meaning the resulting build system does not
1301
require the GNU Autotools.
1302
@item
1303
A central place where fixes and improvements are made:
1304
a bug-fix for a portability issue will benefit every package.
1305
@end itemize
1306
1307
Yet there also exist reasons why you may want NOT to use the
1308
Autotools@enddots{} For instance you may be already using (or used to)
1309
another incompatible build system. Autotools will only be useful if
1310
you do accept the concepts of the GNU Build System. People who have their
1311
own idea of how a build system should work will feel frustrated by the
1312
Autotools.
1313
1314
@node Hello World
1315
@section A Small Hello World
1316
@cindex Example Hello World
1317
@cindex Hello World example
1318
@cindex @file{amhello-1.0.tar.gz}, creation
1319
1320
In this section we recreate the @file{amhello-1.0} package from
1321
scratch. The first subsection shows how to call the Autotools to
1322
instantiate the GNU Build System, while the second explains the
1323
meaning of the @file{configure.ac} and @file{Makefile.am} files read
1324
by the Autotools.
1325
1326
@menu
1327
* Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1328
* amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
1329
@end menu
1330
1331
@node Creating amhello
1332
@subsection Creating @file{amhello-1.0.tar.gz}
1333
1334
Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1335
The package is simple enough so that we will only need to write 5
1336
files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1337
that is distributed with Automake if you do not want to write them.)
1338
1339
Create the following files in an empty directory.
1340
1341
@itemize @bullet
1342
1343
@item
1344
@file{src/main.c} is the source file for the @file{hello} program. We
1345
store it in the @file{src/} subdirectory, because later, when the package
1346
evolves, it will ease the addition of a @file{man/} directory for man
1347
pages, a @file{data/} directory for data files, etc.
1348
@example
1349
~/amhello % @kbd{cat src/main.c}
1350
#include <config.h>
1351
#include <stdio.h>
1352
1353
int
1354
main (void)
1355
@{
1356
puts ("Hello World!");
1357
puts ("This is " PACKAGE_STRING ".");
1358
return 0;
1359
@}
1360
@end example
1361
1362
@item
1363
@file{README} contains some very limited documentation for our little
1364
package.
1365
@example
1366
~/amhello % @kbd{cat README}
1367
This is a demonstration package for GNU Automake.
1368
Type `info Automake' to read the Automake manual.
1369
@end example
1370
1371
@item
1372
@file{Makefile.am} and @file{src/Makefile.am} contain Automake
1373
instructions for these two directories.
1374
1375
@example
1376
~/amhello % @kbd{cat src/Makefile.am}
1377
bin_PROGRAMS = hello
1378
hello_SOURCES = main.c
1379
~/amhello % @kbd{cat Makefile.am}
1380
SUBDIRS = src
1381
dist_doc_DATA = README
1382
@end example
1383
1384
@item
1385
Finally, @file{configure.ac} contains Autoconf instructions to
1386
create the @command{configure} script.
1387
1388
@example
1389
~/amhello % @kbd{cat configure.ac}
1390
AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1391
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1392
AC_PROG_CC
1393
AC_CONFIG_HEADERS([config.h])
1394
AC_CONFIG_FILES([
1395
Makefile
1396
src/Makefile
1397
])
1398
AC_OUTPUT
1399
@end example
1400
@end itemize
1401
1402
@cindex @command{autoreconf}, example
1403
1404
Once you have these five files, it is time to run the Autotools to
1405
instantiate the build system. Do this using the @command{autoreconf}
1406
command as follows:
1407
1408
@example
1409
~/amhello % @kbd{autoreconf --install}
1410
configure.ac: installing `./install-sh'
1411
configure.ac: installing `./missing'
1412
src/Makefile.am: installing `./depcomp'
1413
@end example
1414
1415
At this point the build system is complete.
1416
1417
In addition to the three scripts mentioned in its output, you can see
1418
that @command{autoreconf} created four other files: @file{configure},
1419
@file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1420
The latter three files are templates that will be adapted to the
1421
system by @command{configure} under the names @file{config.h},
1422
@file{Makefile}, and @file{src/Makefile}. Let's do this:
1423
1424
@example
1425
~/amhello % @kbd{./configure}
1426
checking for a BSD-compatible install... /usr/bin/install -c
1427
checking whether build environment is sane... yes
1428
checking for gawk... no
1429
checking for mawk... mawk
1430
checking whether make sets $(MAKE)... yes
1431
checking for gcc... gcc
1432
checking for C compiler default output file name... a.out
1433
checking whether the C compiler works... yes
1434
checking whether we are cross compiling... no
1435
checking for suffix of executables...
1436
checking for suffix of object files... o
1437
checking whether we are using the GNU C compiler... yes
1438
checking whether gcc accepts -g... yes
1439
checking for gcc option to accept ISO C89... none needed
1440
checking for style of include used by make... GNU
1441
checking dependency style of gcc... gcc3
1442
configure: creating ./config.status
1443
config.status: creating Makefile
1444
config.status: creating src/Makefile
1445
config.status: creating config.h
1446
config.status: executing depfiles commands
1447
@end example
1448
1449
@trindex distcheck
1450
@cindex @code{distcheck} example
1451
1452
You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1453
being created at the end after @command{configure} has probed the
1454
system. It is now possible to run all the targets we wish
1455
(@pxref{Standard Targets}). For instance:
1456
1457
@example
1458
~/amhello % @kbd{make}
1459
@dots{}
1460
~/amhello % @kbd{src/hello}
1461
Hello World!
1462
This is amhello 1.0.
1463
~/amhello % @kbd{make distcheck}
1464
@dots{}
1465
=============================================
1466
amhello-1.0 archives ready for distribution:
1467
amhello-1.0.tar.gz
1468
=============================================
1469
@end example
1470
1471
Note that running @command{autoreconf} is only needed initially when
1472
the GNU Build System does not exist. When you later change some
1473
instructions in a @file{Makefile.am} or @file{configure.ac}, the
1474
relevant part of the build system will be regenerated automatically
1475
when you execute @command{make}.
1476
1477
@command{autoreconf} is a script that calls @command{autoconf},
1478
@command{automake}, and a bunch of other commands in the right order.
1479
If you are beginning with these tools, it is not important to figure
1480
out in which order all these tools should be invoked and why. However,
1481
because Autoconf and Automake have separate manuals, the important
1482
point to understand is that @command{autoconf} is in charge of
1483
creating @file{configure} from @file{configure.ac}, while
1484
@command{automake} is in charge of creating @file{Makefile.in}s from
1485
@file{Makefile.am}s and @file{configure.ac}. This should at least
1486
direct you to the right manual when seeking answers.
1487
1488
1489
@node amhello Explained
1490
@subsection @file{amhello-1.0} Explained
1491
1492
Let us begin with the contents of @file{configure.ac}.
1493
1494
@example
1495
AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1496
AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1497
AC_PROG_CC
1498
AC_CONFIG_HEADERS([config.h])
1499
AC_CONFIG_FILES([
1500
Makefile
1501
src/Makefile
1502
])
1503
AC_OUTPUT
1504
@end example
1505
1506
This file is read by both @command{autoconf} (to create
1507
@file{configure.ac}) and @command{automake} (to create the various
1508
@file{Makefile.in}s). It contains a series of M4 macros that will be
1509
expanded as shell code to finally form the @file{configure} script.
1510
We will not elaborate on the syntax of this file, because the Autoconf
1511
manual has a whole section about it (@pxref{Writing configure.ac, ,
1512
Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1513
1514
The macros prefixed with @code{AC_} are Autoconf macros, documented
1515
in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1516
Index, autoconf, The Autoconf Manual}). The macros that start with
1517
@code{AM_} are Automake macros, documented later in this manual
1518
(@pxref{Macro Index}).
1519
1520
The first two lines of @file{configure.ac} initialize Autoconf and
1521
Automake. @code{AC_INIT} takes in as parameters the name of the package,
1522
its version number, and a contact address for bug-reports about the
1523
package (this address is output at the end of @code{./configure
1524
--help}, for instance). When adapting this setup to your own package,
1525
by all means please do not blindly copy Automake's address: use the
1526
mailing list of your package, or your own mail address.
1527
1528
@opindex -Wall
1529
@opindex -Werror
1530
@opindex foreign
1531
1532
The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1533
@command{automake} (@pxref{Options}). @option{-Wall} and
1534
@option{-Werror} ask @command{automake} to turn on all warnings and
1535
report them as errors. We are speaking of @strong{Automake} warnings
1536
here, such as dubious instructions in @file{Makefile.am}. This has
1537
absolutely nothing to do with how the compiler will be called, even
1538
though it may support options with similar names. Using @option{-Wall
1539
-Werror} is a safe setting when starting to work on a package: you do
1540
not want to miss any issues. Later you may decide to relax things a
1541
bit. The @option{foreign} option tells Automake that this package
1542
will not follow the GNU Standards. GNU packages should always
1543
distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1544
etc. We do not want @command{automake} to complain about these
1545
missing files in our small example.
1546
1547
The @code{AC_PROG_CC} line causes the @command{configure} script to
1548
search for a C compiler and define the variable @code{CC} with its
1549
name. The @file{src/Makefile.in} file generated by Automake uses the
1550
variable @code{CC} to build @file{hello}, so when @command{configure}
1551
creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1552
@code{CC} with the value it has found. If Automake is asked to create
1553
a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1554
not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1555
1556
The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1557
@command{configure} script to create a @file{config.h} file gathering
1558
@samp{#define}s defined by other macros in @file{configure.ac}. In our
1559
case, the @code{AC_INIT} macro already defined a few of them. Here
1560
is an excerpt of @file{config.h} after @command{configure} has run:
1561
1562
@smallexample
1563
@dots{}
1564
/* Define to the address where bug reports for this package should be sent. */
1565
#define PACKAGE_BUGREPORT "bug-automake@@gnu.org"
1566
1567
/* Define to the full name and version of this package. */
1568
#define PACKAGE_STRING "amhello 1.0"
1569
@dots{}
1570
@end smallexample
1571
1572
As you probably noticed, @file{src/main.c} includes @file{config.h} so
1573
it can use @code{PACKAGE_STRING}. In a real-world project,
1574
@file{config.h} can grow really big, with one @samp{#define} per
1575
feature probed on the system.
1576
1577
The @code{AC_CONFIG_FILES} macro declares the list of files that
1578
@command{configure} should create from their @file{*.in} templates.
1579
Automake also scans this list to find the @file{Makefile.am} files it must
1580
process. (This is important to remember: when adding a new directory
1581
to your project, you should add its @file{Makefile} to this list,
1582
otherwise Automake will never process the new @file{Makefile.am} you
1583
wrote in that directory.)
1584
1585
Finally, the @code{AC_OUTPUT} line is a closing command that actually
1586
produces the part of the script in charge of creating the files
1587
registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1588
1589
@cindex @command{autoscan}
1590
1591
When starting a new project, we suggest you start with such a simple
1592
@file{configure.ac}, and gradually add the other tests it requires.
1593
The command @command{autoscan} can also suggest a few of the tests
1594
your package may need (@pxref{autoscan Invocation, , Using
1595
@command{autoscan} to Create @file{configure.ac}, autoconf, The
1596
Autoconf Manual}).
1597
1598
@cindex @file{Makefile.am}, Hello World
1599
1600
We now turn to @file{src/Makefile.am}. This file contains
1601
Automake instructions to build and install @file{hello}.
1602
1603
@example
1604
bin_PROGRAMS = hello
1605
hello_SOURCES = main.c
1606
@end example
1607
1608
A @file{Makefile.am} has the same syntax as an ordinary
1609
@file{Makefile}. When @command{automake} processes a
1610
@file{Makefile.am} it copies the entire file into the output
1611
@file{Makefile.in} (that will be later turned into @file{Makefile} by
1612
@command{configure}) but will react to certain variable definitions
1613
by generating some build rules and other variables.
1614
Often @file{Makefile.am}s contain only a list of variable definitions as
1615
above, but they can also contain other variable and rule definitions that
1616
@command{automake} will pass along without interpretation.
1617
1618
Variables that end with @code{_PROGRAMS} are special variables
1619
that list programs that the resulting @file{Makefile} should build.
1620
In Automake speak, this @code{_PROGRAMS} suffix is called a
1621
@dfn{primary}; Automake recognizes other primaries such as
1622
@code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1623
to different types of files.
1624
1625
The @samp{bin} part of the @code{bin_PROGRAMS} tells
1626
@command{automake} that the resulting programs should be installed in
1627
@var{bindir}. Recall that the GNU Build System uses a set of variables
1628
to denote destination directories and allow users to customize these
1629
locations (@pxref{Standard Directory Variables}). Any such directory
1630
variable can be put in front of a primary (omitting the @code{dir}
1631
suffix) to tell @command{automake} where to install the listed files.
1632
1633
Programs need to be built from source files, so for each program
1634
@code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1635
@command{automake} will look for another variable named
1636
@code{@var{prog}_SOURCES} listing its source files. There may be more
1637
than one source file: they will all be compiled and linked together.
1638
1639
Automake also knows that source files need to be distributed when
1640
creating a tarball (unlike built programs). So a side-effect of this
1641
@code{hello_SOURCES} declaration is that @file{main.c} will be
1642
part of the tarball created by @code{make dist}.
1643
1644
Finally here are some explanations regarding the top-level
1645
@file{Makefile.am}.
1646
1647
@example
1648
SUBDIRS = src
1649
dist_doc_DATA = README
1650
@end example
1651
1652
@code{SUBDIRS} is a special variable listing all directories that
1653
@command{make} should recurse into before processing the current
1654
directory. So this line is responsible for @command{make} building
1655
@file{src/hello} even though we run it from the top-level. This line
1656
also causes @code{make install} to install @file{src/hello} before
1657
installing @file{README} (not that this order matters).
1658
1659
The line @code{dist_doc_DATA = README} causes @file{README} to be
1660
distributed and installed in @var{docdir}. Files listed with the
1661
@code{_DATA} primary are not automatically part of the tarball built
1662
with @code{make dist}, so we add the @code{dist_} prefix so they get
1663
distributed. However, for @file{README} it would not have been
1664
necessary: @command{automake} automatically distributes any
1665
@file{README} file it encounters (the list of other files
1666
automatically distributed is presented by @code{automake --help}).
1667
The only important effect of this second line is therefore to install
1668
@file{README} during @code{make install}.
1669
1670
1671
@node Generalities
1672
@chapter General ideas
1673
1674
The following sections cover a few basic ideas that will help you
1675
understand how Automake works.
1676
1677
@menu
1678
* General Operation:: General operation of Automake
1679
* Strictness:: Standards conformance checking
1680
* Uniform:: The Uniform Naming Scheme
1681
* Canonicalization:: How derived variables are named
1682
* User Variables:: Variables reserved for the user
1683
* Auxiliary Programs:: Programs automake might require
1684
@end menu
1685
1686
1687
@node General Operation
1688
@section General Operation
1689
1690
Automake works by reading a @file{Makefile.am} and generating a
1691
@file{Makefile.in}. Certain variables and rules defined in the
1692
@file{Makefile.am} instruct Automake to generate more specialized code;
1693
for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1694
for compiling and linking programs to be generated.
1695
1696
@cindex Non-standard targets
1697
@cindex @code{cvs-dist}, non-standard example
1698
@trindex cvs-dist
1699
@trindex git-dist
1700
1701
The variable definitions and rules in the @file{Makefile.am} are
1702
copied verbatim into the generated file. This allows you to add
1703
arbitrary code into the generated @file{Makefile.in}. For instance,
1704
the Automake distribution includes a non-standard rule for the
1705
@code{git-dist} target, which the Automake maintainer uses to make
1706
distributions from his source control system.
1707
1708
@cindex GNU make extensions
1709
1710
Note that most GNU make extensions are not recognized by Automake. Using
1711
such extensions in a @file{Makefile.am} will lead to errors or confusing
1712
behavior.
1713
1714
@cindex Append operator
1715
@cmindex +=
1716
A special exception is that the GNU make append operator, @samp{+=}, is
1717
supported. This operator appends its right hand argument to the variable
1718
specified on the left. Automake will translate the operator into
1719
an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1720
1721
Automake tries to keep comments grouped with any adjoining rules or
1722
variable definitions.
1723
1724
@cindex Make targets, overriding
1725
@cindex Make rules, overriding
1726
@cindex Overriding make rules
1727
@cindex Overriding make targets
1728
1729
A rule defined in @file{Makefile.am} generally overrides any such
1730
rule of a similar name that would be automatically generated by
1731
@command{automake}. Although this is a supported feature, it is generally
1732
best to avoid making use of it, as sometimes the generated rules are
1733
very particular.
1734
1735
@cindex Variables, overriding
1736
@cindex Overriding make variables
1737
1738
Similarly, a variable defined in @file{Makefile.am} or
1739
@code{AC_SUBST}ed from @file{configure.ac} will override any
1740
definition of the variable that @command{automake} would ordinarily
1741
create. This feature is more often useful than the ability to
1742
override a rule. Be warned that many of the variables generated by
1743
@command{automake} are considered to be for internal use only, and their
1744
names might change in future releases.
1745
1746
@cindex Recursive operation of Automake
1747
@cindex Automake, recursive operation
1748
@cindex Example of recursive operation
1749
1750
When examining a variable definition, Automake will recursively examine
1751
variables referenced in the definition. For example, if Automake is
1752
looking at the content of @code{foo_SOURCES} in this snippet
1753
1754
@example
1755
xs = a.c b.c
1756
foo_SOURCES = c.c $(xs)
1757
@end example
1758
1759
it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1760
contents of @code{foo_SOURCES}.
1761
1762
@cindex @code{##} (special Automake comment)
1763
@cindex Special Automake comment
1764
@cindex Comment, special to Automake
1765
1766
Automake also allows a form of comment that is @emph{not} copied into
1767
the output; all lines beginning with @samp{##} (leading spaces allowed)
1768
are completely ignored by Automake.
1769
1770
It is customary to make the first line of @file{Makefile.am} read:
1771
1772
@cindex Makefile.am, first line
1773
@cindex First line of Makefile.am
1774
1775
@example
1776
## Process this file with automake to produce Makefile.in
1777
@end example
1778
1779
@c FIXME discuss putting a copyright into Makefile.am here? I would but
1780
@c I don't know quite what to say.
1781
1782
@c FIXME document customary ordering of Makefile.am here!
1783
1784
1785
@node Strictness
1786
@section Strictness
1787
1788
@cindex Non-GNU packages
1789
1790
While Automake is intended to be used by maintainers of GNU packages, it
1791
does make some effort to accommodate those who wish to use it, but do
1792
not want to use all the GNU conventions.
1793
1794
@cindex Strictness, defined
1795
@cindex Strictness, @option{foreign}
1796
@cindex @option{foreign} strictness
1797
@cindex Strictness, @option{gnu}
1798
@cindex @option{gnu} strictness
1799
@cindex Strictness, @option{gnits}
1800
@cindex @option{gnits} strictness
1801
1802
To this end, Automake supports three levels of @dfn{strictness}---the
1803
strictness indicating how stringently Automake should check standards
1804
conformance.
1805
1806
The valid strictness levels are:
1807
1808
@table @option
1809
@item foreign
1810
Automake will check for only those things that are absolutely
1811
required for proper operations. For instance, whereas GNU standards
1812
dictate the existence of a @file{NEWS} file, it will not be required in
1813
this mode. The name comes from the fact that Automake is intended to be
1814
used for GNU programs; these relaxed rules are not the standard mode of
1815
operation.
1816
1817
@item gnu
1818
Automake will check---as much as possible---for compliance to the GNU
1819
standards for packages. This is the default.
1820
1821
@item gnits
1822
Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1823
standards}. These are based on the GNU standards, but are even more
1824
detailed. Unless you are a Gnits standards contributor, it is
1825
recommended that you avoid this option until such time as the Gnits
1826
standard is actually published (which may never happen).
1827
@end table
1828
1829
@xref{Gnits}, for more information on the precise implications of the
1830
strictness level.
1831
1832
Automake also has a special ``cygnus'' mode that is similar to
1833
strictness but handled differently. This mode is useful for packages
1834
that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1835
@xref{Cygnus}, for more information on this mode.
1836
1837
1838
@node Uniform
1839
@section The Uniform Naming Scheme
1840
1841
@cindex Uniform naming scheme
1842
1843
Automake variables generally follow a @dfn{uniform naming scheme} that
1844
makes it easy to decide how programs (and other derived objects) are
1845
built, and how they are installed. This scheme also supports
1846
@command{configure} time determination of what should be built.
1847
1848
@cindex @code{_PROGRAMS} primary variable
1849
@cindex @code{PROGRAMS} primary variable
1850
@cindex Primary variable, @code{PROGRAMS}
1851
@cindex Primary variable, defined
1852
@vindex _PROGRAMS
1853
1854
At @command{make} time, certain variables are used to determine which
1855
objects are to be built. The variable names are made of several pieces
1856
that are concatenated together.
1857
1858
The piece that tells automake what is being built is commonly called
1859
the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1860
list of programs that are to be compiled and linked.
1861
@vindex PROGRAMS
1862
1863
@cindex @code{pkglibdir}, defined
1864
@cindex @code{pkgincludedir}, defined
1865
@cindex @code{pkgdatadir}, defined
1866
1867
@vindex pkglibdir
1868
@vindex pkgincludedir
1869
@vindex pkgdatadir
1870
1871
@cindex @code{PACKAGE}, directory
1872
A different set of names is used to decide where the built objects
1873
should be installed. These names are prefixes to the primary, and they
1874
indicate which standard directory should be used as the installation
1875
directory. The standard directory names are given in the GNU standards
1876
(@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1877
Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
1878
and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
1879
versions, but with @samp{$(PACKAGE)} appended. For instance,
1880
@code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
1881
1882
@cindex @code{EXTRA_}, prepending
1883
For each primary, there is one additional variable named by prepending
1884
@samp{EXTRA_} to the primary name. This variable is used to list
1885
objects that may or may not be built, depending on what
1886
@command{configure} decides. This variable is required because Automake
1887
must statically know the entire list of objects that may be built in
1888
order to generate a @file{Makefile.in} that will work in all cases.
1889
1890
@cindex @code{EXTRA_PROGRAMS}, defined
1891
@cindex Example, @code{EXTRA_PROGRAMS}
1892
@cindex @command{cpio} example
1893
1894
For instance, @command{cpio} decides at configure time which programs
1895
should be built. Some of the programs are installed in @code{bindir},
1896
and some are installed in @code{sbindir}:
1897
1898
@example
1899
EXTRA_PROGRAMS = mt rmt
1900
bin_PROGRAMS = cpio pax
1901
sbin_PROGRAMS = $(MORE_PROGRAMS)
1902
@end example
1903
1904
Defining a primary without a prefix as a variable, e.g.,
1905
@samp{PROGRAMS}, is an error.
1906
1907
Note that the common @samp{dir} suffix is left off when constructing the
1908
variable names; thus one writes @samp{bin_PROGRAMS} and not
1909
@samp{bindir_PROGRAMS}.
1910
1911
Not every sort of object can be installed in every directory. Automake
1912
will flag those attempts it finds in error.
1913
Automake will also diagnose obvious misspellings in directory names.
1914
1915
@cindex Extending list of installation directories
1916
@cindex Installation directories, extending list
1917
1918
Sometimes the standard directories---even as augmented by
1919
Automake---are not enough. In particular it is sometimes useful, for
1920
clarity, to install objects in a subdirectory of some predefined
1921
directory. To this end, Automake allows you to extend the list of
1922
possible installation directories. A given prefix (e.g., @samp{zar})
1923
is valid if a variable of the same name with @samp{dir} appended is
1924
defined (e.g., @samp{zardir}).
1925
1926
For instance, the following snippet will install @file{file.xml} into
1927
@samp{$(datadir)/xml}.
1928
1929
@example
1930
xmldir = $(datadir)/xml
1931
xml_DATA = file.xml
1932
@end example
1933
1934
@cindex @samp{noinst_} primary prefix, definition
1935
@vindex noinst_
1936
1937
The special prefix @samp{noinst_} indicates that the objects in question
1938
should be built but not installed at all. This is usually used for
1939
objects required to build the rest of your package, for instance static
1940
libraries (@pxref{A Library}), or helper scripts.
1941
1942
@cindex @samp{check_} primary prefix, definition
1943
@vindex check_
1944
1945
The special prefix @samp{check_} indicates that the objects in question
1946
should not be built until the @samp{make check} command is run. Those
1947
objects are not installed either.
1948
1949
The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
1950
@samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
1951
@samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
1952
@vindex PROGRAMS
1953
@vindex LIBRARIES
1954
@vindex LISP
1955
@vindex PYTHON
1956
@vindex JAVA
1957
@vindex SCRIPTS
1958
@vindex DATA
1959
@vindex HEADERS
1960
@vindex MANS
1961
@vindex TEXINFOS
1962
1963
Some primaries also allow additional prefixes that control other
1964
aspects of @command{automake}'s behavior. The currently defined prefixes
1965
are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
1966
are explained later (@pxref{Program and Library Variables}).
1967
1968
1969
@node Canonicalization
1970
@section How derived variables are named
1971
1972
@cindex canonicalizing Automake variables
1973
1974
Sometimes a Makefile variable name is derived from some text the
1975
maintainer supplies. For instance, a program name listed in
1976
@samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
1977
variable. In cases like this, Automake canonicalizes the text, so that
1978
program names and the like do not have to follow Makefile variable naming
1979
rules. All characters in the name except for letters, numbers, the
1980
strudel (@@), and the underscore are turned into underscores when making
1981
variable references.
1982
1983
For example, if your program is named @file{sniff-glue}, the derived
1984
variable name would be @samp{sniff_glue_SOURCES}, not
1985
@samp{sniff-glue_SOURCES}. Similarly the sources for a library named
1986
@file{libmumble++.a} should be listed in the
1987
@samp{libmumble___a_SOURCES} variable.
1988
1989
The strudel is an addition, to make the use of Autoconf substitutions in
1990
variable names less obfuscating.
1991
1992
1993
@node User Variables
1994
@section Variables reserved for the user
1995
1996
@cindex variables, reserved for the user
1997
@cindex user variables
1998
1999
Some @file{Makefile} variables are reserved by the GNU Coding Standards
2000
for the use of the ``user''---the person building the package. For
2001
instance, @code{CFLAGS} is one such variable.
2002
2003
Sometimes package developers are tempted to set user variables such as
2004
@code{CFLAGS} because it appears to make their job easier. However,
2005
the package itself should never set a user variable, particularly not
2006
to include switches that are required for proper compilation of the
2007
package. Since these variables are documented as being for the
2008
package builder, that person rightfully expects to be able to override
2009
any of these variables at build time.
2010
2011
To get around this problem, Automake introduces an automake-specific
2012
shadow variable for each user flag variable. (Shadow variables are
2013
not introduced for variables like @code{CC}, where they would make no
2014
sense.) The shadow variable is named by prepending @samp{AM_} to the
2015
user variable's name. For instance, the shadow variable for
2016
@code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2017
the author(s) of the @file{Makefile.am} and @file{configure.ac}
2018
files---may adjust these shadow variables however necessary.
2019
2020
@xref{Flag Variables Ordering}, for more discussion about these
2021
variables and how they interact with per-target variables.
2022
2023
@node Auxiliary Programs
2024
@section Programs automake might require
2025
2026
@cindex Programs, auxiliary
2027
@cindex Auxiliary programs
2028
2029
Automake sometimes requires helper programs so that the generated
2030
@file{Makefile} can do its work properly. There are a fairly large
2031
number of them, and we list them here.
2032
2033
Although all of these files are distributed and installed with
2034
Automake, a couple of them are maintained separately. The Automake
2035
copies are updated before each release, but we mention the original
2036
source in case you need more recent versions.
2037
2038
@table @code
2039
@item ansi2knr.c
2040
@itemx ansi2knr.1
2041
These two files are used by the obsolete de-ANSI-fication support
2042
(@pxref{ANSI}).
2043
2044
@item compile
2045
This is a wrapper for compilers that do not accept options @option{-c}
2046
and @option{-o} at the same time. It is only used when absolutely
2047
required. Such compilers are rare.
2048
2049
@item config.guess
2050
@itemx config.sub
2051
These two programs compute the canonical triplets for the given build,
2052
host, or target architecture. These programs are updated regularly to
2053
support new architectures and fix probes broken by changes in new
2054
kernel versions. Each new release of Automake comes with up-to-date
2055
copies of these programs. If your copy of Automake is getting old,
2056
you are encouraged to fetch the latest versions of these files from
2057
@url{http://savannah.gnu.org/cvs/?group=config} before making a
2058
release.
2059
2060
@item config-ml.in
2061
This file is not a program, it is a @file{configure} fragment used for
2062
multilib support (@pxref{Multilibs}). This file is maintained in the
2063
GCC tree at @url{http://gcc.gnu.org/svn.html}.
2064
2065
@item depcomp
2066
This program understands how to run a compiler so that it will
2067
generate not only the desired output but also dependency information
2068
that is then used by the automatic dependency tracking feature
2069
(@pxref{Dependencies}).
2070
2071
@item elisp-comp
2072
This program is used to byte-compile Emacs Lisp code.
2073
2074
@item install-sh
2075
This is a replacement for the @command{install} program that works on
2076
platforms where @command{install} is unavailable or unusable.
2077
2078
@item mdate-sh
2079
This script is used to generate a @file{version.texi} file. It examines
2080
a file and prints some date information about it.
2081
2082
@item missing
2083
This wraps a number of programs that are typically only required by
2084
maintainers. If the program in question doesn't exist,
2085
@command{missing} prints an informative warning and attempts to fix
2086
things so that the build can continue.
2087
2088
@item mkinstalldirs
2089
This script used to be a wrapper around @samp{mkdir -p}, which is not
2090
portable. Now we prefer to use @samp{install-sh -d} when configure
2091
finds that @samp{mkdir -p} does not work, this makes one less script to
2092
distribute.
2093
2094
For backward compatibility @file{mkinstalldirs} is still used and
2095
distributed when @command{automake} finds it in a package. But it is no
2096
longer installed automatically, and it should be safe to remove it.
2097
2098
@item py-compile
2099
This is used to byte-compile Python scripts.
2100
2101
@item symlink-tree
2102
This program duplicates a tree of directories, using symbolic links
2103
instead of copying files. Such operation is performed when building
2104
multilibs (@pxref{Multilibs}). This file is maintained in the GCC
2105
tree at @url{http://gcc.gnu.org/svn.html}.
2106
2107
@item texinfo.tex
2108
Not a program, this file is required for @samp{make dvi}, @samp{make
2109
ps} and @samp{make pdf} to work when Texinfo sources are in the
2110
package. The latest version can be downloaded from
2111
@url{http://www.gnu.org/software/texinfo/}.
2112
2113
@item ylwrap
2114
This program wraps @command{lex} and @command{yacc} to rename their
2115
output files. It also ensures that, for instance, multiple
2116
@command{yacc} instances can be invoked in a single directory in
2117
parallel.
2118
2119
@end table
2120
2121
2122
@node Examples
2123
@chapter Some example packages
2124
2125
This section contains two small examples.
2126
2127
The first example (@pxref{Complete}) assumes you have an existing
2128
project already using Autoconf, with handcrafted @file{Makefile}s, and
2129
that you want to convert it to using Automake. If you are discovering
2130
both tools, it is probably better that you look at the Hello World
2131
example presented earlier (@pxref{Hello World}).
2132
2133
The second example (@pxref{true}) shows how two programs can be built
2134
from the same file, using different compilation parameters. It
2135
contains some technical digressions that are probably best skipped on
2136
first read.
2137
2138
@menu
2139
* Complete:: A simple example, start to finish
2140
* true:: Building true and false
2141
@end menu
2142
2143
2144
@node Complete
2145
@section A simple example, start to finish
2146
2147
@cindex Complete example
2148
2149
Let's suppose you just finished writing @code{zardoz}, a program to make
2150
your head float from vortex to vortex. You've been using Autoconf to
2151
provide a portability framework, but your @file{Makefile.in}s have been
2152
ad-hoc. You want to make them bulletproof, so you turn to Automake.
2153
2154
@cindex @code{AM_INIT_AUTOMAKE}, example use
2155
2156
The first step is to update your @file{configure.ac} to include the
2157
commands that @command{automake} needs. The way to do this is to add an
2158
@code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2159
2160
@example
2161
AC_INIT([zardoz], [1.0])
2162
AM_INIT_AUTOMAKE
2163
@dots{}
2164
@end example
2165
2166
Since your program doesn't have any complicating factors (e.g., it
2167
doesn't use @code{gettext}, it doesn't want to build a shared library),
2168
you're done with this part. That was easy!
2169
2170
@cindex @command{aclocal} program, introduction
2171
@cindex @file{aclocal.m4}, preexisting
2172
@cindex @file{acinclude.m4}, defined
2173
2174
Now you must regenerate @file{configure}. But to do that, you'll need
2175
to tell @command{autoconf} how to find the new macro you've used. The
2176
easiest way to do this is to use the @command{aclocal} program to
2177
generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2178
already have an @file{aclocal.m4}, because you had to write some hairy
2179
macros for your program. The @command{aclocal} program lets you put
2180
your own macros into @file{acinclude.m4}, so simply rename and then
2181
run:
2182
2183
@example
2184
mv aclocal.m4 acinclude.m4
2185
aclocal
2186
autoconf
2187
@end example
2188
2189
@cindex @command{zardoz} example
2190
2191
Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2192
Since @code{zardoz} is a user program, you want to install it where the
2193
rest of the user programs go: @code{bindir}. Additionally,
2194
@code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2195
script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2196
@samp{$(LIBOBJS)}. So here's what you'd write:
2197
2198
@example
2199
bin_PROGRAMS = zardoz
2200
zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2201
zardoz_LDADD = $(LIBOBJS)
2202
2203
info_TEXINFOS = zardoz.texi
2204
@end example
2205
2206
Now you can run @samp{automake --add-missing} to generate your
2207
@file{Makefile.in} and grab any auxiliary files you might need, and
2208
you're done!
2209
2210
2211
@node true
2212
@section Building true and false
2213
2214
@cindex Example, @command{false} and @command{true}
2215
@cindex @command{false} Example
2216
@cindex @command{true} Example
2217
2218
Here is another, trickier example. It shows how to generate two
2219
programs (@code{true} and @code{false}) from the same source file
2220
(@file{true.c}). The difficult part is that each compilation of
2221
@file{true.c} requires different @code{cpp} flags.
2222
2223
@example
2224
bin_PROGRAMS = true false
2225
false_SOURCES =
2226
false_LDADD = false.o
2227
2228
true.o: true.c
2229
$(COMPILE) -DEXIT_CODE=0 -c true.c
2230
2231
false.o: true.c
2232
$(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2233
@end example
2234
2235
Note that there is no @code{true_SOURCES} definition. Automake will
2236
implicitly assume that there is a source file named @file{true.c}, and
2237
define rules to compile @file{true.o} and link @file{true}. The
2238
@samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2239
will override the Automake generated rule to build @file{true.o}.
2240
2241
@code{false_SOURCES} is defined to be empty---that way no implicit value
2242
is substituted. Because we have not listed the source of
2243
@file{false}, we have to tell Automake how to link the program. This is
2244
the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2245
variable, holding the dependencies of the @file{false} target will be
2246
automatically generated by Automake from the content of
2247
@code{false_LDADD}.
2248
2249
The above rules won't work if your compiler doesn't accept both
2250
@option{-c} and @option{-o}. The simplest fix for this is to introduce a
2251
bogus dependency (to avoid problems with a parallel @command{make}):
2252
2253
@example
2254
true.o: true.c false.o
2255
$(COMPILE) -DEXIT_CODE=0 -c true.c
2256
2257
false.o: true.c
2258
$(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2259
@end example
2260
2261
Also, these explicit rules do not work if the obsolete de-ANSI-fication feature
2262
is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
2263
more work:
2264
2265
@example
2266
true_.o: true_.c false_.o
2267
$(COMPILE) -DEXIT_CODE=0 -c true_.c
2268
2269
false_.o: true_.c
2270
$(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
2271
@end example
2272
2273
As it turns out, there is also a much easier way to do this same task.
2274
Some of the above techniques are useful enough that we've kept the
2275
example in the manual. However if you were to build @code{true} and
2276
@code{false} in real life, you would probably use per-program
2277
compilation flags, like so:
2278
2279
@example
2280
bin_PROGRAMS = false true
2281
2282
false_SOURCES = true.c
2283
false_CPPFLAGS = -DEXIT_CODE=1
2284
2285
true_SOURCES = true.c
2286
true_CPPFLAGS = -DEXIT_CODE=0
2287
@end example
2288
2289
In this case Automake will cause @file{true.c} to be compiled twice,
2290
with different flags. De-ANSI-fication will work automatically. In
2291
this instance, the names of the object files would be chosen by
2292
automake; they would be @file{false-true.o} and @file{true-true.o}.
2293
(The name of the object files rarely matters.)
2294
2295
2296
@node Invoking Automake
2297
@chapter Creating a @file{Makefile.in}
2298
2299
@cindex Multiple @file{configure.ac} files
2300
@cindex Invoking @command{automake}
2301
@cindex @command{automake}, invoking
2302
2303
To create all the @file{Makefile.in}s for a package, run the
2304
@command{automake} program in the top level directory, with no
2305
arguments. @command{automake} will automatically find each
2306
appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2307
@pxref{configure}) and generate the corresponding @file{Makefile.in}.
2308
Note that @command{automake} has a rather simplistic view of what
2309
constitutes a package; it assumes that a package has only one
2310
@file{configure.ac}, at the top. If your package has multiple
2311
@file{configure.ac}s, then you must run @command{automake} in each
2312
directory holding a @file{configure.ac}. (Alternatively, you may rely
2313
on Autoconf's @command{autoreconf}, which is able to recurse your
2314
package tree and run @command{automake} where appropriate.)
2315
2316
You can optionally give @command{automake} an argument; @file{.am} is
2317
appended to the argument and the result is used as the name of the
2318
input file. This feature is generally only used to automatically
2319
rebuild an out-of-date @file{Makefile.in}. Note that
2320
@command{automake} must always be run from the topmost directory of a
2321
project, even if being used to regenerate the @file{Makefile.in} in
2322
some subdirectory. This is necessary because @command{automake} must
2323
scan @file{configure.ac}, and because @command{automake} uses the
2324
knowledge that a @file{Makefile.in} is in a subdirectory to change its
2325
behavior in some cases.
2326
2327
@vindex AUTOCONF
2328
Automake will run @command{autoconf} to scan @file{configure.ac} and
2329
its dependencies (i.e., @file{aclocal.m4} and any included file),
2330
therefore @command{autoconf} must be in your @env{PATH}. If there is
2331
an @env{AUTOCONF} variable in your environment it will be used
2332
instead of @command{autoconf}, this allows you to select a particular
2333
version of Autoconf. By the way, don't misunderstand this paragraph:
2334
@command{automake} runs @command{autoconf} to @strong{scan} your
2335
@file{configure.ac}, this won't build @file{configure} and you still
2336
have to run @command{autoconf} yourself for this purpose.
2337
2338
@cindex @command{automake} options
2339
@cindex Options, @command{automake}
2340
@cindex Strictness, command line
2341
2342
@command{automake} accepts the following options:
2343
2344
@cindex Extra files distributed with Automake
2345
@cindex Files distributed with Automake
2346
@cindex @file{config.guess}
2347
2348
@table @code
2349
@item -a
2350
@itemx --add-missing
2351
@opindex -a
2352
@opindex --add-missing
2353
Automake requires certain common files to exist in certain situations;
2354
for instance, @file{config.guess} is required if @file{configure.ac} runs
2355
@code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2356
files (@pxref{Auxiliary Programs}); this option will cause the missing
2357
ones to be automatically added to the package, whenever possible. In
2358
general if Automake tells you a file is missing, try using this option.
2359
By default Automake tries to make a symbolic link pointing to its own
2360
copy of the missing file; this can be changed with @option{--copy}.
2361
2362
Many of the potentially-missing files are common scripts whose
2363
location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2364
Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2365
file is considered missing, and where the missing file is added
2366
(@pxref{Optional}).
2367
2368
@item --libdir=@var{dir}
2369
@opindex --libdir
2370
Look for Automake data files in directory @var{dir} instead of in the
2371
installation directory. This is typically used for debugging.
2372
2373
@item -c
2374
@opindex -c
2375
@itemx --copy
2376
@opindex --copy
2377
When used with @option{--add-missing}, causes installed files to be
2378
copied. The default is to make a symbolic link.
2379
2380
@item --cygnus
2381
@opindex --cygnus
2382
Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2383
of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2384
2385
@item -f
2386
@opindex -f
2387
@itemx --force-missing
2388
@opindex --force-missing
2389
When used with @option{--add-missing}, causes standard files to be reinstalled
2390
even if they already exist in the source tree. This involves removing
2391
the file from the source tree before creating the new symlink (or, with
2392
@option{--copy}, copying the new file).
2393
2394
@item --foreign
2395
@opindex --foreign
2396
Set the global strictness to @option{foreign}. For more information, see
2397
@ref{Strictness}.
2398
2399
@item --gnits
2400
@opindex --gnits
2401
Set the global strictness to @option{gnits}. For more information, see
2402
@ref{Gnits}.
2403
2404
@item --gnu
2405
@opindex --gnu
2406
Set the global strictness to @option{gnu}. For more information, see
2407
@ref{Gnits}. This is the default strictness.
2408
2409
@item --help
2410
@opindex --help
2411
Print a summary of the command line options and exit.
2412
2413
@item -i
2414
@itemx --ignore-deps
2415
@opindex -i
2416
This disables the dependency tracking feature in generated
2417
@file{Makefile}s; see @ref{Dependencies}.
2418
2419
@item --include-deps
2420
@opindex --include-deps
2421
This enables the dependency tracking feature. This feature is enabled
2422
by default. This option is provided for historical reasons only and
2423
probably should not be used.
2424
2425
@item --no-force
2426
@opindex --no-force
2427
Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2428
@file{configure.ac}. This option causes it to only update those
2429
@file{Makefile.in}s that are out of date with respect to one of their
2430
dependents.
2431
2432
@item -o @var{dir}
2433
@itemx --output-dir=@var{dir}
2434
@opindex -o
2435
@opindex --output-dir
2436
Put the generated @file{Makefile.in} in the directory @var{dir}.
2437
Ordinarily each @file{Makefile.in} is created in the directory of the
2438
corresponding @file{Makefile.am}. This option is deprecated and will be
2439
removed in a future release.
2440
2441
@item -v
2442
@itemx --verbose
2443
@opindex -v
2444
@opindex --verbose
2445
Cause Automake to print information about which files are being read or
2446
created.
2447
2448
@item --version
2449
@opindex --version
2450
Print the version number of Automake and exit.
2451
2452
@item -W CATEGORY
2453
@item --warnings=@var{category}
2454
@opindex -W
2455
@opindex --warnings
2456
Output warnings falling in @var{category}. @var{category} can be
2457
one of:
2458
@table @code
2459
@item gnu
2460
warnings related to the GNU Coding Standards
2461
(@pxref{Top, , , standards, The GNU Coding Standards}).
2462
@item obsolete
2463
obsolete features or constructions
2464
@item override
2465
user redefinitions of Automake rules or variables
2466
@item portability
2467
portability issues (e.g., use of @command{make} features that are
2468
known to be not portable)
2469
@item syntax
2470
weird syntax, unused variables, typos
2471
@item unsupported
2472
unsupported or incomplete features
2473
@item all
2474
all the warnings
2475
@item none
2476
turn off all the warnings
2477
@item error
2478
treat warnings as errors
2479
@end table
2480
2481
A category can be turned off by prefixing its name with @samp{no-}. For
2482
instance, @option{-Wno-syntax} will hide the warnings about unused
2483
variables.
2484
2485
The categories output by default are @samp{syntax} and
2486
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2487
are enabled in @option{--gnu} and @option{--gnits} strictness.
2488
2489
@vindex WARNINGS
2490
The environment variable @env{WARNINGS} can contain a comma separated
2491
list of categories to enable. It will be taken into account before the
2492
command-line switches, this way @option{-Wnone} will also ignore any
2493
warning category enabled by @env{WARNINGS}. This variable is also used
2494
by other tools like @command{autoconf}; unknown categories are ignored
2495
for this reason.
2496
2497
@end table
2498
2499
2500
@node configure
2501
@chapter Scanning @file{configure.ac}
2502
2503
@cindex @file{configure.ac}, scanning
2504
@cindex Scanning @file{configure.ac}
2505
2506
Automake scans the package's @file{configure.ac} to determine certain
2507
information about the package. Some @command{autoconf} macros are required
2508
and some variables must be defined in @file{configure.ac}. Automake
2509
will also use information from @file{configure.ac} to further tailor its
2510
output.
2511
2512
Automake also supplies some Autoconf macros to make the maintenance
2513
easier. These macros can automatically be put into your
2514
@file{aclocal.m4} using the @command{aclocal} program.
2515
2516
@menu
2517
* Requirements:: Configuration requirements
2518
* Optional:: Other things Automake recognizes
2519
* Invoking aclocal:: Auto-generating aclocal.m4
2520
* Macros:: Autoconf macros supplied with Automake
2521
@end menu
2522
2523
2524
@node Requirements
2525
@section Configuration requirements
2526
2527
@cindex Automake requirements
2528
@cindex Requirements of Automake
2529
2530
@acindex AM_INIT_AUTOMAKE
2531
The one real requirement of Automake is that your @file{configure.ac}
2532
call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2533
required for proper Automake operation (@pxref{Macros}).
2534
2535
Here are the other macros that Automake requires but which are not run
2536
by @code{AM_INIT_AUTOMAKE}:
2537
2538
@table @code
2539
@item AC_CONFIG_FILES
2540
@itemx AC_OUTPUT
2541
@acindex AC_CONFIG_FILES
2542
@acindex AC_OUTPUT
2543
These two macros are usually invoked as follows near the end of
2544
@file{configure.ac}.
2545
2546
@example
2547
@dots{}
2548
AC_CONFIG_FILES([
2549
Makefile
2550
doc/Makefile
2551
src/Makefile
2552
src/lib/Makefile
2553
@dots{}
2554
])
2555
AC_OUTPUT
2556
@end example
2557
2558
Automake uses these to determine which files to create (@pxref{Output, ,
2559
Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2560
is considered to be an Automake generated @file{Makefile} if there
2561
exists a file with the same name and the @file{.am} extension appended.
2562
Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2563
generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2564
2565
When using @code{AC_CONFIG_FILES} with multiple input files, as in
2566
2567
@example
2568
AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2569
@end example
2570
2571
@noindent
2572
@command{automake} will generate the first @file{.in} input file for
2573
which a @file{.am} file exists. If no such file exists the output
2574
file is not considered to be Automake generated.
2575
2576
Files created by @code{AC_CONFIG_FILES}, be they Automake
2577
@file{Makefile}s or not, are all removed by @samp{make distclean}.
2578
Their inputs are automatically distributed, except for inputs that
2579
turn out the be outputs of prior @code{AC_CONFIG_FILES} commands.
2580
Finally, rebuild rules are generated in the Automake @file{Makefile}
2581
existing in the subdirectory of the output file, if there is one, or
2582
in the top-level @file{Makefile} otherwise.
2583
2584
The above machinery (cleaning, distributing, and rebuilding) works
2585
fine if the @code{AC_CONFIG_FILES} specifications contain only
2586
literals. If part of the specification uses shell variables,
2587
@command{automake} will not be able to fulfill this setup, and you will
2588
have to complete the missing bits by hand. For instance, on
2589
2590
@example
2591
file=input
2592
@dots{}
2593
AC_CONFIG_FILES([output:$file],, [file=$file])
2594
@end example
2595
2596
@noindent
2597
@command{automake} will output rules to clean @file{output}, and
2598
rebuild it. However the rebuild rule will not depend on @file{input},
2599
and this file will not be distributed either. (You must add
2600
@samp{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
2601
source file.)
2602
2603
Similarly
2604
2605
@example
2606
file=output
2607
file2=out:in
2608
@dots{}
2609
AC_CONFIG_FILES([$file:input],, [file=$file])
2610
AC_CONFIG_FILES([$file2],, [file2=$file2])
2611
@end example
2612
2613
@noindent
2614
will only cause @file{input} to be distributed. No file will be
2615
cleaned automatically (add @samp{DISTCLEANFILES = output out}
2616
yourself), and no rebuild rule will be output.
2617
2618
Obviously @command{automake} cannot guess what value @samp{$file} is
2619
going to hold later when @file{configure} is run, and it cannot use
2620
the shell variable @samp{$file} in a @file{Makefile}. However, if you
2621
make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2622
that is compatible with @command{make}'s syntax) and furthermore use
2623
@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2624
@file{Makefile}, then @command{automake} will be able to use
2625
@samp{$@{file@}} to generate all these rules. For instance, here is
2626
how the Automake package itself generates versioned scripts for its
2627
test suite:
2628
2629
@example
2630
AC_SUBST([APIVERSION], @dots{})
2631
@dots{}
2632
AC_CONFIG_FILES(
2633
[tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2634
[chmod +x tests/aclocal-$@{APIVERSION@}],
2635
[APIVERSION=$APIVERSION])
2636
AC_CONFIG_FILES(
2637
[tests/automake-$@{APIVERSION@}:tests/automake.in],
2638
[chmod +x tests/automake-$@{APIVERSION@}])
2639
@end example
2640
2641
@noindent
2642
Here cleaning, distributing, and rebuilding are done automatically,
2643
because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2644
2645
Note that you should not use shell variables to declare
2646
@file{Makefile} files for which @command{automake} must create
2647
@file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2648
@command{automake} needs to know the file name when it runs in order
2649
to check whether @file{Makefile.am} exists. (In the very hairy case
2650
that your setup requires such use of variables, you will have to tell
2651
Automake which @file{Makefile.in}s to generate on the command-line.)
2652
2653
To summarize:
2654
@itemize @bullet
2655
@item
2656
Use literals for @file{Makefile}s, and for other files whenever possible.
2657
@item
2658
Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2659
for files that @command{automake} should ignore.
2660
@item
2661
Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2662
that @command{automake} should not ignore.
2663
@end itemize
2664
2665
@end table
2666
2667
2668
@node Optional
2669
@section Other things Automake recognizes
2670
2671
@cindex Macros Automake recognizes
2672
@cindex Recognized macros by Automake
2673
2674
Every time Automake is run it calls Autoconf to trace
2675
@file{configure.ac}. This way it can recognize the use of certain
2676
macros and tailor the generated @file{Makefile.in} appropriately.
2677
Currently recognized macros and their effects are:
2678
2679
@ftable @code
2680
@item AC_CANONICAL_BUILD
2681
@itemx AC_CANONICAL_HOST
2682
@itemx AC_CANONICAL_TARGET
2683
@vindex build_triplet
2684
@vindex host_triplet
2685
@vindex target_triplet
2686
Automake will ensure that @file{config.guess} and @file{config.sub}
2687
exist. Also, the @file{Makefile} variables @code{build_triplet},
2688
@code{host_triplet} and @code{target_triplet} are introduced. See
2689
@ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2690
The Autoconf Manual}.
2691
2692
@item AC_CONFIG_AUX_DIR
2693
Automake will look for various helper scripts, such as
2694
@file{install-sh}, in the directory named in this macro invocation.
2695
@c This list is accurate relative to version 1.8
2696
(The full list of scripts is: @file{config.guess}, @file{config.sub},
2697
@file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh},
2698
@file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs},
2699
@file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
2700
scripts are always searched for; some scripts will only be sought if the
2701
generated @file{Makefile.in} requires them.
2702
2703
If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2704
their standard locations. For @file{mdate-sh},
2705
@file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2706
source directory corresponding to the current @file{Makefile.am}. For
2707
the rest, the standard location is the first one of @file{.}, @file{..},
2708
or @file{../..} (relative to the top source directory) that provides any
2709
one of the helper scripts. @xref{Input, , Finding `configure' Input,
2710
autoconf, The Autoconf Manual}.
2711
2712
Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2713
distributed, even if there is no @file{Makefile.am} in this directory.
2714
2715
@item AC_CONFIG_LIBOBJ_DIR
2716
Automake will require the sources file declared with
2717
@code{AC_LIBSOURCE} (see below) in the directory specified by this
2718
macro.
2719
2720
@item AC_CONFIG_HEADERS
2721
Automake will generate rules to rebuild these headers. Older versions
2722
of Automake required the use of @code{AM_CONFIG_HEADER}
2723
(@pxref{Macros}); this is no longer the case today.
2724
2725
As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2726
specification using shell variables will be ignored as far as
2727
cleaning, distributing, and rebuilding is concerned.
2728
2729
@item AC_CONFIG_LINKS
2730
Automake will generate rules to remove @file{configure} generated
2731
links on @samp{make distclean} and to distribute named source files as
2732
part of @samp{make dist}.
2733
2734
As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2735
specification using shell variables will be ignored as far as cleaning
2736
and distributing is concerned. (There is no rebuild rules for links.)
2737
2738
@item AC_LIBOBJ
2739
@itemx AC_LIBSOURCE
2740
@itemx AC_LIBSOURCES
2741
@vindex LIBOBJS
2742
Automake will automatically distribute any file listed in
2743
@code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2744
2745
Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2746
an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2747
@file{file.c} will be distributed automatically by Automake. This
2748
encompasses many macros like @code{AC_FUNC_ALLOCA},
2749
@code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2750
2751
By the way, direct assignments to @code{LIBOBJS} are no longer
2752
supported. You should always use @code{AC_LIBOBJ} for this purpose.
2753
@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2754
autoconf, The Autoconf Manual}.
2755
2756
@item AC_PROG_RANLIB
2757
This is required if any libraries are built in the package.
2758
@xref{Particular Programs, , Particular Program Checks, autoconf, The
2759
Autoconf Manual}.
2760
2761
@item AC_PROG_CXX
2762
This is required if any C++ source is included. @xref{Particular
2763
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2764
2765
@item AC_PROG_OBJC
2766
This is required if any Objective C source is included. @xref{Particular
2767
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2768
2769
@item AC_PROG_F77
2770
This is required if any Fortran 77 source is included. This macro is
2771
distributed with Autoconf version 2.13 and later. @xref{Particular
2772
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2773
2774
@item AC_F77_LIBRARY_LDFLAGS
2775
This is required for programs and shared libraries that are a mixture of
2776
languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
2777
C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
2778
2779
@item AC_PROG_FC
2780
This is required if any Fortran 90/95 source is included. This macro is
2781
distributed with Autoconf version 2.58 and later. @xref{Particular
2782
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2783
2784
@item AC_PROG_LIBTOOL
2785
Automake will turn on processing for @command{libtool} (@pxref{Top, ,
2786
Introduction, libtool, The Libtool Manual}).
2787
2788
@item AC_PROG_YACC
2789
@vindex YACC
2790
If a Yacc source file is seen, then you must either use this macro or
2791
define the variable @code{YACC} in @file{configure.ac}. The former is
2792
preferred (@pxref{Particular Programs, , Particular Program Checks,
2793
autoconf, The Autoconf Manual}).
2794
2795
@item AC_PROG_LEX
2796
If a Lex source file is seen, then this macro must be used.
2797
@xref{Particular Programs, , Particular Program Checks, autoconf, The
2798
Autoconf Manual}.
2799
2800
@item AC_REQUIRE_AUX_FILE
2801
@command{automake} will ensure each file for which this macro is
2802
called exists in the aux directory, and will complain otherwise. It
2803
will also automatically distribute the file. This macro should be
2804
used by third-party Autoconf macros that requires some supporting
2805
files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
2806
above. @xref{Input, , Finding @command{configure} Input, autoconf,
2807
The Autoconf Manual}.
2808
2809
@item AC_SUBST
2810
The first argument is automatically defined as a variable in each
2811
generated @file{Makefile.in}. @xref{Setting Output Variables, , Setting
2812
Output Variables, autoconf, The Autoconf Manual}.
2813
2814
If the Autoconf manual says that a macro calls @code{AC_SUBST} for
2815
@var{var}, or defines the output variable @var{var} then @var{var} will
2816
be defined in each @file{Makefile.in} generated by Automake.
2817
E.g.@: @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
2818
you can use these variables in any @file{Makefile.am} if
2819
@code{AC_PATH_XTRA} is called.
2820
2821
@item AM_C_PROTOTYPES
2822
This is required when using the obsolete de-ANSI-fication feature; see
2823
@ref{ANSI}.
2824
2825
@item AM_GNU_GETTEXT
2826
This macro is required for packages that use GNU gettext
2827
(@pxref{gettext}). It is distributed with gettext. If Automake sees
2828
this macro it ensures that the package meets some of gettext's
2829
requirements.
2830
2831
@item AM_GNU_GETTEXT_INTL_SUBDIR
2832
This macro specifies that the @file{intl/} subdirectory is to be built,
2833
even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
2834
of @samp{external}.
2835
2836
@item AM_MAINTAINER_MODE
2837
@opindex --enable-maintainer-mode
2838
This macro adds a @option{--enable-maintainer-mode} option to
2839
@command{configure}. If this is used, @command{automake} will cause
2840
``maintainer-only'' rules to be turned off by default in the
2841
generated @file{Makefile.in}s. This macro defines the
2842
@code{MAINTAINER_MODE} conditional, which you can use in your own
2843
@file{Makefile.am}. @xref{maintainer-mode}.
2844
2845
@item m4_include
2846
Files included by @file{configure.ac} using this macro will be
2847
detected by Automake and automatically distributed. They will also
2848
appear as dependencies in @file{Makefile} rules.
2849
2850
@code{m4_include} is seldom used by @file{configure.ac} authors, but
2851
can appear in @file{aclocal.m4} when @command{aclocal} detects that
2852
some required macros come from files local to your package (as opposed
2853
to macros installed in a system-wide directory, @pxref{Invoking
2854
aclocal}).
2855
2856
@end ftable
2857
2858
2859
@node Invoking aclocal
2860
@section Auto-generating aclocal.m4
2861
2862
@cindex Invoking @command{aclocal}
2863
@cindex @command{aclocal}, Invoking
2864
2865
Automake includes a number of Autoconf macros that can be used in
2866
your package (@pxref{Macros}); some of them are actually required by
2867
Automake in certain situations. These macros must be defined in your
2868
@file{aclocal.m4}; otherwise they will not be seen by
2869
@command{autoconf}.
2870
2871
The @command{aclocal} program will automatically generate
2872
@file{aclocal.m4} files based on the contents of @file{configure.ac}.
2873
This provides a convenient way to get Automake-provided macros,
2874
without having to search around. The @command{aclocal} mechanism
2875
allows other packages to supply their own macros (@pxref{Extending
2876
aclocal}). You can also use it to maintain your own set of custom
2877
macros (@pxref{Local Macros}).
2878
2879
At startup, @command{aclocal} scans all the @file{.m4} files it can
2880
find, looking for macro definitions (@pxref{Macro search path}). Then
2881
it scans @file{configure.ac}. Any mention of one of the macros found
2882
in the first step causes that macro, and any macros it in turn
2883
requires, to be put into @file{aclocal.m4}.
2884
2885
@emph{Putting} the file that contains the macro definition into
2886
@file{aclocal.m4} is usually done by copying the entire text of this
2887
file, including unused macro definitions as well as both @samp{#} and
2888
@samp{dnl} comments. If you want to make a comment that will be
2889
completely ignored by @command{aclocal}, use @samp{##} as the comment
2890
leader.
2891
2892
When a file selected by @command{aclocal} is located in a subdirectory
2893
specified as a relative search path with @command{aclocal}'s @option{-I}
2894
argument, @command{aclocal} assumes the file belongs to the package
2895
and uses @code{m4_include} instead of copying it into
2896
@file{aclocal.m4}. This makes the package smaller, eases dependency
2897
tracking, and cause the file to be distributed automatically.
2898
(@xref{Local Macros}, for an example.) Any macro that is found in a
2899
system-wide directory, or via an absolute search path will be copied.
2900
So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
2901
some relative directory need to be considered outside the package.
2902
2903
The contents of @file{acinclude.m4}, if this file exists, are also
2904
automatically included in @file{aclocal.m4}. We recommend against
2905
using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
2906
2907
@vindex AUTOM4TE
2908
@cindex autom4te
2909
While computing @file{aclocal.m4}, @command{aclocal} runs
2910
@command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
2911
autoconf, The Autoconf Manual}) in order to trace the macros that are
2912
really used, and omit from @file{aclocal.m4} all macros that are
2913
mentioned but otherwise unexpanded (this can happen when a macro is
2914
called conditionally). @command{autom4te} is expected to be in the
2915
@env{PATH}, just as @command{autoconf}. Its location can be
2916
overridden using the @env{AUTOM4TE} environment variable.
2917
2918
@menu
2919
* aclocal options:: Options supported by aclocal
2920
* Macro search path:: How aclocal finds .m4 files
2921
* Extending aclocal:: Writing your own aclocal macros
2922
* Local Macros:: Organizing local macros
2923
* Serials:: Serial lines in Autoconf macros
2924
* Future of aclocal:: aclocal's scheduled death
2925
@end menu
2926
2927
@node aclocal options
2928
@subsection aclocal options
2929
2930
@cindex @command{aclocal}, Options
2931
@cindex Options, @command{aclocal}
2932
2933
@command{aclocal} accepts the following options:
2934
2935
@table @code
2936
@item --acdir=@var{dir}
2937
@opindex --acdir
2938
Look for the macro files in @var{dir} instead of the installation
2939
directory. This is typically used for debugging.
2940
2941
@item --diff[=@var{command}]
2942
@opindex --diff
2943
Run @var{command} on M4 file that would be installed or overwritten
2944
by @option{--install}. The default @var{command} is @samp{diff -u}.
2945
This option implies @option{--install} and @option{--dry-run}.
2946
2947
@item --dry-run
2948
@opindex --dry-run
2949
Do not actually overwrite (or create) @file{aclocal.m4} and M4
2950
files installed by @option{--install}.
2951
2952
@item --help
2953
@opindex --help
2954
Print a summary of the command line options and exit.
2955
2956
@item -I @var{dir}
2957
@opindex -I
2958
Add the directory @var{dir} to the list of directories searched for
2959
@file{.m4} files.
2960
2961
@item --install
2962
@opindex --install
2963
Install system-wide third-party macros into the first directory
2964
specified with @samp{-I @var{dir}} instead of copying them in the
2965
output file.
2966
2967
@cindex serial number and @option{--install}
2968
When this option is used, and only when this option is used,
2969
@command{aclocal} will also honor @samp{#serial @var{NUMBER}} lines
2970
that appear in macros: an M4 file is ignored if there exists another
2971
M4 file with the same basename and a greater serial number in the
2972
search path (@pxref{Serials}).
2973
2974
@item --force
2975
@opindex --force
2976
Always overwrite the output file. The default is to overwrite the output
2977
file only when really needed, i.e., when its contents changes or if one
2978
of its dependencies is younger.
2979
2980
This option forces the update of @file{aclocal.m4} (or the file
2981
specified with @file{--output} below) and only this file, it has
2982
absolutely no influence on files that may need to be installed by
2983
@option{--install}.
2984
2985
@item --output=@var{file}
2986
@opindex --output
2987
Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
2988
2989
@item --print-ac-dir
2990
@opindex --print-ac-dir
2991
Prints the name of the directory that @command{aclocal} will search to
2992
find third-party @file{.m4} files. When this option is given, normal
2993
processing is suppressed. This option can be used by a package to
2994
determine where to install a macro file.
2995
2996
@item --verbose
2997
@opindex --verbose
2998
Print the names of the files it examines.
2999
3000
@item --version
3001
@opindex --version
3002
Print the version number of Automake and exit.
3003
3004
@item -W CATEGORY
3005
@item --warnings=@var{category}
3006
@opindex -W
3007
@opindex --warnings
3008
Output warnings falling in @var{category}. @var{category} can be
3009
one of:
3010
@table @code
3011
@item syntax
3012
dubious syntactic constructs, underquoted macros, unused macros, etc.
3013
@item unsupported
3014
unknown macros
3015
@item all
3016
all the warnings, this is the default
3017
@item none
3018
turn off all the warnings
3019
@item error
3020
treat warnings as errors
3021
@end table
3022
3023
All warnings are output by default.
3024
3025
@vindex WARNINGS
3026
The environment variable @env{WARNINGS} is honored in the same
3027
way as it is for @command{automake} (@pxref{Invoking Automake}).
3028
3029
@end table
3030
3031
@node Macro search path
3032
@subsection Macro search path
3033
3034
@cindex Macro search path
3035
@cindex @command{aclocal} search path
3036
3037
By default, @command{aclocal} searches for @file{.m4} files in the following
3038
directories, in this order:
3039
3040
@table @code
3041
@item @var{acdir-APIVERSION}
3042
This is where the @file{.m4} macros distributed with automake itself
3043
are stored. @var{APIVERSION} depends on the automake release used;
3044
for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
3045
3046
@item @var{acdir}
3047
This directory is intended for third party @file{.m4} files, and is
3048
configured when @command{automake} itself is built. This is
3049
@file{@@datadir@@/aclocal/}, which typically
3050
expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3051
value of @var{acdir}, use the @option{--print-ac-dir} option
3052
(@pxref{aclocal options}).
3053
@end table
3054
3055
As an example, suppose that @command{automake-1.6.2} was configured with
3056
@option{--prefix=@-/usr/local}. Then, the search path would be:
3057
3058
@enumerate
3059
@item @file{/usr/local/share/aclocal-1.6/}
3060
@item @file{/usr/local/share/aclocal/}
3061
@end enumerate
3062
3063
As explained in (@pxref{aclocal options}), there are several options that
3064
can be used to change or extend this search path.
3065
3066
@subsubsection Modifying the macro search path: @option{--acdir}
3067
3068
The most erroneous option to modify the search path is
3069
@option{--acdir=@var{dir}}, which changes default directory and
3070
drops the @var{APIVERSION} directory. For example, if one specifies
3071
@samp{--acdir=/opt/private/}, then the search path becomes:
3072
3073
@enumerate
3074
@item @file{/opt/private/}
3075
@end enumerate
3076
3077
This option, @option{--acdir}, is intended for use by the internal
3078
automake test suite only; it is not ordinarily needed by end-users.
3079
3080
@subsubsection Modifying the macro search path: @samp{-I @var{dir}}
3081
3082
Any extra directories specified using @option{-I} options
3083
(@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
3084
@samp{aclocal -I /foo -I /bar} results in the following search path:
3085
3086
@enumerate
3087
@item @file{/foo}
3088
@item @file{/bar}
3089
@item @var{acdir}-@var{APIVERSION}
3090
@item @var{acdir}
3091
@end enumerate
3092
3093
@subsubsection Modifying the macro search path: @file{dirlist}
3094
@cindex @file{dirlist}
3095
3096
There is a third mechanism for customizing the search path. If a
3097
@file{dirlist} file exists in @var{acdir}, then that file is assumed to
3098
contain a list of directory patterns, one per line. @command{aclocal}
3099
expands these patterns to directory names, and adds them to the search
3100
list @emph{after} all other directories. @file{dirlist} entries may
3101
use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3102
3103
For example, suppose
3104
@file{@var{acdir}/dirlist} contains the following:
3105
3106
@example
3107
/test1
3108
/test2
3109
/test3*
3110
@end example
3111
3112
@noindent
3113
and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3114
Then, the search path would be
3115
3116
@c @code looks better than @file here
3117
@enumerate
3118
@item @code{/foo}
3119
@item @code{/bar}
3120
@item @var{acdir}-@var{APIVERSION}
3121
@item @var{acdir}
3122
@item @code{/test1}
3123
@item @code{/test2}
3124
@end enumerate
3125
3126
@noindent
3127
and all directories with path names starting with @code{/test3}.
3128
3129
If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
3130
will search for the @file{dirlist} file in @var{dir}. In the
3131
@samp{--acdir=/opt/private/} example above, @command{aclocal} would look
3132
for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
3133
option is intended for use by the internal automake test suite only;
3134
@option{--acdir} is not ordinarily needed by end-users.
3135
3136
@file{dirlist} is useful in the following situation: suppose that
3137
@command{automake} version @code{1.6.2} is installed with
3138
@samp{--prefix=/usr} by the system vendor. Thus, the default search
3139
directories are
3140
3141
@c @code looks better than @file here
3142
@enumerate
3143
@item @code{/usr/share/aclocal-1.6/}
3144
@item @code{/usr/share/aclocal/}
3145
@end enumerate
3146
3147
However, suppose further that many packages have been manually
3148
installed on the system, with $prefix=/usr/local, as is typical. In
3149
that case, many of these ``extra'' @file{.m4} files are in
3150
@file{/usr/local/share/aclocal}. The only way to force
3151
@file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3152
always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3153
inconvenient. With @file{dirlist}, one may create a file
3154
@file{/usr/share/aclocal/dirlist} containing only the single line
3155
3156
@example
3157
/usr/local/share/aclocal
3158
@end example
3159
3160
Now, the ``default'' search path on the affected system is
3161
3162
@c @code looks better than @file here
3163
@enumerate
3164
@item @code{/usr/share/aclocal-1.6/}
3165
@item @code{/usr/share/aclocal/}
3166
@item @code{/usr/local/share/aclocal/}
3167
@end enumerate
3168
3169
without the need for @option{-I} options; @option{-I} options can be reserved
3170
for project-specific needs (@file{my-source-dir/m4/}), rather than
3171
using it to work around local system-dependent tool installation
3172
directories.
3173
3174
Similarly, @file{dirlist} can be handy if you have installed a local
3175
copy Automake on your account and want @command{aclocal} to look for
3176
macros installed at other places on the system.
3177
3178
3179
@node Extending aclocal
3180
@subsection Writing your own aclocal macros
3181
3182
@cindex @command{aclocal}, extending
3183
@cindex Extending @command{aclocal}
3184
3185
The @command{aclocal} program doesn't have any built-in knowledge of any
3186
macros, so it is easy to extend it with your own macros.
3187
3188
This can be used by libraries that want to supply their own Autoconf
3189
macros for use by other programs. For instance, the @command{gettext}
3190
library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3191
any package using @command{gettext}. When the library is installed, it
3192
installs this macro so that @command{aclocal} will find it.
3193
3194
A macro file's name should end in @file{.m4}. Such files should be
3195
installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3196
3197
@example
3198
aclocaldir = $(datadir)/aclocal
3199
aclocal_DATA = mymacro.m4 myothermacro.m4
3200
@end example
3201
3202
@noindent
3203
Please do use @file{$(datadir)/aclocal}, and not something based on
3204
the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
3205
Paths}, for arguments.
3206
3207
A file of macros should be a series of properly quoted
3208
@code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3209
Autoconf Manual}). The @command{aclocal} programs also understands
3210
@code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3211
Autoconf Manual}), so it is safe to put each macro in a separate file.
3212
Each file should have no side effects but macro definitions.
3213
Especially, any call to @code{AC_PREREQ} should be done inside the
3214
defined macro, not at the beginning of the file.
3215
3216
@cindex underquoted @code{AC_DEFUN}
3217
@acindex AC_DEFUN
3218
@acindex AC_PREREQ
3219
3220
Starting with Automake 1.8, @command{aclocal} will warn about all
3221
underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3222
lot of people, because @command{aclocal} was not so strict in the past
3223
and many third party macros are underquoted; and we have to apologize
3224
for this temporary inconvenience. The reason we have to be stricter
3225
is that a future implementation of @command{aclocal} (@pxref{Future of
3226
aclocal}) will have to temporarily include all these third party
3227
@file{.m4} files, maybe several times, including even files that are
3228
not actually needed. Doing so should alleviate many problems of the
3229
current implementation, however it requires a stricter style from the
3230
macro authors. Hopefully it is easy to revise the existing macros.
3231
For instance,
3232
@example
3233
# bad style
3234
AC_PREREQ(2.57)
3235
AC_DEFUN(AX_FOOBAR,
3236
[AC_REQUIRE([AX_SOMETHING])dnl
3237
AX_FOO
3238
AX_BAR
3239
])
3240
@end example
3241
@noindent
3242
should be rewritten as
3243
@example
3244
AC_DEFUN([AX_FOOBAR],
3245
[AC_PREREQ([2.57])dnl
3246
AC_REQUIRE([AX_SOMETHING])dnl
3247
AX_FOO
3248
AX_BAR
3249
])
3250
@end example
3251
3252
Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3253
Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3254
used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3255
allows the macro to be redefined or included twice (otherwise this
3256
first argument would be expanded during the second definition). For
3257
consistency we like to quote even arguments such as @code{2.57} that
3258
do not require it.
3259
3260
If you have been directed here by the @command{aclocal} diagnostic but
3261
are not the maintainer of the implicated macro, you will want to
3262
contact the maintainer of that macro. Please make sure you have the
3263
last version of the macro and that the problem already hasn't been
3264
reported before doing so: people tend to work faster when they aren't
3265
flooded by mails.
3266
3267
Another situation where @command{aclocal} is commonly used is to
3268
manage macros that are used locally by the package, @ref{Local
3269
Macros}.
3270
3271
@node Local Macros
3272
@subsection Handling Local Macros
3273
3274
Feature tests offered by Autoconf do not cover all needs. People
3275
often have to supplement existing tests with their own macros, or
3276
with third-party macros.
3277
3278
There are two ways to organize custom macros in a package.
3279
3280
The first possibility (the historical practice) is to list all your
3281
macros in @file{acinclude.m4}. This file will be included in
3282
@file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3283
henceforth be visible to @command{autoconf}. However if it contains
3284
numerous macros, it will rapidly become difficult to maintain, and it
3285
will be almost impossible to share macros between packages.
3286
3287
@vindex ACLOCAL_AMFLAGS
3288
The second possibility, which we do recommend, is to write each macro
3289
in its own file and gather all these files in a directory. This
3290
directory is usually called @file{m4/}. To build @file{aclocal.m4},
3291
one should therefore instruct @command{aclocal} to scan @file{m4/}.
3292
From the command line, this is done with @samp{aclocal -I m4}. The
3293
top-level @file{Makefile.am} should also be updated to define
3294
3295
@example
3296
ACLOCAL_AMFLAGS = -I m4
3297
@end example
3298
3299
@code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3300
when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3301
also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3302
Using @command{autoreconf} to Update @file{configure} Scripts,
3303
autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3304
options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3305
Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3306
and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3307
@command{gettextize} Program, gettext, GNU gettext tools}) to locate
3308
the place where Gettext's macros should be installed. So even if you
3309
do not really care about the rebuild rules, you should define
3310
@code{ACLOCAL_AMFLAGS}.
3311
3312
When @samp{aclocal -I m4} is run, it will build a @file{aclocal.m4}
3313
that @code{m4_include}s any file from @file{m4/} that defines a
3314
required macro. Macros not found locally will still be searched in
3315
system-wide directories, as explained in @ref{Macro search path}.
3316
3317
Custom macros should be distributed for the same reason that
3318
@file{configure.ac} is: so that other people have all the sources of
3319
your package if they want to work on it. Actually, this distribution
3320
happens automatically because all @code{m4_include}d files are
3321
distributed.
3322
3323
However there is no consensus on the distribution of third-party
3324
macros that your package may use. Many libraries install their own
3325
macro in the system-wide @command{aclocal} directory (@pxref{Extending
3326
aclocal}). For instance, Guile ships with a file called
3327
@file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3328
be used to define setup compiler and linker flags appropriate for
3329
using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3330
cause @command{aclocal} to copy @file{guile.m4} into
3331
@file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3332
it will not be distributed. Technically, that means a user who
3333
needs to rebuild @file{aclocal.m4} will have to install Guile first.
3334
This is probably OK, if Guile already is a requirement to build the
3335
package. However, if Guile is only an optional feature, or if your
3336
package might run on architectures where Guile cannot be installed,
3337
this requirement will hinder development. An easy solution is to copy
3338
such third-party macros in your local @file{m4/} directory so they get
3339
distributed.
3340
3341
Since Automake 1.10, @command{aclocal} offers an option to copy these
3342
system-wide third-party macros in your local macro directory, solving
3343
the above problem. Simply use:
3344
3345
@example
3346
ACLOCAL_AMFLAGS = -I m4 --install
3347
@end example
3348
3349
@noindent
3350
With this setup, system-wide macros will be copied to @file{m4/}
3351
the first time you run @command{autoreconf}. Then the locally
3352
installed macros will have precedence over the system-wide installed
3353
macros each time @command{aclocal} is run again.
3354
3355
One reason why you should keep @option{--install} in the flags even
3356
after the first run is that when you later edit @file{configure.ac}
3357
and depend on a new macro, this macro will be installed in your
3358
@file{m4/} automatically. Another one is that serial numbers
3359
(@pxref{Serials}) can be used to update the macros in your source tree
3360
automatically when new system-wide versions are installed. A serial
3361
number should be a single line of the form
3362
3363
@example
3364
#serial @var{NNN}
3365
@end example
3366
3367
@noindent
3368
where @var{NNN} contains only digits and dots. It should appear in
3369
the M4 file before any macro definition. It is a good practice to
3370
maintain a serial number for each macro you distribute, even if you do
3371
not use the @option{--install} option of @command{aclocal}: this allows
3372
other people to use it.
3373
3374
3375
@node Serials
3376
@subsection Serial Numbers
3377
@cindex serial numbers in macros
3378
@cindex macro serial numbers
3379
@cindex @code{#serial} syntax
3380
@cindex @command{aclocal} and serial numbers
3381
3382
Because third-party macros defined in @file{*.m4} files are naturally
3383
shared between multiple projects, some people like to version them.
3384
This makes it easier to tell which of two M4 files is newer. Since at
3385
least 1996, the tradition is to use a @samp{#serial} line for this.
3386
3387
A serial number should be a single line of the form
3388
3389
@example
3390
# serial @var{version}
3391
@end example
3392
3393
@noindent
3394
where @var{version} is a version number containing only digits and
3395
dots. Usually people use a single integer, and they increment it each
3396
time they change the macro (hence the name of ``serial''). Such a
3397
line should appear in the M4 file before any macro definition.
3398
3399
The @samp{#} must be the first character on the line,
3400
and it is OK to have extra words after the version, as in
3401
3402
@example
3403
#serial @var{version} @var{garbage}
3404
@end example
3405
3406
Normally these serial numbers are completely ignored by
3407
@command{aclocal} and @command{autoconf}, like any genuine comment.
3408
However when using @command{aclocal}'s @option{--install} feature, these
3409
serial numbers will modify the way @command{aclocal} selects the
3410
macros to install in the package: if two files with the same basename
3411
exists in your search path, and if at least one of them use a
3412
@samp{#serial} line, @command{aclocal} will ignore the file that has
3413
the older @samp{#serial} line (or the file that has none).
3414
3415
Note that a serial number applies to a whole M4 file, not to any macro
3416
it contains. A file can contains multiple macros, but only one
3417
serial.
3418
3419
Here is a use case that illustrate the use of @option{--install} and
3420
its interaction with serial numbers. Let's assume we maintain a
3421
package called MyPackage, the @file{configure.ac} of which requires a
3422
third-party macro @code{AX_THIRD_PARTY} defined in
3423
@file{/usr/share/aclocal/thirdparty.m4} as follows:
3424
3425
@example
3426
# serial 1
3427
AC_DEFUN([AX_THIRD_PARTY], [...])
3428
@end example
3429
3430
MyPackage uses an @file{m4/} directory to store local macros as
3431
explained in @ref{Local Macros}, and has
3432
3433
@example
3434
ACLOCAL_AMFLAGS = -I m4 --install
3435
@end example
3436
3437
@noindent
3438
in its top-level @file{Makefile.am}.
3439
3440
Initially the @file{m4/} directory is empty. The first time we run
3441
@command{autoreconf}, it will fetch the options to pass to
3442
@command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3443
--install}. @command{aclocal} will notice that
3444
3445
@itemize @bullet
3446
@item
3447
@file{configure.ac} uses @code{AX_THIRD_PARTY}
3448
@item
3449
No local macros define @code{AX_THIRD_PARTY}
3450
@item
3451
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3452
with serial 1.
3453
@end itemize
3454
3455
@noindent
3456
Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3457
and @command{aclocal} was given the @option{--install} option, it will
3458
copy this file in @file{m4/thirdparty.m4}, and output an
3459
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3460
3461
The next time @samp{aclocal -I m4 --install} is run (either via
3462
@command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3463
rules) something different happens. @command{aclocal} notices that
3464
3465
@itemize @bullet
3466
@item
3467
@file{configure.ac} uses @code{AX_THIRD_PARTY}
3468
@item
3469
@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3470
with serial 1.
3471
@item
3472
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3473
with serial 1.
3474
@end itemize
3475
3476
@noindent
3477
Because both files have the same serial number, @command{aclocal} uses
3478
the first it found in its search path order (@pxref{Macro search
3479
path}). @command{aclocal} therefore ignores
3480
@file{/usr/share/aclocal/thirdparty.m4} and outputs an
3481
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3482
3483
Local directories specified with @option{-I} are always searched before
3484
system-wide directories, so a local file will always be preferred to
3485
the system-wide file in case of equal serial numbers.
3486
3487
Now suppose the system-wide third-party macro is changed. This can
3488
happen if the package installing this macro is updated. Let's suppose
3489
the new macro has serial number 2. The next time @samp{aclocal -I m4
3490
--install} is run the situation is the following:
3491
3492
@itemize @bullet
3493
@item
3494
@file{configure.ac} uses @code{AX_THIRD_PARTY}
3495
@item
3496
@file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3497
with serial 1.
3498
@item
3499
@file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3500
with serial 2.
3501
@end itemize
3502
3503
@noindent
3504
When @command{aclocal} sees a greater serial number, it immediately
3505
forgets anything it knows from files that have the same basename and a
3506
smaller serial number. So after it has found
3507
@file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3508
@command{aclocal} will proceed as if it had never seen
3509
@file{m4/thirdparty.m4}. This brings us back to a situation similar
3510
to that at the beginning of our example, where no local file defined
3511
the macro. @command{aclocal} will install the new version of the
3512
macro in @file{m4/thirdparty.m4}, in this case overriding the old
3513
version. MyPackage just had its macro updated as a side effect of
3514
running @command{aclocal}.
3515
3516
If you are leery of letting @command{aclocal} update your local macro,
3517
you can run @samp{aclocal -I m4 --diff} to review the changes
3518
@samp{aclocal -I m4 --install} would perform on these macros.
3519
3520
Finally, note that the @option{--force} option of @command{aclocal} has
3521
absolutely no effect on the files installed by @option{--install}. For
3522
instance, if you have modified your local macros, do not expect
3523
@option{--install --force} to replace the local macros by their
3524
system-wide versions. If you want to do so, simply erase the local
3525
macros you want to revert, and run @samp{aclocal -I m4 --install}.
3526
3527
3528
@node Future of aclocal
3529
@subsection The Future of @command{aclocal}
3530
@cindex @command{aclocal}'s scheduled death
3531
3532
@command{aclocal} is expected to disappear. This feature really
3533
should not be offered by Automake. Automake should focus on
3534
generating @file{Makefile}s; dealing with M4 macros really is
3535
Autoconf's job. That some people install Automake just to use
3536
@command{aclocal}, but do not use @command{automake} otherwise is an
3537
indication of how that feature is misplaced.
3538
3539
The new implementation will probably be done slightly differently.
3540
For instance, it could enforce the @file{m4/}-style layout discussed in
3541
@ref{Local Macros}.
3542
3543
We have no idea when and how this will happen. This has been
3544
discussed several times in the past, but someone still has to commit
3545
itself to that non-trivial task.
3546
3547
From the user point of view, @command{aclocal}'s removal might turn
3548
out to be painful. There is a simple precaution that you may take to
3549
make that switch more seamless: never call @command{aclocal} yourself.
3550
Keep this guy under the exclusive control of @command{autoreconf} and
3551
Automake's rebuild rules. Hopefully you won't need to worry about
3552
things breaking, when @command{aclocal} disappears, because everything
3553
will have been taken care of. If otherwise you used to call
3554
@command{aclocal} directly yourself or from some script, you will
3555
quickly notice the change.
3556
3557
Many packages come with a script called @file{bootstrap.sh} or
3558
@file{autogen.sh}, that will just call @command{aclocal},
3559
@command{libtoolize}, @command{gettextize} or @command{autopoint},
3560
@command{autoconf}, @command{autoheader}, and @command{automake} in
3561
the right order. Actually this is precisely what @command{autoreconf}
3562
can do for you. If your package has such a @file{bootstrap.sh} or
3563
@file{autogen.sh} script, consider using @command{autoreconf}. That
3564
should simplify its logic a lot (less things to maintain, yum!), it's
3565
even likely you will not need the script anymore, and more to the point
3566
you will not call @command{aclocal} directly anymore.
3567
3568
For the time being, third-party packages should continue to install
3569
public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3570
is replaced by another tool it might make sense to rename the
3571
directory, but supporting @file{/usr/share/aclocal/} for backward
3572
compatibility should be really easy provided all macros are properly
3573
written (@pxref{Extending aclocal}).
3574
3575
3576
3577
@node Macros
3578
@section Autoconf macros supplied with Automake
3579
3580
Automake ships with several Autoconf macros that you can use from your
3581
@file{configure.ac}. When you use one of them it will be included by
3582
@command{aclocal} in @file{aclocal.m4}.
3583
3584
@menu
3585
* Public macros:: Macros that you can use.
3586
* Obsolete macros:: Macros that you should stop using.
3587
* Private macros:: Macros that you should not use.
3588
@end menu
3589
3590
@c consider generating the following subsections automatically from m4 files.
3591
3592
@node Public macros
3593
@subsection Public macros
3594
3595
@table @code
3596
3597
@item AM_ENABLE_MULTILIB
3598
@acindex AM_ENABLE_MULTILIB
3599
This is used when a ``multilib'' library is being built. The first
3600
optional argument is the name of the @file{Makefile} being generated; it
3601
defaults to @samp{Makefile}. The second option argument is used to find
3602
the top source directory; it defaults to the empty string (generally
3603
this should not be used unless you are familiar with the internals).
3604
@xref{Multilibs}.
3605
3606
@item AM_INIT_AUTOMAKE([OPTIONS])
3607
@itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3608
@acindex AM_INIT_AUTOMAKE
3609
Runs many macros required for proper operation of the generated Makefiles.
3610
3611
@vindex AUTOMAKE_OPTIONS
3612
This macro has two forms, the first of which is preferred.
3613
In this form, @code{AM_INIT_AUTOMAKE} is called with a
3614
single argument: a space-separated list of Automake options that should
3615
be applied to every @file{Makefile.am} in the tree. The effect is as if
3616
each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3617
3618
@acindex AC_INIT
3619
The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3620
arguments: the package and the version number. This form is
3621
obsolete because the @var{package} and @var{version} can be obtained
3622
from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3623
form).
3624
3625
If your @file{configure.ac} has:
3626
3627
@example
3628
AC_INIT([src/foo.c])
3629
AM_INIT_AUTOMAKE([mumble], [1.5])
3630
@end example
3631
3632
@noindent
3633
you can modernize it as follows:
3634
3635
@example
3636
AC_INIT([mumble], [1.5])
3637
AC_CONFIG_SRCDIR([src/foo.c])
3638
AM_INIT_AUTOMAKE
3639
@end example
3640
3641
Note that if you're upgrading your @file{configure.ac} from an earlier
3642
version of Automake, it is not always correct to simply move the
3643
package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3644
@code{AC_INIT}, as in the example above. The first argument to
3645
@code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3646
Automake}), not the tarball name (e.g., @samp{automake}) that you used
3647
to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3648
tarball name from the package name, which should work for most but not
3649
all package names. (If it doesn't work for yours, you can use the
3650
four-argument form of @code{AC_INIT} to provide the tarball name
3651
explicitly).
3652
3653
@cindex @code{PACKAGE}, prevent definition
3654
@cindex @code{VERSION}, prevent definition
3655
@opindex no-define
3656
By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3657
@code{VERSION}. This can be avoided by passing the @option{no-define}
3658
option, as in:
3659
@example
3660
AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3661
@end example
3662
or by passing a third non-empty argument to the obsolete form.
3663
3664
@item AM_PATH_LISPDIR
3665
@acindex AM_PATH_LISPDIR
3666
@vindex EMACS
3667
@vindex lispdir
3668
Searches for the program @command{emacs}, and, if found, sets the
3669
output variable @code{lispdir} to the full path to Emacs' site-lisp
3670
directory.
3671
3672
Note that this test assumes the @command{emacs} found to be a version
3673
that supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other
3674
emacsen can cause this test to hang (some, like old versions of
3675
MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3676
exit, which is hardly obvious for a non-emacs user). In most cases,
3677
however, you should be able to use @kbd{C-c} to kill the test. In
3678
order to avoid problems, you can set @env{EMACS} to ``no'' in the
3679
environment, or use the @option{--with-lispdir} option to
3680
@command{configure} to explicitly set the correct path (if you're sure
3681
you have an @command{emacs} that supports Emacs Lisp.
3682
3683
@item AM_PROG_AS
3684
@acindex AM_PROG_AS
3685
@vindex CCAS
3686
@vindex CCASFLAGS
3687
Use this macro when you have assembly code in your project. This will
3688
choose the assembler for you (by default the C compiler) and set
3689
@code{CCAS}, and will also set @code{CCASFLAGS} if required.
3690
3691
@item AM_PROG_CC_C_O
3692
@acindex AM_PROG_CC_C_O
3693
@acindex AC_PROG_CC_C_O
3694
This is like @code{AC_PROG_CC_C_O}, but it generates its results in
3695
the manner required by automake. You must use this instead of
3696
@code{AC_PROG_CC_C_O} when you need this functionality, that is, when
3697
using per-target flags or subdir-objects with C sources.
3698
3699
@item AM_PROG_LEX
3700
@acindex AM_PROG_LEX
3701
@acindex AC_PROG_LEX
3702
@cindex HP-UX 10, @command{lex} problems
3703
@cindex @command{lex} problems with HP-UX 10
3704
Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
3705
Program Checks, autoconf, The Autoconf Manual}), but uses the
3706
@command{missing} script on systems that do not have @command{lex}.
3707
HP-UX 10 is one such system.
3708
3709
@item AM_PROG_GCJ
3710
@acindex AM_PROG_GCJ
3711
@vindex GCJ
3712
@vindex GCJFLAGS
3713
This macro finds the @command{gcj} program or causes an error. It sets
3714
@code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
3715
GNU Compiler Collection.
3716
3717
@item AM_PROG_UPC([@var{compiler-search-list}])
3718
@acindex AM_PROG_UPC
3719
@vindex UPC
3720
Find a compiler for Unified Parallel C and define the @code{UPC}
3721
variable. The default @var{compiler-search-list} is @samp{upcc upc}.
3722
This macro will abort @command{configure} if no Unified Parallel C
3723
compiler is found.
3724
3725
@item AM_WITH_DMALLOC
3726
@acindex AM_WITH_DMALLOC
3727
@cindex @command{dmalloc}, support for
3728
@vindex WITH_DMALLOC
3729
@opindex --with-dmalloc
3730
Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
3731
the user runs @command{configure} with @option{--with-dmalloc}, then
3732
define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
3733
3734
@item AM_WITH_REGEX
3735
@acindex AM_WITH_REGEX
3736
@vindex WITH_REGEX
3737
@opindex --with-regex
3738
@cindex regex package
3739
@cindex rx package
3740
Adds @option{--with-regex} to the @command{configure} command line. If
3741
specified (the default), then the @samp{regex} regular expression
3742
library is used, @file{regex.o} is put into @code{LIBOBJS}, and
3743
@code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
3744
the @code{rx} regular expression library is used, and @file{rx.o} is put
3745
into @code{LIBOBJS}.
3746
3747
@end table
3748
3749
3750
@node Obsolete macros
3751
@subsection Obsolete macros
3752
@cindex obsolete macros
3753
@cindex autoupdate
3754
3755
Although using some of the following macros was required in past
3756
releases, you should not use any of them in new code. Running
3757
@command{autoupdate} should adjust your @file{configure.ac}
3758
automatically (@pxref{autoupdate Invocation, , Using
3759
@command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
3760
Autoconf Manual}).
3761
3762
@table @code
3763
@item AM_C_PROTOTYPES
3764
@acindex AM_C_PROTOTYPES
3765
@vindex ANSI2KNR
3766
@vindex U
3767
Check to see if function prototypes are understood by the compiler. If
3768
so, define @samp{PROTOTYPES} and set the output variables @code{U} and
3769
@code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
3770
@samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
3771
values to implement the obsolete de-ANSI-fication feature.
3772
3773
@item AM_CONFIG_HEADER
3774
@acindex AM_CONFIG_HEADER
3775
Automake will generate rules to automatically regenerate the config
3776
header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
3777
today (@pxref{Optional}).
3778
3779
@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3780
@acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3781
If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
3782
define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
3783
found in @file{<termios.h>}. This macro is obsolete, you should
3784
use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
3785
3786
@item AM_PROG_MKDIR_P
3787
@acindex AM_PROG_MKDIR_P
3788
@cindex @code{mkdir -p}, macro check
3789
@vindex MKDIR_P
3790
@vindex mkdir_p
3791
3792
From Automake 1.8 to 1.9.6 this macro used to define the output
3793
variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
3794
-d}, or @code{mkinstalldirs}.
3795
3796
Nowadays Autoconf provides a similar functionality with
3797
@code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
3798
Program Checks, autoconf, The Autoconf Manual}), however this defines
3799
the output variable @code{MKDIR_P} instead. Therefore
3800
@code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
3801
@code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
3802
@code{MKDIR_P} for backward compatibility.
3803
3804
If you are using Automake, there is normally no reason to call this
3805
macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
3806
sure that the custom rules in your @file{Makefile}s use
3807
@code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
3808
still work, the latter should be considered obsolete.
3809
3810
If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
3811
instead of @code{AM_PROG_MKDIR_P}.
3812
3813
@item AM_SYS_POSIX_TERMIOS
3814
@acindex AM_SYS_POSIX_TERMIOS
3815
@cindex POSIX termios headers
3816
@cindex termios POSIX headers
3817
Check to see if POSIX termios headers and functions are available on the
3818
system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
3819
@samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
3820
you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
3821
3822
@end table
3823
3824
3825
@node Private macros
3826
@subsection Private macros
3827
3828
The following macros are private macros you should not call directly.
3829
They are called by the other public macros when appropriate. Do not
3830
rely on them, as they might be changed in a future version. Consider
3831
them as implementation details; or better, do not consider them at all:
3832
skip this section!
3833
3834
@ftable @code
3835
@item _AM_DEPENDENCIES
3836
@itemx AM_SET_DEPDIR
3837
@itemx AM_DEP_TRACK
3838
@itemx AM_OUTPUT_DEPENDENCY_COMMANDS
3839
These macros are used to implement Automake's automatic dependency
3840
tracking scheme. They are called automatically by automake when
3841
required, and there should be no need to invoke them manually.
3842
3843
@item AM_MAKE_INCLUDE
3844
This macro is used to discover how the user's @command{make} handles
3845
@code{include} statements. This macro is automatically invoked when
3846
needed; there should be no need to invoke it manually.
3847
3848
@item AM_PROG_INSTALL_STRIP
3849
This is used to find a version of @code{install} that can be used to
3850
strip a program at installation time. This macro is automatically
3851
included when required.
3852
3853
@item AM_SANITY_CHECK
3854
This checks to make sure that a file created in the build directory is
3855
newer than a file in the source directory. This can fail on systems
3856
where the clock is set incorrectly. This macro is automatically run
3857
from @code{AM_INIT_AUTOMAKE}.
3858
3859
@end ftable
3860
3861
3862
@node Directories
3863
@chapter Directories
3864
3865
For simple projects that distributes all files in the same directory
3866
it is enough to have a single @file{Makefile.am} that builds
3867
everything in place.
3868
3869
In larger projects it is common to organize files in different
3870
directories, in a tree. For instance one directory per program, per
3871
library or per module. The traditional approach is to build these
3872
subdirectory recursively: each directory contains its @file{Makefile}
3873
(generated from @file{Makefile.am}), and when @command{make} is run
3874
from the top level directory it enters each subdirectory in turn to
3875
build its contents.
3876
3877
@menu
3878
* Subdirectories:: Building subdirectories recursively
3879
* Conditional Subdirectories:: Conditionally not building directories
3880
* Alternative:: Subdirectories without recursion
3881
* Subpackages:: Nesting packages
3882
@end menu
3883
3884
@node Subdirectories
3885
@section Recursing subdirectories
3886
3887
@cindex @code{SUBDIRS}, explained
3888
3889
In packages with subdirectories, the top level @file{Makefile.am} must
3890
tell Automake which subdirectories are to be built. This is done via
3891
the @code{SUBDIRS} variable.
3892
@vindex SUBDIRS
3893
3894
The @code{SUBDIRS} variable holds a list of subdirectories in which
3895
building of various sorts can occur. The rules for many targets
3896
(e.g., @code{all}) in the generated @file{Makefile} will run commands
3897
both locally and in all specified subdirectories. Note that the
3898
directories listed in @code{SUBDIRS} are not required to contain
3899
@file{Makefile.am}s; only @file{Makefile}s (after configuration).
3900
This allows inclusion of libraries from packages that do not use
3901
Automake (such as @code{gettext}; see also @ref{Third-Party
3902
Makefiles}).
3903
3904
In packages that use subdirectories, the top-level @file{Makefile.am} is
3905
often very short. For instance, here is the @file{Makefile.am} from the
3906
GNU Hello distribution:
3907
3908
@example
3909
EXTRA_DIST = BUGS ChangeLog.O README-alpha
3910
SUBDIRS = doc intl po src tests
3911
@end example
3912
3913
When Automake invokes @command{make} in a subdirectory, it uses the value
3914
of the @code{MAKE} variable. It passes the value of the variable
3915
@code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
3916
@file{Makefile.am} if there are flags you must always pass to
3917
@command{make}.
3918
@vindex MAKE
3919
@vindex AM_MAKEFLAGS
3920
3921
The directories mentioned in @code{SUBDIRS} are usually direct
3922
children of the current directory, each subdirectory containing its
3923
own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
3924
subdirectories. Automake can be used to construct packages of
3925
arbitrary depth this way.
3926
3927
By default, Automake generates @file{Makefiles} that work depth-first
3928
in postfix order: the subdirectories are built before the current
3929
directory. However, it is possible to change this ordering. You can
3930
do this by putting @samp{.} into @code{SUBDIRS}. For instance,
3931
putting @samp{.} first will cause a prefix ordering of
3932
directories.
3933
3934
Using
3935
3936
@example
3937
SUBDIRS = lib src . test
3938
@end example
3939
3940
@noindent
3941
will cause @file{lib/} to be built before @file{src/}, then the
3942
current directory will be built, finally the @file{test/} directory
3943
will be built. It is customary to arrange test directories to be
3944
built after everything else since they are meant to test what has
3945
been constructed.
3946
3947
All @code{clean} rules are run in reverse order of build rules.
3948
3949
@node Conditional Subdirectories
3950
@section Conditional Subdirectories
3951
@cindex Subdirectories, building conditionally
3952
@cindex Conditional subdirectories
3953
@cindex @code{SUBDIRS}, conditional
3954
@cindex Conditional @code{SUBDIRS}
3955
3956
It is possible to define the @code{SUBDIRS} variable conditionally if,
3957
like in the case of GNU Inetutils, you want to only build a subset of
3958
the entire package.
3959
3960
To illustrate how this works, let's assume we have two directories
3961
@file{src/} and @file{opt/}. @file{src/} should always be built, but we
3962
want to decide in @command{configure} whether @file{opt/} will be built
3963
or not. (For this example we will assume that @file{opt/} should be
3964
built when the variable @samp{$want_opt} was set to @samp{yes}.)
3965
3966
Running @command{make} should thus recurse into @file{src/} always, and
3967
then maybe in @file{opt/}.
3968
3969
However @samp{make dist} should always recurse into both @file{src/}
3970
and @file{opt/}. Because @file{opt/} should be distributed even if it
3971
is not needed in the current configuration. This means
3972
@file{opt/Makefile} should be created @emph{unconditionally}.
3973
3974
There are two ways to setup a project like this. You can use Automake
3975
conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
3976
variables (@pxref{Setting Output Variables, , Setting Output
3977
Variables, autoconf, The Autoconf Manual}). Using Automake
3978
conditionals is the preferred solution. Before we illustrate these
3979
two possibilities, let's introduce @code{DIST_SUBDIRS}.
3980
3981
@subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
3982
@cindex @code{DIST_SUBDIRS}, explained
3983
3984
Automake considers two sets of directories, defined by the variables
3985
@code{SUBDIRS} and @code{DIST_SUBDIRS}.
3986
3987
@code{SUBDIRS} contains the subdirectories of the current directory
3988
that must be built (@pxref{Subdirectories}). It must be defined
3989
manually; Automake will never guess a directory is to be built. As we
3990
will see in the next two sections, it is possible to define it
3991
conditionally so that some directory will be omitted from the build.
3992
3993
@code{DIST_SUBDIRS} is used in rules that need to recurse in all
3994
directories, even those that have been conditionally left out of the
3995
build. Recall our example where we may not want to build subdirectory
3996
@file{opt/}, but yet we want to distribute it? This is where
3997
@code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
3998
@code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
3999
4000
Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4001
maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4002
other recursive rules use @code{SUBDIRS}.
4003
4004
If @code{SUBDIRS} is defined conditionally using Automake
4005
conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4006
from the possibles values of @code{SUBDIRS} in all conditions.
4007
4008
If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4009
@code{DIST_SUBDIRS} will not be defined correctly because Automake
4010
does not know the possible values of these variables. In this case
4011
@code{DIST_SUBDIRS} needs to be defined manually.
4012
4013
@subsection Conditional subdirectories with @code{AM_CONDITIONAL}
4014
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4015
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4016
4017
@c The test case for the setup described here is
4018
@c test/subdircond2.test
4019
@c Try to keep it in sync.
4020
4021
@file{configure} should output the @file{Makefile} for each directory
4022
and define a condition into which @file{opt/} should be built.
4023
4024
@example
4025
@dots{}
4026
AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4027
AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4028
@dots{}
4029
@end example
4030
4031
Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4032
as follows.
4033
4034
@example
4035
if COND_OPT
4036
MAYBE_OPT = opt
4037
endif
4038
SUBDIRS = src $(MAYBE_OPT)
4039
@end example
4040
4041
As you can see, running @command{make} will rightly recurse into
4042
@file{src/} and maybe @file{opt/}.
4043
4044
@vindex DIST_SUBDIRS
4045
As you can't see, running @samp{make dist} will recurse into both
4046
@file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4047
@samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4048
@code{DIST_SUBDIRS} variable.
4049
4050
In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4051
automatically because it knows that @code{MAYBE_OPT} can contain
4052
@samp{opt} in some condition.
4053
4054
@subsection Conditional Subdirectories with @code{AC_SUBST}
4055
@cindex @code{SUBDIRS} and @code{AC_SUBST}
4056
@cindex @code{AC_SUBST} and @code{SUBDIRS}
4057
4058
@c The test case for the setup described here is
4059
@c test/subdircond3.test
4060
@c Try to keep it in sync.
4061
4062
Another possibility is to define @code{MAYBE_OPT} from
4063
@file{./configure} using @code{AC_SUBST}:
4064
4065
@example
4066
@dots{}
4067
if test "$want_opt" = yes; then
4068
MAYBE_OPT=opt
4069
else
4070
MAYBE_OPT=
4071
fi
4072
AC_SUBST([MAYBE_OPT])
4073
AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4074
@dots{}
4075
@end example
4076
4077
In this case the top-level @file{Makefile.am} should look as follows.
4078
4079
@example
4080
SUBDIRS = src $(MAYBE_OPT)
4081
DIST_SUBDIRS = src opt
4082
@end example
4083
4084
The drawback is that since Automake cannot guess what the possible
4085
values of @code{MAYBE_OPT} are, it is necessary to define
4086
@code{DIST_SUBDIRS}.
4087
4088
@subsection Non-configured Subdirectories
4089
@cindex Subdirectories, configured conditionally
4090
4091
The semantic of @code{DIST_SUBDIRS} is often misunderstood by some
4092
users that try to @emph{configure and build} subdirectories
4093
conditionally. Here by configuring we mean creating the
4094
@file{Makefile} (it might also involve running a nested
4095
@command{configure} script: this is a costly operation that explains
4096
why people want to do it conditionally, but only the @file{Makefile}
4097
is relevant to the discussion).
4098
4099
The above examples all assume that every @file{Makefile} is created,
4100
even in directories that are not going to be built. The simple reason
4101
is that we want @samp{make dist} to distribute even the directories
4102
that are not being built (e.g., platform-dependent code), hence
4103
@file{make dist} must recurse into the subdirectory, hence this
4104
directory must be configured and appear in @code{DIST_SUBDIRS}.
4105
4106
Building packages that do not configure every subdirectory is a tricky
4107
business, and we do not recommend it to the novice as it is easy to
4108
produce an incomplete tarball by mistake. We will not discuss this
4109
topic in depth here, yet for the adventurous here are a few rules to
4110
remember.
4111
4112
@cartouche
4113
@itemize
4114
@item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4115
4116
It makes little sense to have a directory in @code{SUBDIRS} that
4117
is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4118
which directories listed in the latter should be built.
4119
@item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4120
must be configured.
4121
4122
I.e., the @file{Makefile} must exists or the recursive @command{make}
4123
rules will not be able to process the directory.
4124
@item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4125
4126
So that the cleaning rule remove the generated @file{Makefile}s.
4127
It would be correct to see @code{DIST_SUBDIRS} as a variable that
4128
lists all the directories that have been configured.
4129
@end itemize
4130
@end cartouche
4131
4132
In order to prevent recursion in some non-configured directory you
4133
must therefore ensure that this directory does not appear in
4134
@code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4135
@code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4136
@code{DIST_SUBDIRS} explicitly, it will be default to
4137
@samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4138
= $(SUBDIRS)}.
4139
4140
Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4141
not be distributed unless you make other arrangements for this to
4142
happen (for instance, always running @samp{make dist} in a
4143
configuration where all directories are known to appear in
4144
@code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4145
distribute these directories).
4146
4147
@cindex Subdirectories, not distributed
4148
In few packages, non-configured directories are not even expected to
4149
be distributed. Although these packages do not require the
4150
aforementioned extra arrangements, there is another pitfall. If the
4151
name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4152
@command{automake} will make sure the directory exists. Consequently
4153
@command{automake} cannot be run on such a distribution when one
4154
directory has been omitted. One way to avoid this check is to use the
4155
@code{AC_SUBST} method to declare conditional directories; since
4156
@command{automake} does not know the values of @code{AC_SUBST}
4157
variables it cannot ensure the corresponding directory exist.
4158
4159
@node Alternative
4160
@section An Alternative Approach to Subdirectories
4161
4162
If you've ever read Peter Miller's excellent paper,
4163
@uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
4164
Recursive Make Considered Harmful}, the preceding sections on the use of
4165
subdirectories will probably come as unwelcome advice. For those who
4166
haven't read the paper, Miller's main thesis is that recursive
4167
@command{make} invocations are both slow and error-prone.
4168
4169
Automake provides sufficient cross-directory support @footnote{We
4170
believe. This work is new and there are probably warts.
4171
@xref{Introduction}, for information on reporting bugs.} to enable you
4172
to write a single @file{Makefile.am} for a complex multi-directory
4173
package.
4174
4175
4176
By default an installable file specified in a subdirectory will have its
4177
directory name stripped before installation. For instance, in this
4178
example, the header file will be installed as
4179
@file{$(includedir)/stdio.h}:
4180
4181
@example
4182
include_HEADERS = inc/stdio.h
4183
@end example
4184
4185
@vindex nobase_
4186
@cindex @code{nobase_} prefix
4187
@cindex Path stripping, avoiding
4188
@cindex Avoiding path stripping
4189
4190
However, the @samp{nobase_} prefix can be used to circumvent this path
4191
stripping. In this example, the header file will be installed as
4192
@file{$(includedir)/sys/types.h}:
4193
4194
@example
4195
nobase_include_HEADERS = sys/types.h
4196
@end example
4197
4198
@cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4199
@cindex @code{dist_} and @code{nobase_}
4200
@cindex @code{nodist_} and @code{nobase_}
4201
@vindex dist_
4202
@vindex nodist_
4203
4204
@samp{nobase_} should be specified first when used in conjunction with
4205
either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
4206
4207
@example
4208
nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4209
@end example
4210
4211
Finally, note that a variable using the @samp{nobase_} prefix can
4212
always be replaced by several variables, one for each destination
4213
directory (@pxref{Uniform}). For instance, the last example could be
4214
rewritten as follows:
4215
4216
@example
4217
imagesdir = $(pkgdatadir)/images
4218
soundsdir = $(pkgdatadir)/sounds
4219
dist_images_DATA = images/vortex.pgm
4220
dist_sounds_DATA = sounds/whirl.ogg
4221
@end example
4222
4223
@noindent
4224
This latter syntax makes it possible to change one destination
4225
directory without changing the layout of the source tree.
4226
4227
@node Subpackages
4228
@section Nesting Packages
4229
@cindex Nesting packages
4230
@cindex Subpackages
4231
@acindex AC_CONFIG_SUBDIRS
4232
@acindex AC_CONFIG_AUX_DIR
4233
4234
4235
In the GNU Build System, packages can be nested to arbitrary depth.
4236
This means that a package can embedded other packages with their own
4237
@file{configure}, @file{Makefile}s, etc.
4238
4239
These other packages should just appear as subdirectories of their
4240
parent package. They must be listed in @code{SUBDIRS} like other
4241
ordinary directories. However the subpackage's @file{Makefile}s
4242
should be output by its own @file{configure} script, not by the
4243
parent's @file{configure}. This is achieved using the
4244
@code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4245
AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4246
autoconf, The Autoconf Manual}).
4247
4248
Here is an example package for an @code{arm} program that links with
4249
an @code{hand} library that is a nested package in subdirectory
4250
@file{hand/}.
4251
4252
@code{arm}'s @file{configure.ac}:
4253
4254
@example
4255
AC_INIT([arm], [1.0])
4256
AC_CONFIG_AUX_DIR([.])
4257
AM_INIT_AUTOMAKE
4258
AC_PROG_CC
4259
AC_CONFIG_FILES([Makefile])
4260
# Call hand's ./configure script recursively.
4261
AC_CONFIG_SUBDIRS([hand])
4262
AC_OUTPUT
4263
@end example
4264
4265
@code{arm}'s @file{Makefile.am}:
4266
4267
@example
4268
# Build the library in the hand subdirectory first.
4269
SUBDIRS = hand
4270
4271
# Include hand's header when compiling this directory.
4272
AM_CPPFLAGS = -I$(srcdir)/hand
4273
4274
bin_PROGRAMS = arm
4275
arm_SOURCES = arm.c
4276
# link with the hand library.
4277
arm_LDADD = hand/libhand.a
4278
@end example
4279
4280
Now here is @code{hand}'s @file{hand/configure.ac}:
4281
4282
@example
4283
AC_INIT([hand], [1.2])
4284
AC_CONFIG_AUX_DIR([.])
4285
AM_INIT_AUTOMAKE
4286
AC_PROG_CC
4287
AC_PROG_RANLIB
4288
AC_CONFIG_FILES([Makefile])
4289
AC_OUTPUT
4290
@end example
4291
4292
@noindent
4293
and its @file{hand/Makefile.am}:
4294
4295
@example
4296
lib_LIBRARIES = libhand.a
4297
libhand_a_SOURCES = hand.c
4298
@end example
4299
4300
When @samp{make dist} is run from the top-level directory it will
4301
create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4302
code as well as the @file{hand} subdirectory. This package can be
4303
built and installed like any ordinary package, with the usual
4304
@samp{./configure && make && make install} sequence (the @code{hand}
4305
subpackage will be built and installed by the process).
4306
4307
When @samp{make dist} is run from the hand directory, it will create a
4308
self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4309
to be embedded in another package, it can still be used separately.
4310
4311
The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4312
force Automake and Autoconf to search for auxiliary scripts in the
4313
current directory. For instance, this means that there will be two
4314
copies of @file{install-sh}: one in the top-level of the @code{arm}
4315
package, and another one in the @file{hand/} subdirectory for the
4316
@code{hand} package.
4317
4318
The historical default is to search for these auxiliary scripts in
4319
the parent directory and the grandparent directory. So if the
4320
@samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4321
@file{hand/configure.ac}, that subpackage would share the auxiliary
4322
script of the @code{arm} package. This may looks like a gain in size
4323
(a few kilobytes), but it is actually a loss of modularity as the
4324
@code{hand} subpackage is no longer self-contained (@samp{make dist}
4325
in the subdirectory will not work anymore).
4326
4327
Packages that do not use Automake need more work to be integrated this
4328
way. @xref{Third-Party Makefiles}.
4329
4330
@node Programs
4331
@chapter Building Programs and Libraries
4332
4333
A large part of Automake's functionality is dedicated to making it easy
4334
to build programs and libraries.
4335
4336
@menu
4337
* A Program:: Building a program
4338
* A Library:: Building a library
4339
* A Shared Library:: Building a Libtool library
4340
* Program and Library Variables:: Variables controlling program and
4341
library builds
4342
* Default _SOURCES:: Default source files
4343
* LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4344
* Program variables:: Variables used when building a program
4345
* Yacc and Lex:: Yacc and Lex support
4346
* C++ Support:: Compiling C++ sources
4347
* Objective C Support:: Compiling Objective C sources
4348
* Unified Parallel C Support:: Compiling Unified Parallel C sources
4349
* Assembly Support:: Compiling assembly sources
4350
* Fortran 77 Support:: Compiling Fortran 77 sources
4351
* Fortran 9x Support:: Compiling Fortran 9x sources
4352
* Java Support:: Compiling Java sources
4353
* Support for Other Languages:: Compiling other languages
4354
* ANSI:: Automatic de-ANSI-fication (obsolete)
4355
* Dependencies:: Automatic dependency tracking
4356
* EXEEXT:: Support for executable extensions
4357
@end menu
4358
4359
4360
@node A Program
4361
@section Building a program
4362
4363
In order to build a program, you need to tell Automake which sources
4364
are part of it, and which libraries it should be linked with.
4365
4366
This section also covers conditional compilation of sources or
4367
programs. Most of the comments about these also apply to libraries
4368
(@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4369
4370
@menu
4371
* Program Sources:: Defining program sources
4372
* Linking:: Linking with libraries or extra objects
4373
* Conditional Sources:: Handling conditional sources
4374
* Conditional Programs:: Building program conditionally
4375
@end menu
4376
4377
@node Program Sources
4378
@subsection Defining program sources
4379
4380
@cindex @code{PROGRAMS}, @code{bindir}
4381
@vindex _PROGRAMS
4382
@vindex bin_PROGRAMS
4383
@vindex sbin_PROGRAMS
4384
@vindex libexec_PROGRAMS
4385
@vindex pkglib_PROGRAMS
4386
@vindex noinst_PROGRAMS
4387
@vindex check_PROGRAMS
4388
4389
In a directory containing source that gets built into a program (as
4390
opposed to a library or a script), the @code{PROGRAMS} primary is used.
4391
Programs can be installed in @code{bindir}, @code{sbindir},
4392
@code{libexecdir}, @code{pkglibdir}, or not at all (@code{noinst_}).
4393
They can also be built only for @samp{make check}, in which case the
4394
prefix is @samp{check_}.
4395
4396
For instance:
4397
4398
@example
4399
bin_PROGRAMS = hello
4400
@end example
4401
4402
In this simple case, the resulting @file{Makefile.in} will contain code
4403
to generate a program named @code{hello}.
4404
4405
Associated with each program are several assisting variables that are
4406
named after the program. These variables are all optional, and have
4407
reasonable defaults. Each variable, its use, and default is spelled out
4408
below; we use the ``hello'' example throughout.
4409
4410
The variable @code{hello_SOURCES} is used to specify which source files
4411
get built into an executable:
4412
4413
@example
4414
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4415
@end example
4416
4417
This causes each mentioned @file{.c} file to be compiled into the
4418
corresponding @file{.o}. Then all are linked to produce @file{hello}.
4419
4420
@cindex @code{_SOURCES} primary, defined
4421
@cindex @code{SOURCES} primary, defined
4422
@cindex Primary variable, @code{SOURCES}
4423
@vindex _SOURCES
4424
4425
If @code{hello_SOURCES} is not specified, then it defaults to the single
4426
file @file{hello.c} (@pxref{Default _SOURCES}).
4427
@vindex _SOURCES
4428
@vindex SOURCES
4429
4430
Multiple programs can be built in a single directory. Multiple programs
4431
can share a single source file, which must be listed in each
4432
@code{_SOURCES} definition.
4433
4434
@cindex Header files in @code{_SOURCES}
4435
@cindex @code{_SOURCES} and header files
4436
4437
Header files listed in a @code{_SOURCES} definition will be included in
4438
the distribution but otherwise ignored. In case it isn't obvious, you
4439
should not include the header file generated by @file{configure} in a
4440
@code{_SOURCES} variable; this file should not be distributed. Lex
4441
(@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4442
and Lex}.
4443
4444
4445
@node Linking
4446
@subsection Linking the program
4447
4448
If you need to link against libraries that are not found by
4449
@command{configure}, you can use @code{LDADD} to do so. This variable is
4450
used to specify additional objects or libraries to link with; it is
4451
inappropriate for specifying specific linker flags, you should use
4452
@code{AM_LDFLAGS} for this purpose.
4453
@vindex LDADD
4454
@vindex AM_LDFLAGS
4455
4456
@cindex @code{prog_LDADD}, defined
4457
4458
Sometimes, multiple programs are built in one directory but do not share
4459
the same link-time requirements. In this case, you can use the
4460
@code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4461
program as it appears in some @code{_PROGRAMS} variable, and usually
4462
written in lowercase) to override the global @code{LDADD}. If this
4463
variable exists for a given program, then that program is not linked
4464
using @code{LDADD}.
4465
@vindex maude_LDADD
4466
4467
For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4468
linked against the library @file{libcpio.a}. However, @code{rmt} is
4469
built in the same directory, and has no such link requirement. Also,
4470
@code{mt} and @code{rmt} are only built on certain architectures. Here
4471
is what cpio's @file{src/Makefile.am} looks like (abridged):
4472
4473
@example
4474
bin_PROGRAMS = cpio pax $(MT)
4475
libexec_PROGRAMS = $(RMT)
4476
EXTRA_PROGRAMS = mt rmt
4477
4478
LDADD = ../lib/libcpio.a $(INTLLIBS)
4479
rmt_LDADD =
4480
4481
cpio_SOURCES = @dots{}
4482
pax_SOURCES = @dots{}
4483
mt_SOURCES = @dots{}
4484
rmt_SOURCES = @dots{}
4485
@end example
4486
4487
@cindex @code{_LDFLAGS}, defined
4488
@vindex maude_LDFLAGS
4489
@code{@var{prog}_LDADD} is inappropriate for passing program-specific
4490
linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4491
@option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4492
this purpose.
4493
4494
@cindex @code{_DEPENDENCIES}, defined
4495
@vindex maude_DEPENDENCIES
4496
It is also occasionally useful to have a program depend on some other
4497
target that is not actually part of that program. This can be done
4498
using the @code{@var{prog}_DEPENDENCIES} variable. Each program
4499
depends on the contents of such a variable, but no further
4500
interpretation is done.
4501
4502
Since these dependencies are associated to the link rule used to
4503
create the programs they should normally list files used by the link
4504
command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4505
files. In rare cases you may need to add other kinds of files such as
4506
linker scripts, but @emph{listing a source file in
4507
@code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4508
before all the components of a program are built, consider using the
4509
@code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4510
4511
If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4512
Automake. The automatically-assigned value is the contents of
4513
@code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4514
@option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4515
configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4516
@samp{$(ALLOCA)}; these are left because it is known that they will not
4517
cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4518
generated.
4519
4520
@ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4521
is useful.
4522
4523
@cindex @code{LDADD} and @option{-l}
4524
@cindex @option{-l} and @code{LDADD}
4525
We recommend that you avoid using @option{-l} options in @code{LDADD}
4526
or @code{@var{prog}_LDADD} when referring to libraries built by your
4527
package. Instead, write the file name of the library explicitly as in
4528
the above @code{cpio} example. Use @option{-l} only to list
4529
third-party libraries. If you follow this rule, the default value of
4530
@code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4531
omit the other ones.
4532
4533
4534
@node Conditional Sources
4535
@subsection Conditional compilation of sources
4536
4537
You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4538
@samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4539
@code{_SOURCES} variable. The reason for this is a bit hard to
4540
explain, but suffice to say that it simply won't work. Automake will
4541
give an error if you try to do this.
4542
4543
Fortunately there are two other ways to achieve the same result. One is
4544
to use configure substitutions in @code{_LDADD} variables, the other is
4545
to use an Automake conditional.
4546
4547
@subsubsection Conditional compilation using @code{_LDADD} substitutions
4548
4549
@cindex @code{EXTRA_prog_SOURCES}, defined
4550
4551
Automake must know all the source files that could possibly go into a
4552
program, even if not all the files are built in every circumstance. Any
4553
files that are only conditionally built should be listed in the
4554
appropriate @code{EXTRA_} variable. For instance, if
4555
@file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4556
in @code{hello}, the @file{Makefile.am} would contain:
4557
4558
@example
4559
bin_PROGRAMS = hello
4560
hello_SOURCES = hello-common.c
4561
EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4562
hello_LDADD = $(HELLO_SYSTEM)
4563
hello_DEPENDENCIES = $(HELLO_SYSTEM)
4564
@end example
4565
4566
@noindent
4567
You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4568
@file{configure.ac}:
4569
4570
@example
4571
@dots{}
4572
case $host in
4573
*linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4574
*) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4575
esac
4576
AC_SUBST([HELLO_SYSTEM])
4577
@dots{}
4578
@end example
4579
4580
In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4581
either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4582
both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4583
built and linked in.
4584
4585
@subsubsection Conditional compilation using Automake conditionals
4586
4587
An often simpler way to compile source files conditionally is to use
4588
Automake conditionals. For instance, you could use this
4589
@file{Makefile.am} construct to build the same @file{hello} example:
4590
4591
@example
4592
bin_PROGRAMS = hello
4593
if LINUX
4594
hello_SOURCES = hello-linux.c hello-common.c
4595
else
4596
hello_SOURCES = hello-generic.c hello-common.c
4597
endif
4598
@end example
4599
4600
In this case, @file{configure.ac} should setup the @code{LINUX}
4601
conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4602
4603
When using conditionals like this you don't need to use the
4604
@code{EXTRA_} variable, because Automake will examine the contents of
4605
each variable to construct the complete list of source files.
4606
4607
If your program uses a lot of files, you will probably prefer a
4608
conditional @samp{+=}.
4609
4610
@example
4611
bin_PROGRAMS = hello
4612
hello_SOURCES = hello-common.c
4613
if LINUX
4614
hello_SOURCES += hello-linux.c
4615
else
4616
hello_SOURCES += hello-generic.c
4617
endif
4618
@end example
4619
4620
@node Conditional Programs
4621
@subsection Conditional compilation of programs
4622
@cindex Conditional programs
4623
@cindex Programs, conditional
4624
4625
Sometimes it is useful to determine the programs that are to be built
4626
at configure time. For instance, GNU @code{cpio} only builds
4627
@code{mt} and @code{rmt} under special circumstances. The means to
4628
achieve conditional compilation of programs are the same you can use
4629
to compile source files conditionally: substitutions or conditionals.
4630
4631
@subsubsection Conditional programs using @command{configure} substitutions
4632
4633
@vindex EXTRA_PROGRAMS
4634
@cindex @code{EXTRA_PROGRAMS}, defined
4635
In this case, you must notify Automake of all the programs that can
4636
possibly be built, but at the same time cause the generated
4637
@file{Makefile.in} to use the programs specified by @command{configure}.
4638
This is done by having @command{configure} substitute values into each
4639
@code{_PROGRAMS} definition, while listing all optionally built programs
4640
in @code{EXTRA_PROGRAMS}.
4641
4642
@example
4643
bin_PROGRAMS = cpio pax $(MT)
4644
libexec_PROGRAMS = $(RMT)
4645
EXTRA_PROGRAMS = mt rmt
4646
@end example
4647
4648
As explained in @ref{EXEEXT}, Automake will rewrite
4649
@code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4650
@code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4651
Obviously it cannot rewrite values obtained at run-time through
4652
@command{configure} substitutions, therefore you should take care of
4653
appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4654
['mt$@{EXEEXT@}'])}.
4655
4656
@subsubsection Conditional programs using Automake conditionals
4657
4658
You can also use Automake conditionals (@pxref{Conditionals}) to
4659
select programs to be built. In this case you don't have to worry
4660
about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4661
4662
@example
4663
bin_PROGRAMS = cpio pax
4664
if WANT_MT
4665
bin_PROGRAMS += mt
4666
endif
4667
if WANT_RMT
4668
libexec_PROGRAMS = rmt
4669
endif
4670
@end example
4671
4672
4673
@node A Library
4674
@section Building a library
4675
4676
@cindex @code{_LIBRARIES} primary, defined
4677
@cindex @code{LIBRARIES} primary, defined
4678
@cindex Primary variable, @code{LIBRARIES}
4679
@vindex _LIBRARIES
4680
4681
@vindex lib_LIBRARIES
4682
@vindex pkglib_LIBRARIES
4683
@vindex noinst_LIBRARIES
4684
4685
Building a library is much like building a program. In this case, the
4686
name of the primary is @code{LIBRARIES}. Libraries can be installed in
4687
@code{libdir} or @code{pkglibdir}.
4688
4689
@xref{A Shared Library}, for information on how to build shared
4690
libraries using libtool and the @code{LTLIBRARIES} primary.
4691
4692
Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4693
For instance, to create a library named @file{libcpio.a}, but not install
4694
it, you would write:
4695
4696
@example
4697
noinst_LIBRARIES = libcpio.a
4698
libcpio_a_SOURCES = @dots{}
4699
@end example
4700
4701
The sources that go into a library are determined exactly as they are
4702
for programs, via the @code{_SOURCES} variables. Note that the library
4703
name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4704
variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4705
not @samp{libcpio.a_SOURCES}.
4706
4707
@vindex maude_LIBADD
4708
Extra objects can be added to a library using the
4709
@code{@var{library}_LIBADD} variable. This should be used for objects
4710
determined by @command{configure}. Again from @code{cpio}:
4711
4712
@example
4713
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4714
@end example
4715
4716
In addition, sources for extra objects that will not exist until
4717
configure-time must be added to the @code{BUILT_SOURCES} variable
4718
(@pxref{Sources}).
4719
4720
Building a static library is done by compiling all object files, then
4721
by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4722
library and the list of objects, and finally by calling
4723
@samp{$(RANLIB)} on that library. You should call
4724
@code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4725
@code{RANLIB} (Automake will complain otherwise). @code{AR} and
4726
@code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
4727
can override these two variables my setting them in your
4728
@file{Makefile.am}, by @code{AC_SUBST}ing them from your
4729
@file{configure.ac}, or by defining a per-library @code{maude_AR}
4730
variable (@pxref{Program and Library Variables}).
4731
4732
@cindex Empty libraries
4733
Be careful when selecting library components conditionally. Because
4734
building an empty library is not portable, you should ensure that any
4735
library contains always at least one object.
4736
4737
To use a static library when building a program, add it to
4738
@code{LDADD} for this program. In the following example, the program
4739
@file{cpio} is statically linked with the library @file{libcpio.a}.
4740
4741
@example
4742
noinst_LIBRARIES = libcpio.a
4743
libcpio_a_SOURCES = @dots{}
4744
4745
bin_PROGRAMS = cpio
4746
cpio_SOURCES = cpio.c @dots{}
4747
cpio_LDADD = libcpio.a
4748
@end example
4749
4750
4751
@node A Shared Library
4752
@section Building a Shared Library
4753
4754
@cindex Shared libraries, support for
4755
4756
Building shared libraries portably is a relatively complex matter.
4757
For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
4758
Libtool Manual}) was created to help build shared libraries in a
4759
platform-independent way.
4760
4761
@menu
4762
* Libtool Concept:: Introducing Libtool
4763
* Libtool Libraries:: Declaring Libtool Libraries
4764
* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
4765
* Conditional Libtool Sources:: Choosing Library Sources Conditionally
4766
* Libtool Convenience Libraries:: Building Convenience Libtool Libraries
4767
* Libtool Modules:: Building Libtool Modules
4768
* Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
4769
* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
4770
* Libtool Issues:: Common Issues Related to Libtool's Use
4771
@end menu
4772
4773
@node Libtool Concept
4774
@subsection The Libtool Concept
4775
4776
@cindex @command{libtool}, introduction
4777
@cindex libtool library, definition
4778
@cindex suffix @file{.la}, defined
4779
@cindex @file{.la} suffix, defined
4780
4781
Libtool abstracts shared and static libraries into a unified concept
4782
henceforth called @dfn{libtool libraries}. Libtool libraries are
4783
files using the @file{.la} suffix, and can designate a static library,
4784
a shared library, or maybe both. Their exact nature cannot be
4785
determined until @file{./configure} is run: not all platforms support
4786
all kinds of libraries, and users can explicitly select which
4787
libraries should be built. (However the package's maintainers can
4788
tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
4789
macro, libtool, The Libtool Manual}.)
4790
4791
@cindex suffix @file{.lo}, defined
4792
Because object files for shared and static libraries must be compiled
4793
differently, libtool is also used during compilation. Object files
4794
built by libtool are called @dfn{libtool objects}: these are files
4795
using the @file{.lo} suffix. Libtool libraries are built from these
4796
libtool objects.
4797
4798
You should not assume anything about the structure of @file{.la} or
4799
@file{.lo} files and how libtool constructs them: this is libtool's
4800
concern, and the last thing one wants is to learn about libtool's
4801
guts. However the existence of these files matters, because they are
4802
used as targets and dependencies in @file{Makefile}s rules when
4803
building libtool libraries. There are situations where you may have
4804
to refer to these, for instance when expressing dependencies for
4805
building source files conditionally (@pxref{Conditional Libtool
4806
Sources}).
4807
4808
@cindex @file{libltdl}, introduction
4809
4810
People considering writing a plug-in system, with dynamically loaded
4811
modules, should look into @file{libltdl}: libtool's dlopening library
4812
(@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
4813
This offers a portable dlopening facility to load libtool libraries
4814
dynamically, and can also achieve static linking where unavoidable.
4815
4816
Before we discuss how to use libtool with Automake in details, it
4817
should be noted that the libtool manual also has a section about how
4818
to use Automake with libtool (@pxref{Using Automake, , Using Automake
4819
with Libtool, libtool, The Libtool Manual}).
4820
4821
@node Libtool Libraries
4822
@subsection Building Libtool Libraries
4823
4824
@cindex @code{_LTLIBRARIES} primary, defined
4825
@cindex @code{LTLIBRARIES} primary, defined
4826
@cindex Primary variable, @code{LTLIBRARIES}
4827
@cindex Example of shared libraries
4828
@vindex lib_LTLIBRARIES
4829
@vindex pkglib_LTLIBRARIES
4830
@vindex _LTLIBRARIES
4831
4832
Automake uses libtool to build libraries declared with the
4833
@code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
4834
list of libtool libraries to build. For instance, to create a libtool
4835
library named @file{libgettext.la}, and install it in @code{libdir},
4836
write:
4837
4838
@example
4839
lib_LTLIBRARIES = libgettext.la
4840
libgettext_la_SOURCES = gettext.c gettext.h @dots{}
4841
@end example
4842
4843
Automake predefines the variable @code{pkglibdir}, so you can use
4844
@code{pkglib_LTLIBRARIES} to install libraries in
4845
@samp{$(libdir)/@@PACKAGE@@/}.
4846
4847
If @file{gettext.h} is a public header file that needs to be installed
4848
in order for people to use the library, it should be declared using a
4849
@code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
4850
Headers listed in the latter should be internal headers that are not
4851
part of the public interface.
4852
4853
@example
4854
lib_LTLIBRARIES = libgettext.la
4855
libgettext_la_SOURCES = gettext.c @dots{}
4856
include_HEADERS = gettext.h @dots{}
4857
@end example
4858
4859
A package can build and install such a library along with other
4860
programs that use it. This dependency should be specified using
4861
@code{LDADD}. The following example builds a program named
4862
@file{hello} that is linked with @file{libgettext.la}.
4863
4864
@example
4865
lib_LTLIBRARIES = libgettext.la
4866
libgettext_la_SOURCES = gettext.c @dots{}
4867
4868
bin_PROGRAMS = hello
4869
hello_SOURCES = hello.c @dots{}
4870
hello_LDADD = libgettext.la
4871
@end example
4872
4873
@noindent
4874
Whether @file{hello} is statically or dynamically linked with
4875
@file{libgettext.la} is not yet known: this will depend on the
4876
configuration of libtool and the capabilities of the host.
4877
4878
4879
@node Conditional Libtool Libraries
4880
@subsection Building Libtool Libraries Conditionally
4881
@cindex libtool libraries, conditional
4882
@cindex conditional libtool libraries
4883
4884
Like conditional programs (@pxref{Conditional Programs}), there are
4885
two main ways to build conditional libraries: using Automake
4886
conditionals or using Autoconf @code{AC_SUBST}itutions.
4887
4888
The important implementation detail you have to be aware of is that
4889
the place where a library will be installed matters to libtool: it
4890
needs to be indicated @emph{at link-time} using the @option{-rpath}
4891
option.
4892
4893
For libraries whose destination directory is known when Automake runs,
4894
Automake will automatically supply the appropriate @option{-rpath}
4895
option to libtool. This is the case for libraries listed explicitly in
4896
some installable @code{_LTLIBRARIES} variables such as
4897
@code{lib_LTLIBRARIES}.
4898
4899
However, for libraries determined at configure time (and thus
4900
mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
4901
final installation directory. For such libraries you must add the
4902
@option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
4903
hand.
4904
4905
The examples below illustrate the differences between these two methods.
4906
4907
Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
4908
variable set at @file{./configure}-time to either @file{libfoo.la},
4909
@file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
4910
appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
4911
relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
4912
the link rule for these two libraries. Therefore the @option{-rpath}
4913
argument must be explicitly supplied.
4914
4915
@example
4916
EXTRA_LTLIBRARIES = libfoo.la libbar.la
4917
lib_LTLIBRARIES = $(WANTEDLIBS)
4918
libfoo_la_SOURCES = foo.c @dots{}
4919
libfoo_la_LDFLAGS = -rpath '$(libdir)'
4920
libbar_la_SOURCES = bar.c @dots{}
4921
libbar_la_LDFLAGS = -rpath '$(libdir)'
4922
@end example
4923
4924
Here is how the same @file{Makefile.am} would look using Automake
4925
conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
4926
Automake is able to compute the @option{-rpath} setting itself, because
4927
it's clear that both libraries will end up in @samp{$(libdir)} if they
4928
are installed.
4929
4930
@example
4931
lib_LTLIBRARIES =
4932
if WANT_LIBFOO
4933
lib_LTLIBRARIES += libfoo.la
4934
endif
4935
if WANT_LIBBAR
4936
lib_LTLIBRARIES += libbar.la
4937
endif
4938
libfoo_la_SOURCES = foo.c @dots{}
4939
libbar_la_SOURCES = bar.c @dots{}
4940
@end example
4941
4942
@node Conditional Libtool Sources
4943
@subsection Libtool Libraries with Conditional Sources
4944
4945
Conditional compilation of sources in a library can be achieved in the
4946
same way as conditional compilation of sources in a program
4947
(@pxref{Conditional Sources}). The only difference is that
4948
@code{_LIBADD} should be used instead of @code{_LDADD} and that it
4949
should mention libtool objects (@file{.lo} files).
4950
4951
So, to mimic the @file{hello} example from @ref{Conditional Sources},
4952
we could build a @file{libhello.la} library using either
4953
@file{hello-linux.c} or @file{hello-generic.c} with the following
4954
@file{Makefile.am}.
4955
4956
@example
4957
lib_LTLIBRARIES = libhello.la
4958
libhello_la_SOURCES = hello-common.c
4959
EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
4960
libhello_la_LIBADD = $(HELLO_SYSTEM)
4961
libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
4962
@end example
4963
4964
@noindent
4965
And make sure @command{configure} defines @code{HELLO_SYSTEM} as
4966
either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
4967
4968
Or we could simply use an Automake conditional as follows.
4969
4970
@example
4971
lib_LTLIBRARIES = libhello.la
4972
libhello_la_SOURCES = hello-common.c
4973
if LINUX
4974
libhello_la_SOURCES += hello-linux.c
4975
else
4976
libhello_la_SOURCES += hello-generic.c
4977
endif
4978
@end example
4979
4980
@node Libtool Convenience Libraries
4981
@subsection Libtool Convenience Libraries
4982
@cindex convenience libraries, libtool
4983
@cindex libtool convenience libraries
4984
@vindex noinst_LTLIBRARIES
4985
@vindex check_LTLIBRARIES
4986
4987
Sometimes you want to build libtool libraries that should not be
4988
installed. These are called @dfn{libtool convenience libraries} and
4989
are typically used to encapsulate many sublibraries, later gathered
4990
into one big installed library.
4991
4992
Libtool convenience libraries are declared by directory-less variables
4993
such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
4994
@code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
4995
not need an @option{-rpath} flag at link time (actually this is the only
4996
difference).
4997
4998
Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
4999
built. Those listed in @code{check_LTLIBRARIES} are built only upon
5000
@samp{make check}. Finally, libraries listed in
5001
@code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5002
rules to build them, but if the library does not appear as a Makefile
5003
dependency anywhere it won't be built (this is why
5004
@code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5005
5006
Here is a sample setup merging libtool convenience libraries from
5007
subdirectories into one main @file{libtop.la} library.
5008
5009
@example
5010
# -- Top-level Makefile.am --
5011
SUBDIRS = sub1 sub2 @dots{}
5012
lib_LTLIBRARIES = libtop.la
5013
libtop_la_SOURCES =
5014
libtop_la_LIBADD = \
5015
sub1/libsub1.la \
5016
sub2/libsub2.la \
5017
@dots{}
5018
5019
# -- sub1/Makefile.am --
5020
noinst_LTLIBRARIES = libsub1.la
5021
libsub1_la_SOURCES = @dots{}
5022
5023
# -- sub2/Makefile.am --
5024
# showing nested convenience libraries
5025
SUBDIRS = sub2.1 sub2.2 @dots{}
5026
noinst_LTLIBRARIES = libsub2.la
5027
libsub2_la_SOURCES =
5028
libsub2_la_LIBADD = \
5029
sub21/libsub21.la \
5030
sub22/libsub22.la \
5031
@dots{}
5032
@end example
5033
5034
When using such setup, beware that @command{automake} will assume
5035
@file{libtop.la} is to be linked with the C linker. This is because
5036
@code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5037
default language. If @code{libtop_la_SOURCES} was not empty,
5038
@command{automake} would select the linker as explained in @ref{How
5039
the Linker is Chosen}.
5040
5041
If one of the sublibraries contains non-C source, it is important that
5042
the appropriate linker be chosen. One way to achieve this is to
5043
pretend that there is such a non-C file among the sources of the
5044
library, thus forcing @command{automake} to select the appropriate
5045
linker. Here is the top-level @file{Makefile} of our example updated
5046
to force C++ linking.
5047
5048
@example
5049
SUBDIRS = sub1 sub2 @dots{}
5050
lib_LTLIBRARIES = libtop.la
5051
libtop_la_SOURCES =
5052
# Dummy C++ source to cause C++ linking.
5053
nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5054
libtop_la_LIBADD = \
5055
sub1/libsub1.la \
5056
sub2/libsub2.la \
5057
@dots{}
5058
@end example
5059
5060
@samp{EXTRA_*_SOURCES} variables are used to keep track of source
5061
files that might be compiled (this is mostly useful when doing
5062
conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5063
Libtool Sources}), and the @code{nodist_} prefix means the listed
5064
sources are not to be distributed (@pxref{Program and Library
5065
Variables}). In effect the file @file{dummy.cxx} does not need to
5066
exist in the source tree. Of course if you have some real source file
5067
to list in @code{libtop_la_SOURCES} there is no point in cheating with
5068
@code{nodist_EXTRA_libtop_la_SOURCES}.
5069
5070
5071
@node Libtool Modules
5072
@subsection Libtool Modules
5073
@cindex modules, libtool
5074
@cindex libtool modules
5075
@cindex @option{-module}, libtool
5076
5077
These are libtool libraries meant to be dlopened. They are
5078
indicated to libtool by passing @option{-module} at link-time.
5079
5080
@example
5081
pkglib_LTLIBRARIES = mymodule.la
5082
mymodule_la_SOURCES = doit.c
5083
mymodule_la_LDFLAGS = -module
5084
@end example
5085
5086
Ordinarily, Automake requires that a library's name starts with
5087
@code{lib}. However, when building a dynamically loadable module you
5088
might wish to use a "nonstandard" name. Automake will not complain
5089
about such nonstandard name if it knows the library being built is a
5090
libtool module, i.e., if @option{-module} explicitly appears in the
5091
library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5092
variable when no per-library @code{_LDFLAGS} variable is defined).
5093
5094
As always, @code{AC_SUBST} variables are black boxes to Automake since
5095
their values are not yet known when @command{automake} is run.
5096
Therefore if @option{-module} is set via such a variable, Automake
5097
cannot notice it and will proceed as if the library was an ordinary
5098
libtool library, with strict naming.
5099
5100
If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5101
the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5102
5103
@node Libtool Flags
5104
@subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5105
@cindex @code{_LIBADD}, libtool
5106
@cindex @code{_LDFLAGS}, libtool
5107
@cindex @code{_LIBTOOLFLAGS}, libtool
5108
@vindex AM_LIBTOOLFLAGS
5109
@vindex LIBTOOLFLAGS
5110
@vindex maude_LIBTOOLFLAGS
5111
5112
As shown in previous sections, the @samp{@var{library}_LIBADD}
5113
variable should be used to list extra libtool objects (@file{.lo}
5114
files) or libtool libraries (@file{.la}) to add to @var{library}.
5115
5116
The @samp{@var{library}_LDFLAGS} variable is the place to list
5117
additional libtool linking flags, such as @option{-version-info},
5118
@option{-static}, and a lot more. @xref{Link mode, , Link mode,
5119
libtool, The Libtool Manual}.
5120
5121
The @command{libtool} command has two kinds of options: mode-specific
5122
options and generic options. Mode-specific options such as the
5123
aforementioned linking flags should be lumped with the other flags
5124
passed to the tool invoked by @command{libtool} (hence the use of
5125
@samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5126
options include @option{--tag=@var{TAG}} and @option{--silent}
5127
(@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5128
Libtool Manual} for more options) should appear before the mode
5129
selection on the command line; in @file{Makefile.am}s they should
5130
be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5131
5132
If @samp{@var{library}_LIBTOOLFLAGS} is not defined, the global
5133
@code{AM_LIBTOOLFLAGS} variable is used instead.
5134
5135
These flags are passed to libtool after the @option{--tag=@var{TAG}}
5136
option computed by Automake (if any), so
5137
@samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is the
5138
good place to override or supplement the @option{--tag=@var{TAG}}
5139
setting.
5140
5141
The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5142
not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5143
Variables Ordering}. It allows users to run @samp{make
5144
LIBTOOLFLAGS=--silent}, for instance.
5145
5146
5147
@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5148
@subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5149
@cindex @code{LTLIBOBJS}, special handling
5150
@cindex @code{LIBOBJS}, and Libtool
5151
@cindex @code{LTALLOCA}, special handling
5152
@cindex @code{ALLOCA}, and Libtool
5153
@vindex LTLIBOBJS
5154
@vindex LIBOBJS
5155
@vindex LTALLOCA
5156
@vindex ALLOCA
5157
@acindex AC_LIBOBJ
5158
5159
Where an ordinary library might include @samp{$(LIBOBJS)} or
5160
@samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5161
@samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5162
the object files that libtool operates on do not necessarily end in
5163
@file{.o}.
5164
5165
Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5166
performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5167
@code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5168
5169
@node Libtool Issues
5170
@subsection Common Issues Related to Libtool's Use
5171
5172
@subsubsection @samp{required file `./ltmain.sh' not found}
5173
@cindex @file{ltmain.sh} not found
5174
@cindex @command{libtoolize}, no longer run by @command{automake}
5175
@cindex @command{libtoolize} and @command{autoreconf}
5176
@cindex @command{autoreconf} and @command{libtoolize}
5177
@cindex @file{bootstrap.sh} and @command{autoreconf}
5178
@cindex @file{autogen.sh} and @command{autoreconf}
5179
5180
Libtool comes with a tool called @command{libtoolize} that will
5181
install libtool's supporting files into a package. Running this
5182
command will install @file{ltmain.sh}. You should execute it before
5183
@command{aclocal} and @command{automake}.
5184
5185
People upgrading old packages to newer autotools are likely to face
5186
this issue because older Automake versions used to call
5187
@command{libtoolize}. Therefore old build scripts do not call
5188
@command{libtoolize}.
5189
5190
Since Automake 1.6, it has been decided that running
5191
@command{libtoolize} was none of Automake's business. Instead, that
5192
functionality has been moved into the @command{autoreconf} command
5193
(@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5194
The Autoconf Manual}). If you do not want to remember what to run and
5195
when, just learn the @command{autoreconf} command. Hopefully,
5196
replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5197
a call to @command{autoreconf} should also free you from any similar
5198
incompatible change in the future.
5199
5200
@subsubsection Objects @samp{created with both libtool and without}
5201
5202
Sometimes, the same source file is used both to build a libtool
5203
library and to build another non-libtool target (be it a program or
5204
another library).
5205
5206
Let's consider the following @file{Makefile.am}.
5207
5208
@example
5209
bin_PROGRAMS = prog
5210
prog_SOURCES = prog.c foo.c @dots{}
5211
5212
lib_LTLIBRARIES = libfoo.la
5213
libfoo_la_SOURCES = foo.c @dots{}
5214
@end example
5215
5216
@noindent
5217
(In this trivial case the issue could be avoided by linking
5218
@file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5219
@code{prog_SOURCES}. But let's assume we really want to keep
5220
@file{prog} and @file{libfoo.la} separate.)
5221
5222
Technically, it means that we should build @file{foo.$(OBJEXT)} for
5223
@file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5224
that in the course of creating @file{foo.lo}, libtool may erase (or
5225
replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5226
5227
Therefore, when Automake detects this situation it will complain
5228
with a message such as
5229
@example
5230
object `foo.$(OBJEXT)' created both with libtool and without
5231
@end example
5232
5233
A workaround for this issue is to ensure that these two objects get
5234
different basenames. As explained in @ref{renamed objects}, this
5235
happens automatically when per-targets flags are used.
5236
5237
@example
5238
bin_PROGRAMS = prog
5239
prog_SOURCES = prog.c foo.c @dots{}
5240
prog_CFLAGS = $(AM_CFLAGS)
5241
5242
lib_LTLIBRARIES = libfoo.la
5243
libfoo_la_SOURCES = foo.c @dots{}
5244
@end example
5245
5246
@noindent
5247
Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5248
when the @code{prog_CFLAGS} is defined, it is used instead of
5249
@code{AM_CFLAGS}. However as a side effect it will cause
5250
@file{prog.c} and @file{foo.c} to be compiled as
5251
@file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5252
the issue.
5253
5254
@node Program and Library Variables
5255
@section Program and Library Variables
5256
5257
Associated with each program are a collection of variables that can be
5258
used to modify how that program is built. There is a similar list of
5259
such variables for each library. The canonical name of the program (or
5260
library) is used as a base for naming these variables.
5261
5262
In the list below, we use the name ``maude'' to refer to the program or
5263
library. In your @file{Makefile.am} you would replace this with the
5264
canonical name of your program. This list also refers to ``maude'' as a
5265
program, but in general the same rules apply for both static and dynamic
5266
libraries; the documentation below notes situations where programs and
5267
libraries differ.
5268
5269
@vtable @code
5270
@item maude_SOURCES
5271
This variable, if it exists, lists all the source files that are
5272
compiled to build the program. These files are added to the
5273
distribution by default. When building the program, Automake will cause
5274
each source file to be compiled to a single @file{.o} file (or
5275
@file{.lo} when using libtool). Normally these object files are named
5276
after the source file, but other factors can change this. If a file in
5277
the @code{_SOURCES} variable has an unrecognized extension, Automake
5278
will do one of two things with it. If a suffix rule exists for turning
5279
files with the unrecognized extension into @file{.o} files, then
5280
automake will treat this file as it will any other source file
5281
(@pxref{Support for Other Languages}). Otherwise, the file will be
5282
ignored as though it were a header file.
5283
5284
The prefixes @code{dist_} and @code{nodist_} can be used to control
5285
whether files listed in a @code{_SOURCES} variable are distributed.
5286
@code{dist_} is redundant, as sources are distributed by default, but it
5287
can be specified for clarity if desired.
5288
5289
It is possible to have both @code{dist_} and @code{nodist_} variants of
5290
a given @code{_SOURCES} variable at once; this lets you easily
5291
distribute some files and not others, for instance:
5292
5293
@example
5294
nodist_maude_SOURCES = nodist.c
5295
dist_maude_SOURCES = dist-me.c
5296
@end example
5297
5298
By default the output file (on Unix systems, the @file{.o} file) will
5299
be put into the current build directory. However, if the option
5300
@option{subdir-objects} is in effect in the current directory then the
5301
@file{.o} file will be put into the subdirectory named after the
5302
source file. For instance, with @option{subdir-objects} enabled,
5303
@file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5304
people prefer this mode of operation. You can specify
5305
@option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5306
@cindex Subdirectory, objects in
5307
@cindex Objects in subdirectory
5308
5309
5310
@item EXTRA_maude_SOURCES
5311
Automake needs to know the list of files you intend to compile
5312
@emph{statically}. For one thing, this is the only way Automake has of
5313
knowing what sort of language support a given @file{Makefile.in}
5314
requires. @footnote{There are other, more obscure reasons for
5315
this limitation as well.} This means that, for example, you can't put a
5316
configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5317
variable. If you intend to conditionally compile source files and use
5318
@file{configure} to substitute the appropriate object names into, e.g.,
5319
@code{_LDADD} (see below), then you should list the corresponding source
5320
files in the @code{EXTRA_} variable.
5321
5322
This variable also supports @code{dist_} and @code{nodist_} prefixes.
5323
For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5324
sources that may need to be built, but should not be distributed.
5325
5326
@item maude_AR
5327
A static library is created by default by invoking @samp{$(AR)
5328
$(ARFLAGS)} followed by the name of the library and then the objects
5329
being put into the library. You can override this by setting the
5330
@code{_AR} variable. This is usually used with C++; some C++
5331
compilers require a special invocation in order to instantiate all the
5332
templates that should go into a library. For instance, the SGI C++
5333
compiler likes this variable set like so:
5334
@example
5335
libmaude_a_AR = $(CXX) -ar -o
5336
@end example
5337
5338
@item maude_LIBADD
5339
Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5340
variable. For instance, this should be used for objects determined by
5341
@command{configure} (@pxref{A Library}).
5342
5343
In the case of libtool libraries, @code{maude_LIBADD} can also refer
5344
to other libtool libraries.
5345
5346
@item maude_LDADD
5347
Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5348
@file{*.la}) can be added to a @emph{program} by listing them in the
5349
@code{_LDADD} variable. For instance, this should be used for objects
5350
determined by @command{configure} (@pxref{Linking}).
5351
5352
@code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5353
program-specific linker flags (except for @option{-l}, @option{-L},
5354
@option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5355
for this purpose.
5356
5357
For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5358
could link your program against the X libraries like so:
5359
5360
@example
5361
maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5362
@end example
5363
5364
We recommend that you use @option{-l} and @option{-L} only when
5365
referring to third-party libraries, and give the explicit file names
5366
of any library built by your package. Doing so will ensure that
5367
@code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5368
5369
@item maude_LDFLAGS
5370
This variable is used to pass extra flags to the link step of a program
5371
or a shared library. It overrides the global @code{AM_LDFLAGS} variable.
5372
5373
@item maude_LIBTOOLFLAGS
5374
This variable is used to pass extra options to @command{libtool}.
5375
It overrides the global @code{AM_LIBTOOLFLAGS} variable.
5376
These options are output before @command{libtool}'s @option{--mode=@var{MODE}}
5377
option, so they should not be mode-specific options (those belong to
5378
the compiler or linker flags). @xref{Libtool Flags}.
5379
5380
@item maude_DEPENDENCIES
5381
It is also occasionally useful to have a target (program or library)
5382
depend on some other file that is not actually part of that target.
5383
This can be done using the @code{_DEPENDENCIES} variable. Each
5384
targets depends on the contents of such a variable, but no further
5385
interpretation is done.
5386
5387
Since these dependencies are associated to the link rule used to
5388
create the programs they should normally list files used by the link
5389
command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5390
for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5391
and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5392
may need to add other kinds of files such as linker scripts, but
5393
@emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5394
some source file needs to be built before all the components of a
5395
program are built, consider using the @code{BUILT_SOURCES} variable
5396
(@pxref{Sources}).
5397
5398
If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5399
The automatically-assigned value is the contents of @code{_LDADD} or
5400
@code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5401
@option{-dlopen} and @option{-dlpreopen} options removed. The configure
5402
substitutions that are left in are only @samp{$(LIBOBJS)} and
5403
@samp{$(ALLOCA)}; these are left because it is known that they will not
5404
cause an invalid value for @code{_DEPENDENCIES} to be generated.
5405
5406
@code{_DEPENDENCIES} is more likely used to perform conditional
5407
compilation using an @code{AC_SUBST} variable that contains a list of
5408
objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5409
Sources}.
5410
5411
@item maude_LINK
5412
You can override the linker on a per-program basis. By default the
5413
linker is chosen according to the languages used by the program. For
5414
instance, a program that includes C++ source code would use the C++
5415
compiler to link. The @code{_LINK} variable must hold the name of a
5416
command that can be passed all the @file{.o} file names as arguments.
5417
Note that the name of the underlying program is @emph{not} passed to
5418
@code{_LINK}; typically one uses @samp{$@@}:
5419
5420
@example
5421
maude_LINK = $(CCLD) -magic -o $@@
5422
@end example
5423
5424
@item maude_CCASFLAGS
5425
@itemx maude_CFLAGS
5426
@itemx maude_CPPFLAGS
5427
@itemx maude_CXXFLAGS
5428
@itemx maude_FFLAGS
5429
@itemx maude_GCJFLAGS
5430
@itemx maude_LFLAGS
5431
@itemx maude_OBJCFLAGS
5432
@itemx maude_RFLAGS
5433
@itemx maude_UPCFLAGS
5434
@itemx maude_YFLAGS
5435
@cindex per-target compilation flags, defined
5436
Automake allows you to set compilation flags on a per-program (or
5437
per-library) basis. A single source file can be included in several
5438
programs, and it will potentially be compiled with different flags for
5439
each program. This works for any language directly supported by
5440
Automake. These @dfn{per-target compilation flags} are
5441
@samp{_CCASFLAGS},
5442
@samp{_CFLAGS},
5443
@samp{_CPPFLAGS},
5444
@samp{_CXXFLAGS},
5445
@samp{_FFLAGS},
5446
@samp{_GCJFLAGS},
5447
@samp{_LFLAGS},
5448
@samp{_OBJCFLAGS},
5449
@samp{_RFLAGS},
5450
@samp{_UPCFLAGS}, and
5451
@samp{_YFLAGS}.
5452
5453
When using a per-target compilation flag, Automake will choose a
5454
different name for the intermediate object files. Ordinarily a file
5455
like @file{sample.c} will be compiled to produce @file{sample.o}.
5456
However, if the program's @code{_CFLAGS} variable is set, then the
5457
object file will be named, for instance, @file{maude-sample.o}. (See
5458
also @ref{renamed objects}.) The use of per-target compilation flags
5459
with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5460
from @file{configure.ac}.
5461
5462
In compilations with per-target flags, the ordinary @samp{AM_} form of
5463
the flags variable is @emph{not} automatically included in the
5464
compilation (however, the user form of the variable @emph{is} included).
5465
So for instance, if you want the hypothetical @file{maude} compilations
5466
to also use the value of @code{AM_CFLAGS}, you would need to write:
5467
5468
@example
5469
maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5470
@end example
5471
5472
@xref{Flag Variables Ordering}, for more discussion about the
5473
interaction between user variables, @samp{AM_} shadow variables, and
5474
per-target variables.
5475
5476
@item maude_SHORTNAME
5477
On some platforms the allowable file names are very short. In order to
5478
support these systems and per-target compilation flags at the same
5479
time, Automake allows you to set a ``short name'' that will influence
5480
how intermediate object files are named. For instance, in the following
5481
example,
5482
5483
@example
5484
bin_PROGRAMS = maude
5485
maude_CPPFLAGS = -DSOMEFLAG
5486
maude_SHORTNAME = m
5487
maude_SOURCES = sample.c @dots{}
5488
@end example
5489
5490
@noindent
5491
the object file would be named @file{m-sample.o} rather than
5492
@file{maude-sample.o}.
5493
5494
This facility is rarely needed in practice,
5495
and we recommend avoiding it until you find it is required.
5496
@end vtable
5497
5498
@node Default _SOURCES
5499
@section Default @code{_SOURCES}
5500
5501
@vindex _SOURCES
5502
@vindex SOURCES
5503
@cindex @code{_SOURCES}, default
5504
@cindex default @code{_SOURCES}
5505
5506
@code{_SOURCES} variables are used to specify source files of programs
5507
(@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5508
libraries (@pxref{A Shared Library}).
5509
5510
When no such variable is specified for a target, Automake will define
5511
one itself. The default is to compile a single C file whose base name
5512
is the name of the target itself, with any extension replaced by
5513
@file{.c}. (Defaulting to C is terrible but we are stuck with it for
5514
historical reasons.)
5515
5516
For example if you have the following somewhere in your
5517
@file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5518
5519
@example
5520
lib_LIBRARIES = libfoo.a sub/libc++.a
5521
@end example
5522
5523
@noindent
5524
@file{libfoo.a} will be built using a default source file named
5525
@file{libfoo.c}, and @file{sub/libc++.a} will be built from
5526
@file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5527
would be built from @file{sub_libc___a.c}, i.e., the default source
5528
was the canonized name of the target, with @file{.c} appended.
5529
We believe the new behavior is more sensible, but for backward
5530
compatibility automake will use the old name if a file or a rule
5531
with that name exist.)
5532
5533
@cindex @code{check_PROGRAMS} example
5534
@vindex check_PROGRAMS
5535
Default sources are mainly useful in test suites, when building many
5536
tests programs each from a single source. For instance, in
5537
5538
@example
5539
check_PROGRAMS = test1 test2 test3
5540
@end example
5541
5542
@noindent
5543
@file{test1}, @file{test2}, and @file{test3} will be built
5544
from @file{test1.c}, @file{test2.c}, and @file{test3.c}.
5545
5546
@cindex Libtool modules, default source example
5547
@cindex default source, Libtool modules example
5548
Another case where is this convenient is building many Libtool modules
5549
(@file{moduleN.la}), each defined in its own file (@file{moduleN.c}).
5550
5551
@example
5552
AM_LDFLAGS = -module
5553
lib_LTLIBRARIES = module1.la module2.la module3.la
5554
@end example
5555
5556
@cindex empty @code{_SOURCES}
5557
@cindex @code{_SOURCES}, empty
5558
Finally, there is one situation where this default source computation
5559
needs to be avoided: when a target should not be built from sources.
5560
We already saw such an example in @ref{true}; this happens when all
5561
the constituents of a target have already been compiled and need just
5562
to be combined using a @code{_LDADD} variable. Then it is necessary
5563
to define an empty @code{_SOURCES} variable, so that automake does not
5564
compute a default.
5565
5566
@example
5567
bin_PROGRAMS = target
5568
target_SOURCES =
5569
target_LDADD = libmain.a libmisc.a
5570
@end example
5571
5572
@node LIBOBJS
5573
@section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5574
5575
@cindex @code{LIBOBJS}, example
5576
@cindex @code{ALLOCA}, example
5577
@cindex @code{LIBOBJS}, special handling
5578
@cindex @code{ALLOCA}, special handling
5579
@vindex LTLIBOBJS
5580
@vindex LIBOBJS
5581
@vindex LTALLOCA
5582
@vindex ALLOCA
5583
5584
The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5585
files that should be compiled into the project to provide an
5586
implementation for functions that are missing or broken on the host
5587
system. They are substituted by @file{configure}.
5588
5589
@acindex AC_LIBOBJ
5590
5591
These variables are defined by Autoconf macros such as
5592
@code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5593
Generic Function Checks, autoconf, The Autoconf Manual}), or
5594
@code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5595
Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5596
macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5597
populate @samp{$(LIBOBJS)}.
5598
5599
@acindex AC_LIBSOURCE
5600
5601
Using these variables is very similar to doing conditional compilation
5602
using @code{AC_SUBST} variables, as described in @ref{Conditional
5603
Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5604
@samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5605
variable, or to the @samp{*_LIBADD} variable when building a library.
5606
However there is no need to list the corresponding sources in
5607
@samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5608
automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5609
dependencies, and it will discover the list of corresponding source
5610
files automatically (by tracing the invocations of the
5611
@code{AC_LIBSOURCE} Autoconf macros).
5612
5613
These variables are usually used to build a portability library that
5614
is linked with all the programs of the project. We now review a
5615
sample setup. First, @file{configure.ac} contains some checks that
5616
affect either @code{LIBOBJS} or @code{ALLOCA}.
5617
5618
@example
5619
# configure.ac
5620
@dots{}
5621
AC_CONFIG_LIBOBJ_DIR([lib])
5622
@dots{}
5623
AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5624
AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5625
AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5626
AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5627
@dots{}
5628
AC_CONFIG_FILES([
5629
lib/Makefile
5630
src/Makefile
5631
])
5632
AC_OUTPUT
5633
@end example
5634
5635
@acindex AC_CONFIG_LIBOBJ_DIR
5636
5637
The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5638
of these object files are to be found in the @file{lib/} directory.
5639
Automake can also use this information, otherwise it expects the
5640
source files are to be in the directory where the @samp{$(LIBOBJS)}
5641
and @samp{$(ALLOCA)} variables are used.
5642
5643
The @file{lib/} directory should therefore contain @file{malloc.c},
5644
@file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5645
@file{Makefile.am}:
5646
5647
@example
5648
# lib/Makefile.am
5649
5650
noinst_LIBRARIES = libcompat.a
5651
libcompat_a_SOURCES =
5652
libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5653
@end example
5654
5655
The library can have any name, of course, and anyway it is not going
5656
to be installed: it just holds the replacement versions of the missing
5657
or broken functions so we can later link them in. In many projects
5658
also include extra functions, specific to the project, in that
5659
library: they are simply added on the @code{_SOURCES} line.
5660
5661
@cindex Empty libraries and @samp{$(LIBOBJS)}
5662
@cindex @samp{$(LIBOBJS)} and empty libraries
5663
There is a small trap here, though: @samp{$(LIBOBJS)} and
5664
@samp{$(ALLOCA)} might be empty, and building an empty library is not
5665
portable. You should ensure that there is always something to put in
5666
@file{libcompat.a}. Most projects will also add some utility
5667
functions in that directory, and list them in
5668
@code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5669
be empty.
5670
5671
Finally here is how this library could be used from the @file{src/}
5672
directory.
5673
5674
@example
5675
# src/Makefile.am
5676
5677
# Link all programs in this directory with libcompat.a
5678
LDADD = ../lib/libcompat.a
5679
5680
bin_PROGRAMS = tool1 tool2 @dots{}
5681
tool1_SOURCES = @dots{}
5682
tool2_SOURCES = @dots{}
5683
@end example
5684
5685
When option @option{subdir-objects} is not used, as in the above
5686
example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5687
be used in the directory where their sources lie. E.g., here it would
5688
be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5689
@file{src/Makefile.am}. However if both @option{subdir-objects} and
5690
@code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5691
in other directories. For instance @file{src/Makefile.am} could be
5692
changed as follows.
5693
5694
@example
5695
# src/Makefile.am
5696
5697
AUTOMAKE_OPTIONS = subdir-objects
5698
LDADD = $(LIBOBJS) $(ALLOCA)
5699
5700
bin_PROGRAMS = tool1 tool2 @dots{}
5701
tool1_SOURCES = @dots{}
5702
tool2_SOURCES = @dots{}
5703
@end example
5704
5705
Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5706
file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5707
Libtool libraries (where the expected object extension is @file{.lo}):
5708
@code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
5709
5710
@code{LTLIBOBJS} is defined automatically by Autoconf and should not
5711
be defined by hand (as in the past), however at the time of writing
5712
@code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
5713
@xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
5714
autoconf, The Autoconf Manual}.
5715
5716
5717
@node Program variables
5718
@section Variables used when building a program
5719
5720
Occasionally it is useful to know which @file{Makefile} variables
5721
Automake uses for compilations; for instance, you might need to do your
5722
own compilation in some special cases.
5723
5724
Some variables are inherited from Autoconf; these are @code{CC},
5725
@code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
5726
@code{LIBS}.
5727
@vindex CC
5728
@vindex CFLAGS
5729
@vindex CPPFLAGS
5730
@vindex DEFS
5731
@vindex LDFLAGS
5732
@vindex LIBS
5733
5734
There are some additional variables that Automake defines on its own:
5735
5736
@vtable @code
5737
@item AM_CPPFLAGS
5738
The contents of this variable are passed to every compilation that invokes
5739
the C preprocessor; it is a list of arguments to the preprocessor. For
5740
instance, @option{-I} and @option{-D} options should be listed here.
5741
5742
Automake already provides some @option{-I} options automatically, in a
5743
separate variable that is also passed to every compilation that invokes
5744
the C preprocessor. In particular it generates @samp{-I.},
5745
@samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
5746
@file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
5747
@code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
5748
options using the @option{nostdinc} option.
5749
5750
@code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
5751
per-library) @code{_CPPFLAGS} variable if it is defined.
5752
5753
@item INCLUDES
5754
This does the same job as @code{AM_CPPFLAGS} (or any per-target
5755
@code{_CPPFLAGS} variable if it is used). It is an older name for the
5756
same functionality. This variable is deprecated; we suggest using
5757
@code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
5758
5759
@item AM_CFLAGS
5760
This is the variable the @file{Makefile.am} author can use to pass
5761
in additional C compiler flags. It is more fully documented elsewhere.
5762
In some situations, this is not used, in preference to the
5763
per-executable (or per-library) @code{_CFLAGS}.
5764
5765
@item COMPILE
5766
This is the command used to actually compile a C source file. The
5767
file name is appended to form the complete command line.
5768
5769
@item AM_LDFLAGS
5770
This is the variable the @file{Makefile.am} author can use to pass
5771
in additional linker flags. In some situations, this is not used, in
5772
preference to the per-executable (or per-library) @code{_LDFLAGS}.
5773
5774
@item LINK
5775
This is the command used to actually link a C program. It already
5776
includes @samp{-o $@@} and the usual variable references (for instance,
5777
@code{CFLAGS}); it takes as ``arguments'' the names of the object files
5778
and libraries to link in.
5779
@end vtable
5780
5781
5782
@node Yacc and Lex
5783
@section Yacc and Lex support
5784
5785
Automake has somewhat idiosyncratic support for Yacc and Lex.
5786
5787
Automake assumes that the @file{.c} file generated by @command{yacc}
5788
(or @command{lex}) should be named using the basename of the input
5789
file. That is, for a yacc source file @file{foo.y}, Automake will
5790
cause the intermediate file to be named @file{foo.c} (as opposed to
5791
@file{y.tab.c}, which is more traditional).
5792
5793
The extension of a yacc source file is used to determine the extension
5794
of the resulting C or C++ file. Files with the extension @file{.y}
5795
will be turned into @file{.c} files; likewise, @file{.yy} will become
5796
@file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
5797
@file{.ypp}, @file{.cpp}.
5798
5799
Likewise, lex source files can be used to generate C or C++; the
5800
extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
5801
@file{.lpp} are recognized.
5802
5803
You should never explicitly mention the intermediate (C or C++) file
5804
in any @code{SOURCES} variable; only list the source file.
5805
5806
The intermediate files generated by @command{yacc} (or @command{lex})
5807
will be included in any distribution that is made. That way the user
5808
doesn't need to have @command{yacc} or @command{lex}.
5809
5810
If a @command{yacc} source file is seen, then your @file{configure.ac} must
5811
define the variable @code{YACC}. This is most easily done by invoking
5812
the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
5813
Program Checks, autoconf, The Autoconf Manual}).
5814
5815
@vindex YFLAGS
5816
@vindex AM_YFLAGS
5817
When @code{yacc} is invoked, it is passed @code{YFLAGS} and
5818
@code{AM_YFLAGS}. The former is a user variable and the latter is
5819
intended for the @file{Makefile.am} author.
5820
5821
@code{AM_YFLAGS} is usually used to pass the @option{-d} option to
5822
@command{yacc}. Automake knows what this means and will automatically
5823
adjust its rules to update and distribute the header file built by
5824
@samp{yacc -d}. What Automake cannot guess, though, is where this
5825
header will be used: it is up to you to ensure the header gets built
5826
before it is first used. Typically this is necessary in order for
5827
dependency tracking to work when the header is included by another
5828
file. The common solution is listing the header file in
5829
@code{BUILT_SOURCES} (@pxref{Sources}) as follows.
5830
5831
@example
5832
BUILT_SOURCES = parser.h
5833
AM_YFLAGS = -d
5834
bin_PROGRAMS = foo
5835
foo_SOURCES = @dots{} parser.y @dots{}
5836
@end example
5837
5838
If a @command{lex} source file is seen, then your @file{configure.ac}
5839
must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
5840
to do this (@pxref{Particular Programs, , Particular Program Checks,
5841
autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
5842
(@pxref{Macros}) is recommended.
5843
5844
@vindex LFLAGS
5845
@vindex AM_LFLAGS
5846
When @command{lex} is invoked, it is passed @code{LFLAGS} and
5847
@code{AM_LFLAGS}. The former is a user variable and the latter is
5848
intended for the @file{Makefile.am} author.
5849
5850
When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
5851
rebuild rule for distributed Yacc and Lex sources are only used when
5852
@code{maintainer-mode} is enabled, or when the files have been erased.
5853
5854
@cindex @command{ylwrap}
5855
@cindex @command{yacc}, multiple parsers
5856
@cindex Multiple @command{yacc} parsers
5857
@cindex Multiple @command{lex} lexers
5858
@cindex @command{lex}, multiple lexers
5859
5860
When @command{lex} or @command{yacc} sources are used, @code{automake
5861
-i} automatically installs an auxiliary program called
5862
@command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
5863
program is used by the build rules to rename the output of these
5864
tools, and makes it possible to include multiple @command{yacc} (or
5865
@command{lex}) source files in a single directory. (This is necessary
5866
because yacc's output file name is fixed, and a parallel make could
5867
conceivably invoke more than one instance of @command{yacc}
5868
simultaneously.)
5869
5870
For @command{yacc}, simply managing locking is insufficient. The output of
5871
@command{yacc} always uses the same symbol names internally, so it isn't
5872
possible to link two @command{yacc} parsers into the same executable.
5873
5874
We recommend using the following renaming hack used in @command{gdb}:
5875
@example
5876
#define yymaxdepth c_maxdepth
5877
#define yyparse c_parse
5878
#define yylex c_lex
5879
#define yyerror c_error
5880
#define yylval c_lval
5881
#define yychar c_char
5882
#define yydebug c_debug
5883
#define yypact c_pact
5884
#define yyr1 c_r1
5885
#define yyr2 c_r2
5886
#define yydef c_def
5887
#define yychk c_chk
5888
#define yypgo c_pgo
5889
#define yyact c_act
5890
#define yyexca c_exca
5891
#define yyerrflag c_errflag
5892
#define yynerrs c_nerrs
5893
#define yyps c_ps
5894
#define yypv c_pv
5895
#define yys c_s
5896
#define yy_yys c_yys
5897
#define yystate c_state
5898
#define yytmp c_tmp
5899
#define yyv c_v
5900
#define yy_yyv c_yyv
5901
#define yyval c_val
5902
#define yylloc c_lloc
5903
#define yyreds c_reds
5904
#define yytoks c_toks
5905
#define yylhs c_yylhs
5906
#define yylen c_yylen
5907
#define yydefred c_yydefred
5908
#define yydgoto c_yydgoto
5909
#define yysindex c_yysindex
5910
#define yyrindex c_yyrindex
5911
#define yygindex c_yygindex
5912
#define yytable c_yytable
5913
#define yycheck c_yycheck
5914
#define yyname c_yyname
5915
#define yyrule c_yyrule
5916
@end example
5917
5918
For each define, replace the @samp{c_} prefix with whatever you like.
5919
These defines work for @command{bison}, @command{byacc}, and
5920
traditional @code{yacc}s. If you find a parser generator that uses a
5921
symbol not covered here, please report the new name so it can be added
5922
to the list.
5923
5924
5925
@node C++ Support
5926
@section C++ Support
5927
5928
@cindex C++ support
5929
@cindex Support for C++
5930
5931
Automake includes full support for C++.
5932
5933
Any package including C++ code must define the output variable
5934
@code{CXX} in @file{configure.ac}; the simplest way to do this is to use
5935
the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
5936
Program Checks, autoconf, The Autoconf Manual}).
5937
5938
A few additional variables are defined when a C++ source file is seen:
5939
5940
@vtable @code
5941
@item CXX
5942
The name of the C++ compiler.
5943
5944
@item CXXFLAGS
5945
Any flags to pass to the C++ compiler.
5946
5947
@item AM_CXXFLAGS
5948
The maintainer's variant of @code{CXXFLAGS}.
5949
5950
@item CXXCOMPILE
5951
The command used to actually compile a C++ source file. The file name
5952
is appended to form the complete command line.
5953
5954
@item CXXLINK
5955
The command used to actually link a C++ program.
5956
@end vtable
5957
5958
5959
@node Objective C Support
5960
@section Objective C Support
5961
5962
@cindex Objective C support
5963
@cindex Support for Objective C
5964
5965
Automake includes some support for Objective C.
5966
5967
Any package including Objective C code must define the output variable
5968
@code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
5969
the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
5970
Program Checks, autoconf, The Autoconf Manual}).
5971
5972
A few additional variables are defined when an Objective C source file
5973
is seen:
5974
5975
@vtable @code
5976
@item OBJC
5977
The name of the Objective C compiler.
5978
5979
@item OBJCFLAGS
5980
Any flags to pass to the Objective C compiler.
5981
5982
@item AM_OBJCFLAGS
5983
The maintainer's variant of @code{OBJCFLAGS}.
5984
5985
@item OBJCCOMPILE
5986
The command used to actually compile a Objective C source file. The
5987
file name is appended to form the complete command line.
5988
5989
@item OBJCLINK
5990
The command used to actually link a Objective C program.
5991
@end vtable
5992
5993
5994
@node Unified Parallel C Support
5995
@section Unified Parallel C Support
5996
5997
@cindex Unified Parallel C support
5998
@cindex Support for Unified Parallel C
5999
6000
Automake includes some support for Unified Parallel C.
6001
6002
Any package including Unified Parallel C code must define the output
6003
variable @code{UPC} in @file{configure.ac}; the simplest way to do
6004
this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}).
6005
6006
A few additional variables are defined when an Unified Parallel C
6007
source file is seen:
6008
6009
@vtable @code
6010
@item UPC
6011
The name of the Unified Parallel C compiler.
6012
6013
@item UPCFLAGS
6014
Any flags to pass to the Unified Parallel C compiler.
6015
6016
@item AM_UPCFLAGS
6017
The maintainer's variant of @code{UPCFLAGS}.
6018
6019
@item UPCCOMPILE
6020
The command used to actually compile a Unified Parallel C source file.
6021
The file name is appended to form the complete command line.
6022
6023
@item UPCLINK
6024
The command used to actually link a Unified Parallel C program.
6025
@end vtable
6026
6027
6028
@node Assembly Support
6029
@section Assembly Support
6030
6031
Automake includes some support for assembly code. There are two forms
6032
of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6033
(@file{*.S} or @file{*.sx}).
6034
6035
@vindex CCAS
6036
@vindex CCASFLAGS
6037
@vindex CPPFLAGS
6038
@vindex AM_CCASFLAGS
6039
@vindex AM_CPPFLAGS
6040
The variable @code{CCAS} holds the name of the compiler used to build
6041
assembly code. This compiler must work a bit like a C compiler; in
6042
particular it must accept @option{-c} and @option{-o}. The values of
6043
@code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6044
definition) is passed to the compilation. For preprocessed files,
6045
@code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6046
and @code{AM_CPPFLAGS} are also used.
6047
6048
The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6049
@code{CCASFLAGS} for you (unless they are already set, it simply sets
6050
@code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6051
flags), but you are free to define these variables by other means.
6052
6053
Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6054
@command{automake} as being files containing assembly code.
6055
6056
6057
@node Fortran 77 Support
6058
@comment node-name, next, previous, up
6059
@section Fortran 77 Support
6060
6061
@cindex Fortran 77 support
6062
@cindex Support for Fortran 77
6063
6064
Automake includes full support for Fortran 77.
6065
6066
Any package including Fortran 77 code must define the output variable
6067
@code{F77} in @file{configure.ac}; the simplest way to do this is to use
6068
the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6069
Program Checks, autoconf, The Autoconf Manual}).
6070
6071
A few additional variables are defined when a Fortran 77 source file is
6072
seen:
6073
6074
@vtable @code
6075
6076
@item F77
6077
The name of the Fortran 77 compiler.
6078
6079
@item FFLAGS
6080
Any flags to pass to the Fortran 77 compiler.
6081
6082
@item AM_FFLAGS
6083
The maintainer's variant of @code{FFLAGS}.
6084
6085
@item RFLAGS
6086
Any flags to pass to the Ratfor compiler.
6087
6088
@item AM_RFLAGS
6089
The maintainer's variant of @code{RFLAGS}.
6090
6091
@item F77COMPILE
6092
The command used to actually compile a Fortran 77 source file. The file
6093
name is appended to form the complete command line.
6094
6095
@item FLINK
6096
The command used to actually link a pure Fortran 77 program or shared
6097
library.
6098
6099
@end vtable
6100
6101
Automake can handle preprocessing Fortran 77 and Ratfor source files in
6102
addition to compiling them@footnote{Much, if not most, of the
6103
information in the following sections pertaining to preprocessing
6104
Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6105
Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6106
also contains some support for creating programs and shared libraries
6107
that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6108
Fortran 77 With C and C++}).
6109
6110
These issues are covered in the following sections.
6111
6112
@menu
6113
* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6114
* Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6115
* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6116
@end menu
6117
6118
6119
@node Preprocessing Fortran 77
6120
@comment node-name, next, previous, up
6121
@subsection Preprocessing Fortran 77
6122
6123
@cindex Preprocessing Fortran 77
6124
@cindex Fortran 77, Preprocessing
6125
@cindex Ratfor programs
6126
6127
@file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6128
rule runs just the preprocessor to convert a preprocessable Fortran 77
6129
or Ratfor source file into a strict Fortran 77 source file. The precise
6130
command used is as follows:
6131
6132
@table @file
6133
6134
@item .F
6135
@code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6136
$(AM_FFLAGS) $(FFLAGS)}
6137
6138
@item .r
6139
@code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6140
6141
@end table
6142
6143
6144
@node Compiling Fortran 77 Files
6145
@comment node-name, next, previous, up
6146
@subsection Compiling Fortran 77 Files
6147
6148
@file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6149
@file{N.r} by running the Fortran 77 compiler. The precise command used
6150
is as follows:
6151
6152
@table @file
6153
6154
@item .f
6155
@code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6156
6157
@item .F
6158
@code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6159
$(AM_FFLAGS) $(FFLAGS)}
6160
6161
@item .r
6162
@code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6163
6164
@end table
6165
6166
6167
@node Mixing Fortran 77 With C and C++
6168
@comment node-name, next, previous, up
6169
@subsection Mixing Fortran 77 With C and C++
6170
6171
@cindex Fortran 77, mixing with C and C++
6172
@cindex Mixing Fortran 77 with C and C++
6173
@cindex Linking Fortran 77 with C and C++
6174
@cindex cfortran
6175
@cindex Mixing Fortran 77 with C and/or C++
6176
6177
Automake currently provides @emph{limited} support for creating programs
6178
and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6179
However, there are many other issues related to mixing Fortran 77 with
6180
other languages that are @emph{not} (currently) handled by Automake, but
6181
that are handled by other packages@footnote{For example,
6182
@uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6183
addresses all of these inter-language issues, and runs under nearly all
6184
Fortran 77, C and C++ compilers on nearly all platforms. However,
6185
@command{cfortran} is not yet Free Software, but it will be in the next
6186
major release.}.
6187
6188
@page
6189
Automake can help in two ways:
6190
6191
@enumerate
6192
@item
6193
Automatic selection of the linker depending on which combinations of
6194
source code.
6195
6196
@item
6197
Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6198
@option{-l}) to pass to the automatically selected linker in order to link
6199
in the appropriate Fortran 77 intrinsic and run-time libraries.
6200
6201
@cindex @code{FLIBS}, defined
6202
@vindex FLIBS
6203
These extra Fortran 77 linker flags are supplied in the output variable
6204
@code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6205
supplied with newer versions of Autoconf (Autoconf version 2.13 and
6206
later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
6207
Autoconf}.
6208
@end enumerate
6209
6210
If Automake detects that a program or shared library (as mentioned in
6211
some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6212
code that is a mixture of Fortran 77 and C and/or C++, then it requires
6213
that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6214
@file{configure.ac}, and that either @code{$(FLIBS)}
6215
appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6216
(for shared libraries) variables. It is the responsibility of the
6217
person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6218
appears in the appropriate @code{_LDADD} or
6219
@code{_LIBADD} variable.
6220
6221
@cindex Mixed language example
6222
@cindex Example, mixed language
6223
6224
For example, consider the following @file{Makefile.am}:
6225
6226
@example
6227
bin_PROGRAMS = foo
6228
foo_SOURCES = main.cc foo.f
6229
foo_LDADD = libfoo.la $(FLIBS)
6230
6231
pkglib_LTLIBRARIES = libfoo.la
6232
libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6233
libfoo_la_LIBADD = $(FLIBS)
6234
@end example
6235
6236
In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6237
is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6238
been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6239
Automake would have issued a warning.
6240
6241
6242
@page
6243
@menu
6244
* How the Linker is Chosen:: Automatic linker selection
6245
@end menu
6246
6247
@node How the Linker is Chosen
6248
@comment node-name, next, previous, up
6249
@subsubsection How the Linker is Chosen
6250
6251
@cindex Automatic linker selection
6252
@cindex Selecting the linker automatically
6253
6254
When a program or library mixes several languages, Automake choose the
6255
linker according to the following priorities. (The names in
6256
parentheses are the variables containing the link command.)
6257
6258
@enumerate
6259
@item
6260
@vindex GCJLINK
6261
Native Java (@code{GCJLINK})
6262
@item
6263
@vindex CXXLINK
6264
C++ (@code{CXXLINK})
6265
@item
6266
@vindex F77LINK
6267
Fortran 77 (@code{F77LINK})
6268
@item
6269
@vindex FCLINK
6270
Fortran (@code{FCLINK})
6271
@item
6272
@vindex OBJCLINK
6273
Objective C (@code{OBJCLINK})
6274
@item
6275
@vindex UPCLINK
6276
Unified Parallel C (@code{UPCLINK})
6277
@item
6278
@vindex LINK
6279
C (@code{LINK})
6280
@end enumerate
6281
6282
For example, if Fortran 77, C and C++ source code is compiled
6283
into a program, then the C++ linker will be used. In this case, if the
6284
C or Fortran 77 linkers required any special libraries that weren't
6285
included by the C++ linker, then they must be manually added to an
6286
@code{_LDADD} or @code{_LIBADD} variable by the user writing the
6287
@file{Makefile.am}.
6288
6289
Automake only looks at the file names listed in @file{_SOURCES}
6290
variables to choose the linker, and defaults to the C linker.
6291
Sometimes this is inconvenient because you are linking against a
6292
library written in another language and would like to set the linker
6293
more appropriately. @xref{Libtool Convenience Libraries}, for a
6294
trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6295
6296
6297
@node Fortran 9x Support
6298
@comment node-name, next, previous, up
6299
@section Fortran 9x Support
6300
6301
@cindex Fortran 9x support
6302
@cindex Support for Fortran 9x
6303
6304
Automake includes full support for Fortran 9x.
6305
6306
Any package including Fortran 9x code must define the output variable
6307
@code{FC} in @file{configure.ac}; the simplest way to do this is to use
6308
the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6309
Program Checks, autoconf, The Autoconf Manual}).
6310
6311
A few additional variables are defined when a Fortran 9x source file is
6312
seen:
6313
6314
@vtable @code
6315
6316
@item FC
6317
The name of the Fortran 9x compiler.
6318
6319
@item FCFLAGS
6320
Any flags to pass to the Fortran 9x compiler.
6321
6322
@item AM_FCFLAGS
6323
The maintainer's variant of @code{FCFLAGS}.
6324
6325
@item FCCOMPILE
6326
The command used to actually compile a Fortran 9x source file. The file
6327
name is appended to form the complete command line.
6328
6329
@item FCLINK
6330
The command used to actually link a pure Fortran 9x program or shared
6331
library.
6332
6333
@end vtable
6334
6335
@menu
6336
* Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6337
@end menu
6338
6339
@node Compiling Fortran 9x Files
6340
@comment node-name, next, previous, up
6341
@subsection Compiling Fortran 9x Files
6342
6343
@file{N.o} is made automatically from @file{N.f90} or @file{N.f95}
6344
by running the Fortran 9x compiler. The precise command used
6345
is as follows:
6346
6347
@table @file
6348
6349
@item .f9x
6350
@code{$(FC) -c $(AM_FCFLAGS) $(FCFLAGS)}
6351
6352
@end table
6353
6354
@node Java Support
6355
@comment node-name, next, previous, up
6356
@section Java Support
6357
6358
@cindex Java support
6359
@cindex Support for Java
6360
6361
Automake includes support for compiled Java, using @command{gcj}, the Java
6362
front end to the GNU Compiler Collection.
6363
6364
Any package including Java code to be compiled must define the output
6365
variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6366
must also be defined somehow (either in @file{configure.ac} or
6367
@file{Makefile.am}). The simplest way to do this is to use the
6368
@code{AM_PROG_GCJ} macro.
6369
6370
@vindex GCJFLAGS
6371
6372
By default, programs including Java source files are linked with
6373
@command{gcj}.
6374
6375
As always, the contents of @code{AM_GCJFLAGS} are passed to every
6376
compilation invoking @command{gcj} (in its role as an ahead-of-time
6377
compiler, when invoking it to create @file{.class} files,
6378
@code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6379
options to @command{gcj} from @file{Makefile.am}, this variable, and not
6380
the user variable @code{GCJFLAGS}, should be used.
6381
6382
@vindex AM_GCJFLAGS
6383
6384
@command{gcj} can be used to compile @file{.java}, @file{.class},
6385
@file{.zip}, or @file{.jar} files.
6386
6387
When linking, @command{gcj} requires that the main class be specified
6388
using the @option{--main=} option. The easiest way to do this is to use
6389
the @code{_LDFLAGS} variable for the program.
6390
6391
6392
@node Support for Other Languages
6393
@comment node-name, next, previous, up
6394
@section Support for Other Languages
6395
6396
Automake currently only includes full support for C, C++ (@pxref{C++
6397
Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6398
(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6399
and Java (@pxref{Java Support}). There is only rudimentary support for other
6400
languages, support for which will be improved based on user demand.
6401
6402
Some limited support for adding your own languages is available via the
6403
suffix rule handling (@pxref{Suffixes}).
6404
6405
6406
@node ANSI
6407
@section Automatic de-ANSI-fication
6408
6409
@cindex de-ANSI-fication, defined
6410
6411
The features described in this section are obsolete; you should not
6412
used any of them in new code, and they may be withdrawn in future
6413
Automake releases.
6414
6415
When the C language was standardized in 1989, there was a long
6416
transition period where package developers needed to worry about
6417
porting to older systems that did not support ANSI C by default.
6418
These older systems are no longer in practical use and are no longer
6419
supported by their original suppliers, so developers need not worry
6420
about this problem any more.
6421
6422
Automake allows you to write packages that are portable to K&R C by
6423
@dfn{de-ANSI-fying} each source file before the actual compilation takes
6424
place.
6425
6426
@vindex AUTOMAKE_OPTIONS
6427
@opindex ansi2knr
6428
6429
If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
6430
(@pxref{Options}) contains the option @option{ansi2knr} then code to
6431
handle de-ANSI-fication is inserted into the generated
6432
@file{Makefile.in}.
6433
6434
This causes each C source file in the directory to be treated as ANSI C@.
6435
If an ANSI C compiler is available, it is used. If no ANSI C compiler
6436
is available, the @command{ansi2knr} program is used to convert the source
6437
files into K&R C, which is then compiled.
6438
6439
The @command{ansi2knr} program is simple-minded. It assumes the source
6440
code will be formatted in a particular way; see the @command{ansi2knr} man
6441
page for details.
6442
6443
@acindex AM_C_PROTOTYPES
6444
Support for the obsolete de-ANSI-fication feature
6445
requires the source files @file{ansi2knr.c}
6446
and @file{ansi2knr.1} to be in the same package as the ANSI C source;
6447
these files are distributed with Automake. Also, the package
6448
@file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
6449
(@pxref{Macros}).
6450
6451
Automake also handles finding the @command{ansi2knr} support files in some
6452
other directory in the current package. This is done by prepending the
6453
relative path to the appropriate directory to the @command{ansi2knr}
6454
option. For instance, suppose the package has ANSI C code in the
6455
@file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
6456
@file{ansi2knr.1} appear in @file{lib}. Then this could appear in
6457
@file{src/Makefile.am}:
6458
6459
@example
6460
AUTOMAKE_OPTIONS = ../lib/ansi2knr
6461
@end example
6462
6463
If no directory prefix is given, the files are assumed to be in the
6464
current directory.
6465
6466
Note that automatic de-ANSI-fication will not work when the package is
6467
being built for a different host architecture. That is because automake
6468
currently has no way to build @command{ansi2knr} for the build machine.
6469
6470
@c FIXME: this paragraph might be better moved to an `upgrading' section.
6471
@cindex @code{LTLIBOBJS} and @code{ansi2knr}
6472
@cindex @code{LIBOBJS} and @code{ansi2knr}
6473
@cindex @code{ansi2knr} and @code{LTLIBOBJS}
6474
@cindex @code{ansi2knr} and @code{LIBOBJS}
6475
Using @code{LIBOBJS} with source de-ANSI-fication used to require
6476
hand-crafted code in @file{configure} to append @samp{$U} to basenames
6477
in @code{LIBOBJS}. This is no longer true today. Starting with version
6478
2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
6479
@code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
6480
vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
6481
6482
@node Dependencies
6483
@section Automatic dependency tracking
6484
6485
As a developer it is often painful to continually update the
6486
@file{Makefile.in} whenever the include-file dependencies change in a
6487
project. Automake supplies a way to automatically track dependency
6488
changes (@pxref{Dependency Tracking}).
6489
6490
@cindex Dependency tracking
6491
@cindex Automatic dependency tracking
6492
6493
Automake always uses complete dependencies for a compilation,
6494
including system headers. Automake's model is that dependency
6495
computation should be a side effect of the build. To this end,
6496
dependencies are computed by running all compilations through a
6497
special wrapper program called @command{depcomp}. @command{depcomp}
6498
understands how to coax many different C and C++ compilers into
6499
generating dependency information in the format it requires.
6500
@samp{automake -a} will install @command{depcomp} into your source
6501
tree for you. If @command{depcomp} can't figure out how to properly
6502
invoke your compiler, dependency tracking will simply be disabled for
6503
your build.
6504
6505
@cindex @command{depcomp}
6506
6507
Experience with earlier versions of Automake (@pxref{Dependency
6508
Tracking Evolution}) taught us that it is not reliable to generate
6509
dependencies only on the maintainer's system, as configurations vary
6510
too much. So instead Automake implements dependency tracking at build
6511
time.
6512
6513
Automatic dependency tracking can be suppressed by putting
6514
@option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6515
passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6516
(this should be the preferred way). Or, you can invoke @command{automake}
6517
with the @option{-i} option. Dependency tracking is enabled by default.
6518
6519
@vindex AUTOMAKE_OPTIONS
6520
@opindex no-dependencies
6521
6522
The person building your package also can choose to disable dependency
6523
tracking by configuring with @option{--disable-dependency-tracking}.
6524
6525
@cindex Disabling dependency tracking
6526
@cindex Dependency tracking, disabling
6527
6528
6529
@node EXEEXT
6530
@section Support for executable extensions
6531
6532
@cindex Executable extension
6533
@cindex Extension, executable
6534
@cindex Windows
6535
6536
On some platforms, such as Windows, executables are expected to have an
6537
extension such as @file{.exe}. On these platforms, some compilers (GCC
6538
among them) will automatically generate @file{foo.exe} when asked to
6539
generate @file{foo}.
6540
6541
Automake provides mostly-transparent support for this. Unfortunately
6542
@emph{mostly} doesn't yet mean @emph{fully}. Until the English
6543
dictionary is revised, you will have to assist Automake if your package
6544
must support those platforms.
6545
6546
One thing you must be aware of is that, internally, Automake rewrites
6547
something like this:
6548
6549
@example
6550
bin_PROGRAMS = liver
6551
@end example
6552
6553
to this:
6554
6555
@example
6556
bin_PROGRAMS = liver$(EXEEXT)
6557
@end example
6558
6559
The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6560
extension.
6561
6562
The variables @code{TESTS}, @code{XFAIL_TESTS} (@pxref{Tests}) are also
6563
rewritten if it contains filenames that have been declared as programs
6564
in the same @file{Makefile}. (This is mostly useful when some programs
6565
from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6566
6567
However, Automake cannot apply this rewriting to @command{configure}
6568
substitutions. This means that if you are conditionally building a
6569
program using such a substitution, then your @file{configure.ac} must
6570
take care to add @samp{$(EXEEXT)} when constructing the output variable.
6571
6572
With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6573
to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6574
automatically if you configure a compiler (say, through
6575
@code{AC_PROG_CC}).
6576
6577
Sometimes maintainers like to write an explicit link rule for their
6578
program. Without executable extension support, this is easy---you
6579
simply write a rule whose target is the name of the program. However,
6580
when executable extension support is enabled, you must instead add the
6581
@samp{$(EXEEXT)} suffix.
6582
6583
Unfortunately, due to the change in Autoconf 2.50, this means you must
6584
always add this extension. However, this is a problem for maintainers
6585
who know their package will never run on a platform that has
6586
executable extensions. For those maintainers, the @option{no-exeext}
6587
option (@pxref{Options}) will disable this feature. This works in a
6588
fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6589
rule for a target named @code{foo} in @file{Makefile.am} will override
6590
an automake-generated rule for @samp{foo$(EXEEXT)}. Without
6591
the @option{no-exeext} option, this use will give a diagnostic.
6592
6593
6594
@node Other objects
6595
@chapter Other Derived Objects
6596
6597
Automake can handle derived objects that are not C programs. Sometimes
6598
the support for actually building such objects must be explicitly
6599
supplied, but Automake will still automatically handle installation and
6600
distribution.
6601
6602
@menu
6603
* Scripts:: Executable scripts
6604
* Headers:: Header files
6605
* Data:: Architecture-independent data files
6606
* Sources:: Derived sources
6607
@end menu
6608
6609
6610
@node Scripts
6611
@section Executable Scripts
6612
6613
@cindex @code{_SCRIPTS} primary, defined
6614
@cindex @code{SCRIPTS} primary, defined
6615
@cindex Primary variable, @code{SCRIPTS}
6616
@vindex _SCRIPTS
6617
@cindex Installing scripts
6618
6619
It is possible to define and install programs that are scripts. Such
6620
programs are listed using the @code{SCRIPTS} primary name. When the
6621
script is distributed in its final, installable form, the
6622
@file{Makefile} usually looks as follows:
6623
@vindex SCRIPTS
6624
6625
@example
6626
# Install my_script in $(bindir) and distribute it.
6627
dist_bin_SCRIPTS = my_script
6628
@end example
6629
6630
Script are not distributed by default; as we have just seen, those
6631
that should be distributed can be specified using a @code{dist_}
6632
prefix as with other primaries.
6633
6634
@cindex @code{SCRIPTS}, installation directories
6635
@vindex bin_SCRIPTS
6636
@vindex sbin_SCRIPTS
6637
@vindex libexec_SCRIPTS
6638
@vindex pkgdata_SCRIPTS
6639
@vindex noinst_SCRIPTS
6640
@vindex check_SCRIPTS
6641
6642
Scripts can be installed in @code{bindir}, @code{sbindir},
6643
@code{libexecdir}, or @code{pkgdatadir}.
6644
6645
Scripts that need not being installed can be listed in
6646
@code{noinst_SCRIPTS}, and among them, those which are needed only by
6647
@samp{make check} should go in @code{check_SCRIPTS}.
6648
6649
When a script needs to be built, the @file{Makefile.am} should include
6650
the appropriate rules. For instance the @command{automake} program
6651
itself is a Perl script that is generated from @file{automake.in}.
6652
Here is how this is handled:
6653
6654
@example
6655
bin_SCRIPTS = automake
6656
CLEANFILES = $(bin_SCRIPTS)
6657
EXTRA_DIST = automake.in
6658
6659
do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
6660
-e 's,[@@]PERL[@@],$(PERL),g' \
6661
-e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
6662
-e 's,[@@]VERSION[@@],$(VERSION),g' \
6663
@dots{}
6664
6665
automake: automake.in Makefile
6666
$(do_subst) < $(srcdir)/automake.in > automake
6667
chmod +x automake
6668
@end example
6669
6670
Such scripts for which a build rule has been supplied need to be
6671
deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
6672
sources have to be distributed, usually with @code{EXTRA_DIST}
6673
(@pxref{Dist}).
6674
6675
Another common way to build scripts is to process them from
6676
@file{configure} with @code{AC_CONFIG_FILES}. In this situation
6677
Automake knows which files should be cleaned and distributed, and what
6678
the rebuild rules should look like.
6679
6680
For instance if @file{configure.ac} contains
6681
6682
@example
6683
AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
6684
@end example
6685
6686
@noindent
6687
to build @file{src/my_script} from @file{src/my_script.in}, then an
6688
@file{src/Makefile.am} to install this script in @code{$(bindir)} can
6689
be as simple as
6690
6691
@example
6692
bin_SCRIPTS = my_script
6693
CLEANFILES = $(bin_SCRIPTS)
6694
@end example
6695
6696
@noindent
6697
There is no need for @code{EXTRA_DIST} or any build rule: Automake
6698
infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
6699
@code{CLEANFILES} is still useful, because by default Automake will
6700
clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
6701
@code{clean}.
6702
6703
Although this looks simpler, building scripts this way has one
6704
drawback: directory variables such as @code{$(datadir)} are not fully
6705
expanded and may refer to other directory variables.
6706
6707
@node Headers
6708
@section Header files
6709
6710
@cindex @code{_HEADERS} primary, defined
6711
@cindex @code{HEADERS} primary, defined
6712
@cindex Primary variable, @code{HEADERS}
6713
@vindex _HEADERS
6714
@vindex noinst_HEADERS
6715
@cindex @code{HEADERS}, installation directories
6716
@cindex Installing headers
6717
@vindex include_HEADERS
6718
@vindex oldinclude_HEADERS
6719
@vindex pkginclude_HEADERS
6720
6721
6722
Header files that must be installed are specified by the
6723
@code{HEADERS} family of variables. Headers can be installed in
6724
@code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
6725
other directory you may have defined (@pxref{Uniform}). For instance,
6726
6727
@example
6728
include_HEADERS = foo.h bar/bar.h
6729
@end example
6730
6731
@noindent
6732
will install the two files as @file{$(includedir)/foo.h} and
6733
@file{$(includedir)/bar.h}.
6734
6735
The @code{nobase_} prefix is also supported,
6736
6737
@example
6738
nobase_include_HEADERS = foo.h bar/bar.h
6739
@end example
6740
6741
@noindent
6742
will install the two files as @file{$(includedir)/foo.h} and
6743
@file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
6744
6745
@vindex noinst_HEADERS
6746
Usually, only header files that accompany installed libraries need to
6747
be installed. Headers used by programs or convenience libraries are
6748
not installed. The @code{noinst_HEADERS} variable can be used for
6749
such headers. However when the header actually belongs to one
6750
convenient library or program, we recommend listing it in the
6751
program's or library's @code{_SOURCES} variable (@pxref{Program
6752
Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
6753
the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
6754
right variable to use in a directory containing only headers and no
6755
associated library or program.
6756
6757
All header files must be listed somewhere; in a @code{_SOURCES}
6758
variable or in a @code{_HEADERS} variable. Missing ones will not
6759
appear in the distribution.
6760
6761
For header files that are built and must not be distributed, use the
6762
@code{nodist_} prefix as in @code{nodist_include_HEADERS} or
6763
@code{nodist_prog_SOURCES}. If these generated headers are needed
6764
during the build, you must also ensure they exist before they are
6765
used (@pxref{Sources}).
6766
6767
6768
@node Data
6769
@section Architecture-independent data files
6770
6771
@cindex @code{_DATA} primary, defined
6772
@cindex @code{DATA} primary, defined
6773
@cindex Primary variable, @code{DATA}
6774
@vindex _DATA
6775
6776
Automake supports the installation of miscellaneous data files using the
6777
@code{DATA} family of variables.
6778
@vindex DATA
6779
6780
@vindex data_DATA
6781
@vindex sysconf_DATA
6782
@vindex sharedstate_DATA
6783
@vindex localstate_DATA
6784
@vindex pkgdata_DATA
6785
6786
Such data can be installed in the directories @code{datadir},
6787
@code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
6788
@code{pkgdatadir}.
6789
6790
By default, data files are @emph{not} included in a distribution. Of
6791
course, you can use the @code{dist_} prefix to change this on a
6792
per-variable basis.
6793
6794
Here is how Automake declares its auxiliary data files:
6795
6796
@example
6797
dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
6798
@end example
6799
6800
6801
@node Sources
6802
@section Built sources
6803
6804
Because Automake's automatic dependency tracking works as a side-effect
6805
of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
6806
target should not be compiled before its dependencies are made, but
6807
these dependencies are unknown until the target is first compiled.
6808
6809
Ordinarily this is not a problem, because dependencies are distributed
6810
sources: they preexist and do not need to be built. Suppose that
6811
@file{foo.c} includes @file{foo.h}. When it first compiles
6812
@file{foo.o}, @command{make} only knows that @file{foo.o} depends on
6813
@file{foo.c}. As a side-effect of this compilation @command{depcomp}
6814
records the @file{foo.h} dependency so that following invocations of
6815
@command{make} will honor it. In these conditions, it's clear there is
6816
no problem: either @file{foo.o} doesn't exist and has to be built
6817
(regardless of the dependencies), or accurate dependencies exist and
6818
they can be used to decide whether @file{foo.o} should be rebuilt.
6819
6820
It's a different story if @file{foo.h} doesn't exist by the first
6821
@command{make} run. For instance, there might be a rule to build
6822
@file{foo.h}. This time @file{file.o}'s build will fail because the
6823
compiler can't find @file{foo.h}. @command{make} failed to trigger the
6824
rule to build @file{foo.h} first by lack of dependency information.
6825
6826
@vindex BUILT_SOURCES
6827
@cindex @code{BUILT_SOURCES}, defined
6828
6829
The @code{BUILT_SOURCES} variable is a workaround for this problem. A
6830
source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
6831
or @samp{make check} (or even @samp{make install}) before other
6832
targets are processed. However, such a source file is not
6833
@emph{compiled} unless explicitly requested by mentioning it in some
6834
other @code{_SOURCES} variable.
6835
6836
So, to conclude our introductory example, we could use
6837
@samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
6838
any other target (including @file{foo.o}) during @samp{make all} or
6839
@samp{make check}.
6840
6841
@code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
6842
must be created early in the build process can be listed in this
6843
variable. Moreover, all built sources do not necessarily have to be
6844
listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
6845
doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
6846
another source), because it's a known dependency of the associated
6847
object.
6848
6849
It might be important to emphasize that @code{BUILT_SOURCES} is
6850
honored only by @samp{make all}, @samp{make check} and @samp{make
6851
install}. This means you cannot build a specific target (e.g.,
6852
@samp{make foo}) in a clean tree if it depends on a built source.
6853
However it will succeed if you have run @samp{make all} earlier,
6854
because accurate dependencies are already available.
6855
6856
The next section illustrates and discusses the handling of built sources
6857
on a toy example.
6858
6859
@menu
6860
* Built sources example:: Several ways to handle built sources.
6861
@end menu
6862
6863
@node Built sources example
6864
@subsection Built sources example
6865
6866
Suppose that @file{foo.c} includes @file{bindir.h}, which is
6867
installation-dependent and not distributed: it needs to be built. Here
6868
@file{bindir.h} defines the preprocessor macro @code{bindir} to the
6869
value of the @command{make} variable @code{bindir} (inherited from
6870
@file{configure}).
6871
6872
We suggest several implementations below. It's not meant to be an
6873
exhaustive listing of all ways to handle built sources, but it will give
6874
you a few ideas if you encounter this issue.
6875
6876
@unnumberedsubsec First try
6877
6878
This first implementation will illustrate the bootstrap issue mentioned
6879
in the previous section (@pxref{Sources}).
6880
6881
Here is a tentative @file{Makefile.am}.
6882
6883
@example
6884
# This won't work.
6885
bin_PROGRAMS = foo
6886
foo_SOURCES = foo.c
6887
nodist_foo_SOURCES = bindir.h
6888
CLEANFILES = bindir.h
6889
bindir.h: Makefile
6890
echo '#define bindir "$(bindir)"' >$@@
6891
@end example
6892
6893
This setup doesn't work, because Automake doesn't know that @file{foo.c}
6894
includes @file{bindir.h}. Remember, automatic dependency tracking works
6895
as a side-effect of compilation, so the dependencies of @file{foo.o} will
6896
be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
6897
The symptom is as follows.
6898
6899
@example
6900
% make
6901
source='foo.c' object='foo.o' libtool=no \
6902
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6903
depmode=gcc /bin/sh ./depcomp \
6904
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6905
foo.c:2: bindir.h: No such file or directory
6906
make: *** [foo.o] Error 1
6907
@end example
6908
6909
In this example @file{bindir.h} is not distributed nor installed, and
6910
it is not even being built on-time. One may wonder if the
6911
@samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
6912
line simply states that @file{bindir.h} is a source of @code{foo}, so
6913
for instance, it should be inspected while generating tags
6914
(@pxref{Tags}). In other words, it does not help our present problem,
6915
and the build would fail identically without it.
6916
6917
@unnumberedsubsec Using @code{BUILT_SOURCES}
6918
6919
A solution is to require @file{bindir.h} to be built before anything
6920
else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
6921
6922
@example
6923
bin_PROGRAMS = foo
6924
foo_SOURCES = foo.c
6925
nodist_foo_SOURCES = bindir.h
6926
BUILT_SOURCES = bindir.h
6927
CLEANFILES = bindir.h
6928
bindir.h: Makefile
6929
echo '#define bindir "$(bindir)"' >$@@
6930
@end example
6931
6932
See how @file{bindir.h} get built first:
6933
6934
@example
6935
% make
6936
echo '#define bindir "/usr/local/bin"' >bindir.h
6937
make all-am
6938
make[1]: Entering directory `/home/adl/tmp'
6939
source='foo.c' object='foo.o' libtool=no \
6940
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6941
depmode=gcc /bin/sh ./depcomp \
6942
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6943
gcc -g -O2 -o foo foo.o
6944
make[1]: Leaving directory `/home/adl/tmp'
6945
@end example
6946
6947
However, as said earlier, @code{BUILT_SOURCES} applies only to the
6948
@code{all}, @code{check}, and @code{install} targets. It still fails
6949
if you try to run @samp{make foo} explicitly:
6950
6951
@example
6952
% make clean
6953
test -z "bindir.h" || rm -f bindir.h
6954
test -z "foo" || rm -f foo
6955
rm -f *.o
6956
% : > .deps/foo.Po # Suppress previously recorded dependencies
6957
% make foo
6958
source='foo.c' object='foo.o' libtool=no \
6959
depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6960
depmode=gcc /bin/sh ./depcomp \
6961
gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6962
foo.c:2: bindir.h: No such file or directory
6963
make: *** [foo.o] Error 1
6964
@end example
6965
6966
@unnumberedsubsec Recording dependencies manually
6967
6968
Usually people are happy enough with @code{BUILT_SOURCES} because they
6969
never build targets such as @samp{make foo} before @samp{make all}, as
6970
in the previous example. However if this matters to you, you can
6971
avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
6972
the @file{Makefile.am}.
6973
6974
@example
6975
bin_PROGRAMS = foo
6976
foo_SOURCES = foo.c
6977
nodist_foo_SOURCES = bindir.h
6978
foo.$(OBJEXT): bindir.h
6979
CLEANFILES = bindir.h
6980
bindir.h: Makefile
6981
echo '#define bindir "$(bindir)"' >$@@
6982
@end example
6983
6984
You don't have to list @emph{all} the dependencies of @file{foo.o}
6985
explicitly, only those that might need to be built. If a dependency
6986
already exists, it will not hinder the first compilation and will be
6987
recorded by the normal dependency tracking code. (Note that after
6988
this first compilation the dependency tracking code will also have
6989
recorded the dependency between @file{foo.o} and
6990
@file{bindir.h}; so our explicit dependency is really useful to
6991
the first build only.)
6992
6993
Adding explicit dependencies like this can be a bit dangerous if you are
6994
not careful enough. This is due to the way Automake tries not to
6995
overwrite your rules (it assumes you know better than it).
6996
@samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
6997
output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
6998
because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
6999
target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7000
Always check the generated @file{Makefile.in} if you do this.
7001
7002
@unnumberedsubsec Build @file{bindir.h} from @file{configure}
7003
7004
It's possible to define this preprocessor macro from @file{configure},
7005
either in @file{config.h} (@pxref{Defining Directories, , Defining
7006
Directories, autoconf, The Autoconf Manual}), or by processing a
7007
@file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7008
(@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7009
Autoconf Manual}).
7010
7011
At this point it should be clear that building @file{bindir.h} from
7012
@file{configure} work well for this example. @file{bindir.h} will exist
7013
before you build any target, hence will not cause any dependency issue.
7014
7015
The Makefile can be shrunk as follows. We do not even have to mention
7016
@file{bindir.h}.
7017
7018
@example
7019
bin_PROGRAMS = foo
7020
foo_SOURCES = foo.c
7021
@end example
7022
7023
However, it's not always possible to build sources from
7024
@file{configure}, especially when these sources are generated by a tool
7025
that needs to be built first...
7026
7027
@unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
7028
7029
Another attractive idea is to define @code{bindir} as a variable or
7030
function exported from @file{bindir.o}, and build @file{bindir.c}
7031
instead of @file{bindir.h}.
7032
7033
@example
7034
noinst_PROGRAMS = foo
7035
foo_SOURCES = foo.c bindir.h
7036
nodist_foo_SOURCES = bindir.c
7037
CLEANFILES = bindir.c
7038
bindir.c: Makefile
7039
echo 'const char bindir[] = "$(bindir)";' >$@@
7040
@end example
7041
7042
@file{bindir.h} contains just the variable's declaration and doesn't
7043
need to be built, so it won't cause any trouble. @file{bindir.o} is
7044
always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7045
first.
7046
7047
@unnumberedsubsec Which is best?
7048
7049
There is no panacea, of course. Each solution has its merits and
7050
drawbacks.
7051
7052
You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7053
foo} on a clean tree is important to you.
7054
7055
You won't add explicit dependencies if you are leery of overriding
7056
an Automake rule by mistake.
7057
7058
Building files from @file{./configure} is not always possible, neither
7059
is converting @file{.h} files into @file{.c} files.
7060
7061
7062
@node Other GNU Tools
7063
@chapter Other GNU Tools
7064
7065
Since Automake is primarily intended to generate @file{Makefile.in}s for
7066
use in GNU programs, it tries hard to interoperate with other GNU tools.
7067
7068
@menu
7069
* Emacs Lisp:: Emacs Lisp
7070
* gettext:: Gettext
7071
* Libtool:: Libtool
7072
* Java:: Java
7073
* Python:: Python
7074
@end menu
7075
7076
7077
@node Emacs Lisp
7078
@section Emacs Lisp
7079
7080
@cindex @code{_LISP} primary, defined
7081
@cindex @code{LISP} primary, defined
7082
@cindex Primary variable, @code{LISP}
7083
7084
@vindex _LISP
7085
@vindex lisp_LISP
7086
@vindex noinst_LISP
7087
7088
Automake provides some support for Emacs Lisp. The @code{LISP} primary
7089
is used to hold a list of @file{.el} files. Possible prefixes for this
7090
primary are @code{lisp_} and @code{noinst_}. Note that if
7091
@code{lisp_LISP} is defined, then @file{configure.ac} must run
7092
@code{AM_PATH_LISPDIR} (@pxref{Macros}).
7093
7094
@vindex dist_lisp_LISP
7095
@vindex dist_noinst_LISP
7096
Lisp sources are not distributed by default. You can prefix the
7097
@code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7098
@code{dist_noinst_LISP}, to indicate that these files should be
7099
distributed.
7100
7101
Automake will byte-compile all Emacs Lisp source files using the Emacs
7102
found by @code{AM_PATH_LISPDIR}, if any was found.
7103
7104
Byte-compiled Emacs Lisp files are not portable among all versions of
7105
Emacs, so it makes sense to turn this off if you expect sites to have
7106
more than one version of Emacs installed. Furthermore, many packages
7107
don't actually benefit from byte-compilation. Still, we recommend
7108
that you byte-compile your Emacs Lisp sources. It is probably better
7109
for sites with strange setups to cope for themselves than to make the
7110
installation less nice for everybody else.
7111
7112
There are two ways to avoid byte-compiling. Historically, we have
7113
recommended the following construct.
7114
@example
7115
lisp_LISP = file1.el file2.el
7116
ELCFILES =
7117
@end example
7118
@noindent
7119
@code{ELCFILES} is an internal Automake variable that normally lists
7120
all @file{.elc} files that must be byte-compiled. Automake defines
7121
@code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7122
variable explicitly prevents byte-compilation to occur.
7123
7124
Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
7125
in
7126
@example
7127
lisp_DATA = file1.el file2.el
7128
@end example
7129
7130
Note that these two constructs are not equivalent. @code{_LISP} will
7131
not install a file if Emacs is not installed, while @code{_DATA} will
7132
always install its files.
7133
7134
@node gettext
7135
@section Gettext
7136
7137
@cindex GNU Gettext support
7138
@cindex Gettext support
7139
@cindex Support for GNU Gettext
7140
7141
If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7142
turns on support for GNU gettext, a message catalog system for
7143
internationalization
7144
(@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7145
7146
The @code{gettext} support in Automake requires the addition of one or
7147
two subdirectories to the package, @file{po} and possibly also @file{intl}.
7148
The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7149
@samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7150
Automake ensures that these directories exist and are mentioned in
7151
@code{SUBDIRS}.
7152
7153
@node Libtool
7154
@section Libtool
7155
7156
Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7157
libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7158
@xref{A Shared Library}.
7159
7160
7161
@node Java
7162
@section Java
7163
7164
@cindex @code{_JAVA} primary, defined
7165
@cindex @code{JAVA} primary, defined
7166
@cindex Primary variable, @code{JAVA}
7167
7168
Automake provides some minimal support for Java compilation with the
7169
@code{JAVA} primary.
7170
7171
Any @file{.java} files listed in a @code{_JAVA} variable will be
7172
compiled with @code{JAVAC} at build time. By default, @file{.java}
7173
files are not included in the distribution, you should use the
7174
@code{dist_} prefix to distribute them.
7175
7176
Here is a typical setup for distributing @file{.java} files and
7177
installing the @file{.class} files resulting from their compilation.
7178
7179
@example
7180
javadir = $(datadir)/java
7181
dist_java_JAVA = a.java b.java @dots{}
7182
@end example
7183
7184
@cindex @code{JAVA} restrictions
7185
@cindex Restrictions for @code{JAVA}
7186
7187
Currently Automake enforces the restriction that only one @code{_JAVA}
7188
primary can be used in a given @file{Makefile.am}. The reason for this
7189
restriction is that, in general, it isn't possible to know which
7190
@file{.class} files were generated from which @file{.java} files, so
7191
it would be impossible to know which files to install where. For
7192
instance, a @file{.java} file can define multiple classes; the resulting
7193
@file{.class} file names cannot be predicted without parsing the
7194
@file{.java} file.
7195
7196
There are a few variables that are used when compiling Java sources:
7197
7198
@vtable @code
7199
@item JAVAC
7200
The name of the Java compiler. This defaults to @samp{javac}.
7201
7202
@item JAVACFLAGS
7203
The flags to pass to the compiler. This is considered to be a user
7204
variable (@pxref{User Variables}).
7205
7206
@item AM_JAVACFLAGS
7207
More flags to pass to the Java compiler. This, and not
7208
@code{JAVACFLAGS}, should be used when it is necessary to put Java
7209
compiler flags into @file{Makefile.am}.
7210
7211
@item JAVAROOT
7212
The value of this variable is passed to the @option{-d} option to
7213
@code{javac}. It defaults to @samp{$(top_builddir)}.
7214
7215
@item CLASSPATH_ENV
7216
This variable is an @code{sh} expression that is used to set the
7217
@env{CLASSPATH} environment variable on the @code{javac} command line.
7218
(In the future we will probably handle class path setting differently.)
7219
@end vtable
7220
7221
7222
@node Python
7223
@section Python
7224
7225
@cindex @code{_PYTHON} primary, defined
7226
@cindex @code{PYTHON} primary, defined
7227
@cindex Primary variable, @code{PYTHON}
7228
@vindex _PYTHON
7229
7230
Automake provides support for Python compilation with the
7231
@code{PYTHON} primary. A typical setup is to call
7232
@code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7233
following in @file{Makefile.am}:
7234
7235
@example
7236
python_PYTHON = tree.py leave.py
7237
@end example
7238
7239
Any files listed in a @code{_PYTHON} variable will be byte-compiled
7240
with @command{py-compile} at install time. @command{py-compile}
7241
actually creates both standard (@file{.pyc}) and optimized
7242
(@file{.pyo}) byte-compiled versions of the source files. Note that
7243
because byte-compilation occurs at install time, any files listed in
7244
@code{noinst_PYTHON} will not be compiled. Python source files are
7245
included in the distribution by default, prepend @code{nodist_} (as in
7246
@code{nodist_python_PYTHON}) to omit them.
7247
7248
Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7249
that will determine some Python-related directory variables (see
7250
below). If you have called @code{AM_PATH_PYTHON} from
7251
@file{configure.ac}, then you may use the variables
7252
@code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7253
files in your @file{Makefile.am}, depending where you want your files
7254
installed (see the definitions of @code{pythondir} and
7255
@code{pkgpythondir} below).
7256
7257
@defmac AM_PATH_PYTHON ([@var{VERSION}], [@var{ACTION-IF-FOUND}], [@var{ACTION-IF-NOT-FOUND}])
7258
7259
Search for a Python interpreter on the system. This macro takes three
7260
optional arguments. The first argument, if present, is the minimum
7261
version of Python required for this package: @code{AM_PATH_PYTHON}
7262
will skip any Python interpreter that is older than @var{VERSION}.
7263
If an interpreter is found and satisfies @var{VERSION}, then
7264
@var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is
7265
run.
7266
7267
If @var{ACTION-IF-NOT-FOUND} is not specified, as in the following
7268
example, the default is to abort @command{configure}.
7269
7270
@example
7271
AM_PATH_PYTHON([2.2])
7272
@end example
7273
7274
@noindent
7275
This is fine when Python is an absolute requirement for the package.
7276
If Python >= 2.2 was only @emph{optional} to the package,
7277
@code{AM_PATH_PYTHON} could be called as follows.
7278
7279
@example
7280
AM_PATH_PYTHON([2.2],, [:])
7281
@end example
7282
7283
@code{AM_PATH_PYTHON} creates the following output variables based on
7284
the Python installation found during configuration.
7285
@end defmac
7286
7287
@vtable @code
7288
@item PYTHON
7289
The name of the Python executable, or @samp{:} if no suitable
7290
interpreter could be found.
7291
7292
Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
7293
will abort if Python is absent), the value of @code{PYTHON} can be used
7294
to setup a conditional in order to disable the relevant part of a build
7295
as follows.
7296
7297
@example
7298
AM_PATH_PYTHON(,, [:])
7299
AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7300
@end example
7301
7302
@item PYTHON_VERSION
7303
The Python version number, in the form @var{major}.@var{minor}
7304
(e.g., @samp{1.5}). This is currently the value of
7305
@samp{sys.version[:3]}.
7306
7307
@item PYTHON_PREFIX
7308
The string @samp{$@{prefix@}}. This term may be used in future work
7309
that needs the contents of Python's @samp{sys.prefix}, but general
7310
consensus is to always use the value from configure.
7311
7312
@item PYTHON_EXEC_PREFIX
7313
The string @samp{$@{exec_prefix@}}. This term may be used in future work
7314
that needs the contents of Python's @samp{sys.exec_prefix}, but general
7315
consensus is to always use the value from configure.
7316
7317
@item PYTHON_PLATFORM
7318
The canonical name used by Python to describe the operating system, as
7319
given by @samp{sys.platform}. This value is sometimes needed when
7320
building Python extensions.
7321
7322
@item pythondir
7323
The directory name for the @file{site-packages} subdirectory of the
7324
standard Python install tree.
7325
7326
@item pkgpythondir
7327
This is the directory under @code{pythondir} that is named after the
7328
package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7329
as a convenience.
7330
7331
@item pyexecdir
7332
This is the directory where Python extension modules (shared libraries)
7333
should be installed. An extension module written in C could be declared
7334
as follows to Automake:
7335
7336
@example
7337
pyexec_LTLIBRARIES = quaternion.la
7338
quaternion_SOURCES = quaternion.c support.c support.h
7339
quaternion_la_LDFLAGS = -avoid-version -module
7340
@end example
7341
7342
@item pkgpyexecdir
7343
This is a convenience variable that is defined as
7344
@samp{$(pyexecdir)/$(PACKAGE)}.
7345
@end vtable
7346
7347
All these directory variables have values that start with either
7348
@samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7349
fine in @file{Makefiles}, but it makes these variables hard to use in
7350
@file{configure}. This is mandated by the GNU coding standards, so
7351
that the user can run @samp{make prefix=/foo install}. The Autoconf
7352
manual has a section with more details on this topic
7353
(@pxref{Installation Directory Variables, , Installation Directory
7354
Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7355
Install Paths}.
7356
7357
7358
@node Documentation
7359
@chapter Building documentation
7360
7361
Currently Automake provides support for Texinfo and man pages.
7362
7363
@menu
7364
* Texinfo:: Texinfo
7365
* Man pages:: Man pages
7366
@end menu
7367
7368
7369
@node Texinfo
7370
@section Texinfo
7371
7372
@cindex @code{_TEXINFOS} primary, defined
7373
@cindex @code{TEXINFOS} primary, defined
7374
@cindex Primary variable, @code{TEXINFOS}
7375
@cindex HTML output using Texinfo
7376
@cindex PDF output using Texinfo
7377
@cindex PS output using Texinfo
7378
@cindex DVI output using Texinfo
7379
@vindex _TEXINFOS
7380
@vindex info_TEXINFOS
7381
7382
If the current directory contains Texinfo source, you must declare it
7383
with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7384
into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7385
here. Any Texinfo source file must end in the @file{.texi},
7386
@file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7387
for new manuals.
7388
7389
Automake generates rules to build @file{.info}, @file{.dvi},
7390
@file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7391
sources. Following the GNU Coding Standards, only the @file{.info}
7392
files are built by @samp{make all} and installed by @samp{make
7393
install} (unless you use @option{no-installinfo}, see below).
7394
Furthermore, @file{.info} files are automatically distributed so that
7395
Texinfo is not a prerequisite for installing your package.
7396
7397
@trindex dvi
7398
@trindex html
7399
@trindex pdf
7400
@trindex ps
7401
@trindex install-dvi
7402
@trindex install-html
7403
@trindex install-pdf
7404
@trindex install-ps
7405
Other documentation formats can be built on request by @samp{make
7406
dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7407
can be installed with @samp{make install-dvi}, @samp{make install-ps},
7408
@samp{make install-pdf} and @samp{make install-html} explicitly.
7409
@samp{make uninstall} will remove everything: the Texinfo
7410
documentation installed by default as well as all the above optional
7411
formats.
7412
7413
All these targets can be extended using @samp{-local} rules
7414
(@pxref{Extending}).
7415
7416
@cindex Texinfo flag, @code{VERSION}
7417
@cindex Texinfo flag, @code{UPDATED}
7418
@cindex Texinfo flag, @code{EDITION}
7419
@cindex Texinfo flag, @code{UPDATED-MONTH}
7420
7421
@cindex @code{VERSION} Texinfo flag
7422
@cindex @code{UPDATED} Texinfo flag
7423
@cindex @code{EDITION} Texinfo flag
7424
@cindex @code{UPDATED-MONTH} Texinfo flag
7425
7426
@cindex @file{mdate-sh}
7427
7428
If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7429
that file will be automatically generated. The file @file{version.texi}
7430
defines four Texinfo flag you can reference using
7431
@code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7432
@code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7433
7434
@table @code
7435
@item EDITION
7436
@itemx VERSION
7437
Both of these flags hold the version number of your program. They are
7438
kept separate for clarity.
7439
7440
@item UPDATED
7441
This holds the date the primary @file{.texi} file was last modified.
7442
7443
@item UPDATED-MONTH
7444
This holds the name of the month in which the primary @file{.texi} file
7445
was last modified.
7446
@end table
7447
7448
The @file{version.texi} support requires the @command{mdate-sh}
7449
script; this script is supplied with Automake and automatically
7450
included when @command{automake} is invoked with the
7451
@option{--add-missing} option.
7452
7453
If you have multiple Texinfo files, and you want to use the
7454
@file{version.texi} feature, then you have to have a separate version
7455
file for each Texinfo file. Automake will treat any include in a
7456
Texinfo file that matches @file{vers*.texi} just as an automatically
7457
generated version file.
7458
7459
Sometimes an info file actually depends on more than one @file{.texi}
7460
file. For instance, in GNU Hello, @file{hello.texi} includes the file
7461
@file{gpl.texi}. You can tell Automake about these dependencies using
7462
the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7463
@vindex TEXINFOS
7464
@vindex _TEXINFOS
7465
7466
@example
7467
info_TEXINFOS = hello.texi
7468
hello_TEXINFOS = gpl.texi
7469
@end example
7470
7471
@cindex @file{texinfo.tex}
7472
7473
By default, Automake requires the file @file{texinfo.tex} to appear in
7474
the same directory as the @file{Makefile.am} file that lists the
7475
@file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7476
@file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7477
autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7478
there. In both cases, automake then supplies @file{texinfo.tex} if
7479
@option{--add-missing} is given, and takes care of its distribution.
7480
However, if you set the @code{TEXINFO_TEX} variable (see below),
7481
it overrides the location of the file and turns off its installation
7482
into the source as well as its distribution.
7483
7484
The option @option{no-texinfo.tex} can be used to eliminate the
7485
requirement for the file @file{texinfo.tex}. Use of the variable
7486
@code{TEXINFO_TEX} is preferable, however, because that allows the
7487
@code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7488
7489
@cindex Option, @code{no-installinfo}
7490
@cindex Target, @code{install-info}
7491
@cindex @code{install-info} target
7492
@cindex @code{no-installinfo} option
7493
7494
@opindex no-installinfo
7495
@trindex install-info
7496
7497
Automake generates an @code{install-info} rule; some people apparently
7498
use this. By default, info pages are installed by @samp{make
7499
install}, so running @code{make install-info} is pointless. This can
7500
be prevented via the @code{no-installinfo} option. In this case,
7501
@file{.info} files are not installed by default, and user must
7502
request this explicitly using @samp{make install-info}
7503
7504
The following variables are used by the Texinfo build rules.
7505
7506
@vtable @code
7507
@item MAKEINFO
7508
The name of the program invoked to build @file{.info} files. This
7509
variable is defined by Automake. If the @command{makeinfo} program is
7510
found on the system then it will be used by default; otherwise
7511
@command{missing} will be used instead.
7512
7513
@item MAKEINFOHTML
7514
The command invoked to build @file{.html} files. Automake
7515
defines this to @samp{$(MAKEINFO) --html}.
7516
7517
@item MAKEINFOFLAGS
7518
User flags passed to each invocation of @samp{$(MAKEINFO)} and
7519
@samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7520
not expected to be defined in any @file{Makefile}; it can be used by
7521
users to pass extra flags to suit their needs.
7522
7523
@item AM_MAKEINFOFLAGS
7524
@itemx AM_MAKEINFOHTMLFLAGS
7525
Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7526
@code{MAKEINFOFLAGS}, these variables are meant to be defined by
7527
maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7528
passed to @code{makeinfo} when building @file{.info} files; and
7529
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7530
files.
7531
7532
For instance, the following setting can be used to obtain one single
7533
@file{.html} file per manual, without node separators.
7534
@example
7535
AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7536
@end example
7537
7538
@code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7539
This means that defining @code{AM_MAKEINFOFLAGS} without defining
7540
@code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7541
and @file{.html} files.
7542
7543
@item TEXI2DVI
7544
The name of the command that converts a @file{.texi} file into a
7545
@file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7546
with the Texinfo package.
7547
7548
@item TEXI2PDF
7549
The name of the command that translates a @file{.texi} file into a
7550
@file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7551
7552
@item DVIPS
7553
The name of the command that build a @file{.ps} file out of a
7554
@file{.dvi} file. This defaults to @samp{dvips}.
7555
7556
@item TEXINFO_TEX
7557
7558
If your package has Texinfo files in many directories, you can use the
7559
variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7560
@file{texinfo.tex} for your package. The value of this variable should
7561
be the relative path from the current @file{Makefile.am} to
7562
@file{texinfo.tex}:
7563
7564
@example
7565
TEXINFO_TEX = ../doc/texinfo.tex
7566
@end example
7567
@end vtable
7568
7569
7570
@node Man pages
7571
@section Man pages
7572
7573
@cindex @code{_MANS} primary, defined
7574
@cindex @code{MANS} primary, defined
7575
@cindex Primary variable, @code{MANS}
7576
7577
@vindex _MANS
7578
@vindex man_MANS
7579
A package can also include man pages (but see the GNU standards on this
7580
matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7581
pages are declared using the @code{MANS} primary. Generally the
7582
@code{man_MANS} variable is used. Man pages are automatically installed in
7583
the correct subdirectory of @code{mandir}, based on the file extension.
7584
7585
File extensions such as @file{.1c} are handled by looking for the valid
7586
part of the extension and using that to determine the correct
7587
subdirectory of @code{mandir}. Valid section names are the digits
7588
@samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7589
7590
Sometimes developers prefer to name a man page something like
7591
@file{foo.man} in the source, and then rename it to have the correct
7592
suffix, for example @file{foo.1}, when installing the file. Automake
7593
also supports this mode. For a valid section named @var{SECTION},
7594
there is a corresponding directory named @samp{man@var{SECTION}dir},
7595
and a corresponding @code{_MANS} variable. Files listed in such a
7596
variable are installed in the indicated section. If the file already
7597
has a valid suffix, then it is installed as-is; otherwise the file
7598
suffix is changed to match the section.
7599
7600
For instance, consider this example:
7601
@example
7602
man1_MANS = rename.man thesame.1 alsothesame.1c
7603
@end example
7604
7605
In this case, @file{rename.man} will be renamed to @file{rename.1} when
7606
installed, but the other files will keep their names.
7607
7608
@cindex Target, @code{install-man}
7609
@cindex Option, @option{no-installman}
7610
@cindex @code{install-man} target
7611
@cindex @option{no-installman} option
7612
@opindex no-installman
7613
@trindex install-man
7614
7615
By default, man pages are installed by @samp{make install}. However,
7616
since the GNU project does not require man pages, many maintainers do
7617
not expend effort to keep the man pages up to date. In these cases, the
7618
@option{no-installman} option will prevent the man pages from being
7619
installed by default. The user can still explicitly install them via
7620
@samp{make install-man}.
7621
7622
Man pages are not currently considered to be source, because it is not
7623
uncommon for man pages to be automatically generated. Therefore they
7624
are not automatically included in the distribution. However, this can
7625
be changed by use of the @code{dist_} prefix. For instance here is
7626
how to distribute and install the two man pages of GNU @command{cpio}
7627
(which includes both Texinfo documentation and man pages):
7628
7629
@example
7630
dist_man_MANS = cpio.1 mt.1
7631
@end example
7632
7633
The @code{nobase_} prefix is meaningless for man pages and is
7634
disallowed.
7635
7636
7637
@node Install
7638
@chapter What Gets Installed
7639
7640
@cindex Installation support
7641
@cindex @samp{make install} support
7642
7643
@section Basics of installation
7644
7645
Naturally, Automake handles the details of actually installing your
7646
program once it has been built. All files named by the various
7647
primaries are automatically installed in the appropriate places when the
7648
user runs @samp{make install}.
7649
7650
A file named in a primary is installed by copying the built file into
7651
the appropriate directory. The base name of the file is used when
7652
installing.
7653
7654
@example
7655
bin_PROGRAMS = hello subdir/goodbye
7656
@end example
7657
7658
In this example, both @samp{hello} and @samp{goodbye} will be installed
7659
in @samp{$(bindir)}.
7660
7661
Sometimes it is useful to avoid the basename step at install time. For
7662
instance, you might have a number of header files in subdirectories of
7663
the source tree that are laid out precisely how you want to install
7664
them. In this situation you can use the @code{nobase_} prefix to
7665
suppress the base name step. For example:
7666
7667
@example
7668
nobase_include_HEADERS = stdio.h sys/types.h
7669
@end example
7670
7671
Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
7672
in @samp{$(includedir)/sys}.
7673
7674
@section The two parts of install
7675
7676
Automake generates separate @code{install-data} and @code{install-exec}
7677
rules, in case the installer is installing on multiple machines that
7678
share directory structure---these targets allow the machine-independent
7679
parts to be installed only once. @code{install-exec} installs
7680
platform-dependent files, and @code{install-data} installs
7681
platform-independent files. The @code{install} target depends on both
7682
of these targets. While Automake tries to automatically segregate
7683
objects into the correct category, the @file{Makefile.am} author is, in
7684
the end, responsible for making sure this is done correctly.
7685
@trindex install-data
7686
@trindex install-exec
7687
@trindex install
7688
@cindex Install, two parts of
7689
7690
Variables using the standard directory prefixes @samp{data},
7691
@samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
7692
@samp{pkgdata}, or @samp{pkginclude} are installed by
7693
@code{install-data}.
7694
7695
Variables using the standard directory prefixes @samp{bin},
7696
@samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
7697
@samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
7698
7699
For instance, @code{data_DATA} files are installed by @code{install-data},
7700
while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
7701
7702
Any variable using a user-defined directory prefix with @samp{exec} in
7703
the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
7704
@code{install-exec}. All other user-defined prefixes are installed by
7705
@code{install-data}.
7706
7707
@section Extending installation
7708
7709
It is possible to extend this mechanism by defining an
7710
@code{install-exec-local} or @code{install-data-local} rule. If these
7711
rules exist, they will be run at @samp{make install} time. These
7712
rules can do almost anything; care is required.
7713
@trindex install-exec-local
7714
@trindex install-data-local
7715
7716
Automake also supports two install hooks, @code{install-exec-hook} and
7717
@code{install-data-hook}. These hooks are run after all other install
7718
rules of the appropriate type, exec or data, have completed. So, for
7719
instance, it is possible to perform post-installation modifications
7720
using an install hook. @ref{Extending} gives some examples.
7721
@cindex Install hook
7722
7723
@section Staged installs
7724
7725
@vindex DESTDIR
7726
Automake generates support for the @code{DESTDIR} variable in all
7727
install rules. @code{DESTDIR} is used during the @samp{make install}
7728
step to relocate install objects into a staging area. Each object and
7729
path is prefixed with the value of @code{DESTDIR} before being copied
7730
into the install area. Here is an example of typical DESTDIR usage:
7731
7732
@example
7733
mkdir /tmp/staging &&
7734
make DESTDIR=/tmp/staging install
7735
@end example
7736
7737
The @command{mkdir} command avoids a security problem if the attacker
7738
creates a symbolic link from @file{/tmp/staging} to a victim area;
7739
then @command{make} places install objects in a directory tree built under
7740
@file{/tmp/staging}. If @file{/gnu/bin/foo} and
7741
@file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
7742
would install @file{/tmp/staging/gnu/bin/foo} and
7743
@file{/tmp/staging/gnu/share/aclocal/foo.m4}.
7744
7745
This feature is commonly used to build install images and packages
7746
(@pxref{DESTDIR}).
7747
7748
Support for @code{DESTDIR} is implemented by coding it directly into
7749
the install rules. If your @file{Makefile.am} uses a local install
7750
rule (e.g., @code{install-exec-local}) or an install hook, then you
7751
must write that code to respect @code{DESTDIR}.
7752
7753
@xref{Makefile Conventions, , , standards, The GNU Coding Standards},
7754
for another usage example.
7755
7756
@section Rules for the user
7757
7758
Automake also generates rules for targets @code{uninstall},
7759
@code{installdirs}, and @code{install-strip}.
7760
@trindex uninstall
7761
@trindex installdirs
7762
@trindex install-strip
7763
7764
Automake supports @code{uninstall-local} and @code{uninstall-hook}.
7765
There is no notion of separate uninstalls for ``exec'' and ``data'', as
7766
these features would not provide additional functionality.
7767
7768
Note that @code{uninstall} is not meant as a replacement for a real
7769
packaging tool.
7770
7771
7772
@node Clean
7773
@chapter What Gets Cleaned
7774
7775
@cindex @samp{make clean} support
7776
7777
The GNU Makefile Standards specify a number of different clean rules.
7778
@xref{Standard Targets, , Standard Targets for Users, standards,
7779
The GNU Coding Standards}.
7780
7781
Generally the files that can be cleaned are determined automatically by
7782
Automake. Of course, Automake also recognizes some variables that can
7783
be defined to specify additional files to clean. These variables are
7784
@code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
7785
@code{MAINTAINERCLEANFILES}.
7786
@vindex MOSTLYCLEANFILES
7787
@vindex CLEANFILES
7788
@vindex DISTCLEANFILES
7789
@vindex MAINTAINERCLEANFILES
7790
7791
@trindex mostlyclean-local
7792
@trindex clean-local
7793
@trindex distclean-local
7794
@trindex maintainer-clean-local
7795
When cleaning involves more than deleting some hard-coded list of
7796
files, it is also possible to supplement the cleaning rules with your
7797
own commands. Simply define a rule for any of the
7798
@code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
7799
or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
7800
case is deleting a directory, for instance, a directory created by the
7801
test suite:
7802
7803
@example
7804
clean-local:
7805
-rm -rf testSubDir
7806
@end example
7807
7808
As the GNU Standards aren't always explicit as to which files should
7809
be removed by which rule, we've adopted a heuristic that we believe
7810
was first formulated by Fran@,{c}ois Pinard:
7811
7812
@itemize @bullet
7813
@item
7814
If @command{make} built it, and it is commonly something that one would
7815
want to rebuild (for instance, a @file{.o} file), then
7816
@code{mostlyclean} should delete it.
7817
7818
@item
7819
Otherwise, if @command{make} built it, then @code{clean} should delete it.
7820
7821
@item
7822
If @command{configure} built it, then @code{distclean} should delete it.
7823
7824
@item
7825
If the maintainer built it (for instance, a @file{.info} file), then
7826
@code{maintainer-clean} should delete it. However
7827
@code{maintainer-clean} should not delete anything that needs to exist
7828
in order to run @samp{./configure && make}.
7829
@end itemize
7830
7831
We recommend that you follow this same set of heuristics in your
7832
@file{Makefile.am}.
7833
7834
7835
@node Dist
7836
@chapter What Goes in a Distribution
7837
7838
@section Basics of distribution
7839
7840
@cindex @samp{make dist}
7841
7842
@vindex PACKAGE
7843
@vindex VERSION
7844
@trindex dist
7845
The @code{dist} rule in the generated @file{Makefile.in} can be used
7846
to generate a gzipped @code{tar} file and other flavors of archive for
7847
distribution. The files is named based on the @code{PACKAGE} and
7848
@code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
7849
(@pxref{Macros}); more precisely the gzipped @code{tar} file is named
7850
@samp{@var{package}-@var{version}.tar.gz}.
7851
@vindex GZIP_ENV
7852
You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
7853
is run. The default setting is @option{--best}.
7854
7855
@cindex @code{m4_include}, distribution
7856
@cindex @code{include}, distribution
7857
@acindex m4_include
7858
@cmindex include
7859
For the most part, the files to distribute are automatically found by
7860
Automake: all source files are automatically included in a distribution,
7861
as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
7862
has a built-in list of commonly used files that are automatically
7863
included if they are found in the current directory (either physically,
7864
or as the target of a @file{Makefile.am} rule). This list is printed by
7865
@samp{automake --help}. Also, files that are read by @command{configure}
7866
(i.e.@: the source files corresponding to the files specified in various
7867
Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
7868
automatically distributed. Files included in @file{Makefile.am}s (using
7869
@code{include}) or in @file{configure.ac} (using @code{m4_include}), and
7870
helper scripts installed with @samp{automake --add-missing} are also
7871
distributed.
7872
7873
@vindex EXTRA_DIST
7874
Still, sometimes there are files that must be distributed, but which
7875
are not covered in the automatic rules. These files should be listed in
7876
the @code{EXTRA_DIST} variable. You can mention files from
7877
subdirectories in @code{EXTRA_DIST}.
7878
7879
You can also mention a directory in @code{EXTRA_DIST}; in this case the
7880
entire directory will be recursively copied into the distribution.
7881
Please note that this will also copy @emph{everything} in the directory,
7882
including CVS/RCS version control files. We recommend against using
7883
this feature.
7884
7885
@vindex SUBDIRS
7886
@vindex DIST_SUBDIRS
7887
If you define @code{SUBDIRS}, Automake will recursively include the
7888
subdirectories in the distribution. If @code{SUBDIRS} is defined
7889
conditionally (@pxref{Conditionals}), Automake will normally include
7890
all directories that could possibly appear in @code{SUBDIRS} in the
7891
distribution. If you need to specify the set of directories
7892
conditionally, you can set the variable @code{DIST_SUBDIRS} to the
7893
exact list of subdirectories to include in the distribution
7894
(@pxref{Conditional Subdirectories}).
7895
7896
7897
@section Fine-grained distribution control
7898
7899
@vindex dist_
7900
@vindex nodist_
7901
Sometimes you need tighter control over what does @emph{not} go into the
7902
distribution; for instance, you might have source files that are
7903
generated and that you do not want to distribute. In this case
7904
Automake gives fine-grained control using the @code{dist} and
7905
@code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
7906
prefixed with @code{dist_} to add the listed files to the distribution.
7907
Similarly, @code{nodist_} can be used to omit the files from the
7908
distribution.
7909
7910
As an example, here is how you would cause some data to be distributed
7911
while leaving some source code out of the distribution:
7912
7913
@example
7914
dist_data_DATA = distribute-this
7915
bin_PROGRAMS = foo
7916
nodist_foo_SOURCES = do-not-distribute.c
7917
@end example
7918
7919
@section The dist hook
7920
7921
@trindex dist-hook
7922
7923
Occasionally it is useful to be able to change the distribution before
7924
it is packaged up. If the @code{dist-hook} rule exists, it is run
7925
after the distribution directory is filled, but before the actual tar
7926
(or shar) file is created. One way to use this is for distributing
7927
files in subdirectories for which a new @file{Makefile.am} is overkill:
7928
7929
@example
7930
dist-hook:
7931
mkdir $(distdir)/random
7932
cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
7933
@end example
7934
7935
Another way to use this is for removing unnecessary files that get
7936
recursively included by specifying a directory in EXTRA_DIST:
7937
7938
@example
7939
EXTRA_DIST = doc
7940
7941
dist-hook:
7942
rm -rf `find $(distdir)/doc -name CVS`
7943
@end example
7944
7945
@vindex distdir
7946
@vindex top_distdir
7947
Two variables that come handy when writing @code{dist-hook} rules are
7948
@samp{$(distdir)} and @samp{$(top_distdir)}.
7949
7950
@samp{$(distdir)} points to the directory where the @code{dist} rule
7951
will copy files from the current directory before creating the
7952
tarball. If you are at the top-level directory, then @samp{distdir =
7953
$(PACKAGE)-$(VERSION)}. When used from subdirectory named
7954
@file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
7955
@samp{$(distdir)} can be a relative or absolute path, do not assume
7956
any form.
7957
7958
@samp{$(top_distdir)} always points to the root directory of the
7959
distributed tree. At the top-level it's equal to @samp{$(distdir)}.
7960
In the @file{foo/} subdirectory
7961
@samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
7962
@samp{$(top_distdir)} too can be a relative or absolute path.
7963
7964
Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
7965
(@pxref{Subpackages}), then @samp{$(distdir)} and
7966
@samp{$(top_distdir)} are relative to the package where @samp{make
7967
dist} was run, not to any sub-packages involved.
7968
7969
@section Checking the distribution
7970
7971
@cindex @samp{make distcheck}
7972
@cindex @samp{make distcleancheck}
7973
@vindex distcleancheck_listfiles
7974
@cindex @samp{make distuninstallcheck}
7975
@vindex distuninstallcheck_listfiles
7976
7977
@trindex distcheck
7978
Automake also generates a @code{distcheck} rule that can be of help to
7979
ensure that a given distribution will actually work. @code{distcheck}
7980
makes a distribution, then tries to do a @code{VPATH} build
7981
(@pxref{VPATH Builds}), run the test suite, and finally make another
7982
tarball to ensure the distribution is self-contained.
7983
7984
@vindex DISTCHECK_CONFIGURE_FLAGS
7985
Building the package involves running @samp{./configure}. If you need
7986
to supply additional flags to @command{configure}, define them in the
7987
@code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
7988
@file{Makefile.am}, or on the command line when invoking @command{make}.
7989
7990
@trindex distcheck-hook
7991
If the @code{distcheck-hook} rule is defined in your top-level
7992
@file{Makefile.am}, then it will be invoked by @code{distcheck} after
7993
the new distribution has been unpacked, but before the unpacked copy
7994
is configured and built. Your @code{distcheck-hook} can do almost
7995
anything, though as always caution is advised. Generally this hook is
7996
used to check for potential distribution errors not caught by the
7997
standard mechanism. Note that @code{distcheck-hook} as well as
7998
@code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
7999
@file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
8000
passed down to the @command{configure} script of the subpackage.
8001
8002
@trindex distcleancheck
8003
@vindex DISTCLEANFILES
8004
@vindex distcleancheck_listfiles
8005
Speaking of potential distribution errors, @code{distcheck} also
8006
ensures that the @code{distclean} rule actually removes all built
8007
files. This is done by running @samp{make distcleancheck} at the end of
8008
the @code{VPATH} build. By default, @code{distcleancheck} will run
8009
@code{distclean} and then make sure the build tree has been emptied by
8010
running @samp{$(distcleancheck_listfiles)}. Usually this check will
8011
find generated files that you forgot to add to the @code{DISTCLEANFILES}
8012
variable (@pxref{Clean}).
8013
8014
The @code{distcleancheck} behavior should be OK for most packages,
8015
otherwise you have the possibility to override the definition of
8016
either the @code{distcleancheck} rule, or the
8017
@samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8018
@code{distcleancheck} completely, add the following rule to your
8019
top-level @file{Makefile.am}:
8020
8021
@example
8022
distcleancheck:
8023
@@:
8024
@end example
8025
8026
If you want @code{distcleancheck} to ignore built files that have not
8027
been cleaned because they are also part of the distribution, add the
8028
following definition instead:
8029
8030
@example
8031
distcleancheck_listfiles = \
8032
find -type f -exec sh -c 'test -f $(srcdir)/@{@} || echo @{@}' ';'
8033
@end example
8034
8035
The above definition is not the default because it's usually an error if
8036
your Makefiles cause some distributed files to be rebuilt when the user
8037
build the package. (Think about the user missing the tool required to
8038
build the file; or if the required tool is built by your package,
8039
consider the cross-compilation case where it can't be run.) There is
8040
a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
8041
before playing with @code{distcleancheck_listfiles}.
8042
8043
@code{distcheck} also checks that the @code{uninstall} rule works
8044
properly, both for ordinary and @code{DESTDIR} builds. It does this
8045
by invoking @samp{make uninstall}, and then it checks the install tree
8046
to see if any files are left over. This check will make sure that you
8047
correctly coded your @code{uninstall}-related rules.
8048
8049
By default, the checking is done by the @code{distuninstallcheck} rule,
8050
and the list of files in the install tree is generated by
8051
@samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is
8052
a shell command to run that prints the list of files to stdout).
8053
8054
Either of these can be overridden to modify the behavior of
8055
@code{distcheck}. For instance, to disable this check completely, you
8056
would write:
8057
8058
@example
8059
distuninstallcheck:
8060
@@:
8061
@end example
8062
8063
@section The types of distributions
8064
8065
Automake generates rules to provide archives of the project for
8066
distributions in various formats. Their targets are:
8067
8068
@table @asis
8069
@item @code{dist-bzip2}
8070
Generate a bzip2 tar archive of the distribution. bzip2 archives are
8071
frequently smaller than gzipped archives.
8072
@trindex dist-bzip2
8073
8074
@item @code{dist-gzip}
8075
Generate a gzip tar archive of the distribution.
8076
@trindex dist-gzip
8077
8078
@item @code{dist-lzma}
8079
Generate a lzma tar archive of the distribution. lzma archives are
8080
frequently smaller than @command{bzip2}-compressed archives.
8081
@trindex dist-lzma
8082
8083
@item @code{dist-shar}
8084
Generate a shar archive of the distribution.
8085
@trindex dist-shar
8086
8087
@item @code{dist-zip}
8088
Generate a zip archive of the distribution.
8089
@trindex dist-zip
8090
8091
@item @code{dist-tarZ}
8092
Generate a compressed tar archive of
8093
the distribution.
8094
@trindex dist-tarZ
8095
@end table
8096
8097
The rule @code{dist} (and its historical synonym @code{dist-all}) will
8098
create archives in all the enabled formats, @ref{Options}. By
8099
default, only the @code{dist-gzip} target is hooked to @code{dist}.
8100
8101
8102
@node Tests
8103
@chapter Support for test suites
8104
8105
@cindex Test suites
8106
@cindex @code{make check}
8107
@trindex check
8108
8109
Automake supports two forms of test suites.
8110
8111
@section Simple Tests
8112
8113
If the variable @code{TESTS} is defined, its value is taken to be a
8114
list of programs or scripts to run in order to do the testing.
8115
Programs needing data files should look for them in @code{srcdir}
8116
(which is both an environment variable and a make variable) so they
8117
work when building in a separate directory (@pxref{Build Directories,
8118
, Build Directories , autoconf, The Autoconf Manual}), and in
8119
particular for the @code{distcheck} rule (@pxref{Dist}).
8120
8121
@cindex Exit status 77, special interpretation
8122
8123
The number of failures will be printed at the end of the run. If a
8124
given test program exits with a status of 77, then its result is ignored
8125
in the final count. This feature allows non-portable tests to be
8126
ignored in environments where they don't make sense.
8127
8128
@vindex TESTS
8129
@vindex TESTS_ENVIRONMENT
8130
The variable @code{TESTS_ENVIRONMENT} can be used to set environment
8131
variables for the test run; the environment variable @code{srcdir} is
8132
set in the rule. If all your test programs are scripts, you can also
8133
set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
8134
@samp{$(SHELL) -x} can be useful for debugging the tests), or any other
8135
interpreter. For instance the following setup is used by the Automake
8136
package to run four tests in Perl.
8137
@example
8138
TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
8139
TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
8140
@end example
8141
8142
8143
@cindex Tests, expected failure
8144
@cindex Expected test failure
8145
8146
You may define the variable @code{XFAIL_TESTS} to a list of tests
8147
(usually a subset of @code{TESTS}) that are expected to fail. This will
8148
reverse the result of those tests.
8149
@vindex XFAIL_TESTS
8150
8151
Automake ensures that each file listed in @code{TESTS} is built before
8152
any tests are run; you can list both source and derived programs (or
8153
scripts) in @code{TESTS}; the generated rule will look both in
8154
@code{srcdir} and @file{.}. For instance, you might want to run a C
8155
program as a test. To do this you would list its name in @code{TESTS}
8156
and also in @code{check_PROGRAMS}, and then specify it as you would
8157
any other program.
8158
8159
Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8160
@code{check_LTLIBRARIES}...) are only built during @code{make check},
8161
not during @code{make all}. You should list there any program needed
8162
by your tests that does not need to be built by @code{make all}. Note
8163
that @code{check_PROGRAMS} are @emph{not} automatically added to
8164
@code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8165
by the tests, not the tests themselves. Of course you can set
8166
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8167
8168
@section DejaGnu Tests
8169
8170
If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
8171
@code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
8172
assumed. The variable @code{DEJATOOL} is a list of names that are
8173
passed, one at a time, as the @option{--tool} argument to
8174
@command{runtest} invocations; it defaults to the name of the package.
8175
8176
The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
8177
@option{--srcdir} flags that are passed to dejagnu by default; this can be
8178
overridden if necessary.
8179
@vindex RUNTESTDEFAULTFLAGS
8180
8181
The variables @code{EXPECT} and @code{RUNTEST} can
8182
also be overridden to provide project-specific values. For instance,
8183
you will need to do this if you are testing a compiler toolchain,
8184
because the default values do not take into account host and target
8185
names.
8186
@opindex dejagnu
8187
@vindex DEJATOOL
8188
@vindex EXPECT
8189
@vindex RUNTEST
8190
8191
The contents of the variable @code{RUNTESTFLAGS} are passed to the
8192
@code{runtest} invocation. This is considered a ``user variable''
8193
(@pxref{User Variables}). If you need to set @command{runtest} flags in
8194
@file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
8195
@vindex RUNTESTFLAGS
8196
@vindex AM_RUNTESTFLAGS
8197
8198
@cindex @file{site.exp}
8199
Automake will generate rules to create a local @file{site.exp} file,
8200
defining various variables detected by @command{configure}. This file
8201
is automatically read by DejaGnu. It is OK for the user of a package
8202
to edit this file in order to tune the test suite. However this is
8203
not the place where the test suite author should define new variables:
8204
this should be done elsewhere in the real test suite code.
8205
Especially, @file{site.exp} should not be distributed.
8206
8207
For more information regarding DejaGnu test suites, see @ref{Top, , ,
8208
dejagnu, The DejaGnu Manual}.
8209
8210
In either case, the testing is done via @samp{make check}.
8211
8212
@section Install Tests
8213
8214
The @code{installcheck} target is available to the user as a way to
8215
run any tests after the package has been installed. You can add tests
8216
to this by writing an @code{installcheck-local} rule.
8217
8218
8219
@node Rebuilding
8220
@chapter Rebuilding Makefiles
8221
@cindex rebuild rules
8222
8223
Automake generates rules to automatically rebuild @file{Makefile}s,
8224
@file{configure}, and other derived files like @file{Makefile.in}.
8225
8226
@acindex AM_MAINTAINER_MODE
8227
If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
8228
these automatic rebuilding rules are only enabled in maintainer mode.
8229
8230
@vindex ACLOCAL_AMFLAGS
8231
Sometimes you need to run @command{aclocal} with an argument like
8232
@option{-I} to tell it where to find @file{.m4} files. Since
8233
sometimes @command{make} will automatically run @command{aclocal}, you
8234
need a way to specify these arguments. You can do this by defining
8235
@code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
8236
to @command{aclocal}. This variable is only useful in the top-level
8237
@file{Makefile.am}.
8238
8239
@vindex CONFIG_STATUS_DEPENDENCIES
8240
@vindex CONFIGURE_DEPENDENCIES
8241
@cindex @file{version.sh}, example
8242
@cindex @file{version.m4}, example
8243
8244
Sometimes it is convenient to supplement the rebuild rules for
8245
@file{configure} or @file{config.status} with additional dependencies.
8246
The variables @code{CONFIGURE_DEPENDENCIES} and
8247
@code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
8248
dependencies. These variable should be defined in all
8249
@file{Makefile}s of the tree (because these two rebuild rules are
8250
output in all them), so it is safer and easier to @code{AC_SUBST} them
8251
from @file{configure.ac}. For instance, the following statement will
8252
cause @file{configure} to be rerun each time @file{version.sh} is
8253
changed.
8254
@example
8255
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
8256
@end example
8257
@noindent
8258
Note the @samp{$(top_srcdir)/} in the file name. Since this variable
8259
is to be used in all @file{Makefile}s, its value must be sensible at
8260
any level in the build hierarchy.
8261
8262
Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
8263
@code{CONFIG_STATUS_DEPENDENCIES}.
8264
8265
@code{CONFIGURE_DEPENDENCIES} adds dependencies to the
8266
@file{configure} rule, whose effect is to run @command{autoconf}. This
8267
variable should be seldom used, because @command{automake} already tracks
8268
@code{m4_include}d files. However it can be useful when playing
8269
tricky games with @code{m4_esyscmd} or similar non-recommendable
8270
macros with side effects.
8271
8272
@code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
8273
@file{config.status} rule, whose effect is to run @file{configure}.
8274
This variable should therefore carry any non-standard source that may
8275
be read as a side effect of running configure, like @file{version.sh}
8276
in the example above.
8277
8278
Speaking of @file{version.sh} scripts, we recommend against them
8279
today. They are mainly used when the version of a package is updated
8280
automatically by a script (e.g., in daily builds). Here is what some
8281
old-style @file{configure.ac}s may look like:
8282
@example
8283
AC_INIT
8284
. $srcdir/version.sh
8285
AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
8286
@dots{}
8287
@end example
8288
@noindent
8289
Here, @file{version.sh} is a shell fragment that sets
8290
@code{VERSION_NUMBER}. The problem with this example is that
8291
@command{automake} cannot track dependencies (listing @file{version.sh}
8292
in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
8293
to the user), and that it uses the obsolete form of @code{AC_INIT} and
8294
@code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
8295
straightforward, because shell variables are not allowed in
8296
@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
8297
replaced by an M4 file that is included by @file{configure.ac}:
8298
@example
8299
m4_include([version.m4])
8300
AC_INIT([name], VERSION_NUMBER)
8301
AM_INIT_AUTOMAKE
8302
@dots{}
8303
@end example
8304
@noindent
8305
Here @file{version.m4} could contain something like
8306
@samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
8307
second form is that @command{automake} will take care of the
8308
dependencies when defining the rebuild rule, and will also distribute
8309
the file automatically. An inconvenience is that @command{autoconf}
8310
will now be rerun each time the version number is bumped, when only
8311
@file{configure} had to be rerun in the previous setup.
8312
8313
8314
@node Options
8315
@chapter Changing Automake's Behavior
8316
8317
Various features of Automake can be controlled by options in the
8318
@file{Makefile.am}. Such options are applied on a per-@file{Makefile}
8319
basis when listed in a special @file{Makefile} variable named
8320
@code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
8321
@file{Makefiles} when listed in the first argument of
8322
@code{AM_INIT_AUTOMAKE} in @file{configure.ac}. Currently understood
8323
options are:
8324
@vindex AUTOMAKE_OPTIONS
8325
8326
@table @asis
8327
@item @option{gnits}
8328
@itemx @option{gnu}
8329
@itemx @option{foreign}
8330
@itemx @option{cygnus}
8331
@cindex Option, @option{gnits}
8332
@cindex Option, @option{gnu}
8333
@cindex Option, @option{foreign}
8334
@cindex Option, @option{cygnus}
8335
@opindex gnits
8336
@opindex gnu
8337
@opindex foreign
8338
@opindex cygnus
8339
8340
Set the strictness as appropriate. The @option{gnits} option also
8341
implies options @option{readme-alpha} and @option{check-news}.
8342
8343
@item @option{ansi2knr}
8344
@itemx @option{@var{path}/ansi2knr}
8345
@cindex Option, @option{ansi2knr}
8346
@opindex ansi2knr
8347
Turn on the obsolete de-ANSI-fication feature. @xref{ANSI}. If preceded by a
8348
path, the generated @file{Makefile.in} will look in the specified
8349
directory to find the @file{ansi2knr} program. The path should be a
8350
relative path to another directory in the same distribution (Automake
8351
currently does not check this).
8352
8353
@item @option{check-news}
8354
@cindex Option, @option{check-news}
8355
@opindex check-news
8356
Cause @samp{make dist} to fail unless the current version number appears
8357
in the first few lines of the @file{NEWS} file.
8358
8359
@item @option{dejagnu}
8360
@cindex Option, @option{dejagnu}
8361
@opindex dejagnu
8362
Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
8363
8364
@item @option{dist-bzip2}
8365
@cindex Option, @option{dist-bzip2}
8366
@opindex dist-bzip2
8367
Hook @code{dist-bzip2} to @code{dist}.
8368
@trindex dist-bzip2
8369
8370
@item @option{dist-lzma}
8371
@cindex Option, @option{dist-lzma}
8372
@opindex dist-lzma
8373
Hook @code{dist-lzma} to @code{dist}.
8374
@trindex dist-lzma
8375
8376
@item @option{dist-shar}
8377
@cindex Option, @option{dist-shar}
8378
@opindex dist-shar
8379
Hook @code{dist-shar} to @code{dist}.
8380
@trindex dist-shar
8381
8382
@item @option{dist-zip}
8383
@cindex Option, @option{dist-zip}
8384
@opindex dist-zip
8385
Hook @code{dist-zip} to @code{dist}.
8386
@trindex dist-zip
8387
8388
@item @option{dist-tarZ}
8389
@cindex Option, @option{dist-tarZ}
8390
@opindex dist-tarZ
8391
Hook @code{dist-tarZ} to @code{dist}.
8392
@trindex dist-tarZ
8393
8394
@item @option{filename-length-max=99}
8395
@cindex Option, @option{filename-length-max=99}
8396
@opindex filename-length-max=99
8397
Abort if file names longer than 99 characters are found during
8398
@samp{make dist}. Such long file names are generally considered not to
8399
be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
8400
options below. This option should be used in the top-level
8401
@file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
8402
@file{configure.ac}, it will be ignored otherwise. It will also be
8403
ignored in sub-packages of nested packages (@pxref{Subpackages}).
8404
8405
@item @option{no-define}
8406
@cindex Option, @option{no-define}
8407
@opindex no-define
8408
This options is meaningful only when passed as an argument to
8409
@code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
8410
@code{VERSION} variables to be @code{AC_DEFINE}d.
8411
8412
@item @option{no-dependencies}
8413
@cindex Option, @option{no-dependencies}
8414
@opindex no-dependencies
8415
This is similar to using @option{--ignore-deps} on the command line,
8416
but is useful for those situations where you don't have the necessary
8417
bits to make automatic dependency tracking work
8418
(@pxref{Dependencies}). In this case the effect is to effectively
8419
disable automatic dependency tracking.
8420
8421
@item @option{no-dist}
8422
@cindex Option, @option{no-dist}
8423
@opindex no-dist
8424
Don't emit any code related to @code{dist} target. This is useful
8425
when a package has its own method for making distributions.
8426
8427
@item @option{no-dist-gzip}
8428
@cindex Option, @option{no-dist-gzip}
8429
@opindex no-dist-gzip
8430
Do not hook @code{dist-gzip} to @code{dist}.
8431
@trindex no-dist-gzip
8432
8433
@item @option{no-exeext}
8434
@cindex Option, @option{no-exeext}
8435
@opindex no-exeext
8436
If your @file{Makefile.am} defines a rule for target @code{foo}, it
8437
will override a rule for a target named @samp{foo$(EXEEXT)}. This is
8438
necessary when @code{EXEEXT} is found to be empty. However, by
8439
default automake will generate an error for this use. The
8440
@option{no-exeext} option will disable this error. This is intended for
8441
use only where it is known in advance that the package will not be
8442
ported to Windows, or any other operating system using extensions on
8443
executables.
8444
8445
@item @option{no-installinfo}
8446
@cindex Option, @option{no-installinfo}
8447
@opindex no-installinfo
8448
The generated @file{Makefile.in} will not cause info pages to be built
8449
or installed by default. However, @code{info} and @code{install-info}
8450
targets will still be available. This option is disallowed at
8451
@option{gnu} strictness and above.
8452
@trindex info
8453
@trindex install-info
8454
8455
@item @option{no-installman}
8456
@cindex Option, @option{no-installman}
8457
@opindex no-installman
8458
The generated @file{Makefile.in} will not cause man pages to be
8459
installed by default. However, an @code{install-man} target will still
8460
be available for optional installation. This option is disallowed at
8461
@option{gnu} strictness and above.
8462
@trindex install-man
8463
8464
@item @option{nostdinc}
8465
@cindex Option, @option{nostdinc}
8466
@opindex nostdinc
8467
This option can be used to disable the standard @option{-I} options that
8468
are ordinarily automatically provided by Automake.
8469
8470
@item @option{no-texinfo.tex}
8471
@cindex Option, @option{no-texinfo.tex}
8472
@opindex no-texinfo.tex
8473
Don't require @file{texinfo.tex}, even if there are texinfo files in
8474
this directory.
8475
8476
@item @option{readme-alpha}
8477
@cindex Option, @option{readme-alpha}
8478
@opindex readme-alpha
8479
If this release is an alpha release, and the file @file{README-alpha}
8480
exists, then it will be added to the distribution. If this option is
8481
given, version numbers are expected to follow one of two forms. The
8482
first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
8483
element is a number; the final period and number should be left off for
8484
non-alpha releases. The second form is
8485
@samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
8486
letter; it should be omitted for non-alpha releases.
8487
8488
@item @option{std-options}
8489
@cindex Options, @option{std-options}
8490
@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
8491
@cindex @option{--help} check
8492
@cindex @option{--version} check
8493
@opindex std-options
8494
8495
Make the @code{installcheck} rule check that installed scripts and
8496
programs support the @option{--help} and @option{--version} options.
8497
This also provides a basic check that the program's
8498
run-time dependencies are satisfied after installation.
8499
8500
@vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
8501
In a few situations, programs (or scripts) have to be exempted from this
8502
test. For instance, @command{false} (from GNU sh-utils) is never
8503
successful, even for @option{--help} or @option{--version}. You can list
8504
such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
8505
Programs (not scripts) listed in this variable should be suffixed by
8506
@samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
8507
build @file{false} as a program but @file{true.sh} as a script, and that
8508
neither of them support @option{--help} or @option{--version}:
8509
8510
@example
8511
AUTOMAKE_OPTIONS = std-options
8512
bin_PROGRAMS = false ...
8513
bin_SCRIPTS = true.sh ...
8514
AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
8515
@end example
8516
8517
@item @option{subdir-objects}
8518
@cindex Options, @option{subdir-objects}
8519
@opindex subdir-objects
8520
If this option is specified, then objects are placed into the
8521
subdirectory of the build directory corresponding to the subdirectory of
8522
the source file. For instance, if the source file is
8523
@file{subdir/file.cxx}, then the output file would be
8524
@file{subdir/file.o}.
8525
8526
In order to use this option with C sources, you should add
8527
@code{AM_PROG_CC_C_O} to @file{configure.ac}.
8528
8529
@anchor{tar-formats}
8530
@item @option{tar-v7}
8531
@itemx @option{tar-ustar}
8532
@itemx @option{tar-pax}
8533
@cindex Option, @option{tar-v7}
8534
@cindex Option, @option{tar-ustar}
8535
@cindex Option, @option{tar-pax}
8536
@cindex @command{tar} formats
8537
@cindex v7 @command{tar} format
8538
@cindex ustar format
8539
@cindex pax format
8540
@opindex tar-v7
8541
@opindex tar-ustar
8542
@opindex tar-pax
8543
8544
These three mutually exclusive options select the tar format to use
8545
when generating tarballs with @samp{make dist}. (The tar file created
8546
is then compressed according to the set of @option{no-dist-gzip},
8547
@option{dist-bzip2}, @option{dist-lzma} and @option{dist-tarZ} options in use.)
8548
8549
These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
8550
(@pxref{Macros}) because they can require additional configure checks.
8551
Automake will complain if it sees such options in an
8552
@code{AUTOMAKE_OPTIONS} variable.
8553
8554
@option{tar-v7} selects the old V7 tar format. This is the historical
8555
default. This antiquated format is understood by all tar
8556
implementations and supports file names with up to 99 characters. When
8557
given longer file names some tar implementations will diagnose the
8558
problem while other will generate broken tarballs or use non-portable
8559
extensions. Furthermore, the V7 format cannot store empty
8560
directories. When using this format, consider using the
8561
@option{filename-length-max=99} option to catch file names too long.
8562
8563
@option{tar-ustar} selects the ustar format defined by POSIX
8564
1003.1-1988. This format is believed to be old enough to be portable.
8565
It fully supports empty directories. It can store file names with up
8566
to 256 characters, provided that the file name can be split at
8567
directory separator in two parts, first of them being at most 155
8568
bytes long. So, in most cases the maximum file name length will be
8569
shorter than 256 characters. However you may run against broken tar
8570
implementations that incorrectly handle file names longer than 99
8571
characters (please report them to @email{bug-automake@@gnu.org} so we
8572
can document this accurately).
8573
8574
@option{tar-pax} selects the new pax interchange format defined by POSIX
8575
1003.1-2001. It does not limit the length of file names. However,
8576
this format is very young and should probably be restricted to
8577
packages that target only very modern platforms. There are moves to
8578
change the pax format in an upward-compatible way, so this option may
8579
refer to a more recent version in the future.
8580
8581
@xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
8582
further discussion about tar formats.
8583
8584
@command{configure} knows several ways to construct these formats. It
8585
will not abort if it cannot find a tool up to the task (so that the
8586
package can still be built), but @samp{make dist} will fail.
8587
8588
@item @var{version}
8589
@cindex Option, @var{version}
8590
A version number (e.g., @samp{0.30}) can be specified. If Automake is not
8591
newer than the version specified, creation of the @file{Makefile.in}
8592
will be suppressed.
8593
8594
@item @option{-W@var{category}} or @option{--warnings=@var{category}}
8595
@cindex Option, warnings
8596
@cindex Option, @option{-W@var{category}}
8597
@cindex Option, @option{--warnings=@var{category}}
8598
These options behave exactly like their command-line counterpart
8599
(@pxref{Invoking Automake}). This allows you to enable or disable some
8600
warning categories on a per-file basis. You can also setup some warnings
8601
for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
8602
in your @file{configure.ac}.
8603
8604
@end table
8605
8606
Unrecognized options are diagnosed by @command{automake}.
8607
8608
If you want an option to apply to all the files in the tree, you can use
8609
the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
8610
@xref{Macros}.
8611
8612
8613
@node Miscellaneous
8614
@chapter Miscellaneous Rules
8615
8616
There are a few rules and variables that didn't fit anywhere else.
8617
8618
@menu
8619
* Tags:: Interfacing to etags and mkid
8620
* Suffixes:: Handling new file extensions
8621
* Multilibs:: Support for multilibs.
8622
@end menu
8623
8624
8625
@node Tags
8626
@section Interfacing to @command{etags}
8627
8628
@cindex @file{TAGS} support
8629
8630
Automake will generate rules to generate @file{TAGS} files for use with
8631
GNU Emacs under some circumstances.
8632
8633
@trindex tags
8634
If any C, C++ or Fortran 77 source code or headers are present, then
8635
@code{tags} and @code{TAGS} rules will be generated for the directory.
8636
All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
8637
@code{_LISP} primaries will be used to generate tags. Note that
8638
generated source files that are not distributed must be declared in
8639
variables like @code{nodist_noinst_HEADERS} or
8640
@code{nodist_@var{prog}_SOURCES} or they will be ignored.
8641
8642
A @code{tags} rule will be output at the topmost directory of a
8643
multi-directory package. When run from this topmost directory,
8644
@samp{make tags} will generate a @file{TAGS} file that includes by
8645
reference all @file{TAGS} files from subdirectories.
8646
8647
The @code{tags} rule will also be generated if the variable
8648
@code{ETAGS_ARGS} is defined. This variable is intended for use in
8649
directories that contain taggable source that @command{etags} does
8650
not understand. The user can use the @code{ETAGSFLAGS} to pass
8651
additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
8652
available for use in @file{Makefile.am}.
8653
@vindex ETAGS_ARGS
8654
@vindex ETAGSFLAGS
8655
@vindex AM_ETAGSFLAGS
8656
8657
Here is how Automake generates tags for its source, and for nodes in its
8658
Texinfo file:
8659
8660
@example
8661
ETAGS_ARGS = automake.in --lang=none \
8662
--regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
8663
@end example
8664
8665
If you add file names to @code{ETAGS_ARGS}, you will probably also
8666
want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
8667
are added directly to the dependencies for the @code{tags} rule.
8668
@vindex TAGS_DEPENDENCIES
8669
8670
Automake also generates a @code{ctags} rule that can be used to
8671
build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
8672
is the name of the program to invoke (by default @command{ctags});
8673
@code{CTAGSFLAGS} can be used by the user to pass additional flags,
8674
and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
8675
8676
Automake will also generate an @code{ID} rule that will run
8677
@command{mkid} on the source. This is only supported on a
8678
directory-by-directory basis.
8679
@trindex id
8680
8681
Finally, Automake also emit rules to support the
8682
@uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
8683
The @code{GTAGS} rule runs Global Tags and puts the
8684
result in the top build directory. The variable @code{GTAGS_ARGS}
8685
holds arguments that are passed to @command{gtags}.
8686
@vindex GTAGS_ARGS
8687
8688
8689
@node Suffixes
8690
@section Handling new file extensions
8691
8692
@cindex Adding new @code{SUFFIXES}
8693
@cindex @code{SUFFIXES}, adding
8694
@vindex SUFFIXES
8695
8696
It is sometimes useful to introduce a new implicit rule to handle a file
8697
type that Automake does not know about.
8698
8699
For instance, suppose you had a compiler that could compile @file{.foo}
8700
files to @file{.o} files. You would simply define an suffix rule for
8701
your language:
8702
8703
@example
8704
.foo.o:
8705
foocc -c -o $@@ $<
8706
@end example
8707
8708
Then you could directly use a @file{.foo} file in a @code{_SOURCES}
8709
variable and expect the correct results:
8710
8711
@example
8712
bin_PROGRAMS = doit
8713
doit_SOURCES = doit.foo
8714
@end example
8715
8716
This was the simpler and more common case. In other cases, you will
8717
have to help Automake to figure which extensions you are defining your
8718
suffix rule for. This usually happens when your extensions does not
8719
start with a dot. Then, all you have to do is to put a list of new
8720
suffixes in the @code{SUFFIXES} variable @strong{before} you define your
8721
implicit rule.
8722
8723
For instance, the following definition prevents Automake to misinterpret
8724
@samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
8725
@file{.cpp} files.
8726
8727
@example
8728
SUFFIXES = .idl C.cpp
8729
.idlC.cpp:
8730
# whatever
8731
@end example
8732
8733
As you may have noted, the @code{SUFFIXES} variable behaves like the
8734
@code{.SUFFIXES} special target of @command{make}. You should not touch
8735
@code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
8736
Automake generate the suffix list for @code{.SUFFIXES}. Any given
8737
@code{SUFFIXES} go at the start of the generated suffixes list, followed
8738
by Automake generated suffixes not already in the list.
8739
8740
@node Multilibs
8741
@section Support for Multilibs
8742
8743
Automake has support for an obscure feature called multilibs. A
8744
@dfn{multilib} is a library that is built for multiple different ABIs
8745
at a single time; each time the library is built with a different target
8746
flag combination. This is only useful when the library is intended to
8747
be cross-compiled, and it is almost exclusively used for compiler
8748
support libraries.
8749
8750
The multilib support is still experimental. Only use it if you are
8751
familiar with multilibs and can debug problems you might encounter.
8752
8753
8754
@node Include
8755
@chapter Include
8756
8757
@cmindex include
8758
@cindex Including @file{Makefile} fragment
8759
@cindex @file{Makefile} fragment, including
8760
8761
Automake supports an @code{include} directive that can be used to
8762
include other @file{Makefile} fragments when @command{automake} is run.
8763
Note that these fragments are read and interpreted by @command{automake},
8764
not by @command{make}. As with conditionals, @command{make} has no idea that
8765
@code{include} is in use.
8766
8767
There are two forms of @code{include}:
8768
8769
@table @code
8770
@item include $(srcdir)/file
8771
Include a fragment that is found relative to the current source
8772
directory.
8773
8774
@item include $(top_srcdir)/file
8775
Include a fragment that is found relative to the top source directory.
8776
@end table
8777
8778
Note that if a fragment is included inside a conditional, then the
8779
condition applies to the entire contents of that fragment.
8780
8781
Makefile fragments included this way are always distributed because
8782
they are needed to rebuild @file{Makefile.in}.
8783
8784
@node Conditionals
8785
@chapter Conditionals
8786
8787
@cindex Conditionals
8788
8789
Automake supports a simple type of conditionals.
8790
8791
@unnumberedsec Usage
8792
8793
@acindex AM_CONDITIONAL
8794
Before using a conditional, you must define it by using
8795
@code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
8796
8797
@defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
8798
The conditional name, @var{conditional}, should be a simple string
8799
starting with a letter and containing only letters, digits, and
8800
underscores. It must be different from @samp{TRUE} and @samp{FALSE}
8801
that are reserved by Automake.
8802
8803
The shell @var{condition} (suitable for use in a shell @code{if}
8804
statement) is evaluated when @command{configure} is run. Note that you
8805
must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
8806
time @command{configure} is run. If @code{AM_CONDITIONAL} is run
8807
conditionally (e.g., in a shell @code{if} statement), then the result
8808
will confuse automake.
8809
@end defmac
8810
8811
@cindex @option{--enable-debug}, example
8812
@cindex Example conditional @option{--enable-debug}
8813
@cindex Conditional example, @option{--enable-debug}
8814
8815
Conditionals typically depend upon options that the user provides to
8816
the @command{configure} script. Here is an example of how to write a
8817
conditional that is true if the user uses the @option{--enable-debug}
8818
option.
8819
8820
@example
8821
AC_ARG_ENABLE([debug],
8822
[ --enable-debug Turn on debugging],
8823
[case "$@{enableval@}" in
8824
yes) debug=true ;;
8825
no) debug=false ;;
8826
*) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
8827
esac],[debug=false])
8828
AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
8829
@end example
8830
8831
Here is an example of how to use that conditional in @file{Makefile.am}:
8832
8833
@cmindex if
8834
@cmindex endif
8835
@cmindex else
8836
8837
@example
8838
if DEBUG
8839
DBG = debug
8840
else
8841
DBG =
8842
endif
8843
noinst_PROGRAMS = $(DBG)
8844
@end example
8845
8846
This trivial example could also be handled using @code{EXTRA_PROGRAMS}
8847
(@pxref{Conditional Programs}).
8848
8849
You may only test a single variable in an @code{if} statement, possibly
8850
negated using @samp{!}. The @code{else} statement may be omitted.
8851
Conditionals may be nested to any depth. You may specify an argument to
8852
@code{else} in which case it must be the negation of the condition used
8853
for the current @code{if}. Similarly you may specify the condition
8854
that is closed by an @code{end}:
8855
8856
@example
8857
if DEBUG
8858
DBG = debug
8859
else !DEBUG
8860
DBG =
8861
endif !DEBUG
8862
@end example
8863
8864
@noindent
8865
Unbalanced conditions are errors.
8866
8867
The @code{else} branch of the above two examples could be omitted,
8868
since assigning the empty string to an otherwise undefined variable
8869
makes no difference.
8870
8871
@unnumberedsec Portability
8872
8873
Note that conditionals in Automake are not the same as conditionals in
8874
GNU Make. Automake conditionals are checked at configure time by the
8875
@file{configure} script, and affect the translation from
8876
@file{Makefile.in} to @file{Makefile}. They are based on options passed
8877
to @file{configure} and on results that @file{configure} has discovered
8878
about the host system. GNU Make conditionals are checked at @command{make}
8879
time, and are based on variables passed to the make program or defined
8880
in the @file{Makefile}.
8881
8882
Automake conditionals will work with any make program.
8883
8884
@unnumberedsec Limits
8885
8886
Conditionals should enclose complete statements like variables or
8887
rules definitions. Automake cannot deal with conditionals used inside
8888
a variable definition, for instance, and is not even able to diagnose
8889
this situation. The following example would not work:
8890
8891
@example
8892
# This syntax is not understood by Automake
8893
AM_CPPFLAGS = \
8894
-DFEATURE_A \
8895
if WANT_DEBUG
8896
-DDEBUG \
8897
endif
8898
-DFEATURE_B
8899
@end example
8900
8901
However the intended definition of @code{AM_CPPFLAGS} can be achieved
8902
with
8903
8904
@example
8905
if WANT_DEBUG
8906
DEBUGFLAGS = -DDEBUG
8907
endif
8908
AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
8909
@end example
8910
8911
@noindent or
8912
8913
@example
8914
AM_CPPFLAGS = -DFEATURE_A
8915
if WANT_DEBUG
8916
AM_CPPFLAGS += -DDEBUG
8917
endif
8918
AM_CPPFLAGS += -DFEATURE_B
8919
@end example
8920
8921
@node Gnits
8922
@chapter The effect of @option{--gnu} and @option{--gnits}
8923
8924
@cindex @option{--gnu}, required files
8925
@cindex @option{--gnu}, complete description
8926
8927
The @option{--gnu} option (or @option{gnu} in the
8928
@code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
8929
the following:
8930
8931
@itemize @bullet
8932
@item
8933
The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
8934
and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
8935
or @file{COPYING}, are required at the topmost directory of the package.
8936
8937
@item
8938
The options @option{no-installman} and @option{no-installinfo} are
8939
prohibited.
8940
@end itemize
8941
8942
Note that this option will be extended in the future to do even more
8943
checking; it is advisable to be familiar with the precise requirements
8944
of the GNU standards. Also, @option{--gnu} can require certain
8945
non-standard GNU programs to exist for use by various maintainer-only
8946
rules; for instance, in the future @command{pathchk} might be required for
8947
@samp{make dist}.
8948
8949
@cindex @option{--gnits}, complete description
8950
8951
The @option{--gnits} option does everything that @option{--gnu} does, and
8952
checks the following as well:
8953
8954
@itemize @bullet
8955
@item
8956
@samp{make installcheck} will check to make sure that the @option{--help}
8957
and @option{--version} really print a usage message and a version string,
8958
respectively. This is the @option{std-options} option (@pxref{Options}).
8959
8960
@item
8961
@samp{make dist} will check to make sure the @file{NEWS} file has been
8962
updated to the current version.
8963
8964
@item
8965
@code{VERSION} is checked to make sure its format complies with Gnits
8966
standards.
8967
@c FIXME xref when standards are finished
8968
8969
@item
8970
@cindex @file{README-alpha}
8971
If @code{VERSION} indicates that this is an alpha release, and the file
8972
@file{README-alpha} appears in the topmost directory of a package, then
8973
it is included in the distribution. This is done in @option{--gnits}
8974
mode, and no other, because this mode is the only one where version
8975
number formats are constrained, and hence the only mode where Automake
8976
can automatically determine whether @file{README-alpha} should be
8977
included.
8978
8979
@item
8980
The file @file{THANKS} is required.
8981
@end itemize
8982
8983
8984
@node Cygnus
8985
@chapter The effect of @option{--cygnus}
8986
8987
@cindex @option{cygnus} strictness
8988
8989
Some packages, notably GNU GCC and GNU gdb, have a build environment
8990
originally written at Cygnus Support (subsequently renamed Cygnus
8991
Solutions, and then later purchased by Red Hat). Packages with this
8992
ancestry are sometimes referred to as ``Cygnus'' trees.
8993
8994
A Cygnus tree has slightly different rules for how a
8995
@file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
8996
@command{automake} will cause any generated @file{Makefile.in} to
8997
comply with Cygnus rules.
8998
8999
Here are the precise effects of @option{--cygnus}:
9000
9001
@itemize @bullet
9002
@item
9003
Info files are always created in the build directory, and not in the
9004
source directory.
9005
9006
@item
9007
@file{texinfo.tex} is not required if a Texinfo source file is
9008
specified. The assumption is that the file will be supplied, but in a
9009
place that Automake cannot find. This assumption is an artifact of how
9010
Cygnus packages are typically bundled.
9011
9012
@item
9013
@samp{make dist} is not supported, and the rules for it are not
9014
generated. Cygnus-style trees use their own distribution mechanism.
9015
9016
@item
9017
Certain tools will be searched for in the build tree as well as in the
9018
user's @env{PATH}. These tools are @command{runtest}, @command{expect},
9019
@command{makeinfo} and @command{texi2dvi}.
9020
9021
@item
9022
@option{--foreign} is implied.
9023
9024
@item
9025
The options @option{no-installinfo} and @option{no-dependencies} are
9026
implied.
9027
9028
@item
9029
The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
9030
required.
9031
9032
@item
9033
The @code{check} target doesn't depend on @code{all}.
9034
@end itemize
9035
9036
GNU maintainers are advised to use @option{gnu} strictness in preference
9037
to the special Cygnus mode. Some day, perhaps, the differences between
9038
Cygnus trees and GNU trees will disappear (for instance, as GCC is made
9039
more standards compliant). At that time the special Cygnus mode will be
9040
removed.
9041
9042
9043
@node Not Enough
9044
@chapter When Automake Isn't Enough
9045
9046
In some situations, where Automake is not up to one task, one has to
9047
resort to handwritten rules or even handwritten @file{Makefile}s.
9048
9049
@menu
9050
* Extending:: Adding new rules or overriding existing ones.
9051
* Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
9052
@end menu
9053
9054
@node Extending
9055
@section Extending Automake Rules
9056
9057
With some minor exceptions (like @code{_PROGRAMS} variables, @code{TESTS},
9058
or @code{XFAIL_TESTS}) being rewritten to append @samp{$(EXEEXT)}), the
9059
contents of a @file{Makefile.am} is copied to @file{Makefile.in} verbatim.
9060
9061
@cindex copying semantics
9062
9063
These copying semantics means that many problems can be worked around
9064
by simply adding some @command{make} variables and rules to
9065
@file{Makefile.am}. Automake will ignore these additions.
9066
9067
@cindex conflicting definitions
9068
@cindex rules, conflicting
9069
@cindex variables, conflicting
9070
@cindex definitions, conflicts
9071
9072
Since a @file{Makefile.in} is built from data gathered from three
9073
different places (@file{Makefile.am}, @file{configure.ac}, and
9074
@command{automake} itself), it is possible to have conflicting
9075
definitions of rules or variables. When building @file{Makefile.in}
9076
the following priorities are respected by @command{automake} to ensure
9077
the user always have the last word. User defined variables in
9078
@file{Makefile.am} have priority over variables @code{AC_SUBST}ed from
9079
@file{configure.ac}, and @code{AC_SUBST}ed variables have priority
9080
over @command{automake}-defined variables. As far rules are
9081
concerned, a user-defined rule overrides any
9082
@command{automake}-defined rule for the same target.
9083
9084
@cindex overriding rules
9085
@cindex overriding semantics
9086
@cindex rules, overriding
9087
9088
These overriding semantics make it possible to fine tune some default
9089
settings of Automake, or replace some of its rules. Overriding
9090
Automake rules is often inadvisable, particularly in the topmost
9091
directory of a package with subdirectories. The @option{-Woverride}
9092
option (@pxref{Invoking Automake}) comes handy to catch overridden
9093
definitions.
9094
9095
Note that Automake does not make any difference between rules with
9096
commands and rules that only specify dependencies. So it is not
9097
possible to append new dependencies to an @command{automake}-defined
9098
target without redefining the entire rule.
9099
9100
@cindex @option{-local} targets
9101
@cindex local targets
9102
9103
However, various useful targets have a @samp{-local} version you can
9104
specify in your @file{Makefile.am}. Automake will supplement the
9105
standard target with these user-supplied targets.
9106
9107
@trindex all
9108
@trindex all-local
9109
@trindex info
9110
@trindex info-local
9111
@trindex dvi
9112
@trindex dvi-local
9113
@trindex ps
9114
@trindex ps-local
9115
@trindex pdf
9116
@trindex pdf-local
9117
@trindex html
9118
@trindex html-local
9119
@trindex check
9120
@trindex check-local
9121
@trindex install
9122
@trindex install-data
9123
@trindex install-data-local
9124
@trindex install-dvi
9125
@trindex install-dvi-local
9126
@trindex install-exec
9127
@trindex install-exec-local
9128
@trindex install-html
9129
@trindex install-html-local
9130
@trindex install-info
9131
@trindex install-info-local
9132
@trindex install-pdf
9133
@trindex install-pdf-local
9134
@trindex install-ps
9135
@trindex install-ps-local
9136
@trindex uninstall
9137
@trindex uninstall-local
9138
@trindex mostlyclean
9139
@trindex mostlyclean-local
9140
@trindex clean
9141
@trindex clean-local
9142
@trindex distclean
9143
@trindex distclean-local
9144
@trindex installdirs
9145
@trindex installdirs-local
9146
@trindex installcheck
9147
@trindex installcheck-local
9148
9149
The targets that support a local version are @code{all}, @code{info},
9150
@code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
9151
@code{install-data}, @code{install-dvi}, @code{install-exec},
9152
@code{install-html}, @code{install-info}, @code{install-pdf},
9153
@code{install-ps}, @code{uninstall}, @code{installdirs},
9154
@code{installcheck} and the various @code{clean} targets
9155
(@code{mostlyclean}, @code{clean}, @code{distclean}, and
9156
@code{maintainer-clean}).
9157
9158
Note that there are no @code{uninstall-exec-local} or
9159
@code{uninstall-data-local} targets; just use @code{uninstall-local}.
9160
It doesn't make sense to uninstall just data or just executables.
9161
9162
For instance, here is one way to erase a subdirectory during
9163
@samp{make clean} (@pxref{Clean}).
9164
9165
@example
9166
clean-local:
9167
-rm -rf testSubDir
9168
@end example
9169
9170
Older version of this manual used to show how to use
9171
@code{install-data-local} to install a file to some hard-coded
9172
location, but you should avoid this. (@pxref{Hard-Coded Install Paths})
9173
9174
@cindex @option{-hook} targets
9175
@cindex hook targets
9176
9177
Some rule also have a way to run another rule, called a @dfn{hook},
9178
after their work is done. The hook is named after the principal target,
9179
with @samp{-hook} appended. The targets allowing hooks are
9180
@code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
9181
and @code{distcheck}.
9182
@trindex install-data-hook
9183
@trindex install-exec-hook
9184
@trindex uninstall-hook
9185
@trindex dist-hook
9186
9187
For instance, here is how to create a hard link to an installed program:
9188
9189
@example
9190
install-exec-hook:
9191
ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
9192
$(DESTDIR)$(bindir)/proglink$(EXEEXT)
9193
@end example
9194
9195
Although cheaper and more portable than symbolic links, hard links
9196
will not work everywhere (for instance, OS/2 does not have
9197
@command{ln}). Ideally you should fall back to @samp{cp -p} when
9198
@command{ln} does not work. An easy way, if symbolic links are
9199
acceptable to you, is to add @code{AC_PROG_LN_S} to
9200
@file{configure.ac} (@pxref{Particular Programs, , Particular Program
9201
Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
9202
@file{Makefile.am}.
9203
9204
@cindex versioned binaries, installing
9205
@cindex installing versioned binaries
9206
@cindex @code{LN_S} example
9207
For instance, here is how you could install a versioned copy of a
9208
program using @samp{$(LN_S)}:
9209
9210
@example
9211
install-exec-hook:
9212
cd $(DESTDIR)$(bindir) && \
9213
mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
9214
$(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
9215
@end example
9216
9217
Note that we rename the program so that a new version will erase the
9218
symbolic link, not the real binary. Also we @command{cd} into the
9219
destination directory in order to create relative links.
9220
9221
When writing @code{install-exec-hook} or @code{install-data-hook},
9222
please bear in mind that the exec/data distinction is based on the
9223
installation directory, not on the primary used (@pxref{Install}). So
9224
a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
9225
@code{barexec_SCRIPTS} will be installed by @code{install-exec}. You
9226
should define your hooks consequently.
9227
9228
@c FIXME should include discussion of variables you can use in these
9229
@c rules
9230
9231
@node Third-Party Makefiles
9232
@section Third-Party @file{Makefile}s
9233
9234
@cindex Third-party packages, interfacing with
9235
@cindex Interfacing with third-party packages
9236
9237
In most projects all @file{Makefile}s are generated by Automake. In
9238
some cases, however, projects need to embed subdirectories with
9239
handwritten @file{Makefile}s. For instance, one subdirectory could be
9240
a third-party project with its own build system, not using Automake.
9241
9242
It is possible to list arbitrary directories in @code{SUBDIRS} or
9243
@code{DIST_SUBDIRS} provided each of these directories has a
9244
@file{Makefile} that recognizes all the following recursive targets.
9245
9246
@cindex recursive targets and third-party @file{Makefile}s
9247
When a user runs one of these targets, that target is run recursively
9248
in all subdirectories. This is why it is important that even
9249
third-party @file{Makefile}s support them.
9250
9251
@table @code
9252
@item all
9253
Compile the entire package. This is the default target in
9254
Automake-generated @file{Makefile}s, but it does not need to be the
9255
default in third-party @file{Makefile}s.
9256
9257
@item distdir
9258
@trindex distdir
9259
@vindex distdir
9260
@vindex top_distdir
9261
Copy files to distribute into @samp{$(distdir)}, before a tarball is
9262
constructed. Of course this target is not required if the
9263
@option{no-dist} option (@pxref{Options}) is used.
9264
9265
The variables @samp{$(top_distdir)} and @samp{$(distdir)}
9266
(@pxref{Dist}) will be passed from the outer package to the subpackage
9267
when the @code{distdir} target is invoked. These two variables have
9268
been adjusted for the directory that is being recursed into, so they
9269
are ready to use.
9270
9271
@item install
9272
@itemx install-data
9273
@itemx install-exec
9274
@itemx uninstall
9275
Install or uninstall files (@pxref{Install}).
9276
9277
@item install-dvi
9278
@itemx install-html
9279
@itemx install-info
9280
@itemx install-ps
9281
@itemx install-pdf
9282
Install only some specific documentation format (@pxref{Texinfo}).
9283
9284
@item installdirs
9285
Create install directories, but do not install any files.
9286
9287
@item check
9288
@itemx installcheck
9289
Check the package (@pxref{Tests}).
9290
9291
@item mostlyclean
9292
@itemx clean
9293
@itemx distclean
9294
@itemx maintainer-clean
9295
Cleaning rules (@pxref{Clean}).
9296
9297
@item dvi
9298
@itemx pdf
9299
@itemx ps
9300
@itemx info
9301
@itemx html
9302
Build the documentation in various formats (@pxref{Texinfo}).
9303
9304
@item tags
9305
@itemx ctags
9306
Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
9307
@end table
9308
9309
If you have ever used Gettext in a project, this is a good example of
9310
how third-party @file{Makefile}s can be used with Automake. The
9311
@file{Makefile}s @command{gettextize} puts in the @file{po/} and
9312
@file{intl/} directories are handwritten @file{Makefile}s that
9313
implement all these targets. That way they can be added to
9314
@code{SUBDIRS} in Automake packages.
9315
9316
Directories that are only listed in @code{DIST_SUBDIRS} but not in
9317
@code{SUBDIRS} need only the @code{distclean},
9318
@code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
9319
Subdirectories}).
9320
9321
Usually, many of these rules are irrelevant to the third-party
9322
subproject, but they are required for the whole package to work. It's
9323
OK to have a rule that does nothing, so if you are integrating a
9324
third-party project with no documentation or tag support, you could
9325
simply augment its @file{Makefile} as follows:
9326
9327
@example
9328
EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
9329
.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
9330
$(EMPTY_AUTOMAKE_TARGETS):
9331
@end example
9332
9333
Another aspect of integrating third-party build systems is whether
9334
they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
9335
subpackage does not support VPATH builds the whole package will not
9336
support VPATH builds. This in turns means that @samp{make distcheck}
9337
will not work, because it relies on VPATH builds. Some people can
9338
live without this (actually, many Automake users have never heard of
9339
@samp{make distcheck}). Other people may prefer to revamp the
9340
existing @file{Makefile}s to support VPATH@. Doing so does not
9341
necessarily require Automake, only Autoconf is needed (@pxref{Build
9342
Directories, , Build Directories, autoconf, The Autoconf Manual}).
9343
The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
9344
and @samp{@@top_builddir@@} are defined by @file{configure} when it
9345
processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
9346
Output Variables, autoconf, The Autoconf Manual}), they are not
9347
computed by the Makefile like the aforementioned @samp{$(distdir)} and
9348
@samp{$(top_distdir)} variables..
9349
9350
It is sometimes inconvenient to modify a third-party @file{Makefile}
9351
to introduce the above required targets. For instance, one may want to
9352
keep the third-party sources untouched to ease upgrades to new
9353
versions.
9354
9355
@cindex @file{GNUmakefile} including @file{Makefile}
9356
Here are two other ideas. If GNU make is assumed, one possibility is
9357
to add to that subdirectory a @file{GNUmakefile} that defines the
9358
required targets and include the third-party @file{Makefile}. For
9359
this to work in VPATH builds, @file{GNUmakefile} must lie in the build
9360
directory; the easiest way to do this is to write a
9361
@file{GNUmakefile.in} instead, and have it processed with
9362
@code{AC_CONFIG_FILES} from the outer package. For example if we
9363
assume @file{Makefile} defines all targets except the documentation
9364
targets, and that the @code{check} target is actually called
9365
@code{test}, we could write @file{GNUmakefile} (or
9366
@file{GNUmakefile.in}) like this:
9367
9368
@example
9369
# First, include the real Makefile
9370
include Makefile
9371
# Then, define the other targets needed by Automake Makefiles.
9372
.PHONY: dvi pdf ps info html check
9373
dvi pdf ps info html:
9374
check: test
9375
@end example
9376
9377
@cindex Proxy @file{Makefile} for third-party packages
9378
A similar idea that does not use @code{include} is to write a proxy
9379
@file{Makefile} that dispatches rules to the real @file{Makefile},
9380
either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
9381
it's OK to rename the original @file{Makefile}) or with @samp{cd
9382
subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
9383
subdirectory project one directory deeper). The good news is that
9384
this proxy @file{Makefile} can be generated with Automake. All we
9385
need are @option{-local} targets (@pxref{Extending}) that perform the
9386
dispatch. Of course the other Automake features are available, so you
9387
could decide to let Automake perform distribution or installation.
9388
Here is a possible @file{Makefile.am}:
9389
9390
@example
9391
all-local:
9392
cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
9393
check-local:
9394
cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
9395
clean-local:
9396
cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
9397
9398
# Assuming the package knows how to install itself
9399
install-data-local:
9400
cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
9401
install-exec-local:
9402
cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
9403
uninstall-local:
9404
cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
9405
9406
# Distribute files from here.
9407
EXTRA_DIST = subdir/Makefile subdir/program.c ...
9408
@end example
9409
9410
Pushing this idea to the extreme, it is also possible to ignore the
9411
subproject build system and build everything from this proxy
9412
@file{Makefile.am}. This might sounds very sensible if you need VPATH
9413
builds but the subproject does not support them.
9414
9415
@node Distributing
9416
@chapter Distributing @file{Makefile.in}s
9417
9418
Automake places no restrictions on the distribution of the resulting
9419
@file{Makefile.in}s. We still encourage software authors to
9420
distribute their work under terms like those of the GPL, but doing so
9421
is not required to use Automake.
9422
9423
Some of the files that can be automatically installed via the
9424
@option{--add-missing} switch do fall under the GPL@. However, these also
9425
have a special exception allowing you to distribute them with your
9426
package, regardless of the licensing you choose.
9427
9428
9429
@node API versioning
9430
@chapter Automake API versioning
9431
9432
New Automake releases usually include bug fixes and new features.
9433
Unfortunately they may also introduce new bugs and incompatibilities.
9434
This makes four reasons why a package may require a particular Automake
9435
version.
9436
9437
Things get worse when maintaining a large tree of packages, each one
9438
requiring a different version of Automake. In the past, this meant that
9439
any developer (and sometime users) had to install several versions of
9440
Automake in different places, and switch @samp{$PATH} appropriately for
9441
each package.
9442
9443
Starting with version 1.6, Automake installs versioned binaries. This
9444
means you can install several versions of Automake in the same
9445
@samp{$prefix}, and can select an arbitrary Automake version by running
9446
@command{automake-1.6} or @command{automake-1.7} without juggling with
9447
@samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
9448
will use @command{automake-1.6} explicitly in their rebuild rules.
9449
9450
The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
9451
not Automake's version. If a bug fix release is made, for instance
9452
Automake 1.6.1, the API version will remain 1.6. This means that a
9453
package that works with Automake 1.6 should also work with 1.6.1; after
9454
all, this is what people expect from bug fix releases.
9455
9456
If your package relies on a feature or a bug fix introduced in
9457
a release, you can pass this version as an option to Automake to ensure
9458
older releases will not be used. For instance, use this in your
9459
@file{configure.ac}:
9460
9461
@example
9462
AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
9463
@end example
9464
@noindent
9465
or, in a particular @file{Makefile.am}:
9466
9467
@example
9468
AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
9469
@end example
9470
@noindent
9471
Automake will print an error message if its version is
9472
older than the requested version.
9473
9474
9475
@heading What is in the API
9476
9477
Automake's programming interface is not easy to define. Basically it
9478
should include at least all @strong{documented} variables and targets
9479
that a @file{Makefile.am} author can use, any behavior associated with
9480
them (e.g., the places where @samp{-hook}'s are run), the command line
9481
interface of @command{automake} and @command{aclocal}, @dots{}
9482
9483
@heading What is not in the API
9484
9485
Every undocumented variable, target, or command line option, is not part
9486
of the API@. You should avoid using them, as they could change from one
9487
version to the other (even in bug fix releases, if this helps to fix a
9488
bug).
9489
9490
If it turns out you need to use such a undocumented feature, contact
9491
@email{automake@@gnu.org} and try to get it documented and exercised by
9492
the test-suite.
9493
9494
@node Upgrading
9495
@chapter Upgrading a Package to a Newer Automake Version
9496
9497
Automake maintains three kind of files in a package.
9498
9499
@itemize
9500
@item @file{aclocal.m4}
9501
@item @file{Makefile.in}s
9502
@item auxiliary tools like @file{install-sh} or @file{py-compile}
9503
@end itemize
9504
9505
@file{aclocal.m4} is generated by @command{aclocal} and contains some
9506
Automake-supplied M4 macros. Auxiliary tools are installed by
9507
@samp{automake --add-missing} when needed. @file{Makefile.in}s are
9508
built from @file{Makefile.am} by @command{automake}, and rely on the
9509
definitions of the M4 macros put in @file{aclocal.m4} as well as the
9510
behavior of the auxiliary tools installed.
9511
9512
Because all these files are closely related, it is important to
9513
regenerate all of them when upgrading to a newer Automake release.
9514
The usual way to do that is
9515
9516
@example
9517
aclocal # with any option needed (such a -I m4)
9518
autoconf
9519
automake --add-missing --force-missing
9520
@end example
9521
9522
@noindent
9523
or more conveniently:
9524
9525
@example
9526
autoreconf -vfi
9527
@end example
9528
9529
The use of @option{--force-missing} ensures that auxiliary tools will be
9530
overridden by new versions (@pxref{Invoking Automake}).
9531
9532
It is important to regenerate all these files each time Automake is
9533
upgraded, even between bug fixes releases. For instance, it is not
9534
unusual for a bug fix to involve changes to both the rules generated
9535
in @file{Makefile.in} and the supporting M4 macros copied to
9536
@file{aclocal.m4}.
9537
9538
Presently @command{automake} is able to diagnose situations where
9539
@file{aclocal.m4} has been generated with another version of
9540
@command{aclocal}. However it never checks whether auxiliary scripts
9541
are up-to-date. In other words, @command{automake} will tell you when
9542
@command{aclocal} needs to be rerun, but it will never diagnose a
9543
missing @option{--force-missing}.
9544
9545
Before upgrading to a new major release, it is a good idea to read the
9546
file @file{NEWS}. This file lists all changes between releases: new
9547
features, obsolete constructs, known incompatibilities, and
9548
workarounds.
9549
9550
@node FAQ
9551
@chapter Frequently Asked Questions about Automake
9552
9553
This chapter covers some questions that often come up on the mailing
9554
lists.
9555
9556
@menu
9557
* CVS:: CVS and generated files
9558
* maintainer-mode:: missing and AM_MAINTAINER_MODE
9559
* wildcards:: Why doesn't Automake support wildcards?
9560
* limitations on file names:: Limitations on source and installed file names
9561
* distcleancheck:: Files left in build directory after distclean
9562
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
9563
* renamed objects:: Why are object files sometimes renamed?
9564
* Per-Object Flags:: How to simulate per-object flags?
9565
* Multiple Outputs:: Writing rules for tools with many output files
9566
* Hard-Coded Install Paths:: Installing to Hard-Coded Locations
9567
@end menu
9568
9569
@node CVS
9570
@section CVS and generated files
9571
9572
@subsection Background: distributed generated files
9573
@cindex generated files, distributed
9574
@cindex rebuild rules
9575
9576
Packages made with Autoconf and Automake ship with some generated
9577
files like @file{configure} or @file{Makefile.in}. These files were
9578
generated on the developer's host and are distributed so that
9579
end-users do not have to install the maintainer tools required to
9580
rebuild them. Other generated files like Lex scanners, Yacc parsers,
9581
or Info documentation, are usually distributed on similar grounds.
9582
9583
Automake outputs rules in @file{Makefile}s to rebuild these files. For
9584
instance, @command{make} will run @command{autoconf} to rebuild
9585
@file{configure} whenever @file{configure.ac} is changed. This makes
9586
development safer by ensuring a @file{configure} is never out-of-date
9587
with respect to @file{configure.ac}.
9588
9589
As generated files shipped in packages are up-to-date, and because
9590
@command{tar} preserves times-tamps, these rebuild rules are not
9591
triggered when a user unpacks and builds a package.
9592
9593
@subsection Background: CVS and timestamps
9594
@cindex timestamps and CVS
9595
@cindex CVS and timestamps
9596
9597
Unless you use CVS keywords (in which case files must be updated at
9598
commit time), CVS preserves timestamp during @samp{cvs commit} and
9599
@samp{cvs import -d} operations.
9600
9601
When you check out a file using @samp{cvs checkout} its timestamp is
9602
set to that of the revision that is being checked out.
9603
9604
However, during @command{cvs update}, files will have the date of the
9605
update, not the original timestamp of this revision. This is meant to
9606
make sure that @command{make} notices sources files have been updated.
9607
9608
This timestamp shift is troublesome when both sources and generated
9609
files are kept under CVS@. Because CVS processes files in alphabetical
9610
order, @file{configure.ac} will appear older than @file{configure}
9611
after a @command{cvs update} that updates both files, even if
9612
@file{configure} was newer than @file{configure.ac} when it was
9613
checked in. Calling @command{make} will then trigger a spurious rebuild
9614
of @file{configure}.
9615
9616
@subsection Living with CVS in Autoconfiscated projects
9617
@cindex CVS and generated files
9618
@cindex generated files and CVS
9619
9620
There are basically two clans amongst maintainers: those who keep all
9621
distributed files under CVS, including generated files, and those who
9622
keep generated files @emph{out} of CVS.
9623
9624
@subsubheading All files in CVS
9625
9626
@itemize @bullet
9627
@item
9628
The CVS repository contains all distributed files so you know exactly
9629
what is distributed, and you can checkout any prior version entirely.
9630
9631
@item
9632
Maintainers can see how generated files evolve (for instance, you can
9633
see what happens to your @file{Makefile.in}s when you upgrade Automake
9634
and make sure they look OK).
9635
9636
@item
9637
Users do not need the autotools to build a checkout of the project, it
9638
works just like a released tarball.
9639
9640
@item
9641
If users use @command{cvs update} to update their copy, instead of
9642
@command{cvs checkout} to fetch a fresh one, timestamps will be
9643
inaccurate. Some rebuild rules will be triggered and attempt to
9644
run developer tools such as @command{autoconf} or @command{automake}.
9645
9646
Actually, calls to such tools are all wrapped into a call to the
9647
@command{missing} script discussed later (@pxref{maintainer-mode}).
9648
@command{missing} will take care of fixing the timestamps when these
9649
tools are not installed, so that the build can continue.
9650
9651
@item
9652
In distributed development, developers are likely to have different
9653
version of the maintainer tools installed. In this case rebuilds
9654
triggered by timestamp lossage will lead to spurious changes
9655
to generated files. There are several solutions to this:
9656
9657
@itemize
9658
@item
9659
All developers should use the same versions, so that the rebuilt files
9660
are identical to files in CVS@. (This starts to be difficult when each
9661
project you work on uses different versions.)
9662
@item
9663
Or people use a script to fix the timestamp after a checkout (the GCC
9664
folks have such a script).
9665
@item
9666
Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
9667
disable all these rebuild rules by default. This is further discussed
9668
in @ref{maintainer-mode}.
9669
@end itemize
9670
9671
@item
9672
Although we focused on spurious rebuilds, the converse can also
9673
happen. CVS's timestamp handling can also let you think an
9674
out-of-date file is up-to-date.
9675
9676
For instance, suppose a developer has modified @file{Makefile.am} and
9677
has rebuilt @file{Makefile.in}. He then decide to do a last-minute
9678
change to @file{Makefile.am} right before checking in both files
9679
(without rebuilding @file{Makefile.in} to account for the change).
9680
9681
This last change to @file{Makefile.am} make the copy of
9682
@file{Makefile.in} out-of-date. Since CVS processes files
9683
alphabetically, when another developer @samp{cvs update} his or her
9684
tree, @file{Makefile.in} will happen to be newer than
9685
@file{Makefile.am}. This other developer will not see
9686
@file{Makefile.in} is out-of-date.
9687
9688
@end itemize
9689
9690
@subsubheading Generated files out of CVS
9691
9692
One way to get CVS and @command{make} working peacefully is to never
9693
store generated files in CVS, i.e., do not CVS-control files that
9694
are @file{Makefile} targets (also called @emph{derived} files).
9695
9696
This way developers are not annoyed by changes to generated files. It
9697
does not matter if they all have different versions (assuming they are
9698
compatible, of course). And finally, timestamps are not lost, changes
9699
to sources files can't be missed as in the
9700
@file{Makefile.am}/@file{Makefile.in} example discussed earlier.
9701
9702
The drawback is that the CVS repository is not an exact copy of what
9703
is distributed and that users now need to install various development
9704
tools (maybe even specific versions) before they can build a checkout.
9705
But, after all, CVS's job is versioning, not distribution.
9706
9707
Allowing developers to use different versions of their tools can also
9708
hide bugs during distributed development. Indeed, developers will be
9709
using (hence testing) their own generated files, instead of the
9710
generated files that will be released actually. The developer who
9711
prepares the tarball might be using a version of the tool that
9712
produces bogus output (for instance a non-portable C file), something
9713
other developers could have noticed if they weren't using their own
9714
versions of this tool.
9715
9716
@subsection Third-party files
9717
@cindex CVS and third-party files
9718
@cindex third-party files and CVS
9719
9720
Another class of files not discussed here (because they do not cause
9721
timestamp issues) are files that are shipped with a package, but
9722
maintained elsewhere. For instance, tools like @command{gettextize}
9723
and @command{autopoint} (from Gettext) or @command{libtoolize} (from
9724
Libtool), will install or update files in your package.
9725
9726
These files, whether they are kept under CVS or not, raise similar
9727
concerns about version mismatch between developers' tools. The
9728
Gettext manual has a section about this, see @ref{CVS Issues, CVS
9729
Issues, Integrating with CVS, gettext, GNU gettext tools}.
9730
9731
@node maintainer-mode
9732
@section @command{missing} and @code{AM_MAINTAINER_MODE}
9733
9734
@subsection @command{missing}
9735
@cindex @command{missing}, purpose
9736
9737
The @command{missing} script is a wrapper around several maintainer
9738
tools, designed to warn users if a maintainer tool is required but
9739
missing. Typical maintainer tools are @command{autoconf},
9740
@command{automake}, @command{bison}, etc. Because file generated by
9741
these tools are shipped with the other sources of a package, these
9742
tools shouldn't be required during a user build and they are not
9743
checked for in @file{configure}.
9744
9745
However, if for some reason a rebuild rule is triggered and involves a
9746
missing tool, @command{missing} will notice it and warn the user.
9747
Besides the warning, when a tool is missing, @command{missing} will
9748
attempt to fix timestamps in a way that allows the build to continue.
9749
For instance, @command{missing} will touch @file{configure} if
9750
@command{autoconf} is not installed. When all distributed files are
9751
kept under CVS, this feature of @command{missing} allows user
9752
@emph{with no maintainer tools} to build a package off CVS, bypassing
9753
any timestamp inconsistency implied by @samp{cvs update}.
9754
9755
If the required tool is installed, @command{missing} will run it and
9756
won't attempt to continue after failures. This is correct during
9757
development: developers love fixing failures. However, users with
9758
wrong versions of maintainer tools may get an error when the rebuild
9759
rule is spuriously triggered, halting the build. This failure to let
9760
the build continue is one of the arguments of the
9761
@code{AM_MAINTAINER_MODE} advocates.
9762
9763
@subsection @code{AM_MAINTAINER_MODE}
9764
@cindex @code{AM_MAINTAINER_MODE}, purpose
9765
@acindex AM_MAINTAINER_MODE
9766
9767
@code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
9768
default. If you have @code{AM_MAINTAINER_MODE} in
9769
@file{configure.ac}, and run @samp{./configure && make}, then
9770
@command{make} will *never* attempt to rebuilt @file{configure},
9771
@file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
9772
build rules for files that are usually distributed and that users
9773
should normally not have to update.
9774
9775
If you run @samp{./configure --enable-maintainer-mode}, then these
9776
rebuild rules will be active.
9777
9778
People use @code{AM_MAINTAINER_MODE} either because they do want their
9779
users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
9780
because they simply can't stand the rebuild rules and prefer running
9781
maintainer tools explicitly.
9782
9783
@code{AM_MAINTAINER_MODE} also allows you to disable some custom build
9784
rules conditionally. Some developers use this feature to disable
9785
rules that need exotic tools that users may not have available.
9786
9787
Several years ago Fran@,{c}ois Pinard pointed out several arguments
9788
against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
9789
insecurity. By removing dependencies you get non-dependable builds:
9790
change to sources files can have no effect on generated files and this
9791
can be very confusing when unnoticed. He adds that security shouldn't
9792
be reserved to maintainers (what @option{--enable-maintainer-mode}
9793
suggests), on the contrary. If one user has to modify a
9794
@file{Makefile.am}, then either @file{Makefile.in} should be updated
9795
or a warning should be output (this is what Automake uses
9796
@command{missing} for) but the last thing you want is that nothing
9797
happens and the user doesn't notice it (this is what happens when
9798
rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
9799
9800
Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
9801
swayed by Fran@,{c}ois's arguments, and got rid of
9802
@code{AM_MAINTAINER_MODE} in all of his packages.
9803
9804
Still many people continue to use @code{AM_MAINTAINER_MODE}, because
9805
it helps them working on projects where all files are kept under CVS,
9806
and because @command{missing} isn't enough if you have the wrong
9807
version of the tools.
9808
9809
9810
@node wildcards
9811
@section Why doesn't Automake support wildcards?
9812
@cindex wildcards
9813
9814
Developers are lazy. They often would like to use wildcards in
9815
@file{Makefile.am}s, so they don't need to remember they have to
9816
update @file{Makefile.am}s every time they add, delete, or rename a
9817
file.
9818
9819
There are several objections to this:
9820
@itemize
9821
@item
9822
When using CVS (or similar) developers need to remember they have to
9823
run @samp{cvs add} or @samp{cvs rm} anyway. Updating
9824
@file{Makefile.am} accordingly quickly becomes a reflex.
9825
9826
Conversely, if your application doesn't compile
9827
because you forgot to add a file in @file{Makefile.am}, it will help
9828
you remember to @samp{cvs add} it.
9829
9830
@item
9831
Using wildcards makes easy to distribute files by mistake. For
9832
instance, some code a developer is experimenting with (a test case,
9833
say) but that should not be part of the distribution.
9834
9835
@item
9836
Using wildcards it's easy to omit some files by mistake. For
9837
instance, one developer creates a new file, uses it at many places,
9838
but forget to commit it. Another developer then checkout the
9839
incomplete project and is able to run `make dist' successfully,
9840
even though a file is missing.
9841
9842
@item
9843
Listing files, you control *exactly* what you distribute.
9844
If some file that should be distributed is missing from your
9845
tree, @samp{make dist} will complain. Besides, you don't distribute
9846
more than what you listed.
9847
9848
@item
9849
Finally it's really hard to @file{forget} adding a file to
9850
@file{Makefile.am}, because if you don't add it, it doesn't get
9851
compiled nor installed, so you can't even test it.
9852
@end itemize
9853
9854
Still, these are philosophical objections, and as such you may disagree,
9855
or find enough value in wildcards to dismiss all of them. Before you
9856
start writing a patch against Automake to teach it about wildcards,
9857
let's see the main technical issue: portability.
9858
9859
Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
9860
not portable to other @command{make} implementations.
9861
9862
The only way Automake could support @command{$(wildcard ...)} is by
9863
expending @command{$(wildcard ...)} when @command{automake} is run.
9864
Resulting @file{Makefile.in}s would be portable since they would
9865
list all files and not use @samp{$(wildcard ...)}. However that
9866
means developers need to remember they must run @command{automake} each
9867
time they add, delete, or rename files.
9868
9869
Compared to editing @file{Makefile.am}, this is really little win. Sure,
9870
it's easier and faster to type @samp{automake; make} than to type
9871
@samp{emacs Makefile.am; make}. But nobody bothered enough to write a
9872
patch add support for this syntax. Some people use scripts to
9873
generated file lists in @file{Makefile.am} or in separate
9874
@file{Makefile} fragments.
9875
9876
Even if you don't care about portability, and are tempted to use
9877
@samp{$(wildcard ...)} anyway because you target only GNU Make, you
9878
should know there are many places where Automake need to know exactly
9879
which files should be processed. As Automake doesn't know how to
9880
expand @samp{$(wildcard ...)}, you cannot use it in these places.
9881
@samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
9882
variables as far Automake is concerned.
9883
9884
You can get warnings about @samp{$(wildcard ...}) constructs using the
9885
@option{-Wportability} flag.
9886
9887
@node limitations on file names
9888
@section Limitations on file names
9889
@cindex file names, limitations on
9890
9891
Automake attempts to support all kinds of file names, even those that
9892
contain unusual characters or are unusually long. However, some
9893
limitations are imposed by the underlying operating system and tools.
9894
9895
Most operating systems prohibit the use of the null byte in file
9896
names, and reserve @samp{/} as a directory separator. Also, they
9897
require that file names are properly encoded for the user's locale.
9898
Automake is subject to these limits.
9899
9900
Portable packages should limit themselves to @acronym{POSIX} file
9901
names. These can contain @acronym{ASCII} letters and digits,
9902
@samp{_}, @samp{.}, and @samp{-}. File names consist of components
9903
separated by @samp{/}. File name components cannot begin with
9904
@samp{-}.
9905
9906
Portable POSIX file names cannot contain components that exceed a
9907
14-byte limit, but nowadays it's normally safe to assume the
9908
more-generous @acronym{XOPEN} limit of 255 bytes. @acronym{POSIX}
9909
limits file names to 255 bytes (@acronym{XOPEN} allows 1023 bytes),
9910
but you may want to limit a source tarball to file names to 99 bytes
9911
to avoid interoperability problems with old versions of @command{tar}.
9912
9913
If you depart from these rules (e.g., by using non-@acronym{ASCII}
9914
characters in file names, or by using lengthy file names), your
9915
installers may have problems for reasons unrelated to Automake.
9916
However, if this does not concern you, you should know about the
9917
limitations imposed by Automake itself. These limitations are
9918
undesirable, but some of them seem to be inherent to underlying tools
9919
like Autoconf, Make, M4, and the shell. They fall into three
9920
categories: install directories, build directories, and file names.
9921
9922
The following characters:
9923
9924
@example
9925
@r{newline} " # $ ' `
9926
@end example
9927
9928
should not appear in the names of install directories. For example,
9929
the operand of @command{configure}'s @option{--prefix} option should
9930
not contain these characters.
9931
9932
Build directories suffer the same limitations as install directories,
9933
and in addition should not contain the following characters:
9934
9935
@example
9936
& @@ \
9937
@end example
9938
9939
For example, the full name of the directory containing the source
9940
files should not contain these characters.
9941
9942
Source and installation file names like @file{main.c} are limited even
9943
further: they should conform to the @acronym{POSIX}/@acronym{XOPEN}
9944
rules described above. In addition, if you plan to port to
9945
non-@acronym{POSIX} environments, you should avoid file names that
9946
differ only in case (e.g., @file{makefile} and @file{Makefile}).
9947
Nowadays it is no longer worth worrying about the 8.3 limits of
9948
@acronym{DOS} file systems.
9949
9950
@node distcleancheck
9951
@section Files left in build directory after distclean
9952
@cindex @code{distclean}, diagnostic
9953
@cindex @samp{make distclean}, diagnostic
9954
@cindex dependencies and distributed files
9955
@trindex distclean
9956
@trindex distcleancheck
9957
9958
This is a diagnostic you might encounter while running @samp{make
9959
distcheck}.
9960
9961
As explained in @ref{Dist}, @samp{make distcheck} attempts to build
9962
and check your package for errors like this one.
9963
9964
@samp{make distcheck} will perform a @code{VPATH} build of your
9965
package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
9966
Files left in the build directory after @samp{make distclean} has run
9967
are listed after this error.
9968
9969
This diagnostic really covers two kinds of errors:
9970
9971
@itemize @bullet
9972
@item
9973
files that are forgotten by distclean;
9974
@item
9975
distributed files that are erroneously rebuilt.
9976
@end itemize
9977
9978
The former left-over files are not distributed, so the fix is to mark
9979
them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
9980
more explanations.
9981
9982
The latter bug is not always easy to understand and fix, so let's
9983
proceed with an example. Suppose our package contains a program for
9984
which we want to build a man page using @command{help2man}. GNU
9985
@command{help2man} produces simple manual pages from the @option{--help}
9986
and @option{--version} output of other commands (@pxref{Top, , Overview,
9987
help2man, The Help2man Manual}). Because we don't to force want our
9988
users to install @command{help2man}, we decide to distribute the
9989
generated man page using the following setup.
9990
9991
@example
9992
# This Makefile.am is bogus.
9993
bin_PROGRAMS = foo
9994
foo_SOURCES = foo.c
9995
dist_man_MANS = foo.1
9996
9997
foo.1: foo$(EXEEXT)
9998
help2man --output=foo.1 ./foo$(EXEEXT)
9999
@end example
10000
10001
This will effectively distribute the man page. However,
10002
@samp{make distcheck} will fail with:
10003
10004
@example
10005
ERROR: files left in build directory after distclean:
10006
./foo.1
10007
@end example
10008
10009
Why was @file{foo.1} rebuilt? Because although distributed,
10010
@file{foo.1} depends on a non-distributed built file:
10011
@file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
10012
will always appear to be newer than the distributed @file{foo.1}.
10013
10014
@samp{make distcheck} caught an inconsistency in our package. Our
10015
intent was to distribute @file{foo.1} so users do not need installing
10016
@command{help2man}, however since this our rule causes this file to be
10017
always rebuilt, users @emph{do} need @command{help2man}. Either we
10018
should ensure that @file{foo.1} is not rebuilt by users, or there is
10019
no point in distributing @file{foo.1}.
10020
10021
More generally, the rule is that distributed files should never depend
10022
on non-distributed built files. If you distribute something
10023
generated, distribute its sources.
10024
10025
One way to fix the above example, while still distributing
10026
@file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
10027
assuming @command{foo --version} and @command{foo --help} do not
10028
change unless @file{foo.c} or @file{configure.ac} change, we could
10029
write the following @file{Makefile.am}:
10030
10031
@example
10032
bin_PROGRAMS = foo
10033
foo_SOURCES = foo.c
10034
dist_man_MANS = foo.1
10035
10036
foo.1: foo.c $(top_srcdir)/configure.ac
10037
$(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
10038
help2man --output=foo.1 ./foo$(EXEEXT)
10039
@end example
10040
10041
This way, @file{foo.1} will not get rebuilt every time
10042
@file{foo$(EXEEXT)} changes. The @command{make} call makes sure
10043
@file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
10044
way to ensure this would be to use separate directories for binaries
10045
and man pages, and set @code{SUBDIRS} so that binaries are built
10046
before man pages.
10047
10048
We could also decide not to distribute @file{foo.1}. In
10049
this case it's fine to have @file{foo.1} dependent upon
10050
@file{foo$(EXEEXT)}, since both will have to be rebuilt.
10051
However it would be impossible to build the package in a
10052
cross-compilation, because building @file{foo.1} involves
10053
an @emph{execution} of @file{foo$(EXEEXT)}.
10054
10055
Another context where such errors are common is when distributed files
10056
are built by tools that are built by the package. The pattern is
10057
similar:
10058
10059
@example
10060
distributed-file: built-tools distributed-sources
10061
build-command
10062
@end example
10063
10064
@noindent
10065
should be changed to
10066
10067
@example
10068
distributed-file: distributed-sources
10069
$(MAKE) $(AM_MAKEFLAGS) built-tools
10070
build-command
10071
@end example
10072
10073
@noindent
10074
or you could choose not to distribute @file{distributed-file}, if
10075
cross-compilation does not matter.
10076
10077
The points made through these examples are worth a summary:
10078
10079
@cartouche
10080
@itemize
10081
@item
10082
Distributed files should never depend upon non-distributed built
10083
files.
10084
@item
10085
Distributed files should be distributed with all their dependencies.
10086
@item
10087
If a file is @emph{intended} to be rebuilt by users, then there is no point
10088
in distributing it.
10089
@end itemize
10090
@end cartouche
10091
10092
@vrindex distcleancheck_listfiles
10093
For desperate cases, it's always possible to disable this check by
10094
setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
10095
Make sure you do understand the reason why @samp{make distcheck}
10096
complains before you do this. @code{distcleancheck_listfiles} is a
10097
way to @emph{hide} errors, not to fix them. You can always do better.
10098
10099
@node Flag Variables Ordering
10100
@section Flag Variables Ordering
10101
@cindex Ordering flag variables
10102
@cindex Flag variables, ordering
10103
10104
@display
10105
What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
10106
@code{mumble_CFLAGS}?
10107
@end display
10108
10109
@display
10110
Why does @command{automake} output @code{CPPFLAGS} after
10111
@code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
10112
@end display
10113
10114
@display
10115
My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
10116
one @file{Makefile.am} I would like to append a new flag, however if I
10117
put the flag into @code{AM_CXXFLAGS} it is prepended to the other
10118
flags, not appended.
10119
@end display
10120
10121
@subsection Compile Flag Variables
10122
@cindex Flag Variables, Ordering
10123
@cindex Compile Flag Variables
10124
@cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
10125
@cindex @code{AM_CFLAGS} and @code{CFLAGS}
10126
@cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
10127
@cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
10128
@cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
10129
@cindex @code{AM_FFLAGS} and @code{FFLAGS}
10130
@cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
10131
@cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
10132
@cindex @code{AM_LFLAGS} and @code{LFLAGS}
10133
@cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
10134
@cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
10135
@cindex @code{AM_RFLAGS} and @code{RFLAGS}
10136
@cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
10137
@cindex @code{AM_YFLAGS} and @code{YFLAGS}
10138
@cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
10139
@cindex @code{CFLAGS} and @code{AM_CFLAGS}
10140
@cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
10141
@cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
10142
@cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
10143
@cindex @code{FFLAGS} and @code{AM_FFLAGS}
10144
@cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
10145
@cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
10146
@cindex @code{LFLAGS} and @code{AM_LFLAGS}
10147
@cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
10148
@cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
10149
@cindex @code{RFLAGS} and @code{AM_RFLAGS}
10150
@cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
10151
@cindex @code{YFLAGS} and @code{AM_YFLAGS}
10152
10153
This section attempts to answer all the above questions. We will
10154
mostly discuss @code{CPPFLAGS} in our examples, but actually the
10155
answer holds for all the compile flags used in Automake:
10156
@code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
10157
@code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
10158
@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
10159
@code{UPCFLAGS}, and @code{YFLAGS}.
10160
10161
@code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
10162
three variables that can be used to pass flags to the C preprocessor
10163
(actually these variables are also used for other languages like C++
10164
or preprocessed Fortran). @code{CPPFLAGS} is the user variable
10165
(@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
10166
and @code{mumble_CPPFLAGS} is the variable specific to the
10167
@code{mumble} target (we call this a per-target variable,
10168
@pxref{Program and Library Variables}).
10169
10170
Automake always uses two of these variables when compiling C sources
10171
files. When compiling an object file for the @code{mumble} target,
10172
the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
10173
@code{AM_CPPFLAGS} otherwise. The second variable is always
10174
@code{CPPFLAGS}.
10175
10176
In the following example,
10177
10178
@example
10179
bin_PROGRAMS = foo bar
10180
foo_SOURCES = xyz.c
10181
bar_SOURCES = main.c
10182
foo_CPPFLAGS = -DFOO
10183
AM_CPPFLAGS = -DBAZ
10184
@end example
10185
10186
@noindent
10187
@file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
10188
(because @file{xyz.o} is part of the @code{foo} target), while
10189
@file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
10190
(because there is no per-target variable for target @code{bar}).
10191
10192
The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
10193
being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
10194
is a user variable, i.e., a variable that users are entitled to modify
10195
in order to compile the package. This variable, like many others,
10196
is documented at the end of the output of @samp{configure --help}.
10197
10198
For instance, someone who needs to add @file{/home/my/usr/include} to
10199
the C compiler's search path would configure a package with
10200
10201
@example
10202
./configure CPPFLAGS='-I /home/my/usr/include'
10203
@end example
10204
10205
@noindent
10206
and this flag would be propagated to the compile rules of all
10207
@file{Makefile}s.
10208
10209
It is also not uncommon to override a user variable at
10210
@command{make}-time. Many installers do this with @code{prefix}, but
10211
this can be useful with compiler flags too. For instance, if, while
10212
debugging a C++ project, you need to disable optimization in one
10213
specific object file, you can run something like
10214
10215
@example
10216
rm file.o
10217
make CXXFLAGS=-O0 file.o
10218
make
10219
@end example
10220
10221
The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
10222
@samp{$(mumble_CPPFLAGS)} in the compile command is that users
10223
should always have the last say. It probably makes more sense if you
10224
think about it while looking at the @samp{CXXFLAGS=-O0} above, which
10225
should supersede any other switch from @code{AM_CXXFLAGS} or
10226
@code{mumble_CXXFLAGS} (and this of course replaces the previous value
10227
of @code{CXXFLAGS}).
10228
10229
You should never redefine a user variable such as @code{CPPFLAGS} in
10230
@file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
10231
mistakes. Even something like
10232
10233
@example
10234
CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
10235
@end example
10236
10237
@noindent
10238
is erroneous. Although this preserves @file{configure}'s value of
10239
@code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
10240
user attempts to override @code{CPPFLAGS} from the @command{make}
10241
command line.
10242
10243
@example
10244
AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
10245
@end example
10246
10247
@noindent
10248
is all what is needed here if no per-target flags are used.
10249
10250
You should not add options to these user variables within
10251
@file{configure} either, for the same reason. Occasionally you need
10252
to modify these variables to perform a test, but you should reset
10253
their values afterwards. In contrast, it is OK to modify the
10254
@samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
10255
them, but it is rather rare that you need to do this, unless you
10256
really want to change the default definitions of the @samp{AM_}
10257
variables in all @file{Makefile}s.
10258
10259
What we recommend is that you define extra flags in separate
10260
variables. For instance, you may write an Autoconf macro that computes
10261
a set of warning options for the C compiler, and @code{AC_SUBST} them
10262
in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
10263
determines which compiler and which linker flags should be used to
10264
link with library @file{libfoo}, and @code{AC_SUBST} these in
10265
@code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
10266
@file{Makefile.am} could use these variables as follows:
10267
10268
@example
10269
AM_CFLAGS = $(WARNINGCFLAGS)
10270
bin_PROGRAMS = prog1 prog2
10271
prog1_SOURCES = @dots{}
10272
prog2_SOURCES = @dots{}
10273
prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
10274
prog2_LDFLAGS = $(LIBFOOLDFLAGS)
10275
@end example
10276
10277
In this example both programs will be compiled with the flags
10278
substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
10279
additionally be compiled with the flags required to link with
10280
@file{libfoo}.
10281
10282
Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
10283
variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
10284
every target in a @file{Makefile.in}.
10285
10286
Using variables like this gives you full control over the ordering of
10287
the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
10288
you want to negate for a particular target, you can use something like
10289
@samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
10290
been forcefully appended to @code{CFLAGS}, there would be no way to
10291
disable one flag. Yet another reason to leave user variables to
10292
users.
10293
10294
Finally, we have avoided naming the variable of the example
10295
@code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
10296
Automake to think that this is actually a per-target variable (like
10297
@code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
10298
10299
@subsection Other Variables
10300
10301
There are other variables in Automake that follow similar principles
10302
to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
10303
use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
10304
DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
10305
@code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
10306
(@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
10307
@code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
10308
(@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
10309
of these rules do support per-target flags (yet).
10310
10311
To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
10312
obeys this naming scheme. The slight difference is that
10313
@code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
10314
@command{make} itself.
10315
10316
However you should not think that all variables ending with
10317
@code{FLAGS} follow this convention. For instance,
10318
@code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}),
10319
@code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
10320
are two variables that are only useful to the maintainer and have no
10321
user counterpart.
10322
10323
@code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
10324
has neither @code{AM_} nor per-target cousin.
10325
10326
Finally you should not think either that the existence of a per-target
10327
variable implies that of an @code{AM_} variable or that of a user
10328
variable. For instance, the @code{mumble_LDADD} per-target variable
10329
overrides the global @code{LDADD} variable (which is not a user
10330
variable), and @code{mumble_LIBADD} exists only as a per-target
10331
variable. @xref{Program and Library Variables}.
10332
10333
10334
@node renamed objects
10335
@section Why are object files sometimes renamed?
10336
10337
This happens when per-target compilation flags are used. Object
10338
files need to be renamed just in case they would clash with object
10339
files compiled from the same sources, but with different flags.
10340
Consider the following example.
10341
10342
@example
10343
bin_PROGRAMS = true false
10344
true_SOURCES = generic.c
10345
true_CPPFLAGS = -DEXIT_CODE=0
10346
false_SOURCES = generic.c
10347
false_CPPFLAGS = -DEXIT_CODE=1
10348
@end example
10349
@noindent
10350
Obviously the two programs are built from the same source, but it
10351
would be bad if they shared the same object, because @file{generic.o}
10352
cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
10353
@samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
10354
build two different objects: @file{true-generic.o} and
10355
@file{false-generic.o}.
10356
10357
@command{automake} doesn't actually look whether source files are
10358
shared to decide if it must rename objects. It will just rename all
10359
objects of a target as soon as it sees per-target compilation flags
10360
are used.
10361
10362
It's OK to share object files when per-target compilation flags are not
10363
used. For instance, @file{true} and @file{false} will both use
10364
@file{version.o} in the following example.
10365
10366
@example
10367
AM_CPPFLAGS = -DVERSION=1.0
10368
bin_PROGRAMS = true false
10369
true_SOURCES = true.c version.c
10370
false_SOURCES = false.c version.c
10371
@end example
10372
10373
Note that the renaming of objects is also affected by the
10374
@code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
10375
10376
10377
@node Per-Object Flags
10378
@section Per-Object Flags Emulation
10379
@cindex Per-object flags, emulated
10380
10381
@display
10382
One of my source files needs to be compiled with different flags. How
10383
do I do?
10384
@end display
10385
10386
Automake supports per-program and per-library compilation flags (see
10387
@ref{Program and Library Variables} and @ref{Flag Variables
10388
Ordering}). With this you can define compilation flags that apply to
10389
all files compiled for a target. For instance, in
10390
10391
@example
10392
bin_PROGRAMS = foo
10393
foo_SOURCES = foo.c foo.h bar.c bar.h main.c
10394
foo_CFLAGS = -some -flags
10395
@end example
10396
10397
@noindent
10398
@file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
10399
compiled with @samp{-some -flags}. (If you wonder about the names of
10400
these object files, see @ref{renamed objects}.) Note that
10401
@code{foo_CFLAGS} gives the flags to use when compiling all the C
10402
sources of the @emph{program} @code{foo}, it has nothing to do with
10403
@file{foo.c} or @file{foo-foo.o} specifically.
10404
10405
What if @file{foo.c} needs to be compiled into @file{foo.o} using some
10406
specific flags, that none of the other files require? Obviously
10407
per-program flags are not directly applicable here. Something like
10408
per-object flags are expected, i.e., flags that would be used only
10409
when creating @file{foo-foo.o}. Automake does not support that,
10410
however this is easy to simulate using a library that contains only
10411
that object, and compiling this library with per-library flags.
10412
10413
@example
10414
bin_PROGRAMS = foo
10415
foo_SOURCES = bar.c bar.h main.c
10416
foo_CFLAGS = -some -flags
10417
foo_LDADD = libfoo.a
10418
noinst_LIBRARIES = libfoo.a
10419
libfoo_a_SOURCES = foo.c foo.h
10420
libfoo_a_CFLAGS = -some -other -flags
10421
@end example
10422
10423
Here @file{foo-bar.o} and @file{foo-main.o} will all be
10424
compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
10425
be compiled using @samp{-some -other -flags}. Eventually, all
10426
three objects will be linked to form @file{foo}.
10427
10428
This trick can also be achieved using Libtool convenience libraries,
10429
for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
10430
Convenience Libraries}).
10431
10432
Another tempting idea to implement per-object flags is to override the
10433
compile rules @command{automake} would output for these files.
10434
Automake will not define a rule for a target you have defined, so you
10435
could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
10436
We recommend against this, because this is error prone. For instance,
10437
if you add such a rule to the first example, it will break the day you
10438
decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
10439
compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
10440
objects}). Also in order to support dependency tracking, the two
10441
@file{.o}/@file{.obj} extensions, and all the other flags variables
10442
involved in a compilation, you will end up modifying a copy of the
10443
rule previously output by @command{automake} for this file. If a new
10444
release of Automake generates a different rule, your copy will need to
10445
be updated by hand.
10446
10447
@node Multiple Outputs
10448
@section Handling Tools that Produce Many Outputs
10449
@cindex multiple outputs, rules with
10450
@cindex many outputs, rules with
10451
@cindex rules with multiple outputs
10452
10453
This section describes a @command{make} idiom that can be used when a
10454
tool produces multiple output files. It is not specific to Automake
10455
and can be used in ordinary @file{Makefile}s.
10456
10457
Suppose we have a program called @command{foo} that will read one file
10458
called @file{data.foo} and produce two files named @file{data.c} and
10459
@file{data.h}. We want to write a @file{Makefile} rule that captures
10460
this one-to-two dependency.
10461
10462
The naive rule is incorrect:
10463
10464
@example
10465
# This is incorrect.
10466
data.c data.h: data.foo
10467
foo data.foo
10468
@end example
10469
10470
@noindent
10471
What the above rule really says is that @file{data.c} and
10472
@file{data.h} each depend on @file{data.foo}, and can each be built by
10473
running @samp{foo data.foo}. In other words it is equivalent to:
10474
10475
@example
10476
# We do not want this.
10477
data.c: data.foo
10478
foo data.foo
10479
data.h: data.foo
10480
foo data.foo
10481
@end example
10482
10483
@noindent
10484
which means that @command{foo} can be run twice. Usually it will not
10485
be run twice, because @command{make} implementations are smart enough
10486
to check for the existence of the second file after the first one has
10487
been built; they will therefore detect that it already exists.
10488
However there are a few situations where it can run twice anyway:
10489
10490
@itemize
10491
@item
10492
The most worrying case is when running a parallel @command{make}. If
10493
@file{data.c} and @file{data.h} are built in parallel, two @samp{foo
10494
data.foo} commands will run concurrently. This is harmful.
10495
@item
10496
Another case is when the dependency (here @file{data.foo}) is
10497
(or depends upon) a phony target.
10498
@end itemize
10499
10500
A solution that works with parallel @command{make} but not with
10501
phony dependencies is the following:
10502
10503
@example
10504
data.c data.h: data.foo
10505
foo data.foo
10506
data.h: data.c
10507
@end example
10508
10509
@noindent
10510
The above rules are equivalent to
10511
10512
@example
10513
data.c: data.foo
10514
foo data.foo
10515
data.h: data.foo data.c
10516
foo data.foo
10517
@end example
10518
@noindent
10519
therefore a parallel @command{make} will have to serialize the builds
10520
of @file{data.c} and @file{data.h}, and will detect that the second is
10521
no longer needed once the first is over.
10522
10523
Using this pattern is probably enough for most cases. However it does
10524
not scale easily to more output files (in this scheme all output files
10525
must be totally ordered by the dependency relation), so we will
10526
explore a more complicated solution.
10527
10528
Another idea is to write the following:
10529
10530
@example
10531
# There is still a problem with this one.
10532
data.c: data.foo
10533
foo data.foo
10534
data.h: data.c
10535
@end example
10536
10537
@noindent
10538
The idea is that @samp{foo data.foo} is run only when @file{data.c}
10539
needs to be updated, but we further state that @file{data.h} depends
10540
upon @file{data.c}. That way, if @file{data.h} is required and
10541
@file{data.foo} is out of date, the dependency on @file{data.c} will
10542
trigger the build.
10543
10544
This is almost perfect, but suppose we have built @file{data.h} and
10545
@file{data.c}, and then we erase @file{data.h}. Then, running
10546
@samp{make data.h} will not rebuild @file{data.h}. The above rules
10547
just state that @file{data.c} must be up-to-date with respect to
10548
@file{data.foo}, and this is already the case.
10549
10550
What we need is a rule that forces a rebuild when @file{data.h} is
10551
missing. Here it is:
10552
10553
@example
10554
data.c: data.foo
10555
foo data.foo
10556
data.h: data.c
10557
## Recover from the removal of $@@
10558
@@if test -f $@@; then :; else \
10559
rm -f data.c; \
10560
$(MAKE) $(AM_MAKEFLAGS) data.c; \
10561
fi
10562
@end example
10563
10564
The above scheme can be extended to handle more outputs and more
10565
inputs. One of the outputs is selected to serve as a witness to the
10566
successful completion of the command, it depends upon all inputs, and
10567
all other outputs depend upon it. For instance, if @command{foo}
10568
should additionally read @file{data.bar} and also produce
10569
@file{data.w} and @file{data.x}, we would write:
10570
10571
@example
10572
data.c: data.foo data.bar
10573
foo data.foo data.bar
10574
data.h data.w data.x: data.c
10575
## Recover from the removal of $@@
10576
@@if test -f $@@; then :; else \
10577
rm -f data.c; \
10578
$(MAKE) $(AM_MAKEFLAGS) data.c; \
10579
fi
10580
@end example
10581
10582
However there are now two minor problems in this setup. One is related
10583
to the timestamp ordering of @file{data.h}, @file{data.w},
10584
@file{data.x}, and @file{data.c}. The other one is a race condition
10585
if a parallel @command{make} attempts to run multiple instances of the
10586
recover block at once.
10587
10588
Let us deal with the first problem. @command{foo} outputs four files,
10589
but we do not know in which order these files are created. Suppose
10590
that @file{data.h} is created before @file{data.c}. Then we have a
10591
weird situation. The next time @command{make} is run, @file{data.h}
10592
will appear older than @file{data.c}, the second rule will be
10593
triggered, a shell will be started to execute the @samp{if@dots{}fi}
10594
command, but actually it will just execute the @code{then} branch,
10595
that is: nothing. In other words, because the witness we selected is
10596
not the first file created by @command{foo}, @command{make} will start
10597
a shell to do nothing each time it is run.
10598
10599
A simple riposte is to fix the timestamps when this happens.
10600
10601
@example
10602
data.c: data.foo data.bar
10603
foo data.foo data.bar
10604
data.h data.w data.x: data.c
10605
@@if test -f $@@; then \
10606
touch $@@; \
10607
else \
10608
## Recover from the removal of $@@
10609
rm -f data.c; \
10610
$(MAKE) $(AM_MAKEFLAGS) data.c; \
10611
fi
10612
@end example
10613
10614
Another solution is to use a different and dedicated file as witness,
10615
rather than using any of @command{foo}'s outputs.
10616
10617
@example
10618
data.stamp: data.foo data.bar
10619
@@rm -f data.tmp
10620
@@touch data.tmp
10621
foo data.foo data.bar
10622
@@mv -f data.tmp $@@
10623
data.c data.h data.w data.x: data.stamp
10624
## Recover from the removal of $@@
10625
@@if test -f $@@; then :; else \
10626
rm -f data.stamp; \
10627
$(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10628
fi
10629
@end example
10630
10631
@file{data.tmp} is created before @command{foo} is run, so it has a
10632
timestamp older than output files output by @command{foo}. It is then
10633
renamed to @file{data.stamp} after @command{foo} has run, because we
10634
do not want to update @file{data.stamp} if @command{foo} fails.
10635
10636
This solution still suffers from the second problem: the race
10637
condition in the recover rule. If, after a successful build, a user
10638
erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
10639
@command{make} may start both recover rules in parallel. If the two
10640
instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
10641
data.stamp} concurrently the build is likely to fail (for instance, the
10642
two rules will create @file{data.tmp}, but only one can rename it).
10643
10644
Admittedly, such a weird situation does not arise during ordinary
10645
builds. It occurs only when the build tree is mutilated. Here
10646
@file{data.c} and @file{data.h} have been explicitly removed without
10647
also removing @file{data.stamp} and the other output files.
10648
@code{make clean; make} will always recover from these situations even
10649
with parallel makes, so you may decide that the recover rule is solely
10650
to help non-parallel make users and leave things as-is. Fixing this
10651
requires some locking mechanism to ensure only one instance of the
10652
recover rule rebuilds @file{data.stamp}. One could imagine something
10653
along the following lines.
10654
10655
@example
10656
data.c data.h data.w data.x: data.stamp
10657
## Recover from the removal of $@@
10658
@@if test -f $@@; then :; else \
10659
trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
10660
## mkdir is a portable test-and-set
10661
if mkdir data.lock 2>/dev/null; then \
10662
## This code is being executed by the first process.
10663
rm -f data.stamp; \
10664
$(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10665
result=$$?; rm -rf data.lock; exit $$result; \
10666
else \
10667
## This code is being executed by the follower processes.
10668
## Wait until the first process is done.
10669
while test -d data.lock; do sleep 1; done; \
10670
## Succeed if and only if the first process succeeded.
10671
test -f data.stamp; \
10672
fi; \
10673
fi
10674
@end example
10675
10676
Using a dedicated witness, like @file{data.stamp}, is very handy when
10677
the list of output files is not known beforehand. As an illustration,
10678
consider the following rules to compile many @file{*.el} files into
10679
@file{*.elc} files in a single command. It does not matter how
10680
@code{ELFILES} is defined (as long as it is not empty: empty targets
10681
are not accepted by POSIX).
10682
10683
@example
10684
ELFILES = one.el two.el three.el @dots{}
10685
ELCFILES = $(ELFILES:=c)
10686
10687
elc-stamp: $(ELFILES)
10688
@@rm -f elc-temp
10689
@@touch elc-temp
10690
$(elisp_comp) $(ELFILES)
10691
@@mv -f elc-temp $@@
10692
10693
$(ELCFILES): elc-stamp
10694
## Recover from the removal of $@@
10695
@@if test -f $@@; then :; else \
10696
trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
10697
if mkdir elc-lock 2>/dev/null; then \
10698
## This code is being executed by the first process.
10699
rm -f elc-stamp; \
10700
$(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
10701
rmdir elc-lock; \
10702
else \
10703
## This code is being executed by the follower processes.
10704
## Wait until the first process is done.
10705
while test -d elc-lock; do sleep 1; done; \
10706
## Succeed if and only if the first process succeeded.
10707
test -f elc-stamp; exit $$?; \
10708
fi; \
10709
fi
10710
@end example
10711
10712
For completeness it should be noted that GNU @command{make} is able to
10713
express rules with multiple output files using pattern rules
10714
(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
10715
Manual}). We do not discuss pattern rules here because they are not
10716
portable, but they can be convenient in packages that assume GNU
10717
@command{make}.
10718
10719
10720
@node Hard-Coded Install Paths
10721
@section Installing to Hard-Coded Locations
10722
10723
@display
10724
My package needs to install some configuration file. I tried to use
10725
the following rule, but @samp{make distcheck} fails. Why?
10726
10727
@example
10728
# Do not do this.
10729
install-data-local:
10730
$(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
10731
@end example
10732
@end display
10733
10734
@display
10735
My package needs to populate the installation directory of another
10736
package at install-time. I can easily compute that installation
10737
directory in @file{configure}, but if I install files therein,
10738
@samp{make distcheck} fails. How else should I do?
10739
@end display
10740
10741
These two setups share their symptoms: @samp{make distcheck} fails
10742
because they are installing files to hard-coded paths. In the later
10743
case the path is not really hard-coded in the package, but we can
10744
consider it to be hard-coded in the system (or in whichever tool that
10745
supplies the path). As long as the path does not use any of the
10746
standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
10747
@samp{$(datadir)}, etc.), the effect will be the same:
10748
user-installations are impossible.
10749
10750
When a (non-root) user wants to install a package, he usually has no
10751
right to install anything in @file{/usr} or @file{/usr/local}. So he
10752
does something like @samp{./configure --prefix ~/usr} to install
10753
package in his own @file{~/usr} tree.
10754
10755
If a package attempts to install something to some hard-coded path
10756
(e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
10757
then the installation will fail. @samp{make distcheck} performs such
10758
a @option{--prefix} installation, hence it will fail too.
10759
10760
Now, there are some easy solutions.
10761
10762
The above @code{install-data-local} example for installing
10763
@file{/etc/afile} would be better replaced by
10764
10765
@example
10766
sysconf_DATA = afile
10767
@end example
10768
10769
@noindent
10770
by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
10771
this is what the GNU Standards require. When such a package is
10772
installed on a FHS compliant system, the installer will have to set
10773
@samp{--sysconfdir=/etc}. As the maintainer of the package you
10774
should not be concerned by such site policies: use the appropriate
10775
standard directory variable to install your files so that installer
10776
can easily redefine these variables to match their site conventions.
10777
10778
Installing files that should be used by another package, is slightly
10779
more involved. Let's take an example and assume you want to install
10780
shared library that is a Python extension module. If you ask Python
10781
where to install the library, it will answer something like this:
10782
10783
@example
10784
% @kbd{python -c 'from distutils import sysconfig;
10785
print sysconfig.get_python_lib(1,0)'}
10786
/usr/lib/python2.3/site-packages
10787
@end example
10788
10789
If you indeed use this absolute path to install your shared library,
10790
non-root users will not be able to install the package, hence
10791
distcheck fails.
10792
10793
Let's do better. The @samp{sysconfig.get_python_lib()} function
10794
actually accepts a third argument that will replace Python's
10795
installation prefix.
10796
10797
@example
10798
% @kbd{python -c 'from distutils import sysconfig;
10799
print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
10800
$@{exec_prefix@}/lib/python2.3/site-packages
10801
@end example
10802
10803
You can also use this new path. If you do
10804
@itemize @bullet
10805
@item
10806
root users can install your package with the same @option{--prefix}
10807
as Python (you get the behavior of the previous attempt)
10808
10809
@item
10810
non-root users can install your package too, they will have the
10811
extension module in a place that is not searched by Python but they
10812
can work around this using environment variables (and if you installed
10813
scripts that use this shared library, it's easy to tell Python were to
10814
look in the beginning of your script, so the script works in both
10815
cases).
10816
@end itemize
10817
10818
The @code{AM_PATH_PYTHON} macro uses similar commands to define
10819
@samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
10820
10821
Of course not all tools are as advanced as Python regarding that
10822
substitution of @var{prefix}. So another strategy is to figure the
10823
part of the of the installation directory that must be preserved. For
10824
instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
10825
computes @samp{$(lispdir)}:
10826
10827
@example
10828
$EMACS -batch -q -eval '(while load-path
10829
(princ (concat (car load-path) "\n"))
10830
(setq load-path (cdr load-path)))' >conftest.out
10831
lispdir=`sed -n
10832
-e 's,/$,,'
10833
-e '/.*\/lib\/x*emacs\/site-lisp$/@{
10834
s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
10835
@}'
10836
-e '/.*\/share\/x*emacs\/site-lisp$/@{
10837
s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
10838
@}'
10839
conftest.out`
10840
@end example
10841
10842
I.e., it just picks the first directory that looks like
10843
@file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
10844
the search path of emacs, and then substitutes @samp{$@{libdir@}} or
10845
@samp{$@{datadir@}} appropriately.
10846
10847
The emacs case looks complicated because it processes a list and
10848
expect two possible layouts, otherwise it's easy, and the benefit for
10849
non-root users are really worth the extra @command{sed} invocation.
10850
10851
10852
@node History
10853
@chapter History of Automake
10854
10855
This chapter presents various aspects of the history of Automake. The
10856
exhausted reader can safely skip it; this will be more of interest to
10857
nostalgic people, or to those curious to learn about the evolution of
10858
Automake.
10859
10860
@menu
10861
* Timeline:: The Automake story.
10862
* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
10863
* Releases:: Statistics about Automake Releases
10864
@end menu
10865
10866
@node Timeline
10867
@section Timeline
10868
10869
@table @asis
10870
@item 1994-09-19 First CVS commit.
10871
10872
If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
10873
working on Automake (or AutoMake, as it was spelt then) this Monday.
10874
10875
The first version of the @command{automake} script looks as follows.
10876
10877
@example
10878
#!/bin/sh
10879
10880
status=0
10881
10882
for makefile
10883
do
10884
if test ! -f $@{makefile@}.am; then
10885
echo "automake: $@{makefile@}.am: No such honkin' file"
10886
status=1
10887
continue
10888
fi
10889
10890
exec 4> $@{makefile@}.in
10891
10892
done
10893
@end example
10894
10895
From this you can already see that Automake will be about reading
10896
@file{*.am} file and producing @file{*.in} files. You cannot see
10897
anything else, but if you also know that David is the one who created
10898
Autoconf two years before you can guess the rest.
10899
10900
Several commits follow, and by the end of the day Automake is
10901
reported to work for GNU fileutils and GNU m4.
10902
10903
The modus operandi is the one that is still used today: variables
10904
assignments in @file{Makefile.am} files trigger injections of
10905
precanned @file{Makefile} fragments into the generated
10906
@file{Makefile.in}. The use of @file{Makefile} fragments was inspired
10907
by the 4.4BSD @command{make} and include files, however Automake aims
10908
to be portable and to conform to the GNU standards for @file{Makefile}
10909
variables and targets.
10910
10911
At this point, the most recent release of Autoconf is version 1.11,
10912
and David is preparing to release Autoconf 2.0 in late October. As a
10913
matter of fact, he will barely touch Automake after September.
10914
10915
@item 1994-11-05 David MacKenzie's last commit.
10916
10917
At this point Automake is a 200 line portable shell script, plus 332
10918
lines of @file{Makefile} fragments. In the @file{README}, David
10919
states his ambivalence between ``portable shell'' and ``more
10920
appropriate language'':
10921
10922
@quotation
10923
I wrote it keeping in mind the possibility of it becoming an Autoconf
10924
macro, so it would run at configure-time. That would slow
10925
configuration down a bit, but allow users to modify the Makefile.am
10926
without needing to fetch the AutoMake package. And, the Makefile.in
10927
files wouldn't need to be distributed. But all of AutoMake would. So
10928
I might reimplement AutoMake in Perl, m4, or some other more
10929
appropriate language.
10930
@end quotation
10931
10932
Automake is described as ``an experimental Makefile generator''.
10933
There is no documentation. Adventurous users are referred to the
10934
examples and patches needed to use Automake with GNU m4 1.3, fileutils
10935
3.9, time 1.6, and development versions of find and indent.
10936
10937
These examples seem to have been lost. However at the time of writing
10938
(10 years later in September, 2004) the FSF still distributes a
10939
package that uses this version of Automake: check out GNU termutils
10940
2.0.
10941
10942
@item 1995-11-12 Tom Tromey's first commit.
10943
10944
After one year of inactivity, Tom Tromey takes over the package.
10945
Tom was working on GNU cpio back then, and doing this just for fun,
10946
having trouble finding a project to contribute to. So while hacking
10947
he wanted to bring the @file{Makefile.in} up to GNU standards. This
10948
was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
10949
grabbed it and tried it out.
10950
10951
Tom didn't talk to djm about it until later, just to make sure he
10952
didn't mind if he made a release. He did a bunch of early releases to
10953
the Gnits folks.
10954
10955
Gnits was (and still is) totally informal, just a few GNU friends who
10956
Fran@,cois Pinard knew, who were all interested in making a common
10957
infrastructure for GNU projects, and shared a similar outlook on how
10958
to do it. So they were able to make some progress. It came along
10959
with Autoconf and extensions thereof, and then Automake from David and
10960
Tom (who were both gnitsians). One of their ideas was to write a
10961
document paralleling the GNU standards, that was more strict in some
10962
ways and more detailed. They never finished the GNITS standards, but
10963
the ideas mostly made their way into Automake.
10964
10965
@item 1995-11-23 Automake 0.20
10966
10967
Besides introducing automatic dependency tracking (@pxref{Dependency
10968
Tracking Evolution}), this version also supplies a 9-page manual.
10969
10970
At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
10971
exist, so many things had to be done by hand. For instance, here is
10972
what a configure.in (this is the former name of the
10973
@file{configure.ac} we use today) must contain in order to use
10974
Automake 0.20:
10975
10976
@example
10977
PACKAGE=cpio
10978
VERSION=2.3.911
10979
AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
10980
AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
10981
AC_SUBST(PACKAGE)
10982
AC_SUBST(VERSION)
10983
AC_ARG_PROGRAM
10984
AC_PROG_INSTALL
10985
@end example
10986
10987
(Today all of the above is achieved by @code{AC_INIT} and
10988
@code{AM_INIT_AUTOMAKE}.)
10989
10990
Here is how programs are specified in @file{Makefile.am}:
10991
10992
@example
10993
PROGRAMS = hello
10994
hello_SOURCES = hello.c
10995
@end example
10996
10997
This looks pretty much like what we do today, except the
10998
@code{PROGRAMS} variable has no directory prefix specifying where
10999
@file{hello} should be installed: all programs are installed in
11000
@samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
11001
that must be built but not installed (it is called
11002
@code{noinst_PROGRAMS} nowadays).
11003
11004
Programs can be built conditionally using @code{AC_SUBST}itutions:
11005
11006
@example
11007
PROGRAMS = @@progs@@
11008
AM_PROGRAMS = foo bar baz
11009
@end example
11010
11011
(@code{AM_PROGRAMS} has since then been renamed to
11012
@code{EXTRA_PROGRAMS}.)
11013
11014
Similarly scripts, static libraries, and data can built and installed
11015
using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
11016
However @code{LIBRARIES} were treated a bit specially in that Automake
11017
did automatically supply the @file{lib} and @file{.a} prefixes.
11018
Therefore to build @file{libcpio.a}, one had to write
11019
11020
@example
11021
LIBRARIES = cpio
11022
cpio_SOURCES = ...
11023
@end example
11024
11025
Extra files to distribute must be listed in @code{DIST_OTHER} (the
11026
ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
11027
distributed should appear in @code{DIST_SUBDIRS}, but the manual
11028
describes this as a temporary ugly hack (today extra directories should
11029
also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
11030
for another purpose, @pxref{Conditional Subdirectories}).
11031
11032
@item 1995-11-26 Automake 0.21
11033
11034
In less time that it takes to cook a frozen pizza, Tom rewrites
11035
Automake using Perl. At this time Perl 5 is only one year old, and
11036
Perl 4.036 is in use at many sites. Supporting several Perl versions
11037
has been a source of problems through the whole history of Automake.
11038
11039
If you never used Perl 4, imagine Perl 5 without objects, without
11040
@samp{my} variables (only dynamically scoped @samp{local} variables),
11041
without function prototypes, with function calls that needs to be
11042
prefixed with @samp{&}, etc. Traces of this old style can still be
11043
found in today's @command{automake}.
11044
11045
@item 1995-11-28 Automake 0.22
11046
@itemx 1995-11-29 Automake 0.23
11047
11048
Bug fixes.
11049
11050
@item 1995-12-08 Automake 0.24
11051
@itemx 1995-12-10 Automake 0.25
11052
11053
Releases are raining. 0.24 introduces the uniform naming scheme we
11054
use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
11055
@code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
11056
@code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
11057
in use; and @code{TEXINFOS} and @code{MANS} still have no directory
11058
prefixes.) Adding support for prefixes like that was one of the major
11059
ideas in automake; it has lasted pretty well.
11060
11061
AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
11062
Pinard's doing).
11063
11064
0.25 fixes a Perl 4 portability bug.
11065
11066
@item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
11067
@item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
11068
11069
@item 1996-01-03 Automake 0.26
11070
@itemx 1996-01-03 Automake 0.27
11071
11072
Of the many change and suggestions sent by Fran@,cois Pinard and
11073
included in 0.26, the most important is perhaps the advise that to
11074
ease customization a user rule or variable definition should always
11075
override an Automake rule or definition.
11076
11077
Gordon Matzigkeit and Jim Meyering are two other early contributors
11078
that have been sending fixes.
11079
11080
0.27 fixes yet another Perl 4 portability bug.
11081
11082
@item 1996-01-13 Automake 0.28
11083
11084
Automake starts scanning @file{configure.in} for @code{LIBOBJS}
11085
support. This is an important step because until this version
11086
Automake did only know about the @file{Makefile.am}s it processed.
11087
@file{configure.in} was Autoconf's world and the link between Autoconf
11088
and Automake had to be done by the @file{Makefile.am} author. For
11089
instance, if @file{config.h} was generated by @file{configure}, it was the
11090
package maintainer's responsibility to define the @code{CONFIG_HEADER}
11091
variable in each @file{Makefile.am}.
11092
11093
Succeeding releases will rely more and more on scanning
11094
@file{configure.in} to better automate the Autoconf integration.
11095
11096
0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
11097
@option{--gnu} and @option{--gnits} options, the latter being stricter.
11098
11099
@item 1996-02-07 Automake 0.29
11100
11101
Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
11102
and rebuild rules for @file{configure}-generated file are
11103
automatically output.
11104
11105
@code{TEXINFOS} and @code{MANS} converted to the uniform naming
11106
scheme.
11107
11108
@item 1996-02-24 Automake 0.30
11109
11110
The test suite is born. It contains 9 tests. From now on test cases
11111
will be added pretty regularly (@pxref{Releases}), and this proved to
11112
be really helpful later on.
11113
11114
@code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
11115
11116
All the third-party Autoconf macros, written mostly by Fran@,cois
11117
Pinard (and later Jim Meyering), are distributed in Automake's
11118
hand-written @file{aclocal.m4} file. Package maintainers are expected
11119
to extract the necessary macros from this file. (In previous version
11120
you had to copy and paste them from the manual...)
11121
11122
@item 1996-03-11 Automake 0.31
11123
11124
The test suite in 0.30 was run via a long @code{check-local} rule. Upon
11125
Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
11126
whenever the @code{TESTS} variable is defined.
11127
11128
@code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
11129
prefix is introduced. The syntax is now the same as today.
11130
11131
@item 1996-03-15 Gordon Matzigkeit starts writing libtool.
11132
11133
@item 1996-04-27 Automake 0.32
11134
11135
@code{-hook} targets are introduced; an idea from Dieter Baron.
11136
11137
@file{*.info} files, which were output in the build directory are
11138
now built in the source directory, because they are distributed. It
11139
seems these files like to move back and forth as that will happen
11140
again in future versions.
11141
11142
@item 1996-05-18 Automake 0.33
11143
11144
Gord Matzigkeit's main two contributions:
11145
11146
@itemize
11147
@item very preliminary libtool support
11148
@item the distcheck rule
11149
@end itemize
11150
11151
Although they were very basic at this point, these are probably
11152
among the top features for Automake today.
11153
11154
Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
11155
since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
11156
author (@pxref{maintainer-mode}).
11157
11158
@item 1996-05-28 Automake 1.0
11159
11160
After only six months of heavy development, the automake script is
11161
3134 lines long, plus 973 lines of @file{Makefile} fragments. The
11162
package has 30 pages of documentation, and 38 test cases.
11163
@file{aclocal.m4} contains 4 macros.
11164
11165
From now on and until version 1.4, new releases will occur at a rate
11166
of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
11167
been the name of beta releases for 1.2. This is the first time
11168
Automake uses suffix letters to designate beta releases, an habit that
11169
lasts.
11170
11171
@item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
11172
11173
@item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
11174
11175
Between June and October, the Autoconf development is almost staled.
11176
Roland McGrath has been working at the beginning of the year. David
11177
comes back in November to release 2.12, but he won't touch Autoconf
11178
anymore after this year, and Autoconf then really stagnates. The
11179
desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
11180
11181
@item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
11182
11183
The mailing list is announced as follows:
11184
@smallexample
11185
I've created the "automake" mailing list. It is
11186
"automake@@gnu.ai.mit.edu". Administrivia, as always, to
11187
automake-request@@gnu.ai.mit.edu.
11188
11189
The charter of this list is discussion of automake, autoconf, and
11190
other configuration/portability tools (e.g., libtool). It is expected
11191
that discussion will range from pleas for help all the way up to
11192
patches.
11193
11194
This list is archived on the FSF machines. Offhand I don't know if
11195
you can get the archive without an account there.
11196
11197
This list is open to anybody who wants to join. Tell all your
11198
friends!
11199
-- Tom Tromey
11200
@end smallexample
11201
11202
Before that people were discussing Automake privately, on the Gnits
11203
mailing list (which is not public either), and less frequently on
11204
@code{gnu.misc.discuss}.
11205
11206
@code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
11207
noticed. The archives of the early years of the
11208
@code{automake@@gnu.org} list have been lost, so today it is almost
11209
impossible to find traces of discussions that occurred before 1999.
11210
This has been annoying more than once, as such discussions can be
11211
useful to understand the rationale behind a piece of uncommented code
11212
that was introduced back then.
11213
11214
@item 1997-06-22 Automake 1.2
11215
11216
Automake developments continues, and more and more new Autoconf macros
11217
are required. Distributing them in @file{aclocal.m4} and requiring
11218
people to browse this file to extract the relevant macros becomes
11219
uncomfortable. Ideally, some of them should be contributed to
11220
Autoconf so that they can be used directly, however Autoconf is
11221
currently inactive. Automake 1.2 consequently introduces
11222
@command{aclocal} (@command{aclocal} was actually started on
11223
1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
11224
file from a repository of third-party macros. Because Autoconf has
11225
stalled, Automake also becomes a kind of repository for such
11226
third-party macros, even macros completely unrelated to Automake (for
11227
instance macros that fix broken Autoconf macros).
11228
11229
The 1.2 release contains 20 macros, among which the
11230
@code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
11231
@file{configure.in}.
11232
11233
Libtool is fully supported using @code{*_LTLIBRARIES}.
11234
11235
The missing script is introduced by Fran@,cois Pinard; it is meant to be
11236
a better solution than @code{AM_MAINTAINER_MODE}
11237
(@pxref{maintainer-mode}).
11238
11239
Conditionals support was implemented by Ian Lance Taylor. At the
11240
time, Tom and Ian were working on an internal project at Cygnus. They
11241
were using ILU, which is pretty similar to CORBA@. They wanted to
11242
integrate ILU into their build, which was all @file{configure}-based,
11243
and Ian thought that adding conditionals to @command{automake} was
11244
simpler than doing all the work in @file{configure} (which was the
11245
standard at the time). So this was actually funded by Cygnus.
11246
11247
This very useful but tricky feature will take a lot of time to
11248
stabilize. (At the time this text is written, there are still
11249
primaries that have not been updated to support conditional
11250
definitions in Automake 1.9.)
11251
11252
The @command{automake} script has almost doubled: 6089 lines of Perl,
11253
plus 1294 lines of @file{Makefile} fragments.
11254
11255
@item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
11256
11257
@item 1998-04-05 Automake 1.3
11258
11259
This is a small advance compared to 1.2.
11260
It add support for assembly, and preliminary support for Java.
11261
11262
Perl 5.004_04 is out, but fixes to support Perl 4 are still
11263
regularly submitted whenever Automake breaks it.
11264
11265
@item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
11266
11267
Sourceware was setup by Jason Molenda to host open source projects.
11268
11269
@item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
11270
@itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake
11271
Automake is now hosted on @code{sourceware.cygnus.com}. It has a
11272
publicly accessible CVS repository. This CVS repository is a copy of
11273
the one Tom was using on his machine, which in turn is based on
11274
a copy of the CVS repository of David MacKenzie. This is why we still
11275
have to full source history. (Automake was on Sourceware until 2007-10-29,
11276
when it moved to a git repository on @code{savannah.gnu.org},
11277
but the Sourceware host had been renamed to @code{sources.redhat.com}.)
11278
11279
The oldest file in the administrative directory of the CVS repository
11280
that was created on Sourceware is dated 1998-09-19, while the
11281
announcement that @command{automake} and @command{autoconf} had joined
11282
@command{sourceware} was made on 1998-10-26. They were among the
11283
first projects to be hosted there.
11284
11285
The heedful reader will have noticed Automake was exactly 4-year-old
11286
on 1998-09-19.
11287
11288
@item 1999-01-05 Ben Elliston releases Autoconf 2.13.
11289
11290
@item 1999-01-14 Automake 1.4
11291
11292
This release adds support for Fortran 77 and for the @code{include}
11293
statement. Also, @samp{+=} assignments are introduced, but it is
11294
still quite easy to fool Automake when mixing this with conditionals.
11295
11296
These two releases, Automake 1.4 and Autoconf 2.13 makes a duo that
11297
will be used together for years.
11298
11299
@command{automake} is 7228 lines, plus 1591 lines of Makefile
11300
fragment, 20 macros (some 1.3 macros were finally contributed back to
11301
Autoconf), 197 test cases, and 51 pages of documentation.
11302
11303
@item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
11304
11305
This implements a new dependency tracking schemed that should be
11306
able to handle automatic dependency tracking using any compiler (not
11307
just gcc) and any make (not just GNU @command{make}). In addition,
11308
the new scheme should be more reliable than the old one, as
11309
dependencies are generated on the end user's machine. Alexandre Oliva
11310
creates depcomp for this purpose.
11311
11312
@xref{Dependency Tracking Evolution}, for more details about the
11313
evolution of automatic dependency tracking in Automake.
11314
11315
@item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
11316
11317
This was a huge problem since we also had patches going in on the
11318
trunk. The merge took a long time and was very painful.
11319
11320
@item 2000-05-10
11321
11322
Since September 1999 and until 2003, Akim Demaille will be zealously
11323
revamping Autoconf.
11324
11325
@quotation
11326
I think the next release should be called "3.0".@*
11327
Let's face it: you've basically rewritten autoconf.@*
11328
Every weekend there are 30 new patches.@*
11329
I don't see how we could call this "2.15" with a straight face.@*
11330
-- Tom Tromey on @email{autoconf@@gnu.org}
11331
@end quotation
11332
11333
Actually Akim works like a submarine: he will pile up patches while he
11334
works off-line during the weekend, and flush them in batch when he
11335
resurfaces on Monday.
11336
11337
@item 2001-01-24
11338
11339
On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
11340
is out, and Akim has to find something to do during his week-end :)
11341
11342
@item 2001-01-28
11343
11344
Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
11345
11346
@quotation
11347
Aiieeee! I was dreading the day that the Demaillator turned his
11348
sights on automake@dots{} and now it has arrived! -- Tom Tromey
11349
@end quotation
11350
11351
It's only the beginning: in two months he will send 192 patches. Then
11352
he would slow down so Tom can catch up and review all this. Initially
11353
Tom actually read all these patches, then he probably trustingly
11354
answered OK to most of them, and finally gave up and let Akim apply
11355
whatever he wanted. There was no way to keep up with that patch rate.
11356
11357
@quotation
11358
Anyway the patch below won't apply since it predates Akim's
11359
sourcequake; I have yet to figure where the relevant passage has
11360
been moved :) -- Alexandre Duret-Lutz
11361
@end quotation
11362
11363
All these patches were sent to and discussed on
11364
@email{automake@@gnu.org}, so subscribed users were literally drown in
11365
technical mails. Eventually, the @email{automake-patches@@gnu.org}
11366
mailing list was created in May.
11367
11368
Year after year, Automake had drifted away from its initial design:
11369
construct @file{Makefile.in} by assembling various @file{Makefile}
11370
fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
11371
various places in the @command{automake} script itself; this does not
11372
help ensuring a consistent treatment of these rules (for instance
11373
making sure that user-defined rules override Automake's own rules).
11374
One of Akim's goal was moving all these hard-coded rules to separate
11375
@file{Makefile} fragments, so the logic could be centralized in a
11376
@file{Makefile} fragment processor.
11377
11378
Another significant contribution of Akim is the interface with the
11379
``trace'' feature of Autoconf. The way to scan @file{configure.in} at
11380
this time was to read the file and grep the various macro of interest
11381
to Automake. Doing so could break in many unexpected ways; automake
11382
could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
11383
where the arguments are known only when M4 is run), or conversely it
11384
could detect some macro that was not expanded (because it is called
11385
conditionally). In the CVS version of Autoconf, Akim had implemented
11386
the @option{--trace} option, which provides accurate information about
11387
where macros are actually called and with what arguments. Akim will
11388
equip Automake with a second @file{configure.in} scanner that uses
11389
this @option{--trace} interface. Since it was not sensible to drop the
11390
Autoconf 2.13 compatibility yet, this experimental scanner was only
11391
used when an environment variable was set, the traditional
11392
grep-scanner being still the default.
11393
11394
@item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
11395
11396
It has been more than two years since Automake 1.4, CVS Automake has
11397
suffered lot's of heavy changes and still is not ready for release.
11398
Libtool 1.4 had to be distributed with a patch against Automake 1.4.
11399
11400
@item 2001-05-08 Automake 1.4-p1
11401
@itemx 2001-05-24 Automake 1.4-p2
11402
11403
Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
11404
release'' of Automake:
11405
11406
@quotation
11407
The main purpose of this release is to have a stable automake
11408
which is compatible with the latest stable libtool.
11409
@end quotation
11410
11411
The release also contains obvious fixes for bugs in Automake 1.4,
11412
some of which were reported almost monthly.
11413
11414
@item 2001-05-21 Akim Demaille releases Autoconf 2.50
11415
11416
@item 2001-06-07 Automake 1.4-p3
11417
@itemx 2001-06-10 Automake 1.4-p4
11418
@itemx 2001-07-15 Automake 1.4-p5
11419
11420
Gary continues his patch-release series. These also add support for
11421
some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
11422
@file{configure.ac} over @file{configure.in}, and it introduces a new
11423
syntax for @code{AC_OUTPUT}ing files.
11424
11425
@item 2001-08-23 Automake 1.5
11426
11427
A major and long-awaited release, that comes more than two years after
11428
1.4. It brings many changes, among which:
11429
@itemize
11430
@item The new dependency tracking scheme that uses @command{depcomp}.
11431
Aside from the improvement on the dependency tracking itself
11432
(@pxref{Dependency Tracking Evolution}), this also streamlines the use
11433
of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
11434
used during development are now the same as those used in
11435
distributions. Before that the @file{Makefile.in}s generated for
11436
maintainers required GNU @command{make} and GCC, they were different
11437
from the portable @file{Makefile} generated for distribution; this was
11438
causing some confusion.
11439
11440
@item Support for per-target compilation flags.
11441
11442
@item Support for reference to files in subdirectories in most
11443
@file{Makefile.am} variables.
11444
11445
@item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
11446
prefixes.
11447
@item Perl 4 support is finally dropped.
11448
@end itemize
11449
11450
1.5 did broke several packages that worked with 1.4. Enough so that
11451
Linux distributions could not easily install the new Automake version
11452
without breaking many of the packages for which they had to run
11453
@command{automake}.
11454
11455
Some of these breakages were effectively bugs that would eventually be
11456
fixed in the next release. However, a lot of damage was caused by
11457
some changes made deliberately to render Automake stricter on some
11458
setup we did consider bogus. For instance, @samp{make distcheck} was
11459
improved to check that @samp{make uninstall} did remove all the files
11460
@samp{make install} installed, that @samp{make distclean} did not omit
11461
some file, and that a VPATH build would work even if the source
11462
directory was read-only. Similarly, Automake now rejects multiple
11463
definitions of the same variable (because that would mix very badly
11464
with conditionals), and @samp{+=} assignments with no previous
11465
definition. Because these changes all occurred suddenly after 1.4 had
11466
been established for more than two years, it hurt users.
11467
11468
To make matter worse, meanwhile Autoconf (now at version 2.52) was
11469
facing similar troubles, for similar reasons.
11470
11471
@item 2002-03-05 Automake 1.6
11472
11473
This release introduced versioned installation (@pxref{API
11474
versioning}). This was mainly pushed by Havoc Pennington, taking the
11475
GNOME source tree as motive: due to incompatibilities between the
11476
autotools it's impossible for the GNOME packages to switch to Autoconf
11477
2.53 and Automake 1.5 all at once, so they are currently stuck with
11478
Autoconf 2.13 and Automake 1.4.
11479
11480
The idea was to call this version @file{automake-1.6}, call all its
11481
bug-fix versions identically, and switch to @file{automake-1.7} for
11482
the next release that adds new features or changes some rules. This
11483
scheme implies maintaining a bug-fix branch in addition to the
11484
development trunk, which means more work from the maintainer, but
11485
providing regular bug-fix releases proved to be really worthwhile.
11486
11487
Like 1.5, 1.6 also introduced a bunch of incompatibilities, meant or
11488
not. Perhaps the more annoying was the dependence on the newly
11489
released Autoconf 2.53. Autoconf seemed to have stabilized enough
11490
since its explosive 2.50 release, and included changes required to fix
11491
some bugs in Automake. In order to upgrade to Automake 1.6, people
11492
now had to upgrade Autoconf too; for some packages it was no picnic.
11493
11494
While versioned installation helped people to upgrade, it also
11495
unfortunately allowed people not to upgrade. At the time of writing,
11496
some Linux distributions are shipping packages for Automake 1.4, 1.5,
11497
1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
11498
Some distribution also call 1.4 the ``stable'' version, and present
11499
``1.9'' as the development version; this does not really makes sense
11500
since 1.9 is way more solid than 1.4. All this does not help the
11501
newcomer.
11502
11503
@item 2002-04-11 Automake 1.6.1
11504
11505
1.6, and the upcoming 1.4-p6 release were the last release by Tom.
11506
This one and those following will be handled by Alexandre
11507
Duret-Lutz. Tom is still around, and will be there until about 1.7,
11508
but his interest into Automake is drifting away towards projects like
11509
@command{gcj}.
11510
11511
Alexandre has been using Automake since 2000, and started to
11512
contribute mostly on Akim's incitement (Akim and Alexandre have been
11513
working in the same room from 1999 to 2002). In 2001 and 2002 he had
11514
a lot of free time to enjoy hacking Automake.
11515
11516
@item 2002-06-14 Automake 1.6.2
11517
11518
@item 2002-07-28 Automake 1.6.3
11519
@itemx 2002-07-28 Automake 1.4-p6
11520
11521
Two releases on the same day. 1.6.3 is a bug-fix release.
11522
11523
Tom Tromey backported the versioned installation mechanism on the 1.4
11524
branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
11525
side by side. Another request from the GNOME folks.
11526
11527
@item 2002-09-25 Automake 1.7
11528
11529
This release switches to the new @file{configure.ac} scanner Akim
11530
was experimenting in 1.5.
11531
11532
@item 2002-10-16 Automake 1.7.1
11533
@itemx 2002-12-06 Automake 1.7.2
11534
@itemx 2003-02-20 Automake 1.7.3
11535
@itemx 2003-04-23 Automake 1.7.4
11536
@itemx 2003-05-18 Automake 1.7.5
11537
@itemx 2003-07-10 Automake 1.7.6
11538
@itemx 2003-09-07 Automake 1.7.7
11539
@itemx 2003-10-07 Automake 1.7.8
11540
11541
Many bug-fix releases. 1.7 lasted because the development version
11542
(upcoming 1.8) was suffering some major internal revamping.
11543
11544
@item 2003-10-26 Automake on screen
11545
11546
Episode 49, `Repercussions', in the third season of the `Alias' TV
11547
show is first aired.
11548
11549
Marshall, one of the character, is working on a computer virus that he
11550
has to modify before it gets into the wrong hands or something like
11551
that. The screenshots you see do not show any program code, they show
11552
a @file{Makefile.in} @code{generated by automake}...
11553
11554
@item 2003-11-09 Automake 1.7.9
11555
11556
@item 2003-12-10 Automake 1.8
11557
11558
The most striking update is probably that of @command{aclocal}.
11559
11560
@command{aclocal} now uses @code{m4_include} in the produced
11561
@file{aclocal.m4} when the included macros are already distributed
11562
with the package (an idiom used in many packages), which reduces code
11563
duplication. Many people liked that, but in fact this change was
11564
really introduced to fix a bug in rebuild rules: @file{Makefile.in}
11565
must be rebuilt whenever a dependency of @file{configure} changes, but
11566
all the @file{m4} files included in @file{aclocal.m4} where unknown
11567
from @command{automake}. Now @command{automake} can just trace the
11568
@code{m4_include}s to discover the dependencies.
11569
11570
@command{aclocal} also starts using the @option{--trace} Autoconf option
11571
in order to discover used macros more accurately. This will turn out
11572
to be very tricky (later releases will improve this) as people had
11573
devised many ways to cope with the limitation of previous
11574
@command{aclocal} versions, notably using handwritten
11575
@code{m4_include}s: @command{aclocal} must make sure not to redefine a
11576
rule that is already included by such statement.
11577
11578
Automake also has seen its guts rewritten. Although this rewriting
11579
took a lot of efforts, it is only apparent to the users in that some
11580
constructions previously disallowed by the implementation now work
11581
nicely. Conditionals, Locations, Variable and Rule definitions,
11582
Options: these items on which Automake works have been rewritten as
11583
separate Perl modules, and documented.
11584
11585
@itemx 2004-01-11 Automake 1.8.1
11586
@itemx 2004-01-12 Automake 1.8.2
11587
@itemx 2004-03-07 Automake 1.8.3
11588
@itemx 2004-04-25 Automake 1.8.4
11589
@itemx 2004-05-16 Automake 1.8.5
11590
11591
@item 2004-07-28 Automake 1.9
11592
11593
This release tries to simplify the compilation rules it outputs to
11594
reduce the size of the Makefile. The complaint initially come from
11595
the libgcj developers. Their @file{Makefile.in} generated with
11596
Automake 1.4 and custom build rules (1.4 did not support compiled
11597
Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
11598
down to 1.2MB@.
11599
11600
Aside from this it contains mainly minor changes and bug-fixes.
11601
11602
@itemx 2004-08-11 Automake 1.9.1
11603
@itemx 2004-09-19 Automake 1.9.2
11604
11605
Automake has ten years. This chapter of the manual was initially
11606
written for this occasion.
11607
11608
@itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
11609
git as primary repository.
11610
11611
@end table
11612
11613
@node Dependency Tracking Evolution
11614
@section Dependency Tracking in Automake
11615
11616
Over the years Automake has deployed three different dependency
11617
tracking methods. Each method, including the current one, has had
11618
flaws of various sorts. Here we lay out the different dependency
11619
tracking methods, their flaws, and their fixes. We conclude with
11620
recommendations for tool writers, and by indicating future directions
11621
for dependency tracking work in Automake.
11622
11623
@subsection First Take
11624
@unnumberedsubsubsec Description
11625
11626
Our first attempt at automatic dependency tracking was based on the
11627
method recommended by GNU @command{make}. (@pxref{Automatic
11628
Prerequisites, , Generating Prerequisites Automatically, make, The GNU
11629
make Manual})
11630
11631
This version worked by precomputing dependencies ahead of time. For
11632
each source file, it had a special @file{.P} file that held the
11633
dependencies. There was a rule to generate a @file{.P} file by
11634
invoking the compiler appropriately. All such @file{.P} files were
11635
included by the @file{Makefile}, thus implicitly becoming dependencies
11636
of @file{Makefile}.
11637
11638
@unnumberedsubsubsec Bugs
11639
11640
This approach had several critical bugs.
11641
11642
@itemize
11643
@item
11644
The code to generate the @file{.P} file relied on @command{gcc}.
11645
(A limitation, not technically a bug.)
11646
@item
11647
The dependency tracking mechanism itself relied on GNU @command{make}.
11648
(A limitation, not technically a bug.)
11649
@item
11650
Because each @file{.P} file was a dependency of @file{Makefile}, this
11651
meant that dependency tracking was done eagerly by @command{make}.
11652
For instance, @samp{make clean} would cause all the dependency files
11653
to be updated, and then immediately removed. This eagerness also
11654
caused problems with some configurations; if a certain source file
11655
could not be compiled on a given architecture for some reason,
11656
dependency tracking would fail, aborting the entire build.
11657
@item
11658
As dependency tracking was done as a pre-pass, compile times were
11659
doubled--the compiler had to be run twice per source file.
11660
@item
11661
@samp{make dist} re-ran @command{automake} to generate a
11662
@file{Makefile} that did not have automatic dependency tracking (and
11663
that was thus portable to any version of @command{make}). In order to
11664
do this portably, Automake had to scan the dependency files and remove
11665
any reference that was to a source file not in the distribution.
11666
This process was error-prone. Also, if @samp{make dist} was run in an
11667
environment where some object file had a dependency on a source file
11668
that was only conditionally created, Automake would generate a
11669
@file{Makefile} that referred to a file that might not appear in the
11670
end user's build. A special, hacky mechanism was required to work
11671
around this.
11672
@end itemize
11673
11674
@unnumberedsubsubsec Historical Note
11675
11676
The code generated by Automake is often inspired by the
11677
@file{Makefile} style of a particular author. In the case of the first
11678
implementation of dependency tracking, I believe the impetus and
11679
inspiration was Jim Meyering. (I could be mistaken. If you know
11680
otherwise feel free to correct me.)
11681
11682
@subsection Dependencies As Side Effects
11683
@unnumberedsubsubsec Description
11684
11685
The next refinement of Automake's automatic dependency tracking scheme
11686
was to implement dependencies as side effects of the compilation.
11687
This was aimed at solving the most commonly reported problems with the
11688
first approach. In particular we were most concerned with eliminating
11689
the weird rebuilding effect associated with make clean.
11690
11691
In this approach, the @file{.P} files were included using the
11692
@code{-include} command, which let us create these files lazily. This
11693
avoided the @samp{make clean} problem.
11694
11695
We only computed dependencies when a file was actually compiled. This
11696
avoided the performance penalty associated with scanning each file
11697
twice. It also let us avoid the other problems associated with the
11698
first, eager, implementation. For instance, dependencies would never
11699
be generated for a source file that was not compilable on a given
11700
architecture (because it in fact would never be compiled).
11701
11702
@unnumberedsubsubsec Bugs
11703
11704
@itemize
11705
@item
11706
This approach also relied on the existence of @command{gcc} and GNU
11707
@command{make}. (A limitation, not technically a bug.)
11708
@item
11709
Dependency tracking was still done by the developer, so the problems
11710
from the first implementation relating to massaging of dependencies by
11711
@samp{make dist} were still in effect.
11712
@item
11713
This implementation suffered from the ``deleted header file'' problem.
11714
Suppose a lazily-created @file{.P} file includes a dependency on a
11715
given header file, like this:
11716
11717
@example
11718
maude.o: maude.c something.h
11719
@end example
11720
11721
Now suppose that the developer removes @file{something.h} and updates
11722
@file{maude.c} so that this include is no longer needed. If he runs
11723
@command{make}, he will get an error because there is no way to create
11724
@file{something.h}.
11725
11726
We fixed this problem in a later release by further massaging the
11727
output of @command{gcc} to include a dummy dependency for each header
11728
file.
11729
@end itemize
11730
11731
@subsection Dependencies for the User
11732
@unnumberedsubsubsec Description
11733
11734
The bugs associated with @samp{make dist}, over time, became a real
11735
problem. Packages using Automake were being built on a large number
11736
of platforms, and were becoming increasingly complex. Broken
11737
dependencies were distributed in ``portable'' @file{Makefile.in}s,
11738
leading to user complaints. Also, the requirement for @command{gcc}
11739
and GNU @command{make} was a constant source of bug reports. The next
11740
implementation of dependency tracking aimed to remove these problems.
11741
11742
We realized that the only truly reliable way to automatically track
11743
dependencies was to do it when the package itself was built. This
11744
meant discovering a method portable to any version of make and any
11745
compiler. Also, we wanted to preserve what we saw as the best point
11746
of the second implementation: dependency computation as a side effect
11747
of compilation.
11748
11749
In the end we found that most modern make implementations support some
11750
form of include directive. Also, we wrote a wrapper script that let
11751
us abstract away differences between dependency tracking methods for
11752
compilers. For instance, some compilers cannot generate dependencies
11753
as a side effect of compilation. In this case we simply have the
11754
script run the compiler twice. Currently our wrapper script
11755
(@command{depcomp}) knows about twelve different compilers (including
11756
a "compiler" that simply invokes @command{makedepend} and then the
11757
real compiler, which is assumed to be a standard Unix-like C compiler
11758
with no way to do dependency tracking).
11759
11760
@unnumberedsubsubsec Bugs
11761
11762
@itemize
11763
@item
11764
Running a wrapper script for each compilation slows down the build.
11765
@item
11766
Many users don't really care about precise dependencies.
11767
@item
11768
This implementation, like every other automatic dependency tracking
11769
scheme in common use today (indeed, every one we've ever heard of),
11770
suffers from the ``duplicated new header'' bug.
11771
11772
This bug occurs because dependency tracking tools, such as the
11773
compiler, only generate dependencies on the successful opening of a
11774
file, and not on every probe.
11775
11776
Suppose for instance that the compiler searches three directories for
11777
a given header, and that the header is found in the third directory.
11778
If the programmer erroneously adds a header file with the same name to
11779
the first directory, then a clean rebuild from scratch could fail
11780
(suppose the new header file is buggy), whereas an incremental rebuild
11781
will succeed.
11782
11783
What has happened here is that people have a misunderstanding of what
11784
a dependency is. Tool writers think a dependency encodes information
11785
about which files were read by the compiler. However, a dependency
11786
must actually encode information about what the compiler tried to do.
11787
11788
This problem is not serious in practice. Programmers typically do not
11789
use the same name for a header file twice in a given project. (At
11790
least, not in C or C++. This problem may be more troublesome in
11791
Java.) This problem is easy to fix, by modifying dependency
11792
generators to record every probe, instead of every successful open.
11793
11794
@item
11795
Since automake generates dependencies as a side effect of compilation,
11796
there is a bootstrapping problem when header files are generated by
11797
running a program. The problem is that, the first time the build is
11798
done, there is no way by default to know that the headers are
11799
required, so make might try to run a compilation for which the headers
11800
have not yet been built.
11801
11802
This was also a problem in the previous dependency tracking implementation.
11803
11804
The current fix is to use @code{BUILT_SOURCES} to list built headers
11805
(@pxref{Sources}). This causes them to be built before any other
11806
build rules are run. This is unsatisfactory as a general solution,
11807
however in practice it seems sufficient for most actual programs.
11808
@end itemize
11809
11810
This code is used since Automake 1.5.
11811
11812
In GCC 3.0, we managed to convince the maintainers to add special
11813
command-line options to help Automake more efficiently do its job. We
11814
hoped this would let us avoid the use of a wrapper script when
11815
Automake's automatic dependency tracking was used with @command{gcc}.
11816
11817
Unfortunately, this code doesn't quite do what we want. In
11818
particular, it removes the dependency file if the compilation fails;
11819
we'd prefer that it instead only touch the file in any way if the
11820
compilation succeeds.
11821
11822
Nevertheless, since Automake 1.7, when a recent @command{gcc} is
11823
detected at @command{configure} time, we inline the
11824
dependency-generation code and do not use the @command{depcomp}
11825
wrapper script. This makes compilations faster for those using this
11826
compiler (probably our primary user base). The counterpart is that
11827
because we have to encode two compilation rules in @file{Makefile}
11828
(with or without @command{depcomp}), the produced @file{Makefile}s are
11829
larger.
11830
11831
@subsection Techniques for Computing Dependencies
11832
11833
There are actually several ways for a build tool like Automake to
11834
cause tools to generate dependencies.
11835
11836
@table @asis
11837
@item @command{makedepend}
11838
This was a commonly-used method in the past. The idea is to run a
11839
special program over the source and have it generate dependency
11840
information. Traditional implementations of @command{makedepend} are
11841
not completely precise; ordinarily they were conservative and
11842
discovered too many dependencies.
11843
@item The tool
11844
An obvious way to generate dependencies is to simply write the tool so
11845
that it can generate the information needed by the build tool. This is
11846
also the most portable method. Many compilers have an option to
11847
generate dependencies. Unfortunately, not all tools provide such an
11848
option.
11849
@item The file system
11850
It is possible to write a special file system that tracks opens,
11851
reads, writes, etc, and then feed this information back to the build
11852
tool. @command{clearmake} does this. This is a very powerful
11853
technique, as it doesn't require cooperation from the
11854
tool. Unfortunately it is also very difficult to implement and also
11855
not practical in the general case.
11856
@item @code{LD_PRELOAD}
11857
Rather than use the file system, one could write a special library to
11858
intercept @code{open} and other syscalls. This technique is also quite
11859
powerful, but unfortunately it is not portable enough for use in
11860
@command{automake}.
11861
@end table
11862
11863
@subsection Recommendations for Tool Writers
11864
11865
We think that every compilation tool ought to be able to generate
11866
dependencies as a side effect of compilation. Furthermore, at least
11867
while @command{make}-based tools are nearly universally in use (at
11868
least in the free software community), the tool itself should generate
11869
dummy dependencies for header files, to avoid the deleted header file
11870
bug. Finally, the tool should generate a dependency for each probe,
11871
instead of each successful file open, in order to avoid the duplicated
11872
new header bug.
11873
11874
@subsection Future Directions for Automake's Dependency Tracking
11875
11876
Currently, only languages and compilers understood by Automake can
11877
have dependency tracking enabled. We would like to see if it is
11878
practical (and worthwhile) to let this support be extended by the user
11879
to languages unknown to Automake.
11880
11881
@node Releases
11882
@section Release Statistics
11883
11884
The following table (inspired by @samp{perlhist(1)}) quantifies the
11885
evolution of Automake using these metrics:
11886
11887
@table @asis
11888
@item Date, Rel
11889
The date and version of the release.
11890
@item am
11891
The number of lines of the @command{automake} script.
11892
@item acl
11893
The number of lines of the @command{aclocal} script.
11894
@item pm
11895
The number of lines of the @command{Perl} supporting modules.
11896
@item @file{*.am}
11897
The number of lines of the @file{Makefile} fragments. The number in parenthesis
11898
is the number of files.
11899
@item m4
11900
The number of lines (and files) of Autoconf macros.
11901
@item doc
11902
The number of pages of the documentation (the Postscript version).
11903
@item t
11904
The number of test cases in the test suite.
11905
@end table
11906
11907
@multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888}
11908
@headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
11909
@item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
11910
@item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
11911
@item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
11912
@item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
11913
@item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
11914
@item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
11915
@item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
11916
@item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
11917
@item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11918
@item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11919
@item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
11920
@item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
11921
@item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
11922
@item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
11923
@item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
11924
@item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
11925
@item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
11926
@item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
11927
@item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
11928
@item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11929
@item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11930
@item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
11931
@item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
11932
@item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
11933
@item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
11934
@item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
11935
@item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
11936
@item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
11937
@item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
11938
@item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
11939
@item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
11940
@item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
11941
@item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
11942
@item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
11943
@item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
11944
@item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
11945
@item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
11946
@item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
11947
@item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
11948
@item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
11949
@item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
11950
@item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
11951
@item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
11952
@item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
11953
@item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
11954
@item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
11955
@item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
11956
@item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
11957
@item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
11958
@item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
11959
@item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
11960
@item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
11961
@item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
11962
@item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
11963
@item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
11964
@item 2008-01-21 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3584 (41) @tab 1499 (34) @tab 173 @tab 617
11965
@end multitable
11966
11967
11968
@c ========================================================== Appendices
11969
11970
@page
11971
@node Copying This Manual
11972
@appendix Copying This Manual
11973
11974
@menu
11975
* GNU Free Documentation License:: License for copying this manual
11976
@end menu
11977
11978
@include fdl.texi
11979
11980
@page
11981
@node Indices
11982
@appendix Indices
11983
11984
@menu
11985
* Macro Index:: Index of Autoconf macros
11986
* Variable Index:: Index of Makefile variables
11987
* General Index:: General index
11988
@end menu
11989
11990
@node Macro Index
11991
@appendixsec Macro Index
11992
11993
@printindex fn
11994
11995
@node Variable Index
11996
@appendixsec Variable Index
11997
11998
@printindex vr
11999
12000
@node General Index
12001
@appendixsec General Index
12002
12003
@printindex cp
12004
12005
12006
@page
12007
@contents
12008
@bye
12009
12010
@c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12011
@c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12012
@c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12013
@c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
12014
@c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12015
@c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12016
@c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12017
@c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12018
@c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
12019
@c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12020
@c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12021
@c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12022
@c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12023
@c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12024
@c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12025
@c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12026
@c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12027
@c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12028
@c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
12029
@c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12030
@c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12031
@c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
12032
@c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12033
@c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12034
@c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12035
@c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12036
@c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12037
@c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12038
@c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12039
@c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12040
@c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12041
@c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
12042
@c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
12043
@c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
12044
@c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
12045
@c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
12046
@c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
12047
@c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
12048
@c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
12049
@c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
12050
@c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
12051
@c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
12052
@c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
12053
@c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
12054
@c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
12055
@c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
12056
@c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
12057
@c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
12058
@c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
12059
@c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
12060
@c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
12061
@c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
12062
@c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
12063
@c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
12064
@c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
12065
@c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
12066
@c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
12067
@c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
12068
@c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
12069
@c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
12070
@c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
12071
@c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
12072
@c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
12073
@c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
12074
@c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
12075
@c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
12076
@c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
12077
@c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
12078
@c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
12079
@c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
12080
@c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
12081
@c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
12082
@c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
12083
@c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
12084
@c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
12085
@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
12086
@c LocalWords: barexec Pinard's automatize initialize lzma
Loggerhead is a web-based interface for Breezy
Version: 2.0.1