3 |
@setfilename standards.info |
@setfilename standards.info |
4 |
@settitle GNU Coding Standards |
@settitle GNU Coding Standards |
5 |
@c This date is automagically updated when you save this file: |
@c This date is automagically updated when you save this file: |
6 |
@set lastupdate October 19, 2001 |
@set lastupdate November 23, 2002 |
7 |
@c %**end of header |
@c %**end of header |
8 |
|
|
9 |
@ifinfo |
@dircategory GNU organization |
10 |
@format |
@direntry |
|
START-INFO-DIR-ENTRY |
|
11 |
* Standards: (standards). GNU coding standards. |
* Standards: (standards). GNU coding standards. |
12 |
END-INFO-DIR-ENTRY |
@end direntry |
|
@end format |
|
|
@end ifinfo |
|
13 |
|
|
14 |
@c @setchapternewpage odd |
@c @setchapternewpage odd |
15 |
@setchapternewpage off |
@setchapternewpage off |
29 |
@set CHAPTER node |
@set CHAPTER node |
30 |
@end ifinfo |
@end ifinfo |
31 |
|
|
32 |
@ifinfo |
@copying |
33 |
GNU Coding Standards |
The GNU coding standards, last updated @value{lastupdate}. |
34 |
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. |
|
35 |
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, |
36 |
|
2001, 2002 Free Software Foundation, Inc. |
37 |
|
|
38 |
Permission is granted to copy, distribute and/or modify this document |
Permission is granted to copy, distribute and/or modify this document |
39 |
under the terms of the GNU Free Documentation License, Version 1.1 |
under the terms of the GNU Free Documentation License, Version 1.1 |
42 |
Front-Cover Texts, and with no Back-Cover Texts. |
Front-Cover Texts, and with no Back-Cover Texts. |
43 |
A copy of the license is included in the section entitled ``GNU |
A copy of the license is included in the section entitled ``GNU |
44 |
Free Documentation License''. |
Free Documentation License''. |
45 |
@end ifinfo |
@end copying |
46 |
|
|
47 |
@titlepage |
@titlepage |
48 |
@title GNU Coding Standards |
@title GNU Coding Standards |
49 |
@author Richard Stallman, et al. |
@author Richard Stallman, et al. |
50 |
@author last updated @value{lastupdate} |
@author last updated @value{lastupdate} |
51 |
@page |
@page |
|
|
|
52 |
@vskip 0pt plus 1filll |
@vskip 0pt plus 1filll |
53 |
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. |
@insertcopying |
|
|
|
|
Permission is granted to copy, distribute and/or modify this document |
|
|
under the terms of the GNU Free Documentation License, Version 1.1 |
|
|
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''. |
|
54 |
@end titlepage |
@end titlepage |
55 |
|
|
56 |
@ifinfo |
@contents |
57 |
|
|
58 |
|
@ifnottex |
59 |
@node Top, Preface, (dir), (dir) |
@node Top, Preface, (dir), (dir) |
60 |
@top Version |
@top Version |
61 |
|
|
62 |
Last updated @value{lastupdate}. |
@insertcopying |
63 |
@end ifinfo |
@end ifnottex |
64 |
|
|
65 |
@menu |
@menu |
66 |
* Preface:: About the GNU Coding Standards |
* Preface:: About the GNU Coding Standards |
93 |
@cindex where to obtain @code{standards.texi} |
@cindex where to obtain @code{standards.texi} |
94 |
@cindex downloading this manual |
@cindex downloading this manual |
95 |
If you did not obtain this file directly from the GNU project and |
If you did not obtain this file directly from the GNU project and |
96 |
recently, please check for a newer version. You can ftp the GNU |
recently, please check for a newer version. You can get the GNU |
97 |
Coding Standards from any GNU FTP host in the directory |
Coding Standards from the GNU World Wide Web server host in several |
98 |
@file{/pub/gnu/standards/}. The GNU Coding Standards are available |
different formats: @uref{http://www.gnu.org/prep/standards.text}, |
99 |
there in several different formats: @file{standards.text}, |
@uref{http://www.gnu.org/prep/standards.info}, and |
100 |
@file{standards.info}, and @file{standards.dvi}, as well as the |
@uref{http://www.gnu.org/prep/standards.dvi}, as well as the |
101 |
Texinfo ``source'' which is divided in two files: |
Texinfo ``source'' which is divided in two files: |
102 |
@file{standards.texi} and @file{make-stds.texi}. The GNU Coding |
@uref{http://www.gnu.org/prep/standards.texi} and |
103 |
Standards are also available on the GNU World Wide Web server: |
@uref{http://www.gnu.org/prep/make-stds.texi}. The GNU Coding |
104 |
|
Standards are also available in HTML format starting at |
105 |
@uref{http://www.gnu.org/prep/standards_toc.html}. |
@uref{http://www.gnu.org/prep/standards_toc.html}. |
106 |
|
|
107 |
Corrections or suggestions for this document should be sent to |
Corrections or suggestions for this document should be sent to |
122 |
to document them as much as possible. That way, your program will be |
to document them as much as possible. That way, your program will be |
123 |
more maintainable by others. |
more maintainable by others. |
124 |
|
|
125 |
|
The GNU Hello program serves as an example of how to follow the GNU |
126 |
|
coding standards for a trivial program which prints @samp{Hello, |
127 |
|
world!}. @uref{http://www.gnu.org/software/hello/hello.html}. |
128 |
|
|
129 |
@node Legal Issues |
@node Legal Issues |
130 |
@chapter Keeping Free Software Free |
@chapter Keeping Free Software Free |
131 |
@cindex legal aspects |
@cindex legal aspects |
676 |
@end example |
@end example |
677 |
|
|
678 |
@noindent |
@noindent |
679 |
If you want to mention the column number, use this format: |
If you want to mention the column number, use one of these formats: |
680 |
|
|
681 |
@example |
@example |
682 |
@var{source-file-name}:@var{lineno}:@var{column}: @var{message} |
@var{source-file-name}:@var{lineno}:@var{column}: @var{message} |
683 |
|
@var{source-file-name}:@var{lineno}.@var{column}: @var{message} |
684 |
|
|
685 |
@end example |
@end example |
686 |
|
|
687 |
@noindent |
@noindent |
691 |
numbers assuming that space and all ASCII printing characters have |
numbers assuming that space and all ASCII printing characters have |
692 |
equal width, and assuming tab stops every 8 columns. |
equal width, and assuming tab stops every 8 columns. |
693 |
|
|
694 |
|
The error message can also give both the starting and ending positions |
695 |
|
of the erroneous text. There are several formats so that you can |
696 |
|
avoid redundant information such as a duplicate line number. |
697 |
|
Here are the possible formats: |
698 |
|
|
699 |
|
@example |
700 |
|
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{lineno-2}.@var{column-2}: @var{message} |
701 |
|
@var{source-file-name}:@var{lineno-1}.@var{column-1}-@var{column-2}: @var{message} |
702 |
|
@var{source-file-name}:@var{lineno-1}-@var{lineno-2}: @var{message} |
703 |
|
@end example |
704 |
|
|
705 |
|
@noindent |
706 |
|
When an error is spread over several files, you can use this format: |
707 |
|
|
708 |
|
@example |
709 |
|
@var{file-1}:@var{lineno-1}.@var{column-1}-@var{file-2}:@var{lineno-2}.@var{column-2}: @var{message} |
710 |
|
@end example |
711 |
|
|
712 |
Error messages from other noninteractive programs should look like this: |
Error messages from other noninteractive programs should look like this: |
713 |
|
|
714 |
@example |
@example |
1590 |
@item no-sort |
@item no-sort |
1591 |
@samp{-p} in @code{nm}. |
@samp{-p} in @code{nm}. |
1592 |
|
|
1593 |
|
@item no-splash |
1594 |
|
Don't print a startup splash screen. |
1595 |
|
|
1596 |
@item no-split |
@item no-split |
1597 |
Used in @code{makeinfo}. |
Used in @code{makeinfo}. |
1598 |
|
|
3020 |
|
|
3021 |
The manual which discusses a program should certainly document all of |
The manual which discusses a program should certainly document all of |
3022 |
the program's command-line options and all of its commands. It should |
the program's command-line options and all of its commands. It should |
3023 |
give examples of their use. But don't organize the manual as a list of |
give examples of their use. But don't organize the manual as a list |
3024 |
features. Instead, organize it logically, by subtopics. Address the |
of features. Instead, organize it logically, by subtopics. Address |
3025 |
questions that a user will ask when thinking about the job that the |
the questions that a user will ask when thinking about the job that |
3026 |
program does. |
the program does. Don't just tell the reader what each feature can |
3027 |
|
do---say what jobs it is good for, and show how to use it for those |
3028 |
|
jobs. Explain what is recommended usage, and what kinds of usage |
3029 |
|
users should avoid. |
3030 |
|
|
3031 |
In general, a GNU manual should serve both as tutorial and reference. |
In general, a GNU manual should serve both as tutorial and reference. |
3032 |
It should be set up for convenient access to each topic through Info, |
It should be set up for convenient access to each topic through Info, |
3064 |
different from what we use in GNU manuals. |
different from what we use in GNU manuals. |
3065 |
|
|
3066 |
Please include an email address in the manual for where to report |
Please include an email address in the manual for where to report |
3067 |
bugs @emph{in the manual}. |
bugs @emph{in the text of the manual}. |
3068 |
|
|
3069 |
Please do not use the term ``pathname'' that is used in Unix |
Please do not use the term ``pathname'' that is used in Unix |
3070 |
documentation; use ``file name'' (two words) instead. We use the term |
documentation; use ``file name'' (two words) instead. We use the term |
3071 |
``path'' only for search paths, which are lists of directory names. |
``path'' only for search paths, which are lists of directory names. |
3072 |
|
|
3073 |
Please do not use the term ``illegal'' to refer to erroneous input to a |
Please do not use the term ``illegal'' to refer to erroneous input to |
3074 |
computer program. Please use ``invalid'' for this, and reserve the term |
a computer program. Please use ``invalid'' for this, and reserve the |
3075 |
``illegal'' for activities punishable by law. |
term ``illegal'' for activities prohibited by law. |
3076 |
|
|
3077 |
@node Doc Strings and Manuals |
@node Doc Strings and Manuals |
3078 |
@section Doc Strings and Manuals |
@section Doc Strings and Manuals |
3509 |
@var{cpu}-@var{company}-@var{system} |
@var{cpu}-@var{company}-@var{system} |
3510 |
@end example |
@end example |
3511 |
|
|
3512 |
For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. |
For example, an Athlon-based GNU/Linux system might be |
3513 |
|
@samp{i686-pc-linux-gnu}. |
3514 |
|
|
3515 |
The @code{configure} script needs to be able to decode all plausible |
The @code{configure} script needs to be able to decode all plausible |
3516 |
alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} |
alternatives for how to describe a machine. Thus, |
3517 |
would be a valid alias. For many programs, @samp{vax-dec-ultrix} would |
@samp{athlon-pc-gnu/linux} would be a valid alias. |
3518 |
be an alias for @samp{vax-dec-bsd}, simply because the differences |
There is a shell script called |
3519 |
between Ultrix and @sc{bsd} are rarely noticeable, but a few programs |
@uref{ftp://ftp.gnu.org/gnu/config/config.sub, @file{config.sub}} |
3520 |
might need to distinguish them. |
that you can use |
|
@c Real 4.4BSD now runs on some Suns. |
|
|
|
|
|
There is a shell script called @file{config.sub} that you can use |
|
3521 |
as a subroutine to validate system types and canonicalize aliases. |
as a subroutine to validate system types and canonicalize aliases. |
3522 |
|
|
3523 |
|
The @code{configure} script should also take the option |
3524 |
|
@option{--build=@var{buildtype}}, which should be equivalent to a |
3525 |
|
plain @var{buildtype} argument. For example, @samp{configure |
3526 |
|
--build=i686-pc-linux-gnu} is equivalent to @samp{configure |
3527 |
|
i686-pc-linux-gnu}. When the build type is not specified by an option |
3528 |
|
or argument, the @code{configure} script should normally guess it |
3529 |
|
using the shell script |
3530 |
|
@uref{ftp://ftp.gnu.org/gnu/config/config.guess, @file{config.guess}}. |
3531 |
|
|
3532 |
@cindex optional features, configure-time |
@cindex optional features, configure-time |
3533 |
Other options are permitted to specify in more detail the software |
Other options are permitted to specify in more detail the software |
3534 |
or hardware present on the machine, and include or exclude optional |
or hardware present on the machine, and include or exclude optional |
3588 |
system as both the host and the target, thus producing a program which |
system as both the host and the target, thus producing a program which |
3589 |
works for the same type of machine that it runs on. |
works for the same type of machine that it runs on. |
3590 |
|
|
3591 |
|
To compile a program to run on a host type that differs from the build |
3592 |
|
type, use the configure option @option{--host=@var{hosttype}}, where |
3593 |
|
@var{hosttype} uses the same syntax as @var{buildtype}. The host type |
3594 |
|
normally defaults to the build type. |
3595 |
|
|
3596 |
To configure a cross-compiler, cross-assembler, or what have you, you |
To configure a cross-compiler, cross-assembler, or what have you, you |
3597 |
should specify a target different from the host, using the configure |
should specify a target different from the host, using the configure |
3598 |
option @samp{--target=@var{targettype}}. The syntax for |
option @samp{--target=@var{targettype}}. The syntax for |
3600 |
look like this: |
look like this: |
3601 |
|
|
3602 |
@example |
@example |
3603 |
./configure @var{hosttype} --target=@var{targettype} |
./configure --host=@var{hosttype} --target=@var{targettype} |
3604 |
@end example |
@end example |
3605 |
|
|
3606 |
|
The target type normally defaults to the host type. |
3607 |
Programs for which cross-operation is not meaningful need not accept the |
Programs for which cross-operation is not meaningful need not accept the |
3608 |
@samp{--target} option, because configuring an entire operating system for |
@samp{--target} option, because configuring an entire operating system for |
3609 |
cross-operation is not a meaningful operation. |
cross-operation is not a meaningful operation. |
3610 |
|
|
|
Bootstrapping a cross-compiler requires compiling it on a machine other |
|
|
than the host it will run on. Compilation packages accept a |
|
|
configuration option @samp{--build=@var{buildtype}} for specifying the |
|
|
configuration on which you will compile them, but the configure script |
|
|
should normally guess the build machine type (using |
|
|
@file{config.guess}), so this option is probably not necessary. The |
|
|
host and target types normally default from the build type, so in |
|
|
bootstrapping a cross-compiler you must specify them both explicitly. |
|
|
|
|
3611 |
Some programs have ways of configuring themselves automatically. If |
Some programs have ways of configuring themselves automatically. If |
3612 |
your program is set up to do this, your @code{configure} script can simply |
your program is set up to do this, your @code{configure} script can simply |
3613 |
ignore most of its arguments. |
ignore most of its arguments. |
3708 |
@cindex references to non-free material |
@cindex references to non-free material |
3709 |
|
|
3710 |
A GNU program should not recommend use of any non-free program. We |
A GNU program should not recommend use of any non-free program. We |
3711 |
can't stop some people from writing proprietary programs, or stop other |
can't stop some people from writing proprietary programs, or stop |
3712 |
people from using them. But we can and should avoid helping to |
other people from using them, but we can and should refuse to |
3713 |
advertise them to new customers. |
advertise them to new potential customers. Proprietary software is a |
3714 |
|
social and ethical problem, and the point of GNU is to solve that |
3715 |
Sometimes it is important to mention how to build your package on top of |
problem. |
3716 |
some non-free operating system or other non-free base package. In such |
|
3717 |
cases, please mention the name of the non-free package or system in the |
The GNU definition of free software is found in |
3718 |
briefest possible way. Don't include any references for where to find |
@url{http://www.gnu.org/philosophy/free-sw.html}, with a list of |
3719 |
more information about the proprietary program. The goal should be that |
important licenses and whether they qualify as free in |
3720 |
people already using the proprietary program will get the advice they |
@url{http://www.gnu.org/licenses/license-list.html}. The terms |
3721 |
need about how to use your free program, while people who don't already |
``free'' and ``non-free'', used in this document, refer to that |
3722 |
use the proprietary program will not see anything to encourage them to |
definition. If it is not clear whether a license qualifies as free |
3723 |
take an interest in it. |
under this definition, please ask the GNU Project by writing to |
3724 |
|
@email{licensing@@gnu.org}. We will answer, and if the license is an |
3725 |
Likewise, a GNU package should not refer the user to any non-free |
important one, we will add it to the list. |
3726 |
documentation for free software. The need for free documentation to go |
|
3727 |
with free software is now a major focus of the GNU project; to show that |
When a non-free program or system is well known, you can mention it in |
3728 |
we are serious about the need for free documentation, we must not |
passing---that is harmless, since users who might want to use it |
3729 |
undermine our position by recommending use of documentation that isn't |
probably already know about it. For instance, it is fine to explain |
3730 |
free. |
how to build your package on top of some widely used non-free |
3731 |
|
operating system, or how to use it together with some widely used |
3732 |
|
non-free program. |
3733 |
|
|
3734 |
|
However, you should give only the necessary information to help those |
3735 |
|
who already use the non-free program to use your program with |
3736 |
|
it---don't give, or refer to, any further information about the |
3737 |
|
proprietary program, and don't imply that the proprietary program |
3738 |
|
enhances your program, or that its existence is in any way a good |
3739 |
|
thing. The goal should be that people already using the proprietary |
3740 |
|
program will get the advice they need about how to use your free |
3741 |
|
program with it, while people who don't already use the proprietary |
3742 |
|
program will not see anything to lead them to take an interest in it. |
3743 |
|
|
3744 |
|
If a non-free program or system is obscure in your program's domain, |
3745 |
|
your program should not mention or support it at all, since doing so |
3746 |
|
would tend to popularize the non-free program more than it popularizes |
3747 |
|
your program. (You cannot hope to find many additional users among |
3748 |
|
the users of Foobar if the users of Foobar are few.) |
3749 |
|
|
3750 |
|
Sometimes a program is free software in itself but depends on a |
3751 |
|
non-free platform in order to run. For instance, many Java programs |
3752 |
|
depend on Sun's Java implementation, and won't run on the GNU Java |
3753 |
|
Compiler (which does not yet have all the features) or won't run with |
3754 |
|
the GNU Java libraries. To recommend that program is inherently to |
3755 |
|
recommend the non-free platform as well; if you should not do the |
3756 |
|
latter, then don't do the former. |
3757 |
|
|
3758 |
|
A GNU package should not refer the user to any non-free documentation |
3759 |
|
for free software. Free documentation that can be included in free |
3760 |
|
operating systems is essential for completing the GNU system, or any |
3761 |
|
free operating system, so it is a major focus of the GNU Project; to |
3762 |
|
recommend use of documentation that we are not allowed to use in GNU |
3763 |
|
would weaken the impetus for the community to produce documentation |
3764 |
|
that we can include. So GNU packages should never recommend non-free |
3765 |
|
documentation. |
3766 |
|
|
3767 |
|
By contrast, it is ok to refer to journal articles and textbooks in |
3768 |
|
the comments of a program for explanation of how it functions, even |
3769 |
|
though they be non-free. This is because we don't include such things |
3770 |
|
in the GNU system even if we are allowed to--they are outside the |
3771 |
|
scope of an operating system project. |
3772 |
|
|
3773 |
|
Referring to a web site that describes or recommends a non-free |
3774 |
|
program is in effect promoting that software, so please do not make |
3775 |
|
links (or mention by name) web sites that contain such material. This |
3776 |
|
policy is relevant particulary for the web pages for a GNU package. |
3777 |
|
|
3778 |
|
Following links from nearly any web site can lead to non-free |
3779 |
|
software; this is an inescapable aspect of the nature of the web, and |
3780 |
|
in itself is no objection to linking to a site. As long as the site |
3781 |
|
does not itself recommend a non-free program, there is no need be |
3782 |
|
concerned about the sites it links to for other reasons. |
3783 |
|
|
3784 |
|
Thus, for example, you should not make a link to AT&T's web site, |
3785 |
|
because that recommends AT&T's non-free software packages; you should |
3786 |
|
not make a link to a site that links to AT&T's site saying it is a |
3787 |
|
place to get a non-free program; but if a site you want to link to |
3788 |
|
refers to AT&T's web site in some other context (such as long-distance |
3789 |
|
telephone service), that is not a problem. |
3790 |
|
|
3791 |
@node Copying This Manual |
@node Copying This Manual |
3792 |
@appendix Copying This Manual |
@appendix Copying This Manual |
3801 |
@unnumbered Index |
@unnumbered Index |
3802 |
@printindex cp |
@printindex cp |
3803 |
|
|
|
@contents |
|
|
|
|
3804 |
@bye |
@bye |
3805 |
@c Local variables: |
|
3806 |
@c eval: (add-hook 'write-file-hooks 'time-stamp) |
Local variables: |
3807 |
@c time-stamp-start: "@set lastupdate " |
eval: (add-hook 'write-file-hooks 'time-stamp) |
3808 |
@c time-stamp-end: "$" |
time-stamp-start: "@set lastupdate " |
3809 |
@c time-stamp-format: "%:b %:d, %:y" |
time-stamp-end: "$" |
3810 |
@c compile-command: "make just-standards" |
time-stamp-format: "%:b %:d, %:y" |
3811 |
@c End: |
compile-command: "make just-standards" |
3812 |
|
End: |