autoupdate (for gendocs.sh accepting --email)

[gnulib.git] / doc / make-stds.texi

diff --git a/doc/make-stds.texi b/doc/make-stds.texi
index 8e8d65e..055996e 100644 (file)
--- a/doc/make-stds.texi
+++ b/doc/make-stds.texi
@@ -8,11 +8,11 @@
 @cindex conventions for makefiles
 @cindex standards for makefiles
 
 @cindex conventions for makefiles
 @cindex standards for makefiles
 

-@c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
-
+@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
+@c 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c

 @c Permission is granted to copy, distribute and/or modify this document
 @c Permission is granted to copy, distribute and/or modify this document

-@c under the terms of the GNU Free Documentation License, Version 1.1
+@c under the terms of the GNU Free Documentation License, Version 1.3

 @c or any later version published by the Free Software Foundation;
 @c with no Invariant Sections, with no
 @c Front-Cover Texts, and with no Back-Cover Texts.
 @c or any later version published by the Free Software Foundation;
 @c with no Invariant Sections, with no
 @c Front-Cover Texts, and with no Back-Cover Texts.


@@ -33,14 +33,17 @@ chapter
 @end iftex
 describes conventions for writing the Makefiles for GNU programs.
 Using Automake will help you write a Makefile that follows these
 @end iftex
 describes conventions for writing the Makefiles for GNU programs.
 Using Automake will help you write a Makefile that follows these

-conventions.
+conventions.  For more information on portable Makefiles, see
+@sc{posix} and @ref{Portable Make, Portable Make Programming,, autoconf,
+Autoconf}.
+

 
 @menu
 * Makefile Basics::             General conventions for Makefiles.
 * Utilities in Makefiles::      Utilities to be used in Makefiles.
 * Command Variables::           Variables for specifying commands.
 
 @menu
 * Makefile Basics::             General conventions for Makefiles.
 * Utilities in Makefiles::      Utilities to be used in Makefiles.
 * Command Variables::           Variables for specifying commands.

-* Directory Variables::         Variables for installation directories.

 * DESTDIR::                     Supporting staged installs.
 * DESTDIR::                     Supporting staged installs.

+* Directory Variables::         Variables for installation directories.

 * Standard Targets::            Standard targets for users.
 * Install Command Categories::  Three categories of commands in the `install'
                                   rule: normal, pre-install and post-install.
 * Standard Targets::            Standard targets for users.
 * Install Command Categories::  Three categories of commands in the `install'
                                   rule: normal, pre-install and post-install.


@@ -144,8 +147,10 @@ subtargets) work correctly with a parallel @code{make}.
 @section Utilities in Makefiles
 
 Write the Makefile commands (and any shell scripts, such as
 @section Utilities in Makefiles
 
 Write the Makefile commands (and any shell scripts, such as

-@code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
-special features of @code{ksh} or @code{bash}.
+@code{configure}) to run under @code{sh} (both the traditional Bourne
+shell and the @sc{posix} shell), not @code{csh}.  Don't use any
+special features of @code{ksh} or @code{bash}, or @sc{posix} features
+not widely supported in traditional Bourne @code{sh}.

 
 The @code{configure} script and the Makefile rules for building and
 installation should not use any utilities directly except these:
 
 The @code{configure} script and the Makefile rules for building and
 installation should not use any utilities directly except these:


@@ -155,18 +160,23 @@ installation should not use any utilities directly except these:
 @c mkfifo mknod tee uname
 
 @example
 @c mkfifo mknod tee uname
 
 @example

-cat cmp cp diff echo egrep expr false grep install-info
-ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
+awk cat cmp cp diff echo egrep expr false grep install-info
+ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch tr true

 @end example
 
 @end example
 

-The compression program @code{gzip} can be used in the @code{dist} rule.
+Compression programs such as @code{gzip} can be used in the
+@code{dist} rule.
+
+Generally, stick to the widely-supported (usually
+@sc{posix}-specified) options and features of these programs.  For
+example, don't use @samp{mkdir -p}, convenient as it may be, because a
+few systems don't support it at all and with others, it is not safe
+for parallel execution.  For a list of known incompatibilities, see
+@ref{Portable Shell, Portable Shell Programming,, autoconf, Autoconf}.

 
 

-Stick to the generally supported options for these programs.  For
-example, don't use @samp{mkdir -p}, convenient as it may be, because
-most systems don't support it.

 
 It is a good idea to avoid creating symbolic links in makefiles, since a
 
 It is a good idea to avoid creating symbolic links in makefiles, since a

-few systems don't support them.
+few file systems don't support them.

 
 The Makefile rules for building and installation can also use compilers
 and related programs, but should do so via @code{make} variables so that the
 
 The Makefile rules for building and installation can also use compilers
 and related programs, but should do so via @code{make} variables so that the


@@ -275,10 +285,12 @@ $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
 However, it is preferable to support a @code{DESTDIR} prefix on the
 target files, as explained in the next section.
 
 However, it is preferable to support a @code{DESTDIR} prefix on the
 target files, as explained in the next section.
 

-@noindent
-Always use a file name, not a directory name, as the second argument of
-the installation commands.  Use a separate command for each file to be
-installed.
+It is acceptable, but not required, to install multiple files in one
+command, with the final argument being a directory, as in:
+
+@example
+$(INSTALL_PROGRAM) foo bar baz $(bindir)
+@end example

 
 
 @node DESTDIR
 
 
 @node DESTDIR


@@ -296,9 +308,8 @@ $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
 @end example
 
 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
 @end example
 

-The @code{DESTDIR} variable is specified by the user, either to the
-@file{configure} script or, more commonly, on the @code{make} command
-line.  For example:
+The @code{DESTDIR} variable is specified by the user on the @code{make}
+command line as an absolute file name.  For example:

 
 @example
 make DESTDIR=/tmp/stage install
 
 @example
 make DESTDIR=/tmp/stage install


@@ -778,7 +789,7 @@ manuals, and you wish to install HTML documentation with many files
 certainly want to use subdirectories, or two nodes with the same name
 in different manuals will overwrite each other.
 
 certainly want to use subdirectories, or two nodes with the same name
 in different manuals will overwrite each other.
 

-Please make these @code{install-@var{format}} targets invoke the 
+Please make these @code{install-@var{format}} targets invoke the

 commands for the @var{format} target, for example, by making
 @var{format} a dependency.
 
 commands for the @var{format} target, for example, by making
 @var{format} a dependency.
 


@@ -957,6 +968,8 @@ then @code{tar} that subdirectory.
 
 Compress the tar file with @code{gzip}.  For example, the actual
 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
 
 Compress the tar file with @code{gzip}.  For example, the actual
 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.

+It is ok to support other free compression formats as well, such as
+@code{bzip2} and @code{lzma}.

 
 The @code{dist} target should explicitly depend on all non-source files
 that are in the distribution, to make sure they are up to date in the
 
 The @code{dist} target should explicitly depend on all non-source files
 that are in the distribution, to make sure they are up to date in the