* 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}
* Not Enough:: When Automake is not Enough
* Distributing:: Distributing the Makefile.in
* API Versioning:: About compatibility between Automake versions
Autoconf macros supplied with Automake
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that will soon be removed.
* Private Macros:: Macros that you should not use.
Directories
* 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
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
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@footnote{Older Autoconf versions used
-@file{configure.in}. Autoconf 2.50 and greater promotes
-@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
VPATH builds have other interesting uses. One is to build the same
sources with multiple configurations. For instance:
-@c Keep in sync with amhello-cflags.test.
+@c Keep in sync with amhello-cflags.sh
@example
~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
~ % @kbd{cd amhello-1.0}
Here is how we could build @code{amhello-1.0} for
@code{i586-mingw32msvc} on a GNU/Linux PC.
-@c Keep in sync with amhello-cross-compile.test.
+@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
For instance here is how we could create a binary package containing a
snapshot of all the files to be installed.
-@c Keep in sync with amhello-binpkg.test.
+@c Keep in sync with amhello-binpkg.sh
@example
~/amhello-1.0 % @kbd{./configure --prefix /usr}
@dots{}
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.
-@c Keep this in sync with doc-parsing-buglets-tabs.test.
+@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.
-@c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
+@c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
Also, using more complex macro in target names can cause trouble:
@example
variables referenced in the definition. For example, if Automake is
looking at the content of @code{foo_SOURCES} in this snippet
-@c Keep in sync with interp.test.
+@c Keep in sync with interp.sh
@example
xs = a.c b.c
foo_SOURCES = c.c $(xs)
@xref{Gnits}, for more information on the precise implications of the
strictness level.
-Automake also has a special ``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., the GCC tree).
-@xref{Cygnus}, for more information on this mode.
-
@node Uniform
@section The Uniform Naming Scheme
For instance, the following snippet will install @file{file.xml} into
@samp{$(datadir)/xml}.
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
xmldir = $(datadir)/xml
xml_DATA = file.xml
unlikely case these checks are undesirable, and you really know what
you're doing). For example, Automake would error out on this input:
-@c Should be tested in primary-prefix-invalid-couples.test.
+@c Should be tested in primary-prefix-invalid-couples.sh
@example
# Forbidden directory combinations, automake will error out on this.
pkglib_PROGRAMS = foo
@noindent
but it will succeed with this:
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@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!
@noindent
may also be written as
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
data_DATA = file1 @dots{} file@var{N}
data2dir = $(datadir)
@code{false} in real life, you would probably use per-program
compilation flags, like so:
-@c Keep in sync with specflg7.test and specflg8.test.
+@c Keep in sync with specflg7.sh and specflg8.sh
@example
bin_PROGRAMS = false true
When used with @option{--add-missing}, causes installed files to be
copied. The default is to make a symbolic link.
-@item --cygnus
-@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}.
-
@item -f
@opindex -f
@itemx --force-missing
The categories output by default are @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.
-@c Checked by extra-portability.test
+@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
@command{automake} will not be able to fulfill this setup, and you will
have to complete the missing bits by hand. For instance, on
-@c Keep in sync with output11.test.
+@c Keep in sync with output11.sh
@example
file=input
@dots{}
Similarly
-@c Keep in sync with output11.test.
+@c Keep in sync with output11.sh
@example
file=output
file2=out:in
@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.
+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
This is required if any Objective C source is included. @xref{Particular
Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
+@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
Install system-wide third-party macros into the first directory
specified with @samp{-I @var{dir}} instead of copying them in the
output file.
-@c The following semantics is checked by `aclocal-install-absdir.test'.
+@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}
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
-@c Keep in sync with aclocal-path-precedence.test.
+@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}.
-@c Keep in sync with aclocal-path-installed.test.
+@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.
-@c Keep in sync with aclocal-path-installed-serial.test.
+@c Keep in sync with aclocal-path-installed-serial.sh
In this case, serial numbers in @file{.m4} are honoured too,
@pxref{Serials}.
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:
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
aclocaldir = $(datadir)/aclocal
aclocal_DATA = mymacro.m4 myothermacro.m4
@example
# bad style
-AC_PREREQ(2.57)
+AC_PREREQ(2.68)
AC_DEFUN(AX_FOOBAR,
[AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
@example
AC_DEFUN([AX_FOOBAR],
-[AC_PREREQ([2.57])dnl
+[AC_PREREQ([2.68])dnl
AC_REQUIRE([AX_SOMETHING])dnl
AX_FOO
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
@menu
* Public Macros:: Macros that you can use.
-* Obsolete Macros:: Macros that will soon be removed.
* Private Macros:: Macros that you should not use.
@end menu
@acindex AC_INIT
This macro can also be called in @emph{another, deprecated form} (support
-for which will be @emph{removed in the next major Automake release}):
+for which will be @emph{removed in the next major Automake release (1.13)}):
@code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
there are 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).
+@anchor{Modernize AM_INIT_AUTOMAKE invocation}
If your @file{configure.ac} has:
@example
@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
@end table
-@node Obsolete Macros
-@subsection Obsolete Macros
-@cindex obsolete macros
-@cindex autoupdate
-
-Although using some of the following macros was required in past
-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
-@file{configure.ac}, autoconf, The Autoconf Manual}).
-@emph{Do it NOW!}
-
-@table @code
-
-@item AM_CONFIG_HEADER
-@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}).
-
-@item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
-@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
-@cindex @code{mkdir -p}, macro check
-@vindex MKDIR_P
-@vindex mkdir_p
-
-From Automake 1.8 to 1.9.6 this macro used to define the output
-variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
--d}, or @code{mkinstalldirs}.
-
-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. 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 @emph{will be
-removed} in the next major Automake release.
-
-@item AM_SYS_POSIX_TERMIOS
-@acindex AM_SYS_POSIX_TERMIOS
-@cindex POSIX termios headers
-@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
-@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.
-
-@end table
-
-
@node Private Macros
@subsection Private Macros
@cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
@cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
-@c Keep in sync with subcond2.test.
+@c Keep in sync with subcond2.sh
@file{configure} should output the @file{Makefile} for each directory
and define a condition into which @file{opt/} should be built.
@cindex @code{SUBDIRS} and @code{AC_SUBST}
@cindex @code{AC_SUBST} and @code{SUBDIRS}
-@c Keep in sync with subcond3.test.
+@c Keep in sync with subcond3.sh
Another possibility is to define @code{MAYBE_OPT} from
@file{./configure} using @code{AC_SUBST}:
directory (@pxref{Uniform}). For instance, the last example could be
rewritten as follows:
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
imagesdir = $(pkgdatadir)/images
soundsdir = $(pkgdatadir)/sounds
* 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
select programs to be built. In this case you don't have to worry
about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
-@c Keep in sync with exeext.test.
+@c Keep in sync with exeext.sh
@example
bin_PROGRAMS = cpio pax
if WANT_MT
@code{@var{library}_LIBADD} variable. This should be used for objects
determined by @command{configure}. Again from @code{cpio}:
-@c Keep in sync with pr401c.test.
+@c Keep in sync with pr401c.sh
@example
libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
@end example
the link rule for these two libraries. Therefore the @option{-rpath}
argument must be explicitly supplied.
-@c Keep in sync with ltcond.test.
+@c Keep in sync with ltcond.sh
@example
EXTRA_LTLIBRARIES = libfoo.la libbar.la
lib_LTLIBRARIES = $(WANTEDLIBS)
it's clear that both libraries will end up in @samp{$(libdir)} if they
are installed.
-@c Keep in sync with ltcond.test.
+@c Keep in sync with ltcond.sh
@example
lib_LTLIBRARIES =
if WANT_LIBFOO
@file{hello-linux.c} or @file{hello-generic.c} with the following
@file{Makefile.am}.
-@c Keep in sync with ltcond2.test.
+@c Keep in sync with ltcond2.sh
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
Or we could simply use an Automake conditional as follows.
-@c Keep in sync with ltcond2.test.
+@c Keep in sync with ltcond2.sh
@example
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello-common.c
Here is a sample setup merging libtool convenience libraries from
subdirectories into one main @file{libtop.la} library.
-@c Keep in sync with ltconv.test.
+@c Keep in sync with ltconv.sh
@example
# -- Top-level Makefile.am --
SUBDIRS = sub1 sub2 @dots{}
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
-@command{libtool} can also be influenced with the Automake
-@option{silent-rules} option (@pxref{Options}).
-
+@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}
@itemx maude_GCJFLAGS
@itemx maude_LFLAGS
@itemx maude_OBJCFLAGS
+@itemx maude_OBJCXXFLAGS
@itemx maude_RFLAGS
@itemx maude_UPCFLAGS
@itemx maude_YFLAGS
@samp{_GCJFLAGS},
@samp{_LFLAGS},
@samp{_OBJCFLAGS},
+@samp{_OBJCXXFLAGS},
@samp{_RFLAGS},
@samp{_UPCFLAGS}, and
@samp{_YFLAGS}.
@end vtable
+@node Objective C++ Support
+@section Objective C++ Support
+
+@cindex Objective C++ support
+@cindex Support for Objective C++
+
+Automake includes some support for Objective C++.
+
+Any package including Objective C++ code must define the output variable
+@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:
+
+@vtable @code
+@item OBJCXX
+The name of the Objective C++ compiler.
+
+@item OBJCXXFLAGS
+Any flags to pass to the Objective C++ compiler.
+
+@item AM_OBJCXXFLAGS
+The maintainer's variant of @code{OBJCXXFLAGS}.
+
+@item OBJCXXCOMPILE
+The command used to actually compile an Objective C++ source file. The
+file name is appended to form the complete command line.
+
+@item OBJCXXLINK
+The command used to actually link an Objective C++ program.
+@end vtable
+
+
@node Unified Parallel C Support
@section Unified Parallel C Support
@cindex @code{FLIBS}, defined
@vindex FLIBS
These extra Fortran 77 linker flags are supplied in the output variable
-@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}.
+@code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
+@xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
+The Autoconf Manual}.
@end enumerate
If Automake detects that a program or shared library (as mentioned in
@vindex GCJLINK
Native Java (@code{GCJLINK})
@item
+@vindex OBJCXXLINK
+Objective C++ (@code{OBJCXXLINK})
+@item
@vindex CXXLINK
C++ (@code{CXXLINK})
@item
@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
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
-@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
Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
lisp_DATA = file1.el file2.el
@end example
Here is a typical setup for distributing @file{.java} files and
installing the @file{.class} files resulting from their compilation.
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@c Keep in sync with primary-prefix-couples-documented-valid.sh
@example
javadir = $(datadir)/java
dist_java_JAVA = a.java b.java @dots{}
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
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@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
should be installed. An extension module written in C could be declared
as follows to Automake:
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@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
request this explicitly using @samp{make install-info}.
@vindex AM_UPDATE_INFO_DIR
-By default, @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. If this is undesired, it
-can be prevented by exporting the @code{AM_UPDATE_INFO_DIR} variable
-to "@code{no}".
+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.
+If this is undesired, it can be prevented by exporting the
+@code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
The following variables are used by the Texinfo build rules.
@samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
files.
-@c Keep in sync with txinfo21.test.
+@c Keep in sync with txinfo21.sh
For instance, the following setting can be used to obtain one single
@file{.html} file per manual, without node separators.
@example
Any variable using a user-defined directory prefix with
@samp{exec} in the name (e.g.,
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@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}.
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,
-@c Keep in sync with autodist-config-headers.test.
+@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}
been cleaned because they are also part of the distribution, add the
following definition instead:
-@c Keep in sync with distcleancheck.test.
+@c Keep in sync with distcleancheck.sh
@example
distcleancheck_listfiles = \
find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
enable such protocols only when the parallel harness is used: they won't
work with the serial test harness. In the rest of this section we are
-going to concentrate mostly on protocol-less tests, since we'll have later
-a whole section devoted to the use of test protocols (again, @pxref{Custom
-Test Drivers}).
+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
@cindex Exit status 99, special interpretation
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,
-@c Keep this in sync with tap-no-disable-hard-errors.test.
+@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
@code{DISABLE_HARD_ERRORS} variable has no effect on them).
@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:
-@c Keep in sync with tap-doc.test.
+@c Keep in sync with tap-doc.sh
@example
PASS: foo.sh
PASS: zardoz.tap 1 - Daemon started
@c FIXME: should we offer a link to the relevant discussions on the
@c bug-autoconf list?
-@c Keep in sync with tests-environment-backcompat.test.
+@c Keep in sync with tests-environment-backcompat.sh
@example
AM_TESTS_ENVIRONMENT = \
## Some environment initializations are kept in a separate shell
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.
-@c Keep in sync with test-extensions.test.
+@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.
tests without a registered extension, the variables @code{LOG_COMPILER},
@code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
-@c Keep in sync with parallel-tests-log-compiler-example.test.
+@c Keep in sync with parallel-tests-log-compiler-example.sh
@example
TESTS = foo.pl bar.py baz
TEST_EXTENSIONS = .pl .py
easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
for example,
-@c Keep in sync with parallel-tests-log-override-2.test.
+@c Keep in sync with parallel-tests-log-override-2.sh
@example
env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
@end example
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 grab the @file{tap-driver.sh}
+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
compatibility with the @command{prove} utility.
@table @option
-@c Keep in sync with 'tap-exit.test' and 'tap-signal.test'.
+@c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
@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 exit with a
-non-zero status. This option has effect also
+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.
@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 in the @file{.log} file.
+default, TAP diagnostic is only copied to the @file{.log} file.
@item --no-comments
Revert the effects of @option{--comments}.
@item --merge
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 by other tools invoked in the
+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
@noindent
Here is an example of how the TAP driver can be set up and used.
-@c Keep in sync with tap-doc2.test.
+@c Keep in sync with tap-doc2.sh
@example
% @kbd{cat configure.ac}
AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
#!/bin/sh
echo 1..1
echo ok 1
-# Exit with error, even if all the test case has been successful.
+# Exit with error, even if all the tests have been successful.
exit 7
% @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
@itemize @bullet
@item
A @code{Bail out!} directive doesn't stop the whole testsuite, but only
-the test script it occurs into. This doesn't follows TAP specifications,
+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 @option{parallel-tests} driver.
@item
The @code{version} and @code{pragma} directives are not supported.
@item
-The @option{--diagnostic-string} option of out driver allows to modify
+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
@item @option{gnits}
@itemx @option{gnu}
@itemx @option{foreign}
-@itemx @option{cygnus}
@cindex Option, @option{gnits}
@cindex Option, @option{gnu}
@cindex Option, @option{foreign}
-@cindex Option, @option{cygnus}
@opindex gnits
@opindex gnu
@opindex foreign
-@opindex cygnus
Set the strictness as appropriate. The @option{gnits} option also
implies options @option{readme-alpha} and @option{check-news}.
@samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
letter; it should be omitted for non-alpha releases.
-@item @option{silent-rules}
-@cindex Option, @option{silent-rules}
-@opindex silent-rules
-Enable less verbose build rules. This can be used to let build rules
-output status lines of the form:
-@example
-GEN @var{output-file}
- CC @var{object-file}
-@end example
-@noindent
-instead of printing the command that will be executed to update
-@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}
the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
@file{.cpp} files.
-@c Keep in sync with suffix7.test.
+@c Keep in sync with suffix7.sh
@example
SUFFIXES = .idl C.cpp
.idlC.cpp:
@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
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
@end itemize
-@node Automake silent-rules Option
+@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:
CCLD foo
@end example
-@cindex silent-rules and libtool
+@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:
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:
-
-@itemize @bullet
-@item
-Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
-@item
-Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
-file.
-@end itemize
-
-It is not possible to instead specify @option{silent-rules} in a
-@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
@code{make V=0} less verbose output.
@end itemize
-@cindex default verbosity for silent-rules
+@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
-@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}.
-@c Keep in sync with silent-configsite.test
+@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
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
-@option{-Wportability} (@pxref{automake Invocation}). 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
+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}
@end itemize
-@node Cygnus
-@chapter The effect of @option{--cygnus}
-
-@cindex @option{cygnus} strictness
-
-Some packages, notably GNU GCC and GNU gdb, 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
-@file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
-@command{automake} will cause any generated @file{Makefile.in} to
-comply with Cygnus rules.
-
-Here are the precise effects of @option{--cygnus}:
-
-@itemize @bullet
-@item
-Info files are always created in the build directory, and not in the
-source directory.
-
-@item
-@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. This assumption is an artifact of how
-Cygnus packages are typically bundled.
-
-@item
-@samp{make dist} is not supported, and the rules for it are not
-generated. Cygnus-style trees use their own distribution mechanism.
-
-@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},
-@command{makeinfo} and @command{texi2dvi}.
-
-@item
-@option{--foreign} is implied.
-
-@item
-The options @option{no-installinfo} and @option{no-dependencies} are
-implied.
-
-@item
-The macro @code{AM_MAINTAINER_MODE} is required.
-
-@item
-The @code{check} target doesn't depend on @code{all}.
-@end itemize
-
-GNU maintainers are advised to use @option{gnu} strictness in preference
-to the special Cygnus mode. Some day, perhaps, the differences between
-Cygnus trees and GNU trees will disappear (for instance, as GCC is made
-more standards compliant). At that time the special Cygnus mode will be
-removed.
-
-
@node Not Enough
@chapter When Automake Isn't Enough
For instance, here is how you could install a versioned copy of a
program using @samp{$(LN_S)}:
-@c Keep in sync with insthook.test
+@c Keep in sync with insthook.sh
@example
install-exec-hook:
cd $(DESTDIR)$(bindir) && \
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}).
-@c Keep in sync with primary-prefix-couples-documented-valid.test.
+@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.
@cindex @code{AM_LFLAGS} and @code{LFLAGS}
@cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
@cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
+@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}
@cindex @code{LFLAGS} and @code{AM_LFLAGS}
@cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
@cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
+@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}
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},
-@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
-@code{UPCFLAGS}, and @code{YFLAGS}.
+@code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
+@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
@itemize
@item
-If less verbose output has been enabled in the package with the
-@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
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.
+suite failures, please attach the @file{test-suite.log} file.
@c ========================================================== Appendices
@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
-@c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
+@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: 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
+@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