|
428
|
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.
|
