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