GNU Coding Standards

Table of Contents
*****************

Version
1 About the GNU Coding Standards
2 Keeping Free Software Free
2.1 Referring to Proprietary Programs
2.2 Accepting Contributions
2.3 Trademarks
3 General Program Design
3.1 Which Languages to Use
3.2 Compatibility with Other Implementations
3.3 Using Non-standard Features
3.4 Standard C and Pre-Standard C
3.5 Conditional Compilation
4 Program Behavior for All Programs
4.1 Non-GNU Standards
4.2 Writing Robust Programs
4.3 Library Behavior
4.4 Formatting Error Messages
4.5 Standards for Interfaces Generally
4.6 Standards for Graphical Interfaces
4.7 Standards for Command Line Interfaces
4.7.1 `--version'
4.7.2 `--help'
4.8 Table of Long Options
4.9 OID Allocations
4.10 Memory Usage
4.11 File Usage
5 Making The Best Use of C
5.1 Formatting Your Source Code
5.2 Commenting Your Work
5.3 Clean Use of C Constructs
5.4 Naming Variables, Functions, and Files
5.5 Portability between System Types
5.6 Portability between CPUs
5.7 Calling System Functions
5.8 Internationalization
5.9 Character Set
5.10 Quote Characters
5.11 Mmap
6 Documenting Programs
6.1 GNU Manuals
6.2 Doc Strings and Manuals
6.3 Manual Structure Details
6.4 License for Manuals
6.5 Manual Credits
6.6 Printed Manuals
6.7 The NEWS File
6.8 Change Logs
6.8.1 Change Log Concepts
6.8.2 Style of Change Logs
6.8.3 Simple Changes
6.8.4 Conditional Changes
6.8.5 Indicating the Part Changed
6.9 Man Pages
6.10 Reading other Manuals
7 The Release Process
7.1 How Configuration Should Work
7.2 Makefile Conventions
7.2.1 General Conventions for Makefiles
7.2.2 Utilities in Makefiles
7.2.3 Variables for Specifying Commands
7.2.4 `DESTDIR': support for staged installs
7.2.5 Variables for Installation Directories
7.2.6 Standard Targets for Users
7.2.7 Install Command Categories
7.3 Making Releases
8 References to Non-Free Software and Documentation
Appendix A GNU Free Documentation License
Index

Version
*******

The GNU coding standards, last updated December 11, 2009.

Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled "GNU
Free Documentation License".

1 About the GNU Coding Standards
********************************

The GNU Coding Standards were written by Richard Stallman and other GNU
Project volunteers. Their purpose is to make the GNU system clean,
consistent, and easy to install. This document can also be read as a
guide to writing portable, robust and reliable programs. It focuses on
programs written in C, but many of the rules and principles are useful
even if you write in another programming language. The rules often
state reasons for writing in a certain way.

If you did not obtain this file directly from the GNU project and
recently, please check for a newer version. You can get the GNU Coding
Standards from the GNU web server in many different formats, including
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
`http://www.gnu.org/prep/standards/'.

If you are maintaining an official GNU package, in addition to this
document, please read and follow the GNU maintainer information (*note
Contents: (maintain)Top.).

If you want to receive diffs for every change to these GNU documents,
join the mailing list `gnustandards-commit@gnu.org', via the web
interface at
`http://lists.gnu.org/mailman/listinfo/gnustandards-commit'. Archives
are also available there.

Corrections or suggestions for this document should be sent to
<bug-standards@gnu.org>. If you make a suggestion, please include a
suggested new wording for it; our time is limited. We prefer a context
diff to the `standards.texi' or `make-stds.texi' files, but if you
don't have those files, please mail your suggestion anyway.

These standards cover the minimum of what is important when writing a
GNU package. Likely, the need for additional standards will come up.
Sometimes, you might suggest that such standards be added to this
document. If you think your standards would be generally useful, please
do suggest them.

You should also set standards for your package on many questions not
addressed or not firmly specified here. The most important point is to
be self-consistent--try to stick to the conventions you pick, and try
to document them as much as possible. That way, your program will be
more maintainable by others.

The GNU Hello program serves as an example of how to follow the GNU
coding standards for a trivial program.
`http://www.gnu.org/software/hello/hello.html'.

This release of the GNU Coding Standards was last updated December
11, 2009.

2 Keeping Free Software Free
****************************

This chapter discusses how you can make sure that GNU software avoids
legal difficulties, and other related issues.

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

2.2 Accepting Contributions
===========================

If the program you are working on is copyrighted by the Free Software
Foundation, then when someone else sends you a piece of code to add to
the program, we need legal papers to use it--just as we asked you to
sign papers initially. _Each_ person who makes a nontrivial
contribution 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, please 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 changes, we
need legal papers for that change.

This also applies to comments and documentation files. For copyright
law, comments and code are just text. Copyright applies to all kinds of
text, so we need legal papers for all kinds.

We know it is frustrating to ask for legal papers; 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!

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 someone sent you one implementation, but
you write a different implementation of the same idea, you don't need to
get papers.

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.

We have more detailed advice for maintainers of programs; if you have
reached the stage of actually maintaining a program for GNU (whether
released or not), please ask us for a copy. It is also available
online for your perusal: `http://www.gnu.org/prep/maintain/'.

2.3 Trademarks
==============

Please do not include any trademark acknowledgements in GNU software
packages or documentation.

Trademark acknowledgements are the statements that such-and-such is a
trademark of so-and-so. The GNU Project has no objection to the basic
idea of trademarks, but these acknowledgements feel like kowtowing, and
there is no legal requirement for them, so we don't use them.

What is legally required, as regards other people's trademarks, is to
avoid using them in ways which a reader might reasonably understand as
naming or labeling our own programs or activities. For example, since
"Objective C" is (or at least was) a trademark, we made sure to say
that we provide a "compiler for the Objective C language" rather than
an "Objective C compiler". The latter would have been meant as a
shorter way of saying the former, but it does not explicitly state the
relationship, so it could be misinterpreted as using "Objective C" as a
label for the compiler rather than for the language.

Please don't use "win" as an abbreviation for Microsoft Windows in
GNU software or documentation. In hacker terminology, calling
something a "win" is a form of praise. If you wish to praise Microsoft
Windows when speaking on your own, by all means do so, but not in GNU
software. Usually we write the name "Windows" in full, but when
brevity is very important (as in file names and sometimes symbol
names), we abbreviate it to "w". For instance, the files and functions
in Emacs that deal with Windows start with `w32'.

3 General Program Design
************************

This chapter discusses some of the issues you should take into account
when designing your program.

3.1 Which Languages to Use
==========================

When you want to use a language that gets compiled and runs at high
speed, the best language to use is C. Using another language 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. For example, if you write your program in C++, people will
have to install the GNU C++ compiler in order to compile your program.

C has one other advantage over C++ and other compiled languages: more
people know C, so more people will find it easy to read and modify the
program if it is written in C.

So in general it is much better to use C, rather than the comparable
alternatives.

But there are two exceptions to that conclusion:

* It is no problem to use another language to write a tool
specifically intended for use with that language. That is because
the only people who want to build the tool will be those who have
installed the other language anyway.

* If an application is of interest only to a narrow part of the
community, then the question of which language it is written in
has less effect on other people, so you may as well please
yourself.

Many programs are designed to be extensible: they include an
interpreter for a language that is higher level than C. Often much of
the program is written in that language, too. The Emacs editor
pioneered this technique.

The standard extensibility interpreter for GNU software is Guile
(`http://www.gnu.org/software/guile/'), which implements the language
Scheme (an especially clean and simple dialect of Lisp). Guile also
includes bindings for GTK+/GNOME, making it practical to write modern
GUI functionality within Guile. We don't reject programs written in
other "scripting languages" such as Perl and Python, but using Guile is
very important for the overall consistency of the GNU system.

3.2 Compatibility with Other Implementations
============================================

With occasional exceptions, utility programs and libraries for GNU
should be upward compatible with those in Berkeley Unix, and upward
compatible with Standard C if Standard C specifies their behavior, and
upward compatible with POSIX if POSIX specifies their behavior.

When these standards conflict, it is useful to offer compatibility
modes for each of them.

Standard C and POSIX prohibit many kinds of extensions. Feel free
to make the extensions anyway, and include a `--ansi', `--posix', or
`--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. So you should try to redesign its
interface to make it upward compatible.

Many GNU programs suppress extensions that conflict with POSIX if the
environment variable `POSIXLY_CORRECT' is defined (even if it is
defined with a null value). Please make your program recognize this
variable if appropriate.

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 are welcome regardless of whether there
is any precedent for them.

3.3 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" `INLINE' and
define that as a macro to expand into either `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. Using GNU
extensions in such programs would make many users unhappy, so we don't
do that.

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 extremely troublesome in certain
cases.

3.4 Standard C and Pre-Standard C
=================================

1989 Standard C is widespread enough now that it is ok to use its
features in new programs. There is one exception: do not ever use the
"trigraph" feature of Standard C.

1999 Standard C is not widespread yet, so please do not require its
features in programs. It is ok to use its features if they are present.

However, it is easy to support pre-standard compilers in most
programs, so if you know how to do that, feel free. If a program you
are maintaining has such support, you should try to keep it working.

To support pre-standard C, instead of writing function definitions in
standard prototype form,

int
foo (int x, int y)
...

write the definition in pre-standard style like this,

int
foo (x, y)
int x, y;
...

and use a separate declaration to specify the argument prototype:

int foo (int, int);

You need such a declaration anyway, in a header file, to get the
benefit of prototypes in all the files where the function is called.
And once you have the declaration, you normally lose nothing by writing
the function definition in the pre-standard style.

This technique does not work for integer types narrower than `int'.
If you think of an argument as being of a type narrower than `int',
declare it as `int' instead.

There are a few special cases where this technique is hard to use.
For example, if a function argument needs to hold the system type
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
some machines; but you cannot use `int' instead, because `dev_t' is
wider than `int' on some machines. There is no type you can safely use
on all machines in a non-standard definition. The only way to support
non-standard C and pass such an argument is to check the width of
`dev_t' using Autoconf and choose the argument type accordingly. This
may not be worth the trouble.

In order to support pre-standard compilers that do not recognize
prototypes, you may want to use a preprocessor macro like this:

/* Declare the prototype for a general external function. */
#if defined (__STDC__) || defined (WINDOWSNT)
#define P_(proto) proto
#else
#define P_(proto) ()
#endif

3.5 Conditional Compilation
===========================

When supporting configuration options already known when building your
program we prefer using `if (... )' over conditional compilation, as in
the former case the compiler is able to perform more extensive checking
of all possible code paths.

For example, please write

if (HAS_FOO)
...
else
...

instead of:

#ifdef HAS_FOO
...
#else
...
#endif

A modern compiler such as GCC will generate exactly the same code in
both cases, and we have been using similar techniques with good success
in several projects. Of course, the former method assumes that
`HAS_FOO' is defined as either 0 or 1.

While this is not a silver bullet solving all portability problems,
and is not always appropriate, following this policy would have saved
GCC developers many hours, or even days, per year.

In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
which cannot be simply used in `if( ...)' statements, there is an easy
workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
in the following example:

#ifdef REVERSIBLE_CC_MODE
#define HAS_REVERSIBLE_CC_MODE 1
#else
#define HAS_REVERSIBLE_CC_MODE 0
#endif

4 Program Behavior for All Programs
***********************************

This chapter describes conventions for writing robust software. It
also describes general standards for error messages, the command line
interface, and how libraries should behave.

4.1 Non-GNU Standards
=====================

The GNU Project regards standards published by other organizations as
suggestions, not orders. We consider those standards, but we do not
"obey" them. In developing a GNU program, you should implement an
outside standard's specifications when that makes the GNU system better
overall in an objective sense. When it doesn't, you shouldn't.

In most cases, following published standards is convenient for
users--it means that their programs or scripts will work more portably.
For instance, GCC implements nearly all the features of Standard C as
specified by that standard. C program developers would be unhappy if
it did not. And GNU utilities mostly follow specifications of POSIX.2;
shell script writers and users would be unhappy if our programs were
incompatible.

But we do not follow either of these specifications rigidly, and
there are specific points on which we decided not to follow them, so as
to make the GNU system better for users.

For instance, Standard C says that nearly all extensions to C are
prohibited. How silly! GCC implements many extensions, some of which
were later adopted as part of the standard. If you want these
constructs to give an error message as "required" by the standard, you
must specify `--pedantic', which was implemented only so that we can
say "GCC is a 100% implementation of the standard," not because there
is any reason to actually use it.

POSIX.2 specifies that `df' and `du' must output sizes by default in
units of 512 bytes. What users want is units of 1k, so that is what we
do by default. If you want the ridiculous behavior "required" by
POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
was originally going to be named `POSIX_ME_HARDER').

GNU utilities also depart from the letter of the POSIX.2
specification when they support long-named command-line options, and
intermixing options with ordinary arguments. This minor
incompatibility with POSIX is never a problem in practice, and it is
very useful.

In particular, don't reject a new feature, or remove an old one,
merely because a standard says it is "forbidden" or "deprecated."

4.2 Writing Robust Programs
===========================