From 4b80b05c22b13e99499c2e96ca67653779b9c27a Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Thu, 26 Jan 2012 15:56:21 +0100 Subject: [PATCH] [ng] docs: we assume GNU make now; update accordingly * doc/automake.texi: Update and adjust. Add some FIXME comments for more delicate passages that should be re-worked and addressed in the future. * tests/interp3.test: New test, exposing a known Automake limitation that is particularly annoying for GNU make users. * tests/Makefile.am (XFAIL_TESTS): Add it. * tests/list-of-tests.mk: Likewise. --- doc/automake.texi | 114 ++++++++++++++++++----------------------- tests/Makefile.am | 1 + tests/interp3.test | 60 ++++++++++++++++++++++ tests/list-of-tests.mk | 1 + 4 files changed, 112 insertions(+), 64 deletions(-) create mode 100755 tests/interp3.test diff --git a/doc/automake.texi b/doc/automake.texi index f3a35324c..15af18586 100644 --- a/doc/automake.texi +++ b/doc/automake.texi @@ -1829,16 +1829,18 @@ distributions from the source control system. @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. @@ -1880,9 +1882,10 @@ names might change in future releases. @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 @@ -1893,6 +1896,19 @@ foo_SOURCES = c.c $(xs) 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 @@ -2688,8 +2704,10 @@ obsolete features or constructions @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. @@ -6794,8 +6812,7 @@ the @code{_LDFLAGS} variable for the program. 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 @@ -9181,14 +9198,7 @@ to avoid this limitation. 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 @@ -10705,7 +10715,7 @@ debugging and error assessment very difficult. @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 @@ -11359,7 +11369,7 @@ keep the third-party sources untouched to ease upgrades to new 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 @@ -11854,11 +11864,6 @@ incomplete project and is able to run @samp{make dist} successfully, 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 @@ -11866,38 +11871,18 @@ not compiled or installed, so you can't even test them. @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 @@ -12596,8 +12581,7 @@ to the timestamp ordering of @file{data.h}, @file{data.w}, @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}). @@ -12774,6 +12758,8 @@ $(ELCFILES): elc-stamp 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 @@ -12933,10 +12919,10 @@ If less verbose output has been enabled in the package with the @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 diff --git a/tests/Makefile.am b/tests/Makefile.am index dc16ad5bb..9381f26a9 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -38,6 +38,7 @@ XFAIL_TESTS = \ all.test \ cond17.test \ gcj6.test \ +interp3.test \ override-conditional-2.test \ java-nobase.test \ objext-pr10128.test \ diff --git a/tests/interp3.test b/tests/interp3.test new file mode 100755 index 000000000..ba74339cc --- /dev/null +++ b/tests/interp3.test @@ -0,0 +1,60 @@ +#! /bin/sh +# 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 . + +# Variable interpolation should work even when GNU make functions are +# involved. This is unfortunately not the case currently, due to +# historical and hard-to-lift limitations (this is also documented in +# the manual, using an example that is a stripped-down version of this +# test case). + +required=cc +. ./defs || Exit 1 + +cat >> configure.in << 'END' +AC_PROG_CC +AC_OUTPUT +END + +cat > Makefile.am << 'END' +bin_PROGRAMS = foo +xs = one two +foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h) +END + +$ACLOCAL +$AUTOMAKE +$AUTOCONF + +./configure + +echo 'int one (void) { return 1; }' > one.c +echo 'extern int one (void);' > one.h +echo 'int two (void) { return 2; }' > two.c +echo 'extern int two (void);' > two.h + +cat > main.c <<'END' +#include "one.h" +#include "two.h" +int maint (void) +{ + return one () + two (); +} +END + +$MAKE +$MAKE distcheck + +: diff --git a/tests/list-of-tests.mk b/tests/list-of-tests.mk index 8f66c26bc..ea04a1021 100644 --- a/tests/list-of-tests.mk +++ b/tests/list-of-tests.mk @@ -491,6 +491,7 @@ instmany-python.test \ install-info-dir.test \ interp.test \ interp2.test \ +interp3.test \ java.test \ java2.test \ java3.test \ -- 2.47.2