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: Top, Next: Overview, Up: (dir)
38
The GNU `make' utility automatically determines which pieces of a
39
large program need to be recompiled, and issues the commands to
42
This edition of the `GNU Make Manual', last updated 09 September
43
1999, documents GNU `make' Version 3.78.1.
45
This manual describes `make' and contains the following chapters:
49
* Overview:: Overview of `make'.
50
* Introduction:: An introduction to `make'.
51
* Makefiles:: Makefiles tell `make' what to do.
52
* Rules:: Rules describe when a file must be remade.
53
* Commands:: Commands say how to remake a file.
54
* Using Variables:: You can use variables to avoid repetition.
55
* Conditionals:: Use or ignore parts of the makefile based
56
on the values of variables.
57
* Functions:: Many powerful ways to manipulate text.
58
* Invoking make: Running. How to invoke `make' on the command line.
59
* Implicit Rules:: Use implicit rules to treat many files alike,
60
based on their file names.
61
* Archives:: How `make' can update library archives.
62
* Features:: Features GNU `make' has over other `make's.
63
* Missing:: What GNU `make' lacks from other `make's.
64
* Makefile Conventions:: Conventions for makefiles in GNU programs.
65
* Quick Reference:: A quick reference for experienced users.
66
* Make Errors:: A list of common errors generated by `make'.
67
* Complex Makefile:: A real example of a straightforward,
68
but nontrivial, makefile.
69
* Concept Index:: Index of Concepts
70
* Name Index:: Index of Functions, Variables, & Directives
72
--- The Detailed Node Listing ---
76
* Preparing:: Preparing and Running Make
77
* Reading:: On Reading this Text
78
* Bugs:: Problems and Bugs
80
An Introduction to Makefiles
82
* Rule Introduction:: What a rule looks like.
83
* Simple Makefile:: A Simple Makefile
84
* How Make Works:: How `make' Processes This Makefile
85
* Variables Simplify:: Variables Make Makefiles Simpler
86
* make Deduces:: Letting `make' Deduce the Commands
87
* Combine By Prerequisite:: Another Style of Makefile
88
* Cleanup:: Rules for Cleaning the Directory
92
* Makefile Contents:: What makefiles contain.
93
* Makefile Names:: How to name your makefile.
94
* Include:: How one makefile can use another makefile.
95
* MAKEFILES Variable:: The environment can specify extra makefiles.
96
* Remaking Makefiles:: How makefiles get remade.
97
* Overriding Makefiles:: How to override part of one makefile
98
with another makefile.
99
* Reading Makefiles:: How makefiles are parsed.
103
* Rule Example:: An example explained.
104
* Rule Syntax:: General syntax explained.
105
* Wildcards:: Using wildcard characters such as `*'.
106
* Directory Search:: Searching other directories for source files.
107
* Phony Targets:: Using a target that is not a real file's name.
108
* Force Targets:: You can use a target without commands
109
or prerequisites to mark other
111
* Empty Targets:: When only the date matters and the
113
* Special Targets:: Targets with special built-in meanings.
114
* Multiple Targets:: When to make use of several targets in a rule.
115
* Multiple Rules:: How to use several rules with the same target.
116
* Static Pattern:: Static pattern rules apply to multiple targets
117
and can vary the prerequisites according to
119
* Double-Colon:: How to use a special kind of rule to allow
120
several independent rules for one target.
121
* Automatic Prerequisites:: How to automatically generate rules giving
122
prerequisites from source files themselves.
124
Using Wildcard Characters in File Names
126
* Wildcard Examples:: Several examples
127
* Wildcard Pitfall:: Problems to avoid.
128
* Wildcard Function:: How to cause wildcard expansion where
129
it does not normally take place.
131
Searching Directories for Prerequisites
133
* General Search:: Specifying a search path that applies
134
to every prerequisite.
135
* Selective Search:: Specifying a search path
136
for a specified class of names.
137
* Search Algorithm:: When and how search paths are applied.
138
* Commands/Search:: How to write shell commands that work together
140
* Implicit/Search:: How search paths affect implicit rules.
141
* Libraries/Search:: Directory search for link libraries.
145
* Static Usage:: The syntax of static pattern rules.
146
* Static versus Implicit:: When are they better than implicit rules?
148
Writing the Commands in Rules
150
* Echoing:: How to control when commands are echoed.
151
* Execution:: How commands are executed.
152
* Parallel:: How commands can be executed in parallel.
153
* Errors:: What happens after a command execution error.
154
* Interrupts:: What happens when a command is interrupted.
155
* Recursion:: Invoking `make' from makefiles.
156
* Sequences:: Defining canned sequences of commands.
157
* Empty Commands:: Defining useful, do-nothing commands.
159
Recursive Use of `make'
161
* MAKE Variable:: The special effects of using `$(MAKE)'.
162
* Variables/Recursion:: How to communicate variables to a sub-`make'.
163
* Options/Recursion:: How to communicate options to a sub-`make'.
164
* -w Option:: How the `-w' or `--print-directory' option
165
helps debug use of recursive `make' commands.
169
* Reference:: How to use the value of a variable.
170
* Flavors:: Variables come in two flavors.
171
* Advanced:: Advanced features for referencing a variable.
172
* Values:: All the ways variables get their values.
173
* Setting:: How to set a variable in the makefile.
174
* Appending:: How to append more text to the old value
176
* Override Directive:: How to set a variable in the makefile even if
177
the user has set it with a command argument.
178
* Defining:: An alternate way to set a variable
179
to a verbatim string.
180
* Environment:: Variable values can come from the environment.
181
* Automatic:: Some special variables have predefined
182
meanings for use with implicit rules.
184
Advanced Features for Reference to Variables
186
* Substitution Refs:: Referencing a variable with
187
substitutions on the value.
188
* Computed Names:: Computing the name of the variable to refer to.
190
Conditional Parts of Makefiles
192
* Conditional Example:: Example of a conditional
193
* Conditional Syntax:: The syntax of conditionals.
194
* Testing Flags:: Conditionals that test flags.
196
Functions for Transforming Text
198
* Syntax of Functions:: How to write a function call.
199
* Text Functions:: General-purpose text manipulation functions.
200
* File Name Functions:: Functions for manipulating file names.
201
* Foreach Function:: Repeat some text with controlled variation.
202
* Call Function:: Expand a user-defined function.
203
* Origin Function:: Find where a variable got its value.
204
* Shell Function:: Substitute the output of a shell command.
208
* Makefile Arguments:: How to specify which makefile to use.
209
* Goals:: How to use goal arguments to specify which
210
parts of the makefile to use.
211
* Instead of Execution:: How to use mode flags to specify what
212
kind of thing to do with the commands
213
in the makefile other than simply
215
* Avoiding Compilation:: How to avoid recompiling certain files.
216
* Overriding:: How to override a variable to specify
217
an alternate compiler and other things.
218
* Testing:: How to proceed past some errors, to
220
* Options Summary:: Summary of Options
224
* Using Implicit:: How to use an existing implicit rule
225
to get the commands for updating a file.
226
* Catalogue of Rules:: A list of built-in implicit rules.
227
* Implicit Variables:: How to change what predefined rules do.
228
* Chained Rules:: How to use a chain of implicit rules.
229
* Pattern Rules:: How to define new implicit rules.
230
* Last Resort:: How to defining commands for rules
231
which cannot find any.
232
* Suffix Rules:: The old-fashioned style of implicit rule.
233
* Implicit Rule Search:: The precise algorithm for applying
236
Defining and Redefining Pattern Rules
238
* Pattern Intro:: An introduction to pattern rules.
239
* Pattern Examples:: Examples of pattern rules.
240
* Automatic:: How to use automatic variables in the
241
commands of implicit rules.
242
* Pattern Match:: How patterns match.
243
* Match-Anything Rules:: Precautions you should take prior to
244
defining rules that can match any
245
target file whatever.
246
* Canceling Rules:: How to override or cancel built-in rules.
248
Using `make' to Update Archive Files
250
* Archive Members:: Archive members as targets.
251
* Archive Update:: The implicit rule for archive member targets.
252
* Archive Pitfalls:: Dangers to watch out for when using archives.
253
* Archive Suffix Rules:: You can write a special kind of suffix rule
254
for updating archives.
256
Implicit Rule for Archive Member Targets
258
* Archive Symbols:: How to update archive symbol directories.
261
File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top
266
The `make' utility automatically determines which pieces of a large
267
program need to be recompiled, and issues commands to recompile them.
268
This manual describes GNU `make', which was implemented by Richard
269
Stallman and Roland McGrath. Development since Version 3.76 has been
270
handled by Paul D. Smith.
272
GNU `make' conforms to section 6.2 of `IEEE Standard 1003.2-1992'
275
Our examples show C programs, since they are most common, but you
276
can use `make' with any programming language whose compiler can be run
277
with a shell command. Indeed, `make' is not limited to programs. You
278
can use it to describe any task where some files must be updated
279
automatically from others whenever the others change.
283
* Preparing:: Preparing and Running Make
284
* Reading:: On Reading this Text
285
* Bugs:: Problems and Bugs
288
File: make.info, Node: Preparing, Next: Reading, Up: Overview
290
Preparing and Running Make
291
==========================
293
To prepare to use `make', you must write a file called the
294
"makefile" that describes the relationships among files in your program
295
and provides commands for updating each file. In a program, typically,
296
the executable file is updated from object files, which are in turn
297
made by compiling source files.
299
Once a suitable makefile exists, each time you change some source
300
files, this simple shell command:
304
suffices to perform all necessary recompilations. The `make' program
305
uses the makefile data base and the last-modification times of the
306
files to decide which of the files need to be updated. For each of
307
those files, it issues the commands recorded in the data base.
309
You can provide command line arguments to `make' to control which
310
files should be recompiled, or how. *Note How to Run `make': Running.
313
File: make.info, Node: Reading, Next: Bugs, Prev: Preparing, Up: Overview
315
How to Read This Manual
316
=======================
318
If you are new to `make', or are looking for a general introduction,
319
read the first few sections of each chapter, skipping the later
320
sections. In each chapter, the first few sections contain introductory
321
or general information and the later sections contain specialized or
322
technical information. The exception is the second chapter, *Note An
323
Introduction to Makefiles: Introduction, all of which is introductory.
325
If you are familiar with other `make' programs, see *Note Features
326
of GNU `make': Features, which lists the enhancements GNU `make' has,
327
and *Note Incompatibilities and Missing Features: Missing, which
328
explains the few things GNU `make' lacks that others have.
330
For a quick summary, see *Note Options Summary::, *Note Quick
331
Reference::, and *Note Special Targets::.
334
File: make.info, Node: Bugs, Prev: Reading, Up: Overview
339
If you have problems with GNU `make' or think you've found a bug,
340
please report it to the developers; we cannot promise to do anything but
341
we might well want to fix it.
343
Before reporting a bug, make sure you've actually found a real bug.
344
Carefully reread the documentation and see if it really says you can do
345
what you're trying to do. If it's not clear whether you should be able
346
to do something or not, report that too; it's a bug in the
349
Before reporting a bug or trying to fix it yourself, try to isolate
350
it to the smallest possible makefile that reproduces the problem. Then
351
send us the makefile and the exact results `make' gave you. Also say
352
what you expected to occur; this will help us decide whether the
353
problem was really in the documentation.
355
Once you've got a precise problem, please send electronic mail to:
359
Please include the version number of `make' you are using. You can get
360
this information with the command `make --version'. Be sure also to
361
include the type of machine and operating system you are using. If
362
possible, include the contents of the file `config.h' that is generated
363
by the configuration process.
366
File: make.info, Node: Introduction, Next: Makefiles, Prev: Overview, Up: Top
368
An Introduction to Makefiles
369
****************************
371
You need a file called a "makefile" to tell `make' what to do. Most
372
often, the makefile tells `make' how to compile and link a program.
374
In this chapter, we will discuss a simple makefile that describes
375
how to compile and link a text editor which consists of eight C source
376
files and three header files. The makefile can also tell `make' how to
377
run miscellaneous commands when explicitly asked (for example, to remove
378
certain files as a clean-up operation). To see a more complex example
379
of a makefile, see *Note Complex Makefile::.
381
When `make' recompiles the editor, each changed C source file must
382
be recompiled. If a header file has changed, each C source file that
383
includes the header file must be recompiled to be safe. Each
384
compilation produces an object file corresponding to the source file.
385
Finally, if any source file has been recompiled, all the object files,
386
whether newly made or saved from previous compilations, must be linked
387
together to produce the new executable editor.
391
* Rule Introduction:: What a rule looks like.
392
* Simple Makefile:: A Simple Makefile
393
* How Make Works:: How `make' Processes This Makefile
394
* Variables Simplify:: Variables Make Makefiles Simpler
395
* make Deduces:: Letting `make' Deduce the Commands
396
* Combine By Prerequisite:: Another Style of Makefile
397
* Cleanup:: Rules for Cleaning the Directory
400
File: make.info, Node: Rule Introduction, Next: Simple Makefile, Up: Introduction
402
What a Rule Looks Like
403
======================
405
A simple makefile consists of "rules" with the following shape:
407
TARGET ... : PREREQUISITES ...
412
A "target" is usually the name of a file that is generated by a
413
program; examples of targets are executable or object files. A target
414
can also be the name of an action to carry out, such as `clean' (*note
417
A "prerequisite" is a file that is used as input to create the
418
target. A target often depends on several files.
420
A "command" is an action that `make' carries out. A rule may have
421
more than one command, each on its own line. *Please note:* you need
422
to put a tab character at the beginning of every command line! This is
423
an obscurity that catches the unwary.
425
Usually a command is in a rule with prerequisites and serves to
426
create a target file if any of the prerequisites change. However, the
427
rule that specifies commands for the target need not have
428
prerequisites. For example, the rule containing the delete command
429
associated with the target `clean' does not have prerequisites.
431
A "rule", then, explains how and when to remake certain files which
432
are the targets of the particular rule. `make' carries out the
433
commands on the prerequisites to create or update the target. A rule
434
can also explain how and when to carry out an action. *Note Writing
437
A makefile may contain other text besides rules, but a simple
438
makefile need only contain rules. Rules may look somewhat more
439
complicated than shown in this template, but all fit the pattern more
443
File: make.info, Node: Simple Makefile, Next: How Make Works, Prev: Rule Introduction, Up: Introduction
448
Here is a straightforward makefile that describes the way an
449
executable file called `edit' depends on eight object files which, in
450
turn, depend on eight C source and three header files.
452
In this example, all the C files include `defs.h', but only those
453
defining editing commands include `command.h', and only low level files
454
that change the editor buffer include `buffer.h'.
456
edit : main.o kbd.o command.o display.o \
457
insert.o search.o files.o utils.o
458
cc -o edit main.o kbd.o command.o display.o \
459
insert.o search.o files.o utils.o
461
main.o : main.c defs.h
463
kbd.o : kbd.c defs.h command.h
465
command.o : command.c defs.h command.h
467
display.o : display.c defs.h buffer.h
469
insert.o : insert.c defs.h buffer.h
471
search.o : search.c defs.h buffer.h
473
files.o : files.c defs.h buffer.h command.h
475
utils.o : utils.c defs.h
478
rm edit main.o kbd.o command.o display.o \
479
insert.o search.o files.o utils.o
481
We split each long line into two lines using backslash-newline; this is
482
like using one long line, but is easier to read.
484
To use this makefile to create the executable file called `edit',
489
To use this makefile to delete the executable file and all the object
490
files from the directory, type:
494
In the example makefile, the targets include the executable file
495
`edit', and the object files `main.o' and `kbd.o'. The prerequisites
496
are files such as `main.c' and `defs.h'. In fact, each `.o' file is
497
both a target and a prerequisite. Commands include `cc -c main.c' and
500
When a target is a file, it needs to be recompiled or relinked if any
501
of its prerequisites change. In addition, any prerequisites that are
502
themselves automatically generated should be updated first. In this
503
example, `edit' depends on each of the eight object files; the object
504
file `main.o' depends on the source file `main.c' and on the header
507
A shell command follows each line that contains a target and
508
prerequisites. These shell commands say how to update the target file.
509
A tab character must come at the beginning of every command line to
510
distinguish commands lines from other lines in the makefile. (Bear in
511
mind that `make' does not know anything about how the commands work.
512
It is up to you to supply commands that will update the target file
513
properly. All `make' does is execute the commands in the rule you have
514
specified when the target file needs to be updated.)
516
The target `clean' is not a file, but merely the name of an action.
517
Since you normally do not want to carry out the actions in this rule,
518
`clean' is not a prerequisite of any other rule. Consequently, `make'
519
never does anything with it unless you tell it specifically. Note that
520
this rule not only is not a prerequisite, it also does not have any
521
prerequisites, so the only purpose of the rule is to run the specified
522
commands. Targets that do not refer to files but are just actions are
523
called "phony targets". *Note Phony Targets::, for information about
524
this kind of target. *Note Errors in Commands: Errors, to see how to
525
cause `make' to ignore errors from `rm' or any other command.
528
File: make.info, Node: How Make Works, Next: Variables Simplify, Prev: Simple Makefile, Up: Introduction
530
How `make' Processes a Makefile
531
===============================
533
By default, `make' starts with the first target (not targets whose
534
names start with `.'). This is called the "default goal". ("Goals"
535
are the targets that `make' strives ultimately to update. *Note
536
Arguments to Specify the Goals: Goals.)
538
In the simple example of the previous section, the default goal is to
539
update the executable program `edit'; therefore, we put that rule first.
541
Thus, when you give the command:
545
`make' reads the makefile in the current directory and begins by
546
processing the first rule. In the example, this rule is for relinking
547
`edit'; but before `make' can fully process this rule, it must process
548
the rules for the files that `edit' depends on, which in this case are
549
the object files. Each of these files is processed according to its
550
own rule. These rules say to update each `.o' file by compiling its
551
source file. The recompilation must be done if the source file, or any
552
of the header files named as prerequisites, is more recent than the
553
object file, or if the object file does not exist.
555
The other rules are processed because their targets appear as
556
prerequisites of the goal. If some other rule is not depended on by the
557
goal (or anything it depends on, etc.), that rule is not processed,
558
unless you tell `make' to do so (with a command such as `make clean').
560
Before recompiling an object file, `make' considers updating its
561
prerequisites, the source file and header files. This makefile does not
562
specify anything to be done for them--the `.c' and `.h' files are not
563
the targets of any rules--so `make' does nothing for these files. But
564
`make' would update automatically generated C programs, such as those
565
made by Bison or Yacc, by their own rules at this time.
567
After recompiling whichever object files need it, `make' decides
568
whether to relink `edit'. This must be done if the file `edit' does
569
not exist, or if any of the object files are newer than it. If an
570
object file was just recompiled, it is now newer than `edit', so `edit'
573
Thus, if we change the file `insert.c' and run `make', `make' will
574
compile that file to update `insert.o', and then link `edit'. If we
575
change the file `command.h' and run `make', `make' will recompile the
576
object files `kbd.o', `command.o' and `files.o' and then link the file
580
File: make.info, Node: Variables Simplify, Next: make Deduces, Prev: How Make Works, Up: Introduction
582
Variables Make Makefiles Simpler
583
================================
585
In our example, we had to list all the object files twice in the
586
rule for `edit' (repeated here):
588
edit : main.o kbd.o command.o display.o \
589
insert.o search.o files.o utils.o
590
cc -o edit main.o kbd.o command.o display.o \
591
insert.o search.o files.o utils.o
593
Such duplication is error-prone; if a new object file is added to the
594
system, we might add it to one list and forget the other. We can
595
eliminate the risk and simplify the makefile by using a variable.
596
"Variables" allow a text string to be defined once and substituted in
597
multiple places later (*note How to Use Variables: Using Variables.).
599
It is standard practice for every makefile to have a variable named
600
`objects', `OBJECTS', `objs', `OBJS', `obj', or `OBJ' which is a list
601
of all object file names. We would define such a variable `objects'
602
with a line like this in the makefile:
604
objects = main.o kbd.o command.o display.o \
605
insert.o search.o files.o utils.o
607
Then, each place we want to put a list of the object file names, we can
608
substitute the variable's value by writing `$(objects)' (*note How to
609
Use Variables: Using Variables.).
611
Here is how the complete simple makefile looks when you use a
612
variable for the object files:
614
objects = main.o kbd.o command.o display.o \
615
insert.o search.o files.o utils.o
618
cc -o edit $(objects)
619
main.o : main.c defs.h
621
kbd.o : kbd.c defs.h command.h
623
command.o : command.c defs.h command.h
625
display.o : display.c defs.h buffer.h
627
insert.o : insert.c defs.h buffer.h
629
search.o : search.c defs.h buffer.h
631
files.o : files.c defs.h buffer.h command.h
633
utils.o : utils.c defs.h
639
File: make.info, Node: make Deduces, Next: Combine By Prerequisite, Prev: Variables Simplify, Up: Introduction
641
Letting `make' Deduce the Commands
642
==================================
644
It is not necessary to spell out the commands for compiling the
645
individual C source files, because `make' can figure them out: it has an
646
"implicit rule" for updating a `.o' file from a correspondingly named
647
`.c' file using a `cc -c' command. For example, it will use the
648
command `cc -c main.c -o main.o' to compile `main.c' into `main.o'. We
649
can therefore omit the commands from the rules for the object files.
650
*Note Using Implicit Rules: Implicit Rules.
652
When a `.c' file is used automatically in this way, it is also
653
automatically added to the list of prerequisites. We can therefore omit
654
the `.c' files from the prerequisites, provided we omit the commands.
656
Here is the entire example, with both of these changes, and a
657
variable `objects' as suggested above:
659
objects = main.o kbd.o command.o display.o \
660
insert.o search.o files.o utils.o
663
cc -o edit $(objects)
666
kbd.o : defs.h command.h
667
command.o : defs.h command.h
668
display.o : defs.h buffer.h
669
insert.o : defs.h buffer.h
670
search.o : defs.h buffer.h
671
files.o : defs.h buffer.h command.h
678
This is how we would write the makefile in actual practice. (The
679
complications associated with `clean' are described elsewhere. See
680
*Note Phony Targets::, and *Note Errors in Commands: Errors.)
682
Because implicit rules are so convenient, they are important. You
683
will see them used frequently.
686
File: make.info, Node: Combine By Prerequisite, Next: Cleanup, Prev: make Deduces, Up: Introduction
688
Another Style of Makefile
689
=========================
691
When the objects of a makefile are created only by implicit rules, an
692
alternative style of makefile is possible. In this style of makefile,
693
you group entries by their prerequisites instead of by their targets.
694
Here is what one looks like:
696
objects = main.o kbd.o command.o display.o \
697
insert.o search.o files.o utils.o
700
cc -o edit $(objects)
703
kbd.o command.o files.o : command.h
704
display.o insert.o search.o files.o : buffer.h
706
Here `defs.h' is given as a prerequisite of all the object files;
707
`command.h' and `buffer.h' are prerequisites of the specific object
708
files listed for them.
710
Whether this is better is a matter of taste: it is more compact, but
711
some people dislike it because they find it clearer to put all the
712
information about each target in one place.
715
File: make.info, Node: Cleanup, Prev: Combine By Prerequisite, Up: Introduction
717
Rules for Cleaning the Directory
718
================================
720
Compiling a program is not the only thing you might want to write
721
rules for. Makefiles commonly tell how to do a few other things besides
722
compiling a program: for example, how to delete all the object files
723
and executables so that the directory is `clean'.
725
Here is how we could write a `make' rule for cleaning our example
731
In practice, we might want to write the rule in a somewhat more
732
complicated manner to handle unanticipated situations. We would do
739
This prevents `make' from getting confused by an actual file called
740
`clean' and causes it to continue in spite of errors from `rm'. (See
741
*Note Phony Targets::, and *Note Errors in Commands: Errors.)
743
A rule such as this should not be placed at the beginning of the
744
makefile, because we do not want it to run by default! Thus, in the
745
example makefile, we want the rule for `edit', which recompiles the
746
editor, to remain the default goal.
748
Since `clean' is not a prerequisite of `edit', this rule will not
749
run at all if we give the command `make' with no arguments. In order
750
to make the rule run, we have to type `make clean'. *Note How to Run
754
File: make.info, Node: Makefiles, Next: Rules, Prev: Introduction, Up: Top
759
The information that tells `make' how to recompile a system comes
760
from reading a data base called the "makefile".
764
* Makefile Contents:: What makefiles contain.
765
* Makefile Names:: How to name your makefile.
766
* Include:: How one makefile can use another makefile.
767
* MAKEFILES Variable:: The environment can specify extra makefiles.
768
* Remaking Makefiles:: How makefiles get remade.
769
* Overriding Makefiles:: How to override part of one makefile
770
with another makefile.
771
* Reading Makefiles:: How makefiles are parsed.
774
File: make.info, Node: Makefile Contents, Next: Makefile Names, Up: Makefiles
776
What Makefiles Contain
777
======================
779
Makefiles contain five kinds of things: "explicit rules", "implicit
780
rules", "variable definitions", "directives", and "comments". Rules,
781
variables, and directives are described at length in later chapters.
783
* An "explicit rule" says when and how to remake one or more files,
784
called the rule's targets. It lists the other files that the
785
targets depend on, call the "prerequisites" of the target, and may
786
also give commands to use to create or update the targets. *Note
787
Writing Rules: Rules.
789
* An "implicit rule" says when and how to remake a class of files
790
based on their names. It describes how a target may depend on a
791
file with a name similar to the target and gives commands to
792
create or update such a target. *Note Using Implicit Rules:
795
* A "variable definition" is a line that specifies a text string
796
value for a variable that can be substituted into the text later.
797
The simple makefile example shows a variable definition for
798
`objects' as a list of all object files (*note Variables Make
799
Makefiles Simpler: Variables Simplify.).
801
* A "directive" is a command for `make' to do something special while
802
reading the makefile. These include:
804
* Reading another makefile (*note Including Other Makefiles:
807
* Deciding (based on the values of variables) whether to use or
808
ignore a part of the makefile (*note Conditional Parts of
809
Makefiles: Conditionals.).
811
* Defining a variable from a verbatim string containing
812
multiple lines (*note Defining Variables Verbatim: Defining.).
814
* `#' in a line of a makefile starts a "comment". It and the rest of
815
the line are ignored, except that a trailing backslash not escaped
816
by another backslash will continue the comment across multiple
817
lines. Comments may appear on any of the lines in the makefile,
818
except within a `define' directive, and perhaps within commands
819
(where the shell decides what is a comment). A line containing
820
just a comment (with perhaps spaces before it) is effectively
821
blank, and is ignored.
824
File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles
826
What Name to Give Your Makefile
827
===============================
829
By default, when `make' looks for the makefile, it tries the
830
following names, in order: `GNUmakefile', `makefile' and `Makefile'.
832
Normally you should call your makefile either `makefile' or
833
`Makefile'. (We recommend `Makefile' because it appears prominently
834
near the beginning of a directory listing, right near other important
835
files such as `README'.) The first name checked, `GNUmakefile', is not
836
recommended for most makefiles. You should use this name if you have a
837
makefile that is specific to GNU `make', and will not be understood by
838
other versions of `make'. Other `make' programs look for `makefile' and
839
`Makefile', but not `GNUmakefile'.
841
If `make' finds none of these names, it does not use any makefile.
842
Then you must specify a goal with a command argument, and `make' will
843
attempt to figure out how to remake it using only its built-in implicit
844
rules. *Note Using Implicit Rules: Implicit Rules.
846
If you want to use a nonstandard name for your makefile, you can
847
specify the makefile name with the `-f' or `--file' option. The
848
arguments `-f NAME' or `--file=NAME' tell `make' to read the file NAME
849
as the makefile. If you use more than one `-f' or `--file' option, you
850
can specify several makefiles. All the makefiles are effectively
851
concatenated in the order specified. The default makefile names
852
`GNUmakefile', `makefile' and `Makefile' are not checked automatically
853
if you specify `-f' or `--file'.
856
File: make.info, Node: Include, Next: MAKEFILES Variable, Prev: Makefile Names, Up: Makefiles
858
Including Other Makefiles
859
=========================
861
The `include' directive tells `make' to suspend reading the current
862
makefile and read one or more other makefiles before continuing. The
863
directive is a line in the makefile that looks like this:
867
FILENAMES can contain shell file name patterns.
869
Extra spaces are allowed and ignored at the beginning of the line,
870
but a tab is not allowed. (If the line begins with a tab, it will be
871
considered a command line.) Whitespace is required between `include'
872
and the file names, and between file names; extra whitespace is ignored
873
there and at the end of the directive. A comment starting with `#' is
874
allowed at the end of the line. If the file names contain any variable
875
or function references, they are expanded. *Note How to Use Variables:
878
For example, if you have three `.mk' files, `a.mk', `b.mk', and
879
`c.mk', and `$(bar)' expands to `bish bash', then the following
882
include foo *.mk $(bar)
886
include foo a.mk b.mk c.mk bish bash
888
When `make' processes an `include' directive, it suspends reading of
889
the containing makefile and reads from each listed file in turn. When
890
that is finished, `make' resumes reading the makefile in which the
893
One occasion for using `include' directives is when several programs,
894
handled by individual makefiles in various directories, need to use a
895
common set of variable definitions (*note Setting Variables: Setting.)
896
or pattern rules (*note Defining and Redefining Pattern Rules: Pattern
899
Another such occasion is when you want to generate prerequisites from
900
source files automatically; the prerequisites can be put in a file that
901
is included by the main makefile. This practice is generally cleaner
902
than that of somehow appending the prerequisites to the end of the main
903
makefile as has been traditionally done with other versions of `make'.
904
*Note Automatic Prerequisites::.
906
If the specified name does not start with a slash, and the file is
907
not found in the current directory, several other directories are
908
searched. First, any directories you have specified with the `-I' or
909
`--include-dir' option are searched (*note Summary of Options: Options
910
Summary.). Then the following directories (if they exist) are
911
searched, in this order: `PREFIX/include' (normally `/usr/local/include'
912
(1)) `/usr/gnu/include', `/usr/local/include', `/usr/include'.
914
If an included makefile cannot be found in any of these directories,
915
a warning message is generated, but it is not an immediately fatal
916
error; processing of the makefile containing the `include' continues.
917
Once it has finished reading makefiles, `make' will try to remake any
918
that are out of date or don't exist. *Note How Makefiles Are Remade:
919
Remaking Makefiles. Only after it has tried to find a way to remake a
920
makefile and failed, will `make' diagnose the missing makefile as a
923
If you want `make' to simply ignore a makefile which does not exist
924
and cannot be remade, with no error message, use the `-include'
925
directive instead of `include', like this:
927
-include FILENAMES...
929
This is acts like `include' in every way except that there is no
930
error (not even a warning) if any of the FILENAMES do not exist. For
931
compatibility with some other `make' implementations, `sinclude' is
932
another name for `-include'.
934
---------- Footnotes ----------
936
(1) GNU Make compiled for MS-DOS and MS-Windows behaves as if PREFIX
937
has been defined to be the root of the DJGPP tree hierarchy.
940
File: make.info, Node: MAKEFILES Variable, Next: Remaking Makefiles, Prev: Include, Up: Makefiles
942
The Variable `MAKEFILES'
943
========================
945
If the environment variable `MAKEFILES' is defined, `make' considers
946
its value as a list of names (separated by whitespace) of additional
947
makefiles to be read before the others. This works much like the
948
`include' directive: various directories are searched for those files
949
(*note Including Other Makefiles: Include.). In addition, the default
950
goal is never taken from one of these makefiles and it is not an error
951
if the files listed in `MAKEFILES' are not found.
953
The main use of `MAKEFILES' is in communication between recursive
954
invocations of `make' (*note Recursive Use of `make': Recursion.). It
955
usually is not desirable to set the environment variable before a
956
top-level invocation of `make', because it is usually better not to
957
mess with a makefile from outside. However, if you are running `make'
958
without a specific makefile, a makefile in `MAKEFILES' can do useful
959
things to help the built-in implicit rules work better, such as
960
defining search paths (*note Directory Search::).
962
Some users are tempted to set `MAKEFILES' in the environment
963
automatically on login, and program makefiles to expect this to be done.
964
This is a very bad idea, because such makefiles will fail to work if
965
run by anyone else. It is much better to write explicit `include'
966
directives in the makefiles. *Note Including Other Makefiles: Include.
969
File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: MAKEFILES Variable, Up: Makefiles
971
How Makefiles Are Remade
972
========================
974
Sometimes makefiles can be remade from other files, such as RCS or
975
SCCS files. If a makefile can be remade from other files, you probably
976
want `make' to get an up-to-date version of the makefile to read in.
978
To this end, after reading in all makefiles, `make' will consider
979
each as a goal target and attempt to update it. If a makefile has a
980
rule which says how to update it (found either in that very makefile or
981
in another one) or if an implicit rule applies to it (*note Using
982
Implicit Rules: Implicit Rules.), it will be updated if necessary.
983
After all makefiles have been checked, if any have actually been
984
changed, `make' starts with a clean slate and reads all the makefiles
985
over again. (It will also attempt to update each of them over again,
986
but normally this will not change them again, since they are already up
989
If you know that one or more of your makefiles cannot be remade and
990
you want to keep `make' from performing an implicit rule search on
991
them, perhaps for efficiency reasons, you can use any normal method of
992
preventing implicit rule lookup to do so. For example, you can write an
993
explicit rule with the makefile as the target, and an empty command
994
string (*note Using Empty Commands: Empty Commands.).
996
If the makefiles specify a double-colon rule to remake a file with
997
commands but no prerequisites, that file will always be remade (*note
998
Double-Colon::). In the case of makefiles, a makefile that has a
999
double-colon rule with commands but no prerequisites will be remade
1000
every time `make' is run, and then again after `make' starts over and
1001
reads the makefiles in again. This would cause an infinite loop:
1002
`make' would constantly remake the makefile, and never do anything
1003
else. So, to avoid this, `make' will *not* attempt to remake makefiles
1004
which are specified as targets of a double-colon rule with commands but
1007
If you do not specify any makefiles to be read with `-f' or `--file'
1008
options, `make' will try the default makefile names; *note What Name to
1009
Give Your Makefile: Makefile Names.. Unlike makefiles explicitly
1010
requested with `-f' or `--file' options, `make' is not certain that
1011
these makefiles should exist. However, if a default makefile does not
1012
exist but can be created by running `make' rules, you probably want the
1013
rules to be run so that the makefile can be used.
1015
Therefore, if none of the default makefiles exists, `make' will try
1016
to make each of them in the same order in which they are searched for
1017
(*note What Name to Give Your Makefile: Makefile Names.) until it
1018
succeeds in making one, or it runs out of names to try. Note that it
1019
is not an error if `make' cannot find or make any makefile; a makefile
1020
is not always necessary.
1022
When you use the `-t' or `--touch' option (*note Instead of
1023
Executing the Commands: Instead of Execution.), you would not want to
1024
use an out-of-date makefile to decide which targets to touch. So the
1025
`-t' option has no effect on updating makefiles; they are really
1026
updated even if `-t' is specified. Likewise, `-q' (or `--question')
1027
and `-n' (or `--just-print') do not prevent updating of makefiles,
1028
because an out-of-date makefile would result in the wrong output for
1029
other targets. Thus, `make -f mfile -n foo' will update `mfile', read
1030
it in, and then print the commands to update `foo' and its prerequisites
1031
without running them. The commands printed for `foo' will be those
1032
specified in the updated contents of `mfile'.
1034
However, on occasion you might actually wish to prevent updating of
1035
even the makefiles. You can do this by specifying the makefiles as
1036
goals in the command line as well as specifying them as makefiles.
1037
When the makefile name is specified explicitly as a goal, the options
1038
`-t' and so on do apply to them.
1040
Thus, `make -f mfile -n mfile foo' would read the makefile `mfile',
1041
print the commands needed to update it without actually running them,
1042
and then print the commands needed to update `foo' without running
1043
them. The commands for `foo' will be those specified by the existing
1044
contents of `mfile'.
1047
File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: Remaking Makefiles, Up: Makefiles
1049
Overriding Part of Another Makefile
1050
===================================
1052
Sometimes it is useful to have a makefile that is mostly just like
1053
another makefile. You can often use the `include' directive to include
1054
one in the other, and add more targets or variable definitions.
1055
However, if the two makefiles give different commands for the same
1056
target, `make' will not let you just do this. But there is another way.
1058
In the containing makefile (the one that wants to include the other),
1059
you can use a match-anything pattern rule to say that to remake any
1060
target that cannot be made from the information in the containing
1061
makefile, `make' should look in another makefile. *Note Pattern
1062
Rules::, for more information on pattern rules.
1064
For example, if you have a makefile called `Makefile' that says how
1065
to make the target `foo' (and other targets), you can write a makefile
1066
called `GNUmakefile' that contains:
1072
@$(MAKE) -f Makefile $@
1075
If you say `make foo', `make' will find `GNUmakefile', read it, and
1076
see that to make `foo', it needs to run the command `frobnicate > foo'.
1077
If you say `make bar', `make' will find no way to make `bar' in
1078
`GNUmakefile', so it will use the commands from the pattern rule: `make
1079
-f Makefile bar'. If `Makefile' provides a rule for updating `bar',
1080
`make' will apply the rule. And likewise for any other target that
1081
`GNUmakefile' does not say how to make.
1083
The way this works is that the pattern rule has a pattern of just
1084
`%', so it matches any target whatever. The rule specifies a
1085
prerequisite `force', to guarantee that the commands will be run even
1086
if the target file already exists. We give `force' target empty
1087
commands to prevent `make' from searching for an implicit rule to build
1088
it--otherwise it would apply the same match-anything rule to `force'
1089
itself and create a prerequisite loop!
added
removed
source/3rdparty/qmake/make.info-1
