unicodeio: Fix wrong result on FreeBSD.
[gnulib.git] / doc / make-stds.texi
blobb0745a8a3eed87daf4394df476f6e78901819df9
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, 2014, 2015
12 @c 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.3
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.  For more information on portable Makefiles, see
37 @sc{posix} and @ref{Portable Make, Portable Make Programming,, autoconf,
38 Autoconf}.
41 @menu
42 * Makefile Basics::             General conventions for Makefiles.
43 * Utilities in Makefiles::      Utilities to be used in Makefiles.
44 * Command Variables::           Variables for specifying commands.
45 * DESTDIR::                     Supporting staged installs.
46 * Directory Variables::         Variables for installation directories.
47 * Standard Targets::            Standard targets for users.
48 * Install Command Categories::  Three categories of commands in the @samp{install}
49                                   rule: normal, pre-install and post-install.
50 @end menu
52 @node Makefile Basics
53 @section General Conventions for Makefiles
55 Every Makefile should contain this line:
57 @example
58 SHELL = /bin/sh
59 @end example
61 @noindent
62 to avoid trouble on systems where the @code{SHELL} variable might be
63 inherited from the environment.  (This is never a problem with GNU
64 @code{make}.)
66 Different @code{make} programs have incompatible suffix lists and
67 implicit rules, and this sometimes creates confusion or misbehavior.  So
68 it is a good idea to set the suffix list explicitly using only the
69 suffixes you need in the particular Makefile, like this:
71 @example
72 .SUFFIXES:
73 .SUFFIXES: .c .o
74 @end example
76 @noindent
77 The first line clears out the suffix list, the second introduces all
78 suffixes which may be subject to implicit rules in this Makefile.
80 Don't assume that @file{.} is in the path for command execution.  When
81 you need to run programs that are a part of your package during the
82 make, please make sure that it uses @file{./} if the program is built as
83 part of the make or @file{$(srcdir)/} if the file is an unchanging part
84 of the source code.  Without one of these prefixes, the current search
85 path is used.
87 The distinction between @file{./} (the @dfn{build directory}) and
88 @file{$(srcdir)/} (the @dfn{source directory}) is important because
89 users can build in a separate directory using the @samp{--srcdir} option
90 to @file{configure}.  A rule of the form:
92 @smallexample
93 foo.1 : foo.man sedscript
94         sed -f sedscript foo.man > foo.1
95 @end smallexample
97 @noindent
98 will fail when the build directory is not the source directory, because
99 @file{foo.man} and @file{sedscript} are in the source directory.
101 When using GNU @code{make}, relying on @samp{VPATH} to find the source
102 file will work in the case where there is a single dependency file,
103 since the @code{make} automatic variable @samp{$<} will represent the
104 source file wherever it is.  (Many versions of @code{make} set @samp{$<}
105 only in implicit rules.)  A Makefile target like
107 @smallexample
108 foo.o : bar.c
109         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
110 @end smallexample
112 @noindent
113 should instead be written as
115 @smallexample
116 foo.o : bar.c
117         $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
118 @end smallexample
120 @noindent
121 in order to allow @samp{VPATH} to work correctly.  When the target has
122 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
123 way to make the rule work well.  For example, the target above for
124 @file{foo.1} is best written as:
126 @smallexample
127 foo.1 : foo.man sedscript
128         sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@@
129 @end smallexample
131 GNU distributions usually contain some files which are not source
132 files---for example, Info files, and the output from Autoconf, Automake,
133 Bison or Flex.  Since these files normally appear in the source
134 directory, they should always appear in the source directory, not in the
135 build directory.  So Makefile rules to update them should put the
136 updated files in the source directory.
138 However, if a file does not appear in the distribution, then the
139 Makefile should not put it in the source directory, because building a
140 program in ordinary circumstances should not modify the source directory
141 in any way.
143 Try to make the build and installation targets, at least (and all their
144 subtargets) work correctly with a parallel @code{make}.
146 @node Utilities in Makefiles
147 @section Utilities in Makefiles
149 Write the Makefile commands (and any shell scripts, such as
150 @code{configure}) to run under @code{sh} (both the traditional Bourne
151 shell and the @sc{posix} shell), not @code{csh}.  Don't use any
152 special features of @code{ksh} or @code{bash}, or @sc{posix} features
153 not widely supported in traditional Bourne @code{sh}.
155 The @code{configure} script and the Makefile rules for building and
156 installation should not use any utilities directly except these:
158 @c dd find
159 @c gunzip gzip md5sum
160 @c mkfifo mknod tee uname
162 @example
163 awk cat cmp cp diff echo egrep expr false grep install-info ln ls
164 mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
165 @end example
167 Compression programs such as @code{gzip} can be used in the
168 @code{dist} rule.
170 Generally, stick to the widely-supported (usually
171 @sc{posix}-specified) options and features of these programs.  For
172 example, don't use @samp{mkdir -p}, convenient as it may be, because a
173 few systems don't support it at all and with others, it is not safe
174 for parallel execution.  For a list of known incompatibilities, see
175 @ref{Portable Shell, Portable Shell Programming,, autoconf, Autoconf}.
178 It is a good idea to avoid creating symbolic links in makefiles, since a
179 few file systems don't support them.
181 The Makefile rules for building and installation can also use compilers
182 and related programs, but should do so via @code{make} variables so that the
183 user can substitute alternatives.  Here are some of the programs we
184 mean:
186 @example
187 ar bison cc flex install ld ldconfig lex
188 make makeinfo ranlib texi2dvi yacc
189 @end example
191 Use the following @code{make} variables to run those programs:
193 @example
194 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
195 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
196 @end example
198 When you use @code{ranlib} or @code{ldconfig}, you should make sure
199 nothing bad happens if the system does not have the program in question.
200 Arrange to ignore an error from that command, and print a message before
201 the command to tell the user that failure of this command does not mean
202 a problem.  (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
203 this.)
205 If you use symbolic links, you should implement a fallback for systems
206 that don't have symbolic links.
208 Additional utilities that can be used via Make variables are:
210 @example
211 chgrp chmod chown mknod
212 @end example
214 It is ok to use other utilities in Makefile portions (or scripts)
215 intended only for particular systems where you know those utilities
216 exist.
218 @node Command Variables
219 @section Variables for Specifying Commands
221 Makefiles should provide variables for overriding certain commands, options,
222 and so on.
224 In particular, you should run most utility programs via variables.
225 Thus, if you use Bison, have a variable named @code{BISON} whose default
226 value is set with @samp{BISON = bison}, and refer to it with
227 @code{$(BISON)} whenever you need to use Bison.
229 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
230 so on, need not be referred to through variables in this way, since users
231 don't need to replace them with other programs.
233 Each program-name variable should come with an options variable that is
234 used to supply options to the program.  Append @samp{FLAGS} to the
235 program-name variable name to get the options variable name---for
236 example, @code{BISONFLAGS}.  (The names @code{CFLAGS} for the C
237 compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
238 exceptions to this rule, but we keep them because they are standard.)
239 Use @code{CPPFLAGS} in any compilation command that runs the
240 preprocessor, and use @code{LDFLAGS} in any compilation command that
241 does linking as well as in any direct use of @code{ld}.
243 If there are C compiler options that @emph{must} be used for proper
244 compilation of certain files, do not include them in @code{CFLAGS}.
245 Users expect to be able to specify @code{CFLAGS} freely themselves.
246 Instead, arrange to pass the necessary options to the C compiler
247 independently of @code{CFLAGS}, by writing them explicitly in the
248 compilation commands or by defining an implicit rule, like this:
250 @smallexample
251 CFLAGS = -g
252 ALL_CFLAGS = -I. $(CFLAGS)
253 .c.o:
254         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
255 @end smallexample
257 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
258 @emph{required} for proper compilation.  You can consider it a default
259 that is only recommended.  If the package is set up so that it is
260 compiled with GCC by default, then you might as well include @samp{-O}
261 in the default value of @code{CFLAGS} as well.
263 Put @code{CFLAGS} last in the compilation command, after other variables
264 containing compiler options, so the user can use @code{CFLAGS} to
265 override the others.
267 @code{CFLAGS} should be used in every invocation of the C compiler,
268 both those which do compilation and those which do linking.
270 Every Makefile should define the variable @code{INSTALL}, which is the
271 basic command for installing a file into the system.
273 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
274 and @code{INSTALL_DATA}.  (The default for @code{INSTALL_PROGRAM} should
275 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
276 @code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
277 commands for actual installation, for executables and non-executables
278 respectively.  Minimal use of these variables is as follows:
280 @example
281 $(INSTALL_PROGRAM) foo $(bindir)/foo
282 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
283 @end example
285 However, it is preferable to support a @code{DESTDIR} prefix on the
286 target files, as explained in the next section.
288 It is acceptable, but not required, to install multiple files in one
289 command, with the final argument being a directory, as in:
291 @example
292 $(INSTALL_PROGRAM) foo bar baz $(bindir)
293 @end example
296 @node DESTDIR
297 @section @code{DESTDIR}: Support for Staged Installs
299 @vindex DESTDIR
300 @cindex staged installs
301 @cindex installations, staged
303 @code{DESTDIR} is a variable prepended to each installed target file,
304 like this:
306 @example
307 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
308 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
309 @end example
311 The @code{DESTDIR} variable is specified by the user on the @code{make}
312 command line as an absolute file name.  For example:
314 @example
315 make DESTDIR=/tmp/stage install
316 @end example
318 @noindent
319 @code{DESTDIR} should be supported only in the @code{install*} and
320 @code{uninstall*} targets, as those are the only targets where it is
321 useful.
323 If your installation step would normally install
324 @file{/usr/local/bin/foo} and @file{/usr/@/local/@/lib/@/libfoo.a}, then an
325 installation invoked as in the example above would install
326 @file{/tmp/stage/usr/local/bin/foo} and
327 @file{/tmp/stage/usr/local/lib/libfoo.a} instead.
329 Prepending the variable @code{DESTDIR} to each target in this way
330 provides for @dfn{staged installs}, where the installed files are not
331 placed directly into their expected location but are instead copied
332 into a temporary location (@code{DESTDIR}).  However, installed files
333 maintain their relative directory structure and any embedded file names
334 will not be modified.
336 You should not set the value of @code{DESTDIR} in your @file{Makefile}
337 at all; then the files are installed into their expected locations by
338 default.  Also, specifying @code{DESTDIR} should not change the
339 operation of the software in any way, so its value should not be
340 included in any file contents.
342 @code{DESTDIR} support is commonly used in package creation.  It is
343 also helpful to users who want to understand what a given package will
344 install where, and to allow users who don't normally have permissions
345 to install into protected areas to build and install before gaining
346 those permissions.  Finally, it can be useful with tools such as
347 @code{stow}, where code is installed in one place but made to appear
348 to be installed somewhere else using symbolic links or special mount
349 operations.  So, we strongly recommend GNU packages support
350 @code{DESTDIR}, though it is not an absolute requirement.
353 @node Directory Variables
354 @section Variables for Installation Directories
356 Installation directories should always be named by variables, so it is
357 easy to install in a nonstandard place.  The standard names for these
358 variables and the values they should have in GNU packages are
359 described below.  They are based on a standard file system layout;
360 variants of it are used in GNU/Linux and other modern operating
361 systems.
363 Installers are expected to override these values when calling
364 @command{make} (e.g., @kbd{make prefix=/usr install}) or
365 @command{configure} (e.g., @kbd{configure --prefix=/usr}).  GNU
366 packages should not try to guess which value should be appropriate for
367 these variables on the system they are being installed onto: use the
368 default settings specified here so that all GNU packages behave
369 identically, allowing the installer to achieve any desired layout.
371 @cindex directories, creating installation
372 @cindex installation directories, creating
373 All installation directories, and their parent directories, should be
374 created (if necessary) before they are installed into.
376 These first two variables set the root for the installation.  All the
377 other installation directories should be subdirectories of one of
378 these two, and nothing should be directly installed into these two
379 directories.
381 @table @code
382 @item prefix
383 @vindex prefix
384 A prefix used in constructing the default values of the variables listed
385 below.  The default value of @code{prefix} should be @file{/usr/local}.
386 When building the complete GNU system, the prefix will be empty and
387 @file{/usr} will be a symbolic link to @file{/}.
388 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
390 Running @samp{make install} with a different value of @code{prefix} from
391 the one used to build the program should @emph{not} recompile the
392 program.
394 @item exec_prefix
395 @vindex exec_prefix
396 A prefix used in constructing the default values of some of the
397 variables listed below.  The default value of @code{exec_prefix} should
398 be @code{$(prefix)}.
399 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
401 Generally, @code{$(exec_prefix)} is used for directories that contain
402 machine-specific files (such as executables and subroutine libraries),
403 while @code{$(prefix)} is used directly for other directories.
405 Running @samp{make install} with a different value of @code{exec_prefix}
406 from the one used to build the program should @emph{not} recompile the
407 program.
408 @end table
410 Executable programs are installed in one of the following directories.
412 @table @code
413 @item bindir
414 @vindex bindir
415 The directory for installing executable programs that users can run.
416 This should normally be @file{/usr/local/bin}, but write it as
417 @file{$(exec_prefix)/bin}.
418 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
420 @item sbindir
421 @vindex sbindir
422 The directory for installing executable programs that can be run from
423 the shell, but are only generally useful to system administrators.  This
424 should normally be @file{/usr/local/sbin}, but write it as
425 @file{$(exec_prefix)/sbin}.
426 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
428 @item libexecdir
429 @vindex libexecdir
430 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
431 The directory for installing executable programs to be run by other
432 programs rather than by users.  This directory should normally be
433 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
434 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
436 The definition of @samp{libexecdir} is the same for all packages, so
437 you should install your data in a subdirectory thereof.  Most packages
438 install their data under @file{$(libexecdir)/@var{package-name}/},
439 possibly within additional subdirectories thereof, such as
440 @file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}.
441 @end table
443 Data files used by the program during its execution are divided into
444 categories in two ways.
446 @itemize @bullet
447 @item
448 Some files are normally modified by programs; others are never normally
449 modified (though users may edit some of these).
451 @item
452 Some files are architecture-independent and can be shared by all
453 machines at a site; some are architecture-dependent and can be shared
454 only by machines of the same kind and operating system; others may never
455 be shared between two machines.
456 @end itemize
458 This makes for six different possibilities.  However, we want to
459 discourage the use of architecture-dependent files, aside from object
460 files and libraries.  It is much cleaner to make other data files
461 architecture-independent, and it is generally not hard.
463 Here are the variables Makefiles should use to specify directories
464 to put these various kinds of files in:
466 @table @samp
467 @item datarootdir
468 The root of the directory tree for read-only architecture-independent
469 data files.  This should normally be @file{/usr/local/share}, but
470 write it as @file{$(prefix)/share}.  (If you are using Autoconf, write
471 it as @samp{@@datarootdir@@}.)  @samp{datadir}'s default value is
472 based on this variable; so are @samp{infodir}, @samp{mandir}, and
473 others.
475 @item datadir
476 The directory for installing idiosyncratic read-only
477 architecture-independent data files for this program.  This is usually
478 the same place as @samp{datarootdir}, but we use the two separate
479 variables so that you can move these program-specific files without
480 altering the location for Info files, man pages, etc.
482 @c raggedright  (not until next Texinfo release)
483 This should normally be @file{/usr/local/share}, but write it as
484 @file{$(datarootdir)}.  (If you are using Autoconf, write it as
485 @samp{@@datadir@@}.)
486 @c end raggedright
488 The definition of @samp{datadir} is the same for all packages, so you
489 should install your data in a subdirectory thereof.  Most packages
490 install their data under @file{$(datadir)/@var{package-name}/}.
492 @item sysconfdir
493 The directory for installing read-only data files that pertain to a
494 single machine--that is to say, files for configuring a host.  Mailer
495 and network configuration files, @file{/etc/passwd}, and so forth belong
496 here.  All the files in this directory should be ordinary ASCII text
497 files.  This directory should normally be @file{/usr/local/etc}, but
498 write it as @file{$(prefix)/etc}.
499 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
501 Do not install executables here in this directory (they probably belong
502 in @file{$(libexecdir)} or @file{$(sbindir)}).  Also do not install
503 files that are modified in the normal course of their use (programs
504 whose purpose is to change the configuration of the system excluded).
505 Those probably belong in @file{$(localstatedir)}.
507 @item sharedstatedir
508 The directory for installing architecture-independent data files which
509 the programs modify while they run.  This should normally be
510 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
511 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
513 @item localstatedir
514 The directory for installing data files which the programs modify while
515 they run, and that pertain to one specific machine.  Users should never
516 need to modify files in this directory to configure the package's
517 operation; put such configuration information in separate files that go
518 in @file{$(datadir)} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
519 should normally be @file{/usr/local/var}, but write it as
520 @file{$(prefix)/var}.
521 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
523 @item runstatedir
524 The directory for installing data files which the programs modify
525 while they run, that pertain to one specific machine, and which need
526 not persist longer than the execution of the program---which is
527 generally long-lived, for example, until the next reboot.  PID files
528 for system daemons are a typical use.  In addition, this directory
529 should not be cleaned except perhaps at reboot, while the general
530 @file{/tmp} (@code{TMPDIR}) may be cleaned arbitrarily.  This should
531 normally be @file{/var/run}, but write it as
532 @file{$(localstatedir)/run}.  Having it as a separate variable allows
533 the use of @file{/run} if desired, for example.  (If you are using
534 Autoconf 2.70 or later, write it as @samp{@@runstatedir@@}.)
535 @end table
537 These variables specify the directory for installing certain specific
538 types of files, if your program has them.  Every GNU package should
539 have Info files, so every program needs @samp{infodir}, but not all
540 need @samp{libdir} or @samp{lispdir}.
542 @table @samp
543 @item includedir
544 The directory for installing header files to be included by user
545 programs with the C @samp{#include} preprocessor directive.  This
546 should normally be @file{/usr/local/include}, but write it as
547 @file{$(prefix)/include}.
548 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
550 Most compilers other than GCC do not look for header files in directory
551 @file{/usr/local/include}.  So installing the header files this way is
552 only useful with GCC@.  Sometimes this is not a problem because some
553 libraries are only really intended to work with GCC@.  But some libraries
554 are intended to work with other compilers.  They should install their
555 header files in two places, one specified by @code{includedir} and one
556 specified by @code{oldincludedir}.
558 @item oldincludedir
559 The directory for installing @samp{#include} header files for use with
560 compilers other than GCC@.  This should normally be @file{/usr/include}.
561 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
563 The Makefile commands should check whether the value of
564 @code{oldincludedir} is empty.  If it is, they should not try to use
565 it; they should cancel the second installation of the header files.
567 A package should not replace an existing header in this directory unless
568 the header came from the same package.  Thus, if your Foo package
569 provides a header file @file{foo.h}, then it should install the header
570 file in the @code{oldincludedir} directory if either (1) there is no
571 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
572 package.
574 To tell whether @file{foo.h} came from the Foo package, put a magic
575 string in the file---part of a comment---and @code{grep} for that string.
577 @item docdir
578 The directory for installing documentation files (other than Info) for
579 this package.  By default, it should be
580 @file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as
581 @file{$(datarootdir)/doc/@var{yourpkg}}.  (If you are using Autoconf,
582 write it as @samp{@@docdir@@}.)  The @var{yourpkg} subdirectory, which
583 may include a version number, prevents collisions among files with
584 common names, such as @file{README}.
586 @item infodir
587 The directory for installing the Info files for this package.  By
588 default, it should be @file{/usr/local/share/info}, but it should be
589 written as @file{$(datarootdir)/info}.  (If you are using Autoconf,
590 write it as @samp{@@infodir@@}.)  @code{infodir} is separate from
591 @code{docdir} for compatibility with existing practice.
593 @item htmldir
594 @itemx dvidir
595 @itemx pdfdir
596 @itemx psdir
597 Directories for installing documentation files in the particular
598 format.  They should all be set to @code{$(docdir)} by default.  (If
599 you are using Autoconf, write them as @samp{@@htmldir@@},
600 @samp{@@dvidir@@}, etc.)  Packages which supply several translations
601 of their documentation should install them in
602 @samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where
603 @var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}.
605 @item libdir
606 The directory for object files and libraries of object code.  Do not
607 install executables here, they probably ought to go in @file{$(libexecdir)}
608 instead.  The value of @code{libdir} should normally be
609 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
610 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
612 @item lispdir
613 The directory for installing any Emacs Lisp files in this package.  By
614 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
615 should be written as @file{$(datarootdir)/emacs/site-lisp}.
617 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
618 In order to make @samp{@@lispdir@@} work, you need the following lines
619 in your @file{configure.ac} file:
621 @example
622 lispdir='$@{datarootdir@}/emacs/site-lisp'
623 AC_SUBST(lispdir)
624 @end example
626 @item localedir
627 The directory for installing locale-specific message catalogs for this
628 package.  By default, it should be @file{/usr/local/share/locale}, but
629 it should be written as @file{$(datarootdir)/locale}.  (If you are
630 using Autoconf, write it as @samp{@@localedir@@}.)  This directory
631 usually has a subdirectory per locale.
632 @end table
634 Unix-style man pages are installed in one of the following:
636 @table @samp
637 @item mandir
638 The top-level directory for installing the man pages (if any) for this
639 package.  It will normally be @file{/usr/local/share/man}, but you
640 should write it as @file{$(datarootdir)/man}.  (If you are using
641 Autoconf, write it as @samp{@@mandir@@}.)
643 @item man1dir
644 The directory for installing section 1 man pages.  Write it as
645 @file{$(mandir)/man1}.
646 @item man2dir
647 The directory for installing section 2 man pages.  Write it as
648 @file{$(mandir)/man2}
649 @item @dots{}
651 @strong{Don't make the primary documentation for any GNU software be a
652 man page.  Write a manual in Texinfo instead.  Man pages are just for
653 the sake of people running GNU software on Unix, which is a secondary
654 application only.}
656 @item manext
657 The file name extension for the installed man page.  This should contain
658 a period followed by the appropriate digit; it should normally be @samp{.1}.
660 @item man1ext
661 The file name extension for installed section 1 man pages.
662 @item man2ext
663 The file name extension for installed section 2 man pages.
664 @item @dots{}
665 Use these names instead of @samp{manext} if the package needs to install man
666 pages in more than one section of the manual.
667 @end table
669 And finally, you should set the following variable:
671 @table @samp
672 @item srcdir
673 The directory for the sources being compiled.  The value of this
674 variable is normally inserted by the @code{configure} shell script.
675 (If you are using Autoconf, use @samp{srcdir = @@srcdir@@}.)
676 @end table
678 For example:
680 @smallexample
681 @c I have changed some of the comments here slightly to fix an overfull
682 @c hbox, so the make manual can format correctly. --roland
683 # Common prefix for installation directories.
684 # NOTE: This directory must exist when you start the install.
685 prefix = /usr/local
686 datarootdir = $(prefix)/share
687 datadir = $(datarootdir)
688 exec_prefix = $(prefix)
689 # Where to put the executable for the command 'gcc'.
690 bindir = $(exec_prefix)/bin
691 # Where to put the directories used by the compiler.
692 libexecdir = $(exec_prefix)/libexec
693 # Where to put the Info files.
694 infodir = $(datarootdir)/info
695 @end smallexample
697 If your program installs a large number of files into one of the
698 standard user-specified directories, it might be useful to group them
699 into a subdirectory particular to that program.  If you do this, you
700 should write the @code{install} rule to create these subdirectories.
702 Do not expect the user to include the subdirectory name in the value of
703 any of the variables listed above.  The idea of having a uniform set of
704 variable names for installation directories is to enable the user to
705 specify the exact same values for several different GNU packages.  In
706 order for this to be useful, all the packages must be designed so that
707 they will work sensibly when the user does so.
709 At times, not all of these variables may be implemented in the current
710 release of Autoconf and/or Automake; but as of Autoconf@tie{}2.60, we
711 believe all of them are.  When any are missing, the descriptions here
712 serve as specifications for what Autoconf will implement.  As a
713 programmer, you can either use a development version of Autoconf or
714 avoid using these variables until a stable release is made which
715 supports them.
718 @node Standard Targets
719 @section Standard Targets for Users
721 All GNU programs should have the following targets in their Makefiles:
723 @table @samp
724 @item all
725 Compile the entire program.  This should be the default target.  This
726 target need not rebuild any documentation files; Info files should
727 normally be included in the distribution, and DVI (and other
728 documentation format) files should be made only when explicitly asked
729 for.
731 By default, the Make rules should compile and link with @samp{-g}, so
732 that executable programs have debugging symbols.  Otherwise, you are
733 essentially helpless in the face of a crash, and it is often far from
734 easy to reproduce with a fresh build.
736 @item install
737 Compile the program and copy the executables, libraries, and so on to
738 the file names where they should reside for actual use.  If there is a
739 simple test to verify that a program is properly installed, this target
740 should run that test.
742 Do not strip executables when installing them.  This helps eventual
743 debugging that may be needed later, and nowadays disk space is cheap
744 and dynamic loaders typically ensure debug sections are not loaded during
745 normal execution.  Users that need stripped binaries may invoke the
746 @code{install-strip} target to do that.
748 If possible, write the @code{install} target rule so that it does not
749 modify anything in the directory where the program was built, provided
750 @samp{make all} has just been done.  This is convenient for building the
751 program under one user name and installing it under another.
753 The commands should create all the directories in which files are to be
754 installed, if they don't already exist.  This includes the directories
755 specified as the values of the variables @code{prefix} and
756 @code{exec_prefix}, as well as all subdirectories that are needed.
757 One way to do this is by means of an @code{installdirs} target
758 as described below.
760 Use @samp{-} before any command for installing a man page, so that
761 @code{make} will ignore any errors.  This is in case there are systems
762 that don't have the Unix man page documentation system installed.
764 The way to install Info files is to copy them into @file{$(infodir)}
765 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
766 the @code{install-info} program if it is present.  @code{install-info}
767 is a program that edits the Info @file{dir} file to add or update the
768 menu entry for the given Info file; it is part of the Texinfo package.
770 Here is a sample rule to install an Info file that also tries to
771 handle some additional situations, such as @code{install-info} not
772 being present.
774 @comment This example has been carefully formatted for the Make manual.
775 @comment Please do not reformat it without talking to bug-make@gnu.org.
776 @smallexample
777 do-install-info: foo.info installdirs
778         $(NORMAL_INSTALL)
779 # Prefer an info file in . to one in srcdir.
780         if test -f foo.info; then d=.; \
781          else d="$(srcdir)"; fi; \
782         $(INSTALL_DATA) $$d/foo.info \
783           "$(DESTDIR)$(infodir)/foo.info"
784 # Run install-info only if it exists.
785 # Use 'if' instead of just prepending '-' to the
786 # line so we notice real errors from install-info.
787 # Use '$(SHELL) -c' because some shells do not
788 # fail gracefully when there is an unknown command.
789         $(POST_INSTALL)
790         if $(SHELL) -c 'install-info --version' \
791            >/dev/null 2>&1; then \
792           install-info --dir-file="$(DESTDIR)$(infodir)/dir" \
793                        "$(DESTDIR)$(infodir)/foo.info"; \
794         else true; fi
795 @end smallexample
797 When writing the @code{install} target, you must classify all the
798 commands into three categories: normal ones, @dfn{pre-installation}
799 commands and @dfn{post-installation} commands.  @xref{Install Command
800 Categories}.
802 @item install-html
803 @itemx install-dvi
804 @itemx install-pdf
805 @itemx install-ps
806 These targets install documentation in formats other than Info;
807 they're intended to be called explicitly by the person installing the
808 package, if that format is desired.  GNU prefers Info files, so these
809 must be installed by the @code{install} target.
811 When you have many documentation files to install, we recommend that
812 you avoid collisions and clutter by arranging for these targets to
813 install in subdirectories of the appropriate installation directory,
814 such as @code{htmldir}.  As one example, if your package has multiple
815 manuals, and you wish to install HTML documentation with many files
816 (such as the ``split'' mode output by @code{makeinfo --html}), you'll
817 certainly want to use subdirectories, or two nodes with the same name
818 in different manuals will overwrite each other.
820 Please make these @code{install-@var{format}} targets invoke the
821 commands for the @var{format} target, for example, by making
822 @var{format} a dependency.
824 @item uninstall
825 Delete all the installed files---the copies that the @samp{install}
826 and @samp{install-*} targets create.
828 This rule should not modify the directories where compilation is done,
829 only the directories where files are installed.
831 The uninstallation commands are divided into three categories, just like
832 the installation commands.  @xref{Install Command Categories}.
834 @item install-strip
835 Like @code{install}, but strip the executable files while installing
836 them.  In simple cases, this target can use the @code{install} target in
837 a simple way:
839 @smallexample
840 install-strip:
841         $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
842                 install
843 @end smallexample
845 But if the package installs scripts as well as real executables, the
846 @code{install-strip} target can't just refer to the @code{install}
847 target; it has to strip the executables but not the scripts.
849 @code{install-strip} should not strip the executables in the build
850 directory which are being copied for installation.  It should only strip
851 the copies that are installed.
853 Normally we do not recommend stripping an executable unless you are sure
854 the program has no bugs.  However, it can be reasonable to install a
855 stripped executable for actual execution while saving the unstripped
856 executable elsewhere in case there is a bug.
858 @item clean
859 Delete all files in the current directory that are normally created by
860 building the program.  Also delete files in other directories if they
861 are created by this makefile.  However, don't delete the files that
862 record the configuration.  Also preserve files that could be made by
863 building, but normally aren't because the distribution comes with
864 them.  There is no need to delete parent directories that were created
865 with @samp{mkdir -p}, since they could have existed anyway.
867 Delete @file{.dvi} files here if they are not part of the distribution.
869 @item distclean
870 Delete all files in the current directory (or created by this
871 makefile) that are created by configuring or building the program.  If
872 you have unpacked the source and built the program without creating
873 any other files, @samp{make distclean} should leave only the files
874 that were in the distribution.  However, there is no need to delete
875 parent directories that were created with @samp{mkdir -p}, since they
876 could have existed anyway.
878 @item mostlyclean
879 Like @samp{clean}, but may refrain from deleting a few files that people
880 normally don't want to recompile.  For example, the @samp{mostlyclean}
881 target for GCC does not delete @file{libgcc.a}, because recompiling it
882 is rarely necessary and takes a lot of time.
884 @item maintainer-clean
885 Delete almost everything that can be reconstructed with this Makefile.
886 This typically includes everything deleted by @code{distclean}, plus
887 more: C source files produced by Bison, tags tables, Info files, and
888 so on.
890 The reason we say ``almost everything'' is that running the command
891 @samp{make maintainer-clean} should not delete @file{configure} even
892 if @file{configure} can be remade using a rule in the Makefile.  More
893 generally, @samp{make maintainer-clean} should not delete anything
894 that needs to exist in order to run @file{configure} and then begin to
895 build the program.  Also, there is no need to delete parent
896 directories that were created with @samp{mkdir -p}, since they could
897 have existed anyway.  These are the only exceptions;
898 @code{maintainer-clean} should delete everything else that can be
899 rebuilt.
901 The @samp{maintainer-clean} target is intended to be used by a maintainer of
902 the package, not by ordinary users.  You may need special tools to
903 reconstruct some of the files that @samp{make maintainer-clean} deletes.
904 Since these files are normally included in the distribution, we don't
905 take care to make them easy to reconstruct.  If you find you need to
906 unpack the full distribution again, don't blame us.
908 To help make users aware of this, the commands for the special
909 @code{maintainer-clean} target should start with these two:
911 @smallexample
912 @@echo 'This command is intended for maintainers to use; it'
913 @@echo 'deletes files that may need special tools to rebuild.'
914 @end smallexample
916 @item TAGS
917 Update a tags table for this program.
918 @c ADR: how?
920 @item info
921 Generate any Info files needed.  The best way to write the rules is as
922 follows:
924 @smallexample
925 info: foo.info
927 foo.info: foo.texi chap1.texi chap2.texi
928         $(MAKEINFO) $(srcdir)/foo.texi
929 @end smallexample
931 @noindent
932 You must define the variable @code{MAKEINFO} in the Makefile.  It should
933 run the @code{makeinfo} program, which is part of the Texinfo
934 distribution.
936 Normally a GNU distribution comes with Info files, and that means the
937 Info files are present in the source directory.  Therefore, the Make
938 rule for an info file should update it in the source directory.  When
939 users build the package, ordinarily Make will not update the Info files
940 because they will already be up to date.
942 @item dvi
943 @itemx html
944 @itemx pdf
945 @itemx ps
946 Generate documentation files in the given format.  These targets
947 should always exist, but any or all can be a no-op if the given output
948 format cannot be generated.  These targets should not be dependencies
949 of the @code{all} target; the user must manually invoke them.
951 Here's an example rule for generating DVI files from Texinfo:
953 @smallexample
954 dvi: foo.dvi
956 foo.dvi: foo.texi chap1.texi chap2.texi
957         $(TEXI2DVI) $(srcdir)/foo.texi
958 @end smallexample
960 @noindent
961 You must define the variable @code{TEXI2DVI} in the Makefile.  It
962 should run the program @code{texi2dvi}, which is part of the Texinfo
963 distribution.  (@code{texi2dvi} uses @TeX{} to do the real work of
964 formatting. @TeX{} is not distributed with Texinfo.)  Alternatively,
965 write only the dependencies, and allow GNU @code{make} to provide the
966 command.
968 Here's another example, this one for generating HTML from Texinfo:
970 @smallexample
971 html: foo.html
973 foo.html: foo.texi chap1.texi chap2.texi
974         $(TEXI2HTML) $(srcdir)/foo.texi
975 @end smallexample
977 @noindent
978 Again, you would define the variable @code{TEXI2HTML} in the Makefile;
979 for example, it might run @code{makeinfo --no-split --html}
980 (@command{makeinfo} is part of the Texinfo distribution).
982 @item dist
983 Create a distribution tar file for this program.  The tar file should be
984 set up so that the file names in the tar file start with a subdirectory
985 name which is the name of the package it is a distribution for.  This
986 name can include the version number.
988 For example, the distribution tar file of GCC version 1.40 unpacks into
989 a subdirectory named @file{gcc-1.40}.
991 The easiest way to do this is to create a subdirectory appropriately
992 named, use @code{ln} or @code{cp} to install the proper files in it, and
993 then @code{tar} that subdirectory.
995 Compress the tar file with @code{gzip}.  For example, the actual
996 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
997 It is ok to support other free compression formats as well.
999 The @code{dist} target should explicitly depend on all non-source files
1000 that are in the distribution, to make sure they are up to date in the
1001 distribution.
1002 @ifset CODESTD
1003 @xref{Releases, , Making Releases}.
1004 @end ifset
1005 @ifclear CODESTD
1006 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
1007 @end ifclear
1009 @item check
1010 Perform self-tests (if any).  The user must build the program before
1011 running the tests, but need not install the program; you should write
1012 the self-tests so that they work when the program is built but not
1013 installed.
1014 @end table
1016 The following targets are suggested as conventional names, for programs
1017 in which they are useful.
1019 @table @code
1020 @item installcheck
1021 Perform installation tests (if any).  The user must build and install
1022 the program before running the tests.  You should not assume that
1023 @file{$(bindir)} is in the search path.
1025 @item installdirs
1026 It's useful to add a target named @samp{installdirs} to create the
1027 directories where files are installed, and their parent directories.
1028 There is a script called @file{mkinstalldirs} which is convenient for
1029 this; you can find it in the Gnulib package.
1030 You can use a rule like this:
1032 @comment This has been carefully formatted to look decent in the Make manual.
1033 @comment Please be sure not to make it extend any further to the right.--roland
1034 @smallexample
1035 # Make sure all installation directories (e.g. $(bindir))
1036 # actually exist by making them if necessary.
1037 installdirs: mkinstalldirs
1038         $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1039                                 $(libdir) $(infodir) \
1040                                 $(mandir)
1041 @end smallexample
1043 @noindent
1044 or, if you wish to support @env{DESTDIR} (strongly encouraged),
1046 @smallexample
1047 # Make sure all installation directories (e.g. $(bindir))
1048 # actually exist by making them if necessary.
1049 installdirs: mkinstalldirs
1050         $(srcdir)/mkinstalldirs \
1051             $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
1052             $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
1053             $(DESTDIR)$(mandir)
1054 @end smallexample
1056 This rule should not modify the directories where compilation is done.
1057 It should do nothing but create installation directories.
1058 @end table
1060 @node Install Command Categories
1061 @section Install Command Categories
1063 @cindex pre-installation commands
1064 @cindex post-installation commands
1065 When writing the @code{install} target, you must classify all the
1066 commands into three categories: normal ones, @dfn{pre-installation}
1067 commands and @dfn{post-installation} commands.
1069 Normal commands move files into their proper places, and set their
1070 modes.  They may not alter any files except the ones that come entirely
1071 from the package they belong to.
1073 Pre-installation and post-installation commands may alter other files;
1074 in particular, they can edit global configuration files or data bases.
1076 Pre-installation commands are typically executed before the normal
1077 commands, and post-installation commands are typically run after the
1078 normal commands.
1080 The most common use for a post-installation command is to run
1081 @code{install-info}.  This cannot be done with a normal command, since
1082 it alters a file (the Info directory) which does not come entirely and
1083 solely from the package being installed.  It is a post-installation
1084 command because it needs to be done after the normal command which
1085 installs the package's Info files.
1087 Most programs don't need any pre-installation commands, but we have the
1088 feature just in case it is needed.
1090 To classify the commands in the @code{install} rule into these three
1091 categories, insert @dfn{category lines} among them.  A category line
1092 specifies the category for the commands that follow.
1094 A category line consists of a tab and a reference to a special Make
1095 variable, plus an optional comment at the end.  There are three
1096 variables you can use, one for each category; the variable name
1097 specifies the category.  Category lines are no-ops in ordinary execution
1098 because these three Make variables are normally undefined (and you
1099 @emph{should not} define them in the makefile).
1101 Here are the three possible category lines, each with a comment that
1102 explains what it means:
1104 @smallexample
1105         $(PRE_INSTALL)     # @r{Pre-install commands follow.}
1106         $(POST_INSTALL)    # @r{Post-install commands follow.}
1107         $(NORMAL_INSTALL)  # @r{Normal commands follow.}
1108 @end smallexample
1110 If you don't use a category line at the beginning of the @code{install}
1111 rule, all the commands are classified as normal until the first category
1112 line.  If you don't use any category lines, all the commands are
1113 classified as normal.
1115 These are the category lines for @code{uninstall}:
1117 @smallexample
1118         $(PRE_UNINSTALL)     # @r{Pre-uninstall commands follow.}
1119         $(POST_UNINSTALL)    # @r{Post-uninstall commands follow.}
1120         $(NORMAL_UNINSTALL)  # @r{Normal commands follow.}
1121 @end smallexample
1123 Typically, a pre-uninstall command would be used for deleting entries
1124 from the Info directory.
1126 If the @code{install} or @code{uninstall} target has any dependencies
1127 which act as subroutines of installation, then you should start
1128 @emph{each} dependency's commands with a category line, and start the
1129 main target's commands with a category line also.  This way, you can
1130 ensure that each command is placed in the right category regardless of
1131 which of the dependencies actually run.
1133 Pre-installation and post-installation commands should not run any
1134 programs except for these:
1136 @example
1137 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
1138 egrep expand expr false fgrep find getopt grep gunzip gzip
1139 hostname install install-info kill ldconfig ln ls md5sum
1140 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
1141 test touch true uname xargs yes
1142 @end example
1144 @cindex binary packages
1145 The reason for distinguishing the commands in this way is for the sake
1146 of making binary packages.  Typically a binary package contains all the
1147 executables and other files that need to be installed, and has its own
1148 method of installing them---so it does not need to run the normal
1149 installation commands.  But installing the binary package does need to
1150 execute the pre-installation and post-installation commands.
1152 Programs to build binary packages work by extracting the
1153 pre-installation and post-installation commands.  Here is one way of
1154 extracting the pre-installation commands (the @option{-s} option to
1155 @command{make} is needed to silence messages about entering
1156 subdirectories):
1158 @smallexample
1159 make -s -n install -o all \
1160       PRE_INSTALL=pre-install \
1161       POST_INSTALL=post-install \
1162       NORMAL_INSTALL=normal-install \
1163   | gawk -f pre-install.awk
1164 @end smallexample
1166 @noindent
1167 where the file @file{pre-install.awk} could contain this:
1169 @smallexample
1170 $0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@}
1171 on @{print $0@}
1172 $0 ~ /^pre-install[ \t]*$/ @{on = 1@}
1173 @end smallexample