1This is standards.info, produced by makeinfo version 4.8 from 2.././etc/standards.texi. 3 4INFO-DIR-SECTION GNU organization 5START-INFO-DIR-ENTRY 6* Standards: (standards). GNU coding standards. 7END-INFO-DIR-ENTRY 8 9 The GNU coding standards, last updated July 22, 2007. 10 11 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 122001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 13 14 Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.2 or 16any later version published by the Free Software Foundation; with no 17Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 18Texts. A copy of the license is included in the section entitled "GNU 19Free Documentation License". 20 21 22File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir) 23 24Version 25******* 26 27The GNU coding standards, last updated July 22, 2007. 28 29 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 302001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 31 32 Permission is granted to copy, distribute and/or modify this document 33under the terms of the GNU Free Documentation License, Version 1.2 or 34any later version published by the Free Software Foundation; with no 35Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 36Texts. A copy of the license is included in the section entitled "GNU 37Free Documentation License". 38 39* Menu: 40 41* Preface:: About the GNU Coding Standards. 42* Legal Issues:: Keeping free software free. 43* Design Advice:: General program design. 44* Program Behavior:: Program behavior for all programs 45* Writing C:: Making the best use of C. 46* Documentation:: Documenting programs. 47* Managing Releases:: The release process. 48* References:: Mentioning non-free software or documentation. 49* GNU Free Documentation License:: Copying and sharing this manual. 50* Index:: 51 52 53File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top 54 551 About the GNU Coding Standards 56******************************** 57 58The GNU Coding Standards were written by Richard Stallman and other GNU 59Project volunteers. Their purpose is to make the GNU system clean, 60consistent, and easy to install. This document can also be read as a 61guide to writing portable, robust and reliable programs. It focuses on 62programs written in C, but many of the rules and principles are useful 63even if you write in another programming language. The rules often 64state reasons for writing in a certain way. 65 66 This release of the GNU Coding Standards was last updated July 22, 672007. 68 69 If you did not obtain this file directly from the GNU project and 70recently, please check for a newer version. You can get the GNU Coding 71Standards from the GNU web server in many different formats, including 72the Texinfo source, PDF, HTML, DVI, plain text, and more, at: 73`http://www.gnu.org/prep/standards/'. 74 75 Corrections or suggestions for this document should be sent to 76<bug-standards@gnu.org>. If you make a suggestion, please include a 77suggested new wording for it; our time is limited. We prefer a context 78diff to the `standards.texi' or `make-stds.texi' files, but if you 79don't have those files, please mail your suggestion anyway. 80 81 These standards cover the minimum of what is important when writing a 82GNU package. Likely, the need for additional standards will come up. 83Sometimes, you might suggest that such standards be added to this 84document. If you think your standards would be generally useful, please 85do suggest them. 86 87 You should also set standards for your package on many questions not 88addressed or not firmly specified here. The most important point is to 89be self-consistent--try to stick to the conventions you pick, and try 90to document them as much as possible. That way, your program will be 91more maintainable by others. 92 93 The GNU Hello program serves as an example of how to follow the GNU 94coding standards for a trivial program. 95`http://www.gnu.org/software/hello/hello.html'. 96 97 98File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top 99 1002 Keeping Free Software Free 101**************************** 102 103This chapter discusses how you can make sure that GNU software avoids 104legal difficulties, and other related issues. 105 106* Menu: 107 108* Reading Non-Free Code:: Referring to proprietary programs. 109* Contributions:: Accepting contributions. 110* Trademarks:: How we deal with trademark issues. 111 112 113File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues 114 1152.1 Referring to Proprietary Programs 116===================================== 117 118Don't in any circumstances refer to Unix source code for or during your 119work on GNU! (Or to any other proprietary programs.) 120 121 If you have a vague recollection of the internals of a Unix program, 122this does not absolutely mean you can't write an imitation of it, but 123do try to organize the imitation internally along different lines, 124because this is likely to make the details of the Unix version 125irrelevant and dissimilar to your results. 126 127 For example, Unix utilities were generally optimized to minimize 128memory use; if you go for speed instead, your program will be very 129different. You could keep the entire input file in memory and scan it 130there instead of using stdio. Use a smarter algorithm discovered more 131recently than the Unix program. Eliminate use of temporary files. Do 132it in one pass instead of two (we did this in the assembler). 133 134 Or, on the contrary, emphasize simplicity instead of speed. For some 135applications, the speed of today's computers makes simpler algorithms 136adequate. 137 138 Or go for generality. For example, Unix programs often have static 139tables or fixed-size strings, which make for arbitrary limits; use 140dynamic allocation instead. Make sure your program handles NULs and 141other funny characters in the input files. Add a programming language 142for extensibility and write part of the program in that language. 143 144 Or turn some parts of the program into independently usable 145libraries. Or use a simple garbage collector instead of tracking 146precisely when to free memory, or use a new GNU facility such as 147obstacks. 148 149 150File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues 151 1522.2 Accepting Contributions 153=========================== 154 155If the program you are working on is copyrighted by the Free Software 156Foundation, then when someone else sends you a piece of code to add to 157the program, we need legal papers to use it--just as we asked you to 158sign papers initially. _Each_ person who makes a nontrivial 159contribution to a program must sign some sort of legal papers in order 160for us to have clear title to the program; the main author alone is not 161enough. 162 163 So, before adding in any contributions from other people, please tell 164us, so we can arrange to get the papers. Then wait until we tell you 165that we have received the signed papers, before you actually use the 166contribution. 167 168 This applies both before you release the program and afterward. If 169you receive diffs to fix a bug, and they make significant changes, we 170need legal papers for that change. 171 172 This also applies to comments and documentation files. For copyright 173law, comments and code are just text. Copyright applies to all kinds of 174text, so we need legal papers for all kinds. 175 176 We know it is frustrating to ask for legal papers; it's frustrating 177for us as well. But if you don't wait, you are going out on a limb--for 178example, what if the contributor's employer won't sign a disclaimer? 179You might have to take that code out again! 180 181 You don't need papers for changes of a few lines here or there, since 182they are not significant for copyright purposes. Also, you don't need 183papers if all you get from the suggestion is some ideas, not actual code 184which you use. For example, if someone sent you one implementation, but 185you write a different implementation of the same idea, you don't need to 186get papers. 187 188 The very worst thing is if you forget to tell us about the other 189contributor. We could be very embarrassed in court some day as a 190result. 191 192 We have more detailed advice for maintainers of programs; if you have 193reached the stage of actually maintaining a program for GNU (whether 194released or not), please ask us for a copy. It is also available 195online for your perusal: `http://www.gnu.org/prep/maintain/'. 196 197 198File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues 199 2002.3 Trademarks 201============== 202 203Please do not include any trademark acknowledgements in GNU software 204packages or documentation. 205 206 Trademark acknowledgements are the statements that such-and-such is a 207trademark of so-and-so. The GNU Project has no objection to the basic 208idea of trademarks, but these acknowledgements feel like kowtowing, and 209there is no legal requirement for them, so we don't use them. 210 211 What is legally required, as regards other people's trademarks, is to 212avoid using them in ways which a reader might reasonably understand as 213naming or labeling our own programs or activities. For example, since 214"Objective C" is (or at least was) a trademark, we made sure to say 215that we provide a "compiler for the Objective C language" rather than 216an "Objective C compiler". The latter would have been meant as a 217shorter way of saying the former, but it does not explicitly state the 218relationship, so it could be misinterpreted as using "Objective C" as a 219label for the compiler rather than for the language. 220 221 Please don't use "win" as an abbreviation for Microsoft Windows in 222GNU software or documentation. In hacker terminology, calling 223something a "win" is a form of praise. If you wish to praise Microsoft 224Windows when speaking on your own, by all means do so, but not in GNU 225software. Usually we write the name "Windows" in full, but when 226brevity is very important (as in file names and sometimes symbol 227names), we abbreviate it to "w". For instance, the files and functions 228in Emacs that deal with Windows start with `w32'. 229 230 231File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top 232 2333 General Program Design 234************************ 235 236This chapter discusses some of the issues you should take into account 237when designing your program. 238 239* Menu: 240 241* Source Language:: Which languages to use. 242* Compatibility:: Compatibility with other implementations. 243* Using Extensions:: Using non-standard features. 244* Standard C:: Using standard C features. 245* Conditional Compilation:: Compiling code only if a conditional is true. 246 247 248File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice 249 2503.1 Which Languages to Use 251========================== 252 253When you want to use a language that gets compiled and runs at high 254speed, the best language to use is C. Using another language is like 255using a non-standard feature: it will cause trouble for users. Even if 256GCC supports the other language, users may find it inconvenient to have 257to install the compiler for that other language in order to build your 258program. For example, if you write your program in C++, people will 259have to install the GNU C++ compiler in order to compile your program. 260 261 C has one other advantage over C++ and other compiled languages: more 262people know C, so more people will find it easy to read and modify the 263program if it is written in C. 264 265 So in general it is much better to use C, rather than the comparable 266alternatives. 267 268 But there are two exceptions to that conclusion: 269 270 * It is no problem to use another language to write a tool 271 specifically intended for use with that language. That is because 272 the only people who want to build the tool will be those who have 273 installed the other language anyway. 274 275 * If an application is of interest only to a narrow part of the 276 community, then the question of which language it is written in 277 has less effect on other people, so you may as well please 278 yourself. 279 280 Many programs are designed to be extensible: they include an 281interpreter for a language that is higher level than C. Often much of 282the program is written in that language, too. The Emacs editor 283pioneered this technique. 284 285 The standard extensibility interpreter for GNU software is GUILE 286(`http://www.gnu.org/software/guile/'), which implements the language 287Scheme (an especially clean and simple dialect of Lisp). We don't 288reject programs written in other "scripting languages" such as Perl and 289Python, but using GUILE is very important for the overall consistency 290of the GNU system. 291 292 293File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice 294 2953.2 Compatibility with Other Implementations 296============================================ 297 298With occasional exceptions, utility programs and libraries for GNU 299should be upward compatible with those in Berkeley Unix, and upward 300compatible with Standard C if Standard C specifies their behavior, and 301upward compatible with POSIX if POSIX specifies their behavior. 302 303 When these standards conflict, it is useful to offer compatibility 304modes for each of them. 305 306 Standard C and POSIX prohibit many kinds of extensions. Feel free 307to make the extensions anyway, and include a `--ansi', `--posix', or 308`--compatible' option to turn them off. However, if the extension has 309a significant chance of breaking any real programs or scripts, then it 310is not really upward compatible. So you should try to redesign its 311interface to make it upward compatible. 312 313 Many GNU programs suppress extensions that conflict with POSIX if the 314environment variable `POSIXLY_CORRECT' is defined (even if it is 315defined with a null value). Please make your program recognize this 316variable if appropriate. 317 318 When a feature is used only by users (not by programs or command 319files), and it is done poorly in Unix, feel free to replace it 320completely with something totally different and better. (For example, 321`vi' is replaced with Emacs.) But it is nice to offer a compatible 322feature as well. (There is a free `vi' clone, so we offer it.) 323 324 Additional useful features are welcome regardless of whether there 325is any precedent for them. 326 327 328File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice 329 3303.3 Using Non-standard Features 331=============================== 332 333Many GNU facilities that already exist support a number of convenient 334extensions over the comparable Unix facilities. Whether to use these 335extensions in implementing your program is a difficult question. 336 337 On the one hand, using the extensions can make a cleaner program. 338On the other hand, people will not be able to build the program unless 339the other GNU tools are available. This might cause the program to 340work on fewer kinds of machines. 341 342 With some extensions, it might be easy to provide both alternatives. 343For example, you can define functions with a "keyword" `INLINE' and 344define that as a macro to expand into either `inline' or nothing, 345depending on the compiler. 346 347 In general, perhaps it is best not to use the extensions if you can 348straightforwardly do without them, but to use the extensions if they 349are a big improvement. 350 351 An exception to this rule are the large, established programs (such 352as Emacs) which run on a great variety of systems. Using GNU 353extensions in such programs would make many users unhappy, so we don't 354do that. 355 356 Another exception is for programs that are used as part of 357compilation: anything that must be compiled with other compilers in 358order to bootstrap the GNU compilation facilities. If these require 359the GNU compiler, then no one can compile them without having them 360installed already. That would be extremely troublesome in certain 361cases. 362 363 364File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice 365 3663.4 Standard C and Pre-Standard C 367================================= 368 3691989 Standard C is widespread enough now that it is ok to use its 370features in new programs. There is one exception: do not ever use the 371"trigraph" feature of Standard C. 372 373 1999 Standard C is not widespread yet, so please do not require its 374features in programs. It is ok to use its features if they are present. 375 376 However, it is easy to support pre-standard compilers in most 377programs, so if you know how to do that, feel free. If a program you 378are maintaining has such support, you should try to keep it working. 379 380 To support pre-standard C, instead of writing function definitions in 381standard prototype form, 382 383 int 384 foo (int x, int y) 385 ... 386 387write the definition in pre-standard style like this, 388 389 int 390 foo (x, y) 391 int x, y; 392 ... 393 394and use a separate declaration to specify the argument prototype: 395 396 int foo (int, int); 397 398 You need such a declaration anyway, in a header file, to get the 399benefit of prototypes in all the files where the function is called. 400And once you have the declaration, you normally lose nothing by writing 401the function definition in the pre-standard style. 402 403 This technique does not work for integer types narrower than `int'. 404If you think of an argument as being of a type narrower than `int', 405declare it as `int' instead. 406 407 There are a few special cases where this technique is hard to use. 408For example, if a function argument needs to hold the system type 409`dev_t', you run into trouble, because `dev_t' is shorter than `int' on 410some machines; but you cannot use `int' instead, because `dev_t' is 411wider than `int' on some machines. There is no type you can safely use 412on all machines in a non-standard definition. The only way to support 413non-standard C and pass such an argument is to check the width of 414`dev_t' using Autoconf and choose the argument type accordingly. This 415may not be worth the trouble. 416 417 In order to support pre-standard compilers that do not recognize 418prototypes, you may want to use a preprocessor macro like this: 419 420 /* Declare the prototype for a general external function. */ 421 #if defined (__STDC__) || defined (WINDOWSNT) 422 #define P_(proto) proto 423 #else 424 #define P_(proto) () 425 #endif 426 427 428File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice 429 4303.5 Conditional Compilation 431=========================== 432 433When supporting configuration options already known when building your 434program we prefer using `if (... )' over conditional compilation, as in 435the former case the compiler is able to perform more extensive checking 436of all possible code paths. 437 438 For example, please write 439 440 if (HAS_FOO) 441 ... 442 else 443 ... 444 445instead of: 446 447 #ifdef HAS_FOO 448 ... 449 #else 450 ... 451 #endif 452 453 A modern compiler such as GCC will generate exactly the same code in 454both cases, and we have been using similar techniques with good success 455in several projects. Of course, the former method assumes that 456`HAS_FOO' is defined as either 0 or 1. 457 458 While this is not a silver bullet solving all portability problems, 459and is not always appropriate, following this policy would have saved 460GCC developers many hours, or even days, per year. 461 462 In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC 463which cannot be simply used in `if( ...)' statements, there is an easy 464workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as 465in the following example: 466 467 #ifdef REVERSIBLE_CC_MODE 468 #define HAS_REVERSIBLE_CC_MODE 1 469 #else 470 #define HAS_REVERSIBLE_CC_MODE 0 471 #endif 472 473 474File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top 475 4764 Program Behavior for All Programs 477*********************************** 478 479This chapter describes conventions for writing robust software. It 480also describes general standards for error messages, the command line 481interface, and how libraries should behave. 482 483* Menu: 484 485* Non-GNU Standards:: We consider standards such as POSIX; 486 we don't "obey" them. 487* Semantics:: Writing robust programs. 488* Libraries:: Library behavior. 489* Errors:: Formatting error messages. 490* User Interfaces:: Standards about interfaces generally. 491* Graphical Interfaces:: Standards for graphical interfaces. 492* Command-Line Interfaces:: Standards for command line interfaces. 493* Option Table:: Table of long options. 494* Memory Usage:: When and how to care about memory needs. 495* File Usage:: Which files to use, and where. 496 497 498File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior 499 5004.1 Non-GNU Standards 501===================== 502 503The GNU Project regards standards published by other organizations as 504suggestions, not orders. We consider those standards, but we do not 505"obey" them. In developing a GNU program, you should implement an 506outside standard's specifications when that makes the GNU system better 507overall in an objective sense. When it doesn't, you shouldn't. 508 509 In most cases, following published standards is convenient for 510users--it means that their programs or scripts will work more portably. 511For instance, GCC implements nearly all the features of Standard C as 512specified by that standard. C program developers would be unhappy if 513it did not. And GNU utilities mostly follow specifications of POSIX.2; 514shell script writers and users would be unhappy if our programs were 515incompatible. 516 517 But we do not follow either of these specifications rigidly, and 518there are specific points on which we decided not to follow them, so as 519to make the GNU system better for users. 520 521 For instance, Standard C says that nearly all extensions to C are 522prohibited. How silly! GCC implements many extensions, some of which 523were later adopted as part of the standard. If you want these 524constructs to give an error message as "required" by the standard, you 525must specify `--pedantic', which was implemented only so that we can 526say "GCC is a 100% implementation of the standard," not because there 527is any reason to actually use it. 528 529 POSIX.2 specifies that `df' and `du' must output sizes by default in 530units of 512 bytes. What users want is units of 1k, so that is what we 531do by default. If you want the ridiculous behavior "required" by 532POSIX, you must set the environment variable `POSIXLY_CORRECT' (which 533was originally going to be named `POSIX_ME_HARDER'). 534 535 GNU utilities also depart from the letter of the POSIX.2 536specification when they support long-named command-line options, and 537intermixing options with ordinary arguments. This minor 538incompatibility with POSIX is never a problem in practice, and it is 539very useful. 540 541 In particular, don't reject a new feature, or remove an old one, 542merely because a standard says it is "forbidden" or "deprecated." 543 544 545File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior 546 5474.2 Writing Robust Programs 548=========================== 549 550Avoid arbitrary limits on the length or number of _any_ data structure, 551including file names, lines, files, and symbols, by allocating all data 552structures dynamically. In most Unix utilities, "long lines are 553silently truncated". This is not acceptable in a GNU utility. 554 555 Utilities reading files should not drop NUL characters, or any other 556nonprinting characters _including those with codes above 0177_. The 557only sensible exceptions would be utilities specifically intended for 558interface to certain types of terminals or printers that can't handle 559those characters. Whenever possible, try to make programs work 560properly with sequences of bytes that represent multibyte characters, 561using encodings such as UTF-8 and others. 562 563 Check every system call for an error return, unless you know you 564wish to ignore errors. Include the system error text (from `perror' or 565equivalent) in _every_ error message resulting from a failing system 566call, as well as the name of the file if any and the name of the 567utility. Just "cannot open foo.c" or "stat failed" is not sufficient. 568 569 Check every call to `malloc' or `realloc' to see if it returned 570zero. Check `realloc' even if you are making the block smaller; in a 571system that rounds block sizes to a power of 2, `realloc' may get a 572different block if you ask for less space. 573 574 In Unix, `realloc' can destroy the storage block if it returns zero. 575GNU `realloc' does not have this bug: if it fails, the original block 576is unchanged. Feel free to assume the bug is fixed. If you wish to 577run your program on Unix, and wish to avoid lossage in this case, you 578can use the GNU `malloc'. 579 580 You must expect `free' to alter the contents of the block that was 581freed. Anything you want to fetch from the block, you must fetch before 582calling `free'. 583 584 If `malloc' fails in a noninteractive program, make that a fatal 585error. In an interactive program (one that reads commands from the 586user), it is better to abort the command and return to the command 587reader loop. This allows the user to kill other processes to free up 588virtual memory, and then try the command again. 589 590 Use `getopt_long' to decode arguments, unless the argument syntax 591makes this unreasonable. 592 593 When static storage is to be written in during program execution, use 594explicit C code to initialize it. Reserve C initialized declarations 595for data that will not be changed. 596 597 Try to avoid low-level interfaces to obscure Unix data structures 598(such as file directories, utmp, or the layout of kernel memory), since 599these are less likely to work compatibly. If you need to find all the 600files in a directory, use `readdir' or some other high-level interface. 601These are supported compatibly by GNU. 602 603 The preferred signal handling facilities are the BSD variant of 604`signal', and the POSIX `sigaction' function; the alternative USG 605`signal' interface is an inferior design. 606 607 Nowadays, using the POSIX signal functions may be the easiest way to 608make a program portable. If you use `signal', then on GNU/Linux 609systems running GNU libc version 1, you should include `bsd/signal.h' 610instead of `signal.h', so as to get BSD behavior. It is up to you 611whether to support systems where `signal' has only the USG behavior, or 612give up on them. 613 614 In error checks that detect "impossible" conditions, just abort. 615There is usually no point in printing any message. These checks 616indicate the existence of bugs. Whoever wants to fix the bugs will have 617to read the source code and run a debugger. So explain the problem with 618comments in the source. The relevant data will be in variables, which 619are easy to examine with the debugger, so there is no point moving them 620elsewhere. 621 622 Do not use a count of errors as the exit status for a program. 623_That does not work_, because exit status values are limited to 8 bits 624(0 through 255). A single run of the program might have 256 errors; if 625you try to return 256 as the exit status, the parent process will see 0 626as the status, and it will appear that the program succeeded. 627 628 If you make temporary files, check the `TMPDIR' environment 629variable; if that variable is defined, use the specified directory 630instead of `/tmp'. 631 632 In addition, be aware that there is a possible security problem when 633creating temporary files in world-writable directories. In C, you can 634avoid this problem by creating temporary files in this manner: 635 636 fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600); 637 638or by using the `mkstemps' function from libiberty. 639 640 In bash, use `set -C' to avoid this problem. 641 642 643File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior 644 6454.3 Library Behavior 646==================== 647 648Try to make library functions reentrant. If they need to do dynamic 649storage allocation, at least try to avoid any nonreentrancy aside from 650that of `malloc' itself. 651 652 Here are certain name conventions for libraries, to avoid name 653conflicts. 654 655 Choose a name prefix for the library, more than two characters long. 656All external function and variable names should start with this prefix. 657In addition, there should only be one of these in any given library 658member. This usually means putting each one in a separate source file. 659 660 An exception can be made when two external symbols are always used 661together, so that no reasonable program could use one without the 662other; then they can both go in the same file. 663 664 External symbols that are not documented entry points for the user 665should have names beginning with `_'. The `_' should be followed by 666the chosen name prefix for the library, to prevent collisions with 667other libraries. These can go in the same files with user entry points 668if you like. 669 670 Static functions and variables can be used as you like and need not 671fit any naming convention. 672 673 674File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior 675 6764.4 Formatting Error Messages 677============================= 678 679Error messages from compilers should look like this: 680 681 SOURCE-FILE-NAME:LINENO: MESSAGE 682 683If you want to mention the column number, use one of these formats: 684 685 SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE 686 SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE 687 688Line numbers should start from 1 at the beginning of the file, and 689column numbers should start from 1 at the beginning of the line. (Both 690of these conventions are chosen for compatibility.) Calculate column 691numbers assuming that space and all ASCII printing characters have 692equal width, and assuming tab stops every 8 columns. 693 694 The error message can also give both the starting and ending 695positions of the erroneous text. There are several formats so that you 696can avoid redundant information such as a duplicate line number. Here 697are the possible formats: 698 699 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE 700 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE 701 SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE 702 703When an error is spread over several files, you can use this format: 704 705 FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE 706 707 Error messages from other noninteractive programs should look like 708this: 709 710 PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE 711 712when there is an appropriate source file, or like this: 713 714 PROGRAM: MESSAGE 715 716when there is no relevant source file. 717 718 If you want to mention the column number, use this format: 719 720 PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE 721 722 In an interactive program (one that is reading commands from a 723terminal), it is better not to include the program name in an error 724message. The place to indicate which program is running is in the 725prompt or with the screen layout. (When the same program runs with 726input from a source other than a terminal, it is not interactive and 727would do best to print error messages using the noninteractive style.) 728 729 The string MESSAGE should not begin with a capital letter when it 730follows a program name and/or file name, because that isn't the 731beginning of a sentence. (The sentence conceptually starts at the 732beginning of the line.) Also, it should not end with a period. 733 734 Error messages from interactive programs, and other messages such as 735usage messages, should start with a capital letter. But they should not 736end with a period. 737 738 739File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior 740 7414.5 Standards for Interfaces Generally 742====================================== 743 744Please don't make the behavior of a utility depend on the name used to 745invoke it. It is useful sometimes to make a link to a utility with a 746different name, and that should not change what it does. 747 748 Instead, use a run time option or a compilation switch or both to 749select among the alternate behaviors. 750 751 Likewise, please don't make the behavior of the program depend on the 752type of output device it is used with. Device independence is an 753important principle of the system's design; do not compromise it merely 754to save someone from typing an option now and then. (Variation in error 755message syntax when using a terminal is ok, because that is a side issue 756that people do not depend on.) 757 758 If you think one behavior is most useful when the output is to a 759terminal, and another is most useful when the output is a file or a 760pipe, then it is usually best to make the default behavior the one that 761is useful with output to a terminal, and have an option for the other 762behavior. 763 764 Compatibility requires certain programs to depend on the type of 765output device. It would be disastrous if `ls' or `sh' did not do so in 766the way all users expect. In some of these cases, we supplement the 767program with a preferred alternate version that does not depend on the 768output device type. For example, we provide a `dir' program much like 769`ls' except that its default output format is always multi-column 770format. 771 772 773File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior 774 7754.6 Standards for Graphical Interfaces 776====================================== 777 778When you write a program that provides a graphical user interface, 779please make it work with X Windows and the GTK+ toolkit unless the 780functionality specifically requires some alternative (for example, 781"displaying jpeg images while in console mode"). 782 783 In addition, please provide a command-line interface to control the 784functionality. (In many cases, the graphical user interface can be a 785separate program which invokes the command-line program.) This is so 786that the same jobs can be done from scripts. 787 788 Please also consider providing a CORBA interface (for use from 789GNOME), a library interface (for use from C), and perhaps a 790keyboard-driven console interface (for use by users from console mode). 791Once you are doing the work to provide the functionality and the 792graphical interface, these won't be much extra work. 793 794 795File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior 796 7974.7 Standards for Command Line Interfaces 798========================================= 799 800It is a good idea to follow the POSIX guidelines for the command-line 801options of a program. The easiest way to do this is to use `getopt' to 802parse them. Note that the GNU version of `getopt' will normally permit 803options anywhere among the arguments unless the special argument `--' 804is used. This is not what POSIX specifies; it is a GNU extension. 805 806 Please define long-named options that are equivalent to the 807single-letter Unix-style options. We hope to make GNU more user 808friendly this way. This is easy to do with the GNU function 809`getopt_long'. 810 811 One of the advantages of long-named options is that they can be 812consistent from program to program. For example, users should be able 813to expect the "verbose" option of any GNU program which has one, to be 814spelled precisely `--verbose'. To achieve this uniformity, look at the 815table of common long-option names when you choose the option names for 816your program (*note Option Table::). 817 818 It is usually a good idea for file names given as ordinary arguments 819to be input files only; any output files would be specified using 820options (preferably `-o' or `--output'). Even if you allow an output 821file name as an ordinary argument for compatibility, try to provide an 822option as another way to specify it. This will lead to more consistency 823among GNU utilities, and fewer idiosyncrasies for users to remember. 824 825 All programs should support two standard options: `--version' and 826`--help'. CGI programs should accept these as command-line options, 827and also if given as the `PATH_INFO'; for instance, visiting 828`http://example.org/p.cgi/--help' in a browser should output the same 829information as invoking `p.cgi --help' from the command line. 830 831* Menu: 832 833* --version:: The standard output for --version. 834* --help:: The standard output for --help. 835 836 837File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces 838 8394.7.1 `--version' 840----------------- 841 842The standard `--version' option should direct the program to print 843information about its name, version, origin and legal status, all on 844standard output, and then exit successfully. Other options and 845arguments should be ignored once this is seen, and the program should 846not perform its normal function. 847 848 The first line is meant to be easy for a program to parse; the 849version number proper starts after the last space. In addition, it 850contains the canonical name for this program, in this format: 851 852 GNU Emacs 19.30 853 854The program's name should be a constant string; _don't_ compute it from 855`argv[0]'. The idea is to state the standard or canonical name for the 856program, not its file name. There are other ways to find out the 857precise file name where a command is found in `PATH'. 858 859 If the program is a subsidiary part of a larger package, mention the 860package name in parentheses, like this: 861 862 emacsserver (GNU Emacs) 19.30 863 864If the package has a version number which is different from this 865program's version number, you can mention the package version number 866just before the close-parenthesis. 867 868 If you _need_ to mention the version numbers of libraries which are 869distributed separately from the package which contains this program, 870you can do so by printing an additional line of version info for each 871library you want to mention. Use the same format for these lines as for 872the first line. 873 874 Please do not mention all of the libraries that the program uses 875"just for completeness"--that would produce a lot of unhelpful clutter. 876Please mention library version numbers only if you find in practice that 877they are very important to you in debugging. 878 879 The following line, after the version number line or lines, should 880be a copyright notice. If more than one copyright notice is called 881for, put each on a separate line. 882 883 Next should follow a line stating the license, preferably using one 884of abbrevations below, and a brief statement that the program is free 885software, and that users are free to copy and change it. Also mention 886that there is no warranty, to the extent permitted by law. See 887recommended wording below. 888 889 It is ok to finish the output with a list of the major authors of the 890program, as a way of giving credit. 891 892 Here's an example of output that follows these rules: 893 894 GNU hello 2.3 895 Copyright (C) 2007 Free Software Foundation, Inc. 896 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> 897 This is free software: you are free to change and redistribute it. 898 There is NO WARRANTY, to the extent permitted by law. 899 900 You should adapt this to your program, of course, filling in the 901proper year, copyright holder, name of program, and the references to 902distribution terms, and changing the rest of the wording as necessary. 903 904 This copyright notice only needs to mention the most recent year in 905which changes were made--there's no need to list the years for previous 906versions' changes. You don't have to mention the name of the program in 907these notices, if that is inconvenient, since it appeared in the first 908line. (The rules are different for copyright notices in source files; 909*note Copyright Notices: (maintain)Copyright Notices.) 910 911 Translations of the above lines must preserve the validity of the 912copyright notices (*note Internationalization::). If the translation's 913character set supports it, the `(C)' should be replaced with the 914copyright symbol, as follows: 915 916 (the official copyright symbol, which is the letter C in a circle); 917 918 Write the word "Copyright" exactly like that, in English. Do not 919translate it into another language. International treaties recognize 920the English word "Copyright"; translations into other languages do not 921have legal significance. 922 923 Finally, here is the table of our suggested license abbreviations. 924Any abbreviation can be followed by `vVERSION[+]', meaning that 925particular version, or later versions with the `+', as shown above. 926 927 In the case of exceptions for extra permissions with the GPL, we use 928`/' for a separator; the version number can follow the license 929abbreviation as usual, as in the examples below. 930 931GPL 932 GNU General Public License, `http://www.gnu.org/licenses/gpl.html'. 933 934LGPL 935 GNU Lesser General Public License, 936 `http://www.gnu.org/licenses/lgpl.html'. 937 938GPL/Guile 939 GNU GPL with the exception for Guile; for example, GPLv3+/Guile 940 means the GNU GPL version 3 or later, with the extra exception for 941 Guile. 942 943 GNU GPL with the exception for Ada. 944 945Apache 946 The Apache Software Foundation license, 947 `http://www.apache.org/licenses'. 948 949Artistic 950 The Artistic license used for Perl, 951 `http://www.perlfoundation.org/legal'. 952 953Expat 954 The Expat license, `http://www.jclark.com/xml/copying.txt'. 955 956MPL 957 The Mozilla Public License, `http://www.mozilla.org/MPL/'. 958 959OBSD 960 The original (4-clause) BSD license, incompatible with the GNU GPL 961 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'. 962 963PHP 964 The license used for PHP, `http://www.php.net/license/'. 965 966public domain 967 The non-license that is being in the public domain, 968 `http://www.gnu.org/licenses/license-list.html#PublicDomain'. 969 970Python 971 The license for Python, `http://www.python.org/2.0.1/license.html'. 972 973RBSD 974 The revised (3-clause) BSD, compatible with the GNU GPL, 975 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'. 976 977X11 978 The simple non-copyleft license used for most versions of the X 979 Window system, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'. 980 981Zlib 982 The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'. 983 984 985 More information about these licenses and many more are on the GNU 986licensing web pages, `http://www.gnu.org/licenses/license-list.html'. 987 988 989File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces 990 9914.7.2 `--help' 992-------------- 993 994The standard `--help' option should output brief documentation for how 995to invoke the program, on standard output, then exit successfully. 996Other options and arguments should be ignored once this is seen, and 997the program should not perform its normal function. 998 999 Near the end of the `--help' option's output there should be a line 1000that says where to mail bug reports. It should have this format: 1001 1002 Report bugs to MAILING-ADDRESS. 1003 1004 1005File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior 1006 10074.8 Table of Long Options 1008========================= 1009 1010Here is a table of long options used by GNU programs. It is surely 1011incomplete, but we aim to list all the options that a new program might 1012want to be compatible with. If you use names not already in the table, 1013please send <bug-standards@gnu.org> a list of them, with their 1014meanings, so we can update the table. 1015 1016`after-date' 1017 `-N' in `tar'. 1018 1019`all' 1020 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'. 1021 1022`all-text' 1023 `-a' in `diff'. 1024 1025`almost-all' 1026 `-A' in `ls'. 1027 1028`append' 1029 `-a' in `etags', `tee', `time'; `-r' in `tar'. 1030 1031`archive' 1032 `-a' in `cp'. 1033 1034`archive-name' 1035 `-n' in `shar'. 1036 1037`arglength' 1038 `-l' in `m4'. 1039 1040`ascii' 1041 `-a' in `diff'. 1042 1043`assign' 1044 `-v' in `gawk'. 1045 1046`assume-new' 1047 `-W' in Make. 1048 1049`assume-old' 1050 `-o' in Make. 1051 1052`auto-check' 1053 `-a' in `recode'. 1054 1055`auto-pager' 1056 `-a' in `wdiff'. 1057 1058`auto-reference' 1059 `-A' in `ptx'. 1060 1061`avoid-wraps' 1062 `-n' in `wdiff'. 1063 1064`background' 1065 For server programs, run in the background. 1066 1067`backward-search' 1068 `-B' in `ctags'. 1069 1070`basename' 1071 `-f' in `shar'. 1072 1073`batch' 1074 Used in GDB. 1075 1076`baud' 1077 Used in GDB. 1078 1079`before' 1080 `-b' in `tac'. 1081 1082`binary' 1083 `-b' in `cpio' and `diff'. 1084 1085`bits-per-code' 1086 `-b' in `shar'. 1087 1088`block-size' 1089 Used in `cpio' and `tar'. 1090 1091`blocks' 1092 `-b' in `head' and `tail'. 1093 1094`break-file' 1095 `-b' in `ptx'. 1096 1097`brief' 1098 Used in various programs to make output shorter. 1099 1100`bytes' 1101 `-c' in `head', `split', and `tail'. 1102 1103`c++' 1104 `-C' in `etags'. 1105 1106`catenate' 1107 `-A' in `tar'. 1108 1109`cd' 1110 Used in various programs to specify the directory to use. 1111 1112`changes' 1113 `-c' in `chgrp' and `chown'. 1114 1115`classify' 1116 `-F' in `ls'. 1117 1118`colons' 1119 `-c' in `recode'. 1120 1121`command' 1122 `-c' in `su'; `-x' in GDB. 1123 1124`compare' 1125 `-d' in `tar'. 1126 1127`compat' 1128 Used in `gawk'. 1129 1130`compress' 1131 `-Z' in `tar' and `shar'. 1132 1133`concatenate' 1134 `-A' in `tar'. 1135 1136`confirmation' 1137 `-w' in `tar'. 1138 1139`context' 1140 Used in `diff'. 1141 1142`copyleft' 1143 `-W copyleft' in `gawk'. 1144 1145`copyright' 1146 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'. 1147 1148`core' 1149 Used in GDB. 1150 1151`count' 1152 `-q' in `who'. 1153 1154`count-links' 1155 `-l' in `du'. 1156 1157`create' 1158 Used in `tar' and `cpio'. 1159 1160`cut-mark' 1161 `-c' in `shar'. 1162 1163`cxref' 1164 `-x' in `ctags'. 1165 1166`date' 1167 `-d' in `touch'. 1168 1169`debug' 1170 `-d' in Make and `m4'; `-t' in Bison. 1171 1172`define' 1173 `-D' in `m4'. 1174 1175`defines' 1176 `-d' in Bison and `ctags'. 1177 1178`delete' 1179 `-D' in `tar'. 1180 1181`dereference' 1182 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'. 1183 1184`dereference-args' 1185 `-D' in `du'. 1186 1187`device' 1188 Specify an I/O device (special file name). 1189 1190`diacritics' 1191 `-d' in `recode'. 1192 1193`dictionary-order' 1194 `-d' in `look'. 1195 1196`diff' 1197 `-d' in `tar'. 1198 1199`digits' 1200 `-n' in `csplit'. 1201 1202`directory' 1203 Specify the directory to use, in various programs. In `ls', it 1204 means to show directories themselves rather than their contents. 1205 In `rm' and `ln', it means to not treat links to directories 1206 specially. 1207 1208`discard-all' 1209 `-x' in `strip'. 1210 1211`discard-locals' 1212 `-X' in `strip'. 1213 1214`dry-run' 1215 `-n' in Make. 1216 1217`ed' 1218 `-e' in `diff'. 1219 1220`elide-empty-files' 1221 `-z' in `csplit'. 1222 1223`end-delete' 1224 `-x' in `wdiff'. 1225 1226`end-insert' 1227 `-z' in `wdiff'. 1228 1229`entire-new-file' 1230 `-N' in `diff'. 1231 1232`environment-overrides' 1233 `-e' in Make. 1234 1235`eof' 1236 `-e' in `xargs'. 1237 1238`epoch' 1239 Used in GDB. 1240 1241`error-limit' 1242 Used in `makeinfo'. 1243 1244`error-output' 1245 `-o' in `m4'. 1246 1247`escape' 1248 `-b' in `ls'. 1249 1250`exclude-from' 1251 `-X' in `tar'. 1252 1253`exec' 1254 Used in GDB. 1255 1256`exit' 1257 `-x' in `xargs'. 1258 1259`exit-0' 1260 `-e' in `unshar'. 1261 1262`expand-tabs' 1263 `-t' in `diff'. 1264 1265`expression' 1266 `-e' in `sed'. 1267 1268`extern-only' 1269 `-g' in `nm'. 1270 1271`extract' 1272 `-i' in `cpio'; `-x' in `tar'. 1273 1274`faces' 1275 `-f' in `finger'. 1276 1277`fast' 1278 `-f' in `su'. 1279 1280`fatal-warnings' 1281 `-E' in `m4'. 1282 1283`file' 1284 `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r' 1285 in `touch'. 1286 1287`field-separator' 1288 `-F' in `gawk'. 1289 1290`file-prefix' 1291 `-b' in Bison. 1292 1293`file-type' 1294 `-F' in `ls'. 1295 1296`files-from' 1297 `-T' in `tar'. 1298 1299`fill-column' 1300 Used in `makeinfo'. 1301 1302`flag-truncation' 1303 `-F' in `ptx'. 1304 1305`fixed-output-files' 1306 `-y' in Bison. 1307 1308`follow' 1309 `-f' in `tail'. 1310 1311`footnote-style' 1312 Used in `makeinfo'. 1313 1314`force' 1315 `-f' in `cp', `ln', `mv', and `rm'. 1316 1317`force-prefix' 1318 `-F' in `shar'. 1319 1320`foreground' 1321 For server programs, run in the foreground; in other words, don't 1322 do anything special to run the server in the background. 1323 1324`format' 1325 Used in `ls', `time', and `ptx'. 1326 1327`freeze-state' 1328 `-F' in `m4'. 1329 1330`fullname' 1331 Used in GDB. 1332 1333`gap-size' 1334 `-g' in `ptx'. 1335 1336`get' 1337 `-x' in `tar'. 1338 1339`graphic' 1340 `-i' in `ul'. 1341 1342`graphics' 1343 `-g' in `recode'. 1344 1345`group' 1346 `-g' in `install'. 1347 1348`gzip' 1349 `-z' in `tar' and `shar'. 1350 1351`hashsize' 1352 `-H' in `m4'. 1353 1354`header' 1355 `-h' in `objdump' and `recode' 1356 1357`heading' 1358 `-H' in `who'. 1359 1360`help' 1361 Used to ask for brief usage information. 1362 1363`here-delimiter' 1364 `-d' in `shar'. 1365 1366`hide-control-chars' 1367 `-q' in `ls'. 1368 1369`html' 1370 In `makeinfo', output HTML. 1371 1372`idle' 1373 `-u' in `who'. 1374 1375`ifdef' 1376 `-D' in `diff'. 1377 1378`ignore' 1379 `-I' in `ls'; `-x' in `recode'. 1380 1381`ignore-all-space' 1382 `-w' in `diff'. 1383 1384`ignore-backups' 1385 `-B' in `ls'. 1386 1387`ignore-blank-lines' 1388 `-B' in `diff'. 1389 1390`ignore-case' 1391 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'. 1392 1393`ignore-errors' 1394 `-i' in Make. 1395 1396`ignore-file' 1397 `-i' in `ptx'. 1398 1399`ignore-indentation' 1400 `-I' in `etags'. 1401 1402`ignore-init-file' 1403 `-f' in Oleo. 1404 1405`ignore-interrupts' 1406 `-i' in `tee'. 1407 1408`ignore-matching-lines' 1409 `-I' in `diff'. 1410 1411`ignore-space-change' 1412 `-b' in `diff'. 1413 1414`ignore-zeros' 1415 `-i' in `tar'. 1416 1417`include' 1418 `-i' in `etags'; `-I' in `m4'. 1419 1420`include-dir' 1421 `-I' in Make. 1422 1423`incremental' 1424 `-G' in `tar'. 1425 1426`info' 1427 `-i', `-l', and `-m' in Finger. 1428 1429`init-file' 1430 In some programs, specify the name of the file to read as the 1431 user's init file. 1432 1433`initial' 1434 `-i' in `expand'. 1435 1436`initial-tab' 1437 `-T' in `diff'. 1438 1439`inode' 1440 `-i' in `ls'. 1441 1442`interactive' 1443 `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs'; 1444 `-w' in `tar'. 1445 1446`intermix-type' 1447 `-p' in `shar'. 1448 1449`iso-8601' 1450 Used in `date' 1451 1452`jobs' 1453 `-j' in Make. 1454 1455`just-print' 1456 `-n' in Make. 1457 1458`keep-going' 1459 `-k' in Make. 1460 1461`keep-files' 1462 `-k' in `csplit'. 1463 1464`kilobytes' 1465 `-k' in `du' and `ls'. 1466 1467`language' 1468 `-l' in `etags'. 1469 1470`less-mode' 1471 `-l' in `wdiff'. 1472 1473`level-for-gzip' 1474 `-g' in `shar'. 1475 1476`line-bytes' 1477 `-C' in `split'. 1478 1479`lines' 1480 Used in `split', `head', and `tail'. 1481 1482`link' 1483 `-l' in `cpio'. 1484 1485`lint' 1486`lint-old' 1487 Used in `gawk'. 1488 1489`list' 1490 `-t' in `cpio'; `-l' in `recode'. 1491 1492`list' 1493 `-t' in `tar'. 1494 1495`literal' 1496 `-N' in `ls'. 1497 1498`load-average' 1499 `-l' in Make. 1500 1501`login' 1502 Used in `su'. 1503 1504`machine' 1505 Used in `uname'. 1506 1507`macro-name' 1508 `-M' in `ptx'. 1509 1510`mail' 1511 `-m' in `hello' and `uname'. 1512 1513`make-directories' 1514 `-d' in `cpio'. 1515 1516`makefile' 1517 `-f' in Make. 1518 1519`mapped' 1520 Used in GDB. 1521 1522`max-args' 1523 `-n' in `xargs'. 1524 1525`max-chars' 1526 `-n' in `xargs'. 1527 1528`max-lines' 1529 `-l' in `xargs'. 1530 1531`max-load' 1532 `-l' in Make. 1533 1534`max-procs' 1535 `-P' in `xargs'. 1536 1537`mesg' 1538 `-T' in `who'. 1539 1540`message' 1541 `-T' in `who'. 1542 1543`minimal' 1544 `-d' in `diff'. 1545 1546`mixed-uuencode' 1547 `-M' in `shar'. 1548 1549`mode' 1550 `-m' in `install', `mkdir', and `mkfifo'. 1551 1552`modification-time' 1553 `-m' in `tar'. 1554 1555`multi-volume' 1556 `-M' in `tar'. 1557 1558`name-prefix' 1559 `-a' in Bison. 1560 1561`nesting-limit' 1562 `-L' in `m4'. 1563 1564`net-headers' 1565 `-a' in `shar'. 1566 1567`new-file' 1568 `-W' in Make. 1569 1570`no-builtin-rules' 1571 `-r' in Make. 1572 1573`no-character-count' 1574 `-w' in `shar'. 1575 1576`no-check-existing' 1577 `-x' in `shar'. 1578 1579`no-common' 1580 `-3' in `wdiff'. 1581 1582`no-create' 1583 `-c' in `touch'. 1584 1585`no-defines' 1586 `-D' in `etags'. 1587 1588`no-deleted' 1589 `-1' in `wdiff'. 1590 1591`no-dereference' 1592 `-d' in `cp'. 1593 1594`no-inserted' 1595 `-2' in `wdiff'. 1596 1597`no-keep-going' 1598 `-S' in Make. 1599 1600`no-lines' 1601 `-l' in Bison. 1602 1603`no-piping' 1604 `-P' in `shar'. 1605 1606`no-prof' 1607 `-e' in `gprof'. 1608 1609`no-regex' 1610 `-R' in `etags'. 1611 1612`no-sort' 1613 `-p' in `nm'. 1614 1615`no-splash' 1616 Don't print a startup splash screen. 1617 1618`no-split' 1619 Used in `makeinfo'. 1620 1621`no-static' 1622 `-a' in `gprof'. 1623 1624`no-time' 1625 `-E' in `gprof'. 1626 1627`no-timestamp' 1628 `-m' in `shar'. 1629 1630`no-validate' 1631 Used in `makeinfo'. 1632 1633`no-wait' 1634 Used in `emacsclient'. 1635 1636`no-warn' 1637 Used in various programs to inhibit warnings. 1638 1639`node' 1640 `-n' in `info'. 1641 1642`nodename' 1643 `-n' in `uname'. 1644 1645`nonmatching' 1646 `-f' in `cpio'. 1647 1648`nstuff' 1649 `-n' in `objdump'. 1650 1651`null' 1652 `-0' in `xargs'. 1653 1654`number' 1655 `-n' in `cat'. 1656 1657`number-nonblank' 1658 `-b' in `cat'. 1659 1660`numeric-sort' 1661 `-n' in `nm'. 1662 1663`numeric-uid-gid' 1664 `-n' in `cpio' and `ls'. 1665 1666`nx' 1667 Used in GDB. 1668 1669`old-archive' 1670 `-o' in `tar'. 1671 1672`old-file' 1673 `-o' in Make. 1674 1675`one-file-system' 1676 `-l' in `tar', `cp', and `du'. 1677 1678`only-file' 1679 `-o' in `ptx'. 1680 1681`only-prof' 1682 `-f' in `gprof'. 1683 1684`only-time' 1685 `-F' in `gprof'. 1686 1687`options' 1688 `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'. 1689 1690`output' 1691 In various programs, specify the output file name. 1692 1693`output-prefix' 1694 `-o' in `shar'. 1695 1696`override' 1697 `-o' in `rm'. 1698 1699`overwrite' 1700 `-c' in `unshar'. 1701 1702`owner' 1703 `-o' in `install'. 1704 1705`paginate' 1706 `-l' in `diff'. 1707 1708`paragraph-indent' 1709 Used in `makeinfo'. 1710 1711`parents' 1712 `-p' in `mkdir' and `rmdir'. 1713 1714`pass-all' 1715 `-p' in `ul'. 1716 1717`pass-through' 1718 `-p' in `cpio'. 1719 1720`port' 1721 `-P' in `finger'. 1722 1723`portability' 1724 `-c' in `cpio' and `tar'. 1725 1726`posix' 1727 Used in `gawk'. 1728 1729`prefix-builtins' 1730 `-P' in `m4'. 1731 1732`prefix' 1733 `-f' in `csplit'. 1734 1735`preserve' 1736 Used in `tar' and `cp'. 1737 1738`preserve-environment' 1739 `-p' in `su'. 1740 1741`preserve-modification-time' 1742 `-m' in `cpio'. 1743 1744`preserve-order' 1745 `-s' in `tar'. 1746 1747`preserve-permissions' 1748 `-p' in `tar'. 1749 1750`print' 1751 `-l' in `diff'. 1752 1753`print-chars' 1754 `-L' in `cmp'. 1755 1756`print-data-base' 1757 `-p' in Make. 1758 1759`print-directory' 1760 `-w' in Make. 1761 1762`print-file-name' 1763 `-o' in `nm'. 1764 1765`print-symdefs' 1766 `-s' in `nm'. 1767 1768`printer' 1769 `-p' in `wdiff'. 1770 1771`prompt' 1772 `-p' in `ed'. 1773 1774`proxy' 1775 Specify an HTTP proxy. 1776 1777`query-user' 1778 `-X' in `shar'. 1779 1780`question' 1781 `-q' in Make. 1782 1783`quiet' 1784 Used in many programs to inhibit the usual output. Every program 1785 accepting `--quiet' should accept `--silent' as a synonym. 1786 1787`quiet-unshar' 1788 `-Q' in `shar' 1789 1790`quote-name' 1791 `-Q' in `ls'. 1792 1793`rcs' 1794 `-n' in `diff'. 1795 1796`re-interval' 1797 Used in `gawk'. 1798 1799`read-full-blocks' 1800 `-B' in `tar'. 1801 1802`readnow' 1803 Used in GDB. 1804 1805`recon' 1806 `-n' in Make. 1807 1808`record-number' 1809 `-R' in `tar'. 1810 1811`recursive' 1812 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'. 1813 1814`reference-limit' 1815 Used in `makeinfo'. 1816 1817`references' 1818 `-r' in `ptx'. 1819 1820`regex' 1821 `-r' in `tac' and `etags'. 1822 1823`release' 1824 `-r' in `uname'. 1825 1826`reload-state' 1827 `-R' in `m4'. 1828 1829`relocation' 1830 `-r' in `objdump'. 1831 1832`rename' 1833 `-r' in `cpio'. 1834 1835`replace' 1836 `-i' in `xargs'. 1837 1838`report-identical-files' 1839 `-s' in `diff'. 1840 1841`reset-access-time' 1842 `-a' in `cpio'. 1843 1844`reverse' 1845 `-r' in `ls' and `nm'. 1846 1847`reversed-ed' 1848 `-f' in `diff'. 1849 1850`right-side-defs' 1851 `-R' in `ptx'. 1852 1853`same-order' 1854 `-s' in `tar'. 1855 1856`same-permissions' 1857 `-p' in `tar'. 1858 1859`save' 1860 `-g' in `stty'. 1861 1862`se' 1863 Used in GDB. 1864 1865`sentence-regexp' 1866 `-S' in `ptx'. 1867 1868`separate-dirs' 1869 `-S' in `du'. 1870 1871`separator' 1872 `-s' in `tac'. 1873 1874`sequence' 1875 Used by `recode' to chose files or pipes for sequencing passes. 1876 1877`shell' 1878 `-s' in `su'. 1879 1880`show-all' 1881 `-A' in `cat'. 1882 1883`show-c-function' 1884 `-p' in `diff'. 1885 1886`show-ends' 1887 `-E' in `cat'. 1888 1889`show-function-line' 1890 `-F' in `diff'. 1891 1892`show-tabs' 1893 `-T' in `cat'. 1894 1895`silent' 1896 Used in many programs to inhibit the usual output. Every program 1897 accepting `--silent' should accept `--quiet' as a synonym. 1898 1899`size' 1900 `-s' in `ls'. 1901 1902`socket' 1903 Specify a file descriptor for a network server to use for its 1904 socket, instead of opening and binding a new socket. This 1905 provides a way to run, in a non-privileged process, a server that 1906 normally needs a reserved port number. 1907 1908`sort' 1909 Used in `ls'. 1910 1911`source' 1912 `-W source' in `gawk'. 1913 1914`sparse' 1915 `-S' in `tar'. 1916 1917`speed-large-files' 1918 `-H' in `diff'. 1919 1920`split-at' 1921 `-E' in `unshar'. 1922 1923`split-size-limit' 1924 `-L' in `shar'. 1925 1926`squeeze-blank' 1927 `-s' in `cat'. 1928 1929`start-delete' 1930 `-w' in `wdiff'. 1931 1932`start-insert' 1933 `-y' in `wdiff'. 1934 1935`starting-file' 1936 Used in `tar' and `diff' to specify which file within a directory 1937 to start processing with. 1938 1939`statistics' 1940 `-s' in `wdiff'. 1941 1942`stdin-file-list' 1943 `-S' in `shar'. 1944 1945`stop' 1946 `-S' in Make. 1947 1948`strict' 1949 `-s' in `recode'. 1950 1951`strip' 1952 `-s' in `install'. 1953 1954`strip-all' 1955 `-s' in `strip'. 1956 1957`strip-debug' 1958 `-S' in `strip'. 1959 1960`submitter' 1961 `-s' in `shar'. 1962 1963`suffix' 1964 `-S' in `cp', `ln', `mv'. 1965 1966`suffix-format' 1967 `-b' in `csplit'. 1968 1969`sum' 1970 `-s' in `gprof'. 1971 1972`summarize' 1973 `-s' in `du'. 1974 1975`symbolic' 1976 `-s' in `ln'. 1977 1978`symbols' 1979 Used in GDB and `objdump'. 1980 1981`synclines' 1982 `-s' in `m4'. 1983 1984`sysname' 1985 `-s' in `uname'. 1986 1987`tabs' 1988 `-t' in `expand' and `unexpand'. 1989 1990`tabsize' 1991 `-T' in `ls'. 1992 1993`terminal' 1994 `-T' in `tput' and `ul'. `-t' in `wdiff'. 1995 1996`text' 1997 `-a' in `diff'. 1998 1999`text-files' 2000 `-T' in `shar'. 2001 2002`time' 2003 Used in `ls' and `touch'. 2004 2005`timeout' 2006 Specify how long to wait before giving up on some operation. 2007 2008`to-stdout' 2009 `-O' in `tar'. 2010 2011`total' 2012 `-c' in `du'. 2013 2014`touch' 2015 `-t' in Make, `ranlib', and `recode'. 2016 2017`trace' 2018 `-t' in `m4'. 2019 2020`traditional' 2021 `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4', 2022 and `ptx'. 2023 2024`tty' 2025 Used in GDB. 2026 2027`typedefs' 2028 `-t' in `ctags'. 2029 2030`typedefs-and-c++' 2031 `-T' in `ctags'. 2032 2033`typeset-mode' 2034 `-t' in `ptx'. 2035 2036`uncompress' 2037 `-z' in `tar'. 2038 2039`unconditional' 2040 `-u' in `cpio'. 2041 2042`undefine' 2043 `-U' in `m4'. 2044 2045`undefined-only' 2046 `-u' in `nm'. 2047 2048`update' 2049 `-u' in `cp', `ctags', `mv', `tar'. 2050 2051`usage' 2052 Used in `gawk'; same as `--help'. 2053 2054`uuencode' 2055 `-B' in `shar'. 2056 2057`vanilla-operation' 2058 `-V' in `shar'. 2059 2060`verbose' 2061 Print more information about progress. Many programs support this. 2062 2063`verify' 2064 `-W' in `tar'. 2065 2066`version' 2067 Print the version number. 2068 2069`version-control' 2070 `-V' in `cp', `ln', `mv'. 2071 2072`vgrind' 2073 `-v' in `ctags'. 2074 2075`volume' 2076 `-V' in `tar'. 2077 2078`what-if' 2079 `-W' in Make. 2080 2081`whole-size-limit' 2082 `-l' in `shar'. 2083 2084`width' 2085 `-w' in `ls' and `ptx'. 2086 2087`word-regexp' 2088 `-W' in `ptx'. 2089 2090`writable' 2091 `-T' in `who'. 2092 2093`zeros' 2094 `-z' in `gprof'. 2095 2096 2097File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior 2098 20994.9 Memory Usage 2100================ 2101 2102If a program typically uses just a few meg of memory, don't bother 2103making any effort to reduce memory usage. For example, if it is 2104impractical for other reasons to operate on files more than a few meg 2105long, it is reasonable to read entire input files into memory to 2106operate on them. 2107 2108 However, for programs such as `cat' or `tail', that can usefully 2109operate on very large files, it is important to avoid using a technique 2110that would artificially limit the size of files it can handle. If a 2111program works by lines and could be applied to arbitrary user-supplied 2112input files, it should keep only a line in memory, because this is not 2113very hard and users will want to be able to operate on input files that 2114are bigger than will fit in memory all at once. 2115 2116 If your program creates complicated data structures, just make them 2117in memory and give a fatal error if `malloc' returns zero. 2118 2119 2120File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior 2121 21224.10 File Usage 2123=============== 2124 2125Programs should be prepared to operate when `/usr' and `/etc' are 2126read-only file systems. Thus, if the program manages log files, lock 2127files, backup files, score files, or any other files which are modified 2128for internal purposes, these files should not be stored in `/usr' or 2129`/etc'. 2130 2131 There are two exceptions. `/etc' is used to store system 2132configuration information; it is reasonable for a program to modify 2133files in `/etc' when its job is to update the system configuration. 2134Also, if the user explicitly asks to modify one file in a directory, it 2135is reasonable for the program to store other files in the same 2136directory. 2137 2138 2139File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top 2140 21415 Making The Best Use of C 2142************************** 2143 2144This chapter provides advice on how best to use the C language when 2145writing GNU software. 2146 2147* Menu: 2148 2149* Formatting:: Formatting your source code. 2150* Comments:: Commenting your work. 2151* Syntactic Conventions:: Clean use of C constructs. 2152* Names:: Naming variables, functions, and files. 2153* System Portability:: Portability among different operating systems. 2154* CPU Portability:: Supporting the range of CPU types. 2155* System Functions:: Portability and ``standard'' library functions. 2156* Internationalization:: Techniques for internationalization. 2157* Character Set:: Use ASCII by default. 2158* Quote Characters:: Use `...' in the C locale. 2159* Mmap:: How you can safely use `mmap'. 2160 2161 2162File: standards.info, Node: Formatting, Next: Comments, Up: Writing C 2163 21645.1 Formatting Your Source Code 2165=============================== 2166 2167It is important to put the open-brace that starts the body of a C 2168function in column one, so that they will start a defun. Several tools 2169look for open-braces in column one to find the beginnings of C 2170functions. These tools will not work on code not formatted that way. 2171 2172 Avoid putting open-brace, open-parenthesis or open-bracket in column 2173one when they are inside a function, so that they won't start a defun. 2174The open-brace that starts a `struct' body can go in column one if you 2175find it useful to treat that definition as a defun. 2176 2177 It is also important for function definitions to start the name of 2178the function in column one. This helps people to search for function 2179definitions, and may also help certain tools recognize them. Thus, 2180using Standard C syntax, the format is this: 2181 2182 static char * 2183 concat (char *s1, char *s2) 2184 { 2185 ... 2186 } 2187 2188or, if you want to use traditional C syntax, format the definition like 2189this: 2190 2191 static char * 2192 concat (s1, s2) /* Name starts in column one here */ 2193 char *s1, *s2; 2194 { /* Open brace in column one here */ 2195 ... 2196 } 2197 2198 In Standard C, if the arguments don't fit nicely on one line, split 2199it like this: 2200 2201 int 2202 lots_of_args (int an_integer, long a_long, short a_short, 2203 double a_double, float a_float) 2204 ... 2205 2206 The rest of this section gives our recommendations for other aspects 2207of C formatting style, which is also the default style of the `indent' 2208program in version 1.2 and newer. It corresponds to the options 2209 2210 -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 2211 -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob 2212 2213 We don't think of these recommendations as requirements, because it 2214causes no problems for users if two different programs have different 2215formatting styles. 2216 2217 But whatever style you use, please use it consistently, since a 2218mixture of styles within one program tends to look ugly. If you are 2219contributing changes to an existing program, please follow the style of 2220that program. 2221 2222 For the body of the function, our recommended style looks like this: 2223 2224 if (x < foo (y, z)) 2225 haha = bar[4] + 5; 2226 else 2227 { 2228 while (z) 2229 { 2230 haha += foo (z, z); 2231 z--; 2232 } 2233 return ++x + bar (); 2234 } 2235 2236 We find it easier to read a program when it has spaces before the 2237open-parentheses and after the commas. Especially after the commas. 2238 2239 When you split an expression into multiple lines, split it before an 2240operator, not after one. Here is the right way: 2241 2242 if (foo_this_is_long && bar > win (x, y, z) 2243 && remaining_condition) 2244 2245 Try to avoid having two operators of different precedence at the same 2246level of indentation. For example, don't write this: 2247 2248 mode = (inmode[j] == VOIDmode 2249 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) 2250 ? outmode[j] : inmode[j]); 2251 2252 Instead, use extra parentheses so that the indentation shows the 2253nesting: 2254 2255 mode = ((inmode[j] == VOIDmode 2256 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) 2257 ? outmode[j] : inmode[j]); 2258 2259 Insert extra parentheses so that Emacs will indent the code properly. 2260For example, the following indentation looks nice if you do it by hand, 2261 2262 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 2263 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; 2264 2265but Emacs would alter it. Adding a set of parentheses produces 2266something that looks equally nice, and which Emacs will preserve: 2267 2268 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 2269 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); 2270 2271 Format do-while statements like this: 2272 2273 do 2274 { 2275 a = foo (a); 2276 } 2277 while (a > 0); 2278 2279 Please use formfeed characters (control-L) to divide the program into 2280pages at logical places (but not within a function). It does not matter 2281just how long the pages are, since they do not have to fit on a printed 2282page. The formfeeds should appear alone on lines by themselves. 2283 2284 2285File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C 2286 22875.2 Commenting Your Work 2288======================== 2289 2290Every program should start with a comment saying briefly what it is for. 2291Example: `fmt - filter for simple filling of text'. This comment 2292should be at the top of the source file containing the `main' function 2293of the program. 2294 2295 Also, please write a brief comment at the start of each source file, 2296with the file name and a line or two about the overall purpose of the 2297file. 2298 2299 Please write the comments in a GNU program in English, because 2300English is the one language that nearly all programmers in all 2301countries can read. If you do not write English well, please write 2302comments in English as well as you can, then ask other people to help 2303rewrite them. If you can't write comments in English, please find 2304someone to work with you and translate your comments into English. 2305 2306 Please put a comment on each function saying what the function does, 2307what sorts of arguments it gets, and what the possible values of 2308arguments mean and are used for. It is not necessary to duplicate in 2309words the meaning of the C argument declarations, if a C type is being 2310used in its customary fashion. If there is anything nonstandard about 2311its use (such as an argument of type `char *' which is really the 2312address of the second character of a string, not the first), or any 2313possible values that would not work the way one would expect (such as, 2314that strings containing newlines are not guaranteed to work), be sure 2315to say so. 2316 2317 Also explain the significance of the return value, if there is one. 2318 2319 Please put two spaces after the end of a sentence in your comments, 2320so that the Emacs sentence commands will work. Also, please write 2321complete sentences and capitalize the first word. If a lower-case 2322identifier comes at the beginning of a sentence, don't capitalize it! 2323Changing the spelling makes it a different identifier. If you don't 2324like starting a sentence with a lower case letter, write the sentence 2325differently (e.g., "The identifier lower-case is ..."). 2326 2327 The comment on a function is much clearer if you use the argument 2328names to speak about the argument values. The variable name itself 2329should be lower case, but write it in upper case when you are speaking 2330about the value rather than the variable itself. Thus, "the inode 2331number NODE_NUM" rather than "an inode". 2332 2333 There is usually no purpose in restating the name of the function in 2334the comment before it, because the reader can see that for himself. 2335There might be an exception when the comment is so long that the 2336function itself would be off the bottom of the screen. 2337 2338 There should be a comment on each static variable as well, like this: 2339 2340 /* Nonzero means truncate lines in the display; 2341 zero means continue them. */ 2342 int truncate_lines; 2343 2344 Every `#endif' should have a comment, except in the case of short 2345conditionals (just a few lines) that are not nested. The comment should 2346state the condition of the conditional that is ending, _including its 2347sense_. `#else' should have a comment describing the condition _and 2348sense_ of the code that follows. For example: 2349 2350 #ifdef foo 2351 ... 2352 #else /* not foo */ 2353 ... 2354 #endif /* not foo */ 2355 #ifdef foo 2356 ... 2357 #endif /* foo */ 2358 2359but, by contrast, write the comments this way for a `#ifndef': 2360 2361 #ifndef foo 2362 ... 2363 #else /* foo */ 2364 ... 2365 #endif /* foo */ 2366 #ifndef foo 2367 ... 2368 #endif /* not foo */ 2369 2370 2371File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C 2372 23735.3 Clean Use of C Constructs 2374============================= 2375 2376Please explicitly declare the types of all objects. For example, you 2377should explicitly declare all arguments to functions, and you should 2378declare functions to return `int' rather than omitting the `int'. 2379 2380 Some programmers like to use the GCC `-Wall' option, and change the 2381code whenever it issues a warning. If you want to do this, then do. 2382Other programmers prefer not to use `-Wall', because it gives warnings 2383for valid and legitimate code which they do not want to change. If you 2384want to do this, then do. The compiler should be your servant, not 2385your master. 2386 2387 Declarations of external functions and functions to appear later in 2388the source file should all go in one place near the beginning of the 2389file (somewhere before the first function definition in the file), or 2390else should go in a header file. Don't put `extern' declarations inside 2391functions. 2392 2393 It used to be common practice to use the same local variables (with 2394names like `tem') over and over for different values within one 2395function. Instead of doing this, it is better to declare a separate 2396local variable for each distinct purpose, and give it a name which is 2397meaningful. This not only makes programs easier to understand, it also 2398facilitates optimization by good compilers. You can also move the 2399declaration of each local variable into the smallest scope that includes 2400all its uses. This makes the program even cleaner. 2401 2402 Don't use local variables or parameters that shadow global 2403identifiers. 2404 2405 Don't declare multiple variables in one declaration that spans lines. 2406Start a new declaration on each line, instead. For example, instead of 2407this: 2408 2409 int foo, 2410 bar; 2411 2412write either this: 2413 2414 int foo, bar; 2415 2416or this: 2417 2418 int foo; 2419 int bar; 2420 2421(If they are global variables, each should have a comment preceding it 2422anyway.) 2423 2424 When you have an `if'-`else' statement nested in another `if' 2425statement, always put braces around the `if'-`else'. Thus, never write 2426like this: 2427 2428 if (foo) 2429 if (bar) 2430 win (); 2431 else 2432 lose (); 2433 2434always like this: 2435 2436 if (foo) 2437 { 2438 if (bar) 2439 win (); 2440 else 2441 lose (); 2442 } 2443 2444 If you have an `if' statement nested inside of an `else' statement, 2445either write `else if' on one line, like this, 2446 2447 if (foo) 2448 ... 2449 else if (bar) 2450 ... 2451 2452with its `then'-part indented like the preceding `then'-part, or write 2453the nested `if' within braces like this: 2454 2455 if (foo) 2456 ... 2457 else 2458 { 2459 if (bar) 2460 ... 2461 } 2462 2463 Don't declare both a structure tag and variables or typedefs in the 2464same declaration. Instead, declare the structure tag separately and 2465then use it to declare the variables or typedefs. 2466 2467 Try to avoid assignments inside `if'-conditions (assignments inside 2468`while'-conditions are ok). For example, don't write this: 2469 2470 if ((foo = (char *) malloc (sizeof *foo)) == 0) 2471 fatal ("virtual memory exhausted"); 2472 2473instead, write this: 2474 2475 foo = (char *) malloc (sizeof *foo); 2476 if (foo == 0) 2477 fatal ("virtual memory exhausted"); 2478 2479 Don't make the program ugly to placate `lint'. Please don't insert 2480any casts to `void'. Zero without a cast is perfectly fine as a null 2481pointer constant, except when calling a varargs function. 2482 2483 2484File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C 2485 24865.4 Naming Variables, Functions, and Files 2487========================================== 2488 2489The names of global variables and functions in a program serve as 2490comments of a sort. So don't choose terse names--instead, look for 2491names that give useful information about the meaning of the variable or 2492function. In a GNU program, names should be English, like other 2493comments. 2494 2495 Local variable names can be shorter, because they are used only 2496within one context, where (presumably) comments explain their purpose. 2497 2498 Try to limit your use of abbreviations in symbol names. It is ok to 2499make a few abbreviations, explain what they mean, and then use them 2500frequently, but don't use lots of obscure abbreviations. 2501 2502 Please use underscores to separate words in a name, so that the Emacs 2503word commands can be useful within them. Stick to lower case; reserve 2504upper case for macros and `enum' constants, and for name-prefixes that 2505follow a uniform convention. 2506 2507 For example, you should use names like `ignore_space_change_flag'; 2508don't use names like `iCantReadThis'. 2509 2510 Variables that indicate whether command-line options have been 2511specified should be named after the meaning of the option, not after 2512the option-letter. A comment should state both the exact meaning of 2513the option and its letter. For example, 2514 2515 /* Ignore changes in horizontal whitespace (-b). */ 2516 int ignore_space_change_flag; 2517 2518 When you want to define names with constant integer values, use 2519`enum' rather than `#define'. GDB knows about enumeration constants. 2520 2521 You might want to make sure that none of the file names would 2522conflict if the files were loaded onto an MS-DOS file system which 2523shortens the names. You can use the program `doschk' to test for this. 2524 2525 Some GNU programs were designed to limit themselves to file names of 252614 characters or less, to avoid file name conflicts if they are read 2527into older System V systems. Please preserve this feature in the 2528existing GNU programs that have it, but there is no need to do this in 2529new GNU programs. `doschk' also reports file names longer than 14 2530characters. 2531 2532 2533File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C 2534 25355.5 Portability between System Types 2536==================================== 2537 2538In the Unix world, "portability" refers to porting to different Unix 2539versions. For a GNU program, this kind of portability is desirable, but 2540not paramount. 2541 2542 The primary purpose of GNU software is to run on top of the GNU 2543kernel, compiled with the GNU C compiler, on various types of CPU. So 2544the kinds of portability that are absolutely necessary are quite 2545limited. But it is important to support Linux-based GNU systems, since 2546they are the form of GNU that is popular. 2547 2548 Beyond that, it is good to support the other free operating systems 2549(*BSD), and it is nice to support other Unix-like systems if you want 2550to. Supporting a variety of Unix-like systems is desirable, although 2551not paramount. It is usually not too hard, so you may as well do it. 2552But you don't have to consider it an obligation, if it does turn out to 2553be hard. 2554 2555 The easiest way to achieve portability to most Unix-like systems is 2556to use Autoconf. It's unlikely that your program needs to know more 2557information about the host platform than Autoconf can provide, simply 2558because most of the programs that need such knowledge have already been 2559written. 2560 2561 Avoid using the format of semi-internal data bases (e.g., 2562directories) when there is a higher-level alternative (`readdir'). 2563 2564 As for systems that are not like Unix, such as MSDOS, Windows, VMS, 2565MVS, and older Macintosh systems, supporting them is often a lot of 2566work. When that is the case, it is better to spend your time adding 2567features that will be useful on GNU and GNU/Linux, rather than on 2568supporting other incompatible systems. 2569 2570 If you do support Windows, please do not abbreviate it as "win". In 2571hacker terminology, calling something a "win" is a form of praise. 2572You're free to praise Microsoft Windows on your own if you want, but 2573please don't do this in GNU packages. Instead of abbreviating 2574"Windows" to "un", you can write it in full or abbreviate it to "woe" 2575or "w". In GNU Emacs, for instance, we use `w32' in file names of 2576Windows-specific files, but the macro for Windows conditionals is 2577called `WINDOWSNT'. 2578 2579 It is a good idea to define the "feature test macro" `_GNU_SOURCE' 2580when compiling your C files. When you compile on GNU or GNU/Linux, 2581this will enable the declarations of GNU library extension functions, 2582and that will usually give you a compiler error message if you define 2583the same function names in some other way in your program. (You don't 2584have to actually _use_ these functions, if you prefer to make the 2585program more portable to other systems.) 2586 2587 But whether or not you use these GNU extensions, you should avoid 2588using their names for any other meanings. Doing so would make it hard 2589to move your code into other GNU programs. 2590 2591 2592File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C 2593 25945.6 Portability between CPUs 2595============================ 2596 2597Even GNU systems will differ because of differences among CPU 2598types--for example, difference in byte ordering and alignment 2599requirements. It is absolutely essential to handle these differences. 2600However, don't make any effort to cater to the possibility that an 2601`int' will be less than 32 bits. We don't support 16-bit machines in 2602GNU. 2603 2604 Similarly, don't make any effort to cater to the possibility that 2605`long' will be smaller than predefined types like `size_t'. For 2606example, the following code is ok: 2607 2608 printf ("size = %lu\n", (unsigned long) sizeof array); 2609 printf ("diff = %ld\n", (long) (pointer2 - pointer1)); 2610 2611 1989 Standard C requires this to work, and we know of only one 2612counterexample: 64-bit programs on Microsoft Windows. We will leave it 2613to those who want to port GNU programs to that environment to figure 2614out how to do it. 2615 2616 Predefined file-size types like `off_t' are an exception: they are 2617longer than `long' on many platforms, so code like the above won't work 2618with them. One way to print an `off_t' value portably is to print its 2619digits yourself, one by one. 2620 2621 Don't assume that the address of an `int' object is also the address 2622of its least-significant byte. This is false on big-endian machines. 2623Thus, don't make the following mistake: 2624 2625 int c; 2626 ... 2627 while ((c = getchar ()) != EOF) 2628 write (file_descriptor, &c, 1); 2629 2630Instead, use `unsigned char' as follows. (The `unsigned' is for 2631portability to unusual systems where `char' is signed and where there 2632is integer overflow checking.) 2633 2634 int c; 2635 while ((c = getchar ()) != EOF) 2636 { 2637 unsigned char u = c; 2638 write (file_descriptor, &u, 1); 2639 } 2640 2641 It used to be ok to not worry about the difference between pointers 2642and integers when passing arguments to functions. However, on most 2643modern 64-bit machines pointers are wider than `int'. Conversely, 2644integer types like `long long int' and `off_t' are wider than pointers 2645on most modern 32-bit machines. Hence it's often better nowadays to 2646use prototypes to define functions whose argument types are not trivial. 2647 2648 In particular, if functions accept varying argument counts or types 2649they should be declared using prototypes containing `...' and defined 2650using `stdarg.h'. For an example of this, please see the Gnulib 2651(http://www.gnu.org/software/gnulib/) error module, which declares and 2652defines the following function: 2653 2654 /* Print a message with `fprintf (stderr, FORMAT, ...)'; 2655 if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM). 2656 If STATUS is nonzero, terminate the program with `exit (STATUS)'. */ 2657 2658 void error (int status, int errnum, const char *format, ...); 2659 2660 A simple way to use the Gnulib error module is to obtain the two 2661source files `error.c' and `error.h' from the Gnulib library source 2662code repository at 2663`http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'. Here's a 2664sample use: 2665 2666 #include "error.h" 2667 #include <errno.h> 2668 #include <stdio.h> 2669 2670 char *program_name = "myprogram"; 2671 2672 FILE * 2673 xfopen (char const *name) 2674 { 2675 FILE *fp = fopen (name, "r"); 2676 if (! fp) 2677 error (1, errno, "cannot read %s", name); 2678 return fp; 2679 } 2680 2681 Avoid casting pointers to integers if you can. Such casts greatly 2682reduce portability, and in most programs they are easy to avoid. In the 2683cases where casting pointers to integers is essential--such as, a Lisp 2684interpreter which stores type information as well as an address in one 2685word--you'll have to make explicit provisions to handle different word 2686sizes. You will also need to make provision for systems in which the 2687normal range of addresses you can get from `malloc' starts far away 2688from zero. 2689 2690 2691File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C 2692 26935.7 Calling System Functions 2694============================ 2695 2696C implementations differ substantially. Standard C reduces but does 2697not eliminate the incompatibilities; meanwhile, many GNU packages still 2698support pre-standard compilers because this is not hard to do. This 2699chapter gives recommendations for how to use the more-or-less standard C 2700library functions to avoid unnecessary loss of portability. 2701 2702 * Don't use the return value of `sprintf'. It returns the number of 2703 characters written on some systems, but not on all systems. 2704 2705 * Be aware that `vfprintf' is not always available. 2706 2707 * `main' should be declared to return type `int'. It should 2708 terminate either by calling `exit' or by returning the integer 2709 status code; make sure it cannot ever return an undefined value. 2710 2711 * Don't declare system functions explicitly. 2712 2713 Almost any declaration for a system function is wrong on some 2714 system. To minimize conflicts, leave it to the system header 2715 files to declare system functions. If the headers don't declare a 2716 function, let it remain undeclared. 2717 2718 While it may seem unclean to use a function without declaring it, 2719 in practice this works fine for most system library functions on 2720 the systems where this really happens; thus, the disadvantage is 2721 only theoretical. By contrast, actual declarations have 2722 frequently caused actual conflicts. 2723 2724 * If you must declare a system function, don't specify the argument 2725 types. Use an old-style declaration, not a Standard C prototype. 2726 The more you specify about the function, the more likely a 2727 conflict. 2728 2729 * In particular, don't unconditionally declare `malloc' or `realloc'. 2730 2731 Most GNU programs use those functions just once, in functions 2732 conventionally named `xmalloc' and `xrealloc'. These functions 2733 call `malloc' and `realloc', respectively, and check the results. 2734 2735 Because `xmalloc' and `xrealloc' are defined in your program, you 2736 can declare them in other files without any risk of type conflict. 2737 2738 On most systems, `int' is the same length as a pointer; thus, the 2739 calls to `malloc' and `realloc' work fine. For the few 2740 exceptional systems (mostly 64-bit machines), you can use 2741 *conditionalized* declarations of `malloc' and `realloc'--or put 2742 these declarations in configuration files specific to those 2743 systems. 2744 2745 * The string functions require special treatment. Some Unix systems 2746 have a header file `string.h'; others have `strings.h'. Neither 2747 file name is portable. There are two things you can do: use 2748 Autoconf to figure out which file to include, or don't include 2749 either file. 2750 2751 * If you don't include either strings file, you can't get 2752 declarations for the string functions from the header file in the 2753 usual way. 2754 2755 That causes less of a problem than you might think. The newer 2756 standard string functions should be avoided anyway because many 2757 systems still don't support them. The string functions you can 2758 use are these: 2759 2760 strcpy strncpy strcat strncat 2761 strlen strcmp strncmp 2762 strchr strrchr 2763 2764 The copy and concatenate functions work fine without a declaration 2765 as long as you don't use their values. Using their values without 2766 a declaration fails on systems where the width of a pointer 2767 differs from the width of `int', and perhaps in other cases. It 2768 is trivial to avoid using their values, so do that. 2769 2770 The compare functions and `strlen' work fine without a declaration 2771 on most systems, possibly all the ones that GNU software runs on. 2772 You may find it necessary to declare them *conditionally* on a few 2773 systems. 2774 2775 The search functions must be declared to return `char *'. Luckily, 2776 there is no variation in the data type they return. But there is 2777 variation in their names. Some systems give these functions the 2778 names `index' and `rindex'; other systems use the names `strchr' 2779 and `strrchr'. Some systems support both pairs of names, but 2780 neither pair works on all systems. 2781 2782 You should pick a single pair of names and use it throughout your 2783 program. (Nowadays, it is better to choose `strchr' and `strrchr' 2784 for new programs, since those are the standard names.) Declare 2785 both of those names as functions returning `char *'. On systems 2786 which don't support those names, define them as macros in terms of 2787 the other pair. For example, here is what to put at the beginning 2788 of your file (or in a header) if you want to use the names 2789 `strchr' and `strrchr' throughout: 2790 2791 #ifndef HAVE_STRCHR 2792 #define strchr index 2793 #endif 2794 #ifndef HAVE_STRRCHR 2795 #define strrchr rindex 2796 #endif 2797 2798 char *strchr (); 2799 char *strrchr (); 2800 2801 Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros 2802defined in systems where the corresponding functions exist. One way to 2803get them properly defined is to use Autoconf. 2804 2805 2806File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C 2807 28085.8 Internationalization 2809======================== 2810 2811GNU has a library called GNU gettext that makes it easy to translate the 2812messages in a program into various languages. You should use this 2813library in every program. Use English for the messages as they appear 2814in the program, and let gettext provide the way to translate them into 2815other languages. 2816 2817 Using GNU gettext involves putting a call to the `gettext' macro 2818around each string that might need translation--like this: 2819 2820 printf (gettext ("Processing file `%s'...")); 2821 2822This permits GNU gettext to replace the string `"Processing file 2823`%s'..."' with a translated version. 2824 2825 Once a program uses gettext, please make a point of writing calls to 2826`gettext' when you add new strings that call for translation. 2827 2828 Using GNU gettext in a package involves specifying a "text domain 2829name" for the package. The text domain name is used to separate the 2830translations for this package from the translations for other packages. 2831Normally, the text domain name should be the same as the name of the 2832package--for example, `coreutils' for the GNU core utilities. 2833 2834 To enable gettext to work well, avoid writing code that makes 2835assumptions about the structure of words or sentences. When you want 2836the precise text of a sentence to vary depending on the data, use two or 2837more alternative string constants each containing a complete sentences, 2838rather than inserting conditionalized words or phrases into a single 2839sentence framework. 2840 2841 Here is an example of what not to do: 2842 2843 printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk"); 2844 2845 If you apply gettext to all strings, like this, 2846 2847 printf (gettext ("%s is full"), 2848 capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk")); 2849 2850the translator will hardly know that "disk" and "floppy disk" are meant 2851to be substituted in the other string. Worse, in some languages (like 2852French) the construction will not work: the translation of the word 2853"full" depends on the gender of the first part of the sentence; it 2854happens to be not the same for "disk" as for "floppy disk". 2855 2856 Complete sentences can be translated without problems: 2857 2858 printf (capacity > 5000000 ? gettext ("disk is full") 2859 : gettext ("floppy disk is full")); 2860 2861 A similar problem appears at the level of sentence structure with 2862this code: 2863 2864 printf ("# Implicit rule search has%s been done.\n", 2865 f->tried_implicit ? "" : " not"); 2866 2867Adding `gettext' calls to this code cannot give correct results for all 2868languages, because negation in some languages requires adding words at 2869more than one place in the sentence. By contrast, adding `gettext' 2870calls does the job straightforwardly if the code starts out like this: 2871 2872 printf (f->tried_implicit 2873 ? "# Implicit rule search has been done.\n", 2874 : "# Implicit rule search has not been done.\n"); 2875 2876 Another example is this one: 2877 2878 printf ("%d file%s processed", nfiles, 2879 nfiles != 1 ? "s" : ""); 2880 2881The problem with this example is that it assumes that plurals are made 2882by adding `s'. If you apply gettext to the format string, like this, 2883 2884 printf (gettext ("%d file%s processed"), nfiles, 2885 nfiles != 1 ? "s" : ""); 2886 2887the message can use different words, but it will still be forced to use 2888`s' for the plural. Here is a better way, with gettext being applied to 2889the two strings independently: 2890 2891 printf ((nfiles != 1 ? gettext ("%d files processed") 2892 : gettext ("%d file processed")), 2893 nfiles); 2894 2895But this still doesn't work for languages like Polish, which has three 2896plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23, 289724, ... and one for the rest. The GNU `ngettext' function solves this 2898problem: 2899 2900 printf (ngettext ("%d files processed", "%d file processed", nfiles), 2901 nfiles); 2902 2903 2904File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C 2905 29065.9 Character Set 2907================= 2908 2909Sticking to the ASCII character set (plain text, 7-bit characters) is 2910preferred in GNU source code comments, text documents, and other 2911contexts, unless there is good reason to do something else because of 2912the application domain. For example, if source code deals with the 2913French Revolutionary calendar, it is OK if its literal strings contain 2914accented characters in month names like "Flore'al". Also, it is OK to 2915use non-ASCII characters to represent proper names of contributors in 2916change logs (*note Change Logs::). 2917 2918 If you need to use non-ASCII characters, you should normally stick 2919with one encoding, as one cannot in general mix encodings reliably. 2920 2921 2922File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C 2923 29245.10 Quote Characters 2925===================== 2926 2927In the C locale, GNU programs should stick to plain ASCII for quotation 2928characters in messages to users: preferably 0x60 (``') for left quotes 2929and 0x27 (`'') for right quotes. It is ok, but not required, to use 2930locale-specific quotes in other locales. 2931 2932 The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and 2933`quotearg' modules provide a reasonably straightforward way to support 2934locale-specific quote characters, as well as taking care of other 2935issues, such as quoting a filename that itself contains a quote 2936character. See the Gnulib documentation for usage details. 2937 2938 In any case, the documentation for your program should clearly 2939specify how it does quoting, if different than the preferred method of 2940``' and `''. This is especially important if the output of your 2941program is ever likely to be parsed by another program. 2942 2943 Quotation characters are a difficult area in the computing world at 2944this time: there are no true left or right quote characters in Latin1; 2945the ``' character we use was standardized there as a grave accent. 2946Moreover, Latin1 is still not universally usable. 2947 2948 Unicode contains the unambiguous quote characters required, and its 2949common encoding UTF-8 is upward compatible with Latin1. However, 2950Unicode and UTF-8 are not universally well-supported, either. 2951 2952 This may change over the next few years, and then we will revisit 2953this. 2954 2955 2956File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C 2957 29585.11 Mmap 2959========= 2960 2961Don't assume that `mmap' either works on all files or fails for all 2962files. It may work on some files and fail on others. 2963 2964 The proper way to use `mmap' is to try it on the specific file for 2965which you want to use it--and if `mmap' doesn't work, fall back on 2966doing the job in another way using `read' and `write'. 2967 2968 The reason this precaution is needed is that the GNU kernel (the 2969HURD) provides a user-extensible file system, in which there can be many 2970different kinds of "ordinary files." Many of them support `mmap', but 2971some do not. It is important to make programs handle all these kinds 2972of files. 2973 2974 2975File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top 2976 29776 Documenting Programs 2978********************** 2979 2980A GNU program should ideally come with full free documentation, adequate 2981for both reference and tutorial purposes. If the package can be 2982programmed or extended, the documentation should cover programming or 2983extending it, as well as just using it. 2984 2985* Menu: 2986 2987* GNU Manuals:: Writing proper manuals. 2988* Doc Strings and Manuals:: Compiling doc strings doesn't make a manual. 2989* Manual Structure Details:: Specific structure conventions. 2990* License for Manuals:: Writing the distribution terms for a manual. 2991* Manual Credits:: Giving credit to documentation contributors. 2992* Printed Manuals:: Mentioning the printed manual. 2993* NEWS File:: NEWS files supplement manuals. 2994* Change Logs:: Recording changes. 2995* Man Pages:: Man pages are secondary. 2996* Reading other Manuals:: How far you can go in learning 2997 from other manuals. 2998 2999 3000File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation 3001 30026.1 GNU Manuals 3003=============== 3004 3005The preferred document format for the GNU system is the Texinfo 3006formatting language. Every GNU package should (ideally) have 3007documentation in Texinfo both for reference and for learners. Texinfo 3008makes it possible to produce a good quality formatted book, using TeX, 3009and to generate an Info file. It is also possible to generate HTML 3010output from Texinfo source. See the Texinfo manual, either the 3011hardcopy, or the on-line version available through `info' or the Emacs 3012Info subsystem (`C-h i'). 3013 3014 Nowadays some other formats such as Docbook and Sgmltexi can be 3015converted automatically into Texinfo. It is ok to produce the Texinfo 3016documentation by conversion this way, as long as it gives good results. 3017 3018 Make sure your manual is clear to a reader who knows nothing about 3019the topic and reads it straight through. This means covering basic 3020topics at the beginning, and advanced topics only later. This also 3021means defining every specialized term when it is first used. 3022 3023 Programmers tend to carry over the structure of the program as the 3024structure for its documentation. But this structure is not necessarily 3025good for explaining how to use the program; it may be irrelevant and 3026confusing for a user. 3027 3028 Instead, the right way to structure documentation is according to the 3029concepts and questions that a user will have in mind when reading it. 3030This principle applies at every level, from the lowest (ordering 3031sentences in a paragraph) to the highest (ordering of chapter topics 3032within the manual). Sometimes this structure of ideas matches the 3033structure of the implementation of the software being documented--but 3034often they are different. An important part of learning to write good 3035documentation is to learn to notice when you have unthinkingly 3036structured the documentation like the implementation, stop yourself, 3037and look for better alternatives. 3038 3039 For example, each program in the GNU system probably ought to be 3040documented in one manual; but this does not mean each program should 3041have its own manual. That would be following the structure of the 3042implementation, rather than the structure that helps the user 3043understand. 3044 3045 Instead, each manual should cover a coherent _topic_. For example, 3046instead of a manual for `diff' and a manual for `diff3', we have one 3047manual for "comparison of files" which covers both of those programs, 3048as well as `cmp'. By documenting these programs together, we can make 3049the whole subject clearer. 3050 3051 The manual which discusses a program should certainly document all of 3052the program's command-line options and all of its commands. It should 3053give examples of their use. But don't organize the manual as a list of 3054features. Instead, organize it logically, by subtopics. Address the 3055questions that a user will ask when thinking about the job that the 3056program does. Don't just tell the reader what each feature can do--say 3057what jobs it is good for, and show how to use it for those jobs. 3058Explain what is recommended usage, and what kinds of usage users should 3059avoid. 3060 3061 In general, a GNU manual should serve both as tutorial and reference. 3062It should be set up for convenient access to each topic through Info, 3063and for reading straight through (appendixes aside). A GNU manual 3064should give a good introduction to a beginner reading through from the 3065start, and should also provide all the details that hackers want. The 3066Bison manual is a good example of this--please take a look at it to see 3067what we mean. 3068 3069 That is not as hard as it first sounds. Arrange each chapter as a 3070logical breakdown of its topic, but order the sections, and write their 3071text, so that reading the chapter straight through makes sense. Do 3072likewise when structuring the book into chapters, and when structuring a 3073section into paragraphs. The watchword is, _at each point, address the 3074most fundamental and important issue raised by the preceding text._ 3075 3076 If necessary, add extra chapters at the beginning of the manual which 3077are purely tutorial and cover the basics of the subject. These provide 3078the framework for a beginner to understand the rest of the manual. The 3079Bison manual provides a good example of how to do this. 3080 3081 To serve as a reference, a manual should have an Index that list all 3082the functions, variables, options, and important concepts that are part 3083of the program. One combined Index should do for a short manual, but 3084sometimes for a complex package it is better to use multiple indices. 3085The Texinfo manual includes advice on preparing good index entries, see 3086*Note Making Index Entries: (texinfo)Index Entries, and see *Note 3087Defining the Entries of an Index: (texinfo)Indexing Commands. 3088 3089 Don't use Unix man pages as a model for how to write GNU 3090documentation; most of them are terse, badly structured, and give 3091inadequate explanation of the underlying concepts. (There are, of 3092course, some exceptions.) Also, Unix man pages use a particular format 3093which is different from what we use in GNU manuals. 3094 3095 Please include an email address in the manual for where to report 3096bugs _in the text of the manual_. 3097 3098 Please do not use the term "pathname" that is used in Unix 3099documentation; use "file name" (two words) instead. We use the term 3100"path" only for search paths, which are lists of directory names. 3101 3102 Please do not use the term "illegal" to refer to erroneous input to 3103a computer program. Please use "invalid" for this, and reserve the 3104term "illegal" for activities prohibited by law. 3105 3106 Please do not write `()' after a function name just to indicate it 3107is a function. `foo ()' is not a function, it is a function call with 3108no arguments. 3109 3110 3111File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation 3112 31136.2 Doc Strings and Manuals 3114=========================== 3115 3116Some programming systems, such as Emacs, provide a documentation string 3117for each function, command or variable. You may be tempted to write a 3118reference manual by compiling the documentation strings and writing a 3119little additional text to go around them--but you must not do it. That 3120approach is a fundamental mistake. The text of well-written 3121documentation strings will be entirely wrong for a manual. 3122 3123 A documentation string needs to stand alone--when it appears on the 3124screen, there will be no other text to introduce or explain it. 3125Meanwhile, it can be rather informal in style. 3126 3127 The text describing a function or variable in a manual must not stand 3128alone; it appears in the context of a section or subsection. Other text 3129at the beginning of the section should explain some of the concepts, and 3130should often make some general points that apply to several functions or 3131variables. The previous descriptions of functions and variables in the 3132section will also have given information about the topic. A description 3133written to stand alone would repeat some of that information; this 3134redundancy looks bad. Meanwhile, the informality that is acceptable in 3135a documentation string is totally unacceptable in a manual. 3136 3137 The only good way to use documentation strings in writing a good 3138manual is to use them as a source of information for writing good text. 3139 3140 3141File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation 3142 31436.3 Manual Structure Details 3144============================ 3145 3146The title page of the manual should state the version of the programs or 3147packages documented in the manual. The Top node of the manual should 3148also contain this information. If the manual is changing more 3149frequently than or independent of the program, also state a version 3150number for the manual in both of these places. 3151 3152 Each program documented in the manual should have a node named 3153`PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with 3154its subnodes, if any) should describe the program's command line 3155arguments and how to run it (the sort of information people would look 3156for in a man page). Start with an `@example' containing a template for 3157all the options and arguments that the program uses. 3158 3159 Alternatively, put a menu item in some menu whose item name fits one 3160of the above patterns. This identifies the node which that item points 3161to as the node for this purpose, regardless of the node's actual name. 3162 3163 The `--usage' feature of the Info reader looks for such a node or 3164menu item in order to find the relevant text, so it is essential for 3165every Texinfo file to have one. 3166 3167 If one manual describes several programs, it should have such a node 3168for each program described in the manual. 3169 3170 3171File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation 3172 31736.4 License for Manuals 3174======================= 3175 3176Please use the GNU Free Documentation License for all GNU manuals that 3177are more than a few pages long. Likewise for a collection of short 3178documents--you only need one copy of the GNU FDL for the whole 3179collection. For a single short document, you can use a very permissive 3180non-copyleft license, to avoid taking up space with a long license. 3181 3182 See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation 3183of how to employ the GFDL. 3184 3185 Note that it is not obligatory to include a copy of the GNU GPL or 3186GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It 3187can be a good idea to include the program's license in a large manual; 3188in a short manual, whose size would be increased considerably by 3189including the program's license, it is probably better not to include 3190it. 3191 3192 3193File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation 3194 31956.5 Manual Credits 3196================== 3197 3198Please credit the principal human writers of the manual as the authors, 3199on the title page of the manual. If a company sponsored the work, thank 3200the company in a suitable place in the manual, but do not cite the 3201company as an author. 3202 3203 3204File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation 3205 32066.6 Printed Manuals 3207=================== 3208 3209The FSF publishes some GNU manuals in printed form. To encourage sales 3210of these manuals, the on-line versions of the manual should mention at 3211the very start that the printed manual is available and should point at 3212information for getting it--for instance, with a link to the page 3213`http://www.gnu.org/order/order.html'. This should not be included in 3214the printed manual, though, because there it is redundant. 3215 3216 It is also useful to explain in the on-line forms of the manual how 3217the user can print out the manual from the sources. 3218 3219 3220File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation 3221 32226.7 The NEWS File 3223================= 3224 3225In addition to its manual, the package should have a file named `NEWS' 3226which contains a list of user-visible changes worth mentioning. In 3227each new release, add items to the front of the file and identify the 3228version they pertain to. Don't discard old items; leave them in the 3229file after the newer items. This way, a user upgrading from any 3230previous version can see what is new. 3231 3232 If the `NEWS' file gets very long, move some of the older items into 3233a file named `ONEWS' and put a note at the end referring the user to 3234that file. 3235 3236 3237File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation 3238 32396.8 Change Logs 3240=============== 3241 3242Keep a change log to describe all the changes made to program source 3243files. The purpose of this is so that people investigating bugs in the 3244future will know about the changes that might have introduced the bug. 3245Often a new bug can be found by looking at what was recently changed. 3246More importantly, change logs can help you eliminate conceptual 3247inconsistencies between different parts of a program, by giving you a 3248history of how the conflicting concepts arose and who they came from. 3249 3250* Menu: 3251 3252* Change Log Concepts:: 3253* Style of Change Logs:: 3254* Simple Changes:: 3255* Conditional Changes:: 3256* Indicating the Part Changed:: 3257 3258 3259File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs 3260 32616.8.1 Change Log Concepts 3262------------------------- 3263 3264You can think of the change log as a conceptual "undo list" which 3265explains how earlier versions were different from the current version. 3266People can see the current version; they don't need the change log to 3267tell them what is in it. What they want from a change log is a clear 3268explanation of how the earlier version differed. 3269 3270 The change log file is normally called `ChangeLog' and covers an 3271entire directory. Each directory can have its own change log, or a 3272directory can use the change log of its parent directory-it's up to you. 3273 3274 Another alternative is to record change log information with a 3275version control system such as RCS or CVS. This can be converted 3276automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the 3277command `C-x v a' (`vc-update-change-log') does the job. 3278 3279 There's no need to describe the full purpose of the changes or how 3280they work together. If you think that a change calls for explanation, 3281you're probably right. Please do explain it--but please put the 3282explanation in comments in the code, where people will see it whenever 3283they see the code. For example, "New function" is enough for the 3284change log when you add a function, because there should be a comment 3285before the function definition to explain what it does. 3286 3287 In the past, we recommended not mentioning changes in non-software 3288files (manuals, help files, etc.) in change logs. However, we've been 3289advised that it is a good idea to include them, for the sake of 3290copyright records. 3291 3292 However, sometimes it is useful to write one line to describe the 3293overall purpose of a batch of changes. 3294 3295 The easiest way to add an entry to `ChangeLog' is with the Emacs 3296command `M-x add-change-log-entry'. An entry should have an asterisk, 3297the name of the changed file, and then in parentheses the name of the 3298changed functions, variables or whatever, followed by a colon. Then 3299describe the changes you made to that function or variable. 3300 3301 3302File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs 3303 33046.8.2 Style of Change Logs 3305-------------------------- 3306 3307Here are some simple examples of change log entries, starting with the 3308header line that says who made the change and when it was installed, 3309followed by descriptions of specific changes. (These examples are 3310drawn from Emacs and GCC.) 3311 3312 1998-08-17 Richard Stallman <rms@gnu.org> 3313 3314 * register.el (insert-register): Return nil. 3315 (jump-to-register): Likewise. 3316 3317 * sort.el (sort-subr): Return nil. 3318 3319 * tex-mode.el (tex-bibtex-file, tex-file, tex-region): 3320 Restart the tex shell if process is gone or stopped. 3321 (tex-shell-running): New function. 3322 3323 * expr.c (store_one_arg): Round size up for move_block_to_reg. 3324 (expand_call): Round up when emitting USE insns. 3325 * stmt.c (assign_parms): Round size up for move_block_from_reg. 3326 3327 It's important to name the changed function or variable in full. 3328Don't abbreviate function or variable names, and don't combine them. 3329Subsequent maintainers will often search for a function name to find all 3330the change log entries that pertain to it; if you abbreviate the name, 3331they won't find it when they search. 3332 3333 For example, some people are tempted to abbreviate groups of function 3334names by writing `* register.el ({insert,jump-to}-register)'; this is 3335not a good idea, since searching for `jump-to-register' or 3336`insert-register' would not find that entry. 3337 3338 Separate unrelated change log entries with blank lines. When two 3339entries represent parts of the same change, so that they work together, 3340then don't put blank lines between them. Then you can omit the file 3341name and the asterisk when successive entries are in the same file. 3342 3343 Break long lists of function names by closing continued lines with 3344`)', rather than `,', and opening the continuation with `(' as in this 3345example: 3346 3347 * keyboard.c (menu_bar_items, tool_bar_items) 3348 (Fexecute_extended_command): Deal with `keymap' property. 3349 3350 When you install someone else's changes, put the contributor's name 3351in the change log entry rather than in the text of the entry. In other 3352words, write this: 3353 3354 2002-07-14 John Doe <jdoe@gnu.org> 3355 3356 * sewing.c: Make it sew. 3357 3358rather than this: 3359 3360 2002-07-14 Usual Maintainer <usual@gnu.org> 3361 3362 * sewing.c: Make it sew. Patch by jdoe@gnu.org. 3363 3364 As for the date, that should be the date you applied the change. 3365 3366 3367File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs 3368 33696.8.3 Simple Changes 3370-------------------- 3371 3372Certain simple kinds of changes don't need much detail in the change 3373log. 3374 3375 When you change the calling sequence of a function in a simple 3376fashion, and you change all the callers of the function to use the new 3377calling sequence, there is no need to make individual entries for all 3378the callers that you changed. Just write in the entry for the function 3379being called, "All callers changed"--like this: 3380 3381 * keyboard.c (Fcommand_execute): New arg SPECIAL. 3382 All callers changed. 3383 3384 When you change just comments or doc strings, it is enough to write 3385an entry for the file, without mentioning the functions. Just "Doc 3386fixes" is enough for the change log. 3387 3388 There's no technical need to make change log entries for 3389documentation files. This is because documentation is not susceptible 3390to bugs that are hard to fix. Documentation does not consist of parts 3391that must interact in a precisely engineered fashion. To correct an 3392error, you need not know the history of the erroneous passage; it is 3393enough to compare what the documentation says with the way the program 3394actually works. 3395 3396 However, you should keep change logs for documentation files when the 3397project gets copyright assignments from its contributors, so as to make 3398the records of authorship more accurate. 3399 3400 3401File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs 3402 34036.8.4 Conditional Changes 3404------------------------- 3405 3406C programs often contain compile-time `#if' conditionals. Many changes 3407are conditional; sometimes you add a new definition which is entirely 3408contained in a conditional. It is very useful to indicate in the 3409change log the conditions for which the change applies. 3410 3411 Our convention for indicating conditional changes is to use square 3412brackets around the name of the condition. 3413 3414 Here is a simple example, describing a change which is conditional 3415but does not have a function or entity name associated with it: 3416 3417 * xterm.c [SOLARIS2]: Include string.h. 3418 3419 Here is an entry describing a new definition which is entirely 3420conditional. This new definition for the macro `FRAME_WINDOW_P' is 3421used only when `HAVE_X_WINDOWS' is defined: 3422 3423 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined. 3424 3425 Here is an entry for a change within the function `init_display', 3426whose definition as a whole is unconditional, but the changes themselves 3427are contained in a `#ifdef HAVE_LIBNCURSES' conditional: 3428 3429 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent. 3430 3431 Here is an entry for a change that takes affect only when a certain 3432macro is _not_ defined: 3433 3434 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version. 3435 3436 3437File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs 3438 34396.8.5 Indicating the Part Changed 3440--------------------------------- 3441 3442Indicate the part of a function which changed by using angle brackets 3443enclosing an indication of what the changed part does. Here is an entry 3444for a change in the part of the function `sh-while-getopts' that deals 3445with `sh' commands: 3446 3447 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that 3448 user-specified option string is empty. 3449 3450 3451File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation 3452 34536.9 Man Pages 3454============= 3455 3456In the GNU project, man pages are secondary. It is not necessary or 3457expected for every GNU program to have a man page, but some of them do. 3458It's your choice whether to include a man page in your program. 3459 3460 When you make this decision, consider that supporting a man page 3461requires continual effort each time the program is changed. The time 3462you spend on the man page is time taken away from more useful work. 3463 3464 For a simple program which changes little, updating the man page may 3465be a small job. Then there is little reason not to include a man page, 3466if you have one. 3467 3468 For a large program that changes a great deal, updating a man page 3469may be a substantial burden. If a user offers to donate a man page, 3470you may find this gift costly to accept. It may be better to refuse 3471the man page unless the same person agrees to take full responsibility 3472for maintaining it--so that you can wash your hands of it entirely. If 3473this volunteer later ceases to do the job, then don't feel obliged to 3474pick it up yourself; it may be better to withdraw the man page from the 3475distribution until someone else agrees to update it. 3476 3477 When a program changes only a little, you may feel that the 3478discrepancies are small enough that the man page remains useful without 3479updating. If so, put a prominent note near the beginning of the man 3480page explaining that you don't maintain it and that the Texinfo manual 3481is more authoritative. The note should say how to access the Texinfo 3482documentation. 3483 3484 Be sure that man pages include a copyright statement and free 3485license. The simple all-permissive license is appropriate for simple 3486man pages: 3487 3488 Copying and distribution of this file, with or without modification, 3489 are permitted in any medium without royalty provided the copyright 3490 notice and this notice are preserved. 3491 3492 For long man pages, with enough explanation and documentation that 3493they can be considered true manuals, use the GFDL (*note License for 3494Manuals::). 3495 3496 Finally, the GNU help2man program 3497(`http://www.gnu.org/software/help2man/') is one way to automate 3498generation of a man page, in this case from `--help' output. This is 3499sufficient in many cases. 3500 3501 3502File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation 3503 35046.10 Reading other Manuals 3505========================== 3506 3507There may be non-free books or documentation files that describe the 3508program you are documenting. 3509 3510 It is ok to use these documents for reference, just as the author of 3511a new algebra textbook can read other books on algebra. A large portion 3512of any non-fiction book consists of facts, in this case facts about how 3513a certain program works, and these facts are necessarily the same for 3514everyone who writes about the subject. But be careful not to copy your 3515outline structure, wording, tables or examples from preexisting non-free 3516documentation. Copying from free documentation may be ok; please check 3517with the FSF about the individual case. 3518 3519 3520File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top 3521 35227 The Release Process 3523********************* 3524 3525Making a release is more than just bundling up your source files in a 3526tar file and putting it up for FTP. You should set up your software so 3527that it can be configured to run on a variety of systems. Your Makefile 3528should conform to the GNU standards described below, and your directory 3529layout should also conform to the standards discussed below. Doing so 3530makes it easy to include your package into the larger framework of all 3531GNU software. 3532 3533* Menu: 3534 3535* Configuration:: How configuration of GNU packages should work. 3536* Makefile Conventions:: Makefile conventions. 3537* Releases:: Making releases 3538 3539 3540File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases 3541 35427.1 How Configuration Should Work 3543================================= 3544 3545Each GNU distribution should come with a shell script named 3546`configure'. This script is given arguments which describe the kind of 3547machine and system you want to compile the program for. 3548 3549 The `configure' script must record the configuration options so that 3550they affect compilation. 3551 3552 One way to do this is to make a link from a standard name such as 3553`config.h' to the proper configuration file for the chosen system. If 3554you use this technique, the distribution should _not_ contain a file 3555named `config.h'. This is so that people won't be able to build the 3556program without configuring it first. 3557 3558 Another thing that `configure' can do is to edit the Makefile. If 3559you do this, the distribution should _not_ contain a file named 3560`Makefile'. Instead, it should include a file `Makefile.in' which 3561contains the input used for editing. Once again, this is so that people 3562won't be able to build the program without configuring it first. 3563 3564 If `configure' does write the `Makefile', then `Makefile' should 3565have a target named `Makefile' which causes `configure' to be rerun, 3566setting up the same configuration that was set up last time. The files 3567that `configure' reads should be listed as dependencies of `Makefile'. 3568 3569 All the files which are output from the `configure' script should 3570have comments at the beginning explaining that they were generated 3571automatically using `configure'. This is so that users won't think of 3572trying to edit them by hand. 3573 3574 The `configure' script should write a file named `config.status' 3575which describes which configuration options were specified when the 3576program was last configured. This file should be a shell script which, 3577if run, will recreate the same configuration. 3578 3579 The `configure' script should accept an option of the form 3580`--srcdir=DIRNAME' to specify the directory where sources are found (if 3581it is not the current directory). This makes it possible to build the 3582program in a separate directory, so that the actual source directory is 3583not modified. 3584 3585 If the user does not specify `--srcdir', then `configure' should 3586check both `.' and `..' to see if it can find the sources. If it finds 3587the sources in one of these places, it should use them from there. 3588Otherwise, it should report that it cannot find the sources, and should 3589exit with nonzero status. 3590 3591 Usually the easy way to support `--srcdir' is by editing a 3592definition of `VPATH' into the Makefile. Some rules may need to refer 3593explicitly to the specified source directory. To make this possible, 3594`configure' can add to the Makefile a variable named `srcdir' whose 3595value is precisely the specified directory. 3596 3597 The `configure' script should also take an argument which specifies 3598the type of system to build the program for. This argument should look 3599like this: 3600 3601 CPU-COMPANY-SYSTEM 3602 3603 For example, an Athlon-based GNU/Linux system might be 3604`i686-pc-linux-gnu'. 3605 3606 The `configure' script needs to be able to decode all plausible 3607alternatives for how to describe a machine. Thus, 3608`athlon-pc-gnu/linux' would be a valid alias. There is a shell script 3609called `config.sub' 3610(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub) 3611that you can use as a subroutine to validate system types and 3612canonicalize aliases. 3613 3614 The `configure' script should also take the option 3615`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE 3616argument. For example, `configure --build=i686-pc-linux-gnu' is 3617equivalent to `configure i686-pc-linux-gnu'. When the build type is 3618not specified by an option or argument, the `configure' script should 3619normally guess it using the shell script `config.guess' 3620(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess). 3621 3622 Other options are permitted to specify in more detail the software 3623or hardware present on the machine, to include or exclude optional parts 3624of the package, or to adjust the name of some tools or arguments to 3625them: 3626 3627`--enable-FEATURE[=PARAMETER]' 3628 Configure the package to build and install an optional user-level 3629 facility called FEATURE. This allows users to choose which 3630 optional features to include. Giving an optional PARAMETER of 3631 `no' should omit FEATURE, if it is built by default. 3632 3633 No `--enable' option should *ever* cause one feature to replace 3634 another. No `--enable' option should ever substitute one useful 3635 behavior for another useful behavior. The only proper use for 3636 `--enable' is for questions of whether to build part of the program 3637 or exclude it. 3638 3639`--with-PACKAGE' 3640 The package PACKAGE will be installed, so configure this package 3641 to work with PACKAGE. 3642 3643 Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld', 3644 `gnu-libc', `gdb', `x', and `x-toolkit'. 3645 3646 Do not use a `--with' option to specify the file name to use to 3647 find certain files. That is outside the scope of what `--with' 3648 options are for. 3649 3650`VARIABLE=VALUE' 3651 Set the value of the variable VARIABLE to VALUE. This is used to 3652 override the default values of commands or arguments in the build 3653 process. For example, the user could issue `configure CFLAGS=-g 3654 CXXFLAGS=-g' to build with debugging information and without the 3655 default optimization. 3656 3657 Specifying variables as arguments to `configure', like this: 3658 ./configure CC=gcc 3659 is preferable to setting them in environment variables: 3660 CC=gcc ./configure 3661 as it helps to recreate the same configuration later with 3662 `config.status'. 3663 3664 All `configure' scripts should accept all of the "detail" options 3665and the variable settings, whether or not they make any difference to 3666the particular package at hand. In particular, they should accept any 3667option that starts with `--with-' or `--enable-'. This is so users 3668will be able to configure an entire GNU source tree at once with a 3669single set of options. 3670 3671 You will note that the categories `--with-' and `--enable-' are 3672narrow: they *do not* provide a place for any sort of option you might 3673think of. That is deliberate. We want to limit the possible 3674configuration options in GNU software. We do not want GNU programs to 3675have idiosyncratic configuration options. 3676 3677 Packages that perform part of the compilation process may support 3678cross-compilation. In such a case, the host and target machines for the 3679program may be different. 3680 3681 The `configure' script should normally treat the specified type of 3682system as both the host and the target, thus producing a program which 3683works for the same type of machine that it runs on. 3684 3685 To compile a program to run on a host type that differs from the 3686build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE 3687uses the same syntax as BUILDTYPE. The host type normally defaults to 3688the build type. 3689 3690 To configure a cross-compiler, cross-assembler, or what have you, you 3691should specify a target different from the host, using the configure 3692option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as 3693for the host type. So the command would look like this: 3694 3695 ./configure --host=HOSTTYPE --target=TARGETTYPE 3696 3697 The target type normally defaults to the host type. Programs for 3698which cross-operation is not meaningful need not accept the `--target' 3699option, because configuring an entire operating system for 3700cross-operation is not a meaningful operation. 3701 3702 Some programs have ways of configuring themselves automatically. If 3703your program is set up to do this, your `configure' script can simply 3704ignore most of its arguments. 3705 3706 3707File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases 3708 37097.2 Makefile Conventions 3710======================== 3711 3712This node describes conventions for writing the Makefiles for GNU 3713programs. Using Automake will help you write a Makefile that follows 3714these conventions. 3715 3716* Menu: 3717 3718* Makefile Basics:: General conventions for Makefiles. 3719* Utilities in Makefiles:: Utilities to be used in Makefiles. 3720* Command Variables:: Variables for specifying commands. 3721* DESTDIR:: Supporting staged installs. 3722* Directory Variables:: Variables for installation directories. 3723* Standard Targets:: Standard targets for users. 3724* Install Command Categories:: Three categories of commands in the `install' 3725 rule: normal, pre-install and post-install. 3726 3727 3728File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions 3729 37307.2.1 General Conventions for Makefiles 3731--------------------------------------- 3732 3733Every Makefile should contain this line: 3734 3735 SHELL = /bin/sh 3736 3737to avoid trouble on systems where the `SHELL' variable might be 3738inherited from the environment. (This is never a problem with GNU 3739`make'.) 3740 3741 Different `make' programs have incompatible suffix lists and 3742implicit rules, and this sometimes creates confusion or misbehavior. So 3743it is a good idea to set the suffix list explicitly using only the 3744suffixes you need in the particular Makefile, like this: 3745 3746 .SUFFIXES: 3747 .SUFFIXES: .c .o 3748 3749The first line clears out the suffix list, the second introduces all 3750suffixes which may be subject to implicit rules in this Makefile. 3751 3752 Don't assume that `.' is in the path for command execution. When 3753you need to run programs that are a part of your package during the 3754make, please make sure that it uses `./' if the program is built as 3755part of the make or `$(srcdir)/' if the file is an unchanging part of 3756the source code. Without one of these prefixes, the current search 3757path is used. 3758 3759 The distinction between `./' (the "build directory") and 3760`$(srcdir)/' (the "source directory") is important because users can 3761build in a separate directory using the `--srcdir' option to 3762`configure'. A rule of the form: 3763 3764 foo.1 : foo.man sedscript 3765 sed -e sedscript foo.man > foo.1 3766 3767will fail when the build directory is not the source directory, because 3768`foo.man' and `sedscript' are in the source directory. 3769 3770 When using GNU `make', relying on `VPATH' to find the source file 3771will work in the case where there is a single dependency file, since 3772the `make' automatic variable `$<' will represent the source file 3773wherever it is. (Many versions of `make' set `$<' only in implicit 3774rules.) A Makefile target like 3775 3776 foo.o : bar.c 3777 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o 3778 3779should instead be written as 3780 3781 foo.o : bar.c 3782 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@ 3783 3784in order to allow `VPATH' to work correctly. When the target has 3785multiple dependencies, using an explicit `$(srcdir)' is the easiest way 3786to make the rule work well. For example, the target above for `foo.1' 3787is best written as: 3788 3789 foo.1 : foo.man sedscript 3790 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@ 3791 3792 GNU distributions usually contain some files which are not source 3793files--for example, Info files, and the output from Autoconf, Automake, 3794Bison or Flex. Since these files normally appear in the source 3795directory, they should always appear in the source directory, not in the 3796build directory. So Makefile rules to update them should put the 3797updated files in the source directory. 3798 3799 However, if a file does not appear in the distribution, then the 3800Makefile should not put it in the source directory, because building a 3801program in ordinary circumstances should not modify the source directory 3802in any way. 3803 3804 Try to make the build and installation targets, at least (and all 3805their subtargets) work correctly with a parallel `make'. 3806 3807 3808File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions 3809 38107.2.2 Utilities in Makefiles 3811---------------------------- 3812 3813Write the Makefile commands (and any shell scripts, such as 3814`configure') to run in `sh', not in `csh'. Don't use any special 3815features of `ksh' or `bash'. 3816 3817 The `configure' script and the Makefile rules for building and 3818installation should not use any utilities directly except these: 3819 3820 cat cmp cp diff echo egrep expr false grep install-info 3821 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true 3822 3823 The compression program `gzip' can be used in the `dist' rule. 3824 3825 Stick to the generally supported options for these programs. For 3826example, don't use `mkdir -p', convenient as it may be, because most 3827systems don't support it. 3828 3829 It is a good idea to avoid creating symbolic links in makefiles, 3830since a few systems don't support them. 3831 3832 The Makefile rules for building and installation can also use 3833compilers and related programs, but should do so via `make' variables 3834so that the user can substitute alternatives. Here are some of the 3835programs we mean: 3836 3837 ar bison cc flex install ld ldconfig lex 3838 make makeinfo ranlib texi2dvi yacc 3839 3840 Use the following `make' variables to run those programs: 3841 3842 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) 3843 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) 3844 3845 When you use `ranlib' or `ldconfig', you should make sure nothing 3846bad happens if the system does not have the program in question. 3847Arrange to ignore an error from that command, and print a message before 3848the command to tell the user that failure of this command does not mean 3849a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.) 3850 3851 If you use symbolic links, you should implement a fallback for 3852systems that don't have symbolic links. 3853 3854 Additional utilities that can be used via Make variables are: 3855 3856 chgrp chmod chown mknod 3857 3858 It is ok to use other utilities in Makefile portions (or scripts) 3859intended only for particular systems where you know those utilities 3860exist. 3861 3862 3863File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions 3864 38657.2.3 Variables for Specifying Commands 3866--------------------------------------- 3867 3868Makefiles should provide variables for overriding certain commands, 3869options, and so on. 3870 3871 In particular, you should run most utility programs via variables. 3872Thus, if you use Bison, have a variable named `BISON' whose default 3873value is set with `BISON = bison', and refer to it with `$(BISON)' 3874whenever you need to use Bison. 3875 3876 File management utilities such as `ln', `rm', `mv', and so on, need 3877not be referred to through variables in this way, since users don't 3878need to replace them with other programs. 3879 3880 Each program-name variable should come with an options variable that 3881is used to supply options to the program. Append `FLAGS' to the 3882program-name variable name to get the options variable name--for 3883example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler, 3884`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule, 3885but we keep them because they are standard.) Use `CPPFLAGS' in any 3886compilation command that runs the preprocessor, and use `LDFLAGS' in 3887any compilation command that does linking as well as in any direct use 3888of `ld'. 3889 3890 If there are C compiler options that _must_ be used for proper 3891compilation of certain files, do not include them in `CFLAGS'. Users 3892expect to be able to specify `CFLAGS' freely themselves. Instead, 3893arrange to pass the necessary options to the C compiler independently 3894of `CFLAGS', by writing them explicitly in the compilation commands or 3895by defining an implicit rule, like this: 3896 3897 CFLAGS = -g 3898 ALL_CFLAGS = -I. $(CFLAGS) 3899 .c.o: 3900 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< 3901 3902 Do include the `-g' option in `CFLAGS', because that is not 3903_required_ for proper compilation. You can consider it a default that 3904is only recommended. If the package is set up so that it is compiled 3905with GCC by default, then you might as well include `-O' in the default 3906value of `CFLAGS' as well. 3907 3908 Put `CFLAGS' last in the compilation command, after other variables 3909containing compiler options, so the user can use `CFLAGS' to override 3910the others. 3911 3912 `CFLAGS' should be used in every invocation of the C compiler, both 3913those which do compilation and those which do linking. 3914 3915 Every Makefile should define the variable `INSTALL', which is the 3916basic command for installing a file into the system. 3917 3918 Every Makefile should also define the variables `INSTALL_PROGRAM' 3919and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be 3920`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m 3921644'.) Then it should use those variables as the commands for actual 3922installation, for executables and non-executables respectively. 3923Minimal use of these variables is as follows: 3924 3925 $(INSTALL_PROGRAM) foo $(bindir)/foo 3926 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a 3927 3928 However, it is preferable to support a `DESTDIR' prefix on the 3929target files, as explained in the next section. 3930 3931Always use a file name, not a directory name, as the second argument of 3932the installation commands. Use a separate command for each file to be 3933installed. 3934 3935 3936File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions 3937 39387.2.4 `DESTDIR': support for staged installs 3939-------------------------------------------- 3940 3941`DESTDIR' is a variable prepended to each installed target file, like 3942this: 3943 3944 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo 3945 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a 3946 3947 The `DESTDIR' variable is specified by the user on the `make' 3948command line. For example: 3949 3950 make DESTDIR=/tmp/stage install 3951 3952`DESTDIR' should be supported only in the `install*' and `uninstall*' 3953targets, as those are the only targets where it is useful. 3954 3955 If your installation step would normally install 3956`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an 3957installation invoked as in the example above would install 3958`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a' 3959instead. 3960 3961 Prepending the variable `DESTDIR' to each target in this way 3962provides for "staged installs", where the installed files are not 3963placed directly into their expected location but are instead copied 3964into a temporary location (`DESTDIR'). However, installed files 3965maintain their relative directory structure and any embedded file names 3966will not be modified. 3967 3968 You should not set the value of `DESTDIR' in your `Makefile' at all; 3969then the files are installed into their expected locations by default. 3970Also, specifying `DESTDIR' should not change the operation of the 3971software in any way, so its value should not be included in any file 3972contents. 3973 3974 `DESTDIR' support is commonly used in package creation. It is also 3975helpful to users who want to understand what a given package will 3976install where, and to allow users who don't normally have permissions 3977to install into protected areas to build and install before gaining 3978those permissions. Finally, it can be useful with tools such as 3979`stow', where code is installed in one place but made to appear to be 3980installed somewhere else using symbolic links or special mount 3981operations. So, we strongly recommend GNU packages support `DESTDIR', 3982though it is not an absolute requirement. 3983 3984 3985File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions 3986 39877.2.5 Variables for Installation Directories 3988-------------------------------------------- 3989 3990Installation directories should always be named by variables, so it is 3991easy to install in a nonstandard place. The standard names for these 3992variables and the values they should have in GNU packages are described 3993below. They are based on a standard file system layout; variants of it 3994are used in GNU/Linux and other modern operating systems. 3995 3996 Installers are expected to override these values when calling `make' 3997(e.g., `make prefix=/usr install' or `configure' (e.g., `configure 3998--prefix=/usr'). GNU packages should not try to guess which value 3999should be appropriate for these variables on the system they are being 4000installed onto: use the default settings specified here so that all GNU 4001packages behave identically, allowing the installer to achieve any 4002desired layout. 4003 4004 These first two variables set the root for the installation. All the 4005other installation directories should be subdirectories of one of these 4006two, and nothing should be directly installed into these two 4007directories. 4008 4009`prefix' 4010 A prefix used in constructing the default values of the variables 4011 listed below. The default value of `prefix' should be 4012 `/usr/local'. When building the complete GNU system, the prefix 4013 will be empty and `/usr' will be a symbolic link to `/'. (If you 4014 are using Autoconf, write it as `@prefix@'.) 4015 4016 Running `make install' with a different value of `prefix' from the 4017 one used to build the program should _not_ recompile the program. 4018 4019`exec_prefix' 4020 A prefix used in constructing the default values of some of the 4021 variables listed below. The default value of `exec_prefix' should 4022 be `$(prefix)'. (If you are using Autoconf, write it as 4023 `@exec_prefix@'.) 4024 4025 Generally, `$(exec_prefix)' is used for directories that contain 4026 machine-specific files (such as executables and subroutine 4027 libraries), while `$(prefix)' is used directly for other 4028 directories. 4029 4030 Running `make install' with a different value of `exec_prefix' 4031 from the one used to build the program should _not_ recompile the 4032 program. 4033 4034 Executable programs are installed in one of the following 4035directories. 4036 4037`bindir' 4038 The directory for installing executable programs that users can 4039 run. This should normally be `/usr/local/bin', but write it as 4040 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as 4041 `@bindir@'.) 4042 4043`sbindir' 4044 The directory for installing executable programs that can be run 4045 from the shell, but are only generally useful to system 4046 administrators. This should normally be `/usr/local/sbin', but 4047 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf, 4048 write it as `@sbindir@'.) 4049 4050`libexecdir' 4051 The directory for installing executable programs to be run by other 4052 programs rather than by users. This directory should normally be 4053 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'. 4054 (If you are using Autoconf, write it as `@libexecdir@'.) 4055 4056 The definition of `libexecdir' is the same for all packages, so 4057 you should install your data in a subdirectory thereof. Most 4058 packages install their data under `$(libexecdir)/PACKAGE-NAME/', 4059 possibly within additional subdirectories thereof, such as 4060 `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'. 4061 4062 Data files used by the program during its execution are divided into 4063categories in two ways. 4064 4065 * Some files are normally modified by programs; others are never 4066 normally modified (though users may edit some of these). 4067 4068 * Some files are architecture-independent and can be shared by all 4069 machines at a site; some are architecture-dependent and can be 4070 shared only by machines of the same kind and operating system; 4071 others may never be shared between two machines. 4072 4073 This makes for six different possibilities. However, we want to 4074discourage the use of architecture-dependent files, aside from object 4075files and libraries. It is much cleaner to make other data files 4076architecture-independent, and it is generally not hard. 4077 4078 Here are the variables Makefiles should use to specify directories 4079to put these various kinds of files in: 4080 4081`datarootdir' 4082 The root of the directory tree for read-only 4083 architecture-independent data files. This should normally be 4084 `/usr/local/share', but write it as `$(prefix)/share'. (If you 4085 are using Autoconf, write it as `@datarootdir@'.) `datadir''s 4086 default value is based on this variable; so are `infodir', 4087 `mandir', and others. 4088 4089`datadir' 4090 The directory for installing idiosyncratic read-only 4091 architecture-independent data files for this program. This is 4092 usually the same place as `datarootdir', but we use the two 4093 separate variables so that you can move these program-specific 4094 files without altering the location for Info files, man pages, etc. 4095 4096 This should normally be `/usr/local/share', but write it as 4097 `$(datarootdir)'. (If you are using Autoconf, write it as 4098 `@datadir@'.) 4099 4100 The definition of `datadir' is the same for all packages, so you 4101 should install your data in a subdirectory thereof. Most packages 4102 install their data under `$(datadir)/PACKAGE-NAME/'. 4103 4104`sysconfdir' 4105 The directory for installing read-only data files that pertain to a 4106 single machine-that is to say, files for configuring a host. 4107 Mailer and network configuration files, `/etc/passwd', and so 4108 forth belong here. All the files in this directory should be 4109 ordinary ASCII text files. This directory should normally be 4110 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are 4111 using Autoconf, write it as `@sysconfdir@'.) 4112 4113 Do not install executables here in this directory (they probably 4114 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install 4115 files that are modified in the normal course of their use (programs 4116 whose purpose is to change the configuration of the system 4117 excluded). Those probably belong in `$(localstatedir)'. 4118 4119`sharedstatedir' 4120 The directory for installing architecture-independent data files 4121 which the programs modify while they run. This should normally be 4122 `/usr/local/com', but write it as `$(prefix)/com'. (If you are 4123 using Autoconf, write it as `@sharedstatedir@'.) 4124 4125`localstatedir' 4126 The directory for installing data files which the programs modify 4127 while they run, and that pertain to one specific machine. Users 4128 should never need to modify files in this directory to configure 4129 the package's operation; put such configuration information in 4130 separate files that go in `$(datadir)' or `$(sysconfdir)'. 4131 `$(localstatedir)' should normally be `/usr/local/var', but write 4132 it as `$(prefix)/var'. (If you are using Autoconf, write it as 4133 `@localstatedir@'.) 4134 4135 These variables specify the directory for installing certain specific 4136types of files, if your program has them. Every GNU package should 4137have Info files, so every program needs `infodir', but not all need 4138`libdir' or `lispdir'. 4139 4140`includedir' 4141 The directory for installing header files to be included by user 4142 programs with the C `#include' preprocessor directive. This 4143 should normally be `/usr/local/include', but write it as 4144 `$(prefix)/include'. (If you are using Autoconf, write it as 4145 `@includedir@'.) 4146 4147 Most compilers other than GCC do not look for header files in 4148 directory `/usr/local/include'. So installing the header files 4149 this way is only useful with GCC. Sometimes this is not a problem 4150 because some libraries are only really intended to work with GCC. 4151 But some libraries are intended to work with other compilers. 4152 They should install their header files in two places, one 4153 specified by `includedir' and one specified by `oldincludedir'. 4154 4155`oldincludedir' 4156 The directory for installing `#include' header files for use with 4157 compilers other than GCC. This should normally be `/usr/include'. 4158 (If you are using Autoconf, you can write it as `@oldincludedir@'.) 4159 4160 The Makefile commands should check whether the value of 4161 `oldincludedir' is empty. If it is, they should not try to use 4162 it; they should cancel the second installation of the header files. 4163 4164 A package should not replace an existing header in this directory 4165 unless the header came from the same package. Thus, if your Foo 4166 package provides a header file `foo.h', then it should install the 4167 header file in the `oldincludedir' directory if either (1) there 4168 is no `foo.h' there or (2) the `foo.h' that exists came from the 4169 Foo package. 4170 4171 To tell whether `foo.h' came from the Foo package, put a magic 4172 string in the file--part of a comment--and `grep' for that string. 4173 4174`docdir' 4175 The directory for installing documentation files (other than Info) 4176 for this package. By default, it should be 4177 `/usr/local/share/doc/YOURPKG', but it should be written as 4178 `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write 4179 it as `@docdir@'.) The YOURPKG subdirectory, which may include a 4180 version number, prevents collisions among files with common names, 4181 such as `README'. 4182 4183`infodir' 4184 The directory for installing the Info files for this package. By 4185 default, it should be `/usr/local/share/info', but it should be 4186 written as `$(datarootdir)/info'. (If you are using Autoconf, 4187 write it as `@infodir@'.) `infodir' is separate from `docdir' for 4188 compatibility with existing practice. 4189 4190`htmldir' 4191`dvidir' 4192`pdfdir' 4193`psdir' 4194 Directories for installing documentation files in the particular 4195 format. They should all be set to `$(docdir)' by default. (If 4196 you are using Autoconf, write them as `@htmldir@', `@dvidir@', 4197 etc.) Packages which supply several translations of their 4198 documentation should install them in `$(htmldir)/'LL, 4199 `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as 4200 `en' or `pt_BR'. 4201 4202`libdir' 4203 The directory for object files and libraries of object code. Do 4204 not install executables here, they probably ought to go in 4205 `$(libexecdir)' instead. The value of `libdir' should normally be 4206 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you 4207 are using Autoconf, write it as `@libdir@'.) 4208 4209`lispdir' 4210 The directory for installing any Emacs Lisp files in this package. 4211 By default, it should be `/usr/local/share/emacs/site-lisp', but 4212 it should be written as `$(datarootdir)/emacs/site-lisp'. 4213 4214 If you are using Autoconf, write the default as `@lispdir@'. In 4215 order to make `@lispdir@' work, you need the following lines in 4216 your `configure.in' file: 4217 4218 lispdir='${datarootdir}/emacs/site-lisp' 4219 AC_SUBST(lispdir) 4220 4221`localedir' 4222 The directory for installing locale-specific message catalogs for 4223 this package. By default, it should be `/usr/local/share/locale', 4224 but it should be written as `$(datarootdir)/locale'. (If you are 4225 using Autoconf, write it as `@localedir@'.) This directory 4226 usually has a subdirectory per locale. 4227 4228 Unix-style man pages are installed in one of the following: 4229 4230`mandir' 4231 The top-level directory for installing the man pages (if any) for 4232 this package. It will normally be `/usr/local/share/man', but you 4233 should write it as `$(datarootdir)/man'. (If you are using 4234 Autoconf, write it as `@mandir@'.) 4235 4236`man1dir' 4237 The directory for installing section 1 man pages. Write it as 4238 `$(mandir)/man1'. 4239 4240`man2dir' 4241 The directory for installing section 2 man pages. Write it as 4242 `$(mandir)/man2' 4243 4244`...' 4245 *Don't make the primary documentation for any GNU software be a 4246 man page. Write a manual in Texinfo instead. Man pages are just 4247 for the sake of people running GNU software on Unix, which is a 4248 secondary application only.* 4249 4250`manext' 4251 The file name extension for the installed man page. This should 4252 contain a period followed by the appropriate digit; it should 4253 normally be `.1'. 4254 4255`man1ext' 4256 The file name extension for installed section 1 man pages. 4257 4258`man2ext' 4259 The file name extension for installed section 2 man pages. 4260 4261`...' 4262 Use these names instead of `manext' if the package needs to 4263 install man pages in more than one section of the manual. 4264 4265 And finally, you should set the following variable: 4266 4267`srcdir' 4268 The directory for the sources being compiled. The value of this 4269 variable is normally inserted by the `configure' shell script. 4270 (If you are using Autoconf, use `srcdir = @srcdir@'.) 4271 4272 For example: 4273 4274 # Common prefix for installation directories. 4275 # NOTE: This directory must exist when you start the install. 4276 prefix = /usr/local 4277 datarootdir = $(prefix)/share 4278 datadir = $(datarootdir) 4279 exec_prefix = $(prefix) 4280 # Where to put the executable for the command `gcc'. 4281 bindir = $(exec_prefix)/bin 4282 # Where to put the directories used by the compiler. 4283 libexecdir = $(exec_prefix)/libexec 4284 # Where to put the Info files. 4285 infodir = $(datarootdir)/info 4286 4287 If your program installs a large number of files into one of the 4288standard user-specified directories, it might be useful to group them 4289into a subdirectory particular to that program. If you do this, you 4290should write the `install' rule to create these subdirectories. 4291 4292 Do not expect the user to include the subdirectory name in the value 4293of any of the variables listed above. The idea of having a uniform set 4294of variable names for installation directories is to enable the user to 4295specify the exact same values for several different GNU packages. In 4296order for this to be useful, all the packages must be designed so that 4297they will work sensibly when the user does so. 4298 4299 At times, not all of these variables may be implemented in the 4300current release of Autoconf and/or Automake; but as of Autoconf 2.60, we 4301believe all of them are. When any are missing, the descriptions here 4302serve as specifications for what Autoconf will implement. As a 4303programmer, you can either use a development version of Autoconf or 4304avoid using these variables until a stable release is made which 4305supports them. 4306 4307 4308File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions 4309 43107.2.6 Standard Targets for Users 4311-------------------------------- 4312 4313All GNU programs should have the following targets in their Makefiles: 4314 4315`all' 4316 Compile the entire program. This should be the default target. 4317 This target need not rebuild any documentation files; Info files 4318 should normally be included in the distribution, and DVI (and other 4319 documentation format) files should be made only when explicitly 4320 asked for. 4321 4322 By default, the Make rules should compile and link with `-g', so 4323 that executable programs have debugging symbols. Users who don't 4324 mind being helpless can strip the executables later if they wish. 4325 4326`install' 4327 Compile the program and copy the executables, libraries, and so on 4328 to the file names where they should reside for actual use. If 4329 there is a simple test to verify that a program is properly 4330 installed, this target should run that test. 4331 4332 Do not strip executables when installing them. Devil-may-care 4333 users can use the `install-strip' target to do that. 4334 4335 If possible, write the `install' target rule so that it does not 4336 modify anything in the directory where the program was built, 4337 provided `make all' has just been done. This is convenient for 4338 building the program under one user name and installing it under 4339 another. 4340 4341 The commands should create all the directories in which files are 4342 to be installed, if they don't already exist. This includes the 4343 directories specified as the values of the variables `prefix' and 4344 `exec_prefix', as well as all subdirectories that are needed. One 4345 way to do this is by means of an `installdirs' target as described 4346 below. 4347 4348 Use `-' before any command for installing a man page, so that 4349 `make' will ignore any errors. This is in case there are systems 4350 that don't have the Unix man page documentation system installed. 4351 4352 The way to install Info files is to copy them into `$(infodir)' 4353 with `$(INSTALL_DATA)' (*note Command Variables::), and then run 4354 the `install-info' program if it is present. `install-info' is a 4355 program that edits the Info `dir' file to add or update the menu 4356 entry for the given Info file; it is part of the Texinfo package. 4357 Here is a sample rule to install an Info file: 4358 4359 $(DESTDIR)$(infodir)/foo.info: foo.info 4360 $(POST_INSTALL) 4361 # There may be a newer info file in . than in srcdir. 4362 -if test -f foo.info; then d=.; \ 4363 else d=$(srcdir); fi; \ 4364 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \ 4365 # Run install-info only if it exists. 4366 # Use `if' instead of just prepending `-' to the 4367 # line so we notice real errors from install-info. 4368 # We use `$(SHELL) -c' because some shells do not 4369 # fail gracefully when there is an unknown command. 4370 if $(SHELL) -c 'install-info --version' \ 4371 >/dev/null 2>&1; then \ 4372 install-info --dir-file=$(DESTDIR)$(infodir)/dir \ 4373 $(DESTDIR)$(infodir)/foo.info; \ 4374 else true; fi 4375 4376 When writing the `install' target, you must classify all the 4377 commands into three categories: normal ones, "pre-installation" 4378 commands and "post-installation" commands. *Note Install Command 4379 Categories::. 4380 4381`install-html' 4382`install-dvi' 4383`install-pdf' 4384`install-ps' 4385 These targets install documentation in formats other than Info; 4386 they're intended to be called explicitly by the person installing 4387 the package, if that format is desired. GNU prefers Info files, 4388 so these must be installed by the `install' target. 4389 4390 When you have many documentation files to install, we recommend 4391 that you avoid collisions and clutter by arranging for these 4392 targets to install in subdirectories of the appropriate 4393 installation directory, such as `htmldir'. As one example, if 4394 your package has multiple manuals, and you wish to install HTML 4395 documentation with many files (such as the "split" mode output by 4396 `makeinfo --html'), you'll certainly want to use subdirectories, 4397 or two nodes with the same name in different manuals will 4398 overwrite each other. 4399 4400 Please make these `install-FORMAT' targets invoke the commands for 4401 the FORMAT target, for example, by making FORMAT a dependency. 4402 4403`uninstall' 4404 Delete all the installed files--the copies that the `install' and 4405 `install-*' targets create. 4406 4407 This rule should not modify the directories where compilation is 4408 done, only the directories where files are installed. 4409 4410 The uninstallation commands are divided into three categories, 4411 just like the installation commands. *Note Install Command 4412 Categories::. 4413 4414`install-strip' 4415 Like `install', but strip the executable files while installing 4416 them. In simple cases, this target can use the `install' target in 4417 a simple way: 4418 4419 install-strip: 4420 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ 4421 install 4422 4423 But if the package installs scripts as well as real executables, 4424 the `install-strip' target can't just refer to the `install' 4425 target; it has to strip the executables but not the scripts. 4426 4427 `install-strip' should not strip the executables in the build 4428 directory which are being copied for installation. It should only 4429 strip the copies that are installed. 4430 4431 Normally we do not recommend stripping an executable unless you 4432 are sure the program has no bugs. However, it can be reasonable 4433 to install a stripped executable for actual execution while saving 4434 the unstripped executable elsewhere in case there is a bug. 4435 4436`clean' 4437 Delete all files in the current directory that are normally 4438 created by building the program. Also delete files in other 4439 directories if they are created by this makefile. However, don't 4440 delete the files that record the configuration. Also preserve 4441 files that could be made by building, but normally aren't because 4442 the distribution comes with them. There is no need to delete 4443 parent directories that were created with `mkdir -p', since they 4444 could have existed anyway. 4445 4446 Delete `.dvi' files here if they are not part of the distribution. 4447 4448`distclean' 4449 Delete all files in the current directory (or created by this 4450 makefile) that are created by configuring or building the program. 4451 If you have unpacked the source and built the program without 4452 creating any other files, `make distclean' should leave only the 4453 files that were in the distribution. However, there is no need to 4454 delete parent directories that were created with `mkdir -p', since 4455 they could have existed anyway. 4456 4457`mostlyclean' 4458 Like `clean', but may refrain from deleting a few files that people 4459 normally don't want to recompile. For example, the `mostlyclean' 4460 target for GCC does not delete `libgcc.a', because recompiling it 4461 is rarely necessary and takes a lot of time. 4462 4463`maintainer-clean' 4464 Delete almost everything that can be reconstructed with this 4465 Makefile. This typically includes everything deleted by 4466 `distclean', plus more: C source files produced by Bison, tags 4467 tables, Info files, and so on. 4468 4469 The reason we say "almost everything" is that running the command 4470 `make maintainer-clean' should not delete `configure' even if 4471 `configure' can be remade using a rule in the Makefile. More 4472 generally, `make maintainer-clean' should not delete anything that 4473 needs to exist in order to run `configure' and then begin to build 4474 the program. Also, there is no need to delete parent directories 4475 that were created with `mkdir -p', since they could have existed 4476 anyway. These are the only exceptions; `maintainer-clean' should 4477 delete everything else that can be rebuilt. 4478 4479 The `maintainer-clean' target is intended to be used by a 4480 maintainer of the package, not by ordinary users. You may need 4481 special tools to reconstruct some of the files that `make 4482 maintainer-clean' deletes. Since these files are normally 4483 included in the distribution, we don't take care to make them easy 4484 to reconstruct. If you find you need to unpack the full 4485 distribution again, don't blame us. 4486 4487 To help make users aware of this, the commands for the special 4488 `maintainer-clean' target should start with these two: 4489 4490 @echo 'This command is intended for maintainers to use; it' 4491 @echo 'deletes files that may need special tools to rebuild.' 4492 4493`TAGS' 4494 Update a tags table for this program. 4495 4496`info' 4497 Generate any Info files needed. The best way to write the rules 4498 is as follows: 4499 4500 info: foo.info 4501 4502 foo.info: foo.texi chap1.texi chap2.texi 4503 $(MAKEINFO) $(srcdir)/foo.texi 4504 4505 You must define the variable `MAKEINFO' in the Makefile. It should 4506 run the `makeinfo' program, which is part of the Texinfo 4507 distribution. 4508 4509 Normally a GNU distribution comes with Info files, and that means 4510 the Info files are present in the source directory. Therefore, 4511 the Make rule for an info file should update it in the source 4512 directory. When users build the package, ordinarily Make will not 4513 update the Info files because they will already be up to date. 4514 4515`dvi' 4516`html' 4517`pdf' 4518`ps' 4519 Generate documentation files in the given format. These targets 4520 should always exist, but any or all can be a no-op if the given 4521 output format cannot be generated. These targets should not be 4522 dependencies of the `all' target; the user must manually invoke 4523 them. 4524 4525 Here's an example rule for generating DVI files from Texinfo: 4526 4527 dvi: foo.dvi 4528 4529 foo.dvi: foo.texi chap1.texi chap2.texi 4530 $(TEXI2DVI) $(srcdir)/foo.texi 4531 4532 You must define the variable `TEXI2DVI' in the Makefile. It should 4533 run the program `texi2dvi', which is part of the Texinfo 4534 distribution.(1) Alternatively, write just the dependencies, and 4535 allow GNU `make' to provide the command. 4536 4537 Here's another example, this one for generating HTML from Texinfo: 4538 4539 html: foo.html 4540 4541 foo.html: foo.texi chap1.texi chap2.texi 4542 $(TEXI2HTML) $(srcdir)/foo.texi 4543 4544 Again, you would define the variable `TEXI2HTML' in the Makefile; 4545 for example, it might run `makeinfo --no-split --html' (`makeinfo' 4546 is part of the Texinfo distribution). 4547 4548`dist' 4549 Create a distribution tar file for this program. The tar file 4550 should be set up so that the file names in the tar file start with 4551 a subdirectory name which is the name of the package it is a 4552 distribution for. This name can include the version number. 4553 4554 For example, the distribution tar file of GCC version 1.40 unpacks 4555 into a subdirectory named `gcc-1.40'. 4556 4557 The easiest way to do this is to create a subdirectory 4558 appropriately named, use `ln' or `cp' to install the proper files 4559 in it, and then `tar' that subdirectory. 4560 4561 Compress the tar file with `gzip'. For example, the actual 4562 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'. 4563 4564 The `dist' target should explicitly depend on all non-source files 4565 that are in the distribution, to make sure they are up to date in 4566 the distribution. *Note Making Releases: Releases. 4567 4568`check' 4569 Perform self-tests (if any). The user must build the program 4570 before running the tests, but need not install the program; you 4571 should write the self-tests so that they work when the program is 4572 built but not installed. 4573 4574 The following targets are suggested as conventional names, for 4575programs in which they are useful. 4576 4577`installcheck' 4578 Perform installation tests (if any). The user must build and 4579 install the program before running the tests. You should not 4580 assume that `$(bindir)' is in the search path. 4581 4582`installdirs' 4583 It's useful to add a target named `installdirs' to create the 4584 directories where files are installed, and their parent 4585 directories. There is a script called `mkinstalldirs' which is 4586 convenient for this; you can find it in the Texinfo package. You 4587 can use a rule like this: 4588 4589 # Make sure all installation directories (e.g. $(bindir)) 4590 # actually exist by making them if necessary. 4591 installdirs: mkinstalldirs 4592 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ 4593 $(libdir) $(infodir) \ 4594 $(mandir) 4595 4596 or, if you wish to support `DESTDIR', 4597 4598 # Make sure all installation directories (e.g. $(bindir)) 4599 # actually exist by making them if necessary. 4600 installdirs: mkinstalldirs 4601 $(srcdir)/mkinstalldirs \ 4602 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ 4603 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ 4604 $(DESTDIR)$(mandir) 4605 4606 This rule should not modify the directories where compilation is 4607 done. It should do nothing but create installation directories. 4608 4609 ---------- Footnotes ---------- 4610 4611 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is 4612not distributed with Texinfo. 4613 4614 4615File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions 4616 46177.2.7 Install Command Categories 4618-------------------------------- 4619 4620When writing the `install' target, you must classify all the commands 4621into three categories: normal ones, "pre-installation" commands and 4622"post-installation" commands. 4623 4624 Normal commands move files into their proper places, and set their 4625modes. They may not alter any files except the ones that come entirely 4626from the package they belong to. 4627 4628 Pre-installation and post-installation commands may alter other 4629files; in particular, they can edit global configuration files or data 4630bases. 4631 4632 Pre-installation commands are typically executed before the normal 4633commands, and post-installation commands are typically run after the 4634normal commands. 4635 4636 The most common use for a post-installation command is to run 4637`install-info'. This cannot be done with a normal command, since it 4638alters a file (the Info directory) which does not come entirely and 4639solely from the package being installed. It is a post-installation 4640command because it needs to be done after the normal command which 4641installs the package's Info files. 4642 4643 Most programs don't need any pre-installation commands, but we have 4644the feature just in case it is needed. 4645 4646 To classify the commands in the `install' rule into these three 4647categories, insert "category lines" among them. A category line 4648specifies the category for the commands that follow. 4649 4650 A category line consists of a tab and a reference to a special Make 4651variable, plus an optional comment at the end. There are three 4652variables you can use, one for each category; the variable name 4653specifies the category. Category lines are no-ops in ordinary execution 4654because these three Make variables are normally undefined (and you 4655_should not_ define them in the makefile). 4656 4657 Here are the three possible category lines, each with a comment that 4658explains what it means: 4659 4660 $(PRE_INSTALL) # Pre-install commands follow. 4661 $(POST_INSTALL) # Post-install commands follow. 4662 $(NORMAL_INSTALL) # Normal commands follow. 4663 4664 If you don't use a category line at the beginning of the `install' 4665rule, all the commands are classified as normal until the first category 4666line. If you don't use any category lines, all the commands are 4667classified as normal. 4668 4669 These are the category lines for `uninstall': 4670 4671 $(PRE_UNINSTALL) # Pre-uninstall commands follow. 4672 $(POST_UNINSTALL) # Post-uninstall commands follow. 4673 $(NORMAL_UNINSTALL) # Normal commands follow. 4674 4675 Typically, a pre-uninstall command would be used for deleting entries 4676from the Info directory. 4677 4678 If the `install' or `uninstall' target has any dependencies which 4679act as subroutines of installation, then you should start _each_ 4680dependency's commands with a category line, and start the main target's 4681commands with a category line also. This way, you can ensure that each 4682command is placed in the right category regardless of which of the 4683dependencies actually run. 4684 4685 Pre-installation and post-installation commands should not run any 4686programs except for these: 4687 4688 [ basename bash cat chgrp chmod chown cmp cp dd diff echo 4689 egrep expand expr false fgrep find getopt grep gunzip gzip 4690 hostname install install-info kill ldconfig ln ls md5sum 4691 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee 4692 test touch true uname xargs yes 4693 4694 The reason for distinguishing the commands in this way is for the 4695sake of making binary packages. Typically a binary package contains 4696all the executables and other files that need to be installed, and has 4697its own method of installing them--so it does not need to run the normal 4698installation commands. But installing the binary package does need to 4699execute the pre-installation and post-installation commands. 4700 4701 Programs to build binary packages work by extracting the 4702pre-installation and post-installation commands. Here is one way of 4703extracting the pre-installation commands (the `-s' option to `make' is 4704needed to silence messages about entering subdirectories): 4705 4706 make -s -n install -o all \ 4707 PRE_INSTALL=pre-install \ 4708 POST_INSTALL=post-install \ 4709 NORMAL_INSTALL=normal-install \ 4710 | gawk -f pre-install.awk 4711 4712where the file `pre-install.awk' could contain this: 4713 4714 $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0} 4715 on {print $0} 4716 $0 ~ /^pre-install[ \t]*$/ {on = 1} 4717 4718 4719File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases 4720 47217.3 Making Releases 4722=================== 4723 4724You should identify each release with a pair of version numbers, a 4725major version and a minor. We have no objection to using more than two 4726numbers, but it is very unlikely that you really need them. 4727 4728 Package the distribution of `Foo version 69.96' up in a gzipped tar 4729file with the name `foo-69.96.tar.gz'. It should unpack into a 4730subdirectory named `foo-69.96'. 4731 4732 Building and installing the program should never modify any of the 4733files contained in the distribution. This means that all the files 4734that form part of the program in any way must be classified into "source 4735files" and "non-source files". Source files are written by humans and 4736never changed automatically; non-source files are produced from source 4737files by programs under the control of the Makefile. 4738 4739 The distribution should contain a file named `README' which gives 4740the name of the package, and a general description of what it does. It 4741is also good to explain the purpose of each of the first-level 4742subdirectories in the package, if there are any. The `README' file 4743should either state the version number of the package, or refer to where 4744in the package it can be found. 4745 4746 The `README' file should refer to the file `INSTALL', which should 4747contain an explanation of the installation procedure. 4748 4749 The `README' file should also refer to the file which contains the 4750copying conditions. The GNU GPL, if used, should be in a file called 4751`COPYING'. If the GNU LGPL is used, it should be in a file called 4752`COPYING.LIB'. 4753 4754 Naturally, all the source files must be in the distribution. It is 4755okay to include non-source files in the distribution, provided they are 4756up-to-date and machine-independent, so that building the distribution 4757normally will never modify them. We commonly include non-source files 4758produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid 4759unnecessary dependencies between our distributions, so that users can 4760install whichever packages they want to install. 4761 4762 Non-source files that might actually be modified by building and 4763installing the program should *never* be included in the distribution. 4764So if you do distribute non-source files, always make sure they are up 4765to date when you make a new distribution. 4766 4767 Make sure that the directory into which the distribution unpacks (as 4768well as any subdirectories) are all world-writable (octal mode 777). 4769This is so that old versions of `tar' which preserve the ownership and 4770permissions of the files from the tar archive will be able to extract 4771all the files even if the user is unprivileged. 4772 4773 Make sure that all the files in the distribution are world-readable. 4774 4775 Don't include any symbolic links in the distribution itself. If the 4776tar file contains symbolic links, then people cannot even unpack it on 4777systems that don't support symbolic links. Also, don't use multiple 4778names for one file in different directories, because certain file 4779systems cannot handle this and that prevents unpacking the distribution. 4780 4781 Try to make sure that all the file names will be unique on MS-DOS. A 4782name on MS-DOS consists of up to 8 characters, optionally followed by a 4783period and up to three characters. MS-DOS will truncate extra 4784characters both before and after the period. Thus, `foobarhacker.c' 4785and `foobarhacker.o' are not ambiguous; they are truncated to 4786`foobarha.c' and `foobarha.o', which are distinct. 4787 4788 Include in your distribution a copy of the `texinfo.tex' you used to 4789test print any `*.texinfo' or `*.texi' files. 4790 4791 Likewise, if your program uses small GNU software packages like 4792regex, getopt, obstack, or termcap, include them in the distribution 4793file. Leaving them out would make the distribution file a little 4794smaller at the expense of possible inconvenience to a user who doesn't 4795know what other files to get. 4796 4797 4798File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top 4799 48008 References to Non-Free Software and Documentation 4801*************************************************** 4802 4803A GNU program should not recommend use of any non-free program. We 4804can't stop some people from writing proprietary programs, or stop other 4805people from using them, but we can and should refuse to advertise them 4806to new potential customers. Proprietary software is a social and 4807ethical problem, and the point of GNU is to solve that problem. 4808 4809 The GNU definition of free software is found on the GNU web site at 4810`http://www.gnu.org/philosophy/free-sw.html', and the definition of 4811free documentation is found at 4812`http://www.gnu.org/philosophy/free-doc.html'. A list of important 4813licenses and whether they qualify as free is in 4814`http://www.gnu.org/licenses/license-list.html'. The terms "free" and 4815"non-free", used in this document, refer to that definition. If it is 4816not clear whether a license qualifies as free under this definition, 4817please ask the GNU Project by writing to <licensing@gnu.org>. We will 4818answer, and if the license is an important one, we will add it to the 4819list. 4820 4821 When a non-free program or system is well known, you can mention it 4822in passing--that is harmless, since users who might want to use it 4823probably already know about it. For instance, it is fine to explain 4824how to build your package on top of some widely used non-free operating 4825system, or how to use it together with some widely used non-free 4826program. 4827 4828 However, you should give only the necessary information to help those 4829who already use the non-free program to use your program with it--don't 4830give, or refer to, any further information about the proprietary 4831program, and don't imply that the proprietary program enhances your 4832program, or that its existence is in any way a good thing. The goal 4833should be that people already using the proprietary program will get 4834the advice they need about how to use your free program with it, while 4835people who don't already use the proprietary program will not see 4836anything to lead them to take an interest in it. 4837 4838 If a non-free program or system is obscure in your program's domain, 4839your program should not mention or support it at all, since doing so 4840would tend to popularize the non-free program more than it popularizes 4841your program. (You cannot hope to find many additional users among the 4842users of Foobar if the users of Foobar are few.) 4843 4844 Sometimes a program is free software in itself but depends on a 4845non-free platform in order to run. For instance, many Java programs 4846depend on the parts of Sun's Java implementation which are not yet free 4847software, and won't run on the GNU Java Compiler (which does not yet 4848have all the features) or won't run with the GNU Java libraries. We 4849hope this particular problem will be gone in a few months, when Sun 4850makes the standard Java libraries free software, but of course the 4851general principle remains: you should not recommend programs that 4852depend on non-free software to run. 4853 4854 Some free programs encourage the use of non-free software. A typical 4855example is `mplayer'. It is free software in itself, and the free code 4856can handle some kinds of files. However, `mplayer' recommends use of 4857non-free codecs for other kinds of files, and users that install 4858`mplayer' are very likely to install those codecs along with it. To 4859recommend `mplayer' is, in effect, to recommend the non-free codecs. 4860We must not do that, so we cannot recommend `mplayer' either. 4861 4862 In general, you should also not recommend programs that themselves 4863strongly recommend the use of non-free software. 4864 4865 A GNU package should not refer the user to any non-free documentation 4866for free software. Free documentation that can be included in free 4867operating systems is essential for completing the GNU system, or any 4868free operating system, so it is a major focus of the GNU Project; to 4869recommend use of documentation that we are not allowed to use in GNU 4870would weaken the impetus for the community to produce documentation 4871that we can include. So GNU packages should never recommend non-free 4872documentation. 4873 4874 By contrast, it is ok to refer to journal articles and textbooks in 4875the comments of a program for explanation of how it functions, even 4876though they be non-free. This is because we don't include such things 4877in the GNU system even if we are allowed to--they are outside the scope 4878of an operating system project. 4879 4880 Referring to a web site that describes or recommends a non-free 4881program is in effect promoting that software, so please do not make 4882links (or mention by name) web sites that contain such material. This 4883policy is relevant particularly for the web pages for a GNU package. 4884 4885 Following links from nearly any web site can lead to non-free 4886software; this is an inescapable aspect of the nature of the web, and 4887in itself is no objection to linking to a site. As long as the site 4888does not itself recommend a non-free program, there is no need be 4889concerned about the sites it links to for other reasons. 4890 4891 Thus, for example, you should not make a link to AT&T's web site, 4892because that recommends AT&T's non-free software packages; you should 4893not make a link to a site that links to AT&T's site saying it is a 4894place to get a non-free program; but if a site you want to link to 4895refers to AT&T's web site in some other context (such as long-distance 4896telephone service), that is not a problem. 4897 4898 4899File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top 4900 4901Appendix A GNU Free Documentation License 4902***************************************** 4903 4904 Version 1.2, November 2002 4905 4906 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 4907 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA 4908 4909 Everyone is permitted to copy and distribute verbatim copies 4910 of this license document, but changing it is not allowed. 4911 4912 0. PREAMBLE 4913 4914 The purpose of this License is to make a manual, textbook, or other 4915 functional and useful document "free" in the sense of freedom: to 4916 assure everyone the effective freedom to copy and redistribute it, 4917 with or without modifying it, either commercially or 4918 noncommercially. Secondarily, this License preserves for the 4919 author and publisher a way to get credit for their work, while not 4920 being considered responsible for modifications made by others. 4921 4922 This License is a kind of "copyleft", which means that derivative 4923 works of the document must themselves be free in the same sense. 4924 It complements the GNU General Public License, which is a copyleft 4925 license designed for free software. 4926 4927 We have designed this License in order to use it for manuals for 4928 free software, because free software needs free documentation: a 4929 free program should come with manuals providing the same freedoms 4930 that the software does. But this License is not limited to 4931 software manuals; it can be used for any textual work, regardless 4932 of subject matter or whether it is published as a printed book. 4933 We recommend this License principally for works whose purpose is 4934 instruction or reference. 4935 4936 1. APPLICABILITY AND DEFINITIONS 4937 4938 This License applies to any manual or other work, in any medium, 4939 that contains a notice placed by the copyright holder saying it 4940 can be distributed under the terms of this License. Such a notice 4941 grants a world-wide, royalty-free license, unlimited in duration, 4942 to use that work under the conditions stated herein. The 4943 "Document", below, refers to any such manual or work. Any member 4944 of the public is a licensee, and is addressed as "you". You 4945 accept the license if you copy, modify or distribute the work in a 4946 way requiring permission under copyright law. 4947 4948 A "Modified Version" of the Document means any work containing the 4949 Document or a portion of it, either copied verbatim, or with 4950 modifications and/or translated into another language. 4951 4952 A "Secondary Section" is a named appendix or a front-matter section 4953 of the Document that deals exclusively with the relationship of the 4954 publishers or authors of the Document to the Document's overall 4955 subject (or to related matters) and contains nothing that could 4956 fall directly within that overall subject. (Thus, if the Document 4957 is in part a textbook of mathematics, a Secondary Section may not 4958 explain any mathematics.) The relationship could be a matter of 4959 historical connection with the subject or with related matters, or 4960 of legal, commercial, philosophical, ethical or political position 4961 regarding them. 4962 4963 The "Invariant Sections" are certain Secondary Sections whose 4964 titles are designated, as being those of Invariant Sections, in 4965 the notice that says that the Document is released under this 4966 License. If a section does not fit the above definition of 4967 Secondary then it is not allowed to be designated as Invariant. 4968 The Document may contain zero Invariant Sections. If the Document 4969 does not identify any Invariant Sections then there are none. 4970 4971 The "Cover Texts" are certain short passages of text that are 4972 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 4973 that says that the Document is released under this License. A 4974 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 4975 be at most 25 words. 4976 4977 A "Transparent" copy of the Document means a machine-readable copy, 4978 represented in a format whose specification is available to the 4979 general public, that is suitable for revising the document 4980 straightforwardly with generic text editors or (for images 4981 composed of pixels) generic paint programs or (for drawings) some 4982 widely available drawing editor, and that is suitable for input to 4983 text formatters or for automatic translation to a variety of 4984 formats suitable for input to text formatters. A copy made in an 4985 otherwise Transparent file format whose markup, or absence of 4986 markup, has been arranged to thwart or discourage subsequent 4987 modification by readers is not Transparent. An image format is 4988 not Transparent if used for any substantial amount of text. A 4989 copy that is not "Transparent" is called "Opaque". 4990 4991 Examples of suitable formats for Transparent copies include plain 4992 ASCII without markup, Texinfo input format, LaTeX input format, 4993 SGML or XML using a publicly available DTD, and 4994 standard-conforming simple HTML, PostScript or PDF designed for 4995 human modification. Examples of transparent image formats include 4996 PNG, XCF and JPG. Opaque formats include proprietary formats that 4997 can be read and edited only by proprietary word processors, SGML or 4998 XML for which the DTD and/or processing tools are not generally 4999 available, and the machine-generated HTML, PostScript or PDF 5000 produced by some word processors for output purposes only. 5001 5002 The "Title Page" means, for a printed book, the title page itself, 5003 plus such following pages as are needed to hold, legibly, the 5004 material this License requires to appear in the title page. For 5005 works in formats which do not have any title page as such, "Title 5006 Page" means the text near the most prominent appearance of the 5007 work's title, preceding the beginning of the body of the text. 5008 5009 A section "Entitled XYZ" means a named subunit of the Document 5010 whose title either is precisely XYZ or contains XYZ in parentheses 5011 following text that translates XYZ in another language. (Here XYZ 5012 stands for a specific section name mentioned below, such as 5013 "Acknowledgements", "Dedications", "Endorsements", or "History".) 5014 To "Preserve the Title" of such a section when you modify the 5015 Document means that it remains a section "Entitled XYZ" according 5016 to this definition. 5017 5018 The Document may include Warranty Disclaimers next to the notice 5019 which states that this License applies to the Document. These 5020 Warranty Disclaimers are considered to be included by reference in 5021 this License, but only as regards disclaiming warranties: any other 5022 implication that these Warranty Disclaimers may have is void and 5023 has no effect on the meaning of this License. 5024 5025 2. VERBATIM COPYING 5026 5027 You may copy and distribute the Document in any medium, either 5028 commercially or noncommercially, provided that this License, the 5029 copyright notices, and the license notice saying this License 5030 applies to the Document are reproduced in all copies, and that you 5031 add no other conditions whatsoever to those of this License. You 5032 may not use technical measures to obstruct or control the reading 5033 or further copying of the copies you make or distribute. However, 5034 you may accept compensation in exchange for copies. If you 5035 distribute a large enough number of copies you must also follow 5036 the conditions in section 3. 5037 5038 You may also lend copies, under the same conditions stated above, 5039 and you may publicly display copies. 5040 5041 3. COPYING IN QUANTITY 5042 5043 If you publish printed copies (or copies in media that commonly 5044 have printed covers) of the Document, numbering more than 100, and 5045 the Document's license notice requires Cover Texts, you must 5046 enclose the copies in covers that carry, clearly and legibly, all 5047 these Cover Texts: Front-Cover Texts on the front cover, and 5048 Back-Cover Texts on the back cover. Both covers must also clearly 5049 and legibly identify you as the publisher of these copies. The 5050 front cover must present the full title with all words of the 5051 title equally prominent and visible. You may add other material 5052 on the covers in addition. Copying with changes limited to the 5053 covers, as long as they preserve the title of the Document and 5054 satisfy these conditions, can be treated as verbatim copying in 5055 other respects. 5056 5057 If the required texts for either cover are too voluminous to fit 5058 legibly, you should put the first ones listed (as many as fit 5059 reasonably) on the actual cover, and continue the rest onto 5060 adjacent pages. 5061 5062 If you publish or distribute Opaque copies of the Document 5063 numbering more than 100, you must either include a 5064 machine-readable Transparent copy along with each Opaque copy, or 5065 state in or with each Opaque copy a computer-network location from 5066 which the general network-using public has access to download 5067 using public-standard network protocols a complete Transparent 5068 copy of the Document, free of added material. If you use the 5069 latter option, you must take reasonably prudent steps, when you 5070 begin distribution of Opaque copies in quantity, to ensure that 5071 this Transparent copy will remain thus accessible at the stated 5072 location until at least one year after the last time you 5073 distribute an Opaque copy (directly or through your agents or 5074 retailers) of that edition to the public. 5075 5076 It is requested, but not required, that you contact the authors of 5077 the Document well before redistributing any large number of 5078 copies, to give them a chance to provide you with an updated 5079 version of the Document. 5080 5081 4. MODIFICATIONS 5082 5083 You may copy and distribute a Modified Version of the Document 5084 under the conditions of sections 2 and 3 above, provided that you 5085 release the Modified Version under precisely this License, with 5086 the Modified Version filling the role of the Document, thus 5087 licensing distribution and modification of the Modified Version to 5088 whoever possesses a copy of it. In addition, you must do these 5089 things in the Modified Version: 5090 5091 A. Use in the Title Page (and on the covers, if any) a title 5092 distinct from that of the Document, and from those of 5093 previous versions (which should, if there were any, be listed 5094 in the History section of the Document). You may use the 5095 same title as a previous version if the original publisher of 5096 that version gives permission. 5097 5098 B. List on the Title Page, as authors, one or more persons or 5099 entities responsible for authorship of the modifications in 5100 the Modified Version, together with at least five of the 5101 principal authors of the Document (all of its principal 5102 authors, if it has fewer than five), unless they release you 5103 from this requirement. 5104 5105 C. State on the Title page the name of the publisher of the 5106 Modified Version, as the publisher. 5107 5108 D. Preserve all the copyright notices of the Document. 5109 5110 E. Add an appropriate copyright notice for your modifications 5111 adjacent to the other copyright notices. 5112 5113 F. Include, immediately after the copyright notices, a license 5114 notice giving the public permission to use the Modified 5115 Version under the terms of this License, in the form shown in 5116 the Addendum below. 5117 5118 G. Preserve in that license notice the full lists of Invariant 5119 Sections and required Cover Texts given in the Document's 5120 license notice. 5121 5122 H. Include an unaltered copy of this License. 5123 5124 I. Preserve the section Entitled "History", Preserve its Title, 5125 and add to it an item stating at least the title, year, new 5126 authors, and publisher of the Modified Version as given on 5127 the Title Page. If there is no section Entitled "History" in 5128 the Document, create one stating the title, year, authors, 5129 and publisher of the Document as given on its Title Page, 5130 then add an item describing the Modified Version as stated in 5131 the previous sentence. 5132 5133 J. Preserve the network location, if any, given in the Document 5134 for public access to a Transparent copy of the Document, and 5135 likewise the network locations given in the Document for 5136 previous versions it was based on. These may be placed in 5137 the "History" section. You may omit a network location for a 5138 work that was published at least four years before the 5139 Document itself, or if the original publisher of the version 5140 it refers to gives permission. 5141 5142 K. For any section Entitled "Acknowledgements" or "Dedications", 5143 Preserve the Title of the section, and preserve in the 5144 section all the substance and tone of each of the contributor 5145 acknowledgements and/or dedications given therein. 5146 5147 L. Preserve all the Invariant Sections of the Document, 5148 unaltered in their text and in their titles. Section numbers 5149 or the equivalent are not considered part of the section 5150 titles. 5151 5152 M. Delete any section Entitled "Endorsements". Such a section 5153 may not be included in the Modified Version. 5154 5155 N. Do not retitle any existing section to be Entitled 5156 "Endorsements" or to conflict in title with any Invariant 5157 Section. 5158 5159 O. Preserve any Warranty Disclaimers. 5160 5161 If the Modified Version includes new front-matter sections or 5162 appendices that qualify as Secondary Sections and contain no 5163 material copied from the Document, you may at your option 5164 designate some or all of these sections as invariant. To do this, 5165 add their titles to the list of Invariant Sections in the Modified 5166 Version's license notice. These titles must be distinct from any 5167 other section titles. 5168 5169 You may add a section Entitled "Endorsements", provided it contains 5170 nothing but endorsements of your Modified Version by various 5171 parties--for example, statements of peer review or that the text 5172 has been approved by an organization as the authoritative 5173 definition of a standard. 5174 5175 You may add a passage of up to five words as a Front-Cover Text, 5176 and a passage of up to 25 words as a Back-Cover Text, to the end 5177 of the list of Cover Texts in the Modified Version. Only one 5178 passage of Front-Cover Text and one of Back-Cover Text may be 5179 added by (or through arrangements made by) any one entity. If the 5180 Document already includes a cover text for the same cover, 5181 previously added by you or by arrangement made by the same entity 5182 you are acting on behalf of, you may not add another; but you may 5183 replace the old one, on explicit permission from the previous 5184 publisher that added the old one. 5185 5186 The author(s) and publisher(s) of the Document do not by this 5187 License give permission to use their names for publicity for or to 5188 assert or imply endorsement of any Modified Version. 5189 5190 5. COMBINING DOCUMENTS 5191 5192 You may combine the Document with other documents released under 5193 this License, under the terms defined in section 4 above for 5194 modified versions, provided that you include in the combination 5195 all of the Invariant Sections of all of the original documents, 5196 unmodified, and list them all as Invariant Sections of your 5197 combined work in its license notice, and that you preserve all 5198 their Warranty Disclaimers. 5199 5200 The combined work need only contain one copy of this License, and 5201 multiple identical Invariant Sections may be replaced with a single 5202 copy. If there are multiple Invariant Sections with the same name 5203 but different contents, make the title of each such section unique 5204 by adding at the end of it, in parentheses, the name of the 5205 original author or publisher of that section if known, or else a 5206 unique number. Make the same adjustment to the section titles in 5207 the list of Invariant Sections in the license notice of the 5208 combined work. 5209 5210 In the combination, you must combine any sections Entitled 5211 "History" in the various original documents, forming one section 5212 Entitled "History"; likewise combine any sections Entitled 5213 "Acknowledgements", and any sections Entitled "Dedications". You 5214 must delete all sections Entitled "Endorsements." 5215 5216 6. COLLECTIONS OF DOCUMENTS 5217 5218 You may make a collection consisting of the Document and other 5219 documents released under this License, and replace the individual 5220 copies of this License in the various documents with a single copy 5221 that is included in the collection, provided that you follow the 5222 rules of this License for verbatim copying of each of the 5223 documents in all other respects. 5224 5225 You may extract a single document from such a collection, and 5226 distribute it individually under this License, provided you insert 5227 a copy of this License into the extracted document, and follow 5228 this License in all other respects regarding verbatim copying of 5229 that document. 5230 5231 7. AGGREGATION WITH INDEPENDENT WORKS 5232 5233 A compilation of the Document or its derivatives with other 5234 separate and independent documents or works, in or on a volume of 5235 a storage or distribution medium, is called an "aggregate" if the 5236 copyright resulting from the compilation is not used to limit the 5237 legal rights of the compilation's users beyond what the individual 5238 works permit. When the Document is included in an aggregate, this 5239 License does not apply to the other works in the aggregate which 5240 are not themselves derivative works of the Document. 5241 5242 If the Cover Text requirement of section 3 is applicable to these 5243 copies of the Document, then if the Document is less than one half 5244 of the entire aggregate, the Document's Cover Texts may be placed 5245 on covers that bracket the Document within the aggregate, or the 5246 electronic equivalent of covers if the Document is in electronic 5247 form. Otherwise they must appear on printed covers that bracket 5248 the whole aggregate. 5249 5250 8. TRANSLATION 5251 5252 Translation is considered a kind of modification, so you may 5253 distribute translations of the Document under the terms of section 5254 4. Replacing Invariant Sections with translations requires special 5255 permission from their copyright holders, but you may include 5256 translations of some or all Invariant Sections in addition to the 5257 original versions of these Invariant Sections. You may include a 5258 translation of this License, and all the license notices in the 5259 Document, and any Warranty Disclaimers, provided that you also 5260 include the original English version of this License and the 5261 original versions of those notices and disclaimers. In case of a 5262 disagreement between the translation and the original version of 5263 this License or a notice or disclaimer, the original version will 5264 prevail. 5265 5266 If a section in the Document is Entitled "Acknowledgements", 5267 "Dedications", or "History", the requirement (section 4) to 5268 Preserve its Title (section 1) will typically require changing the 5269 actual title. 5270 5271 9. TERMINATION 5272 5273 You may not copy, modify, sublicense, or distribute the Document 5274 except as expressly provided for under this License. Any other 5275 attempt to copy, modify, sublicense or distribute the Document is 5276 void, and will automatically terminate your rights under this 5277 License. However, parties who have received copies, or rights, 5278 from you under this License will not have their licenses 5279 terminated so long as such parties remain in full compliance. 5280 5281 10. FUTURE REVISIONS OF THIS LICENSE 5282 5283 The Free Software Foundation may publish new, revised versions of 5284 the GNU Free Documentation License from time to time. Such new 5285 versions will be similar in spirit to the present version, but may 5286 differ in detail to address new problems or concerns. See 5287 `http://www.gnu.org/copyleft/'. 5288 5289 Each version of the License is given a distinguishing version 5290 number. If the Document specifies that a particular numbered 5291 version of this License "or any later version" applies to it, you 5292 have the option of following the terms and conditions either of 5293 that specified version or of any later version that has been 5294 published (not as a draft) by the Free Software Foundation. If 5295 the Document does not specify a version number of this License, 5296 you may choose any version ever published (not as a draft) by the 5297 Free Software Foundation. 5298 5299ADDENDUM: How to use this License for your documents 5300==================================================== 5301 5302To use this License in a document you have written, include a copy of 5303the License in the document and put the following copyright and license 5304notices just after the title page: 5305 5306 Copyright (C) YEAR YOUR NAME. 5307 Permission is granted to copy, distribute and/or modify this document 5308 under the terms of the GNU Free Documentation License, Version 1.2 5309 or any later version published by the Free Software Foundation; 5310 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 5311 Texts. A copy of the license is included in the section entitled ``GNU 5312 Free Documentation License''. 5313 5314 If you have Invariant Sections, Front-Cover Texts and Back-Cover 5315Texts, replace the "with...Texts." line with this: 5316 5317 with the Invariant Sections being LIST THEIR TITLES, with 5318 the Front-Cover Texts being LIST, and with the Back-Cover Texts 5319 being LIST. 5320 5321 If you have Invariant Sections without Cover Texts, or some other 5322combination of the three, merge those two alternatives to suit the 5323situation. 5324 5325 If your document contains nontrivial examples of program code, we 5326recommend releasing these examples in parallel under your choice of 5327free software license, such as the GNU General Public License, to 5328permit their use in free software. 5329 5330 5331File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top 5332 5333Index 5334***** 5335 5336[index] 5337* Menu: 5338 5339* #endif, commenting: Comments. (line 60) 5340* --help output: --help. (line 6) 5341* --version output: --version. (line 6) 5342* -Wall compiler option: Syntactic Conventions. 5343 (line 10) 5344* accepting contributions: Contributions. (line 6) 5345* address for bug reports: --help. (line 11) 5346* ANSI C standard: Standard C. (line 6) 5347* arbitrary limits on data: Semantics. (line 6) 5348* ASCII characters: Character Set. (line 6) 5349* autoconf: System Portability. (line 23) 5350* avoiding proprietary code: Reading Non-Free Code. 5351 (line 6) 5352* behavior, dependent on program's name: User Interfaces. (line 6) 5353* binary packages: Install Command Categories. 5354 (line 80) 5355* bindir: Directory Variables. (line 54) 5356* braces, in C source: Formatting. (line 6) 5357* bug reports: --help. (line 11) 5358* canonical name of a program: --version. (line 12) 5359* casting pointers to integers: CPU Portability. (line 90) 5360* CGI programs, standard options for: Command-Line Interfaces. 5361 (line 31) 5362* change logs: Change Logs. (line 6) 5363* change logs, conditional changes: Conditional Changes. (line 6) 5364* change logs, style: Style of Change Logs. 5365 (line 6) 5366* character set: Character Set. (line 6) 5367* command-line arguments, decoding: Semantics. (line 46) 5368* command-line interface: Command-Line Interfaces. 5369 (line 6) 5370* commenting: Comments. (line 6) 5371* compatibility with C and POSIX standards: Compatibility. (line 6) 5372* compiler warnings: Syntactic Conventions. 5373 (line 10) 5374* conditional changes, and change logs: Conditional Changes. (line 6) 5375* conditionals, comments for: Comments. (line 60) 5376* configure: Configuration. (line 6) 5377* control-L: Formatting. (line 118) 5378* conventions for makefiles: Makefile Conventions. 5379 (line 6) 5380* corba: Graphical Interfaces. 5381 (line 16) 5382* credits for manuals: Manual Credits. (line 6) 5383* data types, and portability: CPU Portability. (line 6) 5384* declaration for system functions: System Functions. (line 21) 5385* DESTDIR: DESTDIR. (line 6) 5386* documentation: Documentation. (line 6) 5387* doschk: Names. (line 38) 5388* downloading this manual: Preface. (line 17) 5389* encodings: Character Set. (line 6) 5390* error messages: Semantics. (line 19) 5391* error messages, formatting: Errors. (line 6) 5392* exec_prefix: Directory Variables. (line 36) 5393* expressions, splitting: Formatting. (line 81) 5394* FDL, GNU Free Documentation License: GNU Free Documentation License. 5395 (line 6) 5396* file usage: File Usage. (line 6) 5397* file-name limitations: Names. (line 38) 5398* formatting error messages: Errors. (line 6) 5399* formatting source code: Formatting. (line 6) 5400* formfeed: Formatting. (line 118) 5401* function argument, declaring: Syntactic Conventions. 5402 (line 6) 5403* function prototypes: Standard C. (line 17) 5404* getopt: Command-Line Interfaces. 5405 (line 6) 5406* gettext: Internationalization. 5407 (line 6) 5408* gnome: Graphical Interfaces. 5409 (line 16) 5410* graphical user interface: Graphical Interfaces. 5411 (line 6) 5412* grave accent: Quote Characters. (line 6) 5413* gtk+: Graphical Interfaces. 5414 (line 6) 5415* GUILE: Source Language. (line 38) 5416* implicit int: Syntactic Conventions. 5417 (line 6) 5418* impossible conditions: Semantics. (line 70) 5419* installations, staged: DESTDIR. (line 6) 5420* internationalization: Internationalization. 5421 (line 6) 5422* left quote: Quote Characters. (line 6) 5423* legal aspects: Legal Issues. (line 6) 5424* legal papers: Contributions. (line 6) 5425* libexecdir: Directory Variables. (line 67) 5426* libraries: Libraries. (line 6) 5427* library functions, and portability: System Functions. (line 6) 5428* license for manuals: License for Manuals. (line 6) 5429* lint: Syntactic Conventions. 5430 (line 109) 5431* locale-specific quote characters: Quote Characters. (line 6) 5432* long option names: Option Table. (line 6) 5433* long-named options: Command-Line Interfaces. 5434 (line 12) 5435* makefile, conventions for: Makefile Conventions. 5436 (line 6) 5437* malloc return value: Semantics. (line 25) 5438* man pages: Man Pages. (line 6) 5439* manual structure: Manual Structure Details. 5440 (line 6) 5441* memory allocation failure: Semantics. (line 25) 5442* memory usage: Memory Usage. (line 6) 5443* message text, and internationalization: Internationalization. 5444 (line 29) 5445* mmap: Mmap. (line 6) 5446* multiple variables in a line: Syntactic Conventions. 5447 (line 35) 5448* names of variables, functions, and files: Names. (line 6) 5449* NEWS file: NEWS File. (line 6) 5450* non-ASCII characters: Character Set. (line 6) 5451* non-POSIX systems, and portability: System Portability. (line 32) 5452* non-standard extensions: Using Extensions. (line 6) 5453* NUL characters: Semantics. (line 11) 5454* open brace: Formatting. (line 6) 5455* optional features, configure-time: Configuration. (line 83) 5456* options for compatibility: Compatibility. (line 14) 5457* options, standard command-line: Command-Line Interfaces. 5458 (line 31) 5459* output device and program's behavior: User Interfaces. (line 13) 5460* packaging: Releases. (line 6) 5461* PATH_INFO, specifying standard options as: Command-Line Interfaces. 5462 (line 31) 5463* portability, and data types: CPU Portability. (line 6) 5464* portability, and library functions: System Functions. (line 6) 5465* portability, between system types: System Portability. (line 6) 5466* POSIX compatibility: Compatibility. (line 6) 5467* POSIXLY_CORRECT, environment variable: Compatibility. (line 21) 5468* post-installation commands: Install Command Categories. 5469 (line 6) 5470* pre-installation commands: Install Command Categories. 5471 (line 6) 5472* prefix: Directory Variables. (line 26) 5473* program configuration: Configuration. (line 6) 5474* program design: Design Advice. (line 6) 5475* program name and its behavior: User Interfaces. (line 6) 5476* program's canonical name: --version. (line 12) 5477* programming languages: Source Language. (line 6) 5478* proprietary programs: Reading Non-Free Code. 5479 (line 6) 5480* quote characters: Quote Characters. (line 6) 5481* README file: Releases. (line 21) 5482* references to non-free material: References. (line 6) 5483* releasing: Managing Releases. (line 6) 5484* sbindir: Directory Variables. (line 60) 5485* signal handling: Semantics. (line 59) 5486* spaces before open-paren: Formatting. (line 75) 5487* staged installs: DESTDIR. (line 6) 5488* standard command-line options: Command-Line Interfaces. 5489 (line 31) 5490* standards for makefiles: Makefile Conventions. 5491 (line 6) 5492* string library functions: System Functions. (line 55) 5493* syntactic conventions: Syntactic Conventions. 5494 (line 6) 5495* table of long options: Option Table. (line 6) 5496* temporary files: Semantics. (line 84) 5497* temporary variables: Syntactic Conventions. 5498 (line 23) 5499* texinfo.tex, in a distribution: Releases. (line 70) 5500* TMPDIR environment variable: Semantics. (line 84) 5501* trademarks: Trademarks. (line 6) 5502* where to obtain standards.texi: Preface. (line 17) 5503 5504 5505 5506Tag Table: 5507Node: Top804 5508Node: Preface2060 5509Node: Legal Issues4175 5510Node: Reading Non-Free Code4645 5511Node: Contributions6375 5512Node: Trademarks8613 5513Node: Design Advice10248 5514Node: Source Language10840 5515Node: Compatibility12852 5516Node: Using Extensions14480 5517Node: Standard C16056 5518Node: Conditional Compilation18459 5519Node: Program Behavior19857 5520Node: Non-GNU Standards20913 5521Node: Semantics23194 5522Node: Libraries27913 5523Node: Errors29158 5524Node: User Interfaces31651 5525Node: Graphical Interfaces33256 5526Node: Command-Line Interfaces34292 5527Node: --version36324 5528Node: --help42217 5529Node: Option Table42771 5530Node: Memory Usage57712 5531Node: File Usage58743 5532Node: Writing C59493 5533Node: Formatting60465 5534Node: Comments64754 5535Node: Syntactic Conventions68306 5536Node: Names71768 5537Node: System Portability73980 5538Node: CPU Portability76870 5539Node: System Functions80782 5540Node: Internationalization85979 5541Node: Character Set89973 5542Node: Quote Characters90786 5543Node: Mmap92306 5544Node: Documentation93014 5545Node: GNU Manuals94120 5546Node: Doc Strings and Manuals99858 5547Node: Manual Structure Details101411 5548Node: License for Manuals102829 5549Node: Manual Credits103803 5550Node: Printed Manuals104196 5551Node: NEWS File104882 5552Node: Change Logs105560 5553Node: Change Log Concepts106314 5554Node: Style of Change Logs108403 5555Node: Simple Changes110903 5556Node: Conditional Changes112345 5557Node: Indicating the Part Changed113767 5558Node: Man Pages114294 5559Node: Reading other Manuals116606 5560Node: Managing Releases117397 5561Node: Configuration118178 5562Node: Makefile Conventions125898 5563Node: Makefile Basics126780 5564Node: Utilities in Makefiles129954 5565Node: Command Variables132099 5566Node: DESTDIR135321 5567Node: Directory Variables137470 5568Node: Standard Targets151963 5569Ref: Standard Targets-Footnote-1165478 5570Node: Install Command Categories165578 5571Node: Releases170111 5572Node: References174038 5573Node: GNU Free Documentation License179533 5574Node: Index201965 5575 5576End Tag Table 5577