[SCM] eclipse-cdt - Plug-in for eclipse to handle C/C++ - Debian package. branch, master, updated. debian/8.1.2-2-9-g5354ba3
Jakub Adam
jakub.adam at ktknet.cz
Wed Jul 3 12:11:44 UTC 2013
The following commit has been merged in the master branch:
commit abfbdfc77d10af7ae6beef902a5ad3b6bad1f7eb
Author: Jakub Adam <jakub.adam at ktknet.cz>
Date: Wed Jul 3 11:15:50 2013 +0200
Updated automake documentation sources
diff --git a/debian/changelog b/debian/changelog
index 6ffbaaa..07e27b5 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,7 @@
eclipse-cdt (8.2.0-1) UNRELEASED; urgency=low
* New upstream release.
+ * Updated automake documentation sources.
-- Jakub Adam <jakub.adam at ktknet.cz> Wed, 03 Jul 2013 10:31:52 +0200
diff --git a/debian/docs/src/automake/1.13.3/automake-history.texi b/debian/docs/src/automake/1.13.3/automake-history.texi
new file mode 100644
index 0000000..5089f59
--- /dev/null
+++ b/debian/docs/src/automake/1.13.3/automake-history.texi
@@ -0,0 +1,1214 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename automake-history.info
+ at settitle automake-history
+ at setchapternewpage on
+ at c %**end of header
+
+ at copying
+
+This manual describes (part of) the history of GNU Automake, a program
+that creates GNU standards-compliant Makefiles from template files.
+
+Copyright @copyright{} 1995-2013 Free Software Foundation, Inc.
+
+ at quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License,
+Version 1.3 or any later version published by the Free Software
+Foundation; with no Invariant Sections, with no Front-Cover texts,
+and with no Back-Cover Texts. A copy of the license is included in the
+section entitled ``GNU Free Documentation License.''
+
+ at end quotation
+ at end copying
+
+ at titlepage
+ at title Brief History of Automake
+ at author David MacKenzie
+ at author Tom Tromey
+ at author Alexandre Duret-Lutz
+ at page
+ at vskip 0pt plus 1filll
+ at insertcopying
+ at end titlepage
+
+ at contents
+
+ at ifnottex
+ at node Top
+ at comment node-name, next, previous, up
+ at top Brief History of Automake
+
+ at insertcopying
+
+ at menu
+* Timeline:: The Automake story.
+* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
+* Releases:: Release statistics
+* Copying This Manual:: How to make copies of this manual
+
+ at detailmenu
+ --- The Detailed Node Listing ---
+
+Evolution of Automatic Dependency Tracking
+
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+
+Techniques for Computing Dependencies
+
+* Recommendations for Tool Writers::
+* Future Directions for Dependencies::
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+ at end detailmenu
+ at end menu
+
+ at end ifnottex
+
+ at node Timeline
+ at chapter Timeline
+
+ at table @asis
+ at item 1994-09-19 First CVS commit.
+
+If we can trust the CVS repository, David J. at tie{}MacKenzie (djm) started
+working on Automake (or AutoMake, as it was spelt then) this Monday.
+
+The first version of the @command{automake} script looks as follows.
+
+ at example
+#!/bin/sh
+
+status=0
+
+for makefile
+do
+ if test ! -f $@{makefile@}.am; then
+ echo "automake: $@{makefile@}.am: No such honkin' file"
+ status=1
+ continue
+ fi
+
+ exec 4> $@{makefile@}.in
+
+done
+ at end example
+
+From this you can already see that Automake will be about reading
+ at file{*.am} file and producing @file{*.in} files. You cannot see
+anything else, but if you also know that David is the one who created
+Autoconf two years before you can guess the rest.
+
+Several commits follow, and by the end of the day Automake is
+reported to work for GNU fileutils and GNU m4.
+
+The modus operandi is the one that is still used today: variable
+assignments in @file{Makefile.am} files trigger injections of
+precanned @file{Makefile} fragments into the generated
+ at file{Makefile.in}. The use of @file{Makefile} fragments was inspired
+by the 4.4BSD @command{make} and include files, however Automake aims
+to be portable and to conform to the GNU standards for @file{Makefile}
+variables and targets.
+
+At this point, the most recent release of Autoconf is version 1.11,
+and David is preparing to release Autoconf 2.0 in late October. As a
+matter of fact, he will barely touch Automake after September.
+
+ at item 1994-11-05 David MacKenzie's last commit.
+
+At this point Automake is a 200 line portable shell script, plus 332
+lines of @file{Makefile} fragments. In the @file{README}, David
+states his ambivalence between ``portable shell'' and ``more
+appropriate language'':
+
+ at quotation
+I wrote it keeping in mind the possibility of it becoming an Autoconf
+macro, so it would run at configure-time. That would slow
+configuration down a bit, but allow users to modify the Makefile.am
+without needing to fetch the AutoMake package. And, the Makefile.in
+files wouldn't need to be distributed. But all of AutoMake would. So
+I might reimplement AutoMake in Perl, m4, or some other more
+appropriate language.
+ at end quotation
+
+Automake is described as ``an experimental Makefile generator''.
+There is no documentation. Adventurous users are referred to the
+examples and patches needed to use Automake with GNU m4 1.3, fileutils
+3.9, time 1.6, and development versions of find and indent.
+
+These examples seem to have been lost. However at the time of writing
+(10 years later in September, 2004) the FSF still distributes a
+package that uses this version of Automake: check out GNU termutils
+2.0.
+
+ at item 1995-11-12 Tom Tromey's first commit.
+
+After one year of inactivity, Tom Tromey takes over the package.
+Tom was working on GNU cpio back then, and doing this just for fun,
+having trouble finding a project to contribute to. So while hacking
+he wanted to bring the @file{Makefile.in} up to GNU standards. This
+was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
+grabbed it and tried it out.
+
+Tom didn't talk to djm about it until later, just to make sure he
+didn't mind if he made a release. He did a bunch of early releases to
+the Gnits folks.
+
+Gnits was (and still is) totally informal, just a few GNU friends who
+Fran@,cois Pinard knew, who were all interested in making a common
+infrastructure for GNU projects, and shared a similar outlook on how
+to do it. So they were able to make some progress. It came along
+with Autoconf and extensions thereof, and then Automake from David and
+Tom (who were both gnitsians). One of their ideas was to write a
+document paralleling the GNU standards, that was more strict in some
+ways and more detailed. They never finished the GNITS standards, but
+the ideas mostly made their way into Automake.
+
+ at item 1995-11-23 Automake 0.20
+
+Besides introducing automatic dependency tracking (@pxref{Dependency
+Tracking Evolution}), this version also supplies a 9-page manual.
+
+At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
+exist, so many things had to be done by hand. For instance, here is
+what a configure.in (this is the former name of the
+ at file{configure.ac} we use today) must contain in order to use
+Automake 0.20:
+
+ at example
+PACKAGE=cpio
+VERSION=2.3.911
+AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
+AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
+AC_SUBST(PACKAGE)
+AC_SUBST(VERSION)
+AC_ARG_PROGRAM
+AC_PROG_INSTALL
+ at end example
+
+(Today all of the above is achieved by @code{AC_INIT} and
+ at code{AM_INIT_AUTOMAKE}.)
+
+Here is how programs are specified in @file{Makefile.am}:
+
+ at example
+PROGRAMS = hello
+hello_SOURCES = hello.c
+ at end example
+
+This looks pretty much like what we do today, except the
+ at code{PROGRAMS} variable has no directory prefix specifying where
+ at file{hello} should be installed: all programs are installed in
+ at samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
+that must be built but not installed (it is called
+ at code{noinst_PROGRAMS} nowadays).
+
+Programs can be built conditionally using @code{AC_SUBST}itutions:
+
+ at example
+PROGRAMS = @@progs@@
+AM_PROGRAMS = foo bar baz
+ at end example
+
+(@code{AM_PROGRAMS} has since then been renamed to
+ at code{EXTRA_PROGRAMS}.)
+
+Similarly scripts, static libraries, and data can be built and installed
+using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
+However @code{LIBRARIES} were treated a bit specially in that Automake
+did automatically supply the @file{lib} and @file{.a} prefixes.
+Therefore to build @file{libcpio.a}, one had to write
+
+ at example
+LIBRARIES = cpio
+cpio_SOURCES = ...
+ at end example
+
+Extra files to distribute must be listed in @code{DIST_OTHER} (the
+ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
+distributed should appear in @code{DIST_SUBDIRS}, but the manual
+describes this as a temporary ugly hack (today extra directories should
+also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
+for another purpose, @pxref{Conditional Subdirectories, , Conditional
+Subdirectories, automake, GNU Automake}).
+
+ at item 1995-11-26 Automake 0.21
+
+In less time than it takes to cook a frozen pizza, Tom rewrites
+Automake using Perl. At this time Perl 5 is only one year old, and
+Perl 4.036 is in use at many sites. Supporting several Perl versions
+has been a source of problems through the whole history of Automake.
+
+If you never used Perl 4, imagine Perl 5 without objects, without
+ at samp{my} variables (only dynamically scoped @samp{local} variables),
+without function prototypes, with function calls that needs to be
+prefixed with @samp{&}, etc. Traces of this old style can still be
+found in today's @command{automake}.
+
+ at item 1995-11-28 Automake 0.22
+ at itemx 1995-11-29 Automake 0.23
+
+Bug fixes.
+
+ at item 1995-12-08 Automake 0.24
+ at itemx 1995-12-10 Automake 0.25
+
+Releases are raining. 0.24 introduces the uniform naming scheme we
+use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
+ at code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
+ at code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
+in use; and @code{TEXINFOS} and @code{MANS} still have no directory
+prefixes.) Adding support for prefixes like that was one of the major
+ideas in @command{automake}; it has lasted pretty well.
+
+AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
+Pinard's doing).
+
+0.25 fixes a Perl 4 portability bug.
+
+ at item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
+ at item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
+
+ at item 1996-01-03 Automake 0.26
+ at itemx 1996-01-03 Automake 0.27
+
+Of the many changes and suggestions sent by Fran@,cois Pinard and
+included in 0.26, perhaps the most important is the advice that to
+ease customization a user rule or variable definition should always
+override an Automake rule or definition.
+
+Gordon Matzigkeit and Jim Meyering are two other early contributors
+that have been sending fixes.
+
+0.27 fixes yet another Perl 4 portability bug.
+
+ at item 1996-01-13 Automake 0.28
+
+Automake starts scanning @file{configure.in} for @code{LIBOBJS}
+support. This is an important step because until this version
+Automake only knew about the @file{Makefile.am}s it processed.
+ at file{configure.in} was Autoconf's world and the link between Autoconf
+and Automake had to be done by the @file{Makefile.am} author. For
+instance, if @file{config.h} was generated by @file{configure}, it was the
+package maintainer's responsibility to define the @code{CONFIG_HEADER}
+variable in each @file{Makefile.am}.
+
+Succeeding releases will rely more and more on scanning
+ at file{configure.in} to better automate the Autoconf integration.
+
+0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
+ at option{--gnu} and @option{--gnits} options, the latter being stricter.
+
+ at item 1996-02-07 Automake 0.29
+
+Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
+and rebuild rules for @file{configure}-generated file are
+automatically output.
+
+ at code{TEXINFOS} and @code{MANS} converted to the uniform naming
+scheme.
+
+ at item 1996-02-24 Automake 0.30
+
+The test suite is born. It contains 9 tests. From now on test cases
+will be added pretty regularly (@pxref{Releases}), and this proved to
+be really helpful later on.
+
+ at code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
+
+All the third-party Autoconf macros, written mostly by Fran@,cois
+Pinard (and later Jim Meyering), are distributed in Automake's
+hand-written @file{aclocal.m4} file. Package maintainers are expected
+to extract the necessary macros from this file. (In previous versions
+you had to copy and paste them from the manual...)
+
+ at item 1996-03-11 Automake 0.31
+
+The test suite in 0.30 was run via a long @code{check-local} rule. Upon
+Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
+whenever the @code{TESTS} variable is defined.
+
+ at code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
+prefix is introduced. The syntax is now the same as today.
+
+ at item 1996-03-15 Gordon Matzigkeit starts writing libtool.
+
+ at item 1996-04-27 Automake 0.32
+
+ at code{-hook} targets are introduced; an idea from Dieter Baron.
+
+ at file{*.info} files, which were output in the build directory are
+now built in the source directory, because they are distributed. It
+seems these files like to move back and forth as that will happen
+again in future versions.
+
+ at item 1996-05-18 Automake 0.33
+
+Gord Matzigkeit's main two contributions:
+
+ at itemize
+ at item very preliminary libtool support
+ at item the distcheck rule
+ at end itemize
+
+Although they were very basic at this point, these are probably
+among the top features for Automake today.
+
+Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE}, since
+then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its author
+(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}).
+
+ at item 1996-05-28 Automake 1.0
+
+After only six months of heavy development, the @command{automake} script is
+3134 lines long, plus 973 lines of @file{Makefile} fragments. The
+package has 30 pages of documentation, and 38 test cases.
+ at file{aclocal.m4} contains 4 macros.
+
+From now on and until version 1.4, new releases will occur at a rate
+of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
+been the name of beta releases for 1.2. This is the first time
+Automake uses suffix letters to designate beta releases, a habit that
+lasts.
+
+ at item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
+
+ at item 1996-11-26 David J. at tie{}MacKenzie releases Autoconf 2.12.
+
+Between June and October, the Autoconf development is almost stalled.
+Roland McGrath has been working at the beginning of the year. David
+comes back in November to release 2.12, but he won't touch Autoconf
+anymore after this year, and Autoconf then really stagnates. The
+desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
+
+ at item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
+
+The mailing list is announced as follows:
+ at smallexample
+I've created the "automake" mailing list. It is
+"automake@@gnu.ai.mit.edu". Administrivia, as always, to
+automake-request@@gnu.ai.mit.edu.
+
+The charter of this list is discussion of automake, autoconf, and
+other configuration/portability tools (e.g., libtool). It is expected
+that discussion will range from pleas for help all the way up to
+patches.
+
+This list is archived on the FSF machines. Offhand I don't know if
+you can get the archive without an account there.
+
+This list is open to anybody who wants to join. Tell all your
+friends!
+-- Tom Tromey
+ at end smallexample
+
+Before that people were discussing Automake privately, on the Gnits
+mailing list (which is not public either), and less frequently on
+ at code{gnu.misc.discuss}.
+
+ at code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
+noticed. The archives of the early years of the
+ at code{automake@@gnu.org} list have been lost, so today it is almost
+impossible to find traces of discussions that occurred before 1999.
+This has been annoying more than once, as such discussions can be
+useful to understand the rationale behind a piece of uncommented code
+that was introduced back then.
+
+ at item 1997-06-22 Automake 1.2
+
+Automake developments continues, and more and more new Autoconf macros
+are required. Distributing them in @file{aclocal.m4} and requiring
+people to browse this file to extract the relevant macros becomes
+uncomfortable. Ideally, some of them should be contributed to
+Autoconf so that they can be used directly, however Autoconf is
+currently inactive. Automake 1.2 consequently introduces
+ at command{aclocal} (@command{aclocal} was actually started on
+1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
+file from a repository of third-party macros. Because Autoconf has
+stalled, Automake also becomes a kind of repository for such
+third-party macros, even macros completely unrelated to Automake (for
+instance macros that fix broken Autoconf macros).
+
+The 1.2 release contains 20 macros, including the
+ at code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
+ at file{configure.in}.
+
+Libtool is fully supported using @code{*_LTLIBRARIES}.
+
+The missing script is introduced by Fran@,cois Pinard; it is meant
+to be a better solution than @code{AM_MAINTAINER_MODE}
+(@pxref{maintainer-mode, , maintainer-mode, automake, GNU Automake}).
+
+Conditionals support was implemented by Ian Lance Taylor. At the
+time, Tom and Ian were working on an internal project at Cygnus. They
+were using ILU, which is pretty similar to CORBA at . They wanted to
+integrate ILU into their build, which was all @file{configure}-based,
+and Ian thought that adding conditionals to @command{automake} was
+simpler than doing all the work in @file{configure} (which was the
+standard at the time). So this was actually funded by Cygnus.
+
+This very useful but tricky feature will take a lot of time to
+stabilize. (At the time this text is written, there are still
+primaries that have not been updated to support conditional
+definitions in Automake 1.9.)
+
+The @command{automake} script has almost doubled: 6089 lines of Perl,
+plus 1294 lines of @file{Makefile} fragments.
+
+ at item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
+
+ at item 1998-04-05 Automake 1.3
+
+This is a small advance compared to 1.2.
+It adds support for assembly, and preliminary support for Java.
+
+Perl 5.004_04 is out, but fixes to support Perl 4 are still
+regularly submitted whenever Automake breaks it.
+
+ at item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
+
+Sourceware was setup by Jason Molenda to host open source projects.
+
+ at item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
+ at itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
+Automake is now hosted on @code{sourceware.cygnus.com}. It has a
+publicly accessible CVS repository. This CVS repository is a copy of
+the one Tom was using on his machine, which in turn is based on
+a copy of the CVS repository of David MacKenzie. This is why we still
+have to full source history. (Automake was on Sourceware until 2007-10-29,
+when it moved to a git repository on @code{savannah.gnu.org},
+but the Sourceware host had been renamed to @code{sources.redhat.com}.)
+
+The oldest file in the administrative directory of the CVS repository
+that was created on Sourceware is dated 1998-09-19, while the
+announcement that @command{automake} and @command{autoconf} had joined
+ at command{sourceware} was made on 1998-10-26. They were among the
+first projects to be hosted there.
+
+The heedful reader will have noticed Automake was exactly 4 years old
+on 1998-09-19.
+
+ at item 1999-01-05 Ben Elliston releases Autoconf 2.13.
+
+ at item 1999-01-14 Automake 1.4
+
+This release adds support for Fortran 77 and for the @code{include}
+statement. Also, @samp{+=} assignments are introduced, but it is
+still quite easy to fool Automake when mixing this with conditionals.
+
+These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
+will be used together for years.
+
+ at command{automake} is 7228 lines, plus 1591 lines of Makefile
+fragment, 20 macros (some 1.3 macros were finally contributed back to
+Autoconf), 197 test cases, and 51 pages of documentation.
+
+ at item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
+
+This implements a new dependency tracking schemed that should be
+able to handle automatic dependency tracking using any compiler (not
+just gcc) and any make (not just GNU @command{make}). In addition,
+the new scheme should be more reliable than the old one, as
+dependencies are generated on the end user's machine. Alexandre Oliva
+creates depcomp for this purpose.
+
+ at xref{Dependency Tracking Evolution}, for more details about the
+evolution of automatic dependency tracking in Automake.
+
+ at item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
+
+This was a huge problem since we also had patches going in on the
+trunk. The merge took a long time and was very painful.
+
+ at item 2000-05-10
+
+Since September 1999 and until 2003, Akim Demaille will be zealously
+revamping Autoconf.
+
+ at quotation
+I think the next release should be called "3.0".@*
+Let's face it: you've basically rewritten autoconf.@*
+Every weekend there are 30 new patches.@*
+I don't see how we could call this "2.15" with a straight face.@*
+-- Tom Tromey on @email{autoconf@@gnu.org}
+ at end quotation
+
+Actually Akim works like a submarine: he will pile up patches while he
+works off-line during the weekend, and flush them in batch when he
+resurfaces on Monday.
+
+ at item 2001-01-24
+
+On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
+is out, and Akim has to find something to do during his week-end :)
+
+ at item 2001-01-28
+
+Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
+
+ at quotation
+Aiieeee! I was dreading the day that the Demaillator turned his
+sights on automake at dots{} and now it has arrived! -- Tom Tromey
+ at end quotation
+
+It's only the beginning: in two months he will send 192 patches. Then
+he would slow down so Tom can catch up and review all this. Initially
+Tom actually read all of these patches, then he probably trustingly
+answered OK to most of them, and finally gave up and let Akim apply
+whatever he wanted. There was no way to keep up with that patch rate.
+
+ at quotation
+Anyway the patch below won't apply since it predates Akim's
+sourcequake; I have yet to figure where the relevant passage has
+been moved :) -- Alexandre Duret-Lutz
+ at end quotation
+
+All of these patches were sent to and discussed on
+ at email{automake@@gnu.org}, so subscribed users were literally drowning in
+technical mails. Eventually, the @email{automake-patches@@gnu.org}
+mailing list was created in May.
+
+Year after year, Automake had drifted away from its initial design:
+construct @file{Makefile.in} by assembling various @file{Makefile}
+fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
+various places in the @command{automake} script itself; this does not
+help ensuring a consistent treatment of these rules (for instance
+making sure that user-defined rules override Automake's own rules).
+One of Akim's goal was moving all of these hard-coded rules to separate
+ at file{Makefile} fragments, so the logic could be centralized in a
+ at file{Makefile} fragment processor.
+
+Another significant contribution of Akim is the interface with the
+``trace'' feature of Autoconf. The way to scan @file{configure.in} at
+this time was to read the file and grep the various macro of interest
+to Automake. Doing so could break in many unexpected ways; @command{automake}
+could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
+where the arguments are known only when M4 is run), or conversely it
+could detect some macro that was not expanded (because it is called
+conditionally). In the CVS version of Autoconf, Akim had implemented
+the @option{--trace} option, which provides accurate information about
+where macros are actually called and with what arguments. Akim will
+equip Automake with a second @file{configure.in} scanner that uses
+this @option{--trace} interface. Since it was not sensible to drop the
+Autoconf 2.13 compatibility yet, this experimental scanner was only
+used when an environment variable was set, the traditional
+grep-scanner being still the default.
+
+ at item 2001-04-25 Gary V. at tie{}Vaughan releases Libtool 1.4
+
+It has been more than two years since Automake 1.4, CVS Automake has
+suffered lot's of heavy changes and still is not ready for release.
+Libtool 1.4 had to be distributed with a patch against Automake 1.4.
+
+ at item 2001-05-08 Automake 1.4-p1
+ at itemx 2001-05-24 Automake 1.4-p2
+
+Gary V. at tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
+release'' of Automake:
+
+ at quotation
+The main purpose of this release is to have a stable automake
+which is compatible with the latest stable libtool.
+ at end quotation
+
+The release also contains obvious fixes for bugs in Automake 1.4,
+some of which were reported almost monthly.
+
+ at item 2001-05-21 Akim Demaille releases Autoconf 2.50
+
+ at item 2001-06-07 Automake 1.4-p3
+ at itemx 2001-06-10 Automake 1.4-p4
+ at itemx 2001-07-15 Automake 1.4-p5
+
+Gary continues his patch-release series. These also add support for
+some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
+ at file{configure.ac} over @file{configure.in}, and it introduces a new
+syntax for @code{AC_OUTPUT}ing files.
+
+ at item 2001-08-23 Automake 1.5
+
+A major and long-awaited release, that comes more than two years after
+1.4. It brings many changes, among which:
+ at itemize
+ at item The new dependency tracking scheme that uses @command{depcomp}.
+Aside from the improvement on the dependency tracking itself
+(@pxref{Dependency Tracking Evolution}), this also streamlines the use
+of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
+used during development are now the same as those used in
+distributions. Before that the @file{Makefile.in}s generated for
+maintainers required GNU @command{make} and GCC, they were different
+from the portable @file{Makefile} generated for distribution; this was
+causing some confusion.
+
+ at item Support for per-target compilation flags.
+
+ at item Support for reference to files in subdirectories in most
+ at file{Makefile.am} variables.
+
+ at item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
+prefixes.
+ at item Perl 4 support is finally dropped.
+ at end itemize
+
+1.5 did break several packages that worked with 1.4. Enough so that
+Linux distributions could not easily install the new Automake version
+without breaking many of the packages for which they had to run
+ at command{automake}.
+
+Some of these breakages were effectively bugs that would eventually be
+fixed in the next release. However, a lot of damage was caused by
+some changes made deliberately to render Automake stricter on some
+setup we did consider bogus. For instance, @samp{make distcheck} was
+improved to check that @samp{make uninstall} did remove all the files
+ at samp{make install} installed, that @samp{make distclean} did not omit
+some file, and that a VPATH build would work even if the source
+directory was read-only. Similarly, Automake now rejects multiple
+definitions of the same variable (because that would mix very badly
+with conditionals), and @samp{+=} assignments with no previous
+definition. Because these changes all occurred suddenly after 1.4 had
+been established for more than two years, it hurt users.
+
+To make matter worse, meanwhile Autoconf (now at version 2.52) was
+facing similar troubles, for similar reasons.
+
+ at item 2002-03-05 Automake 1.6
+
+This release introduced versioned installation (@pxref{API Versioning, ,
+API Versioning, automake, GNU Automake}). This was mainly pushed by
+Havoc Pennington, taking the GNOME source tree as motive: due to
+incompatibilities between the autotools it's impossible for the GNOME
+packages to switch to Autoconf 2.53 and Automake 1.5 all at once, so
+they are currently stuck with Autoconf 2.13 and Automake 1.4.
+
+The idea was to call this version @file{automake-1.6}, call all its
+bug-fix versions identically, and switch to @file{automake-1.7} for
+the next release that adds new features or changes some rules. This
+scheme implies maintaining a bug-fix branch in addition to the
+development trunk, which means more work from the maintainer, but
+providing regular bug-fix releases proved to be really worthwhile.
+
+Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
+not. Perhaps the more annoying was the dependence on the newly
+released Autoconf 2.53. Autoconf seemed to have stabilized enough
+since its explosive 2.50 release and included changes required to fix
+some bugs in Automake. In order to upgrade to Automake 1.6, people
+now had to upgrade Autoconf too; for some packages it was no picnic.
+
+While versioned installation helped people to upgrade, it also
+unfortunately allowed people not to upgrade. At the time of writing,
+some Linux distributions are shipping packages for Automake 1.4, 1.5,
+1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
+Some distribution also call 1.4 the ``stable'' version, and present
+``1.9'' as the development version; this does not really makes sense
+since 1.9 is way more solid than 1.4. All this does not help the
+newcomer.
+
+ at item 2002-04-11 Automake 1.6.1
+
+1.6, and the upcoming 1.4-p6 release were the last release by Tom.
+This one and those following will be handled by Alexandre
+Duret-Lutz. Tom is still around, and will be there until about 1.7,
+but his interest into Automake is drifting away towards projects like
+ at command{gcj}.
+
+Alexandre has been using Automake since 2000, and started to
+contribute mostly on Akim's incitement (Akim and Alexandre have been
+working in the same room from 1999 to 2002). In 2001 and 2002 he had
+a lot of free time to enjoy hacking Automake.
+
+ at item 2002-06-14 Automake 1.6.2
+
+ at item 2002-07-28 Automake 1.6.3
+ at itemx 2002-07-28 Automake 1.4-p6
+
+Two releases on the same day. 1.6.3 is a bug-fix release.
+
+Tom Tromey backported the versioned installation mechanism on the 1.4
+branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
+side by side. Another request from the GNOME folks.
+
+ at item 2002-09-25 Automake 1.7
+
+This release switches to the new @file{configure.ac} scanner Akim
+was experimenting in 1.5.
+
+ at item 2002-10-16 Automake 1.7.1
+ at itemx 2002-12-06 Automake 1.7.2
+ at itemx 2003-02-20 Automake 1.7.3
+ at itemx 2003-04-23 Automake 1.7.4
+ at itemx 2003-05-18 Automake 1.7.5
+ at itemx 2003-07-10 Automake 1.7.6
+ at itemx 2003-09-07 Automake 1.7.7
+ at itemx 2003-10-07 Automake 1.7.8
+
+Many bug-fix releases. 1.7 lasted because the development version
+(upcoming 1.8) was suffering some major internal revamping.
+
+ at item 2003-10-26 Automake on screen
+
+Episode 49, `Repercussions', in the third season of the `Alias' TV
+show is first aired.
+
+Marshall, one of the characters, is working on a computer virus that he
+has to modify before it gets into the wrong hands or something like
+that. The screenshots you see do not show any program code, they show
+a @file{Makefile.in} generated by automake...
+
+ at item 2003-11-09 Automake 1.7.9
+
+ at item 2003-12-10 Automake 1.8
+
+The most striking update is probably that of @command{aclocal}.
+
+ at command{aclocal} now uses @code{m4_include} in the produced
+ at file{aclocal.m4} when the included macros are already distributed
+with the package (an idiom used in many packages), which reduces code
+duplication. Many people liked that, but in fact this change was
+really introduced to fix a bug in rebuild rules: @file{Makefile.in}
+must be rebuilt whenever a dependency of @file{configure} changes, but
+all the @file{m4} files included in @file{aclocal.m4} where unknown
+from @command{automake}. Now @command{automake} can just trace the
+ at code{m4_include}s to discover the dependencies.
+
+ at command{aclocal} also starts using the @option{--trace} Autoconf option
+in order to discover used macros more accurately. This will turn out
+to be very tricky (later releases will improve this) as people had
+devised many ways to cope with the limitation of previous
+ at command{aclocal} versions, notably using handwritten
+ at code{m4_include}s: @command{aclocal} must make sure not to redefine a
+rule that is already included by such statement.
+
+Automake also has seen its guts rewritten. Although this rewriting
+took a lot of efforts, it is only apparent to the users in that some
+constructions previously disallowed by the implementation now work
+nicely. Conditionals, Locations, Variable and Rule definitions,
+Options: these items on which Automake works have been rewritten as
+separate Perl modules, and documented.
+
+ at item 2004-01-11 Automake 1.8.1
+ at itemx 2004-01-12 Automake 1.8.2
+ at itemx 2004-03-07 Automake 1.8.3
+ at itemx 2004-04-25 Automake 1.8.4
+ at itemx 2004-05-16 Automake 1.8.5
+
+ at item 2004-07-28 Automake 1.9
+
+This release tries to simplify the compilation rules it outputs to
+reduce the size of the Makefile. The complaint initially come from
+the libgcj developers. Their @file{Makefile.in} generated with
+Automake 1.4 and custom build rules (1.4 did not support compiled
+Java) is 250KB at . The one generated by 1.8 was over 9MB@! 1.9 gets it
+down to 1.2MB at .
+
+Aside from this it contains mainly minor changes and bug-fixes.
+
+ at item 2004-08-11 Automake 1.9.1
+ at itemx 2004-09-19 Automake 1.9.2
+
+Automake has ten years. This chapter of the manual was initially
+written for this occasion.
+
+ at item 2007-10-29 Automake repository moves to @code{savannah.gnu.org}
+and uses git as primary repository.
+
+ at end table
+
+ at node Dependency Tracking Evolution
+ at chapter Evolution of Automatic Dependency Tracking
+
+Over the years Automake has deployed three different dependency
+tracking methods. Each method, including the current one, has had
+flaws of various sorts. Here we lay out the different dependency
+tracking methods, their flaws, and their fixes. We conclude with
+recommendations for tool writers, and by indicating future directions
+for dependency tracking work in Automake.
+
+ at menu
+* First Take on Dependencies:: Precomputed dependency tracking
+* Dependencies As Side Effects:: Update at developer compile time
+* Dependencies for the User:: Update at user compile time
+* Techniques for Dependencies:: Alternative approaches
+ at end menu
+
+ at node First Take on Dependencies
+ at section First Take on Dependency Tracking
+ at unnumberedsubsec Description
+
+Our first attempt at automatic dependency tracking was based on the
+method recommended by GNU @command{make}. (@pxref{Automatic
+Prerequisites, , Generating Prerequisites Automatically, make, The GNU
+make Manual})
+
+This version worked by precomputing dependencies ahead of time. For
+each source file, it had a special @file{.P} file that held the
+dependencies. There was a rule to generate a @file{.P} file by
+invoking the compiler appropriately. All such @file{.P} files were
+included by the @file{Makefile}, thus implicitly becoming dependencies
+of @file{Makefile}.
+
+ at unnumberedsubsec Bugs
+
+This approach had several critical bugs.
+
+ at itemize
+ at item
+The code to generate the @file{.P} file relied on @command{gcc}.
+(A limitation, not technically a bug.)
+ at item
+The dependency tracking mechanism itself relied on GNU @command{make}.
+(A limitation, not technically a bug.)
+ at item
+Because each @file{.P} file was a dependency of @file{Makefile}, this
+meant that dependency tracking was done eagerly by @command{make}.
+For instance, @samp{make clean} would cause all the dependency files
+to be updated, and then immediately removed. This eagerness also
+caused problems with some configurations; if a certain source file
+could not be compiled on a given architecture for some reason,
+dependency tracking would fail, aborting the entire build.
+ at item
+As dependency tracking was done as a pre-pass, compile times were
+doubled--the compiler had to be run twice per source file.
+ at item
+ at samp{make dist} re-ran @command{automake} to generate a
+ at file{Makefile} that did not have automatic dependency tracking (and
+that was thus portable to any version of @command{make}). In order to
+do this portably, Automake had to scan the dependency files and remove
+any reference that was to a source file not in the distribution.
+This process was error-prone. Also, if @samp{make dist} was run in an
+environment where some object file had a dependency on a source file
+that was only conditionally created, Automake would generate a
+ at file{Makefile} that referred to a file that might not appear in the
+end user's build. A special, hacky mechanism was required to work
+around this.
+ at end itemize
+
+ at unnumberedsubsec Historical Note
+
+The code generated by Automake is often inspired by the
+ at file{Makefile} style of a particular author. In the case of the first
+implementation of dependency tracking, I believe the impetus and
+inspiration was Jim Meyering. (I could be mistaken. If you know
+otherwise feel free to correct me.)
+
+ at node Dependencies As Side Effects
+ at section Dependencies As Side Effects
+ at unnumberedsubsec Description
+
+The next refinement of Automake's automatic dependency tracking scheme
+was to implement dependencies as side effects of the compilation.
+This was aimed at solving the most commonly reported problems with the
+first approach. In particular we were most concerned with eliminating
+the weird rebuilding effect associated with make clean.
+
+In this approach, the @file{.P} files were included using the
+ at code{-include} command, which let us create these files lazily. This
+avoided the @samp{make clean} problem.
+
+We only computed dependencies when a file was actually compiled. This
+avoided the performance penalty associated with scanning each file
+twice. It also let us avoid the other problems associated with the
+first, eager, implementation. For instance, dependencies would never
+be generated for a source file that was not compilable on a given
+architecture (because it in fact would never be compiled).
+
+ at unnumberedsubsec Bugs
+
+ at itemize
+ at item
+This approach also relied on the existence of @command{gcc} and GNU
+ at command{make}. (A limitation, not technically a bug.)
+ at item
+Dependency tracking was still done by the developer, so the problems
+from the first implementation relating to massaging of dependencies by
+ at samp{make dist} were still in effect.
+ at item
+This implementation suffered from the ``deleted header file'' problem.
+Suppose a lazily-created @file{.P} file includes a dependency on a
+given header file, like this:
+
+ at example
+maude.o: maude.c something.h
+ at end example
+
+Now suppose that you remove @file{something.h} and update @file{maude.c}
+so that this include is no longer needed. If you run @command{make},
+you will get an error because there is no way to create
+ at file{something.h}.
+
+We fixed this problem in a later release by further massaging the
+output of @command{gcc} to include a dummy dependency for each header
+file.
+ at end itemize
+
+ at node Dependencies for the User
+ at section Dependencies for the User
+ at unnumberedsubsec Description
+
+The bugs associated with @samp{make dist}, over time, became a real
+problem. Packages using Automake were being built on a large number
+of platforms, and were becoming increasingly complex. Broken
+dependencies were distributed in ``portable'' @file{Makefile.in}s,
+leading to user complaints. Also, the requirement for @command{gcc}
+and GNU @command{make} was a constant source of bug reports. The next
+implementation of dependency tracking aimed to remove these problems.
+
+We realized that the only truly reliable way to automatically track
+dependencies was to do it when the package itself was built. This
+meant discovering a method portable to any version of make and any
+compiler. Also, we wanted to preserve what we saw as the best point
+of the second implementation: dependency computation as a side effect
+of compilation.
+
+In the end we found that most modern make implementations support some
+form of include directive. Also, we wrote a wrapper script that let
+us abstract away differences between dependency tracking methods for
+compilers. For instance, some compilers cannot generate dependencies
+as a side effect of compilation. In this case we simply have the
+script run the compiler twice. Currently our wrapper script
+(@command{depcomp}) knows about twelve different compilers (including
+a "compiler" that simply invokes @command{makedepend} and then the
+real compiler, which is assumed to be a standard Unix-like C compiler
+with no way to do dependency tracking).
+
+ at unnumberedsubsec Bugs
+
+ at itemize
+ at item
+Running a wrapper script for each compilation slows down the build.
+ at item
+Many users don't really care about precise dependencies.
+ at item
+This implementation, like every other automatic dependency tracking
+scheme in common use today (indeed, every one we've ever heard of),
+suffers from the ``duplicated new header'' bug.
+
+This bug occurs because dependency tracking tools, such as the
+compiler, only generate dependencies on the successful opening of a
+file, and not on every probe.
+
+Suppose for instance that the compiler searches three directories for
+a given header, and that the header is found in the third directory.
+If the programmer erroneously adds a header file with the same name to
+the first directory, then a clean rebuild from scratch could fail
+(suppose the new header file is buggy), whereas an incremental rebuild
+will succeed.
+
+What has happened here is that people have a misunderstanding of what
+a dependency is. Tool writers think a dependency encodes information
+about which files were read by the compiler. However, a dependency
+must actually encode information about what the compiler tried to do.
+
+This problem is not serious in practice. Programmers typically do not
+use the same name for a header file twice in a given project. (At
+least, not in C or C++. This problem may be more troublesome in
+Java.) This problem is easy to fix, by modifying dependency
+generators to record every probe, instead of every successful open.
+
+ at item
+Since Automake generates dependencies as a side effect of compilation,
+there is a bootstrapping problem when header files are generated by
+running a program. The problem is that, the first time the build is
+done, there is no way by default to know that the headers are
+required, so make might try to run a compilation for which the headers
+have not yet been built.
+
+This was also a problem in the previous dependency tracking implementation.
+
+The current fix is to use @code{BUILT_SOURCES} to list built headers
+(@pxref{Sources, , Sources, automake, GNU Automake}). This causes them
+to be built before any other build rules are run. This is unsatisfactory
+as a general solution, however in practice it seems sufficient for most
+actual programs.
+ at end itemize
+
+This code is used since Automake 1.5.
+
+In GCC 3.0, we managed to convince the maintainers to add special
+command-line options to help Automake more efficiently do its job. We
+hoped this would let us avoid the use of a wrapper script when
+Automake's automatic dependency tracking was used with @command{gcc}.
+
+Unfortunately, this code doesn't quite do what we want. In
+particular, it removes the dependency file if the compilation fails;
+we'd prefer that it instead only touch the file in any way if the
+compilation succeeds.
+
+Nevertheless, since Automake 1.7, when a recent @command{gcc} is
+detected at @command{configure} time, we inline the
+dependency-generation code and do not use the @command{depcomp}
+wrapper script. This makes compilations faster for those using this
+compiler (probably our primary user base). The counterpart is that
+because we have to encode two compilation rules in @file{Makefile}
+(with or without @command{depcomp}), the produced @file{Makefile}s are
+larger.
+
+ at node Techniques for Dependencies
+ at section Techniques for Computing Dependencies
+
+There are actually several ways for a build tool like Automake to
+cause tools to generate dependencies.
+
+ at table @asis
+ at item @command{makedepend}
+This was a commonly-used method in the past. The idea is to run a
+special program over the source and have it generate dependency
+information. Traditional implementations of @command{makedepend} are
+not completely precise; ordinarily they were conservative and
+discovered too many dependencies.
+ at item The tool
+An obvious way to generate dependencies is to simply write the tool so
+that it can generate the information needed by the build tool. This is
+also the most portable method. Many compilers have an option to
+generate dependencies. Unfortunately, not all tools provide such an
+option.
+ at item The file system
+It is possible to write a special file system that tracks opens,
+reads, writes, etc, and then feed this information back to the build
+tool. @command{clearmake} does this. This is a very powerful
+technique, as it doesn't require cooperation from the
+tool. Unfortunately it is also very difficult to implement and also
+not practical in the general case.
+ at item @code{LD_PRELOAD}
+Rather than use the file system, one could write a special library to
+intercept @code{open} and other syscalls. This technique is also quite
+powerful, but unfortunately it is not portable enough for use in
+ at command{automake}.
+ at end table
+
+ at menu
+* Recommendations for Tool Writers::
+* Future Directions for Dependencies::
+ at end menu
+
+ at node Recommendations for Tool Writers
+ at subsection Recommendations for Tool Writers
+
+We think that every compilation tool ought to be able to generate
+dependencies as a side effect of compilation. Furthermore, at least
+while @command{make}-based tools are nearly universally in use (at
+least in the free software community), the tool itself should generate
+dummy dependencies for header files, to avoid the deleted header file
+bug. Finally, the tool should generate a dependency for each probe,
+instead of each successful file open, in order to avoid the duplicated
+new header bug.
+
+ at node Future Directions for Dependencies
+ at subsection Future Directions for Dependencies
+
+Currently, only languages and compilers understood by Automake can
+have dependency tracking enabled. We would like to see if it is
+practical (and worthwhile) to let this support be extended by the user
+to languages unknown to Automake.
+
+ at node Releases
+ at chapter Release Statistics
+
+The following table (inspired by @samp{perlhist(1)}) quantifies the
+evolution of Automake using these metrics:
+
+ at table @asis
+ at item Date, Rel
+The date and version of the release.
+ at item am
+The number of lines of the @command{automake} script.
+ at item acl
+The number of lines of the @command{aclocal} script.
+ at item pm
+The number of lines of the @command{Perl} supporting modules.
+ at item @file{*.am}
+The number of lines of the @file{Makefile} fragments. The number in
+parentheses is the number of files.
+ at item m4
+The number of lines (and files) of Autoconf macros.
+ at item doc
+The number of pages of the documentation (the Postscript version).
+ at item t
+The number of test cases in the test suite. Of those, the number in
+parentheses is the number of generated test cases.
+ at end table
+
+ at multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
+ at headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
+ at item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
+ at item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
+ at item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
+ at item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
+ at item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
+ at item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
+ at item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
+ at item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
+ at item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
+ at item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
+ at item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
+ at item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
+ at item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
+ at item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
+ at item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
+ at item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
+ at item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
+ at item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
+ at item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
+ at item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
+ at item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
+ at item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
+ at item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
+ at item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
+ at item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
+ at item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
+ at item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
+ at item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
+ at item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
+ at item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
+ at item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
+ at item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
+ at item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
+ at item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
+ at item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
+ at item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
+ at item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
+ at item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
+ at item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
+ at item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
+ at item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
+ at item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
+ at item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
+ at item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
+ at item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
+ at item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
+ at item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
+ at item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
+ at item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
+ at item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
+ at item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
+ at item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
+ at item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
+ at item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
+ at end multitable
+
+
+ at c ========================================================== Appendices
+
+ at page
+ at node Copying This Manual
+ at appendix Copying This Manual
+
+ at menu
+* GNU Free Documentation License:: License for copying this manual
+ at end menu
+
+ at node GNU Free Documentation License
+ at appendixsec GNU Free Documentation License
+ at include fdl.texi
+
+ at bye
diff --git a/debian/docs/src/automake/1.11.5/automake.texi b/debian/docs/src/automake/1.13.3/automake.texi
similarity index 82%
copy from debian/docs/src/automake/1.11.5/automake.texi
copy to debian/docs/src/automake/1.13.3/automake.texi
index 10b605e..abf2634 100644
--- a/debian/docs/src/automake/1.11.5/automake.texi
+++ b/debian/docs/src/automake/1.13.3/automake.texi
@@ -1,7 +1,7 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
- at setfilename automake-1.11.info
- at settitle automake-1.11
+ at setfilename automake-1.13.info
+ at settitle automake-1.13
@setchapternewpage off
@c %**end of header
@@ -23,9 +23,7 @@ This manual is for GNU Automake (version @value{VERSION},
@value{UPDATED}), a program that creates GNU standards-compliant
Makefiles from template files.
-Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
-2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1995-2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -40,13 +38,13 @@ section entitled ``GNU Free Documentation License.''
@dircategory Software development
@direntry
-* Automake: (automake-1.11). Making GNU standards-compliant Makefiles.
+* Automake: (automake-1.13). Making GNU standards-compliant Makefiles.
@end direntry
@dircategory Individual utilities
@direntry
-* aclocal-invocation: (automake-1.11)aclocal Invocation. Generating aclocal.m4.
-* automake-invocation: (automake-1.11)automake Invocation. Generating Makefile.in.
+* aclocal-invocation: (automake-1.13)aclocal Invocation. Generating aclocal.m4.
+* automake-invocation: (automake-1.13)automake Invocation. Generating Makefile.in.
@end direntry
@titlepage
@@ -55,6 +53,8 @@ section entitled ``GNU Free Documentation License.''
@author David MacKenzie
@author Tom Tromey
@author Alexandre Duret-Lutz
+ at author Ralf Wildenhues
+ at author Stefano Lattarini
@page
@vskip 0pt plus 1filll
@insertcopying
@@ -117,13 +117,11 @@ section entitled ``GNU Free Documentation License.''
* Conditionals:: Conditionals
* Silencing Make:: Obtain less verbose output from @command{make}
* Gnits:: The effect of @option{--gnu} and @option{--gnits}
-* Cygnus:: The effect of @option{--cygnus} (deprecated, soon to be removed)
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
* API Versioning:: About compatibility between Automake versions
* Upgrading:: Upgrading to a Newer Automake Version
* FAQ:: Frequently Asked Questions
-* History:: Notes about the history of Automake
* Copying This Manual:: How to make copies of this manual
* Indices:: Indices of variables, macros, and concepts
@@ -193,7 +191,6 @@ Auto-generating aclocal.m4
Autoconf macros supplied with Automake
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that you should stop using.
* Private Macros:: Macros that you should not use.
Directories
@@ -223,6 +220,7 @@ Building Programs and Libraries
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
+* Objective C++ Support:: Compiling Objective C++ sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
@@ -230,7 +228,6 @@ Building Programs and Libraries
* Java Support with gcj:: Compiling Java sources using gcj
* Vala Support:: Compiling Vala sources
* Support for Other Languages:: Compiling other languages
-* ANSI:: Automatic de-ANSI-fication (deprecated, soon to be removed)
* Dependencies:: Automatic dependency tracking
* EXEEXT:: Support for executable extensions
@@ -314,16 +311,47 @@ What Goes in a Distribution
Support for test suites
-* Simple Tests:: Listing programs and scripts in @code{TESTS}
-* Simple Tests using parallel-tests:: More powerful test driver
-* DejaGnu Tests:: Interfacing with the external testing framework
+* Generalities about Testing:: Generic concepts and terminology about testing
+* Simple Tests:: Listing test scripts in @code{TESTS}
+* Custom Test Drivers:: Writing and using custom test drivers
+* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
+* DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
* Install Tests:: Running tests on installed packages
+Simple Tests
+
+* Scripts-based Testsuites:: Automake-specific concepts and terminology
+* Serial Test Harness:: Older (and discouraged) serial test harness
+* Parallel Test Harness:: Generic concurrent test harness
+
+Using the TAP test protocol
+
+* Introduction to TAP::
+* Use TAP with the Automake test harness::
+* Incompatibilities with other TAP parsers and drivers::
+* Links and external resources on TAP::
+
+Custom Test Drivers
+
+* Overview of Custom Test Drivers Support::
+* Declaring Custom Test Drivers::
+* API for Custom Test Drivers::
+
+API for Custom Test Drivers
+
+* Command-line arguments for test drivers::
+* Log files generation and test results recording::
+* Testsuite progress output::
+
+Changing Automake's Behavior
+
+* Options generalities:: Semantics of Automake option
+* List of Automake options:: A comprehensive list of Automake options
+
Miscellaneous Rules
-* Tags:: Interfacing to etags and mkid
+* Tags:: Interfacing to cscope, etags and mkid
* Suffixes:: Handling new file extensions
-* Multilibs:: Support for multilibs (deprecated, soon to be removed).
Conditionals
@@ -332,9 +360,9 @@ Conditionals
Silencing Make
-* Make verbosity:: Make is verbose by default
-* Tricks For Silencing Make:: Standard and generic ways to silence make
-* Automake silent-rules Option:: How Automake can help in silencing make
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake Silent Rules:: How Automake can help in silencing make
When Automake Isn't Enough
@@ -347,7 +375,7 @@ Frequently Asked Questions about Automake
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* Wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
-* distcleancheck:: Files left in build directory after distclean
+* Errors with distclean:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
@@ -356,21 +384,6 @@ Frequently Asked Questions about Automake
* Debugging Make Rules:: Strategies when things don't work as expected
* Reporting Bugs:: Feedback on bugs and feature requests
-History of Automake
-
-* Timeline:: The Automake story.
-* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
-* Releases:: Statistics about Automake Releases
-
-Dependency Tracking in Automake
-
-* First Take on Dependencies:: Precomputed dependency tracking
-* Dependencies As Side Effects:: Update at developer compile time
-* Dependencies for the User:: Update at user compile time
-* Techniques for Dependencies:: Alternative approaches
-* Recommendations for Tool Writers:: What tool writers can do to help
-* Future Directions for Dependencies:: Languages Automake does not know
-
Copying This Manual
* GNU Free Documentation License:: License for copying this manual
@@ -409,8 +422,7 @@ individual GNU maintainer (and put it on the back of the Automake
maintainers).
The typical Automake input file is simply a series of variable definitions.
-Each such file is processed to create a @file{Makefile.in}. There
-should generally be one @file{Makefile.am} per directory of a project.
+Each such file is processed to create a @file{Makefile.in}.
@cindex Constraints of Automake
@cindex Automake constraints
@@ -418,11 +430,7 @@ should generally be one @file{Makefile.am} per directory of a project.
Automake does constrain a project in certain ways; for instance, it
assumes that the project uses Autoconf (@pxref{Top, , Introduction,
autoconf, The Autoconf Manual}), and enforces certain restrictions on
-the @file{configure.ac} contents at footnote{Older Autoconf versions used
- at file{configure.in}. Autoconf 2.50 and greater promotes
- at file{configure.ac} over @file{configure.in}. The rest of this
-documentation will refer to @file{configure.ac}, but Automake also
-supports @file{configure.in} for backward compatibility.}.
+the @file{configure.ac} contents.
@cindex Automake requirements
@cindex Requirements, Automake
@@ -531,7 +539,7 @@ illustration of the GNU Build System in action.
@cindex @file{amhello-1.0.tar.gz}, use cases
In this section we explore several use cases for the GNU Build System.
-You can replay all these examples on the @file{amhello-1.0.tar.gz}
+You can replay all of these examples on the @file{amhello-1.0.tar.gz}
package distributed with Automake. If Automake is installed on your
system, you should find a copy of this file in
@file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
@@ -901,7 +909,7 @@ GNU Make Manual}).
VPATH builds have other interesting uses. One is to build the same
sources with multiple configurations. For instance:
- at c Keep in sync with amhello-cflags.test.
+ at c Keep in sync with amhello-cflags.sh
@example
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
@@ -1053,7 +1061,7 @@ instance my cross-compiler for MinGW32 has its binaries called
Here is how we could build @code{amhello-1.0} for
@code{i586-mingw32msvc} on a GNU/Linux PC.
- at c Keep in sync with amhello-cross-compile.test.
+ at c Keep in sync with amhello-cross-compile.sh
@smallexample
~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
checking for a BSD-compatible install... /usr/bin/install -c
@@ -1168,7 +1176,7 @@ by some means.
For instance here is how we could create a binary package containing a
snapshot of all the files to be installed.
- at c Keep in sync with amhello-binpkg.test.
+ at c Keep in sync with amhello-binpkg.sh
@example
~/amhello-1.0 % @kbd{./configure --prefix /usr}
@dots{}
@@ -1302,8 +1310,9 @@ must be passed to @command{configure} to activate them.
Do not reject slow dependency extractors.
@end table
- at xref{Dependency Tracking Evolution}, for some discussion about the
-different dependency tracking schemes used by Automake over the years.
+ at xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
+automake-history, Brief History of Automake}, for some discussion about
+the different dependency tracking schemes used by Automake over the years.
@node Nested Packages
@subsection Nested Packages
@@ -1445,7 +1454,7 @@ package.
@example
~/amhello % @kbd{cat README}
This is a demonstration package for GNU Automake.
-Type `info Automake' to read the Automake manual.
+Type 'info Automake' to read the Automake manual.
@end example
@item
@@ -1487,9 +1496,9 @@ command as follows:
@example
~/amhello % @kbd{autoreconf --install}
-configure.ac: installing `./install-sh'
-configure.ac: installing `./missing'
-src/Makefile.am: installing `./depcomp'
+configure.ac: installing './install-sh'
+configure.ac: installing './missing'
+src/Makefile.am: installing './depcomp'
@end example
At this point the build system is complete.
@@ -1557,7 +1566,7 @@ when you execute @command{make}.
@command{autoreconf} is a script that calls @command{autoconf},
@command{automake}, and a bunch of other commands in the right order.
If you are beginning with these tools, it is not important to figure
-out in which order all these tools should be invoked and why. However,
+out in which order all of these tools should be invoked and why. However,
because Autoconf and Automake have separate manuals, the important
point to understand is that @command{autoconf} is in charge of
creating @file{configure} from @file{configure.ac}, while
@@ -1819,19 +1828,19 @@ variable definitions.
Generally, Automake is not particularly smart in the parsing of unusual
Makefile constructs, so you're advised to avoid fancy constructs or
``creative'' use of whitespaces.
- at c Keep this in sync with doc-parsing-buglets-tabs.test.
+ at c Keep this in sync with doc-parsing-buglets-tabs.sh
For example, @key{TAB} characters cannot be used between a target name
and the following ``@code{:}'' character, and variable assignments
shouldn't be indented with @key{TAB} characters.
- at c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
+ at c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
Also, using more complex macro in target names can cause trouble:
@example
% @kbd{cat Makefile.am}
$(FOO:=x): bar
% @kbd{automake}
-Makefile.am:1: bad characters in variable name `$(FOO'
-Makefile.am:1: `:='-style assignments are not portable
+Makefile.am:1: bad characters in variable name '$(FOO'
+Makefile.am:1: ':='-style assignments are not portable
@end example
@cindex Make targets, overriding
@@ -1864,7 +1873,7 @@ When examining a variable definition, Automake will recursively examine
variables referenced in the definition. For example, if Automake is
looking at the content of @code{foo_SOURCES} in this snippet
- at c Keep in sync with interp.test.
+ at c Keep in sync with interp.sh
@example
xs = a.c b.c
foo_SOURCES = c.c $(xs)
@@ -1924,7 +1933,9 @@ The valid strictness levels are:
Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
-this mode. The name comes from the fact that Automake is intended to be
+this mode. This strictness will also turn off some warnings by default
+(among them, portability warnings).
+The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.
@@ -1943,14 +1954,6 @@ standard is actually published (which may never happen).
@xref{Gnits}, for more information on the precise implications of the
strictness level.
-Automake also has a special (and @emph{today deprecated}) ``cygnus'' mode
-that is similar to strictness but handled differently. This mode is
-useful for packages that are put into a ``Cygnus'' style tree (e.g., older
-versions of the GCC and gdb trees). @xref{Cygnus}, for more information
-on this mode. Please note that this mode is deprecated and @emph{will be
-removed in the future automake versions}; you must avoid its use in new
-packages, and should stop using it in existing packages as well.
-
@node Uniform
@section The Uniform Naming Scheme
@@ -2046,7 +2049,7 @@ defined (e.g., @samp{zardir}).
For instance, the following snippet will install @file{file.xml} into
@samp{$(datadir)/xml}.
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
xmldir = $(datadir)/xml
xml_DATA = file.xml
@@ -2057,7 +2060,7 @@ performs to diagnose suspicious directory/primary couples (in the
unlikely case these checks are undesirable, and you really know what
you're doing). For example, Automake would error out on this input:
- at c Should be tested in primary-prefix-invalid-couples.test.
+ at c Should be tested in primary-prefix-invalid-couples.sh
@example
# Forbidden directory combinations, automake will error out on this.
pkglib_PROGRAMS = foo
@@ -2067,7 +2070,7 @@ doc_LIBRARIES = libquux.a
@noindent
but it will succeed with this:
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
# Work around forbidden directory combinations. Do not use this
# without a very good reason!
@@ -2148,7 +2151,7 @@ data_DATA = file1 @dots{} file at var{N} file at var{N+1} @dots{} file at var{2N}
@noindent
may also be written as
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
data_DATA = file1 @dots{} file at var{N}
data2dir = $(datadir)
@@ -2253,12 +2256,6 @@ source in case you need more recent versions.
This is a wrapper primarily for the Microsoft lib archiver, to make
it more POSIX-like.
- at item ansi2knr.c
- at itemx ansi2knr.1
-These two files are used for de-ANSI-fication support (they are
-deprecated now, and @emph{will be removed} in the next major Automake
-release; @pxref{ANSI}).
-
@item compile
This is a wrapper for compilers that do not accept options @option{-c}
and @option{-o} at the same time. It is only used when absolutely
@@ -2279,23 +2276,12 @@ you are encouraged to fetch the latest versions of these files from
@url{http://savannah.gnu.org/git/?group=config} before making a
release.
- at item config-ml.in
-This file is not a program, it is a @file{configure} fragment used for
-multilib support (@pxref{Multilibs}). Since the Automake multilib
-support has been @emph{deprecated} and targeted for removal, this
-file is going to be @emph{removed from the Automake core} in the next
-major release. The master copy of this file is maintained in the GCC
-tree at @url{http://gcc.gnu.org/svn.html}.
-
@item depcomp
This program understands how to run a compiler so that it will
generate not only the desired output but also dependency information
that is then used by the automatic dependency tracking feature
(@pxref{Dependencies}).
- at item elisp-comp
-This program is used to byte-compile Emacs Lisp code.
-
@item install-sh
This is a replacement for the @command{install} program that works on
platforms where @command{install} is unavailable or unusable.
@@ -2306,9 +2292,9 @@ a file and prints some date information about it.
@item missing
This wraps a number of programs that are typically only required by
-maintainers. If the program in question doesn't exist,
- at command{missing} prints an informative warning and attempts to fix
-things so that the build can continue.
+maintainers. If the program in question doesn't exist, or seems to old,
+ at command{missing} will print an informative warning before failing out,
+to provide the user with more context and information.
@item mkinstalldirs
This script used to be a wrapper around @samp{mkdir -p}, which is not
@@ -2323,14 +2309,9 @@ longer installed automatically, and it should be safe to remove it.
@item py-compile
This is used to byte-compile Python scripts.
- at item symlink-tree
-This program duplicates a tree of directories, using symbolic links
-instead of copying files. Such an operation is performed when building
-multilibs (@pxref{Multilibs}). Since the Automake multilib support has
-been @emph{deprecated} and targeted for removal, this file is going to
-be @emph{removed from the Automake core} in the next major release.
-The master copy of this file is maintained in the GCC tree at
- at url{http://gcc.gnu.org/svn.html}.
+ at item test-driver
+This implements the default test driver offered by the parallel
+testsuite harness.
@item texinfo.tex
Not a program, this file is required for @samp{make dvi}, @samp{make
@@ -2493,7 +2474,7 @@ example in the manual. However if you were to build @code{true} and
@code{false} in real life, you would probably use per-program
compilation flags, like so:
- at c Keep in sync with specflg7.test and specflg8.test.
+ at c Keep in sync with specflg7.sh and specflg8.sh
@example
bin_PROGRAMS = false true
@@ -2594,6 +2575,12 @@ for more information.
Look for Automake data files in directory @var{dir} instead of in the
installation directory. This is typically used for debugging.
+ at item --print-libdir
+ at opindex --print-libdir
+Print the path of the installation directory containing Automake-provided
+scripts and data files (like e.g., @file{texinfo.texi} and
+ at file{install-sh}).
+
@item -c
@opindex -c
@itemx --copy
@@ -2601,13 +2588,6 @@ installation directory. This is typically used for debugging.
When used with @option{--add-missing}, causes installed files to be
copied. The default is to make a symbolic link.
- at item --cygnus
- at opindex --cygnus
-Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
-of GNU or Gnits rules. For more information, see @ref{Cygnus}.
-Note that @emph{this mode of operation is deprecated, and will be removed}
-in a future Automake release.
-
@item -f
@opindex -f
@itemx --force-missing
@@ -2711,13 +2691,11 @@ A category can be turned off by prefixing its name with @samp{no-}. For
instance, @option{-Wno-syntax} will hide the warnings about unused
variables.
-The categories output by default are @samp{syntax} and
+The categories output by default are @samp{obsolete}, @samp{syntax} and
@samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
are enabled in @option{--gnu} and @option{--gnits} strictness.
-On the other hand, the @option{silent-rules} options (@pxref{Options})
-turns off portability warnings about recursive variable expansions.
- at c Checked by extra-portability.test
+ at c Checked by extra-portability.sh
Turning off @samp{portability} will also turn off @samp{extra-portability},
and similarly turning on @samp{extra-portability} will also turn on
@samp{portability}. However, turning on @samp{portability} or turning
@@ -2832,7 +2810,7 @@ literals. If part of the specification uses shell variables,
@command{automake} will not be able to fulfill this setup, and you will
have to complete the missing bits by hand. For instance, on
- at c Keep in sync with output11.test.
+ at c Keep in sync with output11.sh
@example
file=input
@dots{}
@@ -2848,7 +2826,7 @@ source file.)
Similarly
- at c Keep in sync with output11.test.
+ at c Keep in sync with output11.sh
@example
file=output
file2=out:in
@@ -2869,7 +2847,7 @@ make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
that is compatible with @command{make}'s syntax) and furthermore use
@code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
@file{Makefile}, then @command{automake} will be able to use
- at samp{$@{file@}} to generate all these rules. For instance, here is
+ at samp{$@{file@}} to generate all of these rules. For instance, here is
how the Automake package itself generates versioned scripts for its
test suite:
@@ -2943,12 +2921,23 @@ The Autoconf Manual}.
@item AC_CONFIG_AUX_DIR
Automake will look for various helper scripts, such as
@file{install-sh}, in the directory named in this macro invocation.
- at c This list is accurate relative to version 1.8
-(The full list of scripts is: @file{ar-lib}, @file{config.guess},
- at file{config.sub}, @file{depcomp}, @file{elisp-comp}, @file{compile},
- at file{install-sh}, @file{ltmain.sh}, @file{mdate-sh}, @file{missing},
- at file{mkinstalldirs}, @file{py-compile}, @file{texinfo.tex}, and
- at file{ylwrap}.) Not all scripts are always searched for; some scripts
+ at c This list is accurate relative to version 1.11
+(The full list of scripts is:
+ at file{ar-lib},
+ at file{config.guess},
+ at file{config.sub},
+ at file{depcomp},
+ at file{compile},
+ at file{install-sh},
+ at file{ltmain.sh},
+ at file{mdate-sh},
+ at file{missing},
+ at file{mkinstalldirs},
+ at file{py-compile},
+ at file{test-driver},
+ at file{texinfo.tex},
+ at file{ylwrap}.)
+Not all scripts are always searched for; some scripts
will only be sought if the generated @file{Makefile.in} requires them.
If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
@@ -2969,9 +2958,11 @@ Automake will require the sources file declared with
macro.
@item AC_CONFIG_HEADERS
-Automake will generate rules to rebuild these headers. Older versions
-of Automake required the use of @code{AM_CONFIG_HEADER}
-(@pxref{Macros}); this is no longer the case.
+Automake will generate rules to rebuild these headers from the
+corresponding templates (usually, the template for a @file{foo.h}
+header being @file{foo.h.in}). Older versions of Automake
+required the use of @code{AM_CONFIG_HEADER}; this is no longer
+the case, and that macro has indeed been removed.
As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
specification using shell variables will be ignored as far as
@@ -3017,9 +3008,12 @@ Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
This is required if any Objective C source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+ at item AC_PROG_OBJCXX
+This is required if any Objective C++ source is included. @xref{Particular
+Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+
@item AC_PROG_F77
-This is required if any Fortran 77 source is included. This macro is
-distributed with Autoconf version 2.13 and later. @xref{Particular
+This is required if any Fortran 77 source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
@item AC_F77_LIBRARY_LDFLAGS
@@ -3077,11 +3071,6 @@ this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
@code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
if @code{AC_PATH_XTRA} is called.
- at item AM_C_PROTOTYPES
-This is required when using the deprecated de-ANSI-fication feature;
- at pxref{ANSI}. @emph{It will be removed} in the next major Automake
-release.
-
@item AM_CONDITIONAL
This introduces an Automake conditional (@pxref{Conditionals}).
@@ -3229,11 +3218,6 @@ Look for the system-wide third-party macro files (and the special
@file{dirlist} file) in @var{dir} instead of in the installation
directory. This is typically used for debugging.
- at item --acdir=@var{dir}
- at opindex --acdir
- at emph{Deprecated} shorthand for ``@option{--automake-acdir=@var{dir}
---system-acdir=@var{dir}}''. Will be removed in future aclocal versions.
-
@item --diff[=@var{command}]
@opindex --diff
Run @var{command} on M4 file that would be installed or overwritten
@@ -3259,7 +3243,7 @@ Add the directory @var{dir} to the list of directories searched for
Install system-wide third-party macros into the first directory
specified with @samp{-I @var{dir}} instead of copying them in the
output file.
- at c The following semantics is checked by `aclocal-install-absdir.test'.
+ at c Keep in sync with aclocal-install-absdir.sh
Note that this will happen also if @var{dir} is an absolute path.
@cindex serial number and @option{--install}
@@ -3475,18 +3459,18 @@ macros installed at other places on the system.
The fourth and last mechanism to customize the macro search path is
also the simplest. Any directory included in the colon-separated
environment variable @env{ACLOCAL_PATH} is added to the search path
- at c Keep in sync with aclocal-path-precedence.test.
+ at c Keep in sync with aclocal-path-precedence.sh
and takes precedence over system directories (including those found via
@file{dirlist}), with the exception of the versioned directory
@var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
passed via @option{-I} will take precedence over directories in
@env{ACLOCAL_PATH}.
- at c Keep in sync with aclocal-path-installed.test.
+ at c Keep in sync with aclocal-path-installed.sh
Also note that, if the @option{--install} option is used, any @file{.m4}
file containing a required macro that is found in a directory listed in
@env{ACLOCAL_PATH} will be installed locally.
- at c Keep in sync with aclocal-path-installed-serial.test.
+ at c Keep in sync with aclocal-path-installed-serial.sh
In this case, serial numbers in @file{.m4} are honoured too,
@pxref{Serials}.
@@ -3522,7 +3506,7 @@ installs this macro so that @command{aclocal} will find it.
A macro file's name should end in @file{.m4}. Such files should be
installed in @file{$(datadir)/aclocal}. This is as simple as writing:
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
aclocaldir = $(datadir)/aclocal
aclocal_DATA = mymacro.m4 myothermacro.m4
@@ -3556,7 +3540,7 @@ lot of people, because @command{aclocal} was not so strict in the past
and many third party macros are underquoted; and we have to apologize
for this temporary inconvenience. The reason we have to be stricter
is that a future implementation of @command{aclocal} (@pxref{Future of
-aclocal}) will have to temporarily include all these third party
+aclocal}) will have to temporarily include all of these third party
@file{.m4} files, maybe several times, including even files that are
not actually needed. Doing so should alleviate many problems of the
current implementation, however it requires a stricter style from the
@@ -3565,7 +3549,7 @@ For instance,
@example
# bad style
-AC_PREREQ(2.57)
+AC_PREREQ(2.68)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
@@ -3578,7 +3562,7 @@ should be rewritten as
@example
AC_DEFUN([AX_FOOBAR],
-[AC_PREREQ([2.57])dnl
+[AC_PREREQ([2.68])dnl
AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
AX_BAR
@@ -3586,11 +3570,11 @@ AX_BAR
@end example
Wrapping the @code{AC_PREREQ} call inside the macro ensures that
-Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
+Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
used. Most importantly, quoting the first argument of @code{AC_DEFUN}
allows the macro to be redefined or included twice (otherwise this
first argument would be expanded during the second definition). For
-consistency we like to quote even arguments such as @code{2.57} that
+consistency we like to quote even arguments such as @code{2.68} that
do not require it.
If you have been directed here by the @command{aclocal} diagnostic but
@@ -3620,32 +3604,19 @@ henceforth be visible to @command{autoconf}. However if it contains
numerous macros, it will rapidly become difficult to maintain, and it
will be almost impossible to share macros between packages.
- at vindex ACLOCAL_AMFLAGS
The second possibility, which we do recommend, is to write each macro
in its own file and gather all these files in a directory. This
-directory is usually called @file{m4/}. To build @file{aclocal.m4},
-one should therefore instruct @command{aclocal} to scan @file{m4/}.
-From the command line, this is done with @samp{aclocal -I m4}. The
-top-level @file{Makefile.am} should also be updated to define
+directory is usually called @file{m4/}. Then it's enough to update
+ at file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
@example
-ACLOCAL_AMFLAGS = -I m4
+AC_CONFIG_MACRO_DIRS([m4])
@end example
- at code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
-when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
-also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
-Using @command{autoreconf} to Update @file{configure} Scripts,
-autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
-options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
-Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
-and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
- at command{gettextize} Program, gettext, GNU gettext tools}) to locate
-the place where Gettext's macros should be installed. So even if you
-do not really care about the rebuild rules, you should define
- at code{ACLOCAL_AMFLAGS}.
+ at command{aclocal} will then take care of automatically adding @file{m4/}
+to its search path for m4 files.
-When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
+When @samp{aclocal} is run, it will build an @file{aclocal.m4}
that @code{m4_include}s any file from @file{m4/} that defines a
required macro. Macros not found locally will still be searched in
system-wide directories, as explained in @ref{Macro Search Path}.
@@ -3674,19 +3645,14 @@ this requirement will hinder development. An easy solution is to copy
such third-party macros in your local @file{m4/} directory so they get
distributed.
-Since Automake 1.10, @command{aclocal} offers an option to copy these
-system-wide third-party macros in your local macro directory, solving
-the above problem. Simply use:
-
- at example
-ACLOCAL_AMFLAGS = -I m4 --install
- at end example
+Since Automake 1.10, @command{aclocal} offers the option @code{--install}
+to copy these system-wide third-party macros in your local macro directory,
+helping to solve the above problem.
- at noindent
With this setup, system-wide macros will be copied to @file{m4/}
-the first time you run @command{autoreconf}. Then the locally
-installed macros will have precedence over the system-wide installed
-macros each time @command{aclocal} is run again.
+the first time you run @command{aclocal}. Then the locally installed
+macros will have precedence over the system-wide installed macros
+each time @command{aclocal} is run again.
One reason why you should keep @option{--install} in the flags even
after the first run is that when you later edit @file{configure.ac}
@@ -3767,16 +3733,14 @@ MyPackage uses an @file{m4/} directory to store local macros as
explained in @ref{Local Macros}, and has
@example
-ACLOCAL_AMFLAGS = -I m4 --install
+AC_CONFIG_MACRO_DIRS([m4])
@end example
@noindent
-in its top-level @file{Makefile.am}.
+in its @file{configure.ac}.
Initially the @file{m4/} directory is empty. The first time we run
- at command{autoreconf}, it will fetch the options to pass to
- at command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
---install}. @command{aclocal} will notice that
+ at command{aclocal --install}, it will notice that
@itemize @bullet
@item
@@ -3794,9 +3758,8 @@ and @command{aclocal} was given the @option{--install} option, it will
copy this file in @file{m4/thirdparty.m4}, and output an
@file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
-The next time @samp{aclocal -I m4 --install} is run (either via
- at command{autoreconf}, by hand, or from the @file{Makefile} rebuild
-rules) something different happens. @command{aclocal} notices that
+The next time @samp{aclocal --install} is run, something different
+happens. @command{aclocal} notices that
@itemize @bullet
@item
@@ -3822,8 +3785,8 @@ the system-wide file in case of equal serial numbers.
Now suppose the system-wide third-party macro is changed. This can
happen if the package installing this macro is updated. Let's suppose
-the new macro has serial number 2. The next time @samp{aclocal -I m4
---install} is run the situation is the following:
+the new macro has serial number 2. The next time @samp{aclocal --install}
+is run the situation is the following:
@itemize @bullet
@item
@@ -3849,16 +3812,16 @@ macro in @file{m4/thirdparty.m4}, in this case overriding the old
version. MyPackage just had its macro updated as a side effect of
running @command{aclocal}.
-If you are leery of letting @command{aclocal} update your local macro,
-you can run @samp{aclocal -I m4 --diff} to review the changes
- at samp{aclocal -I m4 --install} would perform on these macros.
+If you are leery of letting @command{aclocal} update your local
+macro, you can run @samp{aclocal --diff} to review the changes
+ at samp{aclocal --install} would perform on these macros.
Finally, note that the @option{--force} option of @command{aclocal} has
absolutely no effect on the files installed by @option{--install}. For
instance, if you have modified your local macros, do not expect
@option{--install --force} to replace the local macros by their
system-wide versions. If you want to do so, simply erase the local
-macros you want to revert, and run @samp{aclocal -I m4 --install}.
+macros you want to revert, and run @samp{aclocal --install}.
@node Future of aclocal
@@ -3919,7 +3882,7 @@ Automake ships with several Autoconf macros that you can use from your
@menu
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that you should stop using.
+* Obsolete Macros:: Macros that will soon be removed.
* Private Macros:: Macros that you should not use.
@end menu
@@ -3930,40 +3893,32 @@ Automake ships with several Autoconf macros that you can use from your
@table @code
- at item AM_ENABLE_MULTILIB
- at acindex AM_ENABLE_MULTILIB
-
-This is used when a ``multilib'' library is being built. Please be
-aware that multilib support @emph{will be removed} from the Automake
-core in the next major release, and then @emph{this macro will go away
-as well} (even if a ``frozen'' version of will remain available in the
- at file{contrib/} directory of the Automake distribution).
-
-The first optional argument is the name of the @file{Makefile} being
-generated; it defaults to @samp{Makefile}. The second optional argument
-is used to find the top source directory; it defaults to the empty
-string (generally this should not be used unless you are familiar with
-the internals). @xref{Multilibs}.
-
@item AM_INIT_AUTOMAKE([OPTIONS])
- at itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
@acindex AM_INIT_AUTOMAKE
Runs many macros required for proper operation of the generated Makefiles.
@vindex AUTOMAKE_OPTIONS
-This macro has two forms, the first of which is preferred.
-In this form, @code{AM_INIT_AUTOMAKE} is called with a
-single argument: a space-separated list of Automake options that should
-be applied to every @file{Makefile.am} in the tree. The effect is as if
+Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
+space-separated list of Automake options that should be applied to
+every @file{Makefile.am} in the tree. The effect is as if
each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
@acindex AC_INIT
-The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
-arguments: the package and the version number. This form is
-obsolete because the @var{package} and @var{version} can be obtained
-from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
-form).
-
+This macro can also be called in another, @emph{deprecated} form:
+ at code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
+there are two required arguments: the package and the version number.
+This usage is mostly obsolete because the @var{package} and @var{version}
+can be obtained from Autoconf's @code{AC_INIT} macro. However,
+differently from what happens for @code{AC_INIT} invocations, this
+ at code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
+in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
+still be useful in some selected situations. Our hope is that future
+Autoconf versions will improve their support for package versions
+defined dynamically at configure runtime; when (and if) this happens,
+support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
+be removed from Automake.
+
+ at anchor{Modernize AM_INIT_AUTOMAKE invocation}
If your @file{configure.ac} has:
@example
@@ -3972,7 +3927,7 @@ AM_INIT_AUTOMAKE([mumble], [1.5])
@end example
@noindent
-you can modernize it as follows:
+you should modernize it as follows:
@example
AC_INIT([mumble], [1.5])
@@ -3997,11 +3952,10 @@ explicitly).
@opindex no-define
By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
@code{VERSION}. This can be avoided by passing the @option{no-define}
-option, as in:
+option (@pxref{List of Automake options}):
@example
-AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
+AM_INIT_AUTOMAKE([no-define ...])
@end example
-or by passing a third non-empty argument to the obsolete form.
@item AM_PATH_LISPDIR
@acindex AM_PATH_LISPDIR
@@ -4073,9 +4027,20 @@ variable. The default @var{compiler-search-list} is @samp{upcc upc}.
This macro will abort @command{configure} if no Unified Parallel C
compiler is found.
+ at item AM_MISSING_PROG(@var{name}, @var{program})
+ at acindex AM_MISSING_PROG
+ at vindex MISSING
+Find a maintainer tool @var{program} and define the @var{name}
+environment variable with its location. If @var{program} is not
+detected, then @var{name} will instead invoke the @command{missing}
+script, in order to give useful advice to the user about the missing
+maintainer tool. @xref{maintainer-mode}, for more information on when
+the @command{missing} script is appropriate.
+
@item AM_SILENT_RULES
@acindex AM_SILENT_RULES
-Enable the machinery for less verbose build output (@pxref{Options}).
+Control the machinery for less verbose build output
+(@pxref{Automake Silent Rules}).
@item AM_WITH_DMALLOC
@acindex AM_WITH_DMALLOC
@@ -4095,37 +4060,15 @@ define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
@cindex autoupdate
Although using some of the following macros was required in past
-releases, you should not use any of them in new code. Running
- at command{autoupdate} should adjust your @file{configure.ac}
-automatically (@pxref{autoupdate Invocation, , Using
- at command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
-Autoconf Manual}).
+releases, you should not use any of them in new code. @emph{All
+these macros will be removed in the next major Automake version};
+if you are still using them, running @command{autoupdate} should
+adjust your @file{configure.ac} automatically (@pxref{autoupdate
+Invocation, , Using @command{autoupdate} to Modernize
+ at file{configure.ac}, autoconf, The Autoconf Manual}).
+ at emph{Do it NOW!}
@table @code
- at item AM_C_PROTOTYPES
- at acindex AM_C_PROTOTYPES
- at vindex ANSI2KNR
- at vindex U
-Check to see if function prototypes are understood by the compiler. If
-so, define @samp{PROTOTYPES} and set the output variables @code{U} and
- at code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
- at samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake used these
-values to implement the deprecated de-ANSI-fication feature; however,
-support for @emph{that feature will be removed} in the next major Automake
-release, and then @emph{these macros and variables will go away as well}.
-
- at item AM_CONFIG_HEADER
- at acindex AM_CONFIG_HEADER
-Automake will generate rules to automatically regenerate the config
-header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
-today (@pxref{Optional}).
-
- at item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
- at acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
-If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
-define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
-found in @file{<termios.h>}. This macro is obsolete, you should
-use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
@item AM_PROG_MKDIR_P
@acindex AM_PROG_MKDIR_P
@@ -4140,43 +4083,12 @@ variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
Nowadays Autoconf provides a similar functionality with
@code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
Program Checks, autoconf, The Autoconf Manual}), however this defines
-the output variable @code{MKDIR_P} instead. Therefore
- at code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
- at code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
- at code{MKDIR_P} for backward compatibility.
-
-If you are using Automake, there is normally no reason to call this
-macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
-sure that the custom rules in your @file{Makefile}s use
- at code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
-still work, the latter should be considered obsolete.
-
-If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
-instead of @code{AM_PROG_MKDIR_P}.
-
- at item AM_SYS_POSIX_TERMIOS
- at acindex AM_SYS_POSIX_TERMIOS
- at cindex POSIX termios headers
- at cindex termios POSIX headers
-Check to see if POSIX termios headers and functions are available on the
-system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
- at samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
-you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
-
- at item AM_WITH_REGEX
- at acindex AM_WITH_REGEX
- at vindex WITH_REGEX
- at opindex --with-regex
- at cindex regex package
- at cindex rx package
-Adds @option{--with-regex} to the @command{configure} command line. If
-specified (the default), then the @samp{regex} regular expression
-library is used, @file{regex.o} is put into @code{LIBOBJS}, and
- at code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
-the @samp{rx} regular expression library is used, and @file{rx.o} is put
-into @code{LIBOBJS}. This macro is obsolete now (since @samp{rx} doesn't
-seem to be maintained), and @emph{will be removed the next major version
-of Automake}. Consider using gnulib if you need regex functionality.
+the output variable @code{MKDIR_P} instead. In case you are still
+using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
+or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
+you are advised to switch ASAP to the more modern Autoconf-provided
+interface instead; both the macro and the variable might be removed
+in a future major Automake release.
@end table
@@ -4225,13 +4137,25 @@ For simple projects that distribute all files in the same directory
it is enough to have a single @file{Makefile.am} that builds
everything in place.
-In larger projects it is common to organize files in different
-directories, in a tree. For instance one directory per program, per
-library or per module. The traditional approach is to build these
-subdirectories recursively: each directory contains its @file{Makefile}
-(generated from @file{Makefile.am}), and when @command{make} is run
-from the top level directory it enters each subdirectory in turn to
-build its contents.
+In larger projects, it is common to organize files in different
+directories, in a tree. For example, there could be a directory
+for the program's source, one for the testsuite, and one for the
+documentation; or, for very large projects, there could be one
+directory per program, per library or per module.
+
+The traditional approach is to build these subdirectories recursively,
+employing @emph{make recursion}: each directory contains its
+own @file{Makefile}, and when @command{make} is run from the top-level
+directory, it enters each subdirectory in turn, and invokes there a
+new @command{make} instance to build the directory's contents.
+
+Because this approach is very widespread, Automake offers built-in
+support for it. However, it is worth nothing that the use of make
+recursion has its own serious issues and drawbacks, and that it's
+well possible to have packages with a multi directory layout that
+make little or no use of such recursion (examples of such packages
+are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
+section below.
@menu
* Subdirectories:: Building subdirectories recursively
@@ -4245,7 +4169,7 @@ build its contents.
@cindex @code{SUBDIRS}, explained
-In packages with subdirectories, the top level @file{Makefile.am} must
+In packages using make recursion, the top level @file{Makefile.am} must
tell Automake which subdirectories are to be built. This is done via
the @code{SUBDIRS} variable.
@vindex SUBDIRS
@@ -4303,7 +4227,33 @@ will be built. It is customary to arrange test directories to be
built after everything else since they are meant to test what has
been constructed.
-All @code{clean} rules are run in reverse order of build rules.
+In addition to the built-in recursive targets defined by Automake
+(@code{all}, @code{check}, etc.), the developer can also define his
+own recursive targets. That is done by passing the names of such
+targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
+in @file{configure.ac}. Automake generates rules to handle the
+recursion for such targets; and the developer can define real actions
+for them by defining corresponding @code{-local} targets.
+
+ at example
+% @kbd{cat configure.ac}
+AC_INIT([pkg-name], [1.0]
+AM_INIT_AUTOMAKE
+AM_EXTRA_RECURSIVE_TARGETS([foo])
+AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
+AC_OUTPUT
+% @kbd{cat Makefile.am}
+SUBDIRS = sub
+foo-local:
+ @@echo This will be run by "make foo".
+% @kbd{cat sub/Makefile.am}
+SUBDIRS = src
+% @kbd{cat sub/src/Makefile.am}
+foo-local:
+ @@echo This too will be run by a "make foo" issued either in
+ @@echo the 'sub/src/' directory, the 'sub/' directory, or the
+ @@echo top-level directory.
+ at end example
@node Conditional Subdirectories
@section Conditional Subdirectories
@@ -4382,7 +4332,7 @@ does not know the possible values of these variables. In this case
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
- at c Keep in sync with subcond2.test.
+ at c Keep in sync with subdir-am-cond.sh
@file{configure} should output the @file{Makefile} for each directory
and define a condition into which @file{opt/} should be built.
@@ -4422,7 +4372,7 @@ automatically because it knows that @code{MAYBE_OPT} can contain
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
- at c Keep in sync with subcond3.test.
+ at c Keep in sync with subdir-ac-subst.sh
Another possibility is to define @code{MAYBE_OPT} from
@file{./configure} using @code{AC_SUBST}:
@@ -4528,7 +4478,7 @@ variables it cannot ensure the corresponding directory exists.
If you've ever read Peter Miller's excellent paper,
@uref{http://miller.emu.id.au/pmiller/books/rmch/,
Recursive Make Considered Harmful}, the preceding sections on the use of
-subdirectories will probably come as unwelcome advice. For those who
+make recursion will probably come as unwelcome advice. For those who
haven't read the paper, Miller's main thesis is that recursive
@command{make} invocations are both slow and error-prone.
@@ -4538,7 +4488,6 @@ believe. This work is new and there are probably warts.
to write a single @file{Makefile.am} for a complex multi-directory
package.
-
By default an installable file specified in a subdirectory will have its
directory name stripped before installation. For instance, in this
example, the header file will be installed as
@@ -4580,7 +4529,7 @@ often be replaced by several variables, one for each destination
directory (@pxref{Uniform}). For instance, the last example could be
rewritten as follows:
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
imagesdir = $(pkgdatadir)/images
soundsdir = $(pkgdatadir)/sounds
@@ -4718,6 +4667,7 @@ to build programs and libraries.
* Yacc and Lex:: Yacc and Lex support
* C++ Support:: Compiling C++ sources
* Objective C Support:: Compiling Objective C sources
+* Objective C++ Support:: Compiling Objective C++ sources
* Unified Parallel C Support:: Compiling Unified Parallel C sources
* Assembly Support:: Compiling assembly sources
* Fortran 77 Support:: Compiling Fortran 77 sources
@@ -4725,7 +4675,6 @@ to build programs and libraries.
* Java Support with gcj:: Compiling Java sources using gcj
* Vala Support:: Compiling Vala sources
* Support for Other Languages:: Compiling other languages
-* ANSI:: Automatic de-ANSI-fication (deprecated, soon to be removed)
* Dependencies:: Automatic dependency tracking
* EXEEXT:: Support for executable extensions
@end menu
@@ -5037,7 +4986,7 @@ You can also use Automake conditionals (@pxref{Conditionals}) to
select programs to be built. In this case you don't have to worry
about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
- at c Keep in sync with exeext.test.
+ at c Keep in sync with exeext.sh
@example
bin_PROGRAMS = cpio pax
if WANT_MT
@@ -5088,7 +5037,7 @@ Extra objects can be added to a library using the
@code{@var{library}_LIBADD} variable. This should be used for objects
determined by @command{configure}. Again from @code{cpio}:
- at c Keep in sync with pr401c.test.
+ at c Keep in sync with pr401c.sh
@example
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
@end example
@@ -5294,7 +5243,7 @@ relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
the link rule for these two libraries. Therefore the @option{-rpath}
argument must be explicitly supplied.
- at c Keep in sync with ltcond.test.
+ at c Keep in sync with ltcond.sh
@example
EXTRA_LTLIBRARIES = libfoo.la libbar.la
lib_LTLIBRARIES = $(WANTEDLIBS)
@@ -5310,7 +5259,7 @@ Automake is able to compute the @option{-rpath} setting itself, because
it's clear that both libraries will end up in @samp{$(libdir)} if they
are installed.
- at c Keep in sync with ltcond.test.
+ at c Keep in sync with ltcond.sh
@example
lib_LTLIBRARIES =
if WANT_LIBFOO
@@ -5337,7 +5286,7 @@ we could build a @file{libhello.la} library using either
@file{hello-linux.c} or @file{hello-generic.c} with the following
@file{Makefile.am}.
- at c Keep in sync with ltcond2.test.
+ at c Keep in sync with ltcond2.sh
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
@@ -5352,7 +5301,7 @@ either @file{hello-linux.lo} or @file{hello- at -generic.lo}.
Or we could simply use an Automake conditional as follows.
- at c Keep in sync with ltcond2.test.
+ at c Keep in sync with ltcond2.sh
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
@@ -5392,7 +5341,7 @@ dependency anywhere it won't be built (this is why
Here is a sample setup merging libtool convenience libraries from
subdirectories into one main @file{libtop.la} library.
- at c Keep in sync with ltconv.test.
+ at c Keep in sync with ltconv.sh
@example
# -- Top-level Makefile.am --
SUBDIRS = sub1 sub2 @dots{}
@@ -5529,9 +5478,8 @@ The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
Variables Ordering}. It allows users to run @samp{make
LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
- at command{libtool} can also be influenced with the Automake
- at option{silent-rules} option (@pxref{Options}).
-
+ at command{libtool} can also be influenced by the Automake support
+for silent rules (@pxref{Automake Silent Rules}).
@node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
@subsection @code{LTLIBOBJS} and @code{LTALLOCA}
@@ -5623,7 +5571,7 @@ replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
Therefore, when Automake detects this situation it will complain
with a message such as
@example
-object `foo.$(OBJEXT)' created both with libtool and without
+object 'foo.$(OBJEXT)' created both with libtool and without
@end example
A workaround for this issue is to ensure that these two objects get
@@ -5836,6 +5784,7 @@ they apply.
@itemx maude_GCJFLAGS
@itemx maude_LFLAGS
@itemx maude_OBJCFLAGS
+ at itemx maude_OBJCXXFLAGS
@itemx maude_RFLAGS
@itemx maude_UPCFLAGS
@itemx maude_YFLAGS
@@ -5853,6 +5802,7 @@ Automake. These @dfn{per-target compilation flags} are
@samp{_GCJFLAGS},
@samp{_LFLAGS},
@samp{_OBJCFLAGS},
+ at samp{_OBJCXXFLAGS},
@samp{_RFLAGS},
@samp{_UPCFLAGS}, and
@samp{_YFLAGS}.
@@ -6158,9 +6108,9 @@ Automake already provides some @option{-I} options automatically, in a
separate variable that is also passed to every compilation that invokes
the C preprocessor. In particular it generates @samp{-I.},
@samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
- at file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
- at code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
-options using the @option{nostdinc} option.
+ at file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
+disable the default @option{-I} options using the @option{nostdinc}
+option.
When a file to be included is generated during the build and not part
of a distribution tarball, its location is under @code{$(builddir)},
@@ -6185,9 +6135,9 @@ same functionality. This variable is deprecated; we suggest using
@item AM_CFLAGS
This is the variable the @file{Makefile.am} author can use to pass
-in additional C compiler flags. It is more fully documented elsewhere.
-In some situations, this is not used, in preference to the
-per-executable (or per-library) @code{_CFLAGS}.
+in additional C compiler flags. In some situations, this is
+not used, in preference to the per-executable (or per-library)
+ at code{_CFLAGS}.
@item COMPILE
This is the command used to actually compile a C source file. The
@@ -6220,12 +6170,16 @@ cause the intermediate file to be named @file{foo.c} (as opposed to
@file{y.tab.c}, which is more traditional).
The extension of a yacc source file is used to determine the extension
-of the resulting C or C++ file. Files with the extension @file{.y}
-will be turned into @file{.c} files; likewise, @file{.yy} will become
- at file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
- at file{.ypp}, @file{.cpp}.
-
-Likewise, lex source files can be used to generate C or C++; the
+of the resulting C or C++ source and header files. Note that header
+files are generated only when the @option{-d} Yacc option is used; see
+below for more information about this flag, and how to specify it.
+Files with the extension @file{.y} will thus be turned into @file{.c}
+sources and @file{.h} headers; likewise, @file{.yy} will become
+ at file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
+ at file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
+and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
+
+Similarly, lex source files can be used to generate C or C++; the
extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
@file{.lpp} are recognized.
@@ -6254,7 +6208,7 @@ adjust its rules to update and distribute the header file built by
@option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
options; for example, it won't be recognized if @code{AM_YFLAGS} is
@option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
- at option{-d -t}}.
+ at option{-t -d}.}.
What Automake cannot guess, though, is where this
header will be used: it is up to you to ensure the header gets built
before it is first used. Typically this is necessary in order for
@@ -6425,6 +6379,41 @@ The command used to actually link an Objective C program.
@end vtable
+ at node Objective C++ Support
+ at section Objective C++ Support
+
+ at cindex Objective C++ support
+ at cindex Support for Objective C++
+
+Automake includes some support for Objective C++.
+
+Any package including Objective C++ code must define the output variable
+ at code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
+the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
+Program Checks, autoconf, The Autoconf Manual}).
+
+A few additional variables are defined when an Objective C++ source file
+is seen:
+
+ at vtable @code
+ at item OBJCXX
+The name of the Objective C++ compiler.
+
+ at item OBJCXXFLAGS
+Any flags to pass to the Objective C++ compiler.
+
+ at item AM_OBJCXXFLAGS
+The maintainer's variant of @code{OBJCXXFLAGS}.
+
+ at item OBJCXXCOMPILE
+The command used to actually compile an Objective C++ source file. The
+file name is appended to form the complete command line.
+
+ at item OBJCXXLINK
+The command used to actually link an Objective C++ program.
+ at end vtable
+
+
@node Unified Parallel C Support
@section Unified Parallel C Support
@@ -6634,10 +6623,9 @@ in the appropriate Fortran 77 intrinsic and run-time libraries.
@cindex @code{FLIBS}, defined
@vindex FLIBS
These extra Fortran 77 linker flags are supplied in the output variable
- at code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
-supplied with newer versions of Autoconf (Autoconf version 2.13 and
-later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
-autoconf, The Autoconf Manual}.
+ at code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
+ at xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
+The Autoconf Manual}.
@end enumerate
If Automake detects that a program or shared library (as mentioned in
@@ -6691,6 +6679,9 @@ parentheses are the variables containing the link command.)
@vindex GCJLINK
Native Java (@code{GCJLINK})
@item
+ at vindex OBJCXXLINK
+Objective C++ (@code{OBJCXXLINK})
+ at item
@vindex CXXLINK
C++ (@code{CXXLINK})
@item
@@ -6855,28 +6846,32 @@ foo_SOURCES = foo.vala bar.vala zardoc.c
@end example
Any @file{.vala} file listed in a @code{_SOURCES} variable will be
-compiled into C code by the Vala compiler. The generated @file{.c} files are
-distributed. The end user does not need to have a Vala compiler installed.
+compiled into C code by the Vala compiler. The generated @file{.c} files
+are distributed. The end user does not need to have a Vala compiler installed.
Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
that will locate the Vala compiler and optionally check its version
number.
- at defmac AM_PROG_VALAC (@ovar{minimum-version})
-Try to find a Vala compiler in @env{PATH}. If it is found, the variable
- at code{VALAC} is set. Optionally a minimum release number of the compiler
-can be requested:
-
- at example
-AM_PROG_VALAC([0.7.0])
- at end example
+ at defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
+ @ovar{action-if-not-found})
+Search for a Vala compiler in @env{PATH}. If it is found, the variable
+ at code{VALAC} is set to point to it (see below for more details). This
+macro takes three optional arguments. The first argument, if present,
+is the minimum version of the Vala compiler required to compile this
+package. If a compiler is found and satisfies @var{minimum-version},
+then @var{action-if-found} is run (this defaults to do nothing).
+Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
+is not specified, the default value is to print a warning in case no
+compiler is found, or if a too-old version of the compiler is found.
@end defmac
There are a few variables that are used when compiling Vala sources:
@vtable @code
@item VALAC
-Path to the Vala compiler.
+Absolute path to the Vala compiler, or simply @samp{valac} if no
+suitable compiler Vala could be found at configure runtime.
@item VALAFLAGS
Additional arguments for the Vala compiler.
@@ -6900,7 +6895,9 @@ source file.
@section Support for Other Languages
Automake currently only includes full support for C, C++ (@pxref{C++
-Support}), Objective C (@pxref{Objective C Support}), Fortran 77
+Support}), Objective C (@pxref{Objective C Support}),
+Objective C++ (@pxref{Objective C++ Support}),
+Fortran 77
(@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
and Java (@pxref{Java Support with gcj}). There is only rudimentary
support for other languages, support for which will be improved based
@@ -6909,85 +6906,6 @@ on user demand.
Some limited support for adding your own languages is available via the
suffix rule handling (@pxref{Suffixes}).
-
- at node ANSI
- at section Automatic de-ANSI-fication (deprecated, soon to be removed)
-
- at cindex de-ANSI-fication, defined
-
- at emph{The features described in this section are deprecated; you must
-not use any of them in new code, and remove their use from older but
-still maintained code: they will be withdrawn in the next major
-Automake release.}
-
-When the C language was standardized in 1989, there was a long
-transition period where package developers needed to worry about
-porting to older systems that did not support ANSI C by default.
-These older systems are no longer in practical use and are no longer
-supported by their original suppliers, so developers need not worry
-about this problem any more.
-
-Automake allows you to write packages that are portable to K&R C by
- at dfn{de-ANSI-fying} each source file before the actual compilation takes
-place.
-
- at vindex AUTOMAKE_OPTIONS
- at opindex ansi2knr
-
-If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
-(@pxref{Options}) contains the option @option{ansi2knr} then code to
-handle de-ANSI-fication is inserted into the generated
- at file{Makefile.in}.
-
-This causes each C source file in the directory to be treated as ANSI C at .
-If an ANSI C compiler is available, it is used. If no ANSI C compiler
-is available, the @command{ansi2knr} program is used to convert the source
-files into K&R C, which is then compiled.
-
-The @command{ansi2knr} program is simple-minded. It assumes the source
-code will be formatted in a particular way; see the @command{ansi2knr} man
-page for details.
-
- at acindex AM_C_PROTOTYPES
-Support for the obsolete de-ANSI-fication feature
-requires the source files @file{ansi2knr.c}
-and @file{ansi2knr.1} to be in the same package as the ANSI C source;
-these files are distributed with Automake. Also, the package
- at file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
-(@pxref{Macros}).
-
-Automake also handles finding the @command{ansi2knr} support files in some
-other directory in the current package. This is done by prepending the
-relative path to the appropriate directory to the @command{ansi2knr}
-option. For instance, suppose the package has ANSI C code in the
- at file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
- at file{ansi2knr.1} appear in @file{lib}. Then this could appear in
- at file{src/Makefile.am}:
-
- at example
-AUTOMAKE_OPTIONS = ../lib/ansi2knr
- at end example
-
-If no directory prefix is given, the files are assumed to be in the
-current directory.
-
-Note that automatic de-ANSI-fication will not work when the package is
-being built for a different host architecture. That is because
- at command{automake} currently has no way to build @command{ansi2knr}
-for the build machine.
-
- at c FIXME: this paragraph might be better moved to an `upgrading' section.
- at cindex @code{LTLIBOBJS} and @code{ansi2knr}
- at cindex @code{LIBOBJS} and @code{ansi2knr}
- at cindex @code{ansi2knr} and @code{LTLIBOBJS}
- at cindex @code{ansi2knr} and @code{LIBOBJS}
-Using @code{LIBOBJS} with source de-ANSI-fication used to require
-hand-crafted code in @file{configure} to append @samp{$U} to basenames
-in @code{LIBOBJS}. This is no longer true today. Starting with version
-2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
- at code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
-vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
-
@node Dependencies
@section Automatic dependency tracking
@@ -7013,11 +6931,11 @@ your build.
@cindex @command{depcomp}
-Experience with earlier versions of Automake (@pxref{Dependency
-Tracking Evolution}) taught us that it is not reliable to generate
-dependencies only on the maintainer's system, as configurations vary
-too much. So instead Automake implements dependency tracking at build
-time.
+Experience with earlier versions of Automake (@pxref{Dependency Tracking
+Evolution, , Dependency Tracking Evolution, automake-history, Brief History
+of Automake}) taught us that it is not reliable to generate dependencies
+only on the maintainer's system, as configurations vary too much. So
+instead Automake implements dependency tracking at build time.
Automatic dependency tracking can be suppressed by putting
@option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
@@ -7078,20 +6996,14 @@ substitutions. This means that if you are conditionally building a
program using such a substitution, then your @file{configure.ac} must
take care to add @samp{$(EXEEXT)} when constructing the output variable.
-With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
-to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
-automatically if you configure a compiler (say, through
- at code{AC_PROG_CC}).
-
Sometimes maintainers like to write an explicit link rule for their
program. Without executable extension support, this is easy---you
simply write a rule whose target is the name of the program. However,
when executable extension support is enabled, you must instead add the
@samp{$(EXEEXT)} suffix.
-Unfortunately, due to the change in Autoconf 2.50, this means you must
-always add this extension. However, this is a problem for maintainers
-who know their package will never run on a platform that has
+This might be a nuisance for maintainers who know their package will
+never run on a platform that has
executable extensions. For those maintainers, the @option{no-exeext}
option (@pxref{Options}) will disable this feature. This works in a
fairly ugly way; if @option{no-exeext} is seen, then the presence of a
@@ -7609,7 +7521,10 @@ Lisp sources are not distributed by default. You can prefix the
distributed.
Automake will byte-compile all Emacs Lisp source files using the Emacs
-found by @code{AM_PATH_LISPDIR}, if any was found.
+found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
+byte-compilation, the flags specified in the (developer-reserved)
+ at code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
+will be passed to the Emacs invocation.
Byte-compiled Emacs Lisp files are not portable among all versions of
Emacs, so it makes sense to turn this off if you expect sites to have
@@ -7635,7 +7550,7 @@ variable explicitly prevents byte-compilation.
Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
lisp_DATA = file1.el file2.el
@end example
@@ -7683,11 +7598,11 @@ libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
Automake provides some minimal support for Java bytecode compilation with
the @code{JAVA} primary (in addition to the support for compiling Java to
native machine code; @pxref{Java Support with gcj}). Note however that
- at emph{the interface and most features described here are deprecated}; the
-next automake release will strive to provide a better and cleaner
+ at emph{the interface and most features described here are deprecated}.
+Future Automake releases will strive to provide a better and cleaner
interface, which however @emph{won't be backward-compatible}; the present
-interface will probably be removed altogether in future automake releases
-(1.13 or later), so don't use it in new code.
+interface will probably be removed altogether some time after the
+introduction of the new interface (if that ever materializes).
Any @file{.java} files listed in a @code{_JAVA} variable will be
compiled with @code{JAVAC} at build time. By default, @file{.java}
@@ -7697,7 +7612,7 @@ files are not included in the distribution, you should use the
Here is a typical setup for distributing @file{.java} files and
installing the @file{.class} files resulting from their compilation.
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
javadir = $(datadir)/java
dist_java_JAVA = a.java b.java @dots{}
@@ -7771,7 +7686,7 @@ Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
that will determine some Python-related directory variables (see
below). If you have called @code{AM_PATH_PYTHON} from
@file{configure.ac}, then you may use the variables
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
files in your @file{Makefile.am}, depending on where you want your files
installed (see the definitions of @code{pythondir} and
@@ -7860,7 +7775,7 @@ This is the directory where Python extension modules (shared libraries)
should be installed. An extension module written in C could be declared
as follows to Automake:
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
pyexec_LTLIBRARIES = quaternion.la
quaternion_la_SOURCES = quaternion.c support.c support.h
@@ -7872,7 +7787,7 @@ This is a convenience variable that is defined as
@samp{$(pyexecdir)/$(PACKAGE)}.
@end vtable
-All these directory variables have values that start with either
+All of these directory variables have values that start with either
@samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
fine in @file{Makefiles}, but it makes these variables hard to use in
@file{configure}. This is mandated by the GNU coding standards, so
@@ -7910,9 +7825,9 @@ Currently Automake provides support for Texinfo and man pages.
If the current directory contains Texinfo source, you must declare it
with the @code{TEXINFOS} primary. Generally Texinfo files are converted
into info, and thus the @code{info_TEXINFOS} variable is most commonly used
-here. Any Texinfo source file must end in the @file{.texi},
- at file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
-for new manuals.
+here. Any Texinfo source file should have the @file{.texi} extension.
+Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
+use is discouraged now, and will elicit runtime warnings.
Automake generates rules to build @file{.info}, @file{.dvi},
@file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
@@ -7938,7 +7853,7 @@ can be installed with @samp{make install-dvi}, @samp{make install-ps},
documentation installed by default as well as all the above optional
formats.
-All these targets can be extended using @samp{-local} rules
+All of these targets can be extended using @samp{-local} rules
(@pxref{Extending}).
@cindex Texinfo flag, @code{VERSION}
@@ -8030,9 +7945,9 @@ be prevented via the @code{no-installinfo} option. In this case,
request this explicitly using @samp{make install-info}.
@vindex AM_UPDATE_INFO_DIR
-By default, @code{make install-info} and @code{make install-info}
-will try to run the @command{install-info} program (if available)
-to update (or create) the @file{@code{$@{infodir@}}/dir} index.
+By default, @code{make install-info} and @code{make uninstall-info}
+will try to run the @command{install-info} program (if available) to
+update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
If this is undesired, it can be prevented by exporting the
@code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
@@ -8064,7 +7979,7 @@ passed to @code{makeinfo} when building @file{.info} files; and
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
- at c Keep in sync with txinfo21.test.
+ at c Keep in sync with txinfo-many-output-formats.sh
For instance, the following setting can be used to obtain one single
@file{.html} file per manual, without node separators.
@example
@@ -8292,7 +8207,7 @@ while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
Any variable using a user-defined directory prefix with
@samp{exec} in the name (e.g.,
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
@code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
other user-defined prefixes are installed by @code{install-data}.
@@ -8479,7 +8394,7 @@ included if they are found in the current directory (either physically,
or as the target of a @file{Makefile.am} rule); this list is printed by
@samp{automake --help}. Note that some files in this list are actually
distributed only if other certain conditions hold (for example,
- at c Keep in sync with autodist-config-headers.test.
+ at c Keep in sync with autodist-config-headers.sh
the @file{config.h.top} and @file{config.h.bot} files are automatically
distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
in @file{configure.ac}). Also, files that are read by @command{configure}
@@ -8544,24 +8459,35 @@ nodist_foo_SOURCES = do-not-distribute.c
Occasionally it is useful to be able to change the distribution before
it is packaged up. If the @code{dist-hook} rule exists, it is run
-after the distribution directory is filled, but before the actual tar
-(or shar) file is created. One way to use this is for distributing
-files in subdirectories for which a new @file{Makefile.am} is overkill:
+after the distribution directory is filled, but before the actual
+distribution archives are created. One way to use this is for
+removing unnecessary files that get recursively included by specifying
+a directory in @code{EXTRA_DIST}:
@example
+EXTRA_DIST = doc
dist-hook:
- mkdir $(distdir)/random
- cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
+ rm -rf `find $(distdir)/doc -type d -name .svn`
@end example
-Another way to use this is for removing unnecessary files that get
-recursively included by specifying a directory in EXTRA_DIST:
-
- at example
-EXTRA_DIST = doc
-
+ at c The caveates described here should be documented in 'disthook.sh'.
+ at noindent
+Note that the @code{dist-hook} recipe shouldn't assume that the regular
+files in the distribution directory are writable; this might not be the
+case if one is packaging from a read-only source tree, or when a
+ at code{make distcheck} is being done. For similar reasons, the recipe
+shouldn't assume that the subdirectories put into the distribution
+directory as effect of having them listed in @code{EXTRA_DIST} are
+writable. So, if the @code{dist-hook} recipe wants to modify the
+content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
+distribution directory, it should explicitly to make it writable first:
+
+ at example
+EXTRA_DIST = README doc
dist-hook:
- rm -rf `find $(distdir)/doc -type d -name .svn`
+ chmod u+w $(distdir)/README $(distdir)/doc
+ echo "Distribution date: `date`" >> README
+ rm -f $(distdir)/doc/HACKING
@end example
@vindex distdir
@@ -8592,20 +8518,32 @@ dist} was run, not to any sub-packages involved.
@section Checking the Distribution
@cindex @samp{make distcheck}
- at cindex @samp{make distcleancheck}
- at vindex distcleancheck_listfiles
- at cindex @samp{make distuninstallcheck}
- at vindex distuninstallcheck_listfiles
-
@trindex distcheck
-Automake also generates a @code{distcheck} rule that can be of help to
-ensure that a given distribution will actually work. @code{distcheck}
-makes a distribution, then tries to do a @code{VPATH} build
-(@pxref{VPATH Builds}), run the test suite, and finally make another
-tarball to ensure the distribution is self-contained.
+Automake also generates a @code{distcheck} rule that can be of help
+to ensure that a given distribution will actually work. Simplifying
+a bit, we can say this rule first makes a distribution, and then,
+ at emph{operating from it}, takes the following steps:
+ at itemize
+ at item
+tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
+ at code{srcdir} and all its content made @emph{read-only};
+ at item
+runs the test suite (with @command{make check}) on this fresh build;
+ at item
+installs the package in a temporary directory (with @command{make
+install}), and tries runs the test suite on the resulting installation
+(with @command{make installcheck});
+ at item
+checks that the package can be correctly uninstalled (by @command{make
+uninstall}) and cleaned (by @code{make distclean});
+ at item
+finally, makes another tarball to ensure the distribution is
+self-contained.
+ at end itemize
@vindex AM_DISTCHECK_CONFIGURE_FLAGS
@vindex DISTCHECK_CONFIGURE_FLAGS
+ at subheading DISTCHECK_CONFIGURE_FLAGS
Building the package involves running @samp{./configure}. If you need
to supply additional flags to @command{configure}, define them in the
@code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
@@ -8629,6 +8567,7 @@ installcheck} was wrongly assuming it could blindly test "@command{m4}",
rather than the just-installed "@command{gm4}".
@trindex distcheck-hook
+ at subheading distcheck-hook
If the @code{distcheck-hook} rule is defined in your top-level
@file{Makefile.am}, then it will be invoked by @code{distcheck} after
the new distribution has been unpacked, but before the unpacked copy
@@ -8641,9 +8580,12 @@ are not honored in a subpackage @file{Makefile.am}, but the flags from
@code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
are passed down to the @command{configure} script of the subpackage.
+ at cindex @samp{make distcleancheck}
@trindex distcleancheck
@vindex DISTCLEANFILES
@vindex distcleancheck_listfiles
+
+ at subheading distcleancheck
Speaking of potential distribution errors, @code{distcheck} also
ensures that the @code{distclean} rule actually removes all built
files. This is done by running @samp{make distcleancheck} at the end of
@@ -8669,7 +8611,7 @@ If you want @code{distcleancheck} to ignore built files that have not
been cleaned because they are also part of the distribution, add the
following definition instead:
- at c Keep in sync with distcleancheck.test.
+ at c Keep in sync with distcleancheck.sh
@example
distcleancheck_listfiles = \
find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
@@ -8681,9 +8623,14 @@ your Makefiles cause some distributed files to be rebuilt when the user
build the package. (Think about the user missing the tool required to
build the file; or if the required tool is built by your package,
consider the cross-compilation case where it can't be run.) There is
-an entry in the FAQ about this (@pxref{distcleancheck}), make sure you
-read it before playing with @code{distcleancheck_listfiles}.
+an entry in the FAQ about this (@pxref{Errors with distclean}), make
+sure you read it before playing with @code{distcleancheck_listfiles}.
+ at cindex @samp{make distuninstallcheck}
+ at trindex distuninstallcheck
+ at vindex distuninstallcheck_listfiles
+
+ at subheading distuninstallcheck
@code{distcheck} also checks that the @code{uninstall} rule works
properly, both for ordinary and @code{DESTDIR} builds. It does this
by invoking @samp{make uninstall}, and then it checks the install tree
@@ -8711,60 +8658,57 @@ Automake generates rules to provide archives of the project for
distributions in various formats. Their targets are:
@table @asis
+ at item @code{dist-gzip}
+Generate a @samp{gzip} tar archive of the distribution. This is the
+only format enabled by default.
+ at trindex dist-gzip
+
@vindex BZIP2
@item @code{dist-bzip2}
-Generate a bzip2 tar archive of the distribution. bzip2 archives are
-frequently smaller than gzipped archives.
-By default, this rule makes @samp{bzip2} use a compression option of
- at option{-9}. To make it use a different one, set the @env{BZIP2}
-environment variable. For example, @samp{make dist-bzip2 BZIP2=-7}.
+Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
+are frequently smaller than gzipped archives.
+By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
+To make it use a different one, set the @env{BZIP2} environment variable.
+For example, @samp{make dist-bzip2 BZIP2=-7}.
@trindex dist-bzip2
- at item @code{dist-gzip}
-Generate a gzip tar archive of the distribution.
- at trindex dist-gzip
-
@item @code{dist-lzip}
-Generate a @samp{lzip} tar archive of the distribution. @command{lzip}
+Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
archives are frequently smaller than @command{bzip2}-compressed archives.
@trindex dist-lzip
- at item @code{dist-lzma}
-Generate an @samp{lzma} tar archive of the distribution.
-The @samp{lzma} format is obsolete, you should use the @samp{xz} format
-instead. @emph{Support for @samp{lzma}-compressed archives will be
-removed in the next major Automake release.}
- at trindex dist-lzma
-
- at item @code{dist-shar}
-Generate a shar archive of the distribution.
- at trindex dist-shar
-
@vindex XZ_OPT
@item @code{dist-xz}
Generate an @samp{xz} tar archive of the distribution. @command{xz}
archives are frequently smaller than @command{bzip2}-compressed archives.
-The @samp{xz} format displaces the obsolete @samp{lzma} format.
By default, this rule makes @samp{xz} use a compression option of
@option{-e}. To make it use a different one, set the @env{XZ_OPT}
environment variable. For example, run this command to use the
default compression ratio, but with a progress indicator:
- at samp{make dist-xz XZ_OPT=-7e}.
+ at samp{make dist-xz XZ_OPT=-ve}.
@trindex dist-xz
@item @code{dist-zip}
-Generate a zip archive of the distribution.
+Generate a @samp{zip} archive of the distribution.
@trindex dist-zip
@item @code{dist-tarZ}
-Generate a compressed tar archive of
-the distribution.
+Generate a tar archive of the distribution, compressed with the
+historical (obsolescent) program @command{compress}. Use of this
+option is discouraged.
@trindex dist-tarZ
+
+ at item @code{dist-shar}
+Generate a @samp{shar} archive of the distribution. This format archive
+is obsolescent, and use of this option is discouraged.
+ at trindex dist-shar
+
@end table
-The rule @code{dist} (and its historical synonym @code{dist-all}) will
-create archives in all the enabled formats, @ref{Options}. By
-default, only the @code{dist-gzip} target is hooked to @code{dist}.
+The rule @code{dist} (and its historical synonym @code{dist-all})
+will create archives in all the enabled formats (@pxref{List of
+Automake options} for how to change this list). By default, only
+the @code{dist-gzip} target is hooked to @code{dist}.
@node Tests
@@ -8774,92 +8718,263 @@ default, only the @code{dist-gzip} target is hooked to @code{dist}.
@cindex @code{make check}
@trindex check
-Automake supports three forms of test suites, the first two of which
-are very similar.
+Automake can generate code to handle two kinds of test suites. One is
+based on integration with the @command{dejagnu} framework. The other
+(and most used) form is based on the use of generic test scripts, and
+its activation is triggered by the definition of the special @code{TESTS}
+variable. This second form allows for various degrees of sophistication
+and customization; in particular, it allows for concurrent execution
+of test scripts, use of established test protocols such as TAP, and
+definition of custom test drivers and test runners.
+
+ at noindent
+In either case, the testsuite is invoked via @samp{make check}.
@menu
-* Simple Tests:: Listing programs and scripts in @code{TESTS}
-* Simple Tests using parallel-tests:: More powerful test driver
-* DejaGnu Tests:: Interfacing with the external testing framework
+* Generalities about Testing:: Concepts and terminology about testing
+* Simple Tests:: Listing test scripts in @code{TESTS}
+* Custom Test Drivers:: Writing and using custom test drivers
+* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
+* DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
* Install Tests:: Running tests on installed packages
@end menu
+ at node Generalities about Testing
+ at section Generalities about Testing
+
+The purpose of testing is to determine whether a program or system behaves
+as expected (e.g., known inputs produce the expected outputs, error
+conditions are correctly handled or reported, and older bugs do not
+resurface).
+
+ at cindex test case
+The minimal unit of testing is usually called @emph{test case}, or simply
+ at emph{test}. How a test case is defined or delimited, and even what
+exactly @emph{constitutes} a test case, depends heavily on the testing
+paradigm and/or framework in use, so we won't attempt any more precise
+definition. The set of the test cases for a given program or system
+constitutes its @emph{testsuite}.
+
+ at cindex test harness
+ at cindex testsuite harness
+A @emph{test harness} (also @emph{testsuite harness}) is a program or
+software component that executes all (or part of) the defined test cases,
+analyzes their outcomes, and report or register these outcomes
+appropriately. Again, the details of how this is accomplished (and how
+the developer and user can influence it or interface with it) varies
+wildly, and we'll attempt no precise definition.
+
+ at cindex test pass
+ at cindex test failure
+A test is said to @emph{pass} when it can determine that the condition or
+behaviour it means to verify holds, and is said to @emph{fail} when it can
+determine that such condition of behaviour does @emph{not} hold.
+
+ at cindex test skip
+Sometimes, tests can rely on non-portable tools or prerequisites, or
+simply make no sense on a given system (for example, a test checking a
+Windows-specific feature makes no sense on a GNU/Linux system). In this
+case, accordingly to the definition above, the tests can neither be
+considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
+they are not run, or their result is anyway ignored for what concerns
+the count of failures an successes. Skips are usually explicitly
+reported though, so that the user will be aware that not all of the
+testsuite has really run.
+
+ at cindex xfail
+ at cindex expected failure
+ at cindex expected test failure
+ at cindex xpass
+ at cindex unexpected pass
+ at cindex unexpected test pass
+It's not uncommon, especially during early development stages, that some
+tests fail for known reasons, and that the developer doesn't want to
+tackle these failures immediately (this is especially true when the
+failing tests deal with corner cases). In this situation, the better
+policy is to declare that each of those failures is an @emph{expected
+failure} (or @emph{xfail}). In case a test that is expected to fail ends
+up passing instead, many testing environments will flag the result as a
+special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
+
+ at cindex hard error
+ at cindex Distinction between errors and failures in testsuites
+Many testing environments and frameworks distinguish between test failures
+and hard errors. As we've seen, a test failure happens when some invariant
+or expected behaviour of the software under test is not met. An @emph{hard
+error} happens when e.g., the set-up of a test case scenario fails, or when
+some other unexpected or highly undesirable condition is encountered (for
+example, the program under test experiences a segmentation fault).
+
+ at emph{TODO}: Links to other test harnesses (esp. those sharing our
+terminology)?
+
@node Simple Tests
@section Simple Tests
-If the variable @code{TESTS} is defined, its value is taken to be a
-list of programs or scripts to run in order to do the testing.
-Programs needing data files should look for them in @code{srcdir}
-(which is both an environment variable and a make variable) so they
-work when building in a separate directory (@pxref{Build Directories,
-, Build Directories , autoconf, The Autoconf Manual}), and in
-particular for the @code{distcheck} rule (@pxref{Checking the
-Distribution}).
-
-For each of the @code{TESTS}, the result of execution is printed along
-with the test name, where @code{PASS} denotes a successful test,
- at code{FAIL} denotes a failed test, @code{XFAIL} an expected failure,
- at code{XPASS} an unexpected pass for a test that is supposed to fail,
-and @code{SKIP} denotes a skipped test.
+ at menu
+* Scripts-based Testsuites:: Automake-specific concepts and terminology
+* Serial Test Harness:: Older (and discouraged) serial test harness
+* Parallel Test Harness:: Generic concurrent test harness
+ at end menu
+
+ at node Scripts-based Testsuites
+ at subsection Scripts-based Testsuites
+
+If the special variable @code{TESTS} is defined, its value is taken to be
+a list of programs or scripts to run in order to do the testing. Under
+the appropriate circumstances, it's possible for @code{TESTS} to list
+also data files to be passed to one or more test scripts defined by
+different means (the so-called ``log compilers'', @pxref{Parallel Test
+Harness}).
+
+Test scripts can be executed serially or concurrently. Automake supports
+both these kinds of test execution, with the parallel test harness being
+the default. The concurrent test harness relies on the concurrence
+capabilities (if any) offered by the underlying @command{make}
+implementation, and can thus only be as good as those are.
+
+By default, only the exit statuses of the test scripts are considered when
+determining the testsuite outcome. But Automake allows also the use of
+more complex test protocols, either standard (@pxref{Using the TAP test
+protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
+enable such protocols when the serial harness is used, though.
+In the rest of this section we are going to concentrate mostly on
+protocol-less tests, since we cover test protocols in a later section
+(again, @pxref{Custom Test Drivers}).
@cindex Exit status 77, special interpretation
+ at cindex Exit status 99, special interpretation
+When no test protocol is in use, an exit status of 0 from a test script will
+denote a success, an exit status of 77 a skipped test, an exit status of 99
+an hard error, and any other exit status will denote a failure.
+
+ at cindex Tests, expected failure
+ at cindex Expected test failure
+ at vindex XFAIL_TESTS
+ at vindex DISABLE_HARD_ERRORS
+ at cindex Disabling hard errors
+You may define the variable @code{XFAIL_TESTS} to a list of tests
+(usually a subset of @code{TESTS}) that are expected to fail; this will
+effectively reverse the result of those tests (with the provision that
+skips and hard errors remain untouched). You may also instruct the
+testsuite harness to treat hard errors like simple failures, by defining
+the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
+
+Note however that, for tests based on more complex test protocols,
+the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
+might change, or they might even have no effect at all (for example,
+ at c Keep this in sync with tap-no-disable-hard-errors.sh
+in tests using TAP, there is not way to disable hard errors, and the
+ at code{DISABLE_HARD_ERRORS} variable has no effect on them).
+
+ at anchor{Testsuite progress on console}
+ at cindex Testsuite progress on console
+The result of each test case run by the scripts in @code{TESTS} will be
+printed on standard output, along with the test name. For test protocols
+that allow more test cases per test script (such as TAP), a number,
+identifier and/or brief description specific for the single test case is
+expected to be printed in addition to the name of the test script. The
+possible results (whose meanings should be clear from the previous
+ at ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
+ at code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
+example of output from an hypothetical testsuite that uses both plain
+and TAP tests:
+ at c Keep in sync with tap-doc.sh
+ at example
+PASS: foo.sh
+PASS: zardoz.tap 1 - Daemon started
+PASS: zardoz.tap 2 - Daemon responding
+SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
+PASS: zardoz.tap 4 - Daemon stopped
+SKIP: bar.sh
+PASS: mu.tap 1
+XFAIL: mu.tap 2 # TODO frobnication not yet implemented
+ at end example
-The number of failures will be printed at the end of the run. If a
-given test program exits with a status of 77, then its result is ignored
-in the final count. This feature allows non-portable tests to be
-ignored in environments where they don't make sense.
+ at noindent
+A testsuite summary (expected to report at least the number of run,
+skipped and failed tests) will be printed at the end of the testsuite
+run.
+ at anchor{Simple tests and color-tests}
@vindex AM_COLOR_TESTS
-If the Automake option @code{color-tests} is used (@pxref{Options})
-and standard output is connected to a capable terminal, then the test
-results and the summary are colored appropriately. The user can disable
-colored output by setting the @command{make} variable
- at samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
-terminal with @samp{AM_COLOR_TESTS=always}.
-
-Note that the semantics of some @command{make} implementations when used
-in parallel mode (@pxref{Parallel make,,, autoconf, The Autoconf Manual})
-can cause the automatic detection of a connection to a capable terminal
-to fail. In that case, you can still resort to the use of
- at samp{AM_COLOR_TESTS=always}.
+ at cindex Colorized testsuite output
+If the standard output is connected to a capable terminal, then the test
+results and the summary are colored appropriately. The developer and the
+user can disable colored output by setting the @command{make} variable
+ at samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
+even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
+It's also worth noting that some @command{make} implementations,
+when used in parallel mode, have slightly different semantics
+(@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
+break the automatic detection of a connection to a capable terminal.
+If this is the case, the user will have to resort to the use of
+ at samp{AM_COLOR_TESTS=always} in order to have the testsuite output
+colorized.
+
+Test programs that need data files should look for them in @code{srcdir}
+(which is both a make variable and an environment variable made available
+to the tests), so that they work when building in a separate directory
+(@pxref{Build Directories, , Build Directories , autoconf,
+The Autoconf Manual}), and in particular for the @code{distcheck} rule
+(@pxref{Checking the Distribution}).
@vindex TESTS
@vindex TESTS_ENVIRONMENT
-The variable @code{TESTS_ENVIRONMENT} can be used to set environment
-variables for the test run; the environment variable @env{srcdir} is
-set in the rule. If all your test programs are scripts, you can also
-set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
- at samp{$(SHELL) -x} can be useful for debugging the tests), or any other
-interpreter. For instance, the following setup may be used to run tests
-with Perl:
-
- at c Keep in sync with tests-environment-backcompat.test.
- at example
-TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
-TESTS = foo.pl bar.pl baz.pl
+ at vindex AM_TESTS_ENVIRONMENT
+The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
+be used to run initialization code and set environment variables for the
+test scripts. The former variable is developer-reserved, and can be
+defined in the @file{Makefile.am}, while the latter is reserved for the
+user, which can employ it to extend or override the settings in the
+former; for this to work portably, however, the contents of a non-empty
+ at code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
+
+ at vindex AM_TESTS_FD_REDIRECT
+The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
+descriptor redirections for the test scripts. One might think that
+ at code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
+has shown that doing so portably is practically impossible. The main
+hurdle is constituted by Korn shells, which usually set the close-on-exec
+flag on file descriptors opened with the @command{exec} builtin, thus
+rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
+ineffectual. This issue also affects some Bourne shells, such as the
+HP-UX's @command{/bin/sh},
+ at c FIXME: should we offer a link to the relevant discussions on the
+ at c bug-autoconf list?
+
+ at c Keep in sync with tests-environment-backcompat.sh
+ at example
+AM_TESTS_ENVIRONMENT = \
+## Some environment initializations are kept in a separate shell
+## file 'tests-env.sh', which can make it easier to also run tests
+## from the command line.
+ . $(srcdir)/tests-env.sh; \
+## On Solaris, prefer more POSIX-compliant versions of the standard
+## tools by default.
+ if test -d /usr/xpg4/bin; then \
+ PATH=/usr/xpg4/bin:$$PATH; export PATH; \
+ fi;
+ at c $$ restore font-lock
+## With this, the test scripts will be able to print diagnostic
+## messages to the original standard error stream, even if the test
+## driver redirects the stderr of the test scripts to a log file
+## before executing them.
+AM_TESTS_FD_REDIRECT = 9>&2
@end example
-Note that the @option{parallel-tests} driver provides a more elegant
-way to achieve the same effect, freeing the @code{TESTS_ENVIRONMENT}
-variable for the user to override (@pxref{Simple Tests using
-parallel-tests}).
-
-
- at cindex Tests, expected failure
- at cindex Expected test failure
-
- at vindex XFAIL_TESTS
-You may define the variable @code{XFAIL_TESTS} to a list of tests
-(usually a subset of @code{TESTS}) that are expected to fail. This will
-reverse the result of those tests.
+ at noindent
+Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
+implementation reasons, @emph{not} supported by the serial harness
+(@pxref{Serial Test Harness}).
Automake ensures that each file listed in @code{TESTS} is built before
-any tests are run; you can list both source and derived programs (or
-scripts) in @code{TESTS}; the generated rule will look both in
- at code{srcdir} and @file{.}. For instance, you might want to run a C
-program as a test. To do this you would list its name in @code{TESTS}
-and also in @code{check_PROGRAMS}, and then specify it as you would
-any other program.
+it is run; you can list both source and derived programs (or scripts)
+in @code{TESTS}; the generated rule will look both in @code{srcdir} and
+ at file{.}. For instance, you might want to run a C program as a test.
+To do this you would list its name in @code{TESTS} and also in
+ at code{check_PROGRAMS}, and then specify it as you would any other
+program.
Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
@code{check_LTLIBRARIES}...) are only built during @code{make check},
@@ -8870,51 +8985,116 @@ that @code{check_PROGRAMS} are @emph{not} automatically added to
by the tests, not the tests themselves. Of course you can set
@code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
+ at node Serial Test Harness
+ at subsection Older (and discouraged) serial test harness
+ at cindex @option{serial-tests}, Using
+
+First, note that today the use of this harness is strongly discouraged in
+favour of the parallel test harness (@pxref{Parallel Test Harness}).
+Still, there are @emph{few} situations when the advantages offered by
+the parallel harness are irrelevant, and when test concurrency can
+even cause tricky problems. In those cases, it might make sense to
+still use the serial harness, for simplicity and reliability (we still
+suggest trying to give the parallel harness a shot though).
+
+The serial test harness is enabled by the Automake option
+ at option{serial-tests}. It operates by simply running the tests serially,
+one at the time, without any I/O redirection. It's up to the user to
+implement logging of tests' output, if that's requited or desired.
+ at c TODO: give an example of how this can be done.
+
+For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
+variable is @emph{not} supported by this harness (it will be silently
+ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
+considered a developer-reserved variable. This is done so that, when
+using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
+invocation of an interpreter through which the tests are to be run.
+For instance, the following setup may be used to run tests with Perl:
+
+ at example
+TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
+TESTS = foo.pl bar.pl baz.pl
+ at end example
- at node Simple Tests using parallel-tests
- at section Simple Tests using @samp{parallel-tests}
- at cindex @option{parallel-tests}, Using
+ at noindent
+It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
+here would be @emph{invalid} with the parallel harness. That harness
+provides a more elegant way to achieve the same effect, with the further
+benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
+(@pxref{Parallel Test Harness}).
+
+Another, less serious limit of the serial harness is that it doesn't
+really distinguish between simple failures and hard errors; this is
+due to historical reasons only, and might be fixed in future Automake
+versions.
-The option @option{parallel-tests} (@pxref{Options}) enables a test suite
-driver that is mostly compatible to the simple test driver described in
-the previous section, but provides a few more features and slightly
-different semantics. It features concurrent execution of tests with
- at code{make -j} and automatic collection of the test scripts output and
-summary thereof in @file{.log} files, and allows to specify inter-test
-dependencies, lazy reruns of tests that have not completed in a prior
-run, and hard errors for exceptional failures. Similar to the simple
-test driver, @code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS},
- at code{XFAIL_TESTS}, and the @code{check_*} variables are honored,
-and the environment variable @env{srcdir} is set during test execution.
+ at node Parallel Test Harness
+ at subsection Parallel Test Harness
-This test driver is still experimental and may undergo changes in order
-to satisfy additional portability requirements.
+By default, Automake generated a parallel (concurrent) test harness. It
+features automatic collection of the test scripts output in @file{.log}
+files, concurrent execution of tests with @code{make -j}, specification
+of inter-test dependencies, lazy reruns of tests that have not completed
+in a prior run, and hard errors for exceptional failures.
+ at anchor{Basics of test metadata}
@vindex TEST_SUITE_LOG
@vindex TESTS
-The driver operates by defining a set of @command{make} rules to create
-a summary log file, @code{TEST_SUITE_LOG}, which defaults to
- at file{test-suite.log} and requires a @file{.log} suffix. This file
-depends upon log files created for each single test program listed in
- at code{TESTS}, which in turn contain all output produced by the
-corresponding tests.
+ at cindex @file{.log} files
+ at cindex @file{.trs} files
+ at cindex test metadata
+The parallel test harness operates by defining a set of @command{make}
+rules that run the test scripts listed in @code{TESTS}, and, for each
+such script, save its output in a corresponding @file{.log} file and
+its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
+in a corresponding @file{.trs} (as in @b{T}est @b{R}e at b{S}ults) file.
+ at c We choose the '.trs' extension also because, at the time of writing,
+ at c it isn't already used for other significant purposes; see e.g.:
+ at c - http://filext.com/file-extension/trs
+ at c - http://www.file-extensions.org/search/?searchstring=trs
+The @file{.log} file will contain all the output emitted by the test on
+its standard output and its standard error. The @file{.trs} file will
+contain, among the other things, the results of the test cases run by
+the script.
+
+The parallel test harness will also create a summary log file,
+ at code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
+a @file{.log} suffix. This file depends upon all the @file{.log} and
+ at file{.trs} files created for the test scripts listed in @code{TESTS}.
+
+ at vindex VERBOSE
+As with the serial harness above, by default one status line is printed
+per completed test, and a short summary after the suite has completed.
+However, standard output and standard error of the test are redirected
+to a per-test log file, so that parallel execution does not produce
+intermingled output. The output from failed tests is collected in the
+ at file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
+file is output after the summary.
+ at c FIXME: we should be clearer about what we mean exactly here ...
+For best results, the tests should be verbose by default now.
@vindex TEST_EXTENSIONS
@vindex TEST_LOGS
-Each log file is created when the corresponding test has completed.
-The set of log files is listed in the read-only variable
- at code{TEST_LOGS}, and defaults to @code{TESTS}, with the executable
-extension if any (@pxref{EXEEXT}), as well as any suffix listed in
- at code{TEST_EXTENSIONS} removed, and @file{.log} appended. Results
-are undefined if a test file name ends in several concatenated suffixes.
- at code{TEST_EXTENSIONS} defaults to @file{.test}; it can be overridden by
-the user, in which case any extension listed in it must be constituted
-by a dot, followed by a non-digit alphabetic character, followed by any
-number of alphabetic characters.
- at c Keep in sync with test-extensions.test.
+Each couple of @file{.log} and @file{.trs} files is created when the
+corresponding test has completed. The set of log files is listed in
+the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
+with the executable extension if any (@pxref{EXEEXT}), as well as any
+suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
+Results are undefined if a test file name ends in several concatenated
+suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
+overridden by the user, in which case any extension listed in it must be
+constituted by a dot, followed by a non-digit alphabetic character,
+followed by any number of alphabetic characters.
+ at c Keep in sync with test-extensions.sh
For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
+ at cindex Configure substitutions in @code{TESTS}
+It is important to note that, due to current limitations (unlikely to be
+lifted), configure substitutions in the definition of @code{TESTS} can
+only work if they will expand to a list of tests that have a suffix listed
+in @code{TEST_EXTENSIONS}.
+
@vindex _LOG_COMPILE
@vindex _LOG_COMPILER
@vindex _LOG_FLAGS
@@ -8927,15 +9107,15 @@ while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
@vindex AM_ at var{ext}_LOG_FLAGS
@vindex AM_LOG_FLAGS
For tests that match an extension @code{. at var{ext}} listed in
- at code{TEST_EXTENSIONS}, you can provide a test driver using the variable
- at code{@var{ext}_LOG_COMPILER} (note the upper-case extension) and pass
-options in @code{AM_ at var{ext}_LOG_FLAGS} and allow the user to pass
-options in @code{@var{ext}_LOG_FLAGS}. It will cause all tests with
-this extension to be called with this driver. For all tests without a
-registered extension, the variables @code{LOG_COMPILER},
+ at code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
+the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
+extension) and pass options in @code{AM_ at var{ext}_LOG_FLAGS} and allow
+the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
+all tests with this extension to be called with this runner. For all
+tests without a registered extension, the variables @code{LOG_COMPILER},
@code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
- at c Keep in sync with parallel-tests-log-compiler-example.test.
+ at c Keep in sync with parallel-tests-log-compiler-example.sh
@example
TESTS = foo.pl bar.py baz
TEST_EXTENSIONS = .pl .py
@@ -8950,50 +9130,36 @@ AM_LOG_FLAGS = -d
@noindent
will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
and @samp{./wrapper-script -d baz} to produce @file{foo.log},
- at file{bar.log}, and @file{baz.log}, respectively. The
- at samp{TESTS_ENVIRONMENT} variable is still expanded before the driver,
-but should be reserved for the user.
+ at file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
+ at file{bar.trs} and @file{baz.trs} files will be automatically produced
+as a side-effect.
- at vindex VERBOSE
-As with the simple driver above, by default one status line is printed
-per completed test, and a short summary after the suite has completed.
-However, standard output and standard error of the test are redirected
-to a per-test log file, so that parallel execution does not produce
-intermingled output. The output from failed tests is collected in the
- at file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
-file is output after the summary. For best results, the tests should be
-verbose by default now.
+It's important to note that, differently from what we've seen for the
+serial test harness (@pxref{Parallel Test Harness}), the
+ at code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
+ at emph{cannot} be use to define a custom test runner; the
+ at code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
+counterparts) should be used instead:
- at trindex check-html
- at vindex RST2HTML
- at vindex TEST_SUITE_HTML
-Previous versions of automake used to provide a @code{check-html} target
-to convert the log files to HTML. This feature is now deprecated, and
- at emph{will be removed} in the next major Automake release, so don't rely
-on it anymore.
+ at example
+## This is WRONG!
+AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
+ at end example
- at vindex DISABLE_HARD_ERRORS
- at cindex Exit status 99, special interpretation
- at cindex hard error
-Even in the presence of expected failures (see @code{XFAIL_TESTS}), there
-may be conditions under which a test outcome needs attention. For
-example, with test-driven development, you may write tests for features
-that you have not implemented yet, and thus mark these tests as expected
-to fail. However, you may still be interested in exceptional conditions,
-for example, tests that fail due to a segmentation violation or another
-error that is independent of the feature awaiting implementation.
-Tests can exit with an exit status of 99 to signal such a @emph{hard
-error}. Unless the variable @code{DISABLE_HARD_ERRORS} is set to a
-nonempty value, such tests will be counted as failed.
-
-By default, the test suite driver will run all tests, but there are
+ at example
+## Do this instead.
+AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
+LOG_COMPILER = $(PERL)
+AM_LOG_FLAGS = -Mstrict -w
+ at end example
+
+By default, the test suite harness will run all tests, but there are
several ways to limit the set of tests that are run:
@itemize @bullet
@item
-You can set the @code{TESTS} variable, similarly to how you can with
-the simple test driver from the previous section. For example, you can
-use a command like this to run only a subset of the tests:
+You can set the @code{TESTS} variable. For example, you can use a
+command like this to run only a subset of the tests:
@example
env TESTS="foo.test bar.test" make -e check
@@ -9006,7 +9172,7 @@ whose testsuite takes long time to execute. Luckily, this problem can
easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
for example,
- at c Keep in sync with parallel-tests-log-override-2.test.
+ at c Keep in sync with parallel-tests-log-override-2.sh
@example
env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
@end example
@@ -9030,14 +9196,15 @@ here too.
@item
@vindex RECHECK_LOGS
@cindex lazy test execution
-By default, the test driver removes all old per-test log files before it
-starts running tests to regenerate them. The variable
- at code{RECHECK_LOGS} contains the set of log files which are removed.
- at code{RECHECK_LOGS} defaults to @code{TEST_LOGS}, which means all tests
-need to be rechecked. By overriding this variable, you can choose which
-tests need to be reconsidered. For example, you can lazily rerun only
-those tests which are outdated, i.e., older than their prerequisite test
-files, by setting this variable to the empty value:
+By default, the test harness removes all old per-test @file{.log} and
+ at file{.trs} files before it starts running tests to regenerate them. The
+variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
+implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
+defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
+By overriding this variable, you can choose which tests need to be
+reconsidered. For example, you can lazily rerun only those tests which
+are outdated, i.e., older than their prerequisite test files, by setting
+this variable to the empty value:
@example
env RECHECK_LOGS= make -e check
@@ -9048,13 +9215,14 @@ env RECHECK_LOGS= make -e check
You can ensure that all tests are rerun which have failed or passed
unexpectedly, by running @code{make recheck} in the test directory.
This convenience target will set @code{RECHECK_LOGS} appropriately
-before invoking the main test driver.
+before invoking the main test harness.
@end itemize
+ at noindent
In order to guarantee an ordering between tests even with @code{make
--j at var{N}}, dependencies between the corresponding log files may be
-specified through usual @command{make} dependencies. For example, the
-following snippet lets the test named @file{foo-execute.test} depend
+-j at var{N}}, dependencies between the corresponding @file{.log} files
+may be specified through usual @command{make} dependencies. For example,
+the following snippet lets the test named @file{foo-execute.test} depend
upon completion of the test @file{foo-compile.test}:
@example
@@ -9074,6 +9242,7 @@ parallel @command{make -j at var{N}}, so be sure they are prepared for
concurrent execution.
@cindex Unit tests
+ at c Keep in sync with 'parallel-tests-extra-programs.sh'.
The combination of lazy test execution and correct dependencies between
tests and their sources may be exploited for efficient unit testing
during development. To further speed up the edit-compile-test cycle, it
@@ -9101,88 +9270,631 @@ semantics of FreeBSD and OpenBSD @command{make} conflict with this).
In case of doubt you may want to require to use GNU @command{make},
or work around the issue with inference rules to generate the tests.
+ at node Custom Test Drivers
+ at section Custom Test Drivers
- at node DejaGnu Tests
- at section DejaGnu Tests
+ at menu
+* Overview of Custom Test Drivers Support::
+* Declaring Custom Test Drivers::
+* API for Custom Test Drivers::
+ at end menu
-If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
- at code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
-assumed. The variable @code{DEJATOOL} is a list of names that are
-passed, one at a time, as the @option{--tool} argument to
- at command{runtest} invocations; it defaults to the name of the package.
+ at node Overview of Custom Test Drivers Support
+ at subsection Overview of Custom Test Drivers Support
+
+Starting from Automake version 1.12, the parallel test harness allows
+the package authors to use third-party custom test drivers, in case the
+default ones are inadequate for their purposes, or do not support their
+testing protocol of choice.
+
+A custom test driver is expected to properly run the test programs passed
+to it (including the command-line arguments passed to those programs, if
+any), to analyze their execution and outcome, to create the @file{.log}
+and @file{.trs} files associated to these test runs, and to display the test
+results on the console. It is responsibility of the author of the test
+driver to ensure that it implements all the above steps meaningfully and
+correctly; Automake isn't and can't be of any help here. On the other
+hand, the Automake-provided code for testsuite summary generation offers
+support for test drivers allowing several test results per test script,
+if they take care to register such results properly (@pxref{Log files
+generation and test results recording}).
+
+The exact details of how test scripts' results are to be determined and
+analyzed is left to the individual drivers. Some drivers might only
+consider the test script exit status (this is done for example by the
+default test driver used by the parallel test harness, described
+in the previous section). Other drivers might implement more complex and
+advanced test protocols, which might require them to parse and interpreter
+the output emitted by the test script they're running (examples of such
+protocols are TAP and SubUnit).
+
+It's very important to note that, even when using custom test drivers,
+most of the infrastructure described in the previous section about the
+parallel harness remains in place; this includes:
-The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
- at option{--srcdir} flags that are passed to dejagnu by default; this can be
-overridden if necessary.
- at vindex RUNTESTDEFAULTFLAGS
+ at itemize
+ at item
+list of test scripts defined in @code{TESTS}, and overridable at
+runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
+ at item
+concurrency through the use of @command{make}'s option @option{-j};
+ at item
+per-test @file{.log} and @file{.trs} files, and generation of a summary
+ at file{.log} file from them;
+ at item
+ at code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
+of tests;
+ at item
+inter-test dependencies;
+ at item
+support for @code{check_*} variables (@code{check_PROGRAMS},
+ at code{check_LIBRARIES}, ...);
+ at item
+use of @code{VERBOSE} environment variable to get verbose output on
+testsuite failures;
+ at item
+definition and honoring of @code{TESTS_ENVIRONMENT},
+ at code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
+variables;
+ at item
+definition of generic and extension-specific @code{LOG_COMPILER} and
+ at code{LOG_FLAGS} variables.
+ at end itemize
-The variables @code{EXPECT} and @code{RUNTEST} can
-also be overridden to provide project-specific values. For instance,
-you will need to do this if you are testing a compiler toolchain,
-because the default values do not take into account host and target
-names.
- at opindex dejagnu
- at vindex DEJATOOL
- at vindex EXPECT
- at vindex RUNTEST
+ at noindent
+On the other hand, the exact semantics of how (and if) testsuite output
+colorization, @code{XFAIL_TESTS}, and hard errors are supported and
+handled is left to the individual test drivers.
+
+ at c TODO: We should really add a working example in the doc/ directory,
+ at c TODO: and reference if from here.
+
+ at node Declaring Custom Test Drivers
+ at subsection Declaring Custom Test Drivers
+
+ at vindex _LOG_DRIVER
+ at vindex _LOG_DRIVER_FLAGS
+ at vindex LOG_DRIVER
+ at vindex LOG_DRIVER_FLAGS
+ at vindex @var{ext}_LOG_DRIVER
+ at vindex @var{ext}_LOG_DRIVER_FLAGS
+ at vindex AM_ at var{ext}_LOG_DRIVER_FLAGS
+ at vindex AM_LOG_DRIVER_FLAGS
+Custom testsuite drivers are declared by defining the make variables
+ at code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
+be declared in @code{TEST_EXTENSIONS}). They must be defined to
+programs or scripts that will be used to drive the execution, logging,
+and outcome report of the tests with corresponding extensions (or of
+those with no registered extension in the case of @code{LOG_DRIVER}).
+Clearly, multiple distinct test drivers can be declared in the same
+ at file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
+are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
+two sets of variables can, and often do, usefully and legitimately
+coexist.
+
+ at c TODO: We should really be able to point to a clarifying example here!
+
+The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
+user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
+flags that will be passed to each invocation of @code{LOG_DRIVER},
+with the user-defined flags obviously taking precedence over the
+developer-reserved ones. Similarly, for each extension @var{ext}
+declared in @code{TEST_EXTENSIONS}, flags listed in
+ at code{AM_ at var{ext}_LOG_DRIVER_FLAGS} and
+ at code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
+invocations of @code{@var{ext}_LOG_DRIVER}.
+
+ at node API for Custom Test Drivers
+ at subsection API for Custom Test Drivers
+
+Note that @emph{the APIs described here are still highly experimental},
+and will very likely undergo tightenings and likely also extensive changes
+in the future, to accommodate for new features or to satisfy additional
+portability requirements.
+
+The main characteristic of these APIs is that they are designed to share
+as much infrastructure, semantics, and implementation details as possible
+with the parallel test harness and its default driver.
-The contents of the variable @code{RUNTESTFLAGS} are passed to the
- at code{runtest} invocation. This is considered a ``user variable''
-(@pxref{User Variables}). If you need to set @command{runtest} flags in
- at file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
- at vindex RUNTESTFLAGS
- at vindex AM_RUNTESTFLAGS
+ at menu
+* Command-line arguments for test drivers::
+* Log files generation and test results recording::
+* Testsuite progress output::
+ at end menu
- at cindex @file{site.exp}
-Automake will generate rules to create a local @file{site.exp} file,
-defining various variables detected by @command{configure}. This file
-is automatically read by DejaGnu. It is OK for the user of a package
-to edit this file in order to tune the test suite. However this is
-not the place where the test suite author should define new variables:
-this should be done elsewhere in the real test suite code.
-Especially, @file{site.exp} should not be distributed.
+ at node Command-line arguments for test drivers
+ at subsubsection Command-line arguments for test drivers
-Still, if the package author has legitimate reasons to extend
- at file{site.exp} at @command{make} time, he can do so by defining
-the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
-there will be considered @file{site.exp} prerequisites, and their
-content will be appended to it (in the same order in which they
-appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
- at emph{not} distributed by default.
+A custom driver can rely on various command-line options and arguments
+being passed to it automatically by the Automake-generated test harness.
+It is @emph{mandatory} that it understands all of them (even if the exact
+interpretation of the associated semantics can legitimately change
+between a test driver and another, and even be a no-op in some drivers).
-For more information regarding DejaGnu test suites, see @ref{Top, , ,
-dejagnu, The DejaGnu Manual}.
+ at noindent
+Here is the list of options:
-In either case, the testing is done via @samp{make check}.
+ at table @option
+ at item --test-name=@var{NAME}
+The name of the test, with VPATH prefix (if any) removed. This can have a
+suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
+mostly meant to be used in console reports about testsuite advancements and
+results (@pxref{Testsuite progress output}).
+ at item --log-file=@file{@var{PATH}.log}
+The @file{.log} file the test driver must create (@pxref{Basics of
+test metadata}). If it has a directory component (as in e.g.,
+ at file{sub/foo.log}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
+ at item --trs-file=@file{@var{PATH}.trs}
+The @file{.trs} file the test driver must create (@pxref{Basics of
+test metadata}). If it has a directory component (as in e.g.,
+ at file{sub/foo.trs}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
+ at item --color-tests=@{yes|no@}
+Whether the console output should be colorized or not (@pxref{Simple
+tests and color-tests}, to learn when this option gets activated and
+when it doesn't).
+ at item --expect-failure=@{yes|no@}
+Whether the tested program is expected to fail.
+ at item --enable-hard-errors=@{yes|no@}
+Whether ``hard errors'' in the tested program should be treated differently
+from normal failures or not (the default should be @code{yes}). The exact
+meaning of ``hard error'' is highly dependent from the test protocols or
+conventions in use.
+ at item --
+Explicitly terminate the list of options.
+ at end table
- at node Install Tests
- at section Install Tests
+ at noindent
+The first non-option argument passed to the test driver is the program to
+be run, and all the following ones are command-line options and arguments
+for this program.
+
+Note that the exact semantics attached to the @option{--color-tests},
+ at option{--expect-failure} and @option{--enable-hard-errors} options are
+left up to the individual test drivers. Still, having a behaviour
+compatible or at least similar to that provided by the default driver
+is advised, as that would offer a better consistency and a more pleasant
+user experience.
+
+ at node Log files generation and test results recording
+ at subsubsection Log files generation and test results recording
+
+The test driver must correctly generate the files specified by the
+ at option{--log-file} and @option{--trs-file} option (even when the tested
+program fails or crashes).
+
+The @file{.log} file should ideally contain all the output produced by the
+tested program, plus optionally other information that might facilitate
+debugging or analysis of bug reports. Apart from that, its format is
+basically free.
+
+The @file{.trs} file is used to register some metadata through the use
+of custom reStructuredText fields. This metadata is expected to be
+employed in various ways by the parallel test harness; for example, to
+count the test results when printing the testsuite summary, or to decide
+which tests to re-run upon @command{make reheck}. Unrecognized metadata
+in a @file{.trs} file is currently ignored by the harness, but this might
+change in the future. The list of currently recognized metadata follows.
-The @code{installcheck} target is available to the user as a way to
-run any tests after the package has been installed. You can add tests
-to this by writing an @code{installcheck-local} rule.
+ at table @code
+ at item :test-result:
+ at cindex Register test result
+ at cindex Register test case result
+ at cindex Test result, registering
+ at cindex Test case result, registering
+ at cindex @code{:test-result:}
+ at cindex reStructuredText field, @code{:test-result:}
+The test driver must use this field to register the results of @emph{each}
+test case run by a test script file. Several @code{:test-result:} fields
+can be present in the same @file{.trs} file; this is done in order to
+support test protocols that allow a single test script to run more test
+cases.
+
+ at c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
+The only recognized test results are currently @code{PASS}, @code{XFAIL},
+ at code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
+when declared with @code{:test-result:}, can be optionally followed by
+text holding the name and/or a brief description of the corresponding
+test; the harness will ignore such extra text when generating
+ at file{test-suite.log} and preparing the testsuite summary.
+
+ at c Keep in sync with 'test-metadata-recheck.sh'.
+ at item @code{:recheck:}
+ at cindex :recheck:
+ at cindex reStructuredText field, @code{:recheck:}
+If this field is present and defined to @code{no}, then the corresponding
+test script will @emph{not} be run upon a @command{make recheck}. What
+happens when two or more @code{:recheck:} fields are present in the same
+ at file{.trs} file is undefined behaviour.
+
+ at c Keep in sync with 'test-metadata-global-log.sh'.
+ at item @code{:copy-in-global-log:}
+ at cindex :copy-in-global-log:
+ at cindex reStructuredText field, @code{:copy-in-global-log:}
+If this field is present and defined to @code{no}, then the content
+of the @file{.log} file will @emph{not} be copied into the global
+ at file{test-suite.log}. We allow to forsake such copying because, while
+it can be useful in debugging and analysis of bug report, it can also be
+just a waste of space in normal situations, e.g., when a test script is
+successful. What happens when two or more @code{:copy-in-global-log:}
+fields are present in the same @file{.trs} file is undefined behaviour.
+
+ at c Keep in sync with 'test-metadata-global-result.sh'.
+ at item @code{:test-global-result:}
+ at cindex :test-global-result:
+ at cindex reStructuredText field, @code{:test-global-result:}
+This is used to declare the "global result" of the script. Currently,
+the value of this field is needed only to be reported (more or less
+verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
+so it's quite free-form. For example, a test script which run 10 test
+cases, 6 of which pass and 4 of which are skipped, could reasonably have
+a @code{PASS/SKIP} value for this field, while a test script which run
+19 successful tests and one failed test could have an @code{ALMOST
+PASSED} value. What happens when two or more @code{:test-global-result:}
+fields are present in the same @file{.trs} file is undefined behaviour.
+ at end table
- at node Rebuilding
- at chapter Rebuilding Makefiles
- at cindex rebuild rules
+ at noindent
+Let's see a small example. Assume a @file{.trs} file contains the
+following lines:
-Automake generates rules to automatically rebuild @file{Makefile}s,
- at file{configure}, and other derived files like @file{Makefile.in}.
+ at example
+:test-result: PASS server starts
+:global-log-copy: no
+:test-result: PASS HTTP/1.1 request
+:test-result: FAIL HTTP/1.0 request
+:recheck: yes
+:test-result: SKIP HTTPS request (TLS library wasn't available)
+:test-result: PASS server stops
+ at end example
+
+ at noindent
+Then the corresponding test script will be re-run by @command{make check},
+will contribute with @emph{five} test results to the testsuite summary
+(three of these tests being successful, one failed, and one skipped), and
+the content of the corresponding @file{.log} file will @emph{not} be
+copied in the global log file @file{test-suite.log}.
+
+ at node Testsuite progress output
+ at subsubsection Testsuite progress output
+
+A custom test driver also has the task of displaying, on the standard
+output, the test results as soon as they become available. Depending on
+the protocol in use, it can also display the reasons for failures and
+skips, and, more generally, any useful diagnostic output (but remember
+that each line on the screen is precious, so that cluttering the screen
+with overly verbose information is bad idea). The exact format of this
+progress output is left up to the test driver; in fact, a custom test
+driver might @emph{theoretically} even decide not to do any such report,
+leaving it all to the testsuite summary (that would be a very lousy idea,
+of course, and serves only to illustrate the flexibility that is
+granted here).
+
+Remember that consistency is good; so, if possible, try to be consistent
+with the output of the built-in Automake test drivers, providing a similar
+``look & feel''. In particular, the testsuite progress output should be
+colorized when the @option{--color-tests} is passed to the driver. On the
+other end, if you are using a known and widespread test protocol with
+well-established implementations, being consistent with those
+implementations' output might be a good idea too.
+
+ at c TODO: Give an example, maybe inspired to py.test-style output.
+ at c TODO: That is a good idea because it shows a test driver that allows
+ at c TODO: for different levels of verbosity in the progress output (could
+ at c TODO: be implemented either using a driver cmdline flag, or an
+ at c TODO: environment variable, or both).
+
+ at node Using the TAP test protocol
+ at section Using the TAP test protocol
+
+ at menu
+* Introduction to TAP::
+* Use TAP with the Automake test harness::
+* Incompatibilities with other TAP parsers and drivers::
+* Links and external resources on TAP::
+ at end menu
+
+ at node Introduction to TAP
+ at subsection Introduction to TAP
+
+TAP, the Test Anything Protocol, is a simple text-based interface between
+testing modules or programs and a test harness. The tests (also called
+``TAP producers'' in this context) write test results in a simple format
+on standard output; a test harness (also called ``TAP consumer'') will
+parse and interpret these results, and properly present them to the user,
+and/or register them for later analysis. The exact details of how this
+is accomplished can vary among different test harnesses. The Automake
+harness will present the results on the console in the usual
+fashion (@pxref{Testsuite progress on console}), and will use the
+ at file{.trs} files (@pxref{Basics of test metadata}) to store the test
+results and related metadata. Apart from that, it will try to remain
+as much compatible as possible with pre-existing and widespread utilities,
+such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
+ at command{prove} utility}, at least for the simpler usages.
+
+TAP started its life as part of the test harness for Perl, but today
+it has been (mostly) standardized, and has various independent
+implementations in different languages; among them, C, C++, Perl,
+Python, PHP, and Java. For a semi-official specification of the
+TAP protocol, please refer to the documentation of
+ at uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
+ @samp{Test::Harness::TAP}}.
+
+The most relevant real-world usages of TAP are obviously in the testsuites
+of @command{perl} and of many perl modules. Still, also other important
+third-party packages, such as @uref{http://git-scm.com/, @command{git}},
+use TAP in their testsuite.
+
+ at node Use TAP with the Automake test harness
+ at subsection Use TAP with the Automake test harness
+
+Currently, the TAP driver that comes with Automake requires some by-hand
+steps on the developer's part (this situation should hopefully be improved
+in future Automake versions). You'll have to grab the @file{tap-driver.sh}
+script from the Automake distribution by hand, copy it in your source tree,
+add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
+proper awk program, and use the Automake support for third-party test
+drivers to instruct the harness to use the @file{tap-driver.sh} script
+and that awk program to run your TAP-producing tests. See the example
+below for clarification.
+
+Apart from the options common to all the Automake test drivers
+(@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
+supports the following options, whose names are chosen for enhanced
+compatibility with the @command{prove} utility.
+
+ at table @option
+ at c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
+ at item --ignore-exit
+Causes the test driver to ignore the exit status of the test scripts;
+by default, the driver will report an error if the script exits with a
+non-zero status. This option has effect also on non-zero exit statuses
+due to termination by a signal.
+ at item --comments
+Instruct the test driver to display TAP diagnostic (i.e., lines beginning
+with the @samp{#} character) in the testsuite progress output too; by
+default, TAP diagnostic is only copied to the @file{.log} file.
+ at item --no-comments
+Revert the effects of @option{--comments}.
+ at item --merge
+Instruct the test driver to merge the test scripts' standard error into
+their standard output. This is necessary if you want to ensure that
+diagnostics from the test scripts are displayed in the correct order
+relative to test results; this can be of great help in debugging
+(especially if your test scripts are shell scripts run with shell
+tracing active). As a downside, this option might cause the test
+harness to get confused if anything that appears on standard error
+looks like a test result.
+ at item --no-merge
+Revert the effects of @option{--merge}.
+ at item --diagnostic-string=@var{STRING}
+Change the string that introduces TAP diagnostic from the default value
+of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
+TAP-based test scripts produce verbose output on which they have limited
+control (because, say, the output comes from other tools invoked in the
+scripts), and it might contain text that gets spuriously interpreted as
+TAP diagnostic: such an issue can be solved by redefining the string that
+activates TAP diagnostic to a value you know won't appear by chance in
+the tests' output. Note however that this feature is non-standard, as
+the ``official'' TAP protocol does not allow for such a customization; so
+don't use it if you can avoid it.
+ at end table
+
+ at noindent
+Here is an example of how the TAP driver can be set up and used.
+
+ at c Keep in sync with tap-doc2.sh
+ at example
+% @kbd{cat configure.ac}
+AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
+AC_CONFIG_AUX_DIR([build-aux])
+AM_INIT_AUTOMAKE([foreign -Wall -Werror])
+AC_CONFIG_FILES([Makefile])
+AC_REQUIRE_AUX_FILE([tap-driver.sh])
+AC_PROG_AWK
+AC_OUTPUT
+
+% @kbd{cat Makefile.am}
+TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
+ $(top_srcdir)/build-aux/tap-driver.sh
+TESTS = foo.test bar.test baz.test
+EXTRA_DIST = $(TESTS)
+
+% @kbd{cat foo.test}
+#!/bin/sh
+echo 1..4 # Number of tests to be executed.
+echo 'ok 1 - Swallows fly'
+echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
+echo 'ok 3 - Pigs fly # SKIP not enough acid'
+echo '# I just love word plays ...'
+echo 'ok 4 - Flies fly too :-)'
+
+% @kbd{cat bar.test}
+#!/bin/sh
+echo 1..3
+echo 'not ok 1 - Bummer, this test has failed.'
+echo 'ok 2 - This passed though.'
+echo 'Bail out! Ennui kicking in, sorry...'
+echo 'ok 3 - This will not be seen.'
+
+% @kbd{cat baz.test}
+#!/bin/sh
+echo 1..1
+echo ok 1
+# Exit with error, even if all the tests have been successful.
+exit 7
+
+% @kbd{cp @var{PREFIX}/share/automake- at var{APIVERSION}/tap-driver.pl .}
+% @kbd{autoreconf -vi && ./configure && make check}
+...
+PASS: foo.test 1 - Swallows fly
+XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
+SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
+PASS: foo.test 4 - Flies fly too :-)
+FAIL: bar.test 1 - Bummer, this test has failed.
+PASS: bar.test 2 - This passed though.
+ERROR: bar.test - Bail out! Ennui kicking in, sorry...
+PASS: baz.test 1
+ERROR: baz.test - exited with status 7
+...
+Please report to bug-automake@@gnu.org
+...
+% @kbd{echo exit status: $?}
+exit status: 1
+
+ at c Keep the "skewed" indentation below, it produces pretty PDF output.
+% @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
+ TESTS='foo.test baz.test' make -e check}
+...
+PASS: foo.test 1 - Swallows fly
+XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
+SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
+# foo.test: I just love word plays...
+PASS: foo.test 4 - Flies fly too :-)
+PASS: baz.test 1
+...
+% @kbd{echo exit status: $?}
+exit status: 0
+ at end example
+
+ at node Incompatibilities with other TAP parsers and drivers
+ at subsection Incompatibilities with other TAP parsers and drivers
+
+For implementation or historical reasons, the TAP driver and harness as
+implemented by Automake have some minors incompatibilities with the
+mainstream versions, which you should be aware of.
+
+ at itemize @bullet
+ at item
+A @code{Bail out!} directive doesn't stop the whole testsuite, but only
+the test script it occurs in. This doesn't follow TAP specifications,
+but on the other hand it maximizes compatibility (and code sharing) with
+the ``hard error'' concept of the default testsuite driver.
+ at item
+The @code{version} and @code{pragma} directives are not supported.
+ at item
+The @option{--diagnostic-string} option of our driver allows to modify
+the string that introduces TAP diagnostic from the default value
+of ``@code{#}''. The standard TAP protocol has currently no way to
+allow this, so if you use it your diagnostic will be lost to more
+compliant tools like @command{prove} and @code{Test::Harness}
+ at item
+And there are probably some other small and yet undiscovered
+incompatibilities, especially in corner cases or with rare usages.
+ at end itemize
+
+ at node Links and external resources on TAP
+ at subsection Links and external resources on TAP
+
+ at noindent
+Here are some links to more extensive official or third-party
+documentation and resources about the TAP protocol and related
+tools and libraries.
+ at itemize @bullet
+ at item
+ at uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
+ @samp{Test::Harness::TAP}},
+the (mostly) official documentation about the TAP format and protocol.
+ at item
+ at uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
+ @command{prove}},
+the most famous command-line TAP test driver, included in the distribution
+of @command{perl} and
+ at uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
+ @samp{Test::Harness}}.
+ at item
+The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
+ at item
+A ``gentle introduction'' to testing for perl coders:
+ at uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
+ @samp{Test::Tutorial}}.
+ at item
+ at uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
+ @samp{Test::Simple}}
+and
+ at uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
+ @samp{Test::More}},
+the standard perl testing libraries, which are based on TAP.
+ at item
+ at uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
+a C-based project implementing both a TAP producer and a TAP consumer.
+ at item
+ at uref{http://www.tap4j.org/,tap4j},
+a Java-based project implementing both a TAP producer and a TAP consumer.
+ at end itemize
+
+ at node DejaGnu Tests
+ at section DejaGnu Tests
+
+If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
+ at code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
+assumed. The variable @code{DEJATOOL} is a list of names that are
+passed, one at a time, as the @option{--tool} argument to
+ at command{runtest} invocations; it defaults to the name of the package.
+
+The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
+ at option{--srcdir} flags that are passed to dejagnu by default; this can be
+overridden if necessary.
+ at vindex RUNTESTDEFAULTFLAGS
+
+The variables @code{EXPECT} and @code{RUNTEST} can
+also be overridden to provide project-specific values. For instance,
+you will need to do this if you are testing a compiler toolchain,
+because the default values do not take into account host and target
+names.
+ at opindex dejagnu
+ at vindex DEJATOOL
+ at vindex EXPECT
+ at vindex RUNTEST
+
+The contents of the variable @code{RUNTESTFLAGS} are passed to the
+ at code{runtest} invocation. This is considered a ``user variable''
+(@pxref{User Variables}). If you need to set @command{runtest} flags in
+ at file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
+ at vindex RUNTESTFLAGS
+ at vindex AM_RUNTESTFLAGS
+
+ at cindex @file{site.exp}
+Automake will generate rules to create a local @file{site.exp} file,
+defining various variables detected by @command{configure}. This file
+is automatically read by DejaGnu. It is OK for the user of a package
+to edit this file in order to tune the test suite. However this is
+not the place where the test suite author should define new variables:
+this should be done elsewhere in the real test suite code.
+Especially, @file{site.exp} should not be distributed.
+
+Still, if the package author has legitimate reasons to extend
+ at file{site.exp} at @command{make} time, he can do so by defining
+the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
+there will be considered @file{site.exp} prerequisites, and their
+content will be appended to it (in the same order in which they
+appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
+ at emph{not} distributed by default.
+
+For more information regarding DejaGnu test suites, see @ref{Top, , ,
+dejagnu, The DejaGnu Manual}.
+
+ at node Install Tests
+ at section Install Tests
+
+The @code{installcheck} target is available to the user as a way to
+run any tests after the package has been installed. You can add tests
+to this by writing an @code{installcheck-local} rule.
+
+
+ at node Rebuilding
+ at chapter Rebuilding Makefiles
+ at cindex rebuild rules
+
+Automake generates rules to automatically rebuild @file{Makefile}s,
+ at file{configure}, and other derived files like @file{Makefile.in}.
@acindex AM_MAINTAINER_MODE
If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
these automatic rebuilding rules are only enabled in maintainer mode.
- at vindex ACLOCAL_AMFLAGS
-Sometimes you need to run @command{aclocal} with an argument like
- at option{-I} to tell it where to find @file{.m4} files. Since
-sometimes @command{make} will automatically run @command{aclocal}, you
-need a way to specify these arguments. You can do this by defining
- at code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
-to @command{aclocal}. This variable is only useful in the top-level
- at file{Makefile.am}.
-
@vindex CONFIG_STATUS_DEPENDENCIES
@vindex CONFIGURE_DEPENDENCIES
@cindex @file{version.sh}, example
@@ -9199,6 +9911,7 @@ from @file{configure.ac}. For instance, the following statement will
cause @file{configure} to be rerun each time @file{version.sh} is
changed.
+ at c Keep in sync with remake-config-status-dependencies.sh
@example
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
@end example
@@ -9211,12 +9924,17 @@ any level in the build hierarchy.
Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
@code{CONFIG_STATUS_DEPENDENCIES}.
+ at c Keep in sync with remake-configure-dependencies.sh
@code{CONFIGURE_DEPENDENCIES} adds dependencies to the
@file{configure} rule, whose effect is to run @command{autoconf}. This
variable should be seldom used, because @command{automake} already tracks
@code{m4_include}d files. However it can be useful when playing
tricky games with @code{m4_esyscmd} or similar non-recommendable
-macros with side effects.
+macros with side effects. Be also aware that interactions of this
+variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
+The Autoconf Manual} are quite problematic and can cause subtle
+breakage, so you might want to disable the cache if you want to use
+ at code{CONFIGURE_DEPENDENCIES}.
@code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
@file{config.status} rule, whose effect is to run @file{configure}.
@@ -9267,8 +9985,16 @@ will now be rerun each time the version number is bumped, when only
@node Options
@chapter Changing Automake's Behavior
+ at menu
+* Options generalities:: Semantics of Automake option
+* List of Automake options:: A comprehensive list of Automake options
+ at end menu
+
+ at node Options generalities
+ at section Options generalities
+
Various features of Automake can be controlled by options. Except where
-noted otherwise, options can be specified in one of several ways: Most
+noted otherwise, options can be specified in one of several ways. Most
options can be applied on a per- at file{Makefile} basis when listed in a
special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
of these options only make sense when specified in the toplevel
@@ -9278,52 +10004,65 @@ of these options only make sense when specified in the toplevel
require changes to the @command{configure} script can only be specified
there. These are annotated below.
-Currently understood options are:
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
+turn take precedence over those specified on the command line.
+
+Also, some care must be taken about the interactions among strictness
+level and warning categories. As a general rule, strictness-implied
+warnings are overridden by those specified by explicit options. For
+example, even if @samp{portability} warnings are disabled by default
+in @option{foreign} strictness, an usage like this will end up enabling
+them:
+
+ at example
+AUTOMAKE_OPTIONS = -Wportability foreign
+ at end example
+
+However, a strictness level specified in a higher-priority context
+will override all the explicit warnings specified in a lower-priority
+context. For example, if @file{configure.ac} contains:
+
+ at example
+AM_INIT_AUTOMAKE([-Wportability])
+ at end example
+
+ at noindent
+and @file{Makefile.am} contains:
+
+ at example
+AUTOMAKE_OPTIONS = foreign
+ at end example
+
+ at noindent
+then @samp{portability} warnings will be @emph{disabled} in
+ at file{Makefile.am}.
+
+ at node List of Automake options
+ at section List of Automake options
+
@vindex AUTOMAKE_OPTIONS
@table @asis
@item @option{gnits}
@itemx @option{gnu}
@itemx @option{foreign}
- at itemx @option{cygnus}
@cindex Option, @option{gnits}
@cindex Option, @option{gnu}
@cindex Option, @option{foreign}
- at cindex Option, @option{cygnus}
@opindex gnits
@opindex gnu
@opindex foreign
- at opindex cygnus
Set the strictness as appropriate. The @option{gnits} option also
implies options @option{readme-alpha} and @option{check-news}.
- at item @option{ansi2knr}
- at itemx @option{@var{path}/ansi2knr}
- at cindex Option, @option{ansi2knr}
- at opindex ansi2knr
-Turn on the deprecated de-ANSI-fication feature (@pxref{ANSI}). Note
-that that feature and this option @emph{will be removed} in the next
-major Automake release.
-
-If preceded by a
-path, the generated @file{Makefile.in} will look in the specified
-directory to find the @file{ansi2knr} program. The path should be a
-relative path to another directory in the same distribution (Automake
-does not check this).
-
@item @option{check-news}
@cindex Option, @option{check-news}
@opindex check-news
Cause @samp{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.
- at item @option{color-tests}
- at cindex Option, @option{color-tests}
- at opindex color-tests
-Cause output of the simple test suite (@pxref{Simple Tests}) to be
-colorized on capable terminals.
-
@item @option{dejagnu}
@cindex Option, @option{dejagnu}
@opindex dejagnu
@@ -9341,17 +10080,11 @@ Hook @code{dist-bzip2} to @code{dist}.
Hook @code{dist-lzip} to @code{dist}.
@trindex dist-lzip
- at item @option{dist-lzma}
- at cindex Option, @option{dist-lzma}
- at opindex dist-lzma
-Hook @code{dist-lzma} to @code{dist}. Obsoleted by @code{dist-xz}.
- at trindex dist-lzma
-
- at item @option{dist-shar}
- at cindex Option, @option{dist-shar}
- at opindex dist-shar
-Hook @code{dist-shar} to @code{dist}.
- at trindex dist-shar
+ at item @option{dist-xz}
+ at cindex Option, @option{dist-xz}
+ at opindex dist-xz
+Hook @code{dist-xz} to @code{dist}.
+ at trindex dist-xz
@item @option{dist-zip}
@cindex Option, @option{dist-zip}
@@ -9359,10 +10092,19 @@ Hook @code{dist-shar} to @code{dist}.
Hook @code{dist-zip} to @code{dist}.
@trindex dist-zip
+ at item @option{dist-shar}
+ at cindex Option, @option{dist-shar}
+ at opindex dist-shar
+Hook @code{dist-shar} to @code{dist}. Use of this option
+is discouraged, as the @samp{shar} format is obsolescent and
+problematic.
+ at trindex dist-shar
+
@item @option{dist-tarZ}
@cindex Option, @option{dist-tarZ}
@opindex dist-tarZ
-Hook @code{dist-tarZ} to @code{dist}.
+Hook @code{dist-tarZ} to @code{dist}. Use of this option
+is discouraged, as the @samp{compress} program is obsolete.
@trindex dist-tarZ
@item @option{filename-length-max=99}
@@ -9447,11 +10189,19 @@ are ordinarily automatically provided by Automake.
Don't require @file{texinfo.tex}, even if there are texinfo files in
this directory.
+ at item @option{serial-tests}
+ at cindex Option, @option{serial-tests}
+ at opindex serial-tests
+Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
+Test Harness}, for more information).
+
@item @option{parallel-tests}
@cindex Option, @option{parallel-tests}
@opindex parallel-tests
-Enable test suite driver for @code{TESTS} that can run tests in parallel
-(@pxref{Simple Tests using parallel-tests}, for more information).
+Enable test suite harness for @code{TESTS} that can run tests in parallel
+(@pxref{Parallel Test Harness}, for more information). This option is
+only kept for backward-compatibility, since the parallel test harness is
+the default now.
@item @option{readme-alpha}
@cindex Option, @option{readme-alpha}
@@ -9465,23 +10215,6 @@ non-alpha releases. The second form is
@samp{@var{major}. at var{minor}@var{alpha}}, where @var{alpha} is a
letter; it should be omitted for non-alpha releases.
- at item @option{silent-rules}
- at cindex Option, @option{silent-rules}
- at opindex silent-rules
-Enable less verbose build rules. This can be used to let build rules
-output status lines of the form:
- at example
-GEN @var{output-file}
- CC @var{object-file}
- at end example
- at noindent
-instead of printing the command that will be executed to update
- at var{output-file} or to compile @var{object-file}. It can also
-silence @command{libtool} output.
-
-For more information about how to use, enable, or disable silent
-rules, @pxref{Automake silent-rules Option}.
-
@item @option{std-options}
@cindex Options, @option{std-options}
@cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
@@ -9500,7 +10233,7 @@ test. For instance, @command{false} (from GNU coreutils) is never
successful, even for @option{--help} or @option{--version}. You can list
such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
Programs (not scripts) listed in this variable should be suffixed by
- at samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
+ at samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
build @file{false} as a program but @file{true.sh} as a script, and that
neither of them support @option{--help} or @option{--version}:
@@ -9614,9 +10347,8 @@ the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
There are a few rules and variables that didn't fit anywhere else.
@menu
-* Tags:: Interfacing to etags and mkid
-* Suffixes:: Handling new file extensions
-* Multilibs:: Support for multilibs (deprecated, soon to be removed).
+* Tags:: Interfacing to cscope, etags and mkid
+* Suffixes:: Handling new file extensions
@end menu
@@ -9671,10 +10403,22 @@ is the name of the program to invoke (by default @command{ctags});
@code{CTAGSFLAGS} can be used by the user to pass additional flags,
and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
+ at trindex id
Automake will also generate an @code{ID} rule that will run
@command{mkid} on the source. This is only supported on a
directory-by-directory basis.
- at trindex id
+
+Similarly, the @code{cscope} rule will create a list of all the source
+files in the tree and run @command{cscope} to build an inverted index
+database. The variable @code{CSCOPE} is the name of the program to invoke
+(by default @command{cscope}); @code{CSCOPEFLAGS} and
+ at code{CSCOPE_ARGS} can be used by the user to pass additional flags and
+file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
+ at file{Makefile.am}. Note that, currently, the Automake-provided
+ at code{cscope} support, when used in a VPATH build, might not work well
+with non-GNU make implementations (especially with make implementations
+performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
+The Autoconf Manual}).
Finally, Automake also emits rules to support the
@uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
@@ -9722,7 +10466,7 @@ For instance, the following definition prevents Automake from misinterpreting
the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
@file{.cpp} files.
- at c Keep in sync with suffix7.test.
+ at c Keep in sync with suffix7.sh
@example
SUFFIXES = .idl C.cpp
.idlC.cpp:
@@ -9736,22 +10480,6 @@ Automake generate the suffix list for @code{.SUFFIXES}. Any given
@code{SUFFIXES} go at the start of the generated suffixes list, followed
by Automake generated suffixes not already in the list.
- at node Multilibs
- at section Support for Multilibs (deprecated, soon to be removed).
-
-Automake used to support an obscure feature called multilibs. @emph{This
-feature is now deprecated, and will be removed in the next major Automake
-version}. Still, its implementation will remain available in the
- at file{contrib/} directory of the Automake distribution, so it should be
-very easy for motivated users to continue to use it in their projects,
-if they really need to.
-
-A @dfn{multilib} is a library that is built for multiple different ABIs
-at a single time; each time the library is built with a different target
-flag combination. This is only useful when the library is intended to
-be cross-compiled, and it is almost exclusively used for compiler
-support libraries.
-
@node Include
@chapter Include
@@ -9968,9 +10696,9 @@ Libtool Sources}).
@cindex Silent @command{make} rules
@menu
-* Make verbosity:: Make is verbose by default
-* Tricks For Silencing Make:: Standard and generic ways to silence make
-* Automake silent-rules Option:: How Automake can help in silencing make
+* Make verbosity:: Make is verbose by default
+* Tricks For Silencing Make:: Standard and generic ways to silence make
+* Automake Silent Rules:: How Automake can help in silencing make
@end menu
@node Make verbosity
@@ -10005,8 +10733,8 @@ the easy detection of potentially important warning messages.
Here we describe some common idioms/tricks to obtain a quieter make
output, with their relative advantages and drawbacks. In the next
-section (@ref{Automake silent-rules Option}) we'll see how Automake
-can help in this respect.
+section (@ref{Automake Silent Rules}) we'll see how Automake can help
+in this respect, providing more elaborate and flexible idioms.
@itemize @bullet
@@ -10058,20 +10786,19 @@ automatically activated if the @option{-s} flag is used.
@end itemize
- at node Automake silent-rules Option
+ at node Automake Silent Rules
@section How Automake can help in silencing make
The tricks and idioms for silencing @command{make} described in the
previous section can be useful from time to time, but we've seen that
they all have their serious drawbacks and limitations. That's why
automake provides support for a more advanced and flexible way of
-obtaining quieter output from @command{make}: the @option{silent-rules}
-mode.
+obtaining quieter output from @command{make} (for most rules at least).
@c TODO: Maybe describe in brief the precedent set by the build system
@c of the Linux Kernel, from which Automake took inspiration ... Links?
-To give the gist of what @option{silent-rules} can do, here is a simple
+To give the gist of what Automake can do in this respect, here is a simple
comparison between a typical @command{make} output (where silent rules
are disabled) and one with silent rules enabled:
@@ -10120,7 +10847,7 @@ func.c:4:3: warning: ‘i’ used uninitialized in this function
CCLD foo
@end example
- at cindex silent-rules and libtool
+ at cindex silent rules and libtool
Also, in projects using @command{libtool}, the use of silent rules can
automatically enable the @command{libtool}'s @option{--silent} option:
@@ -10146,26 +10873,9 @@ libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
CCLD libx.la
@end example
-Let's now see how the @option{silent-rules} mode interfaces with the
-package developer and the package user.
-
-To enable the use of @option{silent-rules} in his package, a developer
-needs to do either of the following:
-
- at itemize @bullet
- at item
-Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
- at item
-Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
-file.
- at end itemize
-
-It is not possible to instead specify @option{silent-rules} in a
- at file{Makefile.am} file.
-
-If the developer has done either of the above, then the user of the
-package may influence the verbosity at @command{configure} run time as
-well as at @command{make} run time:
+For Automake-generated @file{Makefile}s, the user may influence the
+verbosity at @command{configure} run time as well as at @command{make}
+run time:
@itemize @bullet
@item
@@ -10181,19 +10891,18 @@ time may be overridden: @code{make V=1} will produce verbose output,
@code{make V=0} less verbose output.
@end itemize
- at cindex default verbosity for silent-rules
+ at cindex default verbosity for silent rules
Note that silent rules are @emph{disabled} by default; the user must
enable them explicitly at either @command{configure} run time or at
@command{make} run time. We think that this is a good policy, since
it provides the casual user with enough information to prepare a good
bug report in case anything breaks.
-Still, notwithstanding the rationales above, a developer who wants to
-make silent rules enabled by default in his own package can do so by
-adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
- at file{configure.ac}. We advise against this approach, though.
+Still, notwithstanding the rationales above, a developer who really
+wants to make silent rules enabled by default in his own package can
+do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
- at c Keep in sync with silent-configsite.test
+ at c Keep in sync with silent-configsite.sh
Users who prefer to have silent rules enabled by default can edit their
@file{config.site} file to make the variable @code{enable_silent_rules}
default to @samp{yes}. This should still allow disabling silent rules
@@ -10204,16 +10913,13 @@ For portability to different @command{make} implementations, package authors
are advised to not set the variable @code{V} inside the @file{Makefile.am}
file, to allow the user to override the value for subdirectories as well.
-The current implementation of this feature normally uses nested
-variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
-that is not required by POSIX 2008 but is widely supported in
-practice. The @option{silent-rules} option thus turns off warnings
-about recursive variable expansion, which are in turn enabled by
- at option{-Wportability} (@pxref{automake Invocation}). On the rare
- at command{make} implementations that do not support nested variable
-expansion, whether rules are silent is always determined at configure
-time, and cannot be overridden at make time. Future versions of POSIX
-are likely to require nested variable expansion, so this minor
+To work at its best, the current implementation of this feature normally
+uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
+feature that is not required by POSIX 2008 but is widely supported in
+practice. On the rare @command{make} implementations that do not support
+nested variable expansion, whether rules are silent is always determined at
+configure time, and cannot be overridden at make time. Future versions of
+POSIX are likely to require nested variable expansion, so this minor
limitation should go away with time.
@vindex @code{AM_V_GEN}
@@ -10221,15 +10927,31 @@ limitation should go away with time.
@vindex @code{AM_DEFAULT_VERBOSITY}
@vindex @code{AM_V}
@vindex @code{AM_DEFAULT_V}
-To extend the silent mode to your own rules, you have two choices:
+To extend the silent mode to your own rules, you have few choices:
@itemize @bullet
+
@item
You can use the predefined variable @code{AM_V_GEN} as a prefix to
commands that should output a status line in silent mode, and
@code{AM_V_at} as a prefix to commands that should not output anything
in silent mode. When output is to be verbose, both of these variables
will expand to the empty string.
+
+ at item
+You can silence a recipe unconditionally with @code{@@}, and then use
+the predefined variable @code{AM_V_P} to know whether make is being run
+in silent or verbose mode, adjust the verbose information your recipe
+displays accordingly:
+
+ at example
+generate-headers:
+ @set -e; \
+ ... [commands defining a shell variable '$headers'] ...; \
+ if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
+ rm -f $$headers && generate-header --flags $$headers
+ at end example
+
@item
You can add your own variables, so strings of your own choice are shown.
The following snippet shows how you would define your own equivalent of
@@ -10322,64 +11044,6 @@ The file @file{THANKS} is required.
@end itemize
- at node Cygnus
- at chapter The effect of @option{--cygnus}
-
- at cindex @option{cygnus} strictness
-
- at emph{The features described in this section are deprecated; you must
-not use any of them in new code, and should remove their use from older
-but still maintained code: they will be withdrawn in a future Automake
-release.}
-
-Some packages, notably GNU GCC and GNU gdb, used to have a build
-environment originally written at Cygnus Support (subsequently renamed
-Cygnus Solutions, and then later purchased by Red Hat). Packages with
-this ancestry are sometimes referred to as ``Cygnus'' trees.
-
-A Cygnus tree has slightly different rules for how a
- at file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
- at command{automake} will cause any generated @file{Makefile.in} to
-comply with Cygnus rules.
-
-Here are the precise effects of @option{--cygnus}:
-
- at itemize @bullet
-
- at item
-The @option{foreign} strictness is implied.
-
- at item
-The options @option{no-installinfo}, @option{no-dependencies} and
- at option{no-dist} are implied (@pxref{Options}).
-
- at item
-The macro @code{AM_MAINTAINER_MODE} is required.
-
- at item
-Info files are always created in the build directory, and not in the
-source directory. Packages that don't use the @option{cygnus} option
-can emulate this effect by using the @option{no-installinfo} option
-and listing the generated info files in the @code{CLEANFILES} variable.
-
- at item
- at file{texinfo.tex} is not required if a Texinfo source file is
-specified. The assumption is that the file will be supplied, but in a
-place that Automake cannot find -- it is an artifact of how Cygnus
-packages are typically bundled. This effect can be emulated in
-packages not using the @option{cygnus} option with a proper definition
-of the @code{TEXINFO_TEX} variable (@pxref{Texinfo}).
-
- at item
-Certain tools will be searched for in the build tree as well as in the
-user's @env{PATH}. These tools are @command{runtest}, @command{expect},
- at command{makeinfo} and @command{texi2dvi}.
-
- at item
-The @code{check} target doesn't depend on @code{all}.
- at end itemize
-
-
@node Not Enough
@chapter When Automake Isn't Enough
@@ -10559,7 +11223,7 @@ Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
For instance, here is how you could install a versioned copy of a
program using @samp{$(LN_S)}:
- at c Keep in sync with insthook.test
+ at c Keep in sync with insthook.sh
@example
install-exec-hook:
cd $(DESTDIR)$(bindir) && \
@@ -10575,7 +11239,7 @@ When writing @code{install-exec-hook} or @code{install-data-hook},
please bear in mind that the exec/data distinction is based on the
installation directory, not on the primary used (@pxref{The Two Parts of
Install}).
- at c Keep in sync with primary-prefix-couples-documented-valid.test.
+ at c Keep in sync with primary-prefix-couples-documented-valid.sh
So a @code{foo_SCRIPTS} will be installed by
@code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
@code{install-exec}. You should define your hooks consequently.
@@ -10665,7 +11329,7 @@ If you have ever used Gettext in a project, this is a good example of
how third-party @file{Makefile}s can be used with Automake. The
@file{Makefile}s @command{gettextize} puts in the @file{po/} and
@file{intl/} directories are handwritten @file{Makefile}s that
-implement all these targets. That way they can be added to
+implement all of these targets. That way they can be added to
@code{SUBDIRS} in Automake packages.
Directories that are only listed in @code{DIST_SUBDIRS} but not in
@@ -10866,7 +11530,7 @@ built from @file{Makefile.am} by @command{automake}, and rely on the
definitions of the M4 macros put in @file{aclocal.m4} as well as the
behavior of the auxiliary tools installed.
-Because all these files are closely related, it is important to
+Because all of these files are closely related, it is important to
regenerate all of them when upgrading to a newer Automake release.
The usual way to do that is
@@ -10886,7 +11550,7 @@ autoreconf -vfi
The use of @option{--force-missing} ensures that auxiliary tools will be
overridden by new versions (@pxref{automake Invocation}).
-It is important to regenerate all these files each time Automake is
+It is important to regenerate all of these files each time Automake is
upgraded, even between bug fixes releases. For instance, it is not
unusual for a bug fix to involve changes to both the rules generated
in @file{Makefile.in} and the supporting M4 macros copied to
@@ -10915,7 +11579,7 @@ lists.
* maintainer-mode:: missing and AM_MAINTAINER_MODE
* Wildcards:: Why doesn't Automake support wildcards?
* Limitations on File Names:: Limitations on source and installed file names
-* distcleancheck:: Files left in build directory after distclean
+* Errors with distclean:: Files left in build directory after distclean
* Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
* Renamed Objects:: Why are object files sometimes renamed?
* Per-Object Flags:: How to simulate per-object flags?
@@ -10934,12 +11598,12 @@ lists.
Packages made with Autoconf and Automake ship with some generated
files like @file{configure} or @file{Makefile.in}. These files were
-generated on the developer's host and are distributed so that
+generated on the developer's machine and are distributed so that
end-users do not have to install the maintainer tools required to
rebuild them. Other generated files like Lex scanners, Yacc parsers,
or Info documentation, are usually distributed on similar grounds.
-Automake outputs rules in @file{Makefile}s to rebuild these files. For
+Automake output rules in @file{Makefile}s to rebuild these files. For
instance, @command{make} will run @command{autoconf} to rebuild
@file{configure} whenever @file{configure.ac} is changed. This makes
development safer by ensuring a @file{configure} is never out-of-date
@@ -11002,10 +11666,41 @@ If users use @command{cvs update} to update their copy, instead of
inaccurate. Some rebuild rules will be triggered and attempt to
run developer tools such as @command{autoconf} or @command{automake}.
-Actually, calls to such tools are all wrapped into a call to the
- at command{missing} script discussed later (@pxref{maintainer-mode}).
- at command{missing} will take care of fixing the timestamps when these
-tools are not installed, so that the build can continue.
+Calls to such tools are all wrapped into a call to the @command{missing}
+script discussed later (@pxref{maintainer-mode}), so that the user will
+see more descriptive warnings about missing or out-of-date tools, and
+possible suggestions about how to obtain them, rather than just some
+``command not found'' error, or (worse) some obscure message from some
+older version of the required tool they happen to have installed.
+
+Maintainers interested in keeping their package buildable from a CVS
+checkout even for those users that lack maintainer-specific tools might
+want to provide an helper script (or to enhance their existing bootstrap
+script) to fix the timestamps after a
+ at command{cvs update} or a @command{git checkout}, to prevent spurious
+rebuilds. In case of a project committing the Autotools-generated
+files, as well as the generated @file{.info} files, such script might
+look something like this:
+
+ at smallexample
+#!/bin/sh
+# fix-timestamp.sh: prevents useless rebuilds after "cvs update"
+sleep 1
+# aclocal-generated aclocal.m4 depends on locally-installed
+# '.m4' macro files, as well as on 'configure.ac'
+touch aclocal.m4
+sleep 1
+# autoconf-generated configure depends on aclocal.m4 and on
+# configure.ac
+configure config.h.in
+# so does autoheader-generated config.h.in
+configure config.h.in
+# and all the automake-generated Makefile.in files
+touch `find . -name Makefile.in -print`
+# finally, the makeinfo-generated '.info' files depend on the
+# corresponding '.texi' files
+touch doc/*.info
+ at end smallexample
@item
In distributed development, developers are likely to have different
@@ -11023,7 +11718,7 @@ Or people use a script to fix the timestamp after a checkout (the GCC
folks have such a script).
@item
Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
-disable all these rebuild rules by default. This is further discussed
+disable all of these rebuild rules by default. This is further discussed
in @ref{maintainer-mode}.
@end itemize
@@ -11102,20 +11797,20 @@ tools shouldn't be required during a user build and they are not
checked for in @file{configure}.
However, if for some reason a rebuild rule is triggered and involves a
-missing tool, @command{missing} will notice it and warn the user.
-Besides the warning, when a tool is missing, @command{missing} will
-attempt to fix timestamps in a way that allows the build to continue.
-For instance, @command{missing} will touch @file{configure} if
- at command{autoconf} is not installed. When all distributed files are
-kept under version control, this feature of @command{missing} allows a
-user @emph{with no maintainer tools} to build a package off its version
-control repository, bypassing any timestamp inconsistency (implied by
-e.g.@: @samp{cvs update} or @samp{git clone}).
+missing tool, @command{missing} will notice it and warn the user, even
+suggesting how to obtain such a tool (at least in case it is a well-known
+one, like @command{makeinfo} or @command{bison}). This is more helpful
+and user-friendly than just having the rebuild rules spewing out a terse
+error message like @samp{sh: @var{tool}: command not found}. Similarly,
+ at command{missing} will warn the user if it detects that a maintainer
+tool it attempted to use seems too old (be warned that diagnosing this
+correctly is typically more difficult that detecting missing tools, and
+requires cooperation from the tool itself, so it won't always work).
If the required tool is installed, @command{missing} will run it and
won't attempt to continue after failures. This is correct during
development: developers love fixing failures. However, users with
-wrong versions of maintainer tools may get an error when the rebuild
+missing or too old maintainer tools may get an error when the rebuild
rule is spuriously triggered, halting the build. This failure to let
the build continue is one of the arguments of the
@code{AM_MAINTAINER_MODE} advocates.
@@ -11223,7 +11918,7 @@ Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
not portable to other @command{make} implementations.
The only way Automake could support @command{$(wildcard ...)} is by
-expending @command{$(wildcard ...)} when @command{automake} is run.
+expanding @command{$(wildcard ...)} when @command{automake} is run.
The resulting @file{Makefile.in}s would be portable since they would
list all files and not use @samp{$(wildcard ...)}. However that
means developers would need to remember to run @command{automake} each
@@ -11310,13 +12005,14 @@ differ only in case (e.g., @file{makefile} and @file{Makefile}).
Nowadays it is no longer worth worrying about the 8.3 limits of
DOS file systems.
- at node distcleancheck
- at section Files left in build directory after distclean
+ at c FIXME This should probably be moved in the "Checking the Distribution"
+ at c FIXME section...
+ at node Errors with distclean
+ at section Errors with distclean
@cindex @code{distclean}, diagnostic
@cindex @samp{make distclean}, diagnostic
@cindex dependencies and distributed files
@trindex distclean
- at trindex distcleancheck
This is a diagnostic you might encounter while running @samp{make
distcheck}.
@@ -11496,6 +12192,7 @@ flags, not appended.
@cindex @code{AM_LFLAGS} and @code{LFLAGS}
@cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
@cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
+ at cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
@cindex @code{AM_RFLAGS} and @code{RFLAGS}
@cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
@cindex @code{AM_YFLAGS} and @code{YFLAGS}
@@ -11510,6 +12207,7 @@ flags, not appended.
@cindex @code{LFLAGS} and @code{AM_LFLAGS}
@cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
@cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
+ at cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
@cindex @code{RFLAGS} and @code{AM_RFLAGS}
@cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
@cindex @code{YFLAGS} and @code{AM_YFLAGS}
@@ -11519,8 +12217,8 @@ mostly discuss @code{CPPFLAGS} in our examples, but actually the
answer holds for all the compile flags used in Automake:
@code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
@code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
- at code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
- at code{UPCFLAGS}, and @code{YFLAGS}.
+ at code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
+ at code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
@code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
three variables that can be used to pass flags to the C preprocessor
@@ -11650,7 +12348,7 @@ every target in a @file{Makefile.in}.
Using variables like this gives you full control over the ordering of
the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
you want to negate for a particular target, you can use something like
- at samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
+ at samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
been forcefully appended to @code{CFLAGS}, there would be no way to
disable one flag. Yet another reason to leave user variables to
users.
@@ -11677,18 +12375,11 @@ obeys this naming scheme. The slight difference is that
@code{MAKEFLAGS} is passed to sub- at command{make}s implicitly by
@command{make} itself.
-However you should not think that all variables ending with
- at code{FLAGS} follow this convention. For instance,
- at code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
- at code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
-are two variables that are only useful to the maintainer and have no
-user counterpart.
-
@code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
has neither @code{AM_} nor per-target cousin.
Finally you should not think that the existence of a per-target
-variable implies the existance of an @code{AM_} variable or of a user
+variable implies the existence of an @code{AM_} variable or of a user
variable. For instance, the @code{mumble_LDADD} per-target variable
overrides the makefile-wide @code{LDADD} variable (which is not a user
variable), and @code{mumble_LIBADD} exists only as a per-target
@@ -12282,8 +12973,8 @@ generated by @command{automake} effectively:
@itemize
@item
-If less verbose output has been enabled in the package with the
- at samp{silent-rules} option (@pxref{Options}), you can use
+If less verbose output has been enabled in the package with the use
+of silent rules (@pxref{Automake Silent Rules}), you can use
@code{make V=1} to see the commands being executed.
@item
@code{make -n} can help show what would be done without actually doing
@@ -12353,1146 +13044,7 @@ bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
sure to include the versions of Autoconf and Automake that you use.
Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
reproduces the problem you encounter. If you have encountered test
-suite failures, please attach the @file{tests/test-suite.log} file.
-
-
- at node History
- at chapter History of Automake
-
-This chapter presents various aspects of the history of Automake. The
-exhausted reader can safely skip it; this will be more of interest to
-nostalgic people, or to those curious to learn about the evolution of
-Automake.
-
- at menu
-* Timeline:: The Automake story.
-* Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
-* Releases:: Statistics about Automake Releases
- at end menu
-
- at node Timeline
- at section Timeline
-
- at table @asis
- at item 1994-09-19 First CVS commit.
-
-If we can trust the CVS repository, David J. at tie{}MacKenzie (djm) started
-working on Automake (or AutoMake, as it was spelt then) this Monday.
-
-The first version of the @command{automake} script looks as follows.
-
- at example
-#!/bin/sh
-
-status=0
-
-for makefile
-do
- if test ! -f $@{makefile@}.am; then
- echo "automake: $@{makefile@}.am: No such honkin' file"
- status=1
- continue
- fi
-
- exec 4> $@{makefile@}.in
-
-done
- at end example
-
-From this you can already see that Automake will be about reading
- at file{*.am} file and producing @file{*.in} files. You cannot see
-anything else, but if you also know that David is the one who created
-Autoconf two years before you can guess the rest.
-
-Several commits follow, and by the end of the day Automake is
-reported to work for GNU fileutils and GNU m4.
-
-The modus operandi is the one that is still used today: variable
-assignments in @file{Makefile.am} files trigger injections of
-precanned @file{Makefile} fragments into the generated
- at file{Makefile.in}. The use of @file{Makefile} fragments was inspired
-by the 4.4BSD @command{make} and include files, however Automake aims
-to be portable and to conform to the GNU standards for @file{Makefile}
-variables and targets.
-
-At this point, the most recent release of Autoconf is version 1.11,
-and David is preparing to release Autoconf 2.0 in late October. As a
-matter of fact, he will barely touch Automake after September.
-
- at item 1994-11-05 David MacKenzie's last commit.
-
-At this point Automake is a 200 line portable shell script, plus 332
-lines of @file{Makefile} fragments. In the @file{README}, David
-states his ambivalence between ``portable shell'' and ``more
-appropriate language'':
-
- at quotation
-I wrote it keeping in mind the possibility of it becoming an Autoconf
-macro, so it would run at configure-time. That would slow
-configuration down a bit, but allow users to modify the Makefile.am
-without needing to fetch the AutoMake package. And, the Makefile.in
-files wouldn't need to be distributed. But all of AutoMake would. So
-I might reimplement AutoMake in Perl, m4, or some other more
-appropriate language.
- at end quotation
-
-Automake is described as ``an experimental Makefile generator''.
-There is no documentation. Adventurous users are referred to the
-examples and patches needed to use Automake with GNU m4 1.3, fileutils
-3.9, time 1.6, and development versions of find and indent.
-
-These examples seem to have been lost. However at the time of writing
-(10 years later in September, 2004) the FSF still distributes a
-package that uses this version of Automake: check out GNU termutils
-2.0.
-
- at item 1995-11-12 Tom Tromey's first commit.
-
-After one year of inactivity, Tom Tromey takes over the package.
-Tom was working on GNU cpio back then, and doing this just for fun,
-having trouble finding a project to contribute to. So while hacking
-he wanted to bring the @file{Makefile.in} up to GNU standards. This
-was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
-grabbed it and tried it out.
-
-Tom didn't talk to djm about it until later, just to make sure he
-didn't mind if he made a release. He did a bunch of early releases to
-the Gnits folks.
-
-Gnits was (and still is) totally informal, just a few GNU friends who
-Fran@,cois Pinard knew, who were all interested in making a common
-infrastructure for GNU projects, and shared a similar outlook on how
-to do it. So they were able to make some progress. It came along
-with Autoconf and extensions thereof, and then Automake from David and
-Tom (who were both gnitsians). One of their ideas was to write a
-document paralleling the GNU standards, that was more strict in some
-ways and more detailed. They never finished the GNITS standards, but
-the ideas mostly made their way into Automake.
-
- at item 1995-11-23 Automake 0.20
-
-Besides introducing automatic dependency tracking (@pxref{Dependency
-Tracking Evolution}), this version also supplies a 9-page manual.
-
-At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
-exist, so many things had to be done by hand. For instance, here is
-what a configure.in (this is the former name of the
- at file{configure.ac} we use today) must contain in order to use
-Automake 0.20:
-
- at example
-PACKAGE=cpio
-VERSION=2.3.911
-AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
-AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
-AC_SUBST(PACKAGE)
-AC_SUBST(VERSION)
-AC_ARG_PROGRAM
-AC_PROG_INSTALL
- at end example
-
-(Today all of the above is achieved by @code{AC_INIT} and
- at code{AM_INIT_AUTOMAKE}.)
-
-Here is how programs are specified in @file{Makefile.am}:
-
- at example
-PROGRAMS = hello
-hello_SOURCES = hello.c
- at end example
-
-This looks pretty much like what we do today, except the
- at code{PROGRAMS} variable has no directory prefix specifying where
- at file{hello} should be installed: all programs are installed in
- at samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
-that must be built but not installed (it is called
- at code{noinst_PROGRAMS} nowadays).
-
-Programs can be built conditionally using @code{AC_SUBST}itutions:
-
- at example
-PROGRAMS = @@progs@@
-AM_PROGRAMS = foo bar baz
- at end example
-
-(@code{AM_PROGRAMS} has since then been renamed to
- at code{EXTRA_PROGRAMS}.)
-
-Similarly scripts, static libraries, and data can be built and installed
-using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
-However @code{LIBRARIES} were treated a bit specially in that Automake
-did automatically supply the @file{lib} and @file{.a} prefixes.
-Therefore to build @file{libcpio.a}, one had to write
-
- at example
-LIBRARIES = cpio
-cpio_SOURCES = ...
- at end example
-
-Extra files to distribute must be listed in @code{DIST_OTHER} (the
-ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
-distributed should appear in @code{DIST_SUBDIRS}, but the manual
-describes this as a temporary ugly hack (today extra directories should
-also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
-for another purpose, @pxref{Conditional Subdirectories}).
-
- at item 1995-11-26 Automake 0.21
-
-In less time than it takes to cook a frozen pizza, Tom rewrites
-Automake using Perl. At this time Perl 5 is only one year old, and
-Perl 4.036 is in use at many sites. Supporting several Perl versions
-has been a source of problems through the whole history of Automake.
-
-If you never used Perl 4, imagine Perl 5 without objects, without
- at samp{my} variables (only dynamically scoped @samp{local} variables),
-without function prototypes, with function calls that needs to be
-prefixed with @samp{&}, etc. Traces of this old style can still be
-found in today's @command{automake}.
-
- at item 1995-11-28 Automake 0.22
- at itemx 1995-11-29 Automake 0.23
-
-Bug fixes.
-
- at item 1995-12-08 Automake 0.24
- at itemx 1995-12-10 Automake 0.25
-
-Releases are raining. 0.24 introduces the uniform naming scheme we
-use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
- at code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
- at code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
-in use; and @code{TEXINFOS} and @code{MANS} still have no directory
-prefixes.) Adding support for prefixes like that was one of the major
-ideas in @command{automake}; it has lasted pretty well.
-
-AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
-Pinard's doing).
-
-0.25 fixes a Perl 4 portability bug.
-
- at item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
- at item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
-
- at item 1996-01-03 Automake 0.26
- at itemx 1996-01-03 Automake 0.27
-
-Of the many changes and suggestions sent by Fran@,cois Pinard and
-included in 0.26, perhaps the most important is the advice that to
-ease customization a user rule or variable definition should always
-override an Automake rule or definition.
-
-Gordon Matzigkeit and Jim Meyering are two other early contributors
-that have been sending fixes.
-
-0.27 fixes yet another Perl 4 portability bug.
-
- at item 1996-01-13 Automake 0.28
-
-Automake starts scanning @file{configure.in} for @code{LIBOBJS}
-support. This is an important step because until this version
-Automake only knew about the @file{Makefile.am}s it processed.
- at file{configure.in} was Autoconf's world and the link between Autoconf
-and Automake had to be done by the @file{Makefile.am} author. For
-instance, if @file{config.h} was generated by @file{configure}, it was the
-package maintainer's responsibility to define the @code{CONFIG_HEADER}
-variable in each @file{Makefile.am}.
-
-Succeeding releases will rely more and more on scanning
- at file{configure.in} to better automate the Autoconf integration.
-
-0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
- at option{--gnu} and @option{--gnits} options, the latter being stricter.
-
- at item 1996-02-07 Automake 0.29
-
-Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
-and rebuild rules for @file{configure}-generated file are
-automatically output.
-
- at code{TEXINFOS} and @code{MANS} converted to the uniform naming
-scheme.
-
- at item 1996-02-24 Automake 0.30
-
-The test suite is born. It contains 9 tests. From now on test cases
-will be added pretty regularly (@pxref{Releases}), and this proved to
-be really helpful later on.
-
- at code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
-
-All the third-party Autoconf macros, written mostly by Fran@,cois
-Pinard (and later Jim Meyering), are distributed in Automake's
-hand-written @file{aclocal.m4} file. Package maintainers are expected
-to extract the necessary macros from this file. (In previous versions
-you had to copy and paste them from the manual...)
-
- at item 1996-03-11 Automake 0.31
-
-The test suite in 0.30 was run via a long @code{check-local} rule. Upon
-Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
-whenever the @code{TESTS} variable is defined.
-
- at code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
-prefix is introduced. The syntax is now the same as today.
-
- at item 1996-03-15 Gordon Matzigkeit starts writing libtool.
-
- at item 1996-04-27 Automake 0.32
-
- at code{-hook} targets are introduced; an idea from Dieter Baron.
-
- at file{*.info} files, which were output in the build directory are
-now built in the source directory, because they are distributed. It
-seems these files like to move back and forth as that will happen
-again in future versions.
-
- at item 1996-05-18 Automake 0.33
-
-Gord Matzigkeit's main two contributions:
-
- at itemize
- at item very preliminary libtool support
- at item the distcheck rule
- at end itemize
-
-Although they were very basic at this point, these are probably
-among the top features for Automake today.
-
-Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
-since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
-author (@pxref{maintainer-mode}).
-
- at item 1996-05-28 Automake 1.0
-
-After only six months of heavy development, the @command{automake} script is
-3134 lines long, plus 973 lines of @file{Makefile} fragments. The
-package has 30 pages of documentation, and 38 test cases.
- at file{aclocal.m4} contains 4 macros.
-
-From now on and until version 1.4, new releases will occur at a rate
-of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
-been the name of beta releases for 1.2. This is the first time
-Automake uses suffix letters to designate beta releases, a habit that
-lasts.
-
- at item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
-
- at item 1996-11-26 David J. at tie{}MacKenzie releases Autoconf 2.12.
-
-Between June and October, the Autoconf development is almost stalled.
-Roland McGrath has been working at the beginning of the year. David
-comes back in November to release 2.12, but he won't touch Autoconf
-anymore after this year, and Autoconf then really stagnates. The
-desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
-
- at item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
-
-The mailing list is announced as follows:
- at smallexample
-I've created the "automake" mailing list. It is
-"automake@@gnu.ai.mit.edu". Administrivia, as always, to
-automake-request@@gnu.ai.mit.edu.
-
-The charter of this list is discussion of automake, autoconf, and
-other configuration/portability tools (e.g., libtool). It is expected
-that discussion will range from pleas for help all the way up to
-patches.
-
-This list is archived on the FSF machines. Offhand I don't know if
-you can get the archive without an account there.
-
-This list is open to anybody who wants to join. Tell all your
-friends!
--- Tom Tromey
- at end smallexample
-
-Before that people were discussing Automake privately, on the Gnits
-mailing list (which is not public either), and less frequently on
- at code{gnu.misc.discuss}.
-
- at code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
-noticed. The archives of the early years of the
- at code{automake@@gnu.org} list have been lost, so today it is almost
-impossible to find traces of discussions that occurred before 1999.
-This has been annoying more than once, as such discussions can be
-useful to understand the rationale behind a piece of uncommented code
-that was introduced back then.
-
- at item 1997-06-22 Automake 1.2
-
-Automake developments continues, and more and more new Autoconf macros
-are required. Distributing them in @file{aclocal.m4} and requiring
-people to browse this file to extract the relevant macros becomes
-uncomfortable. Ideally, some of them should be contributed to
-Autoconf so that they can be used directly, however Autoconf is
-currently inactive. Automake 1.2 consequently introduces
- at command{aclocal} (@command{aclocal} was actually started on
-1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
-file from a repository of third-party macros. Because Autoconf has
-stalled, Automake also becomes a kind of repository for such
-third-party macros, even macros completely unrelated to Automake (for
-instance macros that fix broken Autoconf macros).
-
-The 1.2 release contains 20 macros, including the
- at code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
- at file{configure.in}.
-
-Libtool is fully supported using @code{*_LTLIBRARIES}.
-
-The missing script is introduced by Fran@,cois Pinard; it is meant to be
-a better solution than @code{AM_MAINTAINER_MODE}
-(@pxref{maintainer-mode}).
-
-Conditionals support was implemented by Ian Lance Taylor. At the
-time, Tom and Ian were working on an internal project at Cygnus. They
-were using ILU, which is pretty similar to CORBA at . They wanted to
-integrate ILU into their build, which was all @file{configure}-based,
-and Ian thought that adding conditionals to @command{automake} was
-simpler than doing all the work in @file{configure} (which was the
-standard at the time). So this was actually funded by Cygnus.
-
-This very useful but tricky feature will take a lot of time to
-stabilize. (At the time this text is written, there are still
-primaries that have not been updated to support conditional
-definitions in Automake 1.9.)
-
-The @command{automake} script has almost doubled: 6089 lines of Perl,
-plus 1294 lines of @file{Makefile} fragments.
-
- at item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
-
- at item 1998-04-05 Automake 1.3
-
-This is a small advance compared to 1.2.
-It adds support for assembly, and preliminary support for Java.
-
-Perl 5.004_04 is out, but fixes to support Perl 4 are still
-regularly submitted whenever Automake breaks it.
-
- at item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
-
-Sourceware was setup by Jason Molenda to host open source projects.
-
- at item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
- at itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
-Automake is now hosted on @code{sourceware.cygnus.com}. It has a
-publicly accessible CVS repository. This CVS repository is a copy of
-the one Tom was using on his machine, which in turn is based on
-a copy of the CVS repository of David MacKenzie. This is why we still
-have to full source history. (Automake was on Sourceware until 2007-10-29,
-when it moved to a git repository on @code{savannah.gnu.org},
-but the Sourceware host had been renamed to @code{sources.redhat.com}.)
-
-The oldest file in the administrative directory of the CVS repository
-that was created on Sourceware is dated 1998-09-19, while the
-announcement that @command{automake} and @command{autoconf} had joined
- at command{sourceware} was made on 1998-10-26. They were among the
-first projects to be hosted there.
-
-The heedful reader will have noticed Automake was exactly 4 years old
-on 1998-09-19.
-
- at item 1999-01-05 Ben Elliston releases Autoconf 2.13.
-
- at item 1999-01-14 Automake 1.4
-
-This release adds support for Fortran 77 and for the @code{include}
-statement. Also, @samp{+=} assignments are introduced, but it is
-still quite easy to fool Automake when mixing this with conditionals.
-
-These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
-will be used together for years.
-
- at command{automake} is 7228 lines, plus 1591 lines of Makefile
-fragment, 20 macros (some 1.3 macros were finally contributed back to
-Autoconf), 197 test cases, and 51 pages of documentation.
-
- at item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
-
-This implements a new dependency tracking schemed that should be
-able to handle automatic dependency tracking using any compiler (not
-just gcc) and any make (not just GNU @command{make}). In addition,
-the new scheme should be more reliable than the old one, as
-dependencies are generated on the end user's machine. Alexandre Oliva
-creates depcomp for this purpose.
-
- at xref{Dependency Tracking Evolution}, for more details about the
-evolution of automatic dependency tracking in Automake.
-
- at item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
-
-This was a huge problem since we also had patches going in on the
-trunk. The merge took a long time and was very painful.
-
- at item 2000-05-10
-
-Since September 1999 and until 2003, Akim Demaille will be zealously
-revamping Autoconf.
-
- at quotation
-I think the next release should be called "3.0".@*
-Let's face it: you've basically rewritten autoconf.@*
-Every weekend there are 30 new patches.@*
-I don't see how we could call this "2.15" with a straight face.@*
--- Tom Tromey on @email{autoconf@@gnu.org}
- at end quotation
-
-Actually Akim works like a submarine: he will pile up patches while he
-works off-line during the weekend, and flush them in batch when he
-resurfaces on Monday.
-
- at item 2001-01-24
-
-On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
-is out, and Akim has to find something to do during his week-end :)
-
- at item 2001-01-28
-
-Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
-
- at quotation
-Aiieeee! I was dreading the day that the Demaillator turned his
-sights on automake at dots{} and now it has arrived! -- Tom Tromey
- at end quotation
-
-It's only the beginning: in two months he will send 192 patches. Then
-he would slow down so Tom can catch up and review all this. Initially
-Tom actually read all these patches, then he probably trustingly
-answered OK to most of them, and finally gave up and let Akim apply
-whatever he wanted. There was no way to keep up with that patch rate.
-
- at quotation
-Anyway the patch below won't apply since it predates Akim's
-sourcequake; I have yet to figure where the relevant passage has
-been moved :) -- Alexandre Duret-Lutz
- at end quotation
-
-All these patches were sent to and discussed on
- at email{automake@@gnu.org}, so subscribed users were literally drowning in
-technical mails. Eventually, the @email{automake-patches@@gnu.org}
-mailing list was created in May.
-
-Year after year, Automake had drifted away from its initial design:
-construct @file{Makefile.in} by assembling various @file{Makefile}
-fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
-various places in the @command{automake} script itself; this does not
-help ensuring a consistent treatment of these rules (for instance
-making sure that user-defined rules override Automake's own rules).
-One of Akim's goal was moving all these hard-coded rules to separate
- at file{Makefile} fragments, so the logic could be centralized in a
- at file{Makefile} fragment processor.
-
-Another significant contribution of Akim is the interface with the
-``trace'' feature of Autoconf. The way to scan @file{configure.in} at
-this time was to read the file and grep the various macro of interest
-to Automake. Doing so could break in many unexpected ways; @command{automake}
-could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
-where the arguments are known only when M4 is run), or conversely it
-could detect some macro that was not expanded (because it is called
-conditionally). In the CVS version of Autoconf, Akim had implemented
-the @option{--trace} option, which provides accurate information about
-where macros are actually called and with what arguments. Akim will
-equip Automake with a second @file{configure.in} scanner that uses
-this @option{--trace} interface. Since it was not sensible to drop the
-Autoconf 2.13 compatibility yet, this experimental scanner was only
-used when an environment variable was set, the traditional
-grep-scanner being still the default.
-
- at item 2001-04-25 Gary V. at tie{}Vaughan releases Libtool 1.4
-
-It has been more than two years since Automake 1.4, CVS Automake has
-suffered lot's of heavy changes and still is not ready for release.
-Libtool 1.4 had to be distributed with a patch against Automake 1.4.
-
- at item 2001-05-08 Automake 1.4-p1
- at itemx 2001-05-24 Automake 1.4-p2
-
-Gary V. at tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
-release'' of Automake:
-
- at quotation
-The main purpose of this release is to have a stable automake
-which is compatible with the latest stable libtool.
- at end quotation
-
-The release also contains obvious fixes for bugs in Automake 1.4,
-some of which were reported almost monthly.
-
- at item 2001-05-21 Akim Demaille releases Autoconf 2.50
-
- at item 2001-06-07 Automake 1.4-p3
- at itemx 2001-06-10 Automake 1.4-p4
- at itemx 2001-07-15 Automake 1.4-p5
-
-Gary continues his patch-release series. These also add support for
-some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
- at file{configure.ac} over @file{configure.in}, and it introduces a new
-syntax for @code{AC_OUTPUT}ing files.
-
- at item 2001-08-23 Automake 1.5
-
-A major and long-awaited release, that comes more than two years after
-1.4. It brings many changes, among which:
- at itemize
- at item The new dependency tracking scheme that uses @command{depcomp}.
-Aside from the improvement on the dependency tracking itself
-(@pxref{Dependency Tracking Evolution}), this also streamlines the use
-of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
-used during development are now the same as those used in
-distributions. Before that the @file{Makefile.in}s generated for
-maintainers required GNU @command{make} and GCC, they were different
-from the portable @file{Makefile} generated for distribution; this was
-causing some confusion.
-
- at item Support for per-target compilation flags.
-
- at item Support for reference to files in subdirectories in most
- at file{Makefile.am} variables.
-
- at item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
-prefixes.
- at item Perl 4 support is finally dropped.
- at end itemize
-
-1.5 did break several packages that worked with 1.4. Enough so that
-Linux distributions could not easily install the new Automake version
-without breaking many of the packages for which they had to run
- at command{automake}.
-
-Some of these breakages were effectively bugs that would eventually be
-fixed in the next release. However, a lot of damage was caused by
-some changes made deliberately to render Automake stricter on some
-setup we did consider bogus. For instance, @samp{make distcheck} was
-improved to check that @samp{make uninstall} did remove all the files
- at samp{make install} installed, that @samp{make distclean} did not omit
-some file, and that a VPATH build would work even if the source
-directory was read-only. Similarly, Automake now rejects multiple
-definitions of the same variable (because that would mix very badly
-with conditionals), and @samp{+=} assignments with no previous
-definition. Because these changes all occurred suddenly after 1.4 had
-been established for more than two years, it hurt users.
-
-To make matter worse, meanwhile Autoconf (now at version 2.52) was
-facing similar troubles, for similar reasons.
-
- at item 2002-03-05 Automake 1.6
-
-This release introduced versioned installation (@pxref{API
-Versioning}). This was mainly pushed by Havoc Pennington, taking the
-GNOME source tree as motive: due to incompatibilities between the
-autotools it's impossible for the GNOME packages to switch to Autoconf
-2.53 and Automake 1.5 all at once, so they are currently stuck with
-Autoconf 2.13 and Automake 1.4.
-
-The idea was to call this version @file{automake-1.6}, call all its
-bug-fix versions identically, and switch to @file{automake-1.7} for
-the next release that adds new features or changes some rules. This
-scheme implies maintaining a bug-fix branch in addition to the
-development trunk, which means more work from the maintainer, but
-providing regular bug-fix releases proved to be really worthwhile.
-
-Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
-not. Perhaps the more annoying was the dependence on the newly
-released Autoconf 2.53. Autoconf seemed to have stabilized enough
-since its explosive 2.50 release and included changes required to fix
-some bugs in Automake. In order to upgrade to Automake 1.6, people
-now had to upgrade Autoconf too; for some packages it was no picnic.
-
-While versioned installation helped people to upgrade, it also
-unfortunately allowed people not to upgrade. At the time of writing,
-some Linux distributions are shipping packages for Automake 1.4, 1.5,
-1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
-Some distribution also call 1.4 the ``stable'' version, and present
-``1.9'' as the development version; this does not really makes sense
-since 1.9 is way more solid than 1.4. All this does not help the
-newcomer.
-
- at item 2002-04-11 Automake 1.6.1
-
-1.6, and the upcoming 1.4-p6 release were the last release by Tom.
-This one and those following will be handled by Alexandre
-Duret-Lutz. Tom is still around, and will be there until about 1.7,
-but his interest into Automake is drifting away towards projects like
- at command{gcj}.
-
-Alexandre has been using Automake since 2000, and started to
-contribute mostly on Akim's incitement (Akim and Alexandre have been
-working in the same room from 1999 to 2002). In 2001 and 2002 he had
-a lot of free time to enjoy hacking Automake.
-
- at item 2002-06-14 Automake 1.6.2
-
- at item 2002-07-28 Automake 1.6.3
- at itemx 2002-07-28 Automake 1.4-p6
-
-Two releases on the same day. 1.6.3 is a bug-fix release.
-
-Tom Tromey backported the versioned installation mechanism on the 1.4
-branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
-side by side. Another request from the GNOME folks.
-
- at item 2002-09-25 Automake 1.7
-
-This release switches to the new @file{configure.ac} scanner Akim
-was experimenting in 1.5.
-
- at item 2002-10-16 Automake 1.7.1
- at itemx 2002-12-06 Automake 1.7.2
- at itemx 2003-02-20 Automake 1.7.3
- at itemx 2003-04-23 Automake 1.7.4
- at itemx 2003-05-18 Automake 1.7.5
- at itemx 2003-07-10 Automake 1.7.6
- at itemx 2003-09-07 Automake 1.7.7
- at itemx 2003-10-07 Automake 1.7.8
-
-Many bug-fix releases. 1.7 lasted because the development version
-(upcoming 1.8) was suffering some major internal revamping.
-
- at item 2003-10-26 Automake on screen
-
-Episode 49, `Repercussions', in the third season of the `Alias' TV
-show is first aired.
-
-Marshall, one of the characters, is working on a computer virus that he
-has to modify before it gets into the wrong hands or something like
-that. The screenshots you see do not show any program code, they show
-a @file{Makefile.in} @code{generated by automake}...
-
- at item 2003-11-09 Automake 1.7.9
-
- at item 2003-12-10 Automake 1.8
-
-The most striking update is probably that of @command{aclocal}.
-
- at command{aclocal} now uses @code{m4_include} in the produced
- at file{aclocal.m4} when the included macros are already distributed
-with the package (an idiom used in many packages), which reduces code
-duplication. Many people liked that, but in fact this change was
-really introduced to fix a bug in rebuild rules: @file{Makefile.in}
-must be rebuilt whenever a dependency of @file{configure} changes, but
-all the @file{m4} files included in @file{aclocal.m4} where unknown
-from @command{automake}. Now @command{automake} can just trace the
- at code{m4_include}s to discover the dependencies.
-
- at command{aclocal} also starts using the @option{--trace} Autoconf option
-in order to discover used macros more accurately. This will turn out
-to be very tricky (later releases will improve this) as people had
-devised many ways to cope with the limitation of previous
- at command{aclocal} versions, notably using handwritten
- at code{m4_include}s: @command{aclocal} must make sure not to redefine a
-rule that is already included by such statement.
-
-Automake also has seen its guts rewritten. Although this rewriting
-took a lot of efforts, it is only apparent to the users in that some
-constructions previously disallowed by the implementation now work
-nicely. Conditionals, Locations, Variable and Rule definitions,
-Options: these items on which Automake works have been rewritten as
-separate Perl modules, and documented.
-
- at itemx 2004-01-11 Automake 1.8.1
- at itemx 2004-01-12 Automake 1.8.2
- at itemx 2004-03-07 Automake 1.8.3
- at itemx 2004-04-25 Automake 1.8.4
- at itemx 2004-05-16 Automake 1.8.5
-
- at item 2004-07-28 Automake 1.9
-
-This release tries to simplify the compilation rules it outputs to
-reduce the size of the Makefile. The complaint initially come from
-the libgcj developers. Their @file{Makefile.in} generated with
-Automake 1.4 and custom build rules (1.4 did not support compiled
-Java) is 250KB at . The one generated by 1.8 was over 9MB@! 1.9 gets it
-down to 1.2MB at .
-
-Aside from this it contains mainly minor changes and bug-fixes.
-
- at itemx 2004-08-11 Automake 1.9.1
- at itemx 2004-09-19 Automake 1.9.2
-
-Automake has ten years. This chapter of the manual was initially
-written for this occasion.
-
- at itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
-git as primary repository.
-
- at end table
-
- at node Dependency Tracking Evolution
- at section Dependency Tracking in Automake
-
-Over the years Automake has deployed three different dependency
-tracking methods. Each method, including the current one, has had
-flaws of various sorts. Here we lay out the different dependency
-tracking methods, their flaws, and their fixes. We conclude with
-recommendations for tool writers, and by indicating future directions
-for dependency tracking work in Automake.
-
- at menu
-* First Take on Dependencies:: Precomputed dependency tracking
-* Dependencies As Side Effects:: Update at developer compile time
-* Dependencies for the User:: Update at user compile time
-* Techniques for Dependencies:: Alternative approaches
-* Recommendations for Tool Writers:: What tool writers can do to help
-* Future Directions for Dependencies:: Languages Automake does not know
- at end menu
-
- at node First Take on Dependencies
- at subsection First Take on Dependency Tracking
- at unnumberedsubsubsec Description
-
-Our first attempt at automatic dependency tracking was based on the
-method recommended by GNU @command{make}. (@pxref{Automatic
-Prerequisites, , Generating Prerequisites Automatically, make, The GNU
-make Manual})
-
-This version worked by precomputing dependencies ahead of time. For
-each source file, it had a special @file{.P} file that held the
-dependencies. There was a rule to generate a @file{.P} file by
-invoking the compiler appropriately. All such @file{.P} files were
-included by the @file{Makefile}, thus implicitly becoming dependencies
-of @file{Makefile}.
-
- at unnumberedsubsubsec Bugs
-
-This approach had several critical bugs.
-
- at itemize
- at item
-The code to generate the @file{.P} file relied on @command{gcc}.
-(A limitation, not technically a bug.)
- at item
-The dependency tracking mechanism itself relied on GNU @command{make}.
-(A limitation, not technically a bug.)
- at item
-Because each @file{.P} file was a dependency of @file{Makefile}, this
-meant that dependency tracking was done eagerly by @command{make}.
-For instance, @samp{make clean} would cause all the dependency files
-to be updated, and then immediately removed. This eagerness also
-caused problems with some configurations; if a certain source file
-could not be compiled on a given architecture for some reason,
-dependency tracking would fail, aborting the entire build.
- at item
-As dependency tracking was done as a pre-pass, compile times were
-doubled--the compiler had to be run twice per source file.
- at item
- at samp{make dist} re-ran @command{automake} to generate a
- at file{Makefile} that did not have automatic dependency tracking (and
-that was thus portable to any version of @command{make}). In order to
-do this portably, Automake had to scan the dependency files and remove
-any reference that was to a source file not in the distribution.
-This process was error-prone. Also, if @samp{make dist} was run in an
-environment where some object file had a dependency on a source file
-that was only conditionally created, Automake would generate a
- at file{Makefile} that referred to a file that might not appear in the
-end user's build. A special, hacky mechanism was required to work
-around this.
- at end itemize
-
- at unnumberedsubsubsec Historical Note
-
-The code generated by Automake is often inspired by the
- at file{Makefile} style of a particular author. In the case of the first
-implementation of dependency tracking, I believe the impetus and
-inspiration was Jim Meyering. (I could be mistaken. If you know
-otherwise feel free to correct me.)
-
- at node Dependencies As Side Effects
- at subsection Dependencies As Side Effects
- at unnumberedsubsubsec Description
-
-The next refinement of Automake's automatic dependency tracking scheme
-was to implement dependencies as side effects of the compilation.
-This was aimed at solving the most commonly reported problems with the
-first approach. In particular we were most concerned with eliminating
-the weird rebuilding effect associated with make clean.
-
-In this approach, the @file{.P} files were included using the
- at code{-include} command, which let us create these files lazily. This
-avoided the @samp{make clean} problem.
-
-We only computed dependencies when a file was actually compiled. This
-avoided the performance penalty associated with scanning each file
-twice. It also let us avoid the other problems associated with the
-first, eager, implementation. For instance, dependencies would never
-be generated for a source file that was not compilable on a given
-architecture (because it in fact would never be compiled).
-
- at unnumberedsubsubsec Bugs
-
- at itemize
- at item
-This approach also relied on the existence of @command{gcc} and GNU
- at command{make}. (A limitation, not technically a bug.)
- at item
-Dependency tracking was still done by the developer, so the problems
-from the first implementation relating to massaging of dependencies by
- at samp{make dist} were still in effect.
- at item
-This implementation suffered from the ``deleted header file'' problem.
-Suppose a lazily-created @file{.P} file includes a dependency on a
-given header file, like this:
-
- at example
-maude.o: maude.c something.h
- at end example
-
-Now suppose that you remove @file{something.h} and update @file{maude.c}
-so that this include is no longer needed. If you run @command{make},
-you will get an error because there is no way to create
- at file{something.h}.
-
-We fixed this problem in a later release by further massaging the
-output of @command{gcc} to include a dummy dependency for each header
-file.
- at end itemize
-
- at node Dependencies for the User
- at subsection Dependencies for the User
- at unnumberedsubsubsec Description
-
-The bugs associated with @samp{make dist}, over time, became a real
-problem. Packages using Automake were being built on a large number
-of platforms, and were becoming increasingly complex. Broken
-dependencies were distributed in ``portable'' @file{Makefile.in}s,
-leading to user complaints. Also, the requirement for @command{gcc}
-and GNU @command{make} was a constant source of bug reports. The next
-implementation of dependency tracking aimed to remove these problems.
-
-We realized that the only truly reliable way to automatically track
-dependencies was to do it when the package itself was built. This
-meant discovering a method portable to any version of make and any
-compiler. Also, we wanted to preserve what we saw as the best point
-of the second implementation: dependency computation as a side effect
-of compilation.
-
-In the end we found that most modern make implementations support some
-form of include directive. Also, we wrote a wrapper script that let
-us abstract away differences between dependency tracking methods for
-compilers. For instance, some compilers cannot generate dependencies
-as a side effect of compilation. In this case we simply have the
-script run the compiler twice. Currently our wrapper script
-(@command{depcomp}) knows about twelve different compilers (including
-a "compiler" that simply invokes @command{makedepend} and then the
-real compiler, which is assumed to be a standard Unix-like C compiler
-with no way to do dependency tracking).
-
- at unnumberedsubsubsec Bugs
-
- at itemize
- at item
-Running a wrapper script for each compilation slows down the build.
- at item
-Many users don't really care about precise dependencies.
- at item
-This implementation, like every other automatic dependency tracking
-scheme in common use today (indeed, every one we've ever heard of),
-suffers from the ``duplicated new header'' bug.
-
-This bug occurs because dependency tracking tools, such as the
-compiler, only generate dependencies on the successful opening of a
-file, and not on every probe.
-
-Suppose for instance that the compiler searches three directories for
-a given header, and that the header is found in the third directory.
-If the programmer erroneously adds a header file with the same name to
-the first directory, then a clean rebuild from scratch could fail
-(suppose the new header file is buggy), whereas an incremental rebuild
-will succeed.
-
-What has happened here is that people have a misunderstanding of what
-a dependency is. Tool writers think a dependency encodes information
-about which files were read by the compiler. However, a dependency
-must actually encode information about what the compiler tried to do.
-
-This problem is not serious in practice. Programmers typically do not
-use the same name for a header file twice in a given project. (At
-least, not in C or C++. This problem may be more troublesome in
-Java.) This problem is easy to fix, by modifying dependency
-generators to record every probe, instead of every successful open.
-
- at item
-Since Automake generates dependencies as a side effect of compilation,
-there is a bootstrapping problem when header files are generated by
-running a program. The problem is that, the first time the build is
-done, there is no way by default to know that the headers are
-required, so make might try to run a compilation for which the headers
-have not yet been built.
-
-This was also a problem in the previous dependency tracking implementation.
-
-The current fix is to use @code{BUILT_SOURCES} to list built headers
-(@pxref{Sources}). This causes them to be built before any other
-build rules are run. This is unsatisfactory as a general solution,
-however in practice it seems sufficient for most actual programs.
- at end itemize
-
-This code is used since Automake 1.5.
-
-In GCC 3.0, we managed to convince the maintainers to add special
-command-line options to help Automake more efficiently do its job. We
-hoped this would let us avoid the use of a wrapper script when
-Automake's automatic dependency tracking was used with @command{gcc}.
-
-Unfortunately, this code doesn't quite do what we want. In
-particular, it removes the dependency file if the compilation fails;
-we'd prefer that it instead only touch the file in any way if the
-compilation succeeds.
-
-Nevertheless, since Automake 1.7, when a recent @command{gcc} is
-detected at @command{configure} time, we inline the
-dependency-generation code and do not use the @command{depcomp}
-wrapper script. This makes compilations faster for those using this
-compiler (probably our primary user base). The counterpart is that
-because we have to encode two compilation rules in @file{Makefile}
-(with or without @command{depcomp}), the produced @file{Makefile}s are
-larger.
-
- at node Techniques for Dependencies
- at subsection Techniques for Computing Dependencies
-
-There are actually several ways for a build tool like Automake to
-cause tools to generate dependencies.
-
- at table @asis
- at item @command{makedepend}
-This was a commonly-used method in the past. The idea is to run a
-special program over the source and have it generate dependency
-information. Traditional implementations of @command{makedepend} are
-not completely precise; ordinarily they were conservative and
-discovered too many dependencies.
- at item The tool
-An obvious way to generate dependencies is to simply write the tool so
-that it can generate the information needed by the build tool. This is
-also the most portable method. Many compilers have an option to
-generate dependencies. Unfortunately, not all tools provide such an
-option.
- at item The file system
-It is possible to write a special file system that tracks opens,
-reads, writes, etc, and then feed this information back to the build
-tool. @command{clearmake} does this. This is a very powerful
-technique, as it doesn't require cooperation from the
-tool. Unfortunately it is also very difficult to implement and also
-not practical in the general case.
- at item @code{LD_PRELOAD}
-Rather than use the file system, one could write a special library to
-intercept @code{open} and other syscalls. This technique is also quite
-powerful, but unfortunately it is not portable enough for use in
- at command{automake}.
- at end table
-
- at node Recommendations for Tool Writers
- at subsection Recommendations for Tool Writers
-
-We think that every compilation tool ought to be able to generate
-dependencies as a side effect of compilation. Furthermore, at least
-while @command{make}-based tools are nearly universally in use (at
-least in the free software community), the tool itself should generate
-dummy dependencies for header files, to avoid the deleted header file
-bug. Finally, the tool should generate a dependency for each probe,
-instead of each successful file open, in order to avoid the duplicated
-new header bug.
-
- at node Future Directions for Dependencies
- at subsection Future Directions for Dependencies
-
-Currently, only languages and compilers understood by Automake can
-have dependency tracking enabled. We would like to see if it is
-practical (and worthwhile) to let this support be extended by the user
-to languages unknown to Automake.
-
- at node Releases
- at section Release Statistics
-
-The following table (inspired by @samp{perlhist(1)}) quantifies the
-evolution of Automake using these metrics:
-
- at table @asis
- at item Date, Rel
-The date and version of the release.
- at item am
-The number of lines of the @command{automake} script.
- at item acl
-The number of lines of the @command{aclocal} script.
- at item pm
-The number of lines of the @command{Perl} supporting modules.
- at item @file{*.am}
-The number of lines of the @file{Makefile} fragments. The number in
-parentheses is the number of files.
- at item m4
-The number of lines (and files) of Autoconf macros.
- at item doc
-The number of pages of the documentation (the Postscript version).
- at item t
-The number of test cases in the test suite. Of those, the number in
-parentheses is the number of generated test cases.
- at end table
-
- at multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
- at headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
- at item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
- at item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
- at item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
- at item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
- at item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
- at item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
- at item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
- at item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
- at item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
- at item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
- at item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
- at item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
- at item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
- at item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
- at item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
- at item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
- at item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
- at item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
- at item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
- at item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
- at item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
- at item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
- at item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
- at item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
- at item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
- at item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
- at item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
- at item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
- at item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
- at item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
- at item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
- at item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
- at item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
- at item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
- at item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
- at item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
- at item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
- at item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
- at item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
- at item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
- at item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
- at item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
- at item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
- at item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
- at item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
- at item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
- at item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
- at item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
- at item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
- at item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
- at item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
- at item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
- at item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
- at item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
- at item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
- at item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
- at item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
- at item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
- at item 2009-12-07 @tab 1.10.3 @tab 7892 @tab 1089 @tab 8027 @tab 3566 (40) @tab 1535 (34) @tab 174 @tab 636
- at item 2009-12-07 @tab 1.11.1 @tab 8722 @tab 1092 @tab 8292 @tab 4162 (42) @tab 1730 (37) @tab 181 @tab 739 (20)
- at item 2011-12-21 @tab 1.11.2 @tab 8822 @tab 1112 @tab 8330 @tab 4223 (42) @tab 1821 (38) @tab 189 @tab 915 (22)
- at item 2012-02-01 @tab 1.11.3 @tab 8790 @tab 1068 @tab 8453 @tab 4280 (42) @tab 1852 (38) @tab 190 @tab 932 (22)
- at end multitable
-
+suite failures, please attach the @file{test-suite.log} file.
@c ========================================================== Appendices
@@ -13539,12 +13091,12 @@ parentheses is the number of generated test cases.
@c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
@c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
@c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
- at c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
+ at c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
@c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
@c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
@c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
@c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
- at c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
+ at c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
@c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
@c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
@c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
@@ -13554,10 +13106,10 @@ parentheses is the number of generated test cases.
@c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
@c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
@c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
- at c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
+ at c LocalWords: dirlist noindent usr TIOCGWINSZ sc
@c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
@c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
- at c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
+ at c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
@c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
@c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
@c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
@@ -13565,6 +13117,7 @@ parentheses is the number of generated test cases.
@c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
@c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
@c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
+ at c LocalWords: OBJCXXFLAGS
@c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
@c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
@c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
@@ -13586,7 +13139,7 @@ parentheses is the number of generated test cases.
@c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
@c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
@c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
- at c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
+ at c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
@c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
@c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
@c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
@@ -13612,4 +13165,4 @@ parentheses is the number of generated test cases.
@c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
@c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
@c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
- at c LocalWords: barexec Pinard's automatize initialize lzip lzma xz
+ at c LocalWords: barexec Pinard's automatize initialize lzip xz cscope
diff --git a/debian/docs/src/automake/1.11.5/fdl.texi b/debian/docs/src/automake/1.13.3/fdl.texi
similarity index 99%
copy from debian/docs/src/automake/1.11.5/fdl.texi
copy to debian/docs/src/automake/1.13.3/fdl.texi
index 8805f1a..bcabd3a 100644
--- a/debian/docs/src/automake/1.11.5/fdl.texi
+++ b/debian/docs/src/automake/1.13.3/fdl.texi
@@ -5,7 +5,7 @@
@c hence no sectioning command or @node.
@display
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 2000-2013 Free Software Foundation, Inc.
@uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
@@ -151,7 +151,7 @@ COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
+copies in covers that carry, clearly and legibly, all of these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
diff --git a/debian/docs/src/automake/1.13.3/version.texi b/debian/docs/src/automake/1.13.3/version.texi
new file mode 100644
index 0000000..13d2972
--- /dev/null
+++ b/debian/docs/src/automake/1.13.3/version.texi
@@ -0,0 +1,4 @@
+ at set UPDATED 3 June 2013
+ at set UPDATED-MONTH June 2013
+ at set EDITION 1.13.3
+ at set VERSION 1.13.3
diff --git a/debian/patches/autotools-add-distro-version-to-list.patch b/debian/patches/autotools-add-distro-version-to-list.patch
index 37167e1..edaf8c3 100644
--- a/debian/patches/autotools-add-distro-version-to-list.patch
+++ b/debian/patches/autotools-add-distro-version-to-list.patch
@@ -24,7 +24,7 @@ index 5755bfb..5496bc3 100644
public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
- public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"}; // $NON-NLS-1$
-+ public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5"}; // $NON-NLS-1$
++ public static final String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3"}; // $NON-NLS-1$
public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
public static final String CLEAN_MAKE_TARGET_DEFAULT = "distclean"; // $NON-NLS-1$
@@ -41,7 +41,7 @@ index 3fda416..b65a848 100644
public static final String LATEST_AC_VERSION = fACVersions[fACVersions.length - 1];
- private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1"};
-+ private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5"};
++ private static String[] fAMVersions = {"1.4-p6", "1.9.5", "1.9.6", "1.11.1", "1.11.5", "1.13.3"};
public static final String LATEST_AM_VERSION = fAMVersions[fAMVersions.length - 1];
/** The keys of the overlay store. */
--
eclipse-cdt - Plug-in for eclipse to handle C/C++ - Debian package.
More information about the pkg-java-commits
mailing list