|
0
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @c %**start of header
|
|
290
|
3 @setfilename ../info/standards.info
|
|
0
|
4 @settitle GNU Coding Standards
|
|
|
5 @c UPDATE THIS DATE WHENEVER YOU MAKE CHANGES!
|
|
|
6 @set lastupdate 17 May 1996
|
|
|
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
|
|
|
20 @c This is used by a cross ref in make-stds.texi
|
|
|
21 @set CODESTD 1
|
|
|
22 @iftex
|
|
|
23 @set CHAPTER chapter
|
|
|
24 @end iftex
|
|
|
25 @ifinfo
|
|
|
26 @set CHAPTER node
|
|
|
27 @end ifinfo
|
|
|
28
|
|
|
29 @ifinfo
|
|
|
30 GNU Coding Standards
|
|
|
31 Copyright (C) 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
|
|
|
32
|
|
|
33 Permission is granted to make and distribute verbatim copies of
|
|
|
34 this manual provided the copyright notice and this permission notice
|
|
|
35 are preserved on all copies.
|
|
|
36
|
|
|
37 @ignore
|
|
|
38 Permission is granted to process this file through TeX and print the
|
|
|
39 results, provided the printed document carries copying permission
|
|
|
40 notice identical to this one except for the removal of this paragraph
|
|
|
41 (this paragraph not being relevant to the printed manual).
|
|
|
42 @end ignore
|
|
|
43
|
|
|
44 Permission is granted to copy and distribute modified versions of this
|
|
|
45 manual under the conditions for verbatim copying, provided that the entire
|
|
|
46 resulting derived work is distributed under the terms of a permission
|
|
|
47 notice identical to this one.
|
|
|
48
|
|
|
49 Permission is granted to copy and distribute translations of this manual
|
|
|
50 into another language, under the above conditions for modified versions,
|
|
|
51 except that this permission notice may be stated in a translation approved
|
|
|
52 by the Free Software Foundation.
|
|
|
53 @end ifinfo
|
|
|
54
|
|
|
55 @titlepage
|
|
|
56 @title GNU Coding Standards
|
|
|
57 @author Richard Stallman
|
|
|
58 @author last updated @value{lastupdate}
|
|
|
59 @page
|
|
|
60
|
|
|
61 @vskip 0pt plus 1filll
|
|
|
62 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc.
|
|
|
63
|
|
|
64 Permission is granted to make and distribute verbatim copies of
|
|
|
65 this manual provided the copyright notice and this permission notice
|
|
|
66 are preserved on all copies.
|
|
|
67
|
|
|
68 Permission is granted to copy and distribute modified versions of this
|
|
|
69 manual under the conditions for verbatim copying, provided that the entire
|
|
|
70 resulting derived work is distributed under the terms of a permission
|
|
|
71 notice identical to this one.
|
|
|
72
|
|
|
73 Permission is granted to copy and distribute translations of this manual
|
|
|
74 into another language, under the above conditions for modified versions,
|
|
|
75 except that this permission notice may be stated in a translation approved
|
|
|
76 by the Free Software Foundation.
|
|
|
77 @end titlepage
|
|
|
78
|
|
|
79 @ifinfo
|
|
|
80 @node Top, Preface, (dir), (dir)
|
|
|
81 @top Version
|
|
|
82
|
|
|
83 Last updated @value{lastupdate}.
|
|
|
84 @end ifinfo
|
|
|
85
|
|
|
86 @menu
|
|
|
87 * Preface:: About the GNU Coding Standards
|
|
|
88 * Intellectual Property:: Keeping Free Software Free
|
|
|
89 * Design Advice:: General Program Design
|
|
|
90 * Program Behavior:: Program Behavior for All Programs
|
|
|
91 * Writing C:: Making The Best Use of C
|
|
|
92 * Documentation:: Documenting Programs
|
|
|
93 * Managing Releases:: The Release Process
|
|
|
94 @end menu
|
|
|
95
|
|
|
96 @node Preface
|
|
|
97 @chapter About the GNU Coding Standards
|
|
|
98
|
|
|
99 The GNU Coding Standards were written by Richard Stallman and other GNU
|
|
|
100 Project volunteers. Their purpose is to make the GNU system clean,
|
|
|
101 consistent, and easy to install. This document can also be read as a
|
|
|
102 guide to writing portable, robust and reliable programs. It focuses on
|
|
|
103 programs written in C, but many of the rules and principles are useful
|
|
|
104 even if you write in another programming language. The rules often
|
|
|
105 state reasons for writing in a certain way.
|
|
|
106
|
|
|
107 Corrections or suggestions regarding this document should be sent to
|
|
|
108 @code{gnu@@prep.ai.mit.edu}. If you make a suggestion, please include a
|
|
|
109 suggested new wording for it; our time is limited. We prefer a context
|
|
|
110 diff to the @file{standards.texi} or @file{make-stds.texi} files, but if
|
|
|
111 you don't have those files, please mail your suggestion anyway.
|
|
|
112
|
|
|
113 This release of the GNU Coding Standards was last updated
|
|
|
114 @value{lastupdate}.
|
|
|
115
|
|
|
116 @node Intellectual Property
|
|
|
117 @chapter Keeping Free Software Free
|
|
|
118
|
|
|
119 This @value{CHAPTER} discusses how you can make sure that GNU software
|
|
|
120 remains unencumbered.
|
|
|
121
|
|
|
122 @menu
|
|
|
123 * Reading Non-Free Code:: Referring to Proprietary Programs
|
|
|
124 * Contributions:: Accepting Contributions
|
|
|
125 @end menu
|
|
|
126
|
|
|
127 @node Reading Non-Free Code
|
|
|
128 @section Referring to Proprietary Programs
|
|
|
129
|
|
|
130 Don't in any circumstances refer to Unix source code for or during
|
|
|
131 your work on GNU! (Or to any other proprietary programs.)
|
|
|
132
|
|
|
133 If you have a vague recollection of the internals of a Unix program,
|
|
|
134 this does not absolutely mean you can't write an imitation of it, but
|
|
|
135 do try to organize the imitation internally along different lines,
|
|
|
136 because this is likely to make the details of the Unix version
|
|
|
137 irrelevant and dissimilar to your results.
|
|
|
138
|
|
|
139 For example, Unix utilities were generally optimized to minimize
|
|
|
140 memory use; if you go for speed instead, your program will be very
|
|
|
141 different. You could keep the entire input file in core and scan it
|
|
|
142 there instead of using stdio. Use a smarter algorithm discovered more
|
|
|
143 recently than the Unix program. Eliminate use of temporary files. Do
|
|
|
144 it in one pass instead of two (we did this in the assembler).
|
|
|
145
|
|
|
146 Or, on the contrary, emphasize simplicity instead of speed. For some
|
|
|
147 applications, the speed of today's computers makes simpler algorithms
|
|
|
148 adequate.
|
|
|
149
|
|
|
150 Or go for generality. For example, Unix programs often have static
|
|
|
151 tables or fixed-size strings, which make for arbitrary limits; use
|
|
|
152 dynamic allocation instead. Make sure your program handles NULs and
|
|
|
153 other funny characters in the input files. Add a programming language
|
|
|
154 for extensibility and write part of the program in that language.
|
|
|
155
|
|
|
156 Or turn some parts of the program into independently usable libraries.
|
|
|
157 Or use a simple garbage collector instead of tracking precisely when
|
|
|
158 to free memory, or use a new GNU facility such as obstacks.
|
|
|
159
|
|
|
160
|
|
|
161 @node Contributions
|
|
|
162 @section Accepting Contributions
|
|
|
163
|
|
|
164 If someone else sends you a piece of code to add to the program you are
|
|
|
165 working on, we need legal papers to use it---the same sort of legal
|
|
|
166 papers we will need to get from you. @emph{Each} significant
|
|
|
167 contributor to a program must sign some sort of legal papers in order
|
|
|
168 for us to have clear title to the program. The main author alone is not
|
|
|
169 enough.
|
|
|
170
|
|
|
171 So, before adding in any contributions from other people, tell us
|
|
|
172 so we can arrange to get the papers. Then wait until we tell you
|
|
|
173 that we have received the signed papers, before you actually use the
|
|
|
174 contribution.
|
|
|
175
|
|
|
176 This applies both before you release the program and afterward. If
|
|
|
177 you receive diffs to fix a bug, and they make significant changes, we
|
|
|
178 need legal papers for it.
|
|
|
179
|
|
|
180 You don't need papers for changes of a few lines here or there, since
|
|
|
181 they are not significant for copyright purposes. Also, you don't need
|
|
|
182 papers if all you get from the suggestion is some ideas, not actual code
|
|
|
183 which you use. For example, if you write a different solution to the
|
|
|
184 problem, you don't need to get papers.
|
|
|
185
|
|
|
186 We know this is frustrating; it's frustrating for us as well. But if
|
|
|
187 you don't wait, you are going out on a limb---for example, what if the
|
|
|
188 contributor's employer won't sign a disclaimer? You might have to take
|
|
|
189 that code out again!
|
|
|
190
|
|
|
191 The very worst thing is if you forget to tell us about the other
|
|
|
192 contributor. We could be very embarrassed in court some day as a
|
|
|
193 result.
|
|
|
194
|
|
|
195 @node Design Advice
|
|
|
196 @chapter General Program Design
|
|
|
197
|
|
|
198 This @value{CHAPTER} discusses some of the issues you should take into
|
|
|
199 account when designing your program.
|
|
|
200
|
|
|
201 @menu
|
|
|
202 * Compatibility:: Compatibility with other implementations
|
|
|
203 * Using Extensions:: Using non-standard features
|
|
|
204 * ANSI C:: Using ANSI C features
|
|
|
205 * Source Language:: Using languages other than C
|
|
|
206 @end menu
|
|
|
207
|
|
|
208 @node Compatibility
|
|
|
209 @section Compatibility with Other Implementations
|
|
|
210
|
|
|
211 With occasional exceptions, utility programs and libraries for GNU
|
|
|
212 should be upward compatible with those in Berkeley Unix, and upward
|
|
|
213 compatible with @sc{ansi} C if @sc{ansi} C specifies their behavior, and
|
|
|
214 upward compatible with @sc{POSIX} if @sc{POSIX} specifies their
|
|
|
215 behavior.
|
|
|
216
|
|
|
217 When these standards conflict, it is useful to offer compatibility
|
|
|
218 modes for each of them.
|
|
|
219
|
|
|
220 @sc{ansi} C and @sc{POSIX} prohibit many kinds of extensions. Feel free
|
|
|
221 to make the extensions anyway, and include a @samp{--ansi},
|
|
|
222 @samp{--posix}, or @samp{--compatible} option to turn them off.
|
|
|
223 However, if the extension has a significant chance of breaking any real
|
|
|
224 programs or scripts, then it is not really upward compatible. Try to
|
|
|
225 redesign its interface.
|
|
|
226
|
|
|
227 Many GNU programs suppress extensions that conflict with POSIX if the
|
|
|
228 environment variable @code{POSIXLY_CORRECT} is defined (even if it is
|
|
|
229 defined with a null value). Please make your program recognize this
|
|
|
230 variable if appropriate.
|
|
|
231
|
|
|
232 When a feature is used only by users (not by programs or command
|
|
|
233 files), and it is done poorly in Unix, feel free to replace it
|
|
|
234 completely with something totally different and better. (For example,
|
|
|
235 @code{vi} is replaced with Emacs.) But it is nice to offer a compatible
|
|
|
236 feature as well. (There is a free @code{vi} clone, so we offer it.)
|
|
|
237
|
|
|
238 Additional useful features not in Berkeley Unix are welcome.
|
|
|
239 Additional programs with no counterpart in Unix may be useful,
|
|
|
240 but our first priority is usually to duplicate what Unix already
|
|
|
241 has.
|
|
|
242
|
|
|
243 @node Using Extensions
|
|
|
244 @section Using Non-standard Features
|
|
|
245
|
|
|
246 Many GNU facilities that already exist support a number of convenient
|
|
|
247 extensions over the comparable Unix facilities. Whether to use these
|
|
|
248 extensions in implementing your program is a difficult question.
|
|
|
249
|
|
|
250 On the one hand, using the extensions can make a cleaner program.
|
|
|
251 On the other hand, people will not be able to build the program
|
|
|
252 unless the other GNU tools are available. This might cause the
|
|
|
253 program to work on fewer kinds of machines.
|
|
|
254
|
|
|
255 With some extensions, it might be easy to provide both alternatives.
|
|
|
256 For example, you can define functions with a ``keyword'' @code{INLINE}
|
|
|
257 and define that as a macro to expand into either @code{inline} or
|
|
|
258 nothing, depending on the compiler.
|
|
|
259
|
|
|
260 In general, perhaps it is best not to use the extensions if you can
|
|
|
261 straightforwardly do without them, but to use the extensions if they
|
|
|
262 are a big improvement.
|
|
|
263
|
|
|
264 An exception to this rule are the large, established programs (such as
|
|
|
265 Emacs) which run on a great variety of systems. Such programs would
|
|
|
266 be broken by use of GNU extensions.
|
|
|
267
|
|
|
268 Another exception is for programs that are used as part of
|
|
|
269 compilation: anything that must be compiled with other compilers in
|
|
|
270 order to bootstrap the GNU compilation facilities. If these require
|
|
|
271 the GNU compiler, then no one can compile them without having them
|
|
|
272 installed already. That would be no good.
|
|
|
273
|
|
|
274 @node ANSI C
|
|
|
275 @section @sc{ansi} C and pre-@sc{ansi} C
|
|
|
276
|
|
|
277 Do not ever use the ``trigraph'' feature of @sc{ansi} C.
|
|
|
278
|
|
|
279 @sc{ansi} C is widespread enough now that it is ok to write new programs
|
|
|
280 that use @sc{ansi} C features (and therefore will not work in
|
|
|
281 non-@sc{ansi} compilers). And if a program is already written in
|
|
|
282 @sc{ansi} C, there's no need to convert it to support non-@sc{ansi}
|
|
|
283 compilers.
|
|
|
284
|
|
|
285 However, it is easy to support non-@sc{ansi} compilers in most programs,
|
|
|
286 so you might still consider doing so when you write a program. Instead
|
|
|
287 of writing function definitions in @sc{ansi} prototype form,
|
|
|
288
|
|
|
289 @example
|
|
|
290 int
|
|
|
291 foo (int x, int y)
|
|
|
292 @dots{}
|
|
|
293 @end example
|
|
|
294
|
|
|
295 @noindent
|
|
|
296 write the definition in pre-@sc{ansi} style like this,
|
|
|
297
|
|
|
298 @example
|
|
|
299 int
|
|
|
300 foo (x, y)
|
|
|
301 int x, y;
|
|
|
302 @dots{}
|
|
|
303 @end example
|
|
|
304
|
|
|
305 @noindent
|
|
|
306 and use a separate declaration to specify the argument prototype:
|
|
|
307
|
|
|
308 @example
|
|
|
309 int foo (int, int);
|
|
|
310 @end example
|
|
|
311
|
|
|
312 You need such a declaration anyway, in a header file, to get the benefit
|
|
|
313 of @sc{ansi} C prototypes in all the files where the function is called.
|
|
|
314 And once you have it, you lose nothing by writing the function
|
|
|
315 definition in the pre-@sc{ansi} style.
|
|
|
316
|
|
|
317 If you don't know non-@sc{ansi} C, there's no need to learn it; just
|
|
|
318 write in @sc{ansi} C.
|
|
|
319
|
|
|
320 @node Source Language
|
|
|
321 @section Using Languages Other Than C
|
|
|
322
|
|
|
323 Using a language other than C is like using a non-standard feature: it
|
|
|
324 will cause trouble for users. Even if GCC supports the other language,
|
|
|
325 users may find it inconvenient to have to install the compiler for that
|
|
|
326 other language in order to build your program. So please write in C.
|
|
|
327
|
|
|
328 There are three exceptions for this rule:
|
|
|
329
|
|
|
330 @itemize @bullet
|
|
|
331 @item
|
|
|
332 It is okay to use a special language if the same program contains an
|
|
|
333 interpreter for that language.
|
|
|
334
|
|
|
335 For example, if your program links with GUILE, it is ok to write part of
|
|
|
336 the program in Scheme or another language supported by GUILE.
|
|
|
337
|
|
|
338 @item
|
|
|
339 It is okay to use another language in a tool specifically intended for
|
|
|
340 use with that language.
|
|
|
341
|
|
|
342 This is okay because the only people who want to build the tool will be
|
|
|
343 those who have installed the other language anyway.
|
|
|
344
|
|
|
345 @item
|
|
|
346 If an application is not of extremely widespread interest, then perhaps
|
|
|
347 it's not important if the application is inconvenient to install.
|
|
|
348 @end itemize
|
|
|
349
|
|
|
350 @node Program Behavior
|
|
|
351 @chapter Program Behavior for All Programs
|
|
|
352
|
|
|
353 This @value{CHAPTER} describes how to write robust software. It also
|
|
|
354 describes general standards for error messages, the command line interface,
|
|
|
355 and how libraries should behave.
|
|
|
356
|
|
|
357 @menu
|
|
|
358 * Semantics:: Writing robust programs
|
|
|
359 * Libraries:: Library behavior
|
|
|
360 * Errors:: Formatting error messages
|
|
|
361 * User Interfaces:: Standards for command line interfaces
|
|
|
362 * Memory Usage:: When and how to care about memory needs
|
|
|
363 @end menu
|
|
|
364
|
|
|
365 @node Semantics
|
|
|
366 @section Writing Robust Programs
|
|
|
367
|
|
|
368 Avoid arbitrary limits on the length or number of @emph{any} data
|
|
|
369 structure, including file names, lines, files, and symbols, by allocating
|
|
|
370 all data structures dynamically. In most Unix utilities, ``long lines
|
|
|
371 are silently truncated''. This is not acceptable in a GNU utility.
|
|
|
372
|
|
|
373 Utilities reading files should not drop NUL characters, or any other
|
|
|
374 nonprinting characters @emph{including those with codes above 0177}. The
|
|
|
375 only sensible exceptions would be utilities specifically intended for
|
|
|
376 interface to certain types of printers that can't handle those characters.
|
|
|
377
|
|
|
378 Check every system call for an error return, unless you know you wish to
|
|
|
379 ignore errors. Include the system error text (from @code{perror} or
|
|
|
380 equivalent) in @emph{every} error message resulting from a failing
|
|
|
381 system call, as well as the name of the file if any and the name of the
|
|
|
382 utility. Just ``cannot open foo.c'' or ``stat failed'' is not
|
|
|
383 sufficient.
|
|
|
384
|
|
|
385 Check every call to @code{malloc} or @code{realloc} to see if it
|
|
|
386 returned zero. Check @code{realloc} even if you are making the block
|
|
|
387 smaller; in a system that rounds block sizes to a power of 2,
|
|
|
388 @code{realloc} may get a different block if you ask for less space.
|
|
|
389
|
|
|
390 In Unix, @code{realloc} can destroy the storage block if it returns
|
|
|
391 zero. GNU @code{realloc} does not have this bug: if it fails, the
|
|
|
392 original block is unchanged. Feel free to assume the bug is fixed. If
|
|
|
393 you wish to run your program on Unix, and wish to avoid lossage in this
|
|
|
394 case, you can use the GNU @code{malloc}.
|
|
|
395
|
|
|
396 You must expect @code{free} to alter the contents of the block that was
|
|
|
397 freed. Anything you want to fetch from the block, you must fetch before
|
|
|
398 calling @code{free}.
|
|
|
399
|
|
|
400 If @code{malloc} fails in a noninteractive program, make that a fatal
|
|
|
401 error. In an interactive program (one that reads commands from the
|
|
|
402 user), it is better to abort the command and return to the command
|
|
|
403 reader loop. This allows the user to kill other processes to free up
|
|
|
404 virtual memory, and then try the command again.
|
|
|
405
|
|
|
406 Use @code{getopt_long} to decode arguments, unless the argument syntax
|
|
|
407 makes this unreasonable.
|
|
|
408
|
|
|
409 When static storage is to be written in during program execution, use
|
|
|
410 explicit C code to initialize it. Reserve C initialized declarations
|
|
|
411 for data that will not be changed.
|
|
|
412 @c ADR: why?
|
|
|
413
|
|
|
414 Try to avoid low-level interfaces to obscure Unix data structures (such
|
|
|
415 as file directories, utmp, or the layout of kernel memory), since these
|
|
|
416 are less likely to work compatibly. If you need to find all the files
|
|
|
417 in a directory, use @code{readdir} or some other high-level interface.
|
|
|
418 These will be supported compatibly by GNU.
|
|
|
419
|
|
|
420 By default, the GNU system will provide the signal handling functions of
|
|
|
421 @sc{BSD} and of @sc{POSIX}. So GNU software should be written to use
|
|
|
422 these.
|
|
|
423
|
|
|
424 In error checks that detect ``impossible'' conditions, just abort.
|
|
|
425 There is usually no point in printing any message. These checks
|
|
|
426 indicate the existence of bugs. Whoever wants to fix the bugs will have
|
|
|
427 to read the source code and run a debugger. So explain the problem with
|
|
|
428 comments in the source. The relevant data will be in variables, which
|
|
|
429 are easy to examine with the debugger, so there is no point moving them
|
|
|
430 elsewhere.
|
|
|
431
|
|
|
432 Do not use a count of errors as the exit status for a program.
|
|
|
433 @emph{That does not work}, because exit status values are limited to 8
|
|
|
434 bits (0 through 255). A single run of the program might have 256
|
|
|
435 errors; if you try to return 256 as the exit status, the parent process
|
|
|
436 will see 0 as the status, and it will appear that the program succeeded.
|
|
|
437
|
|
|
438 If you make temporary files, check the @code{TMPDIR} environment
|
|
|
439 variable; if that variable is defined, use the specified directory
|
|
|
440 instead of @file{/tmp}.
|
|
|
441
|
|
|
442 @node Libraries
|
|
|
443 @section Library Behavior
|
|
|
444
|
|
|
445 Try to make library functions reentrant. If they need to do dynamic
|
|
|
446 storage allocation, at least try to avoid any nonreentrancy aside from
|
|
|
447 that of @code{malloc} itself.
|
|
|
448
|
|
|
449 Here are certain name conventions for libraries, to avoid name
|
|
|
450 conflicts.
|
|
|
451
|
|
|
452 Choose a name prefix for the library, more than two characters long.
|
|
|
453 All external function and variable names should start with this
|
|
|
454 prefix. In addition, there should only be one of these in any given
|
|
|
455 library member. This usually means putting each one in a separate
|
|
|
456 source file.
|
|
|
457
|
|
|
458 An exception can be made when two external symbols are always used
|
|
|
459 together, so that no reasonable program could use one without the
|
|
|
460 other; then they can both go in the same file.
|
|
|
461
|
|
|
462 External symbols that are not documented entry points for the user
|
|
|
463 should have names beginning with @samp{_}. They should also contain
|
|
|
464 the chosen name prefix for the library, to prevent collisions with
|
|
|
465 other libraries. These can go in the same files with user entry
|
|
|
466 points if you like.
|
|
|
467
|
|
|
468 Static functions and variables can be used as you like and need not
|
|
|
469 fit any naming convention.
|
|
|
470
|
|
|
471 @node Errors
|
|
|
472 @section Formatting Error Messages
|
|
|
473
|
|
|
474 Error messages from compilers should look like this:
|
|
|
475
|
|
|
476 @example
|
|
|
477 @var{source-file-name}:@var{lineno}: @var{message}
|
|
|
478 @end example
|
|
|
479
|
|
|
480 Error messages from other noninteractive programs should look like this:
|
|
|
481
|
|
|
482 @example
|
|
|
483 @var{program}:@var{source-file-name}:@var{lineno}: @var{message}
|
|
|
484 @end example
|
|
|
485
|
|
|
486 @noindent
|
|
|
487 when there is an appropriate source file, or like this:
|
|
|
488
|
|
|
489 @example
|
|
|
490 @var{program}: @var{message}
|
|
|
491 @end example
|
|
|
492
|
|
|
493 @noindent
|
|
|
494 when there is no relevant source file.
|
|
|
495
|
|
|
496 In an interactive program (one that is reading commands from a
|
|
|
497 terminal), it is better not to include the program name in an error
|
|
|
498 message. The place to indicate which program is running is in the
|
|
|
499 prompt or with the screen layout. (When the same program runs with
|
|
|
500 input from a source other than a terminal, it is not interactive and
|
|
|
501 would do best to print error messages using the noninteractive style.)
|
|
|
502
|
|
|
503 The string @var{message} should not begin with a capital letter when
|
|
|
504 it follows a program name and/or file name. Also, it should not end
|
|
|
505 with a period.
|
|
|
506
|
|
|
507 Error messages from interactive programs, and other messages such as
|
|
|
508 usage messages, should start with a capital letter. But they should not
|
|
|
509 end with a period.
|
|
|
510
|
|
|
511 @node User Interfaces
|
|
|
512 @section Standards for Command Line Interfaces
|
|
|
513
|
|
|
514 Please don't make the behavior of a utility depend on the name used
|
|
|
515 to invoke it. It is useful sometimes to make a link to a utility
|
|
|
516 with a different name, and that should not change what it does.
|
|
|
517
|
|
|
518 Instead, use a run time option or a compilation switch or both
|
|
|
519 to select among the alternate behaviors.
|
|
|
520
|
|
|
521 Likewise, please don't make the behavior of the program depend on the
|
|
|
522 type of output device it is used with. Device independence is an
|
|
|
523 important principle of the system's design; do not compromise it
|
|
|
524 merely to save someone from typing an option now and then.
|
|
|
525
|
|
|
526 If you think one behavior is most useful when the output is to a
|
|
|
527 terminal, and another is most useful when the output is a file or a
|
|
|
528 pipe, then it is usually best to make the default behavior the one that
|
|
|
529 is useful with output to a terminal, and have an option for the other
|
|
|
530 behavior.
|
|
|
531
|
|
|
532 Compatibility requires certain programs to depend on the type of output
|
|
|
533 device. It would be disastrous if @code{ls} or @code{sh} did not do so
|
|
|
534 in the way all users expect. In some of these cases, we supplement the
|
|
|
535 program with a preferred alternate version that does not depend on the
|
|
|
536 output device type. For example, we provide a @code{dir} program much
|
|
|
537 like @code{ls} except that its default output format is always
|
|
|
538 multi-column format.
|
|
|
539
|
|
|
540 It is a good idea to follow the @sc{POSIX} guidelines for the
|
|
|
541 command-line options of a program. The easiest way to do this is to use
|
|
|
542 @code{getopt} to parse them. Note that the GNU version of @code{getopt}
|
|
|
543 will normally permit options anywhere among the arguments unless the
|
|
|
544 special argument @samp{--} is used. This is not what @sc{POSIX}
|
|
|
545 specifies; it is a GNU extension.
|
|
|
546
|
|
|
547 Please define long-named options that are equivalent to the
|
|
|
548 single-letter Unix-style options. We hope to make GNU more user
|
|
|
549 friendly this way. This is easy to do with the GNU function
|
|
|
550 @code{getopt_long}.
|
|
|
551
|
|
|
552 One of the advantages of long-named options is that they can be
|
|
|
553 consistent from program to program. For example, users should be able
|
|
|
554 to expect the ``verbose'' option of any GNU program which has one, to be
|
|
|
555 spelled precisely @samp{--verbose}. To achieve this uniformity, look at
|
|
|
556 the table of common long-option names when you choose the option names
|
|
|
557 for your program. The table appears below.
|
|
|
558
|
|
|
559 If you use names not already in the table, please send
|
|
|
560 @samp{gnu@@prep.ai.mit.edu} a list of them, with their meanings, so we
|
|
|
561 can update the table.
|
|
|
562
|
|
|
563 It is usually a good idea for file names given as ordinary arguments
|
|
|
564 to be input files only; any output files would be specified using
|
|
|
565 options (preferably @samp{-o}). Even if you allow an output file name
|
|
|
566 as an ordinary argument for compatibility, try to provide a suitable
|
|
|
567 option as well. This will lead to more consistency among GNU
|
|
363
|
568 utilities, so that there are fewer idiosyncrasies for users to
|
|
0
|
569 remember.
|
|
|
570
|
|
|
571 Programs should support an option @samp{--version} which prints the
|
|
|
572 program's version number on standard output and exits successfully, and
|
|
|
573 an option @samp{--help} which prints option usage information on
|
|
|
574 standard output and exits successfully. These options should inhibit
|
|
|
575 the normal function of the command; they should do nothing except print
|
|
|
576 the requested information.
|
|
|
577
|
|
|
578 @c Please leave newlines between items in this table; it's much easier
|
|
|
579 @c to update when it isn't completely squashed together and unreadable.
|
|
|
580 @c When there is more than one short option for a long option name, put
|
|
|
581 @c a semicolon between the lists of the programs that use them, not a
|
|
|
582 @c period. --friedman
|
|
|
583
|
|
|
584 Here is the table of long options used by GNU programs.
|
|
|
585
|
|
|
586 @table @samp
|
|
|
587
|
|
|
588 @item after-date
|
|
|
589 @samp{-N} in @code{tar}.
|
|
|
590
|
|
|
591 @item all
|
|
|
592 @samp{-a} in @code{du}, @code{ls}, @code{nm}, @code{stty}, @code{uname},
|
|
|
593 and @code{unexpand}.
|
|
|
594
|
|
|
595 @item all-text
|
|
|
596 @samp{-a} in @code{diff}.
|
|
|
597
|
|
|
598 @item almost-all
|
|
|
599 @samp{-A} in @code{ls}.
|
|
|
600
|
|
|
601 @item append
|
|
|
602 @samp{-a} in @code{etags}, @code{tee}, @code{time};
|
|
|
603 @samp{-r} in @code{tar}.
|
|
|
604
|
|
|
605 @item archive
|
|
|
606 @samp{-a} in @code{cp}.
|
|
|
607
|
|
|
608 @item archive-name
|
|
|
609 @samp{-n} in @code{shar}.
|
|
|
610
|
|
|
611 @item arglength
|
|
|
612 @samp{-l} in @code{m4}.
|
|
|
613
|
|
|
614 @item ascii
|
|
|
615 @samp{-a} in @code{diff}.
|
|
|
616
|
|
|
617 @item assign
|
|
|
618 @samp{-v} in @code{gawk}.
|
|
|
619
|
|
|
620 @item assume-new
|
|
|
621 @samp{-W} in Make.
|
|
|
622
|
|
|
623 @item assume-old
|
|
|
624 @samp{-o} in Make.
|
|
|
625
|
|
|
626 @item auto-check
|
|
|
627 @samp{-a} in @code{recode}.
|
|
|
628
|
|
|
629 @item auto-pager
|
|
|
630 @samp{-a} in @code{wdiff}.
|
|
|
631
|
|
|
632 @item auto-reference
|
|
|
633 @samp{-A} in @code{ptx}.
|
|
|
634
|
|
|
635 @item avoid-wraps
|
|
|
636 @samp{-n} in @code{wdiff}.
|
|
|
637
|
|
|
638 @item backward-search
|
|
|
639 @samp{-B} in @code{ctags}.
|
|
|
640
|
|
|
641 @item basename
|
|
|
642 @samp{-f} in @code{shar}.
|
|
|
643
|
|
|
644 @item batch
|
|
|
645 Used in GDB.
|
|
|
646
|
|
|
647 @item baud
|
|
|
648 Used in GDB.
|
|
|
649
|
|
|
650 @item before
|
|
|
651 @samp{-b} in @code{tac}.
|
|
|
652
|
|
|
653 @item binary
|
|
|
654 @samp{-b} in @code{cpio} and @code{diff}.
|
|
|
655
|
|
|
656 @item bits-per-code
|
|
|
657 @samp{-b} in @code{shar}.
|
|
|
658
|
|
|
659 @item block-size
|
|
|
660 Used in @code{cpio} and @code{tar}.
|
|
|
661
|
|
|
662 @item blocks
|
|
|
663 @samp{-b} in @code{head} and @code{tail}.
|
|
|
664
|
|
|
665 @item break-file
|
|
|
666 @samp{-b} in @code{ptx}.
|
|
|
667
|
|
|
668 @item brief
|
|
|
669 Used in various programs to make output shorter.
|
|
|
670
|
|
|
671 @item bytes
|
|
|
672 @samp{-c} in @code{head}, @code{split}, and @code{tail}.
|
|
|
673
|
|
|
674 @item c@t{++}
|
|
|
675 @samp{-C} in @code{etags}.
|
|
|
676
|
|
|
677 @item catenate
|
|
|
678 @samp{-A} in @code{tar}.
|
|
|
679
|
|
|
680 @item cd
|
|
|
681 Used in various programs to specify the directory to use.
|
|
|
682
|
|
|
683 @item changes
|
|
|
684 @samp{-c} in @code{chgrp} and @code{chown}.
|
|
|
685
|
|
|
686 @item classify
|
|
|
687 @samp{-F} in @code{ls}.
|
|
|
688
|
|
|
689 @item colons
|
|
|
690 @samp{-c} in @code{recode}.
|
|
|
691
|
|
|
692 @item command
|
|
|
693 @samp{-c} in @code{su};
|
|
|
694 @samp{-x} in GDB.
|
|
|
695
|
|
|
696 @item compare
|
|
|
697 @samp{-d} in @code{tar}.
|
|
|
698
|
|
|
699 @item compat
|
|
|
700 Used in @code{gawk}.
|
|
|
701
|
|
|
702 @item compress
|
|
|
703 @samp{-Z} in @code{tar} and @code{shar}.
|
|
|
704
|
|
|
705 @item concatenate
|
|
|
706 @samp{-A} in @code{tar}.
|
|
|
707
|
|
|
708 @item confirmation
|
|
|
709 @samp{-w} in @code{tar}.
|
|
|
710
|
|
|
711 @item context
|
|
|
712 Used in @code{diff}.
|
|
|
713
|
|
|
714 @item copyleft
|
|
|
715 @samp{-W copyleft} in @code{gawk}.
|
|
|
716
|
|
|
717 @item copyright
|
|
|
718 @samp{-C} in @code{ptx}, @code{recode}, and @code{wdiff};
|
|
|
719 @samp{-W copyright} in @code{gawk}.
|
|
|
720
|
|
|
721 @item core
|
|
|
722 Used in GDB.
|
|
|
723
|
|
|
724 @item count
|
|
|
725 @samp{-q} in @code{who}.
|
|
|
726
|
|
|
727 @item count-links
|
|
|
728 @samp{-l} in @code{du}.
|
|
|
729
|
|
|
730 @item create
|
|
|
731 Used in @code{tar} and @code{cpio}.
|
|
|
732
|
|
|
733 @item cut-mark
|
|
|
734 @samp{-c} in @code{shar}.
|
|
|
735
|
|
|
736 @item cxref
|
|
|
737 @samp{-x} in @code{ctags}.
|
|
|
738
|
|
|
739 @item date
|
|
|
740 @samp{-d} in @code{touch}.
|
|
|
741
|
|
|
742 @item debug
|
|
|
743 @samp{-d} in Make and @code{m4};
|
|
|
744 @samp{-t} in Bison.
|
|
|
745
|
|
|
746 @item define
|
|
|
747 @samp{-D} in @code{m4}.
|
|
|
748
|
|
|
749 @item defines
|
|
|
750 @samp{-d} in Bison and @code{ctags}.
|
|
|
751
|
|
|
752 @item delete
|
|
|
753 @samp{-D} in @code{tar}.
|
|
|
754
|
|
|
755 @item dereference
|
|
|
756 @samp{-L} in @code{chgrp}, @code{chown}, @code{cpio}, @code{du},
|
|
|
757 @code{ls}, and @code{tar}.
|
|
|
758
|
|
|
759 @item dereference-args
|
|
|
760 @samp{-D} in @code{du}.
|
|
|
761
|
|
|
762 @item diacritics
|
|
|
763 @samp{-d} in @code{recode}.
|
|
|
764
|
|
|
765 @item dictionary-order
|
|
|
766 @samp{-d} in @code{look}.
|
|
|
767
|
|
|
768 @item diff
|
|
|
769 @samp{-d} in @code{tar}.
|
|
|
770
|
|
|
771 @item digits
|
|
|
772 @samp{-n} in @code{csplit}.
|
|
|
773
|
|
|
774 @item directory
|
|
|
775 Specify the directory to use, in various programs. In @code{ls}, it
|
|
|
776 means to show directories themselves rather than their contents. In
|
|
|
777 @code{rm} and @code{ln}, it means to not treat links to directories
|
|
|
778 specially.
|
|
|
779
|
|
|
780 @item discard-all
|
|
|
781 @samp{-x} in @code{strip}.
|
|
|
782
|
|
|
783 @item discard-locals
|
|
|
784 @samp{-X} in @code{strip}.
|
|
|
785
|
|
|
786 @item dry-run
|
|
|
787 @samp{-n} in Make.
|
|
|
788
|
|
|
789 @item ed
|
|
|
790 @samp{-e} in @code{diff}.
|
|
|
791
|
|
|
792 @item elide-empty-files
|
|
|
793 @samp{-z} in @code{csplit}.
|
|
|
794
|
|
|
795 @item end-delete
|
|
|
796 @samp{-x} in @code{wdiff}.
|
|
|
797
|
|
|
798 @item end-insert
|
|
|
799 @samp{-z} in @code{wdiff}.
|
|
|
800
|
|
|
801 @item entire-new-file
|
|
|
802 @samp{-N} in @code{diff}.
|
|
|
803
|
|
|
804 @item environment-overrides
|
|
|
805 @samp{-e} in Make.
|
|
|
806
|
|
|
807 @item eof
|
|
|
808 @samp{-e} in @code{xargs}.
|
|
|
809
|
|
|
810 @item epoch
|
|
|
811 Used in GDB.
|
|
|
812
|
|
|
813 @item error-limit
|
|
|
814 Used in @code{makeinfo}.
|
|
|
815
|
|
|
816 @item error-output
|
|
|
817 @samp{-o} in @code{m4}.
|
|
|
818
|
|
|
819 @item escape
|
|
|
820 @samp{-b} in @code{ls}.
|
|
|
821
|
|
|
822 @item exclude-from
|
|
|
823 @samp{-X} in @code{tar}.
|
|
|
824
|
|
|
825 @item exec
|
|
|
826 Used in GDB.
|
|
|
827
|
|
|
828 @item exit
|
|
|
829 @samp{-x} in @code{xargs}.
|
|
|
830
|
|
|
831 @item exit-0
|
|
|
832 @samp{-e} in @code{unshar}.
|
|
|
833
|
|
|
834 @item expand-tabs
|
|
|
835 @samp{-t} in @code{diff}.
|
|
|
836
|
|
|
837 @item expression
|
|
|
838 @samp{-e} in @code{sed}.
|
|
|
839
|
|
|
840 @item extern-only
|
|
|
841 @samp{-g} in @code{nm}.
|
|
|
842
|
|
|
843 @item extract
|
|
|
844 @samp{-i} in @code{cpio};
|
|
|
845 @samp{-x} in @code{tar}.
|
|
|
846
|
|
|
847 @item faces
|
|
|
848 @samp{-f} in @code{finger}.
|
|
|
849
|
|
|
850 @item fast
|
|
|
851 @samp{-f} in @code{su}.
|
|
|
852
|
|
|
853 @item fatal-warnings
|
|
|
854 @samp{-E} in @code{m4}.
|
|
|
855
|
|
|
856 @item file
|
|
|
857 @samp{-f} in @code{info}, @code{gawk}, Make, @code{mt}, and @code{tar};
|
|
|
858 @samp{-n} in @code{sed};
|
|
|
859 @samp{-r} in @code{touch}.
|
|
|
860
|
|
|
861 @item field-separator
|
|
|
862 @samp{-F} in @code{gawk}.
|
|
|
863
|
|
|
864 @item file-prefix
|
|
|
865 @samp{-b} in Bison.
|
|
|
866
|
|
|
867 @item file-type
|
|
|
868 @samp{-F} in @code{ls}.
|
|
|
869
|
|
|
870 @item files-from
|
|
|
871 @samp{-T} in @code{tar}.
|
|
|
872
|
|
|
873 @item fill-column
|
|
|
874 Used in @code{makeinfo}.
|
|
|
875
|
|
|
876 @item flag-truncation
|
|
|
877 @samp{-F} in @code{ptx}.
|
|
|
878
|
|
|
879 @item fixed-output-files
|
|
|
880 @samp{-y} in Bison.
|
|
|
881
|
|
|
882 @item follow
|
|
|
883 @samp{-f} in @code{tail}.
|
|
|
884
|
|
|
885 @item footnote-style
|
|
|
886 Used in @code{makeinfo}.
|
|
|
887
|
|
|
888 @item force
|
|
|
889 @samp{-f} in @code{cp}, @code{ln}, @code{mv}, and @code{rm}.
|
|
|
890
|
|
|
891 @item force-prefix
|
|
|
892 @samp{-F} in @code{shar}.
|
|
|
893
|
|
|
894 @item format
|
|
|
895 Used in @code{ls}, @code{time}, and @code{ptx}.
|
|
|
896
|
|
|
897 @item freeze-state
|
|
|
898 @samp{-F} in @code{m4}.
|
|
|
899
|
|
|
900 @item fullname
|
|
|
901 Used in GDB.
|
|
|
902
|
|
|
903 @item gap-size
|
|
|
904 @samp{-g} in @code{ptx}.
|
|
|
905
|
|
|
906 @item get
|
|
|
907 @samp{-x} in @code{tar}.
|
|
|
908
|
|
|
909 @item graphic
|
|
|
910 @samp{-i} in @code{ul}.
|
|
|
911
|
|
|
912 @item graphics
|
|
|
913 @samp{-g} in @code{recode}.
|
|
|
914
|
|
|
915 @item group
|
|
|
916 @samp{-g} in @code{install}.
|
|
|
917
|
|
|
918 @item gzip
|
|
|
919 @samp{-z} in @code{tar} and @code{shar}.
|
|
|
920
|
|
|
921 @item hashsize
|
|
|
922 @samp{-H} in @code{m4}.
|
|
|
923
|
|
|
924 @item header
|
|
|
925 @samp{-h} in @code{objdump} and @code{recode}
|
|
|
926
|
|
|
927 @item heading
|
|
|
928 @samp{-H} in @code{who}.
|
|
|
929
|
|
|
930 @item help
|
|
|
931 Used to ask for brief usage information.
|
|
|
932
|
|
|
933 @item here-delimiter
|
|
|
934 @samp{-d} in @code{shar}.
|
|
|
935
|
|
|
936 @item hide-control-chars
|
|
|
937 @samp{-q} in @code{ls}.
|
|
|
938
|
|
|
939 @item idle
|
|
|
940 @samp{-u} in @code{who}.
|
|
|
941
|
|
|
942 @item ifdef
|
|
|
943 @samp{-D} in @code{diff}.
|
|
|
944
|
|
|
945 @item ignore
|
|
|
946 @samp{-I} in @code{ls};
|
|
|
947 @samp{-x} in @code{recode}.
|
|
|
948
|
|
|
949 @item ignore-all-space
|
|
|
950 @samp{-w} in @code{diff}.
|
|
|
951
|
|
|
952 @item ignore-backups
|
|
|
953 @samp{-B} in @code{ls}.
|
|
|
954
|
|
|
955 @item ignore-blank-lines
|
|
|
956 @samp{-B} in @code{diff}.
|
|
|
957
|
|
|
958 @item ignore-case
|
|
|
959 @samp{-f} in @code{look} and @code{ptx};
|
|
|
960 @samp{-i} in @code{diff} and @code{wdiff}.
|
|
|
961
|
|
|
962 @item ignore-errors
|
|
|
963 @samp{-i} in Make.
|
|
|
964
|
|
|
965 @item ignore-file
|
|
|
966 @samp{-i} in @code{ptx}.
|
|
|
967
|
|
|
968 @item ignore-indentation
|
|
|
969 @samp{-I} in @code{etags}.
|
|
|
970
|
|
|
971 @item ignore-init-file
|
|
|
972 @samp{-f} in Oleo.
|
|
|
973
|
|
|
974 @item ignore-interrupts
|
|
|
975 @samp{-i} in @code{tee}.
|
|
|
976
|
|
|
977 @item ignore-matching-lines
|
|
|
978 @samp{-I} in @code{diff}.
|
|
|
979
|
|
|
980 @item ignore-space-change
|
|
|
981 @samp{-b} in @code{diff}.
|
|
|
982
|
|
|
983 @item ignore-zeros
|
|
|
984 @samp{-i} in @code{tar}.
|
|
|
985
|
|
|
986 @item include
|
|
|
987 @samp{-i} in @code{etags};
|
|
|
988 @samp{-I} in @code{m4}.
|
|
|
989
|
|
|
990 @item include-dir
|
|
|
991 @samp{-I} in Make.
|
|
|
992
|
|
|
993 @item incremental
|
|
|
994 @samp{-G} in @code{tar}.
|
|
|
995
|
|
|
996 @item info
|
|
|
997 @samp{-i}, @samp{-l}, and @samp{-m} in Finger.
|
|
|
998
|
|
|
999 @item initial
|
|
|
1000 @samp{-i} in @code{expand}.
|
|
|
1001
|
|
|
1002 @item initial-tab
|
|
|
1003 @samp{-T} in @code{diff}.
|
|
|
1004
|
|
|
1005 @item inode
|
|
|
1006 @samp{-i} in @code{ls}.
|
|
|
1007
|
|
|
1008 @item interactive
|
|
|
1009 @samp{-i} in @code{cp}, @code{ln}, @code{mv}, @code{rm};
|
|
|
1010 @samp{-e} in @code{m4};
|
|
|
1011 @samp{-p} in @code{xargs};
|
|
|
1012 @samp{-w} in @code{tar}.
|
|
|
1013
|
|
|
1014 @item intermix-type
|
|
|
1015 @samp{-p} in @code{shar}.
|
|
|
1016
|
|
|
1017 @item jobs
|
|
|
1018 @samp{-j} in Make.
|
|
|
1019
|
|
|
1020 @item just-print
|
|
|
1021 @samp{-n} in Make.
|
|
|
1022
|
|
|
1023 @item keep-going
|
|
|
1024 @samp{-k} in Make.
|
|
|
1025
|
|
|
1026 @item keep-files
|
|
|
1027 @samp{-k} in @code{csplit}.
|
|
|
1028
|
|
|
1029 @item kilobytes
|
|
|
1030 @samp{-k} in @code{du} and @code{ls}.
|
|
|
1031
|
|
|
1032 @item language
|
|
|
1033 @samp{-l} in @code{etags}.
|
|
|
1034
|
|
|
1035 @item less-mode
|
|
|
1036 @samp{-l} in @code{wdiff}.
|
|
|
1037
|
|
|
1038 @item level-for-gzip
|
|
|
1039 @samp{-g} in @code{shar}.
|
|
|
1040
|
|
|
1041 @item line-bytes
|
|
|
1042 @samp{-C} in @code{split}.
|
|
|
1043
|
|
|
1044 @item lines
|
|
|
1045 Used in @code{split}, @code{head}, and @code{tail}.
|
|
|
1046
|
|
|
1047 @item link
|
|
|
1048 @samp{-l} in @code{cpio}.
|
|
|
1049
|
|
|
1050 @item lint
|
|
|
1051 @itemx lint-old
|
|
|
1052 Used in @code{gawk}.
|
|
|
1053
|
|
|
1054 @item list
|
|
|
1055 @samp{-t} in @code{cpio};
|
|
|
1056 @samp{-l} in @code{recode}.
|
|
|
1057
|
|
|
1058 @item list
|
|
|
1059 @samp{-t} in @code{tar}.
|
|
|
1060
|
|
|
1061 @item literal
|
|
|
1062 @samp{-N} in @code{ls}.
|
|
|
1063
|
|
|
1064 @item load-average
|
|
|
1065 @samp{-l} in Make.
|
|
|
1066
|
|
|
1067 @item login
|
|
|
1068 Used in @code{su}.
|
|
|
1069
|
|
|
1070 @item machine
|
|
|
1071 No listing of which programs already use this;
|
|
|
1072 someone should check to
|
|
|
1073 see if any actually do and tell @code{gnu@@prep.ai.mit.edu}.
|
|
|
1074
|
|
|
1075 @item macro-name
|
|
|
1076 @samp{-M} in @code{ptx}.
|
|
|
1077
|
|
|
1078 @item mail
|
|
|
1079 @samp{-m} in @code{hello} and @code{uname}.
|
|
|
1080
|
|
|
1081 @item make-directories
|
|
|
1082 @samp{-d} in @code{cpio}.
|
|
|
1083
|
|
|
1084 @item makefile
|
|
|
1085 @samp{-f} in Make.
|
|
|
1086
|
|
|
1087 @item mapped
|
|
|
1088 Used in GDB.
|
|
|
1089
|
|
|
1090 @item max-args
|
|
|
1091 @samp{-n} in @code{xargs}.
|
|
|
1092
|
|
|
1093 @item max-chars
|
|
|
1094 @samp{-n} in @code{xargs}.
|
|
|
1095
|
|
|
1096 @item max-lines
|
|
|
1097 @samp{-l} in @code{xargs}.
|
|
|
1098
|
|
|
1099 @item max-load
|
|
|
1100 @samp{-l} in Make.
|
|
|
1101
|
|
|
1102 @item max-procs
|
|
|
1103 @samp{-P} in @code{xargs}.
|
|
|
1104
|
|
|
1105 @item mesg
|
|
|
1106 @samp{-T} in @code{who}.
|
|
|
1107
|
|
|
1108 @item message
|
|
|
1109 @samp{-T} in @code{who}.
|
|
|
1110
|
|
|
1111 @item minimal
|
|
|
1112 @samp{-d} in @code{diff}.
|
|
|
1113
|
|
|
1114 @item mixed-uuencode
|
|
|
1115 @samp{-M} in @code{shar}.
|
|
|
1116
|
|
|
1117 @item mode
|
|
|
1118 @samp{-m} in @code{install}, @code{mkdir}, and @code{mkfifo}.
|
|
|
1119
|
|
|
1120 @item modification-time
|
|
|
1121 @samp{-m} in @code{tar}.
|
|
|
1122
|
|
|
1123 @item multi-volume
|
|
|
1124 @samp{-M} in @code{tar}.
|
|
|
1125
|
|
|
1126 @item name-prefix
|
|
|
1127 @samp{-a} in Bison.
|
|
|
1128
|
|
|
1129 @item nesting-limit
|
|
|
1130 @samp{-L} in @code{m4}.
|
|
|
1131
|
|
|
1132 @item net-headers
|
|
|
1133 @samp{-a} in @code{shar}.
|
|
|
1134
|
|
|
1135 @item new-file
|
|
|
1136 @samp{-W} in Make.
|
|
|
1137
|
|
|
1138 @item no-builtin-rules
|
|
|
1139 @samp{-r} in Make.
|
|
|
1140
|
|
|
1141 @item no-character-count
|
|
|
1142 @samp{-w} in @code{shar}.
|
|
|
1143
|
|
|
1144 @item no-check-existing
|
|
|
1145 @samp{-x} in @code{shar}.
|
|
|
1146
|
|
|
1147 @item no-common
|
|
|
1148 @samp{-3} in @code{wdiff}.
|
|
|
1149
|
|
|
1150 @item no-create
|
|
|
1151 @samp{-c} in @code{touch}.
|
|
|
1152
|
|
|
1153 @item no-defines
|
|
|
1154 @samp{-D} in @code{etags}.
|
|
|
1155
|
|
|
1156 @item no-deleted
|
|
|
1157 @samp{-1} in @code{wdiff}.
|
|
|
1158
|
|
|
1159 @item no-dereference
|
|
|
1160 @samp{-d} in @code{cp}.
|
|
|
1161
|
|
|
1162 @item no-inserted
|
|
|
1163 @samp{-2} in @code{wdiff}.
|
|
|
1164
|
|
|
1165 @item no-keep-going
|
|
|
1166 @samp{-S} in Make.
|
|
|
1167
|
|
|
1168 @item no-lines
|
|
|
1169 @samp{-l} in Bison.
|
|
|
1170
|
|
|
1171 @item no-piping
|
|
|
1172 @samp{-P} in @code{shar}.
|
|
|
1173
|
|
|
1174 @item no-prof
|
|
|
1175 @samp{-e} in @code{gprof}.
|
|
|
1176
|
|
|
1177 @item no-regex
|
|
|
1178 @samp{-R} in @code{etags}.
|
|
|
1179
|
|
|
1180 @item no-sort
|
|
|
1181 @samp{-p} in @code{nm}.
|
|
|
1182
|
|
|
1183 @item no-split
|
|
|
1184 Used in @code{makeinfo}.
|
|
|
1185
|
|
|
1186 @item no-static
|
|
|
1187 @samp{-a} in @code{gprof}.
|
|
|
1188
|
|
|
1189 @item no-time
|
|
|
1190 @samp{-E} in @code{gprof}.
|
|
|
1191
|
|
|
1192 @item no-timestamp
|
|
|
1193 @samp{-m} in @code{shar}.
|
|
|
1194
|
|
|
1195 @item no-validate
|
|
|
1196 Used in @code{makeinfo}.
|
|
|
1197
|
|
|
1198 @item no-warn
|
|
|
1199 Used in various programs to inhibit warnings.
|
|
|
1200
|
|
|
1201 @item node
|
|
|
1202 @samp{-n} in @code{info}.
|
|
|
1203
|
|
|
1204 @item nodename
|
|
|
1205 @samp{-n} in @code{uname}.
|
|
|
1206
|
|
|
1207 @item nonmatching
|
|
|
1208 @samp{-f} in @code{cpio}.
|
|
|
1209
|
|
|
1210 @item nstuff
|
|
|
1211 @samp{-n} in @code{objdump}.
|
|
|
1212
|
|
|
1213 @item null
|
|
|
1214 @samp{-0} in @code{xargs}.
|
|
|
1215
|
|
|
1216 @item number
|
|
|
1217 @samp{-n} in @code{cat}.
|
|
|
1218
|
|
|
1219 @item number-nonblank
|
|
|
1220 @samp{-b} in @code{cat}.
|
|
|
1221
|
|
|
1222 @item numeric-sort
|
|
|
1223 @samp{-n} in @code{nm}.
|
|
|
1224
|
|
|
1225 @item numeric-uid-gid
|
|
|
1226 @samp{-n} in @code{cpio} and @code{ls}.
|
|
|
1227
|
|
|
1228 @item nx
|
|
|
1229 Used in GDB.
|
|
|
1230
|
|
|
1231 @item old-archive
|
|
|
1232 @samp{-o} in @code{tar}.
|
|
|
1233
|
|
|
1234 @item old-file
|
|
|
1235 @samp{-o} in Make.
|
|
|
1236
|
|
|
1237 @item one-file-system
|
|
|
1238 @samp{-l} in @code{tar}, @code{cp}, and @code{du}.
|
|
|
1239
|
|
|
1240 @item only-file
|
|
|
1241 @samp{-o} in @code{ptx}.
|
|
|
1242
|
|
|
1243 @item only-prof
|
|
|
1244 @samp{-f} in @code{gprof}.
|
|
|
1245
|
|
|
1246 @item only-time
|
|
|
1247 @samp{-F} in @code{gprof}.
|
|
|
1248
|
|
|
1249 @item output
|
|
|
1250 In various programs, specify the output file name.
|
|
|
1251
|
|
|
1252 @item output-prefix
|
|
|
1253 @samp{-o} in @code{shar}.
|
|
|
1254
|
|
|
1255 @item override
|
|
|
1256 @samp{-o} in @code{rm}.
|
|
|
1257
|
|
|
1258 @item overwrite
|
|
|
1259 @samp{-c} in @code{unshar}.
|
|
|
1260
|
|
|
1261 @item owner
|
|
|
1262 @samp{-o} in @code{install}.
|
|
|
1263
|
|
|
1264 @item paginate
|
|
|
1265 @samp{-l} in @code{diff}.
|
|
|
1266
|
|
|
1267 @item paragraph-indent
|
|
|
1268 Used in @code{makeinfo}.
|
|
|
1269
|
|
|
1270 @item parents
|
|
|
1271 @samp{-p} in @code{mkdir} and @code{rmdir}.
|
|
|
1272
|
|
|
1273 @item pass-all
|
|
|
1274 @samp{-p} in @code{ul}.
|
|
|
1275
|
|
|
1276 @item pass-through
|
|
|
1277 @samp{-p} in @code{cpio}.
|
|
|
1278
|
|
|
1279 @item port
|
|
|
1280 @samp{-P} in @code{finger}.
|
|
|
1281
|
|
|
1282 @item portability
|
|
|
1283 @samp{-c} in @code{cpio} and @code{tar}.
|
|
|
1284
|
|
|
1285 @item posix
|
|
|
1286 Used in @code{gawk}.
|
|
|
1287
|
|
|
1288 @item prefix-builtins
|
|
|
1289 @samp{-P} in @code{m4}.
|
|
|
1290
|
|
|
1291 @item prefix
|
|
|
1292 @samp{-f} in @code{csplit}.
|
|
|
1293
|
|
|
1294 @item preserve
|
|
|
1295 Used in @code{tar} and @code{cp}.
|
|
|
1296
|
|
|
1297 @item preserve-environment
|
|
|
1298 @samp{-p} in @code{su}.
|
|
|
1299
|
|
|
1300 @item preserve-modification-time
|
|
|
1301 @samp{-m} in @code{cpio}.
|
|
|
1302
|
|
|
1303 @item preserve-order
|
|
|
1304 @samp{-s} in @code{tar}.
|
|
|
1305
|
|
|
1306 @item preserve-permissions
|
|
|
1307 @samp{-p} in @code{tar}.
|
|
|
1308
|
|
|
1309 @item print
|
|
|
1310 @samp{-l} in @code{diff}.
|
|
|
1311
|
|
|
1312 @item print-chars
|
|
|
1313 @samp{-L} in @code{cmp}.
|
|
|
1314
|
|
|
1315 @item print-data-base
|
|
|
1316 @samp{-p} in Make.
|
|
|
1317
|
|
|
1318 @item print-directory
|
|
|
1319 @samp{-w} in Make.
|
|
|
1320
|
|
|
1321 @item print-file-name
|
|
|
1322 @samp{-o} in @code{nm}.
|
|
|
1323
|
|
|
1324 @item print-symdefs
|
|
|
1325 @samp{-s} in @code{nm}.
|
|
|
1326
|
|
|
1327 @item printer
|
|
|
1328 @samp{-p} in @code{wdiff}.
|
|
|
1329
|
|
|
1330 @item prompt
|
|
|
1331 @samp{-p} in @code{ed}.
|
|
|
1332
|
|
|
1333 @item query-user
|
|
|
1334 @samp{-X} in @code{shar}.
|
|
|
1335
|
|
|
1336 @item question
|
|
|
1337 @samp{-q} in Make.
|
|
|
1338
|
|
|
1339 @item quiet
|
|
298
|
1340 Used in many programs to inhibit the usual output. @strong{Please
|
|
|
1341 note:} every program accepting @samp{--quiet} should accept
|
|
|
1342 @samp{--silent} as a synonym.
|
|
0
|
1343
|
|
|
1344 @item quiet-unshar
|
|
|
1345 @samp{-Q} in @code{shar}
|
|
|
1346
|
|
|
1347 @item quote-name
|
|
|
1348 @samp{-Q} in @code{ls}.
|
|
|
1349
|
|
|
1350 @item rcs
|
|
|
1351 @samp{-n} in @code{diff}.
|
|
|
1352
|
|
|
1353 @item re-interval
|
|
|
1354 Used in @code{gawk}.
|
|
|
1355
|
|
|
1356 @item read-full-blocks
|
|
|
1357 @samp{-B} in @code{tar}.
|
|
|
1358
|
|
|
1359 @item readnow
|
|
|
1360 Used in GDB.
|
|
|
1361
|
|
|
1362 @item recon
|
|
|
1363 @samp{-n} in Make.
|
|
|
1364
|
|
|
1365 @item record-number
|
|
|
1366 @samp{-R} in @code{tar}.
|
|
|
1367
|
|
|
1368 @item recursive
|
|
|
1369 Used in @code{chgrp}, @code{chown}, @code{cp}, @code{ls}, @code{diff},
|
|
|
1370 and @code{rm}.
|
|
|
1371
|
|
|
1372 @item reference-limit
|
|
|
1373 Used in @code{makeinfo}.
|
|
|
1374
|
|
|
1375 @item references
|
|
|
1376 @samp{-r} in @code{ptx}.
|
|
|
1377
|
|
|
1378 @item regex
|
|
|
1379 @samp{-r} in @code{tac} and @code{etags}.
|
|
|
1380
|
|
|
1381 @item release
|
|
|
1382 @samp{-r} in @code{uname}.
|
|
|
1383
|
|
|
1384 @item reload-state
|
|
|
1385 @samp{-R} in @code{m4}.
|
|
|
1386
|
|
|
1387 @item relocation
|
|
|
1388 @samp{-r} in @code{objdump}.
|
|
|
1389
|
|
|
1390 @item rename
|
|
|
1391 @samp{-r} in @code{cpio}.
|
|
|
1392
|
|
|
1393 @item replace
|
|
|
1394 @samp{-i} in @code{xargs}.
|
|
|
1395
|
|
|
1396 @item report-identical-files
|
|
|
1397 @samp{-s} in @code{diff}.
|
|
|
1398
|
|
|
1399 @item reset-access-time
|
|
|
1400 @samp{-a} in @code{cpio}.
|
|
|
1401
|
|
|
1402 @item reverse
|
|
|
1403 @samp{-r} in @code{ls} and @code{nm}.
|
|
|
1404
|
|
|
1405 @item reversed-ed
|
|
|
1406 @samp{-f} in @code{diff}.
|
|
|
1407
|
|
|
1408 @item right-side-defs
|
|
|
1409 @samp{-R} in @code{ptx}.
|
|
|
1410
|
|
|
1411 @item same-order
|
|
|
1412 @samp{-s} in @code{tar}.
|
|
|
1413
|
|
|
1414 @item same-permissions
|
|
|
1415 @samp{-p} in @code{tar}.
|
|
|
1416
|
|
|
1417 @item save
|
|
|
1418 @samp{-g} in @code{stty}.
|
|
|
1419
|
|
|
1420 @item se
|
|
|
1421 Used in GDB.
|
|
|
1422
|
|
|
1423 @item sentence-regexp
|
|
|
1424 @samp{-S} in @code{ptx}.
|
|
|
1425
|
|
|
1426 @item separate-dirs
|
|
|
1427 @samp{-S} in @code{du}.
|
|
|
1428
|
|
|
1429 @item separator
|
|
|
1430 @samp{-s} in @code{tac}.
|
|
|
1431
|
|
|
1432 @item sequence
|
|
|
1433 Used by @code{recode} to chose files or pipes for sequencing passes.
|
|
|
1434
|
|
|
1435 @item shell
|
|
|
1436 @samp{-s} in @code{su}.
|
|
|
1437
|
|
|
1438 @item show-all
|
|
|
1439 @samp{-A} in @code{cat}.
|
|
|
1440
|
|
|
1441 @item show-c-function
|
|
|
1442 @samp{-p} in @code{diff}.
|
|
|
1443
|
|
|
1444 @item show-ends
|
|
|
1445 @samp{-E} in @code{cat}.
|
|
|
1446
|
|
|
1447 @item show-function-line
|
|
|
1448 @samp{-F} in @code{diff}.
|
|
|
1449
|
|
|
1450 @item show-tabs
|
|
|
1451 @samp{-T} in @code{cat}.
|
|
|
1452
|
|
|
1453 @item silent
|
|
|
1454 Used in many programs to inhibit the usual output.
|
|
298
|
1455 @strong{Please note:} every program accepting
|
|
0
|
1456 @samp{--silent} should accept @samp{--quiet} as a synonym.
|
|
|
1457
|
|
|
1458 @item size
|
|
|
1459 @samp{-s} in @code{ls}.
|
|
|
1460
|
|
|
1461 @item sort
|
|
|
1462 Used in @code{ls}.
|
|
|
1463
|
|
|
1464 @item source
|
|
|
1465 @samp{-W source} in @code{gawk}.
|
|
|
1466
|
|
|
1467 @item sparse
|
|
|
1468 @samp{-S} in @code{tar}.
|
|
|
1469
|
|
|
1470 @item speed-large-files
|
|
|
1471 @samp{-H} in @code{diff}.
|
|
|
1472
|
|
|
1473 @item split-at
|
|
|
1474 @samp{-E} in @code{unshar}.
|
|
|
1475
|
|
|
1476 @item split-size-limit
|
|
|
1477 @samp{-L} in @code{shar}.
|
|
|
1478
|
|
|
1479 @item squeeze-blank
|
|
|
1480 @samp{-s} in @code{cat}.
|
|
|
1481
|
|
|
1482 @item start-delete
|
|
|
1483 @samp{-w} in @code{wdiff}.
|
|
|
1484
|
|
|
1485 @item start-insert
|
|
|
1486 @samp{-y} in @code{wdiff}.
|
|
|
1487
|
|
|
1488 @item starting-file
|
|
|
1489 Used in @code{tar} and @code{diff} to specify which file within
|
|
|
1490 a directory to start processing with.
|
|
|
1491
|
|
|
1492 @item statistics
|
|
|
1493 @samp{-s} in @code{wdiff}.
|
|
|
1494
|
|
|
1495 @item stdin-file-list
|
|
|
1496 @samp{-S} in @code{shar}.
|
|
|
1497
|
|
|
1498 @item stop
|
|
|
1499 @samp{-S} in Make.
|
|
|
1500
|
|
|
1501 @item strict
|
|
|
1502 @samp{-s} in @code{recode}.
|
|
|
1503
|
|
|
1504 @item strip
|
|
|
1505 @samp{-s} in @code{install}.
|
|
|
1506
|
|
|
1507 @item strip-all
|
|
|
1508 @samp{-s} in @code{strip}.
|
|
|
1509
|
|
|
1510 @item strip-debug
|
|
|
1511 @samp{-S} in @code{strip}.
|
|
|
1512
|
|
|
1513 @item submitter
|
|
|
1514 @samp{-s} in @code{shar}.
|
|
|
1515
|
|
|
1516 @item suffix
|
|
|
1517 @samp{-S} in @code{cp}, @code{ln}, @code{mv}.
|
|
|
1518
|
|
|
1519 @item suffix-format
|
|
|
1520 @samp{-b} in @code{csplit}.
|
|
|
1521
|
|
|
1522 @item sum
|
|
|
1523 @samp{-s} in @code{gprof}.
|
|
|
1524
|
|
|
1525 @item summarize
|
|
|
1526 @samp{-s} in @code{du}.
|
|
|
1527
|
|
|
1528 @item symbolic
|
|
|
1529 @samp{-s} in @code{ln}.
|
|
|
1530
|
|
|
1531 @item symbols
|
|
|
1532 Used in GDB and @code{objdump}.
|
|
|
1533
|
|
|
1534 @item synclines
|
|
|
1535 @samp{-s} in @code{m4}.
|
|
|
1536
|
|
|
1537 @item sysname
|
|
|
1538 @samp{-s} in @code{uname}.
|
|
|
1539
|
|
|
1540 @item tabs
|
|
|
1541 @samp{-t} in @code{expand} and @code{unexpand}.
|
|
|
1542
|
|
|
1543 @item tabsize
|
|
|
1544 @samp{-T} in @code{ls}.
|
|
|
1545
|
|
|
1546 @item terminal
|
|
|
1547 @samp{-T} in @code{tput} and @code{ul}.
|
|
|
1548 @samp{-t} in @code{wdiff}.
|
|
|
1549
|
|
|
1550 @item text
|
|
|
1551 @samp{-a} in @code{diff}.
|
|
|
1552
|
|
|
1553 @item text-files
|
|
|
1554 @samp{-T} in @code{shar}.
|
|
|
1555
|
|
|
1556 @item time
|
|
|
1557 Used in @code{ls} and @code{touch}.
|
|
|
1558
|
|
|
1559 @item to-stdout
|
|
|
1560 @samp{-O} in @code{tar}.
|
|
|
1561
|
|
|
1562 @item total
|
|
|
1563 @samp{-c} in @code{du}.
|
|
|
1564
|
|
|
1565 @item touch
|
|
|
1566 @samp{-t} in Make, @code{ranlib}, and @code{recode}.
|
|
|
1567
|
|
|
1568 @item trace
|
|
|
1569 @samp{-t} in @code{m4}.
|
|
|
1570
|
|
|
1571 @item traditional
|
|
|
1572 @samp{-t} in @code{hello};
|
|
|
1573 @samp{-W traditional} in @code{gawk};
|
|
|
1574 @samp{-G} in @code{ed}, @code{m4}, and @code{ptx}.
|
|
|
1575
|
|
|
1576 @item tty
|
|
|
1577 Used in GDB.
|
|
|
1578
|
|
|
1579 @item typedefs
|
|
|
1580 @samp{-t} in @code{ctags}.
|
|
|
1581
|
|
|
1582 @item typedefs-and-c++
|
|
|
1583 @samp{-T} in @code{ctags}.
|
|
|
1584
|
|
|
1585 @item typeset-mode
|
|
|
1586 @samp{-t} in @code{ptx}.
|
|
|
1587
|
|
|
1588 @item uncompress
|
|
|
1589 @samp{-z} in @code{tar}.
|
|
|
1590
|
|
|
1591 @item unconditional
|
|
|
1592 @samp{-u} in @code{cpio}.
|
|
|
1593
|
|
|
1594 @item undefine
|
|
|
1595 @samp{-U} in @code{m4}.
|
|
|
1596
|
|
|
1597 @item undefined-only
|
|
|
1598 @samp{-u} in @code{nm}.
|
|
|
1599
|
|
|
1600 @item update
|
|
|
1601 @samp{-u} in @code{cp}, @code{ctags}, @code{mv}, @code{tar}.
|
|
|
1602
|
|
|
1603 @item usage
|
|
|
1604 Used in @code{gawk}; same as @samp{--help}.
|
|
|
1605
|
|
|
1606 @item uuencode
|
|
|
1607 @samp{-B} in @code{shar}.
|
|
|
1608
|
|
|
1609 @item vanilla-operation
|
|
|
1610 @samp{-V} in @code{shar}.
|
|
|
1611
|
|
|
1612 @item verbose
|
|
|
1613 Print more information about progress. Many programs support this.
|
|
|
1614
|
|
|
1615 @item verify
|
|
|
1616 @samp{-W} in @code{tar}.
|
|
|
1617
|
|
|
1618 @item version
|
|
|
1619 Print the version number.
|
|
|
1620
|
|
|
1621 @item version-control
|
|
|
1622 @samp{-V} in @code{cp}, @code{ln}, @code{mv}.
|
|
|
1623
|
|
|
1624 @item vgrind
|
|
|
1625 @samp{-v} in @code{ctags}.
|
|
|
1626
|
|
|
1627 @item volume
|
|
|
1628 @samp{-V} in @code{tar}.
|
|
|
1629
|
|
|
1630 @item what-if
|
|
|
1631 @samp{-W} in Make.
|
|
|
1632
|
|
|
1633 @item whole-size-limit
|
|
|
1634 @samp{-l} in @code{shar}.
|
|
|
1635
|
|
|
1636 @item width
|
|
|
1637 @samp{-w} in @code{ls} and @code{ptx}.
|
|
|
1638
|
|
|
1639 @item word-regexp
|
|
|
1640 @samp{-W} in @code{ptx}.
|
|
|
1641
|
|
|
1642 @item writable
|
|
|
1643 @samp{-T} in @code{who}.
|
|
|
1644
|
|
|
1645 @item zeros
|
|
|
1646 @samp{-z} in @code{gprof}.
|
|
|
1647 @end table
|
|
|
1648
|
|
|
1649 @node Memory Usage
|
|
|
1650 @section Memory Usage
|
|
|
1651
|
|
|
1652 If it typically uses just a few meg of memory, don't bother making any
|
|
|
1653 effort to reduce memory usage. For example, if it is impractical for
|
|
|
1654 other reasons to operate on files more than a few meg long, it is
|
|
|
1655 reasonable to read entire input files into core to operate on them.
|
|
|
1656
|
|
|
1657 However, for programs such as @code{cat} or @code{tail}, that can
|
|
|
1658 usefully operate on very large files, it is important to avoid using a
|
|
|
1659 technique that would artificially limit the size of files it can handle.
|
|
|
1660 If a program works by lines and could be applied to arbitrary
|
|
|
1661 user-supplied input files, it should keep only a line in memory, because
|
|
|
1662 this is not very hard and users will want to be able to operate on input
|
|
|
1663 files that are bigger than will fit in core all at once.
|
|
|
1664
|
|
|
1665 If your program creates complicated data structures, just make them in
|
|
|
1666 core and give a fatal error if @code{malloc} returns zero.
|
|
|
1667
|
|
|
1668 @node Writing C
|
|
|
1669 @chapter Making The Best Use of C
|
|
|
1670
|
|
|
1671 This @value{CHAPTER} provides advice on how best to use the C language
|
|
|
1672 when writing GNU software.
|
|
|
1673
|
|
|
1674 @menu
|
|
|
1675 * Formatting:: Formatting Your Source Code
|
|
|
1676 * Comments:: Commenting Your Work
|
|
|
1677 * Syntactic Conventions:: Clean Use of C Constructs
|
|
|
1678 * Names:: Naming Variables and Functions
|
|
|
1679 * System Portability:: Portability between different operating systems
|
|
|
1680 * CPU Portability:: Supporting the range of CPU types
|
|
|
1681 * System Functions:: Portability and ``standard'' library functions
|
|
|
1682 * Internationalization:: Techniques for internationalization
|
|
|
1683 @end menu
|
|
|
1684
|
|
|
1685 @node Formatting
|
|
|
1686 @section Formatting Your Source Code
|
|
|
1687
|
|
|
1688 It is important to put the open-brace that starts the body of a C
|
|
|
1689 function in column zero, and avoid putting any other open-brace or
|
|
|
1690 open-parenthesis or open-bracket in column zero. Several tools look
|
|
|
1691 for open-braces in column zero to find the beginnings of C functions.
|
|
|
1692 These tools will not work on code not formatted that way.
|
|
|
1693
|
|
|
1694 It is also important for function definitions to start the name of the
|
|
|
1695 function in column zero. This helps people to search for function
|
|
|
1696 definitions, and may also help certain tools recognize them. Thus,
|
|
|
1697 the proper format is this:
|
|
|
1698
|
|
|
1699 @example
|
|
|
1700 static char *
|
|
|
1701 concat (s1, s2) /* Name starts in column zero here */
|
|
|
1702 char *s1, *s2;
|
|
|
1703 @{ /* Open brace in column zero here */
|
|
|
1704 @dots{}
|
|
|
1705 @}
|
|
|
1706 @end example
|
|
|
1707
|
|
|
1708 @noindent
|
|
|
1709 or, if you want to use @sc{ansi} C, format the definition like this:
|
|
|
1710
|
|
|
1711 @example
|
|
|
1712 static char *
|
|
|
1713 concat (char *s1, char *s2)
|
|
|
1714 @{
|
|
|
1715 @dots{}
|
|
|
1716 @}
|
|
|
1717 @end example
|
|
|
1718
|
|
|
1719 In @sc{ansi} C, if the arguments don't fit nicely on one line,
|
|
|
1720 split it like this:
|
|
|
1721
|
|
|
1722 @example
|
|
|
1723 int
|
|
|
1724 lots_of_args (int an_integer, long a_long, short a_short,
|
|
|
1725 double a_double, float a_float)
|
|
|
1726 @dots{}
|
|
|
1727 @end example
|
|
|
1728
|
|
|
1729 For the body of the function, we prefer code formatted like this:
|
|
|
1730
|
|
|
1731 @example
|
|
|
1732 if (x < foo (y, z))
|
|
|
1733 haha = bar[4] + 5;
|
|
|
1734 else
|
|
|
1735 @{
|
|
|
1736 while (z)
|
|
|
1737 @{
|
|
|
1738 haha += foo (z, z);
|
|
|
1739 z--;
|
|
|
1740 @}
|
|
|
1741 return ++x + bar ();
|
|
|
1742 @}
|
|
|
1743 @end example
|
|
|
1744
|
|
|
1745 We find it easier to read a program when it has spaces before the
|
|
|
1746 open-parentheses and after the commas. Especially after the commas.
|
|
|
1747
|
|
|
1748 When you split an expression into multiple lines, split it
|
|
|
1749 before an operator, not after one. Here is the right way:
|
|
|
1750
|
|
|
1751 @example
|
|
|
1752 if (foo_this_is_long && bar > win (x, y, z)
|
|
|
1753 && remaining_condition)
|
|
|
1754 @end example
|
|
|
1755
|
|
|
1756 Try to avoid having two operators of different precedence at the same
|
|
|
1757 level of indentation. For example, don't write this:
|
|
|
1758
|
|
|
1759 @example
|
|
|
1760 mode = (inmode[j] == VOIDmode
|
|
|
1761 || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
|
|
|
1762 ? outmode[j] : inmode[j]);
|
|
|
1763 @end example
|
|
|
1764
|
|
|
1765 Instead, use extra parentheses so that the indentation shows the nesting:
|
|
|
1766
|
|
|
1767 @example
|
|
|
1768 mode = ((inmode[j] == VOIDmode
|
|
|
1769 || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
|
|
|
1770 ? outmode[j] : inmode[j]);
|
|
|
1771 @end example
|
|
|
1772
|
|
|
1773 Insert extra parentheses so that Emacs will indent the code properly.
|
|
|
1774 For example, the following indentation looks nice if you do it by hand,
|
|
|
1775 but Emacs would mess it up:
|
|
|
1776
|
|
|
1777 @example
|
|
|
1778 v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
|
|
1779 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
|
|
|
1780 @end example
|
|
|
1781
|
|
|
1782 But adding a set of parentheses solves the problem:
|
|
|
1783
|
|
|
1784 @example
|
|
|
1785 v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
|
|
|
1786 + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
|
|
|
1787 @end example
|
|
|
1788
|
|
|
1789 Format do-while statements like this:
|
|
|
1790
|
|
|
1791 @example
|
|
|
1792 do
|
|
|
1793 @{
|
|
|
1794 a = foo (a);
|
|
|
1795 @}
|
|
|
1796 while (a > 0);
|
|
|
1797 @end example
|
|
|
1798
|
|
|
1799 Please use formfeed characters (control-L) to divide the program into
|
|
|
1800 pages at logical places (but not within a function). It does not matter
|
|
|
1801 just how long the pages are, since they do not have to fit on a printed
|
|
|
1802 page. The formfeeds should appear alone on lines by themselves.
|
|
|
1803
|
|
|
1804
|
|
|
1805 @node Comments
|
|
|
1806 @section Commenting Your Work
|
|
|
1807
|
|
|
1808 Every program should start with a comment saying briefly what it is for.
|
|
|
1809 Example: @samp{fmt - filter for simple filling of text}.
|
|
|
1810
|
|
|
1811 Please put a comment on each function saying what the function does,
|
|
|
1812 what sorts of arguments it gets, and what the possible values of
|
|
|
1813 arguments mean and are used for. It is not necessary to duplicate in
|
|
|
1814 words the meaning of the C argument declarations, if a C type is being
|
|
|
1815 used in its customary fashion. If there is anything nonstandard about
|
|
|
1816 its use (such as an argument of type @code{char *} which is really the
|
|
|
1817 address of the second character of a string, not the first), or any
|
|
|
1818 possible values that would not work the way one would expect (such as,
|
|
|
1819 that strings containing newlines are not guaranteed to work), be sure
|
|
|
1820 to say so.
|
|
|
1821
|
|
|
1822 Also explain the significance of the return value, if there is one.
|
|
|
1823
|
|
|
1824 Please put two spaces after the end of a sentence in your comments, so
|
|
|
1825 that the Emacs sentence commands will work. Also, please write
|
|
|
1826 complete sentences and capitalize the first word. If a lower-case
|
|
|
1827 identifier comes at the beginning of a sentence, don't capitalize it!
|
|
|
1828 Changing the spelling makes it a different identifier. If you don't
|
|
|
1829 like starting a sentence with a lower case letter, write the sentence
|
|
|
1830 differently (e.g., ``The identifier lower-case is @dots{}'').
|
|
|
1831
|
|
|
1832 The comment on a function is much clearer if you use the argument
|
|
|
1833 names to speak about the argument values. The variable name itself
|
|
|
1834 should be lower case, but write it in upper case when you are speaking
|
|
|
1835 about the value rather than the variable itself. Thus, ``the inode
|
|
|
1836 number NODE_NUM'' rather than ``an inode''.
|
|
|
1837
|
|
|
1838 There is usually no purpose in restating the name of the function in
|
|
|
1839 the comment before it, because the reader can see that for himself.
|
|
|
1840 There might be an exception when the comment is so long that the function
|
|
|
1841 itself would be off the bottom of the screen.
|
|
|
1842
|
|
|
1843 There should be a comment on each static variable as well, like this:
|
|
|
1844
|
|
|
1845 @example
|
|
|
1846 /* Nonzero means truncate lines in the display;
|
|
|
1847 zero means continue them. */
|
|
|
1848 int truncate_lines;
|
|
|
1849 @end example
|
|
|
1850
|
|
|
1851 Every @samp{#endif} should have a comment, except in the case of short
|
|
|
1852 conditionals (just a few lines) that are not nested. The comment should
|
|
|
1853 state the condition of the conditional that is ending, @emph{including
|
|
|
1854 its sense}. @samp{#else} should have a comment describing the condition
|
|
|
1855 @emph{and sense} of the code that follows. For example:
|
|
|
1856
|
|
|
1857 @example
|
|
|
1858 @group
|
|
|
1859 #ifdef foo
|
|
|
1860 @dots{}
|
|
|
1861 #else /* not foo */
|
|
|
1862 @dots{}
|
|
|
1863 #endif /* not foo */
|
|
|
1864 @end group
|
|
|
1865 @end example
|
|
|
1866
|
|
|
1867 @noindent
|
|
|
1868 but, by contrast, write the comments this way for a @samp{#ifndef}:
|
|
|
1869
|
|
|
1870 @example
|
|
|
1871 @group
|
|
|
1872 #ifndef foo
|
|
|
1873 @dots{}
|
|
|
1874 #else /* foo */
|
|
|
1875 @dots{}
|
|
|
1876 #endif /* foo */
|
|
|
1877 @end group
|
|
|
1878 @end example
|
|
|
1879
|
|
|
1880
|
|
|
1881 @node Syntactic Conventions
|
|
|
1882 @section Clean Use of C Constructs
|
|
|
1883
|
|
|
1884 Please explicitly declare all arguments to functions.
|
|
|
1885 Don't omit them just because they are @code{int}s.
|
|
|
1886
|
|
|
1887 Declarations of external functions and functions to appear later in the
|
|
|
1888 source file should all go in one place near the beginning of the file
|
|
|
1889 (somewhere before the first function definition in the file), or else
|
|
|
1890 should go in a header file. Don't put @code{extern} declarations inside
|
|
|
1891 functions.
|
|
|
1892
|
|
|
1893 It used to be common practice to use the same local variables (with
|
|
|
1894 names like @code{tem}) over and over for different values within one
|
|
|
1895 function. Instead of doing this, it is better declare a separate local
|
|
|
1896 variable for each distinct purpose, and give it a name which is
|
|
|
1897 meaningful. This not only makes programs easier to understand, it also
|
|
|
1898 facilitates optimization by good compilers. You can also move the
|
|
|
1899 declaration of each local variable into the smallest scope that includes
|
|
|
1900 all its uses. This makes the program even cleaner.
|
|
|
1901
|
|
|
1902 Don't use local variables or parameters that shadow global identifiers.
|
|
|
1903
|
|
|
1904 Don't declare multiple variables in one declaration that spans lines.
|
|
|
1905 Start a new declaration on each line, instead. For example, instead
|
|
|
1906 of this:
|
|
|
1907
|
|
|
1908 @example
|
|
|
1909 @group
|
|
|
1910 int foo,
|
|
|
1911 bar;
|
|
|
1912 @end group
|
|
|
1913 @end example
|
|
|
1914
|
|
|
1915 @noindent
|
|
|
1916 write either this:
|
|
|
1917
|
|
|
1918 @example
|
|
|
1919 int foo, bar;
|
|
|
1920 @end example
|
|
|
1921
|
|
|
1922 @noindent
|
|
|
1923 or this:
|
|
|
1924
|
|
|
1925 @example
|
|
|
1926 int foo;
|
|
|
1927 int bar;
|
|
|
1928 @end example
|
|
|
1929
|
|
|
1930 @noindent
|
|
|
1931 (If they are global variables, each should have a comment preceding it
|
|
|
1932 anyway.)
|
|
|
1933
|
|
|
1934 When you have an @code{if}-@code{else} statement nested in another
|
|
|
1935 @code{if} statement, always put braces around the @code{if}-@code{else}.
|
|
|
1936 Thus, never write like this:
|
|
|
1937
|
|
|
1938 @example
|
|
|
1939 if (foo)
|
|
|
1940 if (bar)
|
|
|
1941 win ();
|
|
|
1942 else
|
|
|
1943 lose ();
|
|
|
1944 @end example
|
|
|
1945
|
|
|
1946 @noindent
|
|
|
1947 always like this:
|
|
|
1948
|
|
|
1949 @example
|
|
|
1950 if (foo)
|
|
|
1951 @{
|
|
|
1952 if (bar)
|
|
|
1953 win ();
|
|
|
1954 else
|
|
|
1955 lose ();
|
|
|
1956 @}
|
|
|
1957 @end example
|
|
|
1958
|
|
|
1959 If you have an @code{if} statement nested inside of an @code{else}
|
|
|
1960 statement, either write @code{else if} on one line, like this,
|
|
|
1961
|
|
|
1962 @example
|
|
|
1963 if (foo)
|
|
|
1964 @dots{}
|
|
|
1965 else if (bar)
|
|
|
1966 @dots{}
|
|
|
1967 @end example
|
|
|
1968
|
|
|
1969 @noindent
|
|
|
1970 with its @code{then}-part indented like the preceding @code{then}-part,
|
|
|
1971 or write the nested @code{if} within braces like this:
|
|
|
1972
|
|
|
1973 @example
|
|
|
1974 if (foo)
|
|
|
1975 @dots{}
|
|
|
1976 else
|
|
|
1977 @{
|
|
|
1978 if (bar)
|
|
|
1979 @dots{}
|
|
|
1980 @}
|
|
|
1981 @end example
|
|
|
1982
|
|
|
1983 Don't declare both a structure tag and variables or typedefs in the
|
|
|
1984 same declaration. Instead, declare the structure tag separately
|
|
|
1985 and then use it to declare the variables or typedefs.
|
|
|
1986
|
|
|
1987 Try to avoid assignments inside @code{if}-conditions. For example,
|
|
|
1988 don't write this:
|
|
|
1989
|
|
|
1990 @example
|
|
|
1991 if ((foo = (char *) malloc (sizeof *foo)) == 0)
|
|
|
1992 fatal ("virtual memory exhausted");
|
|
|
1993 @end example
|
|
|
1994
|
|
|
1995 @noindent
|
|
|
1996 instead, write this:
|
|
|
1997
|
|
|
1998 @example
|
|
|
1999 foo = (char *) malloc (sizeof *foo);
|
|
|
2000 if (foo == 0)
|
|
|
2001 fatal ("virtual memory exhausted");
|
|
|
2002 @end example
|
|
|
2003
|
|
|
2004 Don't make the program ugly to placate @code{lint}. Please don't insert any
|
|
|
2005 casts to @code{void}. Zero without a cast is perfectly fine as a null
|
|
|
2006 pointer constant, except when calling a varargs function.
|
|
|
2007
|
|
|
2008 @node Names
|
|
|
2009 @section Naming Variables and Functions
|
|
|
2010
|
|
|
2011 Please use underscores to separate words in a name, so that the Emacs
|
|
|
2012 word commands can be useful within them. Stick to lower case; reserve
|
|
|
2013 upper case for macros and @code{enum} constants, and for name-prefixes
|
|
|
2014 that follow a uniform convention.
|
|
|
2015
|
|
|
2016 For example, you should use names like @code{ignore_space_change_flag};
|
|
|
2017 don't use names like @code{iCantReadThis}.
|
|
|
2018
|
|
|
2019 Variables that indicate whether command-line options have been
|
|
|
2020 specified should be named after the meaning of the option, not after
|
|
|
2021 the option-letter. A comment should state both the exact meaning of
|
|
|
2022 the option and its letter. For example,
|
|
|
2023
|
|
|
2024 @example
|
|
|
2025 @group
|
|
|
2026 /* Ignore changes in horizontal whitespace (-b). */
|
|
|
2027 int ignore_space_change_flag;
|
|
|
2028 @end group
|
|
|
2029 @end example
|
|
|
2030
|
|
|
2031 When you want to define names with constant integer values, use
|
|
|
2032 @code{enum} rather than @samp{#define}. GDB knows about enumeration
|
|
|
2033 constants.
|
|
|
2034
|
|
|
2035 Use file names of 14 characters or less, to avoid creating gratuitous
|
|
|
2036 problems on older System V systems. You can use the program @code{doschk} to test for
|
|
|
2037 this. @code{doschk} also tests for potential name conflicts if the
|
|
|
2038 files were loaded onto an MS-DOS file system---something you may or may
|
|
|
2039 not care about.
|
|
|
2040
|
|
|
2041 @node System Portability
|
|
|
2042 @section Portability between System Types
|
|
|
2043
|
|
|
2044 In the Unix world, ``portability'' refers to porting to different Unix
|
|
|
2045 versions. For a GNU program, this kind of portability is desirable, but
|
|
|
2046 not paramount.
|
|
|
2047
|
|
|
2048 The primary purpose of GNU software is to run on top of the GNU kernel,
|
|
|
2049 compiled with the GNU C compiler, on various types of @sc{cpu}. The
|
|
|
2050 amount and kinds of variation among GNU systems on different @sc{cpu}s
|
|
|
2051 will be comparable to the variation among Linux-based GNU systems or
|
|
|
2052 among BSD systems today. So the kinds of portability that are absolutely
|
|
|
2053 necessary are quite limited.
|
|
|
2054
|
|
|
2055 But many users do run GNU software on non-GNU Unix or Unix-like systems.
|
|
|
2056 So supporting a variety of Unix-like systems is desirable, although not
|
|
|
2057 paramount.
|
|
|
2058
|
|
|
2059 The easiest way to achieve portability to most Unix-like systems is to
|
|
|
2060 use Autoconf. It's unlikely that your program needs to know more
|
|
|
2061 information about the host platform than Autoconf can provide, simply
|
|
|
2062 because most of the programs that need such knowledge have already been
|
|
|
2063 written.
|
|
|
2064
|
|
|
2065 Avoid using the format of semi-internal data bases (e.g., directories)
|
|
|
2066 when there is a higher-level alternative (@code{readdir}).
|
|
|
2067
|
|
|
2068 As for systems that are not like Unix, such as MSDOS, Windows, the
|
|
|
2069 Macintosh, VMS, and MVS, supporting them is usually so much work that it
|
|
|
2070 is better if you don't.
|
|
|
2071
|
|
|
2072 The planned GNU kernel is not finished yet, but you can tell which
|
|
|
2073 facilities it will provide by looking at the GNU C Library Manual. The
|
|
|
2074 GNU kernel is based on Mach, so the features of Mach will also be
|
|
|
2075 available. However, if you use Mach features, you'll probably have
|
|
|
2076 trouble debugging your program today.
|
|
|
2077
|
|
|
2078 @node CPU Portability
|
|
|
2079 @section Portability between @sc{cpu}s
|
|
|
2080
|
|
|
2081 Even GNU systems will differ because of differences among @sc{cpu}
|
|
|
2082 types---for example, difference in byte ordering and alignment
|
|
|
2083 requirements. It is absolutely essential to handle these differences.
|
|
|
2084 However, don't make any effort to cater to the possibility that an
|
|
|
2085 @code{int} will be less than 32 bits. We don't support 16-bit machines
|
|
|
2086 in GNU.
|
|
|
2087
|
|
|
2088 Don't assume that the address of an @code{int} object is also the
|
|
|
2089 address of its least-significant byte. This is false on big-endian
|
|
|
2090 machines. Thus, don't make the following mistake:
|
|
|
2091
|
|
|
2092 @example
|
|
|
2093 int c;
|
|
|
2094 @dots{}
|
|
|
2095 while ((c = getchar()) != EOF)
|
|
|
2096 write(file_descriptor, &c, 1);
|
|
|
2097 @end example
|
|
|
2098
|
|
|
2099 When calling functions, you need not worry about the difference between
|
|
|
2100 pointers of various types, or between pointers and integers. On most
|
|
|
2101 machines, there's no difference anyway. As for the few machines where
|
|
|
2102 there is a difference, all of them support @sc{ansi} C, so you can use
|
|
|
2103 prototypes (conditionalized to be active only in @sc{ansi} C) to make
|
|
|
2104 the code work on those systems.
|
|
|
2105
|
|
|
2106 In certain cases, it is ok to pass integer and pointer arguments
|
|
|
2107 indiscriminately to the same function, and use no prototype on any
|
|
|
2108 system. For example, many GNU programs have error-reporting functions
|
|
|
2109 that pass their arguments along to @code{printf} and friends:
|
|
|
2110
|
|
|
2111 @example
|
|
|
2112 error (s, a1, a2, a3)
|
|
|
2113 char *s;
|
|
|
2114 int a1, a2, a3;
|
|
|
2115 @{
|
|
|
2116 fprintf (stderr, "error: ");
|
|
|
2117 fprintf (stderr, s, a1, a2, a3);
|
|
|
2118 @}
|
|
|
2119 @end example
|
|
|
2120
|
|
|
2121 @noindent
|
|
|
2122 In practice, this works on all machines, and it is much simpler than any
|
|
|
2123 ``correct'' alternative. Be sure @emph{not} to use a prototype
|
|
|
2124 for such functions.
|
|
|
2125
|
|
|
2126 However, avoid casting pointers to integers unless you really need to.
|
|
|
2127 These assumptions really reduce portability, and in most programs they
|
|
|
2128 are easy to avoid. In the cases where casting pointers to integers is
|
|
|
2129 essential---such as, a Lisp interpreter which stores type information as
|
|
|
2130 well as an address in one word---it is ok to do so, but you'll have to
|
|
|
2131 make explicit provisions to handle different word sizes.
|
|
|
2132
|
|
|
2133 @node System Functions
|
|
|
2134 @section Calling System Functions
|
|
|
2135
|
|
|
2136 C implementations differ substantially. @sc{ansi} C reduces but does not
|
|
|
2137 eliminate the incompatibilities; meanwhile, many users wish to compile
|
|
|
2138 GNU software with pre-@sc{ansi} compilers. This chapter gives
|
|
|
2139 recommendations for how to use the more or less standard C library
|
|
|
2140 functions to avoid unnecessary loss of portability.
|
|
|
2141
|
|
|
2142 @itemize @bullet
|
|
|
2143 @item
|
|
|
2144 Don't use the value of @code{sprintf}. It returns the number of
|
|
|
2145 characters written on some systems, but not on all systems.
|
|
|
2146
|
|
|
2147 @item
|
|
|
2148 Don't declare system functions explicitly.
|
|
|
2149
|
|
|
2150 Almost any declaration for a system function is wrong on some system.
|
|
|
2151 To minimize conflicts, leave it to the system header files to declare
|
|
|
2152 system functions. If the headers don't declare a function, let it
|
|
|
2153 remain undeclared.
|
|
|
2154
|
|
|
2155 While it may seem unclean to use a function without declaring it, in
|
|
|
2156 practice this works fine for most system library functions on the
|
|
|
2157 systems where this really happens; thus, the disadvantage is only
|
|
|
2158 theoretical. By contrast, actual declarations have frequently caused
|
|
|
2159 actual conflicts.
|
|
|
2160
|
|
|
2161 @item
|
|
|
2162 If you must declare a system function, don't specify the argument types.
|
|
|
2163 Use an old-style declaration, not an @sc{ansi} prototype. The more you
|
|
|
2164 specify about the function, the more likely a conflict.
|
|
|
2165
|
|
|
2166 @item
|
|
|
2167 In particular, don't unconditionally declare @code{malloc} or
|
|
|
2168 @code{realloc}.
|
|
|
2169
|
|
|
2170 Most GNU programs use those functions just once, in functions
|
|
|
2171 conventionally named @code{xmalloc} and @code{xrealloc}. These
|
|
|
2172 functions call @code{malloc} and @code{realloc}, respectively, and
|
|
|
2173 check the results.
|
|
|
2174
|
|
|
2175 Because @code{xmalloc} and @code{xrealloc} are defined in your program,
|
|
|
2176 you can declare them in other files without any risk of type conflict.
|
|
|
2177
|
|
|
2178 On most systems, @code{int} is the same length as a pointer; thus, the
|
|
|
2179 calls to @code{malloc} and @code{realloc} work fine. For the few
|
|
|
2180 exceptional systems (mostly 64-bit machines), you can use
|
|
|
2181 @strong{conditionalized} declarations of @code{malloc} and
|
|
|
2182 @code{realloc}---or put these declarations in configuration files
|
|
|
2183 specific to those systems.
|
|
|
2184
|
|
|
2185 @item
|
|
|
2186 The string functions require special treatment. Some Unix systems have
|
|
|
2187 a header file @file{string.h}; others have @file{strings.h}. Neither
|
|
|
2188 file name is portable. There are two things you can do: use Autoconf to
|
|
|
2189 figure out which file to include, or don't include either file.
|
|
|
2190
|
|
|
2191 @item
|
|
|
2192 If you don't include either strings file, you can't get declarations for
|
|
|
2193 the string functions from the header file in the usual way.
|
|
|
2194
|
|
|
2195 That causes less of a problem than you might think. The newer @sc{ansi}
|
|
|
2196 string functions should be avoided anyway because many systems still
|
|
|
2197 don't support them. The string functions you can use are these:
|
|
|
2198
|
|
|
2199 @example
|
|
|
2200 strcpy strncpy strcat strncat
|
|
|
2201 strlen strcmp strncmp
|
|
|
2202 strchr strrchr
|
|
|
2203 @end example
|
|
|
2204
|
|
|
2205 The copy and concatenate functions work fine without a declaration as
|
|
|
2206 long as you don't use their values. Using their values without a
|
|
|
2207 declaration fails on systems where the width of a pointer differs from
|
|
|
2208 the width of @code{int}, and perhaps in other cases. It is trivial to
|
|
|
2209 avoid using their values, so do that.
|
|
|
2210
|
|
|
2211 The compare functions and @code{strlen} work fine without a declaration
|
|
|
2212 on most systems, possibly all the ones that GNU software runs on.
|
|
|
2213 You may find it necessary to declare them @strong{conditionally} on a
|
|
|
2214 few systems.
|
|
|
2215
|
|
|
2216 The search functions must be declared to return @code{char *}. Luckily,
|
|
|
2217 there is no variation in the data type they return. But there is
|
|
|
2218 variation in their names. Some systems give these functions the names
|
|
|
2219 @code{index} and @code{rindex}; other systems use the names
|
|
|
2220 @code{strchr} and @code{strrchr}. Some systems support both pairs of
|
|
|
2221 names, but neither pair works on all systems.
|
|
|
2222
|
|
|
2223 You should pick a single pair of names and use it throughout your
|
|
|
2224 program. (Nowadays, it is better to choose @code{strchr} and
|
|
|
2225 @code{strrchr} for new programs, since those are the standard @sc{ansi}
|
|
|
2226 names.) Declare both of those names as functions returning @code{char
|
|
|
2227 *}. On systems which don't support those names, define them as macros
|
|
|
2228 in terms of the other pair. For example, here is what to put at the
|
|
|
2229 beginning of your file (or in a header) if you want to use the names
|
|
|
2230 @code{strchr} and @code{strrchr} throughout:
|
|
|
2231
|
|
|
2232 @example
|
|
|
2233 #ifndef HAVE_STRCHR
|
|
|
2234 #define strchr index
|
|
|
2235 #endif
|
|
|
2236 #ifndef HAVE_STRRCHR
|
|
|
2237 #define strrchr rindex
|
|
|
2238 #endif
|
|
|
2239
|
|
|
2240 char *strchr ();
|
|
|
2241 char *strrchr ();
|
|
|
2242 @end example
|
|
|
2243 @end itemize
|
|
|
2244
|
|
|
2245 Here we assume that @code{HAVE_STRCHR} and @code{HAVE_STRRCHR} are
|
|
|
2246 macros defined in systems where the corresponding functions exist.
|
|
|
2247 One way to get them properly defined is to use Autoconf.
|
|
|
2248
|
|
|
2249 @node Internationalization
|
|
|
2250 @section Internationalization
|
|
|
2251
|
|
|
2252 GNU has a library called GNU gettext that makes it easy to translate the
|
|
|
2253 messages in a program into various languages. You should use this
|
|
|
2254 library in every program. Use English for the messages as they appear
|
|
|
2255 in the program, and let gettext provide the way to translate them into
|
|
|
2256 other languages.
|
|
|
2257
|
|
|
2258 Using GNU gettext involves putting a call to the @code{gettext} macro
|
|
|
2259 around each string that might need translation---like this:
|
|
|
2260
|
|
|
2261 @example
|
|
|
2262 printf (gettext ("Processing file `%s'..."));
|
|
|
2263 @end example
|
|
|
2264
|
|
|
2265 @noindent
|
|
|
2266 This permits GNU gettext to replace the string @code{"Processing file
|
|
|
2267 `%s'..."} with a translated version.
|
|
|
2268
|
|
|
2269 Once a program uses gettext, please make a point of writing calls to
|
|
|
2270 @code{gettext} when you add new strings that call for translation.
|
|
|
2271
|
|
|
2272 Using GNU gettext in a package involves specifying a @dfn{text domain
|
|
|
2273 name} for the package. The text domain name is used to separate the
|
|
|
2274 translations for this package from the translations for other packages.
|
|
|
2275 Normally, the text domain name should be the same as the name of the
|
|
|
2276 package---for example, @samp{fileutils} for the GNU file utilities.
|
|
|
2277
|
|
|
2278 To enable gettext to work, avoid writing code that makes assumptions
|
|
|
2279 about the structure of words. Don't construct words from parts. Here
|
|
|
2280 is an example of what not to do:
|
|
|
2281
|
|
|
2282 @example
|
|
|
2283 prinf ("%d file%s processed", nfiles,
|
|
|
2284 nfiles > 1 ? "s" : "");
|
|
|
2285 @end example
|
|
|
2286
|
|
|
2287 @noindent
|
|
|
2288 The problem with that example is that it assumes that plurals are made
|
|
|
2289 by adding `s'. If you apply gettext to the format string, like this,
|
|
|
2290
|
|
|
2291 @example
|
|
|
2292 prinf (gettext ("%d file%s processed"), nfiles,
|
|
|
2293 nfiles > 1 ? "s" : "");
|
|
|
2294 @end example
|
|
|
2295
|
|
|
2296 @noindent
|
|
|
2297 the message can use different words, but it will still be forced to use
|
|
|
2298 `s' for the plural. Here is a better way:
|
|
|
2299
|
|
|
2300 @example
|
|
|
2301 prinf ((nfiles > 1 ? "%d files processed"
|
|
|
2302 : "%d file processed"),
|
|
|
2303 nfiles);
|
|
|
2304 @end example
|
|
|
2305
|
|
|
2306 @noindent
|
|
|
2307 This way, you can apply gettext to each of the two strings
|
|
|
2308 independently:
|
|
|
2309
|
|
|
2310 @example
|
|
|
2311 prinf ((nfiles > 1 ? gettext ("%d files processed")
|
|
|
2312 : gettext ("%d file processed")),
|
|
|
2313 nfiles);
|
|
|
2314 @end example
|
|
|
2315
|
|
|
2316 @noindent
|
|
|
2317 This can handle any language, no matter how it forms the plural of the
|
|
|
2318 word for ``file.''
|
|
|
2319
|
|
|
2320 @node Documentation
|
|
|
2321 @chapter Documenting Programs
|
|
|
2322
|
|
|
2323 @menu
|
|
|
2324 * GNU Manuals:: Writing proper manuals.
|
|
|
2325 * Manual Structure Details:: Specific structure conventions.
|
|
|
2326 * NEWS File:: NEWS files supplement manuals.
|
|
|
2327 * Change Logs:: Recording Changes
|
|
|
2328 * Man Pages:: Man pages are secondary.
|
|
|
2329 * Reading other Manuals:: How far you can go in learning
|
|
|
2330 from other manuals.
|
|
|
2331 @end menu
|
|
|
2332
|
|
|
2333 @node GNU Manuals
|
|
|
2334 @section GNU Manuals
|
|
|
2335
|
|
|
2336 The preferred way to document part of the GNU system is to write a
|
|
|
2337 manual in the Texinfo formatting language. See the Texinfo manual,
|
|
|
2338 either the hardcopy, or the on-line version available through
|
|
|
2339 @code{info} or the Emacs Info subsystem (@kbd{C-h i}).
|
|
|
2340
|
|
|
2341 The manual should document all of the program's command-line options and
|
|
|
2342 all of its commands. It should give examples of their use. But don't
|
|
|
2343 organize the manual as a list of features. Instead, organize it
|
|
|
2344 logically, by subtopics. Address the goals that a user will have in
|
|
|
2345 mind, and explain how to accomplish them.
|
|
|
2346
|
|
|
2347 In general, a GNU manual should serve both as tutorial and reference.
|
|
|
2348 It should be set up for convenient access to each topic through Info,
|
|
|
2349 and for reading straight through (appendixes aside). A GNU manual
|
|
|
2350 should give a good introduction to a beginner reading through from the
|
|
|
2351 start, and should also provide all the details that hackers want.
|
|
|
2352
|
|
|
2353 That is not as hard as it first sounds. Arrange each chapter as a
|
|
|
2354 logical breakdown of its topic, but order the sections, and write their
|
|
|
2355 text, so that reading the chapter straight through makes sense. Do
|
|
|
2356 likewise when structuring the book into chapters, and when structuring a
|
|
|
2357 section into paragraphs. The watchword is, @emph{at each point, address
|
|
|
2358 the most fundamental and important issue raised by the preceding text.}
|
|
|
2359
|
|
|
2360 If necessary, add extra chapters at the beginning of the manual which
|
|
|
2361 are purely tutorial and cover the basics of the subject. These provide
|
|
|
2362 the framework for a beginner to understand the rest of the manual. The
|
|
|
2363 Bison manual provides a good example of how to do this.
|
|
|
2364
|
|
|
2365 Don't use Unix man pages as a model for how to write GNU documentation;
|
|
|
2366 they are a bad example to follow.
|
|
|
2367
|
|
|
2368 Please do not use the term ``pathname'' that is used in Unix
|
|
|
2369 documentation; use ``file name'' (two words) instead. We use the term
|
|
|
2370 ``path'' only for search paths, which are lists of file names.
|
|
|
2371
|
|
|
2372 @node Manual Structure Details
|
|
|
2373 @section Manual Structure Details
|
|
|
2374
|
|
|
2375 The title page of the manual should state the version of the program
|
|
|
2376 to which the manual applies. The Top node of the manual should also
|
|
|
2377 contain this information. If the manual is changing more frequently
|
|
|
2378 than or independent of the program, also state a version number for
|
|
|
2379 the manual in both of these places.
|
|
|
2380
|
|
|
2381 The manual should have a node named @samp{@var{program} Invocation} or
|
|
|
2382 @samp{Invoking @var{program}}, where @var{program} stands for the name
|
|
|
2383 of the program being described, as you would type it in the shell to run
|
|
|
2384 the program. This node (together with its subnodes, if any) should
|
|
|
2385 describe the program's command line arguments and how to run it (the
|
|
|
2386 sort of information people would look in a man page for). Start with an
|
|
|
2387 @samp{@@example} containing a template for all the options and arguments
|
|
|
2388 that the program uses.
|
|
|
2389
|
|
|
2390 Alternatively, put a menu item in some menu whose item name fits one of
|
|
|
2391 the above patterns. This identifies the node which that item points to
|
|
|
2392 as the node for this purpose, regardless of the node's actual name.
|
|
|
2393
|
|
|
2394 There will be automatic features for specifying a program name and
|
|
|
2395 quickly reading just this part of its manual.
|
|
|
2396
|
|
|
2397 If one manual describes several programs, it should have such a node for
|
|
|
2398 each program described.
|
|
|
2399
|
|
|
2400 @node NEWS File
|
|
|
2401 @section The NEWS File
|
|
|
2402
|
|
|
2403 In addition to its manual, the package should have a file named
|
|
|
2404 @file{NEWS} which contains a list of user-visible changes worth
|
|
|
2405 mentioning. In each new release, add items to the front of the file and
|
|
|
2406 identify the version they pertain to. Don't discard old items; leave
|
|
|
2407 them in the file after the newer items. This way, a user upgrading from
|
|
|
2408 any previous version can see what is new.
|
|
|
2409
|
|
|
2410 If the @file{NEWS} file gets very long, move some of the older items
|
|
|
2411 into a file named @file{ONEWS} and put a note at the end referring the
|
|
|
2412 user to that file.
|
|
|
2413
|
|
|
2414 @node Change Logs
|
|
|
2415 @section Change Logs
|
|
|
2416
|
|
|
2417 Keep a change log to describe all the changes made to program source
|
|
|
2418 files. The purpose of this is so that people investigating bugs in the
|
|
|
2419 future will know about the changes that might have introduced the bug.
|
|
|
2420 Often a new bug can be found by looking at what was recently changed.
|
|
|
2421 More importantly, change logs can help eliminate conceptual
|
|
|
2422 inconsistencies between different parts of a program; they can give you
|
|
|
2423 a history of how the conflicting concepts arose.
|
|
|
2424
|
|
|
2425 A change log file is normally called @file{ChangeLog} and covers an
|
|
|
2426 entire directory. Each directory can have its own change log, or a
|
|
|
2427 directory can use the change log of its parent directory--it's up to
|
|
|
2428 you.
|
|
|
2429
|
|
|
2430 Another alternative is to record change log information with a version
|
|
|
2431 control system such as RCS or CVS. This can be converted automatically
|
|
|
2432 to a @file{ChangeLog} file.
|
|
|
2433
|
|
|
2434 The easiest way to add an entry to @file{ChangeLog} is with the Emacs
|
|
|
2435 command @kbd{M-x add-change-log-entry}. An entry should have an
|
|
|
2436 asterisk, the name of the changed file, and then in parentheses the name
|
|
|
2437 of the changed functions, variables or whatever, followed by a colon.
|
|
|
2438 Then describe the changes you made to that function or variable.
|
|
|
2439
|
|
|
2440 Separate unrelated entries with blank lines. When two entries
|
|
|
2441 represent parts of the same change, so that they work together, then
|
|
|
2442 don't put blank lines between them. Then you can omit the file name
|
|
|
2443 and the asterisk when successive entries are in the same file.
|
|
|
2444
|
|
|
2445 Here are some examples:
|
|
|
2446
|
|
|
2447 @example
|
|
|
2448 * register.el (insert-register): Return nil.
|
|
|
2449 (jump-to-register): Likewise.
|
|
|
2450
|
|
|
2451 * sort.el (sort-subr): Return nil.
|
|
|
2452
|
|
|
2453 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
|
|
|
2454 Restart the tex shell if process is gone or stopped.
|
|
|
2455 (tex-shell-running): New function.
|
|
|
2456
|
|
|
2457 * expr.c (store_one_arg): Round size up for move_block_to_reg.
|
|
|
2458 (expand_call): Round up when emitting USE insns.
|
|
|
2459 * stmt.c (assign_parms): Round size up for move_block_from_reg.
|
|
|
2460 @end example
|
|
|
2461
|
|
|
2462 It's important to name the changed function or variable in full. Don't
|
|
|
2463 abbreviate function or variable names, and don't combine them.
|
|
|
2464 Subsequent maintainers will often
|
|
|
2465 search for a function name to find all the change log entries that
|
|
|
2466 pertain to it; if you abbreviate the name, they won't find it when they
|
|
|
2467 search. For example, some people are tempted to abbreviate groups of
|
|
|
2468 function names by writing @samp{* register.el
|
|
|
2469 (@{insert,jump-to@}-register)}; this is not a good idea, since searching
|
|
|
2470 for @code{jump-to-register} or @code{insert-register} would not find the
|
|
|
2471 entry.
|
|
|
2472
|
|
|
2473 There's no need to describe the full purpose of the changes or how they
|
|
|
2474 work together. It is better to put such explanations in comments in the
|
|
|
2475 code. That's why just ``New function'' is enough; there is a comment
|
|
|
2476 with the function in the source to explain what it does.
|
|
|
2477
|
|
|
2478 However, sometimes it is useful to write one line to describe the
|
|
|
2479 overall purpose of a large batch of changes.
|
|
|
2480
|
|
|
2481 You can think of the change log as a conceptual ``undo list'' which
|
|
|
2482 explains how earlier versions were different from the current version.
|
|
|
2483 People can see the current version; they don't need the change log
|
|
|
2484 to tell them what is in it. What they want from a change log is a
|
|
|
2485 clear explanation of how the earlier version differed.
|
|
|
2486
|
|
|
2487 When you change the calling sequence of a function in a simple
|
|
|
2488 fashion, and you change all the callers of the function, there is no
|
|
|
2489 need to make individual entries for all the callers. Just write in
|
|
|
2490 the entry for the function being called, ``All callers changed.''
|
|
|
2491
|
|
|
2492 When you change just comments or doc strings, it is enough to write an
|
|
|
2493 entry for the file, without mentioning the functions. Write just,
|
|
|
2494 ``Doc fix.''
|
|
|
2495
|
|
|
2496 There's no need to make change log entries for documentation files.
|
|
|
2497 This is because documentation is not susceptible to bugs that are hard
|
|
|
2498 to fix. Documentation does not consist of parts that must interact in a
|
|
|
2499 precisely engineered fashion. To correct an error, you need not know
|
|
|
2500 the history of the erroneous passage; it is enough to compare the
|
|
|
2501 passage with the way the program actually works.
|
|
|
2502
|
|
|
2503 @node Man Pages
|
|
|
2504 @section Man Pages
|
|
|
2505
|
|
|
2506 In the GNU project, man pages are secondary. It is not necessary or
|
|
|
2507 expected for every GNU program to have a man page, but some of them do.
|
|
|
2508 It's your choice whether to include a man page in your program.
|
|
|
2509
|
|
|
2510 When you make this decision, consider that supporting a man page
|
|
|
2511 requires continual effort each time the program is changed. The time
|
|
|
2512 you spend on the man page is time taken away from more useful work.
|
|
|
2513
|
|
|
2514 For a simple program which changes little, updating the man page may be
|
|
|
2515 a small job. Then there is little reason not to include a man page, if
|
|
|
2516 you have one.
|
|
|
2517
|
|
|
2518 For a large program that changes a great deal, updating a man page may
|
|
|
2519 be a substantial burden. If a user offers to donate a man page, you may
|
|
|
2520 find this gift costly to accept. It may be better to refuse the man
|
|
|
2521 page unless the same person agrees to take full responsibility for
|
|
|
2522 maintaining it---so that you can wash your hands of it entirely. If
|
|
|
2523 this volunteer later ceases to do the job, then don't feel obliged to
|
|
|
2524 pick it up yourself; it may be better to withdraw the man page from the
|
|
|
2525 distribution until someone else agrees to update it.
|
|
|
2526
|
|
|
2527 When a program changes only a little, you may feel that the
|
|
|
2528 discrepancies are small enough that the man page remains useful without
|
|
|
2529 updating. If so, put a prominent note near the beginning of the man
|
|
|
2530 page explaining that you don't maintain it and that the Texinfo manual
|
|
|
2531 is more authoritative. The note should say how to access the Texinfo
|
|
|
2532 documentation.
|
|
|
2533
|
|
|
2534 @node Reading other Manuals
|
|
|
2535 @section Reading other Manuals
|
|
|
2536
|
|
|
2537 There may be non-free books or documentation files that describe the
|
|
|
2538 program you are documenting.
|
|
|
2539
|
|
|
2540 It is ok to use these documents for reference, just as the author of a
|
|
|
2541 new algebra textbook can read other books on algebra. A large portion
|
|
|
2542 of any non-fiction book consists of facts, in this case facts about how
|
|
|
2543 a certain program works, and these facts are necessarily the same for
|
|
|
2544 everyone who writes about the subject. But be careful not to copy your
|
|
|
2545 outline structure, wording, tables or examples from preexisting non-free
|
|
|
2546 documentation. Copying from free documentation may be ok; please check
|
|
|
2547 with the FSF about the individual case.
|
|
|
2548
|
|
|
2549 @node Managing Releases
|
|
|
2550 @chapter The Release Process
|
|
|
2551
|
|
|
2552 Making a release is more than just bundling up your source files in a
|
|
|
2553 tar file and putting it up for FTP. You should set up your software so
|
|
|
2554 that it can be configured to run on a variety of systems. Your Makefile
|
|
|
2555 should conform to the GNU standards described below, and your directory
|
|
|
2556 layout should also conform to the standards discussed below. Doing so
|
|
|
2557 makes it easy to include your package into the larger framework of
|
|
|
2558 all GNU software.
|
|
|
2559
|
|
|
2560 @menu
|
|
|
2561 * Configuration:: How Configuration Should Work
|
|
|
2562 * Makefile Conventions:: Makefile Conventions
|
|
|
2563 * Releases:: Making Releases
|
|
|
2564 @end menu
|
|
|
2565
|
|
|
2566 @node Configuration
|
|
|
2567 @section How Configuration Should Work
|
|
|
2568
|
|
|
2569 Each GNU distribution should come with a shell script named
|
|
|
2570 @code{configure}. This script is given arguments which describe the
|
|
|
2571 kind of machine and system you want to compile the program for.
|
|
|
2572
|
|
|
2573 The @code{configure} script must record the configuration options so
|
|
|
2574 that they affect compilation.
|
|
|
2575
|
|
|
2576 One way to do this is to make a link from a standard name such as
|
|
|
2577 @file{config.h} to the proper configuration file for the chosen system.
|
|
|
2578 If you use this technique, the distribution should @emph{not} contain a
|
|
|
2579 file named @file{config.h}. This is so that people won't be able to
|
|
|
2580 build the program without configuring it first.
|
|
|
2581
|
|
|
2582 Another thing that @code{configure} can do is to edit the Makefile. If
|
|
|
2583 you do this, the distribution should @emph{not} contain a file named
|
|
|
2584 @file{Makefile}. Instead, it should include a file @file{Makefile.in} which
|
|
|
2585 contains the input used for editing. Once again, this is so that people
|
|
|
2586 won't be able to build the program without configuring it first.
|
|
|
2587
|
|
|
2588 If @code{configure} does write the @file{Makefile}, then @file{Makefile}
|
|
|
2589 should have a target named @file{Makefile} which causes @code{configure}
|
|
|
2590 to be rerun, setting up the same configuration that was set up last
|
|
|
2591 time. The files that @code{configure} reads should be listed as
|
|
|
2592 dependencies of @file{Makefile}.
|
|
|
2593
|
|
|
2594 All the files which are output from the @code{configure} script should
|
|
|
2595 have comments at the beginning explaining that they were generated
|
|
|
2596 automatically using @code{configure}. This is so that users won't think
|
|
|
2597 of trying to edit them by hand.
|
|
|
2598
|
|
|
2599 The @code{configure} script should write a file named @file{config.status}
|
|
|
2600 which describes which configuration options were specified when the
|
|
|
2601 program was last configured. This file should be a shell script which,
|
|
|
2602 if run, will recreate the same configuration.
|
|
|
2603
|
|
|
2604 The @code{configure} script should accept an option of the form
|
|
|
2605 @samp{--srcdir=@var{dirname}} to specify the directory where sources are found
|
|
|
2606 (if it is not the current directory). This makes it possible to build
|
|
|
2607 the program in a separate directory, so that the actual source directory
|
|
|
2608 is not modified.
|
|
|
2609
|
|
|
2610 If the user does not specify @samp{--srcdir}, then @code{configure} should
|
|
|
2611 check both @file{.} and @file{..} to see if it can find the sources. If
|
|
|
2612 it finds the sources in one of these places, it should use them from
|
|
|
2613 there. Otherwise, it should report that it cannot find the sources, and
|
|
|
2614 should exit with nonzero status.
|
|
|
2615
|
|
|
2616 Usually the easy way to support @samp{--srcdir} is by editing a
|
|
|
2617 definition of @code{VPATH} into the Makefile. Some rules may need to
|
|
|
2618 refer explicitly to the specified source directory. To make this
|
|
|
2619 possible, @code{configure} can add to the Makefile a variable named
|
|
|
2620 @code{srcdir} whose value is precisely the specified directory.
|
|
|
2621
|
|
|
2622 The @code{configure} script should also take an argument which specifies the
|
|
|
2623 type of system to build the program for. This argument should look like
|
|
|
2624 this:
|
|
|
2625
|
|
|
2626 @example
|
|
|
2627 @var{cpu}-@var{company}-@var{system}
|
|
|
2628 @end example
|
|
|
2629
|
|
|
2630 For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.
|
|
|
2631
|
|
|
2632 The @code{configure} script needs to be able to decode all plausible
|
|
|
2633 alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1}
|
|
|
2634 would be a valid alias. For many programs, @samp{vax-dec-ultrix} would
|
|
|
2635 be an alias for @samp{vax-dec-bsd}, simply because the differences
|
|
|
2636 between Ultrix and @sc{BSD} are rarely noticeable, but a few programs
|
|
|
2637 might need to distinguish them.
|
|
|
2638 @c Real 4.4BSD now runs on some Suns.
|
|
|
2639
|
|
|
2640 There is a shell script called @file{config.sub} that you can use
|
|
|
2641 as a subroutine to validate system types and canonicalize aliases.
|
|
|
2642
|
|
|
2643 Other options are permitted to specify in more detail the software
|
|
|
2644 or hardware present on the machine, and include or exclude optional
|
|
|
2645 parts of the package:
|
|
|
2646
|
|
|
2647 @table @samp
|
|
|
2648 @item --enable-@var{feature}@r{[}=@var{parameter}@r{]}
|
|
|
2649 Configure the package to build and install an optional user-level
|
|
|
2650 facility called @var{feature}. This allows users to choose which
|
|
|
2651 optional features to include. Giving an optional @var{parameter} of
|
|
|
2652 @samp{no} should omit @var{feature}, if it is built by default.
|
|
|
2653
|
|
|
2654 No @samp{--enable} option should @strong{ever} cause one feature to
|
|
|
2655 replace another. No @samp{--enable} option should ever substitute one
|
|
|
2656 useful behavior for another useful behavior. The only proper use for
|
|
|
2657 @samp{--enable} is for questions of whether to build part of the program
|
|
|
2658 or exclude it.
|
|
|
2659
|
|
|
2660 @item --with-@var{package}
|
|
|
2661 @c @r{[}=@var{parameter}@r{]}
|
|
|
2662 The package @var{package} will be installed, so configure this package
|
|
|
2663 to work with @var{package}.
|
|
|
2664
|
|
|
2665 @c Giving an optional @var{parameter} of
|
|
|
2666 @c @samp{no} should omit @var{package}, if it is used by default.
|
|
|
2667
|
|
|
2668 Possible values of @var{package} include @samp{x}, @samp{x-toolkit},
|
|
|
2669 @samp{gnu-as} (or @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and
|
|
|
2670 @samp{gdb}.
|
|
|
2671
|
|
|
2672 Do not use a @samp{--with} option to specify the file name to use to
|
|
|
2673 find certain files. That is outside the scope of what @samp{--with}
|
|
|
2674 options are for.
|
|
|
2675
|
|
|
2676 @item --nfp
|
|
|
2677 The target machine has no floating point processor.
|
|
|
2678
|
|
|
2679 @item --gas
|
|
|
2680 The target machine assembler is GAS, the GNU assembler.
|
|
|
2681 This is obsolete; users should use @samp{--with-gnu-as} instead.
|
|
|
2682
|
|
|
2683 @item --x
|
|
|
2684 The target machine has the X Window System installed.
|
|
|
2685 This is obsolete; users should use @samp{--with-x} instead.
|
|
|
2686 @end table
|
|
|
2687
|
|
|
2688 All @code{configure} scripts should accept all of these ``detail''
|
|
|
2689 options, whether or not they make any difference to the particular
|
|
|
2690 package at hand. In particular, they should accept any option that
|
|
|
2691 starts with @samp{--with-} or @samp{--enable-}. This is so users will
|
|
|
2692 be able to configure an entire GNU source tree at once with a single set
|
|
|
2693 of options.
|
|
|
2694
|
|
|
2695 You will note that the categories @samp{--with-} and @samp{--enable-}
|
|
|
2696 are narrow: they @strong{do not} provide a place for any sort of option
|
|
|
2697 you might think of. That is deliberate. We want to limit the possible
|
|
|
2698 configuration options in GNU software. We do not want GNU programs to
|
|
|
2699 have idiosyncratic configuration options.
|
|
|
2700
|
|
|
2701 Packages that perform part of the compilation process may support cross-compilation.
|
|
|
2702 In such a case, the host and target machines for the program may be
|
|
|
2703 different. The @code{configure} script should normally treat the
|
|
|
2704 specified type of system as both the host and the target, thus producing
|
|
|
2705 a program which works for the same type of machine that it runs on.
|
|
|
2706
|
|
|
2707 The way to build a cross-compiler, cross-assembler, or what have you, is
|
|
|
2708 to specify the option @samp{--host=@var{hosttype}} when running
|
|
|
2709 @code{configure}. This specifies the host system without changing the
|
|
|
2710 type of target system. The syntax for @var{hosttype} is the same as
|
|
|
2711 described above.
|
|
|
2712
|
|
|
2713 Bootstrapping a cross-compiler requires compiling it on a machine other
|
|
|
2714 than the host it will run on. Compilation packages accept a
|
|
|
2715 configuration option @samp{--build=@var{hosttype}} for specifying the
|
|
|
2716 configuration on which you will compile them, in case that is different
|
|
|
2717 from the host.
|
|
|
2718
|
|
|
2719 Programs for which cross-operation is not meaningful need not accept the
|
|
|
2720 @samp{--host} option, because configuring an entire operating system for
|
|
|
2721 cross-operation is not a meaningful thing.
|
|
|
2722
|
|
|
2723 Some programs have ways of configuring themselves automatically. If
|
|
|
2724 your program is set up to do this, your @code{configure} script can simply
|
|
|
2725 ignore most of its arguments.
|
|
|
2726
|
|
|
2727 @comment The makefile standards are in a separate file that is also
|
|
|
2728 @comment included by make.texinfo. Done by roland@gnu.ai.mit.edu on 1/6/93.
|
|
|
2729 @comment For this document, turn chapters into sections, etc.
|
|
|
2730 @lowersections
|
|
|
2731 @include make-stds.texi
|
|
|
2732 @raisesections
|
|
|
2733
|
|
|
2734 @node Releases
|
|
|
2735 @section Making Releases
|
|
|
2736
|
|
|
2737 Package the distribution of Foo version 69.96 in a gzipped tar file
|
|
|
2738 named @file{foo-69.96.tar.gz}. It should unpack into a subdirectory
|
|
|
2739 named @file{foo-69.96}.
|
|
|
2740
|
|
|
2741 Building and installing the program should never modify any of the files
|
|
|
2742 contained in the distribution. This means that all the files that form
|
|
|
2743 part of the program in any way must be classified into @dfn{source
|
|
|
2744 files} and @dfn{non-source files}. Source files are written by humans
|
|
|
2745 and never changed automatically; non-source files are produced from
|
|
|
2746 source files by programs under the control of the Makefile.
|
|
|
2747
|
|
|
2748 Naturally, all the source files must be in the distribution. It is okay
|
|
|
2749 to include non-source files in the distribution, provided they are
|
|
|
2750 up-to-date and machine-independent, so that building the distribution
|
|
|
2751 normally will never modify them. We commonly include non-source files
|
|
|
2752 produced by Bison, @code{lex}, @TeX{}, and @code{makeinfo}; this helps avoid
|
|
|
2753 unnecessary dependencies between our distributions, so that users can
|
|
|
2754 install whichever packages they want to install.
|
|
|
2755
|
|
|
2756 Non-source files that might actually be modified by building and
|
|
|
2757 installing the program should @strong{never} be included in the
|
|
|
2758 distribution. So if you do distribute non-source files, always make
|
|
|
2759 sure they are up to date when you make a new distribution.
|
|
|
2760
|
|
|
2761 Make sure that the directory into which the distribution unpacks (as
|
|
|
2762 well as any subdirectories) are all world-writable (octal mode 777).
|
|
|
2763 This is so that old versions of @code{tar} which preserve the
|
|
|
2764 ownership and permissions of the files from the tar archive will be
|
|
|
2765 able to extract all the files even if the user is unprivileged.
|
|
|
2766
|
|
|
2767 Make sure that all the files in the distribution are world-readable.
|
|
|
2768
|
|
|
2769 Make sure that no file name in the distribution is more than 14
|
|
|
2770 characters long. Likewise, no file created by building the program
|
|
|
2771 should have a name longer than 14 characters. The reason for this is
|
|
|
2772 that some systems adhere to a foolish interpretation of the POSIX
|
|
|
2773 standard, and refuse to open a longer name, rather than truncating as
|
|
|
2774 they did in the past.
|
|
|
2775
|
|
|
2776 Don't include any symbolic links in the distribution itself. If the tar
|
|
|
2777 file contains symbolic links, then people cannot even unpack it on
|
|
|
2778 systems that don't support symbolic links. Also, don't use multiple
|
|
|
2779 names for one file in different directories, because certain file
|
|
|
2780 systems cannot handle this and that prevents unpacking the
|
|
|
2781 distribution.
|
|
|
2782
|
|
|
2783 Try to make sure that all the file names will be unique on MS-DOS. A
|
|
|
2784 name on MS-DOS consists of up to 8 characters, optionally followed by a
|
|
|
2785 period and up to three characters. MS-DOS will truncate extra
|
|
|
2786 characters both before and after the period. Thus,
|
|
|
2787 @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they
|
|
|
2788 are truncated to @file{foobarha.c} and @file{foobarha.o}, which are
|
|
|
2789 distinct.
|
|
|
2790
|
|
|
2791 Include in your distribution a copy of the @file{texinfo.tex} you used
|
|
|
2792 to test print any @file{*.texinfo} or @file{*.texi} files.
|
|
|
2793
|
|
|
2794 Likewise, if your program uses small GNU software packages like regex,
|
|
|
2795 getopt, obstack, or termcap, include them in the distribution file.
|
|
|
2796 Leaving them out would make the distribution file a little smaller at
|
|
|
2797 the expense of possible inconvenience to a user who doesn't know what
|
|
|
2798 other files to get.
|
|
|
2799
|
|
|
2800 @contents
|
|
|
2801
|
|
|
2802 @bye
|
