1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename standards.info 4@settitle GNU Coding Standards 5@c This date is automagically updated when you save this file: 6@set lastupdate December 17, 2013 7@c %**end of header 8 9@dircategory GNU organization 10@direntry 11* Standards: (standards). GNU coding standards. 12@end direntry 13 14@c @setchapternewpage odd 15@setchapternewpage off 16 17@c Put everything in one index (arbitrarily chosen to be the concept index). 18@syncodeindex fn cp 19@syncodeindex ky cp 20@syncodeindex pg cp 21@syncodeindex vr cp 22 23@c This is used by a cross ref in make-stds.texi 24@set CODESTD 1 25 26@copying 27The GNU coding standards, last updated @value{lastupdate}. 28 29Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 302000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 312011, 2012, 2013 Free Software Foundation, Inc. 32 33Permission is granted to copy, distribute and/or modify this document 34under the terms of the GNU Free Documentation License, Version 1.3 or 35any later version published by the Free Software Foundation; with no 36Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 37Texts. A copy of the license is included in the section entitled 38``GNU Free Documentation License''. 39@end copying 40 41@titlepage 42@title GNU Coding Standards 43@author Richard Stallman, et al. 44@author last updated @value{lastupdate} 45@page 46@vskip 0pt plus 1filll 47@insertcopying 48@end titlepage 49 50@contents 51 52@ifnottex 53@node Top 54@top GNU Coding Standards 55 56@insertcopying 57@end ifnottex 58 59@menu 60* Preface:: About the GNU Coding Standards. 61* Legal Issues:: Keeping free software free. 62* Design Advice:: General program design. 63* Program Behavior:: Program behavior for all programs 64* Writing C:: Making the best use of C. 65* Documentation:: Documenting programs. 66* Managing Releases:: The release process. 67* References:: Mentioning non-free software or documentation. 68* GNU Free Documentation License:: Copying and sharing this manual. 69* Index:: 70 71@end menu 72 73@node Preface 74@chapter About the GNU Coding Standards 75 76The GNU Coding Standards were written by Richard Stallman and other GNU 77Project volunteers. Their purpose is to make the GNU system clean, 78consistent, and easy to install. This document can also be read as a 79guide to writing portable, robust and reliable programs. It focuses on 80programs written in C, but many of the rules and principles are useful 81even if you write in another programming language. The rules often 82state reasons for writing in a certain way. 83 84@cindex where to obtain @code{standards.texi} 85@cindex downloading this manual 86If you did not obtain this file directly from the GNU project and 87recently, please check for a newer version. You can get the GNU 88Coding Standards from the GNU web server in many 89different formats, including the Texinfo source, PDF, HTML, DVI, plain 90text, and more, at: @uref{http://www.gnu.org/prep/standards/}. 91 92If you are maintaining an official GNU package, in addition to this 93document, please read and follow the GNU maintainer information 94(@pxref{Top, , Contents, maintain, Information for Maintainers of GNU 95Software}). 96 97@cindex @code{gnustandards-commit@@gnu.org} mailing list 98If you want to receive diffs for every change to these GNU documents, 99join the mailing list @code{gnustandards-commit@@gnu.org}, via the web 100interface at 101@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}. 102Archives are also available there. 103 104@cindex @code{bug-standards@@gnu.org} email address 105@cindex Savannah repository for gnustandards 106@cindex gnustandards project repository 107Please send corrections or suggestions for this document to 108@email{bug-standards@@gnu.org}. If you make a suggestion, please 109include a suggested new wording for it, to help us consider the 110suggestion efficiently. We prefer a context diff to the Texinfo 111source, but if that's difficult for you, you can make a context diff 112for some other version of this document, or propose it in any way that 113makes it clear. The source repository for this document can be found 114at @url{http://savannah.gnu.org/projects/gnustandards}. 115 116These standards cover the minimum of what is important when writing a 117GNU package. Likely, the need for additional standards will come up. 118Sometimes, you might suggest that such standards be added to this 119document. If you think your standards would be generally useful, please 120do suggest them. 121 122You should also set standards for your package on many questions not 123addressed or not firmly specified here. The most important point is to 124be self-consistent---try to stick to the conventions you pick, and try 125to document them as much as possible. That way, your program will be 126more maintainable by others. 127 128The GNU Hello program serves as an example of how to follow the GNU 129coding standards for a trivial program. 130@uref{http://www.gnu.org/software/hello/hello.html}. 131 132This release of the GNU Coding Standards was last updated 133@value{lastupdate}. 134 135 136@node Legal Issues 137@chapter Keeping Free Software Free 138@cindex legal aspects 139 140This chapter discusses how you can make sure that GNU software 141avoids legal difficulties, and other related issues. 142 143@menu 144* Reading Non-Free Code:: Referring to proprietary programs. 145* Contributions:: Accepting contributions. 146* Trademarks:: How we deal with trademark issues. 147@end menu 148 149@node Reading Non-Free Code 150@section Referring to Proprietary Programs 151@cindex proprietary programs 152@cindex avoiding proprietary code 153 154Don't in any circumstances refer to Unix source code for or during 155your work on GNU! (Or to any other proprietary programs.) 156 157If you have a vague recollection of the internals of a Unix program, 158this does not absolutely mean you can't write an imitation of it, but 159do try to organize the imitation internally along different lines, 160because this is likely to make the details of the Unix version 161irrelevant and dissimilar to your results. 162 163For example, Unix utilities were generally optimized to minimize 164memory use; if you go for speed instead, your program will be very 165different. You could keep the entire input file in memory and scan it 166there instead of using stdio. Use a smarter algorithm discovered more 167recently than the Unix program. Eliminate use of temporary files. Do 168it in one pass instead of two (we did this in the assembler). 169 170Or, on the contrary, emphasize simplicity instead of speed. For some 171applications, the speed of today's computers makes simpler algorithms 172adequate. 173 174Or go for generality. For example, Unix programs often have static 175tables or fixed-size strings, which make for arbitrary limits; use 176dynamic allocation instead. Make sure your program handles NULs and 177other funny characters in the input files. Add a programming language 178for extensibility and write part of the program in that language. 179 180Or turn some parts of the program into independently usable libraries. 181Or use a simple garbage collector instead of tracking precisely when 182to free memory, or use a new GNU facility such as obstacks. 183 184 185@node Contributions 186@section Accepting Contributions 187@cindex legal papers 188@cindex accepting contributions 189 190If the program you are working on is copyrighted by the Free Software 191Foundation, then when someone else sends you a piece of code to add to 192the program, we need legal papers to use it---just as we asked you to 193sign papers initially. @emph{Each} person who makes a nontrivial 194contribution to a program must sign some sort of legal papers in order 195for us to have clear title to the program; the main author alone is not 196enough. 197 198So, before adding in any contributions from other people, please tell 199us, so we can arrange to get the papers. Then wait until we tell you 200that we have received the signed papers, before you actually use the 201contribution. 202 203This applies both before you release the program and afterward. If 204you receive diffs to fix a bug, and they make significant changes, we 205need legal papers for that change. 206 207This also applies to comments and documentation files. For copyright 208law, comments and code are just text. Copyright applies to all kinds of 209text, so we need legal papers for all kinds. 210 211We know it is frustrating to ask for legal papers; it's frustrating for 212us as well. But if you don't wait, you are going out on a limb---for 213example, what if the contributor's employer won't sign a disclaimer? 214You might have to take that code out again! 215 216You don't need papers for changes of a few lines here or there, since 217they are not significant for copyright purposes. Also, you don't need 218papers if all you get from the suggestion is some ideas, not actual code 219which you use. For example, if someone sent you one implementation, but 220you write a different implementation of the same idea, you don't need to 221get papers. 222 223The very worst thing is if you forget to tell us about the other 224contributor. We could be very embarrassed in court some day as a 225result. 226 227We have more detailed advice for maintainers of GNU packages. If you 228have reached the stage of maintaining a GNU program (whether released 229or not), please take a look: @pxref{Legal Matters,,, maintain, 230Information for GNU Maintainers}. 231 232 233@node Trademarks 234@section Trademarks 235@cindex trademarks 236 237Please do not include any trademark acknowledgements in GNU software 238packages or documentation. 239 240Trademark acknowledgements are the statements that such-and-such is a 241trademark of so-and-so. The GNU Project has no objection to the basic 242idea of trademarks, but these acknowledgements feel like kowtowing, 243and there is no legal requirement for them, so we don't use them. 244 245What is legally required, as regards other people's trademarks, is to 246avoid using them in ways which a reader might reasonably understand as 247naming or labeling our own programs or activities. For example, since 248``Objective C'' is (or at least was) a trademark, we made sure to say 249that we provide a ``compiler for the Objective C language'' rather 250than an ``Objective C compiler''. The latter would have been meant as 251a shorter way of saying the former, but it does not explicitly state 252the relationship, so it could be misinterpreted as using ``Objective 253C'' as a label for the compiler rather than for the language. 254 255Please don't use ``win'' as an abbreviation for Microsoft Windows in 256GNU software or documentation. In hacker terminology, calling 257something a ``win'' is a form of praise. If you wish to praise 258Microsoft Windows when speaking on your own, by all means do so, but 259not in GNU software. Usually we write the name ``Windows'' in full, 260but when brevity is very important (as in file names and sometimes 261symbol names), we abbreviate it to ``w''. For instance, the files and 262functions in Emacs that deal with Windows start with @samp{w32}. 263 264@node Design Advice 265@chapter General Program Design 266@cindex program design 267 268This chapter discusses some of the issues you should take into 269account when designing your program. 270 271@c Standard or ANSI C 272@c 273@c In 1989 the American National Standards Institute (ANSI) standardized 274@c C as standard X3.159-1989. In December of that year the 275@c International Standards Organization ISO adopted the ANSI C standard 276@c making minor changes. In 1990 ANSI then re-adopted ISO standard 277@c C. This version of C is known as either ANSI C or Standard C. 278 279@c A major revision of the C Standard appeared in 1999. 280 281@menu 282* Source Language:: Which languages to use. 283* Compatibility:: Compatibility with other implementations. 284* Using Extensions:: Using non-standard features. 285* Standard C:: Using standard C features. 286* Conditional Compilation:: Compiling code only if a conditional is true. 287@end menu 288 289@node Source Language 290@section Which Languages to Use 291@cindex programming languages 292 293When you want to use a language that gets compiled and runs at high 294speed, the best language to use is C. C++ is ok too, but please don't 295make heavy use of templates. So is Java, if you compile it. 296 297When highest efficiency is not required, other languages commonly used 298in the free software community, such as Scheme, Python, Ruby, and 299Java, are OK too. Scheme, as implemented by GNU@tie{}Guile, plays a 300particular role in the GNU System: it is the preferred language to 301extend programs written in C/C++, and also a fine language for a wide 302range of applications. The more GNU components use Guile and Scheme, 303the more users are able to extend and combine them (@pxref{The Emacs 304Thesis,,, guile, GNU Guile Reference Manual}). 305 306Many programs are designed to be extensible: they include an interpreter 307for a language that is higher level than C. Often much of the program 308is written in that language, too. The Emacs editor pioneered this 309technique. 310 311@cindex Guile 312@cindex GNOME and Guile 313The standard extensibility interpreter for GNU software is Guile 314(@uref{http://www.gnu.org/@/software/@/guile/}), which implements the 315language Scheme (an especially clean and simple dialect of Lisp). 316Guile also includes bindings for GTK+/GNOME, making it practical to 317write modern GUI functionality within Guile. We don't reject programs 318written in other ``scripting languages'' such as Perl and Python, but 319using Guile is the path that will lead to overall consistency of the 320GNU system. 321 322 323@node Compatibility 324@section Compatibility with Other Implementations 325@cindex compatibility with C and POSIX standards 326@cindex C compatibility 327@cindex POSIX compatibility 328 329With occasional exceptions, utility programs and libraries for GNU 330should be upward compatible with those in Berkeley Unix, and upward 331compatible with Standard C if Standard C specifies their 332behavior, and upward compatible with POSIX if POSIX specifies 333their behavior. 334 335When these standards conflict, it is useful to offer compatibility 336modes for each of them. 337 338@cindex options for compatibility 339Standard C and POSIX prohibit many kinds of extensions. Feel 340free to make the extensions anyway, and include a @samp{--ansi}, 341@samp{--posix}, or @samp{--compatible} option to turn them off. 342However, if the extension has a significant chance of breaking any real 343programs or scripts, then it is not really upward compatible. So you 344should try to redesign its interface to make it upward compatible. 345 346@cindex @code{POSIXLY_CORRECT}, environment variable 347Many GNU programs suppress extensions that conflict with POSIX if the 348environment variable @code{POSIXLY_CORRECT} is defined (even if it is 349defined with a null value). Please make your program recognize this 350variable if appropriate. 351 352When a feature is used only by users (not by programs or command 353files), and it is done poorly in Unix, feel free to replace it 354completely with something totally different and better. (For example, 355@code{vi} is replaced with Emacs.) But it is nice to offer a compatible 356feature as well. (There is a free @code{vi} clone, so we offer it.) 357 358Additional useful features are welcome regardless of whether 359there is any precedent for them. 360 361@node Using Extensions 362@section Using Non-standard Features 363@cindex non-standard extensions 364 365Many GNU facilities that already exist support a number of convenient 366extensions over the comparable Unix facilities. Whether to use these 367extensions in implementing your program is a difficult question. 368 369On the one hand, using the extensions can make a cleaner program. 370On the other hand, people will not be able to build the program 371unless the other GNU tools are available. This might cause the 372program to work on fewer kinds of machines. 373 374With some extensions, it might be easy to provide both alternatives. 375For example, you can define functions with a ``keyword'' @code{INLINE} 376and define that as a macro to expand into either @code{inline} or 377nothing, depending on the compiler. 378 379In general, perhaps it is best not to use the extensions if you can 380straightforwardly do without them, but to use the extensions if they 381are a big improvement. 382 383An exception to this rule are the large, established programs (such as 384Emacs) which run on a great variety of systems. Using GNU extensions in 385such programs would make many users unhappy, so we don't do that. 386 387Another exception is for programs that are used as part of compilation: 388anything that must be compiled with other compilers in order to 389bootstrap the GNU compilation facilities. If these require the GNU 390compiler, then no one can compile them without having them installed 391already. That would be extremely troublesome in certain cases. 392 393@node Standard C 394@section Standard C and Pre-Standard C 395@cindex ANSI C standard 396 3971989 Standard C is widespread enough now that it is ok to use its 398features in programs. There is one exception: do not ever use the 399``trigraph'' feature of Standard C. 400 401The 1999 and 2011 editions of Standard C are not fully supported 402on all platforms. If you aim to support compilation by 403compilers other than GCC, you should not require these C 404features in your programs. It is ok to use these features 405conditionally when the compiler supports them. 406 407If your program is only meant to compile with GCC, then you can 408use these features if GCC supports them, when they give substantial 409benefit. 410 411However, it is easy to support pre-standard compilers in most programs, 412so if you know how to do that, feel free. 413 414@cindex function prototypes 415To support pre-standard C, instead of writing function definitions in 416standard prototype form, 417 418@example 419int 420foo (int x, int y) 421@dots{} 422@end example 423 424@noindent 425write the definition in pre-standard style like this, 426 427@example 428int 429foo (x, y) 430 int x, y; 431@dots{} 432@end example 433 434@noindent 435and use a separate declaration to specify the argument prototype: 436 437@example 438int foo (int, int); 439@end example 440 441You need such a declaration anyway, in a header file, to get the benefit 442of prototypes in all the files where the function is called. And once 443you have the declaration, you normally lose nothing by writing the 444function definition in the pre-standard style. 445 446This technique does not work for integer types narrower than @code{int}. 447If you think of an argument as being of a type narrower than @code{int}, 448declare it as @code{int} instead. 449 450There are a few special cases where this technique is hard to use. For 451example, if a function argument needs to hold the system type 452@code{dev_t}, you run into trouble, because @code{dev_t} is shorter than 453@code{int} on some machines; but you cannot use @code{int} instead, 454because @code{dev_t} is wider than @code{int} on some machines. There 455is no type you can safely use on all machines in a non-standard 456definition. The only way to support non-standard C and pass such an 457argument is to check the width of @code{dev_t} using Autoconf and choose 458the argument type accordingly. This may not be worth the trouble. 459 460In order to support pre-standard compilers that do not recognize 461prototypes, you may want to use a preprocessor macro like this: 462 463@example 464/* Declare the prototype for a general external function. */ 465#if defined (__STDC__) || defined (WINDOWSNT) 466#define P_(proto) proto 467#else 468#define P_(proto) () 469#endif 470@end example 471 472@node Conditional Compilation 473@section Conditional Compilation 474 475When supporting configuration options already known when building your 476program we prefer using @code{if (... )} over conditional compilation, 477as in the former case the compiler is able to perform more extensive 478checking of all possible code paths. 479 480For example, please write 481 482@smallexample 483 if (HAS_FOO) 484 ... 485 else 486 ... 487@end smallexample 488 489@noindent 490instead of: 491 492@smallexample 493 #ifdef HAS_FOO 494 ... 495 #else 496 ... 497 #endif 498@end smallexample 499 500A modern compiler such as GCC will generate exactly the same code in 501both cases, and we have been using similar techniques with good success 502in several projects. Of course, the former method assumes that 503@code{HAS_FOO} is defined as either 0 or 1. 504 505While this is not a silver bullet solving all portability problems, 506and is not always appropriate, following this policy would have saved 507GCC developers many hours, or even days, per year. 508 509In the case of function-like macros like @code{REVERSIBLE_CC_MODE} in 510GCC which cannot be simply used in @code{if (...)} statements, there is 511an easy workaround. Simply introduce another macro 512@code{HAS_REVERSIBLE_CC_MODE} as in the following example: 513 514@smallexample 515 #ifdef REVERSIBLE_CC_MODE 516 #define HAS_REVERSIBLE_CC_MODE 1 517 #else 518 #define HAS_REVERSIBLE_CC_MODE 0 519 #endif 520@end smallexample 521 522@node Program Behavior 523@chapter Program Behavior for All Programs 524 525This chapter describes conventions for writing robust 526software. It also describes general standards for error messages, the 527command line interface, and how libraries should behave. 528 529@menu 530* Non-GNU Standards:: We consider standards such as POSIX; 531 we don't "obey" them. 532* Semantics:: Writing robust programs. 533* Libraries:: Library behavior. 534* Errors:: Formatting error messages. 535* User Interfaces:: Standards about interfaces generally. 536* Graphical Interfaces:: Standards for graphical interfaces. 537* Command-Line Interfaces:: Standards for command line interfaces. 538* Dynamic Plug-In Interfaces:: Standards for dynamic plug-in interfaces. 539* Option Table:: Table of long options. 540* OID Allocations:: Table of OID slots for GNU. 541* Memory Usage:: When and how to care about memory needs. 542* File Usage:: Which files to use, and where. 543@end menu 544 545@node Non-GNU Standards 546@section Non-GNU Standards 547 548The GNU Project regards standards published by other organizations as 549suggestions, not orders. We consider those standards, but we do not 550``obey'' them. In developing a GNU program, you should implement 551an outside standard's specifications when that makes the GNU system 552better overall in an objective sense. When it doesn't, you shouldn't. 553 554In most cases, following published standards is convenient for 555users---it means that their programs or scripts will work more 556portably. For instance, GCC implements nearly all the features of 557Standard C as specified by that standard. C program developers would 558be unhappy if it did not. And GNU utilities mostly follow 559specifications of POSIX.2; shell script writers and users would be 560unhappy if our programs were incompatible. 561 562But we do not follow either of these specifications rigidly, and there 563are specific points on which we decided not to follow them, so as to 564make the GNU system better for users. 565 566For instance, Standard C says that nearly all extensions to C are 567prohibited. How silly! GCC implements many extensions, some of which 568were later adopted as part of the standard. If you want these 569constructs to give an error message as ``required'' by the standard, 570you must specify @samp{--pedantic}, which was implemented only so that 571we can say ``GCC is a 100% implementation of the standard'', not 572because there is any reason to actually use it. 573 574POSIX.2 specifies that @samp{df} and @samp{du} must output sizes by 575default in units of 512 bytes. What users want is units of 1k, so 576that is what we do by default. If you want the ridiculous behavior 577``required'' by POSIX, you must set the environment variable 578@samp{POSIXLY_CORRECT} (which was originally going to be named 579@samp{POSIX_ME_HARDER}). 580 581GNU utilities also depart from the letter of the POSIX.2 specification 582when they support long-named command-line options, and intermixing 583options with ordinary arguments. This minor incompatibility with 584POSIX is never a problem in practice, and it is very useful. 585 586In particular, don't reject a new feature, or remove an old one, 587merely because a standard says it is ``forbidden'' or ``deprecated''. 588 589 590@node Semantics 591@section Writing Robust Programs 592 593@cindex arbitrary limits on data 594Avoid arbitrary limits on the length or number of @emph{any} data 595structure, including file names, lines, files, and symbols, by allocating 596all data structures dynamically. In most Unix utilities, ``long lines 597are silently truncated''. This is not acceptable in a GNU utility. 598 599@cindex @code{NUL} characters 600@findex libiconv 601Utilities reading files should not drop NUL characters, or any other 602nonprinting characters @emph{including those with codes above 0177}. 603The only sensible exceptions would be utilities specifically intended 604for interface to certain types of terminals or printers that can't 605handle those characters. Whenever possible, try to make programs work 606properly with sequences of bytes that represent multibyte characters; 607UTF-8 is the most important. 608 609@cindex error messages 610Check every system call for an error return, unless you know you wish 611to ignore errors. Include the system error text (from @code{perror}, 612@code{strerror}, or equivalent) in @emph{every} error message 613resulting from a failing system call, as well as the name of the file 614if any and the name of the utility. Just ``cannot open foo.c'' or 615``stat failed'' is not sufficient. 616 617@cindex @code{malloc} return value 618@cindex memory allocation failure 619Check every call to @code{malloc} or @code{realloc} to see if it 620returned zero. Check @code{realloc} even if you are making the block 621smaller; in a system that rounds block sizes to a power of 2, 622@code{realloc} may get a different block if you ask for less space. 623 624In Unix, @code{realloc} can destroy the storage block if it returns 625zero. GNU @code{realloc} does not have this bug: if it fails, the 626original block is unchanged. Feel free to assume the bug is fixed. If 627you wish to run your program on Unix, and wish to avoid lossage in this 628case, you can use the GNU @code{malloc}. 629 630You must expect @code{free} to alter the contents of the block that was 631freed. Anything you want to fetch from the block, you must fetch before 632calling @code{free}. 633 634If @code{malloc} fails in a noninteractive program, make that a fatal 635error. In an interactive program (one that reads commands from the 636user), it is better to abort the command and return to the command 637reader loop. This allows the user to kill other processes to free up 638virtual memory, and then try the command again. 639 640@cindex command-line arguments, decoding 641Use @code{getopt_long} to decode arguments, unless the argument syntax 642makes this unreasonable. 643 644When static storage is to be written in during program execution, use 645explicit C code to initialize it. Reserve C initialized declarations 646for data that will not be changed. 647@c ADR: why? 648 649Try to avoid low-level interfaces to obscure Unix data structures (such 650as file directories, utmp, or the layout of kernel memory), since these 651are less likely to work compatibly. If you need to find all the files 652in a directory, use @code{readdir} or some other high-level interface. 653These are supported compatibly by GNU. 654 655@cindex signal handling 656The preferred signal handling facilities are the BSD variant of 657@code{signal}, and the POSIX @code{sigaction} function; the 658alternative USG @code{signal} interface is an inferior design. 659 660Nowadays, using the POSIX signal functions may be the easiest way 661to make a program portable. If you use @code{signal}, then on GNU/Linux 662systems running GNU libc version 1, you should include 663@file{bsd/signal.h} instead of @file{signal.h}, so as to get BSD 664behavior. It is up to you whether to support systems where 665@code{signal} has only the USG behavior, or give up on them. 666 667@cindex impossible conditions 668In error checks that detect ``impossible'' conditions, just abort. 669There is usually no point in printing any message. These checks 670indicate the existence of bugs. Whoever wants to fix the bugs will have 671to read the source code and run a debugger. So explain the problem with 672comments in the source. The relevant data will be in variables, which 673are easy to examine with the debugger, so there is no point moving them 674elsewhere. 675 676Do not use a count of errors as the exit status for a program. 677@emph{That does not work}, because exit status values are limited to 8 678bits (0 through 255). A single run of the program might have 256 679errors; if you try to return 256 as the exit status, the parent process 680will see 0 as the status, and it will appear that the program succeeded. 681 682@cindex temporary files 683@cindex @code{TMPDIR} environment variable 684If you make temporary files, check the @code{TMPDIR} environment 685variable; if that variable is defined, use the specified directory 686instead of @file{/tmp}. 687 688In addition, be aware that there is a possible security problem when 689creating temporary files in world-writable directories. In C, you can 690avoid this problem by creating temporary files in this manner: 691 692@example 693fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600); 694@end example 695 696@noindent 697or by using the @code{mkstemps} function from Gnulib 698(@pxref{mkstemps,,, gnulib, Gnulib}). 699 700In bash, use @code{set -C} (long name @code{noclobber}) to avoid this 701problem. In addition, the @code{mktemp} utility is a more general 702solution for creating temporary files from shell scripts 703(@pxref{mktemp invocation,,, coreutils, GNU Coreutils}). 704 705 706@node Libraries 707@section Library Behavior 708@cindex libraries 709 710Try to make library functions reentrant. If they need to do dynamic 711storage allocation, at least try to avoid any nonreentrancy aside from 712that of @code{malloc} itself. 713 714Here are certain name conventions for libraries, to avoid name 715conflicts. 716 717Choose a name prefix for the library, more than two characters long. 718All external function and variable names should start with this 719prefix. In addition, there should only be one of these in any given 720library member. This usually means putting each one in a separate 721source file. 722 723An exception can be made when two external symbols are always used 724together, so that no reasonable program could use one without the 725other; then they can both go in the same file. 726 727External symbols that are not documented entry points for the user 728should have names beginning with @samp{_}. The @samp{_} should be 729followed by the chosen name prefix for the library, to prevent 730collisions with other libraries. These can go in the same files with 731user entry points if you like. 732 733Static functions and variables can be used as you like and need not 734fit any naming convention. 735 736@node Errors 737@section Formatting Error Messages 738@cindex formatting error messages 739@cindex error messages, formatting 740 741Error messages from compilers should look like this: 742 743@example 744@var{sourcefile}:@var{lineno}: @var{message} 745@end example 746 747@noindent 748If you want to mention the column number, use one of these formats: 749 750@example 751@var{sourcefile}:@var{lineno}:@var{column}: @var{message} 752@var{sourcefile}:@var{lineno}.@var{column}: @var{message} 753 754@end example 755 756@noindent 757Line numbers should start from 1 at the beginning of the file, and 758column numbers should start from 1 at the beginning of the line. 759(Both of these conventions are chosen for compatibility.) Calculate 760column numbers assuming that space and all ASCII printing characters 761have equal width, and assuming tab stops every 8 columns. For 762non-ASCII characters, Unicode character widths should be used when in 763a UTF-8 locale; GNU libc and GNU gnulib provide suitable 764@code{wcwidth} functions. 765 766The error message can also give both the starting and ending positions 767of the erroneous text. There are several formats so that you can 768avoid redundant information such as a duplicate line number. 769Here are the possible formats: 770 771@example 772@var{sourcefile}:@var{line1}.@var{column1}-@var{line2}.@var{column2}: @var{message} 773@var{sourcefile}:@var{line1}.@var{column1}-@var{column2}: @var{message} 774@var{sourcefile}:@var{line1}-@var{line2}: @var{message} 775@end example 776 777@noindent 778When an error is spread over several files, you can use this format: 779 780@example 781@var{file1}:@var{line1}.@var{column1}-@var{file2}:@var{line2}.@var{column2}: @var{message} 782@end example 783 784Error messages from other noninteractive programs should look like this: 785 786@example 787@var{program}:@var{sourcefile}:@var{lineno}: @var{message} 788@end example 789 790@noindent 791when there is an appropriate source file, or like this: 792 793@example 794@var{program}: @var{message} 795@end example 796 797@noindent 798when there is no relevant source file. 799 800If you want to mention the column number, use this format: 801 802@example 803@var{program}:@var{sourcefile}:@var{lineno}:@var{column}: @var{message} 804@end example 805 806In an interactive program (one that is reading commands from a 807terminal), it is better not to include the program name in an error 808message. The place to indicate which program is running is in the 809prompt or with the screen layout. (When the same program runs with 810input from a source other than a terminal, it is not interactive and 811would do best to print error messages using the noninteractive style.) 812 813The string @var{message} should not begin with a capital letter when 814it follows a program name and/or file name, because that isn't the 815beginning of a sentence. (The sentence conceptually starts at the 816beginning of the line.) Also, it should not end with a period. 817 818Error messages from interactive programs, and other messages such as 819usage messages, should start with a capital letter. But they should not 820end with a period. 821 822@node User Interfaces 823@section Standards for Interfaces Generally 824 825@cindex program name and its behavior 826@cindex behavior, dependent on program's name 827Please don't make the behavior of a utility depend on the name used 828to invoke it. It is useful sometimes to make a link to a utility 829with a different name, and that should not change what it does. 830 831Instead, use a run time option or a compilation switch or both 832to select among the alternate behaviors. 833 834@cindex output device and program's behavior 835Likewise, please don't make the behavior of the program depend on the 836type of output device it is used with. Device independence is an 837important principle of the system's design; do not compromise it merely 838to save someone from typing an option now and then. (Variation in error 839message syntax when using a terminal is ok, because that is a side issue 840that people do not depend on.) 841 842If you think one behavior is most useful when the output is to a 843terminal, and another is most useful when the output is a file or a 844pipe, then it is usually best to make the default behavior the one that 845is useful with output to a terminal, and have an option for the other 846behavior. 847 848Compatibility requires certain programs to depend on the type of output 849device. It would be disastrous if @code{ls} or @code{sh} did not do so 850in the way all users expect. In some of these cases, we supplement the 851program with a preferred alternate version that does not depend on the 852output device type. For example, we provide a @code{dir} program much 853like @code{ls} except that its default output format is always 854multi-column format. 855 856 857@node Graphical Interfaces 858@section Standards for Graphical Interfaces 859@cindex graphical user interface 860@cindex interface styles 861@cindex user interface styles 862 863@cindex GTK+ 864When you write a program that provides a graphical user interface, 865please make it work with the X Window System and the GTK+ toolkit 866unless the functionality specifically requires some alternative (for 867example, ``displaying jpeg images while in console mode''). 868 869In addition, please provide a command-line interface to control the 870functionality. (In many cases, the graphical user interface can be a 871separate program which invokes the command-line program.) This is 872so that the same jobs can be done from scripts. 873 874@cindex CORBA 875@cindex GNOME 876@cindex D-bus 877@cindex keyboard interface 878@cindex library interface 879Please also consider providing a D-bus interface for use from other 880running programs, such as within GNOME. (GNOME used to use CORBA 881for this, but that is being phased out.) In addition, consider 882providing a library interface (for use from C), and perhaps a 883keyboard-driven console interface (for use by users from console 884mode). Once you are doing the work to provide the functionality and 885the graphical interface, these won't be much extra work. 886 887@node Command-Line Interfaces 888@section Standards for Command Line Interfaces 889@cindex command-line interface 890 891@findex getopt 892It is a good idea to follow the POSIX guidelines for the 893command-line options of a program. The easiest way to do this is to use 894@code{getopt} to parse them. Note that the GNU version of @code{getopt} 895will normally permit options anywhere among the arguments unless the 896special argument @samp{--} is used. This is not what POSIX 897specifies; it is a GNU extension. 898 899@cindex long-named options 900Please define long-named options that are equivalent to the 901single-letter Unix-style options. We hope to make GNU more user 902friendly this way. This is easy to do with the GNU function 903@code{getopt_long}. 904 905One of the advantages of long-named options is that they can be 906consistent from program to program. For example, users should be able 907to expect the ``verbose'' option of any GNU program which has one, to be 908spelled precisely @samp{--verbose}. To achieve this uniformity, look at 909the table of common long-option names when you choose the option names 910for your program (@pxref{Option Table}). 911 912It is usually a good idea for file names given as ordinary arguments to 913be input files only; any output files would be specified using options 914(preferably @samp{-o} or @samp{--output}). Even if you allow an output 915file name as an ordinary argument for compatibility, try to provide an 916option as another way to specify it. This will lead to more consistency 917among GNU utilities, and fewer idiosyncrasies for users to remember. 918 919@cindex standard command-line options 920@cindex options, standard command-line 921@cindex CGI programs, standard options for 922@cindex PATH_INFO, specifying standard options as 923All programs should support two standard options: @samp{--version} 924and @samp{--help}. CGI programs should accept these as command-line 925options, and also if given as the @env{PATH_INFO}; for instance, 926visiting @url{http://example.org/p.cgi/--help} in a browser should 927output the same information as invoking @samp{p.cgi --help} from the 928command line. 929 930@menu 931* --version:: The standard output for --version. 932* --help:: The standard output for --help. 933@end menu 934 935@node --version 936@subsection @option{--version} 937 938@cindex @samp{--version} output 939 940The standard @code{--version} option should direct the program to 941print information about its name, version, origin and legal status, 942all on standard output, and then exit successfully. Other options and 943arguments should be ignored once this is seen, and the program should 944not perform its normal function. 945 946@cindex canonical name of a program 947@cindex program's canonical name 948The first line is meant to be easy for a program to parse; the version 949number proper starts after the last space. In addition, it contains 950the canonical name for this program, in this format: 951 952@example 953GNU Emacs 19.30 954@end example 955 956@noindent 957The program's name should be a constant string; @emph{don't} compute it 958from @code{argv[0]}. The idea is to state the standard or canonical 959name for the program, not its file name. There are other ways to find 960out the precise file name where a command is found in @code{PATH}. 961 962If the program is a subsidiary part of a larger package, mention the 963package name in parentheses, like this: 964 965@example 966emacsserver (GNU Emacs) 19.30 967@end example 968 969@noindent 970If the package has a version number which is different from this 971program's version number, you can mention the package version number 972just before the close-parenthesis. 973 974If you @emph{need} to mention the version numbers of libraries which 975are distributed separately from the package which contains this program, 976you can do so by printing an additional line of version info for each 977library you want to mention. Use the same format for these lines as for 978the first line. 979 980Please do not mention all of the libraries that the program uses ``just 981for completeness''---that would produce a lot of unhelpful clutter. 982Please mention library version numbers only if you find in practice that 983they are very important to you in debugging. 984 985The following line, after the version number line or lines, should be a 986copyright notice. If more than one copyright notice is called for, put 987each on a separate line. 988 989Next should follow a line stating the license, preferably using one of 990abbreviations below, and a brief statement that the program is free 991software, and that users are free to copy and change it. Also mention 992that there is no warranty, to the extent permitted by law. See 993recommended wording below. 994 995It is ok to finish the output with a list of the major authors of the 996program, as a way of giving credit. 997 998Here's an example of output that follows these rules: 999 1000@smallexample 1001GNU hello 2.3 1002Copyright (C) 2007 Free Software Foundation, Inc. 1003License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 1004This is free software: you are free to change and redistribute it. 1005There is NO WARRANTY, to the extent permitted by law. 1006@end smallexample 1007 1008You should adapt this to your program, of course, filling in the proper 1009year, copyright holder, name of program, and the references to 1010distribution terms, and changing the rest of the wording as necessary. 1011 1012This copyright notice only needs to mention the most recent year in 1013which changes were made---there's no need to list the years for previous 1014versions' changes. You don't have to mention the name of the program in 1015these notices, if that is inconvenient, since it appeared in the first 1016line. (The rules are different for copyright notices in source files; 1017@pxref{Copyright Notices,,,maintain,Information for GNU Maintainers}.) 1018 1019Translations of the above lines must preserve the validity of the 1020copyright notices (@pxref{Internationalization}). If the translation's 1021character set supports it, the @samp{(C)} should be replaced with the 1022copyright symbol, as follows: 1023 1024@ifinfo 1025(the official copyright symbol, which is the letter C in a circle); 1026@end ifinfo 1027@ifnotinfo 1028@copyright{} 1029@end ifnotinfo 1030 1031Write the word ``Copyright'' exactly like that, in English. Do not 1032translate it into another language. International treaties recognize 1033the English word ``Copyright''; translations into other languages do not 1034have legal significance. 1035 1036Finally, here is the table of our suggested license abbreviations. 1037Any abbreviation can be followed by @samp{v@var{version}[+]}, meaning 1038that particular version, or later versions with the @samp{+}, as shown 1039above. In the case of a GNU license, @emph{always} indicate the permitted 1040versions in this way. 1041 1042In the case of exceptions for extra permissions with the GPL, we use 1043@samp{/} for a separator; the version number can follow the license 1044abbreviation as usual, as in the examples below. 1045 1046@table @asis 1047@item GPL 1048GNU General Public License, @url{http://www.gnu.org/@/licenses/@/gpl.html}. 1049 1050@item LGPL 1051GNU Lesser General Public License, @url{http://www.gnu.org/@/licenses/@/lgpl.html}. 1052 1053@item GPL/Ada 1054GNU GPL with the exception for Ada. 1055 1056@item Apache 1057The Apache Software Foundation license, 1058@url{http://www.apache.org/@/licenses}. 1059 1060@item Artistic 1061The Artistic license used for Perl, @url{http://dev.perl.org/licenses/artistic.html}. 1062 1063@item Expat 1064The Expat license, @url{http://www.jclark.com/@/xml/@/copying.txt}. 1065 1066@item MPL 1067The Mozilla Public License, @url{http://www.mozilla.org/@/MPL/}. 1068 1069@item OBSD 1070The original (4-clause) BSD license, incompatible with the GNU GPL 1071@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#6}. 1072 1073@item PHP 1074The license used for PHP, @url{http://www.php.net/@/license/}. 1075 1076@item public domain 1077The non-license that is being in the public domain, 1078@url{http://www.gnu.org/@/licenses/@/license-list.html#PublicDomain}. 1079 1080@item Python 1081The license for Python, @url{http://www.python.org/@/2.0.1/@/license.html}. 1082 1083@item RBSD 1084The revised (3-clause) BSD, compatible with the GNU GPL,@* 1085@url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#5}. 1086 1087@item X11 1088The simple non-copyleft license used for most versions of the X Window 1089System, @url{http://www.xfree86.org/@/3.3.6/@/COPYRIGHT2.html#3}. 1090 1091@item Zlib 1092The license for Zlib, @url{http://www.gzip.org/@/zlib/@/zlib_license.html}. 1093 1094@end table 1095 1096More information about these licenses and many more are on the GNU 1097licensing web pages, 1098@url{http://www.gnu.org/@/licenses/@/license-list.html}. 1099 1100 1101@node --help 1102@subsection @option{--help} 1103 1104@cindex @samp{--help} output 1105 1106The standard @code{--help} option should output brief documentation 1107for how to invoke the program, on standard output, then exit 1108successfully. Other options and arguments should be ignored once this 1109is seen, and the program should not perform its normal function. 1110 1111@cindex address for bug reports 1112@cindex bug reports 1113Near the end of the @samp{--help} option's output, please place lines 1114giving the email address for bug reports, the package's home page 1115(normally @indicateurl{http://www.gnu.org/software/@var{pkg}}, and the 1116general page for help using GNU programs. The format should be like this: 1117 1118@example 1119Report bugs to: @var{mailing-address} 1120@var{pkg} home page: <http://www.gnu.org/software/@var{pkg}/> 1121General help using GNU software: <http://www.gnu.org/gethelp/> 1122@end example 1123 1124It is ok to mention other appropriate mailing lists and web pages. 1125 1126 1127@node Dynamic Plug-In Interfaces 1128@section Standards for Dynamic Plug-in Interfaces 1129@cindex plug-ins 1130@cindex dynamic plug-ins 1131 1132Another aspect of keeping free programs free is encouraging 1133development of free plug-ins, and discouraging development of 1134proprietary plug-ins. Many GNU programs will not have anything like 1135plug-ins at all, but those that do should follow these 1136practices. 1137 1138First, the general plug-in architecture design should closely tie the 1139plug-in to the original code, such that the plug-in and the base 1140program are parts of one extended program. For GCC, for example, 1141plug-ins receive and modify GCC's internal data structures, and so 1142clearly form an extended program with the base GCC. 1143 1144@vindex plugin_is_GPL_compatible 1145Second, you should require plug-in developers to affirm that their 1146plug-ins are released under an appropriate license. This should be 1147enforced with a simple programmatic check. For GCC, again for 1148example, a plug-in must define the global symbol 1149@code{plugin_is_GPL_compatible}, thus asserting that the plug-in is 1150released under a GPL-compatible license (@pxref{Plugins,, Plugins, 1151gccint, GCC Internals}). 1152 1153By adding this check to your program you are not creating a new legal 1154requirement. The GPL itself requires plug-ins to be free software, 1155licensed compatibly. As long as you have followed the first rule above 1156to keep plug-ins closely tied to your original program, the GPL and AGPL 1157already require those plug-ins to be released under a compatible 1158license. The symbol definition in the plug-in---or whatever equivalent 1159works best in your program---makes it harder for anyone who might 1160distribute proprietary plug-ins to legally defend themselves. If a case 1161about this got to court, we can point to that symbol as evidence that 1162the plug-in developer understood that the license had this requirement. 1163 1164 1165@node Option Table 1166@section Table of Long Options 1167@cindex long option names 1168@cindex table of long options 1169 1170Here is a table of long options used by GNU programs. It is surely 1171incomplete, but we aim to list all the options that a new program might 1172want to be compatible with. If you use names not already in the table, 1173please send @email{bug-standards@@gnu.org} a list of them, with their 1174meanings, so we can update the table. 1175 1176@c Please leave newlines between items in this table; it's much easier 1177@c to update when it isn't completely squashed together and unreadable. 1178@c When there is more than one short option for a long option name, put 1179@c a semicolon between the lists of the programs that use them, not a 1180@c period. --friedman 1181 1182@table @samp 1183@item after-date 1184@samp{-N} in @code{tar}. 1185 1186@item all 1187@samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname}, 1188and @code{unexpand}. 1189 1190@item all-text 1191@samp{-a} in @code{diff}. 1192 1193@item almost-all 1194@samp{-A} in @code{ls}. 1195 1196@item append 1197@samp{-a} in @code{etags}, @code{tee}, @code{time}; 1198@samp{-r} in @code{tar}. 1199 1200@item archive 1201@samp{-a} in @code{cp}. 1202 1203@item archive-name 1204@samp{-n} in @code{shar}. 1205 1206@item arglength 1207@samp{-l} in @code{m4}. 1208 1209@item ascii 1210@samp{-a} in @code{diff}. 1211 1212@item assign 1213@samp{-v} in @code{gawk}. 1214 1215@item assume-new 1216@samp{-W} in @code{make}. 1217 1218@item assume-old 1219@samp{-o} in @code{make}. 1220 1221@item auto-check 1222@samp{-a} in @code{recode}. 1223 1224@item auto-pager 1225@samp{-a} in @code{wdiff}. 1226 1227@item auto-reference 1228@samp{-A} in @code{ptx}. 1229 1230@item avoid-wraps 1231@samp{-n} in @code{wdiff}. 1232 1233@item background 1234For server programs, run in the background. 1235 1236@item backward-search 1237@samp{-B} in @code{ctags}. 1238 1239@item basename 1240@samp{-f} in @code{shar}. 1241 1242@item batch 1243Used in GDB. 1244 1245@item baud 1246Used in GDB. 1247 1248@item before 1249@samp{-b} in @code{tac}. 1250 1251@item binary 1252@samp{-b} in @code{cpio} and @code{diff}. 1253 1254@item bits-per-code 1255@samp{-b} in @code{shar}. 1256 1257@item block-size 1258Used in @code{cpio} and @code{tar}. 1259 1260@item blocks 1261@samp{-b} in @code{head} and @code{tail}. 1262 1263@item break-file 1264@samp{-b} in @code{ptx}. 1265 1266@item brief 1267Used in various programs to make output shorter. 1268 1269@item bytes 1270@samp{-c} in @code{head}, @code{split}, and @code{tail}. 1271 1272@item c@t{++} 1273@samp{-C} in @code{etags}. 1274 1275@item catenate 1276@samp{-A} in @code{tar}. 1277 1278@item cd 1279Used in various programs to specify the directory to use. 1280 1281@item changes 1282@samp{-c} in @code{chgrp} and @code{chown}. 1283 1284@item classify 1285@samp{-F} in @code{ls}. 1286 1287@item colons 1288@samp{-c} in @code{recode}. 1289 1290@item command 1291@samp{-c} in @code{su}; 1292@samp{-x} in GDB. 1293 1294@item compare 1295@samp{-d} in @code{tar}. 1296 1297@item compat 1298Used in @code{gawk}. 1299 1300@item compress 1301@samp{-Z} in @code{tar} and @code{shar}. 1302 1303@item concatenate 1304@samp{-A} in @code{tar}. 1305 1306@item confirmation 1307@samp{-w} in @code{tar}. 1308 1309@item context 1310Used in @code{diff}. 1311 1312@item copyleft 1313@samp{-W copyleft} in @code{gawk}. 1314 1315@item copyright 1316@samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff}; 1317@samp{-W copyright} in @code{gawk}. 1318 1319@item core 1320Used in GDB. 1321 1322@item count 1323@samp{-q} in @code{who}. 1324 1325@item count-links 1326@samp{-l} in @code{du}. 1327 1328@item create 1329Used in @code{tar} and @code{cpio}. 1330 1331@item cut-mark 1332@samp{-c} in @code{shar}. 1333 1334@item cxref 1335@samp{-x} in @code{ctags}. 1336 1337@item date 1338@samp{-d} in @code{touch}. 1339 1340@item debug 1341@samp{-d} in @code{make} and @code{m4}; 1342@samp{-t} in Bison. 1343 1344@item define 1345@samp{-D} in @code{m4}. 1346 1347@item defines 1348@samp{-d} in Bison and @code{ctags}. 1349 1350@item delete 1351@samp{-D} in @code{tar}. 1352 1353@item dereference 1354@samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du}, 1355@code{ls}, and @code{tar}. 1356 1357@item dereference-args 1358@samp{-D} in @code{du}. 1359 1360@item device 1361Specify an I/O device (special file name). 1362 1363@item diacritics 1364@samp{-d} in @code{recode}. 1365 1366@item dictionary-order 1367@samp{-d} in @code{look}. 1368 1369@item diff 1370@samp{-d} in @code{tar}. 1371 1372@item digits 1373@samp{-n} in @code{csplit}. 1374 1375@item directory 1376Specify the directory to use, in various programs. In @code{ls}, it 1377means to show directories themselves rather than their contents. In 1378@code{rm} and @code{ln}, it means to not treat links to directories 1379specially. 1380 1381@item discard-all 1382@samp{-x} in @code{strip}. 1383 1384@item discard-locals 1385@samp{-X} in @code{strip}. 1386 1387@item dry-run 1388@samp{-n} in @code{make}. 1389 1390@item ed 1391@samp{-e} in @code{diff}. 1392 1393@item elide-empty-files 1394@samp{-z} in @code{csplit}. 1395 1396@item end-delete 1397@samp{-x} in @code{wdiff}. 1398 1399@item end-insert 1400@samp{-z} in @code{wdiff}. 1401 1402@item entire-new-file 1403@samp{-N} in @code{diff}. 1404 1405@item environment-overrides 1406@samp{-e} in @code{make}. 1407 1408@item eof 1409@samp{-e} in @code{xargs}. 1410 1411@item epoch 1412Used in GDB. 1413 1414@item error-limit 1415Used in @code{makeinfo}. 1416 1417@item error-output 1418@samp{-o} in @code{m4}. 1419 1420@item escape 1421@samp{-b} in @code{ls}. 1422 1423@item exclude-from 1424@samp{-X} in @code{tar}. 1425 1426@item exec 1427Used in GDB. 1428 1429@item exit 1430@samp{-x} in @code{xargs}. 1431 1432@item exit-0 1433@samp{-e} in @code{unshar}. 1434 1435@item expand-tabs 1436@samp{-t} in @code{diff}. 1437 1438@item expression 1439@samp{-e} in @code{sed}. 1440 1441@item extern-only 1442@samp{-g} in @code{nm}. 1443 1444@item extract 1445@samp{-i} in @code{cpio}; 1446@samp{-x} in @code{tar}. 1447 1448@item faces 1449@samp{-f} in @code{finger}. 1450 1451@item fast 1452@samp{-f} in @code{su}. 1453 1454@item fatal-warnings 1455@samp{-E} in @code{m4}. 1456 1457@item file 1458@samp{-f} in @code{gawk}, @code{info}, @code{make}, @code{mt}, 1459@code{sed}, and @code{tar}. 1460 1461@item field-separator 1462@samp{-F} in @code{gawk}. 1463 1464@item file-prefix 1465@samp{-b} in Bison. 1466 1467@item file-type 1468@samp{-F} in @code{ls}. 1469 1470@item files-from 1471@samp{-T} in @code{tar}. 1472 1473@item fill-column 1474Used in @code{makeinfo}. 1475 1476@item flag-truncation 1477@samp{-F} in @code{ptx}. 1478 1479@item fixed-output-files 1480@samp{-y} in Bison. 1481 1482@item follow 1483@samp{-f} in @code{tail}. 1484 1485@item footnote-style 1486Used in @code{makeinfo}. 1487 1488@item force 1489@samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}. 1490 1491@item force-prefix 1492@samp{-F} in @code{shar}. 1493 1494@item foreground 1495For server programs, run in the foreground; 1496in other words, don't do anything special to run the server 1497in the background. 1498 1499@item format 1500Used in @code{ls}, @code{time}, and @code{ptx}. 1501 1502@item freeze-state 1503@samp{-F} in @code{m4}. 1504 1505@item fullname 1506Used in GDB. 1507 1508@item gap-size 1509@samp{-g} in @code{ptx}. 1510 1511@item get 1512@samp{-x} in @code{tar}. 1513 1514@item graphic 1515@samp{-i} in @code{ul}. 1516 1517@item graphics 1518@samp{-g} in @code{recode}. 1519 1520@item group 1521@samp{-g} in @code{install}. 1522 1523@item gzip 1524@samp{-z} in @code{tar} and @code{shar}. 1525 1526@item hashsize 1527@samp{-H} in @code{m4}. 1528 1529@item header 1530@samp{-h} in @code{objdump} and @code{recode} 1531 1532@item heading 1533@samp{-H} in @code{who}. 1534 1535@item help 1536Used to ask for brief usage information. 1537 1538@item here-delimiter 1539@samp{-d} in @code{shar}. 1540 1541@item hide-control-chars 1542@samp{-q} in @code{ls}. 1543 1544@item html 1545In @code{makeinfo}, output HTML. 1546 1547@item idle 1548@samp{-u} in @code{who}. 1549 1550@item ifdef 1551@samp{-D} in @code{diff}. 1552 1553@item ignore 1554@samp{-I} in @code{ls}; 1555@samp{-x} in @code{recode}. 1556 1557@item ignore-all-space 1558@samp{-w} in @code{diff}. 1559 1560@item ignore-backups 1561@samp{-B} in @code{ls}. 1562 1563@item ignore-blank-lines 1564@samp{-B} in @code{diff}. 1565 1566@item ignore-case 1567@samp{-f} in @code{look} and @code{ptx}; 1568@samp{-i} in @code{diff} and @code{wdiff}. 1569 1570@item ignore-errors 1571@samp{-i} in @code{make}. 1572 1573@item ignore-file 1574@samp{-i} in @code{ptx}. 1575 1576@item ignore-indentation 1577@samp{-I} in @code{etags}. 1578 1579@item ignore-init-file 1580@samp{-f} in Oleo. 1581 1582@item ignore-interrupts 1583@samp{-i} in @code{tee}. 1584 1585@item ignore-matching-lines 1586@samp{-I} in @code{diff}. 1587 1588@item ignore-space-change 1589@samp{-b} in @code{diff}. 1590 1591@item ignore-zeros 1592@samp{-i} in @code{tar}. 1593 1594@item include 1595@samp{-i} in @code{etags}; 1596@samp{-I} in @code{m4}. 1597 1598@item include-dir 1599@samp{-I} in @code{make}. 1600 1601@item incremental 1602@samp{-G} in @code{tar}. 1603 1604@item info 1605@samp{-i}, @samp{-l}, and @samp{-m} in Finger. 1606 1607@item init-file 1608In some programs, specify the name of the file to read as the user's 1609init file. 1610 1611@item initial 1612@samp{-i} in @code{expand}. 1613 1614@item initial-tab 1615@samp{-T} in @code{diff}. 1616 1617@item inode 1618@samp{-i} in @code{ls}. 1619 1620@item interactive 1621@samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm}; 1622@samp{-e} in @code{m4}; 1623@samp{-p} in @code{xargs}; 1624@samp{-w} in @code{tar}. 1625 1626@item intermix-type 1627@samp{-p} in @code{shar}. 1628 1629@item iso-8601 1630Used in @code{date} 1631 1632@item jobs 1633@samp{-j} in @code{make}. 1634 1635@item just-print 1636@samp{-n} in @code{make}. 1637 1638@item keep-going 1639@samp{-k} in @code{make}. 1640 1641@item keep-files 1642@samp{-k} in @code{csplit}. 1643 1644@item kilobytes 1645@samp{-k} in @code{du} and @code{ls}. 1646 1647@item language 1648@samp{-l} in @code{etags}. 1649 1650@item less-mode 1651@samp{-l} in @code{wdiff}. 1652 1653@item level-for-gzip 1654@samp{-g} in @code{shar}. 1655 1656@item line-bytes 1657@samp{-C} in @code{split}. 1658 1659@item lines 1660Used in @code{split}, @code{head}, and @code{tail}. 1661 1662@item link 1663@samp{-l} in @code{cpio}. 1664 1665@item lint 1666@itemx lint-old 1667Used in @code{gawk}. 1668 1669@item list 1670@samp{-t} in @code{cpio}; 1671@samp{-l} in @code{recode}. 1672 1673@item list 1674@samp{-t} in @code{tar}. 1675 1676@item literal 1677@samp{-N} in @code{ls}. 1678 1679@item load-average 1680@samp{-l} in @code{make}. 1681 1682@item login 1683Used in @code{su}. 1684 1685@item machine 1686Used in @code{uname}. 1687 1688@item macro-name 1689@samp{-M} in @code{ptx}. 1690 1691@item mail 1692@samp{-m} in @code{hello} and @code{uname}. 1693 1694@item make-directories 1695@samp{-d} in @code{cpio}. 1696 1697@item makefile 1698@samp{-f} in @code{make}. 1699 1700@item mapped 1701Used in GDB. 1702 1703@item max-args 1704@samp{-n} in @code{xargs}. 1705 1706@item max-chars 1707@samp{-n} in @code{xargs}. 1708 1709@item max-lines 1710@samp{-l} in @code{xargs}. 1711 1712@item max-load 1713@samp{-l} in @code{make}. 1714 1715@item max-procs 1716@samp{-P} in @code{xargs}. 1717 1718@item mesg 1719@samp{-T} in @code{who}. 1720 1721@item message 1722@samp{-T} in @code{who}. 1723 1724@item minimal 1725@samp{-d} in @code{diff}. 1726 1727@item mixed-uuencode 1728@samp{-M} in @code{shar}. 1729 1730@item mode 1731@samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}. 1732 1733@item modification-time 1734@samp{-m} in @code{tar}. 1735 1736@item multi-volume 1737@samp{-M} in @code{tar}. 1738 1739@item name-prefix 1740@samp{-a} in Bison. 1741 1742@item nesting-limit 1743@samp{-L} in @code{m4}. 1744 1745@item net-headers 1746@samp{-a} in @code{shar}. 1747 1748@item new-file 1749@samp{-W} in @code{make}. 1750 1751@item no-builtin-rules 1752@samp{-r} in @code{make}. 1753 1754@item no-character-count 1755@samp{-w} in @code{shar}. 1756 1757@item no-check-existing 1758@samp{-x} in @code{shar}. 1759 1760@item no-common 1761@samp{-3} in @code{wdiff}. 1762 1763@item no-create 1764@samp{-c} in @code{touch}. 1765 1766@item no-defines 1767@samp{-D} in @code{etags}. 1768 1769@item no-deleted 1770@samp{-1} in @code{wdiff}. 1771 1772@item no-dereference 1773@samp{-d} in @code{cp}. 1774 1775@item no-inserted 1776@samp{-2} in @code{wdiff}. 1777 1778@item no-keep-going 1779@samp{-S} in @code{make}. 1780 1781@item no-lines 1782@samp{-l} in Bison. 1783 1784@item no-piping 1785@samp{-P} in @code{shar}. 1786 1787@item no-prof 1788@samp{-e} in @code{gprof}. 1789 1790@item no-regex 1791@samp{-R} in @code{etags}. 1792 1793@item no-sort 1794@samp{-p} in @code{nm}. 1795 1796@item no-splash 1797Don't print a startup splash screen. 1798 1799@item no-split 1800Used in @code{makeinfo}. 1801 1802@item no-static 1803@samp{-a} in @code{gprof}. 1804 1805@item no-time 1806@samp{-E} in @code{gprof}. 1807 1808@item no-timestamp 1809@samp{-m} in @code{shar}. 1810 1811@item no-validate 1812Used in @code{makeinfo}. 1813 1814@item no-wait 1815Used in @code{emacsclient}. 1816 1817@item no-warn 1818Used in various programs to inhibit warnings. 1819 1820@item node 1821@samp{-n} in @code{info}. 1822 1823@item nodename 1824@samp{-n} in @code{uname}. 1825 1826@item nonmatching 1827@samp{-f} in @code{cpio}. 1828 1829@item nstuff 1830@samp{-n} in @code{objdump}. 1831 1832@item null 1833@samp{-0} in @code{xargs}. 1834 1835@item number 1836@samp{-n} in @code{cat}. 1837 1838@item number-nonblank 1839@samp{-b} in @code{cat}. 1840 1841@item numeric-sort 1842@samp{-n} in @code{nm}. 1843 1844@item numeric-uid-gid 1845@samp{-n} in @code{cpio} and @code{ls}. 1846 1847@item nx 1848Used in GDB. 1849 1850@item old-archive 1851@samp{-o} in @code{tar}. 1852 1853@item old-file 1854@samp{-o} in @code{make}. 1855 1856@item one-file-system 1857@samp{-l} in @code{tar}, @code{cp}, and @code{du}. 1858 1859@item only-file 1860@samp{-o} in @code{ptx}. 1861 1862@item only-prof 1863@samp{-f} in @code{gprof}. 1864 1865@item only-time 1866@samp{-F} in @code{gprof}. 1867 1868@item options 1869@samp{-o} in @code{getopt}, @code{fdlist}, @code{fdmount}, 1870@code{fdmountd}, and @code{fdumount}. 1871 1872@item output 1873In various programs, specify the output file name. 1874 1875@item output-prefix 1876@samp{-o} in @code{shar}. 1877 1878@item override 1879@samp{-o} in @code{rm}. 1880 1881@item overwrite 1882@samp{-c} in @code{unshar}. 1883 1884@item owner 1885@samp{-o} in @code{install}. 1886 1887@item paginate 1888@samp{-l} in @code{diff}. 1889 1890@item paragraph-indent 1891Used in @code{makeinfo}. 1892 1893@item parents 1894@samp{-p} in @code{mkdir} and @code{rmdir}. 1895 1896@item pass-all 1897@samp{-p} in @code{ul}. 1898 1899@item pass-through 1900@samp{-p} in @code{cpio}. 1901 1902@item port 1903@samp{-P} in @code{finger}. 1904 1905@item portability 1906@samp{-c} in @code{cpio} and @code{tar}. 1907 1908@item posix 1909Used in @code{gawk}. 1910 1911@item prefix-builtins 1912@samp{-P} in @code{m4}. 1913 1914@item prefix 1915@samp{-f} in @code{csplit}. 1916 1917@item preserve 1918Used in @code{tar} and @code{cp}. 1919 1920@item preserve-environment 1921@samp{-p} in @code{su}. 1922 1923@item preserve-modification-time 1924@samp{-m} in @code{cpio}. 1925 1926@item preserve-order 1927@samp{-s} in @code{tar}. 1928 1929@item preserve-permissions 1930@samp{-p} in @code{tar}. 1931 1932@item print 1933@samp{-l} in @code{diff}. 1934 1935@item print-chars 1936@samp{-L} in @code{cmp}. 1937 1938@item print-data-base 1939@samp{-p} in @code{make}. 1940 1941@item print-directory 1942@samp{-w} in @code{make}. 1943 1944@item print-file-name 1945@samp{-o} in @code{nm}. 1946 1947@item print-symdefs 1948@samp{-s} in @code{nm}. 1949 1950@item printer 1951@samp{-p} in @code{wdiff}. 1952 1953@item prompt 1954@samp{-p} in @code{ed}. 1955 1956@item proxy 1957Specify an HTTP proxy. 1958 1959@item query-user 1960@samp{-X} in @code{shar}. 1961 1962@item question 1963@samp{-q} in @code{make}. 1964 1965@item quiet 1966Used in many programs to inhibit the usual output. Every 1967program accepting @samp{--quiet} should accept @samp{--silent} as a 1968synonym. 1969 1970@item quiet-unshar 1971@samp{-Q} in @code{shar} 1972 1973@item quote-name 1974@samp{-Q} in @code{ls}. 1975 1976@item rcs 1977@samp{-n} in @code{diff}. 1978 1979@item re-interval 1980Used in @code{gawk}. 1981 1982@item read-full-blocks 1983@samp{-B} in @code{tar}. 1984 1985@item readnow 1986Used in GDB. 1987 1988@item recon 1989@samp{-n} in @code{make}. 1990 1991@item record-number 1992@samp{-R} in @code{tar}. 1993 1994@item recursive 1995Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff}, 1996and @code{rm}. 1997 1998@item reference 1999@samp{-r} in @code{touch}. 2000 2001@item references 2002@samp{-r} in @code{ptx}. 2003 2004@item regex 2005@samp{-r} in @code{tac} and @code{etags}. 2006 2007@item release 2008@samp{-r} in @code{uname}. 2009 2010@item reload-state 2011@samp{-R} in @code{m4}. 2012 2013@item relocation 2014@samp{-r} in @code{objdump}. 2015 2016@item rename 2017@samp{-r} in @code{cpio}. 2018 2019@item replace 2020@samp{-i} in @code{xargs}. 2021 2022@item report-identical-files 2023@samp{-s} in @code{diff}. 2024 2025@item reset-access-time 2026@samp{-a} in @code{cpio}. 2027 2028@item reverse 2029@samp{-r} in @code{ls} and @code{nm}. 2030 2031@item reversed-ed 2032@samp{-f} in @code{diff}. 2033 2034@item right-side-defs 2035@samp{-R} in @code{ptx}. 2036 2037@item same-order 2038@samp{-s} in @code{tar}. 2039 2040@item same-permissions 2041@samp{-p} in @code{tar}. 2042 2043@item save 2044@samp{-g} in @code{stty}. 2045 2046@item se 2047Used in GDB. 2048 2049@item sentence-regexp 2050@samp{-S} in @code{ptx}. 2051 2052@item separate-dirs 2053@samp{-S} in @code{du}. 2054 2055@item separator 2056@samp{-s} in @code{tac}. 2057 2058@item sequence 2059Used by @code{recode} to chose files or pipes for sequencing passes. 2060 2061@item shell 2062@samp{-s} in @code{su}. 2063 2064@item show-all 2065@samp{-A} in @code{cat}. 2066 2067@item show-c-function 2068@samp{-p} in @code{diff}. 2069 2070@item show-ends 2071@samp{-E} in @code{cat}. 2072 2073@item show-function-line 2074@samp{-F} in @code{diff}. 2075 2076@item show-tabs 2077@samp{-T} in @code{cat}. 2078 2079@item silent 2080Used in many programs to inhibit the usual output. 2081Every program accepting 2082@samp{--silent} should accept @samp{--quiet} as a synonym. 2083 2084@item size 2085@samp{-s} in @code{ls}. 2086 2087@item socket 2088Specify a file descriptor for a network server to use for its socket, 2089instead of opening and binding a new socket. This provides a way to 2090run, in a non-privileged process, a server that normally needs a 2091reserved port number. 2092 2093@item sort 2094Used in @code{ls}. 2095 2096@item source 2097@samp{-W source} in @code{gawk}. 2098 2099@item sparse 2100@samp{-S} in @code{tar}. 2101 2102@item speed-large-files 2103@samp{-H} in @code{diff}. 2104 2105@item split-at 2106@samp{-E} in @code{unshar}. 2107 2108@item split-size-limit 2109@samp{-L} in @code{shar}. 2110 2111@item squeeze-blank 2112@samp{-s} in @code{cat}. 2113 2114@item start-delete 2115@samp{-w} in @code{wdiff}. 2116 2117@item start-insert 2118@samp{-y} in @code{wdiff}. 2119 2120@item starting-file 2121Used in @code{tar} and @code{diff} to specify which file within 2122a directory to start processing with. 2123 2124@item statistics 2125@samp{-s} in @code{wdiff}. 2126 2127@item stdin-file-list 2128@samp{-S} in @code{shar}. 2129 2130@item stop 2131@samp{-S} in @code{make}. 2132 2133@item strict 2134@samp{-s} in @code{recode}. 2135 2136@item strip 2137@samp{-s} in @code{install}. 2138 2139@item strip-all 2140@samp{-s} in @code{strip}. 2141 2142@item strip-debug 2143@samp{-S} in @code{strip}. 2144 2145@item submitter 2146@samp{-s} in @code{shar}. 2147 2148@item suffix 2149@samp{-S} in @code{cp}, @code{ln}, @code{mv}. 2150 2151@item suffix-format 2152@samp{-b} in @code{csplit}. 2153 2154@item sum 2155@samp{-s} in @code{gprof}. 2156 2157@item summarize 2158@samp{-s} in @code{du}. 2159 2160@item symbolic 2161@samp{-s} in @code{ln}. 2162 2163@item symbols 2164Used in GDB and @code{objdump}. 2165 2166@item synclines 2167@samp{-s} in @code{m4}. 2168 2169@item sysname 2170@samp{-s} in @code{uname}. 2171 2172@item tabs 2173@samp{-t} in @code{expand} and @code{unexpand}. 2174 2175@item tabsize 2176@samp{-T} in @code{ls}. 2177 2178@item terminal 2179@samp{-T} in @code{tput} and @code{ul}. 2180@samp{-t} in @code{wdiff}. 2181 2182@item text 2183@samp{-a} in @code{diff}. 2184 2185@item text-files 2186@samp{-T} in @code{shar}. 2187 2188@item time 2189Used in @code{ls} and @code{touch}. 2190 2191@item timeout 2192Specify how long to wait before giving up on some operation. 2193 2194@item to-stdout 2195@samp{-O} in @code{tar}. 2196 2197@item total 2198@samp{-c} in @code{du}. 2199 2200@item touch 2201@samp{-t} in @code{make}, @code{ranlib}, and @code{recode}. 2202 2203@item trace 2204@samp{-t} in @code{m4}. 2205 2206@item traditional 2207@samp{-t} in @code{hello}; 2208@samp{-W traditional} in @code{gawk}; 2209@samp{-G} in @code{ed}, @code{m4}, and @code{ptx}. 2210 2211@item tty 2212Used in GDB. 2213 2214@item typedefs 2215@samp{-t} in @code{ctags}. 2216 2217@item typedefs-and-c++ 2218@samp{-T} in @code{ctags}. 2219 2220@item typeset-mode 2221@samp{-t} in @code{ptx}. 2222 2223@item uncompress 2224@samp{-z} in @code{tar}. 2225 2226@item unconditional 2227@samp{-u} in @code{cpio}. 2228 2229@item undefine 2230@samp{-U} in @code{m4}. 2231 2232@item undefined-only 2233@samp{-u} in @code{nm}. 2234 2235@item update 2236@samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}. 2237 2238@item usage 2239Used in @code{gawk}; same as @samp{--help}. 2240 2241@item uuencode 2242@samp{-B} in @code{shar}. 2243 2244@item vanilla-operation 2245@samp{-V} in @code{shar}. 2246 2247@item verbose 2248Print more information about progress. Many programs support this. 2249 2250@item verify 2251@samp{-W} in @code{tar}. 2252 2253@item version 2254Print the version number. 2255 2256@item version-control 2257@samp{-V} in @code{cp}, @code{ln}, @code{mv}. 2258 2259@item vgrind 2260@samp{-v} in @code{ctags}. 2261 2262@item volume 2263@samp{-V} in @code{tar}. 2264 2265@item what-if 2266@samp{-W} in @code{make}. 2267 2268@item whole-size-limit 2269@samp{-l} in @code{shar}. 2270 2271@item width 2272@samp{-w} in @code{ls} and @code{ptx}. 2273 2274@item word-regexp 2275@samp{-W} in @code{ptx}. 2276 2277@item writable 2278@samp{-T} in @code{who}. 2279 2280@item zeros 2281@samp{-z} in @code{gprof}. 2282@end table 2283 2284@node OID Allocations 2285@section OID Allocations 2286@cindex OID allocations for GNU 2287@cindex SNMP 2288@cindex LDAP 2289@cindex X.509 2290 2291The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the 2292GNU Project (thanks to Sergey Poznyakoff). These are used for SNMP, 2293LDAP, X.509 certificates, and so on. The web site 2294@url{http://www.alvestrand.no/objectid} has a (voluntary) listing of 2295many OID assignments. 2296 2297If you need a new slot for your GNU package, write 2298@email{maintainers@@gnu.org}. Here is a list of arcs currently 2299assigned: 2300 2301@example 2302@include gnu-oids.texi 2303@end example 2304 2305 2306@node Memory Usage 2307@section Memory Usage 2308@cindex memory usage 2309 2310If a program typically uses just a few meg of memory, don't bother making any 2311effort to reduce memory usage. For example, if it is impractical for 2312other reasons to operate on files more than a few meg long, it is 2313reasonable to read entire input files into memory to operate on them. 2314 2315However, for programs such as @code{cat} or @code{tail}, that can 2316usefully operate on very large files, it is important to avoid using a 2317technique that would artificially limit the size of files it can handle. 2318If a program works by lines and could be applied to arbitrary 2319user-supplied input files, it should keep only a line in memory, because 2320this is not very hard and users will want to be able to operate on input 2321files that are bigger than will fit in memory all at once. 2322 2323If your program creates complicated data structures, just make them in 2324memory and give a fatal error if @code{malloc} returns zero. 2325 2326@pindex valgrind 2327@cindex memory leak 2328Memory analysis tools such as @command{valgrind} can be useful, but 2329don't complicate a program merely to avoid their false alarms. For 2330example, if memory is used until just before a process exits, don't 2331free it simply to silence such a tool. 2332 2333 2334@node File Usage 2335@section File Usage 2336@cindex file usage 2337 2338Programs should be prepared to operate when @file{/usr} and @file{/etc} 2339are read-only file systems. Thus, if the program manages log files, 2340lock files, backup files, score files, or any other files which are 2341modified for internal purposes, these files should not be stored in 2342@file{/usr} or @file{/etc}. 2343 2344There are two exceptions. @file{/etc} is used to store system 2345configuration information; it is reasonable for a program to modify 2346files in @file{/etc} when its job is to update the system configuration. 2347Also, if the user explicitly asks to modify one file in a directory, it 2348is reasonable for the program to store other files in the same 2349directory. 2350 2351@node Writing C 2352@chapter Making The Best Use of C 2353 2354This chapter provides advice on how best to use the C language 2355when writing GNU software. 2356 2357@menu 2358* Formatting:: Formatting your source code. 2359* Comments:: Commenting your work. 2360* Syntactic Conventions:: Clean use of C constructs. 2361* Names:: Naming variables, functions, and files. 2362* System Portability:: Portability among different operating systems. 2363* CPU Portability:: Supporting the range of CPU types. 2364* System Functions:: Portability and ``standard'' library functions. 2365* Internationalization:: Techniques for internationalization. 2366* Character Set:: Use ASCII by default. 2367* Quote Characters:: Use "..." or '...' in the C locale. 2368* Mmap:: How you can safely use @code{mmap}. 2369@end menu 2370 2371@node Formatting 2372@section Formatting Your Source Code 2373@cindex formatting source code 2374 2375@cindex line length 2376@cindex length of source lines 2377Please keep the length of source lines to 79 characters or less, for 2378maximum readability in the widest range of environments. 2379 2380@cindex open brace 2381@cindex braces, in C source 2382@cindex function definitions, formatting 2383It is important to put the open-brace that starts the body of a C 2384function in column one, so that they will start a defun. Several 2385tools look for open-braces in column one to find the beginnings of C 2386functions. These tools will not work on code not formatted that way. 2387 2388Avoid putting open-brace, open-parenthesis or open-bracket in column 2389one when they are inside a function, so that they won't start a defun. 2390The open-brace that starts a @code{struct} body can go in column one 2391if you find it useful to treat that definition as a defun. 2392 2393It is also important for function definitions to start the name of the 2394function in column one. This helps people to search for function 2395definitions, and may also help certain tools recognize them. Thus, 2396using Standard C syntax, the format is this: 2397 2398@example 2399static char * 2400concat (char *s1, char *s2) 2401@{ 2402 @dots{} 2403@} 2404@end example 2405 2406@noindent 2407or, if you want to use traditional C syntax, format the definition like 2408this: 2409 2410@example 2411static char * 2412concat (s1, s2) /* Name starts in column one here */ 2413 char *s1, *s2; 2414@{ /* Open brace in column one here */ 2415 @dots{} 2416@} 2417@end example 2418 2419In Standard C, if the arguments don't fit nicely on one line, 2420split it like this: 2421 2422@example 2423int 2424lots_of_args (int an_integer, long a_long, short a_short, 2425 double a_double, float a_float) 2426@dots{} 2427@end example 2428 2429@cindex @code{struct} types, formatting 2430@cindex @code{enum} types, formatting 2431For @code{struct} and @code{enum} types, likewise put the braces in 2432column one, unless the whole contents fits on one line: 2433 2434@example 2435struct foo 2436@{ 2437 int a, b; 2438@} 2439@exdent @r{or} 2440struct foo @{ int a, b; @} 2441@end example 2442 2443The rest of this section gives our recommendations for other aspects of 2444C formatting style, which is also the default style of the @code{indent} 2445program in version 1.2 and newer. It corresponds to the options 2446 2447@smallexample 2448-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 2449-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob 2450@end smallexample 2451 2452We don't think of these recommendations as requirements, because it 2453causes no problems for users if two different programs have different 2454formatting styles. 2455 2456But whatever style you use, please use it consistently, since a mixture 2457of styles within one program tends to look ugly. If you are 2458contributing changes to an existing program, please follow the style of 2459that program. 2460 2461For the body of the function, our recommended style looks like this: 2462 2463@example 2464if (x < foo (y, z)) 2465 haha = bar[4] + 5; 2466else 2467 @{ 2468 while (z) 2469 @{ 2470 haha += foo (z, z); 2471 z--; 2472 @} 2473 return ++x + bar (); 2474 @} 2475@end example 2476 2477@cindex spaces before open-paren 2478We find it easier to read a program when it has spaces before the 2479open-parentheses and after the commas. Especially after the commas. 2480 2481When you split an expression into multiple lines, split it 2482before an operator, not after one. Here is the right way: 2483 2484@cindex expressions, splitting 2485@example 2486if (foo_this_is_long && bar > win (x, y, z) 2487 && remaining_condition) 2488@end example 2489 2490Try to avoid having two operators of different precedence at the same 2491level of indentation. For example, don't write this: 2492 2493@example 2494mode = (inmode[j] == VOIDmode 2495 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) 2496 ? outmode[j] : inmode[j]); 2497@end example 2498 2499Instead, use extra parentheses so that the indentation shows the nesting: 2500 2501@example 2502mode = ((inmode[j] == VOIDmode 2503 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) 2504 ? outmode[j] : inmode[j]); 2505@end example 2506 2507Insert extra parentheses so that Emacs will indent the code properly. 2508For example, the following indentation looks nice if you do it by hand, 2509 2510@example 2511v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 2512 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; 2513@end example 2514 2515@noindent 2516but Emacs would alter it. Adding a set of parentheses produces 2517something that looks equally nice, and which Emacs will preserve: 2518 2519@example 2520v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 2521 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); 2522@end example 2523 2524Format do-while statements like this: 2525 2526@example 2527do 2528 @{ 2529 a = foo (a); 2530 @} 2531while (a > 0); 2532@end example 2533 2534@cindex formfeed 2535@cindex control-L 2536Please use formfeed characters (control-L) to divide the program into 2537pages at logical places (but not within a function). It does not matter 2538just how long the pages are, since they do not have to fit on a printed 2539page. The formfeeds should appear alone on lines by themselves. 2540 2541@node Comments 2542@section Commenting Your Work 2543@cindex commenting 2544 2545Every program should start with a comment saying briefly what it is for. 2546Example: @samp{fmt - filter for simple filling of text}. This comment 2547should be at the top of the source file containing the @samp{main} 2548function of the program. 2549 2550Also, please write a brief comment at the start of each source file, 2551with the file name and a line or two about the overall purpose of the 2552file. 2553 2554Please write the comments in a GNU program in English, because English 2555is the one language that nearly all programmers in all countries can 2556read. If you do not write English well, please write comments in 2557English as well as you can, then ask other people to help rewrite them. 2558If you can't write comments in English, please find someone to work with 2559you and translate your comments into English. 2560 2561Please put a comment on each function saying what the function does, 2562what sorts of arguments it gets, and what the possible values of 2563arguments mean and are used for. It is not necessary to duplicate in 2564words the meaning of the C argument declarations, if a C type is being 2565used in its customary fashion. If there is anything nonstandard about 2566its use (such as an argument of type @code{char *} which is really the 2567address of the second character of a string, not the first), or any 2568possible values that would not work the way one would expect (such as, 2569that strings containing newlines are not guaranteed to work), be sure 2570to say so. 2571 2572Also explain the significance of the return value, if there is one. 2573 2574Please put two spaces after the end of a sentence in your comments, so 2575that the Emacs sentence commands will work. Also, please write 2576complete sentences and capitalize the first word. If a lower-case 2577identifier comes at the beginning of a sentence, don't capitalize it! 2578Changing the spelling makes it a different identifier. If you don't 2579like starting a sentence with a lower case letter, write the sentence 2580differently (e.g., ``The identifier lower-case is @dots{}''). 2581 2582The comment on a function is much clearer if you use the argument 2583names to speak about the argument values. The variable name itself 2584should be lower case, but write it in upper case when you are speaking 2585about the value rather than the variable itself. Thus, ``the inode 2586number NODE_NUM'' rather than ``an inode''. 2587 2588There is usually no purpose in restating the name of the function in 2589the comment before it, because readers can see that for themselves. 2590There might be an exception when the comment is so long that the function 2591itself would be off the bottom of the screen. 2592 2593There should be a comment on each static variable as well, like this: 2594 2595@example 2596/* Nonzero means truncate lines in the display; 2597 zero means continue them. */ 2598int truncate_lines; 2599@end example 2600 2601@cindex conditionals, comments for 2602@cindex @code{#endif}, commenting 2603Every @samp{#endif} should have a comment, except in the case of short 2604conditionals (just a few lines) that are not nested. The comment should 2605state the condition of the conditional that is ending, @emph{including 2606its sense}. @samp{#else} should have a comment describing the condition 2607@emph{and sense} of the code that follows. For example: 2608 2609@example 2610@group 2611#ifdef foo 2612 @dots{} 2613#else /* not foo */ 2614 @dots{} 2615#endif /* not foo */ 2616@end group 2617@group 2618#ifdef foo 2619 @dots{} 2620#endif /* foo */ 2621@end group 2622@end example 2623 2624@noindent 2625but, by contrast, write the comments this way for a @samp{#ifndef}: 2626 2627@example 2628@group 2629#ifndef foo 2630 @dots{} 2631#else /* foo */ 2632 @dots{} 2633#endif /* foo */ 2634@end group 2635@group 2636#ifndef foo 2637 @dots{} 2638#endif /* not foo */ 2639@end group 2640@end example 2641 2642@node Syntactic Conventions 2643@section Clean Use of C Constructs 2644@cindex syntactic conventions 2645 2646@cindex implicit @code{int} 2647@cindex function argument, declaring 2648Please explicitly declare the types of all objects. For example, you 2649should explicitly declare all arguments to functions, and you should 2650declare functions to return @code{int} rather than omitting the 2651@code{int}. 2652 2653@cindex compiler warnings 2654@cindex @samp{-Wall} compiler option 2655Some programmers like to use the GCC @samp{-Wall} option, and change the 2656code whenever it issues a warning. If you want to do this, then do. 2657Other programmers prefer not to use @samp{-Wall}, because it gives 2658warnings for valid and legitimate code which they do not want to change. 2659If you want to do this, then do. The compiler should be your servant, 2660not your master. 2661 2662@pindex clang 2663@pindex lint 2664Don't make the program ugly just to placate static analysis tools such 2665as @command{lint}, @command{clang}, and GCC with extra warnings 2666options such as @option{-Wconversion} and @option{-Wundef}. These 2667tools can help find bugs and unclear code, but they can also generate 2668so many false alarms that it hurts readability to silence them with 2669unnecessary casts, wrappers, and other complications. For example, 2670please don't insert casts to @code{void} or calls to do-nothing 2671functions merely to pacify a lint checker. 2672 2673Declarations of external functions and functions to appear later in the 2674source file should all go in one place near the beginning of the file 2675(somewhere before the first function definition in the file), or else 2676should go in a header file. Don't put @code{extern} declarations inside 2677functions. 2678 2679@cindex temporary variables 2680It used to be common practice to use the same local variables (with 2681names like @code{tem}) over and over for different values within one 2682function. Instead of doing this, it is better to declare a separate local 2683variable for each distinct purpose, and give it a name which is 2684meaningful. This not only makes programs easier to understand, it also 2685facilitates optimization by good compilers. You can also move the 2686declaration of each local variable into the smallest scope that includes 2687all its uses. This makes the program even cleaner. 2688 2689Don't use local variables or parameters that shadow global identifiers. 2690GCC's @samp{-Wshadow} option can detect this problem. 2691 2692@cindex multiple variables in a line 2693Don't declare multiple variables in one declaration that spans lines. 2694Start a new declaration on each line, instead. For example, instead 2695of this: 2696 2697@example 2698@group 2699int foo, 2700 bar; 2701@end group 2702@end example 2703 2704@noindent 2705write either this: 2706 2707@example 2708int foo, bar; 2709@end example 2710 2711@noindent 2712or this: 2713 2714@example 2715int foo; 2716int bar; 2717@end example 2718 2719@noindent 2720(If they are global variables, each should have a comment preceding it 2721anyway.) 2722 2723When you have an @code{if}-@code{else} statement nested in another 2724@code{if} statement, always put braces around the @code{if}-@code{else}. 2725Thus, never write like this: 2726 2727@example 2728if (foo) 2729 if (bar) 2730 win (); 2731 else 2732 lose (); 2733@end example 2734 2735@noindent 2736always like this: 2737 2738@example 2739if (foo) 2740 @{ 2741 if (bar) 2742 win (); 2743 else 2744 lose (); 2745 @} 2746@end example 2747 2748If you have an @code{if} statement nested inside of an @code{else} 2749statement, either write @code{else if} on one line, like this, 2750 2751@example 2752if (foo) 2753 @dots{} 2754else if (bar) 2755 @dots{} 2756@end example 2757 2758@noindent 2759with its @code{then}-part indented like the preceding @code{then}-part, 2760or write the nested @code{if} within braces like this: 2761 2762@example 2763if (foo) 2764 @dots{} 2765else 2766 @{ 2767 if (bar) 2768 @dots{} 2769 @} 2770@end example 2771 2772Don't declare both a structure tag and variables or typedefs in the 2773same declaration. Instead, declare the structure tag separately 2774and then use it to declare the variables or typedefs. 2775 2776Try to avoid assignments inside @code{if}-conditions (assignments 2777inside @code{while}-conditions are ok). For example, don't write 2778this: 2779 2780@example 2781if ((foo = (char *) malloc (sizeof *foo)) == 0) 2782 fatal ("virtual memory exhausted"); 2783@end example 2784 2785@noindent 2786instead, write this: 2787 2788@example 2789foo = (char *) malloc (sizeof *foo); 2790if (foo == 0) 2791 fatal ("virtual memory exhausted"); 2792@end example 2793 2794This example uses zero without a cast as a null pointer constant. 2795This is perfectly fine, except that a cast is needed when calling a 2796varargs function or when using @code{sizeof}. 2797 2798@node Names 2799@section Naming Variables, Functions, and Files 2800 2801@cindex names of variables, functions, and files 2802The names of global variables and functions in a program serve as 2803comments of a sort. So don't choose terse names---instead, look for 2804names that give useful information about the meaning of the variable or 2805function. In a GNU program, names should be English, like other 2806comments. 2807 2808Local variable names can be shorter, because they are used only within 2809one context, where (presumably) comments explain their purpose. 2810 2811Try to limit your use of abbreviations in symbol names. It is ok to 2812make a few abbreviations, explain what they mean, and then use them 2813frequently, but don't use lots of obscure abbreviations. 2814 2815Please use underscores to separate words in a name, so that the Emacs 2816word commands can be useful within them. Stick to lower case; reserve 2817upper case for macros and @code{enum} constants, and for name-prefixes 2818that follow a uniform convention. 2819 2820For example, you should use names like @code{ignore_space_change_flag}; 2821don't use names like @code{iCantReadThis}. 2822 2823Variables that indicate whether command-line options have been 2824specified should be named after the meaning of the option, not after 2825the option-letter. A comment should state both the exact meaning of 2826the option and its letter. For example, 2827 2828@example 2829@group 2830/* Ignore changes in horizontal whitespace (-b). */ 2831int ignore_space_change_flag; 2832@end group 2833@end example 2834 2835When you want to define names with constant integer values, use 2836@code{enum} rather than @samp{#define}. GDB knows about enumeration 2837constants. 2838 2839@cindex file-name limitations 2840@pindex doschk 2841You might want to make sure that none of the file names would conflict 2842if the files were loaded onto an MS-DOS file system which shortens the 2843names. You can use the program @code{doschk} to test for this. 2844 2845Some GNU programs were designed to limit themselves to file names of 14 2846characters or less, to avoid file name conflicts if they are read into 2847older System V systems. Please preserve this feature in the existing 2848GNU programs that have it, but there is no need to do this in new GNU 2849programs. @code{doschk} also reports file names longer than 14 2850characters. 2851 2852 2853@node System Portability 2854@section Portability between System Types 2855@cindex portability, between system types 2856 2857In the Unix world, ``portability'' refers to porting to different Unix 2858versions. For a GNU program, this kind of portability is desirable, but 2859not paramount. 2860 2861The primary purpose of GNU software is to run on top of the GNU kernel, 2862compiled with the GNU C compiler, on various types of CPU. So the 2863kinds of portability that are absolutely necessary are quite limited. 2864But it is important to support Linux-based GNU systems, since they 2865are the form of GNU that is popular. 2866 2867Beyond that, it is good to support the other free operating systems 2868(*BSD), and it is nice to support other Unix-like systems if you want 2869to. Supporting a variety of Unix-like systems is desirable, although 2870not paramount. It is usually not too hard, so you may as well do it. 2871But you don't have to consider it an obligation, if it does turn out to 2872be hard. 2873 2874@pindex autoconf 2875The easiest way to achieve portability to most Unix-like systems is to 2876use Autoconf. It's unlikely that your program needs to know more 2877information about the host platform than Autoconf can provide, simply 2878because most of the programs that need such knowledge have already been 2879written. 2880 2881Avoid using the format of semi-internal data bases (e.g., directories) 2882when there is a higher-level alternative (@code{readdir}). 2883 2884@cindex non-POSIX systems, and portability 2885As for systems that are not like Unix, such as MSDOS, Windows, VMS, MVS, 2886and older Macintosh systems, supporting them is often a lot of work. 2887When that is the case, it is better to spend your time adding features 2888that will be useful on GNU and GNU/Linux, rather than on supporting 2889other incompatible systems. 2890 2891If you do support Windows, please do not abbreviate it as ``win''. In 2892hacker terminology, calling something a ``win'' is a form of praise. 2893You're free to praise Microsoft Windows on your own if you want, but 2894please don't do this in GNU packages. Instead of abbreviating 2895``Windows'' to ``win'', you can write it in full or abbreviate it to 2896``woe'' or ``w''. In GNU Emacs, for instance, we use @samp{w32} in 2897file names of Windows-specific files, but the macro for Windows 2898conditionals is called @code{WINDOWSNT}. 2899 2900It is a good idea to define the ``feature test macro'' 2901@code{_GNU_SOURCE} when compiling your C files. When you compile on GNU 2902or GNU/Linux, this will enable the declarations of GNU library extension 2903functions, and that will usually give you a compiler error message if 2904you define the same function names in some other way in your program. 2905(You don't have to actually @emph{use} these functions, if you prefer 2906to make the program more portable to other systems.) 2907 2908But whether or not you use these GNU extensions, you should avoid 2909using their names for any other meanings. Doing so would make it hard 2910to move your code into other GNU programs. 2911 2912@node CPU Portability 2913@section Portability between CPUs 2914 2915@cindex data types, and portability 2916@cindex portability, and data types 2917Even GNU systems will differ because of differences among CPU 2918types---for example, difference in byte ordering and alignment 2919requirements. It is absolutely essential to handle these differences. 2920However, don't make any effort to cater to the possibility that an 2921@code{int} will be less than 32 bits. We don't support 16-bit machines 2922in GNU. 2923 2924Similarly, don't make any effort to cater to the possibility that 2925@code{long} will be smaller than predefined types like @code{size_t}. 2926For example, the following code is ok: 2927 2928@example 2929printf ("size = %lu\n", (unsigned long) sizeof array); 2930printf ("diff = %ld\n", (long) (pointer2 - pointer1)); 2931@end example 2932 29331989 Standard C requires this to work, and we know of only one 2934counterexample: 64-bit programs on Microsoft Windows. We will leave 2935it to those who want to port GNU programs to that environment to 2936figure out how to do it. 2937 2938Predefined file-size types like @code{off_t} are an exception: they are 2939longer than @code{long} on many platforms, so code like the above won't 2940work with them. One way to print an @code{off_t} value portably is to 2941print its digits yourself, one by one. 2942 2943Don't assume that the address of an @code{int} object is also the 2944address of its least-significant byte. This is false on big-endian 2945machines. Thus, don't make the following mistake: 2946 2947@example 2948int c; 2949@dots{} 2950while ((c = getchar ()) != EOF) 2951 write (file_descriptor, &c, 1); 2952@end example 2953 2954@noindent Instead, use @code{unsigned char} as follows. (The @code{unsigned} 2955is for portability to unusual systems where @code{char} is signed and 2956where there is integer overflow checking.) 2957 2958@example 2959int c; 2960while ((c = getchar ()) != EOF) 2961 @{ 2962 unsigned char u = c; 2963 write (file_descriptor, &u, 1); 2964 @} 2965@end example 2966 2967@cindex casting pointers to integers 2968Avoid casting pointers to integers if you can. Such casts greatly 2969reduce portability, and in most programs they are easy to avoid. In the 2970cases where casting pointers to integers is essential---such as, a Lisp 2971interpreter which stores type information as well as an address in one 2972word---you'll have to make explicit provisions to handle different word 2973sizes. You will also need to make provision for systems in which the 2974normal range of addresses you can get from @code{malloc} starts far away 2975from zero. 2976 2977 2978@node System Functions 2979@section Calling System Functions 2980 2981@cindex C library functions, and portability 2982@cindex POSIX functions, and portability 2983@cindex library functions, and portability 2984@cindex portability, and library functions 2985 2986Historically, C implementations differed substantially, and many 2987systems lacked a full implementation of ANSI/ISO C89. Nowadays, 2988however, all practical systems have a C89 compiler and GNU C supports 2989almost all of C99 and some of C11. Similarly, most systems implement 2990POSIX.1-2001 libraries and tools, and many have POSIX.1-2008. 2991 2992Hence, there is little reason to support old C or non-POSIX systems, 2993and you may want to take advantage of standard C and POSIX to write 2994clearer, more portable, or faster code. You should use standard 2995interfaces where possible; but if GNU extensions make your program 2996more maintainable, powerful, or otherwise better, don't hesitate to 2997use them. In any case, don't make your own declaration of system 2998functions; that's a recipe for conflict. 2999 3000Despite the standards, nearly every library function has some sort of 3001portability issue on some system or another. Here are some examples: 3002 3003@table @code 3004@item open 3005Names with trailing @code{/}'s are mishandled on many platforms. 3006 3007@item printf 3008@code{long double} may be unimplemented; floating values Infinity and 3009NaN are often mishandled; output for large precisions may be 3010incorrect. 3011 3012@item readlink 3013May return @code{int} instead of @code{ssize_t}. 3014 3015@item scanf 3016On Windows, @code{errno} is not set on failure. 3017@end table 3018 3019@cindex Gnulib 3020@uref{http://www.gnu.org/software/gnulib/, Gnulib} is a big help in 3021this regard. Gnulib provides implementations of standard interfaces 3022on many of the systems that lack them, including portable 3023implementations of enhanced GNU interfaces, thereby making their use 3024portable, and of POSIX-1.2008 interfaces, some of which are missing 3025even on up-to-date GNU systems. 3026 3027@findex xmalloc, in Gnulib 3028@findex error messages, in Gnulib 3029@findex data structures, in Gnulib 3030Gnulib also provides many useful non-standard interfaces; for example, 3031C implementations of standard data structures (hash tables, binary 3032trees), error-checking type-safe wrappers for memory allocation 3033functions (@code{xmalloc}, @code{xrealloc}), and output of error 3034messages. 3035 3036Gnulib integrates with GNU Autoconf and Automake to remove much of the 3037burden of writing portable code from the programmer: Gnulib makes your 3038configure script automatically determine what features are missing and 3039use the Gnulib code to supply the missing pieces. 3040 3041The Gnulib and Autoconf manuals have extensive sections on 3042portability: @ref{Top,, Introduction, gnulib, Gnulib} and 3043@pxref{Portable C and C++,,, autoconf, Autoconf}. Please consult them 3044for many more details. 3045 3046 3047@node Internationalization 3048@section Internationalization 3049@cindex internationalization 3050 3051@pindex gettext 3052GNU has a library called GNU gettext that makes it easy to translate the 3053messages in a program into various languages. You should use this 3054library in every program. Use English for the messages as they appear 3055in the program, and let gettext provide the way to translate them into 3056other languages. 3057 3058Using GNU gettext involves putting a call to the @code{gettext} macro 3059around each string that might need translation---like this: 3060 3061@example 3062printf (gettext ("Processing file '%s'..."), file); 3063@end example 3064 3065@noindent 3066This permits GNU gettext to replace the string @code{"Processing file 3067'%s'..."} with a translated version. 3068 3069Once a program uses gettext, please make a point of writing calls to 3070@code{gettext} when you add new strings that call for translation. 3071 3072Using GNU gettext in a package involves specifying a @dfn{text domain 3073name} for the package. The text domain name is used to separate the 3074translations for this package from the translations for other packages. 3075Normally, the text domain name should be the same as the name of the 3076package---for example, @samp{coreutils} for the GNU core utilities. 3077 3078@cindex message text, and internationalization 3079To enable gettext to work well, avoid writing code that makes 3080assumptions about the structure of words or sentences. When you want 3081the precise text of a sentence to vary depending on the data, use two or 3082more alternative string constants each containing a complete sentences, 3083rather than inserting conditionalized words or phrases into a single 3084sentence framework. 3085 3086Here is an example of what not to do: 3087 3088@smallexample 3089printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk"); 3090@end smallexample 3091 3092If you apply gettext to all strings, like this, 3093 3094@smallexample 3095printf (gettext ("%s is full"), 3096 capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk")); 3097@end smallexample 3098 3099@noindent 3100the translator will hardly know that "disk" and "floppy disk" are meant to 3101be substituted in the other string. Worse, in some languages (like French) 3102the construction will not work: the translation of the word "full" depends 3103on the gender of the first part of the sentence; it happens to be not the 3104same for "disk" as for "floppy disk". 3105 3106Complete sentences can be translated without problems: 3107 3108@example 3109printf (capacity > 5000000 ? gettext ("disk is full") 3110 : gettext ("floppy disk is full")); 3111@end example 3112 3113A similar problem appears at the level of sentence structure with this 3114code: 3115 3116@example 3117printf ("# Implicit rule search has%s been done.\n", 3118 f->tried_implicit ? "" : " not"); 3119@end example 3120 3121@noindent 3122Adding @code{gettext} calls to this code cannot give correct results for 3123all languages, because negation in some languages requires adding words 3124at more than one place in the sentence. By contrast, adding 3125@code{gettext} calls does the job straightforwardly if the code starts 3126out like this: 3127 3128@example 3129printf (f->tried_implicit 3130 ? "# Implicit rule search has been done.\n", 3131 : "# Implicit rule search has not been done.\n"); 3132@end example 3133 3134Another example is this one: 3135 3136@example 3137printf ("%d file%s processed", nfiles, 3138 nfiles != 1 ? "s" : ""); 3139@end example 3140 3141@noindent 3142The problem with this example is that it assumes that plurals are made 3143by adding `s'. If you apply gettext to the format string, like this, 3144 3145@example 3146printf (gettext ("%d file%s processed"), nfiles, 3147 nfiles != 1 ? "s" : ""); 3148@end example 3149 3150@noindent 3151the message can use different words, but it will still be forced to use 3152`s' for the plural. Here is a better way, with gettext being applied to 3153the two strings independently: 3154 3155@example 3156printf ((nfiles != 1 ? gettext ("%d files processed") 3157 : gettext ("%d file processed")), 3158 nfiles); 3159@end example 3160 3161@noindent 3162But this still doesn't work for languages like Polish, which has three 3163plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 24, ... 3164and one for the rest. The GNU @code{ngettext} function solves this problem: 3165 3166@example 3167printf (ngettext ("%d files processed", "%d file processed", nfiles), 3168 nfiles); 3169@end example 3170 3171 3172@node Character Set 3173@section Character Set 3174@cindex character set 3175@cindex encodings 3176@cindex ASCII characters 3177@cindex non-ASCII characters 3178 3179Sticking to the ASCII character set (plain text, 7-bit characters) is 3180preferred in GNU source code comments, text documents, and other 3181contexts, unless there is good reason to do something else because of 3182the application domain. For example, if source code deals with the 3183French Revolutionary calendar, it is OK if its literal strings contain 3184accented characters in month names like ``Flor@'eal''. Also, it is OK 3185(but not required) to use non-ASCII characters to represent proper 3186names of contributors in change logs (@pxref{Change Logs}). 3187 3188If you need to use non-ASCII characters, you should normally stick 3189with one encoding, certainly within a single file. UTF-8 is likely to 3190be the best choice. 3191 3192 3193@node Quote Characters 3194@section Quote Characters 3195@cindex quote characters 3196@cindex locale-specific quote characters 3197@cindex left quote 3198@cindex right quote 3199@cindex opening quote 3200@cindex single quote 3201@cindex double quote 3202@cindex grave accent 3203@set txicodequoteundirected 3204@set txicodequotebacktick 3205 3206In the C locale, the output of GNU programs should stick to plain 3207ASCII for quotation characters in messages to users: preferably 0x22 3208(@samp{"}) or 0x27 (@samp{'}) for both opening and closing quotes. 3209Although GNU programs traditionally used 0x60 (@samp{`}) for opening 3210and 0x27 (@samp{'}) for closing quotes, nowadays quotes @samp{`like 3211this'} are typically rendered asymmetrically, so quoting @samp{"like 3212this"} or @samp{'like this'} typically looks better. 3213 3214It is ok, but not required, for GNU programs to generate 3215locale-specific quotes in non-C locales. For example: 3216 3217@example 3218printf (gettext ("Processing file '%s'..."), file); 3219@end example 3220 3221@noindent 3222Here, a French translation might cause @code{gettext} to return the 3223string @code{"Traitement de fichier 3224@guilsinglleft{}@tie{}%s@tie{}@guilsinglright{}..."}, yielding quotes 3225more appropriate for a French locale. 3226 3227Sometimes a program may need to use opening and closing quotes 3228directly. By convention, @code{gettext} translates the string 3229@samp{"`"} to the opening quote and the string @samp{"'"} to the 3230closing quote, and a program can use these translations. Generally, 3231though, it is better to translate quote characters in the context of 3232longer strings. 3233 3234If the output of your program is ever likely to be parsed by another 3235program, it is good to provide an option that makes this parsing 3236reliable. For example, you could escape special characters using 3237conventions from the C language or the Bourne shell. See for example 3238the option @option{--quoting-style} of GNU @code{ls}. 3239 3240@clear txicodequoteundirected 3241@clear txicodequotebacktick 3242 3243 3244@node Mmap 3245@section Mmap 3246@findex mmap 3247 3248If you use @code{mmap} to read or write files, don't assume it either 3249works on all files or fails for all files. It may work on some files 3250and fail on others. 3251 3252The proper way to use @code{mmap} is to try it on the specific file for 3253which you want to use it---and if @code{mmap} doesn't work, fall back on 3254doing the job in another way using @code{read} and @code{write}. 3255 3256The reason this precaution is needed is that the GNU kernel (the HURD) 3257provides a user-extensible file system, in which there can be many 3258different kinds of ``ordinary files''. Many of them support 3259@code{mmap}, but some do not. It is important to make programs handle 3260all these kinds of files. 3261 3262 3263@node Documentation 3264@chapter Documenting Programs 3265@cindex documentation 3266 3267A GNU program should ideally come with full free documentation, adequate 3268for both reference and tutorial purposes. If the package can be 3269programmed or extended, the documentation should cover programming or 3270extending it, as well as just using it. 3271 3272@menu 3273* GNU Manuals:: Writing proper manuals. 3274* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. 3275* Manual Structure Details:: Specific structure conventions. 3276* License for Manuals:: Writing the distribution terms for a manual. 3277* Manual Credits:: Giving credit to documentation contributors. 3278* Printed Manuals:: Mentioning the printed manual. 3279* NEWS File:: NEWS files supplement manuals. 3280* Change Logs:: Recording changes. 3281* Man Pages:: Man pages are secondary. 3282* Reading other Manuals:: How far you can go in learning 3283 from other manuals. 3284@end menu 3285 3286@node GNU Manuals 3287@section GNU Manuals 3288 3289The preferred document format for the GNU system is the Texinfo 3290formatting language. Every GNU package should (ideally) have 3291documentation in Texinfo both for reference and for learners. Texinfo 3292makes it possible to produce a good quality formatted book, using 3293@TeX{}, and to generate an Info file. It is also possible to generate 3294HTML output from Texinfo source. See the Texinfo manual, either the 3295hardcopy, or the on-line version available through @code{info} or the 3296Emacs Info subsystem (@kbd{C-h i}). 3297 3298Nowadays some other formats such as Docbook and Sgmltexi can be 3299converted automatically into Texinfo. It is ok to produce the Texinfo 3300documentation by conversion this way, as long as it gives good results. 3301 3302Make sure your manual is clear to a reader who knows nothing about the 3303topic and reads it straight through. This means covering basic topics 3304at the beginning, and advanced topics only later. This also means 3305defining every specialized term when it is first used. 3306 3307Programmers tend to carry over the structure of the program as the 3308structure for its documentation. But this structure is not 3309necessarily good for explaining how to use the program; it may be 3310irrelevant and confusing for a user. 3311 3312Instead, the right way to structure documentation is according to the 3313concepts and questions that a user will have in mind when reading it. 3314This principle applies at every level, from the lowest (ordering 3315sentences in a paragraph) to the highest (ordering of chapter topics 3316within the manual). Sometimes this structure of ideas matches the 3317structure of the implementation of the software being documented---but 3318often they are different. An important part of learning to write good 3319documentation is to learn to notice when you have unthinkingly 3320structured the documentation like the implementation, stop yourself, 3321and look for better alternatives. 3322 3323For example, each program in the GNU system probably ought to be 3324documented in one manual; but this does not mean each program should 3325have its own manual. That would be following the structure of the 3326implementation, rather than the structure that helps the user 3327understand. 3328 3329Instead, each manual should cover a coherent @emph{topic}. For example, 3330instead of a manual for @code{diff} and a manual for @code{diff3}, we 3331have one manual for ``comparison of files'' which covers both of those 3332programs, as well as @code{cmp}. By documenting these programs 3333together, we can make the whole subject clearer. 3334 3335The manual which discusses a program should certainly document all of 3336the program's command-line options and all of its commands. It should 3337give examples of their use. But don't organize the manual as a list 3338of features. Instead, organize it logically, by subtopics. Address 3339the questions that a user will ask when thinking about the job that 3340the program does. Don't just tell the reader what each feature can 3341do---say what jobs it is good for, and show how to use it for those 3342jobs. Explain what is recommended usage, and what kinds of usage 3343users should avoid. 3344 3345In general, a GNU manual should serve both as tutorial and reference. 3346It should be set up for convenient access to each topic through Info, 3347and for reading straight through (appendixes aside). A GNU manual 3348should give a good introduction to a beginner reading through from the 3349start, and should also provide all the details that hackers want. 3350The Bison manual is a good example of this---please take a look at it 3351to see what we mean. 3352 3353That is not as hard as it first sounds. Arrange each chapter as a 3354logical breakdown of its topic, but order the sections, and write their 3355text, so that reading the chapter straight through makes sense. Do 3356likewise when structuring the book into chapters, and when structuring a 3357section into paragraphs. The watchword is, @emph{at each point, address 3358the most fundamental and important issue raised by the preceding text.} 3359 3360If necessary, add extra chapters at the beginning of the manual which 3361are purely tutorial and cover the basics of the subject. These provide 3362the framework for a beginner to understand the rest of the manual. The 3363Bison manual provides a good example of how to do this. 3364 3365To serve as a reference, a manual should have an Index that lists all 3366the functions, variables, options, and important concepts that are 3367part of the program. One combined Index should do for a short manual, 3368but sometimes for a complex package it is better to use multiple 3369indices. The Texinfo manual includes advice on preparing good index 3370entries, see @ref{Index Entries, , Making Index Entries, texinfo, GNU 3371Texinfo}, and see @ref{Indexing Commands, , Defining the Entries of an 3372Index, texinfo, GNU Texinfo}. 3373 3374Don't use Unix man pages as a model for how to write GNU documentation; 3375most of them are terse, badly structured, and give inadequate 3376explanation of the underlying concepts. (There are, of course, some 3377exceptions.) Also, Unix man pages use a particular format which is 3378different from what we use in GNU manuals. 3379 3380Please include an email address in the manual for where to report 3381bugs @emph{in the text of the manual}. 3382 3383Please do not use the term ``pathname'' that is used in Unix 3384documentation; use ``file name'' (two words) instead. We use the term 3385``path'' only for search paths, which are lists of directory names. 3386 3387Please do not use the term ``illegal'' to refer to erroneous input to 3388a computer program. Please use ``invalid'' for this, and reserve the 3389term ``illegal'' for activities prohibited by law. 3390 3391Please do not write @samp{()} after a function name just to indicate 3392it is a function. @code{foo ()} is not a function, it is a function 3393call with no arguments. 3394 3395@node Doc Strings and Manuals 3396@section Doc Strings and Manuals 3397 3398Some programming systems, such as Emacs, provide a documentation string 3399for each function, command or variable. You may be tempted to write a 3400reference manual by compiling the documentation strings and writing a 3401little additional text to go around them---but you must not do it. That 3402approach is a fundamental mistake. The text of well-written 3403documentation strings will be entirely wrong for a manual. 3404 3405A documentation string needs to stand alone---when it appears on the 3406screen, there will be no other text to introduce or explain it. 3407Meanwhile, it can be rather informal in style. 3408 3409The text describing a function or variable in a manual must not stand 3410alone; it appears in the context of a section or subsection. Other text 3411at the beginning of the section should explain some of the concepts, and 3412should often make some general points that apply to several functions or 3413variables. The previous descriptions of functions and variables in the 3414section will also have given information about the topic. A description 3415written to stand alone would repeat some of that information; this 3416redundancy looks bad. Meanwhile, the informality that is acceptable in 3417a documentation string is totally unacceptable in a manual. 3418 3419The only good way to use documentation strings in writing a good manual 3420is to use them as a source of information for writing good text. 3421 3422@node Manual Structure Details 3423@section Manual Structure Details 3424@cindex manual structure 3425 3426The title page of the manual should state the version of the programs or 3427packages documented in the manual. The Top node of the manual should 3428also contain this information. If the manual is changing more 3429frequently than or independent of the program, also state a version 3430number for the manual in both of these places. 3431 3432Each program documented in the manual should have a node named 3433@samp{@var{program} Invocation} or @samp{Invoking @var{program}}. This 3434node (together with its subnodes, if any) should describe the program's 3435command line arguments and how to run it (the sort of information people 3436would look for in a man page). Start with an @samp{@@example} 3437containing a template for all the options and arguments that the program 3438uses. 3439 3440Alternatively, put a menu item in some menu whose item name fits one of 3441the above patterns. This identifies the node which that item points to 3442as the node for this purpose, regardless of the node's actual name. 3443 3444The @samp{--usage} feature of the Info reader looks for such a node 3445or menu item in order to find the relevant text, so it is essential 3446for every Texinfo file to have one. 3447 3448If one manual describes several programs, it should have such a node for 3449each program described in the manual. 3450 3451@node License for Manuals 3452@section License for Manuals 3453@cindex license for manuals 3454 3455Please use the GNU Free Documentation License for all GNU manuals that 3456are more than a few pages long. Likewise for a collection of short 3457documents---you only need one copy of the GNU FDL for the whole 3458collection. For a single short document, you can use a very permissive 3459non-copyleft license, to avoid taking up space with a long license. 3460 3461See @uref{http://www.gnu.org/copyleft/fdl-howto.html} for more explanation 3462of how to employ the GFDL. 3463 3464Note that it is not obligatory to include a copy of the GNU GPL or GNU 3465LGPL in a manual whose license is neither the GPL nor the LGPL. It can 3466be a good idea to include the program's license in a large manual; in a 3467short manual, whose size would be increased considerably by including 3468the program's license, it is probably better not to include it. 3469 3470@node Manual Credits 3471@section Manual Credits 3472@cindex credits for manuals 3473 3474Please credit the principal human writers of the manual as the authors, 3475on the title page of the manual. If a company sponsored the work, thank 3476the company in a suitable place in the manual, but do not cite the 3477company as an author. 3478 3479@node Printed Manuals 3480@section Printed Manuals 3481 3482The FSF publishes some GNU manuals in printed form. To encourage sales 3483of these manuals, the on-line versions of the manual should mention at 3484the very start that the printed manual is available and should point at 3485information for getting it---for instance, with a link to the page 3486@url{http://www.gnu.org/order/order.html}. This should not be included 3487in the printed manual, though, because there it is redundant. 3488 3489It is also useful to explain in the on-line forms of the manual how the 3490user can print out the manual from the sources. 3491 3492@node NEWS File 3493@section The NEWS File 3494@cindex @file{NEWS} file 3495 3496In addition to its manual, the package should have a file named 3497@file{NEWS} which contains a list of user-visible changes worth 3498mentioning. In each new release, add items to the front of the file and 3499identify the version they pertain to. Don't discard old items; leave 3500them in the file after the newer items. This way, a user upgrading from 3501any previous version can see what is new. 3502 3503If the @file{NEWS} file gets very long, move some of the older items 3504into a file named @file{ONEWS} and put a note at the end referring the 3505user to that file. 3506 3507@node Change Logs 3508@section Change Logs 3509@cindex change logs 3510 3511Keep a change log to describe all the changes made to program source 3512files. The purpose of this is so that people investigating bugs in the 3513future will know about the changes that might have introduced the bug. 3514Often a new bug can be found by looking at what was recently changed. 3515More importantly, change logs can help you eliminate conceptual 3516inconsistencies between different parts of a program, by giving you a 3517history of how the conflicting concepts arose and who they came from. 3518 3519@menu 3520* Change Log Concepts:: 3521* Style of Change Logs:: 3522* Simple Changes:: 3523* Conditional Changes:: 3524* Indicating the Part Changed:: 3525@end menu 3526 3527@node Change Log Concepts 3528@subsection Change Log Concepts 3529 3530@cindex change set 3531@cindex batch of changes 3532You can think of the change log as a conceptual ``undo list'' which 3533explains how earlier versions were different from the current version. 3534People can see the current version; they don't need the change log to 3535tell them what is in it. What they want from a change log is a clear 3536explanation of how the earlier version differed. Each @dfn{entry} in 3537a change log describes either an individual change or the smallest 3538batch of changes that belong together, also known as a @dfn{change 3539set}. 3540@cindex title, change log entry 3541@cindex description, change log entry 3542For later reference or for summarizing, sometimes it is useful to 3543start the entry with a one-line description (sometimes called a 3544@dfn{title}) to describe its overall purpose. 3545 3546In the past, we recommended not mentioning changes in non-software 3547files (manuals, help files, media files, etc.)@: in change logs. 3548However, we've been advised that it is a good idea to include them, 3549for the sake of copyright records. 3550 3551The change log file is normally called @file{ChangeLog} and covers an 3552entire directory. Each directory can have its own change log, or a 3553directory can use the change log of its parent directory---it's up to 3554you. 3555 3556Another alternative is to record change log information with a version 3557control system such as RCS or CVS. This can be converted automatically 3558to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command 3559@kbd{C-x v a} (@code{vc-update-change-log}) does the job. 3560 3561For changes to code, there's no need to describe the full purpose of 3562the changes or how they work together. If you think that a change 3563calls for explanation, you're probably right. Please do explain 3564it---but please put the full explanation in comments in the code, 3565where people will see it whenever they see the code. For example, 3566``New function'' is enough for the change log when you add a function, 3567because there should be a comment before the function definition to 3568explain what it does. 3569 3570For changes to files that do not support a comment syntax (e.g., media 3571files), it is ok to include the full explanation in the change log file, 3572after the title and before the list of individual changes. 3573 3574The easiest way to add an entry to @file{ChangeLog} is with the Emacs 3575command @kbd{M-x add-change-log-entry}. An individual change should 3576have an asterisk, the name of the changed file, and then in 3577parentheses the name of the changed functions, variables or whatever, 3578followed by a colon. Then describe the changes you made to that 3579function or variable. 3580 3581 3582@node Style of Change Logs 3583@subsection Style of Change Logs 3584@cindex change logs, style 3585 3586Here are some simple examples of change log entries, starting with the 3587header line that says who made the change and when it was installed, 3588followed by descriptions of specific changes. (These examples are 3589drawn from Emacs and GCC.) 3590 3591@example 35921998-08-17 Richard Stallman <rms@@gnu.org> 3593 3594* register.el (insert-register): Return nil. 3595(jump-to-register): Likewise. 3596 3597* sort.el (sort-subr): Return nil. 3598 3599* tex-mode.el (tex-bibtex-file, tex-file, tex-region): 3600Restart the tex shell if process is gone or stopped. 3601(tex-shell-running): New function. 3602 3603* expr.c (store_one_arg): Round size up for move_block_to_reg. 3604(expand_call): Round up when emitting USE insns. 3605* stmt.c (assign_parms): Round size up for move_block_from_reg. 3606@end example 3607 3608It's important to name the changed function or variable in full. Don't 3609abbreviate function or variable names, and don't combine them. 3610Subsequent maintainers will often search for a function name to find all 3611the change log entries that pertain to it; if you abbreviate the name, 3612they won't find it when they search. 3613 3614For example, some people are tempted to abbreviate groups of function 3615names by writing @samp{* register.el (@{insert,jump-to@}-register)}; 3616this is not a good idea, since searching for @code{jump-to-register} or 3617@code{insert-register} would not find that entry. 3618 3619Separate unrelated change log entries with blank lines. Don't put 3620blank lines between individual changes of an entry. You can omit the 3621file name and the asterisk when successive individual changes are in 3622the same file. 3623 3624Break long lists of function names by closing continued lines with 3625@samp{)}, rather than @samp{,}, and opening the continuation with 3626@samp{(} as in this example: 3627 3628@example 3629* keyboard.c (menu_bar_items, tool_bar_items) 3630(Fexecute_extended_command): Deal with 'keymap' property. 3631@end example 3632 3633When you install someone else's changes, put the contributor's name in 3634the change log entry rather than in the text of the entry. In other 3635words, write this: 3636 3637@example 36382002-07-14 John Doe <jdoe@@gnu.org> 3639 3640 * sewing.c: Make it sew. 3641@end example 3642 3643@noindent 3644rather than this: 3645 3646@example 36472002-07-14 Usual Maintainer <usual@@gnu.org> 3648 3649 * sewing.c: Make it sew. Patch by jdoe@@gnu.org. 3650@end example 3651 3652As for the date, that should be the date you applied the change. 3653 3654@node Simple Changes 3655@subsection Simple Changes 3656 3657Certain simple kinds of changes don't need much detail in the change 3658log. 3659 3660When you change the calling sequence of a function in a simple fashion, 3661and you change all the callers of the function to use the new calling 3662sequence, there is no need to make individual entries for all the 3663callers that you changed. Just write in the entry for the function 3664being called, ``All callers changed''---like this: 3665 3666@example 3667* keyboard.c (Fcommand_execute): New arg SPECIAL. 3668All callers changed. 3669@end example 3670 3671When you change just comments or doc strings, it is enough to write an 3672entry for the file, without mentioning the functions. Just ``Doc 3673fixes'' is enough for the change log. 3674 3675There's no technical need to make change log entries for documentation 3676files. This is because documentation is not susceptible to bugs that 3677are hard to fix. Documentation does not consist of parts that must 3678interact in a precisely engineered fashion. To correct an error, you 3679need not know the history of the erroneous passage; it is enough to 3680compare what the documentation says with the way the program actually 3681works. 3682 3683However, you should keep change logs for documentation files when the 3684project gets copyright assignments from its contributors, so as to 3685make the records of authorship more accurate. 3686 3687@node Conditional Changes 3688@subsection Conditional Changes 3689@cindex conditional changes, and change logs 3690@cindex change logs, conditional changes 3691 3692Source files can often contain code that is conditional to build-time 3693or static conditions. For example, C programs can contain 3694compile-time @code{#if} conditionals; programs implemented in 3695interpreted languages can contain module imports of function 3696definitions that are only performed for certain versions of the 3697interpreter; and Automake @file{Makefile.am} files can contain 3698variable definitions or target declarations that are only to be 3699considered if a configure-time Automake conditional is true. 3700 3701Many changes are conditional as well: sometimes you add a new variable, 3702or function, or even a new program or library, which is entirely 3703dependent on a build-time condition. It is useful to indicate 3704in the change log the conditions for which a change applies. 3705 3706Our convention for indicating conditional changes is to use 3707@emph{square brackets around the name of the condition}. 3708 3709Conditional changes can happen in numerous scenarios and with many 3710variations, so here are some examples to help clarify. This first 3711example describes changes in C, Perl, and Python files which are 3712conditional but do not have an associated function or entity name: 3713 3714@example 3715* xterm.c [SOLARIS2]: Include <string.h>. 3716* FilePath.pm [$^O eq 'VMS']: Import the VMS::Feature module. 3717* framework.py [sys.version_info < (2, 6)]: Make "with" statement 3718 available by importing it from __future__, 3719 to support also python 2.5. 3720@end example 3721 3722Our other examples will for simplicity be limited to C, as the minor 3723changes necessary to adapt them to other languages should be 3724self-evident. 3725 3726Next, here is an entry describing a new definition which is entirely 3727conditional: the C macro @code{FRAME_WINDOW_P} is defined (and used) 3728only when the macro @code{HAVE_X_WINDOWS} is defined: 3729 3730@example 3731* frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. 3732@end example 3733 3734Next, an entry for a change within the function @code{init_display}, 3735whose definition as a whole is unconditional, but the changes 3736themselves are contained in a @samp{#ifdef HAVE_LIBNCURSES} 3737conditional: 3738 3739@example 3740* dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. 3741@end example 3742 3743Finally, here is an entry for a change that takes effect only when 3744a certain macro is @emph{not} defined: 3745 3746@example 3747* host.c (gethostname) [!HAVE_SOCKETS]: Replace with winsock version. 3748@end example 3749 3750 3751@node Indicating the Part Changed 3752@subsection Indicating the Part Changed 3753 3754Indicate the part of a function which changed by using angle brackets 3755enclosing an indication of what the changed part does. Here is an entry 3756for a change in the part of the function @code{sh-while-getopts} that 3757deals with @code{sh} commands: 3758 3759@example 3760* progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that 3761user-specified option string is empty. 3762@end example 3763 3764 3765@node Man Pages 3766@section Man Pages 3767@cindex man pages 3768 3769In the GNU project, man pages are secondary. It is not necessary or 3770expected for every GNU program to have a man page, but some of them do. 3771It's your choice whether to include a man page in your program. 3772 3773When you make this decision, consider that supporting a man page 3774requires continual effort each time the program is changed. The time 3775you spend on the man page is time taken away from more useful work. 3776 3777For a simple program which changes little, updating the man page may be 3778a small job. Then there is little reason not to include a man page, if 3779you have one. 3780 3781For a large program that changes a great deal, updating a man page may 3782be a substantial burden. If a user offers to donate a man page, you may 3783find this gift costly to accept. It may be better to refuse the man 3784page unless the same person agrees to take full responsibility for 3785maintaining it---so that you can wash your hands of it entirely. If 3786this volunteer later ceases to do the job, then don't feel obliged to 3787pick it up yourself; it may be better to withdraw the man page from the 3788distribution until someone else agrees to update it. 3789 3790When a program changes only a little, you may feel that the 3791discrepancies are small enough that the man page remains useful without 3792updating. If so, put a prominent note near the beginning of the man 3793page explaining that you don't maintain it and that the Texinfo manual 3794is more authoritative. The note should say how to access the Texinfo 3795documentation. 3796 3797Be sure that man pages include a copyright statement and free license. 3798The simple all-permissive license is appropriate for simple man pages 3799(@pxref{License Notices for Other Files,,,maintain,Information for GNU 3800Maintainers}). 3801 3802For long man pages, with enough explanation and documentation that 3803they can be considered true manuals, use the GFDL (@pxref{License for 3804Manuals}). 3805 3806Finally, the GNU help2man program 3807(@uref{http://www.gnu.org/software/help2man/}) is one way to automate 3808generation of a man page, in this case from @option{--help} output. 3809This is sufficient in many cases. 3810 3811@node Reading other Manuals 3812@section Reading other Manuals 3813 3814There may be non-free books or documentation files that describe the 3815program you are documenting. 3816 3817It is ok to use these documents for reference, just as the author of a 3818new algebra textbook can read other books on algebra. A large portion 3819of any non-fiction book consists of facts, in this case facts about how 3820a certain program works, and these facts are necessarily the same for 3821everyone who writes about the subject. But be careful not to copy your 3822outline structure, wording, tables or examples from preexisting non-free 3823documentation. Copying from free documentation may be ok; please check 3824with the FSF about the individual case. 3825 3826@node Managing Releases 3827@chapter The Release Process 3828@cindex releasing 3829 3830Making a release is more than just bundling up your source files in a 3831tar file and putting it up for FTP. You should set up your software so 3832that it can be configured to run on a variety of systems. Your Makefile 3833should conform to the GNU standards described below, and your directory 3834layout should also conform to the standards discussed below. Doing so 3835makes it easy to include your package into the larger framework of 3836all GNU software. 3837 3838@menu 3839* Configuration:: How configuration of GNU packages should work. 3840* Makefile Conventions:: Makefile conventions. 3841* Releases:: Making releases 3842@end menu 3843 3844@node Configuration 3845@section How Configuration Should Work 3846@cindex program configuration 3847 3848@pindex configure 3849Each GNU distribution should come with a shell script named 3850@code{configure}. This script is given arguments which describe the 3851kind of machine and system you want to compile the program for. 3852The @code{configure} script must record the configuration options so 3853that they affect compilation. 3854 3855The description here is the specification of the interface for the 3856@code{configure} script in GNU packages. Many packages implement it 3857using GNU Autoconf (@pxref{Top,, Introduction, autoconf, Autoconf}) 3858and/or GNU Automake (@pxref{Top,, Introduction, automake, Automake}), 3859but you do not have to use these tools. You can implement it any way 3860you like; for instance, by making @code{configure} be a wrapper around 3861a completely different configuration system. 3862 3863Another way for the @code{configure} script to operate is to make a 3864link from a standard name such as @file{config.h} to the proper 3865configuration file for the chosen system. If you use this technique, 3866the distribution should @emph{not} contain a file named 3867@file{config.h}. This is so that people won't be able to build the 3868program without configuring it first. 3869 3870Another thing that @code{configure} can do is to edit the Makefile. If 3871you do this, the distribution should @emph{not} contain a file named 3872@file{Makefile}. Instead, it should include a file @file{Makefile.in} which 3873contains the input used for editing. Once again, this is so that people 3874won't be able to build the program without configuring it first. 3875 3876If @code{configure} does write the @file{Makefile}, then @file{Makefile} 3877should have a target named @file{Makefile} which causes @code{configure} 3878to be rerun, setting up the same configuration that was set up last 3879time. The files that @code{configure} reads should be listed as 3880dependencies of @file{Makefile}. 3881 3882All the files which are output from the @code{configure} script should 3883have comments at the beginning explaining that they were generated 3884automatically using @code{configure}. This is so that users won't think 3885of trying to edit them by hand. 3886 3887The @code{configure} script should write a file named @file{config.status} 3888which describes which configuration options were specified when the 3889program was last configured. This file should be a shell script which, 3890if run, will recreate the same configuration. 3891 3892The @code{configure} script should accept an option of the form 3893@samp{--srcdir=@var{dirname}} to specify the directory where sources are found 3894(if it is not the current directory). This makes it possible to build 3895the program in a separate directory, so that the actual source directory 3896is not modified. 3897 3898If the user does not specify @samp{--srcdir}, then @code{configure} should 3899check both @file{.} and @file{..} to see if it can find the sources. If 3900it finds the sources in one of these places, it should use them from 3901there. Otherwise, it should report that it cannot find the sources, and 3902should exit with nonzero status. 3903 3904Usually the easy way to support @samp{--srcdir} is by editing a 3905definition of @code{VPATH} into the Makefile. Some rules may need to 3906refer explicitly to the specified source directory. To make this 3907possible, @code{configure} can add to the Makefile a variable named 3908@code{srcdir} whose value is precisely the specified directory. 3909 3910In addition, the @samp{configure} script should take options 3911corresponding to most of the standard directory variables 3912(@pxref{Directory Variables}). Here is the list: 3913 3914@example 3915--prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir 3916--sharedstatedir --localstatedir --runstatedir 3917--libdir --includedir --oldincludedir 3918--datarootdir --datadir --infodir --localedir --mandir --docdir 3919--htmldir --dvidir --pdfdir --psdir 3920@end example 3921 3922The @code{configure} script should also take an argument which specifies the 3923type of system to build the program for. This argument should look like 3924this: 3925 3926@example 3927@var{cpu}-@var{company}-@var{system} 3928@end example 3929 3930For example, an Athlon-based GNU/Linux system might be 3931@samp{i686-pc-linux-gnu}. 3932 3933The @code{configure} script needs to be able to decode all plausible 3934alternatives for how to describe a machine. Thus, 3935@samp{athlon-pc-gnu/linux} would be a valid alias. There is a shell 3936script called 3937@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD, 3938@file{config.sub}} that you can use as a subroutine to validate system 3939types and canonicalize aliases. 3940 3941The @code{configure} script should also take the option 3942@option{--build=@var{buildtype}}, which should be equivalent to a 3943plain @var{buildtype} argument. For example, @samp{configure 3944--build=i686-pc-linux-gnu} is equivalent to @samp{configure 3945i686-pc-linux-gnu}. When the build type is not specified by an option 3946or argument, the @code{configure} script should normally guess it using 3947the shell script 3948@uref{http://git.savannah.gnu.org/@/gitweb/@/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD, 3949@file{config.guess}}. 3950 3951@cindex optional features, configure-time 3952Other options are permitted to specify in more detail the software 3953or hardware present on the machine, to include or exclude optional parts 3954of the package, or to adjust the name of some tools or arguments to them: 3955 3956@table @samp 3957@item --enable-@var{feature}@r{[}=@var{parameter}@r{]} 3958Configure the package to build and install an optional user-level 3959facility called @var{feature}. This allows users to choose which 3960optional features to include. Giving an optional @var{parameter} of 3961@samp{no} should omit @var{feature}, if it is built by default. 3962 3963No @samp{--enable} option should @strong{ever} cause one feature to 3964replace another. No @samp{--enable} option should ever substitute one 3965useful behavior for another useful behavior. The only proper use for 3966@samp{--enable} is for questions of whether to build part of the program 3967or exclude it. 3968 3969@item --with-@var{package} 3970@c @r{[}=@var{parameter}@r{]} 3971The package @var{package} will be installed, so configure this package 3972to work with @var{package}. 3973 3974@c Giving an optional @var{parameter} of 3975@c @samp{no} should omit @var{package}, if it is used by default. 3976 3977Possible values of @var{package} include 3978@samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, 3979@samp{gdb}, 3980@samp{x}, 3981and 3982@samp{x-toolkit}. 3983 3984Do not use a @samp{--with} option to specify the file name to use to 3985find certain files. That is outside the scope of what @samp{--with} 3986options are for. 3987 3988@item @var{variable}=@var{value} 3989Set the value of the variable @var{variable} to @var{value}. This is 3990used to override the default values of commands or arguments in the 3991build process. For example, the user could issue @samp{configure 3992CFLAGS=-g CXXFLAGS=-g} to build with debugging information and without 3993the default optimization. 3994 3995Specifying variables as arguments to @code{configure}, like this: 3996@example 3997./configure CC=gcc 3998@end example 3999is preferable to setting them in environment variables: 4000@example 4001CC=gcc ./configure 4002@end example 4003as it helps to recreate the same configuration later with 4004@file{config.status}. However, both methods should be supported. 4005@end table 4006 4007All @code{configure} scripts should accept all of the ``detail'' 4008options and the variable settings, whether or not they make any 4009difference to the particular package at hand. In particular, they 4010should accept any option that starts with @samp{--with-} or 4011@samp{--enable-}. This is so users will be able to configure an 4012entire GNU source tree at once with a single set of options. 4013 4014You will note that the categories @samp{--with-} and @samp{--enable-} 4015are narrow: they @strong{do not} provide a place for any sort of option 4016you might think of. That is deliberate. We want to limit the possible 4017configuration options in GNU software. We do not want GNU programs to 4018have idiosyncratic configuration options. 4019 4020Packages that perform part of the compilation process may support 4021cross-compilation. In such a case, the host and target machines for the 4022program may be different. 4023 4024The @code{configure} script should normally treat the specified type of 4025system as both the host and the target, thus producing a program which 4026works for the same type of machine that it runs on. 4027 4028To compile a program to run on a host type that differs from the build 4029type, use the configure option @option{--host=@var{hosttype}}, where 4030@var{hosttype} uses the same syntax as @var{buildtype}. The host type 4031normally defaults to the build type. 4032 4033To configure a cross-compiler, cross-assembler, or what have you, you 4034should specify a target different from the host, using the configure 4035option @samp{--target=@var{targettype}}. The syntax for 4036@var{targettype} is the same as for the host type. So the command would 4037look like this: 4038 4039@example 4040./configure --host=@var{hosttype} --target=@var{targettype} 4041@end example 4042 4043The target type normally defaults to the host type. 4044Programs for which cross-operation is not meaningful need not accept the 4045@samp{--target} option, because configuring an entire operating system for 4046cross-operation is not a meaningful operation. 4047 4048Some programs have ways of configuring themselves automatically. If 4049your program is set up to do this, your @code{configure} script can simply 4050ignore most of its arguments. 4051 4052@comment The makefile standards are in a separate file that is also 4053@comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93. 4054@comment For this document, turn chapters into sections, etc. 4055@lowersections 4056@include make-stds.texi 4057@raisesections 4058 4059@node Releases 4060@section Making Releases 4061@cindex packaging 4062 4063@cindex version numbers, for releases 4064You should identify each release with a pair of version numbers, a 4065major version and a minor. We have no objection to using more than 4066two numbers, but it is very unlikely that you really need them. 4067 4068Package the distribution of @code{Foo version 69.96} up in a gzipped tar 4069file with the name @file{foo-69.96.tar.gz}. It should unpack into a 4070subdirectory named @file{foo-69.96}. 4071 4072Building and installing the program should never modify any of the files 4073contained in the distribution. This means that all the files that form 4074part of the program in any way must be classified into @dfn{source 4075files} and @dfn{non-source files}. Source files are written by humans 4076and never changed automatically; non-source files are produced from 4077source files by programs under the control of the Makefile. 4078 4079@cindex @file{README} file 4080The distribution should contain a file named @file{README} with a 4081general overview of the package: 4082 4083@itemize 4084@item the name of the package; 4085 4086@item the version number of the package, or refer to where in the 4087package the version can be found; 4088 4089@item a general description of what the package does; 4090 4091@item a reference to the file @file{INSTALL}, which 4092should in turn contain an explanation of the installation procedure; 4093 4094@item a brief explanation of any unusual top-level directories or 4095files, or other hints for readers to find their way around the source; 4096 4097@item a reference to the file which contains the copying conditions. 4098The GNU GPL, if used, should be in a file called @file{COPYING}. If 4099the GNU LGPL is used, it should be in a file called 4100@file{COPYING.LESSER}. 4101@end itemize 4102 4103Naturally, all the source files must be in the distribution. It is 4104okay to include non-source files in the distribution along with the 4105source files they are generated from, provided they are up-to-date 4106with the source they are made from, and machine-independent, so that 4107normal building of the distribution will never modify them. We 4108commonly include non-source files produced by Autoconf, Automake, 4109Bison, @code{flex}, @TeX{}, and @code{makeinfo}; this helps avoid 4110unnecessary dependencies between our distributions, so that users can 4111install whichever versions of whichever packages they like. Do not 4112induce new dependencies on other software lightly. 4113 4114Non-source files that might actually be modified by building and 4115installing the program should @strong{never} be included in the 4116distribution. So if you do distribute non-source files, always make 4117sure they are up to date when you make a new distribution. 4118 4119Make sure that all the files in the distribution are world-readable, and 4120that directories are world-readable and world-searchable (octal mode 755). 4121We used to recommend that all directories in the distribution also be 4122world-writable (octal mode 777), because ancient versions of @code{tar} 4123would otherwise not cope when extracting the archive as an unprivileged 4124user. That can easily lead to security issues when creating the archive, 4125however, so now we recommend against that. 4126 4127Don't include any symbolic links in the distribution itself. If the tar 4128file contains symbolic links, then people cannot even unpack it on 4129systems that don't support symbolic links. Also, don't use multiple 4130names for one file in different directories, because certain file 4131systems cannot handle this and that prevents unpacking the 4132distribution. 4133 4134Try to make sure that all the file names will be unique on MS-DOS. A 4135name on MS-DOS consists of up to 8 characters, optionally followed by a 4136period and up to three characters. MS-DOS will truncate extra 4137characters both before and after the period. Thus, 4138@file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they 4139are truncated to @file{foobarha.c} and @file{foobarha.o}, which are 4140distinct. 4141 4142@cindex @file{texinfo.tex}, in a distribution 4143Include in your distribution a copy of the @file{texinfo.tex} you used 4144to test print any @file{*.texinfo} or @file{*.texi} files. 4145 4146Likewise, if your program uses small GNU software packages like regex, 4147getopt, obstack, or termcap, include them in the distribution file. 4148Leaving them out would make the distribution file a little smaller at 4149the expense of possible inconvenience to a user who doesn't know what 4150other files to get. 4151 4152@node References 4153@chapter References to Non-Free Software and Documentation 4154@cindex references to non-free material 4155 4156A GNU program should not recommend, promote, or grant legitimacy to 4157the use of any non-free program. Proprietary software is a social and 4158ethical problem, and our aim is to put an end to that problem. We 4159can't stop some people from writing proprietary programs, or stop 4160other people from using them, but we can and should refuse to 4161advertise them to new potential customers, or to give the public the 4162idea that their existence is ethical. 4163 4164The GNU definition of free software is found on the GNU web site at 4165@url{http://www.gnu.org/@/philosophy/@/free-sw.html}, and the definition 4166of free documentation is found at 4167@url{http://www.gnu.org/@/philosophy/@/free-doc.html}. The terms ``free'' 4168and ``non-free'', used in this document, refer to those definitions. 4169 4170A list of important licenses and whether they qualify as free is in 4171@url{http://www.gnu.org/@/licenses/@/license-list.html}. If it is not 4172clear whether a license qualifies as free, please ask the GNU Project 4173by writing to @email{licensing@@gnu.org}. We will answer, and if the 4174license is an important one, we will add it to the list. 4175 4176When a non-free program or system is well known, you can mention it in 4177passing---that is harmless, since users who might want to use it 4178probably already know about it. For instance, it is fine to explain 4179how to build your package on top of some widely used non-free 4180operating system, or how to use it together with some widely used 4181non-free program. 4182 4183However, you should give only the necessary information to help those 4184who already use the non-free program to use your program with 4185it---don't give, or refer to, any further information about the 4186proprietary program, and don't imply that the proprietary program 4187enhances your program, or that its existence is in any way a good 4188thing. The goal should be that people already using the proprietary 4189program will get the advice they need about how to use your free 4190program with it, while people who don't already use the proprietary 4191program will not see anything likely to lead them to take an interest 4192in it. 4193 4194If a non-free program or system is obscure in your program's domain, 4195your program should not mention or support it at all, since doing so 4196would tend to popularize the non-free program more than it popularizes 4197your program. (You cannot hope to find many additional users for your 4198program among the users of Foobar, if the existence of Foobar is not 4199generally known among people who might want to use your program.) 4200 4201Sometimes a program is free software in itself but depends on a 4202non-free platform in order to run. For instance, many Java programs 4203depend on some non-free Java libraries. To recommend or promote such 4204a program is to promote the other programs it needs. This is why we 4205are careful about listing Java programs in the Free Software 4206Directory: we don't want to promote the non-free Java libraries. 4207 4208We hope this particular problem with Java will be gone by and by, as 4209we replace the remaining non-free standard Java libraries with free 4210software, but the general principle will remain the same: don't 4211recommend, promote or legitimize programs that depend on non-free 4212software to run. 4213 4214Some free programs strongly encourage the use of non-free software. A 4215typical example is @command{mplayer}. It is free software in itself, 4216and the free code can handle some kinds of files. However, 4217@command{mplayer} recommends use of non-free codecs for other kinds of 4218files, and users that install @command{mplayer} are very likely to 4219install those codecs along with it. To recommend @command{mplayer} 4220is, in effect, to promote use of the non-free codecs. 4221 4222Thus, you should not recommend programs that strongly encourage the 4223use of non-free software. This is why we do not list 4224@command{mplayer} in the Free Software Directory. 4225 4226A GNU package should not refer the user to any non-free documentation 4227for free software. Free documentation that can be included in free 4228operating systems is essential for completing the GNU system, or any 4229free operating system, so encouraging it is a priority; to recommend 4230use of documentation that we are not allowed to include undermines the 4231impetus for the community to produce documentation that we can 4232include. So GNU packages should never recommend non-free 4233documentation. 4234 4235By contrast, it is ok to refer to journal articles and textbooks in 4236the comments of a program for explanation of how it functions, even 4237though they are non-free. This is because we don't include such 4238things in the GNU system even if they are free---they are outside the 4239scope of what a software distribution needs to include. 4240 4241Referring to a web site that describes or recommends a non-free 4242program is promoting that program, so please do not make links to (or 4243mention by name) web sites that contain such material. This policy is 4244relevant particularly for the web pages for a GNU package. 4245 4246Following links from nearly any web site can lead eventually to 4247non-free software; this is inherent in the nature of the web. So it 4248makes no sense to criticize a site for having such links. As long as 4249the site does not itself recommend a non-free program, there is no 4250need to consider the question of the sites that it links to for other 4251reasons. 4252 4253Thus, for example, you should not refer to AT&T's web site if that 4254recommends AT&T's non-free software packages; you should not refer to 4255a site that links to AT&T's site presenting it as a place to get some 4256non-free program, because that link recommends and legitimizes the 4257non-free program. However, that a site contains a link to AT&T's web 4258site for some other purpose (such as long-distance telephone service) 4259is not an objection against it. 4260 4261@node GNU Free Documentation License 4262@appendix GNU Free Documentation License 4263 4264@cindex FDL, GNU Free Documentation License 4265@include fdl.texi 4266 4267@node Index 4268@unnumbered Index 4269@printindex cp 4270 4271@bye 4272 4273Local variables: 4274eval: (add-hook 'write-file-hooks 'time-stamp) 4275time-stamp-start: "@set lastupdate " 4276time-stamp-end: "$" 4277time-stamp-format: "%:b %:d, %:y" 4278compile-command: "cd work.s && make" 4279End: 4280