Initial revision

1 files changed, 449 insertions, 0 deletions

diff --git a/make-stds.texi b/make-stds.texi
new file mode 100644
index 0000000..2c6b808
--- /dev/null
+++ b/make-stds.texi
@@ -0,0 +1,449 @@
+@comment This file is included by both standards.texi and make.texinfo.
+@comment It was broken out of standards.texi on 1/6/93 by roland.
+
+@node Makefile Conventions
+@chapter Makefile Conventions
+@comment standards.texi does not print an index, but make.texinfo does.
+@cindex makefile, conventions for
+@cindex conventions for makefiles
+@cindex standards for makefiles
+
+This chapter describes conventions for writing the Makefiles for GNU programs.
+
+@menu
+* Makefile Basics::
+* Utilities in Makefiles::
+* Standard Targets::
+* Command Variables::
+* Directory Variables::
+@end menu
+
+@node Makefile Basics
+@section General Conventions for Makefiles
+
+Every Makefile should contain this line:
+
+@example
+SHELL = /bin/sh
+@end example
+
+@noindent
+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}.)
+
+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
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code.  Without one of these prefixes, the current search
+path is used.  
+
+The distinction between @file{./} and @file{$(srcdir)/} is important
+when using the @samp{--srcdir} option to @file{configure}.  A rule of
+the form:
+
+@example
+foo.1 : foo.man sedscript
+        sed -e sedscript foo.man > foo.1
+@end example
+
+@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
+
+@example
+foo.o : bar.c
+        $(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o
+@end example
+
+@noindent
+should instead be written as
+
+@example
+foo.o : bar.c
+        $(CC) $(CFLAGS) $< -o $@@
+@end example
+
+@noindent
+in order to allow @samp{VPATH} to work correctly.  When the target has
+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
+foo.1 : foo.man sedscript
+        sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
+@end example
+
+@node Utilities in Makefiles
+@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}.
+
+The @code{configure} script and the Makefile rules for building and
+installation should not use any utilities directly except these:
+
+@example
+cat cmp cp echo egrep expr grep
+ln mkdir mv pwd rm rmdir sed test touch
+@end example
+
+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.
+
+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
+user can substitute alternatives.  Here are some of the programs we
+mean:
+
+@example
+ar bison cc flex install ld lex make ranlib 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}.
+
+If you use symbolic links, you should implement a fallback for systems
+that don't have symbolic links.
+
+It is ok to use other utilities in Makefile portions (or scripts)
+intended only for particular systems where you know those utilities to
+exist.
+
+@node Standard Targets
+@section Standard Targets for Users
+
+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
+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.
+
+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.
+
+@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).
+
+@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
+normally aren't because the distribution comes with them.
+
+Delete @file{.dvi} files here if they are not part of the distribution.
+
+@item distclean
+Delete all files from the current directory that are created by
+configuring or building the program.  If you have unpacked the source
+and built the program without creating any other files, @samp{make
+distclean} should leave only the files that were in the distribution.
+
+@item mostlyclean
+Like @samp{clean}, but may refrain from deleting a few files that people
+normally don't want to recompile.  For example, the @samp{mostlyclean}
+target for GCC does not delete @file{libgcc.a}, because recompiling it
+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.
+
+One exception, however: @samp{make realclean} should not delete
+@file{configure} even if @file{configure} can be remade using a rule in
+the Makefile.  More generally, @samp{make realclean} should not delete
+anything that needs to exist in order to run @file{configure}
+and then begin to build the program.
+
+@item TAGS
+Update a tags table for this program.
+
+@item info
+Generate any info files needed.  The best way to write the rules is as
+follows:
+
+@example
+info:  foo.info
+
+foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
+        $(MAKEINFO) $(srcdir)/foo.texi
+@end example
+
+@noindent
+You must define the variable @code{MAKEINFO} in the Makefile.
+It should run the Makeinfo program, which is part of the Texinfo2 distribution.
+
+@item dvi
+Generate DVI files for all TeXinfo documentation.  
+For example:
+
+@example
+dvi: foo.dvi
+
+foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
+        $(TEXI2DVI) $(srcdir)/foo.texi
+@end example
+
+@noindent
+You must define the variable @code{TEXI2DVI} in the Makefile.  It should
+run the program @code{texi2dvi}, which is part of the Texinfo2
+distribution.  Alternatively, write just the dependencies, and allow GNU
+Make to provide the command.
+
+@item dist
+Create a distribution tar file for this program.  The tar file should be
+set up so that the file names in the tar file start with a subdirectory
+name which is the name of the package it is a distribution for.  This
+name can include the version number.
+
+For example, the distribution tar file of GCC version 1.40 unpacks into
+a subdirectory named @file{gcc-1.40}.
+
+The easiest way to do this is to create a subdirectory appropriately
+named, use @code{ln} or @code{cp} to install the proper files in it, and
+then @code{tar} that subdirectory.
+
+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
+distribution.  
+@xref{Releases, , Making Releases, standards, GNU Coding Standards}.
+
+@item check
+Perform self-tests (if any).  The user must build the program before
+running the tests, but need not install the program; you should write
+the self-tests so that they work when the program is built but not
+installed.
+@end table
+
+@node Command Variables
+@section Variables for Specifying Commands
+
+Makefiles should provide variables for overriding certain commands, options,
+and so on.
+
+In particular, you should run most utility programs via variables.
+Thus, if you use Bison, have a variable named @code{BISON} whose default
+value is set with @samp{BISON = bison}, and refer to it with
+@code{$(BISON)} whenever you need to use Bison.
+
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
+Each program-name variable should come with an options variable that is
+used to supply options to the program.  Append @samp{FLAGS} to the
+program-name variable name to get the options variable name---for
+example, @code{BISONFLAGS}.  (The name @code{CFLAGS} is an exception to
+this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
+in any compilation command that runs the preprocessor, and use
+@code{LDFLAGS} in any compilation command that does linking as well as
+in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+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
+CFLAGS = -g
+ALL_CFLAGS = $(CFLAGS) -I.
+.c.o:
+        $(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $<
+@end example
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation.  You can consider it a default
+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.
+
+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
+@code{$(INSTALL)}.)  Then it should use those variables as the commands
+for actual installation, for executables and nonexecutables
+respectively.  Use these variables as follows:
+
+@example
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
+@end example
+
+@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.
+
+@node Directory Variables
+@section Variables for Installation Directories
+
+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:
+
+@table @samp
+@item prefix
+A prefix used in constructing the default values of the variables listed
+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
+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.
+
+@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 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}.
+
+@item statedir
+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}.
+
+@item includedir
+@c rewritten to avoid overfull hbox --roland
+The directory for installing header files to be included by user
+programs with the C @samp{#include} preprocessor directive.  This
+should normally be @file{/usr/local/include}, but write it as
+@file{$(prefix)/include}.
+
+Most compilers other than GCC do not look for header files in
+@file{/usr/local/include}.  So installing the header files this way is
+only useful with GCC.  Sometimes this is not a problem because some
+libraries are only really intended to work with GCC.  But some libraries
+are intended to work with other compilers.  They should install their
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
+
+@item oldincludedir
+The directory for installing @samp{#include} header files for use with
+compilers other than GCC.  This should normally be @file{/usr/include}.
+
+The Makefile commands should check whether the value of
+@code{oldincludedir} is empty.  If it is, they should not try to use
+it; they should cancel the second installation of the header files.
+
+A package should not replace an existing header in this directory unless
+the header came from the same package.  Thus, if your Foo package
+provides a header file @file{foo.h}, then it should install the header
+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.
+
+@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.
+
+@item man1dir
+The directory for installing section 1 man pages.
+@item man2dir
+The directory for installing section 2 man pages.
+@item @dots{}
+Use these names instead of @samp{mandir} if the package needs to install man
+pages in more than one section of the manual.
+
+@strong{Don't make the primary documentation for any GNU software be a
+man page.  Write a manual in Texinfo instead.  Man pages are just for
+the sake of people running GNU software on Unix, which is a secondary
+application only.}
+
+@item manext
+The file name extension for the installed man page.  This should contain
+a period followed by the appropriate digit.
+
+@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 srcdir
+The directory for the sources being compiled.  The value of this
+variable is normally inserted by the @code{configure} shell script.
+@end table
+
+For example:
+
+@example
+# Common prefix for installation directories.
+# NOTE: This directory must exist when you start the install.
+prefix = /usr/local
+exec_prefix = $(prefix)
+# Directory in which to put the executable for the command `gcc'.
+bindir = $(exec_prefix)/bin
+# Directory in which to put the directories used by the compiler.
+libdir = $(exec_prefix)/lib
+# Directory in which to put the Info files.
+infodir = $(prefix)/info
+@end example
+
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program.  If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above.  The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages.  In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
+