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