conventions.
@menu
-* Makefile Basics:: General Conventions for Makefiles
-* Utilities in Makefiles:: Utilities in Makefiles
-* Command Variables:: Variables for Specifying Commands
-* Directory Variables:: Variables for Installation Directories
-* Standard Targets:: Standard Targets for Users
+* 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.
+* Standard Targets:: Standard targets for users.
* Install Command Categories:: Three categories of commands in the `install'
rule: normal, pre-install and post-install.
@end menu
be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
commands for actual installation, for executables and nonexecutables
-respectively. Use these variables as follows:
+respectively. Minimal use of these variables is as follows:
@example
$(INSTALL_PROGRAM) foo $(bindir)/foo
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
@end example
-Optionally, you may prepend the value of @code{DESTDIR} to the target
-filename. Doing this allows the installer to create a snapshot of the
-installation to be copied onto the real target file system later. Do not
-set the value of @code{DESTDIR} in your Makefile, and do not include it
-in any installed files. With support for @code{DESTDIR}, the above
-examples become:
+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.
+
+
+@node DESTDIR
+@section @code{DESTDIR}: support for staged installs
+
+@vindex DESTDIR
+@cindex staged installs
+@cindex installations, staged
+
+@code{DESTDIR} is a variable prepended to each installed target file,
+like this:
@example
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
$(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:
+
+@example
+make DESTDIR=/tmp/stage install
+@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.
+(Since the value of @code{DESTDIR} is only used during installation it
+is not necessary to provide it with other @code{make} commands.)
+
+If your installation step would normally install
+@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
+installation invoked as in the example above would install
+@file{/tmp/stage/usr/local/bin/foo} and
+@file{/tmp/stage/usr/local/lib/libfoo.a} instead.
+
+Prepending the variable @code{DESTDIR} to each target in this way
+provides for @dfn{staged installs}, where the installed files are not
+placed directly into their expected location but are instead copied
+into a temporary location (@code{DESTDIR}). However, installed files
+maintain their relative directory structure and any embedded file names
+will not be modified.
+
+You should not set the value of @code{DESTDIR} in your @file{Makefile}
+at all; then the files are installed into their expected locations by
+default. Also, specifying @code{DESTDIR} should not change the
+operation of the software in any way, so its value should not be
+included in any file contents.
+
+@code{DESTDIR} support is commonly used in package creation. It is
+also helpful to users who want to understand what a given package will
+install where, and to allow users who don't normally have permissions
+to install into protected areas to build and install before gaining
+those permissions. Finally, it can be useful with tools such as
+@code{stow}, where code is installed in one place but made to appear
+to be installed somewhere else using symbolic links or special mount
+operations. So, we recommend GNU packages support @code{DESTDIR},
+though it is not an absolute requirement.
+
@node Directory Variables
@section Variables for Installation Directories
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,
-and nothing should be directly installed into these two directories.
+These first 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 @code
@item prefix
order for this to be useful, all the packages must be designed so that
they will work sensibly when the user does so.
+Not all of these variables may be implemented in the current release
+of Autoconf and/or Automake; right now, that includes at least
+@code{docdir}, @code{psdir}, @code{pdfdir}, @code{htmldir},
+@code{dvidir}. In these cases, the descriptions here serve as
+specifications for what Autoconf will implement. As a programmer, you
+can either use a development version of Autoconf or avoid using these
+variables until a stable release is made which supports them.
+
+
@node Standard Targets
@section Standard Targets for Users
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate April 9, 2006
+@set lastupdate April 23, 2006
@c %**end of header
@dircategory GNU organization
converted automatically into Texinfo. It is ok to produce the Texinfo
documentation by conversion this way, as long as it gives good results.
-Programmers often find it most natural to structure the documentation
-following the structure of the implementation, which they know. But
-this structure is not necessarily good for explaining how to use the
-program; it may be irrelevant and confusing for a user.
-
-At every level, from the sentences in a paragraph to the grouping of
-topics into separate manuals, the right way to structure documentation
-is according to the concepts and questions that a user will have in mind
-when reading it. Sometimes this structure of ideas matches the
+Make sure your manual is clear to a reader who knows nothing about the
+topic and reads it straight through. This means covering basic topics
+at the beginning, and advanced topics only later. This also means
+defining every specialized term when it is first used.
+
+Programmers tend to carry over the structure of the program as the
+structure for its documentation. But this structure is not
+necessarily good for explaining how to use the program; it may be
+irrelevant and confusing for a user.
+
+Instead, the right way to structure documentation is according to the
+concepts and questions that a user will have in mind when reading it.
+This principle applies at every level, from the lowest (ordering
+sentences in a paragraph) to the highest (ordering of chapter topics
+within the manual). Sometimes this structure of ideas matches the
structure of the implementation of the software being documented---but
-often they are different. Often the most important part of learning to
-write good documentation is learning to notice when you are structuring
-the documentation like the implementation, and think about better
-alternatives.
+often they are different. An important part of learning to write good
+documentation is to learn to notice when you have unthinkingly
+structured the documentation like the implementation, stop yourself,
+and look for better alternatives.
For example, each program in the GNU system probably ought to be
documented in one manual; but this does not mean each program should
a computer program. Please use ``invalid'' for this, and reserve the
term ``illegal'' for activities prohibited by law.
+Please do not write @samp{()} after a function name just to indicate
+it is a function. @code{foo ()} is not a function, it is a function
+call with no arguments.
+
@node Doc Strings and Manuals
@section Doc Strings and Manuals
projects / pspp / commitdiff