This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
[karl@gnu.org: GNU coding standards and DESTDIR]
- From: Eli Zaretskii <eliz at gnu dot org>
- To: gdb at sources dot redhat dot com
- Date: Wed, 10 May 2006 20:53:36 +0300
- Subject: [karl@gnu.org: GNU coding standards and DESTDIR]
- Reply-to: 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 -------