Re: stronger docs on @SHELL@ usage in Makefile

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Ralf Wildenhues on 4/9/2008 12:27 PM:
| Hi Eric,

Hi Ralf,

|
| * Eric Blake wrote on Wed, Apr 09, 2008 at 08:15:45PM CEST:
|> Does this patch look okay to install?
|
| You meant "these patches", right?

Yes ;)

|
|> * doc/autoconf.texi (The Make Macro SHELL): Stronger wording on
|> the importance of proper SHELL settings.
|> Reported by Bruno Haible, in
|> http://lists.gnu.org/archive/html/bug-libtool/2008-04/msg00029.html.
|
| These parts are probably ok, but the discussion will still take longer
| (I need to check a few things first), so I would appreciate if you could
| wait a little bit.

No problem waiting.  I'm also thinking about rewording the section a bit
more.  Basically, there are multiple problems:

if SHELL is not set explicitly in the Makefile, POSIX make is supposed to
provide a default containing the value of a POSIX-style sh; but some
makes, like Tru64, fail to set a default SHELL.  Workaround - always set
SHELL explicitly

if SHELL is explicitly set in the Makefile, POSIX make is supposed to use
it to invoke make commands, but some makes, like Tru64, blindly execute
/bin/sh.  No direct workaround - commands written in make cannot assume
the fixes that would be available by using a better $SHELL; but the advice
of autoconf was to stick to simple commands in Makefile and factor out
complex ones into separate shell scripts anyway, then invoke those scripts
using $(SHELL) with address@hidden@

if make is run with set -e, POSIX make is supposed to ignore any SHELL in
the environment, but some makes, like Tru64, override an explicit setting.
~ No direct workaround - merely document that users on Tru64 must not run
'make -e' if SHELL is not a POSIX-style sh, or that they should upgrade to
gmake instead

setting SHELL to /bin/sh is not portable; autoconf clients should use
@SHELL@ instead (and automake does this automatically)

In the case of Bruno's problem, I think what happened is:

configure ran, noticed /bin/sh was inadequate, and set @SHELL@ to /bin/ksh.
libtool subtitutes this as address@hidden@ at the start of the script.
But make ran $(SHELL) libtool, with SHELL hard-coded as /bin/sh by Bruno,
and ignored the #! line since it was invoked as an argument to SHELL
rather than as an independent program.
Finally, the generated libtool lacked the _AS_DETECT_BETTER_SHELL logic
that configure had used earlier when setting SHELL.

Telling libtool clients who use autoconf to set 'SHELL = @SHELL@' in their
makefiles (manually, or via Automake) is one thing, but does libtool
intend to be used independently of autoconf, in which case @SHELL@ is not
available?  How do we (or do we even try to) document that in autoconf?

|
|> +       * doc/autoconf.texi: Use @command{make} throughout.
|
|> +* Macros and Submakes::         @command{make macro=value} and submakes
|
| This is not what the texinfo manual suggests:
|
| | Use the address@hidden' command to indicate command names, such as `ls' or
| | `cc'.
| [...]
| |   You should write the name of a program in the ordinary text font,
| | rather than using address@hidden', if you regard it as a new English word,
| | such as `Emacs' or `Bison'.
| |
| |   When writing an entire shell command invocation, as in `ls -l', you
| | should use either address@hidden' or address@hidden' at your discretion.

OK, I think I'll rewrite uses of make with arguments as @samp (it seems
like the manual has more cases of @samp than @code when listing commands
with arguments), and resubmit this patch after the first one is ready to
commit.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkf9d2sACgkQ84KuGfSFAYBqygCfTTN531N2r01NJGYPweoNbGI/
x0QAn0tV7S92NV8irjRuQ26olz9yYbjy
=BPU5
-----END PGP SIGNATURE-----