autoconf-patches
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

stronger docs on @SHELL@ usage in Makefile


From: Eric Blake
Subject: stronger docs on @SHELL@ usage in Makefile
Date: Wed, 9 Apr 2008 18:15:45 +0000 (UTC)
User-agent: Loom/3.14 (http://gmane.org/)

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 <address@hidden>
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 <address@hidden>
---
 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  <address@hidden>
+
+       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 <address@hidden>  (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
 
address@hidden
+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
address@hidden @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
address@hidden, 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 <address@hidden>
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 <address@hidden>
---
 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  <address@hidden>
 
+       * 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},
address@hidden 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},
address@hidden 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 @address@hidden  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
address@hidden variable @code{MAKE}.  Most versions of @command{make} set
address@hidden 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
address@hidden @code{make macro=value} and Submakes
address@hidden @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
address@hidden Exit Status of @code{make -k}
address@hidden @code{make -k}
address@hidden Exit Status of @command{make -k}
address@hidden @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
address@hidden so @code{make} builtin rules don't inadvertently
address@hidden 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







reply via email to

[Prev in Thread] Current Thread [Next in Thread]