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