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
that is then used by the automatic dependency tracking feature
(@pxref{Dependencies}).
-@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.
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.
@file{config.guess},
@file{config.sub},
@file{depcomp},
-@file{elisp-comp},
@file{compile},
@file{install-sh},
@file{ltmain.sh},
numerous macros, it will rapidly become difficult to maintain, and it
will be almost impossible to share macros between packages.
-@vindex ACLOCAL_AMFLAGS
The second possibility, which we do recommend, is to write each macro
-in its own file and gather all of 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
-
-@example
-ACLOCAL_AMFLAGS = -I m4
-@end example
-
-@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
-@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
-@code{ACLOCAL_AMFLAGS}.
-
-When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
+in its own file and gather all these files in a directory. This
+directory is usually called @file{m4/}. Then it's enough to update
+@file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIR}:
+
+@example
+AC_CONFIG_MACRO_DIR([m4])
+@end example
+
+@command{aclocal} will then take care of automatically adding @file{m4/}
+to its search path for m4 files.
+
+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}.
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:
-
-@example
-ACLOCAL_AMFLAGS = -I m4 --install
-@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.
-@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}
explained in @ref{Local Macros}, and has
@example
-ACLOCAL_AMFLAGS = -I m4 --install
+AC_CONFIG_MACRO_DIR([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
-@command{autoreconf}, it will fetch the options to pass to
-@command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
---install}. @command{aclocal} will notice that
+@command{aclocal --install}, it will notice that
@itemize @bullet
@item
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
-@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
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
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
-@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
+@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
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)
+@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
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}".
rm -rf `find $(distdir)/doc -type d -name .svn`
@end example
-@c The caveates described here should be documented in 'disthook.test'.
+@c The caveates described here should be documented in 'disthook.sh'.
@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
@anchor{Simple tests and color-tests}
@vindex AM_COLOR_TESTS
@cindex Colorized testsuite output
-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
-@samp{AM_COLOR_TESTS=no}, or 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, you'll have to
-resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
-testsuite output colorized.
+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
+@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
+@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
concurrent execution.
@cindex Unit tests
-@c Keep in sync with 'parallel-tests-extra-programs.test'.
+@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
@end itemize
@noindent
-On the other hand, the exact semantics of how (and if)
-@option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
-and handled is left to the individual test drivers.
+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.
@c TODO: We should really add a working example in the doc/ directory,
@c TODO: and reference if from here.
test; the harness will ignore such extra text when generating
@file{test-suite.log} and preparing the testsuite summary.
-@c Keep in sync with 'test-metadata-recheck.test'.
+@c Keep in sync with 'test-metadata-recheck.sh'.
@item @code{:recheck:}
@cindex :recheck:
@cindex reStructuredText field, @code{:recheck:}
happens when two or more @code{:recheck:} fields are present in the same
@file{.trs} file is undefined behaviour.
-@c Keep in sync with 'test-metadata-global-log.test'.
+@c Keep in sync with 'test-metadata-global-log.sh'.
@item @code{:copy-in-global-log:}
@cindex :copy-in-global-log:
@cindex reStructuredText field, @code{:copy-in-global-log:}
successful. What happens when two or more @code{:copy-in-global-log:}
fields are present in the same @file{.trs} file is undefined behaviour.
-@c Keep in sync with 'test-metadata-global-result.test'.
+@c Keep in sync with 'test-metadata-global-result.sh'.
@item @code{:test-global-result:}
@cindex :test-global-result:
@cindex reStructuredText field, @code{:test-global-result:}
compatibility with the @command{prove} utility.
@table @option
-@c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
+@c Keep in sync with 'tap-exit.sh' 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 exits with a
If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
these automatic rebuilding rules are only enabled in maintainer mode.
-@vindex ACLOCAL_AMFLAGS
-Sometimes you need to run @command{aclocal} with an argument like
-@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
-@code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
-to @command{aclocal}. This variable is only useful in the top-level
-@file{Makefile.am}.
-
@vindex CONFIG_STATUS_DEPENDENCIES
@vindex CONFIGURE_DEPENDENCIES
@cindex @file{version.sh}, example
Cause @samp{make dist} to fail unless the current version number appears
in the first few lines of the @file{NEWS} file.
-@item @option{color-tests}
-@cindex Option, @option{color-tests}
-@opindex color-tests
-Cause output of the serial and parallel test harnesses (see @ref{Simple
-Tests}) and of properly-written custom test drivers (@pxref{Custom Test
-Drivers}) to be colorized on capable terminals.
-
@item @option{dejagnu}
@cindex Option, @option{dejagnu}
@opindex dejagnu
@code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
@command{make} itself.
-However you should not think that all variables ending with @code{FLAGS}
-follow this convention. For instance, @code{ACLOCAL_AMFLAGS} (see
-@ref{Rebuilding} and @ref{Local Macros}) is a variable that is only
-useful to the maintainer and has no user counterpart.
-
@code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
has neither @code{AM_} nor per-target cousin.