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