Based on Bruno's comments on this thread: http://lists.gnu.org/archive/html/bug-libtool/2008-04/msg00029.html
Does this patch look okay to install? >From adc77bd74d8ab1804cfee9079002043d6e05d8cd Mon Sep 17 00:00:00 2001 From: Eric Blake <[EMAIL PROTECTED]> Date: Wed, 9 Apr 2008 12:09:45 -0600 Subject: [PATCH] Tweak wording about SHELL in Makefile. * 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. Signed-off-by: Eric Blake <[EMAIL PROTECTED]> --- ChangeLog | 8 ++++++++ doc/autoconf.texi | 21 +++++++++++++++------ 2 files changed, 23 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 70528e5..6c6c75b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2008-04-09 Eric Blake <[EMAIL PROTECTED]> + + Tweak wording about SHELL in Makefile. + * 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. + 2008-04-09 Slava Sysoltsev <[EMAIL PROTECTED]> (tiny change) Flush buffered output before exit. diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 49ade0f..bfebf46 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -15780,13 +15780,22 @@ your makefiles. If you use Autoconf, do SHELL = @@SHELL@@ @end example [EMAIL PROTECTED] +If you use Automake, this is done for you. + Do not force @code{SHELL = /bin/sh} because that is not correct -everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when -its @acronym{GNU} @code{make} port sees such a setting it enters a special -emulation mode where features like pipes and redirections are emulated -on top of DOS's @command{command.com}. Unfortunately this emulation is -incomplete; for instance it does not handle command substitutions. -On @acronym{DJGPP} @code{SHELL} should point to Bash. +everywhere. Remember, @file{/bin/sh} is not Posix compliant on many +systems, such as FreeBSD 4, NetBSD 3, AIX 3, Solaris 10, or Tru64. +Additionally, @acronym{DJGPP} lacks @code{/bin/sh}, and when its [EMAIL PROTECTED] @command{make} port sees such a setting it enters a +special emulation mode where features like pipes and redirections are +emulated on top of DOS's @command{command.com}. Unfortunately this +emulation is incomplete; for instance it does not handle command +substitutions. Using @code{@@SHELL@@} means that your makefile will +benefit from the same improved shell, such as @command{bash} or [EMAIL PROTECTED], that was discovered during @command{configure}, so that +you aren't fighting two different sets of shell bugs between the two +contexts. Posix-compliant @command{make} should never acquire the value of $(SHELL) from the environment, even when @code{make -e} is used -- 1.5.5 >From 1757082e476348ad7ef2612158f2326ea0160b2e Mon Sep 17 00:00:00 2001 From: Eric Blake <[EMAIL PROTECTED]> Date: Wed, 9 Apr 2008 12:14:06 -0600 Subject: [PATCH] Formatting improvements. * doc/autoconf.texi: Use @command{make} throughout. Signed-off-by: Eric Blake <[EMAIL PROTECTED]> --- ChangeLog | 2 + doc/autoconf.texi | 56 ++++++++++++++++++++++++++-------------------------- 2 files changed, 30 insertions(+), 28 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6c6c75b..e72d95d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2008-04-09 Eric Blake <[EMAIL PROTECTED]> + * doc/autoconf.texi: Use @command{make} throughout. + Tweak wording about SHELL in Makefile. * doc/autoconf.texi (The Make Macro SHELL): Stronger wording on the importance of proper SHELL settings. diff --git a/doc/autoconf.texi b/doc/autoconf.texi index bfebf46..66c42bb 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -497,7 +497,7 @@ Portable Make Programming * Backslash-Newline-Newline:: Empty last lines in macro definitions * Backslash-Newline Comments:: Spanning comments across line boundaries * Long Lines in Makefiles:: Line length limitations -* Macros and Submakes:: @code{make macro=value} and submakes +* Macros and Submakes:: @command{make macro=value} and submakes * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues * The Make Macro SHELL:: @code{$(SHELL)} portability issues * Comments in Make Rules:: Other problems with Make comments @@ -800,17 +800,17 @@ so on, mean that developers must painfully (and often incorrectly) reinvent the wheel for each project. Portability is non-trivial, thanks to the quirks of @command{make} on many systems. On top of all this is the manual labor required to implement the many standard targets that users -have come to expect (@code{make install}, @code{make distclean}, [EMAIL PROTECTED] uninstall}, etc.). Since you are, of course, using Autoconf, -you also have to insert repetitive code in your @code{Makefile.in} to +have come to expect (@command{make install}, @command{make distclean}, [EMAIL PROTECTED] uninstall}, etc.). Since you are, of course, using Autoconf, +you also have to insert repetitive code in your @file{Makefile.in} to recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions provided by @command{configure}. Into this mess steps @dfn{Automake}. @cindex Automake -Automake allows you to specify your build needs in a @code{Makefile.am} +Automake allows you to specify your build needs in a @file{Makefile.am} file with a vastly simpler and more powerful syntax than that of a plain -makefile, and then generates a portable @code{Makefile.in} for -use with Autoconf. For example, the @code{Makefile.am} to build and +makefile, and then generates a portable @file{Makefile.in} for +use with Autoconf. For example, the @file{Makefile.am} to build and install a simple ``Hello world'' program might look like: @example @@ -819,10 +819,10 @@ hello_SOURCES = hello.c @end example @noindent -The resulting @code{Makefile.in} (~400 lines) automatically supports all +The resulting @file{Makefile.in} (~400 lines) automatically supports all the standard targets, the substitutions provided by Autoconf, automatic dependency tracking, @code{VPATH} building, and so on. @command{make} -builds the @code{hello} program, and @code{make install} installs it +builds the @code{hello} program, and @command{make install} installs it in @file{/usr/local/bin} (or whatever prefix was given to @command{configure}, if not @file{/usr/local}). @@ -1943,7 +1943,7 @@ either absolute or relative to @[EMAIL PROTECTED] The default is @file{install-sh}. The other files are not checked for, so that using @code{AC_PROG_INSTALL} does not automatically require distributing the other auxiliary files. It checks for @file{install.sh} also, but that -name is obsolete because some @code{make} have a rule that creates +name is obsolete because some @command{make} have a rule that creates @file{install} from it if there is no makefile. The auxiliary directory is commonly named @file{build-aux}. @@ -2009,7 +2009,7 @@ are honored. The location of your @code{AC_OUTPUT} invocation is the exact point where configuration actions are taken: any code afterwards is -executed by @code{configure} once @command{config.status} was run. If +executed by @command{configure} once @command{config.status} was run. If you want to bind actions to @command{config.status} itself (independently of whether @command{configure} is being run), see @ref{Configuration Commands, , Running Arbitrary Configuration @@ -2022,7 +2022,7 @@ Historically, the usage of @code{AC_OUTPUT} was somewhat different. If you run @command{make} in subdirectories, you should run it using the [EMAIL PROTECTED] variable @code{MAKE}. Most versions of @command{make} set [EMAIL PROTECTED] variable @code{MAKE}. Most versions of @command{make} set @code{MAKE} to the name of the @command{make} program plus any options it was given. (But many do not include in it the values of any variables set on the command line, so those are not passed on automatically.) @@ -2041,7 +2041,7 @@ Otherwise, define @code{SET_MAKE} to a macro definition that sets @end defmac If you use this macro, place a line like this in each @file{Makefile.in} -that runs @code{MAKE} on other directories: +that runs @command{MAKE} on other directories: @example @@SET_MAKE@@ @@ -2894,7 +2894,7 @@ variable substitutions on the value of @code{VPATH}. @command{configure} substitutes the correct value for @code{srcdir} when it produces @file{Makefile}. -Do not use the @code{make} variable @code{$<}, which expands to the +Do not use the @command{make} variable @code{$<}, which expands to the file name of the file in the source directory (found with @code{VPATH}), except in implicit rules. (An implicit rule is one such as @samp{.c.o}, which tells how to create a @file{.o} file from a @file{.c} file.) Some @@ -8721,7 +8721,7 @@ substitution replaces the whole line, including the spaces, tabs, and the terminating newline. This macro is useful for inserting makefile fragments containing -special dependencies or other @code{make} directives for particular host +special dependencies or other @command{make} directives for particular host or target types into makefiles. For example, @file{configure.ac} could contain: @@ -11474,7 +11474,7 @@ Also see the @code{AC_PROG_MKDIR_P} macro (@pxref {Particular Programs}). @defmac AS_SHELL_SANITIZE @asindex{SHELL_SANITIZE} -Initialize the shell suitably for @code{configure} scripts. This has +Initialize the shell suitably for @command{configure} scripts. This has the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other environment variables for predictable results from configuration tests. For example, it sets @env{LC_ALL} to change to the default C locale. @@ -15524,7 +15524,7 @@ itself. * Backslash-Newline-Newline:: Empty last lines in macro definitions * Backslash-Newline Comments:: Spanning comments across line boundaries * Long Lines in Makefiles:: Line length limitations -* Macros and Submakes:: @code{make macro=value} and submakes +* Macros and Submakes:: @command{make macro=value} and submakes * The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues * The Make Macro SHELL:: @code{$(SHELL)} portability issues * Comments in Make Rules:: Other problems with Make comments @@ -15666,7 +15666,7 @@ makefile with lines longer than around 20 kB. Earlier versions are reported to exit with @code{Line too long} diagnostics. @node Macros and Submakes [EMAIL PROTECTED] @code{make macro=value} and Submakes [EMAIL PROTECTED] @command{make macro=value} and Submakes A command-line variable definition such as @code{foo=bar} overrides any definition of @code{foo} in a makefile. Some @command{make} @@ -15717,7 +15717,7 @@ command line. When run inside a @command{make} rule, @acronym{GNU} Moreover, using @option{-e} could have unexpected side effects if your environment contains some other macros usually defined by the -makefile. (See also the note about @code{make -e} and @code{SHELL} +makefile. (See also the note about @command{make -e} and @code{SHELL} below.) Another way to propagate overrides to submakes is to do it @@ -15770,8 +15770,8 @@ macro to spawn shell processes and execute Make rules. This is a builtin macro supplied by @command{make}, but it can be modified by a makefile or by a command-line argument. -Not all @command{make} implementations define this @code{SHELL} macro. -Tru64 +Not all @command{make} implementations define this @code{SHELL} macro as +a builtin macro. Tru64 @command{make} is an example; this implementation always uses @code{/bin/sh}. So it's a good idea to always define @code{SHELL} in your makefiles. If you use Autoconf, do @@ -15798,7 +15798,7 @@ you aren't fighting two different sets of shell bugs between the two contexts. Posix-compliant @command{make} should never acquire the value of -$(SHELL) from the environment, even when @code{make -e} is used +$(SHELL) from the environment, even when @command{make -e} is used (otherwise, think about what would happen to your rules if @code{SHELL=/bin/tcsh}). @@ -15866,10 +15866,10 @@ World @end example @node make -k Status [EMAIL PROTECTED] Exit Status of @code{make -k} [EMAIL PROTECTED] @code{make -k} [EMAIL PROTECTED] Exit Status of @command{make -k} [EMAIL PROTECTED] @command{make -k} -Do not rely on the exit status of @code{make -k}. Some implementations +Do not rely on the exit status of @command{make -k}. Some implementations reflect whether they encountered an error in their exit status; other implementations always succeed. @@ -18198,7 +18198,7 @@ Makefile: Makefile.in config.status @noindent (If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is -no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally +no need to set @code{CONFIG_HEADERS} in the @command{make} rules. Equally for @code{CONFIG_COMMANDS}, etc.) @@ -19401,7 +19401,7 @@ in a particular package's source directory), you must rename it to @file{acsite.m4}. @xref{autoconf Invocation}. If you distribute @file{install.sh} with your package, rename it to [EMAIL PROTECTED] so @code{make} builtin rules don't inadvertently [EMAIL PROTECTED] so @command{make} builtin rules don't inadvertently create a file called @file{install} from it. @code{AC_PROG_INSTALL} looks for the script under both names, but it is best to use the new name. @@ -20874,7 +20874,7 @@ result, incompatibilities between headers went unnoticed during configuration, and maintainers finally had to deal with this issue elsewhere. -As of Autoconf 2.56 both checks are performed, and @code{configure} +As of Autoconf 2.56 both checks are performed, and @command{configure} complains loudly if the compiler and the preprocessor do not agree. For the time being the result used is that of the preprocessor, to give maintainers time to adjust their @file{configure.ac}, but in the -- 1.5.5
