\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 16 May 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 16 May 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
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
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
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
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.
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
projects / deliverable / binutils-gdb.git / blobdiff