1 This is ../info/standards.info, produced by makeinfo version 4.0 from
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999, 2000 Free 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: Managing Releases, Next: References, Prev: Documentation, Up: Top
31 Making a release is more than just bundling up your source files in a
32 tar file and putting it up for FTP. You should set up your software so
33 that it can be configured to run on a variety of systems. Your Makefile
34 should conform to the GNU standards described below, and your directory
35 layout should also conform to the standards discussed below. Doing so
36 makes it easy to include your package into the larger framework of all
41 * Configuration:: How Configuration Should Work
42 * Makefile Conventions:: Makefile Conventions
43 * Releases:: Making Releases
46 File: standards.info, Node: Configuration, Next: Makefile Conventions, Up: Managing Releases
48 How Configuration Should Work
49 =============================
51 Each GNU distribution should come with a shell script named
52 `configure'. This script is given arguments which describe the kind of
53 machine and system you want to compile the program for.
55 The `configure' script must record the configuration options so that
56 they affect compilation.
58 One way to do this is to make a link from a standard name such as
59 `config.h' to the proper configuration file for the chosen system. If
60 you use this technique, the distribution should _not_ contain a file
61 named `config.h'. This is so that people won't be able to build the
62 program without configuring it first.
64 Another thing that `configure' can do is to edit the Makefile. If
65 you do this, the distribution should _not_ contain a file named
66 `Makefile'. Instead, it should include a file `Makefile.in' which
67 contains the input used for editing. Once again, this is so that people
68 won't be able to build the program without configuring it first.
70 If `configure' does write the `Makefile', then `Makefile' should
71 have a target named `Makefile' which causes `configure' to be rerun,
72 setting up the same configuration that was set up last time. The files
73 that `configure' reads should be listed as dependencies of `Makefile'.
75 All the files which are output from the `configure' script should
76 have comments at the beginning explaining that they were generated
77 automatically using `configure'. This is so that users won't think of
78 trying to edit them by hand.
80 The `configure' script should write a file named `config.status'
81 which describes which configuration options were specified when the
82 program was last configured. This file should be a shell script which,
83 if run, will recreate the same configuration.
85 The `configure' script should accept an option of the form
86 `--srcdir=DIRNAME' to specify the directory where sources are found (if
87 it is not the current directory). This makes it possible to build the
88 program in a separate directory, so that the actual source directory is
91 If the user does not specify `--srcdir', then `configure' should
92 check both `.' and `..' to see if it can find the sources. If it finds
93 the sources in one of these places, it should use them from there.
94 Otherwise, it should report that it cannot find the sources, and should
95 exit with nonzero status.
97 Usually the easy way to support `--srcdir' is by editing a
98 definition of `VPATH' into the Makefile. Some rules may need to refer
99 explicitly to the specified source directory. To make this possible,
100 `configure' can add to the Makefile a variable named `srcdir' whose
101 value is precisely the specified directory.
103 The `configure' script should also take an argument which specifies
104 the type of system to build the program for. This argument should look
109 For example, a Sun 3 might be `m68k-sun-sunos4.1'.
111 The `configure' script needs to be able to decode all plausible
112 alternatives for how to describe a machine. Thus, `sun3-sunos4.1'
113 would be a valid alias. For many programs, `vax-dec-ultrix' would be
114 an alias for `vax-dec-bsd', simply because the differences between
115 Ultrix and BSD are rarely noticeable, but a few programs might need to
118 There is a shell script called `config.sub' that you can use as a
119 subroutine to validate system types and canonicalize aliases.
121 Other options are permitted to specify in more detail the software
122 or hardware present on the machine, and include or exclude optional
123 parts of the package:
125 `--enable-FEATURE[=PARAMETER]'
126 Configure the package to build and install an optional user-level
127 facility called FEATURE. This allows users to choose which
128 optional features to include. Giving an optional PARAMETER of
129 `no' should omit FEATURE, if it is built by default.
131 No `--enable' option should *ever* cause one feature to replace
132 another. No `--enable' option should ever substitute one useful
133 behavior for another useful behavior. The only proper use for
134 `--enable' is for questions of whether to build part of the program
138 The package PACKAGE will be installed, so configure this package
139 to work with PACKAGE.
141 Possible values of PACKAGE include `gnu-as' (or `gas'), `gnu-ld',
142 `gnu-libc', `gdb', `x', and `x-toolkit'.
144 Do not use a `--with' option to specify the file name to use to
145 find certain files. That is outside the scope of what `--with'
148 All `configure' scripts should accept all of these "detail" options,
149 whether or not they make any difference to the particular package at
150 hand. In particular, they should accept any option that starts with
151 `--with-' or `--enable-'. This is so users will be able to configure
152 an entire GNU source tree at once with a single set of options.
154 You will note that the categories `--with-' and `--enable-' are
155 narrow: they *do not* provide a place for any sort of option you might
156 think of. That is deliberate. We want to limit the possible
157 configuration options in GNU software. We do not want GNU programs to
158 have idiosyncratic configuration options.
160 Packages that perform part of the compilation process may support
161 cross-compilation. In such a case, the host and target machines for the
162 program may be different.
164 The `configure' script should normally treat the specified type of
165 system as both the host and the target, thus producing a program which
166 works for the same type of machine that it runs on.
168 To configure a cross-compiler, cross-assembler, or what have you, you
169 should specify a target different from the host, using the configure
170 option `--target=TARGETTYPE'. The syntax for TARGETTYPE is the same as
171 for the host type. So the command would look like this:
173 ./configure HOSTTYPE --target=TARGETTYPE
175 Programs for which cross-operation is not meaningful need not accept
176 the `--target' option, because configuring an entire operating system
177 for cross-operation is not a meaningful operation.
179 Bootstrapping a cross-compiler requires compiling it on a machine
180 other than the host it will run on. Compilation packages accept a
181 configuration option `--build=BUILDTYPE' for specifying the
182 configuration on which you will compile them, but the configure script
183 should normally guess the build machine type (using `config.guess'), so
184 this option is probably not necessary. The host and target types
185 normally default from the build type, so in bootstrapping a
186 cross-compiler you must specify them both explicitly.
188 Some programs have ways of configuring themselves automatically. If
189 your program is set up to do this, your `configure' script can simply
190 ignore most of its arguments.
193 File: standards.info, Node: Makefile Conventions, Next: Releases, Prev: Configuration, Up: Managing Releases
198 This node describes conventions for writing the Makefiles for GNU
199 programs. Using Automake will help you write a Makefile that follows
204 * Makefile Basics:: General Conventions for Makefiles
205 * Utilities in Makefiles:: Utilities in Makefiles
206 * Command Variables:: Variables for Specifying Commands
207 * Directory Variables:: Variables for Installation Directories
208 * Standard Targets:: Standard Targets for Users
209 * Install Command Categories:: Three categories of commands in the `install'
210 rule: normal, pre-install and post-install.
213 File: standards.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
215 General Conventions for Makefiles
216 ---------------------------------
218 Every Makefile should contain this line:
222 to avoid trouble on systems where the `SHELL' variable might be
223 inherited from the environment. (This is never a problem with GNU
226 Different `make' programs have incompatible suffix lists and
227 implicit rules, and this sometimes creates confusion or misbehavior. So
228 it is a good idea to set the suffix list explicitly using only the
229 suffixes you need in the particular Makefile, like this:
234 The first line clears out the suffix list, the second introduces all
235 suffixes which may be subject to implicit rules in this Makefile.
237 Don't assume that `.' is in the path for command execution. When
238 you need to run programs that are a part of your package during the
239 make, please make sure that it uses `./' if the program is built as
240 part of the make or `$(srcdir)/' if the file is an unchanging part of
241 the source code. Without one of these prefixes, the current search
244 The distinction between `./' (the "build directory") and
245 `$(srcdir)/' (the "source directory") is important because users can
246 build in a separate directory using the `--srcdir' option to
247 `configure'. A rule of the form:
249 foo.1 : foo.man sedscript
250 sed -e sedscript foo.man > foo.1
252 will fail when the build directory is not the source directory, because
253 `foo.man' and `sedscript' are in the source directory.
255 When using GNU `make', relying on `VPATH' to find the source file
256 will work in the case where there is a single dependency file, since
257 the `make' automatic variable `$<' will represent the source file
258 wherever it is. (Many versions of `make' set `$<' only in implicit
259 rules.) A Makefile target like
262 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
264 should instead be written as
267 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
269 in order to allow `VPATH' to work correctly. When the target has
270 multiple dependencies, using an explicit `$(srcdir)' is the easiest way
271 to make the rule work well. For example, the target above for `foo.1'
274 foo.1 : foo.man sedscript
275 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
277 GNU distributions usually contain some files which are not source
278 files--for example, Info files, and the output from Autoconf, Automake,
279 Bison or Flex. Since these files normally appear in the source
280 directory, they should always appear in the source directory, not in the
281 build directory. So Makefile rules to update them should put the
282 updated files in the source directory.
284 However, if a file does not appear in the distribution, then the
285 Makefile should not put it in the source directory, because building a
286 program in ordinary circumstances should not modify the source directory
289 Try to make the build and installation targets, at least (and all
290 their subtargets) work correctly with a parallel `make'.
293 File: standards.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
295 Utilities in Makefiles
296 ----------------------
298 Write the Makefile commands (and any shell scripts, such as
299 `configure') to run in `sh', not in `csh'. Don't use any special
300 features of `ksh' or `bash'.
302 The `configure' script and the Makefile rules for building and
303 installation should not use any utilities directly except these:
305 cat cmp cp diff echo egrep expr false grep install-info
306 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
308 The compression program `gzip' can be used in the `dist' rule.
310 Stick to the generally supported options for these programs. For
311 example, don't use `mkdir -p', convenient as it may be, because most
312 systems don't support it.
314 It is a good idea to avoid creating symbolic links in makefiles,
315 since a few systems don't support them.
317 The Makefile rules for building and installation can also use
318 compilers and related programs, but should do so via `make' variables
319 so that the user can substitute alternatives. Here are some of the
322 ar bison cc flex install ld ldconfig lex
323 make makeinfo ranlib texi2dvi yacc
325 Use the following `make' variables to run those programs:
327 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
328 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
330 When you use `ranlib' or `ldconfig', you should make sure nothing
331 bad happens if the system does not have the program in question.
332 Arrange to ignore an error from that command, and print a message before
333 the command to tell the user that failure of this command does not mean
334 a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
336 If you use symbolic links, you should implement a fallback for
337 systems that don't have symbolic links.
339 Additional utilities that can be used via Make variables are:
341 chgrp chmod chown mknod
343 It is ok to use other utilities in Makefile portions (or scripts)
344 intended only for particular systems where you know those utilities
348 File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
350 Variables for Specifying Commands
351 ---------------------------------
353 Makefiles should provide variables for overriding certain commands,
356 In particular, you should run most utility programs via variables.
357 Thus, if you use Bison, have a variable named `BISON' whose default
358 value is set with `BISON = bison', and refer to it with `$(BISON)'
359 whenever you need to use Bison.
361 File management utilities such as `ln', `rm', `mv', and so on, need
362 not be referred to through variables in this way, since users don't
363 need to replace them with other programs.
365 Each program-name variable should come with an options variable that
366 is used to supply options to the program. Append `FLAGS' to the
367 program-name variable name to get the options variable name--for
368 example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
369 `YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
370 but we keep them because they are standard.) Use `CPPFLAGS' in any
371 compilation command that runs the preprocessor, and use `LDFLAGS' in
372 any compilation command that does linking as well as in any direct use
375 If there are C compiler options that _must_ be used for proper
376 compilation of certain files, do not include them in `CFLAGS'. Users
377 expect to be able to specify `CFLAGS' freely themselves. Instead,
378 arrange to pass the necessary options to the C compiler independently
379 of `CFLAGS', by writing them explicitly in the compilation commands or
380 by defining an implicit rule, like this:
383 ALL_CFLAGS = -I. $(CFLAGS)
385 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
387 Do include the `-g' option in `CFLAGS', because that is not
388 _required_ for proper compilation. You can consider it a default that
389 is only recommended. If the package is set up so that it is compiled
390 with GCC by default, then you might as well include `-O' in the default
391 value of `CFLAGS' as well.
393 Put `CFLAGS' last in the compilation command, after other variables
394 containing compiler options, so the user can use `CFLAGS' to override
397 `CFLAGS' should be used in every invocation of the C compiler, both
398 those which do compilation and those which do linking.
400 Every Makefile should define the variable `INSTALL', which is the
401 basic command for installing a file into the system.
403 Every Makefile should also define the variables `INSTALL_PROGRAM'
404 and `INSTALL_DATA'. (The default for `INSTALL_PROGRAM' should be
405 `$(INSTALL)'; the default for `INSTALL_DATA' should be `${INSTALL} -m
406 644'.) Then it should use those variables as the commands for actual
407 installation, for executables and nonexecutables respectively. Use
408 these variables as follows:
410 $(INSTALL_PROGRAM) foo $(bindir)/foo
411 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
413 Optionally, you may prepend the value of `DESTDIR' to the target
414 filename. Doing this allows the installer to create a snapshot of the
415 installation to be copied onto the real target filesystem later. Do not
416 set the value of `DESTDIR' in your Makefile, and do not include it in
417 any installed files. With support for `DESTDIR', the above examples
420 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
421 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
423 Always use a file name, not a directory name, as the second argument of
424 the installation commands. Use a separate command for each file to be
428 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
430 Variables for Installation Directories
431 --------------------------------------
433 Installation directories should always be named by variables, so it
434 is easy to install in a nonstandard place. The standard names for these
435 variables are described below. They are based on a standard filesystem
436 layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
437 and other modern operating systems.
439 These two variables set the root for the installation. All the other
440 installation directories should be subdirectories of one of these two,
441 and nothing should be directly installed into these two directories.
444 A prefix used in constructing the default values of the variables
445 listed below. The default value of `prefix' should be
446 `/usr/local'. When building the complete GNU system, the prefix
447 will be empty and `/usr' will be a symbolic link to `/'. (If you
448 are using Autoconf, write it as `@prefix@'.)
450 Running `make install' with a different value of `prefix' from the
451 one used to build the program should _not_ recompile the program.
454 A prefix used in constructing the default values of some of the
455 variables listed below. The default value of `exec_prefix' should
456 be `$(prefix)'. (If you are using Autoconf, write it as
459 Generally, `$(exec_prefix)' is used for directories that contain
460 machine-specific files (such as executables and subroutine
461 libraries), while `$(prefix)' is used directly for other
464 Running `make install' with a different value of `exec_prefix'
465 from the one used to build the program should _not_ recompile the
468 Executable programs are installed in one of the following
472 The directory for installing executable programs that users can
473 run. This should normally be `/usr/local/bin', but write it as
474 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
478 The directory for installing executable programs that can be run
479 from the shell, but are only generally useful to system
480 administrators. This should normally be `/usr/local/sbin', but
481 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
482 write it as `@sbindir@'.)
485 The directory for installing executable programs to be run by other
486 programs rather than by users. This directory should normally be
487 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
488 (If you are using Autoconf, write it as `@libexecdir@'.)
490 Data files used by the program during its execution are divided into
491 categories in two ways.
493 * Some files are normally modified by programs; others are never
494 normally modified (though users may edit some of these).
496 * Some files are architecture-independent and can be shared by all
497 machines at a site; some are architecture-dependent and can be
498 shared only by machines of the same kind and operating system;
499 others may never be shared between two machines.
501 This makes for six different possibilities. However, we want to
502 discourage the use of architecture-dependent files, aside from object
503 files and libraries. It is much cleaner to make other data files
504 architecture-independent, and it is generally not hard.
506 Therefore, here are the variables Makefiles should use to specify
510 The directory for installing read-only architecture independent
511 data files. This should normally be `/usr/local/share', but write
512 it as `$(prefix)/share'. (If you are using Autoconf, write it as
513 `@datadir@'.) As a special exception, see `$(infodir)' and
514 `$(includedir)' below.
517 The directory for installing read-only data files that pertain to a
518 single machine-that is to say, files for configuring a host.
519 Mailer and network configuration files, `/etc/passwd', and so
520 forth belong here. All the files in this directory should be
521 ordinary ASCII text files. This directory should normally be
522 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
523 using Autoconf, write it as `@sysconfdir@'.)
525 Do not install executables here in this directory (they probably
526 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
527 files that are modified in the normal course of their use (programs
528 whose purpose is to change the configuration of the system
529 excluded). Those probably belong in `$(localstatedir)'.
532 The directory for installing architecture-independent data files
533 which the programs modify while they run. This should normally be
534 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
535 using Autoconf, write it as `@sharedstatedir@'.)
538 The directory for installing data files which the programs modify
539 while they run, and that pertain to one specific machine. Users
540 should never need to modify files in this directory to configure
541 the package's operation; put such configuration information in
542 separate files that go in `$(datadir)' or `$(sysconfdir)'.
543 `$(localstatedir)' should normally be `/usr/local/var', but write
544 it as `$(prefix)/var'. (If you are using Autoconf, write it as
548 The directory for object files and libraries of object code. Do
549 not install executables here, they probably ought to go in
550 `$(libexecdir)' instead. The value of `libdir' should normally be
551 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
552 are using Autoconf, write it as `@libdir@'.)
555 The directory for installing the Info files for this package. By
556 default, it should be `/usr/local/info', but it should be written
557 as `$(prefix)/info'. (If you are using Autoconf, write it as
561 The directory for installing any Emacs Lisp files in this package.
562 By default, it should be `/usr/local/share/emacs/site-lisp', but
563 it should be written as `$(prefix)/share/emacs/site-lisp'.
565 If you are using Autoconf, write the default as `@lispdir@'. In
566 order to make `@lispdir@' work, you need the following lines in
567 your `configure.in' file:
569 lispdir='${datadir}/emacs/site-lisp'
573 The directory for installing header files to be included by user
574 programs with the C `#include' preprocessor directive. This
575 should normally be `/usr/local/include', but write it as
576 `$(prefix)/include'. (If you are using Autoconf, write it as
579 Most compilers other than GCC do not look for header files in
580 directory `/usr/local/include'. So installing the header files
581 this way is only useful with GCC. Sometimes this is not a problem
582 because some libraries are only really intended to work with GCC.
583 But some libraries are intended to work with other compilers.
584 They should install their header files in two places, one
585 specified by `includedir' and one specified by `oldincludedir'.
588 The directory for installing `#include' header files for use with
589 compilers other than GCC. This should normally be `/usr/include'.
590 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
592 The Makefile commands should check whether the value of
593 `oldincludedir' is empty. If it is, they should not try to use
594 it; they should cancel the second installation of the header files.
596 A package should not replace an existing header in this directory
597 unless the header came from the same package. Thus, if your Foo
598 package provides a header file `foo.h', then it should install the
599 header file in the `oldincludedir' directory if either (1) there
600 is no `foo.h' there or (2) the `foo.h' that exists came from the
603 To tell whether `foo.h' came from the Foo package, put a magic
604 string in the file--part of a comment--and `grep' for that string.
606 Unix-style man pages are installed in one of the following:
609 The top-level directory for installing the man pages (if any) for
610 this package. It will normally be `/usr/local/man', but you should
611 write it as `$(prefix)/man'. (If you are using Autoconf, write it
615 The directory for installing section 1 man pages. Write it as
619 The directory for installing section 2 man pages. Write it as
623 *Don't make the primary documentation for any GNU software be a
624 man page. Write a manual in Texinfo instead. Man pages are just
625 for the sake of people running GNU software on Unix, which is a
626 secondary application only.*
629 The file name extension for the installed man page. This should
630 contain a period followed by the appropriate digit; it should
634 The file name extension for installed section 1 man pages.
637 The file name extension for installed section 2 man pages.
640 Use these names instead of `manext' if the package needs to
641 install man pages in more than one section of the manual.
643 And finally, you should set the following variable:
646 The directory for the sources being compiled. The value of this
647 variable is normally inserted by the `configure' shell script.
648 (If you are using Autconf, use `srcdir = @srcdir@'.)
652 # Common prefix for installation directories.
653 # NOTE: This directory must exist when you start the install.
655 exec_prefix = $(prefix)
656 # Where to put the executable for the command `gcc'.
657 bindir = $(exec_prefix)/bin
658 # Where to put the directories used by the compiler.
659 libexecdir = $(exec_prefix)/libexec
660 # Where to put the Info files.
661 infodir = $(prefix)/info
663 If your program installs a large number of files into one of the
664 standard user-specified directories, it might be useful to group them
665 into a subdirectory particular to that program. If you do this, you
666 should write the `install' rule to create these subdirectories.
668 Do not expect the user to include the subdirectory name in the value
669 of any of the variables listed above. The idea of having a uniform set
670 of variable names for installation directories is to enable the user to
671 specify the exact same values for several different GNU packages. In
672 order for this to be useful, all the packages must be designed so that
673 they will work sensibly when the user does so.
676 File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
678 Standard Targets for Users
679 --------------------------
681 All GNU programs should have the following targets in their
685 Compile the entire program. This should be the default target.
686 This target need not rebuild any documentation files; Info files
687 should normally be included in the distribution, and DVI files
688 should be made only when explicitly asked for.
690 By default, the Make rules should compile and link with `-g', so
691 that executable programs have debugging symbols. Users who don't
692 mind being helpless can strip the executables later if they wish.
695 Compile the program and copy the executables, libraries, and so on
696 to the file names where they should reside for actual use. If
697 there is a simple test to verify that a program is properly
698 installed, this target should run that test.
700 Do not strip executables when installing them. Devil-may-care
701 users can use the `install-strip' target to do that.
703 If possible, write the `install' target rule so that it does not
704 modify anything in the directory where the program was built,
705 provided `make all' has just been done. This is convenient for
706 building the program under one user name and installing it under
709 The commands should create all the directories in which files are
710 to be installed, if they don't already exist. This includes the
711 directories specified as the values of the variables `prefix' and
712 `exec_prefix', as well as all subdirectories that are needed. One
713 way to do this is by means of an `installdirs' target as described
716 Use `-' before any command for installing a man page, so that
717 `make' will ignore any errors. This is in case there are systems
718 that don't have the Unix man page documentation system installed.
720 The way to install Info files is to copy them into `$(infodir)'
721 with `$(INSTALL_DATA)' (*note Command Variables::), and then run
722 the `install-info' program if it is present. `install-info' is a
723 program that edits the Info `dir' file to add or update the menu
724 entry for the given Info file; it is part of the Texinfo package.
725 Here is a sample rule to install an Info file:
727 $(DESTDIR)$(infodir)/foo.info: foo.info
729 # There may be a newer info file in . than in srcdir.
730 -if test -f foo.info; then d=.; \
731 else d=$(srcdir); fi; \
732 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
733 # Run install-info only if it exists.
734 # Use `if' instead of just prepending `-' to the
735 # line so we notice real errors from install-info.
736 # We use `$(SHELL) -c' because some shells do not
737 # fail gracefully when there is an unknown command.
738 if $(SHELL) -c 'install-info --version' \
739 >/dev/null 2>&1; then \
740 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
741 $(DESTDIR)$(infodir)/foo.info; \
744 When writing the `install' target, you must classify all the
745 commands into three categories: normal ones, "pre-installation"
746 commands and "post-installation" commands. *Note Install Command
750 Delete all the installed files--the copies that the `install'
753 This rule should not modify the directories where compilation is
754 done, only the directories where files are installed.
756 The uninstallation commands are divided into three categories,
757 just like the installation commands. *Note Install Command
761 Like `install', but strip the executable files while installing
762 them. In simple cases, this target can use the `install' target in
766 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
769 But if the package installs scripts as well as real executables,
770 the `install-strip' target can't just refer to the `install'
771 target; it has to strip the executables but not the scripts.
773 `install-strip' should not strip the executables in the build
774 directory which are being copied for installation. It should only
775 strip the copies that are installed.
777 Normally we do not recommend stripping an executable unless you
778 are sure the program has no bugs. However, it can be reasonable
779 to install a stripped executable for actual execution while saving
780 the unstripped executable elsewhere in case there is a bug.
783 Delete all files from the current directory that are normally
784 created by building the program. Don't delete the files that
785 record the configuration. Also preserve files that could be made
786 by building, but normally aren't because the distribution comes
789 Delete `.dvi' files here if they are not part of the distribution.
792 Delete all files from the current directory that are created by
793 configuring or building the program. If you have unpacked the
794 source and built the program without creating any other files,
795 `make distclean' should leave only the files that were in the
799 Like `clean', but may refrain from deleting a few files that people
800 normally don't want to recompile. For example, the `mostlyclean'
801 target for GCC does not delete `libgcc.a', because recompiling it
802 is rarely necessary and takes a lot of time.
805 Delete almost everything from the current directory that can be
806 reconstructed with this Makefile. This typically includes
807 everything deleted by `distclean', plus more: C source files
808 produced by Bison, tags tables, Info files, and so on.
810 The reason we say "almost everything" is that running the command
811 `make maintainer-clean' should not delete `configure' even if
812 `configure' can be remade using a rule in the Makefile. More
813 generally, `make maintainer-clean' should not delete anything that
814 needs to exist in order to run `configure' and then begin to build
815 the program. This is the only exception; `maintainer-clean' should
816 delete everything else that can be rebuilt.
818 The `maintainer-clean' target is intended to be used by a
819 maintainer of the package, not by ordinary users. You may need
820 special tools to reconstruct some of the files that `make
821 maintainer-clean' deletes. Since these files are normally
822 included in the distribution, we don't take care to make them easy
823 to reconstruct. If you find you need to unpack the full
824 distribution again, don't blame us.
826 To help make users aware of this, the commands for the special
827 `maintainer-clean' target should start with these two:
829 @echo 'This command is intended for maintainers to use; it'
830 @echo 'deletes files that may need special tools to rebuild.'
833 Update a tags table for this program.
836 Generate any Info files needed. The best way to write the rules
841 foo.info: foo.texi chap1.texi chap2.texi
842 $(MAKEINFO) $(srcdir)/foo.texi
844 You must define the variable `MAKEINFO' in the Makefile. It should
845 run the `makeinfo' program, which is part of the Texinfo
848 Normally a GNU distribution comes with Info files, and that means
849 the Info files are present in the source directory. Therefore,
850 the Make rule for an info file should update it in the source
851 directory. When users build the package, ordinarily Make will not
852 update the Info files because they will already be up to date.
855 Generate DVI files for all Texinfo documentation. For example:
859 foo.dvi: foo.texi chap1.texi chap2.texi
860 $(TEXI2DVI) $(srcdir)/foo.texi
862 You must define the variable `TEXI2DVI' in the Makefile. It should
863 run the program `texi2dvi', which is part of the Texinfo
864 distribution.(1) Alternatively, write just the dependencies, and
865 allow GNU `make' to provide the command.
868 Create a distribution tar file for this program. The tar file
869 should be set up so that the file names in the tar file start with
870 a subdirectory name which is the name of the package it is a
871 distribution for. This name can include the version number.
873 For example, the distribution tar file of GCC version 1.40 unpacks
874 into a subdirectory named `gcc-1.40'.
876 The easiest way to do this is to create a subdirectory
877 appropriately named, use `ln' or `cp' to install the proper files
878 in it, and then `tar' that subdirectory.
880 Compress the tar file with `gzip'. For example, the actual
881 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
883 The `dist' target should explicitly depend on all non-source files
884 that are in the distribution, to make sure they are up to date in
885 the distribution. *Note Making Releases: Releases.
888 Perform self-tests (if any). The user must build the program
889 before running the tests, but need not install the program; you
890 should write the self-tests so that they work when the program is
891 built but not installed.
893 The following targets are suggested as conventional names, for
894 programs in which they are useful.
897 Perform installation tests (if any). The user must build and
898 install the program before running the tests. You should not
899 assume that `$(bindir)' is in the search path.
902 It's useful to add a target named `installdirs' to create the
903 directories where files are installed, and their parent
904 directories. There is a script called `mkinstalldirs' which is
905 convenient for this; you can find it in the Texinfo package. You
906 can use a rule like this:
908 # Make sure all installation directories (e.g. $(bindir))
909 # actually exist by making them if necessary.
910 installdirs: mkinstalldirs
911 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
912 $(libdir) $(infodir) \
915 or, if you wish to support `DESTDIR',
917 # Make sure all installation directories (e.g. $(bindir))
918 # actually exist by making them if necessary.
919 installdirs: mkinstalldirs
920 $(srcdir)/mkinstalldirs \
921 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
922 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
925 This rule should not modify the directories where compilation is
926 done. It should do nothing but create installation directories.
928 ---------- Footnotes ----------
930 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
931 not distributed with Texinfo.
934 File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
936 Install Command Categories
937 --------------------------
939 When writing the `install' target, you must classify all the
940 commands into three categories: normal ones, "pre-installation"
941 commands and "post-installation" commands.
943 Normal commands move files into their proper places, and set their
944 modes. They may not alter any files except the ones that come entirely
945 from the package they belong to.
947 Pre-installation and post-installation commands may alter other
948 files; in particular, they can edit global configuration files or data
951 Pre-installation commands are typically executed before the normal
952 commands, and post-installation commands are typically run after the
955 The most common use for a post-installation command is to run
956 `install-info'. This cannot be done with a normal command, since it
957 alters a file (the Info directory) which does not come entirely and
958 solely from the package being installed. It is a post-installation
959 command because it needs to be done after the normal command which
960 installs the package's Info files.
962 Most programs don't need any pre-installation commands, but we have
963 the feature just in case it is needed.
965 To classify the commands in the `install' rule into these three
966 categories, insert "category lines" among them. A category line
967 specifies the category for the commands that follow.
969 A category line consists of a tab and a reference to a special Make
970 variable, plus an optional comment at the end. There are three
971 variables you can use, one for each category; the variable name
972 specifies the category. Category lines are no-ops in ordinary execution
973 because these three Make variables are normally undefined (and you
974 _should not_ define them in the makefile).
976 Here are the three possible category lines, each with a comment that
977 explains what it means:
979 $(PRE_INSTALL) # Pre-install commands follow.
980 $(POST_INSTALL) # Post-install commands follow.
981 $(NORMAL_INSTALL) # Normal commands follow.
983 If you don't use a category line at the beginning of the `install'
984 rule, all the commands are classified as normal until the first category
985 line. If you don't use any category lines, all the commands are
986 classified as normal.
988 These are the category lines for `uninstall':
990 $(PRE_UNINSTALL) # Pre-uninstall commands follow.
991 $(POST_UNINSTALL) # Post-uninstall commands follow.
992 $(NORMAL_UNINSTALL) # Normal commands follow.
994 Typically, a pre-uninstall command would be used for deleting entries
995 from the Info directory.
997 If the `install' or `uninstall' target has any dependencies which
998 act as subroutines of installation, then you should start _each_
999 dependency's commands with a category line, and start the main target's
1000 commands with a category line also. This way, you can ensure that each
1001 command is placed in the right category regardless of which of the
1002 dependencies actually run.
1004 Pre-installation and post-installation commands should not run any
1005 programs except for these:
1007 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1008 egrep expand expr false fgrep find getopt grep gunzip gzip
1009 hostname install install-info kill ldconfig ln ls md5sum
1010 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1011 test touch true uname xargs yes
1013 The reason for distinguishing the commands in this way is for the
1014 sake of making binary packages. Typically a binary package contains
1015 all the executables and other files that need to be installed, and has
1016 its own method of installing them--so it does not need to run the normal
1017 installation commands. But installing the binary package does need to
1018 execute the pre-installation and post-installation commands.
1020 Programs to build binary packages work by extracting the
1021 pre-installation and post-installation commands. Here is one way of
1022 extracting the pre-installation commands:
1024 make -n install -o all \
1025 PRE_INSTALL=pre-install \
1026 POST_INSTALL=post-install \
1027 NORMAL_INSTALL=normal-install \
1028 | gawk -f pre-install.awk
1030 where the file `pre-install.awk' could contain this:
1032 $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
1034 $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
1036 The resulting file of pre-installation commands is executed as a
1037 shell script as part of installing the binary package.
1040 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
1045 Package the distribution of `Foo version 69.96' up in a gzipped tar
1046 file with the name `foo-69.96.tar.gz'. It should unpack into a
1047 subdirectory named `foo-69.96'.
1049 Building and installing the program should never modify any of the
1050 files contained in the distribution. This means that all the files
1051 that form part of the program in any way must be classified into "source
1052 files" and "non-source files". Source files are written by humans and
1053 never changed automatically; non-source files are produced from source
1054 files by programs under the control of the Makefile.
1056 The distribution should contain a file named `README' which gives
1057 the name of the package, and a general description of what it does. It
1058 is also good to explain the purpose of each of the first-level
1059 subdirectories in the package, if there are any. The `README' file
1060 should either state the version number of the package, or refer to where
1061 in the package it can be found.
1063 The `README' file should refer to the file `INSTALL', which should
1064 contain an explanation of the installation procedure.
1066 The `README' file should also refer to the file which contains the
1067 copying conditions. The GNU GPL, if used, should be in a file called
1068 `COPYING'. If the GNU LGPL is used, it should be in a file called
1071 Naturally, all the source files must be in the distribution. It is
1072 okay to include non-source files in the distribution, provided they are
1073 up-to-date and machine-independent, so that building the distribution
1074 normally will never modify them. We commonly include non-source files
1075 produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
1076 unnecessary dependencies between our distributions, so that users can
1077 install whichever packages they want to install.
1079 Non-source files that might actually be modified by building and
1080 installing the program should *never* be included in the distribution.
1081 So if you do distribute non-source files, always make sure they are up
1082 to date when you make a new distribution.
1084 Make sure that the directory into which the distribution unpacks (as
1085 well as any subdirectories) are all world-writable (octal mode 777).
1086 This is so that old versions of `tar' which preserve the ownership and
1087 permissions of the files from the tar archive will be able to extract
1088 all the files even if the user is unprivileged.
1090 Make sure that all the files in the distribution are world-readable.
1092 Make sure that no file name in the distribution is more than 14
1093 characters long. Likewise, no file created by building the program
1094 should have a name longer than 14 characters. The reason for this is
1095 that some systems adhere to a foolish interpretation of the POSIX
1096 standard, and refuse to open a longer name, rather than truncating as
1097 they did in the past.
1099 Don't include any symbolic links in the distribution itself. If the
1100 tar file contains symbolic links, then people cannot even unpack it on
1101 systems that don't support symbolic links. Also, don't use multiple
1102 names for one file in different directories, because certain file
1103 systems cannot handle this and that prevents unpacking the distribution.
1105 Try to make sure that all the file names will be unique on MS-DOS. A
1106 name on MS-DOS consists of up to 8 characters, optionally followed by a
1107 period and up to three characters. MS-DOS will truncate extra
1108 characters both before and after the period. Thus, `foobarhacker.c'
1109 and `foobarhacker.o' are not ambiguous; they are truncated to
1110 `foobarha.c' and `foobarha.o', which are distinct.
1112 Include in your distribution a copy of the `texinfo.tex' you used to
1113 test print any `*.texinfo' or `*.texi' files.
1115 Likewise, if your program uses small GNU software packages like
1116 regex, getopt, obstack, or termcap, include them in the distribution
1117 file. Leaving them out would make the distribution file a little
1118 smaller at the expense of possible inconvenience to a user who doesn't
1119 know what other files to get.
1122 File: standards.info, Node: References, Next: Index, Prev: Managing Releases, Up: Top
1124 References to Non-Free Software and Documentation
1125 *************************************************
1127 A GNU program should not recommend use of any non-free program. We
1128 can't stop some people from writing proprietary programs, or stop other
1129 people from using them. But we can and should avoid helping to
1130 advertise them to new customers.
1132 Sometimes it is important to mention how to build your package on
1133 top of some non-free operating system or other non-free base package.
1134 In such cases, please mention the name of the non-free package or
1135 system in the briefest possible way. Don't include any references for
1136 where to find more information about the proprietary program. The goal
1137 should be that people already using the proprietary program will get
1138 the advice they need about how to use your free program, while people
1139 who don't already use the proprietary program will not see anything to
1140 encourage them to take an interest in it.
1142 Likewise, a GNU package should not refer the user to any non-free
1143 documentation for free software. The need for free documentation to go
1144 with free software is now a major focus of the GNU project; to show that
1145 we are serious about the need for free documentation, we must not
1146 undermine our position by recommending use of documentation that isn't