@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
-@set lastupdate June 7, 2009
+@set lastupdate June 1, 2012
@c %**end of header
@dircategory GNU organization
The GNU coding standards, last updated @value{lastupdate}.
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
-Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
+2011, 2012 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
@contents
@ifnottex
-@node Top, Preface, (dir), (dir)
-@top Version
+@node Top
+@top GNU Coding Standards
@insertcopying
@end ifnottex
even if you write in another programming language. The rules often
state reasons for writing in a certain way.
-This release of the GNU Coding Standards was last updated
-@value{lastupdate}.
-
@cindex where to obtain @code{standards.texi}
@cindex downloading this manual
If you did not obtain this file directly from the GNU project and
different formats, including the Texinfo source, PDF, HTML, DVI, plain
text, and more, at: @uref{http://www.gnu.org/prep/standards/}.
-Corrections or suggestions for this document should be sent to
-@email{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 @file{standards.texi} or @file{make-stds.texi} files, but if
-you don't have those files, please mail your suggestion anyway.
+If you are maintaining an official GNU package, in addition to this
+document, please read and follow the GNU maintainer information
+(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU
+Software}).
+
+@cindex @code{gnustandards-commit@@gnu.org} mailing list
+If you want to receive diffs for every change to these GNU documents,
+join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
+interface at
+@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
+Archives are also available there.
+
+@cindex @code{bug-standards@@gnu.org} email address
+@cindex Savannah repository for gnustandards
+@cindex gnustandards project repository
+Please send corrections or suggestions for this document to
+@email{bug-standards@@gnu.org}. If you make a suggestion, please
+include a suggested new wording for it, to help us consider the
+suggestion efficiently. We prefer a context diff to the Texinfo
+source, but if that's difficult for you, you can make a context diff
+for some other version of this document, or propose it in any way that
+makes it clear. The source repository for this document can be found
+at @url{http://savannah.gnu.org/projects/gnustandards}.
These standards cover the minimum of what is important when writing a
GNU package. Likely, the need for additional standards will come up.
coding standards for a trivial program.
@uref{http://www.gnu.org/software/hello/hello.html}.
+This release of the GNU Coding Standards was last updated
+@value{lastupdate}.
+
+
@node Legal Issues
@chapter Keeping Free Software Free
@cindex legal aspects
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
@section Accepting Contributions
@cindex legal papers
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: @uref{http://www.gnu.org/prep/maintain/}.
+We have more detailed advice for maintainers of GNU packages. If you
+have reached the stage of maintaining a GNU program (whether released
+or not), please take a look: @pxref{Legal Matters,,, maintain,
+Information for GNU Maintainers}.
+
@node Trademarks
@section Trademarks
GCC developers many hours, or even days, per year.
In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in
-GCC which cannot be simply used in @code{if( ...)} statements, there is
+GCC which cannot be simply used in @code{if (...)} statements, there is
an easy workaround. Simply introduce another macro
@code{HAS_REVERSIBLE_CC_MODE} as in the following example:
* User Interfaces:: Standards about interfaces generally.
* Graphical Interfaces:: Standards for graphical interfaces.
* Command-Line Interfaces:: Standards for command line interfaces.
+* Dynamic Plug-In Interfaces:: Standards for dynamic plug-in interfaces.
* Option Table:: Table of long options.
* OID Allocations:: Table of OID slots for GNU.
* Memory Usage:: When and how to care about memory needs.
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 @samp{--pedantic}, which was implemented only so that
-we can say ``GCC is a 100% implementation of the standard,'' not
+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 @samp{df} and @samp{du} must output sizes by
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.''
+merely because a standard says it is ``forbidden'' or ``deprecated''.
+
@node Semantics
@section Writing Robust Programs
are silently truncated''. This is not acceptable in a GNU utility.
@cindex @code{NUL} characters
+@findex libiconv
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 terminals or printers
-that can't handle those characters.
-Whenever possible, try to make programs work properly with
-sequences of bytes that represent multibyte characters, using encodings
-such as UTF-8 and others.
+for interface to certain types of terminals or printers that can't
+handle those characters. Whenever possible, try to make programs work
+properly with sequences of bytes that represent multibyte characters;
+UTF-8 is the most important.
@cindex error messages
-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 system call for an error return, unless you know you wish
+to ignore errors. Include the system error text (from @code{perror},
+@code{strerror}, 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.
@cindex @code{malloc} return value
@cindex memory allocation failure
avoid this problem by creating temporary files in this manner:
@example
-fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
+fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
@end example
@noindent
-or by using the @code{mkstemps} function from libiberty.
+or by using the @code{mkstemps} function from Gnulib
+(@pxref{mkstemps,,, gnulib, Gnulib}).
+
+In bash, use @code{set -C} (long name @code{noclobber}) to avoid this
+problem. In addition, the @code{mktemp} utility is a more general
+solution for creating temporary files from shell scripts
+(@pxref{mktemp invocation,,, coreutils, GNU Coreutils}).
-In bash, use @code{set -C} to avoid this problem.
@node Libraries
@section Library Behavior
Error messages from compilers should look like this:
@example
-@var{source-file-name}:@var{lineno}: @var{message}
+@var{sourcefile}:@var{lineno}: @var{message}
@end example
@noindent
If you want to mention the column number, use one of these formats:
@example
-@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
-@var{source-file-name}:@var{lineno}.@var{column}: @var{message}
+@var{sourcefile}:@var{lineno}:@var{column}: @var{message}
+@var{sourcefile}:@var{lineno}.@var{column}: @var{message}
@end example
@noindent
Line numbers should start from 1 at the beginning of the file, and
-column numbers should start from 1 at the beginning of the line. (Both
-of these conventions are chosen for compatibility.) Calculate column
-numbers assuming that space and all ASCII printing characters have
-equal width, and assuming tab stops every 8 columns.
+column numbers should start from 1 at the beginning of the line.
+(Both of these conventions are chosen for compatibility.) Calculate
+column numbers assuming that space and all ASCII printing characters
+have equal width, and assuming tab stops every 8 columns. For
+non-ASCII characters, Unicode character widths should be used when in
+a UTF-8 locale; GNU libc and GNU gnulib provide suitable
+@code{wcwidth} functions.
The error message can also give both the starting and ending positions
of the erroneous text. There are several formats so that you can
Here are the possible formats:
@example
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message}
-@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message}
+@var{sourcefile}:@var{line1}.@var{column1}-@var{line2}.@var{column2}: @var{message}
+@var{sourcefile}:@var{line1}.@var{column1}-@var{column2}: @var{message}
+@var{sourcefile}:@var{line1}-@var{line2}: @var{message}
@end example
@noindent
When an error is spread over several files, you can use this format:
@example
-@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message}
+@var{file1}:@var{line1}.@var{column1}-@var{file2}:@var{line2}.@var{column2}: @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}
+@var{program}:@var{sourcefile}:@var{lineno}: @var{message}
@end example
@noindent
If you want to mention the column number, use this format:
@example
-@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
+@var{program}:@var{sourcefile}:@var{lineno}:@var{column}: @var{message}
@end example
In an interactive program (one that is reading commands from a
@node Graphical Interfaces
@section Standards for Graphical Interfaces
@cindex graphical user interface
+@cindex interface styles
+@cindex user interface styles
-@cindex gtk+
+@cindex GTK+
When you write a program that provides a graphical user interface,
-please make it work with X Windows and the GTK+ toolkit unless the
-functionality specifically requires some alternative (for example,
-``displaying jpeg images while in console mode'').
+please make it work with the X Window System and the GTK+ toolkit
+unless the functionality specifically requires some alternative (for
+example, ``displaying jpeg images while in console mode'').
In addition, please provide a command-line interface to control the
functionality. (In many cases, the graphical user interface can be a
separate program which invokes the command-line program.) This is
so that the same jobs can be done from scripts.
-@cindex corba
-@cindex gnome
-Please also consider providing a CORBA interface (for use from GNOME), a
-library interface (for use from C), and perhaps a keyboard-driven
-console interface (for use by users from console mode). Once you are
-doing the work to provide the functionality and the graphical interface,
-these won't be much extra work.
+@cindex CORBA
+@cindex GNOME
+@cindex D-bus
+@cindex keyboard interface
+@cindex library interface
+Please also consider providing a D-bus interface for use from other
+running programs, such as within GNOME. (GNOME used to use CORBA
+for this, but that is being phased out.) In addition, consider
+providing a library interface (for use from C), and perhaps a
+keyboard-driven console interface (for use by users from console
+mode). Once you are doing the work to provide the functionality and
+the graphical interface, these won't be much extra work.
@node Command-Line Interfaces
each on a separate line.
Next should follow a line stating the license, preferably using one of
-abbrevations below, and a brief statement that the program is free
+abbreviations below, and a brief statement that the program is free
software, and that users are free to copy and change it. Also mention
that there is no warranty, to the extent permitted by law. See
recommended wording below.
@item LGPL
GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}.
-@item GPL/Guile
-GNU GPL with the exception for Guile; for example, GPLv3+/Guile means
-the GNU GPL version 3 or later, with the extra exception for Guile.
-
@item GPL/Ada
GNU GPL with the exception for Ada.
The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}.
@item RBSD
-The revised (3-clause) BSD, compatible with the GNU GPL,
+The revised (3-clause) BSD, compatible with the GNU GPL,@*
@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}.
@item X11
The simple non-copyleft license used for most versions of the X Window
-system, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
+System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}.
@item Zlib
The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}.
It is ok to mention other appropriate mailing lists and web pages.
+@node Dynamic Plug-In Interfaces
+@section Standards for Dynamic Plug-in Interfaces
+@cindex plug-ins
+@cindex dynamic plug-ins
+
+Another aspect of keeping free programs free is encouraging
+development of free plug-ins, and discouraging development of
+proprietary plug-ins. Many GNU programs will not have anything like
+plug-ins at all, but those that do should follow these
+practices.
+
+First, the general plug-in architecture design should closely tie the
+plug-in to the original code, such that the plug-in and the base
+program are parts of one extended program. For GCC, for example,
+plug-ins receive and modify GCC's internal data structures, and so
+clearly form an extended program with the base GCC.
+
+@vindex plugin_is_GPL_compatible
+Second, you should require plug-in developers to affirm that their
+plug-ins are released under an appropriate license. This should be
+enforced with a simple programmatic check. For GCC, again for
+example, a plug-in must define the global symbol
+@code{plugin_is_GPL_compatible}, thus asserting that the plug-in is
+released under a GPL-compatible license (@pxref{Plugins,, Plugins,
+gccint, GCC Internals}).
+
+By adding this check to your program you are not creating a new legal
+requirement. The GPL itself requires plug-ins to be free software,
+licensed compatibly. As long as you have followed the first rule above
+to keep plug-ins closely tied to your original program, the GPL and AGPL
+already require those plug-ins to be released under a compatible
+license. The symbol definition in the plug-in---or whatever equivalent
+works best in your program---makes it harder for anyone who might
+distribute proprietary plug-ins to legally defend themselves. If a case
+about this got to court, we can point to that symbol as evidence that
+the plug-in developer understood that the license had this requirement.
+
+
@node Option Table
@section Table of Long Options
@cindex long option names
If your program creates complicated data structures, just make them in
memory and give a fatal error if @code{malloc} returns zero.
+@pindex valgrind
+@cindex memory leak
+Memory analysis tools such as @command{valgrind} can be useful, but
+don't complicate a program merely to avoid their false alarms. For
+example, if memory is used until just before a process exits, don't
+free it simply to silence such a tool.
+
+
@node File Usage
@section File Usage
@cindex file usage
* System Functions:: Portability and ``standard'' library functions.
* Internationalization:: Techniques for internationalization.
* Character Set:: Use ASCII by default.
-* Quote Characters:: Use `...' in the C locale.
+* Quote Characters:: Use "..." or '...' in the C locale.
* Mmap:: How you can safely use @code{mmap}.
@end menu
@cindex open brace
@cindex braces, in C source
+@cindex function definitions, formatting
It is important to put the open-brace that starts the body of a C
function in column one, so that they will start a defun. Several
tools look for open-braces in column one to find the beginnings of C
@dots{}
@end example
+@cindex @code{struct} types, formatting
+@cindex @code{enum} types, formatting
+For @code{struct} and @code{enum} types, likewise put the braces in
+column one, unless the whole contents fits on one line:
+
+@example
+struct foo
+@{
+ int a, b;
+@}
+@exdent @r{or}
+struct foo @{ int a, b; @}
+@end example
+
The rest of this section gives our recommendations for other aspects of
C formatting style, which is also the default style of the @code{indent}
program in version 1.2 and newer. It corresponds to the options
number 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.
+the comment before it, because readers can see that for themselves.
There might be an exception when the comment is so long that the function
itself would be off the bottom of the screen.
If you want to do this, then do. The compiler should be your servant,
not your master.
+@pindex clang
+@pindex lint
+Don't make the program ugly just to placate static analysis tools such
+as @command{lint}, @command{clang}, and GCC with extra warnings
+options such as @option{-Wconversion} and @option{-Wundef}. These
+tools can help find bugs and unclear code, but they can also generate
+so many false alarms that it hurts readability to silence them with
+unnecessary casts, wrappers, and other complications. For example,
+please don't insert casts to @code{void} or calls to do-nothing
+functions merely to pacify a lint checker.
+
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
all its uses. This makes the program even cleaner.
Don't use local variables or parameters that shadow global identifiers.
+GCC's @samp{-Wshadow} option can detect this problem.
@cindex multiple variables in a line
Don't declare multiple variables in one declaration that spans lines.
fatal ("virtual memory exhausted");
@end example
-@pindex lint
-Don't make the program ugly to placate @code{lint}. Please don't insert any
-casts to @code{void}. Zero without a cast is perfectly fine as a null
-pointer constant, except when calling a varargs function.
+This example uses zero without a cast as a null pointer constant.
+This is perfectly fine, except that a cast is needed when calling a
+varargs function or when using @code{sizeof}.
@node Names
@section Naming Variables, Functions, and Files
programs. @code{doschk} also reports file names longer than 14
characters.
+
@node System Portability
@section Portability between System Types
@cindex portability, between system types
@end example
1989 Standard C requires this to work, and we know of only one
-counterexample: 64-bit programs on Microsoft Windows. We will
-leave it to those who want to port GNU programs to that environment
-to figure out how to do it.
+counterexample: 64-bit programs on Microsoft Windows. We will leave
+it to those who want to port GNU programs to that environment to
+figure out how to do it.
Predefined file-size types like @code{off_t} are an exception: they are
longer than @code{long} on many platforms, so code like the above won't
@}
@end example
-It used to be ok to not worry about the difference between pointers
-and integers when passing arguments to functions. However, on most
-modern 64-bit machines pointers are wider than @code{int}.
-Conversely, integer types like @code{long long int} and @code{off_t}
-are wider than pointers on most modern 32-bit machines. Hence it's
-often better nowadays to use prototypes to define functions whose
-argument types are not trivial.
-
-In particular, if functions accept varying argument counts or types
-they should be declared using prototypes containing @samp{...} and
-defined using @file{stdarg.h}. For an example of this, please see the
-@uref{http://www.gnu.org/software/gnulib/, Gnulib} error module, which
-declares and defines the following function:
-
-@example
-/* Print a message with `fprintf (stderr, FORMAT, ...)';
- if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
- If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
-
-void error (int status, int errnum, const char *format, ...);
-@end example
-
-A simple way to use the Gnulib error module is to obtain the two
-source files @file{error.c} and @file{error.h} from the Gnulib library
-source code repository at
-@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=gnulib.git}.
-Here's a sample use:
-
-@example
-#include "error.h"
-#include <errno.h>
-#include <stdio.h>
-
-char *program_name = "myprogram";
-
-FILE *
-xfopen (char const *name)
-@{
- FILE *fp = fopen (name, "r");
- if (! fp)
- error (1, errno, "cannot read %s", name);
- return fp;
-@}
-@end example
-
@cindex casting pointers to integers
Avoid casting pointers to integers if you can. Such casts greatly
reduce portability, and in most programs they are easy to avoid. In the
normal range of addresses you can get from @code{malloc} starts far away
from zero.
+
@node System Functions
@section Calling System Functions
+
+@cindex C library functions, and portability
+@cindex POSIX functions, and portability
@cindex library functions, and portability
@cindex portability, and library functions
-C implementations differ substantially. Standard C reduces but does
-not eliminate the incompatibilities; meanwhile, many GNU packages still
-support pre-standard compilers because this is not hard to do. This
-chapter gives recommendations for how to use the more-or-less standard C
-library functions to avoid unnecessary loss of portability.
-
-@itemize @bullet
-@item
-Don't use the return value of @code{sprintf}. It returns the number of
-characters written on some systems, but not on all systems.
-
-@item
-Be aware that @code{vfprintf} is not always available.
-
-@item
-@code{main} should be declared to return type @code{int}. It should
-terminate either by calling @code{exit} or by returning the integer
-status code; make sure it cannot ever return an undefined value.
-
-@cindex declaration for system functions
-@item
-Don't declare system functions explicitly.
-
-Almost any declaration for a system function is wrong on some system.
-To minimize conflicts, leave it to the system header files to declare
-system functions. If the headers don't declare a function, let it
-remain undeclared.
-
-While it may seem unclean to use a function without declaring it, in
-practice this works fine for most system library functions on the
-systems where this really happens; thus, the disadvantage is only
-theoretical. By contrast, actual declarations have frequently caused
-actual conflicts.
-
-@item
-If you must declare a system function, don't specify the argument types.
-Use an old-style declaration, not a Standard C prototype. The more you
-specify about the function, the more likely a conflict.
-
-@item
-In particular, don't unconditionally declare @code{malloc} or
-@code{realloc}.
-
-Most GNU programs use those functions just once, in functions
-conventionally named @code{xmalloc} and @code{xrealloc}. These
-functions call @code{malloc} and @code{realloc}, respectively, and
-check the results.
-
-Because @code{xmalloc} and @code{xrealloc} are defined in your program,
-you can declare them in other files without any risk of type conflict.
-
-On most systems, @code{int} is the same length as a pointer; thus, the
-calls to @code{malloc} and @code{realloc} work fine. For the few
-exceptional systems (mostly 64-bit machines), you can use
-@strong{conditionalized} declarations of @code{malloc} and
-@code{realloc}---or put these declarations in configuration files
-specific to those systems.
-
-@cindex string library functions
-@item
-The string functions require special treatment. Some Unix systems have
-a header file @file{string.h}; others have @file{strings.h}. Neither
-file name is portable. There are two things you can do: use Autoconf to
-figure out which file to include, or don't include either file.
-
-@item
-If you don't include either strings file, you can't get declarations for
-the string functions from the header file in the usual way.
-
-That causes less of a problem than you might think. The newer standard
-string functions should be avoided anyway because many systems still
-don't support them. The string functions you can use are these:
-
-@example
-strcpy strncpy strcat strncat
-strlen strcmp strncmp
-strchr strrchr
-@end example
-
-The copy and concatenate functions work fine without a declaration as
-long as you don't use their values. Using their values without a
-declaration fails on systems where the width of a pointer differs from
-the width of @code{int}, and perhaps in other cases. It is trivial to
-avoid using their values, so do that.
-
-The compare functions and @code{strlen} work fine without a declaration
-on most systems, possibly all the ones that GNU software runs on.
-You may find it necessary to declare them @strong{conditionally} on a
-few systems.
-
-The search functions must be declared to return @code{char *}. Luckily,
-there is no variation in the data type they return. But there is
-variation in their names. Some systems give these functions the names
-@code{index} and @code{rindex}; other systems use the names
-@code{strchr} and @code{strrchr}. Some systems support both pairs of
-names, but neither pair works on all systems.
-
-You should pick a single pair of names and use it throughout your
-program. (Nowadays, it is better to choose @code{strchr} and
-@code{strrchr} for new programs, since those are the standard
-names.) Declare both of those names as functions returning @code{char
-*}. On systems which don't support those names, define them as macros
-in terms of the other pair. For example, here is what to put at the
-beginning of your file (or in a header) if you want to use the names
-@code{strchr} and @code{strrchr} throughout:
-
-@example
-#ifndef HAVE_STRCHR
-#define strchr index
-#endif
-#ifndef HAVE_STRRCHR
-#define strrchr rindex
-#endif
+Historically, C implementations differed substantially, and many
+systems lacked a full implementation of ANSI/ISO C89. Nowadays,
+however, very few systems lack a C89 compiler and GNU C supports
+almost all of C99. Similarly, most systems implement POSIX.1-1993
+libraries and tools, and many have POSIX.1-2001.
+
+Hence, there is little reason to support old C or non-POSIX systems,
+and you may want to take advantage of C99 and POSIX-1.2001 to write
+clearer, more portable, or faster code. You should use standard
+interfaces where possible; but if GNU extensions make your program
+more maintainable, powerful, or otherwise better, don't hesitate to
+use them. In any case, don't make your own declaration of system
+functions; that's a recipe for conflict.
+
+Despite the standards, nearly every library function has some sort of
+portability issue on some system or another. Here are some examples:
+
+@table @code
+@item open
+Names with trailing @code{/}'s are mishandled on many platforms.
+
+@item printf
+@code{long double} may be unimplemented; floating values Infinity and
+NaN are often mishandled; output for large precisions may be
+incorrect.
+
+@item readlink
+May return @code{int} instead of @code{ssize_t}.
+
+@item scanf
+On Windows, @code{errno} is not set on failure.
+@end table
-char *strchr ();
-char *strrchr ();
-@end example
-@end itemize
+@cindex Gnulib
+@uref{http://www.gnu.org/software/gnulib/, Gnulib} is a big help in
+this regard. Gnulib provides implementations of standard interfaces
+on many of the systems that lack them, including portable
+implementations of enhanced GNU interfaces, thereby making their use
+portable, and of POSIX-1.2008 interfaces, some of which are missing
+even on up-to-date GNU systems.
+
+@findex xmalloc, in Gnulib
+@findex error messages, in Gnulib
+@findex data structures, in Gnulib
+Gnulib also provides many useful non-standard interfaces; for example,
+C implementations of standard data structures (hash tables, binary
+trees), error-checking type-safe wrappers for memory allocation
+functions (@code{xmalloc}, @code{xrealloc}), and output of error
+messages.
+
+Gnulib integrates with GNU Autoconf and Automake to remove much of the
+burden of writing portable code from the programmer: Gnulib makes your
+configure script automatically determine what features are missing and
+use the Gnulib code to supply the missing pieces.
+
+The Gnulib and Autoconf manuals have extensive sections on
+portability: @ref{Top,, Introduction, gnulib, Gnulib} and
+@pxref{Portable C and C++,,, autoconf, Autoconf}. Please consult them
+for many more details.
-Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
-macros defined in systems where the corresponding functions exist.
-One way to get them properly defined is to use Autoconf.
@node Internationalization
@section Internationalization
around each string that might need translation---like this:
@example
-printf (gettext ("Processing file `%s'..."));
+printf (gettext ("Processing file '%s'..."), file);
@end example
@noindent
This permits GNU gettext to replace the string @code{"Processing file
-`%s'..."} with a translated version.
+'%s'..."} with a translated version.
Once a program uses gettext, please make a point of writing calls to
@code{gettext} when you add new strings that call for translation.
the application domain. For example, if source code deals with the
French Revolutionary calendar, it is OK if its literal strings contain
accented characters in month names like ``Flor@'eal''. Also, it is OK
-to use non-ASCII characters to represent proper names of contributors in
-change logs (@pxref{Change Logs}).
+(but not required) to use non-ASCII characters to represent proper
+names of contributors in change logs (@pxref{Change Logs}).
-If you need to use non-ASCII characters, you should normally stick with
-one encoding, as one cannot in general mix encodings reliably.
+If you need to use non-ASCII characters, you should normally stick
+with one encoding, certainly within a single file. UTF-8 is likely to
+be the best choice.
@node Quote Characters
@cindex quote characters
@cindex locale-specific quote characters
@cindex left quote
+@cindex right quote
+@cindex opening quote
+@cindex single quote
+@cindex double quote
@cindex grave accent
+@set txicodequoteundirected
+@set txicodequotebacktick
-In the C locale, GNU programs should stick to plain ASCII for quotation
-characters in messages to users: preferably 0x60 (@samp{`}) for left
-quotes and 0x27 (@samp{'}) for right quotes. It is ok, but not
-required, to use locale-specific quotes in other locales.
+In the C locale, the output of GNU programs should stick to plain
+ASCII for quotation characters in messages to users: preferably 0x22
+(@samp{"}) or 0x27 (@samp{'}) for both opening and closing quotes.
+Although GNU programs traditionally used 0x60 (@samp{`}) for opening
+and 0x27 (@samp{'}) for closing quotes, nowadays quotes @samp{`like
+this'} are typically rendered asymmetrically, so quoting @samp{"like
+this"} or @samp{'like this'} typically looks better.
-The @uref{http://www.gnu.org/software/gnulib/, Gnulib} @code{quote} and
-@code{quotearg} modules provide a reasonably straightforward way to
-support locale-specific quote characters, as well as taking care of
-other issues, such as quoting a filename that itself contains a quote
-character. See the Gnulib documentation for usage details.
+It is ok, but not required, for GNU programs to generate
+locale-specific quotes in non-C locales. For example:
-In any case, the documentation for your program should clearly specify
-how it does quoting, if different than the preferred method of @samp{`}
-and @samp{'}. This is especially important if the output of your
-program is ever likely to be parsed by another program.
+@example
+printf (gettext ("Processing file '%s'..."), file);
+@end example
+
+@noindent
+Here, a French translation might cause @code{gettext} to return the
+string @code{"Traitement de fichier
+@guilsinglleft{}@tie{}%s@tie{}@guilsinglright{}..."}, yielding quotes
+more appropriate for a French locale.
-Quotation characters are a difficult area in the computing world at
-this time: there are no true left or right quote characters in Latin1;
-the @samp{`} character we use was standardized there as a grave
-accent. Moreover, Latin1 is still not universally usable.
+Sometimes a program may need to use opening and closing quotes
+directly. By convention, @code{gettext} translates the string
+@samp{"`"} to the opening quote and the string @samp{"'"} to the
+closing quote, and a program can use these translations. Generally,
+though, it is better to translate quote characters in the context of
+longer strings.
-Unicode contains the unambiguous quote characters required, and its
-common encoding UTF-8 is upward compatible with Latin1. However,
-Unicode and UTF-8 are not universally well-supported, either.
+If the output of your program is ever likely to be parsed by another
+program, it is good to provide an option that makes this parsing
+reliable. For example, you could escape special characters using
+conventions from the C language or the Bourne shell. See for example
+the option @option{--quoting-style} of GNU @code{ls}.
-This may change over the next few years, and then we will revisit
-this.
+@clear txicodequoteundirected
+@clear txicodequotebacktick
@node Mmap
The reason this precaution is needed is that the GNU kernel (the HURD)
provides a user-extensible file system, in which there can be many
-different kinds of ``ordinary files.'' Many of them support
+different kinds of ``ordinary files''. Many of them support
@code{mmap}, but some do not. It is important to make programs handle
all these kinds of files.
+
@node Documentation
@chapter Documenting Programs
@cindex documentation
@node Change Log Concepts
@subsection Change Log Concepts
+@cindex change set
+@cindex batch of changes
You can think of the change log as a conceptual ``undo list'' which
explains how earlier versions were different from the current version.
-People can see the current version; they don't need the change log
-to tell them what is in it. What they want from a change log is a
-clear explanation of how the earlier version differed.
+People can see the current version; they don't need the change log to
+tell them what is in it. What they want from a change log is a clear
+explanation of how the earlier version differed. Each @dfn{entry} in
+a change log describes either an individual change or the smallest
+batch of changes that belong together, also known as a @dfn{change
+set}.
The change log file is normally called @file{ChangeLog} and covers an
entire directory. Each directory can have its own change log, or a
-directory can use the change log of its parent directory--it's up to
+directory can use the change log of its parent directory---it's up to
you.
Another alternative is to record change log information with a version
to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
-There's no need to describe the full purpose of the changes or how they
-work together. If you think that a change calls for explanation, you're
-probably right. Please do explain it---but please put the explanation
-in comments in the code, where people will see it whenever they see the
-code. For example, ``New function'' is enough for the change log when
-you add a function, because there should be a comment before the
-function definition to explain what it does.
+There's no need to describe the full purpose of the changes or how
+they work together. However, sometimes it is useful to write one line
+to describe the overall purpose of a change log entry. If
+you think that a change calls for explanation, you're probably right.
+Please do explain it---but please put the full explanation in comments
+in the code, where people will see it whenever they see the code. For
+example, ``New function'' is enough for the change log when you add a
+function, because there should be a comment before the function
+definition to explain what it does.
In the past, we recommended not mentioning changes in non-software
-files (manuals, help files, etc.) in change logs. However, we've been
-advised that it is a good idea to include them, for the sake of
-copyright records.
-
-However, sometimes it is useful to write one line to describe the
-overall purpose of a batch of changes.
+files (manuals, help files, media files, etc.)@: in change logs.
+However, we've been advised that it is a good idea to include them,
+for the sake of copyright records.
The easiest way to add an entry to @file{ChangeLog} is with the Emacs
-command @kbd{M-x add-change-log-entry}. 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.
+command @kbd{M-x add-change-log-entry}. An individual change 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.
+
@node Style of Change Logs
@subsection Style of Change Logs
this is not a good idea, since searching for @code{jump-to-register} or
@code{insert-register} would not find that entry.
-Separate unrelated change log 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.
+Separate unrelated change log entries with blank lines. Don't put
+blank lines between individual changes of an entry. You can omit the
+file name and the asterisk when successive individual changes are in
+the same file.
Break long lists of function names by closing continued lines with
@samp{)}, rather than @samp{,}, and opening the continuation with
@example
* keyboard.c (menu_bar_items, tool_bar_items)
-(Fexecute_extended_command): Deal with `keymap' property.
+(Fexecute_extended_command): Deal with 'keymap' property.
@end example
When you install someone else's changes, put the contributor's name in
@cindex conditional changes, and change logs
@cindex change logs, conditional changes
-C programs often contain compile-time @code{#if} conditionals. Many
-changes are conditional; sometimes you add a new definition which is
-entirely contained in a conditional. It is very useful to indicate in
-the change log the conditions for which the change applies.
+Source files can often contain code that is conditional to build-time
+or static conditions. For example, C programs can contain
+compile-time @code{#if} conditionals; programs implemented in
+interpreted languages can contain module imports of function
+definitions that are only performed for certain versions of the
+interpreter; and Automake @file{Makefile.am} files can contain
+variable definitions or target declarations that are only to be
+considered if a configure-time Automake conditional is true.
+
+Many changes are conditional as well: sometimes you add a new variable,
+or function, or even a new program or library, which is entirely
+dependent on a build-time condition. It is useful to indicate
+in the change log the conditions for which a change applies.
-Our convention for indicating conditional changes is to use square
-brackets around the name of the condition.
+Our convention for indicating conditional changes is to use
+@emph{square brackets around the name of the condition}.
-Here is a simple example, describing a change which is conditional but
-does not have a function or entity name associated with it:
+Conditional changes can happen in numerous scenarios and with many
+variations, so here are some examples to help clarify. This first
+example describes changes in C, Perl, and Python files which are
+conditional but do not have an associated function or entity name:
@example
-* xterm.c [SOLARIS2]: Include string.h.
+* xterm.c [SOLARIS2]: Include <string.h>.
+* FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module.
+* framework.py [sys.version_info < (2, 6)]: Make "with" statement
+ available by importing it from __future__,
+ to support also python 2.5.
@end example
-Here is an entry describing a new definition which is entirely
-conditional. This new definition for the macro @code{FRAME_WINDOW_P} is
-used only when @code{HAVE_X_WINDOWS} is defined:
+Our other examples will for simplicity be limited to C, as the minor
+changes necessary to adapt them to other languages should be
+self-evident.
+
+Next, here is an entry describing a new definition which is entirely
+conditional: the C macro @code{FRAME_WINDOW_P} is defined (and used)
+only when the macro @code{HAVE_X_WINDOWS} is defined:
@example
* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
@end example
-Here is an entry for a change within the function @code{init_display},
-whose definition as a whole is unconditional, but the changes themselves
-are contained in a @samp{#ifdef HAVE_LIBNCURSES} conditional:
+Next, an entry for a change within the function @code{init_display},
+whose definition as a whole is unconditional, but the changes
+themselves are contained in a @samp{#ifdef HAVE_LIBNCURSES}
+conditional:
@example
* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
@end example
-Here is an entry for a change that takes affect only when
+Finally, here is an entry for a change that takes effect only when
a certain macro is @emph{not} defined:
@example
-(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+* host.c (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
@end example
+
@node Indicating the Part Changed
@subsection Indicating the Part Changed
CC=gcc ./configure
@end example
as it helps to recreate the same configuration later with
-@file{config.status}.
+@file{config.status}. However, both methods should be supported.
@end table
All @code{configure} scripts should accept all of the ``detail''
@file{COPYING}. If the GNU LGPL is used, it should be in a file called
@file{COPYING.LESSER}.
-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 include non-source files
-produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
+Naturally, all the source files must be in the distribution. It is
+okay to include non-source files in the distribution along with the
+source files they are generated from, provided they are up-to-date
+with the source they are made from, and machine-independent, so that
+normal building of the distribution will never modify them. We
+commonly include non-source files produced by Autoconf, Automake,
+Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
unnecessary dependencies between our distributions, so that users can
install whichever packages they want to install.
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 the directory into which the distribution unpacks (as
-well as any subdirectories) are all world-writable (octal mode 777).
-This is so that old versions of @code{tar} which preserve the
-ownership and permissions of the files from the tar archive will be
-able to extract all the files even if the user is unprivileged.
-
-Make sure that all the files in the distribution are world-readable.
+Make sure that all the files in the distribution are world-readable, and
+that directories are world-readable and world-searchable (octal mode 755).
+We used to recommend that all directories in the distribution also be
+world-writable (octal mode 777), because ancient versions of @code{tar}
+would otherwise not cope when extracting the archive as an unprivileged
+user. That can easily lead to security issues when creating the archive,
+however, so now we recommend against that.
Don't include any symbolic links in the distribution itself. If the tar
file contains symbolic links, then people cannot even unpack it on
By contrast, it is ok to refer to journal articles and textbooks in
the comments of a program for explanation of how it functions, even
though they are non-free. This is because we don't include such
-things in the GNU system even they are free---they are outside the
+things in the GNU system even if they are free---they are outside the
scope of what a software distribution needs to include.
Referring to a web site that describes or recommends a non-free
-program is promoting that program, so please do not make links (or
+program is promoting that program, so please do not make links to (or
mention by name) web sites that contain such material. This policy is
relevant particularly for the web pages for a GNU package.
time-stamp-start: "@set lastupdate "
time-stamp-end: "$"
time-stamp-format: "%:b %:d, %:y"
-compile-command: "make just-standards"
+compile-command: "cd work.s && make"
End:
projects / gnulib.git / blobdiff