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