From: K. Richard Pixley Date: Mon, 6 Jul 1992 23:25:46 +0000 (+0000) Subject: updated to July 1 X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=3e12f39a38edd5a888e20ece43b74f096dcd9eee;p=binutils-gdb.git updated to July 1 --- diff --git a/standards.texi b/standards.texi index 00786440d24..d808af0b56e 100644 --- a/standards.texi +++ b/standards.texi @@ -34,7 +34,7 @@ by the Free Software Foundation. @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 @@ -57,16 +57,10 @@ by Free Software Foundation. @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 @@ -74,7 +68,7 @@ Last updated 16 May 1992. * 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 @@ -223,7 +217,7 @@ need not know the history of the erroneous passage. @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 @@ -315,6 +309,7 @@ should instead be written as 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 @@ -326,8 +321,6 @@ foo.1 : foo.man sedscript sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1 @end example - - @node Standard Targets @section Standard Targets for Users @@ -411,15 +404,38 @@ Thus, if you use Bison, have a variable named @code{BISON} whose default 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. @@ -431,13 +447,14 @@ for actual installation, for executables and nonexecutables 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 @@ -499,8 +516,8 @@ Most compilers other than GCC do not look for header files in 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 @@ -557,6 +574,18 @@ libdir = $(exec_prefix)/lib 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 @@ -1060,7 +1089,7 @@ extensions in implementing your program is a difficult question. 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. @@ -1212,7 +1241,7 @@ other; then they can both go in the same file. 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