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