1 @comment This file is included by both standards.texi and make.texinfo.
2 @comment It was broken out of standards.texi on 1/6/93 by roland.
4 @node Makefile Conventions
5 @chapter Makefile Conventions
6 @comment standards.texi does not print an index, but make.texinfo does.
7 @cindex makefile, conventions for
8 @cindex conventions for makefiles
9 @cindex standards for makefiles
11 @c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
12 @c 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
14 @c Permission is granted to copy, distribute and/or modify this document
15 @c under the terms of the GNU Free Documentation License, Version 1.2
16 @c or any later version published by the Free Software Foundation;
17 @c with no Invariant Sections, with no
18 @c Front-Cover Texts, and with no Back-Cover Texts.
19 @c A copy of the license is included in the section entitled ``GNU
20 @c Free Documentation License''.
34 describes conventions for writing the Makefiles for GNU programs.
35 Using Automake will help you write a Makefile that follows these
39 * Makefile Basics:: General conventions for Makefiles.
40 * Utilities in Makefiles:: Utilities to be used in Makefiles.
41 * Command Variables:: Variables for specifying commands.
42 * DESTDIR:: Supporting staged installs.
43 * Directory Variables:: Variables for installation directories.
44 * Standard Targets:: Standard targets for users.
45 * Install Command Categories:: Three categories of commands in the `install'
46 rule: normal, pre-install and post-install.
50 @section General Conventions for Makefiles
52 Every Makefile should contain this line:
59 to avoid trouble on systems where the @code{SHELL} variable might be
60 inherited from the environment. (This is never a problem with GNU
63 Different @code{make} programs have incompatible suffix lists and
64 implicit rules, and this sometimes creates confusion or misbehavior. So
65 it is a good idea to set the suffix list explicitly using only the
66 suffixes you need in the particular Makefile, like this:
74 The first line clears out the suffix list, the second introduces all
75 suffixes which may be subject to implicit rules in this Makefile.
77 Don't assume that @file{.} is in the path for command execution. When
78 you need to run programs that are a part of your package during the
79 make, please make sure that it uses @file{./} if the program is built as
80 part of the make or @file{$(srcdir)/} if the file is an unchanging part
81 of the source code. Without one of these prefixes, the current search
84 The distinction between @file{./} (the @dfn{build directory}) and
85 @file{$(srcdir)/} (the @dfn{source directory}) is important because
86 users can build in a separate directory using the @samp{--srcdir} option
87 to @file{configure}. A rule of the form:
90 foo.1 : foo.man sedscript
91 sed -e sedscript foo.man > foo.1
95 will fail when the build directory is not the source directory, because
96 @file{foo.man} and @file{sedscript} are in the source directory.
98 When using GNU @code{make}, relying on @samp{VPATH} to find the source
99 file will work in the case where there is a single dependency file,
100 since the @code{make} automatic variable @samp{$<} will represent the
101 source file wherever it is. (Many versions of @code{make} set @samp{$<}
102 only in implicit rules.) A Makefile target like
106 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
110 should instead be written as
114 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
118 in order to allow @samp{VPATH} to work correctly. When the target has
119 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
120 way to make the rule work well. For example, the target above for
121 @file{foo.1} is best written as:
124 foo.1 : foo.man sedscript
125 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
128 GNU distributions usually contain some files which are not source
129 files---for example, Info files, and the output from Autoconf, Automake,
130 Bison or Flex. Since these files normally appear in the source
131 directory, they should always appear in the source directory, not in the
132 build directory. So Makefile rules to update them should put the
133 updated files in the source directory.
135 However, if a file does not appear in the distribution, then the
136 Makefile should not put it in the source directory, because building a
137 program in ordinary circumstances should not modify the source directory
140 Try to make the build and installation targets, at least (and all their
141 subtargets) work correctly with a parallel @code{make}.
143 @node Utilities in Makefiles
144 @section Utilities in Makefiles
146 Write the Makefile commands (and any shell scripts, such as
147 @code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any
148 special features of @code{ksh} or @code{bash}.
150 The @code{configure} script and the Makefile rules for building and
151 installation should not use any utilities directly except these:
154 @c gunzip gzip md5sum
155 @c mkfifo mknod tee uname
158 awk cat cmp cp diff echo egrep expr false grep install-info
159 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
162 Compression programs such as @code{gzip} can be used in the
165 Stick to the generally supported options for these programs. For
166 example, don't use @samp{mkdir -p}, convenient as it may be, because
167 most systems don't support it.
169 It is a good idea to avoid creating symbolic links in makefiles, since a
170 few systems don't support them.
172 The Makefile rules for building and installation can also use compilers
173 and related programs, but should do so via @code{make} variables so that the
174 user can substitute alternatives. Here are some of the programs we
178 ar bison cc flex install ld ldconfig lex
179 make makeinfo ranlib texi2dvi yacc
182 Use the following @code{make} variables to run those programs:
185 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
186 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
189 When you use @code{ranlib} or @code{ldconfig}, you should make sure
190 nothing bad happens if the system does not have the program in question.
191 Arrange to ignore an error from that command, and print a message before
192 the command to tell the user that failure of this command does not mean
193 a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
196 If you use symbolic links, you should implement a fallback for systems
197 that don't have symbolic links.
199 Additional utilities that can be used via Make variables are:
202 chgrp chmod chown mknod
205 It is ok to use other utilities in Makefile portions (or scripts)
206 intended only for particular systems where you know those utilities
209 @node Command Variables
210 @section Variables for Specifying Commands
212 Makefiles should provide variables for overriding certain commands, options,
215 In particular, you should run most utility programs via variables.
216 Thus, if you use Bison, have a variable named @code{BISON} whose default
217 value is set with @samp{BISON = bison}, and refer to it with
218 @code{$(BISON)} whenever you need to use Bison.
220 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
221 so on, need not be referred to through variables in this way, since users
222 don't need to replace them with other programs.
224 Each program-name variable should come with an options variable that is
225 used to supply options to the program. Append @samp{FLAGS} to the
226 program-name variable name to get the options variable name---for
227 example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
228 compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
229 exceptions to this rule, but we keep them because they are standard.)
230 Use @code{CPPFLAGS} in any compilation command that runs the
231 preprocessor, and use @code{LDFLAGS} in any compilation command that
232 does linking as well as in any direct use of @code{ld}.
234 If there are C compiler options that @emph{must} be used for proper
235 compilation of certain files, do not include them in @code{CFLAGS}.
236 Users expect to be able to specify @code{CFLAGS} freely themselves.
237 Instead, arrange to pass the necessary options to the C compiler
238 independently of @code{CFLAGS}, by writing them explicitly in the
239 compilation commands or by defining an implicit rule, like this:
243 ALL_CFLAGS = -I. $(CFLAGS)
245 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
248 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
249 @emph{required} for proper compilation. You can consider it a default
250 that is only recommended. If the package is set up so that it is
251 compiled with GCC by default, then you might as well include @samp{-O}
252 in the default value of @code{CFLAGS} as well.
254 Put @code{CFLAGS} last in the compilation command, after other variables
255 containing compiler options, so the user can use @code{CFLAGS} to
258 @code{CFLAGS} should be used in every invocation of the C compiler,
259 both those which do compilation and those which do linking.
261 Every Makefile should define the variable @code{INSTALL}, which is the
262 basic command for installing a file into the system.
264 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
265 and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should
266 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
267 @code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
268 commands for actual installation, for executables and non-executables
269 respectively. Minimal use of these variables is as follows:
272 $(INSTALL_PROGRAM) foo $(bindir)/foo
273 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
276 However, it is preferable to support a @code{DESTDIR} prefix on the
277 target files, as explained in the next section.
279 It is acceptable, but not required, to install multiple files in one
280 command, with the final argument being a directory, as in:
283 $(INSTALL_PROGRAM) foo bar baz $(bindir)
288 @section @code{DESTDIR}: support for staged installs
291 @cindex staged installs
292 @cindex installations, staged
294 @code{DESTDIR} is a variable prepended to each installed target file,
298 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
299 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
302 The @code{DESTDIR} variable is specified by the user on the @code{make}
303 command line as an absolute file name. For example:
306 make DESTDIR=/tmp/stage install
310 @code{DESTDIR} should be supported only in the @code{install*} and
311 @code{uninstall*} targets, as those are the only targets where it is
314 If your installation step would normally install
315 @file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
316 installation invoked as in the example above would install
317 @file{/tmp/stage/usr/local/bin/foo} and
318 @file{/tmp/stage/usr/local/lib/libfoo.a} instead.
320 Prepending the variable @code{DESTDIR} to each target in this way
321 provides for @dfn{staged installs}, where the installed files are not
322 placed directly into their expected location but are instead copied
323 into a temporary location (@code{DESTDIR}). However, installed files
324 maintain their relative directory structure and any embedded file names
325 will not be modified.
327 You should not set the value of @code{DESTDIR} in your @file{Makefile}
328 at all; then the files are installed into their expected locations by
329 default. Also, specifying @code{DESTDIR} should not change the
330 operation of the software in any way, so its value should not be
331 included in any file contents.
333 @code{DESTDIR} support is commonly used in package creation. It is
334 also helpful to users who want to understand what a given package will
335 install where, and to allow users who don't normally have permissions
336 to install into protected areas to build and install before gaining
337 those permissions. Finally, it can be useful with tools such as
338 @code{stow}, where code is installed in one place but made to appear
339 to be installed somewhere else using symbolic links or special mount
340 operations. So, we strongly recommend GNU packages support
341 @code{DESTDIR}, though it is not an absolute requirement.
344 @node Directory Variables
345 @section Variables for Installation Directories
347 Installation directories should always be named by variables, so it is
348 easy to install in a nonstandard place. The standard names for these
349 variables and the values they should have in GNU packages are
350 described below. They are based on a standard file system layout;
351 variants of it are used in GNU/Linux and other modern operating
354 Installers are expected to override these values when calling
355 @command{make} (e.g., @kbd{make prefix=/usr install} or
356 @command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU
357 packages should not try to guess which value should be appropriate for
358 these variables on the system they are being installed onto: use the
359 default settings specified here so that all GNU packages behave
360 identically, allowing the installer to achieve any desired layout.
362 These first two variables set the root for the installation. All the
363 other installation directories should be subdirectories of one of
364 these two, and nothing should be directly installed into these two
370 A prefix used in constructing the default values of the variables listed
371 below. The default value of @code{prefix} should be @file{/usr/local}.
372 When building the complete GNU system, the prefix will be empty and
373 @file{/usr} will be a symbolic link to @file{/}.
374 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
376 Running @samp{make install} with a different value of @code{prefix} from
377 the one used to build the program should @emph{not} recompile the
382 A prefix used in constructing the default values of some of the
383 variables listed below. The default value of @code{exec_prefix} should
385 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
387 Generally, @code{$(exec_prefix)} is used for directories that contain
388 machine-specific files (such as executables and subroutine libraries),
389 while @code{$(prefix)} is used directly for other directories.
391 Running @samp{make install} with a different value of @code{exec_prefix}
392 from the one used to build the program should @emph{not} recompile the
396 Executable programs are installed in one of the following directories.
401 The directory for installing executable programs that users can run.
402 This should normally be @file{/usr/local/bin}, but write it as
403 @file{$(exec_prefix)/bin}.
404 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
408 The directory for installing executable programs that can be run from
409 the shell, but are only generally useful to system administrators. This
410 should normally be @file{/usr/local/sbin}, but write it as
411 @file{$(exec_prefix)/sbin}.
412 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
416 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
417 The directory for installing executable programs to be run by other
418 programs rather than by users. This directory should normally be
419 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
420 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
422 The definition of @samp{libexecdir} is the same for all packages, so
423 you should install your data in a subdirectory thereof. Most packages
424 install their data under @file{$(libexecdir)/@var{package-name}/},
425 possibly within additional subdirectories thereof, such as
426 @file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
429 Data files used by the program during its execution are divided into
430 categories in two ways.
434 Some files are normally modified by programs; others are never normally
435 modified (though users may edit some of these).
438 Some files are architecture-independent and can be shared by all
439 machines at a site; some are architecture-dependent and can be shared
440 only by machines of the same kind and operating system; others may never
441 be shared between two machines.
444 This makes for six different possibilities. However, we want to
445 discourage the use of architecture-dependent files, aside from object
446 files and libraries. It is much cleaner to make other data files
447 architecture-independent, and it is generally not hard.
449 Here are the variables Makefiles should use to specify directories
450 to put these various kinds of files in:
454 The root of the directory tree for read-only architecture-independent
455 data files. This should normally be @file{/usr/local/share}, but
456 write it as @file{$(prefix)/share}. (If you are using Autoconf, write
457 it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is
458 based on this variable; so are @samp{infodir}, @samp{mandir}, and
462 The directory for installing idiosyncratic read-only
463 architecture-independent data files for this program. This is usually
464 the same place as @samp{datarootdir}, but we use the two separate
465 variables so that you can move these program-specific files without
466 altering the location for Info files, man pages, etc.
468 This should normally be @file{/usr/local/share}, but write it as
469 @file{$(datarootdir)}. (If you are using Autoconf, write it as
472 The definition of @samp{datadir} is the same for all packages, so you
473 should install your data in a subdirectory thereof. Most packages
474 install their data under @file{$(datadir)/@var{package-name}/}.
477 The directory for installing read-only data files that pertain to a
478 single machine--that is to say, files for configuring a host. Mailer
479 and network configuration files, @file{/etc/passwd}, and so forth belong
480 here. All the files in this directory should be ordinary ASCII text
481 files. This directory should normally be @file{/usr/local/etc}, but
482 write it as @file{$(prefix)/etc}.
483 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
485 Do not install executables here in this directory (they probably belong
486 in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
487 files that are modified in the normal course of their use (programs
488 whose purpose is to change the configuration of the system excluded).
489 Those probably belong in @file{$(localstatedir)}.
492 The directory for installing architecture-independent data files which
493 the programs modify while they run. This should normally be
494 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
495 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
498 The directory for installing data files which the programs modify while
499 they run, and that pertain to one specific machine. Users should never
500 need to modify files in this directory to configure the package's
501 operation; put such configuration information in separate files that go
502 in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)}
503 should normally be @file{/usr/local/var}, but write it as
504 @file{$(prefix)/var}.
505 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
508 These variables specify the directory for installing certain specific
509 types of files, if your program has them. Every GNU package should
510 have Info files, so every program needs @samp{infodir}, but not all
511 need @samp{libdir} or @samp{lispdir}.
515 @c rewritten to avoid overfull hbox --roland
516 The directory for installing header files to be included by user
517 programs with the C @samp{#include} preprocessor directive. This
518 should normally be @file{/usr/local/include}, but write it as
519 @file{$(prefix)/include}.
520 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
522 Most compilers other than GCC do not look for header files in directory
523 @file{/usr/local/include}. So installing the header files this way is
524 only useful with GCC. Sometimes this is not a problem because some
525 libraries are only really intended to work with GCC. But some libraries
526 are intended to work with other compilers. They should install their
527 header files in two places, one specified by @code{includedir} and one
528 specified by @code{oldincludedir}.
531 The directory for installing @samp{#include} header files for use with
532 compilers other than GCC. This should normally be @file{/usr/include}.
533 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
535 The Makefile commands should check whether the value of
536 @code{oldincludedir} is empty. If it is, they should not try to use
537 it; they should cancel the second installation of the header files.
539 A package should not replace an existing header in this directory unless
540 the header came from the same package. Thus, if your Foo package
541 provides a header file @file{foo.h}, then it should install the header
542 file in the @code{oldincludedir} directory if either (1) there is no
543 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
546 To tell whether @file{foo.h} came from the Foo package, put a magic
547 string in the file---part of a comment---and @code{grep} for that string.
550 The directory for installing documentation files (other than Info) for
551 this package. By default, it should be
552 @file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
553 @file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf,
554 write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which
555 may include a version number, prevents collisions among files with
556 common names, such as @file{README}.
559 The directory for installing the Info files for this package. By
560 default, it should be @file{/usr/local/share/info}, but it should be
561 written as @file{$(datarootdir)/info}. (If you are using Autoconf,
562 write it as @samp{@@infodir@@}.) @code{infodir} is separate from
563 @code{docdir} for compatibility with existing practice.
569 Directories for installing documentation files in the particular
570 format. They should all be set to @code{$(docdir)} by default. (If
571 you are using Autoconf, write them as @samp{@@htmldir@@},
572 @samp{@@dvidir@@}, etc.) Packages which supply several translations
573 of their documentation should install them in
574 @samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
575 @var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
578 The directory for object files and libraries of object code. Do not
579 install executables here, they probably ought to go in @file{$(libexecdir)}
580 instead. The value of @code{libdir} should normally be
581 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
582 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
585 The directory for installing any Emacs Lisp files in this package. By
586 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
587 should be written as @file{$(datarootdir)/emacs/site-lisp}.
589 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
590 In order to make @samp{@@lispdir@@} work, you need the following lines
591 in your @file{configure.in} file:
594 lispdir='$@{datarootdir@}/emacs/site-lisp'
599 The directory for installing locale-specific message catalogs for this
600 package. By default, it should be @file{/usr/local/share/locale}, but
601 it should be written as @file{$(datarootdir)/locale}. (If you are
602 using Autoconf, write it as @samp{@@localedir@@}.) This directory
603 usually has a subdirectory per locale.
606 Unix-style man pages are installed in one of the following:
610 The top-level directory for installing the man pages (if any) for this
611 package. It will normally be @file{/usr/local/share/man}, but you
612 should write it as @file{$(datarootdir)/man}. (If you are using
613 Autoconf, write it as @samp{@@mandir@@}.)
616 The directory for installing section 1 man pages. Write it as
617 @file{$(mandir)/man1}.
619 The directory for installing section 2 man pages. Write it as
620 @file{$(mandir)/man2}
623 @strong{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 for
625 the sake of people running GNU software on Unix, which is a secondary
629 The file name extension for the installed man page. This should contain
630 a period followed by the appropriate digit; it should normally be @samp{.1}.
633 The file name extension for installed section 1 man pages.
635 The file name extension for installed section 2 man pages.
637 Use these names instead of @samp{manext} if the package needs to install man
638 pages in more than one section of the manual.
641 And finally, you should set the following variable:
645 The directory for the sources being compiled. The value of this
646 variable is normally inserted by the @code{configure} shell script.
647 (If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.)
653 @c I have changed some of the comments here slightly to fix an overfull
654 @c hbox, so the make manual can format correctly. --roland
655 # Common prefix for installation directories.
656 # NOTE: This directory must exist when you start the install.
658 datarootdir = $(prefix)/share
659 datadir = $(datarootdir)
660 exec_prefix = $(prefix)
661 # Where to put the executable for the command `gcc'.
662 bindir = $(exec_prefix)/bin
663 # Where to put the directories used by the compiler.
664 libexecdir = $(exec_prefix)/libexec
665 # Where to put the Info files.
666 infodir = $(datarootdir)/info
669 If your program installs a large number of files into one of the
670 standard user-specified directories, it might be useful to group them
671 into a subdirectory particular to that program. If you do this, you
672 should write the @code{install} rule to create these subdirectories.
674 Do not expect the user to include the subdirectory name in the value of
675 any of the variables listed above. The idea of having a uniform set of
676 variable names for installation directories is to enable the user to
677 specify the exact same values for several different GNU packages. In
678 order for this to be useful, all the packages must be designed so that
679 they will work sensibly when the user does so.
681 At times, not all of these variables may be implemented in the current
682 release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we
683 believe all of them are. When any are missing, the descriptions here
684 serve as specifications for what Autoconf will implement. As a
685 programmer, you can either use a development version of Autoconf or
686 avoid using these variables until a stable release is made which
690 @node Standard Targets
691 @section Standard Targets for Users
693 All GNU programs should have the following targets in their Makefiles:
697 Compile the entire program. This should be the default target. This
698 target need not rebuild any documentation files; Info files should
699 normally be included in the distribution, and DVI (and other
700 documentation format) files should be made only when explicitly asked
703 By default, the Make rules should compile and link with @samp{-g}, so
704 that executable programs have debugging symbols. Users who don't mind
705 being helpless can strip the executables later if they wish.
708 Compile the program and copy the executables, libraries, and so on to
709 the file names where they should reside for actual use. If there is a
710 simple test to verify that a program is properly installed, this target
711 should run that test.
713 Do not strip executables when installing them. Devil-may-care users can
714 use the @code{install-strip} target to do that.
716 If possible, write the @code{install} target rule so that it does not
717 modify anything in the directory where the program was built, provided
718 @samp{make all} has just been done. This is convenient for building the
719 program under one user name and installing it under another.
721 The commands should create all the directories in which files are to be
722 installed, if they don't already exist. This includes the directories
723 specified as the values of the variables @code{prefix} and
724 @code{exec_prefix}, as well as all subdirectories that are needed.
725 One way to do this is by means of an @code{installdirs} target
728 Use @samp{-} before any command for installing a man page, so that
729 @code{make} will ignore any errors. This is in case there are systems
730 that don't have the Unix man page documentation system installed.
732 The way to install Info files is to copy them into @file{$(infodir)}
733 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
734 the @code{install-info} program if it is present. @code{install-info}
735 is a program that edits the Info @file{dir} file to add or update the
736 menu entry for the given Info file; it is part of the Texinfo package.
737 Here is a sample rule to install an Info file:
739 @comment This example has been carefully formatted for the Make manual.
740 @comment Please do not reformat it without talking to bug-make@gnu.org.
742 $(DESTDIR)$(infodir)/foo.info: foo.info
744 # There may be a newer info file in . than in srcdir.
745 -if test -f foo.info; then d=.; \
746 else d=$(srcdir); fi; \
747 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
748 # Run install-info only if it exists.
749 # Use `if' instead of just prepending `-' to the
750 # line so we notice real errors from install-info.
751 # We use `$(SHELL) -c' because some shells do not
752 # fail gracefully when there is an unknown command.
753 if $(SHELL) -c 'install-info --version' \
754 >/dev/null 2>&1; then \
755 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
756 $(DESTDIR)$(infodir)/foo.info; \
760 When writing the @code{install} target, you must classify all the
761 commands into three categories: normal ones, @dfn{pre-installation}
762 commands and @dfn{post-installation} commands. @xref{Install Command
769 These targets install documentation in formats other than Info;
770 they're intended to be called explicitly by the person installing the
771 package, if that format is desired. GNU prefers Info files, so these
772 must be installed by the @code{install} target.
774 When you have many documentation files to install, we recommend that
775 you avoid collisions and clutter by arranging for these targets to
776 install in subdirectories of the appropriate installation directory,
777 such as @code{htmldir}. As one example, if your package has multiple
778 manuals, and you wish to install HTML documentation with many files
779 (such as the ``split'' mode output by @code{makeinfo --html}), you'll
780 certainly want to use subdirectories, or two nodes with the same name
781 in different manuals will overwrite each other.
783 Please make these @code{install-@var{format}} targets invoke the
784 commands for the @var{format} target, for example, by making
785 @var{format} a dependency.
788 Delete all the installed files---the copies that the @samp{install}
789 and @samp{install-*} targets create.
791 This rule should not modify the directories where compilation is done,
792 only the directories where files are installed.
794 The uninstallation commands are divided into three categories, just like
795 the installation commands. @xref{Install Command Categories}.
798 Like @code{install}, but strip the executable files while installing
799 them. In simple cases, this target can use the @code{install} target in
804 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
808 But if the package installs scripts as well as real executables, the
809 @code{install-strip} target can't just refer to the @code{install}
810 target; it has to strip the executables but not the scripts.
812 @code{install-strip} should not strip the executables in the build
813 directory which are being copied for installation. It should only strip
814 the copies that are installed.
816 Normally we do not recommend stripping an executable unless you are sure
817 the program has no bugs. However, it can be reasonable to install a
818 stripped executable for actual execution while saving the unstripped
819 executable elsewhere in case there is a bug.
821 @comment The gratuitous blank line here is to make the table look better
822 @comment in the printed Make manual. Please leave it in.
825 Delete all files in the current directory that are normally created by
826 building the program. Also delete files in other directories if they
827 are created by this makefile. However, don't delete the files that
828 record the configuration. Also preserve files that could be made by
829 building, but normally aren't because the distribution comes with
830 them. There is no need to delete parent directories that were created
831 with @samp{mkdir -p}, since they could have existed anyway.
833 Delete @file{.dvi} files here if they are not part of the distribution.
836 Delete all files in the current directory (or created by this
837 makefile) that are created by configuring or building the program. If
838 you have unpacked the source and built the program without creating
839 any other files, @samp{make distclean} should leave only the files
840 that were in the distribution. However, there is no need to delete
841 parent directories that were created with @samp{mkdir -p}, since they
842 could have existed anyway.
845 Like @samp{clean}, but may refrain from deleting a few files that people
846 normally don't want to recompile. For example, the @samp{mostlyclean}
847 target for GCC does not delete @file{libgcc.a}, because recompiling it
848 is rarely necessary and takes a lot of time.
850 @item maintainer-clean
851 Delete almost everything that can be reconstructed with this Makefile.
852 This typically includes everything deleted by @code{distclean}, plus
853 more: C source files produced by Bison, tags tables, Info files, and
856 The reason we say ``almost everything'' is that running the command
857 @samp{make maintainer-clean} should not delete @file{configure} even
858 if @file{configure} can be remade using a rule in the Makefile. More
859 generally, @samp{make maintainer-clean} should not delete anything
860 that needs to exist in order to run @file{configure} and then begin to
861 build the program. Also, there is no need to delete parent
862 directories that were created with @samp{mkdir -p}, since they could
863 have existed anyway. These are the only exceptions;
864 @code{maintainer-clean} should delete everything else that can be
867 The @samp{maintainer-clean} target is intended to be used by a maintainer of
868 the package, not by ordinary users. You may need special tools to
869 reconstruct some of the files that @samp{make maintainer-clean} deletes.
870 Since these files are normally included in the distribution, we don't
871 take care to make them easy to reconstruct. If you find you need to
872 unpack the full distribution again, don't blame us.
874 To help make users aware of this, the commands for the special
875 @code{maintainer-clean} target should start with these two:
878 @@echo 'This command is intended for maintainers to use; it'
879 @@echo 'deletes files that may need special tools to rebuild.'
883 Update a tags table for this program.
887 Generate any Info files needed. The best way to write the rules is as
893 foo.info: foo.texi chap1.texi chap2.texi
894 $(MAKEINFO) $(srcdir)/foo.texi
898 You must define the variable @code{MAKEINFO} in the Makefile. It should
899 run the @code{makeinfo} program, which is part of the Texinfo
902 Normally a GNU distribution comes with Info files, and that means the
903 Info files are present in the source directory. Therefore, the Make
904 rule for an info file should update it in the source directory. When
905 users build the package, ordinarily Make will not update the Info files
906 because they will already be up to date.
912 Generate documentation files in the given format. These targets
913 should always exist, but any or all can be a no-op if the given output
914 format cannot be generated. These targets should not be dependencies
915 of the @code{all} target; the user must manually invoke them.
917 Here's an example rule for generating DVI files from Texinfo:
922 foo.dvi: foo.texi chap1.texi chap2.texi
923 $(TEXI2DVI) $(srcdir)/foo.texi
927 You must define the variable @code{TEXI2DVI} in the Makefile. It should
928 run the program @code{texi2dvi}, which is part of the Texinfo
929 distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
930 of formatting. @TeX{} is not distributed with Texinfo.} Alternatively,
931 write just the dependencies, and allow GNU @code{make} to provide the command.
933 Here's another example, this one for generating HTML from Texinfo:
938 foo.html: foo.texi chap1.texi chap2.texi
939 $(TEXI2HTML) $(srcdir)/foo.texi
943 Again, you would define the variable @code{TEXI2HTML} in the Makefile;
944 for example, it might run @code{makeinfo --no-split --html}
945 (@command{makeinfo} is part of the Texinfo distribution).
948 Create a distribution tar file for this program. The tar file should be
949 set up so that the file names in the tar file start with a subdirectory
950 name which is the name of the package it is a distribution for. This
951 name can include the version number.
953 For example, the distribution tar file of GCC version 1.40 unpacks into
954 a subdirectory named @file{gcc-1.40}.
956 The easiest way to do this is to create a subdirectory appropriately
957 named, use @code{ln} or @code{cp} to install the proper files in it, and
958 then @code{tar} that subdirectory.
960 Compress the tar file with @code{gzip}. For example, the actual
961 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
963 The @code{dist} target should explicitly depend on all non-source files
964 that are in the distribution, to make sure they are up to date in the
967 @xref{Releases, , Making Releases}.
970 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
974 Perform self-tests (if any). The user must build the program before
975 running the tests, but need not install the program; you should write
976 the self-tests so that they work when the program is built but not
980 The following targets are suggested as conventional names, for programs
981 in which they are useful.
985 Perform installation tests (if any). The user must build and install
986 the program before running the tests. You should not assume that
987 @file{$(bindir)} is in the search path.
990 It's useful to add a target named @samp{installdirs} to create the
991 directories where files are installed, and their parent directories.
992 There is a script called @file{mkinstalldirs} which is convenient for
993 this; you can find it in the Texinfo package.
994 @c It's in /gd/gnu/lib/mkinstalldirs.
995 You can use a rule like this:
997 @comment This has been carefully formatted to look decent in the Make manual.
998 @comment Please be sure not to make it extend any further to the right.--roland
1000 # Make sure all installation directories (e.g. $(bindir))
1001 # actually exist by making them if necessary.
1002 installdirs: mkinstalldirs
1003 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1004 $(libdir) $(infodir) \
1009 or, if you wish to support @env{DESTDIR},
1012 # Make sure all installation directories (e.g. $(bindir))
1013 # actually exist by making them if necessary.
1014 installdirs: mkinstalldirs
1015 $(srcdir)/mkinstalldirs \
1016 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
1017 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
1021 This rule should not modify the directories where compilation is done.
1022 It should do nothing but create installation directories.
1025 @node Install Command Categories
1026 @section Install Command Categories
1028 @cindex pre-installation commands
1029 @cindex post-installation commands
1030 When writing the @code{install} target, you must classify all the
1031 commands into three categories: normal ones, @dfn{pre-installation}
1032 commands and @dfn{post-installation} commands.
1034 Normal commands move files into their proper places, and set their
1035 modes. They may not alter any files except the ones that come entirely
1036 from the package they belong to.
1038 Pre-installation and post-installation commands may alter other files;
1039 in particular, they can edit global configuration files or data bases.
1041 Pre-installation commands are typically executed before the normal
1042 commands, and post-installation commands are typically run after the
1045 The most common use for a post-installation command is to run
1046 @code{install-info}. This cannot be done with a normal command, since
1047 it alters a file (the Info directory) which does not come entirely and
1048 solely from the package being installed. It is a post-installation
1049 command because it needs to be done after the normal command which
1050 installs the package's Info files.
1052 Most programs don't need any pre-installation commands, but we have the
1053 feature just in case it is needed.
1055 To classify the commands in the @code{install} rule into these three
1056 categories, insert @dfn{category lines} among them. A category line
1057 specifies the category for the commands that follow.
1059 A category line consists of a tab and a reference to a special Make
1060 variable, plus an optional comment at the end. There are three
1061 variables you can use, one for each category; the variable name
1062 specifies the category. Category lines are no-ops in ordinary execution
1063 because these three Make variables are normally undefined (and you
1064 @emph{should not} define them in the makefile).
1066 Here are the three possible category lines, each with a comment that
1067 explains what it means:
1070 $(PRE_INSTALL) # @r{Pre-install commands follow.}
1071 $(POST_INSTALL) # @r{Post-install commands follow.}
1072 $(NORMAL_INSTALL) # @r{Normal commands follow.}
1075 If you don't use a category line at the beginning of the @code{install}
1076 rule, all the commands are classified as normal until the first category
1077 line. If you don't use any category lines, all the commands are
1078 classified as normal.
1080 These are the category lines for @code{uninstall}:
1083 $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
1084 $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
1085 $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
1088 Typically, a pre-uninstall command would be used for deleting entries
1089 from the Info directory.
1091 If the @code{install} or @code{uninstall} target has any dependencies
1092 which act as subroutines of installation, then you should start
1093 @emph{each} dependency's commands with a category line, and start the
1094 main target's commands with a category line also. This way, you can
1095 ensure that each command is placed in the right category regardless of
1096 which of the dependencies actually run.
1098 Pre-installation and post-installation commands should not run any
1099 programs except for these:
1102 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1103 egrep expand expr false fgrep find getopt grep gunzip gzip
1104 hostname install install-info kill ldconfig ln ls md5sum
1105 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1106 test touch true uname xargs yes
1109 @cindex binary packages
1110 The reason for distinguishing the commands in this way is for the sake
1111 of making binary packages. Typically a binary package contains all the
1112 executables and other files that need to be installed, and has its own
1113 method of installing them---so it does not need to run the normal
1114 installation commands. But installing the binary package does need to
1115 execute the pre-installation and post-installation commands.
1117 Programs to build binary packages work by extracting the
1118 pre-installation and post-installation commands. Here is one way of
1119 extracting the pre-installation commands (the @option{-s} option to
1120 @command{make} is needed to silence messages about entering
1124 make -s -n install -o all \
1125 PRE_INSTALL=pre-install \
1126 POST_INSTALL=post-install \
1127 NORMAL_INSTALL=normal-install \
1128 | gawk -f pre-install.awk
1132 where the file @file{pre-install.awk} could contain this:
1135 $0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
1137 $0 ~ /^pre-install[ \t]*$/ @{on = 1@}