1992-04-25 00:21:27 +02:00
|
|
|
\input texinfo @c -*-texinfo-*-
|
|
|
|
@c %**start of header
|
|
|
|
@setfilename standards.text
|
|
|
|
@settitle GNU Coding Standards
|
|
|
|
@c %**end of header
|
|
|
|
|
|
|
|
@setchapternewpage off
|
|
|
|
|
|
|
|
@ifinfo
|
|
|
|
Copyright (C) 1992 Free Software Foundation
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
|
|
this manual provided the copyright notice and this permission notice
|
|
|
|
are preserved on all copies.
|
|
|
|
|
|
|
|
@ignore
|
|
|
|
Permission is granted to process this file through TeX and print the
|
|
|
|
results, provided the printed document carries copying permission
|
|
|
|
notice identical to this one except for the removal of this paragraph
|
|
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
|
|
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
|
|
resulting derived work is distributed under the terms of a permission
|
|
|
|
notice identical to this one.
|
|
|
|
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
|
|
into another language, under the above conditions for modified versions,
|
|
|
|
except that this permission notice may be stated in a translation approved
|
|
|
|
by the Free Software Foundation.
|
|
|
|
@end ifinfo
|
|
|
|
|
|
|
|
@titlepage
|
|
|
|
@sp 10
|
|
|
|
@titlefont{GNU Coding Standards}
|
|
|
|
@author{Richard Stallman}
|
1992-05-19 01:26:45 +02:00
|
|
|
@author{last updated 9 May 1992}
|
1992-04-25 00:21:27 +02:00
|
|
|
@c Note date also appears below.
|
|
|
|
@page
|
|
|
|
|
|
|
|
@vskip 0pt plus 1filll
|
|
|
|
Copyright @copyright{} 1992 Free Software Foundation
|
|
|
|
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
|
|
this manual provided the copyright notice and this permission notice
|
|
|
|
are preserved on all copies.
|
|
|
|
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
|
|
manual under the conditions for verbatim copying, provided that the entire
|
|
|
|
resulting derived work is distributed under the terms of a permission
|
|
|
|
notice identical to this one.
|
|
|
|
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
|
|
into another language, under the above conditions for modified versions,
|
|
|
|
except that this permission notice may be stated in a translation approved
|
|
|
|
by Free Software Foundation.
|
|
|
|
@end titlepage
|
|
|
|
|
|
|
|
@ifinfo
|
1992-04-25 01:04:14 +02:00
|
|
|
@format
|
|
|
|
START-INFO-DIR-ENTRY
|
|
|
|
* standards: (standards.info). The GNU coding standards.
|
|
|
|
END-INFO-DIR-ENTRY
|
|
|
|
@end format
|
|
|
|
|
1992-04-25 00:21:27 +02:00
|
|
|
@node Top, Reading Non-Free Code, (dir), (dir)
|
|
|
|
@top Version
|
|
|
|
|
1992-05-19 01:26:45 +02:00
|
|
|
Last updated 9 May 1992.
|
1992-04-25 00:21:27 +02:00
|
|
|
@c Note date also appears above.
|
|
|
|
@end ifinfo
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Reading Non-Free Code:: Referring to Proprietary Programs
|
|
|
|
* Contributions:: Accepting Contributions
|
|
|
|
* Change Logs:: Recording Changes
|
|
|
|
* Compatibility:: Compatibility with Other Implementations
|
|
|
|
* Makefiles:: Makefile Conventions
|
|
|
|
* Configuration:: How Configuration Should Work
|
|
|
|
* Source Language:: Using Languages Other Than C
|
|
|
|
* Formatting:: Formatting Your Source Code
|
|
|
|
* Comments:: Commenting Your Work
|
|
|
|
* Syntactic Conventions:: Clean Use of C Constructs
|
|
|
|
* Names:: Naming Variables and Functions
|
|
|
|
* Using Extensions:: Using Non-standard Features
|
|
|
|
* Semantics:: Program Behaviour for All Programs
|
|
|
|
* Errors:: Formatting Error Messages
|
|
|
|
* Libraries:: Library Behaviour
|
|
|
|
* Portability:: Portability As It Applies to GNU
|
|
|
|
* User Interfaces:: Standards for Command Line Interfaces
|
|
|
|
* Documentation:: Documenting Programs
|
|
|
|
* Releases:: Making Releases
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Reading Non-Free Code
|
|
|
|
@chapter Referring to Proprietary Programs
|
|
|
|
|
|
|
|
Don't in any circumstances refer to Unix source code for or during
|
|
|
|
your work on GNU! (Or to any other proprietary programs.)
|
|
|
|
|
|
|
|
If you have a vague recollection of the internals of a Unix program,
|
|
|
|
this does not absolutely mean you can't write an imitation of it, but
|
|
|
|
do try to organize the imitation internally along different lines,
|
|
|
|
because this is likely to make the details of the Unix version
|
|
|
|
irrelevant and dissimilar to your results.
|
|
|
|
|
|
|
|
For example, Unix utilities were generally optimized to minimize
|
|
|
|
memory use; if you go for speed instead, your program will be very
|
|
|
|
different. You could keep the entire input file in core and scan it
|
|
|
|
there instead of using stdio. Use a smarter algorithm discovered more
|
|
|
|
recently than the Unix program. Eliminate use of temporary files. Do
|
|
|
|
it in one pass instead of two (we did this in the assembler).
|
|
|
|
|
|
|
|
Or, on the contrary, emphasize simplicity instead of speed. For some
|
|
|
|
applications, the speed of today's computers makes simpler algorithms
|
|
|
|
adequate.
|
|
|
|
|
|
|
|
Or go for generality. For example, Unix programs often have static
|
|
|
|
tables or fixed-size strings, which make for arbitrary limits; use
|
|
|
|
dynamic allocation instead. Make sure your program handles NULs and
|
|
|
|
other funny characters in the input files. Add a programming language
|
|
|
|
for extensibility and write part of the program in that language.
|
|
|
|
|
|
|
|
Or turn some parts of the program into independently usable libraries.
|
|
|
|
Or use a simple garbage collector instead of tracking precisely when
|
|
|
|
to free memory, or use a new GNU facility such as obstacks.
|
|
|
|
|
|
|
|
|
|
|
|
@node Contributions
|
|
|
|
@chapter Accepting Contributions
|
|
|
|
|
|
|
|
If someone else sends you a piece of code to add to the program you are
|
|
|
|
working on, we need legal papers to use it---the same sort of legal
|
|
|
|
papers we will need to get from you. @emph{Each} significant
|
|
|
|
contributor to a program must sign some sort of legal papers in order
|
|
|
|
for us to have clear title to the program. The main author alone is not
|
|
|
|
enough.
|
|
|
|
|
|
|
|
So, before adding in any contributions from other people, tell us
|
|
|
|
so we can arrange to get the papers. Then wait until we tell you
|
|
|
|
that we have received the signed papers, before you actually use the
|
|
|
|
contribution.
|
|
|
|
|
|
|
|
This applies both before you release the program and afterward. If
|
|
|
|
you receive diffs to fix a bug, and they make significant change, we
|
|
|
|
need legal papers for it.
|
|
|
|
|
|
|
|
You don't need papers for changes of a few lines here or there, since
|
|
|
|
they are not significant for copyright purposes. Also, you don't need
|
|
|
|
papers if all you get from the suggestion is some ideas, not actual code
|
|
|
|
which you use. For example, if you write a different solution to the
|
|
|
|
problem, you don't need to get papers.
|
|
|
|
|
|
|
|
I know this is frustrating; it's frustrating for us as well. But if
|
|
|
|
you don't wait, you are going out on a limb---for example, what if the
|
|
|
|
contributor's employer won't sign a disclaimer? You might have to take
|
|
|
|
that code out again!
|
|
|
|
|
|
|
|
The very worst thing is if you forget to tell us about the other
|
|
|
|
contributor. We could be very embarrassed in court some day as a
|
|
|
|
result.
|
|
|
|
|
|
|
|
@node Change Logs
|
|
|
|
@chapter Change Logs
|
|
|
|
|
|
|
|
Keep a change log for each directory, describing the changes made to
|
|
|
|
source files in that directory. The purpose of this is so that people
|
|
|
|
investigating bugs in the future will know about the changes that
|
|
|
|
might have introduced the bug. Often a new bug can be found by
|
|
|
|
looking at what was recently changed. More importantly, change logs
|
|
|
|
can help eliminate conceptual inconsistencies between different parts
|
|
|
|
of a program; they can give you a history of how the conflicting
|
|
|
|
concepts arose.
|
|
|
|
|
|
|
|
Use the Emacs command @kbd{M-x add-change} to start a new entry in the
|
|
|
|
change log. An entry should have an asterisk, the name of the changed
|
|
|
|
file, and then in parentheses the name of the changed functions,
|
|
|
|
variables or whatever, followed by a colon. Then describe the changes
|
|
|
|
you made to that function or variable.
|
|
|
|
|
|
|
|
Separate unrelated entries with blank lines. When two entries
|
|
|
|
represent parts of the same change, so that they work together, then
|
|
|
|
don't put blank lines between them. Then you can omit the file name
|
|
|
|
and the asterisk when successive entries are in the same file.
|
|
|
|
|
|
|
|
Here are some examples:
|
|
|
|
|
|
|
|
@example
|
|
|
|
* register.el (insert-register): Return nil.
|
|
|
|
(jump-to-register): Likewise.
|
|
|
|
|
|
|
|
* sort.el (sort-subr): Return nil.
|
|
|
|
|
|
|
|
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
|
|
|
|
Restart the tex shell if process is gone or stopped.
|
|
|
|
(tex-shell-running): New function.
|
|
|
|
|
|
|
|
* expr.c (store_one_arg): Round size up for move_block_to_reg.
|
|
|
|
(expand_call): Round up when emitting USE insns.
|
|
|
|
* stmt.c (assign_parms): Round size up for move_block_from_reg.
|
|
|
|
@end example
|
|
|
|
|
|
|
|
There's no need to describe here the full purpose of the changes or how
|
|
|
|
they work together. It is better to put this explanation in comments in
|
|
|
|
the code. That's why just ``New function'' is enough; there is a
|
|
|
|
comment with the function in the source to explain what it does.
|
|
|
|
|
|
|
|
However, sometimes it is useful to write one line to describe the
|
|
|
|
overall purpose of a large batch of changes.
|
|
|
|
|
|
|
|
When you change the calling sequence of a function in a simple
|
|
|
|
fashion, and you change all the callers of the function, there is no
|
|
|
|
need to make individual entries for all the callers. Just write in
|
|
|
|
the entry for the function being called, ``All callers changed.''
|
|
|
|
|
|
|
|
When you change just comments or doc strings, it is enough to write an
|
|
|
|
entry for the file, without mentioning the functions. Write just,
|
|
|
|
``Doc fix.'' There's no need to keep a change log for documentation
|
|
|
|
files. This is because documentation is not susceptible to bugs that
|
|
|
|
are hard to fix. Documentation does not consist of parts that must
|
|
|
|
interact in a precisely engineered fashion; to correct an error, you
|
|
|
|
need not know the history of the erroneous passage.
|
|
|
|
|
|
|
|
|
|
|
|
@node Compatibility
|
|
|
|
@chapter Compatibility with Other Implementations
|
|
|
|
|
|
|
|
With certain exceptions, utility programs and libraries for GNU should
|
|
|
|
be upward compatible with those in Berkeley Unix, and upward compatible
|
|
|
|
with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward
|
|
|
|
compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior.
|
|
|
|
|
|
|
|
When these standards conflict, it is useful to offer compatibility
|
|
|
|
modes for each of them.
|
|
|
|
|
|
|
|
@sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel
|
|
|
|
free to make the extensions anyway, and include a @samp{--ansi} or
|
|
|
|
@samp{--compatible} option to turn them off. However, if the extension
|
|
|
|
has a significant chance of breaking any real programs or scripts,
|
|
|
|
then it is not really upward compatible. Try to redesign its
|
|
|
|
interface.
|
|
|
|
|
|
|
|
When a feature is used only by users (not by programs or command
|
|
|
|
files), and it is done poorly in Unix, feel free to replace it
|
|
|
|
completely with something totally different and better. (For example,
|
|
|
|
vi is replaced with Emacs.) But it is nice to offer a compatible
|
|
|
|
feature as well. (There is a free vi clone, so we offer it.)
|
|
|
|
|
|
|
|
Additional useful features not in Berkeley Unix are welcome.
|
|
|
|
Additional programs with no counterpart in Unix may be useful,
|
|
|
|
but our first priority is usually to duplicate what Unix already
|
|
|
|
has.
|
|
|
|
|
|
|
|
|
|
|
|
@node Makefiles
|
|
|
|
@chapter Makefile Conventions
|
|
|
|
|
|
|
|
This chapter describes conventions for writing Makefiles.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Makefile Basics::
|
|
|
|
* Standard Targets::
|
|
|
|
* Command Variables::
|
|
|
|
* Directory Variables::
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Makefile Basics
|
|
|
|
@section General Conventions for Makefiles
|
|
|
|
|
|
|
|
Every Makefile should contain this line:
|
|
|
|
|
|
|
|
@example
|
|
|
|
SHELL = /bin/sh
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
to avoid trouble on systems where the @code{SHELL} variable might be
|
|
|
|
inherited from the environment.
|
|
|
|
|
|
|
|
Don't assume that @file{.} is in the path for command execution. When
|
|
|
|
you need to run programs that are files in the current directory, always
|
|
|
|
use @file{./} to make sure the proper file is run regardless of the
|
|
|
|
current path.
|
|
|
|
|
|
|
|
@node Standard Targets
|
|
|
|
@section Standard Targets for Users
|
|
|
|
|
|
|
|
All GNU programs should have the following targets in their Makefiles:
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item all
|
|
|
|
Compile the entire program.
|
|
|
|
|
|
|
|
@item install
|
|
|
|
Compile the program and copy the executables, libraries, and so on to
|
|
|
|
the file names where they should reside for actual use. If there is a
|
|
|
|
simple test to verify that a program is properly installed then run that
|
|
|
|
test.
|
|
|
|
|
|
|
|
@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.
|
|
|
|
|
|
|
|
@item distclean
|
|
|
|
Delete all files from the current directory that are created by
|
1992-05-19 01:26:45 +02:00
|
|
|
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.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
@item mostlyclean
|
|
|
|
Like @samp{clean}, but may refrain from deleting a few files that people
|
|
|
|
normally don't want to recompile. For example, the @samp{mostlyclean}
|
|
|
|
target for GCC does not delete @file{libgcc.a}, because recompiling it
|
|
|
|
is rarely necessary and takes a lot of time.
|
|
|
|
|
|
|
|
@item realclean
|
|
|
|
Delete everything from the current directory that can be reconstructed
|
|
|
|
with this Makefile. This typically includes everything deleted by
|
|
|
|
distclean, plus more: C source files produced by Bison, tags tables,
|
|
|
|
info files, and so on.
|
|
|
|
|
|
|
|
@item TAGS
|
|
|
|
Update a tags table for this program.
|
|
|
|
|
|
|
|
@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
|
|
|
|
name which is the name of the package it is a distribution for. This
|
|
|
|
name can include the version number.
|
|
|
|
|
|
|
|
For example, the distribution tar file of GCC version 1.40 unpacks into
|
|
|
|
a subdirectory named @file{gcc-1.40}.
|
|
|
|
|
|
|
|
The easiest way to do this is to create a subdirectory appropriately
|
|
|
|
named, use @code{ln} or @code{cp} to install the proper files in it, and
|
|
|
|
then @code{tar} that subdirectory.
|
|
|
|
|
|
|
|
The @code{dist} target should explicitly depend on all non-source files
|
|
|
|
that are in the distribution, to make sure they are up to date in the
|
|
|
|
distribution. @xref{Releases}.
|
|
|
|
|
|
|
|
@item check
|
|
|
|
Perform self-tests (if any). The user must build the program before
|
|
|
|
running the tests, but need not install the program; you should write
|
|
|
|
the self-tests so that they work when the program is built but not
|
|
|
|
installed.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
@node Command Variables
|
|
|
|
@section Variables for Specifying Commands
|
|
|
|
|
|
|
|
Makefiles should provide variables for overriding certain commands, options,
|
|
|
|
and so on.
|
|
|
|
|
|
|
|
In particular, you should run most utility programs via variables.
|
|
|
|
Thus, if you use Bison, have a variable named @code{BISON} whose default
|
|
|
|
value is set with @samp{BISON = bison}, and refer to it with
|
|
|
|
@code{$(BISON)} whenever you need to use Bison.
|
|
|
|
|
|
|
|
Each program-name variable should come with an options variable that is
|
|
|
|
used to supply options to the program. Append @samp{FLAGS} to the
|
|
|
|
program-name variable name to get the options variable name---for
|
|
|
|
example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
|
|
|
|
this rule, but we keep it because it is standard.)
|
|
|
|
|
|
|
|
File-management utilities such as @code{ln}, @code{rm}, @code{mv}, and
|
|
|
|
so on need not be referred to through variables in this way, since users
|
|
|
|
don't need to replace them with other programs.
|
|
|
|
|
|
|
|
Every Makefile should define the variable @code{INSTALL}, which is the
|
|
|
|
basic command for installing a file into the system.
|
|
|
|
|
|
|
|
Every Makefile should also define variables @code{INSTALL_PROGRAM} and
|
|
|
|
@code{INSTALL_DATA}. (The default for each of these should be
|
|
|
|
@code{$(INSTALL)}.) Then it should use those variables as the commands
|
|
|
|
for actual installation, for executables and nonexecutables
|
|
|
|
respectively. Use these variables as follows:
|
|
|
|
|
|
|
|
@example
|
|
|
|
$(INSTALL_PROGRAM) foo $@{bindir@}/foo
|
|
|
|
$(INSTALL_DATA) libfoo.a $@{libdir@}/libfoo.a
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
(Always use a file name, not a directory name, as the second argument.
|
|
|
|
Use a separate command for each file to be installed.)
|
|
|
|
|
|
|
|
@node Directory Variables
|
|
|
|
@section Variables for Installation Directories
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
@table @samp
|
1992-05-08 17:32:25 +02:00
|
|
|
@item prefix
|
|
|
|
A prefix used in constructing the default values of the variables listed
|
|
|
|
below. The default value of @code{prefix} should be @file{/usr/local}
|
|
|
|
(at least for now).
|
|
|
|
|
|
|
|
@item exec_prefix
|
|
|
|
A prefix used in constructing the default values of the some of the
|
|
|
|
variables listed below. The default value of @code{exec_prefix} should
|
|
|
|
be @code{$(prefix)}.
|
|
|
|
|
|
|
|
Generally, @code{$(exec_prefix)} is used for directories that contain
|
|
|
|
machine-specific files (such as executables and subroutine libraries),
|
|
|
|
while @code{$(prefix)} is used directly for other directories.
|
|
|
|
|
1992-04-25 00:21:27 +02:00
|
|
|
@item bindir
|
|
|
|
The directory for installing executable programs that users can run.
|
1992-05-08 17:32:25 +02:00
|
|
|
This should normally be @file{/usr/local/bin}, but it should be written
|
|
|
|
as @file{$(exec_prefix)/bin}.
|
|
|
|
|
|
|
|
@item libdir
|
|
|
|
The directory for installing executable files to be run by the program
|
|
|
|
rather than by users. Object files and libraries of object code should
|
|
|
|
also go in this directory. The idea is that this directory is used for
|
|
|
|
files that pertain to a specific machine architecture, but need not be
|
|
|
|
in the path for commands. The value of @code{libdir} should normally be
|
|
|
|
@file{/usr/local/lib}, but it should be written as
|
|
|
|
@file{$(exec_prefix)/lib}.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
@item datadir
|
|
|
|
The directory for installing read-only data files which the programs
|
|
|
|
refer to while they run. This directory is used for files which are
|
|
|
|
independent of the type of machine being used. This should normally be
|
1992-05-08 17:32:25 +02:00
|
|
|
@file{/usr/local/lib}, but it should be written as
|
|
|
|
@file{$(prefix)/lib}.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
@item statedir
|
|
|
|
The directory for installing data files which the programs modify while
|
|
|
|
they run. These files should be independent of the type of machine
|
|
|
|
being used, and it should be possible to share them among machines at a
|
|
|
|
network installation. This should normally be @file{/usr/local/lib},
|
1992-05-08 17:32:25 +02:00
|
|
|
but it should be written as @file{$(prefix)/lib}.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
@item includedir
|
|
|
|
The directory for installing @samp{#include} header files to be included
|
|
|
|
by user programs. This should normally be @file{/usr/local/include},
|
1992-05-08 17:32:25 +02:00
|
|
|
but it should be written as @file{$(prefix)/include}.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
Most compilers other than GCC do not look for header files in
|
|
|
|
@file{/usr/local/include}. So installing the header files this way is
|
|
|
|
only useful with GCC. Sometimes this is not a problem because some
|
|
|
|
libraries are only really intended to work with GCC. But some libraries
|
|
|
|
are intended to work with other compilers. They should install their
|
|
|
|
header files in two places, one specified by includedir and one
|
|
|
|
specified by oldincludedir
|
|
|
|
|
|
|
|
@item oldincludedir
|
|
|
|
The directory for installing @samp{#include} header files for use with
|
|
|
|
compilers other than GCC. This should normally be @file{/usr/include}.
|
|
|
|
|
|
|
|
The Makefile commands should check whether the value of
|
|
|
|
@code{oldincludedir} is empty. If it is, they should not try to use
|
|
|
|
it; they should cancel the second installation of the header files.
|
|
|
|
|
|
|
|
@item mandir
|
|
|
|
The directory for installing the man pages (if any) for this package.
|
|
|
|
It should include the suffix for the proper section of the
|
|
|
|
manual---usually @samp{1} for a utility.
|
|
|
|
|
|
|
|
@item man1dir
|
|
|
|
The directory for installing section 1 man pages.
|
|
|
|
@item man2dir
|
|
|
|
The directory for installing section 2 man pages.
|
|
|
|
@item @dots{}
|
|
|
|
Use these names instead of @samp{mandir} if the package needs to install man
|
|
|
|
pages in more than one section of the manual.
|
|
|
|
|
|
|
|
@strong{Don't make the primary documentation for any GNU software be a
|
|
|
|
man page. Write a manual in Texinfo instead. Man pages are just for
|
|
|
|
the sake of people running GNU software on Unix, which is a secondary
|
|
|
|
application only.}
|
|
|
|
|
|
|
|
@item manext
|
|
|
|
The file name extension for the installed man page. This should contain
|
|
|
|
a period followed by the appropriate digit.
|
|
|
|
|
|
|
|
@item infodir
|
|
|
|
The directory for installing the info files for this package. By
|
1992-05-08 17:32:25 +02:00
|
|
|
default, it should be @file{/usr/local/info}, but it should be written
|
|
|
|
as @file{$(prefix)/info}.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
@item srcdir
|
|
|
|
The directory for the sources being compiled. The value of this
|
|
|
|
variable is normally inserted by the @code{configure} shell script.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
# Common prefix for installation directories.
|
|
|
|
# NOTE: This directory must exist when you start installation.
|
|
|
|
prefix = /usr/local
|
1992-05-08 17:32:25 +02:00
|
|
|
exec_prefix = $(prefix)
|
1992-04-25 00:21:27 +02:00
|
|
|
# Directory in which to put the executable for the command `gcc'
|
1992-05-08 17:32:25 +02:00
|
|
|
bindir = $(exec_prefix)/bin
|
1992-04-25 00:21:27 +02:00
|
|
|
# Directory in which to put the directories used by the compiler.
|
1992-05-08 17:32:25 +02:00
|
|
|
libdir = $(exec_prefix)/lib
|
|
|
|
# Directory in which to put the Info files.
|
|
|
|
infodir = $(prefix)/info
|
1992-04-25 00:21:27 +02:00
|
|
|
@end example
|
|
|
|
|
|
|
|
@node Configuration
|
|
|
|
@chapter How Configuration Should Work
|
|
|
|
|
|
|
|
Each GNU distribution should come with a shell script named
|
|
|
|
@code{configure}. This script is given arguments which describe the
|
|
|
|
kind of machine and system you want to compile the program for.
|
|
|
|
|
|
|
|
The @code{configure} script must record the configuration options so
|
|
|
|
that they affect compilation.
|
|
|
|
|
|
|
|
One way to do this is to make a link from a standard name such as
|
|
|
|
@file{config.h} to the proper configuration file for the chosen system.
|
|
|
|
If you use this technique, the distribution should @emph{not} contain a
|
|
|
|
file named @file{config.h}. This is so that people won't be able to
|
|
|
|
build the program without configuring it first.
|
|
|
|
|
|
|
|
Another thing that @code{configure} can do is to edit the Makefile. If
|
|
|
|
you do this, the distribution should @emph{not} contain a file named
|
|
|
|
@file{Makefile}. Instead, include a file @file{Makefile.in} which
|
|
|
|
contains the input used for editing. Once again, this is so that people
|
|
|
|
won't be able to build the program without configuring it first.
|
|
|
|
|
|
|
|
If @code{configure} does write the @file{Makefile}, then @file{Makefile}
|
|
|
|
should have a target named @file{Makefile} which causes @code{configure}
|
|
|
|
to be rerun, setting up the same configuration that was set up last
|
|
|
|
time. The files that @code{configure} reads should be listed as
|
|
|
|
dependencies of @file{Makefile}.
|
|
|
|
|
|
|
|
All the files which are output from the @code{configure} script should
|
|
|
|
have comments at the beginning explaining that they were generated
|
|
|
|
automatically using @code{configure}. This is so that users won't think
|
|
|
|
of trying to edit them by hand.
|
|
|
|
|
|
|
|
The @code{configure} script should write a file named @file{config.status}
|
|
|
|
which describes which configuration options were specified when the
|
|
|
|
program was last configured. This file should be a shell script which,
|
|
|
|
if run, will recreate the same configuration.
|
|
|
|
|
|
|
|
The @code{configure} script should accept an option of the form
|
|
|
|
@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
|
|
|
|
(if it is not the current directory). This makes it possible to build
|
|
|
|
the program in a separate directory, so that the actual source directory
|
|
|
|
is not modified.
|
|
|
|
|
|
|
|
If the user does not specify @samp{--srcdir}, then @code{configure} should
|
|
|
|
check both @file{.} and @file{..} to see if it can find the sources. If
|
|
|
|
it finds the sources in one of these places, it should use them from
|
|
|
|
there. Otherwise, it should report that it cannot find the sources, and
|
|
|
|
should exit with nonzero status.
|
|
|
|
|
|
|
|
Usually the easy way to support @samp{--srcdir} is by editing a
|
|
|
|
definition of @code{VPATH} into the Makefile. Some rules may need to
|
|
|
|
refer explicitly to the specified source directory. To make this
|
|
|
|
possible, @code{configure} can add to the Makefile a variable named
|
|
|
|
@code{srcdir} whose value is precisely the specified directory.
|
|
|
|
|
|
|
|
The @code{configure} script should also take an argument which specifies the
|
|
|
|
type of system to build the program for. This argument should look like
|
|
|
|
this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
@var{cpu}-@var{company}-@var{system}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
|
|
|
|
|
|
|
|
The @code{configure} script needs to be able to decode all plausible
|
|
|
|
alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
|
1992-05-19 01:26:45 +02:00
|
|
|
would be a valid alias. So would @samp{sun3-bsd4.2}, since SunOS is
|
1992-04-25 00:21:27 +02:00
|
|
|
basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. For many
|
|
|
|
programs, @samp{vax-dec-ultrix} would be an alias for
|
|
|
|
@samp{vax-dec-bsd}, simply because the differences between Ultrix and
|
|
|
|
@sc{BSD} are rarely noticeable, but a few programs might need to distinguish
|
|
|
|
them.
|
|
|
|
|
|
|
|
There is a shell script called @file{config.sub} that you can use
|
|
|
|
as a subroutine to validate system types and canonicalize aliases.
|
|
|
|
|
|
|
|
Other options are permitted to specify in more detail the software
|
|
|
|
or hardware are present on the machine:
|
|
|
|
|
|
|
|
@table @samp
|
|
|
|
@item --with-@var{package}
|
|
|
|
The package @var{package} will be installed, so configure this package
|
|
|
|
to work with @var{package}.
|
|
|
|
|
|
|
|
Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or
|
|
|
|
@samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}.
|
|
|
|
|
|
|
|
@item --nfp
|
|
|
|
The target machine has no floating point processor.
|
|
|
|
|
|
|
|
@item --gas
|
|
|
|
The target machine assembler is GAS, the GNU assembler.
|
|
|
|
This is obsolete; use @samp{--with-gnu-as} instead.
|
|
|
|
|
|
|
|
@item --x
|
|
|
|
The target machine has the X Window system installed.
|
|
|
|
This is obsolete; use @samp{--with-x} instead.
|
|
|
|
@end table
|
|
|
|
|
|
|
|
All @code{configure} scripts should accept all of these ``detail''
|
|
|
|
options, whether or not they make any difference to the particular
|
|
|
|
package at hand. In particular, they should accept any option that
|
|
|
|
starts with @samp{--with-}. This is so users will be able to configure
|
|
|
|
an entire GNU source tree at once with a single set of options.
|
|
|
|
|
|
|
|
Packages that perform part of compilation may support cross-compilation.
|
|
|
|
In such a case, the host and target machines for the program may be
|
|
|
|
different. The @code{configure} script should normally treat the
|
|
|
|
specified type of system as both the host and the target, thus producing
|
|
|
|
a program which works for the same type of machine that it runs on.
|
|
|
|
|
|
|
|
The way to build a cross-compiler, cross-assembler, or what have you, is
|
|
|
|
to specify the option @samp{--host=@var{hosttype}} when running
|
|
|
|
@code{configure}. This specifies the host system without changing the
|
|
|
|
type of target system. The syntax for @var{hosttype} is the same as
|
|
|
|
described above.
|
|
|
|
|
|
|
|
Programs for which cross-operation is not meaningful need not accept the
|
|
|
|
@samp{--host} option, because configuring an entire operating system for
|
|
|
|
cross-operation is not a meaningful thing.
|
|
|
|
|
|
|
|
Some programs have ways of configuring themselves automatically. If
|
|
|
|
your program is set up to do this, your @code{configure} script can simply
|
|
|
|
ignore most of its arguments.
|
|
|
|
|
|
|
|
|
|
|
|
@node Source Language
|
|
|
|
@chapter Using Languages Other Than C
|
|
|
|
|
|
|
|
Using a language other than C is like using a non-standard feature: it
|
|
|
|
will cause trouble for users. Even if GCC supports the other language,
|
|
|
|
users may find it inconvenient to have to install the compiler for that
|
|
|
|
other language in order to build your program. So please write in C.
|
|
|
|
|
|
|
|
There are three exceptions for this rule:
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
|
|
It is okay to use a special language if the same program contains an
|
|
|
|
interpreter for that language.
|
|
|
|
|
|
|
|
Thus, it is not a problem that GNU Emacs contains code written in Emacs
|
|
|
|
Lisp, because it comes with a Lisp interpreter.
|
|
|
|
|
|
|
|
@item
|
|
|
|
It is okay to use another language in a tool specifically intended for
|
|
|
|
use with that language.
|
|
|
|
|
|
|
|
This is okay because the only people who want to build the tool will be
|
|
|
|
those who have installed the other language anyway.
|
|
|
|
|
|
|
|
@item
|
|
|
|
If an application is not of extremely widespread interest, then perhaps
|
|
|
|
it's not important if the application is inconvenient to install.
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
@node Formatting
|
|
|
|
@chapter Formatting Your Source Code
|
|
|
|
|
|
|
|
It is important to put the open-brace that starts the body of a C
|
|
|
|
function in column zero, and avoid putting any other open-brace or
|
|
|
|
open-parenthesis or open-bracket in column zero. Several tools look
|
|
|
|
for open-braces in column zero to find the beginnings of C functions.
|
|
|
|
These tools will not work on code not formatted that way.
|
|
|
|
|
|
|
|
It is also important for function definitions to start the name of the
|
|
|
|
function in column zero. This helps people to search for function
|
|
|
|
definitions, and may also help certain tools recognize them. Thus,
|
|
|
|
the proper format is this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
static char *
|
|
|
|
concat (s1, s2) /* Name starts in column zero here */
|
|
|
|
char *s1, *s2;
|
|
|
|
@{ /* Open brace in column zero here */
|
|
|
|
@dots{}
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
or, if you want to use @sc{ANSI} C, format the definition like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
static char *
|
|
|
|
concat (char *s1, char *s2)
|
|
|
|
@{
|
|
|
|
@dots{}
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
In @sc{ANSI} C, if the arguments don't fit nicely on one line,
|
|
|
|
split it like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
int
|
|
|
|
lots_of_args (int an_integer, long a_long, short a_short,
|
|
|
|
double a_double, float a_float)
|
|
|
|
@dots{}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
For the body of the function, we prefer code formatted like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (x < foo (y, z))
|
|
|
|
haha = bar[4] + 5;
|
|
|
|
else
|
|
|
|
@{
|
|
|
|
while (z)
|
|
|
|
@{
|
|
|
|
haha += foo (z, z);
|
|
|
|
z--;
|
|
|
|
@}
|
|
|
|
return ++x + bar ();
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
We find it easier to read a program when it has spaces before the
|
|
|
|
open-parentheses and after the commas. Especially after the commas.
|
|
|
|
|
|
|
|
When you split an expression into multiple lines, split it
|
|
|
|
before an operator, not after one. Here is the right way:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (foo_this_is_long && bar > win (x, y, z)
|
|
|
|
&& remaining_condition)
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Try to avoid having two operators of different precedence at the same
|
|
|
|
level of indentation. For example, don't write this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
mode = (inmode[j] == VOIDmode
|
|
|
|
|| GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
|
|
|
|
? outmode[j] : inmode[j]);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Instead, use extra parentheses so that the indentation shows the nesting:
|
|
|
|
|
|
|
|
@example
|
|
|
|
mode = ((inmode[j] == VOIDmode
|
|
|
|
|| (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
|
|
|
|
? outmode[j] : inmode[j]);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Insert extra parentheses so that Emacs will indent the code properly.
|
|
|
|
For example, the following indentation looks nice if you do it by hand,
|
|
|
|
but Emacs would mess it up:
|
|
|
|
|
|
|
|
@example
|
|
|
|
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
|
|
|
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
But adding a set of parentheses solves the problem:
|
|
|
|
|
|
|
|
@example
|
|
|
|
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
|
|
|
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Format do-while statements like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
do
|
|
|
|
@{
|
|
|
|
a = foo (a);
|
|
|
|
@}
|
|
|
|
while (a > 0);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Please use formfeed characters (control-L) to divide the program into
|
|
|
|
pages at logical places (but not within a function). It does not matter
|
|
|
|
just how long the pages are, since they do not have to fit on a printed
|
|
|
|
page. The formfeeds should appear alone on lines by themselves.
|
|
|
|
|
|
|
|
|
|
|
|
@node Comments
|
|
|
|
@chapter Commenting Your Work
|
|
|
|
|
|
|
|
Every program should start with a comment saying briefly what it is for.
|
|
|
|
Example: @samp{fmt - filter for simple filling of text}.
|
|
|
|
|
|
|
|
Please put a comment on each function saying what the function does,
|
|
|
|
what sorts of arguments it gets, and what the possible values of
|
|
|
|
arguments mean and are used for. It is not necessary to duplicate in
|
|
|
|
words the meaning of the C argument declarations, if a C type is being
|
|
|
|
used in its customary fashion. If there is anything nonstandard about
|
|
|
|
its use (such as an argument of type @code{char *} which is really the
|
|
|
|
address of the second character of a string, not the first), or any
|
|
|
|
possible values that would not work the way one would expect (such as,
|
|
|
|
that strings containing newlines are not guaranteed to work), be sure
|
|
|
|
to say so.
|
|
|
|
|
|
|
|
Also explain the significance of the return value, if there is one.
|
|
|
|
|
|
|
|
Please put two spaces after the end of a sentence in your comments, so
|
|
|
|
that the Emacs sentence commands will work. Also, please write
|
|
|
|
complete sentences and capitalize the first word. If a lower-case
|
|
|
|
identifer comes at the beginning of a sentence, don't capitalize it!
|
|
|
|
Changing the spelling makes it a different identifier. If you don't
|
|
|
|
like starting a sentence with a lower case letter, write the sentence
|
|
|
|
differently (e.g. ``The identifier lower-case is @dots{}'').
|
|
|
|
|
|
|
|
The comment on a function is much clearer if you use the argument
|
|
|
|
names to speak about the argument values. The variable name itself
|
|
|
|
should be lower case, but write it in upper case when you are speaking
|
|
|
|
about the value rather than the variable itself. Thus, ``the inode
|
|
|
|
number @var{node_num}'' rather than ``an inode''.
|
|
|
|
|
|
|
|
There is usually no purpose in restating the name of the function in
|
|
|
|
the comment before it, because the reader can see that for himself.
|
|
|
|
There might be an exception when the comment is so long that the function
|
|
|
|
itself would be off the bottom of the screen.
|
|
|
|
|
|
|
|
There should be a comment on each static variable as well, like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
/* Nonzero means truncate lines in the display;
|
|
|
|
zero means continue them. */
|
|
|
|
|
|
|
|
int truncate_lines;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Every @samp{#endif} should have a comment, except in the case of short
|
|
|
|
conditionals (just a few lines) that are not nested. The comment should
|
|
|
|
state the condition of the conditional that is ending, @emph{including
|
|
|
|
its sense}. @samp{#else} should have a comment describing the condition
|
|
|
|
@emph{and sense} of the code that follows. For example:
|
|
|
|
|
|
|
|
@example
|
|
|
|
#ifdef foo
|
|
|
|
@dots{}
|
|
|
|
#else /* not foo */
|
|
|
|
@dots{}
|
|
|
|
#endif /* not foo */
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
but, by contrast, write the comments this way for a @samp{#ifndef}:
|
|
|
|
|
|
|
|
@example
|
|
|
|
#ifndef foo
|
|
|
|
@dots{}
|
|
|
|
#else /* foo */
|
|
|
|
@dots{}
|
|
|
|
#endif /* foo */
|
|
|
|
@end example
|
|
|
|
|
|
|
|
|
|
|
|
@node Syntactic Conventions
|
|
|
|
@chapter Clean Use of C Constructs
|
|
|
|
|
|
|
|
Please explicitly declare all arguments to functions.
|
|
|
|
Don't omit them just because they are ints.
|
|
|
|
|
|
|
|
Declarations of external functions and functions to appear later
|
|
|
|
in the source file should all go in one place near the beginning of
|
|
|
|
the file (somewhere before the first function definition in the file),
|
|
|
|
or else should go in a header file. Don't put extern declarations
|
|
|
|
inside functions.
|
|
|
|
|
|
|
|
Don't declare multiple variables in one declaration that spans lines.
|
|
|
|
Start a new declaration on each line, instead. For example, instead
|
|
|
|
of this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
int foo,
|
|
|
|
bar;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
write either this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
int foo, bar;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
or this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
int foo;
|
|
|
|
int bar;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
(If they are global variables, each should have a comment preceding it
|
|
|
|
anyway.)
|
|
|
|
|
|
|
|
When you have an if-else statement nested in another if statement,
|
|
|
|
always put braces around the if-else. Thus, never write like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (foo)
|
|
|
|
if (bar)
|
|
|
|
win ();
|
|
|
|
else
|
|
|
|
lose ();
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
always like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (foo)
|
|
|
|
@{
|
|
|
|
if (bar)
|
|
|
|
win ();
|
|
|
|
else
|
|
|
|
lose ();
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
If you have an if statement nested inside of an else statement,
|
|
|
|
either write @code{else if} on one line, like this,
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (foo)
|
|
|
|
@dots{}
|
|
|
|
else if (bar)
|
|
|
|
@dots{}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
with its then-part indented like the preceding then-part, or write the
|
|
|
|
nested if within braces like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if (foo)
|
|
|
|
@dots{}
|
|
|
|
else
|
|
|
|
@{
|
|
|
|
if (bar)
|
|
|
|
@dots{}
|
|
|
|
@}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Don't declare both a structure tag and variables or typedefs in the
|
|
|
|
same declaration. Instead, declare the structure tag separately
|
|
|
|
and then use it to declare the variables or typedefs.
|
|
|
|
|
|
|
|
Try to avoid assignments inside if-conditions. For example, don't
|
|
|
|
write this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
if ((foo = (char *) malloc (sizeof *foo)) == 0)
|
|
|
|
fatal ("virtual memory exhausted");
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
instead, write this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
foo = (char *) malloc (sizeof *foo);
|
|
|
|
if (foo == 0)
|
|
|
|
fatal ("virtual memory exhausted");
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Don't make the program ugly to placate lint. Please don't insert any
|
|
|
|
casts to void. Zero without a cast is perfectly fine as a null
|
|
|
|
pointer constant.
|
|
|
|
|
|
|
|
|
|
|
|
@node Names
|
|
|
|
@chapter Naming Variables and Functions
|
|
|
|
|
|
|
|
Please use underscores to separate words in a name, so that the Emacs
|
|
|
|
word commands can be useful within them. Stick to lower case; reserve
|
|
|
|
upper case for macros and enum constants, and for name-prefixes that
|
|
|
|
follow a uniform convention.
|
|
|
|
|
|
|
|
For example, you should use names like @code{ignore_space_change_flag};
|
|
|
|
don't use names like @code{iCantReadThis}.
|
|
|
|
|
|
|
|
Variables that indicate whether command-line options have been
|
|
|
|
specified should be named after the meaning of the option, not after
|
|
|
|
the option-letter. A comment should state both the exact meaning of
|
|
|
|
the option and its letter. For example,
|
|
|
|
|
|
|
|
@example
|
|
|
|
/* Ignore changes in horizontal whitespace (-b). */
|
|
|
|
int ignore_space_change_flag;
|
|
|
|
@end example
|
|
|
|
|
|
|
|
When you want to define names with constant integer values, use
|
|
|
|
@code{enum} rather than @samp{#define}. GDB knows about enumeration
|
|
|
|
constants.
|
|
|
|
|
|
|
|
Use file names of 14 characters or less, to avoid creating gratuitous
|
|
|
|
problems on System V.
|
|
|
|
|
|
|
|
|
|
|
|
@node Using Extensions
|
|
|
|
@chapter Using Non-standard Features
|
|
|
|
|
|
|
|
Many GNU facilities that already exist support a number of convenient
|
|
|
|
extensions over the comparable Unix facilities. Whether to use these
|
|
|
|
extensions in implementing your program is a difficult question.
|
|
|
|
|
|
|
|
On the one hand, using the extensions can make a cleaner program.
|
|
|
|
On the other hand, people will not be able to build the program
|
|
|
|
unless the other GNU tools are available. This might cause the
|
|
|
|
program to work on fewer kinds of machines.
|
|
|
|
|
|
|
|
With some extensions, it might be easy to provide both alternatives.
|
|
|
|
For example, you can define functions with a ``keyword'' @code{INLINE}
|
|
|
|
and define that as a macro to expand into either @code{inline} or
|
|
|
|
nothing, depending on the compiler.
|
|
|
|
|
|
|
|
In general, perhaps it is best not to use the extensions if you can
|
|
|
|
straightforwardly do without them, but to use the extensions if they
|
|
|
|
are a big improvement.
|
|
|
|
|
|
|
|
An exception to this rule are the large, established programs (such as
|
|
|
|
Emacs) which run on a great variety of systems. Such programs would
|
|
|
|
be broken by use of GNU extensions.
|
|
|
|
|
|
|
|
Another exception is for programs that are used as part of
|
|
|
|
compilation: anything that must be compiled with other compilers in
|
|
|
|
order to bootstrap the GNU compilation facilities. If these require
|
|
|
|
the GNU compiler, then no one can compile them without having them
|
|
|
|
installed already. That would be no good.
|
|
|
|
|
|
|
|
Since most computer systems do not yet implement @sc{ANSI} C, using the
|
|
|
|
@sc{ANSI} C features is effectively using a GNU extension, so the
|
|
|
|
same considerations apply. (Except for @sc{ANSI} features that we
|
|
|
|
discourage, such as trigraphs---don't ever use them.)
|
|
|
|
|
|
|
|
@node Semantics
|
|
|
|
@chapter Program Behaviour for All Programs
|
|
|
|
|
|
|
|
Avoid arbitrary limits on the length or number of @emph{any} data
|
|
|
|
structure, including filenames, lines, files, and symbols, by allocating
|
|
|
|
all data structures dynamically. In most Unix utilities, ``long lines
|
|
|
|
are silently truncated''. This is not acceptable in a GNU utility.
|
|
|
|
|
|
|
|
Utilities reading files should not drop NUL characters, or any other
|
|
|
|
nonprinting characters @emph{including those with codes above 0177}. The
|
|
|
|
only sensible exceptions would be utilities specifically intended for
|
|
|
|
interface to certain types of printers that can't handle those characters.
|
|
|
|
|
|
|
|
Check every system call for an error return, unless you know you wish to
|
|
|
|
ignore errors. Include the system error text (from @code{perror} or
|
|
|
|
equivalent) in @emph{every} error message resulting from a failing
|
|
|
|
system call, as well as the name of the file if any and the name of the
|
|
|
|
utility. Just ``cannot open foo.c'' or ``stat failed'' is not
|
|
|
|
sufficient.
|
|
|
|
|
|
|
|
Check every call to @code{malloc} or @code{realloc} to see if it
|
|
|
|
returned zero. Check @code{realloc} even if you are making the block
|
|
|
|
smaller; in a system that rounds block sizes to a power of 2,
|
|
|
|
@code{realloc} may get a different block if you ask for less space.
|
|
|
|
|
|
|
|
In Unix, @code{realloc} can destroy the storage block if it returns
|
|
|
|
zero. GNU @code{realloc} does not have this bug: if it fails, the
|
|
|
|
original block is unchanged. Feel free to assume the bug is fixed. If
|
|
|
|
you wish to run your program on Unix, and wish to avoid lossage in this
|
|
|
|
case, you can use the GNU @code{malloc}.
|
|
|
|
|
|
|
|
You must expect @code{free} to alter the contents of the block that was
|
|
|
|
freed. Anything you want to fetch from the block, you must fetch before
|
|
|
|
calling @code{free}.
|
|
|
|
|
|
|
|
Use @code{getopt_long} to decode arguments, unless the argument syntax
|
|
|
|
makes this unreasonable.
|
|
|
|
|
|
|
|
When static storage is to be written in during program execution, use
|
|
|
|
explicit C code to initialize it. Reserve C initialized declarations
|
|
|
|
for data that will not be changed.
|
|
|
|
|
|
|
|
Try to avoid low-level interfaces to obscure Unix data structures (such
|
|
|
|
as file directories, utmp, or the layout of kernel memory), since these
|
|
|
|
are less likely to work compatibly. If you need to find all the files
|
1992-05-19 01:26:45 +02:00
|
|
|
in a directory, use @code{readdir} or some other high-level interface.
|
|
|
|
These will be supported compatibly by GNU.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
1992-05-19 01:26:45 +02:00
|
|
|
By default, the GNU system will provide the signal handling functions of
|
|
|
|
@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use
|
|
|
|
these.
|
1992-04-25 00:21:27 +02:00
|
|
|
|
|
|
|
In error checks that detect ``impossible'' conditions, just abort.
|
|
|
|
There is usually no point in printing any message. These checks
|
|
|
|
indicate the existence of bugs. Whoever wants to fix the bugs will have
|
|
|
|
to read the source code and run a debugger. So explain the problem with
|
|
|
|
comments in the source. The relevant data will be in variables, which
|
|
|
|
are easy to examine with the debugger, so there is no point moving them
|
|
|
|
elsewhere.
|
|
|
|
|
|
|
|
|
|
|
|
@node Errors
|
|
|
|
@chapter Formatting Error Messages
|
|
|
|
|
|
|
|
Error messages from compilers should look like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
@var{source-file-name}:@var{lineno}: @var{message}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
Error messages from other noninteractive programs should look like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
@var{program}:@var{source-file-name}:@var{lineno}: @var{message}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
when there is an appropriate source file, or like this:
|
|
|
|
|
|
|
|
@example
|
|
|
|
@var{program}: @var{message}
|
|
|
|
@end example
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
when there is no relevant source file.
|
|
|
|
|
|
|
|
In an interactive program (one that is reading commands from a
|
|
|
|
terminal), it is better not to include the program name in an error
|
|
|
|
message. The place to indicate which program is running is in the
|
|
|
|
prompt or with the screen layout. (When the same program runs with
|
|
|
|
input from a source other than a terminal, it is not interactive and
|
|
|
|
would do best to print error messages using the noninteractive style.)
|
|
|
|
|
|
|
|
The string @var{message} should not begin with a capital letter when
|
|
|
|
it follows a program name and/or filename. Also, it should not end
|
|
|
|
with a period.
|
|
|
|
|
|
|
|
Error messages from interactive programs, and other messages such as
|
|
|
|
usage messages, should start with a capital letter. But they should not
|
|
|
|
end with a period.
|
|
|
|
|
|
|
|
|
|
|
|
@node Libraries
|
|
|
|
@chapter Library Behaviour
|
|
|
|
|
|
|
|
Try to make library functions reentrant. If they need to do dynamic
|
|
|
|
storage allocation, at least try to avoid any nonreentrancy aside from
|
|
|
|
that of @code{malloc} itself.
|
|
|
|
|
|
|
|
Here are certain name conventions for libraries, to avoid name
|
|
|
|
conflicts.
|
|
|
|
|
|
|
|
Choose a name prefix for the library, more than two characters long.
|
|
|
|
All external function and variable names should start with this
|
|
|
|
prefix. In addition, there should only be one of these in any given
|
|
|
|
library member. This usually means putting each one in a separate
|
|
|
|
source file.
|
|
|
|
|
|
|
|
An exception can be made when two external symbols are always used
|
|
|
|
together, so that no reasonable program could use one without the
|
|
|
|
other; then they can both go in the same file.
|
|
|
|
|
|
|
|
External symbols that are not documented entry points for the user
|
|
|
|
should have names beginning with @samp{_}. They should also contain
|
|
|
|
the chosen name prefix for the library, to prevent collisions with
|
|
|
|
other libraries. These can go in the same files with user entry
|
|
|
|
points if you like.
|
|
|
|
|
|
|
|
Static functions and variables can be used as you like and need not
|
|
|
|
fit any naming convention.
|
|
|
|
|
|
|
|
|
|
|
|
@node Portability
|
|
|
|
@chapter Portability As It Applies to GNU
|
|
|
|
|
|
|
|
Much of what is called ``portability'' in the Unix world refers to
|
|
|
|
porting to different Unix versions. This is not relevant to GNU
|
|
|
|
software, because its purpose is to run on top of one and only
|
|
|
|
one kernel, the GNU kernel, compiled with one and only one C
|
|
|
|
compiler, the GNU C compiler. The amount and kinds of variation
|
|
|
|
among GNU systems on different cpu's will be like the variation
|
|
|
|
among Berkeley 4.3 systems on different cpu's.
|
|
|
|
|
|
|
|
It is difficult to be sure exactly what facilities the GNU kernel
|
|
|
|
will provide, since it isn't finished yet. Therefore, assume you can
|
|
|
|
use anything in 4.3; just avoid using the format of semi-internal data
|
|
|
|
bases (e.g., directories) when there is a higher-level alternative
|
|
|
|
(readdir).
|
|
|
|
|
|
|
|
You can freely assume any reasonably standard facilities in the C
|
|
|
|
language, libraries or kernel, because we will find it necessary to
|
|
|
|
support these facilities in the full GNU system, whether or not we
|
|
|
|
have already done so. The fact that there may exist kernels or C
|
|
|
|
compilers that lack these facilities is irrelevant as long as the GNU
|
|
|
|
kernel and C compiler support them.
|
|
|
|
|
|
|
|
It remains necessary to worry about differences among cpu types, such
|
|
|
|
as the difference in byte ordering and alignment restrictions. It's
|
|
|
|
unlikely that 16-bit machines will ever be supported by GNU, so there
|
|
|
|
is no point in spending any time to consider the possibility that an
|
|
|
|
int will be less than 32 bits.
|
|
|
|
|
|
|
|
You can assume that all pointers have the same format, regardless
|
|
|
|
of the type they point to, and that this is really an integer.
|
|
|
|
There are some weird machines where this isn't true, but they aren't
|
|
|
|
important; don't waste time catering to them. Besides, eventually
|
|
|
|
we will put function prototypes into all GNU programs, and that will
|
|
|
|
probably make your program work even on weird machines.
|
|
|
|
|
|
|
|
Since some important machines (including the 68000) are big-endian,
|
|
|
|
it is important not to assume that the address of an int object
|
|
|
|
is also the address of its least-significant byte. Thus, don't
|
|
|
|
make the following mistake:
|
|
|
|
|
|
|
|
@example
|
|
|
|
int c;
|
|
|
|
@dots{}
|
|
|
|
while ((c = getchar()) != EOF)
|
|
|
|
write(file_descriptor, &c, 1);
|
|
|
|
@end example
|
|
|
|
|
|
|
|
You can assume that it is reasonable to use a meg of memory. Don't
|
|
|
|
strain to reduce memory usage unless it can get to that level. If
|
|
|
|
your program creates complicated data structures, just make them in
|
|
|
|
core and give a fatal error if malloc returns zero.
|
|
|
|
|
|
|
|
If a program works by lines and could be applied to arbitrary
|
|
|
|
user-supplied input files, it should keep only a line in memory, because
|
|
|
|
this is not very hard and users will want to be able to operate on input
|
|
|
|
files that are bigger than will fit in core all at once.
|
|
|
|
|
|
|
|
|
|
|
|
@node User Interfaces
|
|
|
|
@chapter Standards for Command Line Interfaces
|
|
|
|
|
|
|
|
Please don't make the behavior of a utility depend on the name used
|
|
|
|
to invoke it. It is useful sometimes to make a link to a utility
|
|
|
|
with a different name, and that should not change what it does.
|
|
|
|
|
|
|
|
Instead, use a run time option or a compilation switch or both
|
|
|
|
to select among the alternate behaviors.
|
|
|
|
|
|
|
|
It is a good idea to follow the @sc{POSIX} guidelines for the
|
|
|
|
command-line options of a program. The easiest way to do this is to use
|
|
|
|
@code{getopt} to parse them. Note that the GNU version of @code{getopt}
|
|
|
|
will normally permit options anywhere among the arguments unless the
|
|
|
|
special argument @samp{--} is used. This is not what @sc{POSIX}
|
|
|
|
specifies; it is a GNU extension.
|
|
|
|
|
|
|
|
Please define long-named options that are equivalent to the
|
|
|
|
single-letter Unix-style options. We hope to make GNU more user
|
|
|
|
friendly this way. This is easy to do with the GNU function
|
|
|
|
@code{getopt_long}.
|
|
|
|
|
|
|
|
It is usually a good idea for file names given as ordinary arguments
|
|
|
|
to be input files only; any output files would be specified using
|
|
|
|
options (preferably @samp{-o}). Even if you allow an output file name
|
|
|
|
as an ordinary argument for compatibility, try to provide a suitable
|
|
|
|
option as well. This will lead to more consistency among GNU
|
|
|
|
utilities, so that there are fewer idiosyncracies for users to
|
|
|
|
remember.
|
|
|
|
|
|
|
|
Programs should support an option @samp{--version} which prints the
|
|
|
|
program's version number, and an option @samp{--help} which prints
|
|
|
|
option usage information.
|
|
|
|
|
|
|
|
|
|
|
|
@node Documentation
|
|
|
|
@chapter Documenting Programs
|
|
|
|
|
|
|
|
Please use Texinfo for documenting GNU programs. See the Texinfo
|
|
|
|
manual, either the hardcopy or the version in the GNU Emacs Info
|
|
|
|
sub-system (@kbd{C-h i}).
|
|
|
|
|
|
|
|
See existing GNU texinfo files (e.g. those under the @file{man/}
|
|
|
|
directory in the GNU Emacs Distribution) for examples.
|
|
|
|
|
|
|
|
The title page of the manual should state the version of the program
|
|
|
|
which the manual applies to. The Top node of the manual should also
|
|
|
|
contain this information. If the manual is changing more frequently
|
|
|
|
than or independent of the program, also state a version number for
|
|
|
|
the manual in both of these places.
|
|
|
|
|
|
|
|
The manual should document all command-line arguments and all
|
|
|
|
commands. It should give examples of their use. But don't organize
|
|
|
|
the manual as a list of features. Instead, organize it by the
|
|
|
|
concepts a user will have before reaching that point in the manual.
|
|
|
|
Address the goals that a user will have in mind, and explain how to
|
|
|
|
accomplish them.
|
|
|
|
|
|
|
|
|
|
|
|
@node Releases
|
|
|
|
@chapter Making Releases
|
|
|
|
|
|
|
|
Package the distribution of Foo version 69.96 in a tar file named
|
|
|
|
@file{foo-69.96.tar}. It should unpack into a subdirectory named
|
|
|
|
@file{foo-69.96}.
|
|
|
|
|
|
|
|
Building and installing the program should never modify any of the files
|
|
|
|
contained in the distribution. This means that all the files that form
|
|
|
|
part of the program in any way must be classified into @dfn{source
|
|
|
|
files} and @dfn{non-source files}. Source files are written by humans
|
|
|
|
and never changed automatically; non-source files are produced from
|
|
|
|
source files by programs under the control of the Makefile.
|
|
|
|
|
|
|
|
Naturally, all the source files must be in the distribution. It is okay
|
|
|
|
to include non-source files in the distribution, provided they are
|
|
|
|
up-to-date and machine-independent, so that building the distribution
|
|
|
|
normally will never modify them. We commonly included non-source files
|
|
|
|
produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid
|
|
|
|
unnecessary dependencies between our distributions, so that users can
|
|
|
|
install whichever packages they want to install.
|
|
|
|
|
|
|
|
Non-source files that might actually be modified by building and
|
|
|
|
installing the program should @strong{never} be included in the
|
|
|
|
distribution. So if you do distribute non-source files, always make
|
|
|
|
sure they are up to date when you make a new distribution.
|
|
|
|
|
|
|
|
Make sure that no file name in the distribution is no more than 14
|
|
|
|
characters long. Nowadays, there are systems that adhere to a foolish
|
|
|
|
interpretation of the POSIX standard which holds that they should refuse
|
|
|
|
to open a longer name, rather than truncating as they did in the past.
|
|
|
|
|
|
|
|
Try to make sure that all the file names will be unique on MS-DOG. A
|
|
|
|
name on MS-DOG consists of up to 8 characters, optionally followed by a
|
|
|
|
period and up to three characters. MS-DOG will truncate extra
|
|
|
|
characters both before and after the period. Thus,
|
|
|
|
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
|
|
|
|
are truncated to @file{foobarhac.c} and @file{foobarhac.o}, which are
|
|
|
|
distinct.
|
|
|
|
|
|
|
|
Include in your distribution a copy of the @file{texinfo.tex} you used
|
|
|
|
to test print any @file{*.texinfo} files.
|
|
|
|
|
1992-05-08 17:32:25 +02:00
|
|
|
Likewise, if your program uses small GNU software packages like regex,
|
|
|
|
getopt, obstack, or termcap, include them in the distribution file.
|
|
|
|
Leaving them out would make the distribution file a little smaller at
|
|
|
|
the expense of possible inconvenience to a user who doesn't know what
|
|
|
|
other files to get.
|
1992-04-25 00:21:27 +02:00
|
|
|
@bye
|