daily update
[binutils.git] / etc / make-stds.texi
blob91a1ed0302b5fbb73fd276eb994375c5e944f3dc
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 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''.
22 This
23 @ifinfo
24 node
25 @end ifinfo
26 @iftex
27 @ifset CODESTD
28 section
29 @end ifset
30 @ifclear CODESTD
31 chapter
32 @end ifclear
33 @end iftex
34 describes conventions for writing the Makefiles for GNU programs.
35 Using Automake will help you write a Makefile that follows these
36 conventions.
38 @menu
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.
47 @end menu
49 @node Makefile Basics
50 @section General Conventions for Makefiles
52 Every Makefile should contain this line:
54 @example
55 SHELL = /bin/sh
56 @end example
58 @noindent
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
61 @code{make}.)
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:
68 @example
69 .SUFFIXES:
70 .SUFFIXES: .c .o
71 @end example
73 @noindent
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
82 path is used.
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:
89 @smallexample
90 foo.1 : foo.man sedscript
91         sed -e sedscript foo.man > foo.1
92 @end smallexample
94 @noindent
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
104 @smallexample
105 foo.o : bar.c
106         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
107 @end smallexample
109 @noindent
110 should instead be written as
112 @smallexample
113 foo.o : bar.c
114         $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
115 @end smallexample
117 @noindent
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:
123 @smallexample
124 foo.1 : foo.man sedscript
125         sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
126 @end smallexample
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
138 in any way.
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:
153 @c dd find
154 @c gunzip gzip md5sum
155 @c mkfifo mknod tee uname
157 @example
158 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
160 @end example
162 The compression program @code{gzip} can be used in the @code{dist} rule.
164 Stick to the generally supported options for these programs.  For
165 example, don't use @samp{mkdir -p}, convenient as it may be, because
166 most systems don't support it.
168 It is a good idea to avoid creating symbolic links in makefiles, since a
169 few systems don't support them.
171 The Makefile rules for building and installation can also use compilers
172 and related programs, but should do so via @code{make} variables so that the
173 user can substitute alternatives.  Here are some of the programs we
174 mean:
176 @example
177 ar bison cc flex install ld ldconfig lex
178 make makeinfo ranlib texi2dvi yacc
179 @end example
181 Use the following @code{make} variables to run those programs:
183 @example
184 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
185 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
186 @end example
188 When you use @code{ranlib} or @code{ldconfig}, you should make sure
189 nothing bad happens if the system does not have the program in question.
190 Arrange to ignore an error from that command, and print a message before
191 the command to tell the user that failure of this command does not mean
192 a problem.  (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
193 this.)
195 If you use symbolic links, you should implement a fallback for systems
196 that don't have symbolic links.
198 Additional utilities that can be used via Make variables are:
200 @example
201 chgrp chmod chown mknod
202 @end example
204 It is ok to use other utilities in Makefile portions (or scripts)
205 intended only for particular systems where you know those utilities
206 exist.
208 @node Command Variables
209 @section Variables for Specifying Commands
211 Makefiles should provide variables for overriding certain commands, options,
212 and so on.
214 In particular, you should run most utility programs via variables.
215 Thus, if you use Bison, have a variable named @code{BISON} whose default
216 value is set with @samp{BISON = bison}, and refer to it with
217 @code{$(BISON)} whenever you need to use Bison.
219 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
220 so on, need not be referred to through variables in this way, since users
221 don't need to replace them with other programs.
223 Each program-name variable should come with an options variable that is
224 used to supply options to the program.  Append @samp{FLAGS} to the
225 program-name variable name to get the options variable name---for
226 example, @code{BISONFLAGS}.  (The names @code{CFLAGS} for the C
227 compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
228 exceptions to this rule, but we keep them because they are standard.)
229 Use @code{CPPFLAGS} in any compilation command that runs the
230 preprocessor, and use @code{LDFLAGS} in any compilation command that
231 does linking as well as in any direct use of @code{ld}.
233 If there are C compiler options that @emph{must} be used for proper
234 compilation of certain files, do not include them in @code{CFLAGS}.
235 Users expect to be able to specify @code{CFLAGS} freely themselves.
236 Instead, arrange to pass the necessary options to the C compiler
237 independently of @code{CFLAGS}, by writing them explicitly in the
238 compilation commands or by defining an implicit rule, like this:
240 @smallexample
241 CFLAGS = -g
242 ALL_CFLAGS = -I. $(CFLAGS)
243 .c.o:
244         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
245 @end smallexample
247 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
248 @emph{required} for proper compilation.  You can consider it a default
249 that is only recommended.  If the package is set up so that it is
250 compiled with GCC by default, then you might as well include @samp{-O}
251 in the default value of @code{CFLAGS} as well.
253 Put @code{CFLAGS} last in the compilation command, after other variables
254 containing compiler options, so the user can use @code{CFLAGS} to
255 override the others.
257 @code{CFLAGS} should be used in every invocation of the C compiler,
258 both those which do compilation and those which do linking.
260 Every Makefile should define the variable @code{INSTALL}, which is the
261 basic command for installing a file into the system.
263 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
264 and @code{INSTALL_DATA}.  (The default for @code{INSTALL_PROGRAM} should
265 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
266 @code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
267 commands for actual installation, for executables and non-executables
268 respectively.  Minimal use of these variables is as follows:
270 @example
271 $(INSTALL_PROGRAM) foo $(bindir)/foo
272 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
273 @end example
275 However, it is preferable to support a @code{DESTDIR} prefix on the
276 target files, as explained in the next section.
278 @noindent
279 Always use a file name, not a directory name, as the second argument of
280 the installation commands.  Use a separate command for each file to be
281 installed.
284 @node DESTDIR
285 @section @code{DESTDIR}: support for staged installs
287 @vindex DESTDIR
288 @cindex staged installs
289 @cindex installations, staged
291 @code{DESTDIR} is a variable prepended to each installed target file,
292 like this:
294 @example
295 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
296 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
297 @end example
299 The @code{DESTDIR} variable is specified by the user on the @code{make}
300 command line.  For example:
302 @example
303 make DESTDIR=/tmp/stage install
304 @end example
306 @noindent
307 @code{DESTDIR} should be supported only in the @code{install*} and
308 @code{uninstall*} targets, as those are the only targets where it is
309 useful.
311 If your installation step would normally install
312 @file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
313 installation invoked as in the example above would install
314 @file{/tmp/stage/usr/local/bin/foo} and
315 @file{/tmp/stage/usr/local/lib/libfoo.a} instead.
317 Prepending the variable @code{DESTDIR} to each target in this way
318 provides for @dfn{staged installs}, where the installed files are not
319 placed directly into their expected location but are instead copied
320 into a temporary location (@code{DESTDIR}).  However, installed files
321 maintain their relative directory structure and any embedded file names
322 will not be modified.
324 You should not set the value of @code{DESTDIR} in your @file{Makefile}
325 at all; then the files are installed into their expected locations by
326 default.  Also, specifying @code{DESTDIR} should not change the
327 operation of the software in any way, so its value should not be
328 included in any file contents.
330 @code{DESTDIR} support is commonly used in package creation.  It is
331 also helpful to users who want to understand what a given package will
332 install where, and to allow users who don't normally have permissions
333 to install into protected areas to build and install before gaining
334 those permissions.  Finally, it can be useful with tools such as
335 @code{stow}, where code is installed in one place but made to appear
336 to be installed somewhere else using symbolic links or special mount
337 operations.  So, we strongly recommend GNU packages support
338 @code{DESTDIR}, though it is not an absolute requirement.
341 @node Directory Variables
342 @section Variables for Installation Directories
344 Installation directories should always be named by variables, so it is
345 easy to install in a nonstandard place.  The standard names for these
346 variables and the values they should have in GNU packages are
347 described below.  They are based on a standard file system layout;
348 variants of it are used in GNU/Linux and other modern operating
349 systems.
351 Installers are expected to override these values when calling
352 @command{make} (e.g., @kbd{make prefix=/usr install} or
353 @command{configure} (e.g., @kbd{configure --prefix=/usr}).  GNU
354 packages should not try to guess which value should be appropriate for
355 these variables on the system they are being installed onto: use the
356 default settings specified here so that all GNU packages behave
357 identically, allowing the installer to achieve any desired layout.
359 These first two variables set the root for the installation.  All the
360 other installation directories should be subdirectories of one of
361 these two, and nothing should be directly installed into these two
362 directories.
364 @table @code
365 @item prefix
366 @vindex prefix
367 A prefix used in constructing the default values of the variables listed
368 below.  The default value of @code{prefix} should be @file{/usr/local}.
369 When building the complete GNU system, the prefix will be empty and
370 @file{/usr} will be a symbolic link to @file{/}.
371 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
373 Running @samp{make install} with a different value of @code{prefix} from
374 the one used to build the program should @emph{not} recompile the
375 program.
377 @item exec_prefix
378 @vindex exec_prefix
379 A prefix used in constructing the default values of some of the
380 variables listed below.  The default value of @code{exec_prefix} should
381 be @code{$(prefix)}.
382 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
384 Generally, @code{$(exec_prefix)} is used for directories that contain
385 machine-specific files (such as executables and subroutine libraries),
386 while @code{$(prefix)} is used directly for other directories.
388 Running @samp{make install} with a different value of @code{exec_prefix}
389 from the one used to build the program should @emph{not} recompile the
390 program.
391 @end table
393 Executable programs are installed in one of the following directories.
395 @table @code
396 @item bindir
397 @vindex bindir
398 The directory for installing executable programs that users can run.
399 This should normally be @file{/usr/local/bin}, but write it as
400 @file{$(exec_prefix)/bin}.
401 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
403 @item sbindir
404 @vindex sbindir
405 The directory for installing executable programs that can be run from
406 the shell, but are only generally useful to system administrators.  This
407 should normally be @file{/usr/local/sbin}, but write it as
408 @file{$(exec_prefix)/sbin}.
409 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
411 @item libexecdir
412 @vindex libexecdir
413 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
414 The directory for installing executable programs to be run by other
415 programs rather than by users.  This directory should normally be
416 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
417 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
419 The definition of @samp{libexecdir} is the same for all packages, so
420 you should install your data in a subdirectory thereof.  Most packages
421 install their data under @file{$(libexecdir)/@var{package-name}/},
422 possibly within additional subdirectories thereof, such as
423 @file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
424 @end table
426 Data files used by the program during its execution are divided into
427 categories in two ways.
429 @itemize @bullet
430 @item
431 Some files are normally modified by programs; others are never normally
432 modified (though users may edit some of these).
434 @item
435 Some files are architecture-independent and can be shared by all
436 machines at a site; some are architecture-dependent and can be shared
437 only by machines of the same kind and operating system; others may never
438 be shared between two machines.
439 @end itemize
441 This makes for six different possibilities.  However, we want to
442 discourage the use of architecture-dependent files, aside from object
443 files and libraries.  It is much cleaner to make other data files
444 architecture-independent, and it is generally not hard.
446 Here are the variables Makefiles should use to specify directories
447 to put these various kinds of files in:
449 @table @samp
450 @item datarootdir
451 The root of the directory tree for read-only architecture-independent
452 data files.  This should normally be @file{/usr/local/share}, but
453 write it as @file{$(prefix)/share}.  (If you are using Autoconf, write
454 it as @samp{@@datarootdir@@}.)  @samp{datadir}'s default value is
455 based on this variable; so are @samp{infodir}, @samp{mandir}, and
456 others.
458 @item datadir
459 The directory for installing idiosyncratic read-only
460 architecture-independent data files for this program.  This is usually
461 the same place as @samp{datarootdir}, but we use the two separate
462 variables so that you can move these program-specific files without
463 altering the location for Info files, man pages, etc.
465 This should normally be @file{/usr/local/share}, but write it as
466 @file{$(datarootdir)}.  (If you are using Autoconf, write it as
467 @samp{@@datadir@@}.)
469 The definition of @samp{datadir} is the same for all packages, so you
470 should install your data in a subdirectory thereof.  Most packages
471 install their data under @file{$(datadir)/@var{package-name}/}.
473 @item sysconfdir
474 The directory for installing read-only data files that pertain to a
475 single machine--that is to say, files for configuring a host.  Mailer
476 and network configuration files, @file{/etc/passwd}, and so forth belong
477 here.  All the files in this directory should be ordinary ASCII text
478 files.  This directory should normally be @file{/usr/local/etc}, but
479 write it as @file{$(prefix)/etc}.
480 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
482 Do not install executables here in this directory (they probably belong
483 in @file{$(libexecdir)} or @file{$(sbindir)}).  Also do not install
484 files that are modified in the normal course of their use (programs
485 whose purpose is to change the configuration of the system excluded).
486 Those probably belong in @file{$(localstatedir)}.
488 @item sharedstatedir
489 The directory for installing architecture-independent data files which
490 the programs modify while they run.  This should normally be
491 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
492 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
494 @item localstatedir
495 The directory for installing data files which the programs modify while
496 they run, and that pertain to one specific machine.  Users should never
497 need to modify files in this directory to configure the package's
498 operation; put such configuration information in separate files that go
499 in @file{$(datadir)} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
500 should normally be @file{/usr/local/var}, but write it as
501 @file{$(prefix)/var}.
502 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
503 @end table
505 These variables specify the directory for installing certain specific
506 types of files, if your program has them.  Every GNU package should
507 have Info files, so every program needs @samp{infodir}, but not all
508 need @samp{libdir} or @samp{lispdir}.
510 @table @samp
511 @item includedir
512 @c rewritten to avoid overfull hbox --roland
513 The directory for installing header files to be included by user
514 programs with the C @samp{#include} preprocessor directive.  This
515 should normally be @file{/usr/local/include}, but write it as
516 @file{$(prefix)/include}.
517 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
519 Most compilers other than GCC do not look for header files in directory
520 @file{/usr/local/include}.  So installing the header files this way is
521 only useful with GCC.  Sometimes this is not a problem because some
522 libraries are only really intended to work with GCC.  But some libraries
523 are intended to work with other compilers.  They should install their
524 header files in two places, one specified by @code{includedir} and one
525 specified by @code{oldincludedir}.
527 @item oldincludedir
528 The directory for installing @samp{#include} header files for use with
529 compilers other than GCC.  This should normally be @file{/usr/include}.
530 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
532 The Makefile commands should check whether the value of
533 @code{oldincludedir} is empty.  If it is, they should not try to use
534 it; they should cancel the second installation of the header files.
536 A package should not replace an existing header in this directory unless
537 the header came from the same package.  Thus, if your Foo package
538 provides a header file @file{foo.h}, then it should install the header
539 file in the @code{oldincludedir} directory if either (1) there is no
540 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
541 package.
543 To tell whether @file{foo.h} came from the Foo package, put a magic
544 string in the file---part of a comment---and @code{grep} for that string.
546 @item docdir
547 The directory for installing documentation files (other than Info) for
548 this package.  By default, it should be
549 @file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
550 @file{$(datarootdir)/doc/@var{yourpkg}}.  (If you are using Autoconf,
551 write it as @samp{@@docdir@@}.)  The @var{yourpkg} subdirectory, which
552 may include a version number, prevents collisions among files with
553 common names, such as @file{README}.
555 @item infodir
556 The directory for installing the Info files for this package.  By
557 default, it should be @file{/usr/local/share/info}, but it should be
558 written as @file{$(datarootdir)/info}.  (If you are using Autoconf,
559 write it as @samp{@@infodir@@}.)  @code{infodir} is separate from
560 @code{docdir} for compatibility with existing practice.
562 @item htmldir
563 @itemx dvidir
564 @itemx pdfdir
565 @itemx psdir
566 Directories for installing documentation files in the particular
567 format.  They should all be set to @code{$(docdir)} by default.  (If
568 you are using Autoconf, write them as @samp{@@htmldir@@},
569 @samp{@@dvidir@@}, etc.)  Packages which supply several translations
570 of their documentation should install them in
571 @samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
572 @var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
574 @item libdir
575 The directory for object files and libraries of object code.  Do not
576 install executables here, they probably ought to go in @file{$(libexecdir)}
577 instead.  The value of @code{libdir} should normally be
578 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
579 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
581 @item lispdir
582 The directory for installing any Emacs Lisp files in this package.  By
583 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
584 should be written as @file{$(datarootdir)/emacs/site-lisp}.
586 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
587 In order to make @samp{@@lispdir@@} work, you need the following lines
588 in your @file{configure.in} file:
590 @example
591 lispdir='$@{datarootdir@}/emacs/site-lisp'
592 AC_SUBST(lispdir)
593 @end example
595 @item localedir
596 The directory for installing locale-specific message catalogs for this
597 package.  By default, it should be @file{/usr/local/share/locale}, but
598 it should be written as @file{$(datarootdir)/locale}.  (If you are
599 using Autoconf, write it as @samp{@@localedir@@}.)  This directory
600 usually has a subdirectory per locale.
601 @end table
603 Unix-style man pages are installed in one of the following:
605 @table @samp
606 @item mandir
607 The top-level directory for installing the man pages (if any) for this
608 package.  It will normally be @file{/usr/local/share/man}, but you
609 should write it as @file{$(datarootdir)/man}.  (If you are using
610 Autoconf, write it as @samp{@@mandir@@}.)
612 @item man1dir
613 The directory for installing section 1 man pages.  Write it as
614 @file{$(mandir)/man1}.
615 @item man2dir
616 The directory for installing section 2 man pages.  Write it as
617 @file{$(mandir)/man2}
618 @item @dots{}
620 @strong{Don't make the primary documentation for any GNU software be a
621 man page.  Write a manual in Texinfo instead.  Man pages are just for
622 the sake of people running GNU software on Unix, which is a secondary
623 application only.}
625 @item manext
626 The file name extension for the installed man page.  This should contain
627 a period followed by the appropriate digit; it should normally be @samp{.1}.
629 @item man1ext
630 The file name extension for installed section 1 man pages.
631 @item man2ext
632 The file name extension for installed section 2 man pages.
633 @item @dots{}
634 Use these names instead of @samp{manext} if the package needs to install man
635 pages in more than one section of the manual.
636 @end table
638 And finally, you should set the following variable:
640 @table @samp
641 @item srcdir
642 The directory for the sources being compiled.  The value of this
643 variable is normally inserted by the @code{configure} shell script.
644 (If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.)
645 @end table
647 For example:
649 @smallexample
650 @c I have changed some of the comments here slightly to fix an overfull
651 @c hbox, so the make manual can format correctly. --roland
652 # Common prefix for installation directories.
653 # NOTE: This directory must exist when you start the install.
654 prefix = /usr/local
655 datarootdir = $(prefix)/share
656 datadir = $(datarootdir)
657 exec_prefix = $(prefix)
658 # Where to put the executable for the command `gcc'.
659 bindir = $(exec_prefix)/bin
660 # Where to put the directories used by the compiler.
661 libexecdir = $(exec_prefix)/libexec
662 # Where to put the Info files.
663 infodir = $(datarootdir)/info
664 @end smallexample
666 If your program installs a large number of files into one of the
667 standard user-specified directories, it might be useful to group them
668 into a subdirectory particular to that program.  If you do this, you
669 should write the @code{install} rule to create these subdirectories.
671 Do not expect the user to include the subdirectory name in the value of
672 any of the variables listed above.  The idea of having a uniform set of
673 variable names for installation directories is to enable the user to
674 specify the exact same values for several different GNU packages.  In
675 order for this to be useful, all the packages must be designed so that
676 they will work sensibly when the user does so.
678 At times, not all of these variables may be implemented in the current
679 release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we
680 believe all of them are.  When any are missing, the descriptions here
681 serve as specifications for what Autoconf will implement.  As a
682 programmer, you can either use a development version of Autoconf or
683 avoid using these variables until a stable release is made which
684 supports them.
687 @node Standard Targets
688 @section Standard Targets for Users
690 All GNU programs should have the following targets in their Makefiles:
692 @table @samp
693 @item all
694 Compile the entire program.  This should be the default target.  This
695 target need not rebuild any documentation files; Info files should
696 normally be included in the distribution, and DVI (and other
697 documentation format) files should be made only when explicitly asked
698 for.
700 By default, the Make rules should compile and link with @samp{-g}, so
701 that executable programs have debugging symbols.  Users who don't mind
702 being helpless can strip the executables later if they wish.
704 @item install
705 Compile the program and copy the executables, libraries, and so on to
706 the file names where they should reside for actual use.  If there is a
707 simple test to verify that a program is properly installed, this target
708 should run that test.
710 Do not strip executables when installing them.  Devil-may-care users can
711 use the @code{install-strip} target to do that.
713 If possible, write the @code{install} target rule so that it does not
714 modify anything in the directory where the program was built, provided
715 @samp{make all} has just been done.  This is convenient for building the
716 program under one user name and installing it under another.
718 The commands should create all the directories in which files are to be
719 installed, if they don't already exist.  This includes the directories
720 specified as the values of the variables @code{prefix} and
721 @code{exec_prefix}, as well as all subdirectories that are needed.
722 One way to do this is by means of an @code{installdirs} target
723 as described below.
725 Use @samp{-} before any command for installing a man page, so that
726 @code{make} will ignore any errors.  This is in case there are systems
727 that don't have the Unix man page documentation system installed.
729 The way to install Info files is to copy them into @file{$(infodir)}
730 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
731 the @code{install-info} program if it is present.  @code{install-info}
732 is a program that edits the Info @file{dir} file to add or update the
733 menu entry for the given Info file; it is part of the Texinfo package.
734 Here is a sample rule to install an Info file:
736 @comment This example has been carefully formatted for the Make manual.
737 @comment Please do not reformat it without talking to bug-make@gnu.org.
738 @smallexample
739 $(DESTDIR)$(infodir)/foo.info: foo.info
740         $(POST_INSTALL)
741 # There may be a newer info file in . than in srcdir.
742         -if test -f foo.info; then d=.; \
743          else d=$(srcdir); fi; \
744         $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
745 # Run install-info only if it exists.
746 # Use `if' instead of just prepending `-' to the
747 # line so we notice real errors from install-info.
748 # We use `$(SHELL) -c' because some shells do not
749 # fail gracefully when there is an unknown command.
750         if $(SHELL) -c 'install-info --version' \
751            >/dev/null 2>&1; then \
752           install-info --dir-file=$(DESTDIR)$(infodir)/dir \
753                        $(DESTDIR)$(infodir)/foo.info; \
754         else true; fi
755 @end smallexample
757 When writing the @code{install} target, you must classify all the
758 commands into three categories: normal ones, @dfn{pre-installation}
759 commands and @dfn{post-installation} commands.  @xref{Install Command
760 Categories}.
762 @item install-html
763 @itemx install-dvi
764 @itemx install-pdf
765 @itemx install-ps
766 These targets install documentation in formats other than Info;
767 they're intended to be called explicitly by the person installing the
768 package, if that format is desired.  GNU prefers Info files, so these
769 must be installed by the @code{install} target.
771 When you have many documentation files to install, we recommend that
772 you avoid collisions and clutter by arranging for these targets to
773 install in subdirectories of the appropriate installation directory,
774 such as @code{htmldir}.  As one example, if your package has multiple
775 manuals, and you wish to install HTML documentation with many files
776 (such as the ``split'' mode output by @code{makeinfo --html}), you'll
777 certainly want to use subdirectories, or two nodes with the same name
778 in different manuals will overwrite each other.
780 Please make these @code{install-@var{format}} targets invoke the
781 commands for the @var{format} target, for example, by making
782 @var{format} a dependency.
784 @item uninstall
785 Delete all the installed files---the copies that the @samp{install}
786 and @samp{install-*} targets create.
788 This rule should not modify the directories where compilation is done,
789 only the directories where files are installed.
791 The uninstallation commands are divided into three categories, just like
792 the installation commands.  @xref{Install Command Categories}.
794 @item install-strip
795 Like @code{install}, but strip the executable files while installing
796 them.  In simple cases, this target can use the @code{install} target in
797 a simple way:
799 @smallexample
800 install-strip:
801         $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
802                 install
803 @end smallexample
805 But if the package installs scripts as well as real executables, the
806 @code{install-strip} target can't just refer to the @code{install}
807 target; it has to strip the executables but not the scripts.
809 @code{install-strip} should not strip the executables in the build
810 directory which are being copied for installation.  It should only strip
811 the copies that are installed.
813 Normally we do not recommend stripping an executable unless you are sure
814 the program has no bugs.  However, it can be reasonable to install a
815 stripped executable for actual execution while saving the unstripped
816 executable elsewhere in case there is a bug.
818 @comment The gratuitous blank line here is to make the table look better
819 @comment in the printed Make manual.  Please leave it in.
820 @item clean
822 Delete all files in the current directory that are normally created by
823 building the program.  Also delete files in other directories if they
824 are created by this makefile.  However, don't delete the files that
825 record the configuration.  Also preserve files that could be made by
826 building, but normally aren't because the distribution comes with
827 them.  There is no need to delete parent directories that were created
828 with @samp{mkdir -p}, since they could have existed anyway.
830 Delete @file{.dvi} files here if they are not part of the distribution.
832 @item distclean
833 Delete all files in the current directory (or created by this
834 makefile) that are created by configuring or building the program.  If
835 you have unpacked the source and built the program without creating
836 any other files, @samp{make distclean} should leave only the files
837 that were in the distribution.  However, there is no need to delete
838 parent directories that were created with @samp{mkdir -p}, since they
839 could have existed anyway.
841 @item mostlyclean
842 Like @samp{clean}, but may refrain from deleting a few files that people
843 normally don't want to recompile.  For example, the @samp{mostlyclean}
844 target for GCC does not delete @file{libgcc.a}, because recompiling it
845 is rarely necessary and takes a lot of time.
847 @item maintainer-clean
848 Delete almost everything that can be reconstructed with this Makefile.
849 This typically includes everything deleted by @code{distclean}, plus
850 more: C source files produced by Bison, tags tables, Info files, and
851 so on.
853 The reason we say ``almost everything'' is that running the command
854 @samp{make maintainer-clean} should not delete @file{configure} even
855 if @file{configure} can be remade using a rule in the Makefile.  More
856 generally, @samp{make maintainer-clean} should not delete anything
857 that needs to exist in order to run @file{configure} and then begin to
858 build the program.  Also, there is no need to delete parent
859 directories that were created with @samp{mkdir -p}, since they could
860 have existed anyway.  These are the only exceptions;
861 @code{maintainer-clean} should delete everything else that can be
862 rebuilt.
864 The @samp{maintainer-clean} target is intended to be used by a maintainer of
865 the package, not by ordinary users.  You may need special tools to
866 reconstruct some of the files that @samp{make maintainer-clean} deletes.
867 Since these files are normally included in the distribution, we don't
868 take care to make them easy to reconstruct.  If you find you need to
869 unpack the full distribution again, don't blame us.
871 To help make users aware of this, the commands for the special
872 @code{maintainer-clean} target should start with these two:
874 @smallexample
875 @@echo 'This command is intended for maintainers to use; it'
876 @@echo 'deletes files that may need special tools to rebuild.'
877 @end smallexample
879 @item TAGS
880 Update a tags table for this program.
881 @c ADR: how?
883 @item info
884 Generate any Info files needed.  The best way to write the rules is as
885 follows:
887 @smallexample
888 info: foo.info
890 foo.info: foo.texi chap1.texi chap2.texi
891         $(MAKEINFO) $(srcdir)/foo.texi
892 @end smallexample
894 @noindent
895 You must define the variable @code{MAKEINFO} in the Makefile.  It should
896 run the @code{makeinfo} program, which is part of the Texinfo
897 distribution.
899 Normally a GNU distribution comes with Info files, and that means the
900 Info files are present in the source directory.  Therefore, the Make
901 rule for an info file should update it in the source directory.  When
902 users build the package, ordinarily Make will not update the Info files
903 because they will already be up to date.
905 @item dvi
906 @itemx html
907 @itemx pdf
908 @itemx ps
909 Generate documentation files in the given format.  These targets
910 should always exist, but any or all can be a no-op if the given output
911 format cannot be generated.  These targets should not be dependencies
912 of the @code{all} target; the user must manually invoke them.
914 Here's an example rule for generating DVI files from Texinfo:
916 @smallexample
917 dvi: foo.dvi
919 foo.dvi: foo.texi chap1.texi chap2.texi
920         $(TEXI2DVI) $(srcdir)/foo.texi
921 @end smallexample
923 @noindent
924 You must define the variable @code{TEXI2DVI} in the Makefile.  It should
925 run the program @code{texi2dvi}, which is part of the Texinfo
926 distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
927 of formatting. @TeX{} is not distributed with Texinfo.}  Alternatively,
928 write just the dependencies, and allow GNU @code{make} to provide the command.
930 Here's another example, this one for generating HTML from Texinfo:
932 @smallexample
933 html: foo.html
935 foo.html: foo.texi chap1.texi chap2.texi
936         $(TEXI2HTML) $(srcdir)/foo.texi
937 @end smallexample
939 @noindent
940 Again, you would define the variable @code{TEXI2HTML} in the Makefile;
941 for example, it might run @code{makeinfo --no-split --html}
942 (@command{makeinfo} is part of the Texinfo distribution).
944 @item dist
945 Create a distribution tar file for this program.  The tar file should be
946 set up so that the file names in the tar file start with a subdirectory
947 name which is the name of the package it is a distribution for.  This
948 name can include the version number.
950 For example, the distribution tar file of GCC version 1.40 unpacks into
951 a subdirectory named @file{gcc-1.40}.
953 The easiest way to do this is to create a subdirectory appropriately
954 named, use @code{ln} or @code{cp} to install the proper files in it, and
955 then @code{tar} that subdirectory.
957 Compress the tar file with @code{gzip}.  For example, the actual
958 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
960 The @code{dist} target should explicitly depend on all non-source files
961 that are in the distribution, to make sure they are up to date in the
962 distribution.
963 @ifset CODESTD
964 @xref{Releases, , Making Releases}.
965 @end ifset
966 @ifclear CODESTD
967 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
968 @end ifclear
970 @item check
971 Perform self-tests (if any).  The user must build the program before
972 running the tests, but need not install the program; you should write
973 the self-tests so that they work when the program is built but not
974 installed.
975 @end table
977 The following targets are suggested as conventional names, for programs
978 in which they are useful.
980 @table @code
981 @item installcheck
982 Perform installation tests (if any).  The user must build and install
983 the program before running the tests.  You should not assume that
984 @file{$(bindir)} is in the search path.
986 @item installdirs
987 It's useful to add a target named @samp{installdirs} to create the
988 directories where files are installed, and their parent directories.
989 There is a script called @file{mkinstalldirs} which is convenient for
990 this; you can find it in the Texinfo package.
991 @c It's in /gd/gnu/lib/mkinstalldirs.
992 You can use a rule like this:
994 @comment This has been carefully formatted to look decent in the Make manual.
995 @comment Please be sure not to make it extend any further to the right.--roland
996 @smallexample
997 # Make sure all installation directories (e.g. $(bindir))
998 # actually exist by making them if necessary.
999 installdirs: mkinstalldirs
1000         $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1001                                 $(libdir) $(infodir) \
1002                                 $(mandir)
1003 @end smallexample
1005 @noindent
1006 or, if you wish to support @env{DESTDIR},
1008 @smallexample
1009 # Make sure all installation directories (e.g. $(bindir))
1010 # actually exist by making them if necessary.
1011 installdirs: mkinstalldirs
1012         $(srcdir)/mkinstalldirs \
1013             $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
1014             $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
1015             $(DESTDIR)$(mandir)
1016 @end smallexample
1018 This rule should not modify the directories where compilation is done.
1019 It should do nothing but create installation directories.
1020 @end table
1022 @node Install Command Categories
1023 @section Install Command Categories
1025 @cindex pre-installation commands
1026 @cindex post-installation commands
1027 When writing the @code{install} target, you must classify all the
1028 commands into three categories: normal ones, @dfn{pre-installation}
1029 commands and @dfn{post-installation} commands.
1031 Normal commands move files into their proper places, and set their
1032 modes.  They may not alter any files except the ones that come entirely
1033 from the package they belong to.
1035 Pre-installation and post-installation commands may alter other files;
1036 in particular, they can edit global configuration files or data bases.
1038 Pre-installation commands are typically executed before the normal
1039 commands, and post-installation commands are typically run after the
1040 normal commands.
1042 The most common use for a post-installation command is to run
1043 @code{install-info}.  This cannot be done with a normal command, since
1044 it alters a file (the Info directory) which does not come entirely and
1045 solely from the package being installed.  It is a post-installation
1046 command because it needs to be done after the normal command which
1047 installs the package's Info files.
1049 Most programs don't need any pre-installation commands, but we have the
1050 feature just in case it is needed.
1052 To classify the commands in the @code{install} rule into these three
1053 categories, insert @dfn{category lines} among them.  A category line
1054 specifies the category for the commands that follow.
1056 A category line consists of a tab and a reference to a special Make
1057 variable, plus an optional comment at the end.  There are three
1058 variables you can use, one for each category; the variable name
1059 specifies the category.  Category lines are no-ops in ordinary execution
1060 because these three Make variables are normally undefined (and you
1061 @emph{should not} define them in the makefile).
1063 Here are the three possible category lines, each with a comment that
1064 explains what it means:
1066 @smallexample
1067         $(PRE_INSTALL)     # @r{Pre-install commands follow.}
1068         $(POST_INSTALL)    # @r{Post-install commands follow.}
1069         $(NORMAL_INSTALL)  # @r{Normal commands follow.}
1070 @end smallexample
1072 If you don't use a category line at the beginning of the @code{install}
1073 rule, all the commands are classified as normal until the first category
1074 line.  If you don't use any category lines, all the commands are
1075 classified as normal.
1077 These are the category lines for @code{uninstall}:
1079 @smallexample
1080         $(PRE_UNINSTALL)     # @r{Pre-uninstall commands follow.}
1081         $(POST_UNINSTALL)    # @r{Post-uninstall commands follow.}
1082         $(NORMAL_UNINSTALL)  # @r{Normal commands follow.}
1083 @end smallexample
1085 Typically, a pre-uninstall command would be used for deleting entries
1086 from the Info directory.
1088 If the @code{install} or @code{uninstall} target has any dependencies
1089 which act as subroutines of installation, then you should start
1090 @emph{each} dependency's commands with a category line, and start the
1091 main target's commands with a category line also.  This way, you can
1092 ensure that each command is placed in the right category regardless of
1093 which of the dependencies actually run.
1095 Pre-installation and post-installation commands should not run any
1096 programs except for these:
1098 @example
1099 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1100 egrep expand expr false fgrep find getopt grep gunzip gzip
1101 hostname install install-info kill ldconfig ln ls md5sum
1102 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1103 test touch true uname xargs yes
1104 @end example
1106 @cindex binary packages
1107 The reason for distinguishing the commands in this way is for the sake
1108 of making binary packages.  Typically a binary package contains all the
1109 executables and other files that need to be installed, and has its own
1110 method of installing them---so it does not need to run the normal
1111 installation commands.  But installing the binary package does need to
1112 execute the pre-installation and post-installation commands.
1114 Programs to build binary packages work by extracting the
1115 pre-installation and post-installation commands.  Here is one way of
1116 extracting the pre-installation commands (the @option{-s} option to
1117 @command{make} is needed to silence messages about entering
1118 subdirectories):
1120 @smallexample
1121 make -s -n install -o all \
1122       PRE_INSTALL=pre-install \
1123       POST_INSTALL=post-install \
1124       NORMAL_INSTALL=normal-install \
1125   | gawk -f pre-install.awk
1126 @end smallexample
1128 @noindent
1129 where the file @file{pre-install.awk} could contain this:
1131 @smallexample
1132 $0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
1133 on @{print $0@}
1134 $0 ~ /^pre-install[ \t]*$/ @{on = 1@}
1135 @end smallexample