* standards.texi, make-stds.texi: Update to FSF version of May 13.
From-SVN: r33977
This commit is contained in:
parent
f65741dd0d
commit
d002ededd6
|
@ -1,3 +1,7 @@
|
||||||
|
2000-05-18 Martin von Loewis <loewis@informatik.hu-berlin.de>
|
||||||
|
|
||||||
|
* standards.texi, make-stds.texi: Update to FSF version of May 13.
|
||||||
|
|
||||||
Mon Nov 23 16:46:10 1998 Kaveh R. Ghazi <ghazi@caip.rutgers.edu>
|
Mon Nov 23 16:46:10 1998 Kaveh R. Ghazi <ghazi@caip.rutgers.edu>
|
||||||
|
|
||||||
* configure.in: Use AC_PREREQ(2.12.1).
|
* configure.in: Use AC_PREREQ(2.12.1).
|
||||||
|
|
|
@ -21,6 +21,8 @@ chapter
|
||||||
@end ifclear
|
@end ifclear
|
||||||
@end iftex
|
@end iftex
|
||||||
describes conventions for writing the Makefiles for GNU programs.
|
describes conventions for writing the Makefiles for GNU programs.
|
||||||
|
Using Automake will help you write a Makefile that follows these
|
||||||
|
conventions.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Makefile Basics:: General Conventions for Makefiles
|
* Makefile Basics:: General Conventions for Makefiles
|
||||||
|
@ -280,8 +282,8 @@ installed.
|
||||||
Installation directories should always be named by variables, so it is
|
Installation directories should always be named by variables, so it is
|
||||||
easy to install in a nonstandard place. The standard names for these
|
easy to install in a nonstandard place. The standard names for these
|
||||||
variables are described below. They are based on a standard filesystem
|
variables are described below. They are based on a standard filesystem
|
||||||
layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
|
layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
|
||||||
other modern operating systems.
|
and other modern operating systems.
|
||||||
|
|
||||||
These two variables set the root for the installation. All the other
|
These two variables set the root for the installation. All the other
|
||||||
installation directories should be subdirectories of one of these two,
|
installation directories should be subdirectories of one of these two,
|
||||||
|
|
|
@ -3,7 +3,7 @@
|
||||||
@setfilename standards.info
|
@setfilename standards.info
|
||||||
@settitle GNU Coding Standards
|
@settitle GNU Coding Standards
|
||||||
@c This date is automagically updated when you save this file:
|
@c This date is automagically updated when you save this file:
|
||||||
@set lastupdate March 13, 1998
|
@set lastupdate May 13, 2000
|
||||||
@c %**end of header
|
@c %**end of header
|
||||||
|
|
||||||
@ifinfo
|
@ifinfo
|
||||||
|
@ -28,7 +28,7 @@ END-INFO-DIR-ENTRY
|
||||||
|
|
||||||
@ifinfo
|
@ifinfo
|
||||||
GNU Coding Standards
|
GNU Coding Standards
|
||||||
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
|
Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
|
||||||
|
|
||||||
Permission is granted to make and distribute verbatim copies of
|
Permission is granted to make and distribute verbatim copies of
|
||||||
this manual provided the copyright notice and this permission notice
|
this manual provided the copyright notice and this permission notice
|
||||||
|
@ -85,12 +85,13 @@ Last updated @value{lastupdate}.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Preface:: About the GNU Coding Standards
|
* Preface:: About the GNU Coding Standards
|
||||||
* Intellectual Property:: Keeping Free Software Free
|
* Legal Issues:: Keeping Free Software Free
|
||||||
* Design Advice:: General Program Design
|
* Design Advice:: General Program Design
|
||||||
* Program Behavior:: Program Behavior for All Programs
|
* Program Behavior:: Program Behavior for All Programs
|
||||||
* Writing C:: Making The Best Use of C
|
* Writing C:: Making The Best Use of C
|
||||||
* Documentation:: Documenting Programs
|
* Documentation:: Documenting Programs
|
||||||
* Managing Releases:: The Release Process
|
* Managing Releases:: The Release Process
|
||||||
|
* References:: References to Non-Free Software or Documentation
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@node Preface
|
@node Preface
|
||||||
|
@ -113,15 +114,16 @@ you don't have those files, please mail your suggestion anyway.
|
||||||
This release of the GNU Coding Standards was last updated
|
This release of the GNU Coding Standards was last updated
|
||||||
@value{lastupdate}.
|
@value{lastupdate}.
|
||||||
|
|
||||||
@node Intellectual Property
|
@node Legal Issues
|
||||||
@chapter Keeping Free Software Free
|
@chapter Keeping Free Software Free
|
||||||
|
|
||||||
This @value{CHAPTER} discusses how you can make sure that GNU software
|
This @value{CHAPTER} discusses how you can make sure that GNU software
|
||||||
remains unencumbered.
|
avoids legal difficulties, and other related issues.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Reading Non-Free Code:: Referring to Proprietary Programs
|
* Reading Non-Free Code:: Referring to Proprietary Programs
|
||||||
* Contributions:: Accepting Contributions
|
* Contributions:: Accepting Contributions
|
||||||
|
* Trademarks:: How We Deal with Trademark Issues
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@node Reading Non-Free Code
|
@node Reading Non-Free Code
|
||||||
|
@ -157,15 +159,15 @@ Or turn some parts of the program into independently usable libraries.
|
||||||
Or use a simple garbage collector instead of tracking precisely when
|
Or use a simple garbage collector instead of tracking precisely when
|
||||||
to free memory, or use a new GNU facility such as obstacks.
|
to free memory, or use a new GNU facility such as obstacks.
|
||||||
|
|
||||||
|
|
||||||
@node Contributions
|
@node Contributions
|
||||||
@section Accepting Contributions
|
@section Accepting Contributions
|
||||||
|
|
||||||
If someone else sends you a piece of code to add to the program you are
|
If the program you are working on is copyrighted by the Free Software
|
||||||
working on, we need legal papers to use it---the same sort of legal
|
Foundation, then when someone else sends you a piece of code to add to
|
||||||
papers we will need to get from you. @emph{Each} significant
|
the program, we need legal papers to use it---just as we asked you to
|
||||||
contributor to a program must sign some sort of legal papers in order
|
sign papers initially. @emph{Each} person who makes a nontrivial
|
||||||
for us to have clear title to the program. The main author alone is not
|
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.
|
enough.
|
||||||
|
|
||||||
So, before adding in any contributions from other people, please tell
|
So, before adding in any contributions from other people, please tell
|
||||||
|
@ -181,16 +183,17 @@ This also applies to comments and documentation files. For copyright
|
||||||
law, comments and code are just text. Copyright applies to all kinds of
|
law, comments and code are just text. Copyright applies to all kinds of
|
||||||
text, so we need legal papers for all kinds.
|
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
|
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
|
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
|
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
|
which you use. For example, if someone send you one implementation, but
|
||||||
problem, you don't need to get papers.
|
you write a different implementation of the same idea, you don't need to
|
||||||
|
get papers.
|
||||||
We 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
|
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
|
contributor. We could be very embarrassed in court some day as a
|
||||||
|
@ -200,39 +203,113 @@ We have more detailed advice for maintainers of programs; if you have
|
||||||
reached the stage of actually maintaining a program for GNU (whether
|
reached the stage of actually maintaining a program for GNU (whether
|
||||||
released or not), please ask us for a copy.
|
released or not), please ask us for a copy.
|
||||||
|
|
||||||
|
@node Trademarks
|
||||||
|
@section 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, so
|
||||||
|
we don't use them. There is no legal requirement for them.
|
||||||
|
|
||||||
|
What is legally required, as regards other people's trademarks, is to
|
||||||
|
avoid using them in ways which a reader might read 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 is meant to be short for 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.
|
||||||
|
|
||||||
@node Design Advice
|
@node Design Advice
|
||||||
@chapter General Program Design
|
@chapter General Program Design
|
||||||
|
|
||||||
This @value{CHAPTER} discusses some of the issues you should take into
|
This @value{CHAPTER} discusses some of the issues you should take into
|
||||||
account when designing your program.
|
account when designing your program.
|
||||||
|
|
||||||
|
@c Standard or ANSI C
|
||||||
|
@c
|
||||||
|
@c In 1989 the American National Standards Institute (ANSI) standardized
|
||||||
|
@c C as standard X3.159-1989. In December of that year the
|
||||||
|
@c International Standards Organization ISO adopted the ANSI C standard
|
||||||
|
@c making minor changes. In 1990 ANSI then re-adopted ISO standard
|
||||||
|
@c C. This version of C is known as either ANSI C or Standard C.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
|
* Source Language:: Which languges to use.
|
||||||
* Compatibility:: Compatibility with other implementations
|
* Compatibility:: Compatibility with other implementations
|
||||||
* Using Extensions:: Using non-standard features
|
* Using Extensions:: Using non-standard features
|
||||||
* ANSI C:: Using ANSI C features
|
* Standard C:: Using Standard (ANSI 1989) C features
|
||||||
* Source Language:: Using languages other than C
|
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
|
@node Source Language
|
||||||
|
@section 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 use C, rather than the
|
||||||
|
comparable alternatives.
|
||||||
|
|
||||||
|
But there are two exceptions to that conclusion:
|
||||||
|
|
||||||
|
@itemize @bullet
|
||||||
|
@item
|
||||||
|
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.
|
||||||
|
|
||||||
|
@item
|
||||||
|
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.
|
||||||
|
@end itemize
|
||||||
|
|
||||||
|
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, which
|
||||||
|
implements the language Scheme (an especially clean and simple dialect
|
||||||
|
of Lisp). @uref{http://www.gnu.org/software/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.
|
||||||
|
|
||||||
@node Compatibility
|
@node Compatibility
|
||||||
@section Compatibility with Other Implementations
|
@section Compatibility with Other Implementations
|
||||||
|
|
||||||
With occasional exceptions, utility programs and libraries for GNU
|
With occasional exceptions, utility programs and libraries for GNU
|
||||||
should be upward compatible with those in Berkeley Unix, and upward
|
should be upward compatible with those in Berkeley Unix, and upward
|
||||||
compatible with @sc{ansi} C if @sc{ansi} C specifies their behavior, and
|
compatible with 1989 Standard C if 1989 Standard C specifies their
|
||||||
upward compatible with @sc{POSIX} if @sc{POSIX} specifies their
|
behavior, and upward compatible with @sc{posix} if @sc{posix} specifies
|
||||||
behavior.
|
their behavior.
|
||||||
|
|
||||||
When these standards conflict, it is useful to offer compatibility
|
When these standards conflict, it is useful to offer compatibility
|
||||||
modes for each of them.
|
modes for each of them.
|
||||||
|
|
||||||
@sc{ansi} C and @sc{POSIX} prohibit many kinds of extensions. Feel free
|
1989 Standard C and @sc{posix} prohibit many kinds of extensions. Feel
|
||||||
to make the extensions anyway, and include a @samp{--ansi},
|
free to make the extensions anyway, and include a @samp{--ansi},
|
||||||
@samp{--posix}, or @samp{--compatible} option to turn them off.
|
@samp{--posix}, or @samp{--compatible} option to turn them off.
|
||||||
However, if the extension has a significant chance of breaking any real
|
However, if the extension has a significant chance of breaking any real
|
||||||
programs or scripts, then it is not really upward compatible. Try to
|
programs or scripts, then it is not really upward compatible. So you
|
||||||
redesign its interface.
|
should try to redesign its interface to make it upward compatible.
|
||||||
|
|
||||||
Many GNU programs suppress extensions that conflict with POSIX if the
|
Many GNU programs suppress extensions that conflict with @sc{posix} if the
|
||||||
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
|
environment variable @code{POSIXLY_CORRECT} is defined (even if it is
|
||||||
defined with a null value). Please make your program recognize this
|
defined with a null value). Please make your program recognize this
|
||||||
variable if appropriate.
|
variable if appropriate.
|
||||||
|
@ -243,7 +320,8 @@ completely with something totally different and better. (For example,
|
||||||
@code{vi} is replaced with Emacs.) But it is nice to offer a compatible
|
@code{vi} is replaced with Emacs.) But it is nice to offer a compatible
|
||||||
feature as well. (There is a free @code{vi} clone, so we offer it.)
|
feature as well. (There is a free @code{vi} clone, so we offer it.)
|
||||||
|
|
||||||
Additional useful features not in Berkeley Unix are welcome.
|
Additional useful features are welcome regardless of whether
|
||||||
|
there is any precedent for them.
|
||||||
|
|
||||||
@node Using Extensions
|
@node Using Extensions
|
||||||
@section Using Non-standard Features
|
@section Using Non-standard Features
|
||||||
|
@ -267,29 +345,28 @@ straightforwardly do without them, but to use the extensions if they
|
||||||
are a big improvement.
|
are a big improvement.
|
||||||
|
|
||||||
An exception to this rule are the large, established programs (such as
|
An exception to this rule are the large, established programs (such as
|
||||||
Emacs) which run on a great variety of systems. Such programs would
|
Emacs) which run on a great variety of systems. Using GNU extensions in
|
||||||
be broken by use of GNU extensions.
|
such programs would make many users unhappy, so we don't do that.
|
||||||
|
|
||||||
Another exception is for programs that are used as part of
|
Another exception is for programs that are used as part of compilation:
|
||||||
compilation: anything that must be compiled with other compilers in
|
anything that must be compiled with other compilers in order to
|
||||||
order to bootstrap the GNU compilation facilities. If these require
|
bootstrap the GNU compilation facilities. If these require the GNU
|
||||||
the GNU compiler, then no one can compile them without having them
|
compiler, then no one can compile them without having them installed
|
||||||
installed already. That would be no good.
|
already. That would be extremely troublesome in certain cases.
|
||||||
|
|
||||||
@node ANSI C
|
@node Standard C
|
||||||
@section @sc{ansi} C and pre-@sc{ansi} C
|
@section 1989 Standard C and Pre-Standard C
|
||||||
|
|
||||||
Do not ever use the ``trigraph'' feature of @sc{ansi} 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 1989 Standard C.
|
||||||
|
|
||||||
@sc{ansi} C is widespread enough now that it is ok to write new programs
|
However, it is easy to support pre-standard compilers in most programs,
|
||||||
that use @sc{ansi} C features (and therefore will not work in
|
so if you know how to do that, feel free. If a program you are
|
||||||
non-@sc{ansi} compilers). And if a program is already written in
|
maintaining has such support, you should try to keep it working.
|
||||||
@sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
|
|
||||||
compilers.
|
|
||||||
|
|
||||||
However, it is easy to support non-@sc{ansi} compilers in most programs,
|
To support pre-standard C, instead of writing function definitions in
|
||||||
so you might still consider doing so when you write a program. Instead
|
standard prototype form,
|
||||||
of writing function definitions in @sc{ansi} prototype form,
|
|
||||||
|
|
||||||
@example
|
@example
|
||||||
int
|
int
|
||||||
|
@ -298,7 +375,7 @@ foo (int x, int y)
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
@noindent
|
@noindent
|
||||||
write the definition in pre-@sc{ansi} style like this,
|
write the definition in pre-standard style like this,
|
||||||
|
|
||||||
@example
|
@example
|
||||||
int
|
int
|
||||||
|
@ -315,56 +392,42 @@ int foo (int, int);
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
You need such a declaration anyway, in a header file, to get the benefit
|
You need such a declaration anyway, in a header file, to get the benefit
|
||||||
of @sc{ansi} C prototypes in all the files where the function is called.
|
of prototypes in all the files where the function is called. And once
|
||||||
And once you have it, you lose nothing by writing the function
|
you have the declaration, you normally lose nothing by writing the
|
||||||
definition in the pre-@sc{ansi} style.
|
function definition in the pre-standard style.
|
||||||
|
|
||||||
If you don't know non-@sc{ansi} C, there's no need to learn it; just
|
This technique does not work for integer types narrower than @code{int}.
|
||||||
write in @sc{ansi} C.
|
If you think of an argument as being of a type narrower than @code{int},
|
||||||
|
declare it as @code{int} instead.
|
||||||
|
|
||||||
@node Source Language
|
There are a few special cases where this technique is hard to use. For
|
||||||
@section Using Languages Other Than C
|
example, if a function argument needs to hold the system type
|
||||||
|
@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than
|
||||||
|
@code{int} on some machines; but you cannot use @code{int} instead,
|
||||||
|
because @code{dev_t} is wider than @code{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 @code{dev_t} using Autoconf and choose
|
||||||
|
the argument type accordingly. This may not be worth the trouble.
|
||||||
|
|
||||||
Using a language other than C is like using a non-standard feature: it
|
In order to support pre-standard compilers that do not recognize
|
||||||
will cause trouble for users. Even if GCC supports the other language,
|
prototypes, you may want to use a preprocessor macro like this:
|
||||||
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 C++ compiler
|
|
||||||
in order to compile your program. Thus, it is better if you write in C.
|
|
||||||
|
|
||||||
But there are three situations when there is no disadvantage in using
|
@example
|
||||||
some other language:
|
/* Declare the prototype for a general external function. */
|
||||||
|
#if defined (__STDC__) || defined (WINDOWSNT)
|
||||||
@itemize @bullet
|
#define P_(proto) proto
|
||||||
@item
|
#else
|
||||||
It is okay to use another language if your program contains an
|
#define P_(proto) ()
|
||||||
interpreter for that language.
|
#endif
|
||||||
|
@end example
|
||||||
For example, if your program links with GUILE, it is ok to write part of
|
|
||||||
the program in Scheme or another language supported by GUILE.
|
|
||||||
|
|
||||||
@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 of interest to a narrow community, then perhaps
|
|
||||||
it's not important if the application is inconvenient to install.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
@node Program Behavior
|
@node Program Behavior
|
||||||
@chapter Program Behavior for All Programs
|
@chapter Program Behavior for All Programs
|
||||||
|
|
||||||
This @value{CHAPTER} describes how to write robust software. It also
|
This @value{CHAPTER} describes conventions for writing robust
|
||||||
describes general standards for error messages, the command line interface,
|
software. It also describes general standards for error messages, the
|
||||||
and how libraries should behave.
|
command line interface, and how libraries should behave.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Semantics:: Writing robust programs
|
* Semantics:: Writing robust programs
|
||||||
|
@ -384,9 +447,13 @@ all data structures dynamically. In most Unix utilities, ``long lines
|
||||||
are silently truncated''. This is not acceptable in a GNU utility.
|
are silently truncated''. This is not acceptable in a GNU utility.
|
||||||
|
|
||||||
Utilities reading files should not drop NUL characters, or any other
|
Utilities reading files should not drop NUL characters, or any other
|
||||||
nonprinting characters @emph{including those with codes above 0177}. The
|
nonprinting characters @emph{including those with codes above 0177}.
|
||||||
only sensible exceptions would be utilities specifically intended for
|
The only sensible exceptions would be utilities specifically intended
|
||||||
interface to certain types of printers that can't handle those characters.
|
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.
|
||||||
|
|
||||||
Check every system call for an error return, unless you know you wish to
|
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
|
ignore errors. Include the system error text (from @code{perror} or
|
||||||
|
@ -428,11 +495,18 @@ Try to avoid low-level interfaces to obscure Unix data structures (such
|
||||||
as file directories, utmp, or the layout of kernel memory), since these
|
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
|
are less likely to work compatibly. If you need to find all the files
|
||||||
in a directory, use @code{readdir} or some other high-level interface.
|
in a directory, use @code{readdir} or some other high-level interface.
|
||||||
These will be supported compatibly by GNU.
|
These are supported compatibly by GNU.
|
||||||
|
|
||||||
By default, the GNU system will provide the signal handling functions of
|
The preferred signal handling facilities are the BSD variant of
|
||||||
@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use
|
@code{signal}, and the @sc{posix} @code{sigaction} function; the
|
||||||
these.
|
alternative USG @code{signal} interface is an inferior design.
|
||||||
|
|
||||||
|
Nowadays, using the @sc{posix} signal functions may be the easiest way
|
||||||
|
to make a program portable. If you use @code{signal}, then on GNU/Linux
|
||||||
|
systems running GNU libc version 1, you should include
|
||||||
|
@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD
|
||||||
|
behavior. It is up to you whether to support systems where
|
||||||
|
@code{signal} has only the USG behavior, or give up on them.
|
||||||
|
|
||||||
In error checks that detect ``impossible'' conditions, just abort.
|
In error checks that detect ``impossible'' conditions, just abort.
|
||||||
There is usually no point in printing any message. These checks
|
There is usually no point in printing any message. These checks
|
||||||
|
@ -452,6 +526,20 @@ If you make temporary files, check the @code{TMPDIR} environment
|
||||||
variable; if that variable is defined, use the specified directory
|
variable; if that variable is defined, use the specified directory
|
||||||
instead of @file{/tmp}.
|
instead of @file{/tmp}.
|
||||||
|
|
||||||
|
In addition, be aware that there is a possible security problem when
|
||||||
|
creating temporary files in directories world-writable directories. In
|
||||||
|
C, you can avoid this problem by creating temporary files in this
|
||||||
|
manner:
|
||||||
|
|
||||||
|
@example
|
||||||
|
fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
|
||||||
|
@end example
|
||||||
|
|
||||||
|
@noindent
|
||||||
|
or by using the @code{mkstemps} function from libiberty.
|
||||||
|
|
||||||
|
In bash, use @code{set -C} to avoid this problem.
|
||||||
|
|
||||||
@node Libraries
|
@node Libraries
|
||||||
@section Library Behavior
|
@section Library Behavior
|
||||||
|
|
||||||
|
@ -490,6 +578,20 @@ Error messages from compilers should look like this:
|
||||||
@var{source-file-name}:@var{lineno}: @var{message}
|
@var{source-file-name}:@var{lineno}: @var{message}
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
|
@noindent
|
||||||
|
If you want to mention the column number, use this format:
|
||||||
|
|
||||||
|
@example
|
||||||
|
@var{source-file-name}:@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.
|
||||||
|
|
||||||
Error messages from other noninteractive programs should look like this:
|
Error messages from other noninteractive programs should look like this:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
|
@ -506,6 +608,12 @@ when there is an appropriate source file, or like this:
|
||||||
@noindent
|
@noindent
|
||||||
when there is no relevant source file.
|
when there is no relevant source file.
|
||||||
|
|
||||||
|
If you want to mention the column number, use this format:
|
||||||
|
|
||||||
|
@example
|
||||||
|
@var{program}:@var{source-file-name}:@var{lineno}:@var{column}: @var{message}
|
||||||
|
@end example
|
||||||
|
|
||||||
In an interactive program (one that is reading commands from a
|
In an interactive program (one that is reading commands from a
|
||||||
terminal), it is better not to include the program name in an error
|
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
|
message. The place to indicate which program is running is in the
|
||||||
|
@ -533,8 +641,10 @@ to select among the alternate behaviors.
|
||||||
|
|
||||||
Likewise, please don't make the behavior of the program depend on the
|
Likewise, please don't make the behavior of the program depend on the
|
||||||
type of output device it is used with. Device independence is an
|
type of output device it is used with. Device independence is an
|
||||||
important principle of the system's design; do not compromise it
|
important principle of the system's design; do not compromise it merely
|
||||||
merely to save someone from typing an option now and then.
|
to save someone from typing an option now and then. (Variation in error
|
||||||
|
message syntax when using a terminal is ok, because that is a side issue
|
||||||
|
that people do not depend on.)
|
||||||
|
|
||||||
If you think one behavior is most useful when the output is to a
|
If you think one behavior is most useful when the output is to a
|
||||||
terminal, and another is most useful when the output is a file or a
|
terminal, and another is most useful when the output is a file or a
|
||||||
|
@ -550,11 +660,11 @@ output device type. For example, we provide a @code{dir} program much
|
||||||
like @code{ls} except that its default output format is always
|
like @code{ls} except that its default output format is always
|
||||||
multi-column format.
|
multi-column format.
|
||||||
|
|
||||||
It is a good idea to follow the @sc{POSIX} guidelines for the
|
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
|
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}
|
@code{getopt} to parse them. Note that the GNU version of @code{getopt}
|
||||||
will normally permit options anywhere among the arguments unless the
|
will normally permit options anywhere among the arguments unless the
|
||||||
special argument @samp{--} is used. This is not what @sc{POSIX}
|
special argument @samp{--} is used. This is not what @sc{posix}
|
||||||
specifies; it is a GNU extension.
|
specifies; it is a GNU extension.
|
||||||
|
|
||||||
Please define long-named options that are equivalent to the
|
Please define long-named options that are equivalent to the
|
||||||
|
@ -581,7 +691,7 @@ and @samp{--help}.
|
||||||
|
|
||||||
@table @code
|
@table @code
|
||||||
@item --version
|
@item --version
|
||||||
This option should direct the program to information about its name,
|
This option should direct the program to print information about its name,
|
||||||
version, origin and legal status, all on standard output, and then exit
|
version, origin and legal status, all on standard output, and then exit
|
||||||
successfully. Other options and arguments should be ignored once this
|
successfully. Other options and arguments should be ignored once this
|
||||||
is seen, and the program should not perform its normal function.
|
is seen, and the program should not perform its normal function.
|
||||||
|
@ -738,6 +848,9 @@ and @code{unexpand}.
|
||||||
@item avoid-wraps
|
@item avoid-wraps
|
||||||
@samp{-n} in @code{wdiff}.
|
@samp{-n} in @code{wdiff}.
|
||||||
|
|
||||||
|
@item background
|
||||||
|
For server programs, run in the background.
|
||||||
|
|
||||||
@item backward-search
|
@item backward-search
|
||||||
@samp{-B} in @code{ctags}.
|
@samp{-B} in @code{ctags}.
|
||||||
|
|
||||||
|
@ -862,6 +975,9 @@ Used in @code{tar} and @code{cpio}.
|
||||||
@item dereference-args
|
@item dereference-args
|
||||||
@samp{-D} in @code{du}.
|
@samp{-D} in @code{du}.
|
||||||
|
|
||||||
|
@item device
|
||||||
|
Specify an I/O device (special file name).
|
||||||
|
|
||||||
@item diacritics
|
@item diacritics
|
||||||
@samp{-d} in @code{recode}.
|
@samp{-d} in @code{recode}.
|
||||||
|
|
||||||
|
@ -994,6 +1110,11 @@ Used in @code{makeinfo}.
|
||||||
@item force-prefix
|
@item force-prefix
|
||||||
@samp{-F} in @code{shar}.
|
@samp{-F} in @code{shar}.
|
||||||
|
|
||||||
|
@item foreground
|
||||||
|
For server programs, run in the foreground;
|
||||||
|
in other words, don't do anything special to run the server
|
||||||
|
in the background.
|
||||||
|
|
||||||
@item format
|
@item format
|
||||||
Used in @code{ls}, @code{time}, and @code{ptx}.
|
Used in @code{ls}, @code{time}, and @code{ptx}.
|
||||||
|
|
||||||
|
@ -1039,6 +1160,9 @@ Used to ask for brief usage information.
|
||||||
@item hide-control-chars
|
@item hide-control-chars
|
||||||
@samp{-q} in @code{ls}.
|
@samp{-q} in @code{ls}.
|
||||||
|
|
||||||
|
@item html
|
||||||
|
In @code{makeinfo}, output HTML.
|
||||||
|
|
||||||
@item idle
|
@item idle
|
||||||
@samp{-u} in @code{who}.
|
@samp{-u} in @code{who}.
|
||||||
|
|
||||||
|
@ -1099,6 +1223,10 @@ Used to ask for brief usage information.
|
||||||
@item info
|
@item info
|
||||||
@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
|
@samp{-i}, @samp{-l}, and @samp{-m} in Finger.
|
||||||
|
|
||||||
|
@item init-file
|
||||||
|
In some programs, specify the name of the file to read as the user's
|
||||||
|
init file.
|
||||||
|
|
||||||
@item initial
|
@item initial
|
||||||
@samp{-i} in @code{expand}.
|
@samp{-i} in @code{expand}.
|
||||||
|
|
||||||
|
@ -1117,6 +1245,9 @@ Used to ask for brief usage information.
|
||||||
@item intermix-type
|
@item intermix-type
|
||||||
@samp{-p} in @code{shar}.
|
@samp{-p} in @code{shar}.
|
||||||
|
|
||||||
|
@item iso-8601
|
||||||
|
Used in @code{date}
|
||||||
|
|
||||||
@item jobs
|
@item jobs
|
||||||
@samp{-j} in Make.
|
@samp{-j} in Make.
|
||||||
|
|
||||||
|
@ -1352,6 +1483,10 @@ Used in GDB.
|
||||||
@item only-time
|
@item only-time
|
||||||
@samp{-F} in @code{gprof}.
|
@samp{-F} in @code{gprof}.
|
||||||
|
|
||||||
|
@item options
|
||||||
|
@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount},
|
||||||
|
@code{fdmountd}, and @code{fdumount}.
|
||||||
|
|
||||||
@item output
|
@item output
|
||||||
In various programs, specify the output file name.
|
In various programs, specify the output file name.
|
||||||
|
|
||||||
|
@ -1436,6 +1571,9 @@ Used in @code{tar} and @code{cp}.
|
||||||
@item prompt
|
@item prompt
|
||||||
@samp{-p} in @code{ed}.
|
@samp{-p} in @code{ed}.
|
||||||
|
|
||||||
|
@item proxy
|
||||||
|
Specify an HTTP proxy.
|
||||||
|
|
||||||
@item query-user
|
@item query-user
|
||||||
@samp{-X} in @code{shar}.
|
@samp{-X} in @code{shar}.
|
||||||
|
|
||||||
|
@ -1564,6 +1702,12 @@ Used in many programs to inhibit the usual output.
|
||||||
@item size
|
@item size
|
||||||
@samp{-s} in @code{ls}.
|
@samp{-s} in @code{ls}.
|
||||||
|
|
||||||
|
@item socket
|
||||||
|
Specify a file descriptor for a network server to use for its socket,
|
||||||
|
instead of opening and binding a new socket. This provides a way to
|
||||||
|
run, in a nonpriveledged process, a server that normally needs a
|
||||||
|
reserved port number.
|
||||||
|
|
||||||
@item sort
|
@item sort
|
||||||
Used in @code{ls}.
|
Used in @code{ls}.
|
||||||
|
|
||||||
|
@ -1662,6 +1806,9 @@ Used in GDB and @code{objdump}.
|
||||||
@item time
|
@item time
|
||||||
Used in @code{ls} and @code{touch}.
|
Used in @code{ls} and @code{touch}.
|
||||||
|
|
||||||
|
@item timeout
|
||||||
|
Specify how long to wait before giving up on some operation.
|
||||||
|
|
||||||
@item to-stdout
|
@item to-stdout
|
||||||
@samp{-O} in @code{tar}.
|
@samp{-O} in @code{tar}.
|
||||||
|
|
||||||
|
@ -1813,7 +1960,8 @@ concat (s1, s2) /* Name starts in column zero here */
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
@noindent
|
@noindent
|
||||||
or, if you want to use @sc{ansi} C, format the definition like this:
|
or, if you want to use Standard C syntax, format the definition like
|
||||||
|
this:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
static char *
|
static char *
|
||||||
|
@ -1823,7 +1971,7 @@ concat (char *s1, char *s2)
|
||||||
@}
|
@}
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
In @sc{ansi} C, if the arguments don't fit nicely on one line,
|
In Standard C, if the arguments don't fit nicely on one line,
|
||||||
split it like this:
|
split it like this:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
|
@ -1833,7 +1981,17 @@ lots_of_args (int an_integer, long a_long, short a_short,
|
||||||
@dots{}
|
@dots{}
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
For the body of the function, we prefer code formatted like this:
|
The rest of this section gives our recommendations for other aspects of
|
||||||
|
C formatting style. We don't think of them as requirements, because it
|
||||||
|
causes no problems for users if two different programs have different
|
||||||
|
formatting styles.
|
||||||
|
|
||||||
|
But whatever style you use, please use it consistently, since a mixture
|
||||||
|
of styles within one program tends to look ugly. If you are
|
||||||
|
contributing changes to an existing program, please follow the style of
|
||||||
|
that program.
|
||||||
|
|
||||||
|
For the body of the function, our recommended style looks like this:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
if (x < foo (y, z))
|
if (x < foo (y, z))
|
||||||
|
@ -1879,14 +2037,15 @@ mode = ((inmode[j] == VOIDmode
|
||||||
|
|
||||||
Insert extra parentheses so that Emacs will indent the code properly.
|
Insert extra parentheses so that Emacs will indent the code properly.
|
||||||
For example, the following indentation looks nice if you do it by hand,
|
For example, the following indentation looks nice if you do it by hand,
|
||||||
but Emacs would mess it up:
|
|
||||||
|
|
||||||
@example
|
@example
|
||||||
v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
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;
|
+ rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
But adding a set of parentheses solves the problem:
|
@noindent
|
||||||
|
but Emacs would alter it. Adding a set of parentheses produces
|
||||||
|
something that looks equally nice, and which Emacs will preserve:
|
||||||
|
|
||||||
@example
|
@example
|
||||||
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
||||||
|
@ -1908,7 +2067,6 @@ 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
|
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.
|
page. The formfeeds should appear alone on lines by themselves.
|
||||||
|
|
||||||
|
|
||||||
@node Comments
|
@node Comments
|
||||||
@section Commenting Your Work
|
@section Commenting Your Work
|
||||||
|
|
||||||
|
@ -2007,6 +2165,13 @@ but, by contrast, write the comments this way for a @samp{#ifndef}:
|
||||||
Please explicitly declare all arguments to functions.
|
Please explicitly declare all arguments to functions.
|
||||||
Don't omit them just because they are @code{int}s.
|
Don't omit them just because they are @code{int}s.
|
||||||
|
|
||||||
|
Some programmers like to use the GCC @samp{-Wall} option, and change the
|
||||||
|
code whenever it issues a warning. If you want to do this, then do.
|
||||||
|
Other programmers prefer not to use @samp{-Wall}, because it gives
|
||||||
|
warnings for valid and legitimate code which they do not want to change.
|
||||||
|
If you want to do this, then do. The compiler should be your servant,
|
||||||
|
not your master.
|
||||||
|
|
||||||
Declarations of external functions and functions to appear later in the
|
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
|
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
|
(somewhere before the first function definition in the file), or else
|
||||||
|
@ -2140,6 +2305,10 @@ comments.
|
||||||
Local variable names can be shorter, because they are used only within
|
Local variable names can be shorter, because they are used only within
|
||||||
one context, where (presumably) comments explain their purpose.
|
one context, where (presumably) comments explain their purpose.
|
||||||
|
|
||||||
|
Try to limit your use of abbreviations in symbol names. It is ok to
|
||||||
|
make a few abbreviations, explain what they mean, and then use them
|
||||||
|
frequently, but don't use lots of obscure abbreviations.
|
||||||
|
|
||||||
Please use underscores to separate words in a name, so that the Emacs
|
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
|
word commands can be useful within them. Stick to lower case; reserve
|
||||||
upper case for macros and @code{enum} constants, and for name-prefixes
|
upper case for macros and @code{enum} constants, and for name-prefixes
|
||||||
|
@ -2198,14 +2367,22 @@ Avoid using the format of semi-internal data bases (e.g., directories)
|
||||||
when there is a higher-level alternative (@code{readdir}).
|
when there is a higher-level alternative (@code{readdir}).
|
||||||
|
|
||||||
As for systems that are not like Unix, such as MSDOS, Windows, the
|
As for systems that are not like Unix, such as MSDOS, Windows, the
|
||||||
Macintosh, VMS, and MVS, supporting them is usually so much work that it
|
Macintosh, VMS, and MVS, supporting them is often a lot of work. When
|
||||||
is better if you don't.
|
that is the case, it is better to spend your time adding features that
|
||||||
|
will be useful on GNU and GNU/Linux, rather than on supporting other
|
||||||
|
incompatible systems.
|
||||||
|
|
||||||
The planned GNU kernel is not finished yet, but you can tell which
|
It is a good idea to define the ``feature test macro''
|
||||||
facilities it will provide by looking at the GNU C Library Manual. The
|
@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU
|
||||||
GNU kernel is based on Mach, so the features of Mach will also be
|
or GNU/Linux, this will enable the declarations of GNU library extension
|
||||||
available. However, if you use Mach features, you'll probably have
|
functions, and that will usually give you a compiler error message if
|
||||||
trouble debugging your program today.
|
you define the same function names in some other way in your program.
|
||||||
|
(You don't have to actually @emph{use} these functions, if you prefer
|
||||||
|
to make the program more portable to other systems.)
|
||||||
|
|
||||||
|
But whether or not you use these GNU extensions, you should avoid
|
||||||
|
using their names for any other meanings. Doing so would make it hard
|
||||||
|
to move your code into other GNU programs.
|
||||||
|
|
||||||
@node CPU Portability
|
@node CPU Portability
|
||||||
@section Portability between @sc{cpu}s
|
@section Portability between @sc{cpu}s
|
||||||
|
@ -2231,9 +2408,9 @@ while ((c = getchar()) != EOF)
|
||||||
When calling functions, you need not worry about the difference between
|
When calling functions, you need not worry about the difference between
|
||||||
pointers of various types, or between pointers and integers. On most
|
pointers of various types, or between pointers and integers. On most
|
||||||
machines, there's no difference anyway. As for the few machines where
|
machines, there's no difference anyway. As for the few machines where
|
||||||
there is a difference, all of them support @sc{ansi} C, so you can use
|
there is a difference, all of them support 1989 Standard C, so you can
|
||||||
prototypes (conditionalized to be active only in @sc{ansi} C) to make
|
use prototypes (perhaps conditionalized to be active only in Standard C)
|
||||||
the code work on those systems.
|
to make the code work on those systems.
|
||||||
|
|
||||||
In certain cases, it is ok to pass integer and pointer arguments
|
In certain cases, it is ok to pass integer and pointer arguments
|
||||||
indiscriminately to the same function, and use no prototype on any
|
indiscriminately to the same function, and use no prototype on any
|
||||||
|
@ -2243,7 +2420,7 @@ that pass their arguments along to @code{printf} and friends:
|
||||||
@example
|
@example
|
||||||
error (s, a1, a2, a3)
|
error (s, a1, a2, a3)
|
||||||
char *s;
|
char *s;
|
||||||
int a1, a2, a3;
|
char *a1, *a2, *a3;
|
||||||
@{
|
@{
|
||||||
fprintf (stderr, "error: ");
|
fprintf (stderr, "error: ");
|
||||||
fprintf (stderr, s, a1, a2, a3);
|
fprintf (stderr, s, a1, a2, a3);
|
||||||
|
@ -2251,31 +2428,41 @@ error (s, a1, a2, a3)
|
||||||
@end example
|
@end example
|
||||||
|
|
||||||
@noindent
|
@noindent
|
||||||
In practice, this works on all machines, and it is much simpler than any
|
In practice, this works on all machines, since a pointer is generally
|
||||||
``correct'' alternative. Be sure @emph{not} to use a prototype
|
the widest possible kind of argument; it is much simpler than any
|
||||||
for such functions.
|
``correct'' alternative. Be sure @emph{not} to use a prototype for such
|
||||||
|
functions.
|
||||||
|
|
||||||
However, avoid casting pointers to integers unless you really need to.
|
If you have decided to use 1989 Standard C, then you can instead define
|
||||||
These assumptions really reduce portability, and in most programs they
|
@code{error} using @file{stdarg.h}, and pass the arguments along to
|
||||||
are easy to avoid. In the cases where casting pointers to integers is
|
@code{vfprintf}.
|
||||||
essential---such as, a Lisp interpreter which stores type information as
|
|
||||||
well as an address in one word---it is ok to do so, but you'll have to
|
Avoid casting pointers to integers if you can. Such casts greatly
|
||||||
make explicit provisions to handle different word sizes.
|
reduce portability, and in most programs they are easy to avoid. In the
|
||||||
|
cases where casting pointers to integers is essential---such as, a Lisp
|
||||||
|
interpreter which stores type information as well as an address in one
|
||||||
|
word---you'll have to make explicit provisions to handle different word
|
||||||
|
sizes. You will also need to make provision for systems in which the
|
||||||
|
normal range of addresses you can get from @code{malloc} starts far away
|
||||||
|
from zero.
|
||||||
|
|
||||||
@node System Functions
|
@node System Functions
|
||||||
@section Calling System Functions
|
@section Calling System Functions
|
||||||
|
|
||||||
C implementations differ substantially. @sc{ansi} C reduces but does not
|
C implementations differ substantially. 1989 Standard C reduces but does
|
||||||
eliminate the incompatibilities; meanwhile, many users wish to compile
|
not eliminate the incompatibilities; meanwhile, many GNU packages still
|
||||||
GNU software with pre-@sc{ansi} compilers. This chapter gives
|
support pre-standard compilers because this is not hard to do. This
|
||||||
recommendations for how to use the more or less standard C library
|
chapter gives recommendations for how to use the more-or-less standard C
|
||||||
functions to avoid unnecessary loss of portability.
|
library functions to avoid unnecessary loss of portability.
|
||||||
|
|
||||||
@itemize @bullet
|
@itemize @bullet
|
||||||
@item
|
@item
|
||||||
Don't use the value of @code{sprintf}. It returns the number of
|
Don't use the return value of @code{sprintf}. It returns the number of
|
||||||
characters written on some systems, but not on all systems.
|
characters written on some systems, but not on all systems.
|
||||||
|
|
||||||
|
@item
|
||||||
|
Be aware that @code{vfprintf} is not always available.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
@code{main} should be declared to return type @code{int}. It should
|
@code{main} should be declared to return type @code{int}. It should
|
||||||
terminate either by calling @code{exit} or by returning the integer
|
terminate either by calling @code{exit} or by returning the integer
|
||||||
|
@ -2297,7 +2484,7 @@ actual conflicts.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
If you must declare a system function, don't specify the argument types.
|
If you must declare a system function, don't specify the argument types.
|
||||||
Use an old-style declaration, not an @sc{ansi} prototype. The more you
|
Use an old-style declaration, not a Standard C prototype. The more you
|
||||||
specify about the function, the more likely a conflict.
|
specify about the function, the more likely a conflict.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
|
@ -2329,7 +2516,7 @@ figure out which file to include, or don't include either file.
|
||||||
If you don't include either strings file, you can't get declarations for
|
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.
|
the string functions from the header file in the usual way.
|
||||||
|
|
||||||
That causes less of a problem than you might think. The newer @sc{ansi}
|
That causes less of a problem than you might think. The newer standard
|
||||||
string functions should be avoided anyway because many systems still
|
string functions should be avoided anyway because many systems still
|
||||||
don't support them. The string functions you can use are these:
|
don't support them. The string functions you can use are these:
|
||||||
|
|
||||||
|
@ -2359,7 +2546,7 @@ names, but neither pair works on all systems.
|
||||||
|
|
||||||
You should pick a single pair of names and use it throughout your
|
You should pick a single pair of names and use it throughout your
|
||||||
program. (Nowadays, it is better to choose @code{strchr} and
|
program. (Nowadays, it is better to choose @code{strchr} and
|
||||||
@code{strrchr} for new programs, since those are the standard @sc{ansi}
|
@code{strrchr} for new programs, since those are the standard
|
||||||
names.) Declare both of those names as functions returning @code{char
|
names.) Declare both of those names as functions returning @code{char
|
||||||
*}. On systems which don't support those names, define them as macros
|
*}. 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
|
in terms of the other pair. For example, here is what to put at the
|
||||||
|
@ -2503,6 +2690,7 @@ all these kinds of files.
|
||||||
@menu
|
@menu
|
||||||
* GNU Manuals:: Writing proper manuals.
|
* GNU Manuals:: Writing proper manuals.
|
||||||
* Manual Structure Details:: Specific structure conventions.
|
* Manual Structure Details:: Specific structure conventions.
|
||||||
|
* License for Manuals:: Writing the distribution terms for a manual.
|
||||||
* NEWS File:: NEWS files supplement manuals.
|
* NEWS File:: NEWS files supplement manuals.
|
||||||
* Change Logs:: Recording Changes
|
* Change Logs:: Recording Changes
|
||||||
* Man Pages:: Man pages are secondary.
|
* Man Pages:: Man pages are secondary.
|
||||||
|
@ -2514,9 +2702,12 @@ all these kinds of files.
|
||||||
@section GNU Manuals
|
@section GNU Manuals
|
||||||
|
|
||||||
The preferred way to document part of the GNU system is to write a
|
The preferred way to document part of the GNU system is to write a
|
||||||
manual in the Texinfo formatting language. See the Texinfo manual,
|
manual in the Texinfo formatting language. This makes it possible to
|
||||||
either the hardcopy, or the on-line version available through
|
produce a good quality formatted book, using @TeX{}, and to generate an
|
||||||
@code{info} or the Emacs Info subsystem (@kbd{C-h i}).
|
Info file. It is also possible to generate HTML output from Texinfo
|
||||||
|
source. See the Texinfo manual, either the hardcopy, or the on-line
|
||||||
|
version available through @code{info} or the Emacs Info subsystem
|
||||||
|
(@kbd{C-h i}).
|
||||||
|
|
||||||
Programmers often find it most natural to structure the documentation
|
Programmers often find it most natural to structure the documentation
|
||||||
following the structure of the implementation, which they know. But
|
following the structure of the implementation, which they know. But
|
||||||
|
@ -2557,6 +2748,8 @@ It should be set up for convenient access to each topic through Info,
|
||||||
and for reading straight through (appendixes aside). A GNU manual
|
and for reading straight through (appendixes aside). A GNU manual
|
||||||
should give a good introduction to a beginner reading through from the
|
should give a good introduction to a beginner reading through from the
|
||||||
start, and should also provide all the details that hackers want.
|
start, and should also provide all the details that hackers want.
|
||||||
|
The Bison manual is a good example of this---please take a look at it
|
||||||
|
to see what we mean.
|
||||||
|
|
||||||
That is not as hard as it first sounds. Arrange each chapter as a
|
That is not as hard as it first sounds. Arrange each chapter as a
|
||||||
logical breakdown of its topic, but order the sections, and write their
|
logical breakdown of its topic, but order the sections, and write their
|
||||||
|
@ -2576,9 +2769,12 @@ explanation of the underlying concepts. (There are, of course
|
||||||
exceptions.) Also Unix man pages use a particular format which is
|
exceptions.) Also Unix man pages use a particular format which is
|
||||||
different from what we use in GNU manuals.
|
different from what we use in GNU manuals.
|
||||||
|
|
||||||
|
Please include an email address in the manual for where to report
|
||||||
|
bugs @emph{in the manual}.
|
||||||
|
|
||||||
Please do not use the term ``pathname'' that is used in Unix
|
Please do not use the term ``pathname'' that is used in Unix
|
||||||
documentation; use ``file name'' (two words) instead. We use the term
|
documentation; use ``file name'' (two words) instead. We use the term
|
||||||
``path'' only for search paths, which are lists of file names.
|
``path'' only for search paths, which are lists of directory names.
|
||||||
|
|
||||||
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 a
|
||||||
computer program. Please use ``invalid'' for this, and reserve the term
|
computer program. Please use ``invalid'' for this, and reserve the term
|
||||||
|
@ -2611,6 +2807,18 @@ quickly reading just this part of its manual.
|
||||||
If one manual describes several programs, it should have such a node for
|
If one manual describes several programs, it should have such a node for
|
||||||
each program described.
|
each program described.
|
||||||
|
|
||||||
|
@node License for Manuals
|
||||||
|
@section License for Manuals
|
||||||
|
|
||||||
|
If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
|
||||||
|
contains chapters that make political or personal statements, please
|
||||||
|
copy the distribution terms of the GNU Emacs Manual, and adapt it by
|
||||||
|
modifying appropriately the list of special chapters that may not be
|
||||||
|
modified or deleted.
|
||||||
|
|
||||||
|
If the manual does not contain any such chapters, then imitate the
|
||||||
|
simpler distribution terms of the Texinfo manual.
|
||||||
|
|
||||||
@node NEWS File
|
@node NEWS File
|
||||||
@section The NEWS File
|
@section The NEWS File
|
||||||
|
|
||||||
|
@ -2659,7 +2867,8 @@ you.
|
||||||
|
|
||||||
Another alternative is to record change log information with a version
|
Another alternative is to record change log information with a version
|
||||||
control system such as RCS or CVS. This can be converted automatically
|
control system such as RCS or CVS. This can be converted automatically
|
||||||
to a @file{ChangeLog} file.
|
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
|
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
|
work together. If you think that a change calls for explanation, you're
|
||||||
|
@ -3030,6 +3239,21 @@ files} and @dfn{non-source files}. Source files are written by humans
|
||||||
and never changed automatically; non-source files are produced from
|
and never changed automatically; non-source files are produced from
|
||||||
source files by programs under the control of the Makefile.
|
source files by programs under the control of the Makefile.
|
||||||
|
|
||||||
|
The distribution should contain a file named @file{README} which gives
|
||||||
|
the name of the package, and a general description of what it does. It
|
||||||
|
is also good to explain the purpose of each of the first-level
|
||||||
|
subdirectories in the package, if there are any. The @file{README} file
|
||||||
|
should either state the version number of the package, or refer to where
|
||||||
|
in the package it can be found.
|
||||||
|
|
||||||
|
The @file{README} file should refer to the file @file{INSTALL}, which
|
||||||
|
should contain an explanation of the installation procedure.
|
||||||
|
|
||||||
|
The @file{README} file should also refer to the file which contains the
|
||||||
|
copying conditions. The GNU GPL, if used, should be in a file called
|
||||||
|
@file{COPYING}. If the GNU LGPL is used, it should be in a file called
|
||||||
|
@file{COPYING.LIB}.
|
||||||
|
|
||||||
Naturally, all the source files must be in the distribution. It is okay
|
Naturally, all the source files must be in the distribution. It is okay
|
||||||
to include non-source files in the distribution, provided they are
|
to include non-source files in the distribution, provided they are
|
||||||
up-to-date and machine-independent, so that building the distribution
|
up-to-date and machine-independent, so that building the distribution
|
||||||
|
@ -3054,7 +3278,7 @@ Make sure that all the files in the distribution are world-readable.
|
||||||
Make sure that no file name in the distribution is more than 14
|
Make sure that no file name in the distribution is more than 14
|
||||||
characters long. Likewise, no file created by building the program
|
characters long. Likewise, no file created by building the program
|
||||||
should have a name longer than 14 characters. The reason for this is
|
should have a name longer than 14 characters. The reason for this is
|
||||||
that some systems adhere to a foolish interpretation of the POSIX
|
that some systems adhere to a foolish interpretation of the @sc{posix}
|
||||||
standard, and refuse to open a longer name, rather than truncating as
|
standard, and refuse to open a longer name, rather than truncating as
|
||||||
they did in the past.
|
they did in the past.
|
||||||
|
|
||||||
|
@ -3082,6 +3306,31 @@ 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
|
the expense of possible inconvenience to a user who doesn't know what
|
||||||
other files to get.
|
other files to get.
|
||||||
|
|
||||||
|
@node References
|
||||||
|
@chapter References to Non-Free Software and Documentation
|
||||||
|
|
||||||
|
A GNU program should not recommend use of any non-free program. We
|
||||||
|
can't stop some people from writing proprietary programs, or stop other
|
||||||
|
people from using them. But we can and should avoid helping to
|
||||||
|
advertise them to new customers.
|
||||||
|
|
||||||
|
Sometimes it is important to mention how to build your package on top of
|
||||||
|
some non-free operating system or other non-free base package. In such
|
||||||
|
cases, please mention the name of the non-free package or system in the
|
||||||
|
briefest possible way. Don't include any references for where to find
|
||||||
|
more information about the proprietary program. The goal should be that
|
||||||
|
people already using the proprietary program will get the advice they
|
||||||
|
need about how to use your free program, while people who don't already
|
||||||
|
use the proprietary program will not see anything to encourage them to
|
||||||
|
take an interest in it.
|
||||||
|
|
||||||
|
Likewise, a GNU package should not refer the user to any non-free
|
||||||
|
documentation for free software. The need for free documentation to go
|
||||||
|
with free software is now a major focus of the GNU project; to show that
|
||||||
|
we are serious about the need for free documentation, we must not
|
||||||
|
undermine our position by recommending use of documentation that isn't
|
||||||
|
free.
|
||||||
|
|
||||||
@contents
|
@contents
|
||||||
|
|
||||||
@bye
|
@bye
|
||||||
|
|
Loading…
Reference in New Issue