[PATCH] texi: info files can be generated in the builddir (was: Re: [PATCH 0/3] Texinfo: allow '.info' placed in $(builddir), remove cruft)

[Stefano Lattarini]

References:
<http://lists.gnu.org/archive/html/automake-patches/2012-12/msg00107.html>
<http://lists.gnu.org/archive/html/automake-patches/2012-12/msg00125.html>

On 12/31/2012 07:45 PM, Stefano Lattarini wrote:
> On 12/31/2012 11:02 AM, Stefano Lattarini wrote:
>> See the commit messages of the individual patches for rationales and
>> background.  I plan to push this series to master in 72 hours.
>>
>> Stefano Lattarini (3):
>>   texinfo: info files can be generated in the builddir
>>   docs: document the new 'info-in-builddir' option
>>   texinfo: remove hack about info files in CLEANFILES variables
>>
> Actually, I think it might make sense to apply the first two patches
> to maint (after the 1.13.1 bug-fixing release is out).  This should
> be OK, since the change itself is very unobtrusive and no possible
> source of bugs (Murphy spare me for having said so :-).  In addition,
> having this new option earlier will allow a proper deprecation of the
> old CLEANFILES hack, so that its final removal in Automake 1.14 won't
> be too abrupt.
> 
> Opinions, objections?
> 
OK, so here is the first patch for maint, that I hope to get into
Automake 1.13.2.  I will push it in a couple of days if there is no
review by then.  The deprecation of the obsolescent "CLEANFILES hack"
(that too for maint) and its removal (that for master only, to appear
as part of 1.14) will follow at leisure.

Thanks,
  Stefano

---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ---- 8< ----

>From 36ee783a1000b5a1e52b81e5564de19ffb99fd37 Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Tue, 3 Apr 2012 22:02:55 +0200
Subject: [PATCH] texi: info files can be generated in the builddir

User can now ask info files to be built in the $(builddir), rather than
the $(srcdir), by specifying the Automake option 'info-in-builddir'.
This feature was requested by the developers of GCC, GDB, GNU binutils
and the GNU bfd library.  See the extensive discussion about automake
bug#11034 for more details.

OK, to be honest, having '.info' files built in the builddir was
*already* possible, but only using ugly and undocumented hacks involving
definition of the CLEANFILES and/or DISTCLEANFILES.  For example, the
binutils project did something like this in the relevant 'Makefile.am':

    # Automake 1.9 will only build info files in the objdir if they are
    # mentioned in DISTCLEANFILES.  It doesn't have to be unconditional,
    # though, so we use a bogus condition.
    if GENINSRC_NEVER
    DISTCLEANFILES = binutils.info
    endif

See also the extensive discussion about automake bug#11034; in
particular, the following messages:
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#65>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#80>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#86>
<http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11034#101>

* lib/Automake/Options.pm (_is_valid_easy_option): Recognize the
new 'info-in-builddir' option.
* automake.in (handle_texinfo_helper): If that option is set,
initialize '$insrc' to '0', so that info files will be generated
in the builddir.  Adjust comments to match.
* t/txinfo-builddir.sh: New test.
* t/list-of-tests.mk: Add it.
* NEWS: Update.
* doc/automake.texi: Document the new options.

Signed-off-by: Stefano Lattarini <address@hidden>
---
 NEWS                    |   9 ++++
 automake.in             |  38 +++++++++------
 doc/automake.texi       |  13 +++++
 lib/Automake/Options.pm |   1 +
 t/list-of-tests.mk      |   1 +
 t/txinfo-builddir.sh    | 127 ++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 174 insertions(+), 15 deletions(-)
 create mode 100755 t/txinfo-builddir.sh

diff --git a/NEWS b/NEWS
index c5b6514..804805e 100644
--- a/NEWS
+++ b/NEWS
@@ -49,6 +49,15 @@ New in 1.13.2:
     should take precedence over the same-named automake-provided macro
     (defined in '/usr/local/share/aclocal-1.14/vala.m4').

+* Texinfo support:
+
+  - Automake can now be instructed to place '.info' files generated from
+    Texinfo input in the builddir rather than in the srcdir; this is done
+    specifying the new automake option 'info-in-builddir'.  This feature
+    was requested by the developers of GCC, GDB, GNU binutils and the GNU
+    bfd library.  See the extensive discussion about automake bug#11034
+    for more details.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 New in 1.13.1:
diff --git a/automake.in b/automake.in
index 0764258..e56ea65 100644
--- a/automake.in
+++ b/automake.in
@@ -3269,23 +3269,31 @@ sub handle_texinfo_helper ($)
       # have a single variable ($INSRC) that controls whether
       # the current .info file must be built in the source tree
       # or in the build tree.  Actually this variable is switched
-      # off for .info files that appear to be cleaned; this is
-      # for backward compatibility with package such as Texinfo,
-      # which do things like
-      #   info_TEXINFOS = texinfo.txi info-stnd.texi info.texi
-      #   DISTCLEANFILES = texinfo texinfo-* info*.info*
-      #   # Do not create info files for distribution.
-      #   dist-info:
-      # in order not to distribute .info files.
-      my $insrc = ($out_file =~ $user_cleaned_files) ? 0 : 1;
-
-      my $soutdir = '$(srcdir)/' . $outdir;
-      $outdir = $soutdir if $insrc;
+      # off in two cases:
+      #  (1) For '.info' files that appear to be cleaned; this is for
+      #      backward compatibility with package such as Texinfo,
+      #      which do things like
+      #        info_TEXINFOS = texinfo.txi info-stnd.texi info.texi
+      #        DISTCLEANFILES = texinfo texinfo-* info*.info*
+      #        # Do not create info files for distribution.
+      #        dist-info:
+      #      in order not to distribute .info files.
+      #  (2) When the undocumented option 'info-in-builddir' is given.
+      #      This is done to allow the developers of GCC, GDB, GNU
+      #      binutils and the GNU bfd library to force the '.info' files
+      #      to be generated in the builddir rather than the srcdir, as
+      #      was once done when the (now removed) 'cygnus' option was
+      #      given.  See automake bug#11034 for more discussion.
+      my $insrc = 1;
+      $insrc = 0 if $out_file =~ $user_cleaned_files;
+      $insrc = 0 if option 'info-in-builddir';
+
+      $outdir = '$(srcdir)/' . $outdir if $insrc;

       # If user specified file_TEXINFOS, then use that as explicit
       # dependency list.
       @texi_deps = ();
-      push (@texi_deps, "$soutdir$vtexi") if $vtexi;
+      push (@texi_deps, "$outdir$vtexi") if $vtexi;

       my $canonical = canonicalize ($infobase);
       if (var ($canonical . "_TEXINFOS"))
@@ -3339,8 +3347,8 @@ sub handle_texinfo_helper ($)
                                          new Automake::Location,
                                          TEXI     => $texi,
                                          VTI      => $vti,
-                                         STAMPVTI => "${soutdir}stamp-$vti",
-                                         VTEXI    => "$soutdir$vtexi",
+                                         STAMPVTI => "${outdir}stamp-$vti",
+                                         VTEXI    => "$outdir$vtexi",
                                          MDDIR    => $conf_dir,
                                          DIRSTAMP => $dirstamp);
        }
diff --git a/doc/automake.texi b/doc/automake.texi
index b4dad5c..443f65a 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -7830,6 +7830,11 @@ install} (unless you use @option{no-installinfo}, see 
below).
 Furthermore, @file{.info} files are automatically distributed so that
 Texinfo is not a prerequisite for installing your package.

+It is worth noting that, contrary to what happens with the other formats,
+the generated @file{.info} files are by default placed in @code{srcdir}
+rather than in the @code{builddir}.  This can be changed with the
address@hidden option.
+
 @trindex dvi
 @trindex html
 @trindex pdf
@@ -10069,6 +10074,14 @@ options below.  This option should be used in the 
top-level
 @file{configure.ac}, it will be ignored otherwise.  It will also be
 ignored in sub-packages of nested packages (@pxref{Subpackages}).

address@hidden @option{info-in-builddir}
address@hidden Option, @option{info-in-builddir}
address@hidden info-in-builddir
+Instruct Automake to place the generated @file{.info} files in the
address@hidden rather than in the @code{srcdir}.  Note that this
+might make VPATH builds with some non-GNU make implementations more
+brittle.
+
 @item @option{no-define}
 @cindex Option, @option{no-define}
 @opindex no-define
diff --git a/lib/Automake/Options.pm b/lib/Automake/Options.pm
index 3674920..3932798 100644
--- a/lib/Automake/Options.pm
+++ b/lib/Automake/Options.pm
@@ -276,6 +276,7 @@ sub _is_valid_easy_option ($)
     dist-tarZ
     dist-xz
     dist-zip
+    info-in-builddir
     no-define
     no-dependencies
     no-dist
diff --git a/t/list-of-tests.mk b/t/list-of-tests.mk
index 591b4f0..71487e9 100644
--- a/t/list-of-tests.mk
+++ b/t/list-of-tests.mk
@@ -1162,6 +1162,7 @@ t/tests-environment-and-log-compiler.sh \
 t/txinfo-absolute-srcdir-pr408.sh \
 t/txinfo-add-missing-and-dist.sh \
 t/txinfo-bsd-make-recurs.sh \
+t/txinfo-builddir.sh \
 t/txinfo-clean.sh \
 t/txinfo-dvi-recurs.sh \
 t/txinfo-info-in-srcdir.sh \
diff --git a/t/txinfo-builddir.sh b/t/txinfo-builddir.sh
new file mode 100755
index 0000000..148a1a6
--- /dev/null
+++ b/t/txinfo-builddir.sh
@@ -0,0 +1,127 @@
+#! /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 <http://www.gnu.org/licenses/>.
+
+# Check that info files are built in builddir when needed.
+# This test that this can be done through the so far undocumented
+# option 'info-in-builddir', as requested by at least GCC, GDB,
+# GNU binutils and the GNU bfd library.  See automake bug#11034.
+
+required='makeinfo tex texi2dvi'
+. test-init.sh
+
+echo AC_OUTPUT >> configure.ac
+
+cat > Makefile.am << 'END'
+AUTOMAKE_OPTIONS = info-in-builddir
+info_TEXINFOS = foo.texi subdir/bar.texi mu.texi
+subdir_bar_TEXINFOS = subdir/inc.texi
+CLEANFILES = mu.info
+
+# mu.info should not be rebuilt in the current directory, since
+# it's up-to-date in $(srcdir).
+# This can be caused by a subtle issue related to VPATH handling
+# of version.texi (see also the comment in texi-vers.am): because
+# stamp-vti is newer than version.texi, the 'version.texi: stamp-vti'
+# rule is always triggered.  Still that's not a reason for 'make'
+# to think 'version.texi' has been created...
+check-local:
+       test ! -e mu.info
+       test -f ../mu.info
+END
+
+mkdir subdir
+
+cat > foo.texi << 'END'
+\input texinfo
address@hidden foo.info
address@hidden foo
address@hidden Top
+Hello walls.
address@hidden version.texi
address@hidden
+END
+
+cat > mu.texi << 'END'
+\input texinfo
address@hidden mu.info
address@hidden mu
address@hidden Top
+Mu mu mu.
address@hidden
+END
+
+cat > subdir/bar.texi << 'END'
+\input texinfo
address@hidden bar.info
address@hidden bar
address@hidden Top
+Hello walls.
address@hidden inc.texi
address@hidden
+END
+
+echo "I'm included." > subdir/inc.texi
+
+$ACLOCAL
+$AUTOMAKE --add-missing
+$AUTOCONF
+
+mkdir build
+cd build
+../configure
+$MAKE info
+test -f foo.info
+test -f subdir/bar.info
+test -f mu.info
+test -f stamp-vti
+test -f version.texi
+test ! -e ../foo.info
+test ! -e ../subdir/bar.info
+test ! -e ../mu.info
+test ! -e ../stamp-vti
+test ! -e ../version.texi
+$MAKE clean
+test -f foo.info
+test -f subdir/bar.info
+test ! -e mu.info
+test -f stamp-vti
+test -f version.texi
+
+# Make sure stamp-vti is older that version.texi.
+# (A common situation in a real tree).
+$sleep
+touch stamp-vti
+
+$MAKE distcheck
+# Being distributed, this file should have been rebuilt.
+test -f mu.info
+
+$MAKE distclean
+test -f stamp-vti
+test -f version.texi
+test -f foo.info
+test -f subdir/bar.info
+test ! -e mu.info
+
+../configure
+$MAKE maintainer-clean
+test ! -e stamp-vti
+test ! -e version.texi
+test ! -e foo.info
+test ! -e subdir/bar.info
+test ! -e mu.info
+
+:
-- 
1.8.1.rc3.27.g3b73c7d