@sp 10
@titlefont{GNU Coding Standards}
@author{Richard Stallman}
-@author{last updated 16 May 1992}
+@author{last updated 1 Jul 1992}
@c Note date also appears below.
@page
@end titlepage
@ifinfo
-@format
-START-INFO-DIR-ENTRY
-* standards: (standards.info). GNU Project Coding Standards
-END-INFO-DIR-ENTRY
-@end format
-
@node Top, Reading Non-Free Code, (dir), (dir)
@top Version
-Last updated 16 May 1992.
+Last updated 1 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
@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
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
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
projects / binutils-gdb.git / commitdiff