X-Git-Url: https://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fstandards.texi;h=6978e51ece505f85a4a0e4cd31dfda23befff521;hb=a0f402b76e57d57abd1961f20683a25d46179297;hp=60a0ea2c8f5b38a1d081175d3013cf0e4e3e174b;hpb=5b1ef1fd0197758898074b20a052b7bfee9a1b25;p=gnulib.git diff --git a/doc/standards.texi b/doc/standards.texi index 60a0ea2c8..6978e51ec 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate June 1, 2012 +@set lastupdate January 1, 2013 @c %**end of header @dircategory GNU organization @@ -28,7 +28,7 @@ The GNU coding standards, last updated @value{lastupdate}. Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, -2011, 2012 Free Software Foundation, Inc. +2011, 2012, 2013 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -339,20 +339,21 @@ system. @node Compatibility @section Compatibility with Other Implementations -@cindex compatibility with C and @sc{posix} standards -@cindex @sc{posix} compatibility +@cindex compatibility with C and POSIX standards +@cindex C compatibility +@cindex POSIX compatibility With occasional exceptions, utility programs and libraries for GNU should be upward compatible with those in Berkeley Unix, and upward compatible with Standard C if Standard C specifies their -behavior, and upward compatible with @sc{posix} if @sc{posix} specifies +behavior, and upward compatible with POSIX if POSIX specifies their behavior. When these standards conflict, it is useful to offer compatibility modes for each of them. @cindex options for compatibility -Standard C and @sc{posix} prohibit many kinds of extensions. Feel +Standard C and POSIX prohibit many kinds of extensions. Feel free to make the extensions anyway, and include a @samp{--ansi}, @samp{--posix}, or @samp{--compatible} option to turn them off. However, if the extension has a significant chance of breaking any real @@ -360,7 +361,7 @@ programs or scripts, then it is not really upward compatible. So you should try to redesign its interface to make it upward compatible. @cindex @code{POSIXLY_CORRECT}, environment variable -Many GNU programs suppress extensions that conflict with @sc{posix} if the +Many GNU programs suppress extensions that conflict with POSIX if the environment variable @code{POSIXLY_CORRECT} is defined (even if it is defined with a null value). Please make your program recognize this variable if appropriate. @@ -408,18 +409,24 @@ already. That would be extremely troublesome in certain cases. @node Standard C @section Standard C and Pre-Standard C -@cindex @sc{ansi} C standard +@cindex ANSI C standard 1989 Standard C is widespread enough now that it is ok to use its -features in new programs. There is one exception: do not ever use the +features in programs. There is one exception: do not ever use the ``trigraph'' feature of Standard C. -1999 Standard C is not widespread yet, so please do not require its -features in programs. It is ok to use its features if they are present. +The 1999 and 2011 editions of Standard C are not fully supported +on all platforms. If you aim to support compilation by +compilers other than GCC, you should not require these C +features in your programs. It is ok to use these features +conditionally when the compiler supports them. + +If your program is only meant to compile with GCC, then you can +use these features if GCC supports them, when they give substantial +benefit. However, it is easy to support pre-standard compilers in most programs, -so if you know how to do that, feel free. If a program you are -maintaining has such support, you should try to keep it working. +so if you know how to do that, feel free. @cindex function prototypes To support pre-standard C, instead of writing function definitions in @@ -664,10 +671,10 @@ These are supported compatibly by GNU. @cindex signal handling The preferred signal handling facilities are the BSD variant of -@code{signal}, and the @sc{posix} @code{sigaction} function; the +@code{signal}, and the POSIX @code{sigaction} function; the alternative USG @code{signal} interface is an inferior design. -Nowadays, using the @sc{posix} signal functions may be the easiest way +Nowadays, using the POSIX signal functions may be the easiest way to make a program portable. If you use @code{signal}, then on GNU/Linux systems running GNU libc version 1, you should include @file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD @@ -900,11 +907,11 @@ the graphical interface, these won't be much extra work. @cindex command-line interface @findex getopt -It is a good idea to follow the @sc{posix} guidelines for the +It is a good idea to follow the POSIX guidelines for the command-line options of a program. The easiest way to do this is to use @code{getopt} to parse them. Note that the GNU version of @code{getopt} will normally permit options anywhere among the arguments unless the -special argument @samp{--} is used. This is not what @sc{posix} +special argument @samp{--} is used. This is not what POSIX specifies; it is a GNU extension. @cindex long-named options @@ -1047,7 +1054,8 @@ have legal significance. Finally, here is the table of our suggested license abbreviations. Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning that particular version, or later versions with the @samp{+}, as shown -above. +above. In the case of a GNU license, @emph{always} indicate the permitted +versions in this way. In the case of exceptions for extra permissions with the GPL, we use @samp{/} for a separator; the version number can follow the license @@ -2864,7 +2872,7 @@ versions. For a GNU program, this kind of portability is desirable, but not paramount. The primary purpose of GNU software is to run on top of the GNU kernel, -compiled with the GNU C compiler, on various types of @sc{cpu}. So the +compiled with the GNU C compiler, on various types of CPU. So the kinds of portability that are absolutely necessary are quite limited. But it is important to support Linux-based GNU systems, since they are the form of GNU that is popular. @@ -2886,7 +2894,7 @@ written. Avoid using the format of semi-internal data bases (e.g., directories) when there is a higher-level alternative (@code{readdir}). -@cindex non-@sc{posix} systems, and portability +@cindex non-POSIX systems, and portability As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS, and older Macintosh systems, supporting them is often a lot of work. When that is the case, it is better to spend your time adding features @@ -2915,11 +2923,11 @@ using their names for any other meanings. Doing so would make it hard to move your code into other GNU programs. @node CPU Portability -@section Portability between @sc{cpu}s +@section Portability between CPUs @cindex data types, and portability @cindex portability, and data types -Even GNU systems will differ because of differences among @sc{cpu} +Even GNU systems will differ because of differences among CPU types---for example, difference in byte ordering and alignment requirements. It is absolutely essential to handle these differences. However, don't make any effort to cater to the possibility that an @@ -2990,12 +2998,12 @@ from zero. Historically, C implementations differed substantially, and many systems lacked a full implementation of ANSI/ISO C89. Nowadays, -however, very few systems lack a C89 compiler and GNU C supports -almost all of C99. Similarly, most systems implement POSIX.1-1993 -libraries and tools, and many have POSIX.1-2001. +however, all practical systems have a C89 compiler and GNU C supports +almost all of C99 and some of C11. Similarly, most systems implement +POSIX.1-2001 libraries and tools, and many have POSIX.1-2008. Hence, there is little reason to support old C or non-POSIX systems, -and you may want to take advantage of C99 and POSIX-1.2001 to write +and you may want to take advantage of standard C and POSIX to write clearer, more portable, or faster code. You should use standard interfaces where possible; but if GNU extensions make your program more maintainable, powerful, or otherwise better, don't hesitate to @@ -3541,6 +3549,16 @@ explanation of how the earlier version differed. Each @dfn{entry} in a change log describes either an individual change or the smallest batch of changes that belong together, also known as a @dfn{change set}. +@cindex title, change log entry +@cindex description, change log entry +For later reference or for summarizing, sometimes it is useful to +start the entry with a one-line description (sometimes called a +@dfn{title}) to describe its overall purpose. + +In the past, we recommended not mentioning changes in non-software +files (manuals, help files, media files, etc.)@: in change logs. +However, we've been advised that it is a good idea to include them, +for the sake of copyright records. The change log file is normally called @file{ChangeLog} and covers an entire directory. Each directory can have its own change log, or a @@ -3552,20 +3570,18 @@ control system such as RCS or CVS. This can be converted automatically to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command @kbd{C-x v a} (@code{vc-update-change-log}) does the job. -There's no need to describe the full purpose of the changes or how -they work together. However, sometimes it is useful to write one line -to describe the overall purpose of a change log entry. If -you think that a change calls for explanation, you're probably right. -Please do explain it---but please put the full explanation in comments -in the code, where people will see it whenever they see the code. For -example, ``New function'' is enough for the change log when you add a -function, because there should be a comment before the function -definition to explain what it does. +For changes to code, there's no need to describe the full purpose of +the changes or how they work together. If you think that a change +calls for explanation, you're probably right. Please do explain +it---but please put the full explanation in comments in the code, +where people will see it whenever they see the code. For example, +``New function'' is enough for the change log when you add a function, +because there should be a comment before the function definition to +explain what it does. -In the past, we recommended not mentioning changes in non-software -files (manuals, help files, media files, etc.)@: in change logs. -However, we've been advised that it is a good idea to include them, -for the sake of copyright records. +For changes to files that do not support a comment syntax (e.g., media +files), it is ok to include the full explanation in the change log file, +after the title and before the list of individual changes. The easiest way to add an entry to @file{ChangeLog} is with the Emacs command @kbd{M-x add-change-log-entry}. An individual change should @@ -4055,6 +4071,7 @@ ignore most of its arguments. @section Making Releases @cindex packaging +@cindex version numbers, for releases You should identify each release with a pair of version numbers, a major version and a minor. We have no objection to using more than two numbers, but it is very unlikely that you really need them. @@ -4071,20 +4088,28 @@ and never changed automatically; non-source files are produced from source files by programs under the control of the Makefile. @cindex @file{README} file -The distribution should contain a file named @file{README} which gives -the name of the package, and a general description of what it does. It -is also good to explain the purpose of each of the first-level -subdirectories in the package, if there are any. The @file{README} file -should either state the version number of the package, or refer to where -in the package it can be found. - -The @file{README} file should refer to the file @file{INSTALL}, which -should contain an explanation of the installation procedure. - -The @file{README} file should also refer to the file which contains the -copying conditions. The GNU GPL, if used, should be in a file called -@file{COPYING}. If the GNU LGPL is used, it should be in a file called +The distribution should contain a file named @file{README} with a +general overview of the package: + +@itemize +@item the name of the package; + +@item the version number of the package, or refer to where in the +package the version can be found; + +@item a general description of what the package does; + +@item a reference to the file @file{INSTALL}, which +should in turn contain an explanation of the installation procedure; + +@item a brief explanation of any unusual top-level directories or +files, or other hints for readers to find their way around the source; + +@item a reference to the file which contains the copying conditions. +The GNU GPL, if used, should be in a file called @file{COPYING}. If +the GNU LGPL is used, it should be in a file called @file{COPYING.LESSER}. +@end itemize Naturally, all the source files must be in the distribution. It is okay to include non-source files in the distribution along with the @@ -4092,9 +4117,10 @@ source files they are generated from, provided they are up-to-date with the source they are made from, and machine-independent, so that normal building of the distribution will never modify them. We commonly include non-source files produced by Autoconf, Automake, -Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid +Bison, @code{flex}, @TeX{}, and @code{makeinfo}; this helps avoid unnecessary dependencies between our distributions, so that users can -install whichever packages they want to install. +install whichever versions of whichever packages they like. Do not +induce new dependencies on other software lightly. Non-source files that might actually be modified by building and installing the program should @strong{never} be included in the