X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=standards.texi;h=69eaa531498cbe1779a61ef1004941558abebb5d;hb=c7c9407366c9e9b97d27427978870f4b81d7ed5e;hp=93a7c5b526c5de72f228ffe9272dad9306c5be76;hpb=9dec541731bcce65a2048059e74477b1127c4485;p=deliverable%2Fbinutils-gdb.git diff --git a/standards.texi b/standards.texi index 93a7c5b526..69eaa53149 100644 --- a/standards.texi +++ b/standards.texi @@ -1,9 +1,18 @@ \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 @@ -34,7 +43,7 @@ by the Free Software Foundation. @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 @@ -60,7 +69,7 @@ by Free Software Foundation. @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 @@ -68,7 +77,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 @@ -202,6 +211,12 @@ comment with the function in the source to explain what it does. 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 @@ -217,7 +232,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 @@ -272,9 +287,54 @@ to avoid trouble on systems where the @code{SHELL} variable might be 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 @@ -359,15 +419,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. @@ -379,13 +462,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 @@ -447,8 +531,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 @@ -505,6 +589,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 @@ -1008,7 +1104,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. @@ -1160,7 +1256,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 @@ -1171,12 +1267,20 @@ fit any naming convention. @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 @@ -1267,10 +1371,9 @@ option usage information. 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 @@ -1285,6 +1388,12 @@ concepts a user will have before reaching that point in the manual. 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 @@ -1323,7 +1432,7 @@ name on MS-DOG consists of up to 8 characters, optionally followed by a 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