Mercurial > hg > xemacs-beta

comparison man/make-stds.texi @ 428:3ecd8885ac67 r21-2-22

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-2-22
author cvs
date Mon, 13 Aug 2007 11:28:15 +0200
parents
children abe6d1db359e
comparison
equal deleted inserted replaced
427:0a0253eac470 428:3ecd8885ac67
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 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 each of these should be
253 @code{$(INSTALL)}.) Then it should use those variables as the commands
254 for actual installation, for executables and nonexecutables
255 respectively. Use these variables as follows:
256
257 @example
258 $(INSTALL_PROGRAM) foo $(bindir)/foo
259 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
260 @end example
261
262 Optionally, you may prepend the value of @code{DESTDIR} to the target
263 filename. Doing this allows the installer to create a snapshot of the
264 installation to be copied onto the real target filesystem later. Do not
265 set the value of @code{DESTDIR} in your Makefile, and do not include it
266 in any installed files. With support for @code{DESTDIR}, the above
267 examples become:
268
269 @example
270 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
271 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
272 @end example
273
274 @noindent
275 Always use a file name, not a directory name, as the second argument of
276 the installation commands. Use a separate command for each file to be
277 installed.
278
279 @node Directory Variables
280 @section Variables for Installation Directories
281
282 Installation directories should always be named by variables, so it is
283 easy to install in a nonstandard place. The standard names for these
284 variables are described below. They are based on a standard filesystem
285 layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
286 other modern operating systems.
287
288 These two variables set the root for the installation. All the other
289 installation directories should be subdirectories of one of these two,
290 and nothing should be directly installed into these two directories.
291
292 @table @samp
293 @item prefix
294 A prefix used in constructing the default values of the variables listed
295 below. The default value of @code{prefix} should be @file{/usr/local}.
296 When building the complete GNU system, the prefix will be empty and
297 @file{/usr} will be a symbolic link to @file{/}.
298 (If you are using Autoconf, write it as @samp{@@prefix@@}.)
299
300 Running @samp{make install} with a different value of @code{prefix}
301 from the one used to build the program should @var{not} recompile
302 the program.
303
304 @item exec_prefix
305 A prefix used in constructing the default values of some of the
306 variables listed below. The default value of @code{exec_prefix} should
307 be @code{$(prefix)}.
308 (If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)
309
310 Generally, @code{$(exec_prefix)} is used for directories that contain
311 machine-specific files (such as executables and subroutine libraries),
312 while @code{$(prefix)} is used directly for other directories.
313
314 Running @samp{make install} with a different value of @code{exec_prefix}
315 from the one used to build the program should @var{not} recompile the
316 program.
317 @end table
318
319 Executable programs are installed in one of the following directories.
320
321 @table @samp
322 @item bindir
323 The directory for installing executable programs that users can run.
324 This should normally be @file{/usr/local/bin}, but write it as
325 @file{$(exec_prefix)/bin}.
326 (If you are using Autoconf, write it as @samp{@@bindir@@}.)
327
328 @item sbindir
329 The directory for installing executable programs that can be run from
330 the shell, but are only generally useful to system administrators. This
331 should normally be @file{/usr/local/sbin}, but write it as
332 @file{$(exec_prefix)/sbin}.
333 (If you are using Autoconf, write it as @samp{@@sbindir@@}.)
334
335 @item libexecdir
336 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
337 The directory for installing executable programs to be run by other
338 programs rather than by users. This directory should normally be
339 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
340 (If you are using Autoconf, write it as @samp{@@libexecdir@@}.)
341 @end table
342
343 Data files used by the program during its execution are divided into
344 categories in two ways.
345
346 @itemize @bullet
347 @item
348 Some files are normally modified by programs; others are never normally
349 modified (though users may edit some of these).
350
351 @item
352 Some files are architecture-independent and can be shared by all
353 machines at a site; some are architecture-dependent and can be shared
354 only by machines of the same kind and operating system; others may never
355 be shared between two machines.
356 @end itemize
357
358 This makes for six different possibilities. However, we want to
359 discourage the use of architecture-dependent files, aside from object
360 files and libraries. It is much cleaner to make other data files
361 architecture-independent, and it is generally not hard.
362
363 Therefore, here are the variables Makefiles should use to specify
364 directories:
365
366 @table @samp
367 @item datadir
368 The directory for installing read-only architecture independent data
369 files. This should normally be @file{/usr/local/share}, but write it as
370 @file{$(prefix)/share}.
371 (If you are using Autoconf, write it as @samp{@@datadir@@}.)
372 As a special exception, see @file{$(infodir)}
373 and @file{$(includedir)} below.
374
375 @item sysconfdir
376 The directory for installing read-only data files that pertain to a
377 single machine--that is to say, files for configuring a host. Mailer
378 and network configuration files, @file{/etc/passwd}, and so forth belong
379 here. All the files in this directory should be ordinary ASCII text
380 files. This directory should normally be @file{/usr/local/etc}, but
381 write it as @file{$(prefix)/etc}.
382 (If you are using Autoconf, write it as @samp{@@sysconfdir@@}.)
383
384 Do not install executables here in this directory (they probably belong
385 in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install
386 files that are modified in the normal course of their use (programs
387 whose purpose is to change the configuration of the system excluded).
388 Those probably belong in @file{$(localstatedir)}.
389
390 @item sharedstatedir
391 The directory for installing architecture-independent data files which
392 the programs modify while they run. This should normally be
393 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
394 (If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.)
395
396 @item localstatedir
397 The directory for installing data files which the programs modify while
398 they run, and that pertain to one specific machine. Users should never
399 need to modify files in this directory to configure the package's
400 operation; put such configuration information in separate files that go
401 in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)}
402 should normally be @file{/usr/local/var}, but write it as
403 @file{$(prefix)/var}.
404 (If you are using Autoconf, write it as @samp{@@localstatedir@@}.)
405
406 @item libdir
407 The directory for object files and libraries of object code. Do not
408 install executables here, they probably ought to go in @file{$(libexecdir)}
409 instead. The value of @code{libdir} should normally be
410 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
411 (If you are using Autoconf, write it as @samp{@@libdir@@}.)
412
413 @item infodir
414 The directory for installing the Info files for this package. By
415 default, it should be @file{/usr/local/info}, but it should be written
416 as @file{$(prefix)/info}.
417 (If you are using Autoconf, write it as @samp{@@infodir@@}.)
418
419 @item lispdir
420 The directory for installing any Emacs Lisp files in this package. By
421 default, it should be @file{/usr/local/share/emacs/site-lisp}, but it
422 should be written as @file{$(prefix)/share/emacs/site-lisp}.
423
424 If you are using Autoconf, write the default as @samp{@@lispdir@@}.
425 In order to make @samp{@@lispdir@@} work, you need the following lines
426 in your @file{configure.in} file:
427
428 @example
429 lispdir='$@{datadir@}/emacs/site-lisp'
430 AC_SUBST(lispdir)
431 @end example
432
433 @item includedir
434 @c rewritten to avoid overfull hbox --roland
435 The directory for installing header files to be included by user
436 programs with the C @samp{#include} preprocessor directive. This
437 should normally be @file{/usr/local/include}, but write it as
438 @file{$(prefix)/include}.
439 (If you are using Autoconf, write it as @samp{@@includedir@@}.)
440
441 Most compilers other than GCC do not look for header files in directory
442 @file{/usr/local/include}. So installing the header files this way is
443 only useful with GCC. Sometimes this is not a problem because some
444 libraries are only really intended to work with GCC. But some libraries
445 are intended to work with other compilers. They should install their
446 header files in two places, one specified by @code{includedir} and one
447 specified by @code{oldincludedir}.
448
449 @item oldincludedir
450 The directory for installing @samp{#include} header files for use with
451 compilers other than GCC. This should normally be @file{/usr/include}.
452 (If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.)
453
454 The Makefile commands should check whether the value of
455 @code{oldincludedir} is empty. If it is, they should not try to use
456 it; they should cancel the second installation of the header files.
457
458 A package should not replace an existing header in this directory unless
459 the header came from the same package. Thus, if your Foo package
460 provides a header file @file{foo.h}, then it should install the header
461 file in the @code{oldincludedir} directory if either (1) there is no
462 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
463 package.
464
465 To tell whether @file{foo.h} came from the Foo package, put a magic
466 string in the file---part of a comment---and @code{grep} for that string.
467 @end table
468
469 Unix-style man pages are installed in one of the following:
470
471 @table @samp
472 @item mandir
473 The top-level directory for installing the man pages (if any) for this
474 package. It will normally be @file{/usr/local/man}, but you should
475 write it as @file{$(prefix)/man}.
476 (If you are using Autoconf, write it as @samp{@@mandir@@}.)
477
478 @item man1dir
479 The directory for installing section 1 man pages. Write it as
480 @file{$(mandir)/man1}.
481 @item man2dir
482 The directory for installing section 2 man pages. Write it as
483 @file{$(mandir)/man2}
484 @item @dots{}
485
486 @strong{Don't make the primary documentation for any GNU software be a
487 man page. Write a manual in Texinfo instead. Man pages are just for
488 the sake of people running GNU software on Unix, which is a secondary
489 application only.}
490
491 @item manext
492 The file name extension for the installed man page. This should contain
493 a period followed by the appropriate digit; it should normally be @samp{.1}.
494
495 @item man1ext
496 The file name extension for installed section 1 man pages.
497 @item man2ext
498 The file name extension for installed section 2 man pages.
499 @item @dots{}
500 Use these names instead of @samp{manext} if the package needs to install man
501 pages in more than one section of the manual.
502 @end table
503
504 And finally, you should set the following variable:
505
506 @table @samp
507 @item srcdir
508 The directory for the sources being compiled. The value of this
509 variable is normally inserted by the @code{configure} shell script.
510 (If you are using Autconf, use @samp{srcdir = @@srcdir@@}.)
511 @end table
512
513 For example:
514
515 @smallexample
516 @c I have changed some of the comments here slightly to fix an overfull
517 @c hbox, so the make manual can format correctly. --roland
518 # Common prefix for installation directories.
519 # NOTE: This directory must exist when you start the install.
520 prefix = /usr/local
521 exec_prefix = $(prefix)
522 # Where to put the executable for the command `gcc'.
523 bindir = $(exec_prefix)/bin
524 # Where to put the directories used by the compiler.
525 libexecdir = $(exec_prefix)/libexec
526 # Where to put the Info files.
527 infodir = $(prefix)/info
528 @end smallexample
529
530 If your program installs a large number of files into one of the
531 standard user-specified directories, it might be useful to group them
532 into a subdirectory particular to that program. If you do this, you
533 should write the @code{install} rule to create these subdirectories.
534
535 Do not expect the user to include the subdirectory name in the value of
536 any of the variables listed above. The idea of having a uniform set of
537 variable names for installation directories is to enable the user to
538 specify the exact same values for several different GNU packages. In
539 order for this to be useful, all the packages must be designed so that
540 they will work sensibly when the user does so.
541
542 @node Standard Targets
543 @section Standard Targets for Users
544
545 All GNU programs should have the following targets in their Makefiles:
546
547 @table @samp
548 @item all
549 Compile the entire program. This should be the default target. This
550 target need not rebuild any documentation files; Info files should
551 normally be included in the distribution, and DVI files should be made
552 only when explicitly asked for.
553
554 By default, the Make rules should compile and link with @samp{-g}, so
555 that executable programs have debugging symbols. Users who don't mind
556 being helpless can strip the executables later if they wish.
557
558 @item install
559 Compile the program and copy the executables, libraries, and so on to
560 the file names where they should reside for actual use. If there is a
561 simple test to verify that a program is properly installed, this target
562 should run that test.
563
564 Do not strip executables when installing them. Devil-may-care users can
565 use the @code{install-strip} target to do that.
566
567 If possible, write the @code{install} target rule so that it does not
568 modify anything in the directory where the program was built, provided
569 @samp{make all} has just been done. This is convenient for building the
570 program under one user name and installing it under another.
571
572 The commands should create all the directories in which files are to be
573 installed, if they don't already exist. This includes the directories
574 specified as the values of the variables @code{prefix} and
575 @code{exec_prefix}, as well as all subdirectories that are needed.
576 One way to do this is by means of an @code{installdirs} target
577 as described below.
578
579 Use @samp{-} before any command for installing a man page, so that
580 @code{make} will ignore any errors. This is in case there are systems
581 that don't have the Unix man page documentation system installed.
582
583 The way to install Info files is to copy them into @file{$(infodir)}
584 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
585 the @code{install-info} program if it is present. @code{install-info}
586 is a program that edits the Info @file{dir} file to add or update the
587 menu entry for the given Info file; it is part of the Texinfo package.
588 Here is a sample rule to install an Info file:
589
590 @comment This example has been carefully formatted for the Make manual.
591 @comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
592 @smallexample
593 $(DESTDIR)$(infodir)/foo.info: foo.info
594 $(POST_INSTALL)
595 # There may be a newer info file in . than in srcdir.
596 -if test -f foo.info; then d=.; \
597 else d=$(srcdir); fi; \
598 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \
599 # Run install-info only if it exists.
600 # Use `if' instead of just prepending `-' to the
601 # line so we notice real errors from install-info.
602 # We use `$(SHELL) -c' because some shells do not
603 # fail gracefully when there is an unknown command.
604 if $(SHELL) -c 'install-info --version' \
605 >/dev/null 2>&1; then \
606 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
607 $(DESTDIR)$(infodir)/foo.info; \
608 else true; fi
609 @end smallexample
610
611 When writing the @code{install} target, you must classify all the
612 commands into three categories: normal ones, @dfn{pre-installation}
613 commands and @dfn{post-installation} commands. @xref{Install Command
614 Categories}.
615
616 @item uninstall
617 Delete all the installed files---the copies that the @samp{install}
618 target creates.
619
620 This rule should not modify the directories where compilation is done,
621 only the directories where files are installed.
622
623 The uninstallation commands are divided into three categories, just like
624 the installation commands. @xref{Install Command Categories}.
625
626 @item install-strip
627 Like @code{install}, but strip the executable files while installing
628 them. In many cases, the definition of this target can be very simple:
629
630 @smallexample
631 install-strip:
632 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
633 install
634 @end smallexample
635
636 Normally we do not recommend stripping an executable unless you are sure
637 the program has no bugs. However, it can be reasonable to install a
638 stripped executable for actual execution while saving the unstripped
639 executable elsewhere in case there is a bug.
640
641 @comment The gratuitous blank line here is to make the table look better
642 @comment in the printed Make manual. Please leave it in.
643 @item clean
644
645 Delete all files from the current directory that are normally created by
646 building the program. Don't delete the files that record the
647 configuration. Also preserve files that could be made by building, but
648 normally aren't because the distribution comes with them.
649
650 Delete @file{.dvi} files here if they are not part of the distribution.
651
652 @item distclean
653 Delete all files from the current directory that are created by
654 configuring or building the program. If you have unpacked the source
655 and built the program without creating any other files, @samp{make
656 distclean} should leave only the files that were in the distribution.
657
658 @item mostlyclean
659 Like @samp{clean}, but may refrain from deleting a few files that people
660 normally don't want to recompile. For example, the @samp{mostlyclean}
661 target for GCC does not delete @file{libgcc.a}, because recompiling it
662 is rarely necessary and takes a lot of time.
663
664 @item maintainer-clean
665 Delete almost everything from the current directory that can be
666 reconstructed with this Makefile. This typically includes everything
667 deleted by @code{distclean}, plus more: C source files produced by
668 Bison, tags tables, Info files, and so on.
669
670 The reason we say ``almost everything'' is that running the command
671 @samp{make maintainer-clean} should not delete @file{configure} even if
672 @file{configure} can be remade using a rule in the Makefile. More generally,
673 @samp{make maintainer-clean} should not delete anything that needs to
674 exist in order to run @file{configure} and then begin to build the
675 program. This is the only exception; @code{maintainer-clean} should
676 delete everything else that can be rebuilt.
677
678 The @samp{maintainer-clean} target is intended to be used by a maintainer of
679 the package, not by ordinary users. You may need special tools to
680 reconstruct some of the files that @samp{make maintainer-clean} deletes.
681 Since these files are normally included in the distribution, we don't
682 take care to make them easy to reconstruct. If you find you need to
683 unpack the full distribution again, don't blame us.
684
685 To help make users aware of this, the commands for the special
686 @code{maintainer-clean} target should start with these two:
687
688 @smallexample
689 @@echo 'This command is intended for maintainers to use; it'
690 @@echo 'deletes files that may need special tools to rebuild.'
691 @end smallexample
692
693 @item TAGS
694 Update a tags table for this program.
695 @c ADR: how?
696
697 @item info
698 Generate any Info files needed. The best way to write the rules is as
699 follows:
700
701 @smallexample
702 info: foo.info
703
704 foo.info: foo.texi chap1.texi chap2.texi
705 $(MAKEINFO) $(srcdir)/foo.texi
706 @end smallexample
707
708 @noindent
709 You must define the variable @code{MAKEINFO} in the Makefile. It should
710 run the @code{makeinfo} program, which is part of the Texinfo
711 distribution.
712
713 Normally a GNU distribution comes with Info files, and that means the
714 Info files are present in the source directory. Therefore, the Make
715 rule for an info file should update it in the source directory. When
716 users build the package, ordinarily Make will not update the Info files
717 because they will already be up to date.
718
719 @item dvi
720 Generate DVI files for all Texinfo documentation.
721 For example:
722
723 @smallexample
724 dvi: foo.dvi
725
726 foo.dvi: foo.texi chap1.texi chap2.texi
727 $(TEXI2DVI) $(srcdir)/foo.texi
728 @end smallexample
729
730 @noindent
731 You must define the variable @code{TEXI2DVI} in the Makefile. It should
732 run the program @code{texi2dvi}, which is part of the Texinfo
733 distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work
734 of formatting. @TeX{} is not distributed with Texinfo.} Alternatively,
735 write just the dependencies, and allow GNU @code{make} to provide the command.
736
737 @item dist
738 Create a distribution tar file for this program. The tar file should be
739 set up so that the file names in the tar file start with a subdirectory
740 name which is the name of the package it is a distribution for. This
741 name can include the version number.
742
743 For example, the distribution tar file of GCC version 1.40 unpacks into
744 a subdirectory named @file{gcc-1.40}.
745
746 The easiest way to do this is to create a subdirectory appropriately
747 named, use @code{ln} or @code{cp} to install the proper files in it, and
748 then @code{tar} that subdirectory.
749
750 Compress the tar file file with @code{gzip}. For example, the actual
751 distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}.
752
753 The @code{dist} target should explicitly depend on all non-source files
754 that are in the distribution, to make sure they are up to date in the
755 distribution.
756 @ifset CODESTD
757 @xref{Releases, , Making Releases}.
758 @end ifset
759 @ifclear CODESTD
760 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
761 @end ifclear
762
763 @item check
764 Perform self-tests (if any). The user must build the program before
765 running the tests, but need not install the program; you should write
766 the self-tests so that they work when the program is built but not
767 installed.
768 @end table
769
770 The following targets are suggested as conventional names, for programs
771 in which they are useful.
772
773 @table @code
774 @item installcheck
775 Perform installation tests (if any). The user must build and install
776 the program before running the tests. You should not assume that
777 @file{$(bindir)} is in the search path.
778
779 @item installdirs
780 It's useful to add a target named @samp{installdirs} to create the
781 directories where files are installed, and their parent directories.
782 There is a script called @file{mkinstalldirs} which is convenient for
783 this; you can find it in the Texinfo package.
784 @c It's in /gd/gnu/lib/mkinstalldirs.
785 You can use a rule like this:
786
787 @comment This has been carefully formatted to look decent in the Make manual.
788 @comment Please be sure not to make it extend any further to the right.--roland
789 @smallexample
790 # Make sure all installation directories (e.g. $(bindir))
791 # actually exist by making them if necessary.
792 installdirs: mkinstalldirs
793 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
794 $(libdir) $(infodir) \
795 $(mandir)
796 @end smallexample
797
798 This rule should not modify the directories where compilation is done.
799 It should do nothing but create installation directories.
800 @end table
801
802 @node Install Command Categories
803 @section Install Command Categories
804
805 @cindex pre-installation commands
806 @cindex post-installation commands
807 When writing the @code{install} target, you must classify all the
808 commands into three categories: normal ones, @dfn{pre-installation}
809 commands and @dfn{post-installation} commands.
810
811 Normal commands move files into their proper places, and set their
812 modes. They may not alter any files except the ones that come entirely
813 from the package they belong to.
814
815 Pre-installation and post-installation commands may alter other files;
816 in particular, they can edit global configuration files or data bases.
817
818 Pre-installation commands are typically executed before the normal
819 commands, and post-installation commands are typically run after the
820 normal commands.
821
822 The most common use for a post-installation command is to run
823 @code{install-info}. This cannot be done with a normal command, since
824 it alters a file (the Info directory) which does not come entirely and
825 solely from the package being installed. It is a post-installation
826 command because it needs to be done after the normal command which
827 installs the package's Info files.
828
829 Most programs don't need any pre-installation commands, but we have the
830 feature just in case it is needed.
831
832 To classify the commands in the @code{install} rule into these three
833 categories, insert @dfn{category lines} among them. A category line
834 specifies the category for the commands that follow.
835
836 A category line consists of a tab and a reference to a special Make
837 variable, plus an optional comment at the end. There are three
838 variables you can use, one for each category; the variable name
839 specifies the category. Category lines are no-ops in ordinary execution
840 because these three Make variables are normally undefined (and you
841 @emph{should not} define them in the makefile).
842
843 Here are the three possible category lines, each with a comment that
844 explains what it means:
845
846 @smallexample
847 $(PRE_INSTALL) # @r{Pre-install commands follow.}
848 $(POST_INSTALL) # @r{Post-install commands follow.}
849 $(NORMAL_INSTALL) # @r{Normal commands follow.}
850 @end smallexample
851
852 If you don't use a category line at the beginning of the @code{install}
853 rule, all the commands are classified as normal until the first category
854 line. If you don't use any category lines, all the commands are
855 classified as normal.
856
857 These are the category lines for @code{uninstall}:
858
859 @smallexample
860 $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.}
861 $(POST_UNINSTALL) # @r{Post-uninstall commands follow.}
862 $(NORMAL_UNINSTALL) # @r{Normal commands follow.}
863 @end smallexample
864
865 Typically, a pre-uninstall command would be used for deleting entries
866 from the Info directory.
867
868 If the @code{install} or @code{uninstall} target has any dependencies
869 which act as subroutines of installation, then you should start
870 @emph{each} dependency's commands with a category line, and start the
871 main target's commands with a category line also. This way, you can
872 ensure that each command is placed in the right category regardless of
873 which of the dependencies actually run.
874
875 Pre-installation and post-installation commands should not run any
876 programs except for these:
877
878 @example
879 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
880 egrep expand expr false fgrep find getopt grep gunzip gzip
881 hostname install install-info kill ldconfig ln ls md5sum
882 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
883 test touch true uname xargs yes
884 @end example
885
886 @cindex binary packages
887 The reason for distinguishing the commands in this way is for the sake
888 of making binary packages. Typically a binary package contains all the
889 executables and other files that need to be installed, and has its own
890 method of installing them---so it does not need to run the normal
891 installation commands. But installing the binary package does need to
892 execute the pre-installation and post-installation commands.
893
894 Programs to build binary packages work by extracting the
895 pre-installation and post-installation commands. Here is one way of
896 extracting the pre-installation commands:
897
898 @smallexample
899 make -n install -o all \
900 PRE_INSTALL=pre-install \
901 POST_INSTALL=post-install \
902 NORMAL_INSTALL=normal-install \
903 | gawk -f pre-install.awk
904 @end smallexample
905
906 @noindent
907 where the file @file{pre-install.awk} could contain this:
908
909 @smallexample
910 $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@}
911 on @{print $0@}
912 $0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@}
913 @end smallexample
914
915 The resulting file of pre-installation commands is executed as a shell
916 script as part of installing the binary package.