[Top][All Lists]
[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
- stronger docs on @SHELL@ usage in Makefile,
Eric Blake <=