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 November 15, 2006.
11 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
12 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
18 Texts. A copy of the license is included in the section entitled "GNU
19 Free Documentation License".
22 File: standards.info, Node: Top, Next: Preface, Prev: (dir), Up: (dir)
27 The GNU coding standards, last updated November 15, 2006.
29 Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
30 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.2 or
34 any later version published by the Free Software Foundation; with no
35 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
36 Texts. A copy of the license is included in the section entitled "GNU
37 Free Documentation License".
41 * Preface:: About the GNU Coding Standards
42 * Legal Issues:: Keeping Free Software Free
43 * Design Advice:: General Program Design
44 * Program Behavior:: Program Behavior for All Programs
45 * Writing C:: Making The Best Use of C
46 * Documentation:: Documenting Programs
47 * Managing Releases:: The Release Process
48 * References:: References to Non-Free Software or Documentation
49 * Copying This Manual:: How to Make Copies of This Manual
53 File: standards.info, Node: Preface, Next: Legal Issues, Prev: Top, Up: Top
55 1 About the GNU Coding Standards
56 ********************************
58 The GNU Coding Standards were written by Richard Stallman and other GNU
59 Project volunteers. Their purpose is to make the GNU system clean,
60 consistent, and easy to install. This document can also be read as a
61 guide to writing portable, robust and reliable programs. It focuses on
62 programs written in C, but many of the rules and principles are useful
63 even if you write in another programming language. The rules often
64 state reasons for writing in a certain way.
66 This release of the GNU Coding Standards was last updated November
69 If you did not obtain this file directly from the GNU project and
70 recently, please check for a newer version. You can get the GNU Coding
71 Standards from the GNU web server in many different formats, including
72 the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
73 `http://www.gnu.org/prep/standards/'.
75 Corrections or suggestions for this document should be sent to
76 <bug-standards@gnu.org>. If you make a suggestion, please include a
77 suggested new wording for it; our time is limited. We prefer a context
78 diff to the `standards.texi' or `make-stds.texi' files, but if you
79 don't have those files, please mail your suggestion anyway.
81 These standards cover the minimum of what is important when writing a
82 GNU package. Likely, the needs for additional standards will come up.
83 Sometimes, you might suggest that such standards be added to this
84 document. If you think your standards would be generally useful, please
87 You should also set standards for your package on many questions not
88 addressed or not firmly specified here. The most important point is to
89 be self-consistent--try to stick to the conventions you pick, and try
90 to document them as much as possible. That way, your program will be
91 more maintainable by others.
93 The GNU Hello program serves as an example of how to follow the GNU
94 coding standards for a trivial program.
95 `http://www.gnu.org/software/hello/hello.html'.
98 File: standards.info, Node: Legal Issues, Next: Design Advice, Prev: Preface, Up: Top
100 2 Keeping Free Software Free
101 ****************************
103 This chapter discusses how you can make sure that GNU software avoids
104 legal difficulties, and other related issues.
108 * Reading Non-Free Code:: Referring to Proprietary Programs
109 * Contributions:: Accepting Contributions
110 * Trademarks:: How We Deal with Trademark Issues
113 File: standards.info, Node: Reading Non-Free Code, Next: Contributions, Up: Legal Issues
115 2.1 Referring to Proprietary Programs
116 =====================================
118 Don't in any circumstances refer to Unix source code for or during your
119 work on GNU! (Or to any other proprietary programs.)
121 If you have a vague recollection of the internals of a Unix program,
122 this does not absolutely mean you can't write an imitation of it, but
123 do try to organize the imitation internally along different lines,
124 because this is likely to make the details of the Unix version
125 irrelevant and dissimilar to your results.
127 For example, Unix utilities were generally optimized to minimize
128 memory use; if you go for speed instead, your program will be very
129 different. You could keep the entire input file in memory and scan it
130 there instead of using stdio. Use a smarter algorithm discovered more
131 recently than the Unix program. Eliminate use of temporary files. Do
132 it in one pass instead of two (we did this in the assembler).
134 Or, on the contrary, emphasize simplicity instead of speed. For some
135 applications, the speed of today's computers makes simpler algorithms
138 Or go for generality. For example, Unix programs often have static
139 tables or fixed-size strings, which make for arbitrary limits; use
140 dynamic allocation instead. Make sure your program handles NULs and
141 other funny characters in the input files. Add a programming language
142 for extensibility and write part of the program in that language.
144 Or turn some parts of the program into independently usable
145 libraries. Or use a simple garbage collector instead of tracking
146 precisely when to free memory, or use a new GNU facility such as
150 File: standards.info, Node: Contributions, Next: Trademarks, Prev: Reading Non-Free Code, Up: Legal Issues
152 2.2 Accepting Contributions
153 ===========================
155 If the program you are working on is copyrighted by the Free Software
156 Foundation, then when someone else sends you a piece of code to add to
157 the program, we need legal papers to use it--just as we asked you to
158 sign papers initially. _Each_ person who makes a nontrivial
159 contribution to a program must sign some sort of legal papers in order
160 for us to have clear title to the program; the main author alone is not
163 So, before adding in any contributions from other people, please tell
164 us, so we can arrange to get the papers. Then wait until we tell you
165 that we have received the signed papers, before you actually use the
168 This applies both before you release the program and afterward. If
169 you receive diffs to fix a bug, and they make significant changes, we
170 need legal papers for that change.
172 This also applies to comments and documentation files. For copyright
173 law, comments and code are just text. Copyright applies to all kinds of
174 text, so we need legal papers for all kinds.
176 We know it is frustrating to ask for legal papers; it's frustrating
177 for us as well. But if you don't wait, you are going out on a limb--for
178 example, what if the contributor's employer won't sign a disclaimer?
179 You might have to take that code out again!
181 You don't need papers for changes of a few lines here or there, since
182 they are not significant for copyright purposes. Also, you don't need
183 papers if all you get from the suggestion is some ideas, not actual code
184 which you use. For example, if someone sent you one implementation, but
185 you write a different implementation of the same idea, you don't need to
188 The very worst thing is if you forget to tell us about the other
189 contributor. We could be very embarrassed in court some day as a
192 We have more detailed advice for maintainers of programs; if you have
193 reached the stage of actually maintaining a program for GNU (whether
194 released or not), please ask us for a copy. It is also available
195 online for your perusal: `http://www.gnu.org/prep/maintain/'.
198 File: standards.info, Node: Trademarks, Prev: Contributions, Up: Legal Issues
203 Please do not include any trademark acknowledgements in GNU software
204 packages or documentation.
206 Trademark acknowledgements are the statements that such-and-such is a
207 trademark of so-and-so. The GNU Project has no objection to the basic
208 idea of trademarks, but these acknowledgements feel like kowtowing, and
209 there is no legal requirement for them, so we don't use them.
211 What is legally required, as regards other people's trademarks, is to
212 avoid using them in ways which a reader might reasonably understand as
213 naming or labeling our own programs or activities. For example, since
214 "Objective C" is (or at least was) a trademark, we made sure to say
215 that we provide a "compiler for the Objective C language" rather than
216 an "Objective C compiler". The latter would have been meant as a
217 shorter way of saying the former, but it does not explicitly state the
218 relationship, so it could be misinterpreted as using "Objective C" as a
219 label for the compiler rather than for the language.
221 Please don't use "win" as an abbreviation for Microsoft Windows in
222 GNU software or documentation. In hacker terminology, calling
223 something a "win" is a form of praise. If you wish to praise Microsoft
224 Windows when speaking on your own, by all means do so, but not in GNU
225 software. Usually we write the name "Windows" in full, but when
226 brevity is very important (as in file names and sometimes symbol
227 names), we abbreviate it to "w". For instance, the files and functions
228 in Emacs that deal with Windows start with `w32'.
231 File: standards.info, Node: Design Advice, Next: Program Behavior, Prev: Legal Issues, Up: Top
233 3 General Program Design
234 ************************
236 This chapter discusses some of the issues you should take into account
237 when designing your program.
241 * Source Language:: Which languages to use.
242 * Compatibility:: Compatibility with other implementations
243 * Using Extensions:: Using non-standard features
244 * Standard C:: Using Standard C features
245 * Conditional Compilation:: Compiling Code Only If A Conditional is True
248 File: standards.info, Node: Source Language, Next: Compatibility, Up: Design Advice
250 3.1 Which Languages to Use
251 ==========================
253 When you want to use a language that gets compiled and runs at high
254 speed, the best language to use is C. Using another language is like
255 using a non-standard feature: it will cause trouble for users. Even if
256 GCC supports the other language, users may find it inconvenient to have
257 to install the compiler for that other language in order to build your
258 program. For example, if you write your program in C++, people will
259 have to install the GNU C++ compiler in order to compile your program.
261 C has one other advantage over C++ and other compiled languages: more
262 people know C, so more people will find it easy to read and modify the
263 program if it is written in C.
265 So in general it is much better to use C, rather than the comparable
268 But there are two exceptions to that conclusion:
270 * It is no problem to use another language to write a tool
271 specifically intended for use with that language. That is because
272 the only people who want to build the tool will be those who have
273 installed the other language anyway.
275 * If an application is of interest only to a narrow part of the
276 community, then the question of which language it is written in
277 has less effect on other people, so you may as well please
280 Many programs are designed to be extensible: they include an
281 interpreter for a language that is higher level than C. Often much of
282 the program is written in that language, too. The Emacs editor
283 pioneered this technique.
285 The standard extensibility interpreter for GNU software is GUILE
286 (`http://www.gnu.org/software/guile/'), which implements the language
287 Scheme (an especially clean and simple dialect of Lisp). We don't
288 reject programs written in other "scripting languages" such as Perl and
289 Python, but using GUILE is very important for the overall consistency
293 File: standards.info, Node: Compatibility, Next: Using Extensions, Prev: Source Language, Up: Design Advice
295 3.2 Compatibility with Other Implementations
296 ============================================
298 With occasional exceptions, utility programs and libraries for GNU
299 should be upward compatible with those in Berkeley Unix, and upward
300 compatible with Standard C if Standard C specifies their behavior, and
301 upward compatible with POSIX if POSIX specifies their behavior.
303 When these standards conflict, it is useful to offer compatibility
304 modes for each of them.
306 Standard C and POSIX prohibit many kinds of extensions. Feel free
307 to make the extensions anyway, and include a `--ansi', `--posix', or
308 `--compatible' option to turn them off. However, if the extension has
309 a significant chance of breaking any real programs or scripts, then it
310 is not really upward compatible. So you should try to redesign its
311 interface to make it upward compatible.
313 Many GNU programs suppress extensions that conflict with POSIX if the
314 environment variable `POSIXLY_CORRECT' is defined (even if it is
315 defined with a null value). Please make your program recognize this
316 variable if appropriate.
318 When a feature is used only by users (not by programs or command
319 files), and it is done poorly in Unix, feel free to replace it
320 completely with something totally different and better. (For example,
321 `vi' is replaced with Emacs.) But it is nice to offer a compatible
322 feature as well. (There is a free `vi' clone, so we offer it.)
324 Additional useful features are welcome regardless of whether there
325 is any precedent for them.
328 File: standards.info, Node: Using Extensions, Next: Standard C, Prev: Compatibility, Up: Design Advice
330 3.3 Using Non-standard Features
331 ===============================
333 Many GNU facilities that already exist support a number of convenient
334 extensions over the comparable Unix facilities. Whether to use these
335 extensions in implementing your program is a difficult question.
337 On the one hand, using the extensions can make a cleaner program.
338 On the other hand, people will not be able to build the program unless
339 the other GNU tools are available. This might cause the program to
340 work on fewer kinds of machines.
342 With some extensions, it might be easy to provide both alternatives.
343 For example, you can define functions with a "keyword" `INLINE' and
344 define that as a macro to expand into either `inline' or nothing,
345 depending on the compiler.
347 In general, perhaps it is best not to use the extensions if you can
348 straightforwardly do without them, but to use the extensions if they
349 are a big improvement.
351 An exception to this rule are the large, established programs (such
352 as Emacs) which run on a great variety of systems. Using GNU
353 extensions in such programs would make many users unhappy, so we don't
356 Another exception is for programs that are used as part of
357 compilation: anything that must be compiled with other compilers in
358 order to bootstrap the GNU compilation facilities. If these require
359 the GNU compiler, then no one can compile them without having them
360 installed already. That would be extremely troublesome in certain
364 File: standards.info, Node: Standard C, Next: Conditional Compilation, Prev: Using Extensions, Up: Design Advice
366 3.4 Standard C and Pre-Standard C
367 =================================
369 1989 Standard C is widespread enough now that it is ok to use its
370 features in new programs. There is one exception: do not ever use the
371 "trigraph" feature of Standard C.
373 1999 Standard C is not widespread yet, so please do not require its
374 features in programs. It is ok to use its features if they are present.
376 However, it is easy to support pre-standard compilers in most
377 programs, so if you know how to do that, feel free. If a program you
378 are maintaining has such support, you should try to keep it working.
380 To support pre-standard C, instead of writing function definitions in
381 standard prototype form,
387 write the definition in pre-standard style like this,
394 and use a separate declaration to specify the argument prototype:
398 You need such a declaration anyway, in a header file, to get the
399 benefit of prototypes in all the files where the function is called.
400 And once you have the declaration, you normally lose nothing by writing
401 the function definition in the pre-standard style.
403 This technique does not work for integer types narrower than `int'.
404 If you think of an argument as being of a type narrower than `int',
405 declare it as `int' instead.
407 There are a few special cases where this technique is hard to use.
408 For example, if a function argument needs to hold the system type
409 `dev_t', you run into trouble, because `dev_t' is shorter than `int' on
410 some machines; but you cannot use `int' instead, because `dev_t' is
411 wider than `int' on some machines. There is no type you can safely use
412 on all machines in a non-standard definition. The only way to support
413 non-standard C and pass such an argument is to check the width of
414 `dev_t' using Autoconf and choose the argument type accordingly. This
415 may not be worth the trouble.
417 In order to support pre-standard compilers that do not recognize
418 prototypes, you may want to use a preprocessor macro like this:
420 /* Declare the prototype for a general external function. */
421 #if defined (__STDC__) || defined (WINDOWSNT)
422 #define P_(proto) proto
428 File: standards.info, Node: Conditional Compilation, Prev: Standard C, Up: Design Advice
430 3.5 Conditional Compilation
431 ===========================
433 When supporting configuration options already known when building your
434 program we prefer using `if (... )' over conditional compilation, as in
435 the former case the compiler is able to perform more extensive checking
436 of all possible code paths.
438 For example, please write
453 A modern compiler such as GCC will generate exactly the same code in
454 both cases, and we have been using similar techniques with good success
455 in several projects. Of course, the former method assumes that
456 `HAS_FOO' is defined as either 0 or 1.
458 While this is not a silver bullet solving all portability problems,
459 and is not always appropriate, following this policy would have saved
460 GCC developers many hours, or even days, per year.
462 In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
463 which cannot be simply used in `if( ...)' statements, there is an easy
464 workaround. Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
465 in the following example:
467 #ifdef REVERSIBLE_CC_MODE
468 #define HAS_REVERSIBLE_CC_MODE 1
470 #define HAS_REVERSIBLE_CC_MODE 0
474 File: standards.info, Node: Program Behavior, Next: Writing C, Prev: Design Advice, Up: Top
476 4 Program Behavior for All Programs
477 ***********************************
479 This chapter describes conventions for writing robust software. It
480 also describes general standards for error messages, the command line
481 interface, and how libraries should behave.
485 * Non-GNU Standards:: We consider standards such as POSIX;
486 we don't "obey" them.
487 * Semantics:: Writing robust programs
488 * Libraries:: Library behavior
489 * Errors:: Formatting error messages
490 * User Interfaces:: Standards about interfaces generally
491 * Graphical Interfaces:: Standards for graphical interfaces
492 * Command-Line Interfaces:: Standards for command line interfaces
493 * Option Table:: Table of long options
494 * Memory Usage:: When and how to care about memory needs
495 * File Usage:: Which files to use, and where
498 File: standards.info, Node: Non-GNU Standards, Next: Semantics, Up: Program Behavior
500 4.1 Non-GNU Standards
501 =====================
503 The GNU Project regards standards published by other organizations as
504 suggestions, not orders. We consider those standards, but we do not
505 "obey" them. In developing a GNU program, you should implement an
506 outside standard's specifications when that makes the GNU system better
507 overall in an objective sense. When it doesn't, you shouldn't.
509 In most cases, following published standards is convenient for
510 users--it means that their programs or scripts will work more portably.
511 For instance, GCC implements nearly all the features of Standard C as
512 specified by that standard. C program developers would be unhappy if
513 it did not. And GNU utilities mostly follow specifications of POSIX.2;
514 shell script writers and users would be unhappy if our programs were
517 But we do not follow either of these specifications rigidly, and
518 there are specific points on which we decided not to follow them, so as
519 to make the GNU system better for users.
521 For instance, Standard C says that nearly all extensions to C are
522 prohibited. How silly! GCC implements many extensions, some of which
523 were later adopted as part of the standard. If you want these
524 constructs to give an error message as "required" by the standard, you
525 must specify `--pedantic', which was implemented only so that we can
526 say "GCC is a 100% implementation of the standard," not because there
527 is any reason to actually use it.
529 POSIX.2 specifies that `df' and `du' must output sizes by default in
530 units of 512 bytes. What users want is units of 1k, so that is what we
531 do by default. If you want the ridiculous behavior "required" by
532 POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
533 was originally going to be named `POSIX_ME_HARDER').
535 GNU utilities also depart from the letter of the POSIX.2
536 specification when they support long-named command-line options, and
537 intermixing options with ordinary arguments. This minor
538 incompatibility with POSIX is never a problem in practice, and it is
541 In particular, don't reject a new feature, or remove an old one,
542 merely because a standard says it is "forbidden" or "deprecated."
545 File: standards.info, Node: Semantics, Next: Libraries, Prev: Non-GNU Standards, Up: Program Behavior
547 4.2 Writing Robust Programs
548 ===========================
550 Avoid arbitrary limits on the length or number of _any_ data structure,
551 including file names, lines, files, and symbols, by allocating all data
552 structures dynamically. In most Unix utilities, "long lines are
553 silently truncated". This is not acceptable in a GNU utility.
555 Utilities reading files should not drop NUL characters, or any other
556 nonprinting characters _including those with codes above 0177_. The
557 only sensible exceptions would be utilities specifically intended for
558 interface to certain types of terminals or printers that can't handle
559 those characters. Whenever possible, try to make programs work
560 properly with sequences of bytes that represent multibyte characters,
561 using encodings such as UTF-8 and others.
563 Check every system call for an error return, unless you know you
564 wish to ignore errors. Include the system error text (from `perror' or
565 equivalent) in _every_ error message resulting from a failing system
566 call, as well as the name of the file if any and the name of the
567 utility. Just "cannot open foo.c" or "stat failed" is not sufficient.
569 Check every call to `malloc' or `realloc' to see if it returned
570 zero. Check `realloc' even if you are making the block smaller; in a
571 system that rounds block sizes to a power of 2, `realloc' may get a
572 different block if you ask for less space.
574 In Unix, `realloc' can destroy the storage block if it returns zero.
575 GNU `realloc' does not have this bug: if it fails, the original block
576 is unchanged. Feel free to assume the bug is fixed. If you wish to
577 run your program on Unix, and wish to avoid lossage in this case, you
578 can use the GNU `malloc'.
580 You must expect `free' to alter the contents of the block that was
581 freed. Anything you want to fetch from the block, you must fetch before
584 If `malloc' fails in a noninteractive program, make that a fatal
585 error. In an interactive program (one that reads commands from the
586 user), it is better to abort the command and return to the command
587 reader loop. This allows the user to kill other processes to free up
588 virtual memory, and then try the command again.
590 Use `getopt_long' to decode arguments, unless the argument syntax
591 makes this unreasonable.
593 When static storage is to be written in during program execution, use
594 explicit C code to initialize it. Reserve C initialized declarations
595 for data that will not be changed.
597 Try to avoid low-level interfaces to obscure Unix data structures
598 (such as file directories, utmp, or the layout of kernel memory), since
599 these are less likely to work compatibly. If you need to find all the
600 files in a directory, use `readdir' or some other high-level interface.
601 These are supported compatibly by GNU.
603 The preferred signal handling facilities are the BSD variant of
604 `signal', and the POSIX `sigaction' function; the alternative USG
605 `signal' interface is an inferior design.
607 Nowadays, using the POSIX signal functions may be the easiest way to
608 make a program portable. If you use `signal', then on GNU/Linux
609 systems running GNU libc version 1, you should include `bsd/signal.h'
610 instead of `signal.h', so as to get BSD behavior. It is up to you
611 whether to support systems where `signal' has only the USG behavior, or
614 In error checks that detect "impossible" conditions, just abort.
615 There is usually no point in printing any message. These checks
616 indicate the existence of bugs. Whoever wants to fix the bugs will have
617 to read the source code and run a debugger. So explain the problem with
618 comments in the source. The relevant data will be in variables, which
619 are easy to examine with the debugger, so there is no point moving them
622 Do not use a count of errors as the exit status for a program.
623 _That does not work_, because exit status values are limited to 8 bits
624 (0 through 255). A single run of the program might have 256 errors; if
625 you try to return 256 as the exit status, the parent process will see 0
626 as the status, and it will appear that the program succeeded.
628 If you make temporary files, check the `TMPDIR' environment
629 variable; if that variable is defined, use the specified directory
632 In addition, be aware that there is a possible security problem when
633 creating temporary files in world-writable directories. In C, you can
634 avoid this problem by creating temporary files in this manner:
636 fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
638 or by using the `mkstemps' function from libiberty.
640 In bash, use `set -C' to avoid this problem.
643 File: standards.info, Node: Libraries, Next: Errors, Prev: Semantics, Up: Program Behavior
648 Try to make library functions reentrant. If they need to do dynamic
649 storage allocation, at least try to avoid any nonreentrancy aside from
650 that of `malloc' itself.
652 Here are certain name conventions for libraries, to avoid name
655 Choose a name prefix for the library, more than two characters long.
656 All external function and variable names should start with this prefix.
657 In addition, there should only be one of these in any given library
658 member. This usually means putting each one in a separate source file.
660 An exception can be made when two external symbols are always used
661 together, so that no reasonable program could use one without the
662 other; then they can both go in the same file.
664 External symbols that are not documented entry points for the user
665 should have names beginning with `_'. The `_' should be followed by
666 the chosen name prefix for the library, to prevent collisions with
667 other libraries. These can go in the same files with user entry points
670 Static functions and variables can be used as you like and need not
671 fit any naming convention.
674 File: standards.info, Node: Errors, Next: User Interfaces, Prev: Libraries, Up: Program Behavior
676 4.4 Formatting Error Messages
677 =============================
679 Error messages from compilers should look like this:
681 SOURCE-FILE-NAME:LINENO: MESSAGE
683 If you want to mention the column number, use one of these formats:
685 SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
686 SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
688 Line numbers should start from 1 at the beginning of the file, and
689 column numbers should start from 1 at the beginning of the line. (Both
690 of these conventions are chosen for compatibility.) Calculate column
691 numbers assuming that space and all ASCII printing characters have
692 equal width, and assuming tab stops every 8 columns.
694 The error message can also give both the starting and ending
695 positions of the erroneous text. There are several formats so that you
696 can avoid redundant information such as a duplicate line number. Here
697 are the possible formats:
699 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
700 SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
701 SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
703 When an error is spread over several files, you can use this format:
705 FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
707 Error messages from other noninteractive programs should look like
710 PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
712 when there is an appropriate source file, or like this:
716 when there is no relevant source file.
718 If you want to mention the column number, use this format:
720 PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
722 In an interactive program (one that is reading commands from a
723 terminal), it is better not to include the program name in an error
724 message. The place to indicate which program is running is in the
725 prompt or with the screen layout. (When the same program runs with
726 input from a source other than a terminal, it is not interactive and
727 would do best to print error messages using the noninteractive style.)
729 The string MESSAGE should not begin with a capital letter when it
730 follows a program name and/or file name, because that isn't the
731 beginning of a sentence. (The sentence conceptually starts at the
732 beginning of the line.) Also, it should not end with a period.
734 Error messages from interactive programs, and other messages such as
735 usage messages, should start with a capital letter. But they should not
739 File: standards.info, Node: User Interfaces, Next: Graphical Interfaces, Prev: Errors, Up: Program Behavior
741 4.5 Standards for Interfaces Generally
742 ======================================
744 Please don't make the behavior of a utility depend on the name used to
745 invoke it. It is useful sometimes to make a link to a utility with a
746 different name, and that should not change what it does.
748 Instead, use a run time option or a compilation switch or both to
749 select among the alternate behaviors.
751 Likewise, please don't make the behavior of the program depend on the
752 type of output device it is used with. Device independence is an
753 important principle of the system's design; do not compromise it merely
754 to save someone from typing an option now and then. (Variation in error
755 message syntax when using a terminal is ok, because that is a side issue
756 that people do not depend on.)
758 If you think one behavior is most useful when the output is to a
759 terminal, and another is most useful when the output is a file or a
760 pipe, then it is usually best to make the default behavior the one that
761 is useful with output to a terminal, and have an option for the other
764 Compatibility requires certain programs to depend on the type of
765 output device. It would be disastrous if `ls' or `sh' did not do so in
766 the way all users expect. In some of these cases, we supplement the
767 program with a preferred alternate version that does not depend on the
768 output device type. For example, we provide a `dir' program much like
769 `ls' except that its default output format is always multi-column
773 File: standards.info, Node: Graphical Interfaces, Next: Command-Line Interfaces, Prev: User Interfaces, Up: Program Behavior
775 4.6 Standards for Graphical Interfaces
776 ======================================
778 When you write a program that provides a graphical user interface,
779 please make it work with X Windows and the GTK+ toolkit unless the
780 functionality specifically requires some alternative (for example,
781 "displaying jpeg images while in console mode").
783 In addition, please provide a command-line interface to control the
784 functionality. (In many cases, the graphical user interface can be a
785 separate program which invokes the command-line program.) This is so
786 that the same jobs can be done from scripts.
788 Please also consider providing a CORBA interface (for use from
789 GNOME), a library interface (for use from C), and perhaps a
790 keyboard-driven console interface (for use by users from console mode).
791 Once you are doing the work to provide the functionality and the
792 graphical interface, these won't be much extra work.
795 File: standards.info, Node: Command-Line Interfaces, Next: Option Table, Prev: Graphical Interfaces, Up: Program Behavior
797 4.7 Standards for Command Line Interfaces
798 =========================================
800 It is a good idea to follow the POSIX guidelines for the command-line
801 options of a program. The easiest way to do this is to use `getopt' to
802 parse them. Note that the GNU version of `getopt' will normally permit
803 options anywhere among the arguments unless the special argument `--'
804 is used. This is not what POSIX specifies; it is a GNU extension.
806 Please define long-named options that are equivalent to the
807 single-letter Unix-style options. We hope to make GNU more user
808 friendly this way. This is easy to do with the GNU function
811 One of the advantages of long-named options is that they can be
812 consistent from program to program. For example, users should be able
813 to expect the "verbose" option of any GNU program which has one, to be
814 spelled precisely `--verbose'. To achieve this uniformity, look at the
815 table of common long-option names when you choose the option names for
816 your program (*note Option Table::).
818 It is usually a good idea for file names given as ordinary arguments
819 to be input files only; any output files would be specified using
820 options (preferably `-o' or `--output'). Even if you allow an output
821 file name as an ordinary argument for compatibility, try to provide an
822 option as another way to specify it. This will lead to more consistency
823 among GNU utilities, and fewer idiosyncrasies for users to remember.
825 All programs should support two standard options: `--version' and
826 `--help'. CGI programs should accept these as command-line options,
827 and also if given as the `PATH_INFO'; for instance, visiting
828 `http://example.org/p.cgi/--help' in a browser should output the same
829 information as invoking `p.cgi --help' from the command line.
832 This option should direct the program to print information about
833 its name, version, origin and legal status, all on standard
834 output, and then exit successfully. Other options and arguments
835 should be ignored once this is seen, and the program should not
836 perform its normal function.
838 The first line is meant to be easy for a program to parse; the
839 version number proper starts after the last space. In addition,
840 it contains the canonical name for this program, in this format:
844 The program's name should be a constant string; _don't_ compute it
845 from `argv[0]'. The idea is to state the standard or canonical
846 name for the program, not its file name. There are other ways to
847 find out the precise file name where a command is found in `PATH'.
849 If the program is a subsidiary part of a larger package, mention
850 the package name in parentheses, like this:
852 emacsserver (GNU Emacs) 19.30
854 If the package has a version number which is different from this
855 program's version number, you can mention the package version
856 number just before the close-parenthesis.
858 If you *need* to mention the version numbers of libraries which
859 are distributed separately from the package which contains this
860 program, you can do so by printing an additional line of version
861 info for each library you want to mention. Use the same format
862 for these lines as for the first line.
864 Please do not mention all of the libraries that the program uses
865 "just for completeness"--that would produce a lot of unhelpful
866 clutter. Please mention library version numbers only if you find
867 in practice that they are very important to you in debugging.
869 The following line, after the version number line or lines, should
870 be a copyright notice. If more than one copyright notice is
871 called for, put each on a separate line.
873 Next should follow a brief statement that the program is free
874 software, and that users are free to copy and change it on certain
875 conditions. If the program is covered by the GNU GPL, say so
876 here. Also mention that there is no warranty, to the extent
879 It is ok to finish the output with a list of the major authors of
880 the program, as a way of giving credit.
882 Here's an example of output that follows these rules:
885 Copyright (C) 1996 Free Software Foundation, Inc.
886 GNU Emacs comes with NO WARRANTY,
887 to the extent permitted by law.
888 You may redistribute copies of GNU Emacs
889 under the terms of the GNU General Public License.
890 For more information about these matters,
891 see the files named COPYING.
893 You should adapt this to your program, of course, filling in the
894 proper year, copyright holder, name of program, and the references
895 to distribution terms, and changing the rest of the wording as
898 This copyright notice only needs to mention the most recent year in
899 which changes were made--there's no need to list the years for
900 previous versions' changes. You don't have to mention the name of
901 the program in these notices, if that is inconvenient, since it
902 appeared in the first line. (The rules are different for
903 copyright notices in source files; see *Note Copyright Notices:
904 (maintain)Copyright Notices.)
906 Translations of the above lines must preserve the validity of the
907 copyright notices (*note Internationalization::). If the
908 translation's character set supports it, the `(C)' should be
909 replaced with the copyright symbol, as follows:
911 (the official copyright symbol, which is the letter C in a circle);
913 Write the word "Copyright" exactly like that, in English. Do not
914 translate it into another language. International treaties
915 recognize the English word "Copyright"; translations into other
916 languages do not have legal significance.
919 This option should output brief documentation for how to invoke the
920 program, on standard output, then exit successfully. Other
921 options and arguments should be ignored once this is seen, and the
922 program should not perform its normal function.
924 Near the end of the `--help' option's output there should be a line
925 that says where to mail bug reports. It should have this format:
927 Report bugs to MAILING-ADDRESS.
930 File: standards.info, Node: Option Table, Next: Memory Usage, Prev: Command-Line Interfaces, Up: Program Behavior
932 4.8 Table of Long Options
933 =========================
935 Here is a table of long options used by GNU programs. It is surely
936 incomplete, but we aim to list all the options that a new program might
937 want to be compatible with. If you use names not already in the table,
938 please send <bug-standards@gnu.org> a list of them, with their
939 meanings, so we can update the table.
945 `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
954 `-a' in `etags', `tee', `time'; `-r' in `tar'.
990 For server programs, run in the background.
1008 `-b' in `cpio' and `diff'.
1014 Used in `cpio' and `tar'.
1017 `-b' in `head' and `tail'.
1023 Used in various programs to make output shorter.
1026 `-c' in `head', `split', and `tail'.
1035 Used in various programs to specify the directory to use.
1038 `-c' in `chgrp' and `chown'.
1047 `-c' in `su'; `-x' in GDB.
1056 `-Z' in `tar' and `shar'.
1068 `-W copyleft' in `gawk'.
1071 `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
1083 Used in `tar' and `cpio'.
1095 `-d' in Make and `m4'; `-t' in Bison.
1101 `-d' in Bison and `ctags'.
1107 `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
1113 Specify an I/O device (special file name).
1128 Specify the directory to use, in various programs. In `ls', it
1129 means to show directories themselves rather than their contents.
1130 In `rm' and `ln', it means to not treat links to directories
1157 `environment-overrides'
1197 `-i' in `cpio'; `-x' in `tar'.
1209 `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
1230 `fixed-output-files'
1240 `-f' in `cp', `ln', `mv', and `rm'.
1246 For server programs, run in the foreground; in other words, don't
1247 do anything special to run the server in the background.
1250 Used in `ls', `time', and `ptx'.
1274 `-z' in `tar' and `shar'.
1280 `-h' in `objdump' and `recode'
1286 Used to ask for brief usage information.
1291 `hide-control-chars'
1295 In `makeinfo', output HTML.
1304 `-I' in `ls'; `-x' in `recode'.
1312 `ignore-blank-lines'
1316 `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1324 `ignore-indentation'
1333 `ignore-matching-lines'
1336 `ignore-space-change'
1343 `-i' in `etags'; `-I' in `m4'.
1352 `-i', `-l', and `-m' in Finger.
1355 In some programs, specify the name of the file to read as the
1368 `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
1390 `-k' in `du' and `ls'.
1405 Used in `split', `head', and `tail'.
1415 `-t' in `cpio'; `-l' in `recode'.
1436 `-m' in `hello' and `uname'.
1475 `-m' in `install', `mkdir', and `mkfifo'.
1498 `no-character-count'
1541 Don't print a startup splash screen.
1559 Used in `emacsclient'.
1562 Used in various programs to inhibit warnings.
1589 `-n' in `cpio' and `ls'.
1601 `-l' in `tar', `cp', and `du'.
1613 `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1616 In various programs, specify the output file name.
1637 `-p' in `mkdir' and `rmdir'.
1649 `-c' in `cpio' and `tar'.
1661 Used in `tar' and `cp'.
1663 `preserve-environment'
1666 `preserve-modification-time'
1672 `preserve-permissions'
1700 Specify an HTTP proxy.
1709 Used in many programs to inhibit the usual output. Every program
1710 accepting `--quiet' should accept `--silent' as a synonym.
1737 Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1746 `-r' in `tac' and `etags'.
1763 `report-identical-files'
1770 `-r' in `ls' and `nm'.
1800 Used by `recode' to chose files or pipes for sequencing passes.
1814 `show-function-line'
1821 Used in many programs to inhibit the usual output. Every program
1822 accepting `--silent' should accept `--quiet' as a synonym.
1828 Specify a file descriptor for a network server to use for its
1829 socket, instead of opening and binding a new socket. This
1830 provides a way to run, in a non-privileged process, a server that
1831 normally needs a reserved port number.
1837 `-W source' in `gawk'.
1861 Used in `tar' and `diff' to specify which file within a directory
1862 to start processing with.
1889 `-S' in `cp', `ln', `mv'.
1904 Used in GDB and `objdump'.
1913 `-t' in `expand' and `unexpand'.
1919 `-T' in `tput' and `ul'. `-t' in `wdiff'.
1928 Used in `ls' and `touch'.
1931 Specify how long to wait before giving up on some operation.
1940 `-t' in Make, `ranlib', and `recode'.
1946 `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
1974 `-u' in `cp', `ctags', `mv', `tar'.
1977 Used in `gawk'; same as `--help'.
1986 Print more information about progress. Many programs support this.
1992 Print the version number.
1995 `-V' in `cp', `ln', `mv'.
2010 `-w' in `ls' and `ptx'.
2022 File: standards.info, Node: Memory Usage, Next: File Usage, Prev: Option Table, Up: Program Behavior
2027 If a program typically uses just a few meg of memory, don't bother
2028 making any effort to reduce memory usage. For example, if it is
2029 impractical for other reasons to operate on files more than a few meg
2030 long, it is reasonable to read entire input files into memory to
2033 However, for programs such as `cat' or `tail', that can usefully
2034 operate on very large files, it is important to avoid using a technique
2035 that would artificially limit the size of files it can handle. If a
2036 program works by lines and could be applied to arbitrary user-supplied
2037 input files, it should keep only a line in memory, because this is not
2038 very hard and users will want to be able to operate on input files that
2039 are bigger than will fit in memory all at once.
2041 If your program creates complicated data structures, just make them
2042 in memory and give a fatal error if `malloc' returns zero.
2045 File: standards.info, Node: File Usage, Prev: Memory Usage, Up: Program Behavior
2050 Programs should be prepared to operate when `/usr' and `/etc' are
2051 read-only file systems. Thus, if the program manages log files, lock
2052 files, backup files, score files, or any other files which are modified
2053 for internal purposes, these files should not be stored in `/usr' or
2056 There are two exceptions. `/etc' is used to store system
2057 configuration information; it is reasonable for a program to modify
2058 files in `/etc' when its job is to update the system configuration.
2059 Also, if the user explicitly asks to modify one file in a directory, it
2060 is reasonable for the program to store other files in the same
2064 File: standards.info, Node: Writing C, Next: Documentation, Prev: Program Behavior, Up: Top
2066 5 Making The Best Use of C
2067 **************************
2069 This chapter provides advice on how best to use the C language when
2070 writing GNU software.
2074 * Formatting:: Formatting Your Source Code
2075 * Comments:: Commenting Your Work
2076 * Syntactic Conventions:: Clean Use of C Constructs
2077 * Names:: Naming Variables, Functions, and Files
2078 * System Portability:: Portability between different operating systems
2079 * CPU Portability:: Supporting the range of CPU types
2080 * System Functions:: Portability and ``standard'' library functions
2081 * Internationalization:: Techniques for internationalization
2082 * Character Set:: Use ASCII by default.
2083 * Quote Characters:: Use `...' in the C locale.
2084 * Mmap:: How you can safely use `mmap'.
2087 File: standards.info, Node: Formatting, Next: Comments, Up: Writing C
2089 5.1 Formatting Your Source Code
2090 ===============================
2092 It is important to put the open-brace that starts the body of a C
2093 function in column one, and avoid putting any other open-brace or
2094 open-parenthesis or open-bracket in column one. Several tools look for
2095 open-braces in column one to find the beginnings of C functions. These
2096 tools will not work on code not formatted that way.
2098 It is also important for function definitions to start the name of
2099 the function in column one. This helps people to search for function
2100 definitions, and may also help certain tools recognize them. Thus,
2101 using Standard C syntax, the format is this:
2104 concat (char *s1, char *s2)
2109 or, if you want to use traditional C syntax, format the definition like
2113 concat (s1, s2) /* Name starts in column one here */
2115 { /* Open brace in column one here */
2119 In Standard C, if the arguments don't fit nicely on one line, split
2123 lots_of_args (int an_integer, long a_long, short a_short,
2124 double a_double, float a_float)
2127 The rest of this section gives our recommendations for other aspects
2128 of C formatting style, which is also the default style of the `indent'
2129 program in version 1.2 and newer. It corresponds to the options
2131 -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2132 -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2134 We don't think of these recommendations as requirements, because it
2135 causes no problems for users if two different programs have different
2138 But whatever style you use, please use it consistently, since a
2139 mixture of styles within one program tends to look ugly. If you are
2140 contributing changes to an existing program, please follow the style of
2143 For the body of the function, our recommended style looks like this:
2154 return ++x + bar ();
2157 We find it easier to read a program when it has spaces before the
2158 open-parentheses and after the commas. Especially after the commas.
2160 When you split an expression into multiple lines, split it before an
2161 operator, not after one. Here is the right way:
2163 if (foo_this_is_long && bar > win (x, y, z)
2164 && remaining_condition)
2166 Try to avoid having two operators of different precedence at the same
2167 level of indentation. For example, don't write this:
2169 mode = (inmode[j] == VOIDmode
2170 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2171 ? outmode[j] : inmode[j]);
2173 Instead, use extra parentheses so that the indentation shows the
2176 mode = ((inmode[j] == VOIDmode
2177 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2178 ? outmode[j] : inmode[j]);
2180 Insert extra parentheses so that Emacs will indent the code properly.
2181 For example, the following indentation looks nice if you do it by hand,
2183 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2184 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2186 but Emacs would alter it. Adding a set of parentheses produces
2187 something that looks equally nice, and which Emacs will preserve:
2189 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2190 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2192 Format do-while statements like this:
2200 Please use formfeed characters (control-L) to divide the program into
2201 pages at logical places (but not within a function). It does not matter
2202 just how long the pages are, since they do not have to fit on a printed
2203 page. The formfeeds should appear alone on lines by themselves.
2206 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
2208 5.2 Commenting Your Work
2209 ========================
2211 Every program should start with a comment saying briefly what it is for.
2212 Example: `fmt - filter for simple filling of text'. This comment
2213 should be at the top of the source file containing the `main' function
2216 Also, please write a brief comment at the start of each source file,
2217 with the file name and a line or two about the overall purpose of the
2220 Please write the comments in a GNU program in English, because
2221 English is the one language that nearly all programmers in all
2222 countries can read. If you do not write English well, please write
2223 comments in English as well as you can, then ask other people to help
2224 rewrite them. If you can't write comments in English, please find
2225 someone to work with you and translate your comments into English.
2227 Please put a comment on each function saying what the function does,
2228 what sorts of arguments it gets, and what the possible values of
2229 arguments mean and are used for. It is not necessary to duplicate in
2230 words the meaning of the C argument declarations, if a C type is being
2231 used in its customary fashion. If there is anything nonstandard about
2232 its use (such as an argument of type `char *' which is really the
2233 address of the second character of a string, not the first), or any
2234 possible values that would not work the way one would expect (such as,
2235 that strings containing newlines are not guaranteed to work), be sure
2238 Also explain the significance of the return value, if there is one.
2240 Please put two spaces after the end of a sentence in your comments,
2241 so that the Emacs sentence commands will work. Also, please write
2242 complete sentences and capitalize the first word. If a lower-case
2243 identifier comes at the beginning of a sentence, don't capitalize it!
2244 Changing the spelling makes it a different identifier. If you don't
2245 like starting a sentence with a lower case letter, write the sentence
2246 differently (e.g., "The identifier lower-case is ...").
2248 The comment on a function is much clearer if you use the argument
2249 names to speak about the argument values. The variable name itself
2250 should be lower case, but write it in upper case when you are speaking
2251 about the value rather than the variable itself. Thus, "the inode
2252 number NODE_NUM" rather than "an inode".
2254 There is usually no purpose in restating the name of the function in
2255 the comment before it, because the reader can see that for himself.
2256 There might be an exception when the comment is so long that the
2257 function itself would be off the bottom of the screen.
2259 There should be a comment on each static variable as well, like this:
2261 /* Nonzero means truncate lines in the display;
2262 zero means continue them. */
2265 Every `#endif' should have a comment, except in the case of short
2266 conditionals (just a few lines) that are not nested. The comment should
2267 state the condition of the conditional that is ending, _including its
2268 sense_. `#else' should have a comment describing the condition _and
2269 sense_ of the code that follows. For example:
2275 #endif /* not foo */
2280 but, by contrast, write the comments this way for a `#ifndef':
2289 #endif /* not foo */
2292 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
2294 5.3 Clean Use of C Constructs
2295 =============================
2297 Please explicitly declare the types of all objects. For example, you
2298 should explicitly declare all arguments to functions, and you should
2299 declare functions to return `int' rather than omitting the `int'.
2301 Some programmers like to use the GCC `-Wall' option, and change the
2302 code whenever it issues a warning. If you want to do this, then do.
2303 Other programmers prefer not to use `-Wall', because it gives warnings
2304 for valid and legitimate code which they do not want to change. If you
2305 want to do this, then do. The compiler should be your servant, not
2308 Declarations of external functions and functions to appear later in
2309 the source file should all go in one place near the beginning of the
2310 file (somewhere before the first function definition in the file), or
2311 else should go in a header file. Don't put `extern' declarations inside
2314 It used to be common practice to use the same local variables (with
2315 names like `tem') over and over for different values within one
2316 function. Instead of doing this, it is better to declare a separate
2317 local variable for each distinct purpose, and give it a name which is
2318 meaningful. This not only makes programs easier to understand, it also
2319 facilitates optimization by good compilers. You can also move the
2320 declaration of each local variable into the smallest scope that includes
2321 all its uses. This makes the program even cleaner.
2323 Don't use local variables or parameters that shadow global
2326 Don't declare multiple variables in one declaration that spans lines.
2327 Start a new declaration on each line, instead. For example, instead of
2342 (If they are global variables, each should have a comment preceding it
2345 When you have an `if'-`else' statement nested in another `if'
2346 statement, always put braces around the `if'-`else'. Thus, never write
2365 If you have an `if' statement nested inside of an `else' statement,
2366 either write `else if' on one line, like this,
2373 with its `then'-part indented like the preceding `then'-part, or write
2374 the nested `if' within braces like this:
2384 Don't declare both a structure tag and variables or typedefs in the
2385 same declaration. Instead, declare the structure tag separately and
2386 then use it to declare the variables or typedefs.
2388 Try to avoid assignments inside `if'-conditions (assignments inside
2389 `while'-conditions are ok). For example, don't write this:
2391 if ((foo = (char *) malloc (sizeof *foo)) == 0)
2392 fatal ("virtual memory exhausted");
2394 instead, write this:
2396 foo = (char *) malloc (sizeof *foo);
2398 fatal ("virtual memory exhausted");
2400 Don't make the program ugly to placate `lint'. Please don't insert
2401 any casts to `void'. Zero without a cast is perfectly fine as a null
2402 pointer constant, except when calling a varargs function.
2405 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
2407 5.4 Naming Variables, Functions, and Files
2408 ==========================================
2410 The names of global variables and functions in a program serve as
2411 comments of a sort. So don't choose terse names--instead, look for
2412 names that give useful information about the meaning of the variable or
2413 function. In a GNU program, names should be English, like other
2416 Local variable names can be shorter, because they are used only
2417 within one context, where (presumably) comments explain their purpose.
2419 Try to limit your use of abbreviations in symbol names. It is ok to
2420 make a few abbreviations, explain what they mean, and then use them
2421 frequently, but don't use lots of obscure abbreviations.
2423 Please use underscores to separate words in a name, so that the Emacs
2424 word commands can be useful within them. Stick to lower case; reserve
2425 upper case for macros and `enum' constants, and for name-prefixes that
2426 follow a uniform convention.
2428 For example, you should use names like `ignore_space_change_flag';
2429 don't use names like `iCantReadThis'.
2431 Variables that indicate whether command-line options have been
2432 specified should be named after the meaning of the option, not after
2433 the option-letter. A comment should state both the exact meaning of
2434 the option and its letter. For example,
2436 /* Ignore changes in horizontal whitespace (-b). */
2437 int ignore_space_change_flag;
2439 When you want to define names with constant integer values, use
2440 `enum' rather than `#define'. GDB knows about enumeration constants.
2442 You might want to make sure that none of the file names would
2443 conflict if the files were loaded onto an MS-DOS file system which
2444 shortens the names. You can use the program `doschk' to test for this.
2446 Some GNU programs were designed to limit themselves to file names of
2447 14 characters or less, to avoid file name conflicts if they are read
2448 into older System V systems. Please preserve this feature in the
2449 existing GNU programs that have it, but there is no need to do this in
2450 new GNU programs. `doschk' also reports file names longer than 14
2454 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
2456 5.5 Portability between System Types
2457 ====================================
2459 In the Unix world, "portability" refers to porting to different Unix
2460 versions. For a GNU program, this kind of portability is desirable, but
2463 The primary purpose of GNU software is to run on top of the GNU
2464 kernel, compiled with the GNU C compiler, on various types of CPU. So
2465 the kinds of portability that are absolutely necessary are quite
2466 limited. But it is important to support Linux-based GNU systems, since
2467 they are the form of GNU that is popular.
2469 Beyond that, it is good to support the other free operating systems
2470 (*BSD), and it is nice to support other Unix-like systems if you want
2471 to. Supporting a variety of Unix-like systems is desirable, although
2472 not paramount. It is usually not too hard, so you may as well do it.
2473 But you don't have to consider it an obligation, if it does turn out to
2476 The easiest way to achieve portability to most Unix-like systems is
2477 to use Autoconf. It's unlikely that your program needs to know more
2478 information about the host platform than Autoconf can provide, simply
2479 because most of the programs that need such knowledge have already been
2482 Avoid using the format of semi-internal data bases (e.g.,
2483 directories) when there is a higher-level alternative (`readdir').
2485 As for systems that are not like Unix, such as MSDOS, Windows, VMS,
2486 MVS, and older Macintosh systems, supporting them is often a lot of
2487 work. When that is the case, it is better to spend your time adding
2488 features that will be useful on GNU and GNU/Linux, rather than on
2489 supporting other incompatible systems.
2491 If you do support Windows, please do not abbreviate it as "win". In
2492 hacker terminology, calling something a "win" is a form of praise.
2493 You're free to praise Microsoft Windows on your own if you want, but
2494 please don't do this in GNU packages. Instead of abbreviating
2495 "Windows" to "un", you can write it in full or abbreviate it to "woe"
2496 or "w". In GNU Emacs, for instance, we use `w32' in file names of
2497 Windows-specific files, but the macro for Windows conditionals is
2500 It is a good idea to define the "feature test macro" `_GNU_SOURCE'
2501 when compiling your C files. When you compile on GNU or GNU/Linux,
2502 this will enable the declarations of GNU library extension functions,
2503 and that will usually give you a compiler error message if you define
2504 the same function names in some other way in your program. (You don't
2505 have to actually _use_ these functions, if you prefer to make the
2506 program more portable to other systems.)
2508 But whether or not you use these GNU extensions, you should avoid
2509 using their names for any other meanings. Doing so would make it hard
2510 to move your code into other GNU programs.
2513 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
2515 5.6 Portability between CPUs
2516 ============================
2518 Even GNU systems will differ because of differences among CPU
2519 types--for example, difference in byte ordering and alignment
2520 requirements. It is absolutely essential to handle these differences.
2521 However, don't make any effort to cater to the possibility that an
2522 `int' will be less than 32 bits. We don't support 16-bit machines in
2525 Similarly, don't make any effort to cater to the possibility that
2526 `long' will be smaller than predefined types like `size_t'. For
2527 example, the following code is ok:
2529 printf ("size = %lu\n", (unsigned long) sizeof array);
2530 printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2532 1989 Standard C requires this to work, and we know of only one
2533 counterexample: 64-bit programs on Microsoft Windows. We will leave it
2534 to those who want to port GNU programs to that environment to figure
2537 Predefined file-size types like `off_t' are an exception: they are
2538 longer than `long' on many platforms, so code like the above won't work
2539 with them. One way to print an `off_t' value portably is to print its
2540 digits yourself, one by one.
2542 Don't assume that the address of an `int' object is also the address
2543 of its least-significant byte. This is false on big-endian machines.
2544 Thus, don't make the following mistake:
2548 while ((c = getchar ()) != EOF)
2549 write (file_descriptor, &c, 1);
2551 Instead, use `unsigned char' as follows. (The `unsigned' is for
2552 portability to unusual systems where `char' is signed and where there
2553 is integer overflow checking.)
2556 while ((c = getchar ()) != EOF)
2558 unsigned char u = c;
2559 write (file_descriptor, &u, 1);
2562 It used to be ok to not worry about the difference between pointers
2563 and integers when passing arguments to functions. However, on most
2564 modern 64-bit machines pointers are wider than `int'. Conversely,
2565 integer types like `long long int' and `off_t' are wider than pointers
2566 on most modern 32-bit machines. Hence it's often better nowadays to
2567 use prototypes to define functions whose argument types are not trivial.
2569 In particular, if functions accept varying argument counts or types
2570 they should be declared using prototypes containing `...' and defined
2571 using `stdarg.h'. For an example of this, please see the Gnulib
2572 (http://www.gnu.org/software/gnulib/) error module, which declares and
2573 defines the following function:
2575 /* Print a message with `fprintf (stderr, FORMAT, ...)';
2576 if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2577 If STATUS is nonzero, terminate the program with `exit (STATUS)'. */
2579 void error (int status, int errnum, const char *format, ...);
2581 A simple way to use the Gnulib error module is to obtain the two
2582 source files `error.c' and `error.h' from the Gnulib library source
2584 `http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'. Here's a
2591 char *program_name = "myprogram";
2594 xfopen (char const *name)
2596 FILE *fp = fopen (name, "r");
2598 error (1, errno, "cannot read %s", name);
2602 Avoid casting pointers to integers if you can. Such casts greatly
2603 reduce portability, and in most programs they are easy to avoid. In the
2604 cases where casting pointers to integers is essential--such as, a Lisp
2605 interpreter which stores type information as well as an address in one
2606 word--you'll have to make explicit provisions to handle different word
2607 sizes. You will also need to make provision for systems in which the
2608 normal range of addresses you can get from `malloc' starts far away
2612 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
2614 5.7 Calling System Functions
2615 ============================
2617 C implementations differ substantially. Standard C reduces but does
2618 not eliminate the incompatibilities; meanwhile, many GNU packages still
2619 support pre-standard compilers because this is not hard to do. This
2620 chapter gives recommendations for how to use the more-or-less standard C
2621 library functions to avoid unnecessary loss of portability.
2623 * Don't use the return value of `sprintf'. It returns the number of
2624 characters written on some systems, but not on all systems.
2626 * Be aware that `vfprintf' is not always available.
2628 * `main' should be declared to return type `int'. It should
2629 terminate either by calling `exit' or by returning the integer
2630 status code; make sure it cannot ever return an undefined value.
2632 * Don't declare system functions explicitly.
2634 Almost any declaration for a system function is wrong on some
2635 system. To minimize conflicts, leave it to the system header
2636 files to declare system functions. If the headers don't declare a
2637 function, let it remain undeclared.
2639 While it may seem unclean to use a function without declaring it,
2640 in practice this works fine for most system library functions on
2641 the systems where this really happens; thus, the disadvantage is
2642 only theoretical. By contrast, actual declarations have
2643 frequently caused actual conflicts.
2645 * If you must declare a system function, don't specify the argument
2646 types. Use an old-style declaration, not a Standard C prototype.
2647 The more you specify about the function, the more likely a
2650 * In particular, don't unconditionally declare `malloc' or `realloc'.
2652 Most GNU programs use those functions just once, in functions
2653 conventionally named `xmalloc' and `xrealloc'. These functions
2654 call `malloc' and `realloc', respectively, and check the results.
2656 Because `xmalloc' and `xrealloc' are defined in your program, you
2657 can declare them in other files without any risk of type conflict.
2659 On most systems, `int' is the same length as a pointer; thus, the
2660 calls to `malloc' and `realloc' work fine. For the few
2661 exceptional systems (mostly 64-bit machines), you can use
2662 *conditionalized* declarations of `malloc' and `realloc'--or put
2663 these declarations in configuration files specific to those
2666 * The string functions require special treatment. Some Unix systems
2667 have a header file `string.h'; others have `strings.h'. Neither
2668 file name is portable. There are two things you can do: use
2669 Autoconf to figure out which file to include, or don't include
2672 * If you don't include either strings file, you can't get
2673 declarations for the string functions from the header file in the
2676 That causes less of a problem than you might think. The newer
2677 standard string functions should be avoided anyway because many
2678 systems still don't support them. The string functions you can
2681 strcpy strncpy strcat strncat
2682 strlen strcmp strncmp
2685 The copy and concatenate functions work fine without a declaration
2686 as long as you don't use their values. Using their values without
2687 a declaration fails on systems where the width of a pointer
2688 differs from the width of `int', and perhaps in other cases. It
2689 is trivial to avoid using their values, so do that.
2691 The compare functions and `strlen' work fine without a declaration
2692 on most systems, possibly all the ones that GNU software runs on.
2693 You may find it necessary to declare them *conditionally* on a few
2696 The search functions must be declared to return `char *'. Luckily,
2697 there is no variation in the data type they return. But there is
2698 variation in their names. Some systems give these functions the
2699 names `index' and `rindex'; other systems use the names `strchr'
2700 and `strrchr'. Some systems support both pairs of names, but
2701 neither pair works on all systems.
2703 You should pick a single pair of names and use it throughout your
2704 program. (Nowadays, it is better to choose `strchr' and `strrchr'
2705 for new programs, since those are the standard names.) Declare
2706 both of those names as functions returning `char *'. On systems
2707 which don't support those names, define them as macros in terms of
2708 the other pair. For example, here is what to put at the beginning
2709 of your file (or in a header) if you want to use the names
2710 `strchr' and `strrchr' throughout:
2713 #define strchr index
2715 #ifndef HAVE_STRRCHR
2716 #define strrchr rindex
2722 Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
2723 defined in systems where the corresponding functions exist. One way to
2724 get them properly defined is to use Autoconf.
2727 File: standards.info, Node: Internationalization, Next: Character Set, Prev: System Functions, Up: Writing C
2729 5.8 Internationalization
2730 ========================
2732 GNU has a library called GNU gettext that makes it easy to translate the
2733 messages in a program into various languages. You should use this
2734 library in every program. Use English for the messages as they appear
2735 in the program, and let gettext provide the way to translate them into
2738 Using GNU gettext involves putting a call to the `gettext' macro
2739 around each string that might need translation--like this:
2741 printf (gettext ("Processing file `%s'..."));
2743 This permits GNU gettext to replace the string `"Processing file
2744 `%s'..."' with a translated version.
2746 Once a program uses gettext, please make a point of writing calls to
2747 `gettext' when you add new strings that call for translation.
2749 Using GNU gettext in a package involves specifying a "text domain
2750 name" for the package. The text domain name is used to separate the
2751 translations for this package from the translations for other packages.
2752 Normally, the text domain name should be the same as the name of the
2753 package--for example, `coreutils' for the GNU core utilities.
2755 To enable gettext to work well, avoid writing code that makes
2756 assumptions about the structure of words or sentences. When you want
2757 the precise text of a sentence to vary depending on the data, use two or
2758 more alternative string constants each containing a complete sentences,
2759 rather than inserting conditionalized words or phrases into a single
2762 Here is an example of what not to do:
2764 printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
2766 If you apply gettext to all strings, like this,
2768 printf (gettext ("%s is full"),
2769 capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
2771 the translator will hardly know that "disk" and "floppy disk" are meant
2772 to be substituted in the other string. Worse, in some languages (like
2773 French) the construction will not work: the translation of the word
2774 "full" depends on the gender of the first part of the sentence; it
2775 happens to be not the same for "disk" as for "floppy disk".
2777 Complete sentences can be translated without problems:
2779 printf (capacity > 5000000 ? gettext ("disk is full")
2780 : gettext ("floppy disk is full"));
2782 A similar problem appears at the level of sentence structure with
2785 printf ("# Implicit rule search has%s been done.\n",
2786 f->tried_implicit ? "" : " not");
2788 Adding `gettext' calls to this code cannot give correct results for all
2789 languages, because negation in some languages requires adding words at
2790 more than one place in the sentence. By contrast, adding `gettext'
2791 calls does the job straightforwardly if the code starts out like this:
2793 printf (f->tried_implicit
2794 ? "# Implicit rule search has been done.\n",
2795 : "# Implicit rule search has not been done.\n");
2797 Another example is this one:
2799 printf ("%d file%s processed", nfiles,
2800 nfiles != 1 ? "s" : "");
2802 The problem with this example is that it assumes that plurals are made
2803 by adding `s'. If you apply gettext to the format string, like this,
2805 printf (gettext ("%d file%s processed"), nfiles,
2806 nfiles != 1 ? "s" : "");
2808 the message can use different words, but it will still be forced to use
2809 `s' for the plural. Here is a better way, with gettext being applied to
2810 the two strings independently:
2812 printf ((nfiles != 1 ? gettext ("%d files processed")
2813 : gettext ("%d file processed")),
2816 But this still doesn't work for languages like Polish, which has three
2817 plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
2818 24, ... and one for the rest. The GNU `ngettext' function solves this
2821 printf (ngettext ("%d files processed", "%d file processed", nfiles),
2825 File: standards.info, Node: Character Set, Next: Quote Characters, Prev: Internationalization, Up: Writing C
2830 Sticking to the ASCII character set (plain text, 7-bit characters) is
2831 preferred in GNU source code comments, text documents, and other
2832 contexts, unless there is good reason to do something else because of
2833 the application domain. For example, if source code deals with the
2834 French Revolutionary calendar, it is OK if its literal strings contain
2835 accented characters in month names like "Flore'al". Also, it is OK to
2836 use non-ASCII characters to represent proper names of contributors in
2837 change logs (*note Change Logs::).
2839 If you need to use non-ASCII characters, you should normally stick
2840 with one encoding, as one cannot in general mix encodings reliably.
2843 File: standards.info, Node: Quote Characters, Next: Mmap, Prev: Character Set, Up: Writing C
2845 5.10 Quote Characters
2846 =====================
2848 In the C locale, GNU programs should stick to plain ASCII for quotation
2849 characters in messages to users: preferably 0x60 (``') for left quotes
2850 and 0x27 (`'') for right quotes. It is ok, but not required, to use
2851 locale-specific quotes in other locales.
2853 The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
2854 `quotearg' modules provide a reasonably straightforward way to support
2855 locale-specific quote characters, as well as taking care of other
2856 issues, such as quoting a filename that itself contains a quote
2857 character. See the Gnulib documentation for usage details.
2859 In any case, the documentation for your program should clearly
2860 specify how it does quoting, if different than the preferred method of
2861 ``' and `''. This is especially important if the output of your
2862 program is ever likely to be parsed by another program.
2864 Quotation characters are a difficult area in the computing world at
2865 this time: there are no true left or right quote characters in Latin1;
2866 the ``' character we use was standardized there as a grave accent.
2867 Moreover, Latin1 is still not universally usable.
2869 Unicode contains the unambiguous quote characters required, and its
2870 common encoding UTF-8 is upward compatible with Latin1. However,
2871 Unicode and UTF-8 are not universally well-supported, either.
2873 This may change over the next few years, and then we will revisit
2877 File: standards.info, Node: Mmap, Prev: Quote Characters, Up: Writing C
2882 Don't assume that `mmap' either works on all files or fails for all
2883 files. It may work on some files and fail on others.
2885 The proper way to use `mmap' is to try it on the specific file for
2886 which you want to use it--and if `mmap' doesn't work, fall back on
2887 doing the job in another way using `read' and `write'.
2889 The reason this precaution is needed is that the GNU kernel (the
2890 HURD) provides a user-extensible file system, in which there can be many
2891 different kinds of "ordinary files." Many of them support `mmap', but
2892 some do not. It is important to make programs handle all these kinds
2896 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
2898 6 Documenting Programs
2899 **********************
2901 A GNU program should ideally come with full free documentation, adequate
2902 for both reference and tutorial purposes. If the package can be
2903 programmed or extended, the documentation should cover programming or
2904 extending it, as well as just using it.
2908 * GNU Manuals:: Writing proper manuals.
2909 * Doc Strings and Manuals:: Compiling doc strings doesn't make a manual.
2910 * Manual Structure Details:: Specific structure conventions.
2911 * License for Manuals:: Writing the distribution terms for a manual.
2912 * Manual Credits:: Giving credit to documentation contributors.
2913 * Printed Manuals:: Mentioning the printed manual.
2914 * NEWS File:: NEWS files supplement manuals.
2915 * Change Logs:: Recording Changes
2916 * Man Pages:: Man pages are secondary.
2917 * Reading other Manuals:: How far you can go in learning
2921 File: standards.info, Node: GNU Manuals, Next: Doc Strings and Manuals, Up: Documentation
2926 The preferred document format for the GNU system is the Texinfo
2927 formatting language. Every GNU package should (ideally) have
2928 documentation in Texinfo both for reference and for learners. Texinfo
2929 makes it possible to produce a good quality formatted book, using TeX,
2930 and to generate an Info file. It is also possible to generate HTML
2931 output from Texinfo source. See the Texinfo manual, either the
2932 hardcopy, or the on-line version available through `info' or the Emacs
2933 Info subsystem (`C-h i').
2935 Nowadays some other formats such as Docbook and Sgmltexi can be
2936 converted automatically into Texinfo. It is ok to produce the Texinfo
2937 documentation by conversion this way, as long as it gives good results.
2939 Make sure your manual is clear to a reader who knows nothing about
2940 the topic and reads it straight through. This means covering basic
2941 topics at the beginning, and advanced topics only later. This also
2942 means defining every specialized term when it is first used.
2944 Programmers tend to carry over the structure of the program as the
2945 structure for its documentation. But this structure is not necessarily
2946 good for explaining how to use the program; it may be irrelevant and
2947 confusing for a user.
2949 Instead, the right way to structure documentation is according to the
2950 concepts and questions that a user will have in mind when reading it.
2951 This principle applies at every level, from the lowest (ordering
2952 sentences in a paragraph) to the highest (ordering of chapter topics
2953 within the manual). Sometimes this structure of ideas matches the
2954 structure of the implementation of the software being documented--but
2955 often they are different. An important part of learning to write good
2956 documentation is to learn to notice when you have unthinkingly
2957 structured the documentation like the implementation, stop yourself,
2958 and look for better alternatives.
2960 For example, each program in the GNU system probably ought to be
2961 documented in one manual; but this does not mean each program should
2962 have its own manual. That would be following the structure of the
2963 implementation, rather than the structure that helps the user
2966 Instead, each manual should cover a coherent _topic_. For example,
2967 instead of a manual for `diff' and a manual for `diff3', we have one
2968 manual for "comparison of files" which covers both of those programs,
2969 as well as `cmp'. By documenting these programs together, we can make
2970 the whole subject clearer.
2972 The manual which discusses a program should certainly document all of
2973 the program's command-line options and all of its commands. It should
2974 give examples of their use. But don't organize the manual as a list of
2975 features. Instead, organize it logically, by subtopics. Address the
2976 questions that a user will ask when thinking about the job that the
2977 program does. Don't just tell the reader what each feature can do--say
2978 what jobs it is good for, and show how to use it for those jobs.
2979 Explain what is recommended usage, and what kinds of usage users should
2982 In general, a GNU manual should serve both as tutorial and reference.
2983 It should be set up for convenient access to each topic through Info,
2984 and for reading straight through (appendixes aside). A GNU manual
2985 should give a good introduction to a beginner reading through from the
2986 start, and should also provide all the details that hackers want. The
2987 Bison manual is a good example of this--please take a look at it to see
2990 That is not as hard as it first sounds. Arrange each chapter as a
2991 logical breakdown of its topic, but order the sections, and write their
2992 text, so that reading the chapter straight through makes sense. Do
2993 likewise when structuring the book into chapters, and when structuring a
2994 section into paragraphs. The watchword is, _at each point, address the
2995 most fundamental and important issue raised by the preceding text._
2997 If necessary, add extra chapters at the beginning of the manual which
2998 are purely tutorial and cover the basics of the subject. These provide
2999 the framework for a beginner to understand the rest of the manual. The
3000 Bison manual provides a good example of how to do this.
3002 To serve as a reference, a manual should have an Index that list all
3003 the functions, variables, options, and important concepts that are part
3004 of the program. One combined Index should do for a short manual, but
3005 sometimes for a complex package it is better to use multiple indices.
3006 The Texinfo manual includes advice on preparing good index entries, see
3007 *Note Making Index Entries: (texinfo)Index Entries, and see *Note
3008 Defining the Entries of an Index: (texinfo)Indexing Commands.
3010 Don't use Unix man pages as a model for how to write GNU
3011 documentation; most of them are terse, badly structured, and give
3012 inadequate explanation of the underlying concepts. (There are, of
3013 course, some exceptions.) Also, Unix man pages use a particular format
3014 which is different from what we use in GNU manuals.
3016 Please include an email address in the manual for where to report
3017 bugs _in the text of the manual_.
3019 Please do not use the term "pathname" that is used in Unix
3020 documentation; use "file name" (two words) instead. We use the term
3021 "path" only for search paths, which are lists of directory names.
3023 Please do not use the term "illegal" to refer to erroneous input to
3024 a computer program. Please use "invalid" for this, and reserve the
3025 term "illegal" for activities prohibited by law.
3027 Please do not write `()' after a function name just to indicate it
3028 is a function. `foo ()' is not a function, it is a function call with
3032 File: standards.info, Node: Doc Strings and Manuals, Next: Manual Structure Details, Prev: GNU Manuals, Up: Documentation
3034 6.2 Doc Strings and Manuals
3035 ===========================
3037 Some programming systems, such as Emacs, provide a documentation string
3038 for each function, command or variable. You may be tempted to write a
3039 reference manual by compiling the documentation strings and writing a
3040 little additional text to go around them--but you must not do it. That
3041 approach is a fundamental mistake. The text of well-written
3042 documentation strings will be entirely wrong for a manual.
3044 A documentation string needs to stand alone--when it appears on the
3045 screen, there will be no other text to introduce or explain it.
3046 Meanwhile, it can be rather informal in style.
3048 The text describing a function or variable in a manual must not stand
3049 alone; it appears in the context of a section or subsection. Other text
3050 at the beginning of the section should explain some of the concepts, and
3051 should often make some general points that apply to several functions or
3052 variables. The previous descriptions of functions and variables in the
3053 section will also have given information about the topic. A description
3054 written to stand alone would repeat some of that information; this
3055 redundancy looks bad. Meanwhile, the informality that is acceptable in
3056 a documentation string is totally unacceptable in a manual.
3058 The only good way to use documentation strings in writing a good
3059 manual is to use them as a source of information for writing good text.
3062 File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: Doc Strings and Manuals, Up: Documentation
3064 6.3 Manual Structure Details
3065 ============================
3067 The title page of the manual should state the version of the programs or
3068 packages documented in the manual. The Top node of the manual should
3069 also contain this information. If the manual is changing more
3070 frequently than or independent of the program, also state a version
3071 number for the manual in both of these places.
3073 Each program documented in the manual should have a node named
3074 `PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
3075 its subnodes, if any) should describe the program's command line
3076 arguments and how to run it (the sort of information people would look
3077 for in a man page). Start with an `@example' containing a template for
3078 all the options and arguments that the program uses.
3080 Alternatively, put a menu item in some menu whose item name fits one
3081 of the above patterns. This identifies the node which that item points
3082 to as the node for this purpose, regardless of the node's actual name.
3084 The `--usage' feature of the Info reader looks for such a node or
3085 menu item in order to find the relevant text, so it is essential for
3086 every Texinfo file to have one.
3088 If one manual describes several programs, it should have such a node
3089 for each program described in the manual.
3092 File: standards.info, Node: License for Manuals, Next: Manual Credits, Prev: Manual Structure Details, Up: Documentation
3094 6.4 License for Manuals
3095 =======================
3097 Please use the GNU Free Documentation License for all GNU manuals that
3098 are more than a few pages long. Likewise for a collection of short
3099 documents--you only need one copy of the GNU FDL for the whole
3100 collection. For a single short document, you can use a very permissive
3101 non-copyleft license, to avoid taking up space with a long license.
3103 See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
3104 of how to employ the GFDL.
3106 Note that it is not obligatory to include a copy of the GNU GPL or
3107 GNU LGPL in a manual whose license is neither the GPL nor the LGPL. It
3108 can be a good idea to include the program's license in a large manual;
3109 in a short manual, whose size would be increased considerably by
3110 including the program's license, it is probably better not to include
3114 File: standards.info, Node: Manual Credits, Next: Printed Manuals, Prev: License for Manuals, Up: Documentation
3119 Please credit the principal human writers of the manual as the authors,
3120 on the title page of the manual. If a company sponsored the work, thank
3121 the company in a suitable place in the manual, but do not cite the
3122 company as an author.
3125 File: standards.info, Node: Printed Manuals, Next: NEWS File, Prev: Manual Credits, Up: Documentation
3130 The FSF publishes some GNU manuals in printed form. To encourage sales
3131 of these manuals, the on-line versions of the manual should mention at
3132 the very start that the printed manual is available and should point at
3133 information for getting it--for instance, with a link to the page
3134 `http://www.gnu.org/order/order.html'. This should not be included in
3135 the printed manual, though, because there it is redundant.
3137 It is also useful to explain in the on-line forms of the manual how
3138 the user can print out the manual from the sources.
3141 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Printed Manuals, Up: Documentation
3146 In addition to its manual, the package should have a file named `NEWS'
3147 which contains a list of user-visible changes worth mentioning. In
3148 each new release, add items to the front of the file and identify the
3149 version they pertain to. Don't discard old items; leave them in the
3150 file after the newer items. This way, a user upgrading from any
3151 previous version can see what is new.
3153 If the `NEWS' file gets very long, move some of the older items into
3154 a file named `ONEWS' and put a note at the end referring the user to
3158 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
3163 Keep a change log to describe all the changes made to program source
3164 files. The purpose of this is so that people investigating bugs in the
3165 future will know about the changes that might have introduced the bug.
3166 Often a new bug can be found by looking at what was recently changed.
3167 More importantly, change logs can help you eliminate conceptual
3168 inconsistencies between different parts of a program, by giving you a
3169 history of how the conflicting concepts arose and who they came from.
3173 * Change Log Concepts::
3174 * Style of Change Logs::
3176 * Conditional Changes::
3177 * Indicating the Part Changed::
3180 File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
3182 6.8.1 Change Log Concepts
3183 -------------------------
3185 You can think of the change log as a conceptual "undo list" which
3186 explains how earlier versions were different from the current version.
3187 People can see the current version; they don't need the change log to
3188 tell them what is in it. What they want from a change log is a clear
3189 explanation of how the earlier version differed.
3191 The change log file is normally called `ChangeLog' and covers an
3192 entire directory. Each directory can have its own change log, or a
3193 directory can use the change log of its parent directory-it's up to you.
3195 Another alternative is to record change log information with a
3196 version control system such as RCS or CVS. This can be converted
3197 automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
3198 command `C-x v a' (`vc-update-change-log') does the job.
3200 There's no need to describe the full purpose of the changes or how
3201 they work together. If you think that a change calls for explanation,
3202 you're probably right. Please do explain it--but please put the
3203 explanation in comments in the code, where people will see it whenever
3204 they see the code. For example, "New function" is enough for the
3205 change log when you add a function, because there should be a comment
3206 before the function definition to explain what it does.
3208 In the past, we recommended not mentioning changes in non-software
3209 files (manuals, help files, etc.) in change logs. However, we've been
3210 advised that it is a good idea to include them, for the sake of
3213 However, sometimes it is useful to write one line to describe the
3214 overall purpose of a batch of changes.
3216 The easiest way to add an entry to `ChangeLog' is with the Emacs
3217 command `M-x add-change-log-entry'. An entry should have an asterisk,
3218 the name of the changed file, and then in parentheses the name of the
3219 changed functions, variables or whatever, followed by a colon. Then
3220 describe the changes you made to that function or variable.
3223 File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
3225 6.8.2 Style of Change Logs
3226 --------------------------
3228 Here are some simple examples of change log entries, starting with the
3229 header line that says who made the change and when it was installed,
3230 followed by descriptions of specific changes. (These examples are
3231 drawn from Emacs and GCC.)
3233 1998-08-17 Richard Stallman <rms@gnu.org>
3235 * register.el (insert-register): Return nil.
3236 (jump-to-register): Likewise.
3238 * sort.el (sort-subr): Return nil.
3240 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3241 Restart the tex shell if process is gone or stopped.
3242 (tex-shell-running): New function.
3244 * expr.c (store_one_arg): Round size up for move_block_to_reg.
3245 (expand_call): Round up when emitting USE insns.
3246 * stmt.c (assign_parms): Round size up for move_block_from_reg.
3248 It's important to name the changed function or variable in full.
3249 Don't abbreviate function or variable names, and don't combine them.
3250 Subsequent maintainers will often search for a function name to find all
3251 the change log entries that pertain to it; if you abbreviate the name,
3252 they won't find it when they search.
3254 For example, some people are tempted to abbreviate groups of function
3255 names by writing `* register.el ({insert,jump-to}-register)'; this is
3256 not a good idea, since searching for `jump-to-register' or
3257 `insert-register' would not find that entry.
3259 Separate unrelated change log entries with blank lines. When two
3260 entries represent parts of the same change, so that they work together,
3261 then don't put blank lines between them. Then you can omit the file
3262 name and the asterisk when successive entries are in the same file.
3264 Break long lists of function names by closing continued lines with
3265 `)', rather than `,', and opening the continuation with `(' as in this
3268 * keyboard.c (menu_bar_items, tool_bar_items)
3269 (Fexecute_extended_command): Deal with `keymap' property.
3271 When you install someone else's changes, put the contributor's name
3272 in the change log entry rather than in the text of the entry. In other
3275 2002-07-14 John Doe <jdoe@gnu.org>
3277 * sewing.c: Make it sew.
3281 2002-07-14 Usual Maintainer <usual@gnu.org>
3283 * sewing.c: Make it sew. Patch by jdoe@gnu.org.
3285 As for the date, that should be the date you applied the change.
3288 File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
3290 6.8.3 Simple Changes
3291 --------------------
3293 Certain simple kinds of changes don't need much detail in the change
3296 When you change the calling sequence of a function in a simple
3297 fashion, and you change all the callers of the function to use the new
3298 calling sequence, there is no need to make individual entries for all
3299 the callers that you changed. Just write in the entry for the function
3300 being called, "All callers changed"--like this:
3302 * keyboard.c (Fcommand_execute): New arg SPECIAL.
3303 All callers changed.
3305 When you change just comments or doc strings, it is enough to write
3306 an entry for the file, without mentioning the functions. Just "Doc
3307 fixes" is enough for the change log.
3309 There's no technical need to make change log entries for
3310 documentation files. This is because documentation is not susceptible
3311 to bugs that are hard to fix. Documentation does not consist of parts
3312 that must interact in a precisely engineered fashion. To correct an
3313 error, you need not know the history of the erroneous passage; it is
3314 enough to compare what the documentation says with the way the program
3317 However, you should keep change logs for documentation files when the
3318 project gets copyright assignments from its contributors, so as to make
3319 the records of authorship more accurate.
3322 File: standards.info, Node: Conditional Changes, Next: Indicating the Part Changed, Prev: Simple Changes, Up: Change Logs
3324 6.8.4 Conditional Changes
3325 -------------------------
3327 C programs often contain compile-time `#if' conditionals. Many changes
3328 are conditional; sometimes you add a new definition which is entirely
3329 contained in a conditional. It is very useful to indicate in the
3330 change log the conditions for which the change applies.
3332 Our convention for indicating conditional changes is to use square
3333 brackets around the name of the condition.
3335 Here is a simple example, describing a change which is conditional
3336 but does not have a function or entity name associated with it:
3338 * xterm.c [SOLARIS2]: Include string.h.
3340 Here is an entry describing a new definition which is entirely
3341 conditional. This new definition for the macro `FRAME_WINDOW_P' is
3342 used only when `HAVE_X_WINDOWS' is defined:
3344 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3346 Here is an entry for a change within the function `init_display',
3347 whose definition as a whole is unconditional, but the changes themselves
3348 are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
3350 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3352 Here is an entry for a change that takes affect only when a certain
3353 macro is _not_ defined:
3355 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3358 File: standards.info, Node: Indicating the Part Changed, Prev: Conditional Changes, Up: Change Logs
3360 6.8.5 Indicating the Part Changed
3361 ---------------------------------
3363 Indicate the part of a function which changed by using angle brackets
3364 enclosing an indication of what the changed part does. Here is an entry
3365 for a change in the part of the function `sh-while-getopts' that deals
3368 * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
3369 user-specified option string is empty.
3372 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
3377 In the GNU project, man pages are secondary. It is not necessary or
3378 expected for every GNU program to have a man page, but some of them do.
3379 It's your choice whether to include a man page in your program.
3381 When you make this decision, consider that supporting a man page
3382 requires continual effort each time the program is changed. The time
3383 you spend on the man page is time taken away from more useful work.
3385 For a simple program which changes little, updating the man page may
3386 be a small job. Then there is little reason not to include a man page,
3389 For a large program that changes a great deal, updating a man page
3390 may be a substantial burden. If a user offers to donate a man page,
3391 you may find this gift costly to accept. It may be better to refuse
3392 the man page unless the same person agrees to take full responsibility
3393 for maintaining it--so that you can wash your hands of it entirely. If
3394 this volunteer later ceases to do the job, then don't feel obliged to
3395 pick it up yourself; it may be better to withdraw the man page from the
3396 distribution until someone else agrees to update it.
3398 When a program changes only a little, you may feel that the
3399 discrepancies are small enough that the man page remains useful without
3400 updating. If so, put a prominent note near the beginning of the man
3401 page explaining that you don't maintain it and that the Texinfo manual
3402 is more authoritative. The note should say how to access the Texinfo
3405 Be sure that man pages include a copyright statement and free
3406 license. The simple all-permissive license is appropriate for simple
3409 Copying and distribution of this file, with or without modification,
3410 are permitted in any medium without royalty provided the copyright
3411 notice and this notice are preserved.
3413 For long man pages, with enough explanation and documentation that
3414 they can be considered true manuals, use the GFDL (*note License for
3417 Finally, the GNU help2man program
3418 (`http://www.gnu.org/software/help2man/') is one way to automate
3419 generation of a man page, in this case from `--help' output. This is
3420 sufficient in many cases.
3423 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
3425 6.10 Reading other Manuals
3426 ==========================
3428 There may be non-free books or documentation files that describe the
3429 program you are documenting.
3431 It is ok to use these documents for reference, just as the author of
3432 a new algebra textbook can read other books on algebra. A large portion
3433 of any non-fiction book consists of facts, in this case facts about how
3434 a certain program works, and these facts are necessarily the same for
3435 everyone who writes about the subject. But be careful not to copy your
3436 outline structure, wording, tables or examples from preexisting non-free
3437 documentation. Copying from free documentation may be ok; please check
3438 with the FSF about the individual case.
3441 File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
3443 7 The Release Process
3444 *********************
3446 Making a release is more than just bundling up your source files in a
3447 tar file and putting it up for FTP. You should set up your software so
3448 that it can be configured to run on a variety of systems. Your Makefile
3449 should conform to the GNU standards described below, and your directory
3450 layout should also conform to the standards discussed below. Doing so
3451 makes it easy to include your package into the larger framework of all
3456 * Configuration:: How Configuration Should Work
3457 * Makefile Conventions:: Makefile Conventions
3458 * Releases:: Making Releases
3461 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
3463 7.1 How Configuration Should Work
3464 =================================
3466 Each GNU distribution should come with a shell script named
3467 `configure'. This script is given arguments which describe the kind of
3468 machine and system you want to compile the program for.
3470 The `configure' script must record the configuration options so that
3471 they affect compilation.
3473 One way to do this is to make a link from a standard name such as
3474 `config.h' to the proper configuration file for the chosen system. If
3475 you use this technique, the distribution should _not_ contain a file
3476 named `config.h'. This is so that people won't be able to build the
3477 program without configuring it first.
3479 Another thing that `configure' can do is to edit the Makefile. If
3480 you do this, the distribution should _not_ contain a file named
3481 `Makefile'. Instead, it should include a file `Makefile.in' which
3482 contains the input used for editing. Once again, this is so that people
3483 won't be able to build the program without configuring it first.
3485 If `configure' does write the `Makefile', then `Makefile' should
3486 have a target named `Makefile' which causes `configure' to be rerun,
3487 setting up the same configuration that was set up last time. The files
3488 that `configure' reads should be listed as dependencies of `Makefile'.
3490 All the files which are output from the `configure' script should
3491 have comments at the beginning explaining that they were generated
3492 automatically using `configure'. This is so that users won't think of
3493 trying to edit them by hand.
3495 The `configure' script should write a file named `config.status'
3496 which describes which configuration options were specified when the
3497 program was last configured. This file should be a shell script which,
3498 if run, will recreate the same configuration.
3500 The `configure' script should accept an option of the form
3501 `--srcdir=DIRNAME' to specify the directory where sources are found (if
3502 it is not the current directory). This makes it possible to build the
3503 program in a separate directory, so that the actual source directory is
3506 If the user does not specify `--srcdir', then `configure' should
3507 check both `.' and `..' to see if it can find the sources. If it finds
3508 the sources in one of these places, it should use them from there.
3509 Otherwise, it should report that it cannot find the sources, and should
3510 exit with nonzero status.
3512 Usually the easy way to support `--srcdir' is by editing a
3513 definition of `VPATH' into the Makefile. Some rules may need to refer
3514 explicitly to the specified source directory. To make this possible,
3515 `configure' can add to the Makefile a variable named `srcdir' whose
3516 value is precisely the specified directory.
3518 The `configure' script should also take an argument which specifies
3519 the type of system to build the program for. This argument should look
3524 For example, an Athlon-based GNU/Linux system might be
3525 `i686-pc-linux-gnu'.
3527 The `configure' script needs to be able to decode all plausible
3528 alternatives for how to describe a machine. Thus,
3529 `athlon-pc-gnu/linux' would be a valid alias. There is a shell script
3531 (http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub)
3532 that you can use as a subroutine to validate system types and
3533 canonicalize aliases.
3535 The `configure' script should also take the option
3536 `--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
3537 argument. For example, `configure --build=i686-pc-linux-gnu' is
3538 equivalent to `configure i686-pc-linux-gnu'. When the build type is
3539 not specified by an option or argument, the `configure' script should
3540 normally guess it using the shell script `config.guess'
3541 (http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess).
3543 Other options are permitted to specify in more detail the software
3544 or hardware present on the machine, to include or exclude optional parts
3545 of the package, or to adjust the name of some tools or arguments to
3548 `--enable-FEATURE[=PARAMETER]'
3549 Configure the package to build and install an optional user-level
3550 facility called FEATURE. This allows users to choose which
3551 optional features to include. Giving an optional PARAMETER of
3552 `no' should omit FEATURE, if it is built by default.
3554 No `--enable' option should *ever* cause one feature to replace
3555 another. No `--enable' option should ever substitute one useful
3556 behavior for another useful behavior. The only proper use for
3557 `--enable' is for questions of whether to build part of the program
3561 The package PACKAGE will be installed, so configure this package
3562 to work with PACKAGE.
3564 Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
3565 `gnu-libc', `gdb', `x', and `x-toolkit'.
3567 Do not use a `--with' option to specify the file name to use to
3568 find certain files. That is outside the scope of what `--with'
3572 Set the value of the variable VARIABLE to VALUE. This is used to
3573 override the default values of commands or arguments in the build
3574 process. For example, the user could issue `configure CFLAGS=-g
3575 CXXFLAGS=-g' to build with debugging information and without the
3576 default optimization.
3578 Specifying variables as arguments to `configure', like this:
3580 is preferable to setting them in environment variables:
3582 as it helps to recreate the same configuration later with
3585 All `configure' scripts should accept all of the "detail" options
3586 and the variable settings, whether or not they make any difference to
3587 the particular package at hand. In particular, they should accept any
3588 option that starts with `--with-' or `--enable-'. This is so users
3589 will be able to configure an entire GNU source tree at once with a
3590 single set of options.
3592 You will note that the categories `--with-' and `--enable-' are
3593 narrow: they *do not* provide a place for any sort of option you might
3594 think of. That is deliberate. We want to limit the possible
3595 configuration options in GNU software. We do not want GNU programs to
3596 have idiosyncratic configuration options.
3598 Packages that perform part of the compilation process may support
3599 cross-compilation. In such a case, the host and target machines for the
3600 program may be different.
3602 The `configure' script should normally treat the specified type of
3603 system as both the host and the target, thus producing a program which
3604 works for the same type of machine that it runs on.
3606 To compile a program to run on a host type that differs from the
3607 build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
3608 uses the same syntax as BUILDTYPE. The host type normally defaults to
3611 To configure a cross-compiler, cross-assembler, or what have you, you
3612 should specify a target different from the host, using the configure
3613 option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
3614 for the host type. So the command would look like this:
3616 ./configure --host=HOSTTYPE --target=TARGETTYPE
3618 The target type normally defaults to the host type. Programs for
3619 which cross-operation is not meaningful need not accept the `--target'
3620 option, because configuring an entire operating system for
3621 cross-operation is not a meaningful operation.
3623 Some programs have ways of configuring themselves automatically. If
3624 your program is set up to do this, your `configure' script can simply
3625 ignore most of its arguments.
3628 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
3630 7.2 Makefile Conventions
3631 ========================
3633 This node describes conventions for writing the Makefiles for GNU
3634 programs. Using Automake will help you write a Makefile that follows
3639 * Makefile Basics:: General conventions for Makefiles.
3640 * Utilities in Makefiles:: Utilities to be used in Makefiles.
3641 * Command Variables:: Variables for specifying commands.
3642 * DESTDIR:: Supporting staged installs.
3643 * Directory Variables:: Variables for installation directories.
3644 * Standard Targets:: Standard targets for users.
3645 * Install Command Categories:: Three categories of commands in the `install'
3646 rule: normal, pre-install and post-install.
3649 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
3651 7.2.1 General Conventions for Makefiles
3652 ---------------------------------------
3654 Every Makefile should contain this line:
3658 to avoid trouble on systems where the `SHELL' variable might be
3659 inherited from the environment. (This is never a problem with GNU
3662 Different `make' programs have incompatible suffix lists and
3663 implicit rules, and this sometimes creates confusion or misbehavior. So
3664 it is a good idea to set the suffix list explicitly using only the
3665 suffixes you need in the particular Makefile, like this:
3670 The first line clears out the suffix list, the second introduces all
3671 suffixes which may be subject to implicit rules in this Makefile.
3673 Don't assume that `.' is in the path for command execution. When
3674 you need to run programs that are a part of your package during the
3675 make, please make sure that it uses `./' if the program is built as
3676 part of the make or `$(srcdir)/' if the file is an unchanging part of
3677 the source code. Without one of these prefixes, the current search
3680 The distinction between `./' (the "build directory") and
3681 `$(srcdir)/' (the "source directory") is important because users can
3682 build in a separate directory using the `--srcdir' option to
3683 `configure'. A rule of the form:
3685 foo.1 : foo.man sedscript
3686 sed -e sedscript foo.man > foo.1
3688 will fail when the build directory is not the source directory, because
3689 `foo.man' and `sedscript' are in the source directory.
3691 When using GNU `make', relying on `VPATH' to find the source file
3692 will work in the case where there is a single dependency file, since
3693 the `make' automatic variable `$<' will represent the source file
3694 wherever it is. (Many versions of `make' set `$<' only in implicit
3695 rules.) A Makefile target like
3698 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
3700 should instead be written as
3703 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
3705 in order to allow `VPATH' to work correctly. When the target has
3706 multiple dependencies, using an explicit `$(srcdir)' is the easiest way
3707 to make the rule work well. For example, the target above for `foo.1'
3710 foo.1 : foo.man sedscript
3711 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
3713 GNU distributions usually contain some files which are not source
3714 files--for example, Info files, and the output from Autoconf, Automake,
3715 Bison or Flex. Since these files normally appear in the source
3716 directory, they should always appear in the source directory, not in the
3717 build directory. So Makefile rules to update them should put the
3718 updated files in the source directory.
3720 However, if a file does not appear in the distribution, then the
3721 Makefile should not put it in the source directory, because building a
3722 program in ordinary circumstances should not modify the source directory
3725 Try to make the build and installation targets, at least (and all
3726 their subtargets) work correctly with a parallel `make'.
3729 File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
3731 7.2.2 Utilities in Makefiles
3732 ----------------------------
3734 Write the Makefile commands (and any shell scripts, such as
3735 `configure') to run in `sh', not in `csh'. Don't use any special
3736 features of `ksh' or `bash'.
3738 The `configure' script and the Makefile rules for building and
3739 installation should not use any utilities directly except these:
3741 cat cmp cp diff echo egrep expr false grep install-info
3742 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
3744 The compression program `gzip' can be used in the `dist' rule.
3746 Stick to the generally supported options for these programs. For
3747 example, don't use `mkdir -p', convenient as it may be, because most
3748 systems don't support it.
3750 It is a good idea to avoid creating symbolic links in makefiles,
3751 since a few systems don't support them.
3753 The Makefile rules for building and installation can also use
3754 compilers and related programs, but should do so via `make' variables
3755 so that the user can substitute alternatives. Here are some of the
3758 ar bison cc flex install ld ldconfig lex
3759 make makeinfo ranlib texi2dvi yacc
3761 Use the following `make' variables to run those programs:
3763 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
3764 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
3766 When you use `ranlib' or `ldconfig', you should make sure nothing
3767 bad happens if the system does not have the program in question.
3768 Arrange to ignore an error from that command, and print a message before
3769 the command to tell the user that failure of this command does not mean
3770 a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
3772 If you use symbolic links, you should implement a fallback for
3773 systems that don't have symbolic links.
3775 Additional utilities that can be used via Make variables are:
3777 chgrp chmod chown mknod
3779 It is ok to use other utilities in Makefile portions (or scripts)
3780 intended only for particular systems where you know those utilities
3784 File: standards.info, Node: Command Variables, Next: DESTDIR, Prev: Utilities in Makefiles, Up: Makefile Conventions
3786 7.2.3 Variables for Specifying Commands
3787 ---------------------------------------
3789 Makefiles should provide variables for overriding certain commands,
3792 In particular, you should run most utility programs via variables.
3793 Thus, if you use Bison, have a variable named `BISON' whose default
3794 value is set with `BISON = bison', and refer to it with `$(BISON)'
3795 whenever you need to use Bison.
3797 File management utilities such as `ln', `rm', `mv', and so on, need
3798 not be referred to through variables in this way, since users don't
3799 need to replace them with other programs.
3801 Each program-name variable should come with an options variable that
3802 is used to supply options to the program. Append `FLAGS' to the
3803 program-name variable name to get the options variable name--for
3804 example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
3805 `YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
3806 but we keep them because they are standard.) Use `CPPFLAGS' in any
3807 compilation command that runs the preprocessor, and use `LDFLAGS' in
3808 any compilation command that does linking as well as in any direct use
3811 If there are C compiler options that _must_ be used for proper
3812 compilation of certain files, do not include them in `CFLAGS'. Users
3813 expect to be able to specify `CFLAGS' freely themselves. Instead,
3814 arrange to pass the necessary options to the C compiler independently
3815 of `CFLAGS', by writing them explicitly in the compilation commands or
3816 by defining an implicit rule, like this:
3819 ALL_CFLAGS = -I. $(CFLAGS)
3821 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
3823 Do include the `-g' option in `CFLAGS', because that is not
3824 _required_ for proper compilation. You can consider it a default that
3825 is only recommended. If the package is set up so that it is compiled
3826 with GCC by default, then you might as well include `-O' in the default
3827 value of `CFLAGS' as well.
3829 Put `CFLAGS' last in the compilation command, after other variables
3830 containing compiler options, so the user can use `CFLAGS' to override
3833 `CFLAGS' should be used in every invocation of the C compiler, both
3834 those which do compilation and those which do linking.
3836 Every Makefile should define the variable `INSTALL', which is the
3837 basic command for installing a file into the system.
3839 Every Makefile should also define the variables `INSTALL_PROGRAM'
3840 and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
3841 `$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
3842 644'.) Then it should use those variables as the commands for actual
3843 installation, for executables and non-executables respectively.
3844 Minimal use of these variables is as follows:
3846 $(INSTALL_PROGRAM) foo $(bindir)/foo
3847 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
3849 However, it is preferable to support a `DESTDIR' prefix on the
3850 target files, as explained in the next section.
3852 Always use a file name, not a directory name, as the second argument of
3853 the installation commands. Use a separate command for each file to be
3857 File: standards.info, Node: DESTDIR, Next: Directory Variables, Prev: Command Variables, Up: Makefile Conventions
3859 7.2.4 `DESTDIR': support for staged installs
3860 --------------------------------------------
3862 `DESTDIR' is a variable prepended to each installed target file, like
3865 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
3866 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
3868 The `DESTDIR' variable is specified by the user on the `make'
3869 command line. For example:
3871 make DESTDIR=/tmp/stage install
3873 `DESTDIR' should be supported only in the `install*' and `uninstall*'
3874 targets, as those are the only targets where it is useful.
3876 If your installation step would normally install
3877 `/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
3878 installation invoked as in the example above would install
3879 `/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
3882 Prepending the variable `DESTDIR' to each target in this way
3883 provides for "staged installs", where the installed files are not
3884 placed directly into their expected location but are instead copied
3885 into a temporary location (`DESTDIR'). However, installed files
3886 maintain their relative directory structure and any embedded file names
3887 will not be modified.
3889 You should not set the value of `DESTDIR' in your `Makefile' at all;
3890 then the files are installed into their expected locations by default.
3891 Also, specifying `DESTDIR' should not change the operation of the
3892 software in any way, so its value should not be included in any file
3895 `DESTDIR' support is commonly used in package creation. It is also
3896 helpful to users who want to understand what a given package will
3897 install where, and to allow users who don't normally have permissions
3898 to install into protected areas to build and install before gaining
3899 those permissions. Finally, it can be useful with tools such as
3900 `stow', where code is installed in one place but made to appear to be
3901 installed somewhere else using symbolic links or special mount
3902 operations. So, we strongly recommend GNU packages support `DESTDIR',
3903 though it is not an absolute requirement.
3906 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: DESTDIR, Up: Makefile Conventions
3908 7.2.5 Variables for Installation Directories
3909 --------------------------------------------
3911 Installation directories should always be named by variables, so it is
3912 easy to install in a nonstandard place. The standard names for these
3913 variables and the values they should have in GNU packages are described
3914 below. They are based on a standard file system layout; variants of it
3915 are used in GNU/Linux and other modern operating systems.
3917 Installers are expected to override these values when calling `make'
3918 (e.g., `make prefix=/usr install' or `configure' (e.g., `configure
3919 --prefix=/usr'). GNU packages should not try to guess which value
3920 should be appropriate for these variables on the system they are being
3921 installed onto: use the default settings specified here so that all GNU
3922 packages behave identically, allowing the installer to achieve any
3925 These first two variables set the root for the installation. All the
3926 other installation directories should be subdirectories of one of these
3927 two, and nothing should be directly installed into these two
3931 A prefix used in constructing the default values of the variables
3932 listed below. The default value of `prefix' should be
3933 `/usr/local'. When building the complete GNU system, the prefix
3934 will be empty and `/usr' will be a symbolic link to `/'. (If you
3935 are using Autoconf, write it as `@prefix@'.)
3937 Running `make install' with a different value of `prefix' from the
3938 one used to build the program should _not_ recompile the program.
3941 A prefix used in constructing the default values of some of the
3942 variables listed below. The default value of `exec_prefix' should
3943 be `$(prefix)'. (If you are using Autoconf, write it as
3946 Generally, `$(exec_prefix)' is used for directories that contain
3947 machine-specific files (such as executables and subroutine
3948 libraries), while `$(prefix)' is used directly for other
3951 Running `make install' with a different value of `exec_prefix'
3952 from the one used to build the program should _not_ recompile the
3955 Executable programs are installed in one of the following
3959 The directory for installing executable programs that users can
3960 run. This should normally be `/usr/local/bin', but write it as
3961 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
3965 The directory for installing executable programs that can be run
3966 from the shell, but are only generally useful to system
3967 administrators. This should normally be `/usr/local/sbin', but
3968 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
3969 write it as `@sbindir@'.)
3972 The directory for installing executable programs to be run by other
3973 programs rather than by users. This directory should normally be
3974 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
3975 (If you are using Autoconf, write it as `@libexecdir@'.)
3977 The definition of `libexecdir' is the same for all packages, so
3978 you should install your data in a subdirectory thereof. Most
3979 packages install their data under `$(libexecdir)/PACKAGE-NAME/',
3980 possibly within additional subdirectories thereof, such as
3981 `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
3983 Data files used by the program during its execution are divided into
3984 categories in two ways.
3986 * Some files are normally modified by programs; others are never
3987 normally modified (though users may edit some of these).
3989 * Some files are architecture-independent and can be shared by all
3990 machines at a site; some are architecture-dependent and can be
3991 shared only by machines of the same kind and operating system;
3992 others may never be shared between two machines.
3994 This makes for six different possibilities. However, we want to
3995 discourage the use of architecture-dependent files, aside from object
3996 files and libraries. It is much cleaner to make other data files
3997 architecture-independent, and it is generally not hard.
3999 Here are the variables Makefiles should use to specify directories
4000 to put these various kinds of files in:
4003 The root of the directory tree for read-only
4004 architecture-independent data files. This should normally be
4005 `/usr/local/share', but write it as `$(prefix)/share'. (If you
4006 are using Autoconf, write it as `@datarootdir@'.) `datadir''s
4007 default value is based on this variable; so are `infodir',
4008 `mandir', and others.
4011 The directory for installing idiosyncratic read-only
4012 architecture-independent data files for this program. This is
4013 usually the same place as `datarootdir', but we use the two
4014 separate variables so that you can move these program-specific
4015 files without altering the location for Info files, man pages, etc.
4017 This should normally be `/usr/local/share', but write it as
4018 `$(datarootdir)'. (If you are using Autoconf, write it as
4021 The definition of `datadir' is the same for all packages, so you
4022 should install your data in a subdirectory thereof. Most packages
4023 install their data under `$(datadir)/PACKAGE-NAME/'.
4026 The directory for installing read-only data files that pertain to a
4027 single machine-that is to say, files for configuring a host.
4028 Mailer and network configuration files, `/etc/passwd', and so
4029 forth belong here. All the files in this directory should be
4030 ordinary ASCII text files. This directory should normally be
4031 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
4032 using Autoconf, write it as `@sysconfdir@'.)
4034 Do not install executables here in this directory (they probably
4035 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
4036 files that are modified in the normal course of their use (programs
4037 whose purpose is to change the configuration of the system
4038 excluded). Those probably belong in `$(localstatedir)'.
4041 The directory for installing architecture-independent data files
4042 which the programs modify while they run. This should normally be
4043 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
4044 using Autoconf, write it as `@sharedstatedir@'.)
4047 The directory for installing data files which the programs modify
4048 while they run, and that pertain to one specific machine. Users
4049 should never need to modify files in this directory to configure
4050 the package's operation; put such configuration information in
4051 separate files that go in `$(datadir)' or `$(sysconfdir)'.
4052 `$(localstatedir)' should normally be `/usr/local/var', but write
4053 it as `$(prefix)/var'. (If you are using Autoconf, write it as
4056 These variables specify the directory for installing certain specific
4057 types of files, if your program has them. Every GNU package should
4058 have Info files, so every program needs `infodir', but not all need
4059 `libdir' or `lispdir'.
4062 The directory for installing header files to be included by user
4063 programs with the C `#include' preprocessor directive. This
4064 should normally be `/usr/local/include', but write it as
4065 `$(prefix)/include'. (If you are using Autoconf, write it as
4068 Most compilers other than GCC do not look for header files in
4069 directory `/usr/local/include'. So installing the header files
4070 this way is only useful with GCC. Sometimes this is not a problem
4071 because some libraries are only really intended to work with GCC.
4072 But some libraries are intended to work with other compilers.
4073 They should install their header files in two places, one
4074 specified by `includedir' and one specified by `oldincludedir'.
4077 The directory for installing `#include' header files for use with
4078 compilers other than GCC. This should normally be `/usr/include'.
4079 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
4081 The Makefile commands should check whether the value of
4082 `oldincludedir' is empty. If it is, they should not try to use
4083 it; they should cancel the second installation of the header files.
4085 A package should not replace an existing header in this directory
4086 unless the header came from the same package. Thus, if your Foo
4087 package provides a header file `foo.h', then it should install the
4088 header file in the `oldincludedir' directory if either (1) there
4089 is no `foo.h' there or (2) the `foo.h' that exists came from the
4092 To tell whether `foo.h' came from the Foo package, put a magic
4093 string in the file--part of a comment--and `grep' for that string.
4096 The directory for installing documentation files (other than Info)
4097 for this package. By default, it should be
4098 `/usr/local/share/doc/YOURPKG', but it should be written as
4099 `$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write
4100 it as `@docdir@'.) The YOURPKG subdirectory, which may include a
4101 version number, prevents collisions among files with common names,
4105 The directory for installing the Info files for this package. By
4106 default, it should be `/usr/local/share/info', but it should be
4107 written as `$(datarootdir)/info'. (If you are using Autoconf,
4108 write it as `@infodir@'.) `infodir' is separate from `docdir' for
4109 compatibility with existing practice.
4115 Directories for installing documentation files in the particular
4116 format. They should all be set to `$(docdir)' by default. (If
4117 you are using Autoconf, write them as `@htmldir@', `@dvidir@',
4118 etc.) Packages which supply several translations of their
4119 documentation should install them in `$(htmldir)/'LL,
4120 `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
4124 The directory for object files and libraries of object code. Do
4125 not install executables here, they probably ought to go in
4126 `$(libexecdir)' instead. The value of `libdir' should normally be
4127 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
4128 are using Autoconf, write it as `@libdir@'.)
4131 The directory for installing any Emacs Lisp files in this package.
4132 By default, it should be `/usr/local/share/emacs/site-lisp', but
4133 it should be written as `$(datarootdir)/emacs/site-lisp'.
4135 If you are using Autoconf, write the default as `@lispdir@'. In
4136 order to make `@lispdir@' work, you need the following lines in
4137 your `configure.in' file:
4139 lispdir='${datarootdir}/emacs/site-lisp'
4143 The directory for installing locale-specific message catalogs for
4144 this package. By default, it should be `/usr/local/share/locale',
4145 but it should be written as `$(datarootdir)/locale'. (If you are
4146 using Autoconf, write it as `@localedir@'.) This directory
4147 usually has a subdirectory per locale.
4149 Unix-style man pages are installed in one of the following:
4152 The top-level directory for installing the man pages (if any) for
4153 this package. It will normally be `/usr/local/share/man', but you
4154 should write it as `$(datarootdir)/man'. (If you are using
4155 Autoconf, write it as `@mandir@'.)
4158 The directory for installing section 1 man pages. Write it as
4162 The directory for installing section 2 man pages. Write it as
4166 *Don't make the primary documentation for any GNU software be a
4167 man page. Write a manual in Texinfo instead. Man pages are just
4168 for the sake of people running GNU software on Unix, which is a
4169 secondary application only.*
4172 The file name extension for the installed man page. This should
4173 contain a period followed by the appropriate digit; it should
4177 The file name extension for installed section 1 man pages.
4180 The file name extension for installed section 2 man pages.
4183 Use these names instead of `manext' if the package needs to
4184 install man pages in more than one section of the manual.
4186 And finally, you should set the following variable:
4189 The directory for the sources being compiled. The value of this
4190 variable is normally inserted by the `configure' shell script.
4191 (If you are using Autoconf, use `srcdir = @srcdir@'.)
4195 # Common prefix for installation directories.
4196 # NOTE: This directory must exist when you start the install.
4198 datarootdir = $(prefix)/share
4199 datadir = $(datarootdir)
4200 exec_prefix = $(prefix)
4201 # Where to put the executable for the command `gcc'.
4202 bindir = $(exec_prefix)/bin
4203 # Where to put the directories used by the compiler.
4204 libexecdir = $(exec_prefix)/libexec
4205 # Where to put the Info files.
4206 infodir = $(datarootdir)/info
4208 If your program installs a large number of files into one of the
4209 standard user-specified directories, it might be useful to group them
4210 into a subdirectory particular to that program. If you do this, you
4211 should write the `install' rule to create these subdirectories.
4213 Do not expect the user to include the subdirectory name in the value
4214 of any of the variables listed above. The idea of having a uniform set
4215 of variable names for installation directories is to enable the user to
4216 specify the exact same values for several different GNU packages. In
4217 order for this to be useful, all the packages must be designed so that
4218 they will work sensibly when the user does so.
4220 At times, not all of these variables may be implemented in the
4221 current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
4222 believe all of them are. When any are missing, the descriptions here
4223 serve as specifications for what Autoconf will implement. As a
4224 programmer, you can either use a development version of Autoconf or
4225 avoid using these variables until a stable release is made which
4229 File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
4231 7.2.6 Standard Targets for Users
4232 --------------------------------
4234 All GNU programs should have the following targets in their Makefiles:
4237 Compile the entire program. This should be the default target.
4238 This target need not rebuild any documentation files; Info files
4239 should normally be included in the distribution, and DVI (and other
4240 documentation format) files should be made only when explicitly
4243 By default, the Make rules should compile and link with `-g', so
4244 that executable programs have debugging symbols. Users who don't
4245 mind being helpless can strip the executables later if they wish.
4248 Compile the program and copy the executables, libraries, and so on
4249 to the file names where they should reside for actual use. If
4250 there is a simple test to verify that a program is properly
4251 installed, this target should run that test.
4253 Do not strip executables when installing them. Devil-may-care
4254 users can use the `install-strip' target to do that.
4256 If possible, write the `install' target rule so that it does not
4257 modify anything in the directory where the program was built,
4258 provided `make all' has just been done. This is convenient for
4259 building the program under one user name and installing it under
4262 The commands should create all the directories in which files are
4263 to be installed, if they don't already exist. This includes the
4264 directories specified as the values of the variables `prefix' and
4265 `exec_prefix', as well as all subdirectories that are needed. One
4266 way to do this is by means of an `installdirs' target as described
4269 Use `-' before any command for installing a man page, so that
4270 `make' will ignore any errors. This is in case there are systems
4271 that don't have the Unix man page documentation system installed.
4273 The way to install Info files is to copy them into `$(infodir)'
4274 with `$(INSTALL_DATA)' (*note Command Variables::), and then run
4275 the `install-info' program if it is present. `install-info' is a
4276 program that edits the Info `dir' file to add or update the menu
4277 entry for the given Info file; it is part of the Texinfo package.
4278 Here is a sample rule to install an Info file:
4280 $(DESTDIR)$(infodir)/foo.info: foo.info
4282 # There may be a newer info file in . than in srcdir.
4283 -if test -f foo.info; then d=.; \
4284 else d=$(srcdir); fi; \
4285 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
4286 # Run install-info only if it exists.
4287 # Use `if' instead of just prepending `-' to the
4288 # line so we notice real errors from install-info.
4289 # We use `$(SHELL) -c' because some shells do not
4290 # fail gracefully when there is an unknown command.
4291 if $(SHELL) -c 'install-info --version' \
4292 >/dev/null 2>&1; then \
4293 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
4294 $(DESTDIR)$(infodir)/foo.info; \
4297 When writing the `install' target, you must classify all the
4298 commands into three categories: normal ones, "pre-installation"
4299 commands and "post-installation" commands. *Note Install Command
4306 These targets install documentation in formats other than Info;
4307 they're intended to be called explicitly by the person installing
4308 the package, if that format is desired. GNU prefers Info files,
4309 so these must be installed by the `install' target.
4311 When you have many documentation files to install, we recommend
4312 that you avoid collisions and clutter by arranging for these
4313 targets to install in subdirectories of the appropriate
4314 installation directory, such as `htmldir'. As one example, if
4315 your package has multiple manuals, and you wish to install HTML
4316 documentation with many files (such as the "split" mode output by
4317 `makeinfo --html'), you'll certainly want to use subdirectories,
4318 or two nodes with the same name in different manuals will
4319 overwrite each other.
4321 Please make these `install-FORMAT' targets invoke the commands for
4322 the FORMAT target, for example, by making FORMAT a dependency.
4325 Delete all the installed files--the copies that the `install' and
4326 `install-*' targets create.
4328 This rule should not modify the directories where compilation is
4329 done, only the directories where files are installed.
4331 The uninstallation commands are divided into three categories,
4332 just like the installation commands. *Note Install Command
4336 Like `install', but strip the executable files while installing
4337 them. In simple cases, this target can use the `install' target in
4341 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
4344 But if the package installs scripts as well as real executables,
4345 the `install-strip' target can't just refer to the `install'
4346 target; it has to strip the executables but not the scripts.
4348 `install-strip' should not strip the executables in the build
4349 directory which are being copied for installation. It should only
4350 strip the copies that are installed.
4352 Normally we do not recommend stripping an executable unless you
4353 are sure the program has no bugs. However, it can be reasonable
4354 to install a stripped executable for actual execution while saving
4355 the unstripped executable elsewhere in case there is a bug.
4358 Delete all files in the current directory that are normally
4359 created by building the program. Also delete files in other
4360 directories if they are created by this makefile. However, don't
4361 delete the files that record the configuration. Also preserve
4362 files that could be made by building, but normally aren't because
4363 the distribution comes with them. There is no need to delete
4364 parent directories that were created with `mkdir -p', since they
4365 could have existed anyway.
4367 Delete `.dvi' files here if they are not part of the distribution.
4370 Delete all files in the current directory (or created by this
4371 makefile) that are created by configuring or building the program.
4372 If you have unpacked the source and built the program without
4373 creating any other files, `make distclean' should leave only the
4374 files that were in the distribution. However, there is no need to
4375 delete parent directories that were created with `mkdir -p', since
4376 they could have existed anyway.
4379 Like `clean', but may refrain from deleting a few files that people
4380 normally don't want to recompile. For example, the `mostlyclean'
4381 target for GCC does not delete `libgcc.a', because recompiling it
4382 is rarely necessary and takes a lot of time.
4385 Delete almost everything that can be reconstructed with this
4386 Makefile. This typically includes everything deleted by
4387 `distclean', plus more: C source files produced by Bison, tags
4388 tables, Info files, and so on.
4390 The reason we say "almost everything" is that running the command
4391 `make maintainer-clean' should not delete `configure' even if
4392 `configure' can be remade using a rule in the Makefile. More
4393 generally, `make maintainer-clean' should not delete anything that
4394 needs to exist in order to run `configure' and then begin to build
4395 the program. Also, there is no need to delete parent directories
4396 that were created with `mkdir -p', since they could have existed
4397 anyway. These are the only exceptions; `maintainer-clean' should
4398 delete everything else that can be rebuilt.
4400 The `maintainer-clean' target is intended to be used by a
4401 maintainer of the package, not by ordinary users. You may need
4402 special tools to reconstruct some of the files that `make
4403 maintainer-clean' deletes. Since these files are normally
4404 included in the distribution, we don't take care to make them easy
4405 to reconstruct. If you find you need to unpack the full
4406 distribution again, don't blame us.
4408 To help make users aware of this, the commands for the special
4409 `maintainer-clean' target should start with these two:
4411 @echo 'This command is intended for maintainers to use; it'
4412 @echo 'deletes files that may need special tools to rebuild.'
4415 Update a tags table for this program.
4418 Generate any Info files needed. The best way to write the rules
4423 foo.info: foo.texi chap1.texi chap2.texi
4424 $(MAKEINFO) $(srcdir)/foo.texi
4426 You must define the variable `MAKEINFO' in the Makefile. It should
4427 run the `makeinfo' program, which is part of the Texinfo
4430 Normally a GNU distribution comes with Info files, and that means
4431 the Info files are present in the source directory. Therefore,
4432 the Make rule for an info file should update it in the source
4433 directory. When users build the package, ordinarily Make will not
4434 update the Info files because they will already be up to date.
4440 Generate documentation files in the given format. These targets
4441 should always exist, but any or all can be a no-op if the given
4442 output format cannot be generated. These targets should not be
4443 dependencies of the `all' target; the user must manually invoke
4446 Here's an example rule for generating DVI files from Texinfo:
4450 foo.dvi: foo.texi chap1.texi chap2.texi
4451 $(TEXI2DVI) $(srcdir)/foo.texi
4453 You must define the variable `TEXI2DVI' in the Makefile. It should
4454 run the program `texi2dvi', which is part of the Texinfo
4455 distribution.(1) Alternatively, write just the dependencies, and
4456 allow GNU `make' to provide the command.
4458 Here's another example, this one for generating HTML from Texinfo:
4462 foo.html: foo.texi chap1.texi chap2.texi
4463 $(TEXI2HTML) $(srcdir)/foo.texi
4465 Again, you would define the variable `TEXI2HTML' in the Makefile;
4466 for example, it might run `makeinfo --no-split --html' (`makeinfo'
4467 is part of the Texinfo distribution).
4470 Create a distribution tar file for this program. The tar file
4471 should be set up so that the file names in the tar file start with
4472 a subdirectory name which is the name of the package it is a
4473 distribution for. This name can include the version number.
4475 For example, the distribution tar file of GCC version 1.40 unpacks
4476 into a subdirectory named `gcc-1.40'.
4478 The easiest way to do this is to create a subdirectory
4479 appropriately named, use `ln' or `cp' to install the proper files
4480 in it, and then `tar' that subdirectory.
4482 Compress the tar file with `gzip'. For example, the actual
4483 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
4485 The `dist' target should explicitly depend on all non-source files
4486 that are in the distribution, to make sure they are up to date in
4487 the distribution. *Note Making Releases: Releases.
4490 Perform self-tests (if any). The user must build the program
4491 before running the tests, but need not install the program; you
4492 should write the self-tests so that they work when the program is
4493 built but not installed.
4495 The following targets are suggested as conventional names, for
4496 programs in which they are useful.
4499 Perform installation tests (if any). The user must build and
4500 install the program before running the tests. You should not
4501 assume that `$(bindir)' is in the search path.
4504 It's useful to add a target named `installdirs' to create the
4505 directories where files are installed, and their parent
4506 directories. There is a script called `mkinstalldirs' which is
4507 convenient for this; you can find it in the Texinfo package. You
4508 can use a rule like this:
4510 # Make sure all installation directories (e.g. $(bindir))
4511 # actually exist by making them if necessary.
4512 installdirs: mkinstalldirs
4513 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
4514 $(libdir) $(infodir) \
4517 or, if you wish to support `DESTDIR',
4519 # Make sure all installation directories (e.g. $(bindir))
4520 # actually exist by making them if necessary.
4521 installdirs: mkinstalldirs
4522 $(srcdir)/mkinstalldirs \
4523 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
4524 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
4527 This rule should not modify the directories where compilation is
4528 done. It should do nothing but create installation directories.
4530 ---------- Footnotes ----------
4532 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
4533 not distributed with Texinfo.
4536 File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
4538 7.2.7 Install Command Categories
4539 --------------------------------
4541 When writing the `install' target, you must classify all the commands
4542 into three categories: normal ones, "pre-installation" commands and
4543 "post-installation" commands.
4545 Normal commands move files into their proper places, and set their
4546 modes. They may not alter any files except the ones that come entirely
4547 from the package they belong to.
4549 Pre-installation and post-installation commands may alter other
4550 files; in particular, they can edit global configuration files or data
4553 Pre-installation commands are typically executed before the normal
4554 commands, and post-installation commands are typically run after the
4557 The most common use for a post-installation command is to run
4558 `install-info'. This cannot be done with a normal command, since it
4559 alters a file (the Info directory) which does not come entirely and
4560 solely from the package being installed. It is a post-installation
4561 command because it needs to be done after the normal command which
4562 installs the package's Info files.
4564 Most programs don't need any pre-installation commands, but we have
4565 the feature just in case it is needed.
4567 To classify the commands in the `install' rule into these three
4568 categories, insert "category lines" among them. A category line
4569 specifies the category for the commands that follow.
4571 A category line consists of a tab and a reference to a special Make
4572 variable, plus an optional comment at the end. There are three
4573 variables you can use, one for each category; the variable name
4574 specifies the category. Category lines are no-ops in ordinary execution
4575 because these three Make variables are normally undefined (and you
4576 _should not_ define them in the makefile).
4578 Here are the three possible category lines, each with a comment that
4579 explains what it means:
4581 $(PRE_INSTALL) # Pre-install commands follow.
4582 $(POST_INSTALL) # Post-install commands follow.
4583 $(NORMAL_INSTALL) # Normal commands follow.
4585 If you don't use a category line at the beginning of the `install'
4586 rule, all the commands are classified as normal until the first category
4587 line. If you don't use any category lines, all the commands are
4588 classified as normal.
4590 These are the category lines for `uninstall':
4592 $(PRE_UNINSTALL) # Pre-uninstall commands follow.
4593 $(POST_UNINSTALL) # Post-uninstall commands follow.
4594 $(NORMAL_UNINSTALL) # Normal commands follow.
4596 Typically, a pre-uninstall command would be used for deleting entries
4597 from the Info directory.
4599 If the `install' or `uninstall' target has any dependencies which
4600 act as subroutines of installation, then you should start _each_
4601 dependency's commands with a category line, and start the main target's
4602 commands with a category line also. This way, you can ensure that each
4603 command is placed in the right category regardless of which of the
4604 dependencies actually run.
4606 Pre-installation and post-installation commands should not run any
4607 programs except for these:
4609 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
4610 egrep expand expr false fgrep find getopt grep gunzip gzip
4611 hostname install install-info kill ldconfig ln ls md5sum
4612 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
4613 test touch true uname xargs yes
4615 The reason for distinguishing the commands in this way is for the
4616 sake of making binary packages. Typically a binary package contains
4617 all the executables and other files that need to be installed, and has
4618 its own method of installing them--so it does not need to run the normal
4619 installation commands. But installing the binary package does need to
4620 execute the pre-installation and post-installation commands.
4622 Programs to build binary packages work by extracting the
4623 pre-installation and post-installation commands. Here is one way of
4624 extracting the pre-installation commands (the `-s' option to `make' is
4625 needed to silence messages about entering subdirectories):
4627 make -s -n install -o all \
4628 PRE_INSTALL=pre-install \
4629 POST_INSTALL=post-install \
4630 NORMAL_INSTALL=normal-install \
4631 | gawk -f pre-install.awk
4633 where the file `pre-install.awk' could contain this:
4635 $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
4637 $0 ~ /^pre-install[ \t]*$/ {on = 1}
4640 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
4645 You should identify each release with a pair of version numbers, a
4646 major version and a minor. We have no objection to using more than two
4647 numbers, but it is very unlikely that you really need them.
4649 Package the distribution of `Foo version 69.96' up in a gzipped tar
4650 file with the name `foo-69.96.tar.gz'. It should unpack into a
4651 subdirectory named `foo-69.96'.
4653 Building and installing the program should never modify any of the
4654 files contained in the distribution. This means that all the files
4655 that form part of the program in any way must be classified into "source
4656 files" and "non-source files". Source files are written by humans and
4657 never changed automatically; non-source files are produced from source
4658 files by programs under the control of the Makefile.
4660 The distribution should contain a file named `README' which gives
4661 the name of the package, and a general description of what it does. It
4662 is also good to explain the purpose of each of the first-level
4663 subdirectories in the package, if there are any. The `README' file
4664 should either state the version number of the package, or refer to where
4665 in the package it can be found.
4667 The `README' file should refer to the file `INSTALL', which should
4668 contain an explanation of the installation procedure.
4670 The `README' file should also refer to the file which contains the
4671 copying conditions. The GNU GPL, if used, should be in a file called
4672 `COPYING'. If the GNU LGPL is used, it should be in a file called
4675 Naturally, all the source files must be in the distribution. It is
4676 okay to include non-source files in the distribution, provided they are
4677 up-to-date and machine-independent, so that building the distribution
4678 normally will never modify them. We commonly include non-source files
4679 produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
4680 unnecessary dependencies between our distributions, so that users can
4681 install whichever packages they want to install.
4683 Non-source files that might actually be modified by building and
4684 installing the program should *never* be included in the distribution.
4685 So if you do distribute non-source files, always make sure they are up
4686 to date when you make a new distribution.
4688 Make sure that the directory into which the distribution unpacks (as
4689 well as any subdirectories) are all world-writable (octal mode 777).
4690 This is so that old versions of `tar' which preserve the ownership and
4691 permissions of the files from the tar archive will be able to extract
4692 all the files even if the user is unprivileged.
4694 Make sure that all the files in the distribution are world-readable.
4696 Don't include any symbolic links in the distribution itself. If the
4697 tar file contains symbolic links, then people cannot even unpack it on
4698 systems that don't support symbolic links. Also, don't use multiple
4699 names for one file in different directories, because certain file
4700 systems cannot handle this and that prevents unpacking the distribution.
4702 Try to make sure that all the file names will be unique on MS-DOS. A
4703 name on MS-DOS consists of up to 8 characters, optionally followed by a
4704 period and up to three characters. MS-DOS will truncate extra
4705 characters both before and after the period. Thus, `foobarhacker.c'
4706 and `foobarhacker.o' are not ambiguous; they are truncated to
4707 `foobarha.c' and `foobarha.o', which are distinct.
4709 Include in your distribution a copy of the `texinfo.tex' you used to
4710 test print any `*.texinfo' or `*.texi' files.
4712 Likewise, if your program uses small GNU software packages like
4713 regex, getopt, obstack, or termcap, include them in the distribution
4714 file. Leaving them out would make the distribution file a little
4715 smaller at the expense of possible inconvenience to a user who doesn't
4716 know what other files to get.
4719 File: standards.info, Node: References, Next: Copying This Manual, Prev: Managing Releases, Up: Top
4721 8 References to Non-Free Software and Documentation
4722 ***************************************************
4724 A GNU program should not recommend use of any non-free program. We
4725 can't stop some people from writing proprietary programs, or stop other
4726 people from using them, but we can and should refuse to advertise them
4727 to new potential customers. Proprietary software is a social and
4728 ethical problem, and the point of GNU is to solve that problem.
4730 The GNU definition of free software is found on the GNU web site at
4731 `http://www.gnu.org/philosophy/free-sw.html', and the definition of
4732 free documentation is found at
4733 `http://www.gnu.org/philosophy/free-doc.html'. A list of important
4734 licenses and whether they qualify as free is in
4735 `http://www.gnu.org/licenses/license-list.html'. The terms "free" and
4736 "non-free", used in this document, refer to that definition. If it is
4737 not clear whether a license qualifies as free under this definition,
4738 please ask the GNU Project by writing to <licensing@gnu.org>. We will
4739 answer, and if the license is an important one, we will add it to the
4742 When a non-free program or system is well known, you can mention it
4743 in passing--that is harmless, since users who might want to use it
4744 probably already know about it. For instance, it is fine to explain
4745 how to build your package on top of some widely used non-free operating
4746 system, or how to use it together with some widely used non-free
4749 However, you should give only the necessary information to help those
4750 who already use the non-free program to use your program with it--don't
4751 give, or refer to, any further information about the proprietary
4752 program, and don't imply that the proprietary program enhances your
4753 program, or that its existence is in any way a good thing. The goal
4754 should be that people already using the proprietary program will get
4755 the advice they need about how to use your free program with it, while
4756 people who don't already use the proprietary program will not see
4757 anything to lead them to take an interest in it.
4759 If a non-free program or system is obscure in your program's domain,
4760 your program should not mention or support it at all, since doing so
4761 would tend to popularize the non-free program more than it popularizes
4762 your program. (You cannot hope to find many additional users among the
4763 users of Foobar if the users of Foobar are few.)
4765 Sometimes a program is free software in itself but depends on a
4766 non-free platform in order to run. For instance, many Java programs
4767 depend on Sun's Java implementation, and won't run on the GNU Java
4768 Compiler (which does not yet have all the features) or won't run with
4769 the GNU Java libraries. To recommend that program is inherently to
4770 recommend the non-free platform as well; if you should not do the
4771 latter, then don't do the former.
4773 A GNU package should not refer the user to any non-free documentation
4774 for free software. Free documentation that can be included in free
4775 operating systems is essential for completing the GNU system, or any
4776 free operating system, so it is a major focus of the GNU Project; to
4777 recommend use of documentation that we are not allowed to use in GNU
4778 would weaken the impetus for the community to produce documentation
4779 that we can include. So GNU packages should never recommend non-free
4782 By contrast, it is ok to refer to journal articles and textbooks in
4783 the comments of a program for explanation of how it functions, even
4784 though they be non-free. This is because we don't include such things
4785 in the GNU system even if we are allowed to-they are outside the scope
4786 of an operating system project.
4788 Referring to a web site that describes or recommends a non-free
4789 program is in effect promoting that software, so please do not make
4790 links (or mention by name) web sites that contain such material. This
4791 policy is relevant particularly for the web pages for a GNU package.
4793 Following links from nearly any web site can lead to non-free
4794 software; this is an inescapable aspect of the nature of the web, and
4795 in itself is no objection to linking to a site. As long as the site
4796 does not itself recommend a non-free program, there is no need be
4797 concerned about the sites it links to for other reasons.
4799 Thus, for example, you should not make a link to AT&T's web site,
4800 because that recommends AT&T's non-free software packages; you should
4801 not make a link to a site that links to AT&T's site saying it is a
4802 place to get a non-free program; but if a site you want to link to
4803 refers to AT&T's web site in some other context (such as long-distance
4804 telephone service), that is not a problem.
4807 File: standards.info, Node: Copying This Manual, Next: Index, Prev: References, Up: Top
4809 Appendix A Copying This Manual
4810 ******************************
4814 * GNU Free Documentation License:: License for copying this manual
4817 File: standards.info, Node: GNU Free Documentation License, Up: Copying This Manual
4819 A.1 GNU Free Documentation License
4820 ==================================
4822 Version 1.2, November 2002
4824 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
4825 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
4827 Everyone is permitted to copy and distribute verbatim copies
4828 of this license document, but changing it is not allowed.
4832 The purpose of this License is to make a manual, textbook, or other
4833 functional and useful document "free" in the sense of freedom: to
4834 assure everyone the effective freedom to copy and redistribute it,
4835 with or without modifying it, either commercially or
4836 noncommercially. Secondarily, this License preserves for the
4837 author and publisher a way to get credit for their work, while not
4838 being considered responsible for modifications made by others.
4840 This License is a kind of "copyleft", which means that derivative
4841 works of the document must themselves be free in the same sense.
4842 It complements the GNU General Public License, which is a copyleft
4843 license designed for free software.
4845 We have designed this License in order to use it for manuals for
4846 free software, because free software needs free documentation: a
4847 free program should come with manuals providing the same freedoms
4848 that the software does. But this License is not limited to
4849 software manuals; it can be used for any textual work, regardless
4850 of subject matter or whether it is published as a printed book.
4851 We recommend this License principally for works whose purpose is
4852 instruction or reference.
4854 1. APPLICABILITY AND DEFINITIONS
4856 This License applies to any manual or other work, in any medium,
4857 that contains a notice placed by the copyright holder saying it
4858 can be distributed under the terms of this License. Such a notice
4859 grants a world-wide, royalty-free license, unlimited in duration,
4860 to use that work under the conditions stated herein. The
4861 "Document", below, refers to any such manual or work. Any member
4862 of the public is a licensee, and is addressed as "you". You
4863 accept the license if you copy, modify or distribute the work in a
4864 way requiring permission under copyright law.
4866 A "Modified Version" of the Document means any work containing the
4867 Document or a portion of it, either copied verbatim, or with
4868 modifications and/or translated into another language.
4870 A "Secondary Section" is a named appendix or a front-matter section
4871 of the Document that deals exclusively with the relationship of the
4872 publishers or authors of the Document to the Document's overall
4873 subject (or to related matters) and contains nothing that could
4874 fall directly within that overall subject. (Thus, if the Document
4875 is in part a textbook of mathematics, a Secondary Section may not
4876 explain any mathematics.) The relationship could be a matter of
4877 historical connection with the subject or with related matters, or
4878 of legal, commercial, philosophical, ethical or political position
4881 The "Invariant Sections" are certain Secondary Sections whose
4882 titles are designated, as being those of Invariant Sections, in
4883 the notice that says that the Document is released under this
4884 License. If a section does not fit the above definition of
4885 Secondary then it is not allowed to be designated as Invariant.
4886 The Document may contain zero Invariant Sections. If the Document
4887 does not identify any Invariant Sections then there are none.
4889 The "Cover Texts" are certain short passages of text that are
4890 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4891 that says that the Document is released under this License. A
4892 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
4893 be at most 25 words.
4895 A "Transparent" copy of the Document means a machine-readable copy,
4896 represented in a format whose specification is available to the
4897 general public, that is suitable for revising the document
4898 straightforwardly with generic text editors or (for images
4899 composed of pixels) generic paint programs or (for drawings) some
4900 widely available drawing editor, and that is suitable for input to
4901 text formatters or for automatic translation to a variety of
4902 formats suitable for input to text formatters. A copy made in an
4903 otherwise Transparent file format whose markup, or absence of
4904 markup, has been arranged to thwart or discourage subsequent
4905 modification by readers is not Transparent. An image format is
4906 not Transparent if used for any substantial amount of text. A
4907 copy that is not "Transparent" is called "Opaque".
4909 Examples of suitable formats for Transparent copies include plain
4910 ASCII without markup, Texinfo input format, LaTeX input format,
4911 SGML or XML using a publicly available DTD, and
4912 standard-conforming simple HTML, PostScript or PDF designed for
4913 human modification. Examples of transparent image formats include
4914 PNG, XCF and JPG. Opaque formats include proprietary formats that
4915 can be read and edited only by proprietary word processors, SGML or
4916 XML for which the DTD and/or processing tools are not generally
4917 available, and the machine-generated HTML, PostScript or PDF
4918 produced by some word processors for output purposes only.
4920 The "Title Page" means, for a printed book, the title page itself,
4921 plus such following pages as are needed to hold, legibly, the
4922 material this License requires to appear in the title page. For
4923 works in formats which do not have any title page as such, "Title
4924 Page" means the text near the most prominent appearance of the
4925 work's title, preceding the beginning of the body of the text.
4927 A section "Entitled XYZ" means a named subunit of the Document
4928 whose title either is precisely XYZ or contains XYZ in parentheses
4929 following text that translates XYZ in another language. (Here XYZ
4930 stands for a specific section name mentioned below, such as
4931 "Acknowledgements", "Dedications", "Endorsements", or "History".)
4932 To "Preserve the Title" of such a section when you modify the
4933 Document means that it remains a section "Entitled XYZ" according
4936 The Document may include Warranty Disclaimers next to the notice
4937 which states that this License applies to the Document. These
4938 Warranty Disclaimers are considered to be included by reference in
4939 this License, but only as regards disclaiming warranties: any other
4940 implication that these Warranty Disclaimers may have is void and
4941 has no effect on the meaning of this License.
4945 You may copy and distribute the Document in any medium, either
4946 commercially or noncommercially, provided that this License, the
4947 copyright notices, and the license notice saying this License
4948 applies to the Document are reproduced in all copies, and that you
4949 add no other conditions whatsoever to those of this License. You
4950 may not use technical measures to obstruct or control the reading
4951 or further copying of the copies you make or distribute. However,
4952 you may accept compensation in exchange for copies. If you
4953 distribute a large enough number of copies you must also follow
4954 the conditions in section 3.
4956 You may also lend copies, under the same conditions stated above,
4957 and you may publicly display copies.
4959 3. COPYING IN QUANTITY
4961 If you publish printed copies (or copies in media that commonly
4962 have printed covers) of the Document, numbering more than 100, and
4963 the Document's license notice requires Cover Texts, you must
4964 enclose the copies in covers that carry, clearly and legibly, all
4965 these Cover Texts: Front-Cover Texts on the front cover, and
4966 Back-Cover Texts on the back cover. Both covers must also clearly
4967 and legibly identify you as the publisher of these copies. The
4968 front cover must present the full title with all words of the
4969 title equally prominent and visible. You may add other material
4970 on the covers in addition. Copying with changes limited to the
4971 covers, as long as they preserve the title of the Document and
4972 satisfy these conditions, can be treated as verbatim copying in
4975 If the required texts for either cover are too voluminous to fit
4976 legibly, you should put the first ones listed (as many as fit
4977 reasonably) on the actual cover, and continue the rest onto
4980 If you publish or distribute Opaque copies of the Document
4981 numbering more than 100, you must either include a
4982 machine-readable Transparent copy along with each Opaque copy, or
4983 state in or with each Opaque copy a computer-network location from
4984 which the general network-using public has access to download
4985 using public-standard network protocols a complete Transparent
4986 copy of the Document, free of added material. If you use the
4987 latter option, you must take reasonably prudent steps, when you
4988 begin distribution of Opaque copies in quantity, to ensure that
4989 this Transparent copy will remain thus accessible at the stated
4990 location until at least one year after the last time you
4991 distribute an Opaque copy (directly or through your agents or
4992 retailers) of that edition to the public.
4994 It is requested, but not required, that you contact the authors of
4995 the Document well before redistributing any large number of
4996 copies, to give them a chance to provide you with an updated
4997 version of the Document.
5001 You may copy and distribute a Modified Version of the Document
5002 under the conditions of sections 2 and 3 above, provided that you
5003 release the Modified Version under precisely this License, with
5004 the Modified Version filling the role of the Document, thus
5005 licensing distribution and modification of the Modified Version to
5006 whoever possesses a copy of it. In addition, you must do these
5007 things in the Modified Version:
5009 A. Use in the Title Page (and on the covers, if any) a title
5010 distinct from that of the Document, and from those of
5011 previous versions (which should, if there were any, be listed
5012 in the History section of the Document). You may use the
5013 same title as a previous version if the original publisher of
5014 that version gives permission.
5016 B. List on the Title Page, as authors, one or more persons or
5017 entities responsible for authorship of the modifications in
5018 the Modified Version, together with at least five of the
5019 principal authors of the Document (all of its principal
5020 authors, if it has fewer than five), unless they release you
5021 from this requirement.
5023 C. State on the Title page the name of the publisher of the
5024 Modified Version, as the publisher.
5026 D. Preserve all the copyright notices of the Document.
5028 E. Add an appropriate copyright notice for your modifications
5029 adjacent to the other copyright notices.
5031 F. Include, immediately after the copyright notices, a license
5032 notice giving the public permission to use the Modified
5033 Version under the terms of this License, in the form shown in
5036 G. Preserve in that license notice the full lists of Invariant
5037 Sections and required Cover Texts given in the Document's
5040 H. Include an unaltered copy of this License.
5042 I. Preserve the section Entitled "History", Preserve its Title,
5043 and add to it an item stating at least the title, year, new
5044 authors, and publisher of the Modified Version as given on
5045 the Title Page. If there is no section Entitled "History" in
5046 the Document, create one stating the title, year, authors,
5047 and publisher of the Document as given on its Title Page,
5048 then add an item describing the Modified Version as stated in
5049 the previous sentence.
5051 J. Preserve the network location, if any, given in the Document
5052 for public access to a Transparent copy of the Document, and
5053 likewise the network locations given in the Document for
5054 previous versions it was based on. These may be placed in
5055 the "History" section. You may omit a network location for a
5056 work that was published at least four years before the
5057 Document itself, or if the original publisher of the version
5058 it refers to gives permission.
5060 K. For any section Entitled "Acknowledgements" or "Dedications",
5061 Preserve the Title of the section, and preserve in the
5062 section all the substance and tone of each of the contributor
5063 acknowledgements and/or dedications given therein.
5065 L. Preserve all the Invariant Sections of the Document,
5066 unaltered in their text and in their titles. Section numbers
5067 or the equivalent are not considered part of the section
5070 M. Delete any section Entitled "Endorsements". Such a section
5071 may not be included in the Modified Version.
5073 N. Do not retitle any existing section to be Entitled
5074 "Endorsements" or to conflict in title with any Invariant
5077 O. Preserve any Warranty Disclaimers.
5079 If the Modified Version includes new front-matter sections or
5080 appendices that qualify as Secondary Sections and contain no
5081 material copied from the Document, you may at your option
5082 designate some or all of these sections as invariant. To do this,
5083 add their titles to the list of Invariant Sections in the Modified
5084 Version's license notice. These titles must be distinct from any
5085 other section titles.
5087 You may add a section Entitled "Endorsements", provided it contains
5088 nothing but endorsements of your Modified Version by various
5089 parties--for example, statements of peer review or that the text
5090 has been approved by an organization as the authoritative
5091 definition of a standard.
5093 You may add a passage of up to five words as a Front-Cover Text,
5094 and a passage of up to 25 words as a Back-Cover Text, to the end
5095 of the list of Cover Texts in the Modified Version. Only one
5096 passage of Front-Cover Text and one of Back-Cover Text may be
5097 added by (or through arrangements made by) any one entity. If the
5098 Document already includes a cover text for the same cover,
5099 previously added by you or by arrangement made by the same entity
5100 you are acting on behalf of, you may not add another; but you may
5101 replace the old one, on explicit permission from the previous
5102 publisher that added the old one.
5104 The author(s) and publisher(s) of the Document do not by this
5105 License give permission to use their names for publicity for or to
5106 assert or imply endorsement of any Modified Version.
5108 5. COMBINING DOCUMENTS
5110 You may combine the Document with other documents released under
5111 this License, under the terms defined in section 4 above for
5112 modified versions, provided that you include in the combination
5113 all of the Invariant Sections of all of the original documents,
5114 unmodified, and list them all as Invariant Sections of your
5115 combined work in its license notice, and that you preserve all
5116 their Warranty Disclaimers.
5118 The combined work need only contain one copy of this License, and
5119 multiple identical Invariant Sections may be replaced with a single
5120 copy. If there are multiple Invariant Sections with the same name
5121 but different contents, make the title of each such section unique
5122 by adding at the end of it, in parentheses, the name of the
5123 original author or publisher of that section if known, or else a
5124 unique number. Make the same adjustment to the section titles in
5125 the list of Invariant Sections in the license notice of the
5128 In the combination, you must combine any sections Entitled
5129 "History" in the various original documents, forming one section
5130 Entitled "History"; likewise combine any sections Entitled
5131 "Acknowledgements", and any sections Entitled "Dedications". You
5132 must delete all sections Entitled "Endorsements."
5134 6. COLLECTIONS OF DOCUMENTS
5136 You may make a collection consisting of the Document and other
5137 documents released under this License, and replace the individual
5138 copies of this License in the various documents with a single copy
5139 that is included in the collection, provided that you follow the
5140 rules of this License for verbatim copying of each of the
5141 documents in all other respects.
5143 You may extract a single document from such a collection, and
5144 distribute it individually under this License, provided you insert
5145 a copy of this License into the extracted document, and follow
5146 this License in all other respects regarding verbatim copying of
5149 7. AGGREGATION WITH INDEPENDENT WORKS
5151 A compilation of the Document or its derivatives with other
5152 separate and independent documents or works, in or on a volume of
5153 a storage or distribution medium, is called an "aggregate" if the
5154 copyright resulting from the compilation is not used to limit the
5155 legal rights of the compilation's users beyond what the individual
5156 works permit. When the Document is included in an aggregate, this
5157 License does not apply to the other works in the aggregate which
5158 are not themselves derivative works of the Document.
5160 If the Cover Text requirement of section 3 is applicable to these
5161 copies of the Document, then if the Document is less than one half
5162 of the entire aggregate, the Document's Cover Texts may be placed
5163 on covers that bracket the Document within the aggregate, or the
5164 electronic equivalent of covers if the Document is in electronic
5165 form. Otherwise they must appear on printed covers that bracket
5166 the whole aggregate.
5170 Translation is considered a kind of modification, so you may
5171 distribute translations of the Document under the terms of section
5172 4. Replacing Invariant Sections with translations requires special
5173 permission from their copyright holders, but you may include
5174 translations of some or all Invariant Sections in addition to the
5175 original versions of these Invariant Sections. You may include a
5176 translation of this License, and all the license notices in the
5177 Document, and any Warranty Disclaimers, provided that you also
5178 include the original English version of this License and the
5179 original versions of those notices and disclaimers. In case of a
5180 disagreement between the translation and the original version of
5181 this License or a notice or disclaimer, the original version will
5184 If a section in the Document is Entitled "Acknowledgements",
5185 "Dedications", or "History", the requirement (section 4) to
5186 Preserve its Title (section 1) will typically require changing the
5191 You may not copy, modify, sublicense, or distribute the Document
5192 except as expressly provided for under this License. Any other
5193 attempt to copy, modify, sublicense or distribute the Document is
5194 void, and will automatically terminate your rights under this
5195 License. However, parties who have received copies, or rights,
5196 from you under this License will not have their licenses
5197 terminated so long as such parties remain in full compliance.
5199 10. FUTURE REVISIONS OF THIS LICENSE
5201 The Free Software Foundation may publish new, revised versions of
5202 the GNU Free Documentation License from time to time. Such new
5203 versions will be similar in spirit to the present version, but may
5204 differ in detail to address new problems or concerns. See
5205 `http://www.gnu.org/copyleft/'.
5207 Each version of the License is given a distinguishing version
5208 number. If the Document specifies that a particular numbered
5209 version of this License "or any later version" applies to it, you
5210 have the option of following the terms and conditions either of
5211 that specified version or of any later version that has been
5212 published (not as a draft) by the Free Software Foundation. If
5213 the Document does not specify a version number of this License,
5214 you may choose any version ever published (not as a draft) by the
5215 Free Software Foundation.
5217 ADDENDUM: How to use this License for your documents
5218 ====================================================
5220 To use this License in a document you have written, include a copy of
5221 the License in the document and put the following copyright and license
5222 notices just after the title page:
5224 Copyright (C) YEAR YOUR NAME.
5225 Permission is granted to copy, distribute and/or modify this document
5226 under the terms of the GNU Free Documentation License, Version 1.2
5227 or any later version published by the Free Software Foundation;
5228 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5229 Texts. A copy of the license is included in the section entitled ``GNU
5230 Free Documentation License''.
5232 If you have Invariant Sections, Front-Cover Texts and Back-Cover
5233 Texts, replace the "with...Texts." line with this:
5235 with the Invariant Sections being LIST THEIR TITLES, with
5236 the Front-Cover Texts being LIST, and with the Back-Cover Texts
5239 If you have Invariant Sections without Cover Texts, or some other
5240 combination of the three, merge those two alternatives to suit the
5243 If your document contains nontrivial examples of program code, we
5244 recommend releasing these examples in parallel under your choice of
5245 free software license, such as the GNU General Public License, to
5246 permit their use in free software.
5249 File: standards.info, Node: Index, Prev: Copying This Manual, Up: Top
5257 * #endif, commenting: Comments. (line 60)
5258 * --help option: Command-Line Interfaces.
5260 * --version option: Command-Line Interfaces.
5262 * -Wall compiler option: Syntactic Conventions.
5264 * accepting contributions: Contributions. (line 6)
5265 * address for bug reports: Command-Line Interfaces.
5267 * ANSI C standard: Standard C. (line 6)
5268 * arbitrary limits on data: Semantics. (line 6)
5269 * ASCII characters: Character Set. (line 6)
5270 * autoconf: System Portability. (line 23)
5271 * avoiding proprietary code: Reading Non-Free Code.
5273 * behavior, dependent on program's name: User Interfaces. (line 6)
5274 * binary packages: Install Command Categories.
5276 * bindir: Directory Variables. (line 54)
5277 * braces, in C source: Formatting. (line 6)
5278 * bug reports: Command-Line Interfaces.
5280 * canonical name of a program: Command-Line Interfaces.
5282 * casting pointers to integers: CPU Portability. (line 90)
5283 * CGI programs, standard options for: Command-Line Interfaces.
5285 * change logs: Change Logs. (line 6)
5286 * change logs, conditional changes: Conditional Changes. (line 6)
5287 * change logs, style: Style of Change Logs.
5289 * character set: Character Set. (line 6)
5290 * command-line arguments, decoding: Semantics. (line 46)
5291 * command-line interface: Command-Line Interfaces.
5293 * commenting: Comments. (line 6)
5294 * compatibility with C and POSIX standards: Compatibility. (line 6)
5295 * compiler warnings: Syntactic Conventions.
5297 * conditional changes, and change logs: Conditional Changes. (line 6)
5298 * conditionals, comments for: Comments. (line 60)
5299 * configure: Configuration. (line 6)
5300 * control-L: Formatting. (line 114)
5301 * conventions for makefiles: Makefile Conventions.
5303 * corba: Graphical Interfaces.
5305 * credits for manuals: Manual Credits. (line 6)
5306 * data types, and portability: CPU Portability. (line 6)
5307 * declaration for system functions: System Functions. (line 21)
5308 * DESTDIR: DESTDIR. (line 6)
5309 * documentation: Documentation. (line 6)
5310 * doschk: Names. (line 38)
5311 * downloading this manual: Preface. (line 17)
5312 * encodings: Character Set. (line 6)
5313 * error messages: Semantics. (line 19)
5314 * error messages, formatting: Errors. (line 6)
5315 * exec_prefix: Directory Variables. (line 36)
5316 * expressions, splitting: Formatting. (line 77)
5317 * FDL, GNU Free Documentation License: GNU Free Documentation License.
5319 * file usage: File Usage. (line 6)
5320 * file-name limitations: Names. (line 38)
5321 * formatting error messages: Errors. (line 6)
5322 * formatting source code: Formatting. (line 6)
5323 * formfeed: Formatting. (line 114)
5324 * function argument, declaring: Syntactic Conventions.
5326 * function prototypes: Standard C. (line 17)
5327 * getopt: Command-Line Interfaces.
5329 * gettext: Internationalization.
5331 * gnome: Graphical Interfaces.
5333 * graphical user interface: Graphical Interfaces.
5335 * grave accent: Quote Characters. (line 6)
5336 * gtk+: Graphical Interfaces.
5338 * GUILE: Source Language. (line 38)
5339 * implicit int: Syntactic Conventions.
5341 * impossible conditions: Semantics. (line 70)
5342 * installations, staged: DESTDIR. (line 6)
5343 * internationalization: Internationalization.
5345 * left quote: Quote Characters. (line 6)
5346 * legal aspects: Legal Issues. (line 6)
5347 * legal papers: Contributions. (line 6)
5348 * libexecdir: Directory Variables. (line 67)
5349 * libraries: Libraries. (line 6)
5350 * library functions, and portability: System Functions. (line 6)
5351 * license for manuals: License for Manuals. (line 6)
5352 * lint: Syntactic Conventions.
5354 * locale-specific quote characters: Quote Characters. (line 6)
5355 * long option names: Option Table. (line 6)
5356 * long-named options: Command-Line Interfaces.
5358 * makefile, conventions for: Makefile Conventions.
5360 * malloc return value: Semantics. (line 25)
5361 * man pages: Man Pages. (line 6)
5362 * manual structure: Manual Structure Details.
5364 * memory allocation failure: Semantics. (line 25)
5365 * memory usage: Memory Usage. (line 6)
5366 * message text, and internationalization: Internationalization.
5368 * mmap: Mmap. (line 6)
5369 * multiple variables in a line: Syntactic Conventions.
5371 * names of variables, functions, and files: Names. (line 6)
5372 * NEWS file: NEWS File. (line 6)
5373 * non-ASCII characters: Character Set. (line 6)
5374 * non-POSIX systems, and portability: System Portability. (line 32)
5375 * non-standard extensions: Using Extensions. (line 6)
5376 * NUL characters: Semantics. (line 11)
5377 * open brace: Formatting. (line 6)
5378 * optional features, configure-time: Configuration. (line 83)
5379 * options for compatibility: Compatibility. (line 14)
5380 * options, standard command-line: Command-Line Interfaces.
5382 * output device and program's behavior: User Interfaces. (line 13)
5383 * packaging: Releases. (line 6)
5384 * PATH_INFO, specifying standard options as: Command-Line Interfaces.
5386 * portability, and data types: CPU Portability. (line 6)
5387 * portability, and library functions: System Functions. (line 6)
5388 * portability, between system types: System Portability. (line 6)
5389 * POSIX compatibility: Compatibility. (line 6)
5390 * POSIXLY_CORRECT, environment variable: Compatibility. (line 21)
5391 * post-installation commands: Install Command Categories.
5393 * pre-installation commands: Install Command Categories.
5395 * prefix: Directory Variables. (line 26)
5396 * program configuration: Configuration. (line 6)
5397 * program design: Design Advice. (line 6)
5398 * program name and its behavior: User Interfaces. (line 6)
5399 * program's canonical name: Command-Line Interfaces.
5401 * programming languages: Source Language. (line 6)
5402 * proprietary programs: Reading Non-Free Code.
5404 * quote characters: Quote Characters. (line 6)
5405 * README file: Releases. (line 21)
5406 * references to non-free material: References. (line 6)
5407 * releasing: Managing Releases. (line 6)
5408 * sbindir: Directory Variables. (line 60)
5409 * signal handling: Semantics. (line 59)
5410 * spaces before open-paren: Formatting. (line 71)
5411 * staged installs: DESTDIR. (line 6)
5412 * standard command-line options: Command-Line Interfaces.
5414 * standards for makefiles: Makefile Conventions.
5416 * string library functions: System Functions. (line 55)
5417 * syntactic conventions: Syntactic Conventions.
5419 * table of long options: Option Table. (line 6)
5420 * temporary files: Semantics. (line 84)
5421 * temporary variables: Syntactic Conventions.
5423 * texinfo.tex, in a distribution: Releases. (line 70)
5424 * TMPDIR environment variable: Semantics. (line 84)
5425 * trademarks: Trademarks. (line 6)
5426 * where to obtain standards.texi: Preface. (line 17)
5432 Node: Preface
\x7f2039
5433 Node: Legal Issues
\x7f4159
5434 Node: Reading Non-Free Code
\x7f4626
5435 Node: Contributions
\x7f6356
5436 Node: Trademarks
\x7f8594
5437 Node: Design Advice
\x7f10229
5438 Node: Source Language
\x7f10817
5439 Node: Compatibility
\x7f12829
5440 Node: Using Extensions
\x7f14457
5441 Node: Standard C
\x7f16033
5442 Node: Conditional Compilation
\x7f18436
5443 Node: Program Behavior
\x7f19834
5444 Node: Non-GNU Standards
\x7f20881
5445 Node: Semantics
\x7f23162
5446 Node: Libraries
\x7f27881
5447 Node: Errors
\x7f29126
5448 Node: User Interfaces
\x7f31619
5449 Node: Graphical Interfaces
\x7f33224
5450 Node: Command-Line Interfaces
\x7f34260
5451 Node: Option Table
\x7f40717
5452 Node: Memory Usage
\x7f55658
5453 Node: File Usage
\x7f56689
5454 Node: Writing C
\x7f57439
5455 Node: Formatting
\x7f58405
5456 Node: Comments
\x7f62484
5457 Node: Syntactic Conventions
\x7f66036
5458 Node: Names
\x7f69498
5459 Node: System Portability
\x7f71710
5460 Node: CPU Portability
\x7f74600
5461 Node: System Functions
\x7f78512
5462 Node: Internationalization
\x7f83709
5463 Node: Character Set
\x7f87703
5464 Node: Quote Characters
\x7f88516
5466 Node: Documentation
\x7f90744
5467 Node: GNU Manuals
\x7f91849
5468 Node: Doc Strings and Manuals
\x7f97587
5469 Node: Manual Structure Details
\x7f99140
5470 Node: License for Manuals
\x7f100558
5471 Node: Manual Credits
\x7f101532
5472 Node: Printed Manuals
\x7f101925
5473 Node: NEWS File
\x7f102611
5474 Node: Change Logs
\x7f103289
5475 Node: Change Log Concepts
\x7f104043
5476 Node: Style of Change Logs
\x7f106132
5477 Node: Simple Changes
\x7f108632
5478 Node: Conditional Changes
\x7f110074
5479 Node: Indicating the Part Changed
\x7f111496
5480 Node: Man Pages
\x7f112023
5481 Node: Reading other Manuals
\x7f114335
5482 Node: Managing Releases
\x7f115126
5483 Node: Configuration
\x7f115889
5484 Node: Makefile Conventions
\x7f123609
5485 Node: Makefile Basics
\x7f124491
5486 Node: Utilities in Makefiles
\x7f127665
5487 Node: Command Variables
\x7f129810
5488 Node: DESTDIR
\x7f133032
5489 Node: Directory Variables
\x7f135181
5490 Node: Standard Targets
\x7f149674
5491 Ref: Standard Targets-Footnote-1
\x7f163189
5492 Node: Install Command Categories
\x7f163289
5493 Node: Releases
\x7f167822
5494 Node: References
\x7f171749
5495 Node: Copying This Manual
\x7f176489
5496 Node: GNU Free Documentation License
\x7f176725
5497 Node: Index
\x7f199126