\input texinfo @c -*-texinfo-*-
@c %**start of header
-@setfilename standards.text
+@setfilename standards.info
@settitle GNU Coding Standards
@c %**end of header
+@ifinfo
+@format
+START-INFO-DIR-ENTRY
+* standards: (standards). GNU Project Coding Standards
+END-INFO-DIR-ENTRY
+@end format
+@end ifinfo
+
+
@setchapternewpage off
@ifinfo
@sp 10
@titlefont{GNU Coding Standards}
@author{Richard Stallman}
-@author{last updated 21 April 1992}
+@author{last updated 16 Jul 1992}
@c Note date also appears below.
@page
@node Top, Reading Non-Free Code, (dir), (dir)
@top Version
-Last updated 21 April 1992.
+Last updated 16 Jul 1992.
@c Note date also appears above.
@end ifinfo
* Reading Non-Free Code:: Referring to Proprietary Programs
* Contributions:: Accepting Contributions
* Change Logs:: Recording Changes
-* Compatibility:: Compatibility with Other Implementations
+* Compatibility:: Compatibility with Other Implementations
* Makefiles:: Makefile Conventions
* Configuration:: How Configuration Should Work
* Source Language:: Using Languages Other Than C
However, sometimes it is useful to write one line to describe the
overall purpose of a large 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.
+
When you change the calling sequence of a function in a simple
fashion, and you change all the callers of the function, there is no
need to make individual entries for all the callers. Just write in
@node Compatibility
-@chapter Compatibility with Other Implementations
+@chapter Compatibility with Other Implementations
With certain exceptions, utility programs and libraries for GNU should
be upward compatible with those in Berkeley Unix, and upward compatible
inherited from the environment.
Don't assume that @file{.} is in the path for command execution. When
-you need to run programs that are files in the current directory, always
-use @file{./} to make sure the proper file is run regardless of the
-current path.
+you need to run programs that are a part of your package during the
+make, please make sure that it uses @file{./} if the program is built as
+part of the make or @file{$(srcdir)/} if the file is an unchanging part
+of the source code. Without one of these prefixes, the current search
+path is used.
+
+The distinction between @file{./} and @file{$(srcdir)/} is important
+when using the @samp{--srcdir} option to @file{configure}. A rule of
+the form:
+
+@example
+foo.1 : foo.man sedscript
+ sed -e sedscript foo.man > foo.1
+@end example
+
+@noindent
+will fail when the current directory is not the source directory,
+because @file{foo.man} and @file{sedscript} are not in the current
+directory.
+
+Relying on @samp{VPATH} to find the source file will work in the case
+where there is a single dependency file, since the @file{make} automatic
+variable @samp{$<} will represent the source file wherever it is. A
+makefile target like
+
+@example
+foo.o : bar.c
+ $(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o
+@end example
+
+@noindent
+should instead be written as
+
+@example
+foo.o : bar.c
+ $(CC) $(CFLAGS) $< -o $@
+@end example
+
+@noindent
+in order to allow @samp{VPATH} to work correctly. When the target has
+multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
+way to make the rule work well. For example, the target above for
+@file{foo.1} is best written as:
+
+@example
+foo.1 : foo.man sedscript
+ sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
+@end example
@node Standard Targets
@section Standard Targets for Users
simple test to verify that a program is properly installed then run that
test.
+Use @samp{-} before any command for installing a man page, so that
+@code{make} will ignore any errors. This is in case there are systems
+that don't have the Unix man page documentation system installed.
+
@item clean
Delete all files from the current directory that are normally created by
building the program. Don't delete the files that record the
configuration. Also preserve files that could be made by building, but
normally aren't because the distribution comes with them.
+Delete @file{.dvi} files here if they are not part of the distribution.
+
@item distclean
Delete all files from the current directory that are created by
-configuring or building the program. This should leave only the files
-that would be in the distribution.
+configuring or building the program. If you have unpacked the source
+and built the program without creating any other files, @samp{make
+distclean} should leave only the files that were in the distribution.
@item mostlyclean
Like @samp{clean}, but may refrain from deleting a few files that people
value is set with @samp{BISON = bison}, and refer to it with
@code{$(BISON)} whenever you need to use Bison.
+File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
+so on, need not be referred to through variables in this way, since users
+don't need to replace them with other programs.
+
Each program-name variable should come with an options variable that is
used to supply options to the program. Append @samp{FLAGS} to the
program-name variable name to get the options variable name---for
example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
-this rule, but we keep it because it is standard.)
+this rule, but we keep it because it is standard.) Use @code{CPPFLAGS}
+in any compilation command that runs the preprocessor, and use
+@code{LDFLAGS} in any compilation command that does linking as well as
+in any direct use of @code{ld}.
+
+If there are C compiler options that @emph{must} be used for proper
+compilation of certain files, do not include them in @code{CFLAGS}.
+Users expect to be able to specify @code{CFLAGS} freely themselves.
+Instead, arrange to pass the necessary options to the C compiler
+independently of @code{CFLAGS}, by writing them explicitly in the
+compilation commands or by defining an implicit rule, like this:
-File-management utilities such as @code{ln}, @code{rm}, @code{mv}, and
-so on need not be referred to through variables in this way, since users
-don't need to replace them with other programs.
+@example
+CFLAGS = -g
+ALL_CFLAGS = $(CFLAGS) -I.
+.c.o:
+ $(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $<
+@end example
+
+Do include the @samp{-g} option in @code{CFLAGS}, because that is not
+@emph{required} for proper compilation. You can consider it a default
+that is only recommended. If the package is set up so that it is
+compiled with GCC by default, then you might as well include @samp{-O}
+in the default value of @code{CFLAGS} as well.
Every Makefile should define the variable @code{INSTALL}, which is the
basic command for installing a file into the system.
respectively. Use these variables as follows:
@example
-$(INSTALL_PROGRAM) foo $@{bindir@}/foo
-$(INSTALL_DATA) libfoo.a $@{libdir@}/libfoo.a
+$(INSTALL_PROGRAM) foo $(bindir)/foo
+$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
@end example
@noindent
-(Always use a file name, not a directory name, as the second argument.
-Use a separate command for each file to be installed.)
+Always use a file name, not a directory name, as the second argument of
+the installation commands. Use a separate command for each file to be
+installed.
@node Directory Variables
@section Variables for Installation Directories
variables are:
@table @samp
+@item prefix
+A prefix used in constructing the default values of the variables listed
+below. The default value of @code{prefix} should be @file{/usr/local}
+(at least for now).
+
+@item exec_prefix
+A prefix used in constructing the default values of the some of the
+variables listed below. The default value of @code{exec_prefix} should
+be @code{$(prefix)}.
+
+Generally, @code{$(exec_prefix)} is used for directories that contain
+machine-specific files (such as executables and subroutine libraries),
+while @code{$(prefix)} is used directly for other directories.
+
@item bindir
The directory for installing executable programs that users can run.
-This should normally be @file{/usr/local/bin}, but it should be based on
-the value of @code{$(prefix)}.
+This should normally be @file{/usr/local/bin}, but it should be written
+as @file{$(exec_prefix)/bin}.
+
+@item libdir
+The directory for installing executable files to be run by the program
+rather than by users. Object files and libraries of object code should
+also go in this directory. The idea is that this directory is used for
+files that pertain to a specific machine architecture, but need not be
+in the path for commands. The value of @code{libdir} should normally be
+@file{/usr/local/lib}, but it should be written as
+@file{$(exec_prefix)/lib}.
@item datadir
The directory for installing read-only data files which the programs
refer to while they run. This directory is used for files which are
independent of the type of machine being used. This should normally be
-@file{/usr/local/lib}, but it should be based on the value of
-@code{$(prefix)}.
+@file{/usr/local/lib}, but it should be written as
+@file{$(prefix)/lib}.
@item statedir
The directory for installing data files which the programs modify while
they run. These files should be independent of the type of machine
being used, and it should be possible to share them among machines at a
network installation. This should normally be @file{/usr/local/lib},
-but it should be based on the value of @code{$(prefix)}.
-
-@item libdir
-The directory for installing executable files to be run by the program
-rather than by users. Object files and libraries of object code should
-also go in this directory. The idea is that this directory is used for
-files that pertain to a specific machine architecture. This should
-normally be @file{/usr/local/lib}, but it should be based on the value of
-@code{$(prefix)}.
+but it should be written as @file{$(prefix)/lib}.
@item includedir
The directory for installing @samp{#include} header files to be included
by user programs. This should normally be @file{/usr/local/include},
-but it should be based on the value of @code{$(prefix)}.
+but it should be written as @file{$(prefix)/include}.
Most compilers other than GCC do not look for header files in
@file{/usr/local/include}. So installing the header files this way is
only useful with GCC. Sometimes this is not a problem because some
libraries are only really intended to work with GCC. But some libraries
are intended to work with other compilers. They should install their
-header files in two places, one specified by includedir and one
-specified by oldincludedir
+header files in two places, one specified by @code{includedir} and one
+specified by @code{oldincludedir}.
@item oldincludedir
The directory for installing @samp{#include} header files for use with
@item infodir
The directory for installing the info files for this package. By
-default, it should be @file{/usr/local/info}, but it should be based on the
-value of @code{$(prefix)}.
+default, it should be @file{/usr/local/info}, but it should be written
+as @file{$(prefix)/info}.
@item srcdir
The directory for the sources being compiled. The value of this
variable is normally inserted by the @code{configure} shell script.
-
-@item prefix
-A prefix used in constructing the default values of the variables listed
-above. The default value of @code{prefix} should be @file{/usr/local}
-(at least for now).
@end table
For example:
# Common prefix for installation directories.
# NOTE: This directory must exist when you start installation.
prefix = /usr/local
+exec_prefix = $(prefix)
# Directory in which to put the executable for the command `gcc'
-bindir = $(prefix)/bin
+bindir = $(exec_prefix)/bin
# Directory in which to put the directories used by the compiler.
-libdir = $(prefix)/lib
+libdir = $(exec_prefix)/lib
+# Directory in which to put the Info files.
+infodir = $(prefix)/info
@end example
+If your program installs a large number of files into one of the
+standard user-specified directories, it might be useful to group them
+into a subdirectory particular to that program. If you do this, you
+should write the @code{install} rule to create these subdirectories.
+
+Do not expect the user to include the subdirectory name in the value of
+any of the variables listed above. The idea of having a uniform set of
+variable names for installation directories is to enable the user to
+specify the exact same values for several different GNU packages. In
+order for this to be useful, all the packages must be designed so that
+they will work sensibly when the user does so.
@node Configuration
@chapter How Configuration Should Work
The @code{configure} script needs to be able to decode all plausible
alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
-would be a valid alias. So would @samp{sun3-bsd4.2}, since Sunos is
+would be a valid alias. So would @samp{sun3-bsd4.2}, since SunOS is
basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. For many
programs, @samp{vax-dec-ultrix} would be an alias for
@samp{vax-dec-bsd}, simply because the differences between Ultrix and
On the one hand, using the extensions can make a cleaner program.
On the other hand, people will not be able to build the program
-unless the other GNU tools are available. This might cause the
+unless the other GNU tools are available. This might cause the
program to work on fewer kinds of machines.
With some extensions, it might be easy to provide both alternatives.
Try to avoid low-level interfaces to obscure Unix data structures (such
as file directories, utmp, or the layout of kernel memory), since these
are less likely to work compatibly. If you need to find all the files
-in a directory, use @code{readdir} or some other high-level interface. These
-will be supported compatibly by GNU.
+in a directory, use @code{readdir} or some other high-level interface.
+These will be supported compatibly by GNU.
-By default, the GNU system will provide the signal handling
-functions of @sc{BSD} and of @sc{POSIX}. So GNU software should be
-written to use these.
+By default, the GNU system will provide the signal handling functions of
+@sc{BSD} and of @sc{POSIX}. So GNU software should be written to use
+these.
In error checks that detect ``impossible'' conditions, just abort.
There is usually no point in printing any message. These checks
External symbols that are not documented entry points for the user
should have names beginning with @samp{_}. They should also contain
the chosen name prefix for the library, to prevent collisions with
-other libraries. These can go in the same files with user entry
+other libraries. These can go in the same files with user entry
points if you like.
Static functions and variables can be used as you like and need not
@chapter Portability As It Applies to GNU
Much of what is called ``portability'' in the Unix world refers to
-porting to different Unix versions. This is not relevant to GNU
-software, because its purpose is to run on top of one and only
-one kernel, the GNU kernel, compiled with one and only one C
-compiler, the GNU C compiler. The amount and kinds of variation
-among GNU systems on different cpu's will be like the variation
-among Berkeley 4.3 systems on different cpu's.
+porting to different Unix versions. This is a secondary consideration
+for GNU software, because its primary purpose is to run on top of one
+and only one kernel, the GNU kernel, compiled with one and only one C
+compiler, the GNU C compiler. The amount and kinds of variation among
+GNU systems on different cpu's will be like the variation among Berkeley
+4.3 systems on different cpu's.
+
+All users today run GNU software on non-GNU systems. So supporting a
+variety of non-GNU systems is desirable; simply not paramount.
+The easiest way to achieve portability to a reasonable range of systems
+is to use Autoconf. It's unlikely that your program needs to know more
+information about the host machine than Autoconf can provide, simply
+because most of the programs that need such knowledge have already been
+written.
It is difficult to be sure exactly what facilities the GNU kernel
will provide, since it isn't finished yet. Therefore, assume you can
Please use Texinfo for documenting GNU programs. See the Texinfo
manual, either the hardcopy or the version in the GNU Emacs Info
-sub-system (@kbd{C-h i}).
-
-See existing GNU texinfo files (e.g. those under the @file{man/}
-directory in the GNU Emacs Distribution) for examples.
+subsystem (@kbd{C-h i}). See existing GNU Texinfo files (e.g. those
+under the @file{man/} directory in the GNU Emacs Distribution) for
+examples.
The title page of the manual should state the version of the program
which the manual applies to. The Top node of the manual should also
Address the goals that a user will have in mind, and explain how to
accomplish them.
+In addition to its manual, the package should have a file named
+@file{NEWS} which contains a list of user-visible changes worth
+mentioning. In each new release, add items to the front of the file,
+and identify the version they pertain to. Don't discard old items.
+This way, a user upgrading from any previous version can see what
+is new.
@node Releases
@chapter Making Releases
period and up to three characters. MS-DOG will truncate extra
characters both before and after the period. Thus,
@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
-are truncated to @file{foobarhac.c} and @file{foobarhac.o}, which are
+are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
distinct.
Include in your distribution a copy of the @file{texinfo.tex} you used
to test print any @file{*.texinfo} files.
+Likewise, if your program uses small GNU software packages like regex,
+getopt, obstack, or termcap, include them in the distribution file.
+Leaving them out would make the distribution file a little smaller at
+the expense of possible inconvenience to a user who doesn't know what
+other files to get.
@bye
projects / deliverable / binutils-gdb.git / blobdiff