1 This is standards.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION GNU organization
6 * Standards: (standards). GNU coding standards.
9 The GNU coding standards, last updated April 12, 2010.
11 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
12 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
19 Texts. A copy of the license is included in the section entitled "GNU
20 Free Documentation License".
23 File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
28 The GNU coding standards, last updated April 12, 2010.
30 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
31 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.3 or
36 any later version published by the Free Software Foundation; with no
37 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
38 Texts. A copy of the license is included in the section entitled "GNU
39 Free Documentation License".
43 * Preface:: About the GNU Coding Standards.
44 * Legal Issues:: Keeping free software free.
45 * Design Advice:: General program design.
46 * Program Behavior:: Program behavior for all programs
47 * Writing C:: Making the best use of C.
48 * Documentation:: Documenting programs.
49 * Managing Releases:: The release process.
50 * References:: Mentioning non-free software or documentation.
51 * GNU Free Documentation License:: Copying and sharing this manual.
55 File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
57 1 About the GNU Coding Standards
58 ********************************
60 The GNU Coding Standards were written by Richard Stallman and other GNU
61 Project volunteers. Their purpose is to make the GNU system clean,
62 consistent, and easy to install. This document can also be read as a
63 guide to writing portable, robust and reliable programs. It focuses on
64 programs written in C, but many of the rules and principles are useful
65 even if you write in another programming language. The rules often
66 state reasons for writing in a certain way.
68 If you did not obtain this file directly from the GNU project and
69 recently, please check for a newer version. You can get the GNU Coding
70 Standards from the GNU web server in many different formats, including
71 the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
72 `http://www.gnu.org/prep/standards/'.
74 If you are maintaining an official GNU package, in addition to this
75 document, please read and follow the GNU maintainer information (*note
76 Contents: (maintain)Top.).
78 If you want to receive diffs for every change to these GNU documents,
79 join the mailing list `gnustandards-commit@gnu.org', via the web
81 `http://lists.gnu.org/mailman/listinfo/gnustandards-commit'. Archives
82 are also available there.
84 Please send corrections or suggestions for this document to
85 <bug-standards@gnu.org>. If you make a suggestion, please include a
86 suggested new wording for it, to help us consider the suggestion
87 efficiently. We prefer a context diff to the Texinfo source, but if
88 that's difficult for you, you can make a context diff for some other
89 version of this document, or propose it in any way that makes it clear.
90 The source repository for this document can be found at
91 `http://savannah.gnu.org/projects/gnustandards'.
93 These standards cover the minimum of what is important when writing a
94 GNU package. Likely, the need for additional standards will come up.
95 Sometimes, you might suggest that such standards be added to this
96 document. If you think your standards would be generally useful, please
99 You should also set standards for your package on many questions not
100 addressed or not firmly specified here. The most important point is to
101 be self-consistent--try to stick to the conventions you pick, and try
102 to document them as much as possible. That way, your program will be
103 more maintainable by others.
105 The GNU Hello program serves as an example of how to follow the GNU
106 coding standards for a trivial program.
107 `http://www.gnu.org/software/hello/hello.html'.
109 This release of the GNU Coding Standards was last updated April 12,
113 File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
115 2 Keeping Free Software Free
116 ****************************
118 This chapter discusses how you can make sure that GNU software avoids
119 legal difficulties, and other related issues.
123 * Reading Non-Free Code:: Referring to proprietary programs.
124 * Contributions:: Accepting contributions.
125 * Trademarks:: How we deal with trademark issues.
128 File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
130 2.1 Referring to Proprietary Programs
131 =====================================
133 Don't in any circumstances refer to Unix source code for or during your
134 work on GNU! (Or to any other proprietary programs.)
136 If you have a vague recollection of the internals of a Unix program,
137 this does not absolutely mean you can't write an imitation of it, but
138 do try to organize the imitation internally along different lines,
139 because this is likely to make the details of the Unix version
140 irrelevant and dissimilar to your results.
142 For example, Unix utilities were generally optimized to minimize
143 memory use; if you go for speed instead, your program will be very
144 different. You could keep the entire input file in memory and scan it
145 there instead of using stdio. Use a smarter algorithm discovered more
146 recently than the Unix program. Eliminate use of temporary files. Do
147 it in one pass instead of two (we did this in the assembler).
149 Or, on the contrary, emphasize simplicity instead of speed. For some
150 applications, the speed of today's computers makes simpler algorithms
153 Or go for generality. For example, Unix programs often have static
154 tables or fixed-size strings, which make for arbitrary limits; use
155 dynamic allocation instead. Make sure your program handles NULs and
156 other funny characters in the input files. Add a programming language
157 for extensibility and write part of the program in that language.
159 Or turn some parts of the program into independently usable
160 libraries. Or use a simple garbage collector instead of tracking
161 precisely when to free memory, or use a new GNU facility such as
165 File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
167 2.2 Accepting Contributions
168 ===========================
170 If the program you are working on is copyrighted by the Free Software
171 Foundation, then when someone else sends you a piece of code to add to
172 the program, we need legal papers to use it--just as we asked you to
173 sign papers initially. _Each_ person who makes a nontrivial
174 contribution to a program must sign some sort of legal papers in order
175 for us to have clear title to the program; the main author alone is not
178 So, before adding in any contributions from other people, please tell
179 us, so we can arrange to get the papers. Then wait until we tell you
180 that we have received the signed papers, before you actually use the
183 This applies both before you release the program and afterward. If
184 you receive diffs to fix a bug, and they make significant changes, we
185 need legal papers for that change.
187 This also applies to comments and documentation files. For copyright
188 law, comments and code are just text. Copyright applies to all kinds of
189 text, so we need legal papers for all kinds.
191 We know it is frustrating to ask for legal papers; it's frustrating
192 for us as well. But if you don't wait, you are going out on a limb--for
193 example, what if the contributor's employer won't sign a disclaimer?
194 You might have to take that code out again!
196 You don't need papers for changes of a few lines here or there, since
197 they are not significant for copyright purposes. Also, you don't need
198 papers if all you get from the suggestion is some ideas, not actual code
199 which you use. For example, if someone sent you one implementation, but
200 you write a different implementation of the same idea, you don't need to
203 The very worst thing is if you forget to tell us about the other
204 contributor. We could be very embarrassed in court some day as a
207 We have more detailed advice for maintainers of programs; if you have
208 reached the stage of actually maintaining a program for GNU (whether
209 released or not), please ask us for a copy. It is also available
210 online for your perusal: `http://www.gnu.org/prep/maintain/'.
213 File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
218 Please do not include any trademark acknowledgements in GNU software
219 packages or documentation.
221 Trademark acknowledgements are the statements that such-and-such is a
222 trademark of so-and-so. The GNU Project has no objection to the basic
223 idea of trademarks, but these acknowledgements feel like kowtowing, and
224 there is no legal requirement for them, so we don't use them.
226 What is legally required, as regards other people's trademarks, is to
227 avoid using them in ways which a reader might reasonably understand as
228 naming or labeling our own programs or activities. For example, since
229 "Objective C" is (or at least was) a trademark, we made sure to say
230 that we provide a "compiler for the Objective C language" rather than
231 an "Objective C compiler". The latter would have been meant as a
232 shorter way of saying the former, but it does not explicitly state the
233 relationship, so it could be misinterpreted as using "Objective C" as a
234 label for the compiler rather than for the language.
236 Please don't use "win" as an abbreviation for Microsoft Windows in
237 GNU software or documentation. In hacker terminology, calling
238 something a "win" is a form of praise. If you wish to praise Microsoft
239 Windows when speaking on your own, by all means do so, but not in GNU
240 software. Usually we write the name "Windows" in full, but when
241 brevity is very important (as in file names and sometimes symbol
242 names), we abbreviate it to "w". For instance, the files and functions
243 in Emacs that deal with Windows start with `w32'.
246 File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
248 3 General Program Design
249 ************************
251 This chapter discusses some of the issues you should take into account
252 when designing your program.
256 * Source Language:: Which languages to use.
257 * Compatibility:: Compatibility with other implementations.
258 * Using Extensions:: Using non-standard features.
259 * Standard C:: Using standard C features.
260 * Conditional Compilation:: Compiling code only if a conditional is true.
263 File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
265 3.1 Which Languages to Use
266 ==========================
268 When you want to use a language that gets compiled and runs at high
269 speed, the best language to use is C. Using another language is like
270 using a non-standard feature: it will cause trouble for users. Even if
271 GCC supports the other language, users may find it inconvenient to have
272 to install the compiler for that other language in order to build your
273 program. For example, if you write your program in C++, people will
274 have to install the GNU C++ compiler in order to compile your program.
276 C has one other advantage over C++ and other compiled languages: more
277 people know C, so more people will find it easy to read and modify the
278 program if it is written in C.
280 So in general it is much better to use C, rather than the comparable
283 But there are two exceptions to that conclusion:
285 * It is no problem to use another language to write a tool
286 specifically intended for use with that language. That is because
287 the only people who want to build the tool will be those who have
288 installed the other language anyway.
290 * If an application is of interest only to a narrow part of the
291 community, then the question of which language it is written in
292 has less effect on other people, so you may as well please
295 Many programs are designed to be extensible: they include an
296 interpreter for a language that is higher level than C. Often much of
297 the program is written in that language, too. The Emacs editor
298 pioneered this technique.
300 The standard extensibility interpreter for GNU software is Guile
301 (`http://www.gnu.org/software/guile/'), which implements the language
302 Scheme (an especially clean and simple dialect of Lisp). Guile also
303 includes bindings for GTK+/GNOME, making it practical to write modern
304 GUI functionality within Guile. We don't reject programs written in
305 other "scripting languages" such as Perl and Python, but using Guile is
306 very important for the overall consistency of the GNU system.
309 File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
311 3.2 Compatibility with Other Implementations
312 ============================================
314 With occasional exceptions, utility programs and libraries for GNU
315 should be upward compatible with those in Berkeley Unix, and upward
316 compatible with Standard C if Standard C specifies their behavior, and
317 upward compatible with POSIX if POSIX specifies their behavior.
319 When these standards conflict, it is useful to offer compatibility
320 modes for each of them.
322 Standard C and POSIX prohibit many kinds of extensions. Feel free
323 to make the extensions anyway, and include a `--ansi', `--posix', or
324 `--compatible' option to turn them off. However, if the extension has
325 a significant chance of breaking any real programs or scripts, then it
326 is not really upward compatible. So you should try to redesign its
327 interface to make it upward compatible.
329 Many GNU programs suppress extensions that conflict with POSIX if the
330 environment variable `POSIXLY_CORRECT' is defined (even if it is
331 defined with a null value). Please make your program recognize this
332 variable if appropriate.
334 When a feature is used only by users (not by programs or command
335 files), and it is done poorly in Unix, feel free to replace it
336 completely with something totally different and better. (For example,
337 `vi' is replaced with Emacs.) But it is nice to offer a compatible
338 feature as well. (There is a free `vi' clone, so we offer it.)
340 Additional useful features are welcome regardless of whether there
341 is any precedent for them.
344 File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
346 3.3 Using Non-standard Features
347 ===============================
349 Many GNU facilities that already exist support a number of convenient
350 extensions over the comparable Unix facilities. Whether to use these
351 extensions in implementing your program is a difficult question.
353 On the one hand, using the extensions can make a cleaner program.
354 On the other hand, people will not be able to build the program unless
355 the other GNU tools are available. This might cause the program to
356 work on fewer kinds of machines.
358 With some extensions, it might be easy to provide both alternatives.
359 For example, you can define functions with a "keyword" `INLINE' and
360 define that as a macro to expand into either `inline' or nothing,
361 depending on the compiler.
363 In general, perhaps it is best not to use the extensions if you can
364 straightforwardly do without them, but to use the extensions if they
365 are a big improvement.
367 An exception to this rule are the large, established programs (such
368 as Emacs) which run on a great variety of systems. Using GNU
369 extensions in such programs would make many users unhappy, so we don't
372 Another exception is for programs that are used as part of
373 compilation: anything that must be compiled with other compilers in
374 order to bootstrap the GNU compilation facilities. If these require
375 the GNU compiler, then no one can compile them without having them
376 installed already. That would be extremely troublesome in certain
380 File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
382 3.4 Standard C and Pre-Standard C
383 =================================
385 1989 Standard C is widespread enough now that it is ok to use its
386 features in new programs. There is one exception: do not ever use the
387 "trigraph" feature of Standard C.
389 1999 Standard C is not widespread yet, so please do not require its
390 features in programs. It is ok to use its features if they are present.
392 However, it is easy to support pre-standard compilers in most
393 programs, so if you know how to do that, feel free. If a program you
394 are maintaining has such support, you should try to keep it working.
396 To support pre-standard C, instead of writing function definitions in
397 standard prototype form,
403 write the definition in pre-standard style like this,
410 and use a separate declaration to specify the argument prototype:
414 You need such a declaration anyway, in a header file, to get the
415 benefit of prototypes in all the files where the function is called.
416 And once you have the declaration, you normally lose nothing by writing
417 the function definition in the pre-standard style.
419 This technique does not work for integer types narrower than `int'.
420 If you think of an argument as being of a type narrower than `int',
421 declare it as `int' instead.
423 There are a few special cases where this technique is hard to use.
424 For example, if a function argument needs to hold the system type
425 `dev_t', you run into trouble, because `dev_t' is shorter than `int' on
426 some machines; but you cannot use `int' instead, because `dev_t' is
427 wider than `int' on some machines. There is no type you can safely use
428 on all machines in a non-standard definition. The only way to support
429 non-standard C and pass such an argument is to check the width of
430 `dev_t' using Autoconf and choose the argument type accordingly. This
431 may not be worth the trouble.
433 In order to support pre-standard compilers that do not recognize
434 prototypes, you may want to use a preprocessor macro like this:
436 /* Declare the prototype for a general external function. */
437 #if defined (__STDC__) || defined (WINDOWSNT)
438 #define P_(proto) proto
444 File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
446 3.5 Conditional Compilation
447 ===========================
449 When supporting configuration options already known when building your
450 program we prefer using `if (... )' over conditional compilation, as in
451 the former case the compiler is able to perform more extensive checking
452 of all possible code paths.
454 For example, please write
469 A modern compiler such as GCC will generate exactly the same code in
470 both cases, and we have been using similar techniques with good success
471 in several projects. Of course, the former method assumes that
472 `HAS_FOO' is defined as either 0 or 1.
474 While this is not a silver bullet solving all portability problems,
475 and is not always appropriate, following this policy would have saved
476 GCC developers many hours, or even days, per year.
478 In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
479 which cannot be simply used in `if (...)' statements, there is an easy
480 workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
481 in the following example:
483 #ifdef REVERSIBLE_CC_MODE
484 #define HAS_REVERSIBLE_CC_MODE 1
486 #define HAS_REVERSIBLE_CC_MODE 0
490 File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
492 4 Program Behavior for All Programs
493 ***********************************
495 This chapter describes conventions for writing robust software. It
496 also describes general standards for error messages, the command line
497 interface, and how libraries should behave.
501 * Non-GNU Standards:: We consider standards such as POSIX;
502 we don't "obey" them.
503 * Semantics:: Writing robust programs.
504 * Libraries:: Library behavior.
505 * Errors:: Formatting error messages.
506 * User Interfaces:: Standards about interfaces generally.
507 * Graphical Interfaces:: Standards for graphical interfaces.
508 * Command-Line Interfaces:: Standards for command line interfaces.
509 * Option Table:: Table of long options.
510 * OID Allocations:: Table of OID slots for GNU.
511 * Memory Usage:: When and how to care about memory needs.
512 * File Usage:: Which files to use, and where.
515 File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
517 4.1 Non-GNU Standards
518 =====================
520 The GNU Project regards standards published by other organizations as
521 suggestions, not orders. We consider those standards, but we do not
522 "obey" them. In developing a GNU program, you should implement an
523 outside standard's specifications when that makes the GNU system better
524 overall in an objective sense. When it doesn't, you shouldn't.
526 In most cases, following published standards is convenient for
527 users--it means that their programs or scripts will work more portably.
528 For instance, GCC implements nearly all the features of Standard C as
529 specified by that standard. C program developers would be unhappy if
530 it did not. And GNU utilities mostly follow specifications of POSIX.2;
531 shell script writers and users would be unhappy if our programs were
534 But we do not follow either of these specifications rigidly, and
535 there are specific points on which we decided not to follow them, so as
536 to make the GNU system better for users.
538 For instance, Standard C says that nearly all extensions to C are
539 prohibited. How silly! GCC implements many extensions, some of which
540 were later adopted as part of the standard. If you want these
541 constructs to give an error message as "required" by the standard, you
542 must specify `--pedantic', which was implemented only so that we can
543 say "GCC is a 100% implementation of the standard," not because there
544 is any reason to actually use it.
546 POSIX.2 specifies that `df' and `du' must output sizes by default in
547 units of 512 bytes. What users want is units of 1k, so that is what we
548 do by default. If you want the ridiculous behavior "required" by
549 POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
550 was originally going to be named `POSIX_ME_HARDER').
552 GNU utilities also depart from the letter of the POSIX.2
553 specification when they support long-named command-line options, and
554 intermixing options with ordinary arguments. This minor
555 incompatibility with POSIX is never a problem in practice, and it is
558 In particular, don't reject a new feature, or remove an old one,
559 merely because a standard says it is "forbidden" or "deprecated."
562 File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior
564 4.2 Writing Robust Programs
565 ===========================
567 Avoid arbitrary limits on the length or number of _any_ data structure,
568 including file names, lines, files, and symbols, by allocating all data
569 structures dynamically. In most Unix utilities, "long lines are
570 silently truncated". This is not acceptable in a GNU utility.
572 Utilities reading files should not drop NUL characters, or any other
573 nonprinting characters _including those with codes above 0177_. The
574 only sensible exceptions would be utilities specifically intended for
575 interface to certain types of terminals or printers that can't handle
576 those characters. Whenever possible, try to make programs work
577 properly with sequences of bytes that represent multibyte characters,
578 using encodings such as UTF-8 and others.
580 Check every system call for an error return, unless you know you
581 wish to ignore errors. Include the system error text (from `perror' or
582 equivalent) in _every_ error message resulting from a failing system
583 call, as well as the name of the file if any and the name of the
584 utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
586 Check every call to `malloc' or `realloc' to see if it returned
587 zero. Check `realloc' even if you are making the block smaller; in a
588 system that rounds block sizes to a power of 2, `realloc' may get a
589 different block if you ask for less space.
591 In Unix, `realloc' can destroy the storage block if it returns zero.
592 GNU `realloc' does not have this bug: if it fails, the original block
593 is unchanged. Feel free to assume the bug is fixed. If you wish to
594 run your program on Unix, and wish to avoid lossage in this case, you
595 can use the GNU `malloc'.
597 You must expect `free' to alter the contents of the block that was
598 freed. Anything you want to fetch from the block, you must fetch before
601 If `malloc' fails in a noninteractive program, make that a fatal
602 error. In an interactive program (one that reads commands from the
603 user), it is better to abort the command and return to the command
604 reader loop. This allows the user to kill other processes to free up
605 virtual memory, and then try the command again.
607 Use `getopt_long' to decode arguments, unless the argument syntax
608 makes this unreasonable.
610 When static storage is to be written in during program execution, use
611 explicit C code to initialize it. Reserve C initialized declarations
612 for data that will not be changed.
614 Try to avoid low-level interfaces to obscure Unix data structures
615 (such as file directories, utmp, or the layout of kernel memory), since
616 these are less likely to work compatibly. If you need to find all the
617 files in a directory, use `readdir' or some other high-level interface.
618 These are supported compatibly by GNU.
620 The preferred signal handling facilities are the BSD variant of
621 `signal', and the POSIX `sigaction' function; the alternative USG
622 `signal' interface is an inferior design.
624 Nowadays, using the POSIX signal functions may be the easiest way to
625 make a program portable. If you use `signal', then on GNU/Linux
626 systems running GNU libc version 1, you should include `bsd/signal.h'
627 instead of `signal.h', so as to get BSD behavior. It is up to you
628 whether to support systems where `signal' has only the USG behavior, or
631 In error checks that detect "impossible" conditions, just abort.
632 There is usually no point in printing any message. These checks
633 indicate the existence of bugs. Whoever wants to fix the bugs will have
634 to read the source code and run a debugger. So explain the problem with
635 comments in the source. The relevant data will be in variables, which
636 are easy to examine with the debugger, so there is no point moving them
639 Do not use a count of errors as the exit status for a program.
640 _That does not work_, because exit status values are limited to 8 bits
641 (0 through 255). A single run of the program might have 256 errors; if
642 you try to return 256 as the exit status, the parent process will see 0
643 as the status, and it will appear that the program succeeded.
645 If you make temporary files, check the `TMPDIR' environment
646 variable; if that variable is defined, use the specified directory
649 In addition, be aware that there is a possible security problem when
650 creating temporary files in world-writable directories. In C, you can
651 avoid this problem by creating temporary files in this manner:
653 fd = open (filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
655 or by using the `mkstemps' function from libiberty.
657 In bash, use `set -C' to avoid this problem.
660 File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
665 Try to make library functions reentrant. If they need to do dynamic
666 storage allocation, at least try to avoid any nonreentrancy aside from
667 that of `malloc' itself.
669 Here are certain name conventions for libraries, to avoid name
672 Choose a name prefix for the library, more than two characters long.
673 All external function and variable names should start with this prefix.
674 In addition, there should only be one of these in any given library
675 member. This usually means putting each one in a separate source file.
677 An exception can be made when two external symbols are always used
678 together, so that no reasonable program could use one without the
679 other; then they can both go in the same file.
681 External symbols that are not documented entry points for the user
682 should have names beginning with `_'. The `_' should be followed by
683 the chosen name prefix for the library, to prevent collisions with
684 other libraries. These can go in the same files with user entry points
687 Static functions and variables can be used as you like and need not
688 fit any naming convention.
691 File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
693 4.4 Formatting Error Messages
694 =============================
696 Error messages from compilers should look like this:
698 SOURCE-FILE-NAME:LINENO: MESSAGE
700 If you want to mention the column number, use one of these formats:
702 SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
703 SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
705 Line numbers should start from 1 at the beginning of the file, and
706 column numbers should start from 1 at the beginning of the line. (Both
707 of these conventions are chosen for compatibility.) Calculate column
708 numbers assuming that space and all ASCII printing characters have
709 equal width, and assuming tab stops every 8 columns.
711 The error message can also give both the starting and ending
712 positions of the erroneous text. There are several formats so that you
713 can avoid redundant information such as a duplicate line number. Here
714 are the possible formats:
716 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
717 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
718 SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
720 When an error is spread over several files, you can use this format:
722 FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
724 Error messages from other noninteractive programs should look like
727 PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
729 when there is an appropriate source file, or like this:
733 when there is no relevant source file.
735 If you want to mention the column number, use this format:
737 PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
739 In an interactive program (one that is reading commands from a
740 terminal), it is better not to include the program name in an error
741 message. The place to indicate which program is running is in the
742 prompt or with the screen layout. (When the same program runs with
743 input from a source other than a terminal, it is not interactive and
744 would do best to print error messages using the noninteractive style.)
746 The string MESSAGE should not begin with a capital letter when it
747 follows a program name and/or file name, because that isn't the
748 beginning of a sentence. (The sentence conceptually starts at the
749 beginning of the line.) Also, it should not end with a period.
751 Error messages from interactive programs, and other messages such as
752 usage messages, should start with a capital letter. But they should not
756 File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
758 4.5 Standards for Interfaces Generally
759 ======================================
761 Please don't make the behavior of a utility depend on the name used to
762 invoke it. It is useful sometimes to make a link to a utility with a
763 different name, and that should not change what it does.
765 Instead, use a run time option or a compilation switch or both to
766 select among the alternate behaviors.
768 Likewise, please don't make the behavior of the program depend on the
769 type of output device it is used with. Device independence is an
770 important principle of the system's design; do not compromise it merely
771 to save someone from typing an option now and then. (Variation in error
772 message syntax when using a terminal is ok, because that is a side issue
773 that people do not depend on.)
775 If you think one behavior is most useful when the output is to a
776 terminal, and another is most useful when the output is a file or a
777 pipe, then it is usually best to make the default behavior the one that
778 is useful with output to a terminal, and have an option for the other
781 Compatibility requires certain programs to depend on the type of
782 output device. It would be disastrous if `ls' or `sh' did not do so in
783 the way all users expect. In some of these cases, we supplement the
784 program with a preferred alternate version that does not depend on the
785 output device type. For example, we provide a `dir' program much like
786 `ls' except that its default output format is always multi-column
790 File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
792 4.6 Standards for Graphical Interfaces
793 ======================================
795 When you write a program that provides a graphical user interface,
796 please make it work with the X Window System and the GTK+ toolkit
797 unless the functionality specifically requires some alternative (for
798 example, "displaying jpeg images while in console mode").
800 In addition, please provide a command-line interface to control the
801 functionality. (In many cases, the graphical user interface can be a
802 separate program which invokes the command-line program.) This is so
803 that the same jobs can be done from scripts.
805 Please also consider providing a D-bus interface for use from other
806 running programs, such as within GNOME. (GNOME used to use CORBA for
807 this, but that is being phased out.) In addition, consider providing a
808 library interface (for use from C), and perhaps a keyboard-driven
809 console interface (for use by users from console mode). Once you are
810 doing the work to provide the functionality and the graphical
811 interface, these won't be much extra work.
814 File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
816 4.7 Standards for Command Line Interfaces
817 =========================================
819 It is a good idea to follow the POSIX guidelines for the command-line
820 options of a program. The easiest way to do this is to use `getopt' to
821 parse them. Note that the GNU version of `getopt' will normally permit
822 options anywhere among the arguments unless the special argument `--'
823 is used. This is not what POSIX specifies; it is a GNU extension.
825 Please define long-named options that are equivalent to the
826 single-letter Unix-style options. We hope to make GNU more user
827 friendly this way. This is easy to do with the GNU function
830 One of the advantages of long-named options is that they can be
831 consistent from program to program. For example, users should be able
832 to expect the "verbose" option of any GNU program which has one, to be
833 spelled precisely `--verbose'. To achieve this uniformity, look at the
834 table of common long-option names when you choose the option names for
835 your program (*note Option Table::).
837 It is usually a good idea for file names given as ordinary arguments
838 to be input files only; any output files would be specified using
839 options (preferably `-o' or `--output'). Even if you allow an output
840 file name as an ordinary argument for compatibility, try to provide an
841 option as another way to specify it. This will lead to more consistency
842 among GNU utilities, and fewer idiosyncrasies for users to remember.
844 All programs should support two standard options: `--version' and
845 `--help'. CGI programs should accept these as command-line options,
846 and also if given as the `PATH_INFO'; for instance, visiting
847 `http://example.org/p.cgi/--help' in a browser should output the same
848 information as invoking `p.cgi --help' from the command line.
852 * --version:: The standard output for --version.
853 * --help:: The standard output for --help.
856 File: standards.info, Node: --version, Next: --help, Up: Command-Line Interfaces
861 The standard `--version' option should direct the program to print
862 information about its name, version, origin and legal status, all on
863 standard output, and then exit successfully. Other options and
864 arguments should be ignored once this is seen, and the program should
865 not perform its normal function.
867 The first line is meant to be easy for a program to parse; the
868 version number proper starts after the last space. In addition, it
869 contains the canonical name for this program, in this format:
873 The program's name should be a constant string; _don't_ compute it from
874 `argv[0]'. The idea is to state the standard or canonical name for the
875 program, not its file name. There are other ways to find out the
876 precise file name where a command is found in `PATH'.
878 If the program is a subsidiary part of a larger package, mention the
879 package name in parentheses, like this:
881 emacsserver (GNU Emacs) 19.30
883 If the package has a version number which is different from this
884 program's version number, you can mention the package version number
885 just before the close-parenthesis.
887 If you _need_ to mention the version numbers of libraries which are
888 distributed separately from the package which contains this program,
889 you can do so by printing an additional line of version info for each
890 library you want to mention. Use the same format for these lines as for
893 Please do not mention all of the libraries that the program uses
894 "just for completeness"--that would produce a lot of unhelpful clutter.
895 Please mention library version numbers only if you find in practice that
896 they are very important to you in debugging.
898 The following line, after the version number line or lines, should
899 be a copyright notice. If more than one copyright notice is called
900 for, put each on a separate line.
902 Next should follow a line stating the license, preferably using one
903 of abbrevations below, and a brief statement that the program is free
904 software, and that users are free to copy and change it. Also mention
905 that there is no warranty, to the extent permitted by law. See
906 recommended wording below.
908 It is ok to finish the output with a list of the major authors of the
909 program, as a way of giving credit.
911 Here's an example of output that follows these rules:
914 Copyright (C) 2007 Free Software Foundation, Inc.
915 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
916 This is free software: you are free to change and redistribute it.
917 There is NO WARRANTY, to the extent permitted by law.
919 You should adapt this to your program, of course, filling in the
920 proper year, copyright holder, name of program, and the references to
921 distribution terms, and changing the rest of the wording as necessary.
923 This copyright notice only needs to mention the most recent year in
924 which changes were made--there's no need to list the years for previous
925 versions' changes. You don't have to mention the name of the program in
926 these notices, if that is inconvenient, since it appeared in the first
927 line. (The rules are different for copyright notices in source files;
928 *note Copyright Notices: (maintain)Copyright Notices.)
930 Translations of the above lines must preserve the validity of the
931 copyright notices (*note Internationalization::). If the translation's
932 character set supports it, the `(C)' should be replaced with the
933 copyright symbol, as follows:
935 (the official copyright symbol, which is the letter C in a circle);
937 Write the word "Copyright" exactly like that, in English. Do not
938 translate it into another language. International treaties recognize
939 the English word "Copyright"; translations into other languages do not
940 have legal significance.
942 Finally, here is the table of our suggested license abbreviations.
943 Any abbreviation can be followed by `vVERSION[+]', meaning that
944 particular version, or later versions with the `+', as shown above.
946 In the case of exceptions for extra permissions with the GPL, we use
947 `/' for a separator; the version number can follow the license
948 abbreviation as usual, as in the examples below.
951 GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
954 GNU Lesser General Public License,
955 `http://www.gnu.org/licenses/lgpl.html'.
958 GNU GPL with the exception for Ada.
961 The Apache Software Foundation license,
962 `http://www.apache.org/licenses'.
965 The Artistic license used for Perl,
966 `http://www.perlfoundation.org/legal'.
969 The Expat license, `http://www.jclark.com/xml/copying.txt'.
972 The Mozilla Public License, `http://www.mozilla.org/MPL/'.
975 The original (4-clause) BSD license, incompatible with the GNU GPL
976 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
979 The license used for PHP, `http://www.php.net/license/'.
982 The non-license that is being in the public domain,
983 `http://www.gnu.org/licenses/license-list.html#PublicDomain'.
986 The license for Python, `http://www.python.org/2.0.1/license.html'.
989 The revised (3-clause) BSD, compatible with the GNU GPL,
990 `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
993 The simple non-copyleft license used for most versions of the X
994 Window System, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
997 The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
1000 More information about these licenses and many more are on the GNU
1001 licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
1004 File: standards.info, Node: --help, Prev: --version, Up: Command-Line Interfaces
1009 The standard `--help' option should output brief documentation for how
1010 to invoke the program, on standard output, then exit successfully.
1011 Other options and arguments should be ignored once this is seen, and
1012 the program should not perform its normal function.
1014 Near the end of the `--help' option's output, please place lines
1015 giving the email address for bug reports, the package's home page
1016 (normally <http://www.gnu.org/software/PKG>, and the general page for
1017 help using GNU programs. The format should be like this:
1019 Report bugs to: MAILING-ADDRESS
1020 PKG home page: <http://www.gnu.org/software/PKG/>
1021 General help using GNU software: <http://www.gnu.org/gethelp/>
1023 It is ok to mention other appropriate mailing lists and web pages.
1026 File: standards.info, Node: Option Table, Next: OID Allocations, Prev: Command-Line Interfaces, Up: Program Behavior
1028 4.8 Table of Long Options
1029 =========================
1031 Here is a table of long options used by GNU programs. It is surely
1032 incomplete, but we aim to list all the options that a new program might
1033 want to be compatible with. If you use names not already in the table,
1034 please send <bug-standards@gnu.org> a list of them, with their
1035 meanings, so we can update the table.
1041 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
1050 `-a' in `etags', `tee', `time'; `-r' in `tar'.
1086 For server programs, run in the background.
1104 `-b' in `cpio' and `diff'.
1110 Used in `cpio' and `tar'.
1113 `-b' in `head' and `tail'.
1119 Used in various programs to make output shorter.
1122 `-c' in `head', `split', and `tail'.
1131 Used in various programs to specify the directory to use.
1134 `-c' in `chgrp' and `chown'.
1143 `-c' in `su'; `-x' in GDB.
1152 `-Z' in `tar' and `shar'.
1164 `-W copyleft' in `gawk'.
1167 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
1179 Used in `tar' and `cpio'.
1191 `-d' in `make' and `m4'; `-t' in Bison.
1197 `-d' in Bison and `ctags'.
1203 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
1209 Specify an I/O device (special file name).
1224 Specify the directory to use, in various programs. In `ls', it
1225 means to show directories themselves rather than their contents.
1226 In `rm' and `ln', it means to not treat links to directories
1253 `environment-overrides'
1293 `-i' in `cpio'; `-x' in `tar'.
1305 `-f' in `gawk', `info', `make', `mt', `sed', and `tar'.
1325 `fixed-output-files'
1335 `-f' in `cp', `ln', `mv', and `rm'.
1341 For server programs, run in the foreground; in other words, don't
1342 do anything special to run the server in the background.
1345 Used in `ls', `time', and `ptx'.
1369 `-z' in `tar' and `shar'.
1375 `-h' in `objdump' and `recode'
1381 Used to ask for brief usage information.
1386 `hide-control-chars'
1390 In `makeinfo', output HTML.
1399 `-I' in `ls'; `-x' in `recode'.
1407 `ignore-blank-lines'
1411 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1419 `ignore-indentation'
1428 `ignore-matching-lines'
1431 `ignore-space-change'
1438 `-i' in `etags'; `-I' in `m4'.
1447 `-i', `-l', and `-m' in Finger.
1450 In some programs, specify the name of the file to read as the
1463 `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
1485 `-k' in `du' and `ls'.
1500 Used in `split', `head', and `tail'.
1510 `-t' in `cpio'; `-l' in `recode'.
1531 `-m' in `hello' and `uname'.
1570 `-m' in `install', `mkdir', and `mkfifo'.
1593 `no-character-count'
1636 Don't print a startup splash screen.
1654 Used in `emacsclient'.
1657 Used in various programs to inhibit warnings.
1684 `-n' in `cpio' and `ls'.
1696 `-l' in `tar', `cp', and `du'.
1708 `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1711 In various programs, specify the output file name.
1732 `-p' in `mkdir' and `rmdir'.
1744 `-c' in `cpio' and `tar'.
1756 Used in `tar' and `cp'.
1758 `preserve-environment'
1761 `preserve-modification-time'
1767 `preserve-permissions'
1795 Specify an HTTP proxy.
1804 Used in many programs to inhibit the usual output. Every program
1805 accepting `--quiet' should accept `--silent' as a synonym.
1832 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1841 `-r' in `tac' and `etags'.
1858 `report-identical-files'
1865 `-r' in `ls' and `nm'.
1895 Used by `recode' to chose files or pipes for sequencing passes.
1909 `show-function-line'
1916 Used in many programs to inhibit the usual output. Every program
1917 accepting `--silent' should accept `--quiet' as a synonym.
1923 Specify a file descriptor for a network server to use for its
1924 socket, instead of opening and binding a new socket. This
1925 provides a way to run, in a non-privileged process, a server that
1926 normally needs a reserved port number.
1932 `-W source' in `gawk'.
1956 Used in `tar' and `diff' to specify which file within a directory
1957 to start processing with.
1984 `-S' in `cp', `ln', `mv'.
1999 Used in GDB and `objdump'.
2008 `-t' in `expand' and `unexpand'.
2014 `-T' in `tput' and `ul'. `-t' in `wdiff'.
2023 Used in `ls' and `touch'.
2026 Specify how long to wait before giving up on some operation.
2035 `-t' in `make', `ranlib', and `recode'.
2041 `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
2069 `-u' in `cp', `ctags', `mv', `tar'.
2072 Used in `gawk'; same as `--help'.
2081 Print more information about progress. Many programs support this.
2087 Print the version number.
2090 `-V' in `cp', `ln', `mv'.
2105 `-w' in `ls' and `ptx'.
2117 File: standards.info, Node: OID Allocations, Next: Memory Usage, Prev: Option Table, Up: Program Behavior
2122 The OID (object identifier) 1.3.6.1.4.1.11591 has been assigned to the
2123 GNU Project (thanks to Werner Koch). These are used for SNMP, LDAP,
2124 X.509 certificates, and so on. The web site
2125 `http://www.alvestrand.no/objectid' has a (voluntary) listing of many
2128 If you need a new slot for your GNU package, write
2129 <maintainers@gnu.org>. Here is a list of arcs currently assigned:
2132 1.3.6.1.4.1.11591 GNU
2134 1.3.6.1.4.1.11591.1 GNU Radius
2136 1.3.6.1.4.1.11591.2 GnuPG
2137 1.3.6.1.4.1.11591.2.1 notation
2138 1.3.6.1.4.1.11591.2.1.1 pkaAddress
2140 1.3.6.1.4.1.11591.3 GNU Radar
2142 1.3.6.1.4.1.11591.4 GNU GSS
2144 1.3.6.1.4.1.11591.5 GNU Mailutils
2146 1.3.6.1.4.1.11591.6 GNU Shishi
2148 1.3.6.1.4.1.11591.7 GNU Radio
2150 1.3.6.1.4.1.11591.12 digestAlgorithm
2151 1.3.6.1.4.1.11591.12.2 TIGER/192
2152 1.3.6.1.4.1.11591.13 encryptionAlgorithm
2153 1.3.6.1.4.1.11591.13.2 Serpent
2154 1.3.6.1.4.1.11591.13.2.1 Serpent-128-ECB
2155 1.3.6.1.4.1.11591.13.2.2 Serpent-128-CBC
2156 1.3.6.1.4.1.11591.13.2.3 Serpent-128-OFB
2157 1.3.6.1.4.1.11591.13.2.4 Serpent-128-CFB
2158 1.3.6.1.4.1.11591.13.2.21 Serpent-192-ECB
2159 1.3.6.1.4.1.11591.13.2.22 Serpent-192-CBC
2160 1.3.6.1.4.1.11591.13.2.23 Serpent-192-OFB
2161 1.3.6.1.4.1.11591.13.2.24 Serpent-192-CFB
2162 1.3.6.1.4.1.11591.13.2.41 Serpent-256-ECB
2163 1.3.6.1.4.1.11591.13.2.42 Serpent-256-CBC
2164 1.3.6.1.4.1.11591.13.2.43 Serpent-256-OFB
2165 1.3.6.1.4.1.11591.13.2.44 Serpent-256-CFB
2166 1.3.6.1.4.1.11591.14 CRC algorithms
2167 1.3.6.1.4.1.11591.14.1 CRC 32
2170 File: standards.info, Node: Memory Usage, Next: File Usage, Prev: OID Allocations, Up: Program Behavior
2175 If a program typically uses just a few meg of memory, don't bother
2176 making any effort to reduce memory usage. For example, if it is
2177 impractical for other reasons to operate on files more than a few meg
2178 long, it is reasonable to read entire input files into memory to
2181 However, for programs such as `cat' or `tail', that can usefully
2182 operate on very large files, it is important to avoid using a technique
2183 that would artificially limit the size of files it can handle. If a
2184 program works by lines and could be applied to arbitrary user-supplied
2185 input files, it should keep only a line in memory, because this is not
2186 very hard and users will want to be able to operate on input files that
2187 are bigger than will fit in memory all at once.
2189 If your program creates complicated data structures, just make them
2190 in memory and give a fatal error if `malloc' returns zero.
2193 File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
2198 Programs should be prepared to operate when `/usr' and `/etc' are
2199 read-only file systems. Thus, if the program manages log files, lock
2200 files, backup files, score files, or any other files which are modified
2201 for internal purposes, these files should not be stored in `/usr' or
2204 There are two exceptions. `/etc' is used to store system
2205 configuration information; it is reasonable for a program to modify
2206 files in `/etc' when its job is to update the system configuration.
2207 Also, if the user explicitly asks to modify one file in a directory, it
2208 is reasonable for the program to store other files in the same
2212 File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
2214 5 Making The Best Use of C
2215 **************************
2217 This chapter provides advice on how best to use the C language when
2218 writing GNU software.
2222 * Formatting:: Formatting your source code.
2223 * Comments:: Commenting your work.
2224 * Syntactic Conventions:: Clean use of C constructs.
2225 * Names:: Naming variables, functions, and files.
2226 * System Portability:: Portability among different operating systems.
2227 * CPU Portability:: Supporting the range of CPU types.
2228 * System Functions:: Portability and ``standard'' library functions.
2229 * Internationalization:: Techniques for internationalization.
2230 * Character Set:: Use ASCII by default.
2231 * Quote Characters:: Use `...' in the C locale.
2232 * Mmap:: How you can safely use `mmap'.
2235 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
2237 5.1 Formatting Your Source Code
2238 ===============================
2240 It is important to put the open-brace that starts the body of a C
2241 function in column one, so that they will start a defun. Several tools
2242 look for open-braces in column one to find the beginnings of C
2243 functions. These tools will not work on code not formatted that way.
2245 Avoid putting open-brace, open-parenthesis or open-bracket in column
2246 one when they are inside a function, so that they won't start a defun.
2247 The open-brace that starts a `struct' body can go in column one if you
2248 find it useful to treat that definition as a defun.
2250 It is also important for function definitions to start the name of
2251 the function in column one. This helps people to search for function
2252 definitions, and may also help certain tools recognize them. Thus,
2253 using Standard C syntax, the format is this:
2256 concat (char *s1, char *s2)
2261 or, if you want to use traditional C syntax, format the definition like
2265 concat (s1, s2) /* Name starts in column one here */
2267 { /* Open brace in column one here */
2271 In Standard C, if the arguments don't fit nicely on one line, split
2275 lots_of_args (int an_integer, long a_long, short a_short,
2276 double a_double, float a_float)
2279 The rest of this section gives our recommendations for other aspects
2280 of C formatting style, which is also the default style of the `indent'
2281 program in version 1.2 and newer. It corresponds to the options
2283 -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2284 -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2286 We don't think of these recommendations as requirements, because it
2287 causes no problems for users if two different programs have different
2290 But whatever style you use, please use it consistently, since a
2291 mixture of styles within one program tends to look ugly. If you are
2292 contributing changes to an existing program, please follow the style of
2295 For the body of the function, our recommended style looks like this:
2306 return ++x + bar ();
2309 We find it easier to read a program when it has spaces before the
2310 open-parentheses and after the commas. Especially after the commas.
2312 When you split an expression into multiple lines, split it before an
2313 operator, not after one. Here is the right way:
2315 if (foo_this_is_long && bar > win (x, y, z)
2316 && remaining_condition)
2318 Try to avoid having two operators of different precedence at the same
2319 level of indentation. For example, don't write this:
2321 mode = (inmode[j] == VOIDmode
2322 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2323 ? outmode[j] : inmode[j]);
2325 Instead, use extra parentheses so that the indentation shows the
2328 mode = ((inmode[j] == VOIDmode
2329 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2330 ? outmode[j] : inmode[j]);
2332 Insert extra parentheses so that Emacs will indent the code properly.
2333 For example, the following indentation looks nice if you do it by hand,
2335 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2336 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2338 but Emacs would alter it. Adding a set of parentheses produces
2339 something that looks equally nice, and which Emacs will preserve:
2341 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2342 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2344 Format do-while statements like this:
2352 Please use formfeed characters (control-L) to divide the program into
2353 pages at logical places (but not within a function). It does not matter
2354 just how long the pages are, since they do not have to fit on a printed
2355 page. The formfeeds should appear alone on lines by themselves.
2358 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
2360 5.2 Commenting Your Work
2361 ========================
2363 Every program should start with a comment saying briefly what it is for.
2364 Example: `fmt - filter for simple filling of text'. This comment
2365 should be at the top of the source file containing the `main' function
2368 Also, please write a brief comment at the start of each source file,
2369 with the file name and a line or two about the overall purpose of the
2372 Please write the comments in a GNU program in English, because
2373 English is the one language that nearly all programmers in all
2374 countries can read. If you do not write English well, please write
2375 comments in English as well as you can, then ask other people to help
2376 rewrite them. If you can't write comments in English, please find
2377 someone to work with you and translate your comments into English.
2379 Please put a comment on each function saying what the function does,
2380 what sorts of arguments it gets, and what the possible values of
2381 arguments mean and are used for. It is not necessary to duplicate in
2382 words the meaning of the C argument declarations, if a C type is being
2383 used in its customary fashion. If there is anything nonstandard about
2384 its use (such as an argument of type `char *' which is really the
2385 address of the second character of a string, not the first), or any
2386 possible values that would not work the way one would expect (such as,
2387 that strings containing newlines are not guaranteed to work), be sure
2390 Also explain the significance of the return value, if there is one.
2392 Please put two spaces after the end of a sentence in your comments,
2393 so that the Emacs sentence commands will work. Also, please write
2394 complete sentences and capitalize the first word. If a lower-case
2395 identifier comes at the beginning of a sentence, don't capitalize it!
2396 Changing the spelling makes it a different identifier. If you don't
2397 like starting a sentence with a lower case letter, write the sentence
2398 differently (e.g., "The identifier lower-case is ...").
2400 The comment on a function is much clearer if you use the argument
2401 names to speak about the argument values. The variable name itself
2402 should be lower case, but write it in upper case when you are speaking
2403 about the value rather than the variable itself. Thus, "the inode
2404 number NODE_NUM" rather than "an inode".
2406 There is usually no purpose in restating the name of the function in
2407 the comment before it, because the reader can see that for himself.
2408 There might be an exception when the comment is so long that the
2409 function itself would be off the bottom of the screen.
2411 There should be a comment on each static variable as well, like this:
2413 /* Nonzero means truncate lines in the display;
2414 zero means continue them. */
2417 Every `#endif' should have a comment, except in the case of short
2418 conditionals (just a few lines) that are not nested. The comment should
2419 state the condition of the conditional that is ending, _including its
2420 sense_. `#else' should have a comment describing the condition _and
2421 sense_ of the code that follows. For example:
2427 #endif /* not foo */
2432 but, by contrast, write the comments this way for a `#ifndef':
2441 #endif /* not foo */
2444 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
2446 5.3 Clean Use of C Constructs
2447 =============================
2449 Please explicitly declare the types of all objects. For example, you
2450 should explicitly declare all arguments to functions, and you should
2451 declare functions to return `int' rather than omitting the `int'.
2453 Some programmers like to use the GCC `-Wall' option, and change the
2454 code whenever it issues a warning. If you want to do this, then do.
2455 Other programmers prefer not to use `-Wall', because it gives warnings
2456 for valid and legitimate code which they do not want to change. If you
2457 want to do this, then do. The compiler should be your servant, not
2460 Declarations of external functions and functions to appear later in
2461 the source file should all go in one place near the beginning of the
2462 file (somewhere before the first function definition in the file), or
2463 else should go in a header file. Don't put `extern' declarations inside
2466 It used to be common practice to use the same local variables (with
2467 names like `tem') over and over for different values within one
2468 function. Instead of doing this, it is better to declare a separate
2469 local variable for each distinct purpose, and give it a name which is
2470 meaningful. This not only makes programs easier to understand, it also
2471 facilitates optimization by good compilers. You can also move the
2472 declaration of each local variable into the smallest scope that includes
2473 all its uses. This makes the program even cleaner.
2475 Don't use local variables or parameters that shadow global
2478 Don't declare multiple variables in one declaration that spans lines.
2479 Start a new declaration on each line, instead. For example, instead of
2494 (If they are global variables, each should have a comment preceding it
2497 When you have an `if'-`else' statement nested in another `if'
2498 statement, always put braces around the `if'-`else'. Thus, never write
2517 If you have an `if' statement nested inside of an `else' statement,
2518 either write `else if' on one line, like this,
2525 with its `then'-part indented like the preceding `then'-part, or write
2526 the nested `if' within braces like this:
2536 Don't declare both a structure tag and variables or typedefs in the
2537 same declaration. Instead, declare the structure tag separately and
2538 then use it to declare the variables or typedefs.
2540 Try to avoid assignments inside `if'-conditions (assignments inside
2541 `while'-conditions are ok). For example, don't write this:
2543 if ((foo = (char *) malloc (sizeof *foo)) == 0)
2544 fatal ("virtual memory exhausted");
2546 instead, write this:
2548 foo = (char *) malloc (sizeof *foo);
2550 fatal ("virtual memory exhausted");
2552 Don't make the program ugly to placate `lint'. Please don't insert
2553 any casts to `void'. Zero without a cast is perfectly fine as a null
2554 pointer constant, except when calling a varargs function.
2557 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
2559 5.4 Naming Variables, Functions, and Files
2560 ==========================================
2562 The names of global variables and functions in a program serve as
2563 comments of a sort. So don't choose terse names--instead, look for
2564 names that give useful information about the meaning of the variable or
2565 function. In a GNU program, names should be English, like other
2568 Local variable names can be shorter, because they are used only
2569 within one context, where (presumably) comments explain their purpose.
2571 Try to limit your use of abbreviations in symbol names. It is ok to
2572 make a few abbreviations, explain what they mean, and then use them
2573 frequently, but don't use lots of obscure abbreviations.
2575 Please use underscores to separate words in a name, so that the Emacs
2576 word commands can be useful within them. Stick to lower case; reserve
2577 upper case for macros and `enum' constants, and for name-prefixes that
2578 follow a uniform convention.
2580 For example, you should use names like `ignore_space_change_flag';
2581 don't use names like `iCantReadThis'.
2583 Variables that indicate whether command-line options have been
2584 specified should be named after the meaning of the option, not after
2585 the option-letter. A comment should state both the exact meaning of
2586 the option and its letter. For example,
2588 /* Ignore changes in horizontal whitespace (-b). */
2589 int ignore_space_change_flag;
2591 When you want to define names with constant integer values, use
2592 `enum' rather than `#define'. GDB knows about enumeration constants.
2594 You might want to make sure that none of the file names would
2595 conflict if the files were loaded onto an MS-DOS file system which
2596 shortens the names. You can use the program `doschk' to test for this.
2598 Some GNU programs were designed to limit themselves to file names of
2599 14 characters or less, to avoid file name conflicts if they are read
2600 into older System V systems. Please preserve this feature in the
2601 existing GNU programs that have it, but there is no need to do this in
2602 new GNU programs. `doschk' also reports file names longer than 14
2606 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
2608 5.5 Portability between System Types
2609 ====================================
2611 In the Unix world, "portability" refers to porting to different Unix
2612 versions. For a GNU program, this kind of portability is desirable, but
2615 The primary purpose of GNU software is to run on top of the GNU
2616 kernel, compiled with the GNU C compiler, on various types of CPU. So
2617 the kinds of portability that are absolutely necessary are quite
2618 limited. But it is important to support Linux-based GNU systems, since
2619 they are the form of GNU that is popular.
2621 Beyond that, it is good to support the other free operating systems
2622 (*BSD), and it is nice to support other Unix-like systems if you want
2623 to. Supporting a variety of Unix-like systems is desirable, although
2624 not paramount. It is usually not too hard, so you may as well do it.
2625 But you don't have to consider it an obligation, if it does turn out to
2628 The easiest way to achieve portability to most Unix-like systems is
2629 to use Autoconf. It's unlikely that your program needs to know more
2630 information about the host platform than Autoconf can provide, simply
2631 because most of the programs that need such knowledge have already been
2634 Avoid using the format of semi-internal data bases (e.g.,
2635 directories) when there is a higher-level alternative (`readdir').
2637 As for systems that are not like Unix, such as MSDOS, Windows, VMS,
2638 MVS, and older Macintosh systems, supporting them is often a lot of
2639 work. When that is the case, it is better to spend your time adding
2640 features that will be useful on GNU and GNU/Linux, rather than on
2641 supporting other incompatible systems.
2643 If you do support Windows, please do not abbreviate it as "win". In
2644 hacker terminology, calling something a "win" is a form of praise.
2645 You're free to praise Microsoft Windows on your own if you want, but
2646 please don't do this in GNU packages. Instead of abbreviating
2647 "Windows" to "win", you can write it in full or abbreviate it to "woe"
2648 or "w". In GNU Emacs, for instance, we use `w32' in file names of
2649 Windows-specific files, but the macro for Windows conditionals is
2652 It is a good idea to define the "feature test macro" `_GNU_SOURCE'
2653 when compiling your C files. When you compile on GNU or GNU/Linux,
2654 this will enable the declarations of GNU library extension functions,
2655 and that will usually give you a compiler error message if you define
2656 the same function names in some other way in your program. (You don't
2657 have to actually _use_ these functions, if you prefer to make the
2658 program more portable to other systems.)
2660 But whether or not you use these GNU extensions, you should avoid
2661 using their names for any other meanings. Doing so would make it hard
2662 to move your code into other GNU programs.
2665 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
2667 5.6 Portability between CPUs
2668 ============================
2670 Even GNU systems will differ because of differences among CPU
2671 types--for example, difference in byte ordering and alignment
2672 requirements. It is absolutely essential to handle these differences.
2673 However, don't make any effort to cater to the possibility that an
2674 `int' will be less than 32 bits. We don't support 16-bit machines in
2677 Similarly, don't make any effort to cater to the possibility that
2678 `long' will be smaller than predefined types like `size_t'. For
2679 example, the following code is ok:
2681 printf ("size = %lu\n", (unsigned long) sizeof array);
2682 printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2684 1989 Standard C requires this to work, and we know of only one
2685 counterexample: 64-bit programs on Microsoft Windows. We will leave it
2686 to those who want to port GNU programs to that environment to figure
2689 Predefined file-size types like `off_t' are an exception: they are
2690 longer than `long' on many platforms, so code like the above won't work
2691 with them. One way to print an `off_t' value portably is to print its
2692 digits yourself, one by one.
2694 Don't assume that the address of an `int' object is also the address
2695 of its least-significant byte. This is false on big-endian machines.
2696 Thus, don't make the following mistake:
2700 while ((c = getchar ()) != EOF)
2701 write (file_descriptor, &c, 1);
2703 Instead, use `unsigned char' as follows. (The `unsigned' is for
2704 portability to unusual systems where `char' is signed and where there
2705 is integer overflow checking.)
2708 while ((c = getchar ()) != EOF)
2710 unsigned char u = c;
2711 write (file_descriptor, &u, 1);
2714 It used to be ok to not worry about the difference between pointers
2715 and integers when passing arguments to functions. However, on most
2716 modern 64-bit machines pointers are wider than `int'. Conversely,
2717 integer types like `long long int' and `off_t' are wider than pointers
2718 on most modern 32-bit machines. Hence it's often better nowadays to
2719 use prototypes to define functions whose argument types are not trivial.
2721 In particular, if functions accept varying argument counts or types
2722 they should be declared using prototypes containing `...' and defined
2723 using `stdarg.h'. For an example of this, please see the Gnulib
2724 (http://www.gnu.org/software/gnulib/) error module, which declares and
2725 defines the following function:
2727 /* Print a message with `fprintf (stderr, FORMAT, ...)';
2728 if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2729 If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
2731 void error (int status, int errnum, const char *format, ...);
2733 A simple way to use the Gnulib error module is to obtain the two
2734 source files `error.c' and `error.h' from the Gnulib library source
2735 code repository at `http://git.savannah.gnu.org/gitweb/?p=gnulib.git'.
2736 Here's a sample use:
2742 char *program_name = "myprogram";
2745 xfopen (char const *name)
2747 FILE *fp = fopen (name, "r");
2749 error (1, errno, "cannot read %s", name);
2753 Avoid casting pointers to integers if you can. Such casts greatly
2754 reduce portability, and in most programs they are easy to avoid. In the
2755 cases where casting pointers to integers is essential--such as, a Lisp
2756 interpreter which stores type information as well as an address in one
2757 word--you'll have to make explicit provisions to handle different word
2758 sizes. You will also need to make provision for systems in which the
2759 normal range of addresses you can get from `malloc' starts far away
2763 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
2765 5.7 Calling System Functions
2766 ============================
2768 C implementations differ substantially. Standard C reduces but does
2769 not eliminate the incompatibilities; meanwhile, many GNU packages still
2770 support pre-standard compilers because this is not hard to do. This
2771 chapter gives recommendations for how to use the more-or-less standard C
2772 library functions to avoid unnecessary loss of portability.
2774 * Don't use the return value of `sprintf'. It returns the number of
2775 characters written on some systems, but not on all systems.
2777 * Be aware that `vfprintf' is not always available.
2779 * `main' should be declared to return type `int'. It should
2780 terminate either by calling `exit' or by returning the integer
2781 status code; make sure it cannot ever return an undefined value.
2783 * Don't declare system functions explicitly.
2785 Almost any declaration for a system function is wrong on some
2786 system. To minimize conflicts, leave it to the system header
2787 files to declare system functions. If the headers don't declare a
2788 function, let it remain undeclared.
2790 While it may seem unclean to use a function without declaring it,
2791 in practice this works fine for most system library functions on
2792 the systems where this really happens; thus, the disadvantage is
2793 only theoretical. By contrast, actual declarations have
2794 frequently caused actual conflicts.
2796 * If you must declare a system function, don't specify the argument
2797 types. Use an old-style declaration, not a Standard C prototype.
2798 The more you specify about the function, the more likely a
2801 * In particular, don't unconditionally declare `malloc' or `realloc'.
2803 Most GNU programs use those functions just once, in functions
2804 conventionally named `xmalloc' and `xrealloc'. These functions
2805 call `malloc' and `realloc', respectively, and check the results.
2807 Because `xmalloc' and `xrealloc' are defined in your program, you
2808 can declare them in other files without any risk of type conflict.
2810 On most systems, `int' is the same length as a pointer; thus, the
2811 calls to `malloc' and `realloc' work fine. For the few
2812 exceptional systems (mostly 64-bit machines), you can use
2813 *conditionalized* declarations of `malloc' and `realloc'--or put
2814 these declarations in configuration files specific to those
2817 * The string functions require special treatment. Some Unix systems
2818 have a header file `string.h'; others have `strings.h'. Neither
2819 file name is portable. There are two things you can do: use
2820 Autoconf to figure out which file to include, or don't include
2823 * If you don't include either strings file, you can't get
2824 declarations for the string functions from the header file in the
2827 That causes less of a problem than you might think. The newer
2828 standard string functions should be avoided anyway because many
2829 systems still don't support them. The string functions you can
2832 strcpy strncpy strcat strncat
2833 strlen strcmp strncmp
2836 The copy and concatenate functions work fine without a declaration
2837 as long as you don't use their values. Using their values without
2838 a declaration fails on systems where the width of a pointer
2839 differs from the width of `int', and perhaps in other cases. It
2840 is trivial to avoid using their values, so do that.
2842 The compare functions and `strlen' work fine without a declaration
2843 on most systems, possibly all the ones that GNU software runs on.
2844 You may find it necessary to declare them *conditionally* on a few
2847 The search functions must be declared to return `char *'. Luckily,
2848 there is no variation in the data type they return. But there is
2849 variation in their names. Some systems give these functions the
2850 names `index' and `rindex'; other systems use the names `strchr'
2851 and `strrchr'. Some systems support both pairs of names, but
2852 neither pair works on all systems.
2854 You should pick a single pair of names and use it throughout your
2855 program. (Nowadays, it is better to choose `strchr' and `strrchr'
2856 for new programs, since those are the standard names.) Declare
2857 both of those names as functions returning `char *'. On systems
2858 which don't support those names, define them as macros in terms of
2859 the other pair. For example, here is what to put at the beginning
2860 of your file (or in a header) if you want to use the names
2861 `strchr' and `strrchr' throughout:
2864 #define strchr index
2866 #ifndef HAVE_STRRCHR
2867 #define strrchr rindex
2873 Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
2874 defined in systems where the corresponding functions exist. One way to
2875 get them properly defined is to use Autoconf.
2878 File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C
2880 5.8 Internationalization
2881 ========================
2883 GNU has a library called GNU gettext that makes it easy to translate the
2884 messages in a program into various languages. You should use this
2885 library in every program. Use English for the messages as they appear
2886 in the program, and let gettext provide the way to translate them into
2889 Using GNU gettext involves putting a call to the `gettext' macro
2890 around each string that might need translation--like this:
2892 printf (gettext ("Processing file `%s'..."));
2894 This permits GNU gettext to replace the string `"Processing file
2895 `%s'..."' with a translated version.
2897 Once a program uses gettext, please make a point of writing calls to
2898 `gettext' when you add new strings that call for translation.
2900 Using GNU gettext in a package involves specifying a "text domain
2901 name" for the package. The text domain name is used to separate the
2902 translations for this package from the translations for other packages.
2903 Normally, the text domain name should be the same as the name of the
2904 package--for example, `coreutils' for the GNU core utilities.
2906 To enable gettext to work well, avoid writing code that makes
2907 assumptions about the structure of words or sentences. When you want
2908 the precise text of a sentence to vary depending on the data, use two or
2909 more alternative string constants each containing a complete sentences,
2910 rather than inserting conditionalized words or phrases into a single
2913 Here is an example of what not to do:
2915 printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
2917 If you apply gettext to all strings, like this,
2919 printf (gettext ("%s is full"),
2920 capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
2922 the translator will hardly know that "disk" and "floppy disk" are meant
2923 to be substituted in the other string. Worse, in some languages (like
2924 French) the construction will not work: the translation of the word
2925 "full" depends on the gender of the first part of the sentence; it
2926 happens to be not the same for "disk" as for "floppy disk".
2928 Complete sentences can be translated without problems:
2930 printf (capacity > 5000000 ? gettext ("disk is full")
2931 : gettext ("floppy disk is full"));
2933 A similar problem appears at the level of sentence structure with
2936 printf ("# Implicit rule search has%s been done.\n",
2937 f->tried_implicit ? "" : " not");
2939 Adding `gettext' calls to this code cannot give correct results for all
2940 languages, because negation in some languages requires adding words at
2941 more than one place in the sentence. By contrast, adding `gettext'
2942 calls does the job straightforwardly if the code starts out like this:
2944 printf (f->tried_implicit
2945 ? "# Implicit rule search has been done.\n",
2946 : "# Implicit rule search has not been done.\n");
2948 Another example is this one:
2950 printf ("%d file%s processed", nfiles,
2951 nfiles != 1 ? "s" : "");
2953 The problem with this example is that it assumes that plurals are made
2954 by adding `s'. If you apply gettext to the format string, like this,
2956 printf (gettext ("%d file%s processed"), nfiles,
2957 nfiles != 1 ? "s" : "");
2959 the message can use different words, but it will still be forced to use
2960 `s' for the plural. Here is a better way, with gettext being applied to
2961 the two strings independently:
2963 printf ((nfiles != 1 ? gettext ("%d files processed")
2964 : gettext ("%d file processed")),
2967 But this still doesn't work for languages like Polish, which has three
2968 plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
2969 24, ... and one for the rest. The GNU `ngettext' function solves this
2972 printf (ngettext ("%d files processed", "%d file processed", nfiles),
2976 File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C
2981 Sticking to the ASCII character set (plain text, 7-bit characters) is
2982 preferred in GNU source code comments, text documents, and other
2983 contexts, unless there is good reason to do something else because of
2984 the application domain. For example, if source code deals with the
2985 French Revolutionary calendar, it is OK if its literal strings contain
2986 accented characters in month names like "Flore'al". Also, it is OK to
2987 use non-ASCII characters to represent proper names of contributors in
2988 change logs (*note Change Logs::).
2990 If you need to use non-ASCII characters, you should normally stick
2991 with one encoding, as one cannot in general mix encodings reliably.
2994 File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
2996 5.10 Quote Characters
2997 =====================
2999 In the C locale, GNU programs should stick to plain ASCII for quotation
3000 characters in messages to users: preferably 0x60 (``') for left quotes
3001 and 0x27 (`'') for right quotes. It is ok, but not required, to use
3002 locale-specific quotes in other locales.
3004 The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
3005 `quotearg' modules provide a reasonably straightforward way to support
3006 locale-specific quote characters, as well as taking care of other
3007 issues, such as quoting a filename that itself contains a quote
3008 character. See the Gnulib documentation for usage details.
3010 In any case, the documentation for your program should clearly
3011 specify how it does quoting, if different than the preferred method of
3012 ``' and `''. This is especially important if the output of your
3013 program is ever likely to be parsed by another program.
3015 Quotation characters are a difficult area in the computing world at
3016 this time: there are no true left or right quote characters in Latin1;
3017 the ``' character we use was standardized there as a grave accent.
3018 Moreover, Latin1 is still not universally usable.
3020 Unicode contains the unambiguous quote characters required, and its
3021 common encoding UTF-8 is upward compatible with Latin1. However,
3022 Unicode and UTF-8 are not universally well-supported, either.
3024 This may change over the next few years, and then we will revisit
3028 File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
3033 Don't assume that `mmap' either works on all files or fails for all
3034 files. It may work on some files and fail on others.
3036 The proper way to use `mmap' is to try it on the specific file for
3037 which you want to use it--and if `mmap' doesn't work, fall back on
3038 doing the job in another way using `read' and `write'.
3040 The reason this precaution is needed is that the GNU kernel (the
3041 HURD) provides a user-extensible file system, in which there can be many
3042 different kinds of "ordinary files." Many of them support `mmap', but
3043 some do not. It is important to make programs handle all these kinds
3047 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
3049 6 Documenting Programs
3050 **********************
3052 A GNU program should ideally come with full free documentation, adequate
3053 for both reference and tutorial purposes. If the package can be
3054 programmed or extended, the documentation should cover programming or
3055 extending it, as well as just using it.
3059 * GNU Manuals:: Writing proper manuals.
3060 * Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
3061 * Manual Structure Details:: Specific structure conventions.
3062 * License for Manuals:: Writing the distribution terms for a manual.
3063 * Manual Credits:: Giving credit to documentation contributors.
3064 * Printed Manuals:: Mentioning the printed manual.
3065 * NEWS File:: NEWS files supplement manuals.
3066 * Change Logs:: Recording changes.
3067 * Man Pages:: Man pages are secondary.
3068 * Reading other Manuals:: How far you can go in learning
3072 File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
3077 The preferred document format for the GNU system is the Texinfo
3078 formatting language. Every GNU package should (ideally) have
3079 documentation in Texinfo both for reference and for learners. Texinfo
3080 makes it possible to produce a good quality formatted book, using TeX,
3081 and to generate an Info file. It is also possible to generate HTML
3082 output from Texinfo source. See the Texinfo manual, either the
3083 hardcopy, or the on-line version available through `info' or the Emacs
3084 Info subsystem (`C-h i').
3086 Nowadays some other formats such as Docbook and Sgmltexi can be
3087 converted automatically into Texinfo. It is ok to produce the Texinfo
3088 documentation by conversion this way, as long as it gives good results.
3090 Make sure your manual is clear to a reader who knows nothing about
3091 the topic and reads it straight through. This means covering basic
3092 topics at the beginning, and advanced topics only later. This also
3093 means defining every specialized term when it is first used.
3095 Programmers tend to carry over the structure of the program as the
3096 structure for its documentation. But this structure is not necessarily
3097 good for explaining how to use the program; it may be irrelevant and
3098 confusing for a user.
3100 Instead, the right way to structure documentation is according to the
3101 concepts and questions that a user will have in mind when reading it.
3102 This principle applies at every level, from the lowest (ordering
3103 sentences in a paragraph) to the highest (ordering of chapter topics
3104 within the manual). Sometimes this structure of ideas matches the
3105 structure of the implementation of the software being documented--but
3106 often they are different. An important part of learning to write good
3107 documentation is to learn to notice when you have unthinkingly
3108 structured the documentation like the implementation, stop yourself,
3109 and look for better alternatives.
3111 For example, each program in the GNU system probably ought to be
3112 documented in one manual; but this does not mean each program should
3113 have its own manual. That would be following the structure of the
3114 implementation, rather than the structure that helps the user
3117 Instead, each manual should cover a coherent _topic_. For example,
3118 instead of a manual for `diff' and a manual for `diff3', we have one
3119 manual for "comparison of files" which covers both of those programs,
3120 as well as `cmp'. By documenting these programs together, we can make
3121 the whole subject clearer.
3123 The manual which discusses a program should certainly document all of
3124 the program's command-line options and all of its commands. It should
3125 give examples of their use. But don't organize the manual as a list of
3126 features. Instead, organize it logically, by subtopics. Address the
3127 questions that a user will ask when thinking about the job that the
3128 program does. Don't just tell the reader what each feature can do--say
3129 what jobs it is good for, and show how to use it for those jobs.
3130 Explain what is recommended usage, and what kinds of usage users should
3133 In general, a GNU manual should serve both as tutorial and reference.
3134 It should be set up for convenient access to each topic through Info,
3135 and for reading straight through (appendixes aside). A GNU manual
3136 should give a good introduction to a beginner reading through from the
3137 start, and should also provide all the details that hackers want. The
3138 Bison manual is a good example of this--please take a look at it to see
3141 That is not as hard as it first sounds. Arrange each chapter as a
3142 logical breakdown of its topic, but order the sections, and write their
3143 text, so that reading the chapter straight through makes sense. Do
3144 likewise when structuring the book into chapters, and when structuring a
3145 section into paragraphs. The watchword is, _at each point, address the
3146 most fundamental and important issue raised by the preceding text._
3148 If necessary, add extra chapters at the beginning of the manual which
3149 are purely tutorial and cover the basics of the subject. These provide
3150 the framework for a beginner to understand the rest of the manual. The
3151 Bison manual provides a good example of how to do this.
3153 To serve as a reference, a manual should have an Index that list all
3154 the functions, variables, options, and important concepts that are part
3155 of the program. One combined Index should do for a short manual, but
3156 sometimes for a complex package it is better to use multiple indices.
3157 The Texinfo manual includes advice on preparing good index entries, see
3158 *Note Making Index Entries: (texinfo)Index Entries, and see *Note
3159 Defining the Entries of an Index: (texinfo)Indexing Commands.
3161 Don't use Unix man pages as a model for how to write GNU
3162 documentation; most of them are terse, badly structured, and give
3163 inadequate explanation of the underlying concepts. (There are, of
3164 course, some exceptions.) Also, Unix man pages use a particular format
3165 which is different from what we use in GNU manuals.
3167 Please include an email address in the manual for where to report
3168 bugs _in the text of the manual_.
3170 Please do not use the term "pathname" that is used in Unix
3171 documentation; use "file name" (two words) instead. We use the term
3172 "path" only for search paths, which are lists of directory names.
3174 Please do not use the term "illegal" to refer to erroneous input to
3175 a computer program. Please use "invalid" for this, and reserve the
3176 term "illegal" for activities prohibited by law.
3178 Please do not write `()' after a function name just to indicate it
3179 is a function. `foo ()' is not a function, it is a function call with
3183 File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
3185 6.2 Doc Strings and Manuals
3186 ===========================
3188 Some programming systems, such as Emacs, provide a documentation string
3189 for each function, command or variable. You may be tempted to write a
3190 reference manual by compiling the documentation strings and writing a
3191 little additional text to go around them--but you must not do it. That
3192 approach is a fundamental mistake. The text of well-written
3193 documentation strings will be entirely wrong for a manual.
3195 A documentation string needs to stand alone--when it appears on the
3196 screen, there will be no other text to introduce or explain it.
3197 Meanwhile, it can be rather informal in style.
3199 The text describing a function or variable in a manual must not stand
3200 alone; it appears in the context of a section or subsection. Other text
3201 at the beginning of the section should explain some of the concepts, and
3202 should often make some general points that apply to several functions or
3203 variables. The previous descriptions of functions and variables in the
3204 section will also have given information about the topic. A description
3205 written to stand alone would repeat some of that information; this
3206 redundancy looks bad. Meanwhile, the informality that is acceptable in
3207 a documentation string is totally unacceptable in a manual.
3209 The only good way to use documentation strings in writing a good
3210 manual is to use them as a source of information for writing good text.
3213 File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
3215 6.3 Manual Structure Details
3216 ============================
3218 The title page of the manual should state the version of the programs or
3219 packages documented in the manual. The Top node of the manual should
3220 also contain this information. If the manual is changing more
3221 frequently than or independent of the program, also state a version
3222 number for the manual in both of these places.
3224 Each program documented in the manual should have a node named
3225 `PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
3226 its subnodes, if any) should describe the program's command line
3227 arguments and how to run it (the sort of information people would look
3228 for in a man page). Start with an `@example' containing a template for
3229 all the options and arguments that the program uses.
3231 Alternatively, put a menu item in some menu whose item name fits one
3232 of the above patterns. This identifies the node which that item points
3233 to as the node for this purpose, regardless of the node's actual name.
3235 The `--usage' feature of the Info reader looks for such a node or
3236 menu item in order to find the relevant text, so it is essential for
3237 every Texinfo file to have one.
3239 If one manual describes several programs, it should have such a node
3240 for each program described in the manual.
3243 File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
3245 6.4 License for Manuals
3246 =======================
3248 Please use the GNU Free Documentation License for all GNU manuals that
3249 are more than a few pages long. Likewise for a collection of short
3250 documents--you only need one copy of the GNU FDL for the whole
3251 collection. For a single short document, you can use a very permissive
3252 non-copyleft license, to avoid taking up space with a long license.
3254 See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
3255 of how to employ the GFDL.
3257 Note that it is not obligatory to include a copy of the GNU GPL or
3258 GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
3259 can be a good idea to include the program's license in a large manual;
3260 in a short manual, whose size would be increased considerably by
3261 including the program's license, it is probably better not to include
3265 File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
3270 Please credit the principal human writers of the manual as the authors,
3271 on the title page of the manual. If a company sponsored the work, thank
3272 the company in a suitable place in the manual, but do not cite the
3273 company as an author.
3276 File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
3281 The FSF publishes some GNU manuals in printed form. To encourage sales
3282 of these manuals, the on-line versions of the manual should mention at
3283 the very start that the printed manual is available and should point at
3284 information for getting it--for instance, with a link to the page
3285 `http://www.gnu.org/order/order.html'. This should not be included in
3286 the printed manual, though, because there it is redundant.
3288 It is also useful to explain in the on-line forms of the manual how
3289 the user can print out the manual from the sources.
3292 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
3297 In addition to its manual, the package should have a file named `NEWS'
3298 which contains a list of user-visible changes worth mentioning. In
3299 each new release, add items to the front of the file and identify the
3300 version they pertain to. Don't discard old items; leave them in the
3301 file after the newer items. This way, a user upgrading from any
3302 previous version can see what is new.
3304 If the `NEWS' file gets very long, move some of the older items into
3305 a file named `ONEWS' and put a note at the end referring the user to
3309 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
3314 Keep a change log to describe all the changes made to program source
3315 files. The purpose of this is so that people investigating bugs in the
3316 future will know about the changes that might have introduced the bug.
3317 Often a new bug can be found by looking at what was recently changed.
3318 More importantly, change logs can help you eliminate conceptual
3319 inconsistencies between different parts of a program, by giving you a
3320 history of how the conflicting concepts arose and who they came from.
3324 * Change Log Concepts::
3325 * Style of Change Logs::
3327 * Conditional Changes::
3328 * Indicating the Part Changed::
3331 File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
3333 6.8.1 Change Log Concepts
3334 -------------------------
3336 You can think of the change log as a conceptual "undo list" which
3337 explains how earlier versions were different from the current version.
3338 People can see the current version; they don't need the change log to
3339 tell them what is in it. What they want from a change log is a clear
3340 explanation of how the earlier version differed.
3342 The change log file is normally called `ChangeLog' and covers an
3343 entire directory. Each directory can have its own change log, or a
3344 directory can use the change log of its parent directory--it's up to
3347 Another alternative is to record change log information with a
3348 version control system such as RCS or CVS. This can be converted
3349 automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
3350 command `C-x v a' (`vc-update-change-log') does the job.
3352 There's no need to describe the full purpose of the changes or how
3353 they work together. However, sometimes it is useful to write one line
3354 to describe the overall purpose of a change or a batch of changes. If
3355 you think that a change calls for explanation, you're probably right.
3356 Please do explain it--but please put the full explanation in comments
3357 in the code, where people will see it whenever they see the code. For
3358 example, "New function" is enough for the change log when you add a
3359 function, because there should be a comment before the function
3360 definition to explain what it does.
3362 In the past, we recommended not mentioning changes in non-software
3363 files (manuals, help files, etc.) in change logs. However, we've been
3364 advised that it is a good idea to include them, for the sake of
3367 The easiest way to add an entry to `ChangeLog' is with the Emacs
3368 command `M-x add-change-log-entry'. An entry should have an asterisk,
3369 the name of the changed file, and then in parentheses the name of the
3370 changed functions, variables or whatever, followed by a colon. Then
3371 describe the changes you made to that function or variable.
3374 File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
3376 6.8.2 Style of Change Logs
3377 --------------------------
3379 Here are some simple examples of change log entries, starting with the
3380 header line that says who made the change and when it was installed,
3381 followed by descriptions of specific changes. (These examples are
3382 drawn from Emacs and GCC.)
3384 1998-08-17 Richard Stallman <rms@gnu.org>
3386 * register.el (insert-register): Return nil.
3387 (jump-to-register): Likewise.
3389 * sort.el (sort-subr): Return nil.
3391 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3392 Restart the tex shell if process is gone or stopped.
3393 (tex-shell-running): New function.
3395 * expr.c (store_one_arg): Round size up for move_block_to_reg.
3396 (expand_call): Round up when emitting USE insns.
3397 * stmt.c (assign_parms): Round size up for move_block_from_reg.
3399 It's important to name the changed function or variable in full.
3400 Don't abbreviate function or variable names, and don't combine them.
3401 Subsequent maintainers will often search for a function name to find all
3402 the change log entries that pertain to it; if you abbreviate the name,
3403 they won't find it when they search.
3405 For example, some people are tempted to abbreviate groups of function
3406 names by writing `* register.el ({insert,jump-to}-register)'; this is
3407 not a good idea, since searching for `jump-to-register' or
3408 `insert-register' would not find that entry.
3410 Separate unrelated change log entries with blank lines. When two
3411 entries represent parts of the same change, so that they work together,
3412 then don't put blank lines between them. Then you can omit the file
3413 name and the asterisk when successive entries are in the same file.
3415 Break long lists of function names by closing continued lines with
3416 `)', rather than `,', and opening the continuation with `(' as in this
3419 * keyboard.c (menu_bar_items, tool_bar_items)
3420 (Fexecute_extended_command): Deal with `keymap' property.
3422 When you install someone else's changes, put the contributor's name
3423 in the change log entry rather than in the text of the entry. In other
3426 2002-07-14 John Doe <jdoe@gnu.org>
3428 * sewing.c: Make it sew.
3432 2002-07-14 Usual Maintainer <usual@gnu.org>
3434 * sewing.c: Make it sew. Patch by jdoe@gnu.org.
3436 As for the date, that should be the date you applied the change.
3439 File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
3441 6.8.3 Simple Changes
3442 --------------------
3444 Certain simple kinds of changes don't need much detail in the change
3447 When you change the calling sequence of a function in a simple
3448 fashion, and you change all the callers of the function to use the new
3449 calling sequence, there is no need to make individual entries for all
3450 the callers that you changed. Just write in the entry for the function
3451 being called, "All callers changed"--like this:
3453 * keyboard.c (Fcommand_execute): New arg SPECIAL.
3454 All callers changed.
3456 When you change just comments or doc strings, it is enough to write
3457 an entry for the file, without mentioning the functions. Just "Doc
3458 fixes" is enough for the change log.
3460 There's no technical need to make change log entries for
3461 documentation files. This is because documentation is not susceptible
3462 to bugs that are hard to fix. Documentation does not consist of parts
3463 that must interact in a precisely engineered fashion. To correct an
3464 error, you need not know the history of the erroneous passage; it is
3465 enough to compare what the documentation says with the way the program
3468 However, you should keep change logs for documentation files when the
3469 project gets copyright assignments from its contributors, so as to make
3470 the records of authorship more accurate.
3473 File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
3475 6.8.4 Conditional Changes
3476 -------------------------
3478 C programs often contain compile-time `#if' conditionals. Many changes
3479 are conditional; sometimes you add a new definition which is entirely
3480 contained in a conditional. It is very useful to indicate in the
3481 change log the conditions for which the change applies.
3483 Our convention for indicating conditional changes is to use square
3484 brackets around the name of the condition.
3486 Here is a simple example, describing a change which is conditional
3487 but does not have a function or entity name associated with it:
3489 * xterm.c [SOLARIS2]: Include string.h.
3491 Here is an entry describing a new definition which is entirely
3492 conditional. This new definition for the macro `FRAME_WINDOW_P' is
3493 used only when `HAVE_X_WINDOWS' is defined:
3495 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3497 Here is an entry for a change within the function `init_display',
3498 whose definition as a whole is unconditional, but the changes themselves
3499 are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
3501 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3503 Here is an entry for a change that takes affect only when a certain
3504 macro is _not_ defined:
3506 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3509 File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
3511 6.8.5 Indicating the Part Changed
3512 ---------------------------------
3514 Indicate the part of a function which changed by using angle brackets
3515 enclosing an indication of what the changed part does. Here is an entry
3516 for a change in the part of the function `sh-while-getopts' that deals
3519 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3520 user-specified option string is empty.
3523 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
3528 In the GNU project, man pages are secondary. It is not necessary or
3529 expected for every GNU program to have a man page, but some of them do.
3530 It's your choice whether to include a man page in your program.
3532 When you make this decision, consider that supporting a man page
3533 requires continual effort each time the program is changed. The time
3534 you spend on the man page is time taken away from more useful work.
3536 For a simple program which changes little, updating the man page may
3537 be a small job. Then there is little reason not to include a man page,
3540 For a large program that changes a great deal, updating a man page
3541 may be a substantial burden. If a user offers to donate a man page,
3542 you may find this gift costly to accept. It may be better to refuse
3543 the man page unless the same person agrees to take full responsibility
3544 for maintaining it--so that you can wash your hands of it entirely. If
3545 this volunteer later ceases to do the job, then don't feel obliged to
3546 pick it up yourself; it may be better to withdraw the man page from the
3547 distribution until someone else agrees to update it.
3549 When a program changes only a little, you may feel that the
3550 discrepancies are small enough that the man page remains useful without
3551 updating. If so, put a prominent note near the beginning of the man
3552 page explaining that you don't maintain it and that the Texinfo manual
3553 is more authoritative. The note should say how to access the Texinfo
3556 Be sure that man pages include a copyright statement and free
3557 license. The simple all-permissive license is appropriate for simple
3558 man pages (*note License Notices for Other Files: (maintain)License
3559 Notices for Other Files.).
3561 For long man pages, with enough explanation and documentation that
3562 they can be considered true manuals, use the GFDL (*note License for
3565 Finally, the GNU help2man program
3566 (`http://www.gnu.org/software/help2man/') is one way to automate
3567 generation of a man page, in this case from `--help' output. This is
3568 sufficient in many cases.
3571 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
3573 6.10 Reading other Manuals
3574 ==========================
3576 There may be non-free books or documentation files that describe the
3577 program you are documenting.
3579 It is ok to use these documents for reference, just as the author of
3580 a new algebra textbook can read other books on algebra. A large portion
3581 of any non-fiction book consists of facts, in this case facts about how
3582 a certain program works, and these facts are necessarily the same for
3583 everyone who writes about the subject. But be careful not to copy your
3584 outline structure, wording, tables or examples from preexisting non-free
3585 documentation. Copying from free documentation may be ok; please check
3586 with the FSF about the individual case.
3589 File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
3591 7 The Release Process
3592 *********************
3594 Making a release is more than just bundling up your source files in a
3595 tar file and putting it up for FTP. You should set up your software so
3596 that it can be configured to run on a variety of systems. Your Makefile
3597 should conform to the GNU standards described below, and your directory
3598 layout should also conform to the standards discussed below. Doing so
3599 makes it easy to include your package into the larger framework of all
3604 * Configuration:: How configuration of GNU packages should work.
3605 * Makefile Conventions:: Makefile conventions.
3606 * Releases:: Making releases
3609 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
3611 7.1 How Configuration Should Work
3612 =================================
3614 Each GNU distribution should come with a shell script named
3615 `configure'. This script is given arguments which describe the kind of
3616 machine and system you want to compile the program for. The
3617 `configure' script must record the configuration options so that they
3620 The description here is the specification of the interface for the
3621 `configure' script in GNU packages. Many packages implement it using
3622 GNU Autoconf (*note Introduction: (autoconf)Top.) and/or GNU Automake
3623 (*note Introduction: (automake)Top.), but you do not have to use these
3624 tools. You can implement it any way you like; for instance, by making
3625 `configure' be a wrapper around a completely different configuration
3628 Another way for the `configure' script to operate is to make a link
3629 from a standard name such as `config.h' to the proper configuration
3630 file for the chosen system. If you use this technique, the
3631 distribution should _not_ contain a file named `config.h'. This is so
3632 that people won't be able to build the program without configuring it
3635 Another thing that `configure' can do is to edit the Makefile. If
3636 you do this, the distribution should _not_ contain a file named
3637 `Makefile'. Instead, it should include a file `Makefile.in' which
3638 contains the input used for editing. Once again, this is so that people
3639 won't be able to build the program without configuring it first.
3641 If `configure' does write the `Makefile', then `Makefile' should
3642 have a target named `Makefile' which causes `configure' to be rerun,
3643 setting up the same configuration that was set up last time. The files
3644 that `configure' reads should be listed as dependencies of `Makefile'.
3646 All the files which are output from the `configure' script should
3647 have comments at the beginning explaining that they were generated
3648 automatically using `configure'. This is so that users won't think of
3649 trying to edit them by hand.
3651 The `configure' script should write a file named `config.status'
3652 which describes which configuration options were specified when the
3653 program was last configured. This file should be a shell script which,
3654 if run, will recreate the same configuration.
3656 The `configure' script should accept an option of the form
3657 `--srcdir=DIRNAME' to specify the directory where sources are found (if
3658 it is not the current directory). This makes it possible to build the
3659 program in a separate directory, so that the actual source directory is
3662 If the user does not specify `--srcdir', then `configure' should
3663 check both `.' and `..' to see if it can find the sources. If it finds
3664 the sources in one of these places, it should use them from there.
3665 Otherwise, it should report that it cannot find the sources, and should
3666 exit with nonzero status.
3668 Usually the easy way to support `--srcdir' is by editing a
3669 definition of `VPATH' into the Makefile. Some rules may need to refer
3670 explicitly to the specified source directory. To make this possible,
3671 `configure' can add to the Makefile a variable named `srcdir' whose
3672 value is precisely the specified directory.
3674 In addition, the `configure' script should take options
3675 corresponding to most of the standard directory variables (*note
3676 Directory Variables::). Here is the list:
3678 --prefix --exec-prefix --bindir --sbindir --libexecdir --sysconfdir
3679 --sharedstatedir --localstatedir --libdir --includedir --oldincludedir
3680 --datarootdir --datadir --infodir --localedir --mandir --docdir
3681 --htmldir --dvidir --pdfdir --psdir
3683 The `configure' script should also take an argument which specifies
3684 the type of system to build the program for. This argument should look
3689 For example, an Athlon-based GNU/Linux system might be
3690 `i686-pc-linux-gnu'.
3692 The `configure' script needs to be able to decode all plausible
3693 alternatives for how to describe a machine. Thus,
3694 `athlon-pc-gnu/linux' would be a valid alias. There is a shell script
3696 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD)
3697 that you can use as a subroutine to validate system types and
3698 canonicalize aliases.
3700 The `configure' script should also take the option
3701 `--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
3702 argument. For example, `configure --build=i686-pc-linux-gnu' is
3703 equivalent to `configure i686-pc-linux-gnu'. When the build type is
3704 not specified by an option or argument, the `configure' script should
3705 normally guess it using the shell script `config.guess'
3706 (http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD).
3708 Other options are permitted to specify in more detail the software
3709 or hardware present on the machine, to include or exclude optional parts
3710 of the package, or to adjust the name of some tools or arguments to
3713 `--enable-FEATURE[=PARAMETER]'
3714 Configure the package to build and install an optional user-level
3715 facility called FEATURE. This allows users to choose which
3716 optional features to include. Giving an optional PARAMETER of
3717 `no' should omit FEATURE, if it is built by default.
3719 No `--enable' option should *ever* cause one feature to replace
3720 another. No `--enable' option should ever substitute one useful
3721 behavior for another useful behavior. The only proper use for
3722 `--enable' is for questions of whether to build part of the program
3726 The package PACKAGE will be installed, so configure this package
3727 to work with PACKAGE.
3729 Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
3730 `gnu-libc', `gdb', `x', and `x-toolkit'.
3732 Do not use a `--with' option to specify the file name to use to
3733 find certain files. That is outside the scope of what `--with'
3737 Set the value of the variable VARIABLE to VALUE. This is used to
3738 override the default values of commands or arguments in the build
3739 process. For example, the user could issue `configure CFLAGS=-g
3740 CXXFLAGS=-g' to build with debugging information and without the
3741 default optimization.
3743 Specifying variables as arguments to `configure', like this:
3745 is preferable to setting them in environment variables:
3747 as it helps to recreate the same configuration later with
3748 `config.status'. However, both methods should be supported.
3750 All `configure' scripts should accept all of the "detail" options
3751 and the variable settings, whether or not they make any difference to
3752 the particular package at hand. In particular, they should accept any
3753 option that starts with `--with-' or `--enable-'. This is so users
3754 will be able to configure an entire GNU source tree at once with a
3755 single set of options.
3757 You will note that the categories `--with-' and `--enable-' are
3758 narrow: they *do not* provide a place for any sort of option you might
3759 think of. That is deliberate. We want to limit the possible
3760 configuration options in GNU software. We do not want GNU programs to
3761 have idiosyncratic configuration options.
3763 Packages that perform part of the compilation process may support
3764 cross-compilation. In such a case, the host and target machines for the
3765 program may be different.
3767 The `configure' script should normally treat the specified type of
3768 system as both the host and the target, thus producing a program which
3769 works for the same type of machine that it runs on.
3771 To compile a program to run on a host type that differs from the
3772 build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
3773 uses the same syntax as BUILDTYPE. The host type normally defaults to
3776 To configure a cross-compiler, cross-assembler, or what have you, you
3777 should specify a target different from the host, using the configure
3778 option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
3779 for the host type. So the command would look like this:
3781 ./configure --host=HOSTTYPE --target=TARGETTYPE
3783 The target type normally defaults to the host type. Programs for
3784 which cross-operation is not meaningful need not accept the `--target'
3785 option, because configuring an entire operating system for
3786 cross-operation is not a meaningful operation.
3788 Some programs have ways of configuring themselves automatically. If
3789 your program is set up to do this, your `configure' script can simply
3790 ignore most of its arguments.
3793 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
3795 7.2 Makefile Conventions
3796 ========================
3798 This node describes conventions for writing the Makefiles for GNU
3799 programs. Using Automake will help you write a Makefile that follows
3804 * Makefile Basics:: General conventions for Makefiles.
3805 * Utilities in Makefiles:: Utilities to be used in Makefiles.
3806 * Command Variables:: Variables for specifying commands.
3807 * DESTDIR:: Supporting staged installs.
3808 * Directory Variables:: Variables for installation directories.
3809 * Standard Targets:: Standard targets for users.
3810 * Install Command Categories:: Three categories of commands in the `install'
3811 rule: normal, pre-install and post-install.
3814 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
3816 7.2.1 General Conventions for Makefiles
3817 ---------------------------------------
3819 Every Makefile should contain this line:
3823 to avoid trouble on systems where the `SHELL' variable might be
3824 inherited from the environment. (This is never a problem with GNU
3827 Different `make' programs have incompatible suffix lists and
3828 implicit rules, and this sometimes creates confusion or misbehavior. So
3829 it is a good idea to set the suffix list explicitly using only the
3830 suffixes you need in the particular Makefile, like this:
3835 The first line clears out the suffix list, the second introduces all
3836 suffixes which may be subject to implicit rules in this Makefile.
3838 Don't assume that `.' is in the path for command execution. When
3839 you need to run programs that are a part of your package during the
3840 make, please make sure that it uses `./' if the program is built as
3841 part of the make or `$(srcdir)/' if the file is an unchanging part of
3842 the source code. Without one of these prefixes, the current search
3845 The distinction between `./' (the "build directory") and
3846 `$(srcdir)/' (the "source directory") is important because users can
3847 build in a separate directory using the `--srcdir' option to
3848 `configure'. A rule of the form:
3850 foo.1 : foo.man sedscript
3851 sed -e sedscript foo.man > foo.1
3853 will fail when the build directory is not the source directory, because
3854 `foo.man' and `sedscript' are in the source directory.
3856 When using GNU `make', relying on `VPATH' to find the source file
3857 will work in the case where there is a single dependency file, since
3858 the `make' automatic variable `$<' will represent the source file
3859 wherever it is. (Many versions of `make' set `$<' only in implicit
3860 rules.) A Makefile target like
3863 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
3865 should instead be written as
3868 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
3870 in order to allow `VPATH' to work correctly. When the target has
3871 multiple dependencies, using an explicit `$(srcdir)' is the easiest way
3872 to make the rule work well. For example, the target above for `foo.1'
3875 foo.1 : foo.man sedscript
3876 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
3878 GNU distributions usually contain some files which are not source
3879 files--for example, Info files, and the output from Autoconf, Automake,
3880 Bison or Flex. Since these files normally appear in the source
3881 directory, they should always appear in the source directory, not in the
3882 build directory. So Makefile rules to update them should put the
3883 updated files in the source directory.
3885 However, if a file does not appear in the distribution, then the
3886 Makefile should not put it in the source directory, because building a
3887 program in ordinary circumstances should not modify the source directory
3890 Try to make the build and installation targets, at least (and all
3891 their subtargets) work correctly with a parallel `make'.
3894 File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
3896 7.2.2 Utilities in Makefiles
3897 ----------------------------
3899 Write the Makefile commands (and any shell scripts, such as
3900 `configure') to run in `sh', not in `csh'. Don't use any special
3901 features of `ksh' or `bash'.
3903 The `configure' script and the Makefile rules for building and
3904 installation should not use any utilities directly except these:
3906 cat cmp cp diff echo egrep expr false grep install-info
3907 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
3909 The compression program `gzip' can be used in the `dist' rule.
3911 Stick to the generally supported options for these programs. For
3912 example, don't use `mkdir -p', convenient as it may be, because most
3913 systems don't support it.
3915 It is a good idea to avoid creating symbolic links in makefiles,
3916 since a few systems don't support them.
3918 The Makefile rules for building and installation can also use
3919 compilers and related programs, but should do so via `make' variables
3920 so that the user can substitute alternatives. Here are some of the
3923 ar bison cc flex install ld ldconfig lex
3924 make makeinfo ranlib texi2dvi yacc
3926 Use the following `make' variables to run those programs:
3928 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
3929 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
3931 When you use `ranlib' or `ldconfig', you should make sure nothing
3932 bad happens if the system does not have the program in question.
3933 Arrange to ignore an error from that command, and print a message before
3934 the command to tell the user that failure of this command does not mean
3935 a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
3937 If you use symbolic links, you should implement a fallback for
3938 systems that don't have symbolic links.
3940 Additional utilities that can be used via Make variables are:
3942 chgrp chmod chown mknod
3944 It is ok to use other utilities in Makefile portions (or scripts)
3945 intended only for particular systems where you know those utilities
3949 File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions
3951 7.2.3 Variables for Specifying Commands
3952 ---------------------------------------
3954 Makefiles should provide variables for overriding certain commands,
3957 In particular, you should run most utility programs via variables.
3958 Thus, if you use Bison, have a variable named `BISON' whose default
3959 value is set with `BISON = bison', and refer to it with `$(BISON)'
3960 whenever you need to use Bison.
3962 File management utilities such as `ln', `rm', `mv', and so on, need
3963 not be referred to through variables in this way, since users don't
3964 need to replace them with other programs.
3966 Each program-name variable should come with an options variable that
3967 is used to supply options to the program. Append `FLAGS' to the
3968 program-name variable name to get the options variable name--for
3969 example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
3970 `YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
3971 but we keep them because they are standard.) Use `CPPFLAGS' in any
3972 compilation command that runs the preprocessor, and use `LDFLAGS' in
3973 any compilation command that does linking as well as in any direct use
3976 If there are C compiler options that _must_ be used for proper
3977 compilation of certain files, do not include them in `CFLAGS'. Users
3978 expect to be able to specify `CFLAGS' freely themselves. Instead,
3979 arrange to pass the necessary options to the C compiler independently
3980 of `CFLAGS', by writing them explicitly in the compilation commands or
3981 by defining an implicit rule, like this:
3984 ALL_CFLAGS = -I. $(CFLAGS)
3986 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
3988 Do include the `-g' option in `CFLAGS', because that is not
3989 _required_ for proper compilation. You can consider it a default that
3990 is only recommended. If the package is set up so that it is compiled
3991 with GCC by default, then you might as well include `-O' in the default
3992 value of `CFLAGS' as well.
3994 Put `CFLAGS' last in the compilation command, after other variables
3995 containing compiler options, so the user can use `CFLAGS' to override
3998 `CFLAGS' should be used in every invocation of the C compiler, both
3999 those which do compilation and those which do linking.
4001 Every Makefile should define the variable `INSTALL', which is the
4002 basic command for installing a file into the system.
4004 Every Makefile should also define the variables `INSTALL_PROGRAM'
4005 and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
4006 `$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
4007 644'.) Then it should use those variables as the commands for actual
4008 installation, for executables and non-executables respectively.
4009 Minimal use of these variables is as follows:
4011 $(INSTALL_PROGRAM) foo $(bindir)/foo
4012 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
4014 However, it is preferable to support a `DESTDIR' prefix on the
4015 target files, as explained in the next section.
4017 Always use a file name, not a directory name, as the second argument of
4018 the installation commands. Use a separate command for each file to be
4022 File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions
4024 7.2.4 `DESTDIR': support for staged installs
4025 --------------------------------------------
4027 `DESTDIR' is a variable prepended to each installed target file, like
4030 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
4031 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
4033 The `DESTDIR' variable is specified by the user on the `make'
4034 command line. For example:
4036 make DESTDIR=/tmp/stage install
4038 `DESTDIR' should be supported only in the `install*' and `uninstall*'
4039 targets, as those are the only targets where it is useful.
4041 If your installation step would normally install
4042 `/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
4043 installation invoked as in the example above would install
4044 `/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
4047 Prepending the variable `DESTDIR' to each target in this way
4048 provides for "staged installs", where the installed files are not
4049 placed directly into their expected location but are instead copied
4050 into a temporary location (`DESTDIR'). However, installed files
4051 maintain their relative directory structure and any embedded file names
4052 will not be modified.
4054 You should not set the value of `DESTDIR' in your `Makefile' at all;
4055 then the files are installed into their expected locations by default.
4056 Also, specifying `DESTDIR' should not change the operation of the
4057 software in any way, so its value should not be included in any file
4060 `DESTDIR' support is commonly used in package creation. It is also
4061 helpful to users who want to understand what a given package will
4062 install where, and to allow users who don't normally have permissions
4063 to install into protected areas to build and install before gaining
4064 those permissions. Finally, it can be useful with tools such as
4065 `stow', where code is installed in one place but made to appear to be
4066 installed somewhere else using symbolic links or special mount
4067 operations. So, we strongly recommend GNU packages support `DESTDIR',
4068 though it is not an absolute requirement.
4071 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions
4073 7.2.5 Variables for Installation Directories
4074 --------------------------------------------
4076 Installation directories should always be named by variables, so it is
4077 easy to install in a nonstandard place. The standard names for these
4078 variables and the values they should have in GNU packages are described
4079 below. They are based on a standard file system layout; variants of it
4080 are used in GNU/Linux and other modern operating systems.
4082 Installers are expected to override these values when calling `make'
4083 (e.g., `make prefix=/usr install' or `configure' (e.g., `configure
4084 --prefix=/usr'). GNU packages should not try to guess which value
4085 should be appropriate for these variables on the system they are being
4086 installed onto: use the default settings specified here so that all GNU
4087 packages behave identically, allowing the installer to achieve any
4090 These first two variables set the root for the installation. All the
4091 other installation directories should be subdirectories of one of these
4092 two, and nothing should be directly installed into these two
4096 A prefix used in constructing the default values of the variables
4097 listed below. The default value of `prefix' should be
4098 `/usr/local'. When building the complete GNU system, the prefix
4099 will be empty and `/usr' will be a symbolic link to `/'. (If you
4100 are using Autoconf, write it as `@prefix@'.)
4102 Running `make install' with a different value of `prefix' from the
4103 one used to build the program should _not_ recompile the program.
4106 A prefix used in constructing the default values of some of the
4107 variables listed below. The default value of `exec_prefix' should
4108 be `$(prefix)'. (If you are using Autoconf, write it as
4111 Generally, `$(exec_prefix)' is used for directories that contain
4112 machine-specific files (such as executables and subroutine
4113 libraries), while `$(prefix)' is used directly for other
4116 Running `make install' with a different value of `exec_prefix'
4117 from the one used to build the program should _not_ recompile the
4120 Executable programs are installed in one of the following
4124 The directory for installing executable programs that users can
4125 run. This should normally be `/usr/local/bin', but write it as
4126 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
4130 The directory for installing executable programs that can be run
4131 from the shell, but are only generally useful to system
4132 administrators. This should normally be `/usr/local/sbin', but
4133 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
4134 write it as `@sbindir@'.)
4137 The directory for installing executable programs to be run by other
4138 programs rather than by users. This directory should normally be
4139 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
4140 (If you are using Autoconf, write it as `@libexecdir@'.)
4142 The definition of `libexecdir' is the same for all packages, so
4143 you should install your data in a subdirectory thereof. Most
4144 packages install their data under `$(libexecdir)/PACKAGE-NAME/',
4145 possibly within additional subdirectories thereof, such as
4146 `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
4148 Data files used by the program during its execution are divided into
4149 categories in two ways.
4151 * Some files are normally modified by programs; others are never
4152 normally modified (though users may edit some of these).
4154 * Some files are architecture-independent and can be shared by all
4155 machines at a site; some are architecture-dependent and can be
4156 shared only by machines of the same kind and operating system;
4157 others may never be shared between two machines.
4159 This makes for six different possibilities. However, we want to
4160 discourage the use of architecture-dependent files, aside from object
4161 files and libraries. It is much cleaner to make other data files
4162 architecture-independent, and it is generally not hard.
4164 Here are the variables Makefiles should use to specify directories
4165 to put these various kinds of files in:
4168 The root of the directory tree for read-only
4169 architecture-independent data files. This should normally be
4170 `/usr/local/share', but write it as `$(prefix)/share'. (If you
4171 are using Autoconf, write it as `@datarootdir@'.) `datadir''s
4172 default value is based on this variable; so are `infodir',
4173 `mandir', and others.
4176 The directory for installing idiosyncratic read-only
4177 architecture-independent data files for this program. This is
4178 usually the same place as `datarootdir', but we use the two
4179 separate variables so that you can move these program-specific
4180 files without altering the location for Info files, man pages, etc.
4182 This should normally be `/usr/local/share', but write it as
4183 `$(datarootdir)'. (If you are using Autoconf, write it as
4186 The definition of `datadir' is the same for all packages, so you
4187 should install your data in a subdirectory thereof. Most packages
4188 install their data under `$(datadir)/PACKAGE-NAME/'.
4191 The directory for installing read-only data files that pertain to a
4192 single machine-that is to say, files for configuring a host.
4193 Mailer and network configuration files, `/etc/passwd', and so
4194 forth belong here. All the files in this directory should be
4195 ordinary ASCII text files. This directory should normally be
4196 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
4197 using Autoconf, write it as `@sysconfdir@'.)
4199 Do not install executables here in this directory (they probably
4200 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
4201 files that are modified in the normal course of their use (programs
4202 whose purpose is to change the configuration of the system
4203 excluded). Those probably belong in `$(localstatedir)'.
4206 The directory for installing architecture-independent data files
4207 which the programs modify while they run. This should normally be
4208 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
4209 using Autoconf, write it as `@sharedstatedir@'.)
4212 The directory for installing data files which the programs modify
4213 while they run, and that pertain to one specific machine. Users
4214 should never need to modify files in this directory to configure
4215 the package's operation; put such configuration information in
4216 separate files that go in `$(datadir)' or `$(sysconfdir)'.
4217 `$(localstatedir)' should normally be `/usr/local/var', but write
4218 it as `$(prefix)/var'. (If you are using Autoconf, write it as
4221 These variables specify the directory for installing certain specific
4222 types of files, if your program has them. Every GNU package should
4223 have Info files, so every program needs `infodir', but not all need
4224 `libdir' or `lispdir'.
4227 The directory for installing header files to be included by user
4228 programs with the C `#include' preprocessor directive. This
4229 should normally be `/usr/local/include', but write it as
4230 `$(prefix)/include'. (If you are using Autoconf, write it as
4233 Most compilers other than GCC do not look for header files in
4234 directory `/usr/local/include'. So installing the header files
4235 this way is only useful with GCC. Sometimes this is not a problem
4236 because some libraries are only really intended to work with GCC.
4237 But some libraries are intended to work with other compilers.
4238 They should install their header files in two places, one
4239 specified by `includedir' and one specified by `oldincludedir'.
4242 The directory for installing `#include' header files for use with
4243 compilers other than GCC. This should normally be `/usr/include'.
4244 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
4246 The Makefile commands should check whether the value of
4247 `oldincludedir' is empty. If it is, they should not try to use
4248 it; they should cancel the second installation of the header files.
4250 A package should not replace an existing header in this directory
4251 unless the header came from the same package. Thus, if your Foo
4252 package provides a header file `foo.h', then it should install the
4253 header file in the `oldincludedir' directory if either (1) there
4254 is no `foo.h' there or (2) the `foo.h' that exists came from the
4257 To tell whether `foo.h' came from the Foo package, put a magic
4258 string in the file--part of a comment--and `grep' for that string.
4261 The directory for installing documentation files (other than Info)
4262 for this package. By default, it should be
4263 `/usr/local/share/doc/YOURPKG', but it should be written as
4264 `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
4265 it as `@docdir@'.) The YOURPKG subdirectory, which may include a
4266 version number, prevents collisions among files with common names,
4270 The directory for installing the Info files for this package. By
4271 default, it should be `/usr/local/share/info', but it should be
4272 written as `$(datarootdir)/info'. (If you are using Autoconf,
4273 write it as `@infodir@'.) `infodir' is separate from `docdir' for
4274 compatibility with existing practice.
4280 Directories for installing documentation files in the particular
4281 format. They should all be set to `$(docdir)' by default. (If
4282 you are using Autoconf, write them as `@htmldir@', `@dvidir@',
4283 etc.) Packages which supply several translations of their
4284 documentation should install them in `$(htmldir)/'LL,
4285 `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
4289 The directory for object files and libraries of object code. Do
4290 not install executables here, they probably ought to go in
4291 `$(libexecdir)' instead. The value of `libdir' should normally be
4292 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
4293 are using Autoconf, write it as `@libdir@'.)
4296 The directory for installing any Emacs Lisp files in this package.
4297 By default, it should be `/usr/local/share/emacs/site-lisp', but
4298 it should be written as `$(datarootdir)/emacs/site-lisp'.
4300 If you are using Autoconf, write the default as `@lispdir@'. In
4301 order to make `@lispdir@' work, you need the following lines in
4302 your `configure.in' file:
4304 lispdir='${datarootdir}/emacs/site-lisp'
4308 The directory for installing locale-specific message catalogs for
4309 this package. By default, it should be `/usr/local/share/locale',
4310 but it should be written as `$(datarootdir)/locale'. (If you are
4311 using Autoconf, write it as `@localedir@'.) This directory
4312 usually has a subdirectory per locale.
4314 Unix-style man pages are installed in one of the following:
4317 The top-level directory for installing the man pages (if any) for
4318 this package. It will normally be `/usr/local/share/man', but you
4319 should write it as `$(datarootdir)/man'. (If you are using
4320 Autoconf, write it as `@mandir@'.)
4323 The directory for installing section 1 man pages. Write it as
4327 The directory for installing section 2 man pages. Write it as
4331 *Don't make the primary documentation for any GNU software be a
4332 man page. Write a manual in Texinfo instead. Man pages are just
4333 for the sake of people running GNU software on Unix, which is a
4334 secondary application only.*
4337 The file name extension for the installed man page. This should
4338 contain a period followed by the appropriate digit; it should
4342 The file name extension for installed section 1 man pages.
4345 The file name extension for installed section 2 man pages.
4348 Use these names instead of `manext' if the package needs to
4349 install man pages in more than one section of the manual.
4351 And finally, you should set the following variable:
4354 The directory for the sources being compiled. The value of this
4355 variable is normally inserted by the `configure' shell script.
4356 (If you are using Autoconf, use `srcdir = @srcdir@'.)
4360 # Common prefix for installation directories.
4361 # NOTE: This directory must exist when you start the install.
4363 datarootdir = $(prefix)/share
4364 datadir = $(datarootdir)
4365 exec_prefix = $(prefix)
4366 # Where to put the executable for the command `gcc'.
4367 bindir = $(exec_prefix)/bin
4368 # Where to put the directories used by the compiler.
4369 libexecdir = $(exec_prefix)/libexec
4370 # Where to put the Info files.
4371 infodir = $(datarootdir)/info
4373 If your program installs a large number of files into one of the
4374 standard user-specified directories, it might be useful to group them
4375 into a subdirectory particular to that program. If you do this, you
4376 should write the `install' rule to create these subdirectories.
4378 Do not expect the user to include the subdirectory name in the value
4379 of any of the variables listed above. The idea of having a uniform set
4380 of variable names for installation directories is to enable the user to
4381 specify the exact same values for several different GNU packages. In
4382 order for this to be useful, all the packages must be designed so that
4383 they will work sensibly when the user does so.
4385 At times, not all of these variables may be implemented in the
4386 current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
4387 believe all of them are. When any are missing, the descriptions here
4388 serve as specifications for what Autoconf will implement. As a
4389 programmer, you can either use a development version of Autoconf or
4390 avoid using these variables until a stable release is made which
4394 File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
4396 7.2.6 Standard Targets for Users
4397 --------------------------------
4399 All GNU programs should have the following targets in their Makefiles:
4402 Compile the entire program. This should be the default target.
4403 This target need not rebuild any documentation files; Info files
4404 should normally be included in the distribution, and DVI (and other
4405 documentation format) files should be made only when explicitly
4408 By default, the Make rules should compile and link with `-g', so
4409 that executable programs have debugging symbols. Users who don't
4410 mind being helpless can strip the executables later if they wish.
4413 Compile the program and copy the executables, libraries, and so on
4414 to the file names where they should reside for actual use. If
4415 there is a simple test to verify that a program is properly
4416 installed, this target should run that test.
4418 Do not strip executables when installing them. Devil-may-care
4419 users can use the `install-strip' target to do that.
4421 If possible, write the `install' target rule so that it does not
4422 modify anything in the directory where the program was built,
4423 provided `make all' has just been done. This is convenient for
4424 building the program under one user name and installing it under
4427 The commands should create all the directories in which files are
4428 to be installed, if they don't already exist. This includes the
4429 directories specified as the values of the variables `prefix' and
4430 `exec_prefix', as well as all subdirectories that are needed. One
4431 way to do this is by means of an `installdirs' target as described
4434 Use `-' before any command for installing a man page, so that
4435 `make' will ignore any errors. This is in case there are systems
4436 that don't have the Unix man page documentation system installed.
4438 The way to install Info files is to copy them into `$(infodir)'
4439 with `$(INSTALL_DATA)' (*note Command Variables::), and then run
4440 the `install-info' program if it is present. `install-info' is a
4441 program that edits the Info `dir' file to add or update the menu
4442 entry for the given Info file; it is part of the Texinfo package.
4443 Here is a sample rule to install an Info file:
4445 $(DESTDIR)$(infodir)/foo.info: foo.info
4447 # There may be a newer info file in . than in srcdir.
4448 -if test -f foo.info; then d=.; \
4449 else d=$(srcdir); fi; \
4450 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
4451 # Run install-info only if it exists.
4452 # Use `if' instead of just prepending `-' to the
4453 # line so we notice real errors from install-info.
4454 # We use `$(SHELL) -c' because some shells do not
4455 # fail gracefully when there is an unknown command.
4456 if $(SHELL) -c 'install-info --version' \
4457 >/dev/null 2>&1; then \
4458 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
4459 $(DESTDIR)$(infodir)/foo.info; \
4462 When writing the `install' target, you must classify all the
4463 commands into three categories: normal ones, "pre-installation"
4464 commands and "post-installation" commands. *Note Install Command
4471 These targets install documentation in formats other than Info;
4472 they're intended to be called explicitly by the person installing
4473 the package, if that format is desired. GNU prefers Info files,
4474 so these must be installed by the `install' target.
4476 When you have many documentation files to install, we recommend
4477 that you avoid collisions and clutter by arranging for these
4478 targets to install in subdirectories of the appropriate
4479 installation directory, such as `htmldir'. As one example, if
4480 your package has multiple manuals, and you wish to install HTML
4481 documentation with many files (such as the "split" mode output by
4482 `makeinfo --html'), you'll certainly want to use subdirectories,
4483 or two nodes with the same name in different manuals will
4484 overwrite each other.
4486 Please make these `install-FORMAT' targets invoke the commands for
4487 the FORMAT target, for example, by making FORMAT a dependency.
4490 Delete all the installed files--the copies that the `install' and
4491 `install-*' targets create.
4493 This rule should not modify the directories where compilation is
4494 done, only the directories where files are installed.
4496 The uninstallation commands are divided into three categories,
4497 just like the installation commands. *Note Install Command
4501 Like `install', but strip the executable files while installing
4502 them. In simple cases, this target can use the `install' target in
4506 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
4509 But if the package installs scripts as well as real executables,
4510 the `install-strip' target can't just refer to the `install'
4511 target; it has to strip the executables but not the scripts.
4513 `install-strip' should not strip the executables in the build
4514 directory which are being copied for installation. It should only
4515 strip the copies that are installed.
4517 Normally we do not recommend stripping an executable unless you
4518 are sure the program has no bugs. However, it can be reasonable
4519 to install a stripped executable for actual execution while saving
4520 the unstripped executable elsewhere in case there is a bug.
4523 Delete all files in the current directory that are normally
4524 created by building the program. Also delete files in other
4525 directories if they are created by this makefile. However, don't
4526 delete the files that record the configuration. Also preserve
4527 files that could be made by building, but normally aren't because
4528 the distribution comes with them. There is no need to delete
4529 parent directories that were created with `mkdir -p', since they
4530 could have existed anyway.
4532 Delete `.dvi' files here if they are not part of the distribution.
4535 Delete all files in the current directory (or created by this
4536 makefile) that are created by configuring or building the program.
4537 If you have unpacked the source and built the program without
4538 creating any other files, `make distclean' should leave only the
4539 files that were in the distribution. However, there is no need to
4540 delete parent directories that were created with `mkdir -p', since
4541 they could have existed anyway.
4544 Like `clean', but may refrain from deleting a few files that people
4545 normally don't want to recompile. For example, the `mostlyclean'
4546 target for GCC does not delete `libgcc.a', because recompiling it
4547 is rarely necessary and takes a lot of time.
4550 Delete almost everything that can be reconstructed with this
4551 Makefile. This typically includes everything deleted by
4552 `distclean', plus more: C source files produced by Bison, tags
4553 tables, Info files, and so on.
4555 The reason we say "almost everything" is that running the command
4556 `make maintainer-clean' should not delete `configure' even if
4557 `configure' can be remade using a rule in the Makefile. More
4558 generally, `make maintainer-clean' should not delete anything that
4559 needs to exist in order to run `configure' and then begin to build
4560 the program. Also, there is no need to delete parent directories
4561 that were created with `mkdir -p', since they could have existed
4562 anyway. These are the only exceptions; `maintainer-clean' should
4563 delete everything else that can be rebuilt.
4565 The `maintainer-clean' target is intended to be used by a
4566 maintainer of the package, not by ordinary users. You may need
4567 special tools to reconstruct some of the files that `make
4568 maintainer-clean' deletes. Since these files are normally
4569 included in the distribution, we don't take care to make them easy
4570 to reconstruct. If you find you need to unpack the full
4571 distribution again, don't blame us.
4573 To help make users aware of this, the commands for the special
4574 `maintainer-clean' target should start with these two:
4576 @echo 'This command is intended for maintainers to use; it'
4577 @echo 'deletes files that may need special tools to rebuild.'
4580 Update a tags table for this program.
4583 Generate any Info files needed. The best way to write the rules
4588 foo.info: foo.texi chap1.texi chap2.texi
4589 $(MAKEINFO) $(srcdir)/foo.texi
4591 You must define the variable `MAKEINFO' in the Makefile. It should
4592 run the `makeinfo' program, which is part of the Texinfo
4595 Normally a GNU distribution comes with Info files, and that means
4596 the Info files are present in the source directory. Therefore,
4597 the Make rule for an info file should update it in the source
4598 directory. When users build the package, ordinarily Make will not
4599 update the Info files because they will already be up to date.
4605 Generate documentation files in the given format. These targets
4606 should always exist, but any or all can be a no-op if the given
4607 output format cannot be generated. These targets should not be
4608 dependencies of the `all' target; the user must manually invoke
4611 Here's an example rule for generating DVI files from Texinfo:
4615 foo.dvi: foo.texi chap1.texi chap2.texi
4616 $(TEXI2DVI) $(srcdir)/foo.texi
4618 You must define the variable `TEXI2DVI' in the Makefile. It should
4619 run the program `texi2dvi', which is part of the Texinfo
4620 distribution.(1) Alternatively, write just the dependencies, and
4621 allow GNU `make' to provide the command.
4623 Here's another example, this one for generating HTML from Texinfo:
4627 foo.html: foo.texi chap1.texi chap2.texi
4628 $(TEXI2HTML) $(srcdir)/foo.texi
4630 Again, you would define the variable `TEXI2HTML' in the Makefile;
4631 for example, it might run `makeinfo --no-split --html' (`makeinfo'
4632 is part of the Texinfo distribution).
4635 Create a distribution tar file for this program. The tar file
4636 should be set up so that the file names in the tar file start with
4637 a subdirectory name which is the name of the package it is a
4638 distribution for. This name can include the version number.
4640 For example, the distribution tar file of GCC version 1.40 unpacks
4641 into a subdirectory named `gcc-1.40'.
4643 The easiest way to do this is to create a subdirectory
4644 appropriately named, use `ln' or `cp' to install the proper files
4645 in it, and then `tar' that subdirectory.
4647 Compress the tar file with `gzip'. For example, the actual
4648 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
4650 The `dist' target should explicitly depend on all non-source files
4651 that are in the distribution, to make sure they are up to date in
4652 the distribution. *Note Making Releases: Releases.
4655 Perform self-tests (if any). The user must build the program
4656 before running the tests, but need not install the program; you
4657 should write the self-tests so that they work when the program is
4658 built but not installed.
4660 The following targets are suggested as conventional names, for
4661 programs in which they are useful.
4664 Perform installation tests (if any). The user must build and
4665 install the program before running the tests. You should not
4666 assume that `$(bindir)' is in the search path.
4669 It's useful to add a target named `installdirs' to create the
4670 directories where files are installed, and their parent
4671 directories. There is a script called `mkinstalldirs' which is
4672 convenient for this; you can find it in the Texinfo package. You
4673 can use a rule like this:
4675 # Make sure all installation directories (e.g. $(bindir))
4676 # actually exist by making them if necessary.
4677 installdirs: mkinstalldirs
4678 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
4679 $(libdir) $(infodir) \
4682 or, if you wish to support `DESTDIR',
4684 # Make sure all installation directories (e.g. $(bindir))
4685 # actually exist by making them if necessary.
4686 installdirs: mkinstalldirs
4687 $(srcdir)/mkinstalldirs \
4688 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
4689 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
4692 This rule should not modify the directories where compilation is
4693 done. It should do nothing but create installation directories.
4695 ---------- Footnotes ----------
4697 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
4698 not distributed with Texinfo.
4701 File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
4703 7.2.7 Install Command Categories
4704 --------------------------------
4706 When writing the `install' target, you must classify all the commands
4707 into three categories: normal ones, "pre-installation" commands and
4708 "post-installation" commands.
4710 Normal commands move files into their proper places, and set their
4711 modes. They may not alter any files except the ones that come entirely
4712 from the package they belong to.
4714 Pre-installation and post-installation commands may alter other
4715 files; in particular, they can edit global configuration files or data
4718 Pre-installation commands are typically executed before the normal
4719 commands, and post-installation commands are typically run after the
4722 The most common use for a post-installation command is to run
4723 `install-info'. This cannot be done with a normal command, since it
4724 alters a file (the Info directory) which does not come entirely and
4725 solely from the package being installed. It is a post-installation
4726 command because it needs to be done after the normal command which
4727 installs the package's Info files.
4729 Most programs don't need any pre-installation commands, but we have
4730 the feature just in case it is needed.
4732 To classify the commands in the `install' rule into these three
4733 categories, insert "category lines" among them. A category line
4734 specifies the category for the commands that follow.
4736 A category line consists of a tab and a reference to a special Make
4737 variable, plus an optional comment at the end. There are three
4738 variables you can use, one for each category; the variable name
4739 specifies the category. Category lines are no-ops in ordinary execution
4740 because these three Make variables are normally undefined (and you
4741 _should not_ define them in the makefile).
4743 Here are the three possible category lines, each with a comment that
4744 explains what it means:
4746 $(PRE_INSTALL) # Pre-install commands follow.
4747 $(POST_INSTALL) # Post-install commands follow.
4748 $(NORMAL_INSTALL) # Normal commands follow.
4750 If you don't use a category line at the beginning of the `install'
4751 rule, all the commands are classified as normal until the first category
4752 line. If you don't use any category lines, all the commands are
4753 classified as normal.
4755 These are the category lines for `uninstall':
4757 $(PRE_UNINSTALL) # Pre-uninstall commands follow.
4758 $(POST_UNINSTALL) # Post-uninstall commands follow.
4759 $(NORMAL_UNINSTALL) # Normal commands follow.
4761 Typically, a pre-uninstall command would be used for deleting entries
4762 from the Info directory.
4764 If the `install' or `uninstall' target has any dependencies which
4765 act as subroutines of installation, then you should start _each_
4766 dependency's commands with a category line, and start the main target's
4767 commands with a category line also. This way, you can ensure that each
4768 command is placed in the right category regardless of which of the
4769 dependencies actually run.
4771 Pre-installation and post-installation commands should not run any
4772 programs except for these:
4774 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
4775 egrep expand expr false fgrep find getopt grep gunzip gzip
4776 hostname install install-info kill ldconfig ln ls md5sum
4777 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
4778 test touch true uname xargs yes
4780 The reason for distinguishing the commands in this way is for the
4781 sake of making binary packages. Typically a binary package contains
4782 all the executables and other files that need to be installed, and has
4783 its own method of installing them--so it does not need to run the normal
4784 installation commands. But installing the binary package does need to
4785 execute the pre-installation and post-installation commands.
4787 Programs to build binary packages work by extracting the
4788 pre-installation and post-installation commands. Here is one way of
4789 extracting the pre-installation commands (the `-s' option to `make' is
4790 needed to silence messages about entering subdirectories):
4792 make -s -n install -o all \
4793 PRE_INSTALL=pre-install \
4794 POST_INSTALL=post-install \
4795 NORMAL_INSTALL=normal-install \
4796 | gawk -f pre-install.awk
4798 where the file `pre-install.awk' could contain this:
4800 $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
4802 $0 ~ /^pre-install[ \t]*$/ {on = 1}
4805 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
4810 You should identify each release with a pair of version numbers, a
4811 major version and a minor. We have no objection to using more than two
4812 numbers, but it is very unlikely that you really need them.
4814 Package the distribution of `Foo version 69.96' up in a gzipped tar
4815 file with the name `foo-69.96.tar.gz'. It should unpack into a
4816 subdirectory named `foo-69.96'.
4818 Building and installing the program should never modify any of the
4819 files contained in the distribution. This means that all the files
4820 that form part of the program in any way must be classified into "source
4821 files" and "non-source files". Source files are written by humans and
4822 never changed automatically; non-source files are produced from source
4823 files by programs under the control of the Makefile.
4825 The distribution should contain a file named `README' which gives
4826 the name of the package, and a general description of what it does. It
4827 is also good to explain the purpose of each of the first-level
4828 subdirectories in the package, if there are any. The `README' file
4829 should either state the version number of the package, or refer to where
4830 in the package it can be found.
4832 The `README' file should refer to the file `INSTALL', which should
4833 contain an explanation of the installation procedure.
4835 The `README' file should also refer to the file which contains the
4836 copying conditions. The GNU GPL, if used, should be in a file called
4837 `COPYING'. If the GNU LGPL is used, it should be in a file called
4840 Naturally, all the source files must be in the distribution. It is
4841 okay to include non-source files in the distribution, provided they are
4842 up-to-date and machine-independent, so that building the distribution
4843 normally will never modify them. We commonly include non-source files
4844 produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
4845 unnecessary dependencies between our distributions, so that users can
4846 install whichever packages they want to install.
4848 Non-source files that might actually be modified by building and
4849 installing the program should *never* be included in the distribution.
4850 So if you do distribute non-source files, always make sure they are up
4851 to date when you make a new distribution.
4853 Make sure that all the files in the distribution are world-readable,
4854 and that directories are world-readable and world-searchable (octal
4855 mode 755). We used to recommend that all directories in the
4856 distribution also be world-writable (octal mode 777), because ancient
4857 versions of `tar' would otherwise not cope when extracting the archive
4858 as an unprivileged user. That can easily lead to security issues when
4859 creating the archive, however, so now we recommend against that.
4861 Don't include any symbolic links in the distribution itself. If the
4862 tar file contains symbolic links, then people cannot even unpack it on
4863 systems that don't support symbolic links. Also, don't use multiple
4864 names for one file in different directories, because certain file
4865 systems cannot handle this and that prevents unpacking the distribution.
4867 Try to make sure that all the file names will be unique on MS-DOS. A
4868 name on MS-DOS consists of up to 8 characters, optionally followed by a
4869 period and up to three characters. MS-DOS will truncate extra
4870 characters both before and after the period. Thus, `foobarhacker.c'
4871 and `foobarhacker.o' are not ambiguous; they are truncated to
4872 `foobarha.c' and `foobarha.o', which are distinct.
4874 Include in your distribution a copy of the `texinfo.tex' you used to
4875 test print any `*.texinfo' or `*.texi' files.
4877 Likewise, if your program uses small GNU software packages like
4878 regex, getopt, obstack, or termcap, include them in the distribution
4879 file. Leaving them out would make the distribution file a little
4880 smaller at the expense of possible inconvenience to a user who doesn't
4881 know what other files to get.
4884 File: standards.info, Node: References, Next: GNU Free Documentation License, Prev: Managing Releases, Up: Top
4886 8 References to Non-Free Software and Documentation
4887 ***************************************************
4889 A GNU program should not recommend, promote, or grant legitimacy to the
4890 use of any non-free program. Proprietary software is a social and
4891 ethical problem, and our aim is to put an end to that problem. We
4892 can't stop some people from writing proprietary programs, or stop other
4893 people from using them, but we can and should refuse to advertise them
4894 to new potential customers, or to give the public the idea that their
4895 existence is ethical.
4897 The GNU definition of free software is found on the GNU web site at
4898 `http://www.gnu.org/philosophy/free-sw.html', and the definition of
4899 free documentation is found at
4900 `http://www.gnu.org/philosophy/free-doc.html'. The terms "free" and
4901 "non-free", used in this document, refer to those definitions.
4903 A list of important licenses and whether they qualify as free is in
4904 `http://www.gnu.org/licenses/license-list.html'. If it is not clear
4905 whether a license qualifies as free, please ask the GNU Project by
4906 writing to <licensing@gnu.org>. We will answer, and if the license is
4907 an important one, we will add it to the list.
4909 When a non-free program or system is well known, you can mention it
4910 in passing--that is harmless, since users who might want to use it
4911 probably already know about it. For instance, it is fine to explain
4912 how to build your package on top of some widely used non-free operating
4913 system, or how to use it together with some widely used non-free
4916 However, you should give only the necessary information to help those
4917 who already use the non-free program to use your program with it--don't
4918 give, or refer to, any further information about the proprietary
4919 program, and don't imply that the proprietary program enhances your
4920 program, or that its existence is in any way a good thing. The goal
4921 should be that people already using the proprietary program will get
4922 the advice they need about how to use your free program with it, while
4923 people who don't already use the proprietary program will not see
4924 anything likely to lead them to take an interest in it.
4926 If a non-free program or system is obscure in your program's domain,
4927 your program should not mention or support it at all, since doing so
4928 would tend to popularize the non-free program more than it popularizes
4929 your program. (You cannot hope to find many additional users for your
4930 program among the users of Foobar, if the existence of Foobar is not
4931 generally known among people who might want to use your program.)
4933 Sometimes a program is free software in itself but depends on a
4934 non-free platform in order to run. For instance, many Java programs
4935 depend on some non-free Java libraries. To recommend or promote such a
4936 program is to promote the other programs it needs. This is why we are
4937 careful about listing Java programs in the Free Software Directory: we
4938 don't want to promote the non-free Java libraries.
4940 We hope this particular problem with Java will be gone by and by, as
4941 we replace the remaining non-free standard Java libraries with free
4942 software, but the general principle will remain the same: don't
4943 recommend, promote or legitimize programs that depend on non-free
4946 Some free programs strongly encourage the use of non-free software.
4947 A typical example is `mplayer'. It is free software in itself, and the
4948 free code can handle some kinds of files. However, `mplayer'
4949 recommends use of non-free codecs for other kinds of files, and users
4950 that install `mplayer' are very likely to install those codecs along
4951 with it. To recommend `mplayer' is, in effect, to promote use of the
4954 Thus, you should not recommend programs that strongly encourage the
4955 use of non-free software. This is why we do not list `mplayer' in the
4956 Free Software Directory.
4958 A GNU package should not refer the user to any non-free documentation
4959 for free software. Free documentation that can be included in free
4960 operating systems is essential for completing the GNU system, or any
4961 free operating system, so encouraging it is a priority; to recommend
4962 use of documentation that we are not allowed to include undermines the
4963 impetus for the community to produce documentation that we can include.
4964 So GNU packages should never recommend non-free documentation.
4966 By contrast, it is ok to refer to journal articles and textbooks in
4967 the comments of a program for explanation of how it functions, even
4968 though they are non-free. This is because we don't include such things
4969 in the GNU system even they are free--they are outside the scope of
4970 what a software distribution needs to include.
4972 Referring to a web site that describes or recommends a non-free
4973 program is promoting that program, so please do not make links (or
4974 mention by name) web sites that contain such material. This policy is
4975 relevant particularly for the web pages for a GNU package.
4977 Following links from nearly any web site can lead eventually to
4978 non-free software; this is inherent in the nature of the web. So it
4979 makes no sense to criticize a site for having such links. As long as
4980 the site does not itself recommend a non-free program, there is no need
4981 to consider the question of the sites that it links to for other
4984 Thus, for example, you should not refer to AT&T's web site if that
4985 recommends AT&T's non-free software packages; you should not refer to a
4986 site that links to AT&T's site presenting it as a place to get some
4987 non-free program, because that link recommends and legitimizes the
4988 non-free program. However, that a site contains a link to AT&T's web
4989 site for some other purpose (such as long-distance telephone service)
4990 is not an objection against it.
4993 File: standards.info, Node: GNU Free Documentation License, Next: Index, Prev: References, Up: Top
4995 Appendix A GNU Free Documentation License
4996 *****************************************
4998 Version 1.3, 3 November 2008
5000 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
5003 Everyone is permitted to copy and distribute verbatim copies
5004 of this license document, but changing it is not allowed.
5008 The purpose of this License is to make a manual, textbook, or other
5009 functional and useful document "free" in the sense of freedom: to
5010 assure everyone the effective freedom to copy and redistribute it,
5011 with or without modifying it, either commercially or
5012 noncommercially. Secondarily, this License preserves for the
5013 author and publisher a way to get credit for their work, while not
5014 being considered responsible for modifications made by others.
5016 This License is a kind of "copyleft", which means that derivative
5017 works of the document must themselves be free in the same sense.
5018 It complements the GNU General Public License, which is a copyleft
5019 license designed for free software.
5021 We have designed this License in order to use it for manuals for
5022 free software, because free software needs free documentation: a
5023 free program should come with manuals providing the same freedoms
5024 that the software does. But this License is not limited to
5025 software manuals; it can be used for any textual work, regardless
5026 of subject matter or whether it is published as a printed book.
5027 We recommend this License principally for works whose purpose is
5028 instruction or reference.
5030 1. APPLICABILITY AND DEFINITIONS
5032 This License applies to any manual or other work, in any medium,
5033 that contains a notice placed by the copyright holder saying it
5034 can be distributed under the terms of this License. Such a notice
5035 grants a world-wide, royalty-free license, unlimited in duration,
5036 to use that work under the conditions stated herein. The
5037 "Document", below, refers to any such manual or work. Any member
5038 of the public is a licensee, and is addressed as "you". You
5039 accept the license if you copy, modify or distribute the work in a
5040 way requiring permission under copyright law.
5042 A "Modified Version" of the Document means any work containing the
5043 Document or a portion of it, either copied verbatim, or with
5044 modifications and/or translated into another language.
5046 A "Secondary Section" is a named appendix or a front-matter section
5047 of the Document that deals exclusively with the relationship of the
5048 publishers or authors of the Document to the Document's overall
5049 subject (or to related matters) and contains nothing that could
5050 fall directly within that overall subject. (Thus, if the Document
5051 is in part a textbook of mathematics, a Secondary Section may not
5052 explain any mathematics.) The relationship could be a matter of
5053 historical connection with the subject or with related matters, or
5054 of legal, commercial, philosophical, ethical or political position
5057 The "Invariant Sections" are certain Secondary Sections whose
5058 titles are designated, as being those of Invariant Sections, in
5059 the notice that says that the Document is released under this
5060 License. If a section does not fit the above definition of
5061 Secondary then it is not allowed to be designated as Invariant.
5062 The Document may contain zero Invariant Sections. If the Document
5063 does not identify any Invariant Sections then there are none.
5065 The "Cover Texts" are certain short passages of text that are
5066 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5067 that says that the Document is released under this License. A
5068 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5069 be at most 25 words.
5071 A "Transparent" copy of the Document means a machine-readable copy,
5072 represented in a format whose specification is available to the
5073 general public, that is suitable for revising the document
5074 straightforwardly with generic text editors or (for images
5075 composed of pixels) generic paint programs or (for drawings) some
5076 widely available drawing editor, and that is suitable for input to
5077 text formatters or for automatic translation to a variety of
5078 formats suitable for input to text formatters. A copy made in an
5079 otherwise Transparent file format whose markup, or absence of
5080 markup, has been arranged to thwart or discourage subsequent
5081 modification by readers is not Transparent. An image format is
5082 not Transparent if used for any substantial amount of text. A
5083 copy that is not "Transparent" is called "Opaque".
5085 Examples of suitable formats for Transparent copies include plain
5086 ASCII without markup, Texinfo input format, LaTeX input format,
5087 SGML or XML using a publicly available DTD, and
5088 standard-conforming simple HTML, PostScript or PDF designed for
5089 human modification. Examples of transparent image formats include
5090 PNG, XCF and JPG. Opaque formats include proprietary formats that
5091 can be read and edited only by proprietary word processors, SGML or
5092 XML for which the DTD and/or processing tools are not generally
5093 available, and the machine-generated HTML, PostScript or PDF
5094 produced by some word processors for output purposes only.
5096 The "Title Page" means, for a printed book, the title page itself,
5097 plus such following pages as are needed to hold, legibly, the
5098 material this License requires to appear in the title page. For
5099 works in formats which do not have any title page as such, "Title
5100 Page" means the text near the most prominent appearance of the
5101 work's title, preceding the beginning of the body of the text.
5103 The "publisher" means any person or entity that distributes copies
5104 of the Document to the public.
5106 A section "Entitled XYZ" means a named subunit of the Document
5107 whose title either is precisely XYZ or contains XYZ in parentheses
5108 following text that translates XYZ in another language. (Here XYZ
5109 stands for a specific section name mentioned below, such as
5110 "Acknowledgements", "Dedications", "Endorsements", or "History".)
5111 To "Preserve the Title" of such a section when you modify the
5112 Document means that it remains a section "Entitled XYZ" according
5115 The Document may include Warranty Disclaimers next to the notice
5116 which states that this License applies to the Document. These
5117 Warranty Disclaimers are considered to be included by reference in
5118 this License, but only as regards disclaiming warranties: any other
5119 implication that these Warranty Disclaimers may have is void and
5120 has no effect on the meaning of this License.
5124 You may copy and distribute the Document in any medium, either
5125 commercially or noncommercially, provided that this License, the
5126 copyright notices, and the license notice saying this License
5127 applies to the Document are reproduced in all copies, and that you
5128 add no other conditions whatsoever to those of this License. You
5129 may not use technical measures to obstruct or control the reading
5130 or further copying of the copies you make or distribute. However,
5131 you may accept compensation in exchange for copies. If you
5132 distribute a large enough number of copies you must also follow
5133 the conditions in section 3.
5135 You may also lend copies, under the same conditions stated above,
5136 and you may publicly display copies.
5138 3. COPYING IN QUANTITY
5140 If you publish printed copies (or copies in media that commonly
5141 have printed covers) of the Document, numbering more than 100, and
5142 the Document's license notice requires Cover Texts, you must
5143 enclose the copies in covers that carry, clearly and legibly, all
5144 these Cover Texts: Front-Cover Texts on the front cover, and
5145 Back-Cover Texts on the back cover. Both covers must also clearly
5146 and legibly identify you as the publisher of these copies. The
5147 front cover must present the full title with all words of the
5148 title equally prominent and visible. You may add other material
5149 on the covers in addition. Copying with changes limited to the
5150 covers, as long as they preserve the title of the Document and
5151 satisfy these conditions, can be treated as verbatim copying in
5154 If the required texts for either cover are too voluminous to fit
5155 legibly, you should put the first ones listed (as many as fit
5156 reasonably) on the actual cover, and continue the rest onto
5159 If you publish or distribute Opaque copies of the Document
5160 numbering more than 100, you must either include a
5161 machine-readable Transparent copy along with each Opaque copy, or
5162 state in or with each Opaque copy a computer-network location from
5163 which the general network-using public has access to download
5164 using public-standard network protocols a complete Transparent
5165 copy of the Document, free of added material. If you use the
5166 latter option, you must take reasonably prudent steps, when you
5167 begin distribution of Opaque copies in quantity, to ensure that
5168 this Transparent copy will remain thus accessible at the stated
5169 location until at least one year after the last time you
5170 distribute an Opaque copy (directly or through your agents or
5171 retailers) of that edition to the public.
5173 It is requested, but not required, that you contact the authors of
5174 the Document well before redistributing any large number of
5175 copies, to give them a chance to provide you with an updated
5176 version of the Document.
5180 You may copy and distribute a Modified Version of the Document
5181 under the conditions of sections 2 and 3 above, provided that you
5182 release the Modified Version under precisely this License, with
5183 the Modified Version filling the role of the Document, thus
5184 licensing distribution and modification of the Modified Version to
5185 whoever possesses a copy of it. In addition, you must do these
5186 things in the Modified Version:
5188 A. Use in the Title Page (and on the covers, if any) a title
5189 distinct from that of the Document, and from those of
5190 previous versions (which should, if there were any, be listed
5191 in the History section of the Document). You may use the
5192 same title as a previous version if the original publisher of
5193 that version gives permission.
5195 B. List on the Title Page, as authors, one or more persons or
5196 entities responsible for authorship of the modifications in
5197 the Modified Version, together with at least five of the
5198 principal authors of the Document (all of its principal
5199 authors, if it has fewer than five), unless they release you
5200 from this requirement.
5202 C. State on the Title page the name of the publisher of the
5203 Modified Version, as the publisher.
5205 D. Preserve all the copyright notices of the Document.
5207 E. Add an appropriate copyright notice for your modifications
5208 adjacent to the other copyright notices.
5210 F. Include, immediately after the copyright notices, a license
5211 notice giving the public permission to use the Modified
5212 Version under the terms of this License, in the form shown in
5215 G. Preserve in that license notice the full lists of Invariant
5216 Sections and required Cover Texts given in the Document's
5219 H. Include an unaltered copy of this License.
5221 I. Preserve the section Entitled "History", Preserve its Title,
5222 and add to it an item stating at least the title, year, new
5223 authors, and publisher of the Modified Version as given on
5224 the Title Page. If there is no section Entitled "History" in
5225 the Document, create one stating the title, year, authors,
5226 and publisher of the Document as given on its Title Page,
5227 then add an item describing the Modified Version as stated in
5228 the previous sentence.
5230 J. Preserve the network location, if any, given in the Document
5231 for public access to a Transparent copy of the Document, and
5232 likewise the network locations given in the Document for
5233 previous versions it was based on. These may be placed in
5234 the "History" section. You may omit a network location for a
5235 work that was published at least four years before the
5236 Document itself, or if the original publisher of the version
5237 it refers to gives permission.
5239 K. For any section Entitled "Acknowledgements" or "Dedications",
5240 Preserve the Title of the section, and preserve in the
5241 section all the substance and tone of each of the contributor
5242 acknowledgements and/or dedications given therein.
5244 L. Preserve all the Invariant Sections of the Document,
5245 unaltered in their text and in their titles. Section numbers
5246 or the equivalent are not considered part of the section
5249 M. Delete any section Entitled "Endorsements". Such a section
5250 may not be included in the Modified Version.
5252 N. Do not retitle any existing section to be Entitled
5253 "Endorsements" or to conflict in title with any Invariant
5256 O. Preserve any Warranty Disclaimers.
5258 If the Modified Version includes new front-matter sections or
5259 appendices that qualify as Secondary Sections and contain no
5260 material copied from the Document, you may at your option
5261 designate some or all of these sections as invariant. To do this,
5262 add their titles to the list of Invariant Sections in the Modified
5263 Version's license notice. These titles must be distinct from any
5264 other section titles.
5266 You may add a section Entitled "Endorsements", provided it contains
5267 nothing but endorsements of your Modified Version by various
5268 parties--for example, statements of peer review or that the text
5269 has been approved by an organization as the authoritative
5270 definition of a standard.
5272 You may add a passage of up to five words as a Front-Cover Text,
5273 and a passage of up to 25 words as a Back-Cover Text, to the end
5274 of the list of Cover Texts in the Modified Version. Only one
5275 passage of Front-Cover Text and one of Back-Cover Text may be
5276 added by (or through arrangements made by) any one entity. If the
5277 Document already includes a cover text for the same cover,
5278 previously added by you or by arrangement made by the same entity
5279 you are acting on behalf of, you may not add another; but you may
5280 replace the old one, on explicit permission from the previous
5281 publisher that added the old one.
5283 The author(s) and publisher(s) of the Document do not by this
5284 License give permission to use their names for publicity for or to
5285 assert or imply endorsement of any Modified Version.
5287 5. COMBINING DOCUMENTS
5289 You may combine the Document with other documents released under
5290 this License, under the terms defined in section 4 above for
5291 modified versions, provided that you include in the combination
5292 all of the Invariant Sections of all of the original documents,
5293 unmodified, and list them all as Invariant Sections of your
5294 combined work in its license notice, and that you preserve all
5295 their Warranty Disclaimers.
5297 The combined work need only contain one copy of this License, and
5298 multiple identical Invariant Sections may be replaced with a single
5299 copy. If there are multiple Invariant Sections with the same name
5300 but different contents, make the title of each such section unique
5301 by adding at the end of it, in parentheses, the name of the
5302 original author or publisher of that section if known, or else a
5303 unique number. Make the same adjustment to the section titles in
5304 the list of Invariant Sections in the license notice of the
5307 In the combination, you must combine any sections Entitled
5308 "History" in the various original documents, forming one section
5309 Entitled "History"; likewise combine any sections Entitled
5310 "Acknowledgements", and any sections Entitled "Dedications". You
5311 must delete all sections Entitled "Endorsements."
5313 6. COLLECTIONS OF DOCUMENTS
5315 You may make a collection consisting of the Document and other
5316 documents released under this License, and replace the individual
5317 copies of this License in the various documents with a single copy
5318 that is included in the collection, provided that you follow the
5319 rules of this License for verbatim copying of each of the
5320 documents in all other respects.
5322 You may extract a single document from such a collection, and
5323 distribute it individually under this License, provided you insert
5324 a copy of this License into the extracted document, and follow
5325 this License in all other respects regarding verbatim copying of
5328 7. AGGREGATION WITH INDEPENDENT WORKS
5330 A compilation of the Document or its derivatives with other
5331 separate and independent documents or works, in or on a volume of
5332 a storage or distribution medium, is called an "aggregate" if the
5333 copyright resulting from the compilation is not used to limit the
5334 legal rights of the compilation's users beyond what the individual
5335 works permit. When the Document is included in an aggregate, this
5336 License does not apply to the other works in the aggregate which
5337 are not themselves derivative works of the Document.
5339 If the Cover Text requirement of section 3 is applicable to these
5340 copies of the Document, then if the Document is less than one half
5341 of the entire aggregate, the Document's Cover Texts may be placed
5342 on covers that bracket the Document within the aggregate, or the
5343 electronic equivalent of covers if the Document is in electronic
5344 form. Otherwise they must appear on printed covers that bracket
5345 the whole aggregate.
5349 Translation is considered a kind of modification, so you may
5350 distribute translations of the Document under the terms of section
5351 4. Replacing Invariant Sections with translations requires special
5352 permission from their copyright holders, but you may include
5353 translations of some or all Invariant Sections in addition to the
5354 original versions of these Invariant Sections. You may include a
5355 translation of this License, and all the license notices in the
5356 Document, and any Warranty Disclaimers, provided that you also
5357 include the original English version of this License and the
5358 original versions of those notices and disclaimers. In case of a
5359 disagreement between the translation and the original version of
5360 this License or a notice or disclaimer, the original version will
5363 If a section in the Document is Entitled "Acknowledgements",
5364 "Dedications", or "History", the requirement (section 4) to
5365 Preserve its Title (section 1) will typically require changing the
5370 You may not copy, modify, sublicense, or distribute the Document
5371 except as expressly provided under this License. Any attempt
5372 otherwise to copy, modify, sublicense, or distribute it is void,
5373 and will automatically terminate your rights under this License.
5375 However, if you cease all violation of this License, then your
5376 license from a particular copyright holder is reinstated (a)
5377 provisionally, unless and until the copyright holder explicitly
5378 and finally terminates your license, and (b) permanently, if the
5379 copyright holder fails to notify you of the violation by some
5380 reasonable means prior to 60 days after the cessation.
5382 Moreover, your license from a particular copyright holder is
5383 reinstated permanently if the copyright holder notifies you of the
5384 violation by some reasonable means, this is the first time you have
5385 received notice of violation of this License (for any work) from
5386 that copyright holder, and you cure the violation prior to 30 days
5387 after your receipt of the notice.
5389 Termination of your rights under this section does not terminate
5390 the licenses of parties who have received copies or rights from
5391 you under this License. If your rights have been terminated and
5392 not permanently reinstated, receipt of a copy of some or all of
5393 the same material does not give you any rights to use it.
5395 10. FUTURE REVISIONS OF THIS LICENSE
5397 The Free Software Foundation may publish new, revised versions of
5398 the GNU Free Documentation License from time to time. Such new
5399 versions will be similar in spirit to the present version, but may
5400 differ in detail to address new problems or concerns. See
5401 `http://www.gnu.org/copyleft/'.
5403 Each version of the License is given a distinguishing version
5404 number. If the Document specifies that a particular numbered
5405 version of this License "or any later version" applies to it, you
5406 have the option of following the terms and conditions either of
5407 that specified version or of any later version that has been
5408 published (not as a draft) by the Free Software Foundation. If
5409 the Document does not specify a version number of this License,
5410 you may choose any version ever published (not as a draft) by the
5411 Free Software Foundation. If the Document specifies that a proxy
5412 can decide which future versions of this License can be used, that
5413 proxy's public statement of acceptance of a version permanently
5414 authorizes you to choose that version for the Document.
5418 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
5419 World Wide Web server that publishes copyrightable works and also
5420 provides prominent facilities for anybody to edit those works. A
5421 public wiki that anybody can edit is an example of such a server.
5422 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
5423 site means any set of copyrightable works thus published on the MMC
5426 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
5427 license published by Creative Commons Corporation, a not-for-profit
5428 corporation with a principal place of business in San Francisco,
5429 California, as well as future copyleft versions of that license
5430 published by that same organization.
5432 "Incorporate" means to publish or republish a Document, in whole or
5433 in part, as part of another Document.
5435 An MMC is "eligible for relicensing" if it is licensed under this
5436 License, and if all works that were first published under this
5437 License somewhere other than this MMC, and subsequently
5438 incorporated in whole or in part into the MMC, (1) had no cover
5439 texts or invariant sections, and (2) were thus incorporated prior
5440 to November 1, 2008.
5442 The operator of an MMC Site may republish an MMC contained in the
5443 site under CC-BY-SA on the same site at any time before August 1,
5444 2009, provided the MMC is eligible for relicensing.
5447 ADDENDUM: How to use this License for your documents
5448 ====================================================
5450 To use this License in a document you have written, include a copy of
5451 the License in the document and put the following copyright and license
5452 notices just after the title page:
5454 Copyright (C) YEAR YOUR NAME.
5455 Permission is granted to copy, distribute and/or modify this document
5456 under the terms of the GNU Free Documentation License, Version 1.3
5457 or any later version published by the Free Software Foundation;
5458 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5459 Texts. A copy of the license is included in the section entitled ``GNU
5460 Free Documentation License''.
5462 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5463 Texts, replace the "with...Texts." line with this:
5465 with the Invariant Sections being LIST THEIR TITLES, with
5466 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5469 If you have Invariant Sections without Cover Texts, or some other
5470 combination of the three, merge those two alternatives to suit the
5473 If your document contains nontrivial examples of program code, we
5474 recommend releasing these examples in parallel under your choice of
5475 free software license, such as the GNU General Public License, to
5476 permit their use in free software.
5479 File: standards.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
5487 * #endif, commenting: Comments. (line 60)
5488 * --help output: --help. (line 6)
5489 * --version output: --version. (line 6)
5490 * -Wall compiler option: Syntactic Conventions.
5492 * accepting contributions: Contributions. (line 6)
5493 * address for bug reports: --help. (line 11)
5494 * ANSI C standard: Standard C. (line 6)
5495 * arbitrary limits on data: Semantics. (line 6)
5496 * ASCII characters: Character Set. (line 6)
5497 * autoconf: System Portability. (line 23)
5498 * avoiding proprietary code: Reading Non-Free Code.
5500 * behavior, dependent on program's name: User Interfaces. (line 6)
5501 * binary packages: Install Command Categories.
5503 * bindir: Directory Variables. (line 54)
5504 * braces, in C source: Formatting. (line 6)
5505 * bug reports: --help. (line 11)
5506 * bug-standards@gnu.org email address: Preface. (line 30)
5507 * canonical name of a program: --version. (line 12)
5508 * casting pointers to integers: CPU Portability. (line 89)
5509 * CGI programs, standard options for: Command-Line Interfaces.
5511 * change logs: Change Logs. (line 6)
5512 * change logs, conditional changes: Conditional Changes. (line 6)
5513 * change logs, style: Style of Change Logs.
5515 * character set: Character Set. (line 6)
5516 * command-line arguments, decoding: Semantics. (line 46)
5517 * command-line interface: Command-Line Interfaces.
5519 * commenting: Comments. (line 6)
5520 * compatibility with C and POSIX standards: Compatibility. (line 6)
5521 * compiler warnings: Syntactic Conventions.
5523 * conditional changes, and change logs: Conditional Changes. (line 6)
5524 * conditionals, comments for: Comments. (line 60)
5525 * configure: Configuration. (line 6)
5526 * control-L: Formatting. (line 118)
5527 * conventions for makefiles: Makefile Conventions.
5529 * CORBA: Graphical Interfaces.
5531 * credits for manuals: Manual Credits. (line 6)
5532 * D-bus: Graphical Interfaces.
5534 * data types, and portability: CPU Portability. (line 6)
5535 * declaration for system functions: System Functions. (line 21)
5536 * DESTDIR: DESTDIR. (line 6)
5537 * documentation: Documentation. (line 6)
5538 * doschk: Names. (line 38)
5539 * downloading this manual: Preface. (line 14)
5540 * encodings: Character Set. (line 6)
5541 * error messages: Semantics. (line 19)
5542 * error messages, formatting: Errors. (line 6)
5543 * exec_prefix: Directory Variables. (line 36)
5544 * expressions, splitting: Formatting. (line 81)
5545 * FDL, GNU Free Documentation License: GNU Free Documentation License.
5547 * file usage: File Usage. (line 6)
5548 * file-name limitations: Names. (line 38)
5549 * formatting error messages: Errors. (line 6)
5550 * formatting source code: Formatting. (line 6)
5551 * formfeed: Formatting. (line 118)
5552 * function argument, declaring: Syntactic Conventions.
5554 * function prototypes: Standard C. (line 17)
5555 * getopt: Command-Line Interfaces.
5557 * gettext: Internationalization.
5559 * GNOME: Graphical Interfaces.
5561 * GNOME and Guile: Source Language. (line 38)
5562 * gnustandards project repository: Preface. (line 30)
5563 * gnustandards-commit@gnu.org mailing list: Preface. (line 24)
5564 * graphical user interface: Graphical Interfaces.
5566 * grave accent: Quote Characters. (line 6)
5567 * GTK+: Graphical Interfaces.
5569 * Guile: Source Language. (line 38)
5570 * implicit int: Syntactic Conventions.
5572 * impossible conditions: Semantics. (line 70)
5573 * installations, staged: DESTDIR. (line 6)
5574 * interface styles: Graphical Interfaces.
5576 * internationalization: Internationalization.
5578 * keyboard interface: Graphical Interfaces.
5580 * LDAP: OID Allocations. (line 6)
5581 * left quote: Quote Characters. (line 6)
5582 * legal aspects: Legal Issues. (line 6)
5583 * legal papers: Contributions. (line 6)
5584 * libexecdir: Directory Variables. (line 67)
5585 * libraries: Libraries. (line 6)
5586 * library functions, and portability: System Functions. (line 6)
5587 * library interface: Graphical Interfaces.
5589 * license for manuals: License for Manuals. (line 6)
5590 * lint: Syntactic Conventions.
5592 * locale-specific quote characters: Quote Characters. (line 6)
5593 * long option names: Option Table. (line 6)
5594 * long-named options: Command-Line Interfaces.
5596 * makefile, conventions for: Makefile Conventions.
5598 * malloc return value: Semantics. (line 25)
5599 * man pages: Man Pages. (line 6)
5600 * manual structure: Manual Structure Details.
5602 * memory allocation failure: Semantics. (line 25)
5603 * memory usage: Memory Usage. (line 6)
5604 * message text, and internationalization: Internationalization.
5606 * mmap: Mmap. (line 6)
5607 * multiple variables in a line: Syntactic Conventions.
5609 * names of variables, functions, and files: Names. (line 6)
5610 * NEWS file: NEWS File. (line 6)
5611 * non-ASCII characters: Character Set. (line 6)
5612 * non-POSIX systems, and portability: System Portability. (line 32)
5613 * non-standard extensions: Using Extensions. (line 6)
5614 * NUL characters: Semantics. (line 11)
5615 * OID allocations for GNU: OID Allocations. (line 6)
5616 * open brace: Formatting. (line 6)
5617 * optional features, configure-time: Configuration. (line 100)
5618 * options for compatibility: Compatibility. (line 14)
5619 * options, standard command-line: Command-Line Interfaces.
5621 * output device and program's behavior: User Interfaces. (line 13)
5622 * packaging: Releases. (line 6)
5623 * PATH_INFO, specifying standard options as: Command-Line Interfaces.
5625 * portability, and data types: CPU Portability. (line 6)
5626 * portability, and library functions: System Functions. (line 6)
5627 * portability, between system types: System Portability. (line 6)
5628 * POSIX compatibility: Compatibility. (line 6)
5629 * POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
5630 * post-installation commands: Install Command Categories.
5632 * pre-installation commands: Install Command Categories.
5634 * prefix: Directory Variables. (line 26)
5635 * program configuration: Configuration. (line 6)
5636 * program design: Design Advice. (line 6)
5637 * program name and its behavior: User Interfaces. (line 6)
5638 * program's canonical name: --version. (line 12)
5639 * programming languages: Source Language. (line 6)
5640 * proprietary programs: Reading Non-Free Code.
5642 * quote characters: Quote Characters. (line 6)
5643 * README file: Releases. (line 21)
5644 * references to non-free material: References. (line 6)
5645 * releasing: Managing Releases. (line 6)
5646 * Savannah repository for gnustandards: Preface. (line 30)
5647 * sbindir: Directory Variables. (line 60)
5648 * signal handling: Semantics. (line 59)
5649 * SNMP: OID Allocations. (line 6)
5650 * spaces before open-paren: Formatting. (line 75)
5651 * staged installs: DESTDIR. (line 6)
5652 * standard command-line options: Command-Line Interfaces.
5654 * standards for makefiles: Makefile Conventions.
5656 * string library functions: System Functions. (line 55)
5657 * syntactic conventions: Syntactic Conventions.
5659 * table of long options: Option Table. (line 6)
5660 * temporary files: Semantics. (line 84)
5661 * temporary variables: Syntactic Conventions.
5663 * texinfo.tex, in a distribution: Releases. (line 70)
5664 * TMPDIR environment variable: Semantics. (line 84)
5665 * trademarks: Trademarks. (line 6)
5666 * user interface styles: Graphical Interfaces.
5668 * where to obtain standards.texi: Preface. (line 14)
5669 * X.509: OID Allocations. (line 6)
5675 Node: Preface
\x7f2089
5676 Node: Legal Issues
\x7f4802
5677 Node: Reading Non-Free Code
\x7f5272
5678 Node: Contributions
\x7f7002
5679 Node: Trademarks
\x7f9240
5680 Node: Design Advice
\x7f10875
5681 Node: Source Language
\x7f11467
5682 Node: Compatibility
\x7f13593
5683 Node: Using Extensions
\x7f15221
5684 Node: Standard C
\x7f16797
5685 Node: Conditional Compilation
\x7f19200
5686 Node: Program Behavior
\x7f20598
5687 Node: Non-GNU Standards
\x7f21714
5688 Node: Semantics
\x7f23995
5689 Node: Libraries
\x7f28715
5690 Node: Errors
\x7f29960
5691 Node: User Interfaces
\x7f32453
5692 Node: Graphical Interfaces
\x7f34058
5693 Node: Command-Line Interfaces
\x7f35242
5694 Node: --version
\x7f37274
5695 Node: --help
\x7f43011
5696 Node: Option Table
\x7f43884
5697 Node: OID Allocations
\x7f58839
5698 Node: Memory Usage
\x7f60636
5699 Node: File Usage
\x7f61672
5700 Node: Writing C
\x7f62422
5701 Node: Formatting
\x7f63394
5702 Node: Comments
\x7f67683
5703 Node: Syntactic Conventions
\x7f71235
5704 Node: Names
\x7f74697
5705 Node: System Portability
\x7f76909
5706 Node: CPU Portability
\x7f79800
5707 Node: System Functions
\x7f83701
5708 Node: Internationalization
\x7f88898
5709 Node: Character Set
\x7f92892
5710 Node: Quote Characters
\x7f93705
5712 Node: Documentation
\x7f95933
5713 Node: GNU Manuals
\x7f97039
5714 Node: Doc Strings and Manuals
\x7f102777
5715 Node: Manual Structure Details
\x7f104330
5716 Node: License for Manuals
\x7f105748
5717 Node: Manual Credits
\x7f106722
5718 Node: Printed Manuals
\x7f107115
5719 Node: NEWS File
\x7f107801
5720 Node: Change Logs
\x7f108479
5721 Node: Change Log Concepts
\x7f109233
5722 Node: Style of Change Logs
\x7f111336
5723 Node: Simple Changes
\x7f113836
5724 Node: Conditional Changes
\x7f115278
5725 Node: Indicating the Part Changed
\x7f116700
5726 Node: Man Pages
\x7f117227
5727 Node: Reading other Manuals
\x7f119433
5728 Node: Managing Releases
\x7f120224
5729 Node: Configuration
\x7f121005
5730 Node: Makefile Conventions
\x7f129670
5731 Node: Makefile Basics
\x7f130552
5732 Node: Utilities in Makefiles
\x7f133726
5733 Node: Command Variables
\x7f135871
5734 Node: DESTDIR
\x7f139093
5735 Node: Directory Variables
\x7f141242
5736 Node: Standard Targets
\x7f155735
5737 Ref: Standard Targets-Footnote-1
\x7f169250
5738 Node: Install Command Categories
\x7f169350
5739 Node: Releases
\x7f173883
5740 Node: References
\x7f177888
5741 Node: GNU Free Documentation License
\x7f183735
5742 Node: Index
\x7f208902