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 @cindex makefile, conventions for
7 @cindex conventions for makefiles
8 @cindex standards for makefiles
10 @c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
11 @c 2004, 2005, 2006, 2007, 2008, 2010, 2013 Free Software Foundation, Inc.
13 @c Permission is granted to copy, distribute and/or modify this document
14 @c under the terms of the GNU Free Documentation License, Version 1.3
15 @c or any later version published by the Free Software Foundation;
16 @c with no Invariant Sections, with no
17 @c Front-Cover Texts, and with no Back-Cover Texts.
18 @c A copy of the license is included in the section entitled ``GNU
19 @c Free Documentation License''.
33 describes conventions for writing the Makefiles for GNU programs.
34 Using Automake will help you write a Makefile that follows these
35 conventions. For more information on portable Makefiles, see
36 @sc{posix} and @ref{Portable Make, Portable Make Programming,, autoconf,
41 * Makefile Basics:: General conventions for Makefiles.
42 * Utilities in Makefiles:: Utilities to be used in Makefiles.
43 * Command Variables:: Variables for specifying commands.
44 * DESTDIR:: Supporting staged installs.
45 * Directory Variables:: Variables for installation directories.
46 * Standard Targets:: Standard targets for users.
47 * Install Command Categories:: Three categories of commands in the `install'
48 rule: normal, pre-install and post-install.
52 @section General Conventions for Makefiles
54 Every Makefile should contain this line:
61 to avoid trouble on systems where the @code{SHELL} variable might be
62 inherited from the environment. (This is never a problem with GNU
65 Different @code{make} programs have incompatible suffix lists and
66 implicit rules, and this sometimes creates confusion or misbehavior. So
67 it is a good idea to set the suffix list explicitly using only the
68 suffixes you need in the particular Makefile, like this:
76 The first line clears out the suffix list, the second introduces all
77 suffixes which may be subject to implicit rules in this Makefile.
79 Don't assume that @file{.} is in the path for command execution. When
80 you need to run programs that are a part of your package during the
81 make, please make sure that it uses @file{./} if the program is built as
82 part of the make or @file{$(srcdir)/} if the file is an unchanging part
83 of the source code. Without one of these prefixes, the current search
86 The distinction between @file{./} (the @dfn{build directory}) and
87 @file{$(srcdir)/} (the @dfn{source directory}) is important because
88 users can build in a separate directory using the @samp{--srcdir} option
89 to @file{configure}. A rule of the form:
92 foo.1 : foo.man sedscript
93 sed -f sedscript foo.man > foo.1
97 will fail when the build directory is not the source directory, because
98 @file{foo.man} and @file{sedscript} are in the source directory.
100 When using GNU @code{make}, relying on @samp{VPATH} to find the source
101 file will work in the case where there is a single dependency file,
102 since the @code{make} automatic variable @samp{$<} will represent the
103 source file wherever it is. (Many versions of @code{make} set @samp{$<}
104 only in implicit rules.) A Makefile target like
108 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
112 should instead be written as
116 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
120 in order to allow @samp{VPATH} to work correctly. When the target has
121 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
122 way to make the rule work well. For example, the target above for
123 @file{foo.1} is best written as:
126 foo.1 : foo.man sedscript
127 sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@@
130 GNU distributions usually contain some files which are not source
131 files---for example, Info files, and the output from Autoconf, Automake,
132 Bison or Flex. Since these files normally appear in the source
133 directory, they should always appear in the source directory, not in the
134 build directory. So Makefile rules to update them should put the
135 updated files in the source directory.
137 However, if a file does not appear in the distribution, then the
138 Makefile should not put it in the source directory, because building a
139 program in ordinary circumstances should not modify the source directory
142 Try to make the build and installation targets, at least (and all their
143 subtargets) work correctly with a parallel @code{make}.
145 @node Utilities in Makefiles
146 @section Utilities in Makefiles
148 Write the Makefile commands (and any shell scripts, such as
149 @code{configure}) to run under @code{sh} (both the traditional Bourne
150 shell and the @sc{posix} shell), not @code{csh}. Don't use any
151 special features of @code{ksh} or @code{bash}, or @sc{posix} features
152 not widely supported in traditional Bourne @code{sh}.
154 The @code{configure} script and the Makefile rules for building and
155 installation should not use any utilities directly except these:
158 @c gunzip gzip md5sum
159 @c mkfifo mknod tee uname
162 awk cat cmp cp diff echo egrep expr false grep install-info ln ls
163 mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
166 Compression programs such as @code{gzip} can be used in the
169 Generally, stick to the widely-supported (usually
170 @sc{posix}-specified) options and features of these programs. For
171 example, don't use @samp{mkdir -p}, convenient as it may be, because a
172 few systems don't support it at all and with others, it is not safe
173 for parallel execution. For a list of known incompatibilities, see
174 @ref{Portable Shell, Portable Shell Programming,, autoconf, Autoconf}.
177 It is a good idea to avoid creating symbolic links in makefiles, since a
178 few file systems don't support them.
180 The Makefile rules for building and installation can also use compilers
181 and related programs, but should do so via @code{make} variables so that the
182 user can substitute alternatives. Here are some of the programs we
186 ar bison cc flex install ld ldconfig lex
187 make makeinfo ranlib texi2dvi yacc
190 Use the following @code{make} variables to run those programs:
193 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
194 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
197 When you use @code{ranlib} or @code{ldconfig}, you should make sure
198 nothing bad happens if the system does not have the program in question.
199 Arrange to ignore an error from that command, and print a message before
200 the command to tell the user that failure of this command does not mean
201 a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
204 If you use symbolic links, you should implement a fallback for systems
205 that don't have symbolic links.
207 Additional utilities that can be used via Make variables are:
210 chgrp chmod chown mknod
213 It is ok to use other utilities in Makefile portions (or scripts)
214 intended only for particular systems where you know those utilities
217 @node Command Variables
218 @section Variables for Specifying Commands
220 Makefiles should provide variables for overriding certain commands, options,
223 In particular, you should run most utility programs via variables.
224 Thus, if you use Bison, have a variable named @code{BISON} whose default
225 value is set with @samp{BISON = bison}, and refer to it with
226 @code{$(BISON)} whenever you need to use Bison.
228 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
229 so on, need not be referred to through variables in this way, since users
230 don't need to replace them with other programs.
232 Each program-name variable should come with an options variable that is
233 used to supply options to the program. Append @samp{FLAGS} to the
234 program-name variable name to get the options variable name---for
235 example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C
236 compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
237 exceptions to this rule, but we keep them because they are standard.)
238 Use @code{CPPFLAGS} in any compilation command that runs the
239 preprocessor, and use @code{LDFLAGS} in any compilation command that
240 does linking as well as in any direct use of @code{ld}.
242 If there are C compiler options that @emph{must} be used for proper
243 compilation of certain files, do not include them in @code{CFLAGS}.
244 Users expect to be able to specify @code{CFLAGS} freely themselves.
245 Instead, arrange to pass the necessary options to the C compiler
246 independently of @code{CFLAGS}, by writing them explicitly in the
247 compilation commands or by defining an implicit rule, like this:
251 ALL_CFLAGS = -I. $(CFLAGS)
253 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
256 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
257 @emph{required} for proper compilation. You can consider it a default
258 that is only recommended. If the package is set up so that it is
259 compiled with GCC by default, then you might as well include @samp{-O}
260 in the default value of @code{CFLAGS} as well.
262 Put @code{CFLAGS} last in the compilation command, after other variables
263 containing compiler options, so the user can use @code{CFLAGS} to
266 @code{CFLAGS} should be used in every invocation of the C compiler,
267 both those which do compilation and those which do linking.
269 Every Makefile should define the variable @code{INSTALL}, which is the
270 basic command for installing a file into the system.
272 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
273 and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should
274 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
275 @code{$@{INSTALL@} -m 644}.) Then it should use those variables as the
276 commands for actual installation, for executables and non-executables
277 respectively. Minimal use of these variables is as follows:
280 $(INSTALL_PROGRAM) foo $(bindir)/foo
281 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
284 However, it is preferable to support a @code{DESTDIR} prefix on the
285 target files, as explained in the next section.
287 It is acceptable, but not required, to install multiple files in one
288 command, with the final argument being a directory, as in:
291 $(INSTALL_PROGRAM) foo bar baz $(bindir)
296 @section @code{DESTDIR}: Support for Staged Installs
299 @cindex staged installs
300 @cindex installations, staged
302 @code{DESTDIR} is a variable prepended to each installed target file,
306 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
307 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
310 The @code{DESTDIR} variable is specified by the user on the @code{make}
311 command line as an absolute file name. For example:
314 make DESTDIR=/tmp/stage install
318 @code{DESTDIR} should be supported only in the @code{install*} and
319 @code{uninstall*} targets, as those are the only targets where it is
322 If your installation step would normally install
323 @file{/usr/local/bin/foo} and @file{/usr/@/local/@/lib/@/libfoo.a}, then an
324 installation invoked as in the example above would install
325 @file{/tmp/stage/usr/local/bin/foo} and
326 @file{/tmp/stage/usr/local/lib/libfoo.a} instead.
328 Prepending the variable @code{DESTDIR} to each target in this way
329 provides for @dfn{staged installs}, where the installed files are not
330 placed directly into their expected location but are instead copied
331 into a temporary location (@code{DESTDIR}). However, installed files
332 maintain their relative directory structure and any embedded file names
333 will not be modified.
335 You should not set the value of @code{DESTDIR} in your @file{Makefile}
336 at all; then the files are installed into their expected locations by
337 default. Also, specifying @code{DESTDIR} should not change the
338 operation of the software in any way, so its value should not be
339 included in any file contents.
341 @code{DESTDIR} support is commonly used in package creation. It is
342 also helpful to users who want to understand what a given package will
343 install where, and to allow users who don't normally have permissions
344 to install into protected areas to build and install before gaining
345 those permissions. Finally, it can be useful with tools such as
346 @code{stow}, where code is installed in one place but made to appear
347 to be installed somewhere else using symbolic links or special mount
348 operations. So, we strongly recommend GNU packages support
349 @code{DESTDIR}, though it is not an absolute requirement.
352 @node Directory Variables
353 @section Variables for Installation Directories
355 Installation directories should always be named by variables, so it is
356 easy to install in a nonstandard place. The standard names for these
357 variables and the values they should have in GNU packages are
358 described below. They are based on a standard file system layout;
359 variants of it are used in GNU/Linux and other modern operating
362 Installers are expected to override these values when calling
363 @command{make} (e.g., @kbd{make prefix=/usr install} or
364 @command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU
365 packages should not try to guess which value should be appropriate for
366 these variables on the system they are being installed onto: use the
367 default settings specified here so that all GNU packages behave
368 identically, allowing the installer to achieve any desired layout.
370 @cindex directories, creating installation
371 @cindex installation directories, creating
372 All installation directories, and their parent directories, should be
373 created (if necessary) before they are installed into.
375 These first two variables set the root for the installation. All the
376 other installation directories should be subdirectories of one of
377 these two, and nothing should be directly installed into these two
383 A prefix used in constructing the default values of the variables listed
384 below. The default value of @code{prefix} should be @file{/usr/local}.
385 When building the complete GNU system, the prefix will be empty and
386 @file{/usr} will be a symbolic link to @file{/}.
387 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
389 Running @samp{make install} with a different value of @code{prefix} from
390 the one used to build the program should @emph{not} recompile the
395 A prefix used in constructing the default values of some of the
396 variables listed below. The default value of @code{exec_prefix} should
398 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
400 Generally, @code{$(exec_prefix)} is used for directories that contain
401 machine-specific files (such as executables and subroutine libraries),
402 while @code{$(prefix)} is used directly for other directories.
404 Running @samp{make install} with a different value of @code{exec_prefix}
405 from the one used to build the program should @emph{not} recompile the
409 Executable programs are installed in one of the following directories.
414 The directory for installing executable programs that users can run.
415 This should normally be @file{/usr/local/bin}, but write it as
416 @file{$(exec_prefix)/bin}.
417 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
421 The directory for installing executable programs that can be run from
422 the shell, but are only generally useful to system administrators. This
423 should normally be @file{/usr/local/sbin}, but write it as
424 @file{$(exec_prefix)/sbin}.
425 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
429 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
430 The directory for installing executable programs to be run by other
431 programs rather than by users. This directory should normally be
432 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
433 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
435 The definition of @samp{libexecdir} is the same for all packages, so
436 you should install your data in a subdirectory thereof. Most packages
437 install their data under @file{$(libexecdir)/@var{package-name}/},
438 possibly within additional subdirectories thereof, such as
439 @file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
442 Data files used by the program during its execution are divided into
443 categories in two ways.
447 Some files are normally modified by programs; others are never normally
448 modified (though users may edit some of these).
451 Some files are architecture-independent and can be shared by all
452 machines at a site; some are architecture-dependent and can be shared
453 only by machines of the same kind and operating system; others may never
454 be shared between two machines.
457 This makes for six different possibilities. However, we want to
458 discourage the use of architecture-dependent files, aside from object
459 files and libraries. It is much cleaner to make other data files
460 architecture-independent, and it is generally not hard.
462 Here are the variables Makefiles should use to specify directories
463 to put these various kinds of files in:
467 The root of the directory tree for read-only architecture-independent
468 data files. This should normally be @file{/usr/local/share}, but
469 write it as @file{$(prefix)/share}. (If you are using Autoconf, write
470 it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is
471 based on this variable; so are @samp{infodir}, @samp{mandir}, and
475 The directory for installing idiosyncratic read-only
476 architecture-independent data files for this program. This is usually
477 the same place as @samp{datarootdir}, but we use the two separate
478 variables so that you can move these program-specific files without
479 altering the location for Info files, man pages, etc.
481 @c raggedright (not until next Texinfo release)
482 This should normally be @file{/usr/local/share}, but write it as
483 @file{$(datarootdir)}. (If you are using Autoconf, write it as
487 The definition of @samp{datadir} is the same for all packages, so you
488 should install your data in a subdirectory thereof. Most packages
489 install their data under @file{$(datadir)/@var{package-name}/}.
492 The directory for installing read-only data files that pertain to a
493 single machine--that is to say, files for configuring a host. Mailer
494 and network configuration files, @file{/etc/passwd}, and so forth belong
495 here. All the files in this directory should be ordinary ASCII text
496 files. This directory should normally be @file{/usr/local/etc}, but
497 write it as @file{$(prefix)/etc}.
498 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
500 Do not install executables here in this directory (they probably belong
501 in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
502 files that are modified in the normal course of their use (programs
503 whose purpose is to change the configuration of the system excluded).
504 Those probably belong in @file{$(localstatedir)}.
507 The directory for installing architecture-independent data files which
508 the programs modify while they run. This should normally be
509 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
510 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
513 The directory for installing data files which the programs modify while
514 they run, and that pertain to one specific machine. Users should never
515 need to modify files in this directory to configure the package's
516 operation; put such configuration information in separate files that go
517 in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)}
518 should normally be @file{/usr/local/var}, but write it as
519 @file{$(prefix)/var}.
520 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
523 The directory for installing data files which the programs modify
524 while they run, that pertain to one specific machine, and which need
525 not persist longer than the execution of the program---which is
526 generally long-lived, for example, until the next reboot. PID files
527 for system daemons are a typical use. In addition, this directory
528 should not be cleaned except perhaps at reboot, while the general
529 @file{/tmp} (@code{TMPDIR}) may be cleaned arbitrarily. This should
530 normally be @file{/var/run}, but write it as
531 @file{$(localstatedir)/run}. Having it as a separate variable allows
532 the use of @file{/run} if desired, for example. (If you are using
533 Autoconf 2.70 or later, write it as @samp{@@runstatedir@@}.)
536 These variables specify the directory for installing certain specific
537 types of files, if your program has them. Every GNU package should
538 have Info files, so every program needs @samp{infodir}, but not all
539 need @samp{libdir} or @samp{lispdir}.
543 The directory for installing header files to be included by user
544 programs with the C @samp{#include} preprocessor directive. This
545 should normally be @file{/usr/local/include}, but write it as
546 @file{$(prefix)/include}.
547 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
549 Most compilers other than GCC do not look for header files in directory
550 @file{/usr/local/include}. So installing the header files this way is
551 only useful with GCC. Sometimes this is not a problem because some
552 libraries are only really intended to work with GCC. But some libraries
553 are intended to work with other compilers. They should install their
554 header files in two places, one specified by @code{includedir} and one
555 specified by @code{oldincludedir}.
558 The directory for installing @samp{#include} header files for use with
559 compilers other than GCC. This should normally be @file{/usr/include}.
560 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
562 The Makefile commands should check whether the value of
563 @code{oldincludedir} is empty. If it is, they should not try to use
564 it; they should cancel the second installation of the header files.
566 A package should not replace an existing header in this directory unless
567 the header came from the same package. Thus, if your Foo package
568 provides a header file @file{foo.h}, then it should install the header
569 file in the @code{oldincludedir} directory if either (1) there is no
570 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
573 To tell whether @file{foo.h} came from the Foo package, put a magic
574 string in the file---part of a comment---and @code{grep} for that string.
577 The directory for installing documentation files (other than Info) for
578 this package. By default, it should be
579 @file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
580 @file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf,
581 write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which
582 may include a version number, prevents collisions among files with
583 common names, such as @file{README}.
586 The directory for installing the Info files for this package. By
587 default, it should be @file{/usr/local/share/info}, but it should be
588 written as @file{$(datarootdir)/info}. (If you are using Autoconf,
589 write it as @samp{@@infodir@@}.) @code{infodir} is separate from
590 @code{docdir} for compatibility with existing practice.
596 Directories for installing documentation files in the particular
597 format. They should all be set to @code{$(docdir)} by default. (If
598 you are using Autoconf, write them as @samp{@@htmldir@@},
599 @samp{@@dvidir@@}, etc.) Packages which supply several translations
600 of their documentation should install them in
601 @samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
602 @var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
605 The directory for object files and libraries of object code. Do not
606 install executables here, they probably ought to go in @file{$(libexecdir)}
607 instead. The value of @code{libdir} should normally be
608 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
609 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
612 The directory for installing any Emacs Lisp files in this package. By
613 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
614 should be written as @file{$(datarootdir)/emacs/site-lisp}.
616 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
617 In order to make @samp{@@lispdir@@} work, you need the following lines
618 in your @file{configure.ac} file:
621 lispdir='$@{datarootdir@}/emacs/site-lisp'
626 The directory for installing locale-specific message catalogs for this
627 package. By default, it should be @file{/usr/local/share/locale}, but
628 it should be written as @file{$(datarootdir)/locale}. (If you are
629 using Autoconf, write it as @samp{@@localedir@@}.) This directory
630 usually has a subdirectory per locale.
633 Unix-style man pages are installed in one of the following:
637 The top-level directory for installing the man pages (if any) for this
638 package. It will normally be @file{/usr/local/share/man}, but you
639 should write it as @file{$(datarootdir)/man}. (If you are using
640 Autoconf, write it as @samp{@@mandir@@}.)
643 The directory for installing section 1 man pages. Write it as
644 @file{$(mandir)/man1}.
646 The directory for installing section 2 man pages. Write it as
647 @file{$(mandir)/man2}
650 @strong{Don't make the primary documentation for any GNU software be a
651 man page. Write a manual in Texinfo instead. Man pages are just for
652 the sake of people running GNU software on Unix, which is a secondary
656 The file name extension for the installed man page. This should contain
657 a period followed by the appropriate digit; it should normally be @samp{.1}.
660 The file name extension for installed section 1 man pages.
662 The file name extension for installed section 2 man pages.
664 Use these names instead of @samp{manext} if the package needs to install man
665 pages in more than one section of the manual.
668 And finally, you should set the following variable:
672 The directory for the sources being compiled. The value of this
673 variable is normally inserted by the @code{configure} shell script.
674 (If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.)
680 @c I have changed some of the comments here slightly to fix an overfull
681 @c hbox, so the make manual can format correctly. --roland
682 # Common prefix for installation directories.
683 # NOTE: This directory must exist when you start the install.
685 datarootdir = $(prefix)/share
686 datadir = $(datarootdir)
687 exec_prefix = $(prefix)
688 # Where to put the executable for the command `gcc'.
689 bindir = $(exec_prefix)/bin
690 # Where to put the directories used by the compiler.
691 libexecdir = $(exec_prefix)/libexec
692 # Where to put the Info files.
693 infodir = $(datarootdir)/info
696 If your program installs a large number of files into one of the
697 standard user-specified directories, it might be useful to group them
698 into a subdirectory particular to that program. If you do this, you
699 should write the @code{install} rule to create these subdirectories.
701 Do not expect the user to include the subdirectory name in the value of
702 any of the variables listed above. The idea of having a uniform set of
703 variable names for installation directories is to enable the user to
704 specify the exact same values for several different GNU packages. In
705 order for this to be useful, all the packages must be designed so that
706 they will work sensibly when the user does so.
708 At times, not all of these variables may be implemented in the current
709 release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we
710 believe all of them are. When any are missing, the descriptions here
711 serve as specifications for what Autoconf will implement. As a
712 programmer, you can either use a development version of Autoconf or
713 avoid using these variables until a stable release is made which
717 @node Standard Targets
718 @section Standard Targets for Users
720 All GNU programs should have the following targets in their Makefiles:
724 Compile the entire program. This should be the default target. This
725 target need not rebuild any documentation files; Info files should
726 normally be included in the distribution, and DVI (and other
727 documentation format) files should be made only when explicitly asked
730 By default, the Make rules should compile and link with @samp{-g}, so
731 that executable programs have debugging symbols. Otherwise, you are
732 essentially helpless in the face of a crash, and it is often far from
733 easy to reproduce with a fresh build.
736 Compile the program and copy the executables, libraries, and so on to
737 the file names where they should reside for actual use. If there is a
738 simple test to verify that a program is properly installed, this target
739 should run that test.
741 Do not strip executables when installing them. This helps eventual
742 debugging that may be needed later, and nowadays disk space is cheap
743 and dynamic loaders typically ensure debug sections are not loaded during
744 normal execution. Users that need stripped binaries may invoke the
745 @code{install-strip} target to do that.
747 If possible, write the @code{install} target rule so that it does not
748 modify anything in the directory where the program was built, provided
749 @samp{make all} has just been done. This is convenient for building the
750 program under one user name and installing it under another.
752 The commands should create all the directories in which files are to be
753 installed, if they don't already exist. This includes the directories
754 specified as the values of the variables @code{prefix} and
755 @code{exec_prefix}, as well as all subdirectories that are needed.
756 One way to do this is by means of an @code{installdirs} target
759 Use @samp{-} before any command for installing a man page, so that
760 @code{make} will ignore any errors. This is in case there are systems
761 that don't have the Unix man page documentation system installed.
763 The way to install Info files is to copy them into @file{$(infodir)}
764 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
765 the @code{install-info} program if it is present. @code{install-info}
766 is a program that edits the Info @file{dir} file to add or update the
767 menu entry for the given Info file; it is part of the Texinfo package.
769 Here is a sample rule to install an Info file that also tries to
770 handle some additional situations, such as @code{install-info} not
773 @comment This example has been carefully formatted for the Make manual.
774 @comment Please do not reformat it without talking to bug-make@gnu.org.
776 do-install-info: foo.info installdirs
778 # Prefer an info file in . to one in srcdir.
779 if test -f foo.info; then d=.; \
780 else d="$(srcdir)"; fi; \
781 $(INSTALL_DATA) $$d/foo.info \
782 "$(DESTDIR)$(infodir)/foo.info"
783 # Run install-info only if it exists.
784 # Use `if' instead of just prepending `-' to the
785 # line so we notice real errors from install-info.
786 # Use `$(SHELL) -c' because some shells do not
787 # fail gracefully when there is an unknown command.
789 if $(SHELL) -c 'install-info --version' \
790 >/dev/null 2>&1; then \
791 install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
792 "$(DESTDIR)$(infodir)/foo.info"; \
796 When writing the @code{install} target, you must classify all the
797 commands into three categories: normal ones, @dfn{pre-installation}
798 commands and @dfn{post-installation} commands. @xref{Install Command
805 These targets install documentation in formats other than Info;
806 they're intended to be called explicitly by the person installing the
807 package, if that format is desired. GNU prefers Info files, so these
808 must be installed by the @code{install} target.
810 When you have many documentation files to install, we recommend that
811 you avoid collisions and clutter by arranging for these targets to
812 install in subdirectories of the appropriate installation directory,
813 such as @code{htmldir}. As one example, if your package has multiple
814 manuals, and you wish to install HTML documentation with many files
815 (such as the ``split'' mode output by @code{makeinfo --html}), you'll
816 certainly want to use subdirectories, or two nodes with the same name
817 in different manuals will overwrite each other.
819 Please make these @code{install-@var{format}} targets invoke the
820 commands for the @var{format} target, for example, by making
821 @var{format} a dependency.
824 Delete all the installed files---the copies that the @samp{install}
825 and @samp{install-*} targets create.
827 This rule should not modify the directories where compilation is done,
828 only the directories where files are installed.
830 The uninstallation commands are divided into three categories, just like
831 the installation commands. @xref{Install Command Categories}.
834 Like @code{install}, but strip the executable files while installing
835 them. In simple cases, this target can use the @code{install} target in
840 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
844 But if the package installs scripts as well as real executables, the
845 @code{install-strip} target can't just refer to the @code{install}
846 target; it has to strip the executables but not the scripts.
848 @code{install-strip} should not strip the executables in the build
849 directory which are being copied for installation. It should only strip
850 the copies that are installed.
852 Normally we do not recommend stripping an executable unless you are sure
853 the program has no bugs. However, it can be reasonable to install a
854 stripped executable for actual execution while saving the unstripped
855 executable elsewhere in case there is a bug.
858 Delete all files in the current directory that are normally created by
859 building the program. Also delete files in other directories if they
860 are created by this makefile. However, don't delete the files that
861 record the configuration. Also preserve files that could be made by
862 building, but normally aren't because the distribution comes with
863 them. There is no need to delete parent directories that were created
864 with @samp{mkdir -p}, since they could have existed anyway.
866 Delete @file{.dvi} files here if they are not part of the distribution.
869 Delete all files in the current directory (or created by this
870 makefile) that are created by configuring or building the program. If
871 you have unpacked the source and built the program without creating
872 any other files, @samp{make distclean} should leave only the files
873 that were in the distribution. However, there is no need to delete
874 parent directories that were created with @samp{mkdir -p}, since they
875 could have existed anyway.
878 Like @samp{clean}, but may refrain from deleting a few files that people
879 normally don't want to recompile. For example, the @samp{mostlyclean}
880 target for GCC does not delete @file{libgcc.a}, because recompiling it
881 is rarely necessary and takes a lot of time.
883 @item maintainer-clean
884 Delete almost everything that can be reconstructed with this Makefile.
885 This typically includes everything deleted by @code{distclean}, plus
886 more: C source files produced by Bison, tags tables, Info files, and
889 The reason we say ``almost everything'' is that running the command
890 @samp{make maintainer-clean} should not delete @file{configure} even
891 if @file{configure} can be remade using a rule in the Makefile. More
892 generally, @samp{make maintainer-clean} should not delete anything
893 that needs to exist in order to run @file{configure} and then begin to
894 build the program. Also, there is no need to delete parent
895 directories that were created with @samp{mkdir -p}, since they could
896 have existed anyway. These are the only exceptions;
897 @code{maintainer-clean} should delete everything else that can be
900 The @samp{maintainer-clean} target is intended to be used by a maintainer of
901 the package, not by ordinary users. You may need special tools to
902 reconstruct some of the files that @samp{make maintainer-clean} deletes.
903 Since these files are normally included in the distribution, we don't
904 take care to make them easy to reconstruct. If you find you need to
905 unpack the full distribution again, don't blame us.
907 To help make users aware of this, the commands for the special
908 @code{maintainer-clean} target should start with these two:
911 @@echo 'This command is intended for maintainers to use; it'
912 @@echo 'deletes files that may need special tools to rebuild.'
916 Update a tags table for this program.
920 Generate any Info files needed. The best way to write the rules is as
926 foo.info: foo.texi chap1.texi chap2.texi
927 $(MAKEINFO) $(srcdir)/foo.texi
931 You must define the variable @code{MAKEINFO} in the Makefile. It should
932 run the @code{makeinfo} program, which is part of the Texinfo
935 Normally a GNU distribution comes with Info files, and that means the
936 Info files are present in the source directory. Therefore, the Make
937 rule for an info file should update it in the source directory. When
938 users build the package, ordinarily Make will not update the Info files
939 because they will already be up to date.
945 Generate documentation files in the given format. These targets
946 should always exist, but any or all can be a no-op if the given output
947 format cannot be generated. These targets should not be dependencies
948 of the @code{all} target; the user must manually invoke them.
950 Here's an example rule for generating DVI files from Texinfo:
955 foo.dvi: foo.texi chap1.texi chap2.texi
956 $(TEXI2DVI) $(srcdir)/foo.texi
960 You must define the variable @code{TEXI2DVI} in the Makefile. It
961 should run the program @code{texi2dvi}, which is part of the Texinfo
962 distribution. (@code{texi2dvi} uses @TeX{} to do the real work of
963 formatting. @TeX{} is not distributed with Texinfo.) Alternatively,
964 write only the dependencies, and allow GNU @code{make} to provide the
967 Here's another example, this one for generating HTML from Texinfo:
972 foo.html: foo.texi chap1.texi chap2.texi
973 $(TEXI2HTML) $(srcdir)/foo.texi
977 Again, you would define the variable @code{TEXI2HTML} in the Makefile;
978 for example, it might run @code{makeinfo --no-split --html}
979 (@command{makeinfo} is part of the Texinfo distribution).
982 Create a distribution tar file for this program. The tar file should be
983 set up so that the file names in the tar file start with a subdirectory
984 name which is the name of the package it is a distribution for. This
985 name can include the version number.
987 For example, the distribution tar file of GCC version 1.40 unpacks into
988 a subdirectory named @file{gcc-1.40}.
990 The easiest way to do this is to create a subdirectory appropriately
991 named, use @code{ln} or @code{cp} to install the proper files in it, and
992 then @code{tar} that subdirectory.
994 Compress the tar file with @code{gzip}. For example, the actual
995 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
996 It is ok to support other free compression formats as well.
998 The @code{dist} target should explicitly depend on all non-source files
999 that are in the distribution, to make sure they are up to date in the
1002 @xref{Releases, , Making Releases}.
1005 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
1009 Perform self-tests (if any). The user must build the program before
1010 running the tests, but need not install the program; you should write
1011 the self-tests so that they work when the program is built but not
1015 The following targets are suggested as conventional names, for programs
1016 in which they are useful.
1020 Perform installation tests (if any). The user must build and install
1021 the program before running the tests. You should not assume that
1022 @file{$(bindir)} is in the search path.
1025 It's useful to add a target named @samp{installdirs} to create the
1026 directories where files are installed, and their parent directories.
1027 There is a script called @file{mkinstalldirs} which is convenient for
1028 this; you can find it in the Gnulib package.
1029 You can use a rule like this:
1031 @comment This has been carefully formatted to look decent in the Make manual.
1032 @comment Please be sure not to make it extend any further to the right.--roland
1034 # Make sure all installation directories (e.g. $(bindir))
1035 # actually exist by making them if necessary.
1036 installdirs: mkinstalldirs
1037 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1038 $(libdir) $(infodir) \
1043 or, if you wish to support @env{DESTDIR} (strongly encouraged),
1046 # Make sure all installation directories (e.g. $(bindir))
1047 # actually exist by making them if necessary.
1048 installdirs: mkinstalldirs
1049 $(srcdir)/mkinstalldirs \
1050 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
1051 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
1055 This rule should not modify the directories where compilation is done.
1056 It should do nothing but create installation directories.
1059 @node Install Command Categories
1060 @section Install Command Categories
1062 @cindex pre-installation commands
1063 @cindex post-installation commands
1064 When writing the @code{install} target, you must classify all the
1065 commands into three categories: normal ones, @dfn{pre-installation}
1066 commands and @dfn{post-installation} commands.
1068 Normal commands move files into their proper places, and set their
1069 modes. They may not alter any files except the ones that come entirely
1070 from the package they belong to.
1072 Pre-installation and post-installation commands may alter other files;
1073 in particular, they can edit global configuration files or data bases.
1075 Pre-installation commands are typically executed before the normal
1076 commands, and post-installation commands are typically run after the
1079 The most common use for a post-installation command is to run
1080 @code{install-info}. This cannot be done with a normal command, since
1081 it alters a file (the Info directory) which does not come entirely and
1082 solely from the package being installed. It is a post-installation
1083 command because it needs to be done after the normal command which
1084 installs the package's Info files.
1086 Most programs don't need any pre-installation commands, but we have the
1087 feature just in case it is needed.
1089 To classify the commands in the @code{install} rule into these three
1090 categories, insert @dfn{category lines} among them. A category line
1091 specifies the category for the commands that follow.
1093 A category line consists of a tab and a reference to a special Make
1094 variable, plus an optional comment at the end. There are three
1095 variables you can use, one for each category; the variable name
1096 specifies the category. Category lines are no-ops in ordinary execution
1097 because these three Make variables are normally undefined (and you
1098 @emph{should not} define them in the makefile).
1100 Here are the three possible category lines, each with a comment that
1101 explains what it means:
1104 $(PRE_INSTALL) # @r{Pre-install commands follow.}
1105 $(POST_INSTALL) # @r{Post-install commands follow.}
1106 $(NORMAL_INSTALL) # @r{Normal commands follow.}
1109 If you don't use a category line at the beginning of the @code{install}
1110 rule, all the commands are classified as normal until the first category
1111 line. If you don't use any category lines, all the commands are
1112 classified as normal.
1114 These are the category lines for @code{uninstall}:
1117 $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
1118 $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
1119 $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
1122 Typically, a pre-uninstall command would be used for deleting entries
1123 from the Info directory.
1125 If the @code{install} or @code{uninstall} target has any dependencies
1126 which act as subroutines of installation, then you should start
1127 @emph{each} dependency's commands with a category line, and start the
1128 main target's commands with a category line also. This way, you can
1129 ensure that each command is placed in the right category regardless of
1130 which of the dependencies actually run.
1132 Pre-installation and post-installation commands should not run any
1133 programs except for these:
1136 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1137 egrep expand expr false fgrep find getopt grep gunzip gzip
1138 hostname install install-info kill ldconfig ln ls md5sum
1139 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1140 test touch true uname xargs yes
1143 @cindex binary packages
1144 The reason for distinguishing the commands in this way is for the sake
1145 of making binary packages. Typically a binary package contains all the
1146 executables and other files that need to be installed, and has its own
1147 method of installing them---so it does not need to run the normal
1148 installation commands. But installing the binary package does need to
1149 execute the pre-installation and post-installation commands.
1151 Programs to build binary packages work by extracting the
1152 pre-installation and post-installation commands. Here is one way of
1153 extracting the pre-installation commands (the @option{-s} option to
1154 @command{make} is needed to silence messages about entering
1158 make -s -n install -o all \
1159 PRE_INSTALL=pre-install \
1160 POST_INSTALL=post-install \
1161 NORMAL_INSTALL=normal-install \
1162 | gawk -f pre-install.awk
1166 where the file @file{pre-install.awk} could contain this:
1169 $0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
1171 $0 ~ /^pre-install[ \t]*$/ @{on = 1@}