@cindex GNU make extensions
-Note that most GNU make extensions are not recognized by Automake. Using
-such extensions in a @file{Makefile.am} will lead to errors or confusing
-behavior.
+Note that most GNU make extensions are sadly not yet recognized by
+Automake. Using such extensions in a @file{Makefile.am} will likely
+lead to errors or confusing behavior. We hope to improve this
+situation over time.
@cindex Append operator
@cmindex +=
-A special exception is that the GNU make append operator, @samp{+=}, is
-supported. This operator appends its right hand argument to the variable
-specified on the left. Automake will translate the operator into
-an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
+For historical reasons, the GNU make append operator @samp{+=} (which
+appends its right hand argument to the variable specified on the left)
+is supported and handled in a special way: Automake will translate the
+operator into an ordinary @samp{=} operator @emph{at Automake (not make)
+runtime}. This behaviour might change future versions.
Automake tries to keep comments grouped with any adjoining rules or
variable definitions.
@cindex Automake, recursive operation
@cindex Example of recursive operation
-When examining a variable definition, Automake will recursively examine
-variables referenced in the definition. For example, if Automake is
-looking at the content of @code{foo_SOURCES} in this snippet
+When examining the definition of some ``special'' variables, Automake
+might recursively examine variables referenced in the definition in order
+to perform its magic. For example, if Automake is looking at the content
+of @code{foo_SOURCES} in this snippet
@c Keep in sync with interp.test.
@example
it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
contents of @code{foo_SOURCES}.
+Unfortunately, for historical reasons, this interpolation processes
+has the effect of currently making it impossible to use more advanced
+GNU make features in the definitions of special variables like
+@code{foo_SOURCES}; for example, Automake will generate a broken
+@file{Makefile.in} on this input:
+
+@c Keep in sync with interp3.test.
+@example
+bin_PROGRAMS = foo
+xs = one two
+foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h)
+@end example
+
@cindex @code{##} (special Automake comment)
@cindex Special Automake comment
@cindex Comment, special to Automake
@item override
user redefinitions of Automake rules or variables
@item portability
-portability issues (e.g., use of @command{make} features that are
-known to be not portable)
+portability issues; e.g., use of file names like @file{aux} that are
+reserved on some systems (like Windows), or use of Automake features
+that require support from the target C compiler, support that is
+known not be present on all the mainstream C compilers.
@item extra-portability
extra portability issues related to obscure tools. One example of such
a tool is the Microsoft @command{lib} archiver.
Automake provides initial support for Vala
(@uref{http://www.vala-project.org/}).
-This requires valac version 0.7.0 or later, and currently requires
-the user to use GNU @command{make}.
+This requires valac version 0.7.0 or later.
@example
foo_SOURCES = foo.vala bar.vala zardoc.c
Please note that it is currently not possible to use @code{$(srcdir)/}
or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
-limitation is necessary to avoid generating test logs in the source tree
-and has the unfortunate consequence that it is not possible to specify
-distributed tests that are themselves generated by means of explicit
-rules, in a way that is portable to all @command{make} implementations
-(@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
-semantics of FreeBSD and OpenBSD @command{make} conflict with this).
-In case of doubt you may want to require to use GNU @command{make},
-or work around the issue with inference rules to generate the tests.
+limitation is necessary to avoid generating test logs in the source tree.
@node Custom Test Drivers
@section Custom Test Drivers
@item @command{make --no-print-directory}
-This is GNU @command{make} specific. When called with the
+When called with the
@option{--no-print-directory} option, GNU @command{make} will disable
printing of the working directory by invoked sub-@command{make}s (the
well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
versions.
@cindex @file{GNUmakefile} including @file{Makefile}
-Here are two other ideas. If GNU make is assumed, one possibility is
+Here are two other ideas. One possibility is
to add to that subdirectory a @file{GNUmakefile} that defines the
required targets and includes the third-party @file{Makefile}. For
this to work in VPATH builds, @file{GNUmakefile} must lie in the build
even though a file is missing. By listing files, @samp{make dist}
@emph{will} complain.
-@item
-Wildcards are not portable to some non-GNU @command{make} implementations,
-e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
-prerequisites of a target.
-
@item
Finally, it's really hard to @emph{forget} to add a file to
@file{Makefile.am}: files that are not listed in @file{Makefile.am} are
@end itemize
Still, these are philosophical objections, and as such you may disagree,
-or find enough value in wildcards to dismiss all of them. Before you
-start writing a patch against Automake to teach it about wildcards,
-let's see the main technical issue: portability.
-
-Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
-not portable to other @command{make} implementations.
-
-The only way Automake could support @command{$(wildcard ...)} is by
-expending @command{$(wildcard ...)} when @command{automake} is run.
-The resulting @file{Makefile.in}s would be portable since they would
-list all files and not use @samp{$(wildcard ...)}. However that
-means developers would need to remember to run @command{automake} each
-time they add, delete, or rename files.
-
-Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
-it's easier and faster to type @samp{automake; make} than to type
-@samp{emacs Makefile.am; make}. But nobody bothered enough to write a
-patch to add support for this syntax. Some people use scripts to
-generate file lists in @file{Makefile.am} or in separate
-@file{Makefile} fragments.
-
-Even if you don't care about portability, and are tempted to use
-@samp{$(wildcard ...)} anyway because you target only GNU Make, you
-should know there are many places where Automake needs to know exactly
-which files should be processed. As Automake doesn't know how to
-expand @samp{$(wildcard ...)}, you cannot use it in these places.
+or find enough value in wildcards to dismiss all of them. Still, before
+you start ignoring our advice and using @samp{$(wildcard ...)} all over
+the place, you should know there are many places where Automake needs to
+know exactly which files should be processed @footnote{This limitation
+is mostly due to historical reasons; unfortunately, the current
+implementation has been heavily influenced by that assumption, and
+is difficult to change now. We hope this situation will improve in
+the future (no promises though).}. As Automake doesn't know how to
+expand @samp{$(wildcard ...)}, you @emph{cannot} use it in these places;
@samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
variables as far Automake is concerned.
-You can get warnings about @samp{$(wildcard ...}) constructs using the
-@option{-Wportability} flag.
-
@node Limitations on File Names
@section Limitations on File Names
@cindex file names, limitations on
@file{data.x}, and @file{data.c}. Another one is a race condition
if a parallel @command{make} attempts to run multiple instances of the
recover block at once. Finally, the recursive rule breaks @samp{make -n}
-when run with GNU @command{make} (as well as some other @command{make}
-implementations), as it may remove @file{data.h} even when it should not
+as it may remove @file{data.h} even when it should not
(@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
The GNU Make Manual}).
fi
@end example
+@emph{FIXME! Automake-NG does assume GNU make, so we might want to
+re-work this section to take advantage of pattern rules support.}
For completeness it should be noted that GNU @command{make} is able to
express rules with multiple output files using pattern rules
(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
@code{make V=1} to see the commands being executed.
@item
@code{make -n} can help show what would be done without actually doing
-it. Note however, that this will @emph{still execute} commands prefixed
-with @samp{+}, and, when using GNU @command{make}, commands that contain
-the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
-Execution,,, make, The GNU Make Manual}).
+it. Note however, that this will @emph{still execute} recipes prefixed
+with @samp{+} and recipes that contain the strings @samp{$(MAKE)} or
+@samp{$@{MAKE@}} (@pxref{Instead of Execution,,, make, The GNU Make
+Manual}).
Typically, this is helpful to show what recursive rules would do, but it
means that, in your own rules, you should not mix such recursion with
actions that change any files.@footnote{Automake's @samp{dist} and
projects / thirdparty / automake.git / commitdiff
