1 This is Info file ../info/standards.info, produced by Makeinfo version
2 1.68 from the input file standards.texi.
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
9 Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
20 Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
26 File: standards.info, Node: CPU Portability, Next: System Functions, Prev: System Portability, Up: Writing C
28 Portability between CPUs
29 ========================
31 Even GNU systems will differ because of differences among CPU
32 types--for example, difference in byte ordering and alignment
33 requirements. It is absolutely essential to handle these differences.
34 However, don't make any effort to cater to the possibility that an
35 `int' will be less than 32 bits. We don't support 16-bit machines in
38 Don't assume that the address of an `int' object is also the address
39 of its least-significant byte. This is false on big-endian machines.
40 Thus, don't make the following mistake:
44 while ((c = getchar()) != EOF)
45 write(file_descriptor, &c, 1);
47 When calling functions, you need not worry about the difference
48 between pointers of various types, or between pointers and integers.
49 On most machines, there's no difference anyway. As for the few
50 machines where there is a difference, all of them support ANSI C, so
51 you can use prototypes (conditionalized to be active only in ANSI C) to
52 make the code work on those systems.
54 In certain cases, it is ok to pass integer and pointer arguments
55 indiscriminately to the same function, and use no prototype on any
56 system. For example, many GNU programs have error-reporting functions
57 that pass their arguments along to `printf' and friends:
63 fprintf (stderr, "error: ");
64 fprintf (stderr, s, a1, a2, a3);
67 In practice, this works on all machines, and it is much simpler than any
68 "correct" alternative. Be sure *not* to use a prototype for such
71 However, avoid casting pointers to integers unless you really need
72 to. These assumptions really reduce portability, and in most programs
73 they are easy to avoid. In the cases where casting pointers to
74 integers is essential--such as, a Lisp interpreter which stores type
75 information as well as an address in one word--it is ok to do so, but
76 you'll have to make explicit provisions to handle different word sizes.
79 File: standards.info, Node: System Functions, Next: Internationalization, Prev: CPU Portability, Up: Writing C
81 Calling System Functions
82 ========================
84 C implementations differ substantially. ANSI C reduces but does not
85 eliminate the incompatibilities; meanwhile, many users wish to compile
86 GNU software with pre-ANSI compilers. This chapter gives
87 recommendations for how to use the more or less standard C library
88 functions to avoid unnecessary loss of portability.
90 * Don't use the value of `sprintf'. It returns the number of
91 characters written on some systems, but not on all systems.
93 * Don't declare system functions explicitly.
95 Almost any declaration for a system function is wrong on some
96 system. To minimize conflicts, leave it to the system header
97 files to declare system functions. If the headers don't declare a
98 function, let it remain undeclared.
100 While it may seem unclean to use a function without declaring it,
101 in practice this works fine for most system library functions on
102 the systems where this really happens; thus, the disadvantage is
103 only theoretical. By contrast, actual declarations have
104 frequently caused actual conflicts.
106 * If you must declare a system function, don't specify the argument
107 types. Use an old-style declaration, not an ANSI prototype. The
108 more you specify about the function, the more likely a conflict.
110 * In particular, don't unconditionally declare `malloc' or `realloc'.
112 Most GNU programs use those functions just once, in functions
113 conventionally named `xmalloc' and `xrealloc'. These functions
114 call `malloc' and `realloc', respectively, and check the results.
116 Because `xmalloc' and `xrealloc' are defined in your program, you
117 can declare them in other files without any risk of type conflict.
119 On most systems, `int' is the same length as a pointer; thus, the
120 calls to `malloc' and `realloc' work fine. For the few
121 exceptional systems (mostly 64-bit machines), you can use
122 *conditionalized* declarations of `malloc' and `realloc'--or put
123 these declarations in configuration files specific to those
126 * The string functions require special treatment. Some Unix systems
127 have a header file `string.h'; others have `strings.h'. Neither
128 file name is portable. There are two things you can do: use
129 Autoconf to figure out which file to include, or don't include
132 * If you don't include either strings file, you can't get
133 declarations for the string functions from the header file in the
136 That causes less of a problem than you might think. The newer ANSI
137 string functions should be avoided anyway because many systems
138 still don't support them. The string functions you can use are
141 strcpy strncpy strcat strncat
142 strlen strcmp strncmp
145 The copy and concatenate functions work fine without a declaration
146 as long as you don't use their values. Using their values without
147 a declaration fails on systems where the width of a pointer
148 differs from the width of `int', and perhaps in other cases. It
149 is trivial to avoid using their values, so do that.
151 The compare functions and `strlen' work fine without a declaration
152 on most systems, possibly all the ones that GNU software runs on.
153 You may find it necessary to declare them *conditionally* on a few
156 The search functions must be declared to return `char *'. Luckily,
157 there is no variation in the data type they return. But there is
158 variation in their names. Some systems give these functions the
159 names `index' and `rindex'; other systems use the names `strchr'
160 and `strrchr'. Some systems support both pairs of names, but
161 neither pair works on all systems.
163 You should pick a single pair of names and use it throughout your
164 program. (Nowadays, it is better to choose `strchr' and `strrchr'
165 for new programs, since those are the standard ANSI names.)
166 Declare both of those names as functions returning `char *'. On
167 systems which don't support those names, define them as macros in
168 terms of the other pair. For example, here is what to put at the
169 beginning of your file (or in a header) if you want to use the
170 names `strchr' and `strrchr' throughout:
176 #define strrchr rindex
182 Here we assume that `HAVE_STRCHR' and `HAVE_STRRCHR' are macros
183 defined in systems where the corresponding functions exist. One way to
184 get them properly defined is to use Autoconf.
187 File: standards.info, Node: Internationalization, Prev: System Functions, Up: Writing C
192 GNU has a library called GNU gettext that makes it easy to translate
193 the messages in a program into various languages. You should use this
194 library in every program. Use English for the messages as they appear
195 in the program, and let gettext provide the way to translate them into
198 Using GNU gettext involves putting a call to the `gettext' macro
199 around each string that might need translation--like this:
201 printf (gettext ("Processing file `%s'..."));
203 This permits GNU gettext to replace the string `"Processing file
204 `%s'..."' with a translated version.
206 Once a program uses gettext, please make a point of writing calls to
207 `gettext' when you add new strings that call for translation.
209 Using GNU gettext in a package involves specifying a "text domain
210 name" for the package. The text domain name is used to separate the
211 translations for this package from the translations for other packages.
212 Normally, the text domain name should be the same as the name of the
213 package--for example, `fileutils' for the GNU file utilities.
215 To enable gettext to work, avoid writing code that makes assumptions
216 about the structure of words. Don't construct words from parts. Here
217 is an example of what not to do:
219 prinf ("%d file%s processed", nfiles,
220 nfiles > 1 ? "s" : "");
222 The problem with that example is that it assumes that plurals are made
223 by adding `s'. If you apply gettext to the format string, like this,
225 prinf (gettext ("%d file%s processed"), nfiles,
226 nfiles > 1 ? "s" : "");
228 the message can use different words, but it will still be forced to use
229 `s' for the plural. Here is a better way:
231 prinf ((nfiles > 1 ? "%d files processed"
232 : "%d file processed"),
235 This way, you can apply gettext to each of the two strings
238 prinf ((nfiles > 1 ? gettext ("%d files processed")
239 : gettext ("%d file processed")),
242 This can handle any language, no matter how it forms the plural of the
246 File: standards.info, Node: Documentation, Next: Managing Releases, Prev: Writing C, Up: Top
253 * GNU Manuals:: Writing proper manuals.
254 * Manual Structure Details:: Specific structure conventions.
255 * NEWS File:: NEWS files supplement manuals.
256 * Change Logs:: Recording Changes
257 * Man Pages:: Man pages are secondary.
258 * Reading other Manuals:: How far you can go in learning
262 File: standards.info, Node: GNU Manuals, Next: Manual Structure Details, Up: Documentation
267 The preferred way to document part of the GNU system is to write a
268 manual in the Texinfo formatting language. See the Texinfo manual,
269 either the hardcopy, or the on-line version available through `info' or
270 the Emacs Info subsystem (`C-h i').
272 The manual should document all of the program's command-line options
273 and all of its commands. It should give examples of their use. But
274 don't organize the manual as a list of features. Instead, organize it
275 logically, by subtopics. Address the goals that a user will have in
276 mind, and explain how to accomplish them.
278 In general, a GNU manual should serve both as tutorial and reference.
279 It should be set up for convenient access to each topic through Info,
280 and for reading straight through (appendixes aside). A GNU manual
281 should give a good introduction to a beginner reading through from the
282 start, and should also provide all the details that hackers want.
284 That is not as hard as it first sounds. Arrange each chapter as a
285 logical breakdown of its topic, but order the sections, and write their
286 text, so that reading the chapter straight through makes sense. Do
287 likewise when structuring the book into chapters, and when structuring a
288 section into paragraphs. The watchword is, *at each point, address the
289 most fundamental and important issue raised by the preceding text.*
291 If necessary, add extra chapters at the beginning of the manual which
292 are purely tutorial and cover the basics of the subject. These provide
293 the framework for a beginner to understand the rest of the manual. The
294 Bison manual provides a good example of how to do this.
296 Don't use Unix man pages as a model for how to write GNU
297 documentation; they are a bad example to follow.
299 Please do not use the term "pathname" that is used in Unix
300 documentation; use "file name" (two words) instead. We use the term
301 "path" only for search paths, which are lists of file names.
304 File: standards.info, Node: Manual Structure Details, Next: NEWS File, Prev: GNU Manuals, Up: Documentation
306 Manual Structure Details
307 ========================
309 The title page of the manual should state the version of the program
310 to which the manual applies. The Top node of the manual should also
311 contain this information. If the manual is changing more frequently
312 than or independent of the program, also state a version number for the
313 manual in both of these places.
315 The manual should have a node named `PROGRAM Invocation' or
316 `Invoking PROGRAM', where PROGRAM stands for the name of the program
317 being described, as you would type it in the shell to run the program.
318 This node (together with its subnodes, if any) should describe the
319 program's command line arguments and how to run it (the sort of
320 information people would look in a man page for). Start with an
321 `@example' containing a template for all the options and arguments that
324 Alternatively, put a menu item in some menu whose item name fits one
325 of the above patterns. This identifies the node which that item points
326 to as the node for this purpose, regardless of the node's actual name.
328 There will be automatic features for specifying a program name and
329 quickly reading just this part of its manual.
331 If one manual describes several programs, it should have such a node
332 for each program described.
335 File: standards.info, Node: NEWS File, Next: Change Logs, Prev: Manual Structure Details, Up: Documentation
340 In addition to its manual, the package should have a file named
341 `NEWS' which contains a list of user-visible changes worth mentioning.
342 In each new release, add items to the front of the file and identify
343 the version they pertain to. Don't discard old items; leave them in
344 the file after the newer items. This way, a user upgrading from any
345 previous version can see what is new.
347 If the `NEWS' file gets very long, move some of the older items into
348 a file named `ONEWS' and put a note at the end referring the user to
352 File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation
357 Keep a change log to describe all the changes made to program source
358 files. The purpose of this is so that people investigating bugs in the
359 future will know about the changes that might have introduced the bug.
360 Often a new bug can be found by looking at what was recently changed.
361 More importantly, change logs can help eliminate conceptual
362 inconsistencies between different parts of a program; they can give you
363 a history of how the conflicting concepts arose.
365 A change log file is normally called `ChangeLog' and covers an
366 entire directory. Each directory can have its own change log, or a
367 directory can use the change log of its parent directory-it's up to you.
369 Another alternative is to record change log information with a
370 version control system such as RCS or CVS. This can be converted
371 automatically to a `ChangeLog' file.
373 The easiest way to add an entry to `ChangeLog' is with the Emacs
374 command `M-x add-change-log-entry'. An entry should have an asterisk,
375 the name of the changed file, and then in parentheses the name of the
376 changed functions, variables or whatever, followed by a colon. Then
377 describe the changes you made to that function or variable.
379 Separate unrelated entries with blank lines. When two entries
380 represent parts of the same change, so that they work together, then
381 don't put blank lines between them. Then you can omit the file name
382 and the asterisk when successive entries are in the same file.
384 Here are some examples:
386 * register.el (insert-register): Return nil.
387 (jump-to-register): Likewise.
389 * sort.el (sort-subr): Return nil.
391 * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
392 Restart the tex shell if process is gone or stopped.
393 (tex-shell-running): New function.
395 * expr.c (store_one_arg): Round size up for move_block_to_reg.
396 (expand_call): Round up when emitting USE insns.
397 * stmt.c (assign_parms): Round size up for move_block_from_reg.
399 It's important to name the changed function or variable in full.
400 Don't abbreviate function or variable names, and don't combine them.
401 Subsequent maintainers will often search for a function name to find
402 all the change log entries that pertain to it; if you abbreviate the
403 name, they won't find it when they search. For example, some people
404 are tempted to abbreviate groups of function names by writing `*
405 register.el ({insert,jump-to}-register)'; this is not a good idea,
406 since searching for `jump-to-register' or `insert-register' would not
409 There's no need to describe the full purpose of the changes or how
410 they work together. It is better to put such explanations in comments
411 in the code. That's why just "New function" is enough; there is a
412 comment with the function in the source to explain what it does.
414 However, sometimes it is useful to write one line to describe the
415 overall purpose of a large batch of changes.
417 You can think of the change log as a conceptual "undo list" which
418 explains how earlier versions were different from the current version.
419 People can see the current version; they don't need the change log to
420 tell them what is in it. What they want from a change log is a clear
421 explanation of how the earlier version differed.
423 When you change the calling sequence of a function in a simple
424 fashion, and you change all the callers of the function, there is no
425 need to make individual entries for all the callers. Just write in the
426 entry for the function being called, "All callers changed."
428 When you change just comments or doc strings, it is enough to write
429 an entry for the file, without mentioning the functions. Write just,
432 There's no need to make change log entries for documentation files.
433 This is because documentation is not susceptible to bugs that are hard
434 to fix. Documentation does not consist of parts that must interact in a
435 precisely engineered fashion. To correct an error, you need not know
436 the history of the erroneous passage; it is enough to compare the
437 passage with the way the program actually works.
440 File: standards.info, Node: Man Pages, Next: Reading other Manuals, Prev: Change Logs, Up: Documentation
445 In the GNU project, man pages are secondary. It is not necessary or
446 expected for every GNU program to have a man page, but some of them do.
447 It's your choice whether to include a man page in your program.
449 When you make this decision, consider that supporting a man page
450 requires continual effort each time the program is changed. The time
451 you spend on the man page is time taken away from more useful work.
453 For a simple program which changes little, updating the man page may
454 be a small job. Then there is little reason not to include a man page,
457 For a large program that changes a great deal, updating a man page
458 may be a substantial burden. If a user offers to donate a man page,
459 you may find this gift costly to accept. It may be better to refuse
460 the man page unless the same person agrees to take full responsibility
461 for maintaining it--so that you can wash your hands of it entirely. If
462 this volunteer later ceases to do the job, then don't feel obliged to
463 pick it up yourself; it may be better to withdraw the man page from the
464 distribution until someone else agrees to update it.
466 When a program changes only a little, you may feel that the
467 discrepancies are small enough that the man page remains useful without
468 updating. If so, put a prominent note near the beginning of the man
469 page explaining that you don't maintain it and that the Texinfo manual
470 is more authoritative. The note should say how to access the Texinfo
474 File: standards.info, Node: Reading other Manuals, Prev: Man Pages, Up: Documentation
476 Reading other Manuals
477 =====================
479 There may be non-free books or documentation files that describe the
480 program you are documenting.
482 It is ok to use these documents for reference, just as the author of
483 a new algebra textbook can read other books on algebra. A large portion
484 of any non-fiction book consists of facts, in this case facts about how
485 a certain program works, and these facts are necessarily the same for
486 everyone who writes about the subject. But be careful not to copy your
487 outline structure, wording, tables or examples from preexisting non-free
488 documentation. Copying from free documentation may be ok; please check
489 with the FSF about the individual case.
492 File: standards.info, Node: Managing Releases, Prev: Documentation, Up: Top
497 Making a release is more than just bundling up your source files in a
498 tar file and putting it up for FTP. You should set up your software so
499 that it can be configured to run on a variety of systems. Your Makefile
500 should conform to the GNU standards described below, and your directory
501 layout should also conform to the standards discussed below. Doing so
502 makes it easy to include your package into the larger framework of all
507 * Configuration:: How Configuration Should Work
508 * Makefile Conventions:: Makefile Conventions
509 * Releases:: Making Releases
512 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
514 How Configuration Should Work
515 =============================
517 Each GNU distribution should come with a shell script named
518 `configure'. This script is given arguments which describe the kind of
519 machine and system you want to compile the program for.
521 The `configure' script must record the configuration options so that
522 they affect compilation.
524 One way to do this is to make a link from a standard name such as
525 `config.h' to the proper configuration file for the chosen system. If
526 you use this technique, the distribution should *not* contain a file
527 named `config.h'. This is so that people won't be able to build the
528 program without configuring it first.
530 Another thing that `configure' can do is to edit the Makefile. If
531 you do this, the distribution should *not* contain a file named
532 `Makefile'. Instead, it should include a file `Makefile.in' which
533 contains the input used for editing. Once again, this is so that people
534 won't be able to build the program without configuring it first.
536 If `configure' does write the `Makefile', then `Makefile' should
537 have a target named `Makefile' which causes `configure' to be rerun,
538 setting up the same configuration that was set up last time. The files
539 that `configure' reads should be listed as dependencies of `Makefile'.
541 All the files which are output from the `configure' script should
542 have comments at the beginning explaining that they were generated
543 automatically using `configure'. This is so that users won't think of
544 trying to edit them by hand.
546 The `configure' script should write a file named `config.status'
547 which describes which configuration options were specified when the
548 program was last configured. This file should be a shell script which,
549 if run, will recreate the same configuration.
551 The `configure' script should accept an option of the form
552 `--srcdir=DIRNAME' to specify the directory where sources are found (if
553 it is not the current directory). This makes it possible to build the
554 program in a separate directory, so that the actual source directory is
557 If the user does not specify `--srcdir', then `configure' should
558 check both `.' and `..' to see if it can find the sources. If it finds
559 the sources in one of these places, it should use them from there.
560 Otherwise, it should report that it cannot find the sources, and should
561 exit with nonzero status.
563 Usually the easy way to support `--srcdir' is by editing a
564 definition of `VPATH' into the Makefile. Some rules may need to refer
565 explicitly to the specified source directory. To make this possible,
566 `configure' can add to the Makefile a variable named `srcdir' whose
567 value is precisely the specified directory.
569 The `configure' script should also take an argument which specifies
570 the type of system to build the program for. This argument should look
575 For example, a Sun 3 might be `m68k-sun-sunos4.1'.
577 The `configure' script needs to be able to decode all plausible
578 alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
579 would be a valid alias. For many programs, `vax-dec-ultrix' would be
580 an alias for `vax-dec-bsd', simply because the differences between
581 Ultrix and BSD are rarely noticeable, but a few programs might need to
584 There is a shell script called `config.sub' that you can use as a
585 subroutine to validate system types and canonicalize aliases.
587 Other options are permitted to specify in more detail the software
588 or hardware present on the machine, and include or exclude optional
589 parts of the package:
591 `--enable-FEATURE[=PARAMETER]'
592 Configure the package to build and install an optional user-level
593 facility called FEATURE. This allows users to choose which
594 optional features to include. Giving an optional PARAMETER of
595 `no' should omit FEATURE, if it is built by default.
597 No `--enable' option should *ever* cause one feature to replace
598 another. No `--enable' option should ever substitute one useful
599 behavior for another useful behavior. The only proper use for
600 `--enable' is for questions of whether to build part of the program
604 The package PACKAGE will be installed, so configure this package
605 to work with PACKAGE.
607 Possible values of PACKAGE include `x', `x-toolkit', `gnu-as' (or
608 `gas'), `gnu-ld', `gnu-libc', and `gdb'.
610 Do not use a `--with' option to specify the file name to use to
611 find certain files. That is outside the scope of what `--with'
615 The target machine has no floating point processor.
618 The target machine assembler is GAS, the GNU assembler. This is
619 obsolete; users should use `--with-gnu-as' instead.
622 The target machine has the X Window System installed. This is
623 obsolete; users should use `--with-x' instead.
625 All `configure' scripts should accept all of these "detail" options,
626 whether or not they make any difference to the particular package at
627 hand. In particular, they should accept any option that starts with
628 `--with-' or `--enable-'. This is so users will be able to configure
629 an entire GNU source tree at once with a single set of options.
631 You will note that the categories `--with-' and `--enable-' are
632 narrow: they *do not* provide a place for any sort of option you might
633 think of. That is deliberate. We want to limit the possible
634 configuration options in GNU software. We do not want GNU programs to
635 have idiosyncratic configuration options.
637 Packages that perform part of the compilation process may support
638 cross-compilation. In such a case, the host and target machines for
639 the program may be different. The `configure' script should normally
640 treat the specified type of system as both the host and the target,
641 thus producing a program which works for the same type of machine that
644 The way to build a cross-compiler, cross-assembler, or what have
645 you, is to specify the option `--host=HOSTTYPE' when running
646 `configure'. This specifies the host system without changing the type
647 of target system. The syntax for HOSTTYPE is the same as described
650 Bootstrapping a cross-compiler requires compiling it on a machine
651 other than the host it will run on. Compilation packages accept a
652 configuration option `--build=HOSTTYPE' for specifying the
653 configuration on which you will compile them, in case that is different
656 Programs for which cross-operation is not meaningful need not accept
657 the `--host' option, because configuring an entire operating system for
658 cross-operation is not a meaningful thing.
660 Some programs have ways of configuring themselves automatically. If
661 your program is set up to do this, your `configure' script can simply
662 ignore most of its arguments.
665 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
670 This node describes conventions for writing the Makefiles for GNU
675 * Makefile Basics:: General Conventions for Makefiles
676 * Utilities in Makefiles:: Utilities in Makefiles
677 * Command Variables:: Variables for Specifying Commands
678 * Directory Variables:: Variables for Installation Directories
679 * Standard Targets:: Standard Targets for Users
682 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
684 General Conventions for Makefiles
685 ---------------------------------
687 Every Makefile should contain this line:
691 to avoid trouble on systems where the `SHELL' variable might be
692 inherited from the environment. (This is never a problem with GNU
695 Different `make' programs have incompatible suffix lists and
696 implicit rules, and this sometimes creates confusion or misbehavior. So
697 it is a good idea to set the suffix list explicitly using only the
698 suffixes you need in the particular Makefile, like this:
703 The first line clears out the suffix list, the second introduces all
704 suffixes which may be subject to implicit rules in this Makefile.
706 Don't assume that `.' is in the path for command execution. When
707 you need to run programs that are a part of your package during the
708 make, please make sure that it uses `./' if the program is built as
709 part of the make or `$(srcdir)/' if the file is an unchanging part of
710 the source code. Without one of these prefixes, the current search
713 The distinction between `./' and `$(srcdir)/' is important when
714 using the `--srcdir' option to `configure'. A rule of the form:
716 foo.1 : foo.man sedscript
717 sed -e sedscript foo.man > foo.1
719 will fail when the current directory is not the source directory,
720 because `foo.man' and `sedscript' are not in the current directory.
722 When using GNU `make', relying on `VPATH' to find the source file
723 will work in the case where there is a single dependency file, since
724 the `make' automatic variable `$<' will represent the source file
725 wherever it is. (Many versions of `make' set `$<' only in implicit
726 rules.) A Makefile target like
729 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
731 should instead be written as
734 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
736 in order to allow `VPATH' to work correctly. When the target has
737 multiple dependencies, using an explicit `$(srcdir)' is the easiest way
738 to make the rule work well. For example, the target above for `foo.1'
741 foo.1 : foo.man sedscript
742 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
744 Try to make the build and installation targets, at least (and all
745 their subtargets) work correctly with a parallel `make'.
748 File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
750 Utilities in Makefiles
751 ----------------------
753 Write the Makefile commands (and any shell scripts, such as
754 `configure') to run in `sh', not in `csh'. Don't use any special
755 features of `ksh' or `bash'.
757 The `configure' script and the Makefile rules for building and
758 installation should not use any utilities directly except these:
760 cat cmp cp echo egrep expr false grep
761 ln mkdir mv pwd rm rmdir sed test touch true
763 Stick to the generally supported options for these programs. For
764 example, don't use `mkdir -p', convenient as it may be, because most
765 systems don't support it.
767 It is a good idea to avoid creating symbolic links in makefiles,
768 since a few systems don't support them.
770 The Makefile rules for building and installation can also use
771 compilers and related programs, but should do so via `make' variables
772 so that the user can substitute alternatives. Here are some of the
775 ar bison cc flex install ld lex
776 make makeinfo ranlib texi2dvi yacc
778 Use the following `make' variables:
780 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
781 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
783 When you use `ranlib', you should make sure nothing bad happens if
784 the system does not have `ranlib'. Arrange to ignore an error from
785 that command, and print a message before the command to tell the user
786 that failure of the `ranlib' command does not mean a problem. (The
787 Autoconf `AC_PROG_RANLIB' macro can help with this.)
789 If you use symbolic links, you should implement a fallback for
790 systems that don't have symbolic links.
792 It is ok to use other utilities in Makefile portions (or scripts)
793 intended only for particular systems where you know those utilities
797 File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
799 Variables for Specifying Commands
800 ---------------------------------
802 Makefiles should provide variables for overriding certain commands,
805 In particular, you should run most utility programs via variables.
806 Thus, if you use Bison, have a variable named `BISON' whose default
807 value is set with `BISON = bison', and refer to it with `$(BISON)'
808 whenever you need to use Bison.
810 File management utilities such as `ln', `rm', `mv', and so on, need
811 not be referred to through variables in this way, since users don't
812 need to replace them with other programs.
814 Each program-name variable should come with an options variable that
815 is used to supply options to the program. Append `FLAGS' to the
816 program-name variable name to get the options variable name--for
817 example, `BISONFLAGS'. (The name `CFLAGS' is an exception to this
818 rule, but we keep it because it is standard.) Use `CPPFLAGS' in any
819 compilation command that runs the preprocessor, and use `LDFLAGS' in
820 any compilation command that does linking as well as in any direct use
823 If there are C compiler options that *must* be used for proper
824 compilation of certain files, do not include them in `CFLAGS'. Users
825 expect to be able to specify `CFLAGS' freely themselves. Instead,
826 arrange to pass the necessary options to the C compiler independently
827 of `CFLAGS', by writing them explicitly in the compilation commands or
828 by defining an implicit rule, like this:
831 ALL_CFLAGS = -I. $(CFLAGS)
833 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
835 Do include the `-g' option in `CFLAGS', because that is not
836 *required* for proper compilation. You can consider it a default that
837 is only recommended. If the package is set up so that it is compiled
838 with GCC by default, then you might as well include `-O' in the default
839 value of `CFLAGS' as well.
841 Put `CFLAGS' last in the compilation command, after other variables
842 containing compiler options, so the user can use `CFLAGS' to override
845 Every Makefile should define the variable `INSTALL', which is the
846 basic command for installing a file into the system.
848 Every Makefile should also define the variables `INSTALL_PROGRAM'
849 and `INSTALL_DATA'. (The default for each of these should be
850 `$(INSTALL)'.) Then it should use those variables as the commands for
851 actual installation, for executables and nonexecutables respectively.
852 Use these variables as follows:
854 $(INSTALL_PROGRAM) foo $(bindir)/foo
855 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
857 Always use a file name, not a directory name, as the second argument of
858 the installation commands. Use a separate command for each file to be
862 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
864 Variables for Installation Directories
865 --------------------------------------
867 Installation directories should always be named by variables, so it
868 is easy to install in a nonstandard place. The standard names for these
869 variables are described below. They are based on a standard filesystem
870 layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
871 other modern operating systems.
873 These two variables set the root for the installation. All the other
874 installation directories should be subdirectories of one of these two,
875 and nothing should be directly installed into these two directories.
878 A prefix used in constructing the default values of the variables
879 listed below. The default value of `prefix' should be
880 `/usr/local'. When building the complete GNU system, the prefix
881 will be empty and `/usr' will be a symbolic link to `/'. (If you
882 are using Autoconf, write it as `@prefix@'.)
885 A prefix used in constructing the default values of some of the
886 variables listed below. The default value of `exec_prefix' should
887 be `$(prefix)'. (If you are using Autoconf, write it as
890 Generally, `$(exec_prefix)' is used for directories that contain
891 machine-specific files (such as executables and subroutine
892 libraries), while `$(prefix)' is used directly for other
895 Executable programs are installed in one of the following
899 The directory for installing executable programs that users can
900 run. This should normally be `/usr/local/bin', but write it as
901 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
905 The directory for installing executable programs that can be run
906 from the shell, but are only generally useful to system
907 administrators. This should normally be `/usr/local/sbin', but
908 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
909 write it as `@sbindir@'.)
912 The directory for installing executable programs to be run by other
913 programs rather than by users. This directory should normally be
914 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
915 (If you are using Autoconf, write it as `@libexecdir@'.)
917 Data files used by the program during its execution are divided into
918 categories in two ways.
920 * Some files are normally modified by programs; others are never
921 normally modified (though users may edit some of these).
923 * Some files are architecture-independent and can be shared by all
924 machines at a site; some are architecture-dependent and can be
925 shared only by machines of the same kind and operating system;
926 others may never be shared between two machines.
928 This makes for six different possibilities. However, we want to
929 discourage the use of architecture-dependent files, aside from object
930 files and libraries. It is much cleaner to make other data files
931 architecture-independent, and it is generally not hard.
933 Therefore, here are the variables Makefiles should use to specify
937 The directory for installing read-only architecture independent
938 data files. This should normally be `/usr/local/share', but write
939 it as `$(prefix)/share'. (If you are using Autoconf, write it as
940 `@datadir@'.) As a special exception, see `$(infodir)' and
941 `$(includedir)' below.
944 The directory for installing read-only data files that pertain to a
945 single machine-that is to say, files for configuring a host.
946 Mailer and network configuration files, `/etc/passwd', and so
947 forth belong here. All the files in this directory should be
948 ordinary ASCII text files. This directory should normally be
949 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
950 using Autoconf, write it as `@sysconfdir@'.)
952 Do not install executables in this directory (they probably belong
953 in `$(libexecdir)' or `$(sbindir)'). Also do not install files
954 that are modified in the normal course of their use (programs
955 whose purpose is to change the configuration of the system
956 excluded). Those probably belong in `$(localstatedir)'.
959 The directory for installing architecture-independent data files
960 which the programs modify while they run. This should normally be
961 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
962 using Autoconf, write it as `@sharedstatedir@'.)
965 The directory for installing data files which the programs modify
966 while they run, and that pertain to one specific machine. Users
967 should never need to modify files in this directory to configure
968 the package's operation; put such configuration information in
969 separate files that go in `$(datadir)' or `$(sysconfdir)'.
970 `$(localstatedir)' should normally be `/usr/local/var', but write
971 it as `$(prefix)/var'. (If you are using Autoconf, write it as
975 The directory for object files and libraries of object code. Do
976 not install executables here, they probably ought to go in
977 `$(libexecdir)' instead. The value of `libdir' should normally be
978 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
979 are using Autoconf, write it as `@libdir@'.)
982 The directory for installing the Info files for this package. By
983 default, it should be `/usr/local/info', but it should be written
984 as `$(prefix)/info'. (If you are using Autoconf, write it as
988 The directory for installing header files to be included by user
989 programs with the C `#include' preprocessor directive. This
990 should normally be `/usr/local/include', but write it as
991 `$(prefix)/include'. (If you are using Autoconf, write it as
994 Most compilers other than GCC do not look for header files in
995 `/usr/local/include'. So installing the header files this way is
996 only useful with GCC. Sometimes this is not a problem because some
997 libraries are only really intended to work with GCC. But some
998 libraries are intended to work with other compilers. They should
999 install their header files in two places, one specified by
1000 `includedir' and one specified by `oldincludedir'.
1003 The directory for installing `#include' header files for use with
1004 compilers other than GCC. This should normally be `/usr/include'.
1005 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
1007 The Makefile commands should check whether the value of
1008 `oldincludedir' is empty. If it is, they should not try to use
1009 it; they should cancel the second installation of the header files.
1011 A package should not replace an existing header in this directory
1012 unless the header came from the same package. Thus, if your Foo
1013 package provides a header file `foo.h', then it should install the
1014 header file in the `oldincludedir' directory if either (1) there
1015 is no `foo.h' there or (2) the `foo.h' that exists came from the
1018 To tell whether `foo.h' came from the Foo package, put a magic
1019 string in the file--part of a comment--and `grep' for that string.
1021 Unix-style man pages are installed in one of the following:
1024 The top-level directory for installing the man pages (if any) for
1025 this package. It will normally be `/usr/local/man', but you should
1026 write it as `$(prefix)/man'. (If you are using Autoconf, write it
1030 The directory for installing section 1 man pages. Write it as
1034 The directory for installing section 2 man pages. Write it as
1038 *Don't make the primary documentation for any GNU software be a
1039 man page. Write a manual in Texinfo instead. Man pages are just
1040 for the sake of people running GNU software on Unix, which is a
1041 secondary application only.*
1044 The file name extension for the installed man page. This should
1045 contain a period followed by the appropriate digit; it should
1049 The file name extension for installed section 1 man pages.
1052 The file name extension for installed section 2 man pages.
1055 Use these names instead of `manext' if the package needs to
1056 install man pages in more than one section of the manual.
1058 And finally, you should set the following variable:
1061 The directory for the sources being compiled. The value of this
1062 variable is normally inserted by the `configure' shell script.
1063 (If you are using Autconf, use `srcdir = @srcdir@'.)
1067 # Common prefix for installation directories.
1068 # NOTE: This directory must exist when you start the install.
1070 exec_prefix = $(prefix)
1071 # Where to put the executable for the command `gcc'.
1072 bindir = $(exec_prefix)/bin
1073 # Where to put the directories used by the compiler.
1074 libexecdir = $(exec_prefix)/libexec
1075 # Where to put the Info files.
1076 infodir = $(prefix)/info
1078 If your program installs a large number of files into one of the
1079 standard user-specified directories, it might be useful to group them
1080 into a subdirectory particular to that program. If you do this, you
1081 should write the `install' rule to create these subdirectories.
1083 Do not expect the user to include the subdirectory name in the value
1084 of any of the variables listed above. The idea of having a uniform set
1085 of variable names for installation directories is to enable the user to
1086 specify the exact same values for several different GNU packages. In
1087 order for this to be useful, all the packages must be designed so that
1088 they will work sensibly when the user does so.
projects / chise / xemacs-chise.git.1 / blob