1
This is make.info, produced by makeinfo version 4.0 from make.texinfo.
3
INFO-DIR-SECTION GNU Packages
5
* Make: (make). Remake files automatically.
8
This file documents the GNU Make utility, which determines
9
automatically which pieces of a large program need to be recompiled,
10
and issues the commands to recompile them.
12
This is Edition 0.54, last updated 09 September 1999, of `The GNU
13
Make Manual', for `make', Version 3.78.1.
15
Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97,
16
'98, '99 Free Software Foundation, Inc.
18
Permission is granted to make and distribute verbatim copies of this
19
manual provided the copyright notice and this permission notice are
20
preserved on all copies.
22
Permission is granted to copy and distribute modified versions of
23
this manual under the conditions for verbatim copying, provided that
24
the entire resulting derived work is distributed under the terms of a
25
permission notice identical to this one.
27
Permission is granted to copy and distribute translations of this
28
manual into another language, under the above conditions for modified
29
versions, except that this permission notice may be stated in a
30
translation approved by the Free Software Foundation.
33
File: make.info, Node: Archive Symbols, Up: Archive Update
35
Updating Archive Symbol Directories
36
-----------------------------------
38
An archive file that is used as a library usually contains a special
39
member named `__.SYMDEF' that contains a directory of the external
40
symbol names defined by all the other members. After you update any
41
other members, you need to update `__.SYMDEF' so that it will summarize
42
the other members properly. This is done by running the `ranlib'
47
Normally you would put this command in the rule for the archive file,
48
and make all the members of the archive file prerequisites of that rule.
51
libfoo.a: libfoo.a(x.o) libfoo.a(y.o) ...
54
The effect of this is to update archive members `x.o', `y.o', etc., and
55
then update the symbol directory member `__.SYMDEF' by running
56
`ranlib'. The rules for updating the members are not shown here; most
57
likely you can omit them and use the implicit rule which copies files
58
into the archive, as described in the preceding section.
60
This is not necessary when using the GNU `ar' program, which updates
61
the `__.SYMDEF' member automatically.
64
File: make.info, Node: Archive Pitfalls, Next: Archive Suffix Rules, Prev: Archive Update, Up: Archives
66
Dangers When Using Archives
67
===========================
69
It is important to be careful when using parallel execution (the
70
`-j' switch; *note Parallel Execution: Parallel.) and archives. If
71
multiple `ar' commands run at the same time on the same archive file,
72
they will not know about each other and can corrupt the file.
74
Possibly a future version of `make' will provide a mechanism to
75
circumvent this problem by serializing all commands that operate on the
76
same archive file. But for the time being, you must either write your
77
makefiles to avoid this problem in some other way, or not use `-j'.
80
File: make.info, Node: Archive Suffix Rules, Prev: Archive Pitfalls, Up: Archives
82
Suffix Rules for Archive Files
83
==============================
85
You can write a special kind of suffix rule for dealing with archive
86
files. *Note Suffix Rules::, for a full explanation of suffix rules.
87
Archive suffix rules are obsolete in GNU `make', because pattern rules
88
for archives are a more general mechanism (*note Archive Update::).
89
But they are retained for compatibility with other `make's.
91
To write a suffix rule for archives, you simply write a suffix rule
92
using the target suffix `.a' (the usual suffix for archive files). For
93
example, here is the old-fashioned suffix rule to update a library
94
archive from C source files:
97
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
101
This works just as if you had written the pattern rule:
104
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
108
In fact, this is just what `make' does when it sees a suffix rule
109
with `.a' as the target suffix. Any double-suffix rule `.X.a' is
110
converted to a pattern rule with the target pattern `(%.o)' and a
111
prerequisite pattern of `%.X'.
113
Since you might want to use `.a' as the suffix for some other kind
114
of file, `make' also converts archive suffix rules to pattern rules in
115
the normal way (*note Suffix Rules::). Thus a double-suffix rule
116
`.X.a' produces two pattern rules: `(%.o): %.X' and `%.a: %.X'.
119
File: make.info, Node: Features, Next: Missing, Prev: Archives, Up: Top
121
Features of GNU `make'
122
**********************
124
Here is a summary of the features of GNU `make', for comparison with
125
and credit to other versions of `make'. We consider the features of
126
`make' in 4.2 BSD systems as a baseline. If you are concerned with
127
writing portable makefiles, you should not use the features of `make'
128
listed here, nor the ones in *Note Missing::.
130
Many features come from the version of `make' in System V.
132
* The `VPATH' variable and its special meaning. *Note Searching
133
Directories for Prerequisites: Directory Search. This feature
134
exists in System V `make', but is undocumented. It is documented
135
in 4.3 BSD `make' (which says it mimics System V's `VPATH'
138
* Included makefiles. *Note Including Other Makefiles: Include.
139
Allowing multiple files to be included with a single directive is
142
* Variables are read from and communicated via the environment.
143
*Note Variables from the Environment: Environment.
145
* Options passed through the variable `MAKEFLAGS' to recursive
146
invocations of `make'. *Note Communicating Options to a
147
Sub-`make': Options/Recursion.
149
* The automatic variable `$%' is set to the member name in an
150
archive reference. *Note Automatic Variables: Automatic.
152
* The automatic variables `$@', `$*', `$<', `$%', and `$?' have
153
corresponding forms like `$(@F)' and `$(@D)'. We have generalized
154
this to `$^' as an obvious extension. *Note Automatic Variables:
157
* Substitution variable references. *Note Basics of Variable
158
References: Reference.
160
* The command-line options `-b' and `-m', accepted and ignored. In
161
System V `make', these options actually do something.
163
* Execution of recursive commands to run `make' via the variable
164
`MAKE' even if `-n', `-q' or `-t' is specified. *Note Recursive
165
Use of `make': Recursion.
167
* Support for suffix `.a' in suffix rules. *Note Archive Suffix
168
Rules::. This feature is obsolete in GNU `make', because the
169
general feature of rule chaining (*note Chains of Implicit Rules:
170
Chained Rules.) allows one pattern rule for installing members in
171
an archive (*note Archive Update::) to be sufficient.
173
* The arrangement of lines and backslash-newline combinations in
174
commands is retained when the commands are printed, so they appear
175
as they do in the makefile, except for the stripping of initial
178
The following features were inspired by various other versions of
179
`make'. In some cases it is unclear exactly which versions inspired
182
* Pattern rules using `%'. This has been implemented in several
183
versions of `make'. We're not sure who invented it first, but
184
it's been spread around a bit. *Note Defining and Redefining
185
Pattern Rules: Pattern Rules.
187
* Rule chaining and implicit intermediate files. This was
188
implemented by Stu Feldman in his version of `make' for AT&T
189
Eighth Edition Research Unix, and later by Andrew Hume of AT&T
190
Bell Labs in his `mk' program (where he terms it "transitive
191
closure"). We do not really know if we got this from either of
192
them or thought it up ourselves at the same time. *Note Chains of
193
Implicit Rules: Chained Rules.
195
* The automatic variable `$^' containing a list of all prerequisites
196
of the current target. We did not invent this, but we have no
197
idea who did. *Note Automatic Variables: Automatic. The
198
automatic variable `$+' is a simple extension of `$^'.
200
* The "what if" flag (`-W' in GNU `make') was (as far as we know)
201
invented by Andrew Hume in `mk'. *Note Instead of Executing the
202
Commands: Instead of Execution.
204
* The concept of doing several things at once (parallelism) exists in
205
many incarnations of `make' and similar programs, though not in the
206
System V or BSD implementations. *Note Command Execution:
209
* Modified variable references using pattern substitution come from
210
SunOS 4. *Note Basics of Variable References: Reference. This
211
functionality was provided in GNU `make' by the `patsubst'
212
function before the alternate syntax was implemented for
213
compatibility with SunOS 4. It is not altogether clear who
214
inspired whom, since GNU `make' had `patsubst' before SunOS 4 was
217
* The special significance of `+' characters preceding command lines
218
(*note Instead of Executing the Commands: Instead of Execution.) is
219
mandated by `IEEE Standard 1003.2-1992' (POSIX.2).
221
* The `+=' syntax to append to the value of a variable comes from
222
SunOS 4 `make'. *Note Appending More Text to Variables: Appending.
224
* The syntax `ARCHIVE(MEM1 MEM2...)' to list multiple members in a
225
single archive file comes from SunOS 4 `make'. *Note Archive
228
* The `-include' directive to include makefiles with no error for a
229
nonexistent file comes from SunOS 4 `make'. (But note that SunOS 4
230
`make' does not allow multiple makefiles to be specified in one
231
`-include' directive.) The same feature appears with the name
232
`sinclude' in SGI `make' and perhaps others.
234
The remaining features are inventions new in GNU `make':
236
* Use the `-v' or `--version' option to print version and copyright
239
* Use the `-h' or `--help' option to summarize the options to `make'.
241
* Simply-expanded variables. *Note The Two Flavors of Variables:
244
* Pass command-line variable assignments automatically through the
245
variable `MAKE' to recursive `make' invocations. *Note Recursive
246
Use of `make': Recursion.
248
* Use the `-C' or `--directory' command option to change directory.
249
*Note Summary of Options: Options Summary.
251
* Make verbatim variable definitions with `define'. *Note Defining
252
Variables Verbatim: Defining.
254
* Declare phony targets with the special target `.PHONY'.
256
Andrew Hume of AT&T Bell Labs implemented a similar feature with a
257
different syntax in his `mk' program. This seems to be a case of
258
parallel discovery. *Note Phony Targets: Phony Targets.
260
* Manipulate text by calling functions. *Note Functions for
261
Transforming Text: Functions.
263
* Use the `-o' or `--old-file' option to pretend a file's
264
modification-time is old. *Note Avoiding Recompilation of Some
265
Files: Avoiding Compilation.
267
* Conditional execution.
269
This feature has been implemented numerous times in various
270
versions of `make'; it seems a natural extension derived from the
271
features of the C preprocessor and similar macro languages and is
272
not a revolutionary concept. *Note Conditional Parts of
273
Makefiles: Conditionals.
275
* Specify a search path for included makefiles. *Note Including
276
Other Makefiles: Include.
278
* Specify extra makefiles to read with an environment variable.
279
*Note The Variable `MAKEFILES': MAKEFILES Variable.
281
* Strip leading sequences of `./' from file names, so that `./FILE'
282
and `FILE' are considered to be the same file.
284
* Use a special search method for library prerequisites written in
285
the form `-lNAME'. *Note Directory Search for Link Libraries:
288
* Allow suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
289
Suffix Rules.) to contain any characters. In other versions of
290
`make', they must begin with `.' and not contain any `/'
293
* Keep track of the current level of `make' recursion using the
294
variable `MAKELEVEL'. *Note Recursive Use of `make': Recursion.
296
* Provide any goals given on the command line in the variable
297
`MAKECMDGOALS'. *Note Arguments to Specify the Goals: Goals.
299
* Specify static pattern rules. *Note Static Pattern Rules: Static
302
* Provide selective `vpath' search. *Note Searching Directories for
303
Prerequisites: Directory Search.
305
* Provide computed variable references. *Note Basics of Variable
306
References: Reference.
308
* Update makefiles. *Note How Makefiles Are Remade: Remaking
309
Makefiles. System V `make' has a very, very limited form of this
310
functionality in that it will check out SCCS files for makefiles.
312
* Various new built-in implicit rules. *Note Catalogue of Implicit
313
Rules: Catalogue of Rules.
315
* The built-in variable `MAKE_VERSION' gives the version number of
319
File: make.info, Node: Missing, Next: Makefile Conventions, Prev: Features, Up: Top
321
Incompatibilities and Missing Features
322
**************************************
324
The `make' programs in various other systems support a few features
325
that are not implemented in GNU `make'. The POSIX.2 standard (`IEEE
326
Standard 1003.2-1992') which specifies `make' does not require any of
329
* A target of the form `FILE((ENTRY))' stands for a member of
330
archive file FILE. The member is chosen, not by name, but by
331
being an object file which defines the linker symbol ENTRY.
333
This feature was not put into GNU `make' because of the
334
nonmodularity of putting knowledge into `make' of the internal
335
format of archive file symbol tables. *Note Updating Archive
336
Symbol Directories: Archive Symbols.
338
* Suffixes (used in suffix rules) that end with the character `~'
339
have a special meaning to System V `make'; they refer to the SCCS
340
file that corresponds to the file one would get without the `~'.
341
For example, the suffix rule `.c~.o' would make the file `N.o' from
342
the SCCS file `s.N.c'. For complete coverage, a whole series of
343
such suffix rules is required. *Note Old-Fashioned Suffix Rules:
346
In GNU `make', this entire series of cases is handled by two
347
pattern rules for extraction from SCCS, in combination with the
348
general feature of rule chaining. *Note Chains of Implicit Rules:
351
* In System V `make', the string `$$@' has the strange meaning that,
352
in the prerequisites of a rule with multiple targets, it stands
353
for the particular target that is being processed.
355
This is not defined in GNU `make' because `$$' should always stand
358
It is possible to get portions of this functionality through the
359
use of static pattern rules (*note Static Pattern Rules: Static
360
Pattern.). The System V `make' rule:
362
$(targets): $$@.o lib.a
364
can be replaced with the GNU `make' static pattern rule:
366
$(targets): %: %.o lib.a
368
* In System V and 4.3 BSD `make', files found by `VPATH' search
369
(*note Searching Directories for Prerequisites: Directory Search.)
370
have their names changed inside command strings. We feel it is
371
much cleaner to always use automatic variables and thus make this
374
* In some Unix `make's, the automatic variable `$*' appearing in the
375
prerequisites of a rule has the amazingly strange "feature" of
376
expanding to the full name of the _target of that rule_. We cannot
377
imagine what went on in the minds of Unix `make' developers to do
378
this; it is utterly inconsistent with the normal definition of
381
* In some Unix `make's, implicit rule search (*note Using Implicit
382
Rules: Implicit Rules.) is apparently done for _all_ targets, not
383
just those without commands. This means you can do:
388
and Unix `make' will intuit that `foo.o' depends on `foo.c'.
390
We feel that such usage is broken. The prerequisite properties of
391
`make' are well-defined (for GNU `make', at least), and doing such
392
a thing simply does not fit the model.
394
* GNU `make' does not include any built-in implicit rules for
395
compiling or preprocessing EFL programs. If we hear of anyone who
396
is using EFL, we will gladly add them.
398
* It appears that in SVR4 `make', a suffix rule can be specified with
399
no commands, and it is treated as if it had empty commands (*note
400
Empty Commands::). For example:
404
will override the built-in `.c.a' suffix rule.
406
We feel that it is cleaner for a rule without commands to always
407
simply add to the prerequisite list for the target. The above
408
example can be easily rewritten to get the desired behavior in GNU
413
* Some versions of `make' invoke the shell with the `-e' flag,
414
except under `-k' (*note Testing the Compilation of a Program:
415
Testing.). The `-e' flag tells the shell to exit as soon as any
416
program it runs returns a nonzero status. We feel it is cleaner to
417
write each shell command line to stand on its own and not require
418
this special treatment.
421
File: make.info, Node: Makefile Conventions, Next: Quick Reference, Prev: Missing, Up: Top
426
This node describes conventions for writing the Makefiles for GNU
427
programs. Using Automake will help you write a Makefile that follows
432
* Makefile Basics:: General Conventions for Makefiles
433
* Utilities in Makefiles:: Utilities in Makefiles
434
* Command Variables:: Variables for Specifying Commands
435
* Directory Variables:: Variables for Installation Directories
436
* Standard Targets:: Standard Targets for Users
437
* Install Command Categories:: Three categories of commands in the `install'
438
rule: normal, pre-install and post-install.
441
File: make.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
443
General Conventions for Makefiles
444
=================================
446
Every Makefile should contain this line:
450
to avoid trouble on systems where the `SHELL' variable might be
451
inherited from the environment. (This is never a problem with GNU
454
Different `make' programs have incompatible suffix lists and
455
implicit rules, and this sometimes creates confusion or misbehavior. So
456
it is a good idea to set the suffix list explicitly using only the
457
suffixes you need in the particular Makefile, like this:
462
The first line clears out the suffix list, the second introduces all
463
suffixes which may be subject to implicit rules in this Makefile.
465
Don't assume that `.' is in the path for command execution. When
466
you need to run programs that are a part of your package during the
467
make, please make sure that it uses `./' if the program is built as
468
part of the make or `$(srcdir)/' if the file is an unchanging part of
469
the source code. Without one of these prefixes, the current search
472
The distinction between `./' (the "build directory") and
473
`$(srcdir)/' (the "source directory") is important because users can
474
build in a separate directory using the `--srcdir' option to
475
`configure'. A rule of the form:
477
foo.1 : foo.man sedscript
478
sed -e sedscript foo.man > foo.1
480
will fail when the build directory is not the source directory, because
481
`foo.man' and `sedscript' are in the the source directory.
483
When using GNU `make', relying on `VPATH' to find the source file
484
will work in the case where there is a single dependency file, since
485
the `make' automatic variable `$<' will represent the source file
486
wherever it is. (Many versions of `make' set `$<' only in implicit
487
rules.) A Makefile target like
490
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
492
should instead be written as
495
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
497
in order to allow `VPATH' to work correctly. When the target has
498
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
499
to make the rule work well. For example, the target above for `foo.1'
502
foo.1 : foo.man sedscript
503
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
505
GNU distributions usually contain some files which are not source
506
files--for example, Info files, and the output from Autoconf, Automake,
507
Bison or Flex. Since these files normally appear in the source
508
directory, they should always appear in the source directory, not in the
509
build directory. So Makefile rules to update them should put the
510
updated files in the source directory.
512
However, if a file does not appear in the distribution, then the
513
Makefile should not put it in the source directory, because building a
514
program in ordinary circumstances should not modify the source directory
517
Try to make the build and installation targets, at least (and all
518
their subtargets) work correctly with a parallel `make'.
521
File: make.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
523
Utilities in Makefiles
524
======================
526
Write the Makefile commands (and any shell scripts, such as
527
`configure') to run in `sh', not in `csh'. Don't use any special
528
features of `ksh' or `bash'.
530
The `configure' script and the Makefile rules for building and
531
installation should not use any utilities directly except these:
533
cat cmp cp diff echo egrep expr false grep install-info
534
ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
536
The compression program `gzip' can be used in the `dist' rule.
538
Stick to the generally supported options for these programs. For
539
example, don't use `mkdir -p', convenient as it may be, because most
540
systems don't support it.
542
It is a good idea to avoid creating symbolic links in makefiles,
543
since a few systems don't support them.
545
The Makefile rules for building and installation can also use
546
compilers and related programs, but should do so via `make' variables
547
so that the user can substitute alternatives. Here are some of the
550
ar bison cc flex install ld ldconfig lex
551
make makeinfo ranlib texi2dvi yacc
553
Use the following `make' variables to run those programs:
555
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
556
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
558
When you use `ranlib' or `ldconfig', you should make sure nothing
559
bad happens if the system does not have the program in question.
560
Arrange to ignore an error from that command, and print a message before
561
the command to tell the user that failure of this command does not mean
562
a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
564
If you use symbolic links, you should implement a fallback for
565
systems that don't have symbolic links.
567
Additional utilities that can be used via Make variables are:
569
chgrp chmod chown mknod
571
It is ok to use other utilities in Makefile portions (or scripts)
572
intended only for particular systems where you know those utilities
576
File: make.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
578
Variables for Specifying Commands
579
=================================
581
Makefiles should provide variables for overriding certain commands,
584
In particular, you should run most utility programs via variables.
585
Thus, if you use Bison, have a variable named `BISON' whose default
586
value is set with `BISON = bison', and refer to it with `$(BISON)'
587
whenever you need to use Bison.
589
File management utilities such as `ln', `rm', `mv', and so on, need
590
not be referred to through variables in this way, since users don't
591
need to replace them with other programs.
593
Each program-name variable should come with an options variable that
594
is used to supply options to the program. Append `FLAGS' to the
595
program-name variable name to get the options variable name--for
596
example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
597
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
598
but we keep them because they are standard.) Use `CPPFLAGS' in any
599
compilation command that runs the preprocessor, and use `LDFLAGS' in
600
any compilation command that does linking as well as in any direct use
603
If there are C compiler options that _must_ be used for proper
604
compilation of certain files, do not include them in `CFLAGS'. Users
605
expect to be able to specify `CFLAGS' freely themselves. Instead,
606
arrange to pass the necessary options to the C compiler independently
607
of `CFLAGS', by writing them explicitly in the compilation commands or
608
by defining an implicit rule, like this:
611
ALL_CFLAGS = -I. $(CFLAGS)
613
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
615
Do include the `-g' option in `CFLAGS', because that is not
616
_required_ for proper compilation. You can consider it a default that
617
is only recommended. If the package is set up so that it is compiled
618
with GCC by default, then you might as well include `-O' in the default
619
value of `CFLAGS' as well.
621
Put `CFLAGS' last in the compilation command, after other variables
622
containing compiler options, so the user can use `CFLAGS' to override
625
`CFLAGS' should be used in every invocation of the C compiler, both
626
those which do compilation and those which do linking.
628
Every Makefile should define the variable `INSTALL', which is the
629
basic command for installing a file into the system.
631
Every Makefile should also define the variables `INSTALL_PROGRAM'
632
and `INSTALL_DATA'. (The default for each of these should be
633
`$(INSTALL)'.) Then it should use those variables as the commands for
634
actual installation, for executables and nonexecutables respectively.
635
Use these variables as follows:
637
$(INSTALL_PROGRAM) foo $(bindir)/foo
638
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
640
Optionally, you may prepend the value of `DESTDIR' to the target
641
filename. Doing this allows the installer to create a snapshot of the
642
installation to be copied onto the real target filesystem later. Do not
643
set the value of `DESTDIR' in your Makefile, and do not include it in
644
any installed files. With support for `DESTDIR', the above examples
647
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
648
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
650
Always use a file name, not a directory name, as the second argument of
651
the installation commands. Use a separate command for each file to be
655
File: make.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
657
Variables for Installation Directories
658
======================================
660
Installation directories should always be named by variables, so it
661
is easy to install in a nonstandard place. The standard names for these
662
variables are described below. They are based on a standard filesystem
663
layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
664
other modern operating systems.
666
These two variables set the root for the installation. All the other
667
installation directories should be subdirectories of one of these two,
668
and nothing should be directly installed into these two directories.
671
A prefix used in constructing the default values of the variables
672
listed below. The default value of `prefix' should be
673
`/usr/local'. When building the complete GNU system, the prefix
674
will be empty and `/usr' will be a symbolic link to `/'. (If you
675
are using Autoconf, write it as `@prefix@'.)
677
Running `make install' with a different value of `prefix' from the
678
one used to build the program should NOT recompile the program.
681
A prefix used in constructing the default values of some of the
682
variables listed below. The default value of `exec_prefix' should
683
be `$(prefix)'. (If you are using Autoconf, write it as
686
Generally, `$(exec_prefix)' is used for directories that contain
687
machine-specific files (such as executables and subroutine
688
libraries), while `$(prefix)' is used directly for other
691
Running `make install' with a different value of `exec_prefix'
692
from the one used to build the program should NOT recompile the
695
Executable programs are installed in one of the following
699
The directory for installing executable programs that users can
700
run. This should normally be `/usr/local/bin', but write it as
701
`$(exec_prefix)/bin'. (If you are using Autoconf, write it as
705
The directory for installing executable programs that can be run
706
from the shell, but are only generally useful to system
707
administrators. This should normally be `/usr/local/sbin', but
708
write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
709
write it as `@sbindir@'.)
712
The directory for installing executable programs to be run by other
713
programs rather than by users. This directory should normally be
714
`/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
715
(If you are using Autoconf, write it as `@libexecdir@'.)
717
Data files used by the program during its execution are divided into
718
categories in two ways.
720
* Some files are normally modified by programs; others are never
721
normally modified (though users may edit some of these).
723
* Some files are architecture-independent and can be shared by all
724
machines at a site; some are architecture-dependent and can be
725
shared only by machines of the same kind and operating system;
726
others may never be shared between two machines.
728
This makes for six different possibilities. However, we want to
729
discourage the use of architecture-dependent files, aside from object
730
files and libraries. It is much cleaner to make other data files
731
architecture-independent, and it is generally not hard.
733
Therefore, here are the variables Makefiles should use to specify
737
The directory for installing read-only architecture independent
738
data files. This should normally be `/usr/local/share', but write
739
it as `$(prefix)/share'. (If you are using Autoconf, write it as
740
`@datadir@'.) As a special exception, see `$(infodir)' and
741
`$(includedir)' below.
744
The directory for installing read-only data files that pertain to a
745
single machine-that is to say, files for configuring a host.
746
Mailer and network configuration files, `/etc/passwd', and so
747
forth belong here. All the files in this directory should be
748
ordinary ASCII text files. This directory should normally be
749
`/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
750
using Autoconf, write it as `@sysconfdir@'.)
752
Do not install executables here in this directory (they probably
753
belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
754
files that are modified in the normal course of their use (programs
755
whose purpose is to change the configuration of the system
756
excluded). Those probably belong in `$(localstatedir)'.
759
The directory for installing architecture-independent data files
760
which the programs modify while they run. This should normally be
761
`/usr/local/com', but write it as `$(prefix)/com'. (If you are
762
using Autoconf, write it as `@sharedstatedir@'.)
765
The directory for installing data files which the programs modify
766
while they run, and that pertain to one specific machine. Users
767
should never need to modify files in this directory to configure
768
the package's operation; put such configuration information in
769
separate files that go in `$(datadir)' or `$(sysconfdir)'.
770
`$(localstatedir)' should normally be `/usr/local/var', but write
771
it as `$(prefix)/var'. (If you are using Autoconf, write it as
775
The directory for object files and libraries of object code. Do
776
not install executables here, they probably ought to go in
777
`$(libexecdir)' instead. The value of `libdir' should normally be
778
`/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
779
are using Autoconf, write it as `@libdir@'.)
782
The directory for installing the Info files for this package. By
783
default, it should be `/usr/local/info', but it should be written
784
as `$(prefix)/info'. (If you are using Autoconf, write it as
788
The directory for installing any Emacs Lisp files in this package.
789
By default, it should be `/usr/local/share/emacs/site-lisp', but
790
it should be written as `$(prefix)/share/emacs/site-lisp'.
792
If you are using Autoconf, write the default as `@lispdir@'. In
793
order to make `@lispdir@' work, you need the following lines in
794
your `configure.in' file:
796
lispdir='${datadir}/emacs/site-lisp'
800
The directory for installing header files to be included by user
801
programs with the C `#include' preprocessor directive. This
802
should normally be `/usr/local/include', but write it as
803
`$(prefix)/include'. (If you are using Autoconf, write it as
806
Most compilers other than GCC do not look for header files in
807
directory `/usr/local/include'. So installing the header files
808
this way is only useful with GCC. Sometimes this is not a problem
809
because some libraries are only really intended to work with GCC.
810
But some libraries are intended to work with other compilers.
811
They should install their header files in two places, one
812
specified by `includedir' and one specified by `oldincludedir'.
815
The directory for installing `#include' header files for use with
816
compilers other than GCC. This should normally be `/usr/include'.
817
(If you are using Autoconf, you can write it as `@oldincludedir@'.)
819
The Makefile commands should check whether the value of
820
`oldincludedir' is empty. If it is, they should not try to use
821
it; they should cancel the second installation of the header files.
823
A package should not replace an existing header in this directory
824
unless the header came from the same package. Thus, if your Foo
825
package provides a header file `foo.h', then it should install the
826
header file in the `oldincludedir' directory if either (1) there
827
is no `foo.h' there or (2) the `foo.h' that exists came from the
830
To tell whether `foo.h' came from the Foo package, put a magic
831
string in the file--part of a comment--and `grep' for that string.
833
Unix-style man pages are installed in one of the following:
836
The top-level directory for installing the man pages (if any) for
837
this package. It will normally be `/usr/local/man', but you should
838
write it as `$(prefix)/man'. (If you are using Autoconf, write it
842
The directory for installing section 1 man pages. Write it as
846
The directory for installing section 2 man pages. Write it as
850
*Don't make the primary documentation for any GNU software be a
851
man page. Write a manual in Texinfo instead. Man pages are just
852
for the sake of people running GNU software on Unix, which is a
853
secondary application only.*
856
The file name extension for the installed man page. This should
857
contain a period followed by the appropriate digit; it should
861
The file name extension for installed section 1 man pages.
864
The file name extension for installed section 2 man pages.
867
Use these names instead of `manext' if the package needs to
868
install man pages in more than one section of the manual.
870
And finally, you should set the following variable:
873
The directory for the sources being compiled. The value of this
874
variable is normally inserted by the `configure' shell script.
875
(If you are using Autconf, use `srcdir = @srcdir@'.)
879
# Common prefix for installation directories.
880
# NOTE: This directory must exist when you start the install.
882
exec_prefix = $(prefix)
883
# Where to put the executable for the command `gcc'.
884
bindir = $(exec_prefix)/bin
885
# Where to put the directories used by the compiler.
886
libexecdir = $(exec_prefix)/libexec
887
# Where to put the Info files.
888
infodir = $(prefix)/info
890
If your program installs a large number of files into one of the
891
standard user-specified directories, it might be useful to group them
892
into a subdirectory particular to that program. If you do this, you
893
should write the `install' rule to create these subdirectories.
895
Do not expect the user to include the subdirectory name in the value
896
of any of the variables listed above. The idea of having a uniform set
897
of variable names for installation directories is to enable the user to
898
specify the exact same values for several different GNU packages. In
899
order for this to be useful, all the packages must be designed so that
900
they will work sensibly when the user does so.
903
File: make.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
905
Standard Targets for Users
906
==========================
908
All GNU programs should have the following targets in their
912
Compile the entire program. This should be the default target.
913
This target need not rebuild any documentation files; Info files
914
should normally be included in the distribution, and DVI files
915
should be made only when explicitly asked for.
917
By default, the Make rules should compile and link with `-g', so
918
that executable programs have debugging symbols. Users who don't
919
mind being helpless can strip the executables later if they wish.
922
Compile the program and copy the executables, libraries, and so on
923
to the file names where they should reside for actual use. If
924
there is a simple test to verify that a program is properly
925
installed, this target should run that test.
927
Do not strip executables when installing them. Devil-may-care
928
users can use the `install-strip' target to do that.
930
If possible, write the `install' target rule so that it does not
931
modify anything in the directory where the program was built,
932
provided `make all' has just been done. This is convenient for
933
building the program under one user name and installing it under
936
The commands should create all the directories in which files are
937
to be installed, if they don't already exist. This includes the
938
directories specified as the values of the variables `prefix' and
939
`exec_prefix', as well as all subdirectories that are needed. One
940
way to do this is by means of an `installdirs' target as described
943
Use `-' before any command for installing a man page, so that
944
`make' will ignore any errors. This is in case there are systems
945
that don't have the Unix man page documentation system installed.
947
The way to install Info files is to copy them into `$(infodir)'
948
with `$(INSTALL_DATA)' (*note Command Variables::), and then run
949
the `install-info' program if it is present. `install-info' is a
950
program that edits the Info `dir' file to add or update the menu
951
entry for the given Info file; it is part of the Texinfo package.
952
Here is a sample rule to install an Info file:
954
$(DESTDIR)$(infodir)/foo.info: foo.info
956
# There may be a newer info file in . than in srcdir.
957
-if test -f foo.info; then d=.; \
958
else d=$(srcdir); fi; \
959
$(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
960
# Run install-info only if it exists.
961
# Use `if' instead of just prepending `-' to the
962
# line so we notice real errors from install-info.
963
# We use `$(SHELL) -c' because some shells do not
964
# fail gracefully when there is an unknown command.
965
if $(SHELL) -c 'install-info --version' \
966
>/dev/null 2>&1; then \
967
install-info --dir-file=$(DESTDIR)$(infodir)/dir \
968
$(DESTDIR)$(infodir)/foo.info; \
971
When writing the `install' target, you must classify all the
972
commands into three categories: normal ones, "pre-installation"
973
commands and "post-installation" commands. *Note Install Command
977
Delete all the installed files--the copies that the `install'
980
This rule should not modify the directories where compilation is
981
done, only the directories where files are installed.
983
The uninstallation commands are divided into three categories,
984
just like the installation commands. *Note Install Command
988
Like `install', but strip the executable files while installing
989
them. In many cases, the definition of this target can be very
993
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
996
Normally we do not recommend stripping an executable unless you
997
are sure the program has no bugs. However, it can be reasonable
998
to install a stripped executable for actual execution while saving
999
the unstripped executable elsewhere in case there is a bug.
1002
Delete all files from the current directory that are normally
1003
created by building the program. Don't delete the files that
1004
record the configuration. Also preserve files that could be made
1005
by building, but normally aren't because the distribution comes
1008
Delete `.dvi' files here if they are not part of the distribution.
1011
Delete all files from the current directory that are created by
1012
configuring or building the program. If you have unpacked the
1013
source and built the program without creating any other files,
1014
`make distclean' should leave only the files that were in the
1018
Like `clean', but may refrain from deleting a few files that people
1019
normally don't want to recompile. For example, the `mostlyclean'
1020
target for GCC does not delete `libgcc.a', because recompiling it
1021
is rarely necessary and takes a lot of time.
1024
Delete almost everything from the current directory that can be
1025
reconstructed with this Makefile. This typically includes
1026
everything deleted by `distclean', plus more: C source files
1027
produced by Bison, tags tables, Info files, and so on.
1029
The reason we say "almost everything" is that running the command
1030
`make maintainer-clean' should not delete `configure' even if
1031
`configure' can be remade using a rule in the Makefile. More
1032
generally, `make maintainer-clean' should not delete anything that
1033
needs to exist in order to run `configure' and then begin to build
1034
the program. This is the only exception; `maintainer-clean' should
1035
delete everything else that can be rebuilt.
1037
The `maintainer-clean' target is intended to be used by a
1038
maintainer of the package, not by ordinary users. You may need
1039
special tools to reconstruct some of the files that `make
1040
maintainer-clean' deletes. Since these files are normally
1041
included in the distribution, we don't take care to make them easy
1042
to reconstruct. If you find you need to unpack the full
1043
distribution again, don't blame us.
1045
To help make users aware of this, the commands for the special
1046
`maintainer-clean' target should start with these two:
1048
@echo 'This command is intended for maintainers to use; it'
1049
@echo 'deletes files that may need special tools to rebuild.'
1052
Update a tags table for this program.
1055
Generate any Info files needed. The best way to write the rules
1060
foo.info: foo.texi chap1.texi chap2.texi
1061
$(MAKEINFO) $(srcdir)/foo.texi
1063
You must define the variable `MAKEINFO' in the Makefile. It should
1064
run the `makeinfo' program, which is part of the Texinfo
1067
Normally a GNU distribution comes with Info files, and that means
1068
the Info files are present in the source directory. Therefore,
1069
the Make rule for an info file should update it in the source
1070
directory. When users build the package, ordinarily Make will not
1071
update the Info files because they will already be up to date.
1074
Generate DVI files for all Texinfo documentation. For example:
1078
foo.dvi: foo.texi chap1.texi chap2.texi
1079
$(TEXI2DVI) $(srcdir)/foo.texi
1081
You must define the variable `TEXI2DVI' in the Makefile. It should
1082
run the program `texi2dvi', which is part of the Texinfo
1083
distribution.(1) Alternatively, write just the dependencies, and
1084
allow GNU `make' to provide the command.
1087
Create a distribution tar file for this program. The tar file
1088
should be set up so that the file names in the tar file start with
1089
a subdirectory name which is the name of the package it is a
1090
distribution for. This name can include the version number.
1092
For example, the distribution tar file of GCC version 1.40 unpacks
1093
into a subdirectory named `gcc-1.40'.
1095
The easiest way to do this is to create a subdirectory
1096
appropriately named, use `ln' or `cp' to install the proper files
1097
in it, and then `tar' that subdirectory.
1099
Compress the tar file file with `gzip'. For example, the actual
1100
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
1102
The `dist' target should explicitly depend on all non-source files
1103
that are in the distribution, to make sure they are up to date in
1104
the distribution. *Note Making Releases: (standards)Releases.
1107
Perform self-tests (if any). The user must build the program
1108
before running the tests, but need not install the program; you
1109
should write the self-tests so that they work when the program is
1110
built but not installed.
1112
The following targets are suggested as conventional names, for
1113
programs in which they are useful.
1116
Perform installation tests (if any). The user must build and
1117
install the program before running the tests. You should not
1118
assume that `$(bindir)' is in the search path.
1121
It's useful to add a target named `installdirs' to create the
1122
directories where files are installed, and their parent
1123
directories. There is a script called `mkinstalldirs' which is
1124
convenient for this; you can find it in the Texinfo package. You
1125
can use a rule like this:
1127
# Make sure all installation directories (e.g. $(bindir))
1128
# actually exist by making them if necessary.
1129
installdirs: mkinstalldirs
1130
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
1131
$(libdir) $(infodir) \
1134
This rule should not modify the directories where compilation is
1135
done. It should do nothing but create installation directories.
1137
---------- Footnotes ----------
1139
(1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
1140
not distributed with Texinfo.