FYI: augment install-exec-hook documentation (Debian Bug #185388)

[Alexandre Duret-Lutz]

I'm checking the following in, on HEAD and branch-1-7.

2003-03-20  Alexandre Duret-Lutz  <address@hidden>

        For Debian Bug #185388:
        * automake.texi (Extending): Augment the install-exec-hook
        discussion with an example how to symlink a versioned binary.
        * tests/insthook.test: Rewrite to test the above example.
        Report from James R. Van Zandt.

Index: THANKS
===================================================================
RCS file: /cvs/automake/automake/THANKS,v
retrieving revision 1.186.2.26
diff -u -r1.186.2.26 THANKS
--- THANKS      13 Mar 2003 21:34:35 -0000      1.186.2.26
+++ THANKS      20 Mar 2003 22:34:28 -0000
@@ -80,6 +80,7 @@
 Imacat                 address@hidden
 Inoue                  address@hidden
 James Henstridge       address@hidden
+James R. Van Zandt     address@hidden
 James Youngman         address@hidden
 Janos Farkas           address@hidden
 Jared Davis            address@hidden
Index: automake.texi
===================================================================
RCS file: /cvs/automake/automake/automake.texi,v
retrieving revision 1.305.2.19
diff -u -r1.305.2.19 automake.texi
--- automake.texi       5 Mar 2003 22:23:53 -0000       1.305.2.19
+++ automake.texi       20 Mar 2003 22:34:33 -0000
@@ -5319,8 +5319,35 @@
 
 @example
 install-exec-hook:
-        ln $(DESTDIR)$(bindir)/program $(DESTDIR)$(bindir)/proglink
+        ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
+           $(DESTDIR)$(bindir)/proglink$(EXEEXT)
 @end example
+
+Although cheaper and more portable than symbolic links, hard links
+will not work everywhere (for instance OS/2 does not have
address@hidden).  Ideally you should fall back to @code{cp -p} when
address@hidden does not work.  An easy way, if symbolic links are
+acceptable to you, is to add @code{AC_PROG_LN_S} to
address@hidden (@pxref{Particular Programs, , Particular Program
+Checks, autoconf, The Autoconf Manual}) and use @code{$(LN_S)} in
address@hidden
+
address@hidden versioned binaries, installing
address@hidden installing versioned binaries
address@hidden LN_S example
+For instance, here is how you could install a versioned copy of a
+program using @code{$(LN_S)}:
+
address@hidden
+install-exec-hook:
+        cd $(DESTDIR)$(bindir) && \
+          mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
+          $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
address@hidden example
+
+Note that we rename the program so that a new version will erase the
+symbolic link, not the real binary.  Also we @code{cd} into the
+destination directory in order to create relative links.
 
Index: tests/insthook.test
===================================================================
RCS file: /cvs/automake/automake/tests/insthook.test,v
retrieving revision 1.7
diff -u -r1.7 insthook.test
--- tests/insthook.test 8 Sep 2002 13:07:55 -0000       1.7
+++ tests/insthook.test 20 Mar 2003 22:34:34 -0000
@@ -1,5 +1,5 @@
 #! /bin/sh
-# Copyright (C) 1998, 1999, 2001, 2002  Free Software Foundation, Inc.
+# Copyright (C) 2003  Free Software Foundation, Inc.
 #
 # This file is part of GNU Automake.
 #
@@ -18,20 +18,51 @@
 # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
 
-# Test to make sure install-exec-hook works.
-# Report from Tim Goodwin.
+# Make sure the install-exec-hook example we give in the manual works.
 
 . ./defs || exit 1
 
-cat > Makefile.am << 'END'
+set -e
+
+cat >>configure.in <<'EOF'
+AC_PROG_LN_S
+AC_OUTPUT
+EOF
+
+cat >Makefile.am <<'END'
+dist_bin_SCRIPTS = foo
+
 install-exec-hook:
-       @echo nothing
+       cd $(DESTDIR)$(bindir) && \
+       mv -f foo foo-$(VERSION) && \
+       $(LN_S) foo-$(VERSION) foo
+
+installcheck-local:
+       test -f $(bindir)/foo
+       test -f $(bindir)/foo-$(VERSION)
+       : > $(top_srcdir)/../ok
 END
 
-$ACLOCAL || exit 1
-$AUTOMAKE || exit 1
+echo 1 > foo
+
+$ACLOCAL
+$AUTOCONF
+$AUTOMAKE
+
+./configure
+$MAKE distcheck
+# Sanity check to make sure installcheck-local was run.
+test -f ok
 
-test "`grep install-exec-hook Makefile.in | wc -l`" -gt 1 || exit 1
-# install-exec-hook must appear in the install-exec-am rule.
-sed -n '/^install-exec-am:/,/^[^       ]/p' Makefile.in | \
-  grep install-exec-hook
+# Make sure that installing a second version doesn't erase the first
+# one.  (This is error prone since `foo' symlinks to `foo-1.0' and the
+# second version will overwrite `foo'.   Hopefully `install' and `install-sh'
+# are smart enough to erase the `foo' symlink before installing the new
+# version.)
+./configure --bindir=`pwd`/bin
+$MAKE install
+echo 2 > foo
+VERSION=2.0 make -e install
+grep 1 bin/foo-1.0
+grep 2 bin/foo-2.0
+grep 2 bin/foo

-- 
Alexandre Duret-Lutz