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