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