daily update
[binutils.git] / etc / make-stds.texi
blob250867adfcd48c03911d72729014b9267168b31d
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 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free
12 @c 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.1
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 in Makefiles
41 * Command Variables::           Variables for Specifying Commands
42 * Directory Variables::         Variables for Installation Directories
43 * Standard Targets::            Standard Targets for Users
44 * Install Command Categories::  Three categories of commands in the `install'
45                                   rule: normal, pre-install and post-install.
46 @end menu
48 @node Makefile Basics
49 @section General Conventions for Makefiles
51 Every Makefile should contain this line:
53 @example
54 SHELL = /bin/sh
55 @end example
57 @noindent
58 to avoid trouble on systems where the @code{SHELL} variable might be
59 inherited from the environment.  (This is never a problem with GNU
60 @code{make}.)
62 Different @code{make} programs have incompatible suffix lists and
63 implicit rules, and this sometimes creates confusion or misbehavior.  So
64 it is a good idea to set the suffix list explicitly using only the
65 suffixes you need in the particular Makefile, like this:
67 @example
68 .SUFFIXES:
69 .SUFFIXES: .c .o
70 @end example
72 @noindent
73 The first line clears out the suffix list, the second introduces all
74 suffixes which may be subject to implicit rules in this Makefile.
76 Don't assume that @file{.} is in the path for command execution.  When
77 you need to run programs that are a part of your package during the
78 make, please make sure that it uses @file{./} if the program is built as
79 part of the make or @file{$(srcdir)/} if the file is an unchanging part
80 of the source code.  Without one of these prefixes, the current search
81 path is used.
83 The distinction between @file{./} (the @dfn{build directory}) and
84 @file{$(srcdir)/} (the @dfn{source directory}) is important because
85 users can build in a separate directory using the @samp{--srcdir} option
86 to @file{configure}.  A rule of the form:
88 @smallexample
89 foo.1 : foo.man sedscript
90         sed -e sedscript foo.man > foo.1
91 @end smallexample
93 @noindent
94 will fail when the build directory is not the source directory, because
95 @file{foo.man} and @file{sedscript} are in the source directory.
97 When using GNU @code{make}, relying on @samp{VPATH} to find the source
98 file will work in the case where there is a single dependency file,
99 since the @code{make} automatic variable @samp{$<} will represent the
100 source file wherever it is.  (Many versions of @code{make} set @samp{$<}
101 only in implicit rules.)  A Makefile target like
103 @smallexample
104 foo.o : bar.c
105         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
106 @end smallexample
108 @noindent
109 should instead be written as
111 @smallexample
112 foo.o : bar.c
113         $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
114 @end smallexample
116 @noindent
117 in order to allow @samp{VPATH} to work correctly.  When the target has
118 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
119 way to make the rule work well.  For example, the target above for
120 @file{foo.1} is best written as:
122 @smallexample
123 foo.1 : foo.man sedscript
124         sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
125 @end smallexample
127 GNU distributions usually contain some files which are not source
128 files---for example, Info files, and the output from Autoconf, Automake,
129 Bison or Flex.  Since these files normally appear in the source
130 directory, they should always appear in the source directory, not in the
131 build directory.  So Makefile rules to update them should put the
132 updated files in the source directory.
134 However, if a file does not appear in the distribution, then the
135 Makefile should not put it in the source directory, because building a
136 program in ordinary circumstances should not modify the source directory
137 in any way.
139 Try to make the build and installation targets, at least (and all their
140 subtargets) work correctly with a parallel @code{make}.
142 @node Utilities in Makefiles
143 @section Utilities in Makefiles
145 Write the Makefile commands (and any shell scripts, such as
146 @code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
147 special features of @code{ksh} or @code{bash}.
149 The @code{configure} script and the Makefile rules for building and
150 installation should not use any utilities directly except these:
152 @c dd find
153 @c gunzip gzip md5sum
154 @c mkfifo mknod tee uname
156 @example
157 cat cmp cp diff echo egrep expr false grep install-info
158 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
159 @end example
161 The compression program @code{gzip} can be used in the @code{dist} rule.
163 Stick to the generally supported options for these programs.  For
164 example, don't use @samp{mkdir -p}, convenient as it may be, because
165 most systems don't support it.
167 It is a good idea to avoid creating symbolic links in makefiles, since a
168 few systems don't support them.
170 The Makefile rules for building and installation can also use compilers
171 and related programs, but should do so via @code{make} variables so that the
172 user can substitute alternatives.  Here are some of the programs we
173 mean:
175 @example
176 ar bison cc flex install ld ldconfig lex
177 make makeinfo ranlib texi2dvi yacc
178 @end example
180 Use the following @code{make} variables to run those programs:
182 @example
183 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
184 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
185 @end example
187 When you use @code{ranlib} or @code{ldconfig}, you should make sure
188 nothing bad happens if the system does not have the program in question.
189 Arrange to ignore an error from that command, and print a message before
190 the command to tell the user that failure of this command does not mean
191 a problem.  (The Autoconf @samp{AC_PROG_RANLIB} macro can help with
192 this.)
194 If you use symbolic links, you should implement a fallback for systems
195 that don't have symbolic links.
197 Additional utilities that can be used via Make variables are:
199 @example
200 chgrp chmod chown mknod
201 @end example
203 It is ok to use other utilities in Makefile portions (or scripts)
204 intended only for particular systems where you know those utilities
205 exist.
207 @node Command Variables
208 @section Variables for Specifying Commands
210 Makefiles should provide variables for overriding certain commands, options,
211 and so on.
213 In particular, you should run most utility programs via variables.
214 Thus, if you use Bison, have a variable named @code{BISON} whose default
215 value is set with @samp{BISON = bison}, and refer to it with
216 @code{$(BISON)} whenever you need to use Bison.
218 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
219 so on, need not be referred to through variables in this way, since users
220 don't need to replace them with other programs.
222 Each program-name variable should come with an options variable that is
223 used to supply options to the program.  Append @samp{FLAGS} to the
224 program-name variable name to get the options variable name---for
225 example, @code{BISONFLAGS}.  (The names @code{CFLAGS} for the C
226 compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
227 exceptions to this rule, but we keep them because they are standard.)
228 Use @code{CPPFLAGS} in any compilation command that runs the
229 preprocessor, and use @code{LDFLAGS} in any compilation command that
230 does linking as well as in any direct use of @code{ld}.
232 If there are C compiler options that @emph{must} be used for proper
233 compilation of certain files, do not include them in @code{CFLAGS}.
234 Users expect to be able to specify @code{CFLAGS} freely themselves.
235 Instead, arrange to pass the necessary options to the C compiler
236 independently of @code{CFLAGS}, by writing them explicitly in the
237 compilation commands or by defining an implicit rule, like this:
239 @smallexample
240 CFLAGS = -g
241 ALL_CFLAGS = -I. $(CFLAGS)
242 .c.o:
243         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
244 @end smallexample
246 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
247 @emph{required} for proper compilation.  You can consider it a default
248 that is only recommended.  If the package is set up so that it is
249 compiled with GCC by default, then you might as well include @samp{-O}
250 in the default value of @code{CFLAGS} as well.
252 Put @code{CFLAGS} last in the compilation command, after other variables
253 containing compiler options, so the user can use @code{CFLAGS} to
254 override the others.
256 @code{CFLAGS} should be used in every invocation of the C compiler,
257 both those which do compilation and those which do linking.
259 Every Makefile should define the variable @code{INSTALL}, which is the
260 basic command for installing a file into the system.
262 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
263 and @code{INSTALL_DATA}.  (The default for @code{INSTALL_PROGRAM} should
264 be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
265 @code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
266 commands for actual installation, for executables and nonexecutables
267 respectively.  Use these variables as follows:
269 @example
270 $(INSTALL_PROGRAM) foo $(bindir)/foo
271 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
272 @end example
274 Optionally, you may prepend the value of @code{DESTDIR} to the target
275 filename.  Doing this allows the installer to create a snapshot of the
276 installation to be copied onto the real target filesystem later.  Do not
277 set the value of @code{DESTDIR} in your Makefile, and do not include it
278 in any installed files.  With support for @code{DESTDIR}, the above
279 examples become:
281 @example
282 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
283 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
284 @end example
286 @noindent
287 Always use a file name, not a directory name, as the second argument of
288 the installation commands.  Use a separate command for each file to be
289 installed.
291 @node Directory Variables
292 @section Variables for Installation Directories
294 Installation directories should always be named by variables, so it is
295 easy to install in a nonstandard place.  The standard names for these
296 variables are described below.  They are based on a standard filesystem
297 layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4,
298 and other modern operating systems.
300 These two variables set the root for the installation.  All the other
301 installation directories should be subdirectories of one of these two,
302 and nothing should be directly installed into these two directories.
304 @table @code
305 @item prefix
306 @vindex prefix
307 A prefix used in constructing the default values of the variables listed
308 below.  The default value of @code{prefix} should be @file{/usr/local}.
309 When building the complete GNU system, the prefix will be empty and
310 @file{/usr} will be a symbolic link to @file{/}.
311 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
313 Running @samp{make install} with a different value of @code{prefix} from
314 the one used to build the program should @emph{not} recompile the
315 program.
317 @item exec_prefix
318 @vindex exec_prefix
319 A prefix used in constructing the default values of some of the
320 variables listed below.  The default value of @code{exec_prefix} should
321 be @code{$(prefix)}.
322 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
324 Generally, @code{$(exec_prefix)} is used for directories that contain
325 machine-specific files (such as executables and subroutine libraries),
326 while @code{$(prefix)} is used directly for other directories.
328 Running @samp{make install} with a different value of @code{exec_prefix}
329 from the one used to build the program should @emph{not} recompile the
330 program.
331 @end table
333 Executable programs are installed in one of the following directories.
335 @table @code
336 @item bindir
337 @vindex bindir
338 The directory for installing executable programs that users can run.
339 This should normally be @file{/usr/local/bin}, but write it as
340 @file{$(exec_prefix)/bin}.
341 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
343 @item sbindir
344 @vindex sbindir
345 The directory for installing executable programs that can be run from
346 the shell, but are only generally useful to system administrators.  This
347 should normally be @file{/usr/local/sbin}, but write it as
348 @file{$(exec_prefix)/sbin}.
349 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
351 @item libexecdir
352 @vindex libexecdir
353 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
354 The directory for installing executable programs to be run by other
355 programs rather than by users.  This directory should normally be
356 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
357 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
358 @end table
360 Data files used by the program during its execution are divided into
361 categories in two ways.
363 @itemize @bullet
364 @item
365 Some files are normally modified by programs; others are never normally
366 modified (though users may edit some of these).
368 @item
369 Some files are architecture-independent and can be shared by all
370 machines at a site; some are architecture-dependent and can be shared
371 only by machines of the same kind and operating system; others may never
372 be shared between two machines.
373 @end itemize
375 This makes for six different possibilities.  However, we want to
376 discourage the use of architecture-dependent files, aside from object
377 files and libraries.  It is much cleaner to make other data files
378 architecture-independent, and it is generally not hard.
380 Therefore, here are the variables Makefiles should use to specify
381 directories:
383 @table @samp
384 @item datadir
385 The directory for installing read-only architecture independent data
386 files.  This should normally be @file{/usr/local/share}, but write it as
387 @file{$(prefix)/share}.
388 (If you are using Autoconf, write it as @samp{@@datadir@@}.)
389 As a special exception, see @file{$(infodir)}
390 and @file{$(includedir)} below.
392 @item sysconfdir
393 The directory for installing read-only data files that pertain to a
394 single machine--that is to say, files for configuring a host.  Mailer
395 and network configuration files, @file{/etc/passwd}, and so forth belong
396 here.  All the files in this directory should be ordinary ASCII text
397 files.  This directory should normally be @file{/usr/local/etc}, but
398 write it as @file{$(prefix)/etc}.
399 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
401 Do not install executables here in this directory (they probably belong
402 in @file{$(libexecdir)} or @file{$(sbindir)}).  Also do not install
403 files that are modified in the normal course of their use (programs
404 whose purpose is to change the configuration of the system excluded).
405 Those probably belong in @file{$(localstatedir)}.
407 @item sharedstatedir
408 The directory for installing architecture-independent data files which
409 the programs modify while they run.  This should normally be
410 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
411 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
413 @item localstatedir
414 The directory for installing data files which the programs modify while
415 they run, and that pertain to one specific machine.  Users should never
416 need to modify files in this directory to configure the package's
417 operation; put such configuration information in separate files that go
418 in @file{$(datadir)} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
419 should normally be @file{/usr/local/var}, but write it as
420 @file{$(prefix)/var}.
421 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
423 @item libdir
424 The directory for object files and libraries of object code.  Do not
425 install executables here, they probably ought to go in @file{$(libexecdir)}
426 instead.  The value of @code{libdir} should normally be
427 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
428 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
430 @item infodir
431 The directory for installing the Info files for this package.  By
432 default, it should be @file{/usr/local/info}, but it should be written
433 as @file{$(prefix)/info}.
434 (If you are using Autoconf, write it as @samp{@@infodir@@}.)
436 @item lispdir
437 The directory for installing any Emacs Lisp files in this package.  By
438 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
439 should be written as @file{$(prefix)/share/emacs/site-lisp}.
441 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
442 In order to make @samp{@@lispdir@@} work, you need the following lines
443 in your @file{configure.in} file:
445 @example
446 lispdir='$@{datadir@}/emacs/site-lisp'
447 AC_SUBST(lispdir)
448 @end example
450 @item includedir
451 @c rewritten to avoid overfull hbox --roland
452 The directory for installing header files to be included by user
453 programs with the C @samp{#include} preprocessor directive.  This
454 should normally be @file{/usr/local/include}, but write it as
455 @file{$(prefix)/include}.
456 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
458 Most compilers other than GCC do not look for header files in directory
459 @file{/usr/local/include}.  So installing the header files this way is
460 only useful with GCC.  Sometimes this is not a problem because some
461 libraries are only really intended to work with GCC.  But some libraries
462 are intended to work with other compilers.  They should install their
463 header files in two places, one specified by @code{includedir} and one
464 specified by @code{oldincludedir}.
466 @item oldincludedir
467 The directory for installing @samp{#include} header files for use with
468 compilers other than GCC.  This should normally be @file{/usr/include}.
469 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
471 The Makefile commands should check whether the value of
472 @code{oldincludedir} is empty.  If it is, they should not try to use
473 it; they should cancel the second installation of the header files.
475 A package should not replace an existing header in this directory unless
476 the header came from the same package.  Thus, if your Foo package
477 provides a header file @file{foo.h}, then it should install the header
478 file in the @code{oldincludedir} directory if either (1) there is no
479 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
480 package.
482 To tell whether @file{foo.h} came from the Foo package, put a magic
483 string in the file---part of a comment---and @code{grep} for that string.
484 @end table
486 Unix-style man pages are installed in one of the following:
488 @table @samp
489 @item mandir
490 The top-level directory for installing the man pages (if any) for this
491 package.  It will normally be @file{/usr/local/man}, but you should
492 write it as @file{$(prefix)/man}.
493 (If you are using Autoconf, write it as @samp{@@mandir@@}.)
495 @item man1dir
496 The directory for installing section 1 man pages.  Write it as
497 @file{$(mandir)/man1}.
498 @item man2dir
499 The directory for installing section 2 man pages.  Write it as
500 @file{$(mandir)/man2}
501 @item @dots{}
503 @strong{Don't make the primary documentation for any GNU software be a
504 man page.  Write a manual in Texinfo instead.  Man pages are just for
505 the sake of people running GNU software on Unix, which is a secondary
506 application only.}
508 @item manext
509 The file name extension for the installed man page.  This should contain
510 a period followed by the appropriate digit; it should normally be @samp{.1}.
512 @item man1ext
513 The file name extension for installed section 1 man pages.
514 @item man2ext
515 The file name extension for installed section 2 man pages.
516 @item @dots{}
517 Use these names instead of @samp{manext} if the package needs to install man
518 pages in more than one section of the manual.
519 @end table
521 And finally, you should set the following variable:
523 @table @samp
524 @item srcdir
525 The directory for the sources being compiled.  The value of this
526 variable is normally inserted by the @code{configure} shell script.
527 (If you are using Autconf, use @samp{srcdir = @@srcdir@@}.)
528 @end table
530 For example:
532 @smallexample
533 @c I have changed some of the comments here slightly to fix an overfull
534 @c hbox, so the make manual can format correctly. --roland
535 # Common prefix for installation directories.
536 # NOTE: This directory must exist when you start the install.
537 prefix = /usr/local
538 exec_prefix = $(prefix)
539 # Where to put the executable for the command `gcc'.
540 bindir = $(exec_prefix)/bin
541 # Where to put the directories used by the compiler.
542 libexecdir = $(exec_prefix)/libexec
543 # Where to put the Info files.
544 infodir = $(prefix)/info
545 @end smallexample
547 If your program installs a large number of files into one of the
548 standard user-specified directories, it might be useful to group them
549 into a subdirectory particular to that program.  If you do this, you
550 should write the @code{install} rule to create these subdirectories.
552 Do not expect the user to include the subdirectory name in the value of
553 any of the variables listed above.  The idea of having a uniform set of
554 variable names for installation directories is to enable the user to
555 specify the exact same values for several different GNU packages.  In
556 order for this to be useful, all the packages must be designed so that
557 they will work sensibly when the user does so.
559 @node Standard Targets
560 @section Standard Targets for Users
562 All GNU programs should have the following targets in their Makefiles:
564 @table @samp
565 @item all
566 Compile the entire program.  This should be the default target.  This
567 target need not rebuild any documentation files; Info files should
568 normally be included in the distribution, and DVI files should be made
569 only when explicitly asked for.
571 By default, the Make rules should compile and link with @samp{-g}, so
572 that executable programs have debugging symbols.  Users who don't mind
573 being helpless can strip the executables later if they wish.
575 @item install
576 Compile the program and copy the executables, libraries, and so on to
577 the file names where they should reside for actual use.  If there is a
578 simple test to verify that a program is properly installed, this target
579 should run that test.
581 Do not strip executables when installing them.  Devil-may-care users can
582 use the @code{install-strip} target to do that.
584 If possible, write the @code{install} target rule so that it does not
585 modify anything in the directory where the program was built, provided
586 @samp{make all} has just been done.  This is convenient for building the
587 program under one user name and installing it under another.
589 The commands should create all the directories in which files are to be
590 installed, if they don't already exist.  This includes the directories
591 specified as the values of the variables @code{prefix} and
592 @code{exec_prefix}, as well as all subdirectories that are needed.
593 One way to do this is by means of an @code{installdirs} target
594 as described below.
596 Use @samp{-} before any command for installing a man page, so that
597 @code{make} will ignore any errors.  This is in case there are systems
598 that don't have the Unix man page documentation system installed.
600 The way to install Info files is to copy them into @file{$(infodir)}
601 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
602 the @code{install-info} program if it is present.  @code{install-info}
603 is a program that edits the Info @file{dir} file to add or update the
604 menu entry for the given Info file; it is part of the Texinfo package.
605 Here is a sample rule to install an Info file:
607 @comment This example has been carefully formatted for the Make manual.
608 @comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
609 @smallexample
610 $(DESTDIR)$(infodir)/foo.info: foo.info
611         $(POST_INSTALL)
612 # There may be a newer info file in . than in srcdir.
613         -if test -f foo.info; then d=.; \
614          else d=$(srcdir); fi; \
615         $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
616 # Run install-info only if it exists.
617 # Use `if' instead of just prepending `-' to the
618 # line so we notice real errors from install-info.
619 # We use `$(SHELL) -c' because some shells do not
620 # fail gracefully when there is an unknown command.
621         if $(SHELL) -c 'install-info --version' \
622            >/dev/null 2>&1; then \
623           install-info --dir-file=$(DESTDIR)$(infodir)/dir \
624                        $(DESTDIR)$(infodir)/foo.info; \
625         else true; fi
626 @end smallexample
628 When writing the @code{install} target, you must classify all the
629 commands into three categories: normal ones, @dfn{pre-installation}
630 commands and @dfn{post-installation} commands.  @xref{Install Command
631 Categories}.
633 @item uninstall
634 Delete all the installed files---the copies that the @samp{install}
635 target creates.
637 This rule should not modify the directories where compilation is done,
638 only the directories where files are installed.
640 The uninstallation commands are divided into three categories, just like
641 the installation commands.  @xref{Install Command Categories}.
643 @item install-strip
644 Like @code{install}, but strip the executable files while installing
645 them.  In simple cases, this target can use the @code{install} target in
646 a simple way:
648 @smallexample
649 install-strip:
650         $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
651                 install
652 @end smallexample
654 But if the package installs scripts as well as real executables, the
655 @code{install-strip} target can't just refer to the @code{install}
656 target; it has to strip the executables but not the scripts.
658 @code{install-strip} should not strip the executables in the build
659 directory which are being copied for installation.  It should only strip
660 the copies that are installed.
662 Normally we do not recommend stripping an executable unless you are sure
663 the program has no bugs.  However, it can be reasonable to install a
664 stripped executable for actual execution while saving the unstripped
665 executable elsewhere in case there is a bug.
667 @comment The gratuitous blank line here is to make the table look better
668 @comment in the printed Make manual.  Please leave it in.
669 @item clean
671 Delete all files from the current directory that are normally created by
672 building the program.  Don't delete the files that record the
673 configuration.  Also preserve files that could be made by building, but
674 normally aren't because the distribution comes with them.
676 Delete @file{.dvi} files here if they are not part of the distribution.
678 @item distclean
679 Delete all files from the current directory that are created by
680 configuring or building the program.  If you have unpacked the source
681 and built the program without creating any other files, @samp{make
682 distclean} should leave only the files that were in the distribution.
684 @item mostlyclean
685 Like @samp{clean}, but may refrain from deleting a few files that people
686 normally don't want to recompile.  For example, the @samp{mostlyclean}
687 target for GCC does not delete @file{libgcc.a}, because recompiling it
688 is rarely necessary and takes a lot of time.
690 @item maintainer-clean
691 Delete almost everything from the current directory that can be
692 reconstructed with this Makefile.  This typically includes everything
693 deleted by @code{distclean}, plus more: C source files produced by
694 Bison, tags tables, Info files, and so on.
696 The reason we say ``almost everything'' is that running the command
697 @samp{make maintainer-clean} should not delete @file{configure} even if
698 @file{configure} can be remade using a rule in the Makefile.  More generally,
699 @samp{make maintainer-clean} should not delete anything that needs to
700 exist in order to run @file{configure} and then begin to build the
701 program.  This is the only exception; @code{maintainer-clean} should
702 delete everything else that can be rebuilt.
704 The @samp{maintainer-clean} target is intended to be used by a maintainer of
705 the package, not by ordinary users.  You may need special tools to
706 reconstruct some of the files that @samp{make maintainer-clean} deletes.
707 Since these files are normally included in the distribution, we don't
708 take care to make them easy to reconstruct.  If you find you need to
709 unpack the full distribution again, don't blame us.
711 To help make users aware of this, the commands for the special
712 @code{maintainer-clean} target should start with these two:
714 @smallexample
715 @@echo 'This command is intended for maintainers to use; it'
716 @@echo 'deletes files that may need special tools to rebuild.'
717 @end smallexample
719 @item TAGS
720 Update a tags table for this program.
721 @c ADR: how?
723 @item info
724 Generate any Info files needed.  The best way to write the rules is as
725 follows:
727 @smallexample
728 info: foo.info
730 foo.info: foo.texi chap1.texi chap2.texi
731         $(MAKEINFO) $(srcdir)/foo.texi
732 @end smallexample
734 @noindent
735 You must define the variable @code{MAKEINFO} in the Makefile.  It should
736 run the @code{makeinfo} program, which is part of the Texinfo
737 distribution.
739 Normally a GNU distribution comes with Info files, and that means the
740 Info files are present in the source directory.  Therefore, the Make
741 rule for an info file should update it in the source directory.  When
742 users build the package, ordinarily Make will not update the Info files
743 because they will already be up to date.
745 @item dvi
746 Generate DVI files for all Texinfo documentation.
747 For example:
749 @smallexample
750 dvi: foo.dvi
752 foo.dvi: foo.texi chap1.texi chap2.texi
753         $(TEXI2DVI) $(srcdir)/foo.texi
754 @end smallexample
756 @noindent
757 You must define the variable @code{TEXI2DVI} in the Makefile.  It should
758 run the program @code{texi2dvi}, which is part of the Texinfo
759 distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
760 of formatting. @TeX{} is not distributed with Texinfo.}  Alternatively,
761 write just the dependencies, and allow GNU @code{make} to provide the command.
763 @item dist
764 Create a distribution tar file for this program.  The tar file should be
765 set up so that the file names in the tar file start with a subdirectory
766 name which is the name of the package it is a distribution for.  This
767 name can include the version number.
769 For example, the distribution tar file of GCC version 1.40 unpacks into
770 a subdirectory named @file{gcc-1.40}.
772 The easiest way to do this is to create a subdirectory appropriately
773 named, use @code{ln} or @code{cp} to install the proper files in it, and
774 then @code{tar} that subdirectory.
776 Compress the tar file with @code{gzip}.  For example, the actual
777 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
779 The @code{dist} target should explicitly depend on all non-source files
780 that are in the distribution, to make sure they are up to date in the
781 distribution.
782 @ifset CODESTD
783 @xref{Releases, , Making Releases}.
784 @end ifset
785 @ifclear CODESTD
786 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
787 @end ifclear
789 @item check
790 Perform self-tests (if any).  The user must build the program before
791 running the tests, but need not install the program; you should write
792 the self-tests so that they work when the program is built but not
793 installed.
794 @end table
796 The following targets are suggested as conventional names, for programs
797 in which they are useful.
799 @table @code
800 @item installcheck
801 Perform installation tests (if any).  The user must build and install
802 the program before running the tests.  You should not assume that
803 @file{$(bindir)} is in the search path.
805 @item installdirs
806 It's useful to add a target named @samp{installdirs} to create the
807 directories where files are installed, and their parent directories.
808 There is a script called @file{mkinstalldirs} which is convenient for
809 this; you can find it in the Texinfo package.
810 @c It's in /gd/gnu/lib/mkinstalldirs.
811 You can use a rule like this:
813 @comment This has been carefully formatted to look decent in the Make manual.
814 @comment Please be sure not to make it extend any further to the right.--roland
815 @smallexample
816 # Make sure all installation directories (e.g. $(bindir))
817 # actually exist by making them if necessary.
818 installdirs: mkinstalldirs
819         $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
820                                 $(libdir) $(infodir) \
821                                 $(mandir)
822 @end smallexample
824 @noindent
825 or, if you wish to support @env{DESTDIR},
827 @smallexample
828 # Make sure all installation directories (e.g. $(bindir))
829 # actually exist by making them if necessary.
830 installdirs: mkinstalldirs
831         $(srcdir)/mkinstalldirs \
832             $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \
833             $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \
834             $(DESTDIR)$(mandir)
835 @end smallexample
837 This rule should not modify the directories where compilation is done.
838 It should do nothing but create installation directories.
839 @end table
841 @node Install Command Categories
842 @section Install Command Categories
844 @cindex pre-installation commands
845 @cindex post-installation commands
846 When writing the @code{install} target, you must classify all the
847 commands into three categories: normal ones, @dfn{pre-installation}
848 commands and @dfn{post-installation} commands.
850 Normal commands move files into their proper places, and set their
851 modes.  They may not alter any files except the ones that come entirely
852 from the package they belong to.
854 Pre-installation and post-installation commands may alter other files;
855 in particular, they can edit global configuration files or data bases.
857 Pre-installation commands are typically executed before the normal
858 commands, and post-installation commands are typically run after the
859 normal commands.
861 The most common use for a post-installation command is to run
862 @code{install-info}.  This cannot be done with a normal command, since
863 it alters a file (the Info directory) which does not come entirely and
864 solely from the package being installed.  It is a post-installation
865 command because it needs to be done after the normal command which
866 installs the package's Info files.
868 Most programs don't need any pre-installation commands, but we have the
869 feature just in case it is needed.
871 To classify the commands in the @code{install} rule into these three
872 categories, insert @dfn{category lines} among them.  A category line
873 specifies the category for the commands that follow.
875 A category line consists of a tab and a reference to a special Make
876 variable, plus an optional comment at the end.  There are three
877 variables you can use, one for each category; the variable name
878 specifies the category.  Category lines are no-ops in ordinary execution
879 because these three Make variables are normally undefined (and you
880 @emph{should not} define them in the makefile).
882 Here are the three possible category lines, each with a comment that
883 explains what it means:
885 @smallexample
886         $(PRE_INSTALL)     # @r{Pre-install commands follow.}
887         $(POST_INSTALL)    # @r{Post-install commands follow.}
888         $(NORMAL_INSTALL)  # @r{Normal commands follow.}
889 @end smallexample
891 If you don't use a category line at the beginning of the @code{install}
892 rule, all the commands are classified as normal until the first category
893 line.  If you don't use any category lines, all the commands are
894 classified as normal.
896 These are the category lines for @code{uninstall}:
898 @smallexample
899         $(PRE_UNINSTALL)     # @r{Pre-uninstall commands follow.}
900         $(POST_UNINSTALL)    # @r{Post-uninstall commands follow.}
901         $(NORMAL_UNINSTALL)  # @r{Normal commands follow.}
902 @end smallexample
904 Typically, a pre-uninstall command would be used for deleting entries
905 from the Info directory.
907 If the @code{install} or @code{uninstall} target has any dependencies
908 which act as subroutines of installation, then you should start
909 @emph{each} dependency's commands with a category line, and start the
910 main target's commands with a category line also.  This way, you can
911 ensure that each command is placed in the right category regardless of
912 which of the dependencies actually run.
914 Pre-installation and post-installation commands should not run any
915 programs except for these:
917 @example
918 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
919 egrep expand expr false fgrep find getopt grep gunzip gzip
920 hostname install install-info kill ldconfig ln ls md5sum
921 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
922 test touch true uname xargs yes
923 @end example
925 @cindex binary packages
926 The reason for distinguishing the commands in this way is for the sake
927 of making binary packages.  Typically a binary package contains all the
928 executables and other files that need to be installed, and has its own
929 method of installing them---so it does not need to run the normal
930 installation commands.  But installing the binary package does need to
931 execute the pre-installation and post-installation commands.
933 Programs to build binary packages work by extracting the
934 pre-installation and post-installation commands.  Here is one way of
935 extracting the pre-installation commands:
937 @smallexample
938 make -n install -o all \
939       PRE_INSTALL=pre-install \
940       POST_INSTALL=post-install \
941       NORMAL_INSTALL=normal-install \
942   | gawk -f pre-install.awk
943 @end smallexample
945 @noindent
946 where the file @file{pre-install.awk} could contain this:
948 @smallexample
949 $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
950 on @{print $0@}
951 $0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
952 @end smallexample
954 The resulting file of pre-installation commands is executed as a shell
955 script as part of installing the binary package.