Changeset 503 for trunk/src/gmake/doc/make-stds.texi

Timestamp:

Sep 15, 2006, 7:09:38 AM (19 years ago)

Author:

bird

Message:

Untested merge with GNU Make v3.81 (vendor/gnumake/2005-05-16 -> vendor/gnumake/current).

File:

• trunk/src/gmake/doc/make-stds.texi (modified) (16 diffs)

trunk/src/gmake/doc/make-stds.texi

@@ -9 +9 @@
 @cindex standards for makefiles
 
-@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free
-@c Software Foundation, Inc.
+@c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
+@c 2004, 2005 Free Software Foundation, Inc.
 
 @c Permission is granted to copy, distribute and/or modify this document
@@ -294 +294 @@
 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 described below.  They are based on a standard filesystem
-layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
-and other modern operating systems.
+variables and the values they should have in GNU packages are
+described below.  They are based on a standard filesystem layout;
+variants of it are used in GNU/Linux and other modern operating
+systems.
+
+Installers are expected to override these values when calling
+@command{make} (e.g., @kbd{make prefix=/usr install} or
+@command{configure} (e.g., @kbd{configure --prefix=/usr}).  GNU
+packages should not try to guess which value should be appropriate for
+these variables on the system they are being installed onto: use the
+default settings specified here so that all GNU packages behave
+identically, allowing the installer to achieve any desired layout.
 
 These two variables set the root for the installation.  All the other
@@ -356 +365 @@
 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
+
+The definition of @samp{libexecdir} is the same for all packages, so
+you should install your data in a subdirectory thereof.  Most packages
+install their data under @file{$(libexecdir)/@var{package-name}/},
+possibly within additional subdirectories thereof, such as
+@file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
 @end table
 
@@ -378 +393 @@
 architecture-independent, and it is generally not hard.
 
-Therefore, here are the variables Makefiles should use to specify
-directories:
+Here are the variables Makefiles should use to specify directories
+to put these various kinds of files in:
 
 @table @samp
+@item datarootdir
+The root of the directory tree for read-only architecture-independent
+data files.  This should normally be @file{/usr/local/share}, but
+write it as @file{$(prefix)/share}.  (If you are using Autoconf, write
+it as @samp{@@datarootdir@@}.)  @samp{datadir}'s default value is
+based on this variable; so are @samp{infodir}, @samp{mandir}, and
+others.
+
 @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}.
-(If you are using Autoconf, write it as @samp{@@datadir@@}.)
-As a special exception, see @file{$(infodir)}
-and @file{$(includedir)} below.
+The directory for installing idiosyncratic read-only
+architecture-independent data files for this program.  This is usually
+the same place as @samp{datarootdir}, but we use the two separate
+variables so that you can move these program-specific files without
+altering the location for Info files, man pages, etc.
+
+This should normally be @file{/usr/local/share}, but write it as
+@file{$(datarootdir)}.  (If you are using Autoconf, write it as
+@samp{@@datadir@@}.)
+
+The definition of @samp{datadir} is the same for all packages, so you
+should install your data in a subdirectory thereof.  Most packages
+install their data under @file{$(datadir)/@var{package-name}/}.
 
 @item sysconfdir
@@ -420 +450 @@
 @file{$(prefix)/var}.
 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
-
-@item libdir
-The directory for object files and libraries of object code.  Do not
-install executables here, they probably ought to go in @file{$(libexecdir)}
-instead.  The value of @code{libdir} should normally be
-@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
-(If you are using Autoconf, write it as @samp{@@libdir@@}.)
-
-@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}.
-(If you are using Autoconf, write it as @samp{@@infodir@@}.)
-
-@item lispdir
-The directory for installing any Emacs Lisp files in this package.  By
-default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
-should be written as @file{$(prefix)/share/emacs/site-lisp}.
-
-If you are using Autoconf, write the default as @samp{@@lispdir@@}.
-In order to make @samp{@@lispdir@@} work, you need the following lines
-in your @file{configure.in} file:
-
-@example
-lispdir='$@{datadir@}/emacs/site-lisp'
-AC_SUBST(lispdir)
-@end example
-
+@end table
+
+These variables specify the directory for installing certain specific
+types of files, if your program has them.  Every GNU package should
+have Info files, so every program needs @samp{infodir}, but not all
+need @samp{libdir} or @samp{lispdir}.
+
+@table @samp
 @item includedir
 @c rewritten to avoid overfull hbox --roland
@@ -482 +492 @@
 To tell whether @file{foo.h} came from the Foo package, put a magic
 string in the file---part of a comment---and @code{grep} for that string.
+
+@item docdir
+The directory for installing documentation files (other than Info) for
+this package.  By default, it should be
+@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
+@file{$(datarootdir)/doc/@var{yourpkg}}.  (If you are using Autoconf,
+write it as @samp{@@docdir@@}.)  The @var{yourpkg} subdirectory, which
+may include a version number, prevents collisions among files with
+common names, such as @file{README}.
+
+@item infodir
+The directory for installing the Info files for this package.  By
+default, it should be @file{/usr/local/share/info}, but it should be
+written as @file{$(datarootdir)/info}.  (If you are using Autoconf,
+write it as @samp{@@infodir@@}.)  @code{infodir} is separate from
+@code{docdir} for compatibility with existing practice.
+
+@item htmldir
+@itemx dvidir
+@itemx pdfdir
+@itemx psdir
+Directories for installing documentation files in the particular
+format.  (It is not required to support documentation in all these
+formats.)  They should all be set to @code{$(docdir)} by default.  (If
+you are using Autoconf, write them as @samp{@@htmldir@@},
+@samp{@@dvidir@@}, etc.)  Packages which supply several translations
+of their documentation should install them in
+@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
+@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
+
+@item libdir
+The directory for object files and libraries of object code.  Do not
+install executables here, they probably ought to go in @file{$(libexecdir)}
+instead.  The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
+(If you are using Autoconf, write it as @samp{@@libdir@@}.)
+
+@item lispdir
+The directory for installing any Emacs Lisp files in this package.  By
+default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
+should be written as @file{$(datarootdir)/emacs/site-lisp}.
+
+If you are using Autoconf, write the default as @samp{@@lispdir@@}.
+In order to make @samp{@@lispdir@@} work, you need the following lines
+in your @file{configure.in} file:
+
+@example
+lispdir='$@{datarootdir@}/emacs/site-lisp'
+AC_SUBST(lispdir)
+@end example
+
+@item localedir
+The directory for installing locale-specific message catalogs for this
+package.  By default, it should be @file{/usr/local/share/locale}, but
+it should be written as @file{$(datarootdir)/locale}.  (If you are
+using Autoconf, write it as @samp{@@localedir@@}.)  This directory
+usually has a subdirectory per locale.
 @end table
 
@@ -489 +556 @@
 @item mandir
 The top-level directory for installing the man pages (if any) for this
-package.  It will normally be @file{/usr/local/man}, but you should
-write it as @file{$(prefix)/man}.
-(If you are using Autoconf, write it as @samp{@@mandir@@}.)
+package.  It will normally be @file{/usr/local/share/man}, but you
+should write it as @file{$(datarootdir)/man}.  (If you are using
+Autoconf, write it as @samp{@@mandir@@}.)
 
 @item man1dir
@@ -536 +603 @@
 # NOTE: This directory must exist when you start the install.
 prefix = /usr/local
+datarootdir = $(prefix)/share
+datadir = $(datarootdir)
 exec_prefix = $(prefix)
 # Where to put the executable for the command `gcc'.
@@ -542 +611 @@
 libexecdir = $(exec_prefix)/libexec
 # Where to put the Info files.
-infodir = $(prefix)/info
+infodir = $(datarootdir)/info
 @end smallexample
 
@@ -631 +700 @@
 Categories}.
 
+@item install-html
+@itemx install-dvi
+@itemx install-pdf
+@itemx install-ps
+These targets install documentation in formats other than Info;
+they're intended to be called explicitly by the person installing the
+package, if that format is desired.  GNU prefers Info files, so these
+must be installed by the @code{install} target.
+
+When you have many documentation files to install, we recommend that
+you avoid collisions and clutter by arranging for these targets to
+install in subdirectories of the appropriate installation directory,
+such as @code{htmldir}.  As one example, if your package has multiple
+manuals, and you wish to install HTML documentation with many files
+(such as the ``split'' mode output by @code{makeinfo --html}), you'll
+certainly want to use subdirectories, or two nodes with the same name
+in different manuals will overwrite each other.
+
 @item uninstall
 Delete all the installed files---the copies that the @samp{install}
-target creates.
+and @samp{install-*} targets create.
 
 This rule should not modify the directories where compilation is done,
@@ -669 +756 @@
 @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 all files in the current directory that are normally created by
+building the program.  Also delete files in other directories if they
+are created by this makefile.  However, 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.  There is no need to delete parent directories that were created
+with @samp{mkdir -p}, since they could have existed anyway.
 
 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.
+Delete all files in the current directory (or created by this
+makefile) 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.  However, there is no need to delete
+parent directories that were created with @samp{mkdir -p}, since they
+could have existed anyway.
 
 @item mostlyclean
@@ -689 +782 @@
 
 @item maintainer-clean
-Delete almost everything from the current directory that can be
-reconstructed with this Makefile.  This typically includes everything
-deleted by @code{distclean}, plus more: C source files produced by
-Bison, tags tables, Info files, and so on.
+Delete almost everything that can be reconstructed with this Makefile.
+This typically includes everything deleted by @code{distclean}, plus
+more: C source files produced by Bison, tags tables, Info files, and
+so on.
 
 The reason we say ``almost everything'' is that running the command
-@samp{make maintainer-clean} should not delete @file{configure} even if
-@file{configure} can be remade using a rule in the Makefile.  More generally,
-@samp{make maintainer-clean} should not delete anything that needs to
-exist in order to run @file{configure} and then begin to build the
-program.  This is the only exception; @code{maintainer-clean} should
-delete everything else that can be rebuilt.
+@samp{make maintainer-clean} should not delete @file{configure} even
+if @file{configure} can be remade using a rule in the Makefile.  More
+generally, @samp{make maintainer-clean} should not delete anything
+that needs to exist in order to run @file{configure} and then begin to
+build the program.  Also, there is no need to delete parent
+directories that were created with @samp{mkdir -p}, since they could
+have existed anyway.  These are the only exceptions;
+@code{maintainer-clean} should delete everything else that can be
+rebuilt.
 
 The @samp{maintainer-clean} target is intended to be used by a maintainer of
@@ -744 +840 @@
 
 @item dvi
-Generate DVI files for all Texinfo documentation.
-For example:
+@itemx html
+@itemx pdf
+@itemx ps
+Generate documentation files in the given format, if possible.
+Here's an example rule for generating DVI files from Texinfo:
 
 @smallexample
@@ -760 +859 @@
 of formatting. @TeX{} is not distributed with Texinfo.}  Alternatively,
 write just the dependencies, and allow GNU @code{make} to provide the command.
+
+Here's another example, this one for generating HTML from Texinfo:
+
+@smallexample
+html: foo.html
+
+foo.html: foo.texi chap1.texi chap2.texi
+        $(TEXI2HTML) $(srcdir)/foo.texi
+@end smallexample
+
+@noindent
+Again, you would define the variable @code{TEXI2HTML} in the Makefile;
+for example, it might run @code{makeinfo --no-split --html}
+(@command{makeinfo} is part of the Texinfo distribution).
 
 @item dist
@@ -933 +1046 @@
 Programs to build binary packages work by extracting the
 pre-installation and post-installation commands.  Here is one way of
-extracting the pre-installation commands:
-
-@smallexample
-make -n install -o all \
+extracting the pre-installation commands (the @option{-s} option to
+@command{make} is needed to silence messages about entering
+subdirectories):
+
+@smallexample
+make -s -n install -o all \
       PRE_INSTALL=pre-install \
       POST_INSTALL=post-install \
@@ -947 +1062 @@
 
 @smallexample
-$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
+$0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
 on @{print $0@}
-$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
-@end smallexample
-
-The resulting file of pre-installation commands is executed as a shell
-script as part of installing the binary package.
+$0 ~ /^pre-install[ \t]*$/ @{on = 1@}
+@end smallexample