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