@cindex conventions for makefiles
@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
@c under the terms of the GNU Free Documentation License, Version 1.1
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
installation directories should be subdirectories of one of these two,
programs rather than by users. This directory should normally be
@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
Data files used by the program during its execution are divided into
@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}. @samp{datadir}'s default value is
-based on this variable; so are @samp{infodir}, @samp{mandir}, and others.
+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 ideosyncratic read-only
+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 ideosyncratic files without
+variables so that you can move these program-specific files without
altering the location for Info files, man pages, etc.
-The default definition of @samp{datadir} should be
+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
The directory for installing read-only data files that pertain to a
single machine--that is to say, files for configuring a host. Mailer
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@@}.)
+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
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@@}.)
+using Autoconf, write it as @samp{@@localedir@@}.) This directory
+usually has a subdirectory per locale.
@end table
Unix-style man pages are installed in one of the following:
commands and @dfn{post-installation} commands. @xref{Install Command
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,
only the directories where files are installed.
@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
-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
Like @samp{clean}, but may refrain from deleting a few files that people
is rarely necessary and takes a lot of time.
@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
the package, not by ordinary users. You may need special tools to
because they will already be up to date.
@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
dvi: foo.dvi
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
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
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:
+extracting the pre-installation commands (the @option{-s} option to
+@command{make} is needed to silence messages about entering
+subdirectories):
@smallexample
-make -n install -o all \
+make -s -n install -o all \
PRE_INSTALL=pre-install \
POST_INSTALL=post-install \
NORMAL_INSTALL=normal-install \
where the file @file{pre-install.awk} could contain this:
@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@}
+$0 ~ /^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.
projects / gnulib.git / blobdiff