# HG changeset patch # User Karl Berry # Date 1147094542 0 # Node ID 21acfa839f4fd4b250f6bfc2bc14b5b5e5fe5b3d # Parent dc482bc540d04ba77b17e1c16ed10525401e21d5 autoupdate diff --git a/doc/make-stds.texi b/doc/make-stds.texi --- a/doc/make-stds.texi +++ b/doc/make-stds.texi @@ -36,11 +36,12 @@ 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 @@ -264,29 +265,78 @@ 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 @@ -306,9 +356,10 @@ 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 @@ -625,6 +676,15 @@ 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 diff --git a/doc/standards.texi b/doc/standards.texi --- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @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 @@ -3137,20 +3137,26 @@ 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 @@ -3220,6 +3226,10 @@ 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