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 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 no longer 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 no longer automatically generate the definition of 'LOG_COMPILE'
  variables.  These have always been meant for internal use only anyway.

* The $(TESTS) and $(XFAIL_TESTS) variables are no longer 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 no longer 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 no longer supported.  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 no longer usable 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).


Texinfo
=======

* Extension-less info files are no longer supported (mainline Automake
  has been warning against them since version 1.13.2, albeit it continues
  to support them for backward-compatibility).

* The only accepted suffix for input Texinfo files is now '.texi'; the
  once-accepted values '.txi' and '.texinfo' are no longer handled, and
  their use will trigger an error (mainline Automake has been warning
  against these suffixes since version 1.13.2, albeit it continues to
  support them for backward-compatibility).

* Disabling distribution of generated '.info' files be re-defining the
  'dist-info' target, as in:

      dist-info:
          @:

  (which has always been an undocumented hack in Automake) no longer
  works.  We are still considering whether to make an equivalent
  capability available with a new, cleaner and documented API.


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

* 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 no longer installed, distributed, nor
  provided; its same effects can be obtained by "install-sh -d" instead.
  Similarly, the $(mkinstallscripts) make variable is no longer defined;
  one should use $(MKDIR_P) instead.

* 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 Automake-NG will *no longer follow those implicit chains* of
  pattern rules; 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: now
  one can no longer use "header files" with extensions unrecognized to
  Automake; 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 no longer exit successfully 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-2015 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/>.