Formerly make-stds.texi.~29~

1 files changed, 248 insertions, 74 deletions

diff --git a/make-stds.texi b/make-stds.texi
index 07a9d36..14caf42 100644
--- a/make-stds.texi
+++ b/make-stds.texi
@@ -32,6 +32,20 @@ to avoid trouble on systems where the @code{SHELL} variable might be
 inherited from the environment.  (This is never a problem with GNU
 @code{make}.)
 
+Different @code{make} programs have incompatible suffix lists and
+implicit rules, and this sometimes creates confusion or misbehavior.  So
+it is a good idea to set the suffix list explicitly using only the
+suffixes you need in the particular Makefile, like this:
+
+@example
+.SUFFIXES:
+.SUFFIXES: .c .o
+@end example
+
+@noindent
+The first line clears out the suffix list, the second introduces all
+suffixes which may be subject to implicit rules in this Makefile.
+
 Don't assume that @file{.} is in the path for command execution.  When
 you need to run programs that are a part of your package during the
 make, please make sure that it uses @file{./} if the program is built as
@@ -43,33 +57,34 @@ The distinction between @file{./} and @file{$(srcdir)/} is important
 when using the @samp{--srcdir} option to @file{configure}.  A rule of
 the form:
 
-@example
+@smallexample
 foo.1 : foo.man sedscript
         sed -e sedscript foo.man > foo.1
-@end example
+@end smallexample
 
 @noindent
 will fail when the current directory is not the source directory,
 because @file{foo.man} and @file{sedscript} are not in the current
 directory.
 
-Relying on @samp{VPATH} to find the source file will work in the case
-where there is a single dependency file, since the @file{make} automatic
-variable @samp{$<} will represent the source file wherever it is.  A
-makefile target like
+When using GNU @code{make}, relying on @samp{VPATH} to find the source
+file will work in the case where there is a single dependency file,
+since the @file{make} automatic variable @samp{$<} will represent the
+source file wherever it is.  (Many versions of @code{make} set @samp{$<}
+only in implicit rules.)  A makefile target like
 
-@example
+@smallexample
 foo.o : bar.c
-        $(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o
-@end example
+        $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
+@end smallexample
 
 @noindent
 should instead be written as
 
-@example
+@smallexample
 foo.o : bar.c
-        $(CC) $(CFLAGS) $< -o $@@
-@end example
+        $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
+@end smallexample
 
 @noindent
 in order to allow @samp{VPATH} to work correctly.  When the target has
@@ -77,10 +92,10 @@ multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
 way to make the rule work well.  For example, the target above for
 @file{foo.1} is best written as:
 
-@example
+@smallexample
 foo.1 : foo.man sedscript
-        sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
-@end example
+        sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
+@end smallexample
 
 @node Utilities in Makefiles
 @section Utilities in Makefiles
@@ -107,12 +122,21 @@ user can substitute alternatives.  Here are some of the programs we
 mean:
 
 @example
-ar bison cc flex install ld lex make ranlib yacc
+ar bison cc flex install ld lex
+make makeinfo ranlib texi2dvi yacc
+@end example
+
+Use the following @code{make} variables:
+
+@example
+$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
+$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
 @end example
 
-When you use @code{ranlib}, you should test whether it exists, and run
-it only if it exists, so that the distribution will work on systems that
-don't have @code{ranlib}.
+When you use @code{ranlib}, you should make sure nothing bad happens if
+the system does not have @code{ranlib}.  Arrange to ignore an error
+from that command, and print a message before the command to tell the
+user that failure of the @code{ranlib} command does not mean a problem.
 
 If you use symbolic links, you should implement a fallback for systems
 that don't have symbolic links.
@@ -129,29 +153,62 @@ All GNU programs should have the following targets in their Makefiles:
 @table @samp
 @item all
 Compile the entire program.  This should be the default target.  This
-target need not rebuild any documentation files; info files should
+target need not rebuild any documentation files; Info files should
 normally be included in the distribution, and DVI files should be made
 only when explicitly asked for.
 
 @item install
 Compile the program and copy the executables, libraries, and so on to
 the file names where they should reside for actual use.  If there is a
-simple test to verify that a program is properly installed then run that
-test.
+simple test to verify that a program is properly installed, this target
+should run that test.
+
+The commands should create all the directories in which files are to be
+installed, if they don't already exist.  This includes the directories
+specified as the values of the variables @code{prefix} and
+@code{exec_prefix}, as well as all subdirectories that are needed.
+One way to do this is by means of an @code{installdirs} target
+as described below.
 
 Use @samp{-} before any command for installing a man page, so that
 @code{make} will ignore any errors.  This is in case there are systems
 that don't have the Unix man page documentation system installed.
 
-In the future, when we have a standard way of installing info files,
-@samp{install} targets will be the proper place to do so.
+The way to install Info files is to copy them into @file{$(infodir)}
+with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
+the @code{install-info} program if it is present.  @code{install-info}
+is a script that edits the Info @file{dir} file to add or update the
+menu entry for the given Info file; it will be part of the Texinfo package.
+Here is a sample rule to install an Info file:
+
+@comment This example has been carefully formatted for the Make manual.
+@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
+@smallexample
+$(infodir)/foo.info: foo.info
+# There may be a newer info file in . than in srcdir.
+        -if test -f foo.info; then d=.; \
+         else d=$(srcdir); fi; \
+        $(INSTALL_DATA) $$d/foo.info $@@; \
+# Run install-info only if it exists.
+# Use `if' instead of just prepending `-' to the
+# line so we notice real errors from install-info.
+# We use `$(SHELL) -c' because some shells do not
+# fail gracefully when there is an unknown command.
+        if $(SHELL) -c 'install-info --version' \
+           >/dev/null 2>&1; then \
+          install-info --infodir=$(infodir) $$d/foo.info; \
+        else true; fi
+@end smallexample
 
 @item uninstall
 Delete all the installed files that the @samp{install} target would
 create (but not the noninstalled files such as @samp{make all} would
 create).
 
+@comment The gratuitous blank line here is to make the table look better
+@comment in the printed Make manual.  Please leave it in.
 @item clean
+
 Delete all files from the current directory that are normally created by
 building the program.  Don't delete the files that record the
 configuration.  Also preserve files that could be made by building, but
@@ -174,8 +231,8 @@ is rarely necessary and takes a lot of time.
 @item realclean
 Delete everything from the current directory that can be reconstructed
 with this Makefile.  This typically includes everything deleted by
-distclean, plus more: C source files produced by Bison, tags tables,
-info files, and so on.
+@code{distclean}, plus more: C source files produced by Bison, tags tables,
+Info files, and so on.
 
 One exception, however: @samp{make realclean} should not delete
 @file{configure} even if @file{configure} can be remade using a rule in
@@ -187,34 +244,35 @@ and then begin to build the program.
 Update a tags table for this program.
 
 @item info
-Generate any info files needed.  The best way to write the rules is as
+Generate any Info files needed.  The best way to write the rules is as
 follows:
 
-@example
-info:  foo.info
+@smallexample
+info: foo.info
 
-foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
+foo.info: foo.texi chap1.texi chap2.texi
         $(MAKEINFO) $(srcdir)/foo.texi
-@end example
+@end smallexample
 
 @noindent
-You must define the variable @code{MAKEINFO} in the Makefile.
-It should run the Makeinfo program, which is part of the Texinfo2 distribution.
+You must define the variable @code{MAKEINFO} in the Makefile.  It should
+run the @code{makeinfo} program, which is part of the Texinfo
+distribution.
 
 @item dvi
 Generate DVI files for all TeXinfo documentation.  
 For example:
 
-@example
+@smallexample
 dvi: foo.dvi
 
-foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
+foo.dvi: foo.texi chap1.texi chap2.texi
         $(TEXI2DVI) $(srcdir)/foo.texi
-@end example
+@end smallexample
 
 @noindent
 You must define the variable @code{TEXI2DVI} in the Makefile.  It should
-run the program @code{texi2dvi}, which is part of the Texinfo2
+run the program @code{texi2dvi}, which is part of the Texinfo
 distribution.  Alternatively, write just the dependencies, and allow GNU
 Make to provide the command.
 
@@ -243,6 +301,34 @@ the self-tests so that they work when the program is built but not
 installed.
 @end table
 
+The following targets are suggested as conventional names, for programs
+in which they are useful.
+
+@table @code
+@item installcheck
+Perform installation tests (if any).  The user must build and install
+the program before running the tests.  You should not assume that
+@file{$(bindir)} is in the search path.  
+
+@item installdirs
+It's useful to add a target named @samp{installdirs} to create the
+directories where files are installed, and their parent directories.
+There is a script called @file{mkinstalldirs} which is convenient for
+this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
+You can use a rule like this:
+
+@comment This has been carefully formatted to look decent in the Make manual.
+@comment Please be sure not to make it extend any further to the right.--roland
+@smallexample
+# Make sure all installation directories (e.g. $(bindir))
+# actually exist by making them if necessary.
+installdirs: mkinstalldirs
+        $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
+                                $(libdir) $(infodir) \
+                                $(mandir)
+@end smallexample
+@end table
+
 @node Command Variables
 @section Variables for Specifying Commands
 
@@ -274,12 +360,12 @@ Instead, arrange to pass the necessary options to the C compiler
 independently of @code{CFLAGS}, by writing them explicitly in the
 compilation commands or by defining an implicit rule, like this:
 
-@example
+@smallexample
 CFLAGS = -g
-ALL_CFLAGS = $(CFLAGS) -I.
+ALL_CFLAGS = -I. $(CFLAGS)
 .c.o:
-        $(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $<
-@end example
+        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
+@end smallexample
 
 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
 @emph{required} for proper compilation.  You can consider it a default
@@ -287,11 +373,15 @@ that is only recommended.  If the package is set up so that it is
 compiled with GCC by default, then you might as well include @samp{-O}
 in the default value of @code{CFLAGS} as well.
 
+Put @code{CFLAGS} last in the compilation command, after other variables
+containing compiler options, so the user can use @code{CFLAGS} to
+override the others.
+
 Every Makefile should define the variable @code{INSTALL}, which is the
 basic command for installing a file into the system.
 
-Every Makefile should also define variables @code{INSTALL_PROGRAM} and
-@code{INSTALL_DATA}.  (The default for each of these should be
+Every Makefile should also define the variables @code{INSTALL_PROGRAM}
+and @code{INSTALL_DATA}.  (The default for each of these should be
 @code{$(INSTALL)}.)  Then it should use those variables as the commands
 for actual installation, for executables and nonexecutables
 respectively.  Use these variables as follows:
@@ -311,7 +401,11 @@ installed.
 
 Installation directories should always be named by variables, so it is
 easy to install in a nonstandard place.  The standard names for these
-variables are:
+variables are as follows.
+
+These two variables set the root for the installation.  All the other
+installation directories should be subdirectories of one of these two,
+and nothing should be directly installed into these two directories.
 
 @table @samp
 @item prefix
@@ -320,39 +414,107 @@ below.  The default value of @code{prefix} should be @file{/usr/local}
 (at least for now).
 
 @item exec_prefix
-A prefix used in constructing the default values of the some of the
+A prefix used in constructing the default values of some of the
 variables listed below.  The default value of @code{exec_prefix} should
 be @code{$(prefix)}.
 
 Generally, @code{$(exec_prefix)} is used for directories that contain
 machine-specific files (such as executables and subroutine libraries),
 while @code{$(prefix)} is used directly for other directories.
+@end table
+
+Executable programs are installed in one of the following directories.
 
+@table @samp
 @item bindir
 The directory for installing executable programs that users can run.
 This should normally be @file{/usr/local/bin}, but write it as
 @file{$(exec_prefix)/bin}.
 
-@item libdir
-The directory for installing executable files to be run by the program
-rather than by users.  Object files and libraries of object code should
-also go in this directory.  The idea is that this directory is used for
-files that pertain to a specific machine architecture, but need not be
-in the path for commands.  The value of @code{libdir} should normally be
-@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+@item sbindir
+The directory for installing executable programs that can be run from
+the shell, but are only generally useful to system administrators.  This
+should normally be @file{/usr/local/sbin}, but write it as
+@file{$(exec_prefix)/sbin}.
+
+@item libexecdir
+@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
+The directory for installing executable programs to be run by other
+programs rather than by users.  This directory should normally be
+@file{/usr/local/libexec}, but write @file{$(exec_prefix)/libexec}.
+@end table
 
-@item datadir
-The directory for installing read-only data files which the programs
-refer to while they run.  This directory is used for files which are
-independent of the type of machine being used.  This should normally be
-@file{/usr/local/lib}, but write it as @file{$(prefix)/lib}.
+Data files used by the program during its execution are divided into
+categories in two ways.
+
+@itemize @bullet
+@item
+Some files are normally modified by programs; others are never normally
+modified (though users may edit some of these).
+
+@item
+Some files are architecture-independent and can be shared by all
+machines at a site; some are architecture-dependent and can be shared
+only by machines of the same kind and operating system; others may never
+be shared between two machines.
+@end itemize
+
+This makes for six different possibilities.  However, we want to
+discourage the use of architecture-dependent files, aside from of object
+files and libraries.  It is much cleaner to make other data files
+architecture-independent, and it is generally not hard.
 
-@item statedir
+Therefore, here are the variables makefiles should use to specify
+directories:
+
+@table @samp
+@item datadir
+The directory for installing read-only architecture independent data
+files.  This should normally be @file{/usr/local/share}, but write it as
+@file{$(prefix)/share}.  As a special exception, see @file{$(infodir)}
+and @file{$(includedir)} below.
+
+@item sysconfdir
+The directory for installing read-only data files that pertain to a
+single machine--that is to say, files for configuring a host.  Mailer
+and network configuration files, @file{/etc/passwd}, and so forth belong
+here.  All the files in this directory should be ordinary ASCII text
+files.  This directory should normally be @file{/usr/local/etc}, but
+write it as @file{$(prefix)/etc}.
+
+@c rewritten to avoid overfull hbox --tower
+Do not install executables
+@c here
+in this directory (they probably
+belong in @file{$(libexecdir)} or @file{$(sbindir))}.  Also do not
+install files that are modified in the normal course of their use
+(programs whose purpose is to change the configuration of the system
+excluded).  Those probably belong in @file{$(localstatedir)}.
+
+@item sharedstatedir
+The directory for installing architecture-independent data files which
+the programs modify while they run.  This should normally be
+@file{/usr/local/com}, but write it as @file{$(prefix)/com}.
+
+@item localstatedir
 The directory for installing data files which the programs modify while
-they run.  These files should be independent of the type of machine
-being used, and it should be possible to share them among machines at a
-network installation.  This should normally be @file{/usr/local/lib},
-but write it as @file{$(prefix)/lib}.
+they run, and that pertain to one specific machine.  Users should never
+need to modify files in this directory to configure the package's
+operation; put such configuration information in separate files that go
+in @file{datadir} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
+should normally be @file{/usr/local/var}, but write it as
+@file{$(prefix)/var}.
+
+@item libdir
+The directory for object files and libraries of object code.  Do not
+install executables here, they probably belong in @file{$(libexecdir)}
+instead.  The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+
+@item infodir
+The directory for installing the Info files for this package.  By
+default, it should be @file{/usr/local/info}, but it should be written
+as @file{$(prefix)/info}.
 
 @item includedir
 @c rewritten to avoid overfull hbox --roland
@@ -384,14 +546,19 @@ file in the @code{oldincludedir} directory if either (1) there is no
 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
 package.
 
-The way to tell whether @file{foo.h} came from the Foo package is to put
-a magic string in the file---part of a comment---and grep for that
-string.
+To tell whether @file{foo.h} came from the Foo package, put a magic
+string in the file---part of a comment---and grep for that string.
+@end table
+
+Unix-style man pages are installed in one of the following:
 
+@table @samp
 @item mandir
 The directory for installing the man pages (if any) for this package.
 It should include the suffix for the proper section of the
-manual---usually @samp{1} for a utility.
+manual---usually @samp{1} for a utility.  It will normally be
+@file{/usr/local/man/man1}, but you should write it as
+@file{$(prefix)/man/man1}. 
 
 @item man1dir
 The directory for installing section 1 man pages.
@@ -408,13 +575,20 @@ application only.}
 
 @item manext
 The file name extension for the installed man page.  This should contain
-a period followed by the appropriate digit.
+a period followed by the appropriate digit; it should normally be @samp{.1}.
 
-@item infodir
-The directory for installing the info files for this package.  By
-default, it should be @file{/usr/local/info}, but it should be written
-as @file{$(prefix)/info}.
+@item man1ext
+The file name extension for installed section 1 man pages.
+@item man2ext
+The file name extension for installed section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{manext} if the package needs to install man
+pages in more than one section of the manual.
+@end table
+
+And finally, you should set the following variable:
 
+@table @samp
 @item srcdir
 The directory for the sources being compiled.  The value of this
 variable is normally inserted by the @code{configure} shell script.
@@ -422,7 +596,7 @@ variable is normally inserted by the @code{configure} shell script.
 
 For example:
 
-@example
+@smallexample
 @c I have changed some of the comments here slightly to fix an overfull
 @c hbox, so the make manual can format correctly. --roland
 # Common prefix for installation directories.
@@ -432,10 +606,10 @@ exec_prefix = $(prefix)
 # Where to put the executable for the command `gcc'.
 bindir = $(exec_prefix)/bin
 # Where to put the directories used by the compiler.
-libdir = $(exec_prefix)/lib
+libexecdir = $(exec_prefix)/libexec
 # Where to put the Info files.
 infodir = $(prefix)/info
-@end example
+@end smallexample
 
 If your program installs a large number of files into one of the
 standard user-specified directories, it might be useful to group them