Significantly improve the handling of --with-pmdir.

INSTALL

@@ -40,6 +40,14 @@ The steps in building Stow are:
     `./configure && make' to configure stow for your system.  If you
     are building from a CPAN tarball, this step can be skipped.
 
+    If `make' warns that the Perl module installation directory is
+    not in @INC, then you should run:
+
+      eval `perl -V:siteprefix`
+      ./configure --prefix=$siteprefix && make
+
+    to avoid a superfluous "use lib" line in your stow executable.
+
 3.  Type `perl Build.PL'.
 
 4.  Type `./Build install' to install the various files.  As noted
@@ -52,11 +60,27 @@ The steps in building Stow are:
 
 1.  `cd' to the directory containing the source code (and this file).
 
-2.  Type `./configure' to configure stow for your system.  This
+2.  Type `./configure' to configure stow for your system.  This step
-    step will attempt to locate your copy of perl and set its location
+    will attempt to locate your copy of perl and set its location in
-    in `Makefile.in'.
+    `Makefile.in'.  You can use the normal arguments to change the
+    default installation paths (see below); additionally you can use
+    the
 
-3.  Type `make install' to install the various files.
+      --with-pmdir=/path/to/perl/modules
+
+    option to manually choose where the Perl modules get installed.
+    However, if you don't, the configure script will go to great
+    lengths to try to choose a sensible default.
+
+3.  Type `make install' to install the various files.  If the chosen
+    installation directory for Perl modules is not included in Perl's
+    built-in @INC search path, the Makefile rules will automatically
+    insert a
+
+      use lib "...";
+
+    line into the generated stow script to ensure that it can always
+    locate the Perl modules without needing to manually set PERL5LIB.
 
 4.  You can remove the generated files from the source code directory
     by typing `make clean'.  To also remove the files that `configure'

Makefile.am

@@ -92,21 +92,53 @@ maintainer-clean-local:
 
 # this is more explicit and reliable than the config file trick
 edit = sed -e 's|[@]PERL[@]|$(PERL)|g'       \
-	   -e 's|[@]VERSION[@]|$(VERSION)|g'
+	   -e 's|[@]VERSION[@]|$(VERSION)|g' \
+	   -e "s|[@]USE_LIB_PMDIR[@]|$$use_lib_pmdir|g"
+
+pmdir_in_INC = \
+	PERL5LIB= $(PERL) -V | \
+	    awk '/@INC/ {p=1; next} p==1 {print $$1}' | \
+	    grep -q "$(pmdir)"
+
+calc_use_lib_pmdir = \
+	if $(pmdir_in_INC); then \
+	    use_lib_pmdir=""; \
+	else \
+	    use_lib_pmdir="use lib \"$(pmdir)\";"; \
+	fi
+
+check_pmdir = \
+	echo; \
+	echo "\# Perl modules will be installed to $(pmdir)"; \
+	echo "\# "; \
+	if $(pmdir_in_INC); then \
+	    echo "\# This is in $(PERL)'s built-in @INC, so everything"; \
+	    echo "\# should work fine with no extra effort."; \
+	else \
+	    echo "\# This is not in $(PERL)'s built-in @INC, so the"; \
+	    echo "\# front-end scripts will have an appropriate \"use lib\""; \
+	    echo "\# line inserted to compensate."; \
+	fi; \
+	echo
 
 bin/stow: bin/stow.in Makefile
 	[ -d bin ] || mkdir bin # required in vpath mode
+	@$(check_pmdir)
+	@$(calc_use_lib_pmdir); \
 	$(edit) < $< > $@
+	@echo "Generated $@ from $<"
 	chmod +x $@
 
 bin/chkstow: bin/chkstow.in Makefile
-	[ -d bin ] || mkdir bin # required in vpath mode
+	@[ -d bin ] || mkdir bin # required in vpath mode
-	$(edit) < $< > $@
+	@$(edit) < $< > $@
+	@echo "Generated $@ from $<"
 	chmod +x $@
 
-lib/Stow.pm: lib/Stow.pm.in Makefile $(DEFAULT_IGNORE_LIST)
+lib/Stow.pm: lib/Stow.pm.in $(DEFAULT_IGNORE_LIST) Makefile
-	[ -d lib ] || mkdir lib # required in vpath mode
+	@[ -d lib ] || mkdir lib # required in vpath mode
-	( $(edit) < $<; cat $(DEFAULT_IGNORE_LIST) ) > $@
+	@( $(edit) < $<; cat $(DEFAULT_IGNORE_LIST) ) > $@
+	@echo "Generated $@ from $< and $(DEFAULT_IGNORE_LIST)"
 
 ##############################################################################
 # The below rules should only be needed by developers.

NEWS

@@ -1,9 +1,23 @@
 News file for Stow.
 
 * Changes in version 2.1.2
+  Many thanks to Stefano Lattarini for help with numerous autoconf and
+  automake issues which are addressed in this release.
+** Significantly improve the handling of --with-pmdir.
+*** Calculation of the default value for --with-pmdir is now done safely in Perl.
+    Previously non-POSIX-compliant shells could cause issues.
+*** The output of ./configure and make are now much more helpful.
+*** The Makefile will now check whether pmdir is in Perl's built-in @INC.
+    If not, it will insert a
+
+      use lib "...";
+
+    line into the generated stow script to ensure that it can always
+    locate the Perl modules without needing to manually set PERL5LIB.
+*** Updated INSTALL and HOWTO-RELEASE accordingly.
 ** ./configure now aborts if Perl isn't found.
 ** Ensured the ChangeLog is up-to-date when making a new distribution.
-   Thanks to Stefano Lattarini for this suggestion.
+** Fixed bug with `make clean' removing files which the user may not be able to rebuild.
 * Changes in version 2.1.1
 ** Fixed bug where ./configure --with-pmdir=X was ineffectual.
 ** Calculated the correct default value for pmdir based on the local Perl installation.

bin/stow.in

@@ -395,6 +395,7 @@ require 5.6.1;
 use POSIX qw(getcwd);
 use Getopt::Long;
 
+@USE_LIB_PMDIR@
 use Stow;
 use Stow::Util qw(parent);
 

configure.ac

@@ -17,13 +17,49 @@ then
   AC_MSG_ERROR([Perl not found; check your \$PATH.])
 fi
 
+# N.B. ${var#pattern} will not work with some shells, such as
+# Solaris 10's /bin/sh :-(
+#
+#   http://www.gnu.org/software/autoconf/manual/autoconf.html#Portable-Shell
+#
+#   eval `$PERL -V:siteprefix -V:installsitelib`
+#   pmdir_relative_path="${installsitelib#$siteprefix/}"
+#
+# This will work:
+#
+#   pmdir_relative_path=`echo "${installsitelib}" | sed -e "s!^$siteprefix/!!"`
+#
+# but this is cleaner:
+pmdir_relative_path=`\
+  $PERL -MConfig \
+        -wle '($_ = $Config{installsitelib})
+              =~ s!^\Q$Config{siteprefix}/!!; \
+              print'`
+
 AC_ARG_WITH(
-    pmdir,
+    [pmdir],
-    [  --with-pmdir=DIR        Perl modules are in DIR [[LIBDIR/perl5]]],
+    AS_HELP_STRING(
+      [--with-pmdir=DIR],
+      [Install Perl modules in DIR]),
     [PMDIR=${withval}],
-    [eval `$PERL -V:installsitelib -V:siteprefix`
+    [PMDIR='${prefix}'/"$pmdir_relative_path"])
-  PMDIR='${prefix}'/"${installsitelib#$siteprefix/}"])
+AC_CONFIG_COMMANDS_POST([[
-AC_CONFIG_COMMANDS_POST([eval echo "Perl modules will be installed to $PMDIR"])
+  eval pmdir="$PMDIR"
+  cat <<EOF
+
+# Perl modules will be installed to $PMDIR
+EOF
+  if [ "$pmdir" != "$PMDIR" ]; then
+    cat <<EOF
+# which will expand to
+#
+#   $pmdir
+#
+# unless you override the value of prefix at make-time.
+EOF
+    echo
+  fi
+]])
 AC_SUBST([PMDIR])
 
 AC_CONFIG_FILES([Makefile])

doc/HOWTO-RELEASE

@@ -7,14 +7,32 @@ How to make a new release of GNU Stow
 
   - Check CPAN distribution will work via Module::Build:
 
-      - Run ./configure && make to generate stow, chkstow, and lib/Stow.pm
+      - Generate stow, chkstow, and lib/Stow.pm via:
+
+          eval `perl -V:siteprefix`
+          ./configure --prefix=$siteprefix && make
+
         (N.B. the CPAN distribution will contain these files, whereas
         the GNU distribution will not.)
-      - Run perl Build.PL.
+
-      - Run ./Build test
+      - Make sure bin/stow does not contain a "use lib" line.  This
-      - Run ./Build install
+        should only happen if the installation directory for Perl
-      - Run ./Build distcheck
+        modules (--with-pmdir's default value) is not in Perl's
-      - Run ./Build distmeta and check META.* have the new version number.
+        built-in @INC, which would be caused by ./configure's default
+        prefix (/usr/local) not matching your Perl's siteprefix, but
+        the above --prefix should prevent that, as would:
+
+          ./configure --with-pmdir=`perl -le 'print $INC[0]'`
+
+      - Make sure all the following commands all run successfully:
+
+          perl Build.PL
+          ./Build test
+          ./Build install
+          ./Build distcheck
+          ./Build distmeta
+
+      - Check META.yaml and META.json have the new version number.
 
   - Ensure all changes are committed to git.