path: root/NG-NEWS

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 unconditionally assumes that nested variables
  expansion are supported.  Accordingly, the AC_SUBST'd variables '@AM_V@'
  and'@AM_DEFAULT_V@' have been removed, so that instead of using
  something like:

    pkg_verbose = $(pkg_verbose_@AM_V@)
    pkg_verbose_ = $(pkg_verbose_@AM_DEFAULT_V@)

  you should simply use:

    pkg_verbose = $(pkg_verbose_$(V))
    pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))


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.


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).


Pattern rules and suffix rules
==============================

* Old-fashioned suffix rules are not supported anymore; Automake-NG will
  error out if you try to use them.  Use pattern rules instead, as
  advised in the GNU make manual itself.

* The .SUFFIXES: special target and the SUFFIXES special variable are
  not supported anymore either; Automake-NG will error out if you try
  to define them.


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 variables $(DISTFILES), $(DIST_COMMON) and $(DIST_SOURCES) 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_files
    DIST_COMMON   =>  am__dist_common
    DIST_SOURCES  =>  am__dist_sources

  Do not use any of these variables in your Makefiles!


Obsolete Features Removed
=========================

* 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.


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
      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!

-----

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/>.