blob: 690abf089596e233102c1a8500da68c56c3cf347 [file] [log] [blame]
This file lists the major changes and differences between mainstream
Automake and Automake-NG. Be aware that there is likely a plethora
of other minor differences and incompatibilities *not* listed here.
Automatic dependency tracking support
=====================================
* The generated Makefile.in files use "-include", not "include", to
read the '.Po' files containing automatically computed dependency
information.
* We unconditionally assume that the "include" and "-include"
directives can be used in the generated Makefiles. Accordingly,
the internal m4 macro 'AM_MAKE_INCLUDE' and AC_SUBST'd variables
'am__include' and 'am__quote' have been removed.
* The makefile fragments files containing automatically computed
dependency information are created at make runtime by Makefile
recipes, not at configure time by config.status. Accordingly,
the special config.status argument 'depfiles' is not supported
anymore.
Silent rules
============
* The silent rules support has been simplified to take advantage
of more GNU make features. Among other things, the AC_SUBST'd
variables '@AM_V@' and'@AM_DEFAULT_V@' have been removed. Now,
when defining uses custom silent rules, you should do something
like:
# Modern correct way.
pkg_verbose = $(pkg_verbose/$(V))
pkg_verbose/0 = @echo PKG-GEN $@;
pkg_verbose/1 =
while the old idiom would have been something like:
# Old obsolete way, won't work anymore.
pkg_verbose = $(pkg_verbose_@AM_V@)
pkg_verbose_ = $(pkg_verbose_@AM_DEFAULT_V@)
pkg_verbose_0 = @echo PKG-GEN $@;
Warnings and diagnostic
=======================
* Automake does not warn anymore about:
- non-POSIX variable names, like "$(dash-separated)" or "$(stem/base)";
- nested variable expansions, like "$(foo$(V))";
- variable definitions with indirections, like "var$(i) = value";
- calls to make functions, whether built-in ones like "$(wildcard *.c)"
or user-defined ones like "$(call my-func, arg1, arg2)".
- pattern rules in GNU make style ("%.o: %.c").
- variable definitions with ":=", as in "foo := $(immediate-evaluation)".
- some issues specific to BSD make.
* The 'portability-recursive' warning category is obsolete, and has been
removed.
* Automake-NG is less smart than mainline Automake in detecting some kind
of possible typos or suspicious usages at automake runtime. This is due
to the fact that more processing and logic takes place in the generated
Makefiles rather than in the automake script, so that the latter has
access to less context and information.
* Diagnostic about possible typos in '_SOURCES', '_LIBADD, '_LDFLAGS',
'_LDADD' and '_DEPENDENCIES' variables is now done at make runtime
rather than at automake runtime. In case some (or all) such diagnostic
is undesired, it can be silenced by adding the affected variables to
the 'AM_VARTYPOS_WHITELIST' variable, as in:
bin_PROGRAMS = cp mv
copy_LDADD = -lselinux -lrt -acl
cp_LDADD = $(copy_LDADD)
mv_LDADD = $(copy_LDADD)
# Without this, the generated Makefile would complain that
# no program or library has 'copy' as canonical name.
AM_VARTYPOS_WHITELIST = copy_LDADD
Compilation and Object Files
=============================
* If a source file is placed in a subdirectory, the corresponding compiled
object will always be put into the subdirectory named after the source
file, rather than in the current directory. For instance, 'src/file.c'
and 'src/file.f90' will be compiled to 'src/file.o', and 'sub/dir/mu.cc'
will be compiled to 'sub/dir/mu.o'.
That is, Automake-NG will unconditionally behave as Automake would do if
its 'subdir-objects' option were active.
Serial testsuite harness (obsolescent)
======================================
* The $(TESTS) and $(XFAIL_TESTS) variables are not anymore rewritten for
$(EXEEXT) appending. The use of compiled programs in $(TESTS) and
$(XFAIL_TESTS) still works as before though, even on systems where
$(EXEEXT) is non-empty.
Parallel testsuite harness
==========================
* Automake does not automatically generate the definition of 'LOG_COMPILE'
variables anymore. These have always been meant for internal use only
anyway.
* The $(TESTS) and $(XFAIL_TESTS) variables are not anymore rewritten for
$(EXEEXT) appending. The use of compiled programs in $(TESTS) still
works as before though, even on systems where $(EXEEXT) is non-empty,
thanks to a careful use of pattern rules.
* The new implementation of the parallel-tests harness tries to defer
as much as possible processing on the $(TESTS), $(XFAIL_TESTS) and
$(TEST_EXTENSIONS) variable at make runtime, rather than doing it at
automake time. This has several positive effects (described below),
but also entails a minor annoyance: due to implementation reasons, the
'test-driver' auxiliary script is now always required and distributed,
even if no test script actually uses it as its LOG_DRIVER script.
This is not a big deal in practice, since as of today, all the real
world packages out there actually use 'test-driver' for most (if not
all) of their tests (the introduction of TAP support in mainstream
automake being too recent for those packages to have had time to phase
out their protocol-less tests, assuming they wanted to -- which is
usually not the case either).
* The parallel testsuite harness realizes whether an entry of $(TESTS)
start with $(srcdir) (as in "TESTS = $(srcdir)/foo.test"), and manages
to correctly create the corresponding '.log' and '.trs' files in the
build directory rather than in the source directory.
* The contents of $(TESTS) are mostly analyzed at make runtime rather
than at automake runtime, so that it is now possible to use GNU make
advanced features (like specific builtins or user-defined functions)
in the definition of $(TESTS); for example, the following should now
work as expected:
TESTS = $(wildcard $(srcdir)/t[0-9][0-9]*.sh)
* The contents of $(TEST_EXTENSIONS) are mostly analyzed at make runtime
rather than at automake runtime, so that it is now possible to use
Automake conditionals and GNU make advanced features in the definition
of $(TEST_EXTENSIONS); for example, the following should now work as
expected:
TEST_EXTENSIONS = $(sort $(suffix $(TESTS)))
if SUPPORT_SHELL_TESTS
TEST_EXTENSIONS += .sh
endif
* We are more liberal and lenient in accepting TEST_EXTENSIONS entries:
it's enough that they start with a dot to be considered valid. However,
using overly "funny" characters (like '!' or '@') could cause problems,
so the user is still advised to limit himself to the use of alphanumeric
characters, plus eventually '.', '-', and '_'.
* Errors about invalid content of $(TEST_EXTENSIONS) are reported at
make runtime, not auto Automake runtime.
* It is not anymore possible to override TEST_LOGS at make runtime as a
mean to redefine the list of tests to be run.
# This won't work anymore!
make check TESTS_LOGS="foo.log bar.log baz.log"
But it's still possible do so overriding TESTS at make runtime; and
in this case (as was the case for TEST_LOGS overriding), it is not
necessary to specify the extensions of the tests to be run:
# This will work even if complete names of the tests are (say)
# "foo.test", "bar.test$(EXEEXT)" and "baz$(EXEEXT)".
make check TESTS="foo bar baz"
* The use of 'RECHECK_LOGS' is not supported anymore. Thus, to lazily
re-run only the tests whose '.trs' or '.log' files are out-of-date,
one must now use:
make check AM_LAZY_CHECK=yes # New valid API.
instead of:
make check RECHECK_LOGS="" # Old API, won't work anymore.
* Per-suffix dependencies for test cases can be specified through
variables "<ext>_LOG_DEPENDENCIES" (this being simply "LOG_DEPENDENCIES"
for suffix-less tests).
Distribution
============
* "Bare" wildcards are not usable anymore in $(EXTRA_DIST):
EXTRA_DIST = $(srcdir)/doc/*.txt # This won't work anymore.
You'll have to use the $(wildcard) GNU make builtin instead, as in:
EXTRA_DIST = $(wildcard $(srcdir)/doc/*.txt) # Good.
or even (for a better support of VPATH builds):
EXTRA_DIST = $(wildcard doc/*.txt $(srcdir)/doc/*.txt) # Better.
* The make variables $(DISTFILES), $(DIST_COMMON), $(DIST_SOURCES) and
$(DIST_ARCHIVES) had never been documented in mainline Automake, and
were always intended to be internal variables. But that was not clear
from their names. So we have renamed rename like this:
DISTFILES => am.dist.all-files
DIST_COMMON => am.dist.common-files
DIST_SOURCES => am.dist.sources
DIST_ARCHIVES => am.dist.default-archives
Do not use any of these variables in your Makefiles!
* Support for distribution archived in the '.shar.gz' and '.tar.Z' formats
have been removed; and with them the targets 'dist-shar' and 'dist-tarZ'.
* The API to specify the formats of distribution tarballs has been changed
completely.
Instead of using the various 'dist-*' automake options, the developer is
now expected to specify the default formats of its distribution tarballs
with the special variable AM_DIST_FORMATS; for example, where once would
have been:
AM_INIT_AUTOMAKE([dist-bzip2 dist-zip])
now it must be:
AM_DIST_FORMATS = gzip bzip2 zip
and similarly, where once would have been:
AUTOMAKE_OPTIONS = no-dist-gzip dist-bzip2 dist-xz
now is it simply:
AM_DIST_FORMATS = bzip2 xz
* The various 'dist-*' targets (dist-gzip, dist-xz, dist-lzip, dist-bzip2
and dist-gz) has been removed. If the user wants to generate tarballs
for formats not specified by the default AM_DIST_FORMATS, he can simply
override that variable dynamically:
# Will generate a '.zip' archive and a '.tar.xz' archive, and not
# further ones.
make dist AM_DIST_FORMATS='zip xz'
* The DIST_TARGETS variable has been removed (as a side-effect of the
previous change).
Obsolete Features Removed
=========================
* Extension-less info files are not supported anymore.
* The only accepted suffix for input Texinfo files is now '.texi';
the once-accepted values '.txi' and '.texinfo' are not handled
anymore, and their use will trigger an error.
* Support for the long-deprecated name 'configure.in' for the Autoconf
input file (instead of the modern 'configure.ac') has been deprecated.
* If the sources for a target library like 'libfoo.a' or 'libbar.la' are
not explicitly specified, mainline Automake looks also (respectively)
for the files 'libfoo_a.c' or 'libbar_la.c' as possible default sources.
Such a behaviour is deprecated though, and is present only for the sake
of backward-compatibility. Automake-NG has thus dropped the behaviour,
and will only look for (respectively) 'libfoo.c' and 'libbar.c' as
possible default sources.
* Automake-NG has removed automatic handling and distribution of the
obsolescent 'acconfig.h', 'config.h.top' and 'config.h.bot' files.
One should instead use the modern macros 'AH_VERBATIM' and 'AH_TEMPLATE',
as recommended in the Autoconf manual (as of Autoconf 2.69, chapter
"Obsolete Constructs", section "acconfig.h").
* The 'mkinstalldirs' script is not installed, distributed, nor provided
anymore; its same effects can be obtained by "install-sh -d" instead.
Similarly, the $(mkinstallscripts) make variable is not defined anymore;
one should use $(MKDIR_P) instead.
* The $(INCLUDES) variable is not anymore passed to the invocations of
compilers with a C-like preprocessing step (as are for example C, C++,
Objective C, preprocessed assembler ...). One should just use
$(AM_CPPFLAGS) instead, which has been supported and recommended for
a long time.
* Support for DJGPP, Windows 95/98/ME and MS-DOS has been removed.
Of course, MinGW/MSYS and Cygwin on Windows 2000 and later are still
fully supported.
* Automake-generated Makefiles assume the target systems always support
file names starting with a dot; accordingly, the internal m4 macro
'AM_SET_LEADING_DOT' and AC_SUBST'd variable 'am__leading_dot' have
been removed.
* The Automake-defined internal make variable '$(ACLOCAL_M4)' has been
renamed to '$(am.remake.aclocal-m4)', and should be considered an
internal detail.
* The variables $(target_triplet), $(host_triplet) and $(build_triplet),
which were redundant because aliases respectively for the variables
$(target), $(host) and $(build), have been removed. Simply use this
latter variables.
* Threaded automake execution (as triggered by $AUTOMAKE_JOBS) has been
removed altogether. Exporting AUTOMAKE_JOBS to in the environment of
Automake will now have no effect.
* Support for "maintainer mode" has been removed, and rules to remake
maintainer-specific files are now always active. The 'missing' script
should till take care of warning users which find themselves in the
situation of having to rebuild some maintainer-specific files but
missing the relevant maintainer-specific tools (or having too old
versions thereof).
* The $(RECURSIVE_CLEAN_TARGETS) variable (never documented, and
always intended to be an internal detail) has been removed, its
content merged into the $(RECURSIVE_TARGETS) variable.
Source Files with Unknown Extensions
====================================
* Automake-NG used a much simpler and dumber algorithm that mainline
Automake to determine how to build an object associated to a source
whose extension in not one of those handled internally by automake.
The new algorithm goes like this. For any file listed in a '_SOURCES'
variable whose suffix is not recognized internally by automake (in
contrast to known suffixes like '.c' or '.f90'), automake will obtain
the expected target object file by stripping the suffix from the source
file, and appending either '.$(OBJEXT)' or '.lo' to it (which one depends
on whether the object is built as part of a program, a static library, or
a libtool library). It will then be assumed that the user has defined a
rule (either explicit or defined from a pattern rule) which can turn that
source file into this corresponding object file. For example, on an
input like:
bin_PROGRAMS = foo
foo_SOURCES = mu.ext1 fu.ext1 zu.ext1
automake will expect that the three objects mu.$(OBJEXT), fu.$(OBJEXT)
and zu.$(OBJEXT) are to be used in the linking of the 'foo' program, and
that the user has provided proper recipes for all those objects to be
built at make time, as well as a link command for linking 'foo'. Here
is an example of how those declarations could look like:
%.$(OBJEXT): %.ext1
my-compiler -c -o $@ $<
foo_LINK = $(CC) -o $@
In this particular case, the idiom above is basically the same one that
would be required in mainline automake (apart for the fact that, there,
old-fashioned suffix rules should be used instead of pattern rules). To
see what is truly changed with the new algorithm, we have to look at a
more indirect usage.
Mainline Automake follows the chain of user-defined pattern rules to
determine how to build the object file deriving from a source file with
a custom user extension; for example, upon reading:
.zoo.cc:
$(preprocess) $< > $@
bin_PROGRAMS = foo
foo_SOURCES = bar.zoo
*mainline* Automake knows that it has to bring in the C++ support
(compilation rules, requirement for AC_PROG_CXX in configure.ac, etc),
and use the C++ linker to link the 'foo' executable.
But Autommake-NG *won't follow those implicit chains of pattern rules*
anymore; so that the idiom above will have to be re-worked like follows
to preserve its intent and behaviour:
%.cc: %.zoo:
$(preprocess) $< > $@
bin_PROGRAMS = foo
# The use of '.cc' is required to let Automake know to bring in
# stuff for the handling of C++ compilation, and to use the C++
# linker to build 'foo'.
nodist_foo_SOURCES = bar.cc
EXTRA_DIST = foo.zoo
And there is another major consequence of this change of semantics: one
can't use anymore "header files" with extensions unrecognized to Automake
anymore; for example, an usage like this will cause errors at make
runtime:
# Won't work anymore.
%.h: %.my-hdr
$(preprocess-header) $< >$@
foo_SOURCES = foo.c bar.my-hdr
BUILT_SOURCES = bar.h
errors that might look like:
make[1]: *** No rule to make target 'bar.o', needed by 'zardoz'. Stop.
The simple workaround is to place the "non-standard" headers in EXTRA_DIST
rather than in a _SOURCES variable:
# This will work.
%.h: %.my-hdr
$(preprocess-header) $< >$@
foo_SOURCES = foo.c foo.h
EXTRA_DIST = foo.my-hdr
BUILT_SOURCES = foo.h
Miscellaneous
=============
* Since GNU make is smart enough to correctly pass the values of macros
redefined on the command line to sub-make invocations, the "special"
variable $(AM_MAKEFLAGS) has been removed, and its content is no more
passed to recursive make invocations.
* The make variable 'CONFIG_HEADER' had never been documented in mainline
Automake, and since when the support for user setting of it has been
removed (in favour of the use of the 'AC_CONFIG_HEADERS' autoconf macro
in configure.ac), it has been intended as an internal variable only.
So we've renamed it to 'AM_CONFIG_HEADERS'. Do not override its value
in your Makefiles!
* The Automake-generated make variable 'DEFAULT_INCLUDES', used internally
in compilation rules and basically never documented in mainline Automake,
has been renamed to AM_DEFAULT_INCLUDES, to avoid impinging on the user's
namespace. Do not override this variable in your Makefiles!
* The Automake-generated clean targets do not exit successfully anymore if
an error occurs while removing a file or directory.
* The semantic of $(BUILT_SOURCES) support has been slightly altered; now,
the files listed in $(BUILT_SOURCES) will be built not only before the
"all", "check" or "install" targets, but before *any* target.
-----
Copyright (C) 2012 Free Software Foundation, Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.