OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [newlib-1.18.0/] [etc/] [make-stds.texi] - Blame information for rev 258

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 207 jeremybenn
@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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.