[karl@gnu.org: GNU coding standards and DESTDIR]

[Eli Zaretskii <eliz at gnu dot org>]

GDB maintainers: FYI.

------- Start of forwarded message -------
Date: Tue, 9 May 2006 17:29:57 -0500
From: karl@gnu.org (Karl Berry)
To: gnu-prog@gnu.org
Subject: GNU coding standards and DESTDIR

After discussion between rms, the GNU make maintainer, and others, we've
added more information about DESTDIR and strongly recommended that GNU
projects support it.  (Automake-based projects do automatically.)  See
new node below, or online at
http://www.gnu.org/prep/standards/html_node/DESTDIR.html

Also, rms added a couple of changes clarifying writing suggestions, and
mentioning not to blindly add () after function names.

Any discussion should be directed to gnu-prog-discuss@gnu.org.

Happy hacking,
Karl


File: standards.info,  Node: DESTDIR

7.2.4 `DESTDIR': support for staged installs
- --------------------------------------------

`DESTDIR' is a variable prepended to each installed target file, like
this:

     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a

   The `DESTDIR' variable is specified by the user, either to the
`configure' script or, more commonly, on the `make' command line.  For
example:

     make DESTDIR=/tmp/stage install

(Since the value of `DESTDIR' is only used during installation it is
not necessary to provide it with other `make' commands.)

   If your installation step would normally install
`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
installation invoked as in the example above would install
`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
instead.

   Prepending the variable `DESTDIR' to each target in this way
provides for "staged installs", where the installed files are not
placed directly into their expected location but are instead copied
into a temporary location (`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 `DESTDIR' in your `Makefile' at all;
then the files are installed into their expected locations by default.
Also, specifying `DESTDIR' should not change the operation of the
software in any way, so its value should not be included in any file
contents.

   `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
`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 `DESTDIR', though it
is not an absolute requirement.

- ------------------------------------------------------------
New and revised text in
http://www.gnu.org/prep/standards/html_node/GNU-Manuals.html:

 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.  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.
  
 ...  

 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.


_______________________________________________

GNU Maintainers Announcement List gnu-prog@gnu.org
http://lists.gnu.org/mailman/listinfo/gnu-prog
------- End of forwarded message -------