Commit | Line | Data |
---|---|---|
b42b3782 RP |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename standards.text | |
4 | @settitle GNU Coding Standards | |
5 | @c %**end of header | |
6 | ||
7 | @setchapternewpage off | |
8 | ||
9 | @ifinfo | |
10 | Copyright (C) 1992 Free Software Foundation | |
11 | Permission is granted to make and distribute verbatim copies of | |
12 | this manual provided the copyright notice and this permission notice | |
13 | are preserved on all copies. | |
14 | ||
15 | @ignore | |
16 | Permission is granted to process this file through TeX and print the | |
17 | results, provided the printed document carries copying permission | |
18 | notice identical to this one except for the removal of this paragraph | |
19 | (this paragraph not being relevant to the printed manual). | |
20 | @end ignore | |
21 | ||
22 | Permission is granted to copy and distribute modified versions of this | |
23 | manual under the conditions for verbatim copying, provided that the entire | |
24 | resulting derived work is distributed under the terms of a permission | |
25 | notice identical to this one. | |
26 | ||
27 | Permission is granted to copy and distribute translations of this manual | |
28 | into another language, under the above conditions for modified versions, | |
29 | except that this permission notice may be stated in a translation approved | |
30 | by the Free Software Foundation. | |
31 | @end ifinfo | |
32 | ||
33 | @titlepage | |
34 | @sp 10 | |
35 | @titlefont{GNU Coding Standards} | |
36 | @author{Richard Stallman} | |
37 | @author{last updated 21 April 1992} | |
38 | @c Note date also appears below. | |
39 | @page | |
40 | ||
41 | @vskip 0pt plus 1filll | |
42 | Copyright @copyright{} 1992 Free Software Foundation | |
43 | ||
44 | Permission is granted to make and distribute verbatim copies of | |
45 | this manual provided the copyright notice and this permission notice | |
46 | are preserved on all copies. | |
47 | ||
48 | Permission is granted to copy and distribute modified versions of this | |
49 | manual under the conditions for verbatim copying, provided that the entire | |
50 | resulting derived work is distributed under the terms of a permission | |
51 | notice identical to this one. | |
52 | ||
53 | Permission is granted to copy and distribute translations of this manual | |
54 | into another language, under the above conditions for modified versions, | |
55 | except that this permission notice may be stated in a translation approved | |
56 | by Free Software Foundation. | |
57 | @end titlepage | |
58 | ||
59 | @ifinfo | |
60 | @node Top, Reading Non-Free Code, (dir), (dir) | |
61 | @top Version | |
62 | ||
63 | Last updated 21 April 1992. | |
64 | @c Note date also appears above. | |
65 | @end ifinfo | |
66 | ||
67 | @menu | |
68 | * Reading Non-Free Code:: Referring to Proprietary Programs | |
69 | * Contributions:: Accepting Contributions | |
70 | * Change Logs:: Recording Changes | |
71 | * Compatibility:: Compatibility with Other Implementations | |
72 | * Makefiles:: Makefile Conventions | |
73 | * Configuration:: How Configuration Should Work | |
74 | * Source Language:: Using Languages Other Than C | |
75 | * Formatting:: Formatting Your Source Code | |
76 | * Comments:: Commenting Your Work | |
77 | * Syntactic Conventions:: Clean Use of C Constructs | |
78 | * Names:: Naming Variables and Functions | |
79 | * Using Extensions:: Using Non-standard Features | |
80 | * Semantics:: Program Behaviour for All Programs | |
81 | * Errors:: Formatting Error Messages | |
82 | * Libraries:: Library Behaviour | |
83 | * Portability:: Portability As It Applies to GNU | |
84 | * User Interfaces:: Standards for Command Line Interfaces | |
85 | * Documentation:: Documenting Programs | |
86 | * Releases:: Making Releases | |
87 | @end menu | |
88 | ||
89 | @node Reading Non-Free Code | |
90 | @chapter Referring to Proprietary Programs | |
91 | ||
92 | Don't in any circumstances refer to Unix source code for or during | |
93 | your work on GNU! (Or to any other proprietary programs.) | |
94 | ||
95 | If you have a vague recollection of the internals of a Unix program, | |
96 | this does not absolutely mean you can't write an imitation of it, but | |
97 | do try to organize the imitation internally along different lines, | |
98 | because this is likely to make the details of the Unix version | |
99 | irrelevant and dissimilar to your results. | |
100 | ||
101 | For example, Unix utilities were generally optimized to minimize | |
102 | memory use; if you go for speed instead, your program will be very | |
103 | different. You could keep the entire input file in core and scan it | |
104 | there instead of using stdio. Use a smarter algorithm discovered more | |
105 | recently than the Unix program. Eliminate use of temporary files. Do | |
106 | it in one pass instead of two (we did this in the assembler). | |
107 | ||
108 | Or, on the contrary, emphasize simplicity instead of speed. For some | |
109 | applications, the speed of today's computers makes simpler algorithms | |
110 | adequate. | |
111 | ||
112 | Or go for generality. For example, Unix programs often have static | |
113 | tables or fixed-size strings, which make for arbitrary limits; use | |
114 | dynamic allocation instead. Make sure your program handles NULs and | |
115 | other funny characters in the input files. Add a programming language | |
116 | for extensibility and write part of the program in that language. | |
117 | ||
118 | Or turn some parts of the program into independently usable libraries. | |
119 | Or use a simple garbage collector instead of tracking precisely when | |
120 | to free memory, or use a new GNU facility such as obstacks. | |
121 | ||
122 | ||
123 | @node Contributions | |
124 | @chapter Accepting Contributions | |
125 | ||
126 | If someone else sends you a piece of code to add to the program you are | |
127 | working on, we need legal papers to use it---the same sort of legal | |
128 | papers we will need to get from you. @emph{Each} significant | |
129 | contributor to a program must sign some sort of legal papers in order | |
130 | for us to have clear title to the program. The main author alone is not | |
131 | enough. | |
132 | ||
133 | So, before adding in any contributions from other people, tell us | |
134 | so we can arrange to get the papers. Then wait until we tell you | |
135 | that we have received the signed papers, before you actually use the | |
136 | contribution. | |
137 | ||
138 | This applies both before you release the program and afterward. If | |
139 | you receive diffs to fix a bug, and they make significant change, we | |
140 | need legal papers for it. | |
141 | ||
142 | You don't need papers for changes of a few lines here or there, since | |
143 | they are not significant for copyright purposes. Also, you don't need | |
144 | papers if all you get from the suggestion is some ideas, not actual code | |
145 | which you use. For example, if you write a different solution to the | |
146 | problem, you don't need to get papers. | |
147 | ||
148 | I know this is frustrating; it's frustrating for us as well. But if | |
149 | you don't wait, you are going out on a limb---for example, what if the | |
150 | contributor's employer won't sign a disclaimer? You might have to take | |
151 | that code out again! | |
152 | ||
153 | The very worst thing is if you forget to tell us about the other | |
154 | contributor. We could be very embarrassed in court some day as a | |
155 | result. | |
156 | ||
157 | @node Change Logs | |
158 | @chapter Change Logs | |
159 | ||
160 | Keep a change log for each directory, describing the changes made to | |
161 | source files in that directory. The purpose of this is so that people | |
162 | investigating bugs in the future will know about the changes that | |
163 | might have introduced the bug. Often a new bug can be found by | |
164 | looking at what was recently changed. More importantly, change logs | |
165 | can help eliminate conceptual inconsistencies between different parts | |
166 | of a program; they can give you a history of how the conflicting | |
167 | concepts arose. | |
168 | ||
169 | Use the Emacs command @kbd{M-x add-change} to start a new entry in the | |
170 | change log. An entry should have an asterisk, the name of the changed | |
171 | file, and then in parentheses the name of the changed functions, | |
172 | variables or whatever, followed by a colon. Then describe the changes | |
173 | you made to that function or variable. | |
174 | ||
175 | Separate unrelated entries with blank lines. When two entries | |
176 | represent parts of the same change, so that they work together, then | |
177 | don't put blank lines between them. Then you can omit the file name | |
178 | and the asterisk when successive entries are in the same file. | |
179 | ||
180 | Here are some examples: | |
181 | ||
182 | @example | |
183 | * register.el (insert-register): Return nil. | |
184 | (jump-to-register): Likewise. | |
185 | ||
186 | * sort.el (sort-subr): Return nil. | |
187 | ||
188 | * tex-mode.el (tex-bibtex-file, tex-file, tex-region): | |
189 | Restart the tex shell if process is gone or stopped. | |
190 | (tex-shell-running): New function. | |
191 | ||
192 | * expr.c (store_one_arg): Round size up for move_block_to_reg. | |
193 | (expand_call): Round up when emitting USE insns. | |
194 | * stmt.c (assign_parms): Round size up for move_block_from_reg. | |
195 | @end example | |
196 | ||
197 | There's no need to describe here the full purpose of the changes or how | |
198 | they work together. It is better to put this explanation in comments in | |
199 | the code. That's why just ``New function'' is enough; there is a | |
200 | comment with the function in the source to explain what it does. | |
201 | ||
202 | However, sometimes it is useful to write one line to describe the | |
203 | overall purpose of a large batch of changes. | |
204 | ||
205 | When you change the calling sequence of a function in a simple | |
206 | fashion, and you change all the callers of the function, there is no | |
207 | need to make individual entries for all the callers. Just write in | |
208 | the entry for the function being called, ``All callers changed.'' | |
209 | ||
210 | When you change just comments or doc strings, it is enough to write an | |
211 | entry for the file, without mentioning the functions. Write just, | |
212 | ``Doc fix.'' There's no need to keep a change log for documentation | |
213 | files. This is because documentation is not susceptible to bugs that | |
214 | are hard to fix. Documentation does not consist of parts that must | |
215 | interact in a precisely engineered fashion; to correct an error, you | |
216 | need not know the history of the erroneous passage. | |
217 | ||
218 | ||
219 | @node Compatibility | |
220 | @chapter Compatibility with Other Implementations | |
221 | ||
222 | With certain exceptions, utility programs and libraries for GNU should | |
223 | be upward compatible with those in Berkeley Unix, and upward compatible | |
224 | with @sc{ANSI} C if @sc{ANSI} C specifies their behavior, and upward | |
225 | compatible with @sc{POSIX} if @sc{POSIX} specifies their behavior. | |
226 | ||
227 | When these standards conflict, it is useful to offer compatibility | |
228 | modes for each of them. | |
229 | ||
230 | @sc{ANSI} C and @sc{POSIX} prohibit many kinds of extensions. Feel | |
231 | free to make the extensions anyway, and include a @samp{--ansi} or | |
232 | @samp{--compatible} option to turn them off. However, if the extension | |
233 | has a significant chance of breaking any real programs or scripts, | |
234 | then it is not really upward compatible. Try to redesign its | |
235 | interface. | |
236 | ||
237 | When a feature is used only by users (not by programs or command | |
238 | files), and it is done poorly in Unix, feel free to replace it | |
239 | completely with something totally different and better. (For example, | |
240 | vi is replaced with Emacs.) But it is nice to offer a compatible | |
241 | feature as well. (There is a free vi clone, so we offer it.) | |
242 | ||
243 | Additional useful features not in Berkeley Unix are welcome. | |
244 | Additional programs with no counterpart in Unix may be useful, | |
245 | but our first priority is usually to duplicate what Unix already | |
246 | has. | |
247 | ||
248 | ||
249 | @node Makefiles | |
250 | @chapter Makefile Conventions | |
251 | ||
252 | This chapter describes conventions for writing Makefiles. | |
253 | ||
254 | @menu | |
255 | * Makefile Basics:: | |
256 | * Standard Targets:: | |
257 | * Command Variables:: | |
258 | * Directory Variables:: | |
259 | @end menu | |
260 | ||
261 | @node Makefile Basics | |
262 | @section General Conventions for Makefiles | |
263 | ||
264 | Every Makefile should contain this line: | |
265 | ||
266 | @example | |
267 | SHELL = /bin/sh | |
268 | @end example | |
269 | ||
270 | @noindent | |
271 | to avoid trouble on systems where the @code{SHELL} variable might be | |
272 | inherited from the environment. | |
273 | ||
274 | Don't assume that @file{.} is in the path for command execution. When | |
275 | you need to run programs that are files in the current directory, always | |
276 | use @file{./} to make sure the proper file is run regardless of the | |
277 | current path. | |
278 | ||
279 | @node Standard Targets | |
280 | @section Standard Targets for Users | |
281 | ||
282 | All GNU programs should have the following targets in their Makefiles: | |
283 | ||
284 | @table @samp | |
285 | @item all | |
286 | Compile the entire program. | |
287 | ||
288 | @item install | |
289 | Compile the program and copy the executables, libraries, and so on to | |
290 | the file names where they should reside for actual use. If there is a | |
291 | simple test to verify that a program is properly installed then run that | |
292 | test. | |
293 | ||
294 | @item clean | |
295 | Delete all files from the current directory that are normally created by | |
296 | building the program. Don't delete the files that record the | |
297 | configuration. Also preserve files that could be made by building, but | |
298 | normally aren't because the distribution comes with them. | |
299 | ||
300 | @item distclean | |
301 | Delete all files from the current directory that are created by | |
302 | configuring or building the program. This should leave only the files | |
303 | that would be in the distribution. | |
304 | ||
305 | @item mostlyclean | |
306 | Like @samp{clean}, but may refrain from deleting a few files that people | |
307 | normally don't want to recompile. For example, the @samp{mostlyclean} | |
308 | target for GCC does not delete @file{libgcc.a}, because recompiling it | |
309 | is rarely necessary and takes a lot of time. | |
310 | ||
311 | @item realclean | |
312 | Delete everything from the current directory that can be reconstructed | |
313 | with this Makefile. This typically includes everything deleted by | |
314 | distclean, plus more: C source files produced by Bison, tags tables, | |
315 | info files, and so on. | |
316 | ||
317 | @item TAGS | |
318 | Update a tags table for this program. | |
319 | ||
320 | @item dist | |
321 | Create a distribution tar file for this program. The tar file should be | |
322 | set up so that the file names in the tar file start with a subdirectory | |
323 | name which is the name of the package it is a distribution for. This | |
324 | name can include the version number. | |
325 | ||
326 | For example, the distribution tar file of GCC version 1.40 unpacks into | |
327 | a subdirectory named @file{gcc-1.40}. | |
328 | ||
329 | The easiest way to do this is to create a subdirectory appropriately | |
330 | named, use @code{ln} or @code{cp} to install the proper files in it, and | |
331 | then @code{tar} that subdirectory. | |
332 | ||
333 | The @code{dist} target should explicitly depend on all non-source files | |
334 | that are in the distribution, to make sure they are up to date in the | |
335 | distribution. @xref{Releases}. | |
336 | ||
337 | @item check | |
338 | Perform self-tests (if any). The user must build the program before | |
339 | running the tests, but need not install the program; you should write | |
340 | the self-tests so that they work when the program is built but not | |
341 | installed. | |
342 | @end table | |
343 | ||
344 | @node Command Variables | |
345 | @section Variables for Specifying Commands | |
346 | ||
347 | Makefiles should provide variables for overriding certain commands, options, | |
348 | and so on. | |
349 | ||
350 | In particular, you should run most utility programs via variables. | |
351 | Thus, if you use Bison, have a variable named @code{BISON} whose default | |
352 | value is set with @samp{BISON = bison}, and refer to it with | |
353 | @code{$(BISON)} whenever you need to use Bison. | |
354 | ||
355 | Each program-name variable should come with an options variable that is | |
356 | used to supply options to the program. Append @samp{FLAGS} to the | |
357 | program-name variable name to get the options variable name---for | |
358 | example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to | |
359 | this rule, but we keep it because it is standard.) | |
360 | ||
361 | File-management utilities such as @code{ln}, @code{rm}, @code{mv}, and | |
362 | so on need not be referred to through variables in this way, since users | |
363 | don't need to replace them with other programs. | |
364 | ||
365 | Every Makefile should define the variable @code{INSTALL}, which is the | |
366 | basic command for installing a file into the system. | |
367 | ||
368 | Every Makefile should also define variables @code{INSTALL_PROGRAM} and | |
369 | @code{INSTALL_DATA}. (The default for each of these should be | |
370 | @code{$(INSTALL)}.) Then it should use those variables as the commands | |
371 | for actual installation, for executables and nonexecutables | |
372 | respectively. Use these variables as follows: | |
373 | ||
374 | @example | |
375 | $(INSTALL_PROGRAM) foo $@{bindir@}/foo | |
376 | $(INSTALL_DATA) libfoo.a $@{libdir@}/libfoo.a | |
377 | @end example | |
378 | ||
379 | @noindent | |
380 | (Always use a file name, not a directory name, as the second argument. | |
381 | Use a separate command for each file to be installed.) | |
382 | ||
383 | @node Directory Variables | |
384 | @section Variables for Installation Directories | |
385 | ||
386 | Installation directories should always be named by variables, so it is | |
387 | easy to install in a nonstandard place. The standard names for these | |
388 | variables are: | |
389 | ||
390 | @table @samp | |
391 | @item bindir | |
392 | The directory for installing executable programs that users can run. | |
393 | This should normally be @file{/usr/local/bin}, but it should be based on | |
394 | the value of @code{$(prefix)}. | |
395 | ||
396 | @item datadir | |
397 | The directory for installing read-only data files which the programs | |
398 | refer to while they run. This directory is used for files which are | |
399 | independent of the type of machine being used. This should normally be | |
400 | @file{/usr/local/lib}, but it should be based on the value of | |
401 | @code{$(prefix)}. | |
402 | ||
403 | @item statedir | |
404 | The directory for installing data files which the programs modify while | |
405 | they run. These files should be independent of the type of machine | |
406 | being used, and it should be possible to share them among machines at a | |
407 | network installation. This should normally be @file{/usr/local/lib}, | |
408 | but it should be based on the value of @code{$(prefix)}. | |
409 | ||
410 | @item libdir | |
411 | The directory for installing executable files to be run by the program | |
412 | rather than by users. Object files and libraries of object code should | |
413 | also go in this directory. The idea is that this directory is used for | |
414 | files that pertain to a specific machine architecture. This should | |
415 | normally be @file{/usr/local/lib}, but it should be based on the value of | |
416 | @code{$(prefix)}. | |
417 | ||
418 | @item includedir | |
419 | The directory for installing @samp{#include} header files to be included | |
420 | by user programs. This should normally be @file{/usr/local/include}, | |
421 | but it should be based on the value of @code{$(prefix)}. | |
422 | ||
423 | Most compilers other than GCC do not look for header files in | |
424 | @file{/usr/local/include}. So installing the header files this way is | |
425 | only useful with GCC. Sometimes this is not a problem because some | |
426 | libraries are only really intended to work with GCC. But some libraries | |
427 | are intended to work with other compilers. They should install their | |
428 | header files in two places, one specified by includedir and one | |
429 | specified by oldincludedir | |
430 | ||
431 | @item oldincludedir | |
432 | The directory for installing @samp{#include} header files for use with | |
433 | compilers other than GCC. This should normally be @file{/usr/include}. | |
434 | ||
435 | The Makefile commands should check whether the value of | |
436 | @code{oldincludedir} is empty. If it is, they should not try to use | |
437 | it; they should cancel the second installation of the header files. | |
438 | ||
439 | @item mandir | |
440 | The directory for installing the man pages (if any) for this package. | |
441 | It should include the suffix for the proper section of the | |
442 | manual---usually @samp{1} for a utility. | |
443 | ||
444 | @item man1dir | |
445 | The directory for installing section 1 man pages. | |
446 | @item man2dir | |
447 | The directory for installing section 2 man pages. | |
448 | @item @dots{} | |
449 | Use these names instead of @samp{mandir} if the package needs to install man | |
450 | pages in more than one section of the manual. | |
451 | ||
452 | @strong{Don't make the primary documentation for any GNU software be a | |
453 | man page. Write a manual in Texinfo instead. Man pages are just for | |
454 | the sake of people running GNU software on Unix, which is a secondary | |
455 | application only.} | |
456 | ||
457 | @item manext | |
458 | The file name extension for the installed man page. This should contain | |
459 | a period followed by the appropriate digit. | |
460 | ||
461 | @item infodir | |
462 | The directory for installing the info files for this package. By | |
463 | default, it should be @file{/usr/local/info}, but it should be based on the | |
464 | value of @code{$(prefix)}. | |
465 | ||
466 | @item srcdir | |
467 | The directory for the sources being compiled. The value of this | |
468 | variable is normally inserted by the @code{configure} shell script. | |
469 | ||
470 | @item prefix | |
471 | A prefix used in constructing the default values of the variables listed | |
472 | above. The default value of @code{prefix} should be @file{/usr/local} | |
473 | (at least for now). | |
474 | @end table | |
475 | ||
476 | For example: | |
477 | ||
478 | @example | |
479 | # Common prefix for installation directories. | |
480 | # NOTE: This directory must exist when you start installation. | |
481 | prefix = /usr/local | |
482 | # Directory in which to put the executable for the command `gcc' | |
483 | bindir = $(prefix)/bin | |
484 | # Directory in which to put the directories used by the compiler. | |
485 | libdir = $(prefix)/lib | |
486 | @end example | |
487 | ||
488 | ||
489 | @node Configuration | |
490 | @chapter How Configuration Should Work | |
491 | ||
492 | Each GNU distribution should come with a shell script named | |
493 | @code{configure}. This script is given arguments which describe the | |
494 | kind of machine and system you want to compile the program for. | |
495 | ||
496 | The @code{configure} script must record the configuration options so | |
497 | that they affect compilation. | |
498 | ||
499 | One way to do this is to make a link from a standard name such as | |
500 | @file{config.h} to the proper configuration file for the chosen system. | |
501 | If you use this technique, the distribution should @emph{not} contain a | |
502 | file named @file{config.h}. This is so that people won't be able to | |
503 | build the program without configuring it first. | |
504 | ||
505 | Another thing that @code{configure} can do is to edit the Makefile. If | |
506 | you do this, the distribution should @emph{not} contain a file named | |
507 | @file{Makefile}. Instead, include a file @file{Makefile.in} which | |
508 | contains the input used for editing. Once again, this is so that people | |
509 | won't be able to build the program without configuring it first. | |
510 | ||
511 | If @code{configure} does write the @file{Makefile}, then @file{Makefile} | |
512 | should have a target named @file{Makefile} which causes @code{configure} | |
513 | to be rerun, setting up the same configuration that was set up last | |
514 | time. The files that @code{configure} reads should be listed as | |
515 | dependencies of @file{Makefile}. | |
516 | ||
517 | All the files which are output from the @code{configure} script should | |
518 | have comments at the beginning explaining that they were generated | |
519 | automatically using @code{configure}. This is so that users won't think | |
520 | of trying to edit them by hand. | |
521 | ||
522 | The @code{configure} script should write a file named @file{config.status} | |
523 | which describes which configuration options were specified when the | |
524 | program was last configured. This file should be a shell script which, | |
525 | if run, will recreate the same configuration. | |
526 | ||
527 | The @code{configure} script should accept an option of the form | |
528 | @samp{--srcdir=@var{dirname}} to specify the directory where sources are found | |
529 | (if it is not the current directory). This makes it possible to build | |
530 | the program in a separate directory, so that the actual source directory | |
531 | is not modified. | |
532 | ||
533 | If the user does not specify @samp{--srcdir}, then @code{configure} should | |
534 | check both @file{.} and @file{..} to see if it can find the sources. If | |
535 | it finds the sources in one of these places, it should use them from | |
536 | there. Otherwise, it should report that it cannot find the sources, and | |
537 | should exit with nonzero status. | |
538 | ||
539 | Usually the easy way to support @samp{--srcdir} is by editing a | |
540 | definition of @code{VPATH} into the Makefile. Some rules may need to | |
541 | refer explicitly to the specified source directory. To make this | |
542 | possible, @code{configure} can add to the Makefile a variable named | |
543 | @code{srcdir} whose value is precisely the specified directory. | |
544 | ||
545 | The @code{configure} script should also take an argument which specifies the | |
546 | type of system to build the program for. This argument should look like | |
547 | this: | |
548 | ||
549 | @example | |
550 | @var{cpu}-@var{company}-@var{system} | |
551 | @end example | |
552 | ||
553 | For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}. | |
554 | ||
555 | The @code{configure} script needs to be able to decode all plausible | |
556 | alternatives for how to describe a machine. Thus, @samp{sun3-sunos4.1} | |
557 | would be a valid alias. So would @samp{sun3-bsd4.2}, since Sunos is | |
558 | basically @sc{BSD} and no other @sc{BSD} system is used on a Sun. For many | |
559 | programs, @samp{vax-dec-ultrix} would be an alias for | |
560 | @samp{vax-dec-bsd}, simply because the differences between Ultrix and | |
561 | @sc{BSD} are rarely noticeable, but a few programs might need to distinguish | |
562 | them. | |
563 | ||
564 | There is a shell script called @file{config.sub} that you can use | |
565 | as a subroutine to validate system types and canonicalize aliases. | |
566 | ||
567 | Other options are permitted to specify in more detail the software | |
568 | or hardware are present on the machine: | |
569 | ||
570 | @table @samp | |
571 | @item --with-@var{package} | |
572 | The package @var{package} will be installed, so configure this package | |
573 | to work with @var{package}. | |
574 | ||
575 | Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or | |
576 | @samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}. | |
577 | ||
578 | @item --nfp | |
579 | The target machine has no floating point processor. | |
580 | ||
581 | @item --gas | |
582 | The target machine assembler is GAS, the GNU assembler. | |
583 | This is obsolete; use @samp{--with-gnu-as} instead. | |
584 | ||
585 | @item --x | |
586 | The target machine has the X Window system installed. | |
587 | This is obsolete; use @samp{--with-x} instead. | |
588 | @end table | |
589 | ||
590 | All @code{configure} scripts should accept all of these ``detail'' | |
591 | options, whether or not they make any difference to the particular | |
592 | package at hand. In particular, they should accept any option that | |
593 | starts with @samp{--with-}. This is so users will be able to configure | |
594 | an entire GNU source tree at once with a single set of options. | |
595 | ||
596 | Packages that perform part of compilation may support cross-compilation. | |
597 | In such a case, the host and target machines for the program may be | |
598 | different. The @code{configure} script should normally treat the | |
599 | specified type of system as both the host and the target, thus producing | |
600 | a program which works for the same type of machine that it runs on. | |
601 | ||
602 | The way to build a cross-compiler, cross-assembler, or what have you, is | |
603 | to specify the option @samp{--host=@var{hosttype}} when running | |
604 | @code{configure}. This specifies the host system without changing the | |
605 | type of target system. The syntax for @var{hosttype} is the same as | |
606 | described above. | |
607 | ||
608 | Programs for which cross-operation is not meaningful need not accept the | |
609 | @samp{--host} option, because configuring an entire operating system for | |
610 | cross-operation is not a meaningful thing. | |
611 | ||
612 | Some programs have ways of configuring themselves automatically. If | |
613 | your program is set up to do this, your @code{configure} script can simply | |
614 | ignore most of its arguments. | |
615 | ||
616 | ||
617 | @node Source Language | |
618 | @chapter Using Languages Other Than C | |
619 | ||
620 | Using a language other than C is like using a non-standard feature: it | |
621 | will cause trouble for users. Even if GCC supports the other language, | |
622 | users may find it inconvenient to have to install the compiler for that | |
623 | other language in order to build your program. So please write in C. | |
624 | ||
625 | There are three exceptions for this rule: | |
626 | ||
627 | @itemize @bullet | |
628 | @item | |
629 | It is okay to use a special language if the same program contains an | |
630 | interpreter for that language. | |
631 | ||
632 | Thus, it is not a problem that GNU Emacs contains code written in Emacs | |
633 | Lisp, because it comes with a Lisp interpreter. | |
634 | ||
635 | @item | |
636 | It is okay to use another language in a tool specifically intended for | |
637 | use with that language. | |
638 | ||
639 | This is okay because the only people who want to build the tool will be | |
640 | those who have installed the other language anyway. | |
641 | ||
642 | @item | |
643 | If an application is not of extremely widespread interest, then perhaps | |
644 | it's not important if the application is inconvenient to install. | |
645 | @end itemize | |
646 | ||
647 | @node Formatting | |
648 | @chapter Formatting Your Source Code | |
649 | ||
650 | It is important to put the open-brace that starts the body of a C | |
651 | function in column zero, and avoid putting any other open-brace or | |
652 | open-parenthesis or open-bracket in column zero. Several tools look | |
653 | for open-braces in column zero to find the beginnings of C functions. | |
654 | These tools will not work on code not formatted that way. | |
655 | ||
656 | It is also important for function definitions to start the name of the | |
657 | function in column zero. This helps people to search for function | |
658 | definitions, and may also help certain tools recognize them. Thus, | |
659 | the proper format is this: | |
660 | ||
661 | @example | |
662 | static char * | |
663 | concat (s1, s2) /* Name starts in column zero here */ | |
664 | char *s1, *s2; | |
665 | @{ /* Open brace in column zero here */ | |
666 | @dots{} | |
667 | @} | |
668 | @end example | |
669 | ||
670 | @noindent | |
671 | or, if you want to use @sc{ANSI} C, format the definition like this: | |
672 | ||
673 | @example | |
674 | static char * | |
675 | concat (char *s1, char *s2) | |
676 | @{ | |
677 | @dots{} | |
678 | @} | |
679 | @end example | |
680 | ||
681 | In @sc{ANSI} C, if the arguments don't fit nicely on one line, | |
682 | split it like this: | |
683 | ||
684 | @example | |
685 | int | |
686 | lots_of_args (int an_integer, long a_long, short a_short, | |
687 | double a_double, float a_float) | |
688 | @dots{} | |
689 | @end example | |
690 | ||
691 | For the body of the function, we prefer code formatted like this: | |
692 | ||
693 | @example | |
694 | if (x < foo (y, z)) | |
695 | haha = bar[4] + 5; | |
696 | else | |
697 | @{ | |
698 | while (z) | |
699 | @{ | |
700 | haha += foo (z, z); | |
701 | z--; | |
702 | @} | |
703 | return ++x + bar (); | |
704 | @} | |
705 | @end example | |
706 | ||
707 | We find it easier to read a program when it has spaces before the | |
708 | open-parentheses and after the commas. Especially after the commas. | |
709 | ||
710 | When you split an expression into multiple lines, split it | |
711 | before an operator, not after one. Here is the right way: | |
712 | ||
713 | @example | |
714 | if (foo_this_is_long && bar > win (x, y, z) | |
715 | && remaining_condition) | |
716 | @end example | |
717 | ||
718 | Try to avoid having two operators of different precedence at the same | |
719 | level of indentation. For example, don't write this: | |
720 | ||
721 | @example | |
722 | mode = (inmode[j] == VOIDmode | |
723 | || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]) | |
724 | ? outmode[j] : inmode[j]); | |
725 | @end example | |
726 | ||
727 | Instead, use extra parentheses so that the indentation shows the nesting: | |
728 | ||
729 | @example | |
730 | mode = ((inmode[j] == VOIDmode | |
731 | || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j]))) | |
732 | ? outmode[j] : inmode[j]); | |
733 | @end example | |
734 | ||
735 | Insert extra parentheses so that Emacs will indent the code properly. | |
736 | For example, the following indentation looks nice if you do it by hand, | |
737 | but Emacs would mess it up: | |
738 | ||
739 | @example | |
740 | v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 | |
741 | + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000; | |
742 | @end example | |
743 | ||
744 | But adding a set of parentheses solves the problem: | |
745 | ||
746 | @example | |
747 | v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000 | |
748 | + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000); | |
749 | @end example | |
750 | ||
751 | Format do-while statements like this: | |
752 | ||
753 | @example | |
754 | do | |
755 | @{ | |
756 | a = foo (a); | |
757 | @} | |
758 | while (a > 0); | |
759 | @end example | |
760 | ||
761 | Please use formfeed characters (control-L) to divide the program into | |
762 | pages at logical places (but not within a function). It does not matter | |
763 | just how long the pages are, since they do not have to fit on a printed | |
764 | page. The formfeeds should appear alone on lines by themselves. | |
765 | ||
766 | ||
767 | @node Comments | |
768 | @chapter Commenting Your Work | |
769 | ||
770 | Every program should start with a comment saying briefly what it is for. | |
771 | Example: @samp{fmt - filter for simple filling of text}. | |
772 | ||
773 | Please put a comment on each function saying what the function does, | |
774 | what sorts of arguments it gets, and what the possible values of | |
775 | arguments mean and are used for. It is not necessary to duplicate in | |
776 | words the meaning of the C argument declarations, if a C type is being | |
777 | used in its customary fashion. If there is anything nonstandard about | |
778 | its use (such as an argument of type @code{char *} which is really the | |
779 | address of the second character of a string, not the first), or any | |
780 | possible values that would not work the way one would expect (such as, | |
781 | that strings containing newlines are not guaranteed to work), be sure | |
782 | to say so. | |
783 | ||
784 | Also explain the significance of the return value, if there is one. | |
785 | ||
786 | Please put two spaces after the end of a sentence in your comments, so | |
787 | that the Emacs sentence commands will work. Also, please write | |
788 | complete sentences and capitalize the first word. If a lower-case | |
789 | identifer comes at the beginning of a sentence, don't capitalize it! | |
790 | Changing the spelling makes it a different identifier. If you don't | |
791 | like starting a sentence with a lower case letter, write the sentence | |
792 | differently (e.g. ``The identifier lower-case is @dots{}''). | |
793 | ||
794 | The comment on a function is much clearer if you use the argument | |
795 | names to speak about the argument values. The variable name itself | |
796 | should be lower case, but write it in upper case when you are speaking | |
797 | about the value rather than the variable itself. Thus, ``the inode | |
798 | number @var{node_num}'' rather than ``an inode''. | |
799 | ||
800 | There is usually no purpose in restating the name of the function in | |
801 | the comment before it, because the reader can see that for himself. | |
802 | There might be an exception when the comment is so long that the function | |
803 | itself would be off the bottom of the screen. | |
804 | ||
805 | There should be a comment on each static variable as well, like this: | |
806 | ||
807 | @example | |
808 | /* Nonzero means truncate lines in the display; | |
809 | zero means continue them. */ | |
810 | ||
811 | int truncate_lines; | |
812 | @end example | |
813 | ||
814 | Every @samp{#endif} should have a comment, except in the case of short | |
815 | conditionals (just a few lines) that are not nested. The comment should | |
816 | state the condition of the conditional that is ending, @emph{including | |
817 | its sense}. @samp{#else} should have a comment describing the condition | |
818 | @emph{and sense} of the code that follows. For example: | |
819 | ||
820 | @example | |
821 | #ifdef foo | |
822 | @dots{} | |
823 | #else /* not foo */ | |
824 | @dots{} | |
825 | #endif /* not foo */ | |
826 | @end example | |
827 | ||
828 | @noindent | |
829 | but, by contrast, write the comments this way for a @samp{#ifndef}: | |
830 | ||
831 | @example | |
832 | #ifndef foo | |
833 | @dots{} | |
834 | #else /* foo */ | |
835 | @dots{} | |
836 | #endif /* foo */ | |
837 | @end example | |
838 | ||
839 | ||
840 | @node Syntactic Conventions | |
841 | @chapter Clean Use of C Constructs | |
842 | ||
843 | Please explicitly declare all arguments to functions. | |
844 | Don't omit them just because they are ints. | |
845 | ||
846 | Declarations of external functions and functions to appear later | |
847 | in the source file should all go in one place near the beginning of | |
848 | the file (somewhere before the first function definition in the file), | |
849 | or else should go in a header file. Don't put extern declarations | |
850 | inside functions. | |
851 | ||
852 | Don't declare multiple variables in one declaration that spans lines. | |
853 | Start a new declaration on each line, instead. For example, instead | |
854 | of this: | |
855 | ||
856 | @example | |
857 | int foo, | |
858 | bar; | |
859 | @end example | |
860 | ||
861 | @noindent | |
862 | write either this: | |
863 | ||
864 | @example | |
865 | int foo, bar; | |
866 | @end example | |
867 | ||
868 | @noindent | |
869 | or this: | |
870 | ||
871 | @example | |
872 | int foo; | |
873 | int bar; | |
874 | @end example | |
875 | ||
876 | @noindent | |
877 | (If they are global variables, each should have a comment preceding it | |
878 | anyway.) | |
879 | ||
880 | When you have an if-else statement nested in another if statement, | |
881 | always put braces around the if-else. Thus, never write like this: | |
882 | ||
883 | @example | |
884 | if (foo) | |
885 | if (bar) | |
886 | win (); | |
887 | else | |
888 | lose (); | |
889 | @end example | |
890 | ||
891 | @noindent | |
892 | always like this: | |
893 | ||
894 | @example | |
895 | if (foo) | |
896 | @{ | |
897 | if (bar) | |
898 | win (); | |
899 | else | |
900 | lose (); | |
901 | @} | |
902 | @end example | |
903 | ||
904 | If you have an if statement nested inside of an else statement, | |
905 | either write @code{else if} on one line, like this, | |
906 | ||
907 | @example | |
908 | if (foo) | |
909 | @dots{} | |
910 | else if (bar) | |
911 | @dots{} | |
912 | @end example | |
913 | ||
914 | @noindent | |
915 | with its then-part indented like the preceding then-part, or write the | |
916 | nested if within braces like this: | |
917 | ||
918 | @example | |
919 | if (foo) | |
920 | @dots{} | |
921 | else | |
922 | @{ | |
923 | if (bar) | |
924 | @dots{} | |
925 | @} | |
926 | @end example | |
927 | ||
928 | Don't declare both a structure tag and variables or typedefs in the | |
929 | same declaration. Instead, declare the structure tag separately | |
930 | and then use it to declare the variables or typedefs. | |
931 | ||
932 | Try to avoid assignments inside if-conditions. For example, don't | |
933 | write this: | |
934 | ||
935 | @example | |
936 | if ((foo = (char *) malloc (sizeof *foo)) == 0) | |
937 | fatal ("virtual memory exhausted"); | |
938 | @end example | |
939 | ||
940 | @noindent | |
941 | instead, write this: | |
942 | ||
943 | @example | |
944 | foo = (char *) malloc (sizeof *foo); | |
945 | if (foo == 0) | |
946 | fatal ("virtual memory exhausted"); | |
947 | @end example | |
948 | ||
949 | Don't make the program ugly to placate lint. Please don't insert any | |
950 | casts to void. Zero without a cast is perfectly fine as a null | |
951 | pointer constant. | |
952 | ||
953 | ||
954 | @node Names | |
955 | @chapter Naming Variables and Functions | |
956 | ||
957 | Please use underscores to separate words in a name, so that the Emacs | |
958 | word commands can be useful within them. Stick to lower case; reserve | |
959 | upper case for macros and enum constants, and for name-prefixes that | |
960 | follow a uniform convention. | |
961 | ||
962 | For example, you should use names like @code{ignore_space_change_flag}; | |
963 | don't use names like @code{iCantReadThis}. | |
964 | ||
965 | Variables that indicate whether command-line options have been | |
966 | specified should be named after the meaning of the option, not after | |
967 | the option-letter. A comment should state both the exact meaning of | |
968 | the option and its letter. For example, | |
969 | ||
970 | @example | |
971 | /* Ignore changes in horizontal whitespace (-b). */ | |
972 | int ignore_space_change_flag; | |
973 | @end example | |
974 | ||
975 | When you want to define names with constant integer values, use | |
976 | @code{enum} rather than @samp{#define}. GDB knows about enumeration | |
977 | constants. | |
978 | ||
979 | Use file names of 14 characters or less, to avoid creating gratuitous | |
980 | problems on System V. | |
981 | ||
982 | ||
983 | @node Using Extensions | |
984 | @chapter Using Non-standard Features | |
985 | ||
986 | Many GNU facilities that already exist support a number of convenient | |
987 | extensions over the comparable Unix facilities. Whether to use these | |
988 | extensions in implementing your program is a difficult question. | |
989 | ||
990 | On the one hand, using the extensions can make a cleaner program. | |
991 | On the other hand, people will not be able to build the program | |
992 | unless the other GNU tools are available. This might cause the | |
993 | program to work on fewer kinds of machines. | |
994 | ||
995 | With some extensions, it might be easy to provide both alternatives. | |
996 | For example, you can define functions with a ``keyword'' @code{INLINE} | |
997 | and define that as a macro to expand into either @code{inline} or | |
998 | nothing, depending on the compiler. | |
999 | ||
1000 | In general, perhaps it is best not to use the extensions if you can | |
1001 | straightforwardly do without them, but to use the extensions if they | |
1002 | are a big improvement. | |
1003 | ||
1004 | An exception to this rule are the large, established programs (such as | |
1005 | Emacs) which run on a great variety of systems. Such programs would | |
1006 | be broken by use of GNU extensions. | |
1007 | ||
1008 | Another exception is for programs that are used as part of | |
1009 | compilation: anything that must be compiled with other compilers in | |
1010 | order to bootstrap the GNU compilation facilities. If these require | |
1011 | the GNU compiler, then no one can compile them without having them | |
1012 | installed already. That would be no good. | |
1013 | ||
1014 | Since most computer systems do not yet implement @sc{ANSI} C, using the | |
1015 | @sc{ANSI} C features is effectively using a GNU extension, so the | |
1016 | same considerations apply. (Except for @sc{ANSI} features that we | |
1017 | discourage, such as trigraphs---don't ever use them.) | |
1018 | ||
1019 | @node Semantics | |
1020 | @chapter Program Behaviour for All Programs | |
1021 | ||
1022 | Avoid arbitrary limits on the length or number of @emph{any} data | |
1023 | structure, including filenames, lines, files, and symbols, by allocating | |
1024 | all data structures dynamically. In most Unix utilities, ``long lines | |
1025 | are silently truncated''. This is not acceptable in a GNU utility. | |
1026 | ||
1027 | Utilities reading files should not drop NUL characters, or any other | |
1028 | nonprinting characters @emph{including those with codes above 0177}. The | |
1029 | only sensible exceptions would be utilities specifically intended for | |
1030 | interface to certain types of printers that can't handle those characters. | |
1031 | ||
1032 | Check every system call for an error return, unless you know you wish to | |
1033 | ignore errors. Include the system error text (from @code{perror} or | |
1034 | equivalent) in @emph{every} error message resulting from a failing | |
1035 | system call, as well as the name of the file if any and the name of the | |
1036 | utility. Just ``cannot open foo.c'' or ``stat failed'' is not | |
1037 | sufficient. | |
1038 | ||
1039 | Check every call to @code{malloc} or @code{realloc} to see if it | |
1040 | returned zero. Check @code{realloc} even if you are making the block | |
1041 | smaller; in a system that rounds block sizes to a power of 2, | |
1042 | @code{realloc} may get a different block if you ask for less space. | |
1043 | ||
1044 | In Unix, @code{realloc} can destroy the storage block if it returns | |
1045 | zero. GNU @code{realloc} does not have this bug: if it fails, the | |
1046 | original block is unchanged. Feel free to assume the bug is fixed. If | |
1047 | you wish to run your program on Unix, and wish to avoid lossage in this | |
1048 | case, you can use the GNU @code{malloc}. | |
1049 | ||
1050 | You must expect @code{free} to alter the contents of the block that was | |
1051 | freed. Anything you want to fetch from the block, you must fetch before | |
1052 | calling @code{free}. | |
1053 | ||
1054 | Use @code{getopt_long} to decode arguments, unless the argument syntax | |
1055 | makes this unreasonable. | |
1056 | ||
1057 | When static storage is to be written in during program execution, use | |
1058 | explicit C code to initialize it. Reserve C initialized declarations | |
1059 | for data that will not be changed. | |
1060 | ||
1061 | Try to avoid low-level interfaces to obscure Unix data structures (such | |
1062 | as file directories, utmp, or the layout of kernel memory), since these | |
1063 | are less likely to work compatibly. If you need to find all the files | |
1064 | in a directory, use @code{readdir} or some other high-level interface. These | |
1065 | will be supported compatibly by GNU. | |
1066 | ||
1067 | By default, the GNU system will provide the signal handling | |
1068 | functions of @sc{BSD} and of @sc{POSIX}. So GNU software should be | |
1069 | written to use these. | |
1070 | ||
1071 | In error checks that detect ``impossible'' conditions, just abort. | |
1072 | There is usually no point in printing any message. These checks | |
1073 | indicate the existence of bugs. Whoever wants to fix the bugs will have | |
1074 | to read the source code and run a debugger. So explain the problem with | |
1075 | comments in the source. The relevant data will be in variables, which | |
1076 | are easy to examine with the debugger, so there is no point moving them | |
1077 | elsewhere. | |
1078 | ||
1079 | ||
1080 | @node Errors | |
1081 | @chapter Formatting Error Messages | |
1082 | ||
1083 | Error messages from compilers should look like this: | |
1084 | ||
1085 | @example | |
1086 | @var{source-file-name}:@var{lineno}: @var{message} | |
1087 | @end example | |
1088 | ||
1089 | Error messages from other noninteractive programs should look like this: | |
1090 | ||
1091 | @example | |
1092 | @var{program}:@var{source-file-name}:@var{lineno}: @var{message} | |
1093 | @end example | |
1094 | ||
1095 | @noindent | |
1096 | when there is an appropriate source file, or like this: | |
1097 | ||
1098 | @example | |
1099 | @var{program}: @var{message} | |
1100 | @end example | |
1101 | ||
1102 | @noindent | |
1103 | when there is no relevant source file. | |
1104 | ||
1105 | In an interactive program (one that is reading commands from a | |
1106 | terminal), it is better not to include the program name in an error | |
1107 | message. The place to indicate which program is running is in the | |
1108 | prompt or with the screen layout. (When the same program runs with | |
1109 | input from a source other than a terminal, it is not interactive and | |
1110 | would do best to print error messages using the noninteractive style.) | |
1111 | ||
1112 | The string @var{message} should not begin with a capital letter when | |
1113 | it follows a program name and/or filename. Also, it should not end | |
1114 | with a period. | |
1115 | ||
1116 | Error messages from interactive programs, and other messages such as | |
1117 | usage messages, should start with a capital letter. But they should not | |
1118 | end with a period. | |
1119 | ||
1120 | ||
1121 | @node Libraries | |
1122 | @chapter Library Behaviour | |
1123 | ||
1124 | Try to make library functions reentrant. If they need to do dynamic | |
1125 | storage allocation, at least try to avoid any nonreentrancy aside from | |
1126 | that of @code{malloc} itself. | |
1127 | ||
1128 | Here are certain name conventions for libraries, to avoid name | |
1129 | conflicts. | |
1130 | ||
1131 | Choose a name prefix for the library, more than two characters long. | |
1132 | All external function and variable names should start with this | |
1133 | prefix. In addition, there should only be one of these in any given | |
1134 | library member. This usually means putting each one in a separate | |
1135 | source file. | |
1136 | ||
1137 | An exception can be made when two external symbols are always used | |
1138 | together, so that no reasonable program could use one without the | |
1139 | other; then they can both go in the same file. | |
1140 | ||
1141 | External symbols that are not documented entry points for the user | |
1142 | should have names beginning with @samp{_}. They should also contain | |
1143 | the chosen name prefix for the library, to prevent collisions with | |
1144 | other libraries. These can go in the same files with user entry | |
1145 | points if you like. | |
1146 | ||
1147 | Static functions and variables can be used as you like and need not | |
1148 | fit any naming convention. | |
1149 | ||
1150 | ||
1151 | @node Portability | |
1152 | @chapter Portability As It Applies to GNU | |
1153 | ||
1154 | Much of what is called ``portability'' in the Unix world refers to | |
1155 | porting to different Unix versions. This is not relevant to GNU | |
1156 | software, because its purpose is to run on top of one and only | |
1157 | one kernel, the GNU kernel, compiled with one and only one C | |
1158 | compiler, the GNU C compiler. The amount and kinds of variation | |
1159 | among GNU systems on different cpu's will be like the variation | |
1160 | among Berkeley 4.3 systems on different cpu's. | |
1161 | ||
1162 | It is difficult to be sure exactly what facilities the GNU kernel | |
1163 | will provide, since it isn't finished yet. Therefore, assume you can | |
1164 | use anything in 4.3; just avoid using the format of semi-internal data | |
1165 | bases (e.g., directories) when there is a higher-level alternative | |
1166 | (readdir). | |
1167 | ||
1168 | You can freely assume any reasonably standard facilities in the C | |
1169 | language, libraries or kernel, because we will find it necessary to | |
1170 | support these facilities in the full GNU system, whether or not we | |
1171 | have already done so. The fact that there may exist kernels or C | |
1172 | compilers that lack these facilities is irrelevant as long as the GNU | |
1173 | kernel and C compiler support them. | |
1174 | ||
1175 | It remains necessary to worry about differences among cpu types, such | |
1176 | as the difference in byte ordering and alignment restrictions. It's | |
1177 | unlikely that 16-bit machines will ever be supported by GNU, so there | |
1178 | is no point in spending any time to consider the possibility that an | |
1179 | int will be less than 32 bits. | |
1180 | ||
1181 | You can assume that all pointers have the same format, regardless | |
1182 | of the type they point to, and that this is really an integer. | |
1183 | There are some weird machines where this isn't true, but they aren't | |
1184 | important; don't waste time catering to them. Besides, eventually | |
1185 | we will put function prototypes into all GNU programs, and that will | |
1186 | probably make your program work even on weird machines. | |
1187 | ||
1188 | Since some important machines (including the 68000) are big-endian, | |
1189 | it is important not to assume that the address of an int object | |
1190 | is also the address of its least-significant byte. Thus, don't | |
1191 | make the following mistake: | |
1192 | ||
1193 | @example | |
1194 | int c; | |
1195 | @dots{} | |
1196 | while ((c = getchar()) != EOF) | |
1197 | write(file_descriptor, &c, 1); | |
1198 | @end example | |
1199 | ||
1200 | You can assume that it is reasonable to use a meg of memory. Don't | |
1201 | strain to reduce memory usage unless it can get to that level. If | |
1202 | your program creates complicated data structures, just make them in | |
1203 | core and give a fatal error if malloc returns zero. | |
1204 | ||
1205 | If a program works by lines and could be applied to arbitrary | |
1206 | user-supplied input files, it should keep only a line in memory, because | |
1207 | this is not very hard and users will want to be able to operate on input | |
1208 | files that are bigger than will fit in core all at once. | |
1209 | ||
1210 | ||
1211 | @node User Interfaces | |
1212 | @chapter Standards for Command Line Interfaces | |
1213 | ||
1214 | Please don't make the behavior of a utility depend on the name used | |
1215 | to invoke it. It is useful sometimes to make a link to a utility | |
1216 | with a different name, and that should not change what it does. | |
1217 | ||
1218 | Instead, use a run time option or a compilation switch or both | |
1219 | to select among the alternate behaviors. | |
1220 | ||
1221 | It is a good idea to follow the @sc{POSIX} guidelines for the | |
1222 | command-line options of a program. The easiest way to do this is to use | |
1223 | @code{getopt} to parse them. Note that the GNU version of @code{getopt} | |
1224 | will normally permit options anywhere among the arguments unless the | |
1225 | special argument @samp{--} is used. This is not what @sc{POSIX} | |
1226 | specifies; it is a GNU extension. | |
1227 | ||
1228 | Please define long-named options that are equivalent to the | |
1229 | single-letter Unix-style options. We hope to make GNU more user | |
1230 | friendly this way. This is easy to do with the GNU function | |
1231 | @code{getopt_long}. | |
1232 | ||
1233 | It is usually a good idea for file names given as ordinary arguments | |
1234 | to be input files only; any output files would be specified using | |
1235 | options (preferably @samp{-o}). Even if you allow an output file name | |
1236 | as an ordinary argument for compatibility, try to provide a suitable | |
1237 | option as well. This will lead to more consistency among GNU | |
1238 | utilities, so that there are fewer idiosyncracies for users to | |
1239 | remember. | |
1240 | ||
1241 | Programs should support an option @samp{--version} which prints the | |
1242 | program's version number, and an option @samp{--help} which prints | |
1243 | option usage information. | |
1244 | ||
1245 | ||
1246 | @node Documentation | |
1247 | @chapter Documenting Programs | |
1248 | ||
1249 | Please use Texinfo for documenting GNU programs. See the Texinfo | |
1250 | manual, either the hardcopy or the version in the GNU Emacs Info | |
1251 | sub-system (@kbd{C-h i}). | |
1252 | ||
1253 | See existing GNU texinfo files (e.g. those under the @file{man/} | |
1254 | directory in the GNU Emacs Distribution) for examples. | |
1255 | ||
1256 | The title page of the manual should state the version of the program | |
1257 | which the manual applies to. The Top node of the manual should also | |
1258 | contain this information. If the manual is changing more frequently | |
1259 | than or independent of the program, also state a version number for | |
1260 | the manual in both of these places. | |
1261 | ||
1262 | The manual should document all command-line arguments and all | |
1263 | commands. It should give examples of their use. But don't organize | |
1264 | the manual as a list of features. Instead, organize it by the | |
1265 | concepts a user will have before reaching that point in the manual. | |
1266 | Address the goals that a user will have in mind, and explain how to | |
1267 | accomplish them. | |
1268 | ||
1269 | ||
1270 | @node Releases | |
1271 | @chapter Making Releases | |
1272 | ||
1273 | Package the distribution of Foo version 69.96 in a tar file named | |
1274 | @file{foo-69.96.tar}. It should unpack into a subdirectory named | |
1275 | @file{foo-69.96}. | |
1276 | ||
1277 | Building and installing the program should never modify any of the files | |
1278 | contained in the distribution. This means that all the files that form | |
1279 | part of the program in any way must be classified into @dfn{source | |
1280 | files} and @dfn{non-source files}. Source files are written by humans | |
1281 | and never changed automatically; non-source files are produced from | |
1282 | source files by programs under the control of the Makefile. | |
1283 | ||
1284 | Naturally, all the source files must be in the distribution. It is okay | |
1285 | to include non-source files in the distribution, provided they are | |
1286 | up-to-date and machine-independent, so that building the distribution | |
1287 | normally will never modify them. We commonly included non-source files | |
1288 | produced by Bison, Lex, @TeX{}, and Makeinfo; this helps avoid | |
1289 | unnecessary dependencies between our distributions, so that users can | |
1290 | install whichever packages they want to install. | |
1291 | ||
1292 | Non-source files that might actually be modified by building and | |
1293 | installing the program should @strong{never} be included in the | |
1294 | distribution. So if you do distribute non-source files, always make | |
1295 | sure they are up to date when you make a new distribution. | |
1296 | ||
1297 | Make sure that no file name in the distribution is no more than 14 | |
1298 | characters long. Nowadays, there are systems that adhere to a foolish | |
1299 | interpretation of the POSIX standard which holds that they should refuse | |
1300 | to open a longer name, rather than truncating as they did in the past. | |
1301 | ||
1302 | Try to make sure that all the file names will be unique on MS-DOG. A | |
1303 | name on MS-DOG consists of up to 8 characters, optionally followed by a | |
1304 | period and up to three characters. MS-DOG will truncate extra | |
1305 | characters both before and after the period. Thus, | |
1306 | @file{foobarhacker.c} and @file{foobarhacker.o} are not ambiguous; they | |
1307 | are truncated to @file{foobarhac.c} and @file{foobarhac.o}, which are | |
1308 | distinct. | |
1309 | ||
1310 | Include in your distribution a copy of the @file{texinfo.tex} you used | |
1311 | to test print any @file{*.texinfo} files. | |
1312 | ||
1313 | @bye |