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