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