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