OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [binutils-2.20.1/] [etc/] [standards.info] - Blame information for rev 280

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 205 julius
This is standards.info, produced by makeinfo version 4.8 from
2
./standards.texi.
3
 
4
INFO-DIR-SECTION GNU organization
5
START-INFO-DIR-ENTRY
6
* Standards: (standards).         GNU coding standards.
7
END-INFO-DIR-ENTRY
8
 
9
   The GNU coding standards, last updated July 22, 2007.
10
 
11
   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
12
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
13
 
14
   Permission is granted to copy, distribute and/or modify this document
15
under the terms of the GNU Free Documentation License, Version 1.2 or
16
any later version published by the Free Software Foundation; with no
17
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
18
Texts.  A copy of the license is included in the section entitled "GNU
19
Free Documentation License".
20
 
21

22
File: standards.info,  Node: Top,  Next: Preface,  Prev: (dir),  Up: (dir)
23
 
24
Version
25
*******
26
 
27
The GNU coding standards, last updated July 22, 2007.
28
 
29
   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
30
2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
31
 
32
   Permission is granted to copy, distribute and/or modify this document
33
under the terms of the GNU Free Documentation License, Version 1.2 or
34
any later version published by the Free Software Foundation; with no
35
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
36
Texts.  A copy of the license is included in the section entitled "GNU
37
Free Documentation License".
38
 
39
* Menu:
40
 
41
* Preface::                     About the GNU Coding Standards.
42
* Legal Issues::                Keeping free software free.
43
* Design Advice::               General program design.
44
* Program Behavior::            Program behavior for all programs
45
* Writing C::                   Making the best use of C.
46
* Documentation::               Documenting programs.
47
* Managing Releases::           The release process.
48
* References::                  Mentioning non-free software or documentation.
49
* GNU Free Documentation License::  Copying and sharing this manual.
50
* Index::
51
 
52

53
File: standards.info,  Node: Preface,  Next: Legal Issues,  Prev: Top,  Up: Top
54
 
55
1 About the GNU Coding Standards
56
********************************
57
 
58
The GNU Coding Standards were written by Richard Stallman and other GNU
59
Project volunteers.  Their purpose is to make the GNU system clean,
60
consistent, and easy to install.  This document can also be read as a
61
guide to writing portable, robust and reliable programs.  It focuses on
62
programs written in C, but many of the rules and principles are useful
63
even if you write in another programming language.  The rules often
64
state reasons for writing in a certain way.
65
 
66
   This release of the GNU Coding Standards was last updated July 22,
67
2007.
68
 
69
   If you did not obtain this file directly from the GNU project and
70
recently, please check for a newer version.  You can get the GNU Coding
71
Standards from the GNU web server in many different formats, including
72
the Texinfo source, PDF, HTML, DVI, plain text, and more, at:
73
`http://www.gnu.org/prep/standards/'.
74
 
75
   Corrections or suggestions for this document should be sent to
76
.  If you make a suggestion, please include a
77
suggested new wording for it; our time is limited.  We prefer a context
78
diff to the `standards.texi' or `make-stds.texi' files, but if you
79
don't have those files, please mail your suggestion anyway.
80
 
81
   These standards cover the minimum of what is important when writing a
82
GNU package.  Likely, the need for additional standards will come up.
83
Sometimes, you might suggest that such standards be added to this
84
document.  If you think your standards would be generally useful, please
85
do suggest them.
86
 
87
   You should also set standards for your package on many questions not
88
addressed or not firmly specified here.  The most important point is to
89
be self-consistent--try to stick to the conventions you pick, and try
90
to document them as much as possible.  That way, your program will be
91
more maintainable by others.
92
 
93
   The GNU Hello program serves as an example of how to follow the GNU
94
coding standards for a trivial program.
95
`http://www.gnu.org/software/hello/hello.html'.
96
 
97

98
File: standards.info,  Node: Legal Issues,  Next: Design Advice,  Prev: Preface,  Up: Top
99
 
100
2 Keeping Free Software Free
101
****************************
102
 
103
This chapter discusses how you can make sure that GNU software avoids
104
legal difficulties, and other related issues.
105
 
106
* Menu:
107
 
108
* Reading Non-Free Code::       Referring to proprietary programs.
109
* Contributions::               Accepting contributions.
110
* Trademarks::                  How we deal with trademark issues.
111
 
112

113
File: standards.info,  Node: Reading Non-Free Code,  Next: Contributions,  Up: Legal Issues
114
 
115
2.1 Referring to Proprietary Programs
116
=====================================
117
 
118
Don't in any circumstances refer to Unix source code for or during your
119
work on GNU!  (Or to any other proprietary programs.)
120
 
121
   If you have a vague recollection of the internals of a Unix program,
122
this does not absolutely mean you can't write an imitation of it, but
123
do try to organize the imitation internally along different lines,
124
because this is likely to make the details of the Unix version
125
irrelevant and dissimilar to your results.
126
 
127
   For example, Unix utilities were generally optimized to minimize
128
memory use; if you go for speed instead, your program will be very
129
different.  You could keep the entire input file in memory and scan it
130
there instead of using stdio.  Use a smarter algorithm discovered more
131
recently than the Unix program.  Eliminate use of temporary files.  Do
132
it in one pass instead of two (we did this in the assembler).
133
 
134
   Or, on the contrary, emphasize simplicity instead of speed.  For some
135
applications, the speed of today's computers makes simpler algorithms
136
adequate.
137
 
138
   Or go for generality.  For example, Unix programs often have static
139
tables or fixed-size strings, which make for arbitrary limits; use
140
dynamic allocation instead.  Make sure your program handles NULs and
141
other funny characters in the input files.  Add a programming language
142
for extensibility and write part of the program in that language.
143
 
144
   Or turn some parts of the program into independently usable
145
libraries.  Or use a simple garbage collector instead of tracking
146
precisely when to free memory, or use a new GNU facility such as
147
obstacks.
148
 
149

150
File: standards.info,  Node: Contributions,  Next: Trademarks,  Prev: Reading Non-Free Code,  Up: Legal Issues
151
 
152
2.2 Accepting Contributions
153
===========================
154
 
155
If the program you are working on is copyrighted by the Free Software
156
Foundation, then when someone else sends you a piece of code to add to
157
the program, we need legal papers to use it--just as we asked you to
158
sign papers initially.  _Each_ person who makes a nontrivial
159
contribution to a program must sign some sort of legal papers in order
160
for us to have clear title to the program; the main author alone is not
161
enough.
162
 
163
   So, before adding in any contributions from other people, please tell
164
us, so we can arrange to get the papers.  Then wait until we tell you
165
that we have received the signed papers, before you actually use the
166
contribution.
167
 
168
   This applies both before you release the program and afterward.  If
169
you receive diffs to fix a bug, and they make significant changes, we
170
need legal papers for that change.
171
 
172
   This also applies to comments and documentation files.  For copyright
173
law, comments and code are just text.  Copyright applies to all kinds of
174
text, so we need legal papers for all kinds.
175
 
176
   We know it is frustrating to ask for legal papers; it's frustrating
177
for us as well.  But if you don't wait, you are going out on a limb--for
178
example, what if the contributor's employer won't sign a disclaimer?
179
You might have to take that code out again!
180
 
181
   You don't need papers for changes of a few lines here or there, since
182
they are not significant for copyright purposes.  Also, you don't need
183
papers if all you get from the suggestion is some ideas, not actual code
184
which you use.  For example, if someone sent you one implementation, but
185
you write a different implementation of the same idea, you don't need to
186
get papers.
187
 
188
   The very worst thing is if you forget to tell us about the other
189
contributor.  We could be very embarrassed in court some day as a
190
result.
191
 
192
   We have more detailed advice for maintainers of programs; if you have
193
reached the stage of actually maintaining a program for GNU (whether
194
released or not), please ask us for a copy.  It is also available
195
online for your perusal: `http://www.gnu.org/prep/maintain/'.
196
 
197

198
File: standards.info,  Node: Trademarks,  Prev: Contributions,  Up: Legal Issues
199
 
200
2.3 Trademarks
201
==============
202
 
203
Please do not include any trademark acknowledgements in GNU software
204
packages or documentation.
205
 
206
   Trademark acknowledgements are the statements that such-and-such is a
207
trademark of so-and-so.  The GNU Project has no objection to the basic
208
idea of trademarks, but these acknowledgements feel like kowtowing, and
209
there is no legal requirement for them, so we don't use them.
210
 
211
   What is legally required, as regards other people's trademarks, is to
212
avoid using them in ways which a reader might reasonably understand as
213
naming or labeling our own programs or activities.  For example, since
214
"Objective C" is (or at least was) a trademark, we made sure to say
215
that we provide a "compiler for the Objective C language" rather than
216
an "Objective C compiler".  The latter would have been meant as a
217
shorter way of saying the former, but it does not explicitly state the
218
relationship, so it could be misinterpreted as using "Objective C" as a
219
label for the compiler rather than for the language.
220
 
221
   Please don't use "win" as an abbreviation for Microsoft Windows in
222
GNU software or documentation.  In hacker terminology, calling
223
something a "win" is a form of praise.  If you wish to praise Microsoft
224
Windows when speaking on your own, by all means do so, but not in GNU
225
software.  Usually we write the name "Windows" in full, but when
226
brevity is very important (as in file names and sometimes symbol
227
names), we abbreviate it to "w".  For instance, the files and functions
228
in Emacs that deal with Windows start with `w32'.
229
 
230

231
File: standards.info,  Node: Design Advice,  Next: Program Behavior,  Prev: Legal Issues,  Up: Top
232
 
233
3 General Program Design
234
************************
235
 
236
This chapter discusses some of the issues you should take into account
237
when designing your program.
238
 
239
* Menu:
240
 
241
* Source Language::             Which languages to use.
242
* Compatibility::               Compatibility with other implementations.
243
* Using Extensions::            Using non-standard features.
244
* Standard C::                  Using standard C features.
245
* Conditional Compilation::     Compiling code only if a conditional is true.
246
 
247

248
File: standards.info,  Node: Source Language,  Next: Compatibility,  Up: Design Advice
249
 
250
3.1 Which Languages to Use
251
==========================
252
 
253
When you want to use a language that gets compiled and runs at high
254
speed, the best language to use is C.  Using another language is like
255
using a non-standard feature: it will cause trouble for users.  Even if
256
GCC supports the other language, users may find it inconvenient to have
257
to install the compiler for that other language in order to build your
258
program.  For example, if you write your program in C++, people will
259
have to install the GNU C++ compiler in order to compile your program.
260
 
261
   C has one other advantage over C++ and other compiled languages: more
262
people know C, so more people will find it easy to read and modify the
263
program if it is written in C.
264
 
265
   So in general it is much better to use C, rather than the comparable
266
alternatives.
267
 
268
   But there are two exceptions to that conclusion:
269
 
270
   * It is no problem to use another language to write a tool
271
     specifically intended for use with that language.  That is because
272
     the only people who want to build the tool will be those who have
273
     installed the other language anyway.
274
 
275
   * If an application is of interest only to a narrow part of the
276
     community, then the question of which language it is written in
277
     has less effect on other people, so you may as well please
278
     yourself.
279
 
280
   Many programs are designed to be extensible: they include an
281
interpreter for a language that is higher level than C.  Often much of
282
the program is written in that language, too.  The Emacs editor
283
pioneered this technique.
284
 
285
   The standard extensibility interpreter for GNU software is GUILE
286
(`http://www.gnu.org/software/guile/'), which implements the language
287
Scheme (an especially clean and simple dialect of Lisp).  We don't
288
reject programs written in other "scripting languages" such as Perl and
289
Python, but using GUILE is very important for the overall consistency
290
of the GNU system.
291
 
292

293
File: standards.info,  Node: Compatibility,  Next: Using Extensions,  Prev: Source Language,  Up: Design Advice
294
 
295
3.2 Compatibility with Other Implementations
296
============================================
297
 
298
With occasional exceptions, utility programs and libraries for GNU
299
should be upward compatible with those in Berkeley Unix, and upward
300
compatible with Standard C if Standard C specifies their behavior, and
301
upward compatible with POSIX if POSIX specifies their behavior.
302
 
303
   When these standards conflict, it is useful to offer compatibility
304
modes for each of them.
305
 
306
   Standard C and POSIX prohibit many kinds of extensions.  Feel free
307
to make the extensions anyway, and include a `--ansi', `--posix', or
308
`--compatible' option to turn them off.  However, if the extension has
309
a significant chance of breaking any real programs or scripts, then it
310
is not really upward compatible.  So you should try to redesign its
311
interface to make it upward compatible.
312
 
313
   Many GNU programs suppress extensions that conflict with POSIX if the
314
environment variable `POSIXLY_CORRECT' is defined (even if it is
315
defined with a null value).  Please make your program recognize this
316
variable if appropriate.
317
 
318
   When a feature is used only by users (not by programs or command
319
files), and it is done poorly in Unix, feel free to replace it
320
completely with something totally different and better.  (For example,
321
`vi' is replaced with Emacs.)  But it is nice to offer a compatible
322
feature as well.  (There is a free `vi' clone, so we offer it.)
323
 
324
   Additional useful features are welcome regardless of whether there
325
is any precedent for them.
326
 
327

328
File: standards.info,  Node: Using Extensions,  Next: Standard C,  Prev: Compatibility,  Up: Design Advice
329
 
330
3.3 Using Non-standard Features
331
===============================
332
 
333
Many GNU facilities that already exist support a number of convenient
334
extensions over the comparable Unix facilities.  Whether to use these
335
extensions in implementing your program is a difficult question.
336
 
337
   On the one hand, using the extensions can make a cleaner program.
338
On the other hand, people will not be able to build the program unless
339
the other GNU tools are available.  This might cause the program to
340
work on fewer kinds of machines.
341
 
342
   With some extensions, it might be easy to provide both alternatives.
343
For example, you can define functions with a "keyword" `INLINE' and
344
define that as a macro to expand into either `inline' or nothing,
345
depending on the compiler.
346
 
347
   In general, perhaps it is best not to use the extensions if you can
348
straightforwardly do without them, but to use the extensions if they
349
are a big improvement.
350
 
351
   An exception to this rule are the large, established programs (such
352
as Emacs) which run on a great variety of systems.  Using GNU
353
extensions in such programs would make many users unhappy, so we don't
354
do that.
355
 
356
   Another exception is for programs that are used as part of
357
compilation: anything that must be compiled with other compilers in
358
order to bootstrap the GNU compilation facilities.  If these require
359
the GNU compiler, then no one can compile them without having them
360
installed already.  That would be extremely troublesome in certain
361
cases.
362
 
363

364
File: standards.info,  Node: Standard C,  Next: Conditional Compilation,  Prev: Using Extensions,  Up: Design Advice
365
 
366
3.4 Standard C and Pre-Standard C
367
=================================
368
 
369
1989 Standard C is widespread enough now that it is ok to use its
370
features in new programs.  There is one exception: do not ever use the
371
"trigraph" feature of Standard C.
372
 
373
   1999 Standard C is not widespread yet, so please do not require its
374
features in programs.  It is ok to use its features if they are present.
375
 
376
   However, it is easy to support pre-standard compilers in most
377
programs, so if you know how to do that, feel free.  If a program you
378
are maintaining has such support, you should try to keep it working.
379
 
380
   To support pre-standard C, instead of writing function definitions in
381
standard prototype form,
382
 
383
     int
384
     foo (int x, int y)
385
     ...
386
 
387
write the definition in pre-standard style like this,
388
 
389
     int
390
     foo (x, y)
391
          int x, y;
392
     ...
393
 
394
and use a separate declaration to specify the argument prototype:
395
 
396
     int foo (int, int);
397
 
398
   You need such a declaration anyway, in a header file, to get the
399
benefit of prototypes in all the files where the function is called.
400
And once you have the declaration, you normally lose nothing by writing
401
the function definition in the pre-standard style.
402
 
403
   This technique does not work for integer types narrower than `int'.
404
If you think of an argument as being of a type narrower than `int',
405
declare it as `int' instead.
406
 
407
   There are a few special cases where this technique is hard to use.
408
For example, if a function argument needs to hold the system type
409
`dev_t', you run into trouble, because `dev_t' is shorter than `int' on
410
some machines; but you cannot use `int' instead, because `dev_t' is
411
wider than `int' on some machines.  There is no type you can safely use
412
on all machines in a non-standard definition.  The only way to support
413
non-standard C and pass such an argument is to check the width of
414
`dev_t' using Autoconf and choose the argument type accordingly.  This
415
may not be worth the trouble.
416
 
417
   In order to support pre-standard compilers that do not recognize
418
prototypes, you may want to use a preprocessor macro like this:
419
 
420
     /* Declare the prototype for a general external function.  */
421
     #if defined (__STDC__) || defined (WINDOWSNT)
422
     #define P_(proto) proto
423
     #else
424
     #define P_(proto) ()
425
     #endif
426
 
427

428
File: standards.info,  Node: Conditional Compilation,  Prev: Standard C,  Up: Design Advice
429
 
430
3.5 Conditional Compilation
431
===========================
432
 
433
When supporting configuration options already known when building your
434
program we prefer using `if (... )' over conditional compilation, as in
435
the former case the compiler is able to perform more extensive checking
436
of all possible code paths.
437
 
438
   For example, please write
439
 
440
       if (HAS_FOO)
441
         ...
442
       else
443
         ...
444
 
445
instead of:
446
 
447
       #ifdef HAS_FOO
448
         ...
449
       #else
450
         ...
451
       #endif
452
 
453
   A modern compiler such as GCC will generate exactly the same code in
454
both cases, and we have been using similar techniques with good success
455
in several projects.  Of course, the former method assumes that
456
`HAS_FOO' is defined as either 0 or 1.
457
 
458
   While this is not a silver bullet solving all portability problems,
459
and is not always appropriate, following this policy would have saved
460
GCC developers many hours, or even days, per year.
461
 
462
   In the case of function-like macros like `REVERSIBLE_CC_MODE' in GCC
463
which cannot be simply used in `if( ...)' statements, there is an easy
464
workaround.  Simply introduce another macro `HAS_REVERSIBLE_CC_MODE' as
465
in the following example:
466
 
467
       #ifdef REVERSIBLE_CC_MODE
468
       #define HAS_REVERSIBLE_CC_MODE 1
469
       #else
470
       #define HAS_REVERSIBLE_CC_MODE 0
471
       #endif
472
 
473

474
File: standards.info,  Node: Program Behavior,  Next: Writing C,  Prev: Design Advice,  Up: Top
475
 
476
4 Program Behavior for All Programs
477
***********************************
478
 
479
This chapter describes conventions for writing robust software.  It
480
also describes general standards for error messages, the command line
481
interface, and how libraries should behave.
482
 
483
* Menu:
484
 
485
* Non-GNU Standards::           We consider standards such as POSIX;
486
                                  we don't "obey" them.
487
* Semantics::                   Writing robust programs.
488
* Libraries::                   Library behavior.
489
* Errors::                      Formatting error messages.
490
* User Interfaces::             Standards about interfaces generally.
491
* Graphical Interfaces::        Standards for graphical interfaces.
492
* Command-Line Interfaces::     Standards for command line interfaces.
493
* Option Table::                Table of long options.
494
* Memory Usage::                When and how to care about memory needs.
495
* File Usage::                  Which files to use, and where.
496
 
497

498
File: standards.info,  Node: Non-GNU Standards,  Next: Semantics,  Up: Program Behavior
499
 
500
4.1 Non-GNU Standards
501
=====================
502
 
503
The GNU Project regards standards published by other organizations as
504
suggestions, not orders.  We consider those standards, but we do not
505
"obey" them.  In developing a GNU program, you should implement an
506
outside standard's specifications when that makes the GNU system better
507
overall in an objective sense.  When it doesn't, you shouldn't.
508
 
509
   In most cases, following published standards is convenient for
510
users--it means that their programs or scripts will work more portably.
511
For instance, GCC implements nearly all the features of Standard C as
512
specified by that standard.  C program developers would be unhappy if
513
it did not.  And GNU utilities mostly follow specifications of POSIX.2;
514
shell script writers and users would be unhappy if our programs were
515
incompatible.
516
 
517
   But we do not follow either of these specifications rigidly, and
518
there are specific points on which we decided not to follow them, so as
519
to make the GNU system better for users.
520
 
521
   For instance, Standard C says that nearly all extensions to C are
522
prohibited.  How silly!  GCC implements many extensions, some of which
523
were later adopted as part of the standard.  If you want these
524
constructs to give an error message as "required" by the standard, you
525
must specify `--pedantic', which was implemented only so that we can
526
say "GCC is a 100% implementation of the standard," not because there
527
is any reason to actually use it.
528
 
529
   POSIX.2 specifies that `df' and `du' must output sizes by default in
530
units of 512 bytes.  What users want is units of 1k, so that is what we
531
do by default.  If you want the ridiculous behavior "required" by
532
POSIX, you must set the environment variable `POSIXLY_CORRECT' (which
533
was originally going to be named `POSIX_ME_HARDER').
534
 
535
   GNU utilities also depart from the letter of the POSIX.2
536
specification when they support long-named command-line options, and
537
intermixing options with ordinary arguments.  This minor
538
incompatibility with POSIX is never a problem in practice, and it is
539
very useful.
540
 
541
   In particular, don't reject a new feature, or remove an old one,
542
merely because a standard says it is "forbidden" or "deprecated."
543
 
544

545
File: standards.info,  Node: Semantics,  Next: Libraries,  Prev: Non-GNU Standards,  Up: Program Behavior
546
 
547
4.2 Writing Robust Programs
548
===========================
549
 
550
Avoid arbitrary limits on the length or number of _any_ data structure,
551
including file names, lines, files, and symbols, by allocating all data
552
structures dynamically.  In most Unix utilities, "long lines are
553
silently truncated".  This is not acceptable in a GNU utility.
554
 
555
   Utilities reading files should not drop NUL characters, or any other
556
nonprinting characters _including those with codes above 0177_.  The
557
only sensible exceptions would be utilities specifically intended for
558
interface to certain types of terminals or printers that can't handle
559
those characters.  Whenever possible, try to make programs work
560
properly with sequences of bytes that represent multibyte characters,
561
using encodings such as UTF-8 and others.
562
 
563
   Check every system call for an error return, unless you know you
564
wish to ignore errors.  Include the system error text (from `perror' or
565
equivalent) in _every_ error message resulting from a failing system
566
call, as well as the name of the file if any and the name of the
567
utility.  Just "cannot open foo.c" or "stat failed" is not sufficient.
568
 
569
   Check every call to `malloc' or `realloc' to see if it returned
570
zero.  Check `realloc' even if you are making the block smaller; in a
571
system that rounds block sizes to a power of 2, `realloc' may get a
572
different block if you ask for less space.
573
 
574
   In Unix, `realloc' can destroy the storage block if it returns zero.
575
GNU `realloc' does not have this bug: if it fails, the original block
576
is unchanged.  Feel free to assume the bug is fixed.  If you wish to
577
run your program on Unix, and wish to avoid lossage in this case, you
578
can use the GNU `malloc'.
579
 
580
   You must expect `free' to alter the contents of the block that was
581
freed.  Anything you want to fetch from the block, you must fetch before
582
calling `free'.
583
 
584
   If `malloc' fails in a noninteractive program, make that a fatal
585
error.  In an interactive program (one that reads commands from the
586
user), it is better to abort the command and return to the command
587
reader loop.  This allows the user to kill other processes to free up
588
virtual memory, and then try the command again.
589
 
590
   Use `getopt_long' to decode arguments, unless the argument syntax
591
makes this unreasonable.
592
 
593
   When static storage is to be written in during program execution, use
594
explicit C code to initialize it.  Reserve C initialized declarations
595
for data that will not be changed.
596
 
597
   Try to avoid low-level interfaces to obscure Unix data structures
598
(such as file directories, utmp, or the layout of kernel memory), since
599
these are less likely to work compatibly.  If you need to find all the
600
files in a directory, use `readdir' or some other high-level interface.
601
These are supported compatibly by GNU.
602
 
603
   The preferred signal handling facilities are the BSD variant of
604
`signal', and the POSIX `sigaction' function; the alternative USG
605
`signal' interface is an inferior design.
606
 
607
   Nowadays, using the POSIX signal functions may be the easiest way to
608
make a program portable.  If you use `signal', then on GNU/Linux
609
systems running GNU libc version 1, you should include `bsd/signal.h'
610
instead of `signal.h', so as to get BSD behavior.  It is up to you
611
whether to support systems where `signal' has only the USG behavior, or
612
give up on them.
613
 
614
   In error checks that detect "impossible" conditions, just abort.
615
There is usually no point in printing any message.  These checks
616
indicate the existence of bugs.  Whoever wants to fix the bugs will have
617
to read the source code and run a debugger.  So explain the problem with
618
comments in the source.  The relevant data will be in variables, which
619
are easy to examine with the debugger, so there is no point moving them
620
elsewhere.
621
 
622
   Do not use a count of errors as the exit status for a program.
623
_That does not work_, because exit status values are limited to 8 bits
624
(0 through 255).  A single run of the program might have 256 errors; if
625
you try to return 256 as the exit status, the parent process will see 0
626
as the status, and it will appear that the program succeeded.
627
 
628
   If you make temporary files, check the `TMPDIR' environment
629
variable; if that variable is defined, use the specified directory
630
instead of `/tmp'.
631
 
632
   In addition, be aware that there is a possible security problem when
633
creating temporary files in world-writable directories.  In C, you can
634
avoid this problem by creating temporary files in this manner:
635
 
636
     fd = open(filename, O_WRONLY | O_CREAT | O_EXCL, 0600);
637
 
638
or by using the `mkstemps' function from libiberty.
639
 
640
   In bash, use `set -C' to avoid this problem.
641
 
642

643
File: standards.info,  Node: Libraries,  Next: Errors,  Prev: Semantics,  Up: Program Behavior
644
 
645
4.3 Library Behavior
646
====================
647
 
648
Try to make library functions reentrant.  If they need to do dynamic
649
storage allocation, at least try to avoid any nonreentrancy aside from
650
that of `malloc' itself.
651
 
652
   Here are certain name conventions for libraries, to avoid name
653
conflicts.
654
 
655
   Choose a name prefix for the library, more than two characters long.
656
All external function and variable names should start with this prefix.
657
In addition, there should only be one of these in any given library
658
member.  This usually means putting each one in a separate source file.
659
 
660
   An exception can be made when two external symbols are always used
661
together, so that no reasonable program could use one without the
662
other; then they can both go in the same file.
663
 
664
   External symbols that are not documented entry points for the user
665
should have names beginning with `_'.  The `_' should be followed by
666
the chosen name prefix for the library, to prevent collisions with
667
other libraries.  These can go in the same files with user entry points
668
if you like.
669
 
670
   Static functions and variables can be used as you like and need not
671
fit any naming convention.
672
 
673

674
File: standards.info,  Node: Errors,  Next: User Interfaces,  Prev: Libraries,  Up: Program Behavior
675
 
676
4.4 Formatting Error Messages
677
=============================
678
 
679
Error messages from compilers should look like this:
680
 
681
     SOURCE-FILE-NAME:LINENO: MESSAGE
682
 
683
If you want to mention the column number, use one of these formats:
684
 
685
     SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
686
     SOURCE-FILE-NAME:LINENO.COLUMN: MESSAGE
687
 
688
Line numbers should start from 1 at the beginning of the file, and
689
column numbers should start from 1 at the beginning of the line.  (Both
690
of these conventions are chosen for compatibility.)  Calculate column
691
numbers assuming that space and all ASCII printing characters have
692
equal width, and assuming tab stops every 8 columns.
693
 
694
   The error message can also give both the starting and ending
695
positions of the erroneous text.  There are several formats so that you
696
can avoid redundant information such as a duplicate line number.  Here
697
are the possible formats:
698
 
699
     SOURCE-FILE-NAME:LINENO-1.COLUMN-1-LINENO-2.COLUMN-2: MESSAGE
700
     SOURCE-FILE-NAME:LINENO-1.COLUMN-1-COLUMN-2: MESSAGE
701
     SOURCE-FILE-NAME:LINENO-1-LINENO-2: MESSAGE
702
 
703
When an error is spread over several files, you can use this format:
704
 
705
     FILE-1:LINENO-1.COLUMN-1-FILE-2:LINENO-2.COLUMN-2: MESSAGE
706
 
707
   Error messages from other noninteractive programs should look like
708
this:
709
 
710
     PROGRAM:SOURCE-FILE-NAME:LINENO: MESSAGE
711
 
712
when there is an appropriate source file, or like this:
713
 
714
     PROGRAM: MESSAGE
715
 
716
when there is no relevant source file.
717
 
718
   If you want to mention the column number, use this format:
719
 
720
     PROGRAM:SOURCE-FILE-NAME:LINENO:COLUMN: MESSAGE
721
 
722
   In an interactive program (one that is reading commands from a
723
terminal), it is better not to include the program name in an error
724
message.  The place to indicate which program is running is in the
725
prompt or with the screen layout.  (When the same program runs with
726
input from a source other than a terminal, it is not interactive and
727
would do best to print error messages using the noninteractive style.)
728
 
729
   The string MESSAGE should not begin with a capital letter when it
730
follows a program name and/or file name, because that isn't the
731
beginning of a sentence.  (The sentence conceptually starts at the
732
beginning of the line.)  Also, it should not end with a period.
733
 
734
   Error messages from interactive programs, and other messages such as
735
usage messages, should start with a capital letter.  But they should not
736
end with a period.
737
 
738

739
File: standards.info,  Node: User Interfaces,  Next: Graphical Interfaces,  Prev: Errors,  Up: Program Behavior
740
 
741
4.5 Standards for Interfaces Generally
742
======================================
743
 
744
Please don't make the behavior of a utility depend on the name used to
745
invoke it.  It is useful sometimes to make a link to a utility with a
746
different name, and that should not change what it does.
747
 
748
   Instead, use a run time option or a compilation switch or both to
749
select among the alternate behaviors.
750
 
751
   Likewise, please don't make the behavior of the program depend on the
752
type of output device it is used with.  Device independence is an
753
important principle of the system's design; do not compromise it merely
754
to save someone from typing an option now and then.  (Variation in error
755
message syntax when using a terminal is ok, because that is a side issue
756
that people do not depend on.)
757
 
758
   If you think one behavior is most useful when the output is to a
759
terminal, and another is most useful when the output is a file or a
760
pipe, then it is usually best to make the default behavior the one that
761
is useful with output to a terminal, and have an option for the other
762
behavior.
763
 
764
   Compatibility requires certain programs to depend on the type of
765
output device.  It would be disastrous if `ls' or `sh' did not do so in
766
the way all users expect.  In some of these cases, we supplement the
767
program with a preferred alternate version that does not depend on the
768
output device type.  For example, we provide a `dir' program much like
769
`ls' except that its default output format is always multi-column
770
format.
771
 
772

773
File: standards.info,  Node: Graphical Interfaces,  Next: Command-Line Interfaces,  Prev: User Interfaces,  Up: Program Behavior
774
 
775
4.6 Standards for Graphical Interfaces
776
======================================
777
 
778
When you write a program that provides a graphical user interface,
779
please make it work with X Windows and the GTK+ toolkit unless the
780
functionality specifically requires some alternative (for example,
781
"displaying jpeg images while in console mode").
782
 
783
   In addition, please provide a command-line interface to control the
784
functionality.  (In many cases, the graphical user interface can be a
785
separate program which invokes the command-line program.)  This is so
786
that the same jobs can be done from scripts.
787
 
788
   Please also consider providing a CORBA interface (for use from
789
GNOME), a library interface (for use from C), and perhaps a
790
keyboard-driven console interface (for use by users from console mode).
791
Once you are doing the work to provide the functionality and the
792
graphical interface, these won't be much extra work.
793
 
794

795
File: standards.info,  Node: Command-Line Interfaces,  Next: Option Table,  Prev: Graphical Interfaces,  Up: Program Behavior
796
 
797
4.7 Standards for Command Line Interfaces
798
=========================================
799
 
800
It is a good idea to follow the POSIX guidelines for the command-line
801
options of a program.  The easiest way to do this is to use `getopt' to
802
parse them.  Note that the GNU version of `getopt' will normally permit
803
options anywhere among the arguments unless the special argument `--'
804
is used.  This is not what POSIX specifies; it is a GNU extension.
805
 
806
   Please define long-named options that are equivalent to the
807
single-letter Unix-style options.  We hope to make GNU more user
808
friendly this way.  This is easy to do with the GNU function
809
`getopt_long'.
810
 
811
   One of the advantages of long-named options is that they can be
812
consistent from program to program.  For example, users should be able
813
to expect the "verbose" option of any GNU program which has one, to be
814
spelled precisely `--verbose'.  To achieve this uniformity, look at the
815
table of common long-option names when you choose the option names for
816
your program (*note Option Table::).
817
 
818
   It is usually a good idea for file names given as ordinary arguments
819
to be input files only; any output files would be specified using
820
options (preferably `-o' or `--output').  Even if you allow an output
821
file name as an ordinary argument for compatibility, try to provide an
822
option as another way to specify it.  This will lead to more consistency
823
among GNU utilities, and fewer idiosyncrasies for users to remember.
824
 
825
   All programs should support two standard options: `--version' and
826
`--help'.  CGI programs should accept these as command-line options,
827
and also if given as the `PATH_INFO'; for instance, visiting
828
`http://example.org/p.cgi/--help' in a browser should output the same
829
information as invoking `p.cgi --help' from the command line.
830
 
831
* Menu:
832
 
833
* --version::       The standard output for --version.
834
* --help::          The standard output for --help.
835
 
836

837
File: standards.info,  Node: --version,  Next: --help,  Up: Command-Line Interfaces
838
 
839
4.7.1 `--version'
840
-----------------
841
 
842
The standard `--version' option should direct the program to print
843
information about its name, version, origin and legal status, all on
844
standard output, and then exit successfully.  Other options and
845
arguments should be ignored once this is seen, and the program should
846
not perform its normal function.
847
 
848
   The first line is meant to be easy for a program to parse; the
849
version number proper starts after the last space.  In addition, it
850
contains the canonical name for this program, in this format:
851
 
852
     GNU Emacs 19.30
853
 
854
The program's name should be a constant string; _don't_ compute it from
855
`argv[0]'.  The idea is to state the standard or canonical name for the
856
program, not its file name.  There are other ways to find out the
857
precise file name where a command is found in `PATH'.
858
 
859
   If the program is a subsidiary part of a larger package, mention the
860
package name in parentheses, like this:
861
 
862
     emacsserver (GNU Emacs) 19.30
863
 
864
If the package has a version number which is different from this
865
program's version number, you can mention the package version number
866
just before the close-parenthesis.
867
 
868
   If you _need_ to mention the version numbers of libraries which are
869
distributed separately from the package which contains this program,
870
you can do so by printing an additional line of version info for each
871
library you want to mention.  Use the same format for these lines as for
872
the first line.
873
 
874
   Please do not mention all of the libraries that the program uses
875
"just for completeness"--that would produce a lot of unhelpful clutter.
876
Please mention library version numbers only if you find in practice that
877
they are very important to you in debugging.
878
 
879
   The following line, after the version number line or lines, should
880
be a copyright notice.  If more than one copyright notice is called
881
for, put each on a separate line.
882
 
883
   Next should follow a line stating the license, preferably using one
884
of abbrevations below, and a brief statement that the program is free
885
software, and that users are free to copy and change it.  Also mention
886
that there is no warranty, to the extent permitted by law.  See
887
recommended wording below.
888
 
889
   It is ok to finish the output with a list of the major authors of the
890
program, as a way of giving credit.
891
 
892
   Here's an example of output that follows these rules:
893
 
894
     GNU hello 2.3
895
     Copyright (C) 2007 Free Software Foundation, Inc.
896
     License GPLv3+: GNU GPL version 3 or later 
897
     This is free software: you are free to change and redistribute it.
898
     There is NO WARRANTY, to the extent permitted by law.
899
 
900
   You should adapt this to your program, of course, filling in the
901
proper year, copyright holder, name of program, and the references to
902
distribution terms, and changing the rest of the wording as necessary.
903
 
904
   This copyright notice only needs to mention the most recent year in
905
which changes were made--there's no need to list the years for previous
906
versions' changes.  You don't have to mention the name of the program in
907
these notices, if that is inconvenient, since it appeared in the first
908
line.  (The rules are different for copyright notices in source files;
909
*note Copyright Notices: (maintain)Copyright Notices.)
910
 
911
   Translations of the above lines must preserve the validity of the
912
copyright notices (*note Internationalization::).  If the translation's
913
character set supports it, the `(C)' should be replaced with the
914
copyright symbol, as follows:
915
 
916
   (the official copyright symbol, which is the letter C in a circle);
917
 
918
   Write the word "Copyright" exactly like that, in English.  Do not
919
translate it into another language.  International treaties recognize
920
the English word "Copyright"; translations into other languages do not
921
have legal significance.
922
 
923
   Finally, here is the table of our suggested license abbreviations.
924
Any abbreviation can be followed by `vVERSION[+]', meaning that
925
particular version, or later versions with the `+', as shown above.
926
 
927
   In the case of exceptions for extra permissions with the GPL, we use
928
`/' for a separator; the version number can follow the license
929
abbreviation as usual, as in the examples below.
930
 
931
GPL
932
     GNU General Public License, `http://www.gnu.org/licenses/gpl.html'.
933
 
934
LGPL
935
     GNU Lesser General Public License,
936
     `http://www.gnu.org/licenses/lgpl.html'.
937
 
938
GPL/Guile
939
     GNU GPL with the exception for Guile; for example, GPLv3+/Guile
940
     means the GNU GPL version 3 or later, with the extra exception for
941
     Guile.
942
 
943
     GNU GPL with the exception for Ada.
944
 
945
Apache
946
     The Apache Software Foundation license,
947
     `http://www.apache.org/licenses'.
948
 
949
Artistic
950
     The Artistic license used for Perl,
951
     `http://www.perlfoundation.org/legal'.
952
 
953
Expat
954
     The Expat license, `http://www.jclark.com/xml/copying.txt'.
955
 
956
MPL
957
     The Mozilla Public License, `http://www.mozilla.org/MPL/'.
958
 
959
OBSD
960
     The original (4-clause) BSD license, incompatible with the GNU GPL
961
     `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6'.
962
 
963
PHP
964
     The license used for PHP, `http://www.php.net/license/'.
965
 
966
public domain
967
     The non-license that is being in the public domain,
968
     `http://www.gnu.org/licenses/license-list.html#PublicDomain'.
969
 
970
Python
971
     The license for Python, `http://www.python.org/2.0.1/license.html'.
972
 
973
RBSD
974
     The revised (3-clause) BSD, compatible with the GNU GPL,
975
     `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5'.
976
 
977
X11
978
     The simple non-copyleft license used for most versions of the X
979
     Window system, `http://www.xfree86.org/3.3.6/COPYRIGHT2.html#3'.
980
 
981
Zlib
982
     The license for Zlib, `http://www.gzip.org/zlib/zlib_license.html'.
983
 
984
 
985
   More information about these licenses and many more are on the GNU
986
licensing web pages, `http://www.gnu.org/licenses/license-list.html'.
987
 
988

989
File: standards.info,  Node: --help,  Prev: --version,  Up: Command-Line Interfaces
990
 
991
4.7.2 `--help'
992
--------------
993
 
994
The standard `--help' option should output brief documentation for how
995
to invoke the program, on standard output, then exit successfully.
996
Other options and arguments should be ignored once this is seen, and
997
the program should not perform its normal function.
998
 
999
   Near the end of the `--help' option's output there should be a line
1000
that says where to mail bug reports.  It should have this format:
1001
 
1002
     Report bugs to MAILING-ADDRESS.
1003
 
1004

1005
File: standards.info,  Node: Option Table,  Next: Memory Usage,  Prev: Command-Line Interfaces,  Up: Program Behavior
1006
 
1007
4.8 Table of Long Options
1008
=========================
1009
 
1010
Here is a table of long options used by GNU programs.  It is surely
1011
incomplete, but we aim to list all the options that a new program might
1012
want to be compatible with.  If you use names not already in the table,
1013
please send  a list of them, with their
1014
meanings, so we can update the table.
1015
 
1016
`after-date'
1017
     `-N' in `tar'.
1018
 
1019
`all'
1020
     `-a' in `du', `ls', `nm', `stty', `uname', and `unexpand'.
1021
 
1022
`all-text'
1023
     `-a' in `diff'.
1024
 
1025
`almost-all'
1026
     `-A' in `ls'.
1027
 
1028
`append'
1029
     `-a' in `etags', `tee', `time'; `-r' in `tar'.
1030
 
1031
`archive'
1032
     `-a' in `cp'.
1033
 
1034
`archive-name'
1035
     `-n' in `shar'.
1036
 
1037
`arglength'
1038
     `-l' in `m4'.
1039
 
1040
`ascii'
1041
     `-a' in `diff'.
1042
 
1043
`assign'
1044
     `-v' in `gawk'.
1045
 
1046
`assume-new'
1047
     `-W' in Make.
1048
 
1049
`assume-old'
1050
     `-o' in Make.
1051
 
1052
`auto-check'
1053
     `-a' in `recode'.
1054
 
1055
`auto-pager'
1056
     `-a' in `wdiff'.
1057
 
1058
`auto-reference'
1059
     `-A' in `ptx'.
1060
 
1061
`avoid-wraps'
1062
     `-n' in `wdiff'.
1063
 
1064
`background'
1065
     For server programs, run in the background.
1066
 
1067
`backward-search'
1068
     `-B' in `ctags'.
1069
 
1070
`basename'
1071
     `-f' in `shar'.
1072
 
1073
`batch'
1074
     Used in GDB.
1075
 
1076
`baud'
1077
     Used in GDB.
1078
 
1079
`before'
1080
     `-b' in `tac'.
1081
 
1082
`binary'
1083
     `-b' in `cpio' and `diff'.
1084
 
1085
`bits-per-code'
1086
     `-b' in `shar'.
1087
 
1088
`block-size'
1089
     Used in `cpio' and `tar'.
1090
 
1091
`blocks'
1092
     `-b' in `head' and `tail'.
1093
 
1094
`break-file'
1095
     `-b' in `ptx'.
1096
 
1097
`brief'
1098
     Used in various programs to make output shorter.
1099
 
1100
`bytes'
1101
     `-c' in `head', `split', and `tail'.
1102
 
1103
`c++'
1104
     `-C' in `etags'.
1105
 
1106
`catenate'
1107
     `-A' in `tar'.
1108
 
1109
`cd'
1110
     Used in various programs to specify the directory to use.
1111
 
1112
`changes'
1113
     `-c' in `chgrp' and `chown'.
1114
 
1115
`classify'
1116
     `-F' in `ls'.
1117
 
1118
`colons'
1119
     `-c' in `recode'.
1120
 
1121
`command'
1122
     `-c' in `su'; `-x' in GDB.
1123
 
1124
`compare'
1125
     `-d' in `tar'.
1126
 
1127
`compat'
1128
     Used in `gawk'.
1129
 
1130
`compress'
1131
     `-Z' in `tar' and `shar'.
1132
 
1133
`concatenate'
1134
     `-A' in `tar'.
1135
 
1136
`confirmation'
1137
     `-w' in `tar'.
1138
 
1139
`context'
1140
     Used in `diff'.
1141
 
1142
`copyleft'
1143
     `-W copyleft' in `gawk'.
1144
 
1145
`copyright'
1146
     `-C' in `ptx', `recode', and `wdiff'; `-W copyright' in `gawk'.
1147
 
1148
`core'
1149
     Used in GDB.
1150
 
1151
`count'
1152
     `-q' in `who'.
1153
 
1154
`count-links'
1155
     `-l' in `du'.
1156
 
1157
`create'
1158
     Used in `tar' and `cpio'.
1159
 
1160
`cut-mark'
1161
     `-c' in `shar'.
1162
 
1163
`cxref'
1164
     `-x' in `ctags'.
1165
 
1166
`date'
1167
     `-d' in `touch'.
1168
 
1169
`debug'
1170
     `-d' in Make and `m4'; `-t' in Bison.
1171
 
1172
`define'
1173
     `-D' in `m4'.
1174
 
1175
`defines'
1176
     `-d' in Bison and `ctags'.
1177
 
1178
`delete'
1179
     `-D' in `tar'.
1180
 
1181
`dereference'
1182
     `-L' in `chgrp', `chown', `cpio', `du', `ls', and `tar'.
1183
 
1184
`dereference-args'
1185
     `-D' in `du'.
1186
 
1187
`device'
1188
     Specify an I/O device (special file name).
1189
 
1190
`diacritics'
1191
     `-d' in `recode'.
1192
 
1193
`dictionary-order'
1194
     `-d' in `look'.
1195
 
1196
`diff'
1197
     `-d' in `tar'.
1198
 
1199
`digits'
1200
     `-n' in `csplit'.
1201
 
1202
`directory'
1203
     Specify the directory to use, in various programs.  In `ls', it
1204
     means to show directories themselves rather than their contents.
1205
     In `rm' and `ln', it means to not treat links to directories
1206
     specially.
1207
 
1208
`discard-all'
1209
     `-x' in `strip'.
1210
 
1211
`discard-locals'
1212
     `-X' in `strip'.
1213
 
1214
`dry-run'
1215
     `-n' in Make.
1216
 
1217
`ed'
1218
     `-e' in `diff'.
1219
 
1220
`elide-empty-files'
1221
     `-z' in `csplit'.
1222
 
1223
`end-delete'
1224
     `-x' in `wdiff'.
1225
 
1226
`end-insert'
1227
     `-z' in `wdiff'.
1228
 
1229
`entire-new-file'
1230
     `-N' in `diff'.
1231
 
1232
`environment-overrides'
1233
     `-e' in Make.
1234
 
1235
`eof'
1236
     `-e' in `xargs'.
1237
 
1238
`epoch'
1239
     Used in GDB.
1240
 
1241
`error-limit'
1242
     Used in `makeinfo'.
1243
 
1244
`error-output'
1245
     `-o' in `m4'.
1246
 
1247
`escape'
1248
     `-b' in `ls'.
1249
 
1250
`exclude-from'
1251
     `-X' in `tar'.
1252
 
1253
`exec'
1254
     Used in GDB.
1255
 
1256
`exit'
1257
     `-x' in `xargs'.
1258
 
1259
`exit-0'
1260
     `-e' in `unshar'.
1261
 
1262
`expand-tabs'
1263
     `-t' in `diff'.
1264
 
1265
`expression'
1266
     `-e' in `sed'.
1267
 
1268
`extern-only'
1269
     `-g' in `nm'.
1270
 
1271
`extract'
1272
     `-i' in `cpio'; `-x' in `tar'.
1273
 
1274
`faces'
1275
     `-f' in `finger'.
1276
 
1277
`fast'
1278
     `-f' in `su'.
1279
 
1280
`fatal-warnings'
1281
     `-E' in `m4'.
1282
 
1283
`file'
1284
     `-f' in `info', `gawk', Make, `mt', and `tar'; `-n' in `sed'; `-r'
1285
     in `touch'.
1286
 
1287
`field-separator'
1288
     `-F' in `gawk'.
1289
 
1290
`file-prefix'
1291
     `-b' in Bison.
1292
 
1293
`file-type'
1294
     `-F' in `ls'.
1295
 
1296
`files-from'
1297
     `-T' in `tar'.
1298
 
1299
`fill-column'
1300
     Used in `makeinfo'.
1301
 
1302
`flag-truncation'
1303
     `-F' in `ptx'.
1304
 
1305
`fixed-output-files'
1306
     `-y' in Bison.
1307
 
1308
`follow'
1309
     `-f' in `tail'.
1310
 
1311
`footnote-style'
1312
     Used in `makeinfo'.
1313
 
1314
`force'
1315
     `-f' in `cp', `ln', `mv', and `rm'.
1316
 
1317
`force-prefix'
1318
     `-F' in `shar'.
1319
 
1320
`foreground'
1321
     For server programs, run in the foreground; in other words, don't
1322
     do anything special to run the server in the background.
1323
 
1324
`format'
1325
     Used in `ls', `time', and `ptx'.
1326
 
1327
`freeze-state'
1328
     `-F' in `m4'.
1329
 
1330
`fullname'
1331
     Used in GDB.
1332
 
1333
`gap-size'
1334
     `-g' in `ptx'.
1335
 
1336
`get'
1337
     `-x' in `tar'.
1338
 
1339
`graphic'
1340
     `-i' in `ul'.
1341
 
1342
`graphics'
1343
     `-g' in `recode'.
1344
 
1345
`group'
1346
     `-g' in `install'.
1347
 
1348
`gzip'
1349
     `-z' in `tar' and `shar'.
1350
 
1351
`hashsize'
1352
     `-H' in `m4'.
1353
 
1354
`header'
1355
     `-h' in `objdump' and `recode'
1356
 
1357
`heading'
1358
     `-H' in `who'.
1359
 
1360
`help'
1361
     Used to ask for brief usage information.
1362
 
1363
`here-delimiter'
1364
     `-d' in `shar'.
1365
 
1366
`hide-control-chars'
1367
     `-q' in `ls'.
1368
 
1369
`html'
1370
     In `makeinfo', output HTML.
1371
 
1372
`idle'
1373
     `-u' in `who'.
1374
 
1375
`ifdef'
1376
     `-D' in `diff'.
1377
 
1378
`ignore'
1379
     `-I' in `ls'; `-x' in `recode'.
1380
 
1381
`ignore-all-space'
1382
     `-w' in `diff'.
1383
 
1384
`ignore-backups'
1385
     `-B' in `ls'.
1386
 
1387
`ignore-blank-lines'
1388
     `-B' in `diff'.
1389
 
1390
`ignore-case'
1391
     `-f' in `look' and `ptx'; `-i' in `diff' and `wdiff'.
1392
 
1393
`ignore-errors'
1394
     `-i' in Make.
1395
 
1396
`ignore-file'
1397
     `-i' in `ptx'.
1398
 
1399
`ignore-indentation'
1400
     `-I' in `etags'.
1401
 
1402
`ignore-init-file'
1403
     `-f' in Oleo.
1404
 
1405
`ignore-interrupts'
1406
     `-i' in `tee'.
1407
 
1408
`ignore-matching-lines'
1409
     `-I' in `diff'.
1410
 
1411
`ignore-space-change'
1412
     `-b' in `diff'.
1413
 
1414
`ignore-zeros'
1415
     `-i' in `tar'.
1416
 
1417
`include'
1418
     `-i' in `etags'; `-I' in `m4'.
1419
 
1420
`include-dir'
1421
     `-I' in Make.
1422
 
1423
`incremental'
1424
     `-G' in `tar'.
1425
 
1426
`info'
1427
     `-i', `-l', and `-m' in Finger.
1428
 
1429
`init-file'
1430
     In some programs, specify the name of the file to read as the
1431
     user's init file.
1432
 
1433
`initial'
1434
     `-i' in `expand'.
1435
 
1436
`initial-tab'
1437
     `-T' in `diff'.
1438
 
1439
`inode'
1440
     `-i' in `ls'.
1441
 
1442
`interactive'
1443
     `-i' in `cp', `ln', `mv', `rm'; `-e' in `m4'; `-p' in `xargs';
1444
     `-w' in `tar'.
1445
 
1446
`intermix-type'
1447
     `-p' in `shar'.
1448
 
1449
`iso-8601'
1450
     Used in `date'
1451
 
1452
`jobs'
1453
     `-j' in Make.
1454
 
1455
`just-print'
1456
     `-n' in Make.
1457
 
1458
`keep-going'
1459
     `-k' in Make.
1460
 
1461
`keep-files'
1462
     `-k' in `csplit'.
1463
 
1464
`kilobytes'
1465
     `-k' in `du' and `ls'.
1466
 
1467
`language'
1468
     `-l' in `etags'.
1469
 
1470
`less-mode'
1471
     `-l' in `wdiff'.
1472
 
1473
`level-for-gzip'
1474
     `-g' in `shar'.
1475
 
1476
`line-bytes'
1477
     `-C' in `split'.
1478
 
1479
`lines'
1480
     Used in `split', `head', and `tail'.
1481
 
1482
`link'
1483
     `-l' in `cpio'.
1484
 
1485
`lint'
1486
`lint-old'
1487
     Used in `gawk'.
1488
 
1489
`list'
1490
     `-t' in `cpio'; `-l' in `recode'.
1491
 
1492
`list'
1493
     `-t' in `tar'.
1494
 
1495
`literal'
1496
     `-N' in `ls'.
1497
 
1498
`load-average'
1499
     `-l' in Make.
1500
 
1501
`login'
1502
     Used in `su'.
1503
 
1504
`machine'
1505
     Used in `uname'.
1506
 
1507
`macro-name'
1508
     `-M' in `ptx'.
1509
 
1510
`mail'
1511
     `-m' in `hello' and `uname'.
1512
 
1513
`make-directories'
1514
     `-d' in `cpio'.
1515
 
1516
`makefile'
1517
     `-f' in Make.
1518
 
1519
`mapped'
1520
     Used in GDB.
1521
 
1522
`max-args'
1523
     `-n' in `xargs'.
1524
 
1525
`max-chars'
1526
     `-n' in `xargs'.
1527
 
1528
`max-lines'
1529
     `-l' in `xargs'.
1530
 
1531
`max-load'
1532
     `-l' in Make.
1533
 
1534
`max-procs'
1535
     `-P' in `xargs'.
1536
 
1537
`mesg'
1538
     `-T' in `who'.
1539
 
1540
`message'
1541
     `-T' in `who'.
1542
 
1543
`minimal'
1544
     `-d' in `diff'.
1545
 
1546
`mixed-uuencode'
1547
     `-M' in `shar'.
1548
 
1549
`mode'
1550
     `-m' in `install', `mkdir', and `mkfifo'.
1551
 
1552
`modification-time'
1553
     `-m' in `tar'.
1554
 
1555
`multi-volume'
1556
     `-M' in `tar'.
1557
 
1558
`name-prefix'
1559
     `-a' in Bison.
1560
 
1561
`nesting-limit'
1562
     `-L' in `m4'.
1563
 
1564
`net-headers'
1565
     `-a' in `shar'.
1566
 
1567
`new-file'
1568
     `-W' in Make.
1569
 
1570
`no-builtin-rules'
1571
     `-r' in Make.
1572
 
1573
`no-character-count'
1574
     `-w' in `shar'.
1575
 
1576
`no-check-existing'
1577
     `-x' in `shar'.
1578
 
1579
`no-common'
1580
     `-3' in `wdiff'.
1581
 
1582
`no-create'
1583
     `-c' in `touch'.
1584
 
1585
`no-defines'
1586
     `-D' in `etags'.
1587
 
1588
`no-deleted'
1589
     `-1' in `wdiff'.
1590
 
1591
`no-dereference'
1592
     `-d' in `cp'.
1593
 
1594
`no-inserted'
1595
     `-2' in `wdiff'.
1596
 
1597
`no-keep-going'
1598
     `-S' in Make.
1599
 
1600
`no-lines'
1601
     `-l' in Bison.
1602
 
1603
`no-piping'
1604
     `-P' in `shar'.
1605
 
1606
`no-prof'
1607
     `-e' in `gprof'.
1608
 
1609
`no-regex'
1610
     `-R' in `etags'.
1611
 
1612
`no-sort'
1613
     `-p' in `nm'.
1614
 
1615
`no-splash'
1616
     Don't print a startup splash screen.
1617
 
1618
`no-split'
1619
     Used in `makeinfo'.
1620
 
1621
`no-static'
1622
     `-a' in `gprof'.
1623
 
1624
`no-time'
1625
     `-E' in `gprof'.
1626
 
1627
`no-timestamp'
1628
     `-m' in `shar'.
1629
 
1630
`no-validate'
1631
     Used in `makeinfo'.
1632
 
1633
`no-wait'
1634
     Used in `emacsclient'.
1635
 
1636
`no-warn'
1637
     Used in various programs to inhibit warnings.
1638
 
1639
`node'
1640
     `-n' in `info'.
1641
 
1642
`nodename'
1643
     `-n' in `uname'.
1644
 
1645
`nonmatching'
1646
     `-f' in `cpio'.
1647
 
1648
`nstuff'
1649
     `-n' in `objdump'.
1650
 
1651
`null'
1652
     `-0' in `xargs'.
1653
 
1654
`number'
1655
     `-n' in `cat'.
1656
 
1657
`number-nonblank'
1658
     `-b' in `cat'.
1659
 
1660
`numeric-sort'
1661
     `-n' in `nm'.
1662
 
1663
`numeric-uid-gid'
1664
     `-n' in `cpio' and `ls'.
1665
 
1666
`nx'
1667
     Used in GDB.
1668
 
1669
`old-archive'
1670
     `-o' in `tar'.
1671
 
1672
`old-file'
1673
     `-o' in Make.
1674
 
1675
`one-file-system'
1676
     `-l' in `tar', `cp', and `du'.
1677
 
1678
`only-file'
1679
     `-o' in `ptx'.
1680
 
1681
`only-prof'
1682
     `-f' in `gprof'.
1683
 
1684
`only-time'
1685
     `-F' in `gprof'.
1686
 
1687
`options'
1688
     `-o' in `getopt', `fdlist', `fdmount', `fdmountd', and `fdumount'.
1689
 
1690
`output'
1691
     In various programs, specify the output file name.
1692
 
1693
`output-prefix'
1694
     `-o' in `shar'.
1695
 
1696
`override'
1697
     `-o' in `rm'.
1698
 
1699
`overwrite'
1700
     `-c' in `unshar'.
1701
 
1702
`owner'
1703
     `-o' in `install'.
1704
 
1705
`paginate'
1706
     `-l' in `diff'.
1707
 
1708
`paragraph-indent'
1709
     Used in `makeinfo'.
1710
 
1711
`parents'
1712
     `-p' in `mkdir' and `rmdir'.
1713
 
1714
`pass-all'
1715
     `-p' in `ul'.
1716
 
1717
`pass-through'
1718
     `-p' in `cpio'.
1719
 
1720
`port'
1721
     `-P' in `finger'.
1722
 
1723
`portability'
1724
     `-c' in `cpio' and `tar'.
1725
 
1726
`posix'
1727
     Used in `gawk'.
1728
 
1729
`prefix-builtins'
1730
     `-P' in `m4'.
1731
 
1732
`prefix'
1733
     `-f' in `csplit'.
1734
 
1735
`preserve'
1736
     Used in `tar' and `cp'.
1737
 
1738
`preserve-environment'
1739
     `-p' in `su'.
1740
 
1741
`preserve-modification-time'
1742
     `-m' in `cpio'.
1743
 
1744
`preserve-order'
1745
     `-s' in `tar'.
1746
 
1747
`preserve-permissions'
1748
     `-p' in `tar'.
1749
 
1750
`print'
1751
     `-l' in `diff'.
1752
 
1753
`print-chars'
1754
     `-L' in `cmp'.
1755
 
1756
`print-data-base'
1757
     `-p' in Make.
1758
 
1759
`print-directory'
1760
     `-w' in Make.
1761
 
1762
`print-file-name'
1763
     `-o' in `nm'.
1764
 
1765
`print-symdefs'
1766
     `-s' in `nm'.
1767
 
1768
`printer'
1769
     `-p' in `wdiff'.
1770
 
1771
`prompt'
1772
     `-p' in `ed'.
1773
 
1774
`proxy'
1775
     Specify an HTTP proxy.
1776
 
1777
`query-user'
1778
     `-X' in `shar'.
1779
 
1780
`question'
1781
     `-q' in Make.
1782
 
1783
`quiet'
1784
     Used in many programs to inhibit the usual output.  Every program
1785
     accepting `--quiet' should accept `--silent' as a synonym.
1786
 
1787
`quiet-unshar'
1788
     `-Q' in `shar'
1789
 
1790
`quote-name'
1791
     `-Q' in `ls'.
1792
 
1793
`rcs'
1794
     `-n' in `diff'.
1795
 
1796
`re-interval'
1797
     Used in `gawk'.
1798
 
1799
`read-full-blocks'
1800
     `-B' in `tar'.
1801
 
1802
`readnow'
1803
     Used in GDB.
1804
 
1805
`recon'
1806
     `-n' in Make.
1807
 
1808
`record-number'
1809
     `-R' in `tar'.
1810
 
1811
`recursive'
1812
     Used in `chgrp', `chown', `cp', `ls', `diff', and `rm'.
1813
 
1814
`reference-limit'
1815
     Used in `makeinfo'.
1816
 
1817
`references'
1818
     `-r' in `ptx'.
1819
 
1820
`regex'
1821
     `-r' in `tac' and `etags'.
1822
 
1823
`release'
1824
     `-r' in `uname'.
1825
 
1826
`reload-state'
1827
     `-R' in `m4'.
1828
 
1829
`relocation'
1830
     `-r' in `objdump'.
1831
 
1832
`rename'
1833
     `-r' in `cpio'.
1834
 
1835
`replace'
1836
     `-i' in `xargs'.
1837
 
1838
`report-identical-files'
1839
     `-s' in `diff'.
1840
 
1841
`reset-access-time'
1842
     `-a' in `cpio'.
1843
 
1844
`reverse'
1845
     `-r' in `ls' and `nm'.
1846
 
1847
`reversed-ed'
1848
     `-f' in `diff'.
1849
 
1850
`right-side-defs'
1851
     `-R' in `ptx'.
1852
 
1853
`same-order'
1854
     `-s' in `tar'.
1855
 
1856
`same-permissions'
1857
     `-p' in `tar'.
1858
 
1859
`save'
1860
     `-g' in `stty'.
1861
 
1862
`se'
1863
     Used in GDB.
1864
 
1865
`sentence-regexp'
1866
     `-S' in `ptx'.
1867
 
1868
`separate-dirs'
1869
     `-S' in `du'.
1870
 
1871
`separator'
1872
     `-s' in `tac'.
1873
 
1874
`sequence'
1875
     Used by `recode' to chose files or pipes for sequencing passes.
1876
 
1877
`shell'
1878
     `-s' in `su'.
1879
 
1880
`show-all'
1881
     `-A' in `cat'.
1882
 
1883
`show-c-function'
1884
     `-p' in `diff'.
1885
 
1886
`show-ends'
1887
     `-E' in `cat'.
1888
 
1889
`show-function-line'
1890
     `-F' in `diff'.
1891
 
1892
`show-tabs'
1893
     `-T' in `cat'.
1894
 
1895
`silent'
1896
     Used in many programs to inhibit the usual output.  Every program
1897
     accepting `--silent' should accept `--quiet' as a synonym.
1898
 
1899
`size'
1900
     `-s' in `ls'.
1901
 
1902
`socket'
1903
     Specify a file descriptor for a network server to use for its
1904
     socket, instead of opening and binding a new socket.  This
1905
     provides a way to run, in a non-privileged process, a server that
1906
     normally needs a reserved port number.
1907
 
1908
`sort'
1909
     Used in `ls'.
1910
 
1911
`source'
1912
     `-W source' in `gawk'.
1913
 
1914
`sparse'
1915
     `-S' in `tar'.
1916
 
1917
`speed-large-files'
1918
     `-H' in `diff'.
1919
 
1920
`split-at'
1921
     `-E' in `unshar'.
1922
 
1923
`split-size-limit'
1924
     `-L' in `shar'.
1925
 
1926
`squeeze-blank'
1927
     `-s' in `cat'.
1928
 
1929
`start-delete'
1930
     `-w' in `wdiff'.
1931
 
1932
`start-insert'
1933
     `-y' in `wdiff'.
1934
 
1935
`starting-file'
1936
     Used in `tar' and `diff' to specify which file within a directory
1937
     to start processing with.
1938
 
1939
`statistics'
1940
     `-s' in `wdiff'.
1941
 
1942
`stdin-file-list'
1943
     `-S' in `shar'.
1944
 
1945
`stop'
1946
     `-S' in Make.
1947
 
1948
`strict'
1949
     `-s' in `recode'.
1950
 
1951
`strip'
1952
     `-s' in `install'.
1953
 
1954
`strip-all'
1955
     `-s' in `strip'.
1956
 
1957
`strip-debug'
1958
     `-S' in `strip'.
1959
 
1960
`submitter'
1961
     `-s' in `shar'.
1962
 
1963
`suffix'
1964
     `-S' in `cp', `ln', `mv'.
1965
 
1966
`suffix-format'
1967
     `-b' in `csplit'.
1968
 
1969
`sum'
1970
     `-s' in `gprof'.
1971
 
1972
`summarize'
1973
     `-s' in `du'.
1974
 
1975
`symbolic'
1976
     `-s' in `ln'.
1977
 
1978
`symbols'
1979
     Used in GDB and `objdump'.
1980
 
1981
`synclines'
1982
     `-s' in `m4'.
1983
 
1984
`sysname'
1985
     `-s' in `uname'.
1986
 
1987
`tabs'
1988
     `-t' in `expand' and `unexpand'.
1989
 
1990
`tabsize'
1991
     `-T' in `ls'.
1992
 
1993
`terminal'
1994
     `-T' in `tput' and `ul'.  `-t' in `wdiff'.
1995
 
1996
`text'
1997
     `-a' in `diff'.
1998
 
1999
`text-files'
2000
     `-T' in `shar'.
2001
 
2002
`time'
2003
     Used in `ls' and `touch'.
2004
 
2005
`timeout'
2006
     Specify how long to wait before giving up on some operation.
2007
 
2008
`to-stdout'
2009
     `-O' in `tar'.
2010
 
2011
`total'
2012
     `-c' in `du'.
2013
 
2014
`touch'
2015
     `-t' in Make, `ranlib', and `recode'.
2016
 
2017
`trace'
2018
     `-t' in `m4'.
2019
 
2020
`traditional'
2021
     `-t' in `hello'; `-W traditional' in `gawk'; `-G' in `ed', `m4',
2022
     and `ptx'.
2023
 
2024
`tty'
2025
     Used in GDB.
2026
 
2027
`typedefs'
2028
     `-t' in `ctags'.
2029
 
2030
`typedefs-and-c++'
2031
     `-T' in `ctags'.
2032
 
2033
`typeset-mode'
2034
     `-t' in `ptx'.
2035
 
2036
`uncompress'
2037
     `-z' in `tar'.
2038
 
2039
`unconditional'
2040
     `-u' in `cpio'.
2041
 
2042
`undefine'
2043
     `-U' in `m4'.
2044
 
2045
`undefined-only'
2046
     `-u' in `nm'.
2047
 
2048
`update'
2049
     `-u' in `cp', `ctags', `mv', `tar'.
2050
 
2051
`usage'
2052
     Used in `gawk'; same as `--help'.
2053
 
2054
`uuencode'
2055
     `-B' in `shar'.
2056
 
2057
`vanilla-operation'
2058
     `-V' in `shar'.
2059
 
2060
`verbose'
2061
     Print more information about progress.  Many programs support this.
2062
 
2063
`verify'
2064
     `-W' in `tar'.
2065
 
2066
`version'
2067
     Print the version number.
2068
 
2069
`version-control'
2070
     `-V' in `cp', `ln', `mv'.
2071
 
2072
`vgrind'
2073
     `-v' in `ctags'.
2074
 
2075
`volume'
2076
     `-V' in `tar'.
2077
 
2078
`what-if'
2079
     `-W' in Make.
2080
 
2081
`whole-size-limit'
2082
     `-l' in `shar'.
2083
 
2084
`width'
2085
     `-w' in `ls' and `ptx'.
2086
 
2087
`word-regexp'
2088
     `-W' in `ptx'.
2089
 
2090
`writable'
2091
     `-T' in `who'.
2092
 
2093
`zeros'
2094
     `-z' in `gprof'.
2095
 
2096

2097
File: standards.info,  Node: Memory Usage,  Next: File Usage,  Prev: Option Table,  Up: Program Behavior
2098
 
2099
4.9 Memory Usage
2100
================
2101
 
2102
If a program typically uses just a few meg of memory, don't bother
2103
making any effort to reduce memory usage.  For example, if it is
2104
impractical for other reasons to operate on files more than a few meg
2105
long, it is reasonable to read entire input files into memory to
2106
operate on them.
2107
 
2108
   However, for programs such as `cat' or `tail', that can usefully
2109
operate on very large files, it is important to avoid using a technique
2110
that would artificially limit the size of files it can handle.  If a
2111
program works by lines and could be applied to arbitrary user-supplied
2112
input files, it should keep only a line in memory, because this is not
2113
very hard and users will want to be able to operate on input files that
2114
are bigger than will fit in memory all at once.
2115
 
2116
   If your program creates complicated data structures, just make them
2117
in memory and give a fatal error if `malloc' returns zero.
2118
 
2119

2120
File: standards.info,  Node: File Usage,  Prev: Memory Usage,  Up: Program Behavior
2121
 
2122
4.10 File Usage
2123
===============
2124
 
2125
Programs should be prepared to operate when `/usr' and `/etc' are
2126
read-only file systems.  Thus, if the program manages log files, lock
2127
files, backup files, score files, or any other files which are modified
2128
for internal purposes, these files should not be stored in `/usr' or
2129
`/etc'.
2130
 
2131
   There are two exceptions.  `/etc' is used to store system
2132
configuration information; it is reasonable for a program to modify
2133
files in `/etc' when its job is to update the system configuration.
2134
Also, if the user explicitly asks to modify one file in a directory, it
2135
is reasonable for the program to store other files in the same
2136
directory.
2137
 
2138

2139
File: standards.info,  Node: Writing C,  Next: Documentation,  Prev: Program Behavior,  Up: Top
2140
 
2141
5 Making The Best Use of C
2142
**************************
2143
 
2144
This chapter provides advice on how best to use the C language when
2145
writing GNU software.
2146
 
2147
* Menu:
2148
 
2149
* Formatting::                  Formatting your source code.
2150
* Comments::                    Commenting your work.
2151
* Syntactic Conventions::       Clean use of C constructs.
2152
* Names::                       Naming variables, functions, and files.
2153
* System Portability::          Portability among different operating systems.
2154
* CPU Portability::             Supporting the range of CPU types.
2155
* System Functions::            Portability and ``standard'' library functions.
2156
* Internationalization::        Techniques for internationalization.
2157
* Character Set::               Use ASCII by default.
2158
* Quote Characters::            Use `...' in the C locale.
2159
* Mmap::                        How you can safely use `mmap'.
2160
 
2161

2162
File: standards.info,  Node: Formatting,  Next: Comments,  Up: Writing C
2163
 
2164
5.1 Formatting Your Source Code
2165
===============================
2166
 
2167
It is important to put the open-brace that starts the body of a C
2168
function in column one, so that they will start a defun.  Several tools
2169
look for open-braces in column one to find the beginnings of C
2170
functions.  These tools will not work on code not formatted that way.
2171
 
2172
   Avoid putting open-brace, open-parenthesis or open-bracket in column
2173
one when they are inside a function, so that they won't start a defun.
2174
The open-brace that starts a `struct' body can go in column one if you
2175
find it useful to treat that definition as a defun.
2176
 
2177
   It is also important for function definitions to start the name of
2178
the function in column one.  This helps people to search for function
2179
definitions, and may also help certain tools recognize them.  Thus,
2180
using Standard C syntax, the format is this:
2181
 
2182
     static char *
2183
     concat (char *s1, char *s2)
2184
     {
2185
       ...
2186
     }
2187
 
2188
or, if you want to use traditional C syntax, format the definition like
2189
this:
2190
 
2191
     static char *
2192
     concat (s1, s2)        /* Name starts in column one here */
2193
          char *s1, *s2;
2194
     {                     /* Open brace in column one here */
2195
       ...
2196
     }
2197
 
2198
   In Standard C, if the arguments don't fit nicely on one line, split
2199
it like this:
2200
 
2201
     int
2202
     lots_of_args (int an_integer, long a_long, short a_short,
2203
                   double a_double, float a_float)
2204
     ...
2205
 
2206
   The rest of this section gives our recommendations for other aspects
2207
of C formatting style, which is also the default style of the `indent'
2208
program in version 1.2 and newer.  It corresponds to the options
2209
 
2210
     -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
2211
     -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
2212
 
2213
   We don't think of these recommendations as requirements, because it
2214
causes no problems for users if two different programs have different
2215
formatting styles.
2216
 
2217
   But whatever style you use, please use it consistently, since a
2218
mixture of styles within one program tends to look ugly.  If you are
2219
contributing changes to an existing program, please follow the style of
2220
that program.
2221
 
2222
   For the body of the function, our recommended style looks like this:
2223
 
2224
     if (x < foo (y, z))
2225
       haha = bar[4] + 5;
2226
     else
2227
       {
2228
         while (z)
2229
           {
2230
             haha += foo (z, z);
2231
             z--;
2232
           }
2233
         return ++x + bar ();
2234
       }
2235
 
2236
   We find it easier to read a program when it has spaces before the
2237
open-parentheses and after the commas.  Especially after the commas.
2238
 
2239
   When you split an expression into multiple lines, split it before an
2240
operator, not after one.  Here is the right way:
2241
 
2242
     if (foo_this_is_long && bar > win (x, y, z)
2243
         && remaining_condition)
2244
 
2245
   Try to avoid having two operators of different precedence at the same
2246
level of indentation.  For example, don't write this:
2247
 
2248
     mode = (inmode[j] == VOIDmode
2249
             || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
2250
             ? outmode[j] : inmode[j]);
2251
 
2252
   Instead, use extra parentheses so that the indentation shows the
2253
nesting:
2254
 
2255
     mode = ((inmode[j] == VOIDmode
2256
              || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
2257
             ? outmode[j] : inmode[j]);
2258
 
2259
   Insert extra parentheses so that Emacs will indent the code properly.
2260
For example, the following indentation looks nice if you do it by hand,
2261
 
2262
     v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2263
         + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
2264
 
2265
but Emacs would alter it.  Adding a set of parentheses produces
2266
something that looks equally nice, and which Emacs will preserve:
2267
 
2268
     v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
2269
          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
2270
 
2271
   Format do-while statements like this:
2272
 
2273
     do
2274
       {
2275
         a = foo (a);
2276
       }
2277
     while (a > 0);
2278
 
2279
   Please use formfeed characters (control-L) to divide the program into
2280
pages at logical places (but not within a function).  It does not matter
2281
just how long the pages are, since they do not have to fit on a printed
2282
page.  The formfeeds should appear alone on lines by themselves.
2283
 
2284

2285
File: standards.info,  Node: Comments,  Next: Syntactic Conventions,  Prev: Formatting,  Up: Writing C
2286
 
2287
5.2 Commenting Your Work
2288
========================
2289
 
2290
Every program should start with a comment saying briefly what it is for.
2291
Example: `fmt - filter for simple filling of text'.  This comment
2292
should be at the top of the source file containing the `main' function
2293
of the program.
2294
 
2295
   Also, please write a brief comment at the start of each source file,
2296
with the file name and a line or two about the overall purpose of the
2297
file.
2298
 
2299
   Please write the comments in a GNU program in English, because
2300
English is the one language that nearly all programmers in all
2301
countries can read.  If you do not write English well, please write
2302
comments in English as well as you can, then ask other people to help
2303
rewrite them.  If you can't write comments in English, please find
2304
someone to work with you and translate your comments into English.
2305
 
2306
   Please put a comment on each function saying what the function does,
2307
what sorts of arguments it gets, and what the possible values of
2308
arguments mean and are used for.  It is not necessary to duplicate in
2309
words the meaning of the C argument declarations, if a C type is being
2310
used in its customary fashion.  If there is anything nonstandard about
2311
its use (such as an argument of type `char *' which is really the
2312
address of the second character of a string, not the first), or any
2313
possible values that would not work the way one would expect (such as,
2314
that strings containing newlines are not guaranteed to work), be sure
2315
to say so.
2316
 
2317
   Also explain the significance of the return value, if there is one.
2318
 
2319
   Please put two spaces after the end of a sentence in your comments,
2320
so that the Emacs sentence commands will work.  Also, please write
2321
complete sentences and capitalize the first word.  If a lower-case
2322
identifier comes at the beginning of a sentence, don't capitalize it!
2323
Changing the spelling makes it a different identifier.  If you don't
2324
like starting a sentence with a lower case letter, write the sentence
2325
differently (e.g., "The identifier lower-case is ...").
2326
 
2327
   The comment on a function is much clearer if you use the argument
2328
names to speak about the argument values.  The variable name itself
2329
should be lower case, but write it in upper case when you are speaking
2330
about the value rather than the variable itself.  Thus, "the inode
2331
number NODE_NUM" rather than "an inode".
2332
 
2333
   There is usually no purpose in restating the name of the function in
2334
the comment before it, because the reader can see that for himself.
2335
There might be an exception when the comment is so long that the
2336
function itself would be off the bottom of the screen.
2337
 
2338
   There should be a comment on each static variable as well, like this:
2339
 
2340
     /* Nonzero means truncate lines in the display;
2341
        zero means continue them.  */
2342
     int truncate_lines;
2343
 
2344
   Every `#endif' should have a comment, except in the case of short
2345
conditionals (just a few lines) that are not nested.  The comment should
2346
state the condition of the conditional that is ending, _including its
2347
sense_.  `#else' should have a comment describing the condition _and
2348
sense_ of the code that follows.  For example:
2349
 
2350
     #ifdef foo
2351
       ...
2352
     #else /* not foo */
2353
       ...
2354
     #endif /* not foo */
2355
     #ifdef foo
2356
       ...
2357
     #endif /* foo */
2358
 
2359
but, by contrast, write the comments this way for a `#ifndef':
2360
 
2361
     #ifndef foo
2362
       ...
2363
     #else /* foo */
2364
       ...
2365
     #endif /* foo */
2366
     #ifndef foo
2367
       ...
2368
     #endif /* not foo */
2369
 
2370

2371
File: standards.info,  Node: Syntactic Conventions,  Next: Names,  Prev: Comments,  Up: Writing C
2372
 
2373
5.3 Clean Use of C Constructs
2374
=============================
2375
 
2376
Please explicitly declare the types of all objects.  For example, you
2377
should explicitly declare all arguments to functions, and you should
2378
declare functions to return `int' rather than omitting the `int'.
2379
 
2380
   Some programmers like to use the GCC `-Wall' option, and change the
2381
code whenever it issues a warning.  If you want to do this, then do.
2382
Other programmers prefer not to use `-Wall', because it gives warnings
2383
for valid and legitimate code which they do not want to change.  If you
2384
want to do this, then do.  The compiler should be your servant, not
2385
your master.
2386
 
2387
   Declarations of external functions and functions to appear later in
2388
the source file should all go in one place near the beginning of the
2389
file (somewhere before the first function definition in the file), or
2390
else should go in a header file.  Don't put `extern' declarations inside
2391
functions.
2392
 
2393
   It used to be common practice to use the same local variables (with
2394
names like `tem') over and over for different values within one
2395
function.  Instead of doing this, it is better to declare a separate
2396
local variable for each distinct purpose, and give it a name which is
2397
meaningful.  This not only makes programs easier to understand, it also
2398
facilitates optimization by good compilers.  You can also move the
2399
declaration of each local variable into the smallest scope that includes
2400
all its uses.  This makes the program even cleaner.
2401
 
2402
   Don't use local variables or parameters that shadow global
2403
identifiers.
2404
 
2405
   Don't declare multiple variables in one declaration that spans lines.
2406
Start a new declaration on each line, instead.  For example, instead of
2407
this:
2408
 
2409
     int    foo,
2410
            bar;
2411
 
2412
write either this:
2413
 
2414
     int foo, bar;
2415
 
2416
or this:
2417
 
2418
     int foo;
2419
     int bar;
2420
 
2421
(If they are global variables, each should have a comment preceding it
2422
anyway.)
2423
 
2424
   When you have an `if'-`else' statement nested in another `if'
2425
statement, always put braces around the `if'-`else'.  Thus, never write
2426
like this:
2427
 
2428
     if (foo)
2429
       if (bar)
2430
         win ();
2431
       else
2432
         lose ();
2433
 
2434
always like this:
2435
 
2436
     if (foo)
2437
       {
2438
         if (bar)
2439
           win ();
2440
         else
2441
           lose ();
2442
       }
2443
 
2444
   If you have an `if' statement nested inside of an `else' statement,
2445
either write `else if' on one line, like this,
2446
 
2447
     if (foo)
2448
       ...
2449
     else if (bar)
2450
       ...
2451
 
2452
with its `then'-part indented like the preceding `then'-part, or write
2453
the nested `if' within braces like this:
2454
 
2455
     if (foo)
2456
       ...
2457
     else
2458
       {
2459
         if (bar)
2460
           ...
2461
       }
2462
 
2463
   Don't declare both a structure tag and variables or typedefs in the
2464
same declaration.  Instead, declare the structure tag separately and
2465
then use it to declare the variables or typedefs.
2466
 
2467
   Try to avoid assignments inside `if'-conditions (assignments inside
2468
`while'-conditions are ok).  For example, don't write this:
2469
 
2470
     if ((foo = (char *) malloc (sizeof *foo)) == 0)
2471
       fatal ("virtual memory exhausted");
2472
 
2473
instead, write this:
2474
 
2475
     foo = (char *) malloc (sizeof *foo);
2476
     if (foo == 0)
2477
       fatal ("virtual memory exhausted");
2478
 
2479
   Don't make the program ugly to placate `lint'.  Please don't insert
2480
any casts to `void'.  Zero without a cast is perfectly fine as a null
2481
pointer constant, except when calling a varargs function.
2482
 
2483

2484
File: standards.info,  Node: Names,  Next: System Portability,  Prev: Syntactic Conventions,  Up: Writing C
2485
 
2486
5.4 Naming Variables, Functions, and Files
2487
==========================================
2488
 
2489
The names of global variables and functions in a program serve as
2490
comments of a sort.  So don't choose terse names--instead, look for
2491
names that give useful information about the meaning of the variable or
2492
function.  In a GNU program, names should be English, like other
2493
comments.
2494
 
2495
   Local variable names can be shorter, because they are used only
2496
within one context, where (presumably) comments explain their purpose.
2497
 
2498
   Try to limit your use of abbreviations in symbol names.  It is ok to
2499
make a few abbreviations, explain what they mean, and then use them
2500
frequently, but don't use lots of obscure abbreviations.
2501
 
2502
   Please use underscores to separate words in a name, so that the Emacs
2503
word commands can be useful within them.  Stick to lower case; reserve
2504
upper case for macros and `enum' constants, and for name-prefixes that
2505
follow a uniform convention.
2506
 
2507
   For example, you should use names like `ignore_space_change_flag';
2508
don't use names like `iCantReadThis'.
2509
 
2510
   Variables that indicate whether command-line options have been
2511
specified should be named after the meaning of the option, not after
2512
the option-letter.  A comment should state both the exact meaning of
2513
the option and its letter.  For example,
2514
 
2515
     /* Ignore changes in horizontal whitespace (-b).  */
2516
     int ignore_space_change_flag;
2517
 
2518
   When you want to define names with constant integer values, use
2519
`enum' rather than `#define'.  GDB knows about enumeration constants.
2520
 
2521
   You might want to make sure that none of the file names would
2522
conflict if the files were loaded onto an MS-DOS file system which
2523
shortens the names.  You can use the program `doschk' to test for this.
2524
 
2525
   Some GNU programs were designed to limit themselves to file names of
2526
14 characters or less, to avoid file name conflicts if they are read
2527
into older System V systems.  Please preserve this feature in the
2528
existing GNU programs that have it, but there is no need to do this in
2529
new GNU programs.  `doschk' also reports file names longer than 14
2530
characters.
2531
 
2532

2533
File: standards.info,  Node: System Portability,  Next: CPU Portability,  Prev: Names,  Up: Writing C
2534
 
2535
5.5 Portability between System Types
2536
====================================
2537
 
2538
In the Unix world, "portability" refers to porting to different Unix
2539
versions.  For a GNU program, this kind of portability is desirable, but
2540
not paramount.
2541
 
2542
   The primary purpose of GNU software is to run on top of the GNU
2543
kernel, compiled with the GNU C compiler, on various types of CPU.  So
2544
the kinds of portability that are absolutely necessary are quite
2545
limited.  But it is important to support Linux-based GNU systems, since
2546
they are the form of GNU that is popular.
2547
 
2548
   Beyond that, it is good to support the other free operating systems
2549
(*BSD), and it is nice to support other Unix-like systems if you want
2550
to.  Supporting a variety of Unix-like systems is desirable, although
2551
not paramount.  It is usually not too hard, so you may as well do it.
2552
But you don't have to consider it an obligation, if it does turn out to
2553
be hard.
2554
 
2555
   The easiest way to achieve portability to most Unix-like systems is
2556
to use Autoconf.  It's unlikely that your program needs to know more
2557
information about the host platform than Autoconf can provide, simply
2558
because most of the programs that need such knowledge have already been
2559
written.
2560
 
2561
   Avoid using the format of semi-internal data bases (e.g.,
2562
directories) when there is a higher-level alternative (`readdir').
2563
 
2564
   As for systems that are not like Unix, such as MSDOS, Windows, VMS,
2565
MVS, and older Macintosh systems, supporting them is often a lot of
2566
work.  When that is the case, it is better to spend your time adding
2567
features that will be useful on GNU and GNU/Linux, rather than on
2568
supporting other incompatible systems.
2569
 
2570
   If you do support Windows, please do not abbreviate it as "win".  In
2571
hacker terminology, calling something a "win" is a form of praise.
2572
You're free to praise Microsoft Windows on your own if you want, but
2573
please don't do this in GNU packages.  Instead of abbreviating
2574
"Windows" to "un", you can write it in full or abbreviate it to "woe"
2575
or "w".  In GNU Emacs, for instance, we use `w32' in file names of
2576
Windows-specific files, but the macro for Windows conditionals is
2577
called `WINDOWSNT'.
2578
 
2579
   It is a good idea to define the "feature test macro" `_GNU_SOURCE'
2580
when compiling your C files.  When you compile on GNU or GNU/Linux,
2581
this will enable the declarations of GNU library extension functions,
2582
and that will usually give you a compiler error message if you define
2583
the same function names in some other way in your program.  (You don't
2584
have to actually _use_ these functions, if you prefer to make the
2585
program more portable to other systems.)
2586
 
2587
   But whether or not you use these GNU extensions, you should avoid
2588
using their names for any other meanings.  Doing so would make it hard
2589
to move your code into other GNU programs.
2590
 
2591

2592
File: standards.info,  Node: CPU Portability,  Next: System Functions,  Prev: System Portability,  Up: Writing C
2593
 
2594
5.6 Portability between CPUs
2595
============================
2596
 
2597
Even GNU systems will differ because of differences among CPU
2598
types--for example, difference in byte ordering and alignment
2599
requirements.  It is absolutely essential to handle these differences.
2600
However, don't make any effort to cater to the possibility that an
2601
`int' will be less than 32 bits.  We don't support 16-bit machines in
2602
GNU.
2603
 
2604
   Similarly, don't make any effort to cater to the possibility that
2605
`long' will be smaller than predefined types like `size_t'.  For
2606
example, the following code is ok:
2607
 
2608
     printf ("size = %lu\n", (unsigned long) sizeof array);
2609
     printf ("diff = %ld\n", (long) (pointer2 - pointer1));
2610
 
2611
   1989 Standard C requires this to work, and we know of only one
2612
counterexample: 64-bit programs on Microsoft Windows.  We will leave it
2613
to those who want to port GNU programs to that environment to figure
2614
out how to do it.
2615
 
2616
   Predefined file-size types like `off_t' are an exception: they are
2617
longer than `long' on many platforms, so code like the above won't work
2618
with them.  One way to print an `off_t' value portably is to print its
2619
digits yourself, one by one.
2620
 
2621
   Don't assume that the address of an `int' object is also the address
2622
of its least-significant byte.  This is false on big-endian machines.
2623
Thus, don't make the following mistake:
2624
 
2625
     int c;
2626
     ...
2627
     while ((c = getchar ()) != EOF)
2628
       write (file_descriptor, &c, 1);
2629
 
2630
Instead, use `unsigned char' as follows.  (The `unsigned' is for
2631
portability to unusual systems where `char' is signed and where there
2632
is integer overflow checking.)
2633
 
2634
     int c;
2635
     while ((c = getchar ()) != EOF)
2636
       {
2637
         unsigned char u = c;
2638
         write (file_descriptor, &u, 1);
2639
       }
2640
 
2641
   It used to be ok to not worry about the difference between pointers
2642
and integers when passing arguments to functions.  However, on most
2643
modern 64-bit machines pointers are wider than `int'.  Conversely,
2644
integer types like `long long int' and `off_t' are wider than pointers
2645
on most modern 32-bit machines.  Hence it's often better nowadays to
2646
use prototypes to define functions whose argument types are not trivial.
2647
 
2648
   In particular, if functions accept varying argument counts or types
2649
they should be declared using prototypes containing `...' and defined
2650
using `stdarg.h'.  For an example of this, please see the Gnulib
2651
(http://www.gnu.org/software/gnulib/) error module, which declares and
2652
defines the following function:
2653
 
2654
     /* Print a message with `fprintf (stderr, FORMAT, ...)';
2655
        if ERRNUM is nonzero, follow it with ": " and strerror (ERRNUM).
2656
        If STATUS is nonzero, terminate the program with `exit (STATUS)'.  */
2657
 
2658
     void error (int status, int errnum, const char *format, ...);
2659
 
2660
   A simple way to use the Gnulib error module is to obtain the two
2661
source files `error.c' and `error.h' from the Gnulib library source
2662
code repository at
2663
`http://savannah.gnu.org/cgi-bin/viewcvs/gnulib/gnulib/lib/'.  Here's a
2664
sample use:
2665
 
2666
     #include "error.h"
2667
     #include 
2668
     #include 
2669
 
2670
     char *program_name = "myprogram";
2671
 
2672
     FILE *
2673
     xfopen (char const *name)
2674
     {
2675
       FILE *fp = fopen (name, "r");
2676
       if (! fp)
2677
         error (1, errno, "cannot read %s", name);
2678
       return fp;
2679
     }
2680
 
2681
   Avoid casting pointers to integers if you can.  Such casts greatly
2682
reduce portability, and in most programs they are easy to avoid.  In the
2683
cases where casting pointers to integers is essential--such as, a Lisp
2684
interpreter which stores type information as well as an address in one
2685
word--you'll have to make explicit provisions to handle different word
2686
sizes.  You will also need to make provision for systems in which the
2687
normal range of addresses you can get from `malloc' starts far away
2688
from zero.
2689
 
2690

2691
File: standards.info,  Node: System Functions,  Next: Internationalization,  Prev: CPU Portability,  Up: Writing C
2692
 
2693
5.7 Calling System Functions
2694
============================
2695
 
2696
C implementations differ substantially.  Standard C reduces but does
2697
not eliminate the incompatibilities; meanwhile, many GNU packages still
2698
support pre-standard compilers because this is not hard to do.  This
2699
chapter gives recommendations for how to use the more-or-less standard C
2700
library functions to avoid unnecessary loss of portability.
2701
 
2702
   * Don't use the return value of `sprintf'.  It returns the number of
2703
     characters written on some systems, but not on all systems.
2704
 
2705
   * Be aware that `vfprintf' is not always available.
2706
 
2707
   * `main' should be declared to return type `int'.  It should
2708
     terminate either by calling `exit' or by returning the integer
2709
     status code; make sure it cannot ever return an undefined value.
2710
 
2711
   * Don't declare system functions explicitly.
2712
 
2713
     Almost any declaration for a system function is wrong on some
2714
     system.  To minimize conflicts, leave it to the system header
2715
     files to declare system functions.  If the headers don't declare a
2716
     function, let it remain undeclared.
2717
 
2718
     While it may seem unclean to use a function without declaring it,
2719
     in practice this works fine for most system library functions on
2720
     the systems where this really happens; thus, the disadvantage is
2721
     only theoretical.  By contrast, actual declarations have
2722
     frequently caused actual conflicts.
2723
 
2724
   * If you must declare a system function, don't specify the argument
2725
     types.  Use an old-style declaration, not a Standard C prototype.
2726
     The more you specify about the function, the more likely a
2727
     conflict.
2728
 
2729
   * In particular, don't unconditionally declare `malloc' or `realloc'.
2730
 
2731
     Most GNU programs use those functions just once, in functions
2732
     conventionally named `xmalloc' and `xrealloc'.  These functions
2733
     call `malloc' and `realloc', respectively, and check the results.
2734
 
2735
     Because `xmalloc' and `xrealloc' are defined in your program, you
2736
     can declare them in other files without any risk of type conflict.
2737
 
2738
     On most systems, `int' is the same length as a pointer; thus, the
2739
     calls to `malloc' and `realloc' work fine.  For the few
2740
     exceptional systems (mostly 64-bit machines), you can use
2741
     *conditionalized* declarations of `malloc' and `realloc'--or put
2742
     these declarations in configuration files specific to those
2743
     systems.
2744
 
2745
   * The string functions require special treatment.  Some Unix systems
2746
     have a header file `string.h'; others have `strings.h'.  Neither
2747
     file name is portable.  There are two things you can do: use
2748
     Autoconf to figure out which file to include, or don't include
2749
     either file.
2750
 
2751
   * If you don't include either strings file, you can't get
2752
     declarations for the string functions from the header file in the
2753
     usual way.
2754
 
2755
     That causes less of a problem than you might think.  The newer
2756
     standard string functions should be avoided anyway because many
2757
     systems still don't support them.  The string functions you can
2758
     use are these:
2759
 
2760
          strcpy   strncpy   strcat   strncat
2761
          strlen   strcmp    strncmp
2762
          strchr   strrchr
2763
 
2764
     The copy and concatenate functions work fine without a declaration
2765
     as long as you don't use their values.  Using their values without
2766
     a declaration fails on systems where the width of a pointer
2767
     differs from the width of `int', and perhaps in other cases.  It
2768
     is trivial to avoid using their values, so do that.
2769
 
2770
     The compare functions and `strlen' work fine without a declaration
2771
     on most systems, possibly all the ones that GNU software runs on.
2772
     You may find it necessary to declare them *conditionally* on a few
2773
     systems.
2774
 
2775
     The search functions must be declared to return `char *'.  Luckily,
2776
     there is no variation in the data type they return.  But there is
2777
     variation in their names.  Some systems give these functions the
2778
     names `index' and `rindex'; other systems use the names `strchr'
2779
     and `strrchr'.  Some systems support both pairs of names, but
2780
     neither pair works on all systems.
2781
 
2782
     You should pick a single pair of names and use it throughout your
2783
     program.  (Nowadays, it is better to choose `strchr' and `strrchr'
2784
     for new programs, since those are the standard names.)  Declare
2785
     both of those names as functions returning `char *'.  On systems
2786
     which don't support those names, define them as macros in terms of
2787
     the other pair.  For example, here is what to put at the beginning
2788
     of your file (or in a header) if you want to use the names
2789
     `strchr' and `strrchr' throughout:
2790
 
2791
          #ifndef HAVE_STRCHR
2792
          #define strchr index
2793
          #endif
2794
          #ifndef HAVE_STRRCHR
2795
          #define strrchr rindex
2796
          #endif
2797
 
2798
          char *strchr ();
2799
          char *strrchr ();
2800
 
2801
   Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
2802
defined in systems where the corresponding functions exist.  One way to
2803
get them properly defined is to use Autoconf.
2804
 
2805

2806
File: standards.info,  Node: Internationalization,  Next: Character Set,  Prev: System Functions,  Up: Writing C
2807
 
2808
5.8 Internationalization
2809
========================
2810
 
2811
GNU has a library called GNU gettext that makes it easy to translate the
2812
messages in a program into various languages.  You should use this
2813
library in every program.  Use English for the messages as they appear
2814
in the program, and let gettext provide the way to translate them into
2815
other languages.
2816
 
2817
   Using GNU gettext involves putting a call to the `gettext' macro
2818
around each string that might need translation--like this:
2819
 
2820
     printf (gettext ("Processing file `%s'..."));
2821
 
2822
This permits GNU gettext to replace the string `"Processing file
2823
`%s'..."' with a translated version.
2824
 
2825
   Once a program uses gettext, please make a point of writing calls to
2826
`gettext' when you add new strings that call for translation.
2827
 
2828
   Using GNU gettext in a package involves specifying a "text domain
2829
name" for the package.  The text domain name is used to separate the
2830
translations for this package from the translations for other packages.
2831
Normally, the text domain name should be the same as the name of the
2832
package--for example, `coreutils' for the GNU core utilities.
2833
 
2834
   To enable gettext to work well, avoid writing code that makes
2835
assumptions about the structure of words or sentences.  When you want
2836
the precise text of a sentence to vary depending on the data, use two or
2837
more alternative string constants each containing a complete sentences,
2838
rather than inserting conditionalized words or phrases into a single
2839
sentence framework.
2840
 
2841
   Here is an example of what not to do:
2842
 
2843
     printf ("%s is full", capacity > 5000000 ? "disk" : "floppy disk");
2844
 
2845
   If you apply gettext to all strings, like this,
2846
 
2847
     printf (gettext ("%s is full"),
2848
             capacity > 5000000 ? gettext ("disk") : gettext ("floppy disk"));
2849
 
2850
the translator will hardly know that "disk" and "floppy disk" are meant
2851
to be substituted in the other string.  Worse, in some languages (like
2852
French) the construction will not work: the translation of the word
2853
"full" depends on the gender of the first part of the sentence; it
2854
happens to be not the same for "disk" as for "floppy disk".
2855
 
2856
   Complete sentences can be translated without problems:
2857
 
2858
     printf (capacity > 5000000 ? gettext ("disk is full")
2859
             : gettext ("floppy disk is full"));
2860
 
2861
   A similar problem appears at the level of sentence structure with
2862
this code:
2863
 
2864
     printf ("#  Implicit rule search has%s been done.\n",
2865
             f->tried_implicit ? "" : " not");
2866
 
2867
Adding `gettext' calls to this code cannot give correct results for all
2868
languages, because negation in some languages requires adding words at
2869
more than one place in the sentence.  By contrast, adding `gettext'
2870
calls does the job straightforwardly if the code starts out like this:
2871
 
2872
     printf (f->tried_implicit
2873
             ? "#  Implicit rule search has been done.\n",
2874
             : "#  Implicit rule search has not been done.\n");
2875
 
2876
   Another example is this one:
2877
 
2878
     printf ("%d file%s processed", nfiles,
2879
             nfiles != 1 ? "s" : "");
2880
 
2881
The problem with this example is that it assumes that plurals are made
2882
by adding `s'.  If you apply gettext to the format string, like this,
2883
 
2884
     printf (gettext ("%d file%s processed"), nfiles,
2885
             nfiles != 1 ? "s" : "");
2886
 
2887
the message can use different words, but it will still be forced to use
2888
`s' for the plural.  Here is a better way, with gettext being applied to
2889
the two strings independently:
2890
 
2891
     printf ((nfiles != 1 ? gettext ("%d files processed")
2892
              : gettext ("%d file processed")),
2893
             nfiles);
2894
 
2895
But this still doesn't work for languages like Polish, which has three
2896
plural forms: one for nfiles == 1, one for nfiles == 2, 3, 4, 22, 23,
2897
24, ...  and one for the rest.  The GNU `ngettext' function solves this
2898
problem:
2899
 
2900
     printf (ngettext ("%d files processed", "%d file processed", nfiles),
2901
             nfiles);
2902
 
2903

2904
File: standards.info,  Node: Character Set,  Next: Quote Characters,  Prev: Internationalization,  Up: Writing C
2905
 
2906
5.9 Character Set
2907
=================
2908
 
2909
Sticking to the ASCII character set (plain text, 7-bit characters) is
2910
preferred in GNU source code comments, text documents, and other
2911
contexts, unless there is good reason to do something else because of
2912
the application domain.  For example, if source code deals with the
2913
French Revolutionary calendar, it is OK if its literal strings contain
2914
accented characters in month names like "Flore'al".  Also, it is OK to
2915
use non-ASCII characters to represent proper names of contributors in
2916
change logs (*note Change Logs::).
2917
 
2918
   If you need to use non-ASCII characters, you should normally stick
2919
with one encoding, as one cannot in general mix encodings reliably.
2920
 
2921

2922
File: standards.info,  Node: Quote Characters,  Next: Mmap,  Prev: Character Set,  Up: Writing C
2923
 
2924
5.10 Quote Characters
2925
=====================
2926
 
2927
In the C locale, GNU programs should stick to plain ASCII for quotation
2928
characters in messages to users: preferably 0x60 (``') for left quotes
2929
and 0x27 (`'') for right quotes.  It is ok, but not required, to use
2930
locale-specific quotes in other locales.
2931
 
2932
   The Gnulib (http://www.gnu.org/software/gnulib/) `quote' and
2933
`quotearg' modules provide a reasonably straightforward way to support
2934
locale-specific quote characters, as well as taking care of other
2935
issues, such as quoting a filename that itself contains a quote
2936
character.  See the Gnulib documentation for usage details.
2937
 
2938
   In any case, the documentation for your program should clearly
2939
specify how it does quoting, if different than the preferred method of
2940
``' and `''.  This is especially important if the output of your
2941
program is ever likely to be parsed by another program.
2942
 
2943
   Quotation characters are a difficult area in the computing world at
2944
this time: there are no true left or right quote characters in Latin1;
2945
the ``' character we use was standardized there as a grave accent.
2946
Moreover, Latin1 is still not universally usable.
2947
 
2948
   Unicode contains the unambiguous quote characters required, and its
2949
common encoding UTF-8 is upward compatible with Latin1.  However,
2950
Unicode and UTF-8 are not universally well-supported, either.
2951
 
2952
   This may change over the next few years, and then we will revisit
2953
this.
2954
 
2955

2956
File: standards.info,  Node: Mmap,  Prev: Quote Characters,  Up: Writing C
2957
 
2958
5.11 Mmap
2959
=========
2960
 
2961
Don't assume that `mmap' either works on all files or fails for all
2962
files.  It may work on some files and fail on others.
2963
 
2964
   The proper way to use `mmap' is to try it on the specific file for
2965
which you want to use it--and if `mmap' doesn't work, fall back on
2966
doing the job in another way using `read' and `write'.
2967
 
2968
   The reason this precaution is needed is that the GNU kernel (the
2969
HURD) provides a user-extensible file system, in which there can be many
2970
different kinds of "ordinary files."  Many of them support `mmap', but
2971
some do not.  It is important to make programs handle all these kinds
2972
of files.
2973
 
2974

2975
File: standards.info,  Node: Documentation,  Next: Managing Releases,  Prev: Writing C,  Up: Top
2976
 
2977
6 Documenting Programs
2978
**********************
2979
 
2980
A GNU program should ideally come with full free documentation, adequate
2981
for both reference and tutorial purposes.  If the package can be
2982
programmed or extended, the documentation should cover programming or
2983
extending it, as well as just using it.
2984
 
2985
* Menu:
2986
 
2987
* GNU Manuals::                 Writing proper manuals.
2988
* Doc Strings and Manuals::     Compiling doc strings doesn't make a manual.
2989
* Manual Structure Details::    Specific structure conventions.
2990
* License for Manuals::         Writing the distribution terms for a manual.
2991
* Manual Credits::              Giving credit to documentation contributors.
2992
* Printed Manuals::             Mentioning the printed manual.
2993
* NEWS File::                   NEWS files supplement manuals.
2994
* Change Logs::                 Recording changes.
2995
* Man Pages::                   Man pages are secondary.
2996
* Reading other Manuals::       How far you can go in learning
2997
                                from other manuals.
2998
 
2999

3000
File: standards.info,  Node: GNU Manuals,  Next: Doc Strings and Manuals,  Up: Documentation
3001
 
3002
6.1 GNU Manuals
3003
===============
3004
 
3005
The preferred document format for the GNU system is the Texinfo
3006
formatting language.  Every GNU package should (ideally) have
3007
documentation in Texinfo both for reference and for learners.  Texinfo
3008
makes it possible to produce a good quality formatted book, using TeX,
3009
and to generate an Info file.  It is also possible to generate HTML
3010
output from Texinfo source.  See the Texinfo manual, either the
3011
hardcopy, or the on-line version available through `info' or the Emacs
3012
Info subsystem (`C-h i').
3013
 
3014
   Nowadays some other formats such as Docbook and Sgmltexi can be
3015
converted automatically into Texinfo.  It is ok to produce the Texinfo
3016
documentation by conversion this way, as long as it gives good results.
3017
 
3018
   Make sure your manual is clear to a reader who knows nothing about
3019
the topic and reads it straight through.  This means covering basic
3020
topics at the beginning, and advanced topics only later.  This also
3021
means defining every specialized term when it is first used.
3022
 
3023
   Programmers tend to carry over the structure of the program as the
3024
structure for its documentation.  But this structure is not necessarily
3025
good for explaining how to use the program; it may be irrelevant and
3026
confusing for a user.
3027
 
3028
   Instead, the right way to structure documentation is according to the
3029
concepts and questions that a user will have in mind when reading it.
3030
This principle applies at every level, from the lowest (ordering
3031
sentences in a paragraph) to the highest (ordering of chapter topics
3032
within the manual).  Sometimes this structure of ideas matches the
3033
structure of the implementation of the software being documented--but
3034
often they are different.  An important part of learning to write good
3035
documentation is to learn to notice when you have unthinkingly
3036
structured the documentation like the implementation, stop yourself,
3037
and look for better alternatives.
3038
 
3039
   For example, each program in the GNU system probably ought to be
3040
documented in one manual; but this does not mean each program should
3041
have its own manual.  That would be following the structure of the
3042
implementation, rather than the structure that helps the user
3043
understand.
3044
 
3045
   Instead, each manual should cover a coherent _topic_.  For example,
3046
instead of a manual for `diff' and a manual for `diff3', we have one
3047
manual for "comparison of files" which covers both of those programs,
3048
as well as `cmp'.  By documenting these programs together, we can make
3049
the whole subject clearer.
3050
 
3051
   The manual which discusses a program should certainly document all of
3052
the program's command-line options and all of its commands.  It should
3053
give examples of their use.  But don't organize the manual as a list of
3054
features.  Instead, organize it logically, by subtopics.  Address the
3055
questions that a user will ask when thinking about the job that the
3056
program does.  Don't just tell the reader what each feature can do--say
3057
what jobs it is good for, and show how to use it for those jobs.
3058
Explain what is recommended usage, and what kinds of usage users should
3059
avoid.
3060
 
3061
   In general, a GNU manual should serve both as tutorial and reference.
3062
It should be set up for convenient access to each topic through Info,
3063
and for reading straight through (appendixes aside).  A GNU manual
3064
should give a good introduction to a beginner reading through from the
3065
start, and should also provide all the details that hackers want.  The
3066
Bison manual is a good example of this--please take a look at it to see
3067
what we mean.
3068
 
3069
   That is not as hard as it first sounds.  Arrange each chapter as a
3070
logical breakdown of its topic, but order the sections, and write their
3071
text, so that reading the chapter straight through makes sense.  Do
3072
likewise when structuring the book into chapters, and when structuring a
3073
section into paragraphs.  The watchword is, _at each point, address the
3074
most fundamental and important issue raised by the preceding text._
3075
 
3076
   If necessary, add extra chapters at the beginning of the manual which
3077
are purely tutorial and cover the basics of the subject.  These provide
3078
the framework for a beginner to understand the rest of the manual.  The
3079
Bison manual provides a good example of how to do this.
3080
 
3081
   To serve as a reference, a manual should have an Index that list all
3082
the functions, variables, options, and important concepts that are part
3083
of the program.  One combined Index should do for a short manual, but
3084
sometimes for a complex package it is better to use multiple indices.
3085
The Texinfo manual includes advice on preparing good index entries, see
3086
*Note Making Index Entries: (texinfo)Index Entries, and see *Note
3087
Defining the Entries of an Index: (texinfo)Indexing Commands.
3088
 
3089
   Don't use Unix man pages as a model for how to write GNU
3090
documentation; most of them are terse, badly structured, and give
3091
inadequate explanation of the underlying concepts.  (There are, of
3092
course, some exceptions.)  Also, Unix man pages use a particular format
3093
which is different from what we use in GNU manuals.
3094
 
3095
   Please include an email address in the manual for where to report
3096
bugs _in the text of the manual_.
3097
 
3098
   Please do not use the term "pathname" that is used in Unix
3099
documentation; use "file name" (two words) instead.  We use the term
3100
"path" only for search paths, which are lists of directory names.
3101
 
3102
   Please do not use the term "illegal" to refer to erroneous input to
3103
a computer program.  Please use "invalid" for this, and reserve the
3104
term "illegal" for activities prohibited by law.
3105
 
3106
   Please do not write `()' after a function name just to indicate it
3107
is a function.  `foo ()' is not a function, it is a function call with
3108
no arguments.
3109
 
3110

3111
File: standards.info,  Node: Doc Strings and Manuals,  Next: Manual Structure Details,  Prev: GNU Manuals,  Up: Documentation
3112
 
3113
6.2 Doc Strings and Manuals
3114
===========================
3115
 
3116
Some programming systems, such as Emacs, provide a documentation string
3117
for each function, command or variable.  You may be tempted to write a
3118
reference manual by compiling the documentation strings and writing a
3119
little additional text to go around them--but you must not do it.  That
3120
approach is a fundamental mistake.  The text of well-written
3121
documentation strings will be entirely wrong for a manual.
3122
 
3123
   A documentation string needs to stand alone--when it appears on the
3124
screen, there will be no other text to introduce or explain it.
3125
Meanwhile, it can be rather informal in style.
3126
 
3127
   The text describing a function or variable in a manual must not stand
3128
alone; it appears in the context of a section or subsection.  Other text
3129
at the beginning of the section should explain some of the concepts, and
3130
should often make some general points that apply to several functions or
3131
variables.  The previous descriptions of functions and variables in the
3132
section will also have given information about the topic.  A description
3133
written to stand alone would repeat some of that information; this
3134
redundancy looks bad.  Meanwhile, the informality that is acceptable in
3135
a documentation string is totally unacceptable in a manual.
3136
 
3137
   The only good way to use documentation strings in writing a good
3138
manual is to use them as a source of information for writing good text.
3139
 
3140

3141
File: standards.info,  Node: Manual Structure Details,  Next: License for Manuals,  Prev: Doc Strings and Manuals,  Up: Documentation
3142
 
3143
6.3 Manual Structure Details
3144
============================
3145
 
3146
The title page of the manual should state the version of the programs or
3147
packages documented in the manual.  The Top node of the manual should
3148
also contain this information.  If the manual is changing more
3149
frequently than or independent of the program, also state a version
3150
number for the manual in both of these places.
3151
 
3152
   Each program documented in the manual should have a node named
3153
`PROGRAM Invocation' or `Invoking PROGRAM'.  This node (together with
3154
its subnodes, if any) should describe the program's command line
3155
arguments and how to run it (the sort of information people would look
3156
for in a man page).  Start with an `@example' containing a template for
3157
all the options and arguments that the program uses.
3158
 
3159
   Alternatively, put a menu item in some menu whose item name fits one
3160
of the above patterns.  This identifies the node which that item points
3161
to as the node for this purpose, regardless of the node's actual name.
3162
 
3163
   The `--usage' feature of the Info reader looks for such a node or
3164
menu item in order to find the relevant text, so it is essential for
3165
every Texinfo file to have one.
3166
 
3167
   If one manual describes several programs, it should have such a node
3168
for each program described in the manual.
3169
 
3170

3171
File: standards.info,  Node: License for Manuals,  Next: Manual Credits,  Prev: Manual Structure Details,  Up: Documentation
3172
 
3173
6.4 License for Manuals
3174
=======================
3175
 
3176
Please use the GNU Free Documentation License for all GNU manuals that
3177
are more than a few pages long.  Likewise for a collection of short
3178
documents--you only need one copy of the GNU FDL for the whole
3179
collection.  For a single short document, you can use a very permissive
3180
non-copyleft license, to avoid taking up space with a long license.
3181
 
3182
   See `http://www.gnu.org/copyleft/fdl-howto.html' for more explanation
3183
of how to employ the GFDL.
3184
 
3185
   Note that it is not obligatory to include a copy of the GNU GPL or
3186
GNU LGPL in a manual whose license is neither the GPL nor the LGPL.  It
3187
can be a good idea to include the program's license in a large manual;
3188
in a short manual, whose size would be increased considerably by
3189
including the program's license, it is probably better not to include
3190
it.
3191
 
3192

3193
File: standards.info,  Node: Manual Credits,  Next: Printed Manuals,  Prev: License for Manuals,  Up: Documentation
3194
 
3195
6.5 Manual Credits
3196
==================
3197
 
3198
Please credit the principal human writers of the manual as the authors,
3199
on the title page of the manual.  If a company sponsored the work, thank
3200
the company in a suitable place in the manual, but do not cite the
3201
company as an author.
3202
 
3203

3204
File: standards.info,  Node: Printed Manuals,  Next: NEWS File,  Prev: Manual Credits,  Up: Documentation
3205
 
3206
6.6 Printed Manuals
3207
===================
3208
 
3209
The FSF publishes some GNU manuals in printed form.  To encourage sales
3210
of these manuals, the on-line versions of the manual should mention at
3211
the very start that the printed manual is available and should point at
3212
information for getting it--for instance, with a link to the page
3213
`http://www.gnu.org/order/order.html'.  This should not be included in
3214
the printed manual, though, because there it is redundant.
3215
 
3216
   It is also useful to explain in the on-line forms of the manual how
3217
the user can print out the manual from the sources.
3218
 
3219

3220
File: standards.info,  Node: NEWS File,  Next: Change Logs,  Prev: Printed Manuals,  Up: Documentation
3221
 
3222
6.7 The NEWS File
3223
=================
3224
 
3225
In addition to its manual, the package should have a file named `NEWS'
3226
which contains a list of user-visible changes worth mentioning.  In
3227
each new release, add items to the front of the file and identify the
3228
version they pertain to.  Don't discard old items; leave them in the
3229
file after the newer items.  This way, a user upgrading from any
3230
previous version can see what is new.
3231
 
3232
   If the `NEWS' file gets very long, move some of the older items into
3233
a file named `ONEWS' and put a note at the end referring the user to
3234
that file.
3235
 
3236

3237
File: standards.info,  Node: Change Logs,  Next: Man Pages,  Prev: NEWS File,  Up: Documentation
3238
 
3239
6.8 Change Logs
3240
===============
3241
 
3242
Keep a change log to describe all the changes made to program source
3243
files.  The purpose of this is so that people investigating bugs in the
3244
future will know about the changes that might have introduced the bug.
3245
Often a new bug can be found by looking at what was recently changed.
3246
More importantly, change logs can help you eliminate conceptual
3247
inconsistencies between different parts of a program, by giving you a
3248
history of how the conflicting concepts arose and who they came from.
3249
 
3250
* Menu:
3251
 
3252
* Change Log Concepts::
3253
* Style of Change Logs::
3254
* Simple Changes::
3255
* Conditional Changes::
3256
* Indicating the Part Changed::
3257
 
3258

3259
File: standards.info,  Node: Change Log Concepts,  Next: Style of Change Logs,  Up: Change Logs
3260
 
3261
6.8.1 Change Log Concepts
3262
-------------------------
3263
 
3264
You can think of the change log as a conceptual "undo list" which
3265
explains how earlier versions were different from the current version.
3266
People can see the current version; they don't need the change log to
3267
tell them what is in it.  What they want from a change log is a clear
3268
explanation of how the earlier version differed.
3269
 
3270
   The change log file is normally called `ChangeLog' and covers an
3271
entire directory.  Each directory can have its own change log, or a
3272
directory can use the change log of its parent directory-it's up to you.
3273
 
3274
   Another alternative is to record change log information with a
3275
version control system such as RCS or CVS.  This can be converted
3276
automatically to a `ChangeLog' file using `rcs2log'; in Emacs, the
3277
command `C-x v a' (`vc-update-change-log') does the job.
3278
 
3279
   There's no need to describe the full purpose of the changes or how
3280
they work together.  If you think that a change calls for explanation,
3281
you're probably right.  Please do explain it--but please put the
3282
explanation in comments in the code, where people will see it whenever
3283
they see the code.  For example, "New function" is enough for the
3284
change log when you add a function, because there should be a comment
3285
before the function definition to explain what it does.
3286
 
3287
   In the past, we recommended not mentioning changes in non-software
3288
files (manuals, help files, etc.) in change logs.  However, we've been
3289
advised that it is a good idea to include them, for the sake of
3290
copyright records.
3291
 
3292
   However, sometimes it is useful to write one line to describe the
3293
overall purpose of a batch of changes.
3294
 
3295
   The easiest way to add an entry to `ChangeLog' is with the Emacs
3296
command `M-x add-change-log-entry'.  An entry should have an asterisk,
3297
the name of the changed file, and then in parentheses the name of the
3298
changed functions, variables or whatever, followed by a colon.  Then
3299
describe the changes you made to that function or variable.
3300
 
3301

3302
File: standards.info,  Node: Style of Change Logs,  Next: Simple Changes,  Prev: Change Log Concepts,  Up: Change Logs
3303
 
3304
6.8.2 Style of Change Logs
3305
--------------------------
3306
 
3307
Here are some simple examples of change log entries, starting with the
3308
header line that says who made the change and when it was installed,
3309
followed by descriptions of specific changes.  (These examples are
3310
drawn from Emacs and GCC.)
3311
 
3312
     1998-08-17  Richard Stallman  
3313
 
3314
     * register.el (insert-register): Return nil.
3315
     (jump-to-register): Likewise.
3316
 
3317
     * sort.el (sort-subr): Return nil.
3318
 
3319
     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
3320
     Restart the tex shell if process is gone or stopped.
3321
     (tex-shell-running): New function.
3322
 
3323
     * expr.c (store_one_arg): Round size up for move_block_to_reg.
3324
     (expand_call): Round up when emitting USE insns.
3325
     * stmt.c (assign_parms): Round size up for move_block_from_reg.
3326
 
3327
   It's important to name the changed function or variable in full.
3328
Don't abbreviate function or variable names, and don't combine them.
3329
Subsequent maintainers will often search for a function name to find all
3330
the change log entries that pertain to it; if you abbreviate the name,
3331
they won't find it when they search.
3332
 
3333
   For example, some people are tempted to abbreviate groups of function
3334
names by writing `* register.el ({insert,jump-to}-register)'; this is
3335
not a good idea, since searching for `jump-to-register' or
3336
`insert-register' would not find that entry.
3337
 
3338
   Separate unrelated change log entries with blank lines.  When two
3339
entries represent parts of the same change, so that they work together,
3340
then don't put blank lines between them.  Then you can omit the file
3341
name and the asterisk when successive entries are in the same file.
3342
 
3343
   Break long lists of function names by closing continued lines with
3344
`)', rather than `,', and opening the continuation with `(' as in this
3345
example:
3346
 
3347
     * keyboard.c (menu_bar_items, tool_bar_items)
3348
     (Fexecute_extended_command): Deal with `keymap' property.
3349
 
3350
   When you install someone else's changes, put the contributor's name
3351
in the change log entry rather than in the text of the entry.  In other
3352
words, write this:
3353
 
3354
     2002-07-14  John Doe  
3355
 
3356
             * sewing.c: Make it sew.
3357
 
3358
rather than this:
3359
 
3360
     2002-07-14  Usual Maintainer  
3361
 
3362
             * sewing.c: Make it sew.  Patch by jdoe@gnu.org.
3363
 
3364
   As for the date, that should be the date you applied the change.
3365
 
3366

3367
File: standards.info,  Node: Simple Changes,  Next: Conditional Changes,  Prev: Style of Change Logs,  Up: Change Logs
3368
 
3369
6.8.3 Simple Changes
3370
--------------------
3371
 
3372
Certain simple kinds of changes don't need much detail in the change
3373
log.
3374
 
3375
   When you change the calling sequence of a function in a simple
3376
fashion, and you change all the callers of the function to use the new
3377
calling sequence, there is no need to make individual entries for all
3378
the callers that you changed.  Just write in the entry for the function
3379
being called, "All callers changed"--like this:
3380
 
3381
     * keyboard.c (Fcommand_execute): New arg SPECIAL.
3382
     All callers changed.
3383
 
3384
   When you change just comments or doc strings, it is enough to write
3385
an entry for the file, without mentioning the functions.  Just "Doc
3386
fixes" is enough for the change log.
3387
 
3388
   There's no technical need to make change log entries for
3389
documentation files.  This is because documentation is not susceptible
3390
to bugs that are hard to fix.  Documentation does not consist of parts
3391
that must interact in a precisely engineered fashion.  To correct an
3392
error, you need not know the history of the erroneous passage; it is
3393
enough to compare what the documentation says with the way the program
3394
actually works.
3395
 
3396
   However, you should keep change logs for documentation files when the
3397
project gets copyright assignments from its contributors, so as to make
3398
the records of authorship more accurate.
3399
 
3400

3401
File: standards.info,  Node: Conditional Changes,  Next: Indicating the Part Changed,  Prev: Simple Changes,  Up: Change Logs
3402
 
3403
6.8.4 Conditional Changes
3404
-------------------------
3405
 
3406
C programs often contain compile-time `#if' conditionals.  Many changes
3407
are conditional; sometimes you add a new definition which is entirely
3408
contained in a conditional.  It is very useful to indicate in the
3409
change log the conditions for which the change applies.
3410
 
3411
   Our convention for indicating conditional changes is to use square
3412
brackets around the name of the condition.
3413
 
3414
   Here is a simple example, describing a change which is conditional
3415
but does not have a function or entity name associated with it:
3416
 
3417
     * xterm.c [SOLARIS2]: Include string.h.
3418
 
3419
   Here is an entry describing a new definition which is entirely
3420
conditional.  This new definition for the macro `FRAME_WINDOW_P' is
3421
used only when `HAVE_X_WINDOWS' is defined:
3422
 
3423
     * frame.h [HAVE_X_WINDOWS] (FRAME_WINDOW_P): Macro defined.
3424
 
3425
   Here is an entry for a change within the function `init_display',
3426
whose definition as a whole is unconditional, but the changes themselves
3427
are contained in a `#ifdef HAVE_LIBNCURSES' conditional:
3428
 
3429
     * dispnew.c (init_display) [HAVE_LIBNCURSES]: If X, call tgetent.
3430
 
3431
   Here is an entry for a change that takes affect only when a certain
3432
macro is _not_ defined:
3433
 
3434
     (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
3435
 
3436

3437
File: standards.info,  Node: Indicating the Part Changed,  Prev: Conditional Changes,  Up: Change Logs
3438
 
3439
6.8.5 Indicating the Part Changed
3440
---------------------------------
3441
 
3442
Indicate the part of a function which changed by using angle brackets
3443
enclosing an indication of what the changed part does.  Here is an entry
3444
for a change in the part of the function `sh-while-getopts' that deals
3445
with `sh' commands:
3446
 
3447
     * progmodes/sh-script.el (sh-while-getopts) : Handle case that
3448
     user-specified option string is empty.
3449
 
3450

3451
File: standards.info,  Node: Man Pages,  Next: Reading other Manuals,  Prev: Change Logs,  Up: Documentation
3452
 
3453
6.9 Man Pages
3454
=============
3455
 
3456
In the GNU project, man pages are secondary.  It is not necessary or
3457
expected for every GNU program to have a man page, but some of them do.
3458
It's your choice whether to include a man page in your program.
3459
 
3460
   When you make this decision, consider that supporting a man page
3461
requires continual effort each time the program is changed.  The time
3462
you spend on the man page is time taken away from more useful work.
3463
 
3464
   For a simple program which changes little, updating the man page may
3465
be a small job.  Then there is little reason not to include a man page,
3466
if you have one.
3467
 
3468
   For a large program that changes a great deal, updating a man page
3469
may be a substantial burden.  If a user offers to donate a man page,
3470
you may find this gift costly to accept.  It may be better to refuse
3471
the man page unless the same person agrees to take full responsibility
3472
for maintaining it--so that you can wash your hands of it entirely.  If
3473
this volunteer later ceases to do the job, then don't feel obliged to
3474
pick it up yourself; it may be better to withdraw the man page from the
3475
distribution until someone else agrees to update it.
3476
 
3477
   When a program changes only a little, you may feel that the
3478
discrepancies are small enough that the man page remains useful without
3479
updating.  If so, put a prominent note near the beginning of the man
3480
page explaining that you don't maintain it and that the Texinfo manual
3481
is more authoritative.  The note should say how to access the Texinfo
3482
documentation.
3483
 
3484
   Be sure that man pages include a copyright statement and free
3485
license.  The simple all-permissive license is appropriate for simple
3486
man pages:
3487
 
3488
     Copying and distribution of this file, with or without modification,
3489
     are permitted in any medium without royalty provided the copyright
3490
     notice and this notice are preserved.
3491
 
3492
   For long man pages, with enough explanation and documentation that
3493
they can be considered true manuals, use the GFDL (*note License for
3494
Manuals::).
3495
 
3496
   Finally, the GNU help2man program
3497
(`http://www.gnu.org/software/help2man/') is one way to automate
3498
generation of a man page, in this case from `--help' output.  This is
3499
sufficient in many cases.
3500
 
3501

3502
File: standards.info,  Node: Reading other Manuals,  Prev: Man Pages,  Up: Documentation
3503
 
3504
6.10 Reading other Manuals
3505
==========================
3506
 
3507
There may be non-free books or documentation files that describe the
3508
program you are documenting.
3509
 
3510
   It is ok to use these documents for reference, just as the author of
3511
a new algebra textbook can read other books on algebra.  A large portion
3512
of any non-fiction book consists of facts, in this case facts about how
3513
a certain program works, and these facts are necessarily the same for
3514
everyone who writes about the subject.  But be careful not to copy your
3515
outline structure, wording, tables or examples from preexisting non-free
3516
documentation.  Copying from free documentation may be ok; please check
3517
with the FSF about the individual case.
3518
 
3519

3520
File: standards.info,  Node: Managing Releases,  Next: References,  Prev: Documentation,  Up: Top
3521
 
3522
7 The Release Process
3523
*********************
3524
 
3525
Making a release is more than just bundling up your source files in a
3526
tar file and putting it up for FTP.  You should set up your software so
3527
that it can be configured to run on a variety of systems.  Your Makefile
3528
should conform to the GNU standards described below, and your directory
3529
layout should also conform to the standards discussed below.  Doing so
3530
makes it easy to include your package into the larger framework of all
3531
GNU software.
3532
 
3533
* Menu:
3534
 
3535
* Configuration::               How configuration of GNU packages should work.
3536
* Makefile Conventions::        Makefile conventions.
3537
* Releases::                    Making releases
3538
 
3539

3540
File: standards.info,  Node: Configuration,  Next: Makefile Conventions,  Up: Managing Releases
3541
 
3542
7.1 How Configuration Should Work
3543
=================================
3544
 
3545
Each GNU distribution should come with a shell script named
3546
`configure'.  This script is given arguments which describe the kind of
3547
machine and system you want to compile the program for.
3548
 
3549
   The `configure' script must record the configuration options so that
3550
they affect compilation.
3551
 
3552
   One way to do this is to make a link from a standard name such as
3553
`config.h' to the proper configuration file for the chosen system.  If
3554
you use this technique, the distribution should _not_ contain a file
3555
named `config.h'.  This is so that people won't be able to build the
3556
program without configuring it first.
3557
 
3558
   Another thing that `configure' can do is to edit the Makefile.  If
3559
you do this, the distribution should _not_ contain a file named
3560
`Makefile'.  Instead, it should include a file `Makefile.in' which
3561
contains the input used for editing.  Once again, this is so that people
3562
won't be able to build the program without configuring it first.
3563
 
3564
   If `configure' does write the `Makefile', then `Makefile' should
3565
have a target named `Makefile' which causes `configure' to be rerun,
3566
setting up the same configuration that was set up last time.  The files
3567
that `configure' reads should be listed as dependencies of `Makefile'.
3568
 
3569
   All the files which are output from the `configure' script should
3570
have comments at the beginning explaining that they were generated
3571
automatically using `configure'.  This is so that users won't think of
3572
trying to edit them by hand.
3573
 
3574
   The `configure' script should write a file named `config.status'
3575
which describes which configuration options were specified when the
3576
program was last configured.  This file should be a shell script which,
3577
if run, will recreate the same configuration.
3578
 
3579
   The `configure' script should accept an option of the form
3580
`--srcdir=DIRNAME' to specify the directory where sources are found (if
3581
it is not the current directory).  This makes it possible to build the
3582
program in a separate directory, so that the actual source directory is
3583
not modified.
3584
 
3585
   If the user does not specify `--srcdir', then `configure' should
3586
check both `.' and `..' to see if it can find the sources.  If it finds
3587
the sources in one of these places, it should use them from there.
3588
Otherwise, it should report that it cannot find the sources, and should
3589
exit with nonzero status.
3590
 
3591
   Usually the easy way to support `--srcdir' is by editing a
3592
definition of `VPATH' into the Makefile.  Some rules may need to refer
3593
explicitly to the specified source directory.  To make this possible,
3594
`configure' can add to the Makefile a variable named `srcdir' whose
3595
value is precisely the specified directory.
3596
 
3597
   The `configure' script should also take an argument which specifies
3598
the type of system to build the program for.  This argument should look
3599
like this:
3600
 
3601
     CPU-COMPANY-SYSTEM
3602
 
3603
   For example, an Athlon-based GNU/Linux system might be
3604
`i686-pc-linux-gnu'.
3605
 
3606
   The `configure' script needs to be able to decode all plausible
3607
alternatives for how to describe a machine.  Thus,
3608
`athlon-pc-gnu/linux' would be a valid alias.  There is a shell script
3609
called `config.sub'
3610
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.sub)
3611
that you can use as a subroutine to validate system types and
3612
canonicalize aliases.
3613
 
3614
   The `configure' script should also take the option
3615
`--build=BUILDTYPE', which should be equivalent to a plain BUILDTYPE
3616
argument.  For example, `configure --build=i686-pc-linux-gnu' is
3617
equivalent to `configure i686-pc-linux-gnu'.  When the build type is
3618
not specified by an option or argument, the `configure' script should
3619
normally guess it using the shell script `config.guess'
3620
(http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/config/config/config.guess).
3621
 
3622
   Other options are permitted to specify in more detail the software
3623
or hardware present on the machine, to include or exclude optional parts
3624
of the package, or to adjust the name of some tools or arguments to
3625
them:
3626
 
3627
`--enable-FEATURE[=PARAMETER]'
3628
     Configure the package to build and install an optional user-level
3629
     facility called FEATURE.  This allows users to choose which
3630
     optional features to include.  Giving an optional PARAMETER of
3631
     `no' should omit FEATURE, if it is built by default.
3632
 
3633
     No `--enable' option should *ever* cause one feature to replace
3634
     another.  No `--enable' option should ever substitute one useful
3635
     behavior for another useful behavior.  The only proper use for
3636
     `--enable' is for questions of whether to build part of the program
3637
     or exclude it.
3638
 
3639
`--with-PACKAGE'
3640
     The package PACKAGE will be installed, so configure this package
3641
     to work with PACKAGE.
3642
 
3643
     Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
3644
     `gnu-libc', `gdb', `x', and `x-toolkit'.
3645
 
3646
     Do not use a `--with' option to specify the file name to use to
3647
     find certain files.  That is outside the scope of what `--with'
3648
     options are for.
3649
 
3650
`VARIABLE=VALUE'
3651
     Set the value of the variable VARIABLE to VALUE.  This is used to
3652
     override the default values of commands or arguments in the build
3653
     process.  For example, the user could issue `configure CFLAGS=-g
3654
     CXXFLAGS=-g' to build with debugging information and without the
3655
     default optimization.
3656
 
3657
     Specifying variables as arguments to `configure', like this:
3658
          ./configure CC=gcc
3659
     is preferable to setting them in environment variables:
3660
          CC=gcc ./configure
3661
     as it helps to recreate the same configuration later with
3662
     `config.status'.
3663
 
3664
   All `configure' scripts should accept all of the "detail" options
3665
and the variable settings, whether or not they make any difference to
3666
the particular package at hand.  In particular, they should accept any
3667
option that starts with `--with-' or `--enable-'.  This is so users
3668
will be able to configure an entire GNU source tree at once with a
3669
single set of options.
3670
 
3671
   You will note that the categories `--with-' and `--enable-' are
3672
narrow: they *do not* provide a place for any sort of option you might
3673
think of.  That is deliberate.  We want to limit the possible
3674
configuration options in GNU software.  We do not want GNU programs to
3675
have idiosyncratic configuration options.
3676
 
3677
   Packages that perform part of the compilation process may support
3678
cross-compilation.  In such a case, the host and target machines for the
3679
program may be different.
3680
 
3681
   The `configure' script should normally treat the specified type of
3682
system as both the host and the target, thus producing a program which
3683
works for the same type of machine that it runs on.
3684
 
3685
   To compile a program to run on a host type that differs from the
3686
build type, use the configure option `--host=HOSTTYPE', where HOSTTYPE
3687
uses the same syntax as BUILDTYPE.  The host type normally defaults to
3688
the build type.
3689
 
3690
   To configure a cross-compiler, cross-assembler, or what have you, you
3691
should specify a target different from the host, using the configure
3692
option `--target=TARGETTYPE'.  The syntax for TARGETTYPE is the same as
3693
for the host type.  So the command would look like this:
3694
 
3695
     ./configure --host=HOSTTYPE --target=TARGETTYPE
3696
 
3697
   The target type normally defaults to the host type.  Programs for
3698
which cross-operation is not meaningful need not accept the `--target'
3699
option, because configuring an entire operating system for
3700
cross-operation is not a meaningful operation.
3701
 
3702
   Some programs have ways of configuring themselves automatically.  If
3703
your program is set up to do this, your `configure' script can simply
3704
ignore most of its arguments.
3705
 
3706

3707
File: standards.info,  Node: Makefile Conventions,  Next: Releases,  Prev: Configuration,  Up: Managing Releases
3708
 
3709
7.2 Makefile Conventions
3710
========================
3711
 
3712
This node describes conventions for writing the Makefiles for GNU
3713
programs.  Using Automake will help you write a Makefile that follows
3714
these conventions.
3715
 
3716
* Menu:
3717
 
3718
* Makefile Basics::             General conventions for Makefiles.
3719
* Utilities in Makefiles::      Utilities to be used in Makefiles.
3720
* Command Variables::           Variables for specifying commands.
3721
* DESTDIR::                     Supporting staged installs.
3722
* Directory Variables::         Variables for installation directories.
3723
* Standard Targets::            Standard targets for users.
3724
* Install Command Categories::  Three categories of commands in the `install'
3725
                                  rule: normal, pre-install and post-install.
3726
 
3727

3728
File: standards.info,  Node: Makefile Basics,  Next: Utilities in Makefiles,  Up: Makefile Conventions
3729
 
3730
7.2.1 General Conventions for Makefiles
3731
---------------------------------------
3732
 
3733
Every Makefile should contain this line:
3734
 
3735
     SHELL = /bin/sh
3736
 
3737
to avoid trouble on systems where the `SHELL' variable might be
3738
inherited from the environment.  (This is never a problem with GNU
3739
`make'.)
3740
 
3741
   Different `make' programs have incompatible suffix lists and
3742
implicit rules, and this sometimes creates confusion or misbehavior.  So
3743
it is a good idea to set the suffix list explicitly using only the
3744
suffixes you need in the particular Makefile, like this:
3745
 
3746
     .SUFFIXES:
3747
     .SUFFIXES: .c .o
3748
 
3749
The first line clears out the suffix list, the second introduces all
3750
suffixes which may be subject to implicit rules in this Makefile.
3751
 
3752
   Don't assume that `.' is in the path for command execution.  When
3753
you need to run programs that are a part of your package during the
3754
make, please make sure that it uses `./' if the program is built as
3755
part of the make or `$(srcdir)/' if the file is an unchanging part of
3756
the source code.  Without one of these prefixes, the current search
3757
path is used.
3758
 
3759
   The distinction between `./' (the "build directory") and
3760
`$(srcdir)/' (the "source directory") is important because users can
3761
build in a separate directory using the `--srcdir' option to
3762
`configure'.  A rule of the form:
3763
 
3764
     foo.1 : foo.man sedscript
3765
             sed -e sedscript foo.man > foo.1
3766
 
3767
will fail when the build directory is not the source directory, because
3768
`foo.man' and `sedscript' are in the source directory.
3769
 
3770
   When using GNU `make', relying on `VPATH' to find the source file
3771
will work in the case where there is a single dependency file, since
3772
the `make' automatic variable `$<' will represent the source file
3773
wherever it is.  (Many versions of `make' set `$<' only in implicit
3774
rules.)  A Makefile target like
3775
 
3776
     foo.o : bar.c
3777
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
3778
 
3779
should instead be written as
3780
 
3781
     foo.o : bar.c
3782
             $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
3783
 
3784
in order to allow `VPATH' to work correctly.  When the target has
3785
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
3786
to make the rule work well.  For example, the target above for `foo.1'
3787
is best written as:
3788
 
3789
     foo.1 : foo.man sedscript
3790
             sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
3791
 
3792
   GNU distributions usually contain some files which are not source
3793
files--for example, Info files, and the output from Autoconf, Automake,
3794
Bison or Flex.  Since these files normally appear in the source
3795
directory, they should always appear in the source directory, not in the
3796
build directory.  So Makefile rules to update them should put the
3797
updated files in the source directory.
3798
 
3799
   However, if a file does not appear in the distribution, then the
3800
Makefile should not put it in the source directory, because building a
3801
program in ordinary circumstances should not modify the source directory
3802
in any way.
3803
 
3804
   Try to make the build and installation targets, at least (and all
3805
their subtargets) work correctly with a parallel `make'.
3806
 
3807

3808
File: standards.info,  Node: Utilities in Makefiles,  Next: Command Variables,  Prev: Makefile Basics,  Up: Makefile Conventions
3809
 
3810
7.2.2 Utilities in Makefiles
3811
----------------------------
3812
 
3813
Write the Makefile commands (and any shell scripts, such as
3814
`configure') to run in `sh', not in `csh'.  Don't use any special
3815
features of `ksh' or `bash'.
3816
 
3817
   The `configure' script and the Makefile rules for building and
3818
installation should not use any utilities directly except these:
3819
 
3820
     cat cmp cp diff echo egrep expr false grep install-info
3821
     ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
3822
 
3823
   The compression program `gzip' can be used in the `dist' rule.
3824
 
3825
   Stick to the generally supported options for these programs.  For
3826
example, don't use `mkdir -p', convenient as it may be, because most
3827
systems don't support it.
3828
 
3829
   It is a good idea to avoid creating symbolic links in makefiles,
3830
since a few systems don't support them.
3831
 
3832
   The Makefile rules for building and installation can also use
3833
compilers and related programs, but should do so via `make' variables
3834
so that the user can substitute alternatives.  Here are some of the
3835
programs we mean:
3836
 
3837
     ar bison cc flex install ld ldconfig lex
3838
     make makeinfo ranlib texi2dvi yacc
3839
 
3840
   Use the following `make' variables to run those programs:
3841
 
3842
     $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
3843
     $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
3844
 
3845
   When you use `ranlib' or `ldconfig', you should make sure nothing
3846
bad happens if the system does not have the program in question.
3847
Arrange to ignore an error from that command, and print a message before
3848
the command to tell the user that failure of this command does not mean
3849
a problem.  (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
3850
 
3851
   If you use symbolic links, you should implement a fallback for
3852
systems that don't have symbolic links.
3853
 
3854
   Additional utilities that can be used via Make variables are:
3855
 
3856
     chgrp chmod chown mknod
3857
 
3858
   It is ok to use other utilities in Makefile portions (or scripts)
3859
intended only for particular systems where you know those utilities
3860
exist.
3861
 
3862

3863
File: standards.info,  Node: Command Variables,  Next: DESTDIR,  Prev: Utilities in Makefiles,  Up: Makefile Conventions
3864
 
3865
7.2.3 Variables for Specifying Commands
3866
---------------------------------------
3867
 
3868
Makefiles should provide variables for overriding certain commands,
3869
options, and so on.
3870
 
3871
   In particular, you should run most utility programs via variables.
3872
Thus, if you use Bison, have a variable named `BISON' whose default
3873
value is set with `BISON = bison', and refer to it with `$(BISON)'
3874
whenever you need to use Bison.
3875
 
3876
   File management utilities such as `ln', `rm', `mv', and so on, need
3877
not be referred to through variables in this way, since users don't
3878
need to replace them with other programs.
3879
 
3880
   Each program-name variable should come with an options variable that
3881
is used to supply options to the program.  Append `FLAGS' to the
3882
program-name variable name to get the options variable name--for
3883
example, `BISONFLAGS'.  (The names `CFLAGS' for the C compiler,
3884
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
3885
but we keep them because they are standard.)  Use `CPPFLAGS' in any
3886
compilation command that runs the preprocessor, and use `LDFLAGS' in
3887
any compilation command that does linking as well as in any direct use
3888
of `ld'.
3889
 
3890
   If there are C compiler options that _must_ be used for proper
3891
compilation of certain files, do not include them in `CFLAGS'.  Users
3892
expect to be able to specify `CFLAGS' freely themselves.  Instead,
3893
arrange to pass the necessary options to the C compiler independently
3894
of `CFLAGS', by writing them explicitly in the compilation commands or
3895
by defining an implicit rule, like this:
3896
 
3897
     CFLAGS = -g
3898
     ALL_CFLAGS = -I. $(CFLAGS)
3899
     .c.o:
3900
             $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
3901
 
3902
   Do include the `-g' option in `CFLAGS', because that is not
3903
_required_ for proper compilation.  You can consider it a default that
3904
is only recommended.  If the package is set up so that it is compiled
3905
with GCC by default, then you might as well include `-O' in the default
3906
value of `CFLAGS' as well.
3907
 
3908
   Put `CFLAGS' last in the compilation command, after other variables
3909
containing compiler options, so the user can use `CFLAGS' to override
3910
the others.
3911
 
3912
   `CFLAGS' should be used in every invocation of the C compiler, both
3913
those which do compilation and those which do linking.
3914
 
3915
   Every Makefile should define the variable `INSTALL', which is the
3916
basic command for installing a file into the system.
3917
 
3918
   Every Makefile should also define the variables `INSTALL_PROGRAM'
3919
and `INSTALL_DATA'.  (The default for `INSTALL_PROGRAM' should be
3920
`$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
3921
644'.)  Then it should use those variables as the commands for actual
3922
installation, for executables and non-executables respectively.
3923
Minimal use of these variables is as follows:
3924
 
3925
     $(INSTALL_PROGRAM) foo $(bindir)/foo
3926
     $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
3927
 
3928
   However, it is preferable to support a `DESTDIR' prefix on the
3929
target files, as explained in the next section.
3930
 
3931
Always use a file name, not a directory name, as the second argument of
3932
the installation commands.  Use a separate command for each file to be
3933
installed.
3934
 
3935

3936
File: standards.info,  Node: DESTDIR,  Next: Directory Variables,  Prev: Command Variables,  Up: Makefile Conventions
3937
 
3938
7.2.4 `DESTDIR': support for staged installs
3939
--------------------------------------------
3940
 
3941
`DESTDIR' is a variable prepended to each installed target file, like
3942
this:
3943
 
3944
     $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
3945
     $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
3946
 
3947
   The `DESTDIR' variable is specified by the user on the `make'
3948
command line.  For example:
3949
 
3950
     make DESTDIR=/tmp/stage install
3951
 
3952
`DESTDIR' should be supported only in the `install*' and `uninstall*'
3953
targets, as those are the only targets where it is useful.
3954
 
3955
   If your installation step would normally install
3956
`/usr/local/bin/foo' and `/usr/local/lib/libfoo.a', then an
3957
installation invoked as in the example above would install
3958
`/tmp/stage/usr/local/bin/foo' and `/tmp/stage/usr/local/lib/libfoo.a'
3959
instead.
3960
 
3961
   Prepending the variable `DESTDIR' to each target in this way
3962
provides for "staged installs", where the installed files are not
3963
placed directly into their expected location but are instead copied
3964
into a temporary location (`DESTDIR').  However, installed files
3965
maintain their relative directory structure and any embedded file names
3966
will not be modified.
3967
 
3968
   You should not set the value of `DESTDIR' in your `Makefile' at all;
3969
then the files are installed into their expected locations by default.
3970
Also, specifying `DESTDIR' should not change the operation of the
3971
software in any way, so its value should not be included in any file
3972
contents.
3973
 
3974
   `DESTDIR' support is commonly used in package creation.  It is also
3975
helpful to users who want to understand what a given package will
3976
install where, and to allow users who don't normally have permissions
3977
to install into protected areas to build and install before gaining
3978
those permissions.  Finally, it can be useful with tools such as
3979
`stow', where code is installed in one place but made to appear to be
3980
installed somewhere else using symbolic links or special mount
3981
operations.  So, we strongly recommend GNU packages support `DESTDIR',
3982
though it is not an absolute requirement.
3983
 
3984

3985
File: standards.info,  Node: Directory Variables,  Next: Standard Targets,  Prev: DESTDIR,  Up: Makefile Conventions
3986
 
3987
7.2.5 Variables for Installation Directories
3988
--------------------------------------------
3989
 
3990
Installation directories should always be named by variables, so it is
3991
easy to install in a nonstandard place.  The standard names for these
3992
variables and the values they should have in GNU packages are described
3993
below.  They are based on a standard file system layout; variants of it
3994
are used in GNU/Linux and other modern operating systems.
3995
 
3996
   Installers are expected to override these values when calling `make'
3997
(e.g., `make prefix=/usr install' or `configure' (e.g., `configure
3998
--prefix=/usr').  GNU packages should not try to guess which value
3999
should be appropriate for these variables on the system they are being
4000
installed onto: use the default settings specified here so that all GNU
4001
packages behave identically, allowing the installer to achieve any
4002
desired layout.
4003
 
4004
   These first two variables set the root for the installation.  All the
4005
other installation directories should be subdirectories of one of these
4006
two, and nothing should be directly installed into these two
4007
directories.
4008
 
4009
`prefix'
4010
     A prefix used in constructing the default values of the variables
4011
     listed below.  The default value of `prefix' should be
4012
     `/usr/local'.  When building the complete GNU system, the prefix
4013
     will be empty and `/usr' will be a symbolic link to `/'.  (If you
4014
     are using Autoconf, write it as `@prefix@'.)
4015
 
4016
     Running `make install' with a different value of `prefix' from the
4017
     one used to build the program should _not_ recompile the program.
4018
 
4019
`exec_prefix'
4020
     A prefix used in constructing the default values of some of the
4021
     variables listed below.  The default value of `exec_prefix' should
4022
     be `$(prefix)'.  (If you are using Autoconf, write it as
4023
     `@exec_prefix@'.)
4024
 
4025
     Generally, `$(exec_prefix)' is used for directories that contain
4026
     machine-specific files (such as executables and subroutine
4027
     libraries), while `$(prefix)' is used directly for other
4028
     directories.
4029
 
4030
     Running `make install' with a different value of `exec_prefix'
4031
     from the one used to build the program should _not_ recompile the
4032
     program.
4033
 
4034
   Executable programs are installed in one of the following
4035
directories.
4036
 
4037
`bindir'
4038
     The directory for installing executable programs that users can
4039
     run.  This should normally be `/usr/local/bin', but write it as
4040
     `$(exec_prefix)/bin'.  (If you are using Autoconf, write it as
4041
     `@bindir@'.)
4042
 
4043
`sbindir'
4044
     The directory for installing executable programs that can be run
4045
     from the shell, but are only generally useful to system
4046
     administrators.  This should normally be `/usr/local/sbin', but
4047
     write it as `$(exec_prefix)/sbin'.  (If you are using Autoconf,
4048
     write it as `@sbindir@'.)
4049
 
4050
`libexecdir'
4051
     The directory for installing executable programs to be run by other
4052
     programs rather than by users.  This directory should normally be
4053
     `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
4054
     (If you are using Autoconf, write it as `@libexecdir@'.)
4055
 
4056
     The definition of `libexecdir' is the same for all packages, so
4057
     you should install your data in a subdirectory thereof.  Most
4058
     packages install their data under `$(libexecdir)/PACKAGE-NAME/',
4059
     possibly within additional subdirectories thereof, such as
4060
     `$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
4061
 
4062
   Data files used by the program during its execution are divided into
4063
categories in two ways.
4064
 
4065
   * Some files are normally modified by programs; others are never
4066
     normally modified (though users may edit some of these).
4067
 
4068
   * Some files are architecture-independent and can be shared by all
4069
     machines at a site; some are architecture-dependent and can be
4070
     shared only by machines of the same kind and operating system;
4071
     others may never be shared between two machines.
4072
 
4073
   This makes for six different possibilities.  However, we want to
4074
discourage the use of architecture-dependent files, aside from object
4075
files and libraries.  It is much cleaner to make other data files
4076
architecture-independent, and it is generally not hard.
4077
 
4078
   Here are the variables Makefiles should use to specify directories
4079
to put these various kinds of files in:
4080
 
4081
`datarootdir'
4082
     The root of the directory tree for read-only
4083
     architecture-independent data files.  This should normally be
4084
     `/usr/local/share', but write it as `$(prefix)/share'.  (If you
4085
     are using Autoconf, write it as `@datarootdir@'.)  `datadir''s
4086
     default value is based on this variable; so are `infodir',
4087
     `mandir', and others.
4088
 
4089
`datadir'
4090
     The directory for installing idiosyncratic read-only
4091
     architecture-independent data files for this program.  This is
4092
     usually the same place as `datarootdir', but we use the two
4093
     separate variables so that you can move these program-specific
4094
     files without altering the location for Info files, man pages, etc.
4095
 
4096
     This should normally be `/usr/local/share', but write it as
4097
     `$(datarootdir)'.  (If you are using Autoconf, write it as
4098
     `@datadir@'.)
4099
 
4100
     The definition of `datadir' is the same for all packages, so you
4101
     should install your data in a subdirectory thereof.  Most packages
4102
     install their data under `$(datadir)/PACKAGE-NAME/'.
4103
 
4104
`sysconfdir'
4105
     The directory for installing read-only data files that pertain to a
4106
     single machine-that is to say, files for configuring a host.
4107
     Mailer and network configuration files, `/etc/passwd', and so
4108
     forth belong here.  All the files in this directory should be
4109
     ordinary ASCII text files.  This directory should normally be
4110
     `/usr/local/etc', but write it as `$(prefix)/etc'.  (If you are
4111
     using Autoconf, write it as `@sysconfdir@'.)
4112
 
4113
     Do not install executables here in this directory (they probably
4114
     belong in `$(libexecdir)' or `$(sbindir)').  Also do not install
4115
     files that are modified in the normal course of their use (programs
4116
     whose purpose is to change the configuration of the system
4117
     excluded).  Those probably belong in `$(localstatedir)'.
4118
 
4119
`sharedstatedir'
4120
     The directory for installing architecture-independent data files
4121
     which the programs modify while they run.  This should normally be
4122
     `/usr/local/com', but write it as `$(prefix)/com'.  (If you are
4123
     using Autoconf, write it as `@sharedstatedir@'.)
4124
 
4125
`localstatedir'
4126
     The directory for installing data files which the programs modify
4127
     while they run, and that pertain to one specific machine.  Users
4128
     should never need to modify files in this directory to configure
4129
     the package's operation; put such configuration information in
4130
     separate files that go in `$(datadir)' or `$(sysconfdir)'.
4131
     `$(localstatedir)' should normally be `/usr/local/var', but write
4132
     it as `$(prefix)/var'.  (If you are using Autoconf, write it as
4133
     `@localstatedir@'.)
4134
 
4135
   These variables specify the directory for installing certain specific
4136
types of files, if your program has them.  Every GNU package should
4137
have Info files, so every program needs `infodir', but not all need
4138
`libdir' or `lispdir'.
4139
 
4140
`includedir'
4141
     The directory for installing header files to be included by user
4142
     programs with the C `#include' preprocessor directive.  This
4143
     should normally be `/usr/local/include', but write it as
4144
     `$(prefix)/include'.  (If you are using Autoconf, write it as
4145
     `@includedir@'.)
4146
 
4147
     Most compilers other than GCC do not look for header files in
4148
     directory `/usr/local/include'.  So installing the header files
4149
     this way is only useful with GCC.  Sometimes this is not a problem
4150
     because some libraries are only really intended to work with GCC.
4151
     But some libraries are intended to work with other compilers.
4152
     They should install their header files in two places, one
4153
     specified by `includedir' and one specified by `oldincludedir'.
4154
 
4155
`oldincludedir'
4156
     The directory for installing `#include' header files for use with
4157
     compilers other than GCC.  This should normally be `/usr/include'.
4158
     (If you are using Autoconf, you can write it as `@oldincludedir@'.)
4159
 
4160
     The Makefile commands should check whether the value of
4161
     `oldincludedir' is empty.  If it is, they should not try to use
4162
     it; they should cancel the second installation of the header files.
4163
 
4164
     A package should not replace an existing header in this directory
4165
     unless the header came from the same package.  Thus, if your Foo
4166
     package provides a header file `foo.h', then it should install the
4167
     header file in the `oldincludedir' directory if either (1) there
4168
     is no `foo.h' there or (2) the `foo.h' that exists came from the
4169
     Foo package.
4170
 
4171
     To tell whether `foo.h' came from the Foo package, put a magic
4172
     string in the file--part of a comment--and `grep' for that string.
4173
 
4174
`docdir'
4175
     The directory for installing documentation files (other than Info)
4176
     for this package.  By default, it should be
4177
     `/usr/local/share/doc/YOURPKG', but it should be written as
4178
     `$(datarootdir)/doc/YOURPKG'.  (If you are using Autoconf, write
4179
     it as `@docdir@'.)  The YOURPKG subdirectory, which may include a
4180
     version number, prevents collisions among files with common names,
4181
     such as `README'.
4182
 
4183
`infodir'
4184
     The directory for installing the Info files for this package.  By
4185
     default, it should be `/usr/local/share/info', but it should be
4186
     written as `$(datarootdir)/info'.  (If you are using Autoconf,
4187
     write it as `@infodir@'.)  `infodir' is separate from `docdir' for
4188
     compatibility with existing practice.
4189
 
4190
`htmldir'
4191
`dvidir'
4192
`pdfdir'
4193
`psdir'
4194
     Directories for installing documentation files in the particular
4195
     format.  They should all be set to `$(docdir)' by default.  (If
4196
     you are using Autoconf, write them as `@htmldir@', `@dvidir@',
4197
     etc.)  Packages which supply several translations of their
4198
     documentation should install them in `$(htmldir)/'LL,
4199
     `$(pdfdir)/'LL, etc. where LL is a locale abbreviation such as
4200
     `en' or `pt_BR'.
4201
 
4202
`libdir'
4203
     The directory for object files and libraries of object code.  Do
4204
     not install executables here, they probably ought to go in
4205
     `$(libexecdir)' instead.  The value of `libdir' should normally be
4206
     `/usr/local/lib', but write it as `$(exec_prefix)/lib'.  (If you
4207
     are using Autoconf, write it as `@libdir@'.)
4208
 
4209
`lispdir'
4210
     The directory for installing any Emacs Lisp files in this package.
4211
     By default, it should be `/usr/local/share/emacs/site-lisp', but
4212
     it should be written as `$(datarootdir)/emacs/site-lisp'.
4213
 
4214
     If you are using Autoconf, write the default as `@lispdir@'.  In
4215
     order to make `@lispdir@' work, you need the following lines in
4216
     your `configure.in' file:
4217
 
4218
          lispdir='${datarootdir}/emacs/site-lisp'
4219
          AC_SUBST(lispdir)
4220
 
4221
`localedir'
4222
     The directory for installing locale-specific message catalogs for
4223
     this package.  By default, it should be `/usr/local/share/locale',
4224
     but it should be written as `$(datarootdir)/locale'.  (If you are
4225
     using Autoconf, write it as `@localedir@'.)  This directory
4226
     usually has a subdirectory per locale.
4227
 
4228
   Unix-style man pages are installed in one of the following:
4229
 
4230
`mandir'
4231
     The top-level directory for installing the man pages (if any) for
4232
     this package.  It will normally be `/usr/local/share/man', but you
4233
     should write it as `$(datarootdir)/man'.  (If you are using
4234
     Autoconf, write it as `@mandir@'.)
4235
 
4236
`man1dir'
4237
     The directory for installing section 1 man pages.  Write it as
4238
     `$(mandir)/man1'.
4239
 
4240
`man2dir'
4241
     The directory for installing section 2 man pages.  Write it as
4242
     `$(mandir)/man2'
4243
 
4244
`...'
4245
     *Don't make the primary documentation for any GNU software be a
4246
     man page.  Write a manual in Texinfo instead.  Man pages are just
4247
     for the sake of people running GNU software on Unix, which is a
4248
     secondary application only.*
4249
 
4250
`manext'
4251
     The file name extension for the installed man page.  This should
4252
     contain a period followed by the appropriate digit; it should
4253
     normally be `.1'.
4254
 
4255
`man1ext'
4256
     The file name extension for installed section 1 man pages.
4257
 
4258
`man2ext'
4259
     The file name extension for installed section 2 man pages.
4260
 
4261
`...'
4262
     Use these names instead of `manext' if the package needs to
4263
     install man pages in more than one section of the manual.
4264
 
4265
   And finally, you should set the following variable:
4266
 
4267
`srcdir'
4268
     The directory for the sources being compiled.  The value of this
4269
     variable is normally inserted by the `configure' shell script.
4270
     (If you are using Autoconf, use `srcdir = @srcdir@'.)
4271
 
4272
   For example:
4273
 
4274
     # Common prefix for installation directories.
4275
     # NOTE: This directory must exist when you start the install.
4276
     prefix = /usr/local
4277
     datarootdir = $(prefix)/share
4278
     datadir = $(datarootdir)
4279
     exec_prefix = $(prefix)
4280
     # Where to put the executable for the command `gcc'.
4281
     bindir = $(exec_prefix)/bin
4282
     # Where to put the directories used by the compiler.
4283
     libexecdir = $(exec_prefix)/libexec
4284
     # Where to put the Info files.
4285
     infodir = $(datarootdir)/info
4286
 
4287
   If your program installs a large number of files into one of the
4288
standard user-specified directories, it might be useful to group them
4289
into a subdirectory particular to that program.  If you do this, you
4290
should write the `install' rule to create these subdirectories.
4291
 
4292
   Do not expect the user to include the subdirectory name in the value
4293
of any of the variables listed above.  The idea of having a uniform set
4294
of variable names for installation directories is to enable the user to
4295
specify the exact same values for several different GNU packages.  In
4296
order for this to be useful, all the packages must be designed so that
4297
they will work sensibly when the user does so.
4298
 
4299
   At times, not all of these variables may be implemented in the
4300
current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
4301
believe all of them are.  When any are missing, the descriptions here
4302
serve as specifications for what Autoconf will implement.  As a
4303
programmer, you can either use a development version of Autoconf or
4304
avoid using these variables until a stable release is made which
4305
supports them.
4306
 
4307

4308
File: standards.info,  Node: Standard Targets,  Next: Install Command Categories,  Prev: Directory Variables,  Up: Makefile Conventions
4309
 
4310
7.2.6 Standard Targets for Users
4311
--------------------------------
4312
 
4313
All GNU programs should have the following targets in their Makefiles:
4314
 
4315
`all'
4316
     Compile the entire program.  This should be the default target.
4317
     This target need not rebuild any documentation files; Info files
4318
     should normally be included in the distribution, and DVI (and other
4319
     documentation format) files should be made only when explicitly
4320
     asked for.
4321
 
4322
     By default, the Make rules should compile and link with `-g', so
4323
     that executable programs have debugging symbols.  Users who don't
4324
     mind being helpless can strip the executables later if they wish.
4325
 
4326
`install'
4327
     Compile the program and copy the executables, libraries, and so on
4328
     to the file names where they should reside for actual use.  If
4329
     there is a simple test to verify that a program is properly
4330
     installed, this target should run that test.
4331
 
4332
     Do not strip executables when installing them.  Devil-may-care
4333
     users can use the `install-strip' target to do that.
4334
 
4335
     If possible, write the `install' target rule so that it does not
4336
     modify anything in the directory where the program was built,
4337
     provided `make all' has just been done.  This is convenient for
4338
     building the program under one user name and installing it under
4339
     another.
4340
 
4341
     The commands should create all the directories in which files are
4342
     to be installed, if they don't already exist.  This includes the
4343
     directories specified as the values of the variables `prefix' and
4344
     `exec_prefix', as well as all subdirectories that are needed.  One
4345
     way to do this is by means of an `installdirs' target as described
4346
     below.
4347
 
4348
     Use `-' before any command for installing a man page, so that
4349
     `make' will ignore any errors.  This is in case there are systems
4350
     that don't have the Unix man page documentation system installed.
4351
 
4352
     The way to install Info files is to copy them into `$(infodir)'
4353
     with `$(INSTALL_DATA)' (*note Command Variables::), and then run
4354
     the `install-info' program if it is present.  `install-info' is a
4355
     program that edits the Info `dir' file to add or update the menu
4356
     entry for the given Info file; it is part of the Texinfo package.
4357
     Here is a sample rule to install an Info file:
4358
 
4359
          $(DESTDIR)$(infodir)/foo.info: foo.info
4360
                  $(POST_INSTALL)
4361
          # There may be a newer info file in . than in srcdir.
4362
                  -if test -f foo.info; then d=.; \
4363
                   else d=$(srcdir); fi; \
4364
                  $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
4365
          # Run install-info only if it exists.
4366
          # Use `if' instead of just prepending `-' to the
4367
          # line so we notice real errors from install-info.
4368
          # We use `$(SHELL) -c' because some shells do not
4369
          # fail gracefully when there is an unknown command.
4370
                  if $(SHELL) -c 'install-info --version' \
4371
                     >/dev/null 2>&1; then \
4372
                    install-info --dir-file=$(DESTDIR)$(infodir)/dir \
4373
                                 $(DESTDIR)$(infodir)/foo.info; \
4374
                  else true; fi
4375
 
4376
     When writing the `install' target, you must classify all the
4377
     commands into three categories: normal ones, "pre-installation"
4378
     commands and "post-installation" commands.  *Note Install Command
4379
     Categories::.
4380
 
4381
`install-html'
4382
`install-dvi'
4383
`install-pdf'
4384
`install-ps'
4385
     These targets install documentation in formats other than Info;
4386
     they're intended to be called explicitly by the person installing
4387
     the package, if that format is desired.  GNU prefers Info files,
4388
     so these must be installed by the `install' target.
4389
 
4390
     When you have many documentation files to install, we recommend
4391
     that you avoid collisions and clutter by arranging for these
4392
     targets to install in subdirectories of the appropriate
4393
     installation directory, such as `htmldir'.  As one example, if
4394
     your package has multiple manuals, and you wish to install HTML
4395
     documentation with many files (such as the "split" mode output by
4396
     `makeinfo --html'), you'll certainly want to use subdirectories,
4397
     or two nodes with the same name in different manuals will
4398
     overwrite each other.
4399
 
4400
     Please make these `install-FORMAT' targets invoke the commands for
4401
     the FORMAT target, for example, by making FORMAT a dependency.
4402
 
4403
`uninstall'
4404
     Delete all the installed files--the copies that the `install' and
4405
     `install-*' targets create.
4406
 
4407
     This rule should not modify the directories where compilation is
4408
     done, only the directories where files are installed.
4409
 
4410
     The uninstallation commands are divided into three categories,
4411
     just like the installation commands.  *Note Install Command
4412
     Categories::.
4413
 
4414
`install-strip'
4415
     Like `install', but strip the executable files while installing
4416
     them.  In simple cases, this target can use the `install' target in
4417
     a simple way:
4418
 
4419
          install-strip:
4420
                  $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
4421
                          install
4422
 
4423
     But if the package installs scripts as well as real executables,
4424
     the `install-strip' target can't just refer to the `install'
4425
     target; it has to strip the executables but not the scripts.
4426
 
4427
     `install-strip' should not strip the executables in the build
4428
     directory which are being copied for installation.  It should only
4429
     strip the copies that are installed.
4430
 
4431
     Normally we do not recommend stripping an executable unless you
4432
     are sure the program has no bugs.  However, it can be reasonable
4433
     to install a stripped executable for actual execution while saving
4434
     the unstripped executable elsewhere in case there is a bug.
4435
 
4436
`clean'
4437
     Delete all files in the current directory that are normally
4438
     created by building the program.  Also delete files in other
4439
     directories if they are created by this makefile.  However, don't
4440
     delete the files that record the configuration.  Also preserve
4441
     files that could be made by building, but normally aren't because
4442
     the distribution comes with them.  There is no need to delete
4443
     parent directories that were created with `mkdir -p', since they
4444
     could have existed anyway.
4445
 
4446
     Delete `.dvi' files here if they are not part of the distribution.
4447
 
4448
`distclean'
4449
     Delete all files in the current directory (or created by this
4450
     makefile) that are created by configuring or building the program.
4451
     If you have unpacked the source and built the program without
4452
     creating any other files, `make distclean' should leave only the
4453
     files that were in the distribution.  However, there is no need to
4454
     delete parent directories that were created with `mkdir -p', since
4455
     they could have existed anyway.
4456
 
4457
`mostlyclean'
4458
     Like `clean', but may refrain from deleting a few files that people
4459
     normally don't want to recompile.  For example, the `mostlyclean'
4460
     target for GCC does not delete `libgcc.a', because recompiling it
4461
     is rarely necessary and takes a lot of time.
4462
 
4463
`maintainer-clean'
4464
     Delete almost everything that can be reconstructed with this
4465
     Makefile.  This typically includes everything deleted by
4466
     `distclean', plus more: C source files produced by Bison, tags
4467
     tables, Info files, and so on.
4468
 
4469
     The reason we say "almost everything" is that running the command
4470
     `make maintainer-clean' should not delete `configure' even if
4471
     `configure' can be remade using a rule in the Makefile.  More
4472
     generally, `make maintainer-clean' should not delete anything that
4473
     needs to exist in order to run `configure' and then begin to build
4474
     the program.  Also, there is no need to delete parent directories
4475
     that were created with `mkdir -p', since they could have existed
4476
     anyway.  These are the only exceptions; `maintainer-clean' should
4477
     delete everything else that can be rebuilt.
4478
 
4479
     The `maintainer-clean' target is intended to be used by a
4480
     maintainer of the package, not by ordinary users.  You may need
4481
     special tools to reconstruct some of the files that `make
4482
     maintainer-clean' deletes.  Since these files are normally
4483
     included in the distribution, we don't take care to make them easy
4484
     to reconstruct.  If you find you need to unpack the full
4485
     distribution again, don't blame us.
4486
 
4487
     To help make users aware of this, the commands for the special
4488
     `maintainer-clean' target should start with these two:
4489
 
4490
          @echo 'This command is intended for maintainers to use; it'
4491
          @echo 'deletes files that may need special tools to rebuild.'
4492
 
4493
`TAGS'
4494
     Update a tags table for this program.
4495
 
4496
`info'
4497
     Generate any Info files needed.  The best way to write the rules
4498
     is as follows:
4499
 
4500
          info: foo.info
4501
 
4502
          foo.info: foo.texi chap1.texi chap2.texi
4503
                  $(MAKEINFO) $(srcdir)/foo.texi
4504
 
4505
     You must define the variable `MAKEINFO' in the Makefile.  It should
4506
     run the `makeinfo' program, which is part of the Texinfo
4507
     distribution.
4508
 
4509
     Normally a GNU distribution comes with Info files, and that means
4510
     the Info files are present in the source directory.  Therefore,
4511
     the Make rule for an info file should update it in the source
4512
     directory.  When users build the package, ordinarily Make will not
4513
     update the Info files because they will already be up to date.
4514
 
4515
`dvi'
4516
`html'
4517
`pdf'
4518
`ps'
4519
     Generate documentation files in the given format.  These targets
4520
     should always exist, but any or all can be a no-op if the given
4521
     output format cannot be generated.  These targets should not be
4522
     dependencies of the `all' target; the user must manually invoke
4523
     them.
4524
 
4525
     Here's an example rule for generating DVI files from Texinfo:
4526
 
4527
          dvi: foo.dvi
4528
 
4529
          foo.dvi: foo.texi chap1.texi chap2.texi
4530
                  $(TEXI2DVI) $(srcdir)/foo.texi
4531
 
4532
     You must define the variable `TEXI2DVI' in the Makefile.  It should
4533
     run the program `texi2dvi', which is part of the Texinfo
4534
     distribution.(1)  Alternatively, write just the dependencies, and
4535
     allow GNU `make' to provide the command.
4536
 
4537
     Here's another example, this one for generating HTML from Texinfo:
4538
 
4539
          html: foo.html
4540
 
4541
          foo.html: foo.texi chap1.texi chap2.texi
4542
                  $(TEXI2HTML) $(srcdir)/foo.texi
4543
 
4544
     Again, you would define the variable `TEXI2HTML' in the Makefile;
4545
     for example, it might run `makeinfo --no-split --html' (`makeinfo'
4546
     is part of the Texinfo distribution).
4547
 
4548
`dist'
4549
     Create a distribution tar file for this program.  The tar file
4550
     should be set up so that the file names in the tar file start with
4551
     a subdirectory name which is the name of the package it is a
4552
     distribution for.  This name can include the version number.
4553
 
4554
     For example, the distribution tar file of GCC version 1.40 unpacks
4555
     into a subdirectory named `gcc-1.40'.
4556
 
4557
     The easiest way to do this is to create a subdirectory
4558
     appropriately named, use `ln' or `cp' to install the proper files
4559
     in it, and then `tar' that subdirectory.
4560
 
4561
     Compress the tar file with `gzip'.  For example, the actual
4562
     distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
4563
 
4564
     The `dist' target should explicitly depend on all non-source files
4565
     that are in the distribution, to make sure they are up to date in
4566
     the distribution.  *Note Making Releases: Releases.
4567
 
4568
`check'
4569
     Perform self-tests (if any).  The user must build the program
4570
     before running the tests, but need not install the program; you
4571
     should write the self-tests so that they work when the program is
4572
     built but not installed.
4573
 
4574
   The following targets are suggested as conventional names, for
4575
programs in which they are useful.
4576
 
4577
`installcheck'
4578
     Perform installation tests (if any).  The user must build and
4579
     install the program before running the tests.  You should not
4580
     assume that `$(bindir)' is in the search path.
4581
 
4582
`installdirs'
4583
     It's useful to add a target named `installdirs' to create the
4584
     directories where files are installed, and their parent
4585
     directories.  There is a script called `mkinstalldirs' which is
4586
     convenient for this; you can find it in the Texinfo package.  You
4587
     can use a rule like this:
4588
 
4589
          # Make sure all installation directories (e.g. $(bindir))
4590
          # actually exist by making them if necessary.
4591
          installdirs: mkinstalldirs
4592
                  $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
4593
                                          $(libdir) $(infodir) \
4594
                                          $(mandir)
4595
 
4596
     or, if you wish to support `DESTDIR',
4597
 
4598
          # Make sure all installation directories (e.g. $(bindir))
4599
          # actually exist by making them if necessary.
4600
          installdirs: mkinstalldirs
4601
                  $(srcdir)/mkinstalldirs \
4602
                      $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
4603
                      $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
4604
                      $(DESTDIR)$(mandir)
4605
 
4606
     This rule should not modify the directories where compilation is
4607
     done.  It should do nothing but create installation directories.
4608
 
4609
   ---------- Footnotes ----------
4610
 
4611
   (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
4612
not distributed with Texinfo.
4613
 
4614

4615
File: standards.info,  Node: Install Command Categories,  Prev: Standard Targets,  Up: Makefile Conventions
4616
 
4617
7.2.7 Install Command Categories
4618
--------------------------------
4619
 
4620
When writing the `install' target, you must classify all the commands
4621
into three categories: normal ones, "pre-installation" commands and
4622
"post-installation" commands.
4623
 
4624
   Normal commands move files into their proper places, and set their
4625
modes.  They may not alter any files except the ones that come entirely
4626
from the package they belong to.
4627
 
4628
   Pre-installation and post-installation commands may alter other
4629
files; in particular, they can edit global configuration files or data
4630
bases.
4631
 
4632
   Pre-installation commands are typically executed before the normal
4633
commands, and post-installation commands are typically run after the
4634
normal commands.
4635
 
4636
   The most common use for a post-installation command is to run
4637
`install-info'.  This cannot be done with a normal command, since it
4638
alters a file (the Info directory) which does not come entirely and
4639
solely from the package being installed.  It is a post-installation
4640
command because it needs to be done after the normal command which
4641
installs the package's Info files.
4642
 
4643
   Most programs don't need any pre-installation commands, but we have
4644
the feature just in case it is needed.
4645
 
4646
   To classify the commands in the `install' rule into these three
4647
categories, insert "category lines" among them.  A category line
4648
specifies the category for the commands that follow.
4649
 
4650
   A category line consists of a tab and a reference to a special Make
4651
variable, plus an optional comment at the end.  There are three
4652
variables you can use, one for each category; the variable name
4653
specifies the category.  Category lines are no-ops in ordinary execution
4654
because these three Make variables are normally undefined (and you
4655
_should not_ define them in the makefile).
4656
 
4657
   Here are the three possible category lines, each with a comment that
4658
explains what it means:
4659
 
4660
             $(PRE_INSTALL)     # Pre-install commands follow.
4661
             $(POST_INSTALL)    # Post-install commands follow.
4662
             $(NORMAL_INSTALL)  # Normal commands follow.
4663
 
4664
   If you don't use a category line at the beginning of the `install'
4665
rule, all the commands are classified as normal until the first category
4666
line.  If you don't use any category lines, all the commands are
4667
classified as normal.
4668
 
4669
   These are the category lines for `uninstall':
4670
 
4671
             $(PRE_UNINSTALL)     # Pre-uninstall commands follow.
4672
             $(POST_UNINSTALL)    # Post-uninstall commands follow.
4673
             $(NORMAL_UNINSTALL)  # Normal commands follow.
4674
 
4675
   Typically, a pre-uninstall command would be used for deleting entries
4676
from the Info directory.
4677
 
4678
   If the `install' or `uninstall' target has any dependencies which
4679
act as subroutines of installation, then you should start _each_
4680
dependency's commands with a category line, and start the main target's
4681
commands with a category line also.  This way, you can ensure that each
4682
command is placed in the right category regardless of which of the
4683
dependencies actually run.
4684
 
4685
   Pre-installation and post-installation commands should not run any
4686
programs except for these:
4687
 
4688
     [ basename bash cat chgrp chmod chown cmp cp dd diff echo
4689
     egrep expand expr false fgrep find getopt grep gunzip gzip
4690
     hostname install install-info kill ldconfig ln ls md5sum
4691
     mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
4692
     test touch true uname xargs yes
4693
 
4694
   The reason for distinguishing the commands in this way is for the
4695
sake of making binary packages.  Typically a binary package contains
4696
all the executables and other files that need to be installed, and has
4697
its own method of installing them--so it does not need to run the normal
4698
installation commands.  But installing the binary package does need to
4699
execute the pre-installation and post-installation commands.
4700
 
4701
   Programs to build binary packages work by extracting the
4702
pre-installation and post-installation commands.  Here is one way of
4703
extracting the pre-installation commands (the `-s' option to `make' is
4704
needed to silence messages about entering subdirectories):
4705
 
4706
     make -s -n install -o all \
4707
           PRE_INSTALL=pre-install \
4708
           POST_INSTALL=post-install \
4709
           NORMAL_INSTALL=normal-install \
4710
       | gawk -f pre-install.awk
4711
 
4712
where the file `pre-install.awk' could contain this:
4713
 
4714
     $0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0}
4715
     on {print $0}
4716
     $0 ~ /^pre-install[ \t]*$/ {on = 1}
4717
 
4718

4719
File: standards.info,  Node: Releases,  Prev: Makefile Conventions,  Up: Managing Releases
4720
 
4721
7.3 Making Releases
4722
===================
4723
 
4724
You should identify each release with a pair of version numbers, a
4725
major version and a minor.  We have no objection to using more than two
4726
numbers, but it is very unlikely that you really need them.
4727
 
4728
   Package the distribution of `Foo version 69.96' up in a gzipped tar
4729
file with the name `foo-69.96.tar.gz'.  It should unpack into a
4730
subdirectory named `foo-69.96'.
4731
 
4732
   Building and installing the program should never modify any of the
4733
files contained in the distribution.  This means that all the files
4734
that form part of the program in any way must be classified into "source
4735
files" and "non-source files".  Source files are written by humans and
4736
never changed automatically; non-source files are produced from source
4737
files by programs under the control of the Makefile.
4738
 
4739
   The distribution should contain a file named `README' which gives
4740
the name of the package, and a general description of what it does.  It
4741
is also good to explain the purpose of each of the first-level
4742
subdirectories in the package, if there are any.  The `README' file
4743
should either state the version number of the package, or refer to where
4744
in the package it can be found.
4745
 
4746
   The `README' file should refer to the file `INSTALL', which should
4747
contain an explanation of the installation procedure.
4748
 
4749
   The `README' file should also refer to the file which contains the
4750
copying conditions.  The GNU GPL, if used, should be in a file called
4751
`COPYING'.  If the GNU LGPL is used, it should be in a file called
4752
`COPYING.LIB'.
4753
 
4754
   Naturally, all the source files must be in the distribution.  It is
4755
okay to include non-source files in the distribution, provided they are
4756
up-to-date and machine-independent, so that building the distribution
4757
normally will never modify them.  We commonly include non-source files
4758
produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
4759
unnecessary dependencies between our distributions, so that users can
4760
install whichever packages they want to install.
4761
 
4762
   Non-source files that might actually be modified by building and
4763
installing the program should *never* be included in the distribution.
4764
So if you do distribute non-source files, always make sure they are up
4765
to date when you make a new distribution.
4766
 
4767
   Make sure that the directory into which the distribution unpacks (as
4768
well as any subdirectories) are all world-writable (octal mode 777).
4769
This is so that old versions of `tar' which preserve the ownership and
4770
permissions of the files from the tar archive will be able to extract
4771
all the files even if the user is unprivileged.
4772
 
4773
   Make sure that all the files in the distribution are world-readable.
4774
 
4775
   Don't include any symbolic links in the distribution itself.  If the
4776
tar file contains symbolic links, then people cannot even unpack it on
4777
systems that don't support symbolic links.  Also, don't use multiple
4778
names for one file in different directories, because certain file
4779
systems cannot handle this and that prevents unpacking the distribution.
4780
 
4781
   Try to make sure that all the file names will be unique on MS-DOS.  A
4782
name on MS-DOS consists of up to 8 characters, optionally followed by a
4783
period and up to three characters.  MS-DOS will truncate extra
4784
characters both before and after the period.  Thus, `foobarhacker.c'
4785
and `foobarhacker.o' are not ambiguous; they are truncated to
4786
`foobarha.c' and `foobarha.o', which are distinct.
4787
 
4788
   Include in your distribution a copy of the `texinfo.tex' you used to
4789
test print any `*.texinfo' or `*.texi' files.
4790
 
4791
   Likewise, if your program uses small GNU software packages like
4792
regex, getopt, obstack, or termcap, include them in the distribution
4793
file.  Leaving them out would make the distribution file a little
4794
smaller at the expense of possible inconvenience to a user who doesn't
4795
know what other files to get.
4796
 
4797

4798
File: standards.info,  Node: References,  Next: GNU Free Documentation License,  Prev: Managing Releases,  Up: Top
4799
 
4800
8 References to Non-Free Software and Documentation
4801
***************************************************
4802
 
4803
A GNU program should not recommend use of any non-free program.  We
4804
can't stop some people from writing proprietary programs, or stop other
4805
people from using them, but we can and should refuse to advertise them
4806
to new potential customers.  Proprietary software is a social and
4807
ethical problem, and the point of GNU is to solve that problem.
4808
 
4809
   The GNU definition of free software is found on the GNU web site at
4810
`http://www.gnu.org/philosophy/free-sw.html', and the definition of
4811
free documentation is found at
4812
`http://www.gnu.org/philosophy/free-doc.html'.  A list of important
4813
licenses and whether they qualify as free is in
4814
`http://www.gnu.org/licenses/license-list.html'.  The terms "free" and
4815
"non-free", used in this document, refer to that definition.  If it is
4816
not clear whether a license qualifies as free under this definition,
4817
please ask the GNU Project by writing to .  We will
4818
answer, and if the license is an important one, we will add it to the
4819
list.
4820
 
4821
   When a non-free program or system is well known, you can mention it
4822
in passing--that is harmless, since users who might want to use it
4823
probably already know about it.  For instance, it is fine to explain
4824
how to build your package on top of some widely used non-free operating
4825
system, or how to use it together with some widely used non-free
4826
program.
4827
 
4828
   However, you should give only the necessary information to help those
4829
who already use the non-free program to use your program with it--don't
4830
give, or refer to, any further information about the proprietary
4831
program, and don't imply that the proprietary program enhances your
4832
program, or that its existence is in any way a good thing.  The goal
4833
should be that people already using the proprietary program will get
4834
the advice they need about how to use your free program with it, while
4835
people who don't already use the proprietary program will not see
4836
anything to lead them to take an interest in it.
4837
 
4838
   If a non-free program or system is obscure in your program's domain,
4839
your program should not mention or support it at all, since doing so
4840
would tend to popularize the non-free program more than it popularizes
4841
your program.  (You cannot hope to find many additional users among the
4842
users of Foobar if the users of Foobar are few.)
4843
 
4844
   Sometimes a program is free software in itself but depends on a
4845
non-free platform in order to run.  For instance, many Java programs
4846
depend on the parts of Sun's Java implementation which are not yet free
4847
software, and won't run on the GNU Java Compiler (which does not yet
4848
have all the features) or won't run with the GNU Java libraries.  We
4849
hope this particular problem will be gone in a few months, when Sun
4850
makes the standard Java libraries free software, but of course the
4851
general principle remains: you should not recommend programs that
4852
depend on non-free software to run.
4853
 
4854
   Some free programs encourage the use of non-free software.  A typical
4855
example is `mplayer'.  It is free software in itself, and the free code
4856
can handle some kinds of files.  However, `mplayer' recommends use of
4857
non-free codecs for other kinds of files, and users that install
4858
`mplayer' are very likely to install those codecs along with it.  To
4859
recommend `mplayer' is, in effect, to recommend the non-free codecs.
4860
We must not do that, so we cannot recommend `mplayer' either.
4861
 
4862
   In general, you should also not recommend programs that themselves
4863
strongly recommend the use of non-free software.
4864
 
4865
   A GNU package should not refer the user to any non-free documentation
4866
for free software.  Free documentation that can be included in free
4867
operating systems is essential for completing the GNU system, or any
4868
free operating system, so it is a major focus of the GNU Project; to
4869
recommend use of documentation that we are not allowed to use in GNU
4870
would weaken the impetus for the community to produce documentation
4871
that we can include.  So GNU packages should never recommend non-free
4872
documentation.
4873
 
4874
   By contrast, it is ok to refer to journal articles and textbooks in
4875
the comments of a program for explanation of how it functions, even
4876
though they be non-free.  This is because we don't include such things
4877
in the GNU system even if we are allowed to--they are outside the scope
4878
of an operating system project.
4879
 
4880
   Referring to a web site that describes or recommends a non-free
4881
program is in effect promoting that software, so please do not make
4882
links (or mention by name) web sites that contain such material.  This
4883
policy is relevant particularly for the web pages for a GNU package.
4884
 
4885
   Following links from nearly any web site can lead to non-free
4886
software; this is an inescapable aspect of the nature of the web, and
4887
in itself is no objection to linking to a site.  As long as the site
4888
does not itself recommend a non-free program, there is no need be
4889
concerned about the sites it links to for other reasons.
4890
 
4891
   Thus, for example, you should not make a link to AT&T's web site,
4892
because that recommends AT&T's non-free software packages; you should
4893
not make a link to a site that links to AT&T's site saying it is a
4894
place to get a non-free program; but if a site you want to link to
4895
refers to AT&T's web site in some other context (such as long-distance
4896
telephone service), that is not a problem.
4897
 
4898

4899
File: standards.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: References,  Up: Top
4900
 
4901
Appendix A GNU Free Documentation License
4902
*****************************************
4903
 
4904
                      Version 1.2, November 2002
4905
 
4906
     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
4907
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
4908
 
4909
     Everyone is permitted to copy and distribute verbatim copies
4910
     of this license document, but changing it is not allowed.
4911
 
4912
  0. PREAMBLE
4913
 
4914
     The purpose of this License is to make a manual, textbook, or other
4915
     functional and useful document "free" in the sense of freedom: to
4916
     assure everyone the effective freedom to copy and redistribute it,
4917
     with or without modifying it, either commercially or
4918
     noncommercially.  Secondarily, this License preserves for the
4919
     author and publisher a way to get credit for their work, while not
4920
     being considered responsible for modifications made by others.
4921
 
4922
     This License is a kind of "copyleft", which means that derivative
4923
     works of the document must themselves be free in the same sense.
4924
     It complements the GNU General Public License, which is a copyleft
4925
     license designed for free software.
4926
 
4927
     We have designed this License in order to use it for manuals for
4928
     free software, because free software needs free documentation: a
4929
     free program should come with manuals providing the same freedoms
4930
     that the software does.  But this License is not limited to
4931
     software manuals; it can be used for any textual work, regardless
4932
     of subject matter or whether it is published as a printed book.
4933
     We recommend this License principally for works whose purpose is
4934
     instruction or reference.
4935
 
4936
  1. APPLICABILITY AND DEFINITIONS
4937
 
4938
     This License applies to any manual or other work, in any medium,
4939
     that contains a notice placed by the copyright holder saying it
4940
     can be distributed under the terms of this License.  Such a notice
4941
     grants a world-wide, royalty-free license, unlimited in duration,
4942
     to use that work under the conditions stated herein.  The
4943
     "Document", below, refers to any such manual or work.  Any member
4944
     of the public is a licensee, and is addressed as "you".  You
4945
     accept the license if you copy, modify or distribute the work in a
4946
     way requiring permission under copyright law.
4947
 
4948
     A "Modified Version" of the Document means any work containing the
4949
     Document or a portion of it, either copied verbatim, or with
4950
     modifications and/or translated into another language.
4951
 
4952
     A "Secondary Section" is a named appendix or a front-matter section
4953
     of the Document that deals exclusively with the relationship of the
4954
     publishers or authors of the Document to the Document's overall
4955
     subject (or to related matters) and contains nothing that could
4956
     fall directly within that overall subject.  (Thus, if the Document
4957
     is in part a textbook of mathematics, a Secondary Section may not
4958
     explain any mathematics.)  The relationship could be a matter of
4959
     historical connection with the subject or with related matters, or
4960
     of legal, commercial, philosophical, ethical or political position
4961
     regarding them.
4962
 
4963
     The "Invariant Sections" are certain Secondary Sections whose
4964
     titles are designated, as being those of Invariant Sections, in
4965
     the notice that says that the Document is released under this
4966
     License.  If a section does not fit the above definition of
4967
     Secondary then it is not allowed to be designated as Invariant.
4968
     The Document may contain zero Invariant Sections.  If the Document
4969
     does not identify any Invariant Sections then there are none.
4970
 
4971
     The "Cover Texts" are certain short passages of text that are
4972
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4973
     that says that the Document is released under this License.  A
4974
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
4975
     be at most 25 words.
4976
 
4977
     A "Transparent" copy of the Document means a machine-readable copy,
4978
     represented in a format whose specification is available to the
4979
     general public, that is suitable for revising the document
4980
     straightforwardly with generic text editors or (for images
4981
     composed of pixels) generic paint programs or (for drawings) some
4982
     widely available drawing editor, and that is suitable for input to
4983
     text formatters or for automatic translation to a variety of
4984
     formats suitable for input to text formatters.  A copy made in an
4985
     otherwise Transparent file format whose markup, or absence of
4986
     markup, has been arranged to thwart or discourage subsequent
4987
     modification by readers is not Transparent.  An image format is
4988
     not Transparent if used for any substantial amount of text.  A
4989
     copy that is not "Transparent" is called "Opaque".
4990
 
4991
     Examples of suitable formats for Transparent copies include plain
4992
     ASCII without markup, Texinfo input format, LaTeX input format,
4993
     SGML or XML using a publicly available DTD, and
4994
     standard-conforming simple HTML, PostScript or PDF designed for
4995
     human modification.  Examples of transparent image formats include
4996
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
4997
     can be read and edited only by proprietary word processors, SGML or
4998
     XML for which the DTD and/or processing tools are not generally
4999
     available, and the machine-generated HTML, PostScript or PDF
5000
     produced by some word processors for output purposes only.
5001
 
5002
     The "Title Page" means, for a printed book, the title page itself,
5003
     plus such following pages as are needed to hold, legibly, the
5004
     material this License requires to appear in the title page.  For
5005
     works in formats which do not have any title page as such, "Title
5006
     Page" means the text near the most prominent appearance of the
5007
     work's title, preceding the beginning of the body of the text.
5008
 
5009
     A section "Entitled XYZ" means a named subunit of the Document
5010
     whose title either is precisely XYZ or contains XYZ in parentheses
5011
     following text that translates XYZ in another language.  (Here XYZ
5012
     stands for a specific section name mentioned below, such as
5013
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
5014
     To "Preserve the Title" of such a section when you modify the
5015
     Document means that it remains a section "Entitled XYZ" according
5016
     to this definition.
5017
 
5018
     The Document may include Warranty Disclaimers next to the notice
5019
     which states that this License applies to the Document.  These
5020
     Warranty Disclaimers are considered to be included by reference in
5021
     this License, but only as regards disclaiming warranties: any other
5022
     implication that these Warranty Disclaimers may have is void and
5023
     has no effect on the meaning of this License.
5024
 
5025
  2. VERBATIM COPYING
5026
 
5027
     You may copy and distribute the Document in any medium, either
5028
     commercially or noncommercially, provided that this License, the
5029
     copyright notices, and the license notice saying this License
5030
     applies to the Document are reproduced in all copies, and that you
5031
     add no other conditions whatsoever to those of this License.  You
5032
     may not use technical measures to obstruct or control the reading
5033
     or further copying of the copies you make or distribute.  However,
5034
     you may accept compensation in exchange for copies.  If you
5035
     distribute a large enough number of copies you must also follow
5036
     the conditions in section 3.
5037
 
5038
     You may also lend copies, under the same conditions stated above,
5039
     and you may publicly display copies.
5040
 
5041
  3. COPYING IN QUANTITY
5042
 
5043
     If you publish printed copies (or copies in media that commonly
5044
     have printed covers) of the Document, numbering more than 100, and
5045
     the Document's license notice requires Cover Texts, you must
5046
     enclose the copies in covers that carry, clearly and legibly, all
5047
     these Cover Texts: Front-Cover Texts on the front cover, and
5048
     Back-Cover Texts on the back cover.  Both covers must also clearly
5049
     and legibly identify you as the publisher of these copies.  The
5050
     front cover must present the full title with all words of the
5051
     title equally prominent and visible.  You may add other material
5052
     on the covers in addition.  Copying with changes limited to the
5053
     covers, as long as they preserve the title of the Document and
5054
     satisfy these conditions, can be treated as verbatim copying in
5055
     other respects.
5056
 
5057
     If the required texts for either cover are too voluminous to fit
5058
     legibly, you should put the first ones listed (as many as fit
5059
     reasonably) on the actual cover, and continue the rest onto
5060
     adjacent pages.
5061
 
5062
     If you publish or distribute Opaque copies of the Document
5063
     numbering more than 100, you must either include a
5064
     machine-readable Transparent copy along with each Opaque copy, or
5065
     state in or with each Opaque copy a computer-network location from
5066
     which the general network-using public has access to download
5067
     using public-standard network protocols a complete Transparent
5068
     copy of the Document, free of added material.  If you use the
5069
     latter option, you must take reasonably prudent steps, when you
5070
     begin distribution of Opaque copies in quantity, to ensure that
5071
     this Transparent copy will remain thus accessible at the stated
5072
     location until at least one year after the last time you
5073
     distribute an Opaque copy (directly or through your agents or
5074
     retailers) of that edition to the public.
5075
 
5076
     It is requested, but not required, that you contact the authors of
5077
     the Document well before redistributing any large number of
5078
     copies, to give them a chance to provide you with an updated
5079
     version of the Document.
5080
 
5081
  4. MODIFICATIONS
5082
 
5083
     You may copy and distribute a Modified Version of the Document
5084
     under the conditions of sections 2 and 3 above, provided that you
5085
     release the Modified Version under precisely this License, with
5086
     the Modified Version filling the role of the Document, thus
5087
     licensing distribution and modification of the Modified Version to
5088
     whoever possesses a copy of it.  In addition, you must do these
5089
     things in the Modified Version:
5090
 
5091
       A. Use in the Title Page (and on the covers, if any) a title
5092
          distinct from that of the Document, and from those of
5093
          previous versions (which should, if there were any, be listed
5094
          in the History section of the Document).  You may use the
5095
          same title as a previous version if the original publisher of
5096
          that version gives permission.
5097
 
5098
       B. List on the Title Page, as authors, one or more persons or
5099
          entities responsible for authorship of the modifications in
5100
          the Modified Version, together with at least five of the
5101
          principal authors of the Document (all of its principal
5102
          authors, if it has fewer than five), unless they release you
5103
          from this requirement.
5104
 
5105
       C. State on the Title page the name of the publisher of the
5106
          Modified Version, as the publisher.
5107
 
5108
       D. Preserve all the copyright notices of the Document.
5109
 
5110
       E. Add an appropriate copyright notice for your modifications
5111
          adjacent to the other copyright notices.
5112
 
5113
       F. Include, immediately after the copyright notices, a license
5114
          notice giving the public permission to use the Modified
5115
          Version under the terms of this License, in the form shown in
5116
          the Addendum below.
5117
 
5118
       G. Preserve in that license notice the full lists of Invariant
5119
          Sections and required Cover Texts given in the Document's
5120
          license notice.
5121
 
5122
       H. Include an unaltered copy of this License.
5123
 
5124
       I. Preserve the section Entitled "History", Preserve its Title,
5125
          and add to it an item stating at least the title, year, new
5126
          authors, and publisher of the Modified Version as given on
5127
          the Title Page.  If there is no section Entitled "History" in
5128
          the Document, create one stating the title, year, authors,
5129
          and publisher of the Document as given on its Title Page,
5130
          then add an item describing the Modified Version as stated in
5131
          the previous sentence.
5132
 
5133
       J. Preserve the network location, if any, given in the Document
5134
          for public access to a Transparent copy of the Document, and
5135
          likewise the network locations given in the Document for
5136
          previous versions it was based on.  These may be placed in
5137
          the "History" section.  You may omit a network location for a
5138
          work that was published at least four years before the
5139
          Document itself, or if the original publisher of the version
5140
          it refers to gives permission.
5141
 
5142
       K. For any section Entitled "Acknowledgements" or "Dedications",
5143
          Preserve the Title of the section, and preserve in the
5144
          section all the substance and tone of each of the contributor
5145
          acknowledgements and/or dedications given therein.
5146
 
5147
       L. Preserve all the Invariant Sections of the Document,
5148
          unaltered in their text and in their titles.  Section numbers
5149
          or the equivalent are not considered part of the section
5150
          titles.
5151
 
5152
       M. Delete any section Entitled "Endorsements".  Such a section
5153
          may not be included in the Modified Version.
5154
 
5155
       N. Do not retitle any existing section to be Entitled
5156
          "Endorsements" or to conflict in title with any Invariant
5157
          Section.
5158
 
5159
       O. Preserve any Warranty Disclaimers.
5160
 
5161
     If the Modified Version includes new front-matter sections or
5162
     appendices that qualify as Secondary Sections and contain no
5163
     material copied from the Document, you may at your option
5164
     designate some or all of these sections as invariant.  To do this,
5165
     add their titles to the list of Invariant Sections in the Modified
5166
     Version's license notice.  These titles must be distinct from any
5167
     other section titles.
5168
 
5169
     You may add a section Entitled "Endorsements", provided it contains
5170
     nothing but endorsements of your Modified Version by various
5171
     parties--for example, statements of peer review or that the text
5172
     has been approved by an organization as the authoritative
5173
     definition of a standard.
5174
 
5175
     You may add a passage of up to five words as a Front-Cover Text,
5176
     and a passage of up to 25 words as a Back-Cover Text, to the end
5177
     of the list of Cover Texts in the Modified Version.  Only one
5178
     passage of Front-Cover Text and one of Back-Cover Text may be
5179
     added by (or through arrangements made by) any one entity.  If the
5180
     Document already includes a cover text for the same cover,
5181
     previously added by you or by arrangement made by the same entity
5182
     you are acting on behalf of, you may not add another; but you may
5183
     replace the old one, on explicit permission from the previous
5184
     publisher that added the old one.
5185
 
5186
     The author(s) and publisher(s) of the Document do not by this
5187
     License give permission to use their names for publicity for or to
5188
     assert or imply endorsement of any Modified Version.
5189
 
5190
  5. COMBINING DOCUMENTS
5191
 
5192
     You may combine the Document with other documents released under
5193
     this License, under the terms defined in section 4 above for
5194
     modified versions, provided that you include in the combination
5195
     all of the Invariant Sections of all of the original documents,
5196
     unmodified, and list them all as Invariant Sections of your
5197
     combined work in its license notice, and that you preserve all
5198
     their Warranty Disclaimers.
5199
 
5200
     The combined work need only contain one copy of this License, and
5201
     multiple identical Invariant Sections may be replaced with a single
5202
     copy.  If there are multiple Invariant Sections with the same name
5203
     but different contents, make the title of each such section unique
5204
     by adding at the end of it, in parentheses, the name of the
5205
     original author or publisher of that section if known, or else a
5206
     unique number.  Make the same adjustment to the section titles in
5207
     the list of Invariant Sections in the license notice of the
5208
     combined work.
5209
 
5210
     In the combination, you must combine any sections Entitled
5211
     "History" in the various original documents, forming one section
5212
     Entitled "History"; likewise combine any sections Entitled
5213
     "Acknowledgements", and any sections Entitled "Dedications".  You
5214
     must delete all sections Entitled "Endorsements."
5215
 
5216
  6. COLLECTIONS OF DOCUMENTS
5217
 
5218
     You may make a collection consisting of the Document and other
5219
     documents released under this License, and replace the individual
5220
     copies of this License in the various documents with a single copy
5221
     that is included in the collection, provided that you follow the
5222
     rules of this License for verbatim copying of each of the
5223
     documents in all other respects.
5224
 
5225
     You may extract a single document from such a collection, and
5226
     distribute it individually under this License, provided you insert
5227
     a copy of this License into the extracted document, and follow
5228
     this License in all other respects regarding verbatim copying of
5229
     that document.
5230
 
5231
  7. AGGREGATION WITH INDEPENDENT WORKS
5232
 
5233
     A compilation of the Document or its derivatives with other
5234
     separate and independent documents or works, in or on a volume of
5235
     a storage or distribution medium, is called an "aggregate" if the
5236
     copyright resulting from the compilation is not used to limit the
5237
     legal rights of the compilation's users beyond what the individual
5238
     works permit.  When the Document is included in an aggregate, this
5239
     License does not apply to the other works in the aggregate which
5240
     are not themselves derivative works of the Document.
5241
 
5242
     If the Cover Text requirement of section 3 is applicable to these
5243
     copies of the Document, then if the Document is less than one half
5244
     of the entire aggregate, the Document's Cover Texts may be placed
5245
     on covers that bracket the Document within the aggregate, or the
5246
     electronic equivalent of covers if the Document is in electronic
5247
     form.  Otherwise they must appear on printed covers that bracket
5248
     the whole aggregate.
5249
 
5250
  8. TRANSLATION
5251
 
5252
     Translation is considered a kind of modification, so you may
5253
     distribute translations of the Document under the terms of section
5254
     4.  Replacing Invariant Sections with translations requires special
5255
     permission from their copyright holders, but you may include
5256
     translations of some or all Invariant Sections in addition to the
5257
     original versions of these Invariant Sections.  You may include a
5258
     translation of this License, and all the license notices in the
5259
     Document, and any Warranty Disclaimers, provided that you also
5260
     include the original English version of this License and the
5261
     original versions of those notices and disclaimers.  In case of a
5262
     disagreement between the translation and the original version of
5263
     this License or a notice or disclaimer, the original version will
5264
     prevail.
5265
 
5266
     If a section in the Document is Entitled "Acknowledgements",
5267
     "Dedications", or "History", the requirement (section 4) to
5268
     Preserve its Title (section 1) will typically require changing the
5269
     actual title.
5270
 
5271
  9. TERMINATION
5272
 
5273
     You may not copy, modify, sublicense, or distribute the Document
5274
     except as expressly provided for under this License.  Any other
5275
     attempt to copy, modify, sublicense or distribute the Document is
5276
     void, and will automatically terminate your rights under this
5277
     License.  However, parties who have received copies, or rights,
5278
     from you under this License will not have their licenses
5279
     terminated so long as such parties remain in full compliance.
5280
 
5281
 10. FUTURE REVISIONS OF THIS LICENSE
5282
 
5283
     The Free Software Foundation may publish new, revised versions of
5284
     the GNU Free Documentation License from time to time.  Such new
5285
     versions will be similar in spirit to the present version, but may
5286
     differ in detail to address new problems or concerns.  See
5287
     `http://www.gnu.org/copyleft/'.
5288
 
5289
     Each version of the License is given a distinguishing version
5290
     number.  If the Document specifies that a particular numbered
5291
     version of this License "or any later version" applies to it, you
5292
     have the option of following the terms and conditions either of
5293
     that specified version or of any later version that has been
5294
     published (not as a draft) by the Free Software Foundation.  If
5295
     the Document does not specify a version number of this License,
5296
     you may choose any version ever published (not as a draft) by the
5297
     Free Software Foundation.
5298
 
5299
ADDENDUM: How to use this License for your documents
5300
====================================================
5301
 
5302
To use this License in a document you have written, include a copy of
5303
the License in the document and put the following copyright and license
5304
notices just after the title page:
5305
 
5306
       Copyright (C)  YEAR  YOUR NAME.
5307
       Permission is granted to copy, distribute and/or modify this document
5308
       under the terms of the GNU Free Documentation License, Version 1.2
5309
       or any later version published by the Free Software Foundation;
5310
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
5311
       Texts.  A copy of the license is included in the section entitled ``GNU
5312
       Free Documentation License''.
5313
 
5314
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
5315
Texts, replace the "with...Texts." line with this:
5316
 
5317
         with the Invariant Sections being LIST THEIR TITLES, with
5318
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
5319
         being LIST.
5320
 
5321
   If you have Invariant Sections without Cover Texts, or some other
5322
combination of the three, merge those two alternatives to suit the
5323
situation.
5324
 
5325
   If your document contains nontrivial examples of program code, we
5326
recommend releasing these examples in parallel under your choice of
5327
free software license, such as the GNU General Public License, to
5328
permit their use in free software.
5329
 
5330

5331
File: standards.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top
5332
 
5333
Index
5334
*****
5335
 
5336
 
5337
* Menu:
5338
5339
* #endif, commenting:                    Comments.            (line  60)
5340
* --help output:                         --help.              (line   6)
5341
* --version output:                      --version.           (line   6)
5342
* -Wall compiler option:                 Syntactic Conventions.
5343
                                                              (line  10)
5344
* accepting contributions:               Contributions.       (line   6)
5345
* address for bug reports:               --help.              (line  11)
5346
* ANSI C standard:                       Standard C.          (line   6)
5347
* arbitrary limits on data:              Semantics.           (line   6)
5348
* ASCII characters:                      Character Set.       (line   6)
5349
* autoconf:                              System Portability.  (line  23)
5350
* avoiding proprietary code:             Reading Non-Free Code.
5351
                                                              (line   6)
5352
* behavior, dependent on program's name: User Interfaces.     (line   6)
5353
* binary packages:                       Install Command Categories.
5354
                                                              (line  80)
5355
* bindir:                                Directory Variables. (line  54)
5356
* braces, in C source:                   Formatting.          (line   6)
5357
* bug reports:                           --help.              (line  11)
5358
* canonical name of a program:           --version.           (line  12)
5359
* casting pointers to integers:          CPU Portability.     (line  90)
5360
* CGI programs, standard options for:    Command-Line Interfaces.
5361
                                                              (line  31)
5362
* change logs:                           Change Logs.         (line   6)
5363
* change logs, conditional changes:      Conditional Changes. (line   6)
5364
* change logs, style:                    Style of Change Logs.
5365
                                                              (line   6)
5366
* character set:                         Character Set.       (line   6)
5367
* command-line arguments, decoding:      Semantics.           (line  46)
5368
* command-line interface:                Command-Line Interfaces.
5369
                                                              (line   6)
5370
* commenting:                            Comments.            (line   6)
5371
* compatibility with C and POSIX standards: Compatibility.    (line   6)
5372
* compiler warnings:                     Syntactic Conventions.
5373
                                                              (line  10)
5374
* conditional changes, and change logs:  Conditional Changes. (line   6)
5375
* conditionals, comments for:            Comments.            (line  60)
5376
* configure:                             Configuration.       (line   6)
5377
* control-L:                             Formatting.          (line 118)
5378
* conventions for makefiles:             Makefile Conventions.
5379
                                                              (line   6)
5380
* corba:                                 Graphical Interfaces.
5381
                                                              (line  16)
5382
* credits for manuals:                   Manual Credits.      (line   6)
5383
* data types, and portability:           CPU Portability.     (line   6)
5384
* declaration for system functions:      System Functions.    (line  21)
5385
* DESTDIR:                               DESTDIR.             (line   6)
5386
* documentation:                         Documentation.       (line   6)
5387
* doschk:                                Names.               (line  38)
5388
* downloading this manual:               Preface.             (line  17)
5389
* encodings:                             Character Set.       (line   6)
5390
* error messages:                        Semantics.           (line  19)
5391
* error messages, formatting:            Errors.              (line   6)
5392
* exec_prefix:                           Directory Variables. (line  36)
5393
* expressions, splitting:                Formatting.          (line  81)
5394
* FDL, GNU Free Documentation License:   GNU Free Documentation License.
5395
                                                              (line   6)
5396
* file usage:                            File Usage.          (line   6)
5397
* file-name limitations:                 Names.               (line  38)
5398
* formatting error messages:             Errors.              (line   6)
5399
* formatting source code:                Formatting.          (line   6)
5400
* formfeed:                              Formatting.          (line 118)
5401
* function argument, declaring:          Syntactic Conventions.
5402
                                                              (line   6)
5403
* function prototypes:                   Standard C.          (line  17)
5404
* getopt:                                Command-Line Interfaces.
5405
                                                              (line   6)
5406
* gettext:                               Internationalization.
5407
                                                              (line   6)
5408
* gnome:                                 Graphical Interfaces.
5409
                                                              (line  16)
5410
* graphical user interface:              Graphical Interfaces.
5411
                                                              (line   6)
5412
* grave accent:                          Quote Characters.    (line   6)
5413
* gtk+:                                  Graphical Interfaces.
5414
                                                              (line   6)
5415
* GUILE:                                 Source Language.     (line  38)
5416
* implicit int:                          Syntactic Conventions.
5417
                                                              (line   6)
5418
* impossible conditions:                 Semantics.           (line  70)
5419
* installations, staged:                 DESTDIR.             (line   6)
5420
* internationalization:                  Internationalization.
5421
                                                              (line   6)
5422
* left quote:                            Quote Characters.    (line   6)
5423
* legal aspects:                         Legal Issues.        (line   6)
5424
* legal papers:                          Contributions.       (line   6)
5425
* libexecdir:                            Directory Variables. (line  67)
5426
* libraries:                             Libraries.           (line   6)
5427
* library functions, and portability:    System Functions.    (line   6)
5428
* license for manuals:                   License for Manuals. (line   6)
5429
* lint:                                  Syntactic Conventions.
5430
                                                              (line 109)
5431
* locale-specific quote characters:      Quote Characters.    (line   6)
5432
* long option names:                     Option Table.        (line   6)
5433
* long-named options:                    Command-Line Interfaces.
5434
                                                              (line  12)
5435
* makefile, conventions for:             Makefile Conventions.
5436
                                                              (line   6)
5437
* malloc return value:                   Semantics.           (line  25)
5438
* man pages:                             Man Pages.           (line   6)
5439
* manual structure:                      Manual Structure Details.
5440
                                                              (line   6)
5441
* memory allocation failure:             Semantics.           (line  25)
5442
* memory usage:                          Memory Usage.        (line   6)
5443
* message text, and internationalization: Internationalization.
5444
                                                              (line  29)
5445
* mmap:                                  Mmap.                (line   6)
5446
* multiple variables in a line:          Syntactic Conventions.
5447
                                                              (line  35)
5448
* names of variables, functions, and files: Names.            (line   6)
5449
* NEWS file:                             NEWS File.           (line   6)
5450
* non-ASCII characters:                  Character Set.       (line   6)
5451
* non-POSIX systems, and portability:    System Portability.  (line  32)
5452
* non-standard extensions:               Using Extensions.    (line   6)
5453
* NUL characters:                        Semantics.           (line  11)
5454
* open brace:                            Formatting.          (line   6)
5455
* optional features, configure-time:     Configuration.       (line  83)
5456
* options for compatibility:             Compatibility.       (line  14)
5457
* options, standard command-line:        Command-Line Interfaces.
5458
                                                              (line  31)
5459
* output device and program's behavior:  User Interfaces.     (line  13)
5460
* packaging:                             Releases.            (line   6)
5461
* PATH_INFO, specifying standard options as: Command-Line Interfaces.
5462
                                                              (line  31)
5463
* portability, and data types:           CPU Portability.     (line   6)
5464
* portability, and library functions:    System Functions.    (line   6)
5465
* portability, between system types:     System Portability.  (line   6)
5466
* POSIX compatibility:                   Compatibility.       (line   6)
5467
* POSIXLY_CORRECT, environment variable: Compatibility.       (line  21)
5468
* post-installation commands:            Install Command Categories.
5469
                                                              (line   6)
5470
* pre-installation commands:             Install Command Categories.
5471
                                                              (line   6)
5472
* prefix:                                Directory Variables. (line  26)
5473
* program configuration:                 Configuration.       (line   6)
5474
* program design:                        Design Advice.       (line   6)
5475
* program name and its behavior:         User Interfaces.     (line   6)
5476
* program's canonical name:              --version.           (line  12)
5477
* programming languages:                 Source Language.     (line   6)
5478
* proprietary programs:                  Reading Non-Free Code.
5479
                                                              (line   6)
5480
* quote characters:                      Quote Characters.    (line   6)
5481
* README file:                           Releases.            (line  21)
5482
* references to non-free material:       References.          (line   6)
5483
* releasing:                             Managing Releases.   (line   6)
5484
* sbindir:                               Directory Variables. (line  60)
5485
* signal handling:                       Semantics.           (line  59)
5486
* spaces before open-paren:              Formatting.          (line  75)
5487
* staged installs:                       DESTDIR.             (line   6)
5488
* standard command-line options:         Command-Line Interfaces.
5489
                                                              (line  31)
5490
* standards for makefiles:               Makefile Conventions.
5491
                                                              (line   6)
5492
* string library functions:              System Functions.    (line  55)
5493
* syntactic conventions:                 Syntactic Conventions.
5494
                                                              (line   6)
5495
* table of long options:                 Option Table.        (line   6)
5496
* temporary files:                       Semantics.           (line  84)
5497
* temporary variables:                   Syntactic Conventions.
5498
                                                              (line  23)
5499
* texinfo.tex, in a distribution:        Releases.            (line  70)
5500
 
5501
 
5502
* where to obtain standards.texi:        Preface.             (line  17)
5503
5504
5505

5506
Tag Table:
5507
Node: Top797
5508
Node: Preface2053
5509
Node: Legal Issues4168
5510
Node: Reading Non-Free Code4638
5511
Node: Contributions6368
5512
Node: Trademarks8606
5513
Node: Design Advice10241
5514
Node: Source Language10833
5515
Node: Compatibility12845
5516
Node: Using Extensions14473
5517
Node: Standard C16049
5518
Node: Conditional Compilation18452
5519
Node: Program Behavior19850
5520
Node: Non-GNU Standards20906
5521
Node: Semantics23187
5522
Node: Libraries27906
5523
Node: Errors29151
5524
Node: User Interfaces31644
5525
Node: Graphical Interfaces33249
5526
Node: Command-Line Interfaces34285
5527
Node: --version36317
5528
Node: --help42210
5529
Node: Option Table42764
5530
Node: Memory Usage57705
5531
Node: File Usage58736
5532
Node: Writing C59486
5533
Node: Formatting60458
5534
Node: Comments64747
5535
Node: Syntactic Conventions68299
5536
Node: Names71761
5537
Node: System Portability73973
5538
Node: CPU Portability76863
5539
Node: System Functions80775
5540
Node: Internationalization85972
5541
Node: Character Set89966
5542
Node: Quote Characters90779
5543
Node: Mmap92299
5544
Node: Documentation93007
5545
Node: GNU Manuals94113
5546
Node: Doc Strings and Manuals99851
5547
Node: Manual Structure Details101404
5548
Node: License for Manuals102822
5549
Node: Manual Credits103796
5550
Node: Printed Manuals104189
5551
Node: NEWS File104875
5552
Node: Change Logs105553
5553
Node: Change Log Concepts106307
5554
Node: Style of Change Logs108396
5555
Node: Simple Changes110896
5556
Node: Conditional Changes112338
5557
Node: Indicating the Part Changed113760
5558
Node: Man Pages114287
5559
Node: Reading other Manuals116599
5560
Node: Managing Releases117390
5561
Node: Configuration118171
5562
Node: Makefile Conventions125891
5563
Node: Makefile Basics126773
5564
Node: Utilities in Makefiles129947
5565
Node: Command Variables132092
5566
Node: DESTDIR135314
5567
Node: Directory Variables137463
5568
Node: Standard Targets151956
5569
Ref: Standard Targets-Footnote-1165471
5570
Node: Install Command Categories165571
5571
Node: Releases170104
5572
Node: References174031
5573
Node: GNU Free Documentation License179526

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.