1 This is ../info/standards.info, produced by makeinfo version 4.0 from
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999 Free Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
20 Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
26 File: standards.info, Node: Comments, Next: Syntactic Conventions, Prev: Formatting, Up: Writing C
31 Every program should start with a comment saying briefly what it is
32 for. Example: `fmt - filter for simple filling of text'.
34 Please write the comments in a GNU program in English, because
35 English is the one language that nearly all programmers in all
36 countries can read. If you do not write English well, please write
37 comments in English as well as you can, then ask other people to help
38 rewrite them. If you can't write comments in English, please find
39 someone to work with you and translate your comments into English.
41 Please put a comment on each function saying what the function does,
42 what sorts of arguments it gets, and what the possible values of
43 arguments mean and are used for. It is not necessary to duplicate in
44 words the meaning of the C argument declarations, if a C type is being
45 used in its customary fashion. If there is anything nonstandard about
46 its use (such as an argument of type `char *' which is really the
47 address of the second character of a string, not the first), or any
48 possible values that would not work the way one would expect (such as,
49 that strings containing newlines are not guaranteed to work), be sure
52 Also explain the significance of the return value, if there is one.
54 Please put two spaces after the end of a sentence in your comments,
55 so that the Emacs sentence commands will work. Also, please write
56 complete sentences and capitalize the first word. If a lower-case
57 identifier comes at the beginning of a sentence, don't capitalize it!
58 Changing the spelling makes it a different identifier. If you don't
59 like starting a sentence with a lower case letter, write the sentence
60 differently (e.g., "The identifier lower-case is ...").
62 The comment on a function is much clearer if you use the argument
63 names to speak about the argument values. The variable name itself
64 should be lower case, but write it in upper case when you are speaking
65 about the value rather than the variable itself. Thus, "the inode
66 number NODE_NUM" rather than "an inode".
68 There is usually no purpose in restating the name of the function in
69 the comment before it, because the reader can see that for himself.
70 There might be an exception when the comment is so long that the
71 function itself would be off the bottom of the screen.
73 There should be a comment on each static variable as well, like this:
75 /* Nonzero means truncate lines in the display;
76 zero means continue them. */
79 Every `#endif' should have a comment, except in the case of short
80 conditionals (just a few lines) that are not nested. The comment should
81 state the condition of the conditional that is ending, _including its
82 sense_. `#else' should have a comment describing the condition _and
83 sense_ of the code that follows. For example:
94 but, by contrast, write the comments this way for a `#ifndef':
106 File: standards.info, Node: Syntactic Conventions, Next: Names, Prev: Comments, Up: Writing C
108 Clean Use of C Constructs
109 =========================
111 Please explicitly declare all arguments to functions. Don't omit
112 them just because they are `int's.
114 Declarations of external functions and functions to appear later in
115 the source file should all go in one place near the beginning of the
116 file (somewhere before the first function definition in the file), or
117 else should go in a header file. Don't put `extern' declarations inside
120 It used to be common practice to use the same local variables (with
121 names like `tem') over and over for different values within one
122 function. Instead of doing this, it is better declare a separate local
123 variable for each distinct purpose, and give it a name which is
124 meaningful. This not only makes programs easier to understand, it also
125 facilitates optimization by good compilers. You can also move the
126 declaration of each local variable into the smallest scope that includes
127 all its uses. This makes the program even cleaner.
129 Don't use local variables or parameters that shadow global
132 Don't declare multiple variables in one declaration that spans lines.
133 Start a new declaration on each line, instead. For example, instead of
148 (If they are global variables, each should have a comment preceding it
151 When you have an `if'-`else' statement nested in another `if'
152 statement, always put braces around the `if'-`else'. Thus, never write
171 If you have an `if' statement nested inside of an `else' statement,
172 either write `else if' on one line, like this,
179 with its `then'-part indented like the preceding `then'-part, or write
180 the nested `if' within braces like this:
190 Don't declare both a structure tag and variables or typedefs in the
191 same declaration. Instead, declare the structure tag separately and
192 then use it to declare the variables or typedefs.
194 Try to avoid assignments inside `if'-conditions. For example, don't
197 if ((foo = (char *) malloc (sizeof *foo)) == 0)
198 fatal ("virtual memory exhausted");
202 foo = (char *) malloc (sizeof *foo);
204 fatal ("virtual memory exhausted");
206 Don't make the program ugly to placate `lint'. Please don't insert
207 any casts to `void'. Zero without a cast is perfectly fine as a null
208 pointer constant, except when calling a varargs function.
211 File: standards.info, Node: Names, Next: System Portability, Prev: Syntactic Conventions, Up: Writing C
213 Naming Variables and Functions
214 ==============================
216 The names of global variables and functions in a program serve as
217 comments of a sort. So don't choose terse names--instead, look for
218 names that give useful information about the meaning of the variable or
219 function. In a GNU program, names should be English, like other
222 Local variable names can be shorter, because they are used only
223 within one context, where (presumably) comments explain their purpose.
225 Try to limit your use of abbreviations in symbol names. It is ok to
226 make a few abbreviations, explain what they mean, and then use them
227 frequently, but don't use lots of obscure abbreviations.
229 Please use underscores to separate words in a name, so that the Emacs
230 word commands can be useful within them. Stick to lower case; reserve
231 upper case for macros and `enum' constants, and for name-prefixes that
232 follow a uniform convention.
234 For example, you should use names like `ignore_space_change_flag';
235 don't use names like `iCantReadThis'.
237 Variables that indicate whether command-line options have been
238 specified should be named after the meaning of the option, not after
239 the option-letter. A comment should state both the exact meaning of
240 the option and its letter. For example,
242 /* Ignore changes in horizontal whitespace (-b). */
243 int ignore_space_change_flag;
245 When you want to define names with constant integer values, use
246 `enum' rather than `#define'. GDB knows about enumeration constants.
248 Use file names of 14 characters or less, to avoid creating gratuitous
249 problems on older System V systems. You can use the program `doschk'
250 to test for this. `doschk' also tests for potential name conflicts if
251 the files were loaded onto an MS-DOS file system--something you may or
255 File: standards.info, Node: System Portability, Next: CPU Portability, Prev: Names, Up: Writing C
257 Portability between System Types
258 ================================
260 In the Unix world, "portability" refers to porting to different Unix
261 versions. For a GNU program, this kind of portability is desirable, but
264 The primary purpose of GNU software is to run on top of the GNU
265 kernel, compiled with the GNU C compiler, on various types of CPU. The
266 amount and kinds of variation among GNU systems on different CPUs will
267 be comparable to the variation among Linux-based GNU systems or among
268 BSD systems today. So the kinds of portability that are absolutely
269 necessary are quite limited.
271 But many users do run GNU software on non-GNU Unix or Unix-like
272 systems. So supporting a variety of Unix-like systems is desirable,
273 although not paramount.
275 The easiest way to achieve portability to most Unix-like systems is
276 to use Autoconf. It's unlikely that your program needs to know more
277 information about the host platform than Autoconf can provide, simply
278 because most of the programs that need such knowledge have already been
281 Avoid using the format of semi-internal data bases (e.g.,
282 directories) when there is a higher-level alternative (`readdir').
284 As for systems that are not like Unix, such as MSDOS, Windows, the
285 Macintosh, VMS, and MVS, supporting them is often a lot of work. When
286 that is the case, it is better to spend your time adding features that
287 will be useful on GNU and GNU/Linux, rather than on supporting other
288 incompatible systems.
291 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
293 Portability between CPUs
294 ========================
296 Even GNU systems will differ because of differences among CPU
297 types--for example, difference in byte ordering and alignment
298 requirements. It is absolutely essential to handle these differences.
299 However, don't make any effort to cater to the possibility that an
300 `int' will be less than 32 bits. We don't support 16-bit machines in
303 Don't assume that the address of an `int' object is also the address
304 of its least-significant byte. This is false on big-endian machines.
305 Thus, don't make the following mistake:
309 while ((c = getchar()) != EOF)
310 write(file_descriptor, &c, 1);
312 When calling functions, you need not worry about the difference
313 between pointers of various types, or between pointers and integers.
314 On most machines, there's no difference anyway. As for the few
315 machines where there is a difference, all of them support ANSI C, so
316 you can use prototypes (conditionalized to be active only in ANSI C) to
317 make the code work on those systems.
319 In certain cases, it is ok to pass integer and pointer arguments
320 indiscriminately to the same function, and use no prototype on any
321 system. For example, many GNU programs have error-reporting functions
322 that pass their arguments along to `printf' and friends:
324 error (s, a1, a2, a3)
328 fprintf (stderr, "error: ");
329 fprintf (stderr, s, a1, a2, a3);
332 In practice, this works on all machines, since a pointer is generally
333 the widest possible kind of argument, and it is much simpler than any
334 "correct" alternative. Be sure _not_ to use a prototype for such
337 However, avoid casting pointers to integers unless you really need
338 to. Outside of special situations, such casts greatly reduce
339 portability, and in most programs they are easy to avoid. In the cases
340 where casting pointers to integers is essential--such as, a Lisp
341 interpreter which stores type information as well as an address in one
342 word--it is ok to do it, but you'll have to make explicit provisions to
343 handle different word sizes.
346 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
348 Calling System Functions
349 ========================
351 C implementations differ substantially. ANSI C reduces but does not
352 eliminate the incompatibilities; meanwhile, many users wish to compile
353 GNU software with pre-ANSI compilers. This chapter gives
354 recommendations for how to use the more or less standard C library
355 functions to avoid unnecessary loss of portability.
357 * Don't use the value of `sprintf'. It returns the number of
358 characters written on some systems, but not on all systems.
360 * `main' should be declared to return type `int'. It should
361 terminate either by calling `exit' or by returning the integer
362 status code; make sure it cannot ever return an undefined value.
364 * Don't declare system functions explicitly.
366 Almost any declaration for a system function is wrong on some
367 system. To minimize conflicts, leave it to the system header
368 files to declare system functions. If the headers don't declare a
369 function, let it remain undeclared.
371 While it may seem unclean to use a function without declaring it,
372 in practice this works fine for most system library functions on
373 the systems where this really happens; thus, the disadvantage is
374 only theoretical. By contrast, actual declarations have
375 frequently caused actual conflicts.
377 * If you must declare a system function, don't specify the argument
378 types. Use an old-style declaration, not an ANSI prototype. The
379 more you specify about the function, the more likely a conflict.
381 * In particular, don't unconditionally declare `malloc' or `realloc'.
383 Most GNU programs use those functions just once, in functions
384 conventionally named `xmalloc' and `xrealloc'. These functions
385 call `malloc' and `realloc', respectively, and check the results.
387 Because `xmalloc' and `xrealloc' are defined in your program, you
388 can declare them in other files without any risk of type conflict.
390 On most systems, `int' is the same length as a pointer; thus, the
391 calls to `malloc' and `realloc' work fine. For the few
392 exceptional systems (mostly 64-bit machines), you can use
393 *conditionalized* declarations of `malloc' and `realloc'--or put
394 these declarations in configuration files specific to those
397 * The string functions require special treatment. Some Unix systems
398 have a header file `string.h'; others have `strings.h'. Neither
399 file name is portable. There are two things you can do: use
400 Autoconf to figure out which file to include, or don't include
403 * If you don't include either strings file, you can't get
404 declarations for the string functions from the header file in the
407 That causes less of a problem than you might think. The newer ANSI
408 string functions should be avoided anyway because many systems
409 still don't support them. The string functions you can use are
412 strcpy strncpy strcat strncat
413 strlen strcmp strncmp
416 The copy and concatenate functions work fine without a declaration
417 as long as you don't use their values. Using their values without
418 a declaration fails on systems where the width of a pointer
419 differs from the width of `int', and perhaps in other cases. It
420 is trivial to avoid using their values, so do that.
422 The compare functions and `strlen' work fine without a declaration
423 on most systems, possibly all the ones that GNU software runs on.
424 You may find it necessary to declare them *conditionally* on a few
427 The search functions must be declared to return `char *'. Luckily,
428 there is no variation in the data type they return. But there is
429 variation in their names. Some systems give these functions the
430 names `index' and `rindex'; other systems use the names `strchr'
431 and `strrchr'. Some systems support both pairs of names, but
432 neither pair works on all systems.
434 You should pick a single pair of names and use it throughout your
435 program. (Nowadays, it is better to choose `strchr' and `strrchr'
436 for new programs, since those are the standard ANSI names.)
437 Declare both of those names as functions returning `char *'. On
438 systems which don't support those names, define them as macros in
439 terms of the other pair. For example, here is what to put at the
440 beginning of your file (or in a header) if you want to use the
441 names `strchr' and `strrchr' throughout:
447 #define strrchr rindex
453 Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
454 defined in systems where the corresponding functions exist. One way to
455 get them properly defined is to use Autoconf.
458 File: standards.info, Node: Internationalization, Next: Mmap, Prev: System Functions, Up: Writing C
463 GNU has a library called GNU gettext that makes it easy to translate
464 the messages in a program into various languages. You should use this
465 library in every program. Use English for the messages as they appear
466 in the program, and let gettext provide the way to translate them into
469 Using GNU gettext involves putting a call to the `gettext' macro
470 around each string that might need translation--like this:
472 printf (gettext ("Processing file `%s'..."));
474 This permits GNU gettext to replace the string `"Processing file
475 `%s'..."' with a translated version.
477 Once a program uses gettext, please make a point of writing calls to
478 `gettext' when you add new strings that call for translation.
480 Using GNU gettext in a package involves specifying a "text domain
481 name" for the package. The text domain name is used to separate the
482 translations for this package from the translations for other packages.
483 Normally, the text domain name should be the same as the name of the
484 package--for example, `fileutils' for the GNU file utilities.
486 To enable gettext to work well, avoid writing code that makes
487 assumptions about the structure of words or sentences. When you want
488 the precise text of a sentence to vary depending on the data, use two or
489 more alternative string constants each containing a complete sentences,
490 rather than inserting conditionalized words or phrases into a single
493 Here is an example of what not to do:
495 printf ("%d file%s processed", nfiles,
496 nfiles != 1 ? "s" : "");
498 The problem with that example is that it assumes that plurals are made
499 by adding `s'. If you apply gettext to the format string, like this,
501 printf (gettext ("%d file%s processed"), nfiles,
502 nfiles != 1 ? "s" : "");
504 the message can use different words, but it will still be forced to use
505 `s' for the plural. Here is a better way:
507 printf ((nfiles != 1 ? "%d files processed"
508 : "%d file processed"),
511 This way, you can apply gettext to each of the two strings
514 printf ((nfiles != 1 ? gettext ("%d files processed")
515 : gettext ("%d file processed")),
518 This can be any method of forming the plural of the word for "file", and
519 also handles languages that require agreement in the word for
522 A similar problem appears at the level of sentence structure with
525 printf ("# Implicit rule search has%s been done.\n",
526 f->tried_implicit ? "" : " not");
528 Adding `gettext' calls to this code cannot give correct results for all
529 languages, because negation in some languages requires adding words at
530 more than one place in the sentence. By contrast, adding `gettext'
531 calls does the job straightfowardly if the code starts out like this:
533 printf (f->tried_implicit
534 ? "# Implicit rule search has been done.\n",
535 : "# Implicit rule search has not been done.\n");
538 File: standards.info, Node: Mmap, Prev: Internationalization, Up: Writing C
543 Don't assume that `mmap' either works on all files or fails for all
544 files. It may work on some files and fail on others.
546 The proper way to use `mmap' is to try it on the specific file for
547 which you want to use it--and if `mmap' doesn't work, fall back on
548 doing the job in another way using `read' and `write'.
550 The reason this precaution is needed is that the GNU kernel (the
551 HURD) provides a user-extensible file system, in which there can be many
552 different kinds of "ordinary files." Many of them support `mmap', but
553 some do not. It is important to make programs handle all these kinds
557 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
564 * GNU Manuals:: Writing proper manuals.
565 * Manual Structure Details:: Specific structure conventions.
566 * License for Manuals:: Writing the distribution terms for a manual.
567 * NEWS File:: NEWS files supplement manuals.
568 * Change Logs:: Recording Changes
569 * Man Pages:: Man pages are secondary.
570 * Reading other Manuals:: How far you can go in learning
574 File: standards.info, Node: GNU Manuals, Next: Manual Structure Details, Up: Documentation
579 The preferred way to document part of the GNU system is to write a
580 manual in the Texinfo formatting language. This makes it possible to
581 produce a good quality formatted book, using TeX, and to generate an
582 Info file. It is also possible to generate HTML output from Texinfo
583 source. See the Texinfo manual, either the hardcopy, or the on-line
584 version available through `info' or the Emacs Info subsystem (`C-h i').
586 Programmers often find it most natural to structure the documentation
587 following the structure of the implementation, which they know. But
588 this structure is not necessarily good for explaining how to use the
589 program; it may be irrelevant and confusing for a user.
591 At every level, from the sentences in a paragraph to the grouping of
592 topics into separate manuals, the right way to structure documentation
593 is according to the concepts and questions that a user will have in mind
594 when reading it. Sometimes this structure of ideas matches the
595 structure of the implementation of the software being documented--but
596 often they are different. Often the most important part of learning to
597 write good documentation is learning to notice when you are structuring
598 the documentation like the implementation, and think about better
601 For example, each program in the GNU system probably ought to be
602 documented in one manual; but this does not mean each program should
603 have its own manual. That would be following the structure of the
604 implementation, rather than the structure that helps the user
607 Instead, each manual should cover a coherent _topic_. For example,
608 instead of a manual for `diff' and a manual for `diff3', we have one
609 manual for "comparison of files" which covers both of those programs,
610 as well as `cmp'. By documenting these programs together, we can make
611 the whole subject clearer.
613 The manual which discusses a program should document all of the
614 program's command-line options and all of its commands. It should give
615 examples of their use. But don't organize the manual as a list of
616 features. Instead, organize it logically, by subtopics. Address the
617 questions that a user will ask when thinking about the job that the
620 In general, a GNU manual should serve both as tutorial and reference.
621 It should be set up for convenient access to each topic through Info,
622 and for reading straight through (appendixes aside). A GNU manual
623 should give a good introduction to a beginner reading through from the
624 start, and should also provide all the details that hackers want. The
625 Bison manual is a good example of this--please take a look at it to see
628 That is not as hard as it first sounds. Arrange each chapter as a
629 logical breakdown of its topic, but order the sections, and write their
630 text, so that reading the chapter straight through makes sense. Do
631 likewise when structuring the book into chapters, and when structuring a
632 section into paragraphs. The watchword is, _at each point, address the
633 most fundamental and important issue raised by the preceding text._
635 If necessary, add extra chapters at the beginning of the manual which
636 are purely tutorial and cover the basics of the subject. These provide
637 the framework for a beginner to understand the rest of the manual. The
638 Bison manual provides a good example of how to do this.
640 Don't use Unix man pages as a model for how to write GNU
641 documentation; most of them are terse, badly structured, and give
642 inadequate explanation of the underlying concepts. (There are, of
643 course exceptions.) Also Unix man pages use a particular format which
644 is different from what we use in GNU manuals.
646 Please include an email address in the manual for where to report
647 bugs _in the manual_.
649 Please do not use the term "pathname" that is used in Unix
650 documentation; use "file name" (two words) instead. We use the term
651 "path" only for search paths, which are lists of directory names.
653 Please do not use the term "illegal" to refer to erroneous input to a
654 computer program. Please use "invalid" for this, and reserve the term
655 "illegal" for violations of law.
658 File: standards.info, Node: Manual Structure Details, Next: License for Manuals, Prev: GNU Manuals, Up: Documentation
660 Manual Structure Details
661 ========================
663 The title page of the manual should state the version of the
664 programs or packages documented in the manual. The Top node of the
665 manual should also contain this information. If the manual is changing
666 more frequently than or independent of the program, also state a version
667 number for the manual in both of these places.
669 Each program documented in the manual should have a node named
670 `PROGRAM Invocation' or `Invoking PROGRAM'. This node (together with
671 its subnodes, if any) should describe the program's command line
672 arguments and how to run it (the sort of information people would look
673 in a man page for). Start with an `@example' containing a template for
674 all the options and arguments that the program uses.
676 Alternatively, put a menu item in some menu whose item name fits one
677 of the above patterns. This identifies the node which that item points
678 to as the node for this purpose, regardless of the node's actual name.
680 There will be automatic features for specifying a program name and
681 quickly reading just this part of its manual.
683 If one manual describes several programs, it should have such a node
684 for each program described.
687 File: standards.info, Node: License for Manuals, Next: NEWS File, Prev: Manual Structure Details, Up: Documentation
692 If the manual contains a copy of the GNU GPL or GNU LGPL, or if it
693 contains chapters that make political or personal statements, please
694 copy the distribution terms of the GNU Emacs Manual, and adapt it by
695 modifying appropriately the list of special chapters that may not be
698 If the manual does not contain any such chapters, then imitate the
699 simpler distribution terms of the Texinfo manual.
702 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: License for Manuals, Up: Documentation
707 In addition to its manual, the package should have a file named
708 `NEWS' which contains a list of user-visible changes worth mentioning.
709 In each new release, add items to the front of the file and identify
710 the version they pertain to. Don't discard old items; leave them in
711 the file after the newer items. This way, a user upgrading from any
712 previous version can see what is new.
714 If the `NEWS' file gets very long, move some of the older items into
715 a file named `ONEWS' and put a note at the end referring the user to
719 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
724 Keep a change log to describe all the changes made to program source
725 files. The purpose of this is so that people investigating bugs in the
726 future will know about the changes that might have introduced the bug.
727 Often a new bug can be found by looking at what was recently changed.
728 More importantly, change logs can help you eliminate conceptual
729 inconsistencies between different parts of a program, by giving you a
730 history of how the conflicting concepts arose and who they came from.
734 * Change Log Concepts::
735 * Style of Change Logs::
737 * Conditional Changes::
740 File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs
745 You can think of the change log as a conceptual "undo list" which
746 explains how earlier versions were different from the current version.
747 People can see the current version; they don't need the change log to
748 tell them what is in it. What they want from a change log is a clear
749 explanation of how the earlier version differed.
751 The change log file is normally called `ChangeLog' and covers an
752 entire directory. Each directory can have its own change log, or a
753 directory can use the change log of its parent directory-it's up to you.
755 Another alternative is to record change log information with a
756 version control system such as RCS or CVS. This can be converted
757 automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
758 command `C-x v a' (`vc-update-change-log') does the job.
760 There's no need to describe the full purpose of the changes or how
761 they work together. If you think that a change calls for explanation,
762 you're probably right. Please do explain it--but please put the
763 explanation in comments in the code, where people will see it whenever
764 they see the code. For example, "New function" is enough for the
765 change log when you add a function, because there should be a comment
766 before the function definition to explain what it does.
768 However, sometimes it is useful to write one line to describe the
769 overall purpose of a batch of changes.
771 The easiest way to add an entry to `ChangeLog' is with the Emacs
772 command `M-x add-change-log-entry'. An entry should have an asterisk,
773 the name of the changed file, and then in parentheses the name of the
774 changed functions, variables or whatever, followed by a colon. Then
775 describe the changes you made to that function or variable.
778 File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs
783 Here are some examples of change log entries:
785 * register.el (insert-register): Return nil.
786 (jump-to-register): Likewise.
788 * sort.el (sort-subr): Return nil.
790 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
791 Restart the tex shell if process is gone or stopped.
792 (tex-shell-running): New function.
794 * expr.c (store_one_arg): Round size up for move_block_to_reg.
795 (expand_call): Round up when emitting USE insns.
796 * stmt.c (assign_parms): Round size up for move_block_from_reg.
798 It's important to name the changed function or variable in full.
799 Don't abbreviate function or variable names, and don't combine them.
800 Subsequent maintainers will often search for a function name to find all
801 the change log entries that pertain to it; if you abbreviate the name,
802 they won't find it when they search.
804 For example, some people are tempted to abbreviate groups of function
805 names by writing `* register.el ({insert,jump-to}-register)'; this is
806 not a good idea, since searching for `jump-to-register' or
807 `insert-register' would not find that entry.
809 Separate unrelated change log entries with blank lines. When two
810 entries represent parts of the same change, so that they work together,
811 then don't put blank lines between them. Then you can omit the file
812 name and the asterisk when successive entries are in the same file.
815 File: standards.info, Node: Simple Changes, Next: Conditional Changes, Prev: Style of Change Logs, Up: Change Logs
820 Certain simple kinds of changes don't need much detail in the change
823 When you change the calling sequence of a function in a simple
824 fashion, and you change all the callers of the function, there is no
825 need to make individual entries for all the callers that you changed.
826 Just write in the entry for the function being called, "All callers
829 * keyboard.c (Fcommand_execute): New arg SPECIAL.
832 When you change just comments or doc strings, it is enough to write
833 an entry for the file, without mentioning the functions. Just "Doc
834 fixes" is enough for the change log.
836 There's no need to make change log entries for documentation files.
837 This is because documentation is not susceptible to bugs that are hard
838 to fix. Documentation does not consist of parts that must interact in a
839 precisely engineered fashion. To correct an error, you need not know
840 the history of the erroneous passage; it is enough to compare what the
841 documentation says with the way the program actually works.
844 File: standards.info, Node: Conditional Changes, Prev: Simple Changes, Up: Change Logs
849 C programs often contain compile-time `#if' conditionals. Many
850 changes are conditional; sometimes you add a new definition which is
851 entirely contained in a conditional. It is very useful to indicate in
852 the change log the conditions for which the change applies.
854 Our convention for indicating conditional changes is to use square
855 brackets around the name of the condition.
857 Here is a simple example, describing a change which is conditional
858 but does not have a function or entity name associated with it:
860 * xterm.c [SOLARIS2]: Include string.h.
862 Here is an entry describing a new definition which is entirely
863 conditional. This new definition for the macro `FRAME_WINDOW_P' is
864 used only when `HAVE_X_WINDOWS' is defined:
866 * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
868 Here is an entry for a change within the function `init_display',
869 whose definition as a whole is unconditional, but the changes themselves
870 are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
872 * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
874 Here is an entry for a change that takes affect only when a certain
875 macro is _not_ defined:
877 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
880 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
885 In the GNU project, man pages are secondary. It is not necessary or
886 expected for every GNU program to have a man page, but some of them do.
887 It's your choice whether to include a man page in your program.
889 When you make this decision, consider that supporting a man page
890 requires continual effort each time the program is changed. The time
891 you spend on the man page is time taken away from more useful work.
893 For a simple program which changes little, updating the man page may
894 be a small job. Then there is little reason not to include a man page,
897 For a large program that changes a great deal, updating a man page
898 may be a substantial burden. If a user offers to donate a man page,
899 you may find this gift costly to accept. It may be better to refuse
900 the man page unless the same person agrees to take full responsibility
901 for maintaining it--so that you can wash your hands of it entirely. If
902 this volunteer later ceases to do the job, then don't feel obliged to
903 pick it up yourself; it may be better to withdraw the man page from the
904 distribution until someone else agrees to update it.
906 When a program changes only a little, you may feel that the
907 discrepancies are small enough that the man page remains useful without
908 updating. If so, put a prominent note near the beginning of the man
909 page explaining that you don't maintain it and that the Texinfo manual
910 is more authoritative. The note should say how to access the Texinfo
914 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
916 Reading other Manuals
917 =====================
919 There may be non-free books or documentation files that describe the
920 program you are documenting.
922 It is ok to use these documents for reference, just as the author of
923 a new algebra textbook can read other books on algebra. A large portion
924 of any non-fiction book consists of facts, in this case facts about how
925 a certain program works, and these facts are necessarily the same for
926 everyone who writes about the subject. But be careful not to copy your
927 outline structure, wording, tables or examples from preexisting non-free
928 documentation. Copying from free documentation may be ok; please check
929 with the FSF about the individual case.
932 File: standards.info, Node: Managing Releases, Next: References, Prev: Documentation, Up: Top
937 Making a release is more than just bundling up your source files in a
938 tar file and putting it up for FTP. You should set up your software so
939 that it can be configured to run on a variety of systems. Your Makefile
940 should conform to the GNU standards described below, and your directory
941 layout should also conform to the standards discussed below. Doing so
942 makes it easy to include your package into the larger framework of all
947 * Configuration:: How Configuration Should Work
948 * Makefile Conventions:: Makefile Conventions
949 * Releases:: Making Releases
952 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
954 How Configuration Should Work
955 =============================
957 Each GNU distribution should come with a shell script named
958 `configure'. This script is given arguments which describe the kind of
959 machine and system you want to compile the program for.
961 The `configure' script must record the configuration options so that
962 they affect compilation.
964 One way to do this is to make a link from a standard name such as
965 `config.h' to the proper configuration file for the chosen system. If
966 you use this technique, the distribution should _not_ contain a file
967 named `config.h'. This is so that people won't be able to build the
968 program without configuring it first.
970 Another thing that `configure' can do is to edit the Makefile. If
971 you do this, the distribution should _not_ contain a file named
972 `Makefile'. Instead, it should include a file `Makefile.in' which
973 contains the input used for editing. Once again, this is so that people
974 won't be able to build the program without configuring it first.
976 If `configure' does write the `Makefile', then `Makefile' should
977 have a target named `Makefile' which causes `configure' to be rerun,
978 setting up the same configuration that was set up last time. The files
979 that `configure' reads should be listed as dependencies of `Makefile'.
981 All the files which are output from the `configure' script should
982 have comments at the beginning explaining that they were generated
983 automatically using `configure'. This is so that users won't think of
984 trying to edit them by hand.
986 The `configure' script should write a file named `config.status'
987 which describes which configuration options were specified when the
988 program was last configured. This file should be a shell script which,
989 if run, will recreate the same configuration.
991 The `configure' script should accept an option of the form
992 `--srcdir=DIRNAME' to specify the directory where sources are found (if
993 it is not the current directory). This makes it possible to build the
994 program in a separate directory, so that the actual source directory is
997 If the user does not specify `--srcdir', then `configure' should
998 check both `.' and `..' to see if it can find the sources. If it finds
999 the sources in one of these places, it should use them from there.
1000 Otherwise, it should report that it cannot find the sources, and should
1001 exit with nonzero status.
1003 Usually the easy way to support `--srcdir' is by editing a
1004 definition of `VPATH' into the Makefile. Some rules may need to refer
1005 explicitly to the specified source directory. To make this possible,
1006 `configure' can add to the Makefile a variable named `srcdir' whose
1007 value is precisely the specified directory.
1009 The `configure' script should also take an argument which specifies
1010 the type of system to build the program for. This argument should look
1015 For example, a Sun 3 might be `m68k-sun-sunos4.1'.
1017 The `configure' script needs to be able to decode all plausible
1018 alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
1019 would be a valid alias. For many programs, `vax-dec-ultrix' would be
1020 an alias for `vax-dec-bsd', simply because the differences between
1021 Ultrix and BSD are rarely noticeable, but a few programs might need to
1024 There is a shell script called `config.sub' that you can use as a
1025 subroutine to validate system types and canonicalize aliases.
1027 Other options are permitted to specify in more detail the software
1028 or hardware present on the machine, and include or exclude optional
1029 parts of the package:
1031 `--enable-FEATURE[=PARAMETER]'
1032 Configure the package to build and install an optional user-level
1033 facility called FEATURE. This allows users to choose which
1034 optional features to include. Giving an optional PARAMETER of
1035 `no' should omit FEATURE, if it is built by default.
1037 No `--enable' option should *ever* cause one feature to replace
1038 another. No `--enable' option should ever substitute one useful
1039 behavior for another useful behavior. The only proper use for
1040 `--enable' is for questions of whether to build part of the program
1044 The package PACKAGE will be installed, so configure this package
1045 to work with PACKAGE.
1047 Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
1048 `gnu-libc', `gdb', `x', and `x-toolkit'.
1050 Do not use a `--with' option to specify the file name to use to
1051 find certain files. That is outside the scope of what `--with'
1055 The target machine has no floating point processor.
1058 The target machine assembler is GAS, the GNU assembler. This is
1059 obsolete; users should use `--with-gnu-as' instead.
1062 The target machine has the X Window System installed. This is
1063 obsolete; users should use `--with-x' instead.
1065 All `configure' scripts should accept all of these "detail" options,
1066 whether or not they make any difference to the particular package at
1067 hand. In particular, they should accept any option that starts with
1068 `--with-' or `--enable-'. This is so users will be able to configure
1069 an entire GNU source tree at once with a single set of options.
1071 You will note that the categories `--with-' and `--enable-' are
1072 narrow: they *do not* provide a place for any sort of option you might
1073 think of. That is deliberate. We want to limit the possible
1074 configuration options in GNU software. We do not want GNU programs to
1075 have idiosyncratic configuration options.
1077 Packages that perform part of the compilation process may support
1078 cross-compilation. In such a case, the host and target machines for
1079 the program may be different. The `configure' script should normally
1080 treat the specified type of system as both the host and the target,
1081 thus producing a program which works for the same type of machine that
1084 The way to build a cross-compiler, cross-assembler, or what have
1085 you, is to specify the option `--host=HOSTTYPE' when running
1086 `configure'. This specifies the host system without changing the type
1087 of target system. The syntax for HOSTTYPE is the same as described
1090 Bootstrapping a cross-compiler requires compiling it on a machine
1091 other than the host it will run on. Compilation packages accept a
1092 configuration option `--build=HOSTTYPE' for specifying the
1093 configuration on which you will compile them, in case that is different
1096 Programs for which cross-operation is not meaningful need not accept
1097 the `--host' option, because configuring an entire operating system for
1098 cross-operation is not a meaningful thing.
1100 Some programs have ways of configuring themselves automatically. If
1101 your program is set up to do this, your `configure' script can simply
1102 ignore most of its arguments.
1105 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
1107 Makefile Conventions
1108 ====================
1110 This node describes conventions for writing the Makefiles for GNU
1111 programs. Using Automake will help you write a Makefile that follows
1116 * Makefile Basics:: General Conventions for Makefiles
1117 * Utilities in Makefiles:: Utilities in Makefiles
1118 * Command Variables:: Variables for Specifying Commands
1119 * Directory Variables:: Variables for Installation Directories
1120 * Standard Targets:: Standard Targets for Users
1121 * Install Command Categories:: Three categories of commands in the `install'
1122 rule: normal, pre-install and post-install.
1125 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
1127 General Conventions for Makefiles
1128 ---------------------------------
1130 Every Makefile should contain this line:
1134 to avoid trouble on systems where the `SHELL' variable might be
1135 inherited from the environment. (This is never a problem with GNU
1138 Different `make' programs have incompatible suffix lists and
1139 implicit rules, and this sometimes creates confusion or misbehavior. So
1140 it is a good idea to set the suffix list explicitly using only the
1141 suffixes you need in the particular Makefile, like this:
1146 The first line clears out the suffix list, the second introduces all
1147 suffixes which may be subject to implicit rules in this Makefile.
1149 Don't assume that `.' is in the path for command execution. When
1150 you need to run programs that are a part of your package during the
1151 make, please make sure that it uses `./' if the program is built as
1152 part of the make or `$(srcdir)/' if the file is an unchanging part of
1153 the source code. Without one of these prefixes, the current search
1156 The distinction between `./' (the "build directory") and
1157 `$(srcdir)/' (the "source directory") is important because users can
1158 build in a separate directory using the `--srcdir' option to
1159 `configure'. A rule of the form:
1161 foo.1 : foo.man sedscript
1162 sed -e sedscript foo.man > foo.1
1164 will fail when the build directory is not the source directory, because
1165 `foo.man' and `sedscript' are in the the source directory.
1167 When using GNU `make', relying on `VPATH' to find the source file
1168 will work in the case where there is a single dependency file, since
1169 the `make' automatic variable `$<' will represent the source file
1170 wherever it is. (Many versions of `make' set `$<' only in implicit
1171 rules.) A Makefile target like
1174 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
1176 should instead be written as
1179 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
1181 in order to allow `VPATH' to work correctly. When the target has
1182 multiple dependencies, using an explicit `$(srcdir)' is the easiest way
1183 to make the rule work well. For example, the target above for `foo.1'
1186 foo.1 : foo.man sedscript
1187 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
1189 GNU distributions usually contain some files which are not source
1190 files--for example, Info files, and the output from Autoconf, Automake,
1191 Bison or Flex. Since these files normally appear in the source
1192 directory, they should always appear in the source directory, not in the
1193 build directory. So Makefile rules to update them should put the
1194 updated files in the source directory.
1196 However, if a file does not appear in the distribution, then the
1197 Makefile should not put it in the source directory, because building a
1198 program in ordinary circumstances should not modify the source directory
1201 Try to make the build and installation targets, at least (and all
1202 their subtargets) work correctly with a parallel `make'.