« back to all changes in this revision
Viewing changes to doc/make.info-1
- browse files at revision 6
- compare with another revision
- download diff
- download tarball
- view history from revision 6
- Committer: Package Import Robot
- Author(s): Manoj Srivastava
- Date: 2014-05-04 18:48:47 UTC
- mfrom: (4.1.1 experimental)
- Revision ID: package-import@ubuntu.com-20140504184847-50zxi1b08m22ehle
Tags: 4.0-2
Move to usntable, since the make binary package has been uploaded
there. No changes.
there. No changes.
- files added:
- .pc
- config
- debian/source
- debian/upstream
- glob
- po
- tests
- tests/scripts
- tests/scripts/features
- tests/scripts/functions
- tests/scripts/misc
- tests/scripts/options
- tests/scripts/targets
- tests/scripts/variables
- w32
- w32/compat
- w32/include
- w32/subproc
- files removed:
- configure.in
- debian/common
- doc/make
- files modified:
- ABOUT-NLS
added
removed
doc/make.info-1
1
This is make.info, produced by makeinfo version 4.8 from make.texi.
1
This is make.info, produced by makeinfo version 4.13 from make.texi.
2
2
3
This file documents the GNU `make' utility, which determines
3
This file documents the GNU `make' utility, which determines
4
4
automatically which pieces of a large program need to be recompiled,
5
5
and issues the commands to recompile them.
6
6
7
This is Edition 0.70, last updated 1 April 2006, of `The GNU Make
8
Manual', for GNU `make' version 3.81.
7
This is Edition 0.72, last updated 9 October 2013, of `The GNU Make
8
Manual', for GNU `make' version 4.0.
9
9
10
10
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
11
1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
12
Foundation, Inc.
11
1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
12
2010, 2011, 2012, 2013 Free Software Foundation, Inc.
13
13
14
14
Permission is granted to copy, distribute and/or modify this
15
15
document under the terms of the GNU Free Documentation License,
16
Version 1.2 or any later version published by the Free Software
16
Version 1.3 or any later version published by the Free Software
17
17
Foundation; with no Invariant Sections, with the Front-Cover Texts
18
18
being "A GNU Manual," and with the Back-Cover Texts as in (a)
19
19
below. A copy of the license is included in the section entitled
20
20
"GNU Free Documentation License."
21
21
22
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
23
modify this GNU Manual, like GNU software. Copies published by
24
the Free Software Foundation raise funds for GNU development."
22
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
23
modify this GNU manual. Buying copies from the FSF supports it in
24
developing GNU and promoting software freedom."
25
25
26
INFO-DIR-SECTION GNU Packages
26
INFO-DIR-SECTION Software development
27
27
START-INFO-DIR-ENTRY
28
28
* Make: (make). Remake files automatically.
29
29
END-INFO-DIR-ENTRY
38
38
automatically which pieces of a large program need to be recompiled,
39
39
and issues the commands to recompile them.
40
40
41
This is Edition 0.70, last updated 1 April 2006, of `The GNU Make
42
Manual', for GNU `make' version 3.81.
41
This is Edition 0.72, last updated 9 October 2013, of `The GNU Make
42
Manual', for GNU `make' version 4.0.
43
43
44
44
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
45
1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
46
Foundation, Inc.
45
1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
46
2010, 2011, 2012, 2013 Free Software Foundation, Inc.
47
47
48
48
Permission is granted to copy, distribute and/or modify this
49
49
document under the terms of the GNU Free Documentation License,
50
Version 1.2 or any later version published by the Free Software
50
Version 1.3 or any later version published by the Free Software
51
51
Foundation; with no Invariant Sections, with the Front-Cover Texts
52
52
being "A GNU Manual," and with the Back-Cover Texts as in (a)
53
53
below. A copy of the license is included in the section entitled
54
54
"GNU Free Documentation License."
55
55
56
(a) The FSF's Back-Cover Text is: "You have freedom to copy and
57
modify this GNU Manual, like GNU software. Copies published by
58
the Free Software Foundation raise funds for GNU development."
56
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
57
modify this GNU manual. Buying copies from the FSF supports it in
58
developing GNU and promoting software freedom."
59
59
60
60
* Menu:
61
61
63
63
* Introduction:: An introduction to `make'.
64
64
* Makefiles:: Makefiles tell `make' what to do.
65
65
* Rules:: Rules describe when a file must be remade.
66
* Commands:: Commands say how to remake a file.
66
* Recipes:: Recipes say how to remake a file.
67
67
* Using Variables:: You can use variables to avoid repetition.
68
68
* Conditionals:: Use or ignore parts of the makefile based
69
69
on the values of variables.
72
72
* Implicit Rules:: Use implicit rules to treat many files alike,
73
73
based on their file names.
74
74
* Archives:: How `make' can update library archives.
75
* Extending make:: Using extensions to `make'.
75
76
* Features:: Features GNU `make' has over other `make's.
76
77
* Missing:: What GNU `make' lacks from other `make's.
77
78
* Makefile Conventions:: Conventions for writing makefiles for
81
82
* Complex Makefile:: A real example of a straightforward,
82
83
but nontrivial, makefile.
83
84
84
* GNU Free Documentation License:: License for copying this manual
85
* Concept Index:: Index of Concepts
86
* Name Index:: Index of Functions, Variables, & Directives
85
* GNU Free Documentation License:: License for copying this manual.
86
* Concept Index:: Index of Concepts.
87
* Name Index:: Index of Functions, Variables, & Directives.
87
88
88
89
--- The Detailed Node Listing ---
89
90
90
91
Overview of `make'
91
92
92
* Preparing:: Preparing and Running Make
93
* Reading:: On Reading this Text
94
* Bugs:: Problems and Bugs
93
* Preparing:: Preparing and running `make'.
94
* Reading:: On reading this text.
95
* Bugs:: Problems and bugs.
95
96
96
97
An Introduction to Makefiles
97
98
98
99
* Rule Introduction:: What a rule looks like.
99
* Simple Makefile:: A Simple Makefile
100
* How Make Works:: How `make' Processes This Makefile
101
* Variables Simplify:: Variables Make Makefiles Simpler
102
* make Deduces:: Letting `make' Deduce the Commands
103
* Combine By Prerequisite:: Another Style of Makefile
104
* Cleanup:: Rules for Cleaning the Directory
100
* Simple Makefile:: A simple makefile.
101
* How Make Works:: How `make' processes this makefile.
102
* Variables Simplify:: Variables make makefiles simpler.
103
* make Deduces:: Letting `make' deduce the recipes.
104
* Combine By Prerequisite:: Another style of makefile.
105
* Cleanup:: Rules for cleaning the directory.
105
106
106
107
Writing Makefiles
107
108
109
110
* Makefile Names:: How to name your makefile.
110
111
* Include:: How one makefile can use another makefile.
111
112
* MAKEFILES Variable:: The environment can specify extra makefiles.
112
* MAKEFILE_LIST Variable:: Discover which makefiles have been read.
113
* Special Variables:: Other special variables.
114
113
* Remaking Makefiles:: How makefiles get remade.
115
114
* Overriding Makefiles:: How to override part of one makefile
116
115
with another makefile.
117
116
* Reading Makefiles:: How makefiles are parsed.
118
117
* Secondary Expansion:: How and when secondary expansion is performed.
119
118
119
What Makefiles Contain
120
121
* Splitting Lines:: Splitting long lines in makefiles
122
120
123
Writing Rules
121
124
122
125
* Rule Example:: An example explained.
125
128
* Wildcards:: Using wildcard characters such as `*'.
126
129
* Directory Search:: Searching other directories for source files.
127
130
* Phony Targets:: Using a target that is not a real file's name.
128
* Force Targets:: You can use a target without commands
131
* Force Targets:: You can use a target without a recipe
129
132
or prerequisites to mark other targets
130
133
as phony.
131
134
* Empty Targets:: When only the date matters and the
143
146
144
147
Using Wildcard Characters in File Names
145
148
146
* Wildcard Examples:: Several examples
149
* Wildcard Examples:: Several examples.
147
150
* Wildcard Pitfall:: Problems to avoid.
148
151
* Wildcard Function:: How to cause wildcard expansion where
149
152
it does not normally take place.
155
158
* Selective Search:: Specifying a search path
156
159
for a specified class of names.
157
160
* Search Algorithm:: When and how search paths are applied.
158
* Commands/Search:: How to write shell commands that work together
161
* Recipes/Search:: How to write recipes that work together
159
162
with search paths.
160
163
* Implicit/Search:: How search paths affect implicit rules.
161
164
* Libraries/Search:: Directory search for link libraries.
165
168
* Static Usage:: The syntax of static pattern rules.
166
169
* Static versus Implicit:: When are they better than implicit rules?
167
170
168
Writing the Commands in Rules
171
Writing Recipes in Rules
169
172
170
* Command Syntax:: Command syntax features and pitfalls.
171
* Echoing:: How to control when commands are echoed.
172
* Execution:: How commands are executed.
173
* Parallel:: How commands can be executed in parallel.
174
* Errors:: What happens after a command execution error.
175
* Interrupts:: What happens when a command is interrupted.
173
* Recipe Syntax:: Recipe syntax features and pitfalls.
174
* Echoing:: How to control when recipes are echoed.
175
* Execution:: How recipes are executed.
176
* Parallel:: How recipes can be executed in parallel.
177
* Errors:: What happens after a recipe execution error.
178
* Interrupts:: What happens when a recipe is interrupted.
176
179
* Recursion:: Invoking `make' from makefiles.
177
* Sequences:: Defining canned sequences of commands.
178
* Empty Commands:: Defining useful, do-nothing commands.
179
180
Command Syntax
181
182
* Splitting Lines:: Breaking long command lines for readability.
183
* Variables in Commands:: Using `make' variables in commands.
184
185
Command Execution
186
180
* Canned Recipes:: Defining canned recipes.
181
* Empty Recipes:: Defining useful, do-nothing recipes.
182
183
Recipe Syntax
184
185
* Splitting Recipe Lines:: Breaking long recipe lines for readability.
186
* Variables in Recipes:: Using `make' variables in recipes.
187
188
Recipe Execution
189
190
* One Shell:: One shell for all lines in a recipe.
187
191
* Choosing the Shell:: How `make' chooses the shell used
188
to run commands.
192
to run recipes.
193
194
Parallel Execution
195
196
* Parallel Output:: Handling output during parallel execution
197
* Parallel Input:: Handling input during parallel execution
189
198
190
199
Recursive Use of `make'
191
200
206
215
of a variable.
207
216
* Override Directive:: How to set a variable in the makefile even if
208
217
the user has set it with a command argument.
209
* Defining:: An alternate way to set a variable
210
to a verbatim string.
218
* Multi-Line:: An alternate way to set a variable
219
to a multi-line string.
220
* Undefine Directive:: How to undefine a variable so that it appears
221
as if it was never set.
211
222
* Environment:: Variable values can come from the environment.
212
223
* Target-specific:: Variable values can be defined on a per-target
213
224
basis.
214
225
* Pattern-specific:: Target-specific variable values can be applied
215
226
to a group of targets that match a pattern.
227
* Suppressing Inheritance:: Suppress inheritance of variables.
228
* Special Variables:: Variables with special meaning or behavior.
216
229
217
230
Advanced Features for Reference to Variables
218
231
233
246
* File Name Functions:: Functions for manipulating file names.
234
247
* Conditional Functions:: Functions that implement conditions.
235
248
* Foreach Function:: Repeat some text with controlled variation.
249
* File Function:: Write text to a file.
236
250
* Call Function:: Expand a user-defined function.
237
251
* Value Function:: Return the un-expanded value of a variable.
238
252
* Eval Function:: Evaluate the arguments as makefile syntax.
239
253
* Origin Function:: Find where a variable got its value.
240
254
* Flavor Function:: Find out the flavor of a variable.
255
* Make Control Functions:: Functions that control how make runs.
241
256
* Shell Function:: Substitute the output of a shell command.
242
* Make Control Functions:: Functions that control how make runs.
257
* Guile Function:: Use GNU Guile embedded scripting language.
243
258
244
259
How to Run `make'
245
260
247
262
* Goals:: How to use goal arguments to specify which
248
263
parts of the makefile to use.
249
264
* Instead of Execution:: How to use mode flags to specify what
250
kind of thing to do with the commands
265
kind of thing to do with the recipes
251
266
in the makefile other than simply
252
267
execute them.
253
268
* Avoiding Compilation:: How to avoid recompiling certain files.
260
275
Using Implicit Rules
261
276
262
277
* Using Implicit:: How to use an existing implicit rule
263
to get the commands for updating a file.
278
to get the recipes for updating a file.
264
279
* Catalogue of Rules:: A list of built-in implicit rules.
265
280
* Implicit Variables:: How to change what predefined rules do.
266
281
* Chained Rules:: How to use a chain of implicit rules.
267
282
* Pattern Rules:: How to define new implicit rules.
268
* Last Resort:: How to define commands for rules which
283
* Last Resort:: How to define a recipe for rules which
269
284
cannot find any.
270
285
* Suffix Rules:: The old-fashioned style of implicit rule.
271
286
* Implicit Rule Search:: The precise algorithm for applying
276
291
* Pattern Intro:: An introduction to pattern rules.
277
292
* Pattern Examples:: Examples of pattern rules.
278
293
* Automatic Variables:: How to use automatic variables in the
279
commands of implicit rules.
294
recipe of implicit rules.
280
295
* Pattern Match:: How patterns match.
281
296
* Match-Anything Rules:: Precautions you should take prior to
282
297
defining rules that can match any
295
310
296
311
* Archive Symbols:: How to update archive symbol directories.
297
312
313
Extending GNU `make'
314
315
* Guile Integration:: Using Guile as an embedded scripting language.
316
* Loading Objects:: Loading dynamic objects as extensions.
317
318
GNU Guile Integration
319
320
* Guile Types:: Converting Guile types to `make' strings.
321
* Guile Interface:: Invoking `make' functions from Guile.
322
* Guile Example:: Example using Guile in `make'.
323
324
Loading Dynamic Objects
325
326
* load Directive:: Loading dynamic objects as extensions.
327
* Remaking Loaded Objects:: How loaded objects get remade.
328
* Loaded Object API:: Programmatic interface for loaded objects.
329
* Loaded Object Example:: Example of a loaded object
330
298
331
299
332
File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top
300
333
318
351
319
352
* Menu:
320
353
321
* Preparing:: Preparing and Running Make
322
* Reading:: On Reading this Text
323
* Bugs:: Problems and Bugs
354
* Preparing:: Preparing and running `make'.
355
* Reading:: On reading this text.
356
* Bugs:: Problems and bugs.
324
357
325
358
326
359
File: make.info, Node: Preparing, Next: Reading, Prev: Overview, Up: Overview
342
375
suffices to perform all necessary recompilations. The `make' program
343
376
uses the makefile data base and the last-modification times of the
344
377
files to decide which of the files need to be updated. For each of
345
those files, it issues the commands recorded in the data base.
378
those files, it issues the recipes recorded in the data base.
346
379
347
380
You can provide command line arguments to `make' to control which
348
381
files should be recompiled, or how. *Note How to Run `make': Running.
357
390
read the first few sections of each chapter, skipping the later
358
391
sections. In each chapter, the first few sections contain introductory
359
392
or general information and the later sections contain specialized or
360
technical information. The exception is the second chapter, *Note An
393
technical information. The exception is the second chapter, *note An
361
394
Introduction to Makefiles: Introduction, all of which is introductory.
362
395
363
If you are familiar with other `make' programs, see *Note Features
396
If you are familiar with other `make' programs, see *note Features
364
397
of GNU `make': Features, which lists the enhancements GNU `make' has,
365
and *Note Incompatibilities and Missing Features: Missing, which
398
and *note Incompatibilities and Missing Features: Missing, which
366
399
explains the few things GNU `make' lacks that others have.
367
400
368
For a quick summary, see *Note Options Summary::, *Note Quick
369
Reference::, and *Note Special Targets::.
401
For a quick summary, see *note Options Summary::, *note Quick
402
Reference::, and *note Special Targets::.
370
403
371
404
372
405
File: make.info, Node: Bugs, Prev: Reading, Up: Overview
390
423
any error or warning messages. Please don't paraphrase these messages:
391
424
it's best to cut and paste them into your report. When generating this
392
425
small makefile, be sure to not use any non-free or unusual tools in
393
your commands: you can almost always emulate what such a tool would do
426
your recipes: you can almost always emulate what such a tool would do
394
427
with simple shell commands. Finally, be sure to explain what you
395
428
expected to occur; this will help us decide whether the problem was
396
429
really in the documentation.
425
458
files and three header files. The makefile can also tell `make' how to
426
459
run miscellaneous commands when explicitly asked (for example, to remove
427
460
certain files as a clean-up operation). To see a more complex example
428
of a makefile, see *Note Complex Makefile::.
461
of a makefile, see *note Complex Makefile::.
429
462
430
463
When `make' recompiles the editor, each changed C source file must
431
464
be recompiled. If a header file has changed, each C source file that
438
471
* Menu:
439
472
440
473
* Rule Introduction:: What a rule looks like.
441
* Simple Makefile:: A Simple Makefile
442
* How Make Works:: How `make' Processes This Makefile
443
* Variables Simplify:: Variables Make Makefiles Simpler
444
* make Deduces:: Letting `make' Deduce the Commands
445
* Combine By Prerequisite:: Another Style of Makefile
446
* Cleanup:: Rules for Cleaning the Directory
474
* Simple Makefile:: A simple makefile.
475
* How Make Works:: How `make' processes this makefile.
476
* Variables Simplify:: Variables make makefiles simpler.
477
* make Deduces:: Letting `make' deduce the recipes.
478
* Combine By Prerequisite:: Another style of makefile.
479
* Cleanup:: Rules for cleaning the directory.
447
480
448
481
449
482
File: make.info, Node: Rule Introduction, Next: Simple Makefile, Prev: Introduction, Up: Introduction
454
487
A simple makefile consists of "rules" with the following shape:
455
488
456
489
TARGET ... : PREREQUISITES ...
457
COMMAND
490
RECIPE
458
491
...
459
492
...
460
493
466
499
A "prerequisite" is a file that is used as input to create the
467
500
target. A target often depends on several files.
468
501
469
A "command" is an action that `make' carries out. A rule may have
470
more than one command, each on its own line. *Please note:* you need
471
to put a tab character at the beginning of every command line! This is
472
an obscurity that catches the unwary.
502
A "recipe" is an action that `make' carries out. A recipe may have
503
more than one command, either on the same line or each on its own line.
504
*Please note:* you need to put a tab character at the beginning of
505
every recipe line! This is an obscurity that catches the unwary. If
506
you prefer to prefix your recipes with a character other than tab, you
507
can set the `.RECIPEPREFIX' variable to an alternate character (*note
508
Special Variables::).
473
509
474
Usually a command is in a rule with prerequisites and serves to
510
Usually a recipe is in a rule with prerequisites and serves to
475
511
create a target file if any of the prerequisites change. However, the
476
rule that specifies commands for the target need not have
512
rule that specifies a recipe for the target need not have
477
513
prerequisites. For example, the rule containing the delete command
478
514
associated with the target `clean' does not have prerequisites.
479
515
480
516
A "rule", then, explains how and when to remake certain files which
481
are the targets of the particular rule. `make' carries out the
482
commands on the prerequisites to create or update the target. A rule
483
can also explain how and when to carry out an action. *Note Writing
484
Rules: Rules.
517
are the targets of the particular rule. `make' carries out the recipe
518
on the prerequisites to create or update the target. A rule can also
519
explain how and when to carry out an action. *Note Writing Rules:
520
Rules.
485
521
486
522
A makefile may contain other text besides rules, but a simple
487
523
makefile need only contain rules. Rules may look somewhat more
527
563
rm edit main.o kbd.o command.o display.o \
528
564
insert.o search.o files.o utils.o
529
565
530
We split each long line into two lines using backslash-newline; this is
531
like using one long line, but is easier to read.
566
We split each long line into two lines using backslash/newline; this is
567
like using one long line, but is easier to read. *Note Splitting Long
568
Lines: Splitting Lines.
532
569
533
570
To use this makefile to create the executable file called `edit',
534
571
type:
543
580
In the example makefile, the targets include the executable file
544
581
`edit', and the object files `main.o' and `kbd.o'. The prerequisites
545
582
are files such as `main.c' and `defs.h'. In fact, each `.o' file is
546
both a target and a prerequisite. Commands include `cc -c main.c' and
583
both a target and a prerequisite. Recipes include `cc -c main.c' and
547
584
`cc -c kbd.c'.
548
585
549
586
When a target is a file, it needs to be recompiled or relinked if any
553
590
file `main.o' depends on the source file `main.c' and on the header
554
591
file `defs.h'.
555
592
556
A shell command follows each line that contains a target and
557
prerequisites. These shell commands say how to update the target file.
558
A tab character must come at the beginning of every command line to
559
distinguish command lines from other lines in the makefile. (Bear in
560
mind that `make' does not know anything about how the commands work.
561
It is up to you to supply commands that will update the target file
562
properly. All `make' does is execute the commands in the rule you have
563
specified when the target file needs to be updated.)
593
A recipe may follow each line that contains a target and
594
prerequisites. These recipes say how to update the target file. A tab
595
character (or whatever character is specified by the `.RECIPEPREFIX'
596
variable; *note Special Variables::) must come at the beginning of
597
every line in the recipe to distinguish recipes from other lines in the
598
makefile. (Bear in mind that `make' does not know anything about how
599
the recipes work. It is up to you to supply recipes that will update
600
the target file properly. All `make' does is execute the recipe you
601
have specified when the target file needs to be updated.)
564
602
565
603
The target `clean' is not a file, but merely the name of an action.
566
604
Since you normally do not want to carry out the actions in this rule,
568
606
never does anything with it unless you tell it specifically. Note that
569
607
this rule not only is not a prerequisite, it also does not have any
570
608
prerequisites, so the only purpose of the rule is to run the specified
571
commands. Targets that do not refer to files but are just actions are
609
recipe. Targets that do not refer to files but are just actions are
572
610
called "phony targets". *Note Phony Targets::, for information about
573
this kind of target. *Note Errors in Commands: Errors, to see how to
611
this kind of target. *Note Errors in Recipes: Errors, to see how to
574
612
cause `make' to ignore errors from `rm' or any other command.
575
613
576
614
689
727
690
728
File: make.info, Node: make Deduces, Next: Combine By Prerequisite, Prev: Variables Simplify, Up: Introduction
691
729
692
2.5 Letting `make' Deduce the Commands
693
======================================
730
2.5 Letting `make' Deduce the Recipes
731
=====================================
694
732
695
It is not necessary to spell out the commands for compiling the
733
It is not necessary to spell out the recipes for compiling the
696
734
individual C source files, because `make' can figure them out: it has an
697
735
"implicit rule" for updating a `.o' file from a correspondingly named
698
`.c' file using a `cc -c' command. For example, it will use the
699
command `cc -c main.c -o main.o' to compile `main.c' into `main.o'. We
700
can therefore omit the commands from the rules for the object files.
701
*Note Using Implicit Rules: Implicit Rules.
736
`.c' file using a `cc -c' command. For example, it will use the recipe
737
`cc -c main.c -o main.o' to compile `main.c' into `main.o'. We can
738
therefore omit the recipes from the rules for the object files. *Note
739
Using Implicit Rules: Implicit Rules.
702
740
703
741
When a `.c' file is used automatically in this way, it is also
704
742
automatically added to the list of prerequisites. We can therefore omit
705
the `.c' files from the prerequisites, provided we omit the commands.
743
the `.c' files from the prerequisites, provided we omit the recipe.
706
744
707
745
Here is the entire example, with both of these changes, and a
708
746
variable `objects' as suggested above:
728
766
729
767
This is how we would write the makefile in actual practice. (The
730
768
complications associated with `clean' are described elsewhere. See
731
*Note Phony Targets::, and *Note Errors in Commands: Errors.)
769
*note Phony Targets::, and *note Errors in Recipes: Errors.)
732
770
733
771
Because implicit rules are so convenient, they are important. You
734
772
will see them used frequently.
789
827
790
828
This prevents `make' from getting confused by an actual file called
791
829
`clean' and causes it to continue in spite of errors from `rm'. (See
792
*Note Phony Targets::, and *Note Errors in Commands: Errors.)
830
*note Phony Targets::, and *note Errors in Recipes: Errors.)
793
831
794
832
A rule such as this should not be placed at the beginning of the
795
833
makefile, because we do not want it to run by default! Thus, in the
816
854
* Makefile Names:: How to name your makefile.
817
855
* Include:: How one makefile can use another makefile.
818
856
* MAKEFILES Variable:: The environment can specify extra makefiles.
819
* MAKEFILE_LIST Variable:: Discover which makefiles have been read.
820
* Special Variables:: Other special variables.
821
857
* Remaking Makefiles:: How makefiles get remade.
822
858
* Overriding Makefiles:: How to override part of one makefile
823
859
with another makefile.
837
873
* An "explicit rule" says when and how to remake one or more files,
838
874
called the rule's "targets". It lists the other files that the
839
875
targets depend on, called the "prerequisites" of the target, and
840
may also give commands to use to create or update the targets.
876
may also give a recipe to use to create or update the targets.
841
877
*Note Writing Rules: Rules.
842
878
843
879
* An "implicit rule" says when and how to remake a class of files
844
880
based on their names. It describes how a target may depend on a
845
file with a name similar to the target and gives commands to
881
file with a name similar to the target and gives a recipe to
846
882
create or update such a target. *Note Using Implicit Rules:
847
883
Implicit Rules.
848
884
852
888
`objects' as a list of all object files (*note Variables Make
853
889
Makefiles Simpler: Variables Simplify.).
854
890
855
* A "directive" is a command for `make' to do something special while
856
reading the makefile. These include:
891
* A "directive" is an instruction for `make' to do something special
892
while reading the makefile. These include:
857
893
858
894
* Reading another makefile (*note Including Other Makefiles:
859
895
Include.).
863
899
Makefiles: Conditionals.).
864
900
865
901
* Defining a variable from a verbatim string containing
866
multiple lines (*note Defining Variables Verbatim: Defining.).
902
multiple lines (*note Defining Multi-Line Variables:
903
Multi-Line.).
867
904
868
905
* `#' in a line of a makefile starts a "comment". It and the rest
869
906
of the line are ignored, except that a trailing backslash not
874
911
Comments may appear on any line in the makefile, although they are
875
912
treated specially in certain situations.
876
913
877
Within a command script (if the line begins with a TAB character)
878
the entire line is passed to the shell, just as with any other
879
line that begins with a TAB. The shell decides how to interpret
880
the text: whether or not this is a comment is up to the shell.
914
You cannot use comments within variable references or function
915
calls: any instance of `#' will be treated literally (rather than
916
as the start of a comment) inside a variable reference or function
917
call.
918
919
Comments within a recipe are passed to the shell, just as with any
920
other recipe text. The shell decides how to interpret it: whether
921
or not this is a comment is up to the shell.
881
922
882
923
Within a `define' directive, comments are not ignored during the
883
924
definition of the variable, but rather kept intact in the value of
884
925
the variable. When the variable is expanded they will either be
885
treated as `make' comments or as command script text, depending on
886
the context in which the variable is evaluated.
926
treated as `make' comments or as recipe text, depending on the
927
context in which the variable is evaluated.
928
929
* Menu:
930
931
* Splitting Lines:: Splitting long lines in makefiles
932
933
934
File: make.info, Node: Splitting Lines, Prev: Makefile Contents, Up: Makefile Contents
935
936
3.1.1 Splitting Long Lines
937
--------------------------
938
939
Makefiles use a "line-based" syntax in which the newline character is
940
special and marks the end of a statement. GNU `make' has no limit on
941
the length of a statement line, up to the amount of memory in your
942
computer.
943
944
However, it is difficult to read lines which are too long to display
945
without wrapping or scrolling. So, you can format your makefiles for
946
readability by adding newlines into the middle of a statement: you do
947
this by escaping the internal newlines with a backslash (`\')
948
character. Where we need to make a distinction we will refer to
949
"physical lines" as a single line ending with a newline (regardless of
950
whether it is escaped) and a "logical line" being a complete statement
951
including all escaped newlines up to the first non-escaped newline.
952
953
The way in which backslash/newline combinations are handled depends
954
on whether the statement is a recipe line or a non-recipe line.
955
Handling of backslash/newline in a recipe line is discussed later
956
(*note Splitting Recipe Lines::).
957
958
Outside of recipe lines, backslash/newlines are converted into a
959
single space character. Once that is done, all whitespace around the
960
backslash/newline is condensed into a single space: this includes all
961
whitespace preceding the backslash, all whitespace at the beginning of
962
the line after the backslash/newline, and any consecutive
963
backslash/newline combinations.
964
965
If the `.POSIX' special target is defined then backslash/newline
966
handling is modified slightly to conform to POSIX.2: first, whitespace
967
preceding a backslash is not removed and second, consecutive
968
backslash/newlines are not condensed.
887
969
888
970
889
971
File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles
933
1015
nothing is included and no error is printed.
934
1016
935
1017
Extra spaces are allowed and ignored at the beginning of the line,
936
but a tab is not allowed. (If the line begins with a tab, it will be
937
considered a command line.) Whitespace is required between `include'
938
and the file names, and between file names; extra whitespace is ignored
939
there and at the end of the directive. A comment starting with `#' is
940
allowed at the end of the line. If the file names contain any variable
941
or function references, they are expanded. *Note How to Use Variables:
1018
but the first character must not be a tab (or the value of
1019
`.RECIPEPREFIX')--if the line begins with a tab, it will be considered
1020
a recipe line. Whitespace is required between `include' and the file
1021
names, and between file names; extra whitespace is ignored there and at
1022
the end of the directive. A comment starting with `#' is allowed at
1023
the end of the line. If the file names contain any variable or
1024
function references, they are expanded. *Note How to Use Variables:
942
1025
Using Variables.
943
1026
944
1027
For example, if you have three `.mk' files, `a.mk', `b.mk', and
987
1070
fatal error.
988
1071
989
1072
If you want `make' to simply ignore a makefile which does not exist
990
and cannot be remade, with no error message, use the `-include'
1073
or cannot be remade, with no error message, use the `-include'
991
1074
directive instead of `include', like this:
992
1075
993
1076
-include FILENAMES...
994
1077
995
1078
This acts like `include' in every way except that there is no error
996
(not even a warning) if any of the FILENAMES do not exist. For
997
compatibility with some other `make' implementations, `sinclude' is
998
another name for `-include'.
1079
(not even a warning) if any of the FILENAMES (or any prerequisites of
1080
any of the FILENAMES) do not exist or cannot be remade.
1081
1082
For compatibility with some other `make' implementations, `sinclude'
1083
is another name for `-include'.
999
1084
1000
1085
---------- Footnotes ----------
1001
1086
1003
1088
has been defined to be the root of the DJGPP tree hierarchy.
1004
1089
1005
1090
1006
File: make.info, Node: MAKEFILES Variable, Next: MAKEFILE_LIST Variable, Prev: Include, Up: Makefiles
1091
File: make.info, Node: MAKEFILES Variable, Next: Remaking Makefiles, Prev: Include, Up: Makefiles
1007
1092
1008
1093
3.4 The Variable `MAKEFILES'
1009
1094
============================
1013
1098
makefiles to be read before the others. This works much like the
1014
1099
`include' directive: various directories are searched for those files
1015
1100
(*note Including Other Makefiles: Include.). In addition, the default
1016
goal is never taken from one of these makefiles and it is not an error
1017
if the files listed in `MAKEFILES' are not found.
1101
goal is never taken from one of these makefiles (or any makefile
1102
included by them) and it is not an error if the files listed in
1103
`MAKEFILES' are not found.
1018
1104
1019
1105
The main use of `MAKEFILES' is in communication between recursive
1020
1106
invocations of `make' (*note Recursive Use of `make': Recursion.). It
1032
1118
directives in the makefiles. *Note Including Other Makefiles: Include.
1033
1119
1034
1120
1035
File: make.info, Node: MAKEFILE_LIST Variable, Next: Special Variables, Prev: MAKEFILES Variable, Up: Makefiles
1036
1037
3.5 The Variable `MAKEFILE_LIST'
1038
================================
1039
1040
As `make' reads various makefiles, including any obtained from the
1041
`MAKEFILES' variable, the command line, the default files, or from
1042
`include' directives, their names will be automatically appended to the
1043
`MAKEFILE_LIST' variable. They are added right before `make' begins to
1044
parse them.
1045
1046
This means that if the first thing a makefile does is examine the
1047
last word in this variable, it will be the name of the current makefile.
1048
Once the current makefile has used `include', however, the last word
1049
will be the just-included makefile.
1050
1051
If a makefile named `Makefile' has this content:
1052
1053
name1 := $(lastword $(MAKEFILE_LIST))
1054
1055
include inc.mk
1056
1057
name2 := $(lastword $(MAKEFILE_LIST))
1058
1059
all:
1060
@echo name1 = $(name1)
1061
@echo name2 = $(name2)
1062
1063
then you would expect to see this output:
1064
1065
name1 = Makefile
1066
name2 = inc.mk
1067
1068
*Note Text Functions::, for more information on the `word' and
1069
`words' functions used above. *Note The Two Flavors of Variables:
1070
Flavors, for more information on simply-expanded (`:=') variable
1071
definitions.
1072
1073
1074
File: make.info, Node: Special Variables, Next: Remaking Makefiles, Prev: MAKEFILE_LIST Variable, Up: Makefiles
1075
1076
3.6 Other Special Variables
1077
===========================
1078
1079
GNU `make' also supports other special variables. Unless otherwise
1080
documented here, these values lose their special properties if they are
1081
set by a makefile or on the command line.
1082
1083
`.DEFAULT_GOAL'
1084
Sets the default goal to be used if no targets were specified on
1085
the command line (*note Arguments to Specify the Goals: Goals.).
1086
The `.DEFAULT_GOAL' variable allows you to discover the current
1087
default goal, restart the default goal selection algorithm by
1088
clearing its value, or to explicitly set the default goal. The
1089
following example illustrates these cases:
1090
1091
# Query the default goal.
1092
ifeq ($(.DEFAULT_GOAL),)
1093
$(warning no default goal is set)
1094
endif
1095
1096
.PHONY: foo
1097
foo: ; @echo $@
1098
1099
$(warning default goal is $(.DEFAULT_GOAL))
1100
1101
# Reset the default goal.
1102
.DEFAULT_GOAL :=
1103
1104
.PHONY: bar
1105
bar: ; @echo $@
1106
1107
$(warning default goal is $(.DEFAULT_GOAL))
1108
1109
# Set our own.
1110
.DEFAULT_GOAL := foo
1111
1112
This makefile prints:
1113
1114
no default goal is set
1115
default goal is foo
1116
default goal is bar
1117
foo
1118
1119
Note that assigning more than one target name to `.DEFAULT_GOAL' is
1120
illegal and will result in an error.
1121
1122
`MAKE_RESTARTS'
1123
This variable is set only if this instance of `make' has restarted
1124
(*note How Makefiles Are Remade: Remaking Makefiles.): it will
1125
contain the number of times this instance has restarted. Note
1126
this is not the same as recursion (counted by the `MAKELEVEL'
1127
variable). You should not set, modify, or export this variable.
1128
1129
`.VARIABLES'
1130
Expands to a list of the _names_ of all global variables defined
1131
so far. This includes variables which have empty values, as well
1132
as built-in variables (*note Variables Used by Implicit Rules:
1133
Implicit Variables.), but does not include any variables which are
1134
only defined in a target-specific context. Note that any value
1135
you assign to this variable will be ignored; it will always return
1136
its special value.
1137
1138
`.FEATURES'
1139
Expands to a list of special features supported by this version of
1140
`make'. Possible values include:
1141
1142
`archives'
1143
Supports `ar' (archive) files using special filename syntax.
1144
*Note Using `make' to Update Archive Files: Archives.
1145
1146
`check-symlink'
1147
Supports the `-L' (`--check-symlink-times') flag. *Note
1148
Summary of Options: Options Summary.
1149
1150
`else-if'
1151
Supports "else if" non-nested conditionals. *Note Syntax of
1152
Conditionals: Conditional Syntax.
1153
1154
`jobserver'
1155
Supports "job server" enhanced parallel builds. *Note
1156
Parallel Execution: Parallel.
1157
1158
`second-expansion'
1159
Supports secondary expansion of prerequisite lists.
1160
1161
`order-only'
1162
Supports order-only prerequisites. *Note Types of
1163
Prerequisites: Prerequisite Types.
1164
1165
`target-specific'
1166
Supports target-specific and pattern-specific variable
1167
assignments. *Note Target-specific Variable Values:
1168
Target-specific.
1169
1170
1171
`.INCLUDE_DIRS'
1172
Expands to a list of directories that `make' searches for included
1173
makefiles (*note Including Other Makefiles: Include.).
1174
1175
1176
1177
File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: Special Variables, Up: Makefiles
1178
1179
3.7 How Makefiles Are Remade
1121
File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: MAKEFILES Variable, Up: Makefiles
1122
1123
3.5 How Makefiles Are Remade
1180
1124
============================
1181
1125
1182
1126
Sometimes makefiles can be remade from other files, such as RCS or SCCS
1197
1141
If you know that one or more of your makefiles cannot be remade and
1198
1142
you want to keep `make' from performing an implicit rule search on
1199
1143
them, perhaps for efficiency reasons, you can use any normal method of
1200
preventing implicit rule lookup to do so. For example, you can write an
1201
explicit rule with the makefile as the target, and an empty command
1202
string (*note Using Empty Commands: Empty Commands.).
1144
preventing implicit rule look-up to do so. For example, you can write
1145
an explicit rule with the makefile as the target, and an empty recipe
1146
(*note Using Empty Recipes: Empty Recipes.).
1203
1147
1204
If the makefiles specify a double-colon rule to remake a file with
1205
commands but no prerequisites, that file will always be remade (*note
1148
If the makefiles specify a double-colon rule to remake a file with a
1149
recipe but no prerequisites, that file will always be remade (*note
1206
1150
Double-Colon::). In the case of makefiles, a makefile that has a
1207
double-colon rule with commands but no prerequisites will be remade
1151
double-colon rule with a recipe but no prerequisites will be remade
1208
1152
every time `make' is run, and then again after `make' starts over and
1209
1153
reads the makefiles in again. This would cause an infinite loop:
1210
1154
`make' would constantly remake the makefile, and never do anything
1211
1155
else. So, to avoid this, `make' will *not* attempt to remake makefiles
1212
which are specified as targets of a double-colon rule with commands but
1156
which are specified as targets of a double-colon rule with a recipe but
1213
1157
no prerequisites.
1214
1158
1215
1159
If you do not specify any makefiles to be read with `-f' or `--file'
1228
1172
is not always necessary.
1229
1173
1230
1174
When you use the `-t' or `--touch' option (*note Instead of
1231
Executing the Commands: Instead of Execution.), you would not want to
1232
use an out-of-date makefile to decide which targets to touch. So the
1233
`-t' option has no effect on updating makefiles; they are really
1234
updated even if `-t' is specified. Likewise, `-q' (or `--question')
1235
and `-n' (or `--just-print') do not prevent updating of makefiles,
1236
because an out-of-date makefile would result in the wrong output for
1237
other targets. Thus, `make -f mfile -n foo' will update `mfile', read
1238
it in, and then print the commands to update `foo' and its prerequisites
1239
without running them. The commands printed for `foo' will be those
1240
specified in the updated contents of `mfile'.
1175
Executing Recipes: Instead of Execution.), you would not want to use an
1176
out-of-date makefile to decide which targets to touch. So the `-t'
1177
option has no effect on updating makefiles; they are really updated
1178
even if `-t' is specified. Likewise, `-q' (or `--question') and `-n'
1179
(or `--just-print') do not prevent updating of makefiles, because an
1180
out-of-date makefile would result in the wrong output for other targets.
1181
Thus, `make -f mfile -n foo' will update `mfile', read it in, and then
1182
print the recipe to update `foo' and its prerequisites without running
1183
it. The recipe printed for `foo' will be the one specified in the
1184
updated contents of `mfile'.
1241
1185
1242
1186
However, on occasion you might actually wish to prevent updating of
1243
1187
even the makefiles. You can do this by specifying the makefiles as
1246
1190
`-t' and so on do apply to them.
1247
1191
1248
1192
Thus, `make -f mfile -n mfile foo' would read the makefile `mfile',
1249
print the commands needed to update it without actually running them,
1250
and then print the commands needed to update `foo' without running
1251
them. The commands for `foo' will be those specified by the existing
1252
contents of `mfile'.
1193
print the recipe needed to update it without actually running it, and
1194
then print the recipe needed to update `foo' without running that. The
1195
recipe for `foo' will be the one specified by the existing contents of
1196
`mfile'.
1253
1197
1254
1198
1255
1199
File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: Remaking Makefiles, Up: Makefiles
1256
1200
1257
3.8 Overriding Part of Another Makefile
1201
3.6 Overriding Part of Another Makefile
1258
1202
=======================================
1259
1203
1260
1204
Sometimes it is useful to have a makefile that is mostly just like
1261
1205
another makefile. You can often use the `include' directive to include
1262
1206
one in the other, and add more targets or variable definitions.
1263
However, if the two makefiles give different commands for the same
1264
target, `make' will not let you just do this. But there is another way.
1207
However, it is invalid for two makefiles to give different recipes for
1208
the same target. But there is another way.
1265
1209
1266
1210
In the containing makefile (the one that wants to include the other),
1267
1211
you can use a match-anything pattern rule to say that to remake any
1281
1225
force: ;
1282
1226
1283
1227
If you say `make foo', `make' will find `GNUmakefile', read it, and
1284
see that to make `foo', it needs to run the command `frobnicate > foo'.
1228
see that to make `foo', it needs to run the recipe `frobnicate > foo'.
1285
1229
If you say `make bar', `make' will find no way to make `bar' in
1286
`GNUmakefile', so it will use the commands from the pattern rule: `make
1230
`GNUmakefile', so it will use the recipe from the pattern rule: `make
1287
1231
-f Makefile bar'. If `Makefile' provides a rule for updating `bar',
1288
1232
`make' will apply the rule. And likewise for any other target that
1289
1233
`GNUmakefile' does not say how to make.
1290
1234
1291
1235
The way this works is that the pattern rule has a pattern of just
1292
1236
`%', so it matches any target whatever. The rule specifies a
1293
prerequisite `force', to guarantee that the commands will be run even
1294
if the target file already exists. We give `force' target empty
1295
commands to prevent `make' from searching for an implicit rule to build
1237
prerequisite `force', to guarantee that the recipe will be run even if
1238
the target file already exists. We give the `force' target an empty
1239
recipe to prevent `make' from searching for an implicit rule to build
1296
1240
it--otherwise it would apply the same match-anything rule to `force'
1297
1241
itself and create a prerequisite loop!
1298
1242
1299
1243
1300
1244
File: make.info, Node: Reading Makefiles, Next: Secondary Expansion, Prev: Overriding Makefiles, Up: Makefiles
1301
1245
1302
3.9 How `make' Reads a Makefile
1246
3.7 How `make' Reads a Makefile
1303
1247
===============================
1304
1248
1305
1249
GNU `make' does its work in two distinct phases. During the first
1318
1262
if it happens during the first phase: in this case `make' will expand
1319
1263
any variables or functions in that section of a construct as the
1320
1264
makefile is parsed. We say that expansion is "deferred" if expansion
1321
is not performed immediately. Expansion of deferred construct is not
1265
is not performed immediately. Expansion of a deferred construct is not
1322
1266
performed until either the construct appears later in an immediate
1323
1267
context, or until the second phase.
1324
1268
1334
1278
IMMEDIATE = DEFERRED
1335
1279
IMMEDIATE ?= DEFERRED
1336
1280
IMMEDIATE := IMMEDIATE
1281
IMMEDIATE ::= IMMEDIATE
1337
1282
IMMEDIATE += DEFERRED or IMMEDIATE
1283
IMMEDIATE != IMMEDIATE
1338
1284
1339
1285
define IMMEDIATE
1340
1286
DEFERRED
1341
1287
endef
1342
1288
1289
define IMMEDIATE =
1290
DEFERRED
1291
endef
1292
1293
define IMMEDIATE ?=
1294
DEFERRED
1295
endef
1296
1297
define IMMEDIATE :=
1298
IMMEDIATE
1299
endef
1300
1301
define IMMEDIATE ::=
1302
IMMEDIATE
1303
endef
1304
1305
define IMMEDIATE +=
1306
DEFERRED or IMMEDIATE
1307
endef
1308
1309
define IMMEDIATE !=
1310
IMMEDIATE
1311
endef
1312
1343
1313
For the append operator, `+=', the right-hand side is considered
1344
immediate if the variable was previously set as a simple variable
1345
(`:='), and deferred otherwise.
1346
1347
Conditional Statements
1314
immediate if the variable was previously set as a simple variable (`:='
1315
or `::='), and deferred otherwise.
1316
1317
For the shell assignment operator, `!=', the right-hand side is
1318
evaluated immediately and handed to the shell. The result is stored in
1319
the variable named on the left, and that variable becomes a simple
1320
variable (and will thus be re-evaluated on each reference).
1321
1322
Conditional Directives
1348
1323
----------------------
1349
1324
1350
All instances of conditional syntax are parsed immediately, in their
1351
entirety; this includes the `ifdef', `ifeq', `ifndef', and `ifneq'
1352
forms. Of course this means that automatic variables cannot be used in
1353
conditional statements, as automatic variables are not set until the
1354
command script for that rule is invoked. If you need to use automatic
1355
variables in a conditional you _must_ use shell conditional syntax, in
1356
your command script proper, for these tests, not `make' conditionals.
1325
Conditional directives are parsed immediately. This means, for
1326
example, that automatic variables cannot be used in conditional
1327
directives, as automatic variables are not set until the recipe for
1328
that rule is invoked. If you need to use automatic variables in a
1329
conditional directive you _must_ move the condition into the recipe and
1330
use shell conditional syntax instead.
1357
1331
1358
1332
Rule Definition
1359
1333
---------------
1364
1338
DEFERRED
1365
1339
1366
1340
That is, the target and prerequisite sections are expanded
1367
immediately, and the commands used to construct the target are always
1341
immediately, and the recipe used to construct the target is always
1368
1342
deferred. This general rule is true for explicit rules, pattern rules,
1369
1343
suffix rules, static pattern rules, and simple prerequisite definitions.
1370
1344
1371
1345
1372
1346
File: make.info, Node: Secondary Expansion, Prev: Reading Makefiles, Up: Makefiles
1373
1347
1374
3.10 Secondary Expansion
1375
========================
1348
3.8 Secondary Expansion
1349
=======================
1376
1350
1377
1351
In the previous section we learned that GNU `make' works in two
1378
1352
distinct phases: a read-in phase and a target-update phase (*note How
1407
1381
(escaped) variable reference is simply unescaped, without being
1408
1382
recognized as a variable reference. Now during the secondary expansion
1409
1383
the first word is expanded again but since it contains no variable or
1410
function references it remains the static value `onefile', while the
1411
second word is now a normal reference to the variable TWOVAR, which is
1384
function references it remains the value `onefile', while the second
1385
word is now a normal reference to the variable TWOVAR, which is
1412
1386
expanded to the value `twofile'. The final result is that there are
1413
1387
two prerequisites, `onefile' and `twofile'.
1414
1388
1433
1407
always take place within the scope of the automatic variables for that
1434
1408
target. This means that you can use variables such as `$@', `$*', etc.
1435
1409
during the second expansion and they will have their expected values,
1436
just as in the command script. All you have to do is defer the
1437
expansion by escaping the `$'. Also, secondary expansion occurs for
1438
both explicit and implicit (pattern) rules. Knowing this, the possible
1439
uses for this feature increase dramatically. For example:
1410
just as in the recipe. All you have to do is defer the expansion by
1411
escaping the `$'. Also, secondary expansion occurs for both explicit
1412
and implicit (pattern) rules. Knowing this, the possible uses for this
1413
feature increase dramatically. For example:
1440
1414
1441
1415
.SECONDEXPANSION:
1442
1416
main_OBJS := main.o try.o test.o
1451
1425
`main.o try.o test.o', while the secondary expansion for the `lib'
1452
1426
target will yield `$(lib_OBJS)', or `lib.o api.o'.
1453
1427
1454
You can also mix functions here, as long as they are properly
1428
You can also mix in functions here, as long as they are properly
1455
1429
escaped:
1456
1430
1457
1431
main_SRCS := main.c try.c test.c
1466
1440
1467
1441
Evaluation of automatic variables during the secondary expansion
1468
1442
phase, especially of the target name variable `$$@', behaves similarly
1469
to evaluation within command scripts. However, there are some subtle
1443
to evaluation within recipes. However, there are some subtle
1470
1444
differences and "corner cases" which come into play for the different
1471
1445
types of rule definitions that `make' understands. The subtleties of
1472
1446
using the different automatic variables are described below.
1495
1469
and `$$+') expand to the empty string. In the second, they will have
1496
1470
values `foo.1', `foo.1 bar.1', and `foo.1 bar.1' respectively. In the
1497
1471
third they will have values `foo.1', `foo.1 bar.1 foo.2 bar.2', and
1498
`foo.1 bar.1 foo.2 bar.2' respectively.
1472
`foo.1 bar.1 foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1' respectively.
1499
1473
1500
1474
Rules undergo secondary expansion in makefile order, except that the
1501
rule with the command script is always evaluated last.
1475
rule with the recipe is always evaluated last.
1502
1476
1503
1477
The variables `$$?' and `$$*' are not available and expand to the
1504
1478
empty string.
1531
1505
`bar', `$$^' expands to `bar boo', `$$+' also expands to `bar boo', and
1532
1506
`$$*' expands to `f'.
1533
1507
1534
Note that the directory prefix (D), as described in *Note Implicit
1508
Note that the directory prefix (D), as described in *note Implicit
1535
1509
Rule Search Algorithm: Implicit Rule Search, is appended (after
1536
1510
expansion) to all the patterns in the prerequisites list. As an
1537
1511
example:
1541
1515
/tmp/foo.o:
1542
1516
1543
1517
%.o: $$(addsuffix /%.c,foo bar) foo.h
1518
@echo $^
1544
1519
1545
The prerequisite list after the secondary expansion and directory
1546
prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c
1520
The prerequisite list printed, after the secondary expansion and
1521
directory prefix reconstruction, will be `/tmp/foo/foo.c /tmp/bar/foo.c
1547
1522
foo.h'. If you are not interested in this reconstruction, you can use
1548
1523
`$$*' instead of `%' in the prerequisites list.
1549
1524
1550
1525
1551
File: make.info, Node: Rules, Next: Commands, Prev: Makefiles, Up: Top
1526
File: make.info, Node: Rules, Next: Recipes, Prev: Makefiles, Up: Top
1552
1527
1553
1528
4 Writing Rules
1554
1529
***************
1556
1531
A "rule" appears in the makefile and says when and how to remake
1557
1532
certain files, called the rule's "targets" (most often only one per
1558
1533
rule). It lists the other files that are the "prerequisites" of the
1559
target, and "commands" to use to create or update the target.
1534
target, and the "recipe" to use to create or update the target.
1560
1535
1561
1536
The order of rules is not significant, except for determining the
1562
1537
"default goal": the target for `make' to consider, if you do not
1581
1556
* Wildcards:: Using wildcard characters such as `*'.
1582
1557
* Directory Search:: Searching other directories for source files.
1583
1558
* Phony Targets:: Using a target that is not a real file's name.
1584
* Force Targets:: You can use a target without commands
1559
* Force Targets:: You can use a target without a recipe
1585
1560
or prerequisites to mark other targets
1586
1561
as phony.
1587
1562
* Empty Targets:: When only the date matters and the
1609
1584
cc -c -g foo.c
1610
1585
1611
1586
Its target is `foo.o' and its prerequisites are `foo.c' and
1612
`defs.h'. It has one command, which is `cc -c -g foo.c'. The command
1613
line starts with a tab to identify it as a command.
1587
`defs.h'. It has one command in the recipe: `cc -c -g foo.c'. The
1588
recipe starts with a tab to identify it as a recipe.
1614
1589
1615
1590
This rule says two things:
1616
1591
1619
1594
than it.
1620
1595
1621
1596
* How to update the file `foo.o': by running `cc' as stated. The
1622
command does not explicitly mention `defs.h', but we presume that
1597
recipe does not explicitly mention `defs.h', but we presume that
1623
1598
`foo.c' includes it, and that that is why `defs.h' was added to
1624
1599
the prerequisites.
1625
1600
1632
1607
In general, a rule looks like this:
1633
1608
1634
1609
TARGETS : PREREQUISITES
1635
COMMAND
1610
RECIPE
1636
1611
...
1637
1612
1638
1613
or like this:
1639
1614
1640
TARGETS : PREREQUISITES ; COMMAND
1641
COMMAND
1615
TARGETS : PREREQUISITES ; RECIPE
1616
RECIPE
1642
1617
...
1643
1618
1644
1619
The TARGETS are file names, separated by spaces. Wildcard
1649
1624
reason to have more (*note Multiple Targets in a Rule: Multiple
1650
1625
Targets.).
1651
1626
1652
The COMMAND lines start with a tab character. The first command may
1653
appear on the line after the prerequisites, with a tab character, or may
1654
appear on the same line, with a semicolon. Either way, the effect is
1655
the same. There are other differences in the syntax of command lines.
1656
*Note Writing the Commands in Rules: Commands.
1627
The RECIPE lines start with a tab character (or the first character
1628
in the value of the `.RECIPEPREFIX' variable; *note Special
1629
Variables::). The first recipe line may appear on the line after the
1630
prerequisites, with a tab character, or may appear on the same line,
1631
with a semicolon. Either way, the effect is the same. There are other
1632
differences in the syntax of recipes. *Note Writing Recipes in Rules:
1633
Recipes.
1657
1634
1658
1635
Because dollar signs are used to start `make' variable references,
1659
1636
if you really want a dollar sign in a target or prerequisite you must
1660
1637
write two of them, `$$' (*note How to Use Variables: Using Variables.).
1661
1638
If you have enabled secondary expansion (*note Secondary Expansion::)
1662
and you want a literal dollar sign in the prerequisites lise, you must
1639
and you want a literal dollar sign in the prerequisites list, you must
1663
1640
actually write _four_ dollar signs (`$$$$').
1664
1641
1665
1642
You may split a long line by inserting a backslash followed by a
1679
1656
changes, the contents of the existing target file are no longer
1680
1657
necessarily valid.
1681
1658
1682
How to update is specified by COMMANDS. These are lines to be
1683
executed by the shell (normally `sh'), but with some extra features
1684
(*note Writing the Commands in Rules: Commands.).
1659
How to update is specified by a RECIPE. This is one or more lines
1660
to be executed by the shell (normally `sh'), but with some extra
1661
features (*note Writing Recipes in Rules: Recipes.).
1685
1662
1686
1663
1687
1664
File: make.info, Node: Prerequisite Types, Next: Wildcards, Prev: Rule Syntax, Up: Rules
1692
1669
There are actually two different types of prerequisites understood by
1693
1670
GNU `make': normal prerequisites such as described in the previous
1694
1671
section, and "order-only" prerequisites. A normal prerequisite makes
1695
two statements: first, it imposes an order of execution of build
1696
commands: any commands necessary to build any of a target's
1697
prerequisites will be fully executed before any commands necessary to
1698
build the target. Second, it imposes a dependency relationship: if any
1699
prerequisite is newer than the target, then the target is considered
1700
out-of-date and must be rebuilt.
1672
two statements: first, it imposes an order in which recipes will be
1673
invoked: the recipes for all prerequisites of a target will be
1674
completed before the recipe for the target is run. Second, it imposes
1675
a dependency relationship: if any prerequisite is newer than the
1676
target, then the target is considered out-of-date and must be rebuilt.
1701
1677
1702
1678
Normally, this is exactly what you want: if a target's prerequisite
1703
1679
is updated, then the target should also be updated.
1714
1690
1715
1691
The normal prerequisites section may of course be empty. Also, you
1716
1692
may still declare multiple lines of prerequisites for the same target:
1717
they are appended appropriately. Note that if you declare the same
1718
file to be both a normal and an order-only prerequisite, the normal
1719
prerequisite takes precedence (since they are a strict superset of the
1720
behavior of an order-only prerequisite).
1693
they are appended appropriately (normal prerequisites are appended to
1694
the list of normal prerequisites; order-only prerequisites are appended
1695
to the list of order-only prerequisites). Note that if you declare the
1696
same file to be both a normal and an order-only prerequisite, the
1697
normal prerequisite takes precedence (since they have a strict superset
1698
of the behavior of an order-only prerequisite).
1699
1700
Consider an example where your targets are to be placed in a separate
1701
directory, and that directory might not exist before `make' is run. In
1702
this situation, you want the directory to be created before any targets
1703
are placed into it but, because the timestamps on directories change
1704
whenever a file is added, removed, or renamed, we certainly don't want
1705
to rebuild all the targets whenever the directory's timestamp changes.
1706
One way to manage this is with order-only prerequisites: make the
1707
directory an order-only prerequisite on all the targets:
1708
1709
OBJDIR := objdir
1710
OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)
1711
1712
$(OBJDIR)/%.o : %.c
1713
$(COMPILE.c) $(OUTPUT_OPTION) $<
1714
1715
all: $(OBJS)
1716
1717
$(OBJS): | $(OBJDIR)
1718
1719
$(OBJDIR):
1720
mkdir $(OBJDIR)
1721
1722
Now the rule to create the `objdir' directory will be run, if
1723
needed, before any `.o' is built, but no `.o' will be built because the
1724
`objdir' directory timestamp changed.
1721
1725
1722
1726
1723
1727
File: make.info, Node: Wildcards, Next: Directory Search, Prev: Prerequisite Types, Up: Rules
1740
1744
simulated by setting the environment variable HOME.
1741
1745
1742
1746
Wildcard expansion is performed by `make' automatically in targets
1743
and in prerequisites. In commands the shell is responsible for
1747
and in prerequisites. In recipes, the shell is responsible for
1744
1748
wildcard expansion. In other contexts, wildcard expansion happens only
1745
1749
if you request it explicitly with the `wildcard' function.
1746
1750
1750
1754
1751
1755
* Menu:
1752
1756
1753
* Wildcard Examples:: Several examples
1757
* Wildcard Examples:: Several examples.
1754
1758
* Wildcard Pitfall:: Problems to avoid.
1755
1759
* Wildcard Function:: How to cause wildcard expansion where
1756
1760
it does not normally take place.
1761
1765
4.4.1 Wildcard Examples
1762
1766
-----------------------
1763
1767
1764
Wildcards can be used in the commands of a rule, where they are expanded
1768
Wildcards can be used in the recipe of a rule, where they are expanded
1765
1769
by the shell. For example, here is a rule to delete all the object
1766
1770
files:
1767
1771
1776
1780
lpr -p $?
1777
1781
touch print
1778
1782
1779
This rule uses `print' as an empty target file; see *Note Empty Target
1783
This rule uses `print' as an empty target file; see *note Empty Target
1780
1784
Files to Record Events: Empty Targets. (The automatic variable `$?' is
1781
used to print only those files that have changed; see *Note Automatic
1785
used to print only those files that have changed; see *note Automatic
1782
1786
Variables::.)
1783
1787
1784
1788
Wildcard expansion does not happen when you define a variable.
1787
1791
objects = *.o
1788
1792
1789
1793
then the value of the variable `objects' is the actual string `*.o'.
1790
However, if you use the value of `objects' in a target, prerequisite or
1791
command, wildcard expansion will take place at that time. To set
1792
`objects' to the expansion, instead use:
1794
However, if you use the value of `objects' in a target or prerequisite,
1795
wildcard expansion will take place there. If you use the value of
1796
`objects' in a recipe, the shell may perform wildcard expansion when
1797
the recipe runs. To set `objects' to the expansion, instead use:
1793
1798
1794
1799
objects := $(wildcard *.o)
1795
1800
1905
1910
* Selective Search:: Specifying a search path
1906
1911
for a specified class of names.
1907
1912
* Search Algorithm:: When and how search paths are applied.
1908
* Commands/Search:: How to write shell commands that work together
1913
* Recipes/Search:: How to write recipes that work together
1909
1914
with search paths.
1910
1915
* Implicit/Search:: How search paths affect implicit rules.
1911
1916
* Libraries/Search:: Directory search for link libraries.
1927
1932
in `VPATH' for a file with that name. If a file is found in one of
1928
1933
them, that file may become the prerequisite (see below). Rules may then
1929
1934
specify the names of files in the prerequisite list as if they all
1930
existed in the current directory. *Note Writing Shell Commands with
1931
Directory Search: Commands/Search.
1935
existed in the current directory. *Note Writing Recipes with Directory
1936
Search: Recipes/Search.
1932
1937
1933
1938
In the `VPATH' variable, directory names are separated by colons or
1934
1939
blanks. The order in which directories are listed is the order followed
2034
2039
will look for a file ending in `.c' in `foo', then `bar', then `blish'.
2035
2040
2036
2041
2037
File: make.info, Node: Search Algorithm, Next: Commands/Search, Prev: Selective Search, Up: Directory Search
2042
File: make.info, Node: Search Algorithm, Next: Recipes/Search, Prev: Selective Search, Up: Directory Search
2038
2043
2039
2044
4.5.3 How Directory Searches are Performed
2040
2045
------------------------------------------
2092
2097
expanded path.
2093
2098
2094
2099
2095
File: make.info, Node: Commands/Search, Next: Implicit/Search, Prev: Search Algorithm, Up: Directory Search
2100
File: make.info, Node: Recipes/Search, Next: Implicit/Search, Prev: Search Algorithm, Up: Directory Search
2096
2101
2097
4.5.4 Writing Shell Commands with Directory Search
2098
--------------------------------------------------
2102
4.5.4 Writing Recipes with Directory Search
2103
-------------------------------------------
2099
2104
2100
2105
When a prerequisite is found in another directory through directory
2101
search, this cannot change the commands of the rule; they will execute
2102
as written. Therefore, you must write the commands with care so that
2103
they will look for the prerequisite in the directory where `make' finds
2104
it.
2106
search, this cannot change the recipe of the rule; they will execute as
2107
written. Therefore, you must write the recipe with care so that it
2108
will look for the prerequisite in the directory where `make' finds it.
2105
2109
2106
2110
This is done with the "automatic variables" such as `$^' (*note
2107
2111
Automatic Variables::). For instance, the value of `$^' is a list of
2118
2122
Rules: Implicit Variables.)
2119
2123
2120
2124
Often the prerequisites include header files as well, which you do
2121
not want to mention in the commands. The automatic variable `$<' is
2122
just the first prerequisite:
2125
not want to mention in the recipe. The automatic variable `$<' is just
2126
the first prerequisite:
2123
2127
2124
2128
VPATH = src:../headers
2125
2129
foo.o : foo.c defs.h hack.h
2126
2130
cc -c $(CFLAGS) $< -o $@
2127
2131
2128
2132
2129
File: make.info, Node: Implicit/Search, Next: Libraries/Search, Prev: Commands/Search, Up: Directory Search
2133
File: make.info, Node: Implicit/Search, Next: Libraries/Search, Prev: Recipes/Search, Up: Directory Search
2130
2134
2131
2135
4.5.5 Directory Search and Implicit Rules
2132
2136
-----------------------------------------
2142
2146
exists (or is mentioned in the makefile) in any of the directories, the
2143
2147
implicit rule for C compilation is applied.
2144
2148
2145
The commands of implicit rules normally use automatic variables as a
2149
The recipes of implicit rules normally use automatic variables as a
2146
2150
matter of necessity; consequently they will use the file names found by
2147
2151
directory search with no extra effort.
2148
2152
2160
2164
like `libNAME.a', not like `-lNAME'.)
2161
2165
2162
2166
When a prerequisite's name has the form `-lNAME', `make' handles it
2163
specially by searching for the file `libNAME.so' in the current
2164
directory, in directories specified by matching `vpath' search paths
2165
and the `VPATH' search path, and then in the directories `/lib',
2166
`/usr/lib', and `PREFIX/lib' (normally `/usr/local/lib', but
2167
MS-DOS/MS-Windows versions of `make' behave as if PREFIX is defined to
2168
be the root of the DJGPP installation tree).
2169
2170
If that file is not found, then the file `libNAME.a' is searched
2171
for, in the same directories as above.
2167
specially by searching for the file `libNAME.so', and, if it is not
2168
found, for the file `libNAME.a' in the current directory, in
2169
directories specified by matching `vpath' search paths and the `VPATH'
2170
search path, and then in the directories `/lib', `/usr/lib', and
2171
`PREFIX/lib' (normally `/usr/local/lib', but MS-DOS/MS-Windows versions
2172
of `make' behave as if PREFIX is defined to be the root of the DJGPP
2173
installation tree).
2172
2174
2173
2175
For example, if there is a `/usr/lib/libcurses.a' library on your
2174
2176
system (and no `/usr/lib/libcurses.so' file), then
2185
2187
Each word in the value of this variable is a pattern string. When a
2186
2188
prerequisite like `-lNAME' is seen, `make' will replace the percent in
2187
2189
each pattern in the list with NAME and perform the above directory
2188
searches using that library filename. If no library is found, the next
2189
word in the list will be used.
2190
searches using each library file name.
2190
2191
2191
2192
The default value for `.LIBPATTERNS' is `lib%.so lib%.a', which
2192
2193
provides the default behavior described above.
2200
2201
4.6 Phony Targets
2201
2202
=================
2202
2203
2203
A phony target is one that is not really the name of a file. It is
2204
just a name for some commands to be executed when you make an explicit
2204
A phony target is one that is not really the name of a file; rather it
2205
is just a name for a recipe to be executed when you make an explicit
2205
2206
request. There are two reasons to use a phony target: to avoid a
2206
2207
conflict with a file of the same name, and to improve performance.
2207
2208
2208
If you write a rule whose commands will not create the target file,
2209
the commands will be executed every time the target comes up for
2210
remaking. Here is an example:
2209
If you write a rule whose recipe will not create the target file, the
2210
recipe will be executed every time the target comes up for remaking.
2211
Here is an example:
2211
2212
2212
2213
clean:
2213
2214
rm *.o temp
2219
2220
The phony target will cease to work if anything ever does create a
2220
2221
file named `clean' in this directory. Since it has no prerequisites,
2221
2222
the file `clean' would inevitably be considered up to date, and its
2222
commands would not be executed. To avoid this problem, you can
2223
explicitly declare the target to be phony, using the special target
2224
`.PHONY' (*note Special Built-in Target Names: Special Targets.) as
2225
follows:
2223
recipe would not be executed. To avoid this problem, you can explicitly
2224
declare the target to be phony, using the special target `.PHONY'
2225
(*note Special Built-in Target Names: Special Targets.) as follows:
2226
2226
2227
2227
.PHONY : clean
2228
2228
2229
Once this is done, `make clean' will run the commands regardless of
2229
Once this is done, `make clean' will run the recipe regardless of
2230
2230
whether there is a file named `clean'.
2231
2231
2232
2232
Since it knows that phony targets do not name actual files that
2243
2243
rm *.o temp
2244
2244
2245
2245
Another example of the usefulness of phony targets is in conjunction
2246
with recursive invocations of `make' (for more information, see *Note
2246
with recursive invocations of `make' (for more information, see *note
2247
2247
Recursive Use of `make': Recursion.). In this case the makefile will
2248
often contain a variable which lists a number of subdirectories to be
2249
built. One way to handle this is with one rule whose command is a
2250
shell loop over the subdirectories, like this:
2248
often contain a variable which lists a number of sub-directories to be
2249
built. One way to handle this is with one rule whose recipe is a shell
2250
loop over the sub-directories, like this:
2251
2251
2252
2252
SUBDIRS = foo bar baz
2253
2253
2256
2256
$(MAKE) -C $$dir; \
2257
2257
done
2258
2258
2259
There are a few problems with this method, however. First, any error
2260
detected in a submake is not noted by this rule, so it will continue to
2259
There are problems with this method, however. First, any error
2260
detected in a sub-make is ignored by this rule, so it will continue to
2261
2261
build the rest of the directories even when one fails. This can be
2262
2262
overcome by adding shell commands to note the error and exit, but then
2263
2263
it will do so even if `make' is invoked with the `-k' option, which is
2265
2265
advantage of `make''s ability to build targets in parallel (*note
2266
2266
Parallel Execution: Parallel.), since there is only one rule.
2267
2267
2268
By declaring the subdirectories as phony targets (you must do this as
2269
the subdirectory obviously always exists; otherwise it won't be built)
2270
you can remove these problems:
2268
By declaring the sub-directories as phony targets (you must do this
2269
as the sub-directory obviously always exists; otherwise it won't be
2270
built) you can remove these problems:
2271
2271
2272
2272
SUBDIRS = foo bar baz
2273
2273
2280
2280
2281
2281
foo: baz
2282
2282
2283
Here we've also declared that the `foo' subdirectory cannot be built
2284
until after the `baz' subdirectory is complete; this kind of
2283
Here we've also declared that the `foo' sub-directory cannot be
2284
built until after the `baz' sub-directory is complete; this kind of
2285
2285
relationship declaration is particularly important when attempting
2286
2286
parallel builds.
2287
2287
2288
2288
A phony target should not be a prerequisite of a real target file;
2289
if it is, its commands are run every time `make' goes to update that
2289
if it is, its recipe will be run every time `make' goes to update that
2290
2290
file. As long as a phony target is never a prerequisite of a real
2291
target, the phony target commands will be executed only when the phony
2291
target, the phony target recipe will be executed only when the phony
2292
2292
target is a specified goal (*note Arguments to Specify the Goals:
2293
2293
Goals.).
2294
2294
2334
2334
2335
2335
File: make.info, Node: Force Targets, Next: Empty Targets, Prev: Phony Targets, Up: Rules
2336
2336
2337
4.7 Rules without Commands or Prerequisites
2338
===========================================
2337
4.7 Rules without Recipes or Prerequisites
2338
==========================================
2339
2339
2340
If a rule has no prerequisites or commands, and the target of the rule
2341
is a nonexistent file, then `make' imagines this target to have been
2340
If a rule has no prerequisites or recipe, and the target of the rule is
2341
a nonexistent file, then `make' imagines this target to have been
2342
2342
updated whenever its rule is run. This implies that all targets
2343
depending on this one will always have their commands run.
2343
depending on this one will always have their recipe run.
2344
2344
2345
2345
An example will illustrate this:
2346
2346
2349
2349
FORCE:
2350
2350
2351
2351
Here the target `FORCE' satisfies the special conditions, so the
2352
target `clean' that depends on it is forced to run its commands. There
2352
target `clean' that depends on it is forced to run its recipe. There
2353
2353
is nothing special about the name `FORCE', but that is one name
2354
2354
commonly used this way.
2355
2355
2367
2367
=======================================
2368
2368
2369
2369
The "empty target" is a variant of the phony target; it is used to hold
2370
commands for an action that you request explicitly from time to time.
2370
recipes for an action that you request explicitly from time to time.
2371
2371
Unlike a phony target, this target file can really exist; but the file's
2372
2372
contents do not matter, and usually are empty.
2373
2373
2374
2374
The purpose of the empty target file is to record, with its
2375
last-modification time, when the rule's commands were last executed. It
2376
does so because one of the commands is a `touch' command to update the
2377
target file.
2375
last-modification time, when the rule's recipe was last executed. It
2376
does so because one of the commands in the recipe is a `touch' command
2377
to update the target file.
2378
2378
2379
2379
The empty target file should have some prerequisites (otherwise it
2380
2380
doesn't make sense). When you ask to remake the empty target, the
2381
commands are executed if any prerequisite is more recent than the
2382
target; in other words, if a prerequisite has changed since the last
2383
time you remade the target. Here is an example:
2381
recipe is executed if any prerequisite is more recent than the target;
2382
in other words, if a prerequisite has changed since the last time you
2383
remade the target. Here is an example:
2384
2384
2385
2385
print: foo.c bar.c
2386
2386
lpr -p $?
2402
2402
`.PHONY'
2403
2403
The prerequisites of the special target `.PHONY' are considered to
2404
2404
be phony targets. When it is time to consider such a target,
2405
`make' will run its commands unconditionally, regardless of
2406
whether a file with that name exists or what its last-modification
2407
time is. *Note Phony Targets: Phony Targets.
2405
`make' will run its recipe unconditionally, regardless of whether
2406
a file with that name exists or what its last-modification time
2407
is. *Note Phony Targets: Phony Targets.
2408
2408
2409
2409
`.SUFFIXES'
2410
2410
The prerequisites of the special target `.SUFFIXES' are the list
2412
2412
Old-Fashioned Suffix Rules: Suffix Rules.
2413
2413
2414
2414
`.DEFAULT'
2415
The commands specified for `.DEFAULT' are used for any target for
2415
The recipe specified for `.DEFAULT' is used for any target for
2416
2416
which no rules are found (either explicit rules or implicit rules).
2417
*Note Last Resort::. If `.DEFAULT' commands are specified, every
2417
*Note Last Resort::. If a `.DEFAULT' recipe is specified, every
2418
2418
file mentioned as a prerequisite, but not as a target in a rule,
2419
will have these commands executed on its behalf. *Note Implicit
2420
Rule Search Algorithm: Implicit Rule Search.
2419
will have that recipe executed on its behalf. *Note Implicit Rule
2420
Search Algorithm: Implicit Rule Search.
2421
2421
2422
2422
`.PRECIOUS'
2423
2423
The targets which `.PRECIOUS' depends on are given the following
2424
2424
special treatment: if `make' is killed or interrupted during the
2425
execution of their commands, the target is not deleted. *Note
2425
execution of their recipes, the target is not deleted. *Note
2426
2426
Interrupting or Killing `make': Interrupts. Also, if the target
2427
2427
is an intermediate file, it will not be deleted after it is no
2428
2428
longer needed, as is normally done. *Note Chains of Implicit
2454
2454
will be expanded a second time after all makefiles have been read
2455
2455
in. *Note Secondary Expansion: Secondary Expansion.
2456
2456
2457
The prerequisites of the special target `.SUFFIXES' are the list
2458
of suffixes to be used in checking for suffix rules. *Note
2459
Old-Fashioned Suffix Rules: Suffix Rules.
2460
2461
2457
`.DELETE_ON_ERROR'
2462
2458
If `.DELETE_ON_ERROR' is mentioned as a target anywhere in the
2463
2459
makefile, then `make' will delete the target of a rule if it has
2464
changed and its commands exit with a nonzero exit status, just as
2465
it does when it receives a signal. *Note Errors in Commands:
2466
Errors.
2460
changed and its recipe exits with a nonzero exit status, just as it
2461
does when it receives a signal. *Note Errors in Recipes: Errors.
2467
2462
2468
2463
`.IGNORE'
2469
2464
If you specify prerequisites for `.IGNORE', then `make' will
2470
ignore errors in execution of the commands run for those particular
2471
files. The commands for `.IGNORE' are not meaningful.
2465
ignore errors in execution of the recipe for those particular
2466
files. The recipe for `.IGNORE' (if any) is ignored.
2472
2467
2473
2468
If mentioned as a target with no prerequisites, `.IGNORE' says to
2474
ignore errors in execution of commands for all files. This usage
2475
of `.IGNORE' is supported only for historical compatibility. Since
2476
this affects every command in the makefile, it is not very useful;
2469
ignore errors in execution of recipes for all files. This usage of
2470
`.IGNORE' is supported only for historical compatibility. Since
2471
this affects every recipe in the makefile, it is not very useful;
2477
2472
we recommend you use the more selective ways to ignore errors in
2478
specific commands. *Note Errors in Commands: Errors.
2473
specific recipes. *Note Errors in Recipes: Errors.
2479
2474
2480
2475
`.LOW_RESOLUTION_TIME'
2481
2476
If you specify prerequisites for `.LOW_RESOLUTION_TIME', `make'
2482
2477
assumes that these files are created by commands that generate low
2483
resolution time stamps. The commands for `.LOW_RESOLUTION_TIME'
2484
are not meaningful.
2478
resolution time stamps. The recipe for the `.LOW_RESOLUTION_TIME'
2479
target are ignored.
2485
2480
2486
The high resolution file time stamps of many modern hosts lessen
2487
the chance of `make' incorrectly concluding that a file is up to
2488
date. Unfortunately, these hosts provide no way to set a high
2489
resolution file time stamp, so commands like `cp -p' that
2490
explicitly set a file's time stamp must discard its subsecond
2481
The high resolution file time stamps of many modern file systems
2482
lessen the chance of `make' incorrectly concluding that a file is
2483
up to date. Unfortunately, some hosts do not provide a way to set
2484
a high resolution file time stamp, so commands like `cp -p' that
2485
explicitly set a file's time stamp must discard its sub-second
2491
2486
part. If a file is created by such a command, you should list it
2492
2487
as a prerequisite of `.LOW_RESOLUTION_TIME' so that `make' does
2493
2488
not mistakenly conclude that the file is out of date. For example:
2496
2491
dst: src
2497
2492
cp -p src dst
2498
2493
2499
Since `cp -p' discards the subsecond part of `src''s time stamp,
2494
Since `cp -p' discards the sub-second part of `src''s time stamp,
2500
2495
`dst' is typically slightly older than `src' even when it is up to
2501
2496
date. The `.LOW_RESOLUTION_TIME' line causes `make' to consider
2502
2497
`dst' to be up to date if its time stamp is at the start of the
2509
2504
2510
2505
`.SILENT'
2511
2506
If you specify prerequisites for `.SILENT', then `make' will not
2512
print the commands to remake those particular files before
2513
executing them. The commands for `.SILENT' are not meaningful.
2507
print the recipe used to remake those particular files before
2508
executing them. The recipe for `.SILENT' is ignored.
2514
2509
2515
2510
If mentioned as a target with no prerequisites, `.SILENT' says not
2516
to print any commands before executing them. This usage of
2511
to print any recipes before executing them. This usage of
2517
2512
`.SILENT' is supported only for historical compatibility. We
2518
2513
recommend you use the more selective ways to silence specific
2519
commands. *Note Command Echoing: Echoing. If you want to silence
2520
all commands for a particular run of `make', use the `-s' or
2514
recipes. *Note Recipe Echoing: Echoing. If you want to silence
2515
all recipes for a particular run of `make', use the `-s' or
2521
2516
`--silent' option (*note Options Summary::).
2522
2517
2523
2518
`.EXPORT_ALL_VARIABLES'
2526
2521
Variables to a Sub-`make': Variables/Recursion.
2527
2522
2528
2523
`.NOTPARALLEL'
2529
If `.NOTPARALLEL' is mentioned as a target, then this invocation of
2530
`make' will be run serially, even if the `-j' option is given.
2531
Any recursively invoked `make' command will still be run in
2532
parallel (unless its makefile contains this target). Any
2524
If `.NOTPARALLEL' is mentioned as a target, then this invocation
2525
of `make' will be run serially, even if the `-j' option is given.
2526
Any recursively invoked `make' command will still run recipes in
2527
parallel (unless its makefile also contains this target). Any
2533
2528
prerequisites on this target are ignored.
2534
2529
2530
`.ONESHELL'
2531
If `.ONESHELL' is mentioned as a target, then when a target is
2532
built all lines of the recipe will be given to a single invocation
2533
of the shell rather than each line being invoked separately (*note
2534
Recipe Execution: Execution.).
2535
2536
`.POSIX'
2537
If `.POSIX' is mentioned as a target, then the makefile will be
2538
parsed and run in POSIX-conforming mode. This does _not_ mean
2539
that only POSIX-conforming makefiles will be accepted: all advanced
2540
GNU `make' features are still available. Rather, this target
2541
causes `make' to behave as required by POSIX in those areas where
2542
`make''s default behavior differs.
2543
2544
In particular, if this target is mentioned then recipes will be
2545
invoked as if the shell had been passed the `-e' flag: the first
2546
failing command in a recipe will cause the recipe to fail
2547
immediately.
2548
2535
2549
Any defined implicit rule suffix also counts as a special target if
2536
2550
it appears as a target, and so does the concatenation of two suffixes,
2537
2551
such as `.c.o'. These targets are suffix rules, an obsolete way of
2548
2562
===============================
2549
2563
2550
2564
A rule with multiple targets is equivalent to writing many rules, each
2551
with one target, and all identical aside from that. The same commands
2552
apply to all the targets, but their effects may vary because you can
2553
substitute the actual target name into the command using `$@'. The
2554
rule contributes the same prerequisites to all the targets also.
2565
with one target, and all identical aside from that. The same recipe
2566
applies to all the targets, but its effect may vary because you can
2567
substitute the actual target name into the recipe using `$@'. The rule
2568
contributes the same prerequisites to all the targets also.
2555
2569
2556
2570
This is useful in two cases.
2557
2571
2558
* You want just prerequisites, no commands. For example:
2572
* You want just prerequisites, no recipe. For example:
2559
2573
2560
2574
kbd.o command.o files.o: command.h
2561
2575
2562
2576
gives an additional prerequisite to each of the three object files
2563
2577
mentioned.
2564
2578
2565
* Similar commands work for all the targets. The commands do not
2566
need to be absolutely identical, since the automatic variable `$@'
2567
can be used to substitute the particular target to be remade into
2568
the commands (*note Automatic Variables::). For example:
2579
* Similar recipes work for all the targets. The recipes do not need
2580
to be absolutely identical, since the automatic variable `$@' can
2581
be used to substitute the particular target to be remade into the
2582
commands (*note Automatic Variables::). For example:
2569
2583
2570
2584
bigoutput littleoutput : text.g
2571
2585
generate text.g -$(subst output,,$@) > $@
2583
2597
for an explanation of the `subst' function.
2584
2598
2585
2599
Suppose you would like to vary the prerequisites according to the
2586
target, much as the variable `$@' allows you to vary the commands. You
2600
target, much as the variable `$@' allows you to vary the recipe. You
2587
2601
cannot do this with multiple targets in an ordinary rule, but you can
2588
2602
do it with a "static pattern rule". *Note Static Pattern Rules: Static
2589
2603
Pattern.
2597
2611
One file can be the target of several rules. All the prerequisites
2598
2612
mentioned in all the rules are merged into one list of prerequisites for
2599
2613
the target. If the target is older than any prerequisite from any rule,
2600
the commands are executed.
2614
the recipe is executed.
2601
2615
2602
There can only be one set of commands to be executed for a file. If
2603
more than one rule gives commands for the same file, `make' uses the
2604
last set given and prints an error message. (As a special case, if the
2605
file's name begins with a dot, no error message is printed. This odd
2606
behavior is only for compatibility with other implementations of
2607
`make'... you should avoid using it). Occasionally it is useful to
2608
have the same target invoke multiple commands which are defined in
2609
different parts of your makefile; you can use "double-colon rules"
2610
(*note Double-Colon::) for this.
2616
There can only be one recipe to be executed for a file. If more than
2617
one rule gives a recipe for the same file, `make' uses the last one
2618
given and prints an error message. (As a special case, if the file's
2619
name begins with a dot, no error message is printed. This odd behavior
2620
is only for compatibility with other implementations of `make'... you
2621
should avoid using it). Occasionally it is useful to have the same
2622
target invoke multiple recipes which are defined in different parts of
2623
your makefile; you can use "double-colon rules" (*note Double-Colon::)
2624
for this.
2611
2625
2612
2626
An extra rule with just prerequisites can be used to give a few extra
2613
2627
prerequisites to many files at once. For example, makefiles often have
2626
2640
intermittently.
2627
2641
2628
2642
Another wrinkle is that the additional prerequisites could be
2629
specified with a variable that you set with a command argument to `make'
2630
(*note Overriding Variables: Overriding.). For example,
2643
specified with a variable that you set with a command line argument to
2644
`make' (*note Overriding Variables: Overriding.). For example,
2631
2645
2632
2646
extradeps=
2633
2647
$(objects) : $(extradeps)
2635
2649
means that the command `make extradeps=foo.h' will consider `foo.h' as
2636
2650
a prerequisite of each object file, but plain `make' will not.
2637
2651
2638
If none of the explicit rules for a target has commands, then `make'
2639
searches for an applicable implicit rule to find some commands *note
2640
Using Implicit Rules: Implicit Rules.).
2652
If none of the explicit rules for a target has a recipe, then `make'
2653
searches for an applicable implicit rule to find one *note Using
2654
Implicit Rules: Implicit Rules.).
2641
2655
2642
2656
2643
2657
File: make.info, Node: Static Pattern, Next: Double-Colon, Prev: Multiple Rules, Up: Rules
2665
2679
Here is the syntax of a static pattern rule:
2666
2680
2667
2681
TARGETS ...: TARGET-PATTERN: PREREQ-PATTERNS ...
2668
COMMANDS
2682
RECIPE
2669
2683
...
2670
2684
2671
2685
The TARGETS list specifies the targets that the rule applies to. The
2716
2730
2717
2731
Here `$<' is the automatic variable that holds the name of the
2718
2732
prerequisite and `$@' is the automatic variable that holds the name of
2719
the target; see *Note Automatic Variables::.
2733
the target; see *note Automatic Variables::.
2720
2734
2721
2735
Each target specified must match the target pattern; a warning is
2722
2736
issued for each target that does not. If you have a list of files,
2723
2737
only some of which will match the pattern, you can use the `filter'
2724
function to remove nonmatching file names (*note Functions for String
2738
function to remove non-matching file names (*note Functions for String
2725
2739
Substitution and Analysis: Text Functions.):
2726
2740
2727
2741
files = foo.elc bar.o lose.o
2758
2772
`make' decides _when_ the rule applies.
2759
2773
2760
2774
An implicit rule _can_ apply to any target that matches its pattern,
2761
but it _does_ apply only when the target has no commands otherwise
2775
but it _does_ apply only when the target has no recipe otherwise
2762
2776
specified, and only when the prerequisites can be found. If more than
2763
2777
one implicit rule appears applicable, only one applies; the choice
2764
2778
depends on the order of rules.
2766
2780
By contrast, a static pattern rule applies to the precise list of
2767
2781
targets that you specify in the rule. It cannot apply to any other
2768
2782
target and it invariably does apply to each of the targets specified.
2769
If two conflicting rules apply, and both have commands, that's an error.
2783
If two conflicting rules apply, and both have recipes, that's an error.
2770
2784
2771
2785
The static pattern rule can be better than an implicit rule for these
2772
2786
reasons:
2788
2802
4.13 Double-Colon Rules
2789
2803
=======================
2790
2804
2791
"Double-colon" rules are rules written with `::' instead of `:' after
2792
the target names. They are handled differently from ordinary rules
2793
when the same target appears in more than one rule.
2805
"Double-colon" rules are explicit rules written with `::' instead of
2806
`:' after the target names. They are handled differently from ordinary
2807
rules when the same target appears in more than one rule. Pattern
2808
rules with double-colons have an entirely different meaning (*note
2809
Match-Anything Rules::).
2794
2810
2795
2811
When a target appears in multiple rules, all the rules must be the
2796
2812
same type: all ordinary, or all double-colon. If they are
2797
2813
double-colon, each of them is independent of the others. Each
2798
double-colon rule's commands are executed if the target is older than
2799
any prerequisites of that rule. If there are no prerequisites for that
2800
rule, its commands are always executed (even if the target already
2814
double-colon rule's recipe is executed if the target is older than any
2815
prerequisites of that rule. If there are no prerequisites for that
2816
rule, its recipe is always executed (even if the target already
2801
2817
exists). This can result in executing none, any, or all of the
2802
2818
double-colon rules.
2803
2819
2807
2823
2808
2824
The double-colon rules for a target are executed in the order they
2809
2825
appear in the makefile. However, the cases where double-colon rules
2810
really make sense are those where the order of executing the commands
2826
really make sense are those where the order of executing the recipes
2811
2827
would not matter.
2812
2828
2813
2829
Double-colon rules are somewhat obscure and not often very useful;
2815
2831
target differs depending on which prerequisite files caused the update,
2816
2832
and such cases are rare.
2817
2833
2818
Each double-colon rule should specify commands; if it does not, an
2834
Each double-colon rule should specify a recipe; if it does not, an
2819
2835
implicit rule will be used if one applies. *Note Using Implicit Rules:
2820
2836
Implicit Rules.
2821
2837
2851
2867
Thus you no longer have to write all those rules yourself. The
2852
2868
compiler will do it for you.
2853
2869
2854
Note that such a prerequisite constitutes mentioning `main.o' in a
2855
makefile, so it can never be considered an intermediate file by implicit
2856
rule search. This means that `make' won't ever remove the file after
2857
using it; *note Chains of Implicit Rules: Chained Rules.
2870
Note that such a rule constitutes mentioning `main.o' in a makefile,
2871
so it can never be considered an intermediate file by implicit rule
2872
search. This means that `make' won't ever remove the file after using
2873
it; *note Chains of Implicit Rules: Chained Rules.
2858
2874
2859
2875
With old `make' programs, it was traditional practice to use this
2860
2876
compiler feature to generate prerequisites on demand with a command like
2889
2905
2890
2906
With the GNU C compiler, you may wish to use the `-MM' flag instead
2891
2907
of `-M'. This omits prerequisites on system header files. *Note
2892
Options Controlling the Preprocessor: (gcc.info)Preprocessor Options,
2893
for details.
2908
Options Controlling the Preprocessor: (gcc)Preprocessor Options, for
2909
details.
2894
2910
2895
2911
The purpose of the `sed' command is to translate (for example):
2896
2912
2926
2942
the default goal. *Note How Make Works::.
2927
2943
2928
2944
2929
File: make.info, Node: Commands, Next: Using Variables, Prev: Rules, Up: Top
2930
2931
5 Writing the Commands in Rules
2932
*******************************
2933
2934
The commands of a rule consist of one or more shell command lines to be
2945
File: make.info, Node: Recipes, Next: Using Variables, Prev: Rules, Up: Top
2946
2947
5 Writing Recipes in Rules
2948
**************************
2949
2950
The recipe of a rule consists of one or more shell command lines to be
2935
2951
executed, one at a time, in the order they appear. Typically, the
2936
2952
result of executing these commands is that the target of the rule is
2937
2953
brought up to date.
2938
2954
2939
Users use many different shell programs, but commands in makefiles
2940
are always interpreted by `/bin/sh' unless the makefile specifies
2941
otherwise. *Note Command Execution: Execution.
2955
Users use many different shell programs, but recipes in makefiles are
2956
always interpreted by `/bin/sh' unless the makefile specifies
2957
otherwise. *Note Recipe Execution: Execution.
2942
2958
2943
2959
* Menu:
2944
2960
2945
* Command Syntax:: Command syntax features and pitfalls.
2946
* Echoing:: How to control when commands are echoed.
2947
* Execution:: How commands are executed.
2948
* Parallel:: How commands can be executed in parallel.
2949
* Errors:: What happens after a command execution error.
2950
* Interrupts:: What happens when a command is interrupted.
2961
* Recipe Syntax:: Recipe syntax features and pitfalls.
2962
* Echoing:: How to control when recipes are echoed.
2963
* Execution:: How recipes are executed.
2964
* Parallel:: How recipes can be executed in parallel.
2965
* Errors:: What happens after a recipe execution error.
2966
* Interrupts:: What happens when a recipe is interrupted.
2951
2967
* Recursion:: Invoking `make' from makefiles.
2952
* Sequences:: Defining canned sequences of commands.
2953
* Empty Commands:: Defining useful, do-nothing commands.
2968
* Canned Recipes:: Defining canned recipes.
2969
* Empty Recipes:: Defining useful, do-nothing recipes.
2954
2970
2955
2971
2956
File: make.info, Node: Command Syntax, Next: Echoing, Prev: Commands, Up: Commands
2972
File: make.info, Node: Recipe Syntax, Next: Echoing, Prev: Recipes, Up: Recipes
2957
2973
2958
5.1 Command Syntax
2959
==================
2974
5.1 Recipe Syntax
2975
=================
2960
2976
2961
2977
Makefiles have the unusual property that there are really two distinct
2962
2978
syntaxes in one file. Most of the makefile uses `make' syntax (*note
2963
Writing Makefiles: Makefiles.). However, commands are meant to be
2979
Writing Makefiles: Makefiles.). However, recipes are meant to be
2964
2980
interpreted by the shell and so they are written using shell syntax.
2965
2981
The `make' program does not try to understand shell syntax: it performs
2966
only a very few specific translations on the content of the command
2982
only a very few specific translations on the content of the recipe
2967
2983
before handing it to the shell.
2968
2984
2969
Each command line must start with a tab, except that the first
2970
command line may be attached to the target-and-prerequisites line with a
2971
semicolon in between. _Any_ line in the makefile that begins with a
2972
tab and appears in a "rule context" (that is, after a rule has been
2973
started until another rule or variable definition) will be considered a
2974
command line for that rule. Blank lines and lines of just comments may
2975
appear among the command lines; they are ignored.
2985
Each line in the recipe must start with a tab (or the first character
2986
in the value of the `.RECIPEPREFIX' variable; *note Special
2987
Variables::), except that the first recipe line may be attached to the
2988
target-and-prerequisites line with a semicolon in between. _Any_ line
2989
in the makefile that begins with a tab and appears in a "rule context"
2990
(that is, after a rule has been started until another rule or variable
2991
definition) will be considered part of a recipe for that rule. Blank
2992
lines and lines of just comments may appear among the recipe lines;
2993
they are ignored.
2976
2994
2977
2995
Some consequences of these rules include:
2978
2996
2979
2997
* A blank line that begins with a tab is not blank: it's an empty
2980
command (*note Empty Commands::).
2998
recipe (*note Empty Recipes::).
2981
2999
2982
* A comment in a command line is not a `make' comment; it will be
2983
passed to the shell as-is. Whether the shell treats it as a
2984
comment or not depends on your shell.
3000
* A comment in a recipe is not a `make' comment; it will be passed
3001
to the shell as-is. Whether the shell treats it as a comment or
3002
not depends on your shell.
2985
3003
2986
3004
* A variable definition in a "rule context" which is indented by a
2987
tab as the first character on the line, will be considered a
2988
command line, not a `make' variable definition, and passed to the
3005
tab as the first character on the line, will be considered part of
3006
a recipe, not a `make' variable definition, and passed to the
2989
3007
shell.
2990
3008
2991
3009
* A conditional expression (`ifdef', `ifeq', etc. *note Syntax of
2992
3010
Conditionals: Conditional Syntax.) in a "rule context" which is
2993
3011
indented by a tab as the first character on the line, will be
2994
considered a command line and be passed to the shell.
3012
considered part of a recipe and be passed to the shell.
2995
3013
2996
3014
2997
3015
* Menu:
2998
3016
2999
* Splitting Lines:: Breaking long command lines for readability.
3000
* Variables in Commands:: Using `make' variables in commands.
3017
* Splitting Recipe Lines:: Breaking long recipe lines for readability.
3018
* Variables in Recipes:: Using `make' variables in recipes.
3001
3019
3002
3020
3003
File: make.info, Node: Splitting Lines, Next: Variables in Commands, Prev: Command Syntax, Up: Command Syntax
3004
3005
5.1.1 Splitting Command Lines
3006
-----------------------------
3007
3008
One of the few ways in which `make' does interpret command lines is
3009
checking for a backslash just before the newline. As in normal
3010
makefile syntax, a single command can be split into multiple lines in
3011
the makefile by placing a backslash before each newline. A sequence of
3012
lines like this is considered a single command, and one instance of the
3013
shell will be invoked to run it.
3021
File: make.info, Node: Splitting Recipe Lines, Next: Variables in Recipes, Prev: Recipe Syntax, Up: Recipe Syntax
3022
3023
5.1.1 Splitting Recipe Lines
3024
----------------------------
3025
3026
One of the few ways in which `make' does interpret recipes is checking
3027
for a backslash just before the newline. As in normal makefile syntax,
3028
a single logical recipe line can be split into multiple physical lines
3029
in the makefile by placing a backslash before each newline. A sequence
3030
of lines like this is considered a single recipe line, and one instance
3031
of the shell will be invoked to run it.
3014
3032
3015
3033
However, in contrast to how they are treated in other places in a
3016
makefile, backslash-newline pairs are _not_ removed from the command.
3017
Both the backslash and the newline characters are preserved and passed
3018
to the shell. How the backslash-newline is interpreted depends on your
3019
shell. If the first character of the next line after the
3020
backslash-newline is a tab, then that tab (and only that tab) is
3021
removed. Whitespace is never added to the command.
3034
makefile (*note Splitting Long Lines: Splitting Lines.),
3035
backslash/newline pairs are _not_ removed from the recipe. Both the
3036
backslash and the newline characters are preserved and passed to the
3037
shell. How the backslash/newline is interpreted depends on your shell.
3038
If the first character of the next line after the backslash/newline is
3039
the recipe prefix character (a tab by default; *note Special
3040
Variables::), then that character (and only that character) is removed.
3041
Whitespace is never added to the recipe.
3022
3042
3023
For example, this makefile:
3043
For example, the recipe for the all target in this makefile:
3024
3044
3025
3045
all :
3026
3046
@echo no\
3045
3065
world' ; echo "hello \
3046
3066
world"
3047
3067
3048
will run one shell with a command script of:
3068
will invoke one shell with a command of:
3049
3069
3050
3070
echo 'hello \
3051
3071
world' ; echo "hello \
3065
3085
different shell in your makefiles it may treat them differently.
3066
3086
3067
3087
Sometimes you want to split a long line inside of single quotes, but
3068
you don't want the backslash-newline to appear in the quoted content.
3088
you don't want the backslash/newline to appear in the quoted content.
3069
3089
This is often the case when passing scripts to languages such as Perl,
3070
3090
where extraneous backslashes inside the script can change its meaning
3071
3091
or even be a syntax error. One simple way of handling this is to place
3072
3092
the quoted string, or even the entire command, into a `make' variable
3073
then use the variable in the command. In this situation the newline
3074
quoting rules for makefiles will be used, and the backslash-newline
3093
then use the variable in the recipe. In this situation the newline
3094
quoting rules for makefiles will be used, and the backslash/newline
3075
3095
will be removed. If we rewrite our example above using this method:
3076
3096
3077
3097
HELLO = 'hello \
3085
3105
3086
3106
If you like, you can also use target-specific variables (*note
3087
3107
Target-specific Variable Values: Target-specific.) to obtain a tighter
3088
correspondence between the variable and the command that uses it.
3108
correspondence between the variable and the recipe that uses it.
3089
3109
3090
3110
3091
File: make.info, Node: Variables in Commands, Prev: Splitting Lines, Up: Command Syntax
3092
3093
5.1.2 Using Variables in Commands
3094
---------------------------------
3095
3096
The other way in which `make' processes commands is by expanding any
3111
File: make.info, Node: Variables in Recipes, Prev: Splitting Recipe Lines, Up: Recipe Syntax
3112
3113
5.1.2 Using Variables in Recipes
3114
--------------------------------
3115
3116
The other way in which `make' processes recipes is by expanding any
3097
3117
variable references in them (*note Basics of Variable References:
3098
3118
Reference.). This occurs after make has finished reading all the
3099
3119
makefiles and the target is determined to be out of date; so, the
3100
commands for targets which are not rebuilt are never expanded.
3120
recipes for targets which are not rebuilt are never expanded.
3101
3121
3102
Variable and function references in commands have identical syntax
3103
and semantics to references elsewhere in the makefile. They also have
3104
the same quoting rules: if you want a dollar sign to appear in your
3105
command, you must double it (`$$'). For shells like the default shell,
3106
that use dollar signs to introduce variables, it's important to keep
3107
clear in your mind whether the variable you want to reference is a
3108
`make' variable (use a single dollar sign) or a shell variable (use two
3109
dollar signs). For example:
3122
Variable and function references in recipes have identical syntax and
3123
semantics to references elsewhere in the makefile. They also have the
3124
same quoting rules: if you want a dollar sign to appear in your recipe,
3125
you must double it (`$$'). For shells like the default shell, that use
3126
dollar signs to introduce variables, it's important to keep clear in
3127
your mind whether the variable you want to reference is a `make'
3128
variable (use a single dollar sign) or a shell variable (use two dollar
3129
signs). For example:
3110
3130
3111
3131
LIST = one two three
3112
3132
all:
3127
3147
three
3128
3148
3129
3149
3130
File: make.info, Node: Echoing, Next: Execution, Prev: Command Syntax, Up: Commands
3131
3132
5.2 Command Echoing
3133
===================
3134
3135
Normally `make' prints each command line before it is executed. We
3136
call this "echoing" because it gives the appearance that you are typing
3137
the commands yourself.
3150
File: make.info, Node: Echoing, Next: Execution, Prev: Recipe Syntax, Up: Recipes
3151
3152
5.2 Recipe Echoing
3153
==================
3154
3155
Normally `make' prints each line of the recipe before it is executed.
3156
We call this "echoing" because it gives the appearance that you are
3157
typing the lines yourself.
3138
3158
3139
3159
When a line starts with `@', the echoing of that line is suppressed.
3140
The `@' is discarded before the command is passed to the shell.
3141
Typically you would use this for a command whose only effect is to print
3160
The `@' is discarded before the line is passed to the shell. Typically
3161
you would use this for a command whose only effect is to print
3142
3162
something, such as an `echo' command to indicate progress through the
3143
3163
makefile:
3144
3164
3145
3165
@echo About to make distribution files
3146
3166
3147
3167
When `make' is given the flag `-n' or `--just-print' it only echoes
3148
commands, it won't execute them. *Note Summary of Options: Options
3149
Summary. In this case and only this case, even the commands starting
3150
with `@' are printed. This flag is useful for finding out which
3151
commands `make' thinks are necessary without actually doing them.
3168
most recipes, without executing them. *Note Summary of Options:
3169
Options Summary. In this case even the recipe lines starting with `@'
3170
are printed. This flag is useful for finding out which recipes `make'
3171
thinks are necessary without actually doing them.
3152
3172
3153
3173
The `-s' or `--silent' flag to `make' prevents all echoing, as if
3154
all commands started with `@'. A rule in the makefile for the special
3174
all recipes started with `@'. A rule in the makefile for the special
3155
3175
target `.SILENT' without prerequisites has the same effect (*note
3156
3176
Special Built-in Target Names: Special Targets.). `.SILENT' is
3157
3177
essentially obsolete since `@' is more flexible.
3158
3178
3159
3179
3160
File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Commands
3161
3162
5.3 Command Execution
3163
=====================
3164
3165
When it is time to execute commands to update a target, they are
3166
executed by invoking a new subshell for each command line. (In
3167
practice, `make' may take shortcuts that do not affect the results.)
3180
File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Recipes
3181
3182
5.3 Recipe Execution
3183
====================
3184
3185
When it is time to execute recipes to update a target, they are
3186
executed by invoking a new sub-shell for each line of the recipe,
3187
unless the `.ONESHELL' special target is in effect (*note Using One
3188
Shell: One Shell.) (In practice, `make' may take shortcuts that do not
3189
affect the results.)
3168
3190
3169
3191
*Please note:* this implies that setting shell variables and
3170
3192
invoking shell commands such as `cd' that set a context local to each
3171
process will not affect the following command lines.(1) If you want to
3172
use `cd' to affect the next statement, put both statements in a single
3173
command line. Then `make' will invoke one shell to run the entire
3174
line, and the shell will execute the statements in sequence. For
3175
example:
3193
process will not affect the following lines in the recipe.(1) If you
3194
want to use `cd' to affect the next statement, put both statements in a
3195
single recipe line. Then `make' will invoke one shell to run the
3196
entire line, and the shell will execute the statements in sequence.
3197
For example:
3176
3198
3177
3199
foo : bar/lose
3178
3200
cd $(@D) && gobble $(@F) > ../$@
3184
3206
3185
3207
* Menu:
3186
3208
3209
* One Shell:: One shell for all lines in a recipe.
3187
3210
* Choosing the Shell:: How `make' chooses the shell used
3188
to run commands.
3211
to run recipes.
3189
3212
3190
3213
---------- Footnotes ----------
3191
3214
3192
3215
(1) On MS-DOS, the value of current working directory is *global*, so
3193
changing it _will_ affect the following command lines on those systems.
3194
3195
3196
File: make.info, Node: Choosing the Shell, Prev: Execution, Up: Execution
3197
3198
5.3.1 Choosing the Shell
3216
changing it _will_ affect the following recipe lines on those systems.
3217
3218
3219
File: make.info, Node: One Shell, Next: Choosing the Shell, Prev: Execution, Up: Execution
3220
3221
5.3.1 Using One Shell
3222
---------------------
3223
3224
Sometimes you would prefer that all the lines in the recipe be passed
3225
to a single invocation of the shell. There are generally two
3226
situations where this is useful: first, it can improve performance in
3227
makefiles where recipes consist of many command lines, by avoiding
3228
extra processes. Second, you might want newlines to be included in
3229
your recipe command (for example perhaps you are using a very different
3230
interpreter as your `SHELL'). If the `.ONESHELL' special target
3231
appears anywhere in the makefile then _all_ recipe lines for each
3232
target will be provided to a single invocation of the shell. Newlines
3233
between recipe lines will be preserved. For example:
3234
3235
.ONESHELL:
3236
foo : bar/lose
3237
cd $(@D)
3238
gobble $(@F) > ../$@
3239
3240
would now work as expected even though the commands are on different
3241
recipe lines.
3242
3243
If `.ONESHELL' is provided, then only the first line of the recipe
3244
will be checked for the special prefix characters (`@', `-', and `+').
3245
Subsequent lines will include the special characters in the recipe line
3246
when the `SHELL' is invoked. If you want your recipe to start with one
3247
of these special characters you'll need to arrange for them to not be
3248
the first characters on the first line, perhaps by adding a comment or
3249
similar. For example, this would be a syntax error in Perl because the
3250
first `@' is removed by make:
3251
3252
.ONESHELL:
3253
SHELL = /usr/bin/perl
3254
.SHELLFLAGS = -e
3255
show :
3256
@f = qw(a b c);
3257
print "@f\n";
3258
3259
However, either of these alternatives would work properly:
3260
3261
.ONESHELL:
3262
SHELL = /usr/bin/perl
3263
.SHELLFLAGS = -e
3264
show :
3265
# Make sure "@" is not the first character on the first line
3266
@f = qw(a b c);
3267
print "@f\n";
3268
3269
or
3270
3271
.ONESHELL:
3272
SHELL = /usr/bin/perl
3273
.SHELLFLAGS = -e
3274
show :
3275
my @f = qw(a b c);
3276
print "@f\n";
3277
3278
As a special feature, if `SHELL' is determined to be a POSIX-style
3279
shell, the special prefix characters in "internal" recipe lines will
3280
_removed_ before the recipe is processed. This feature is intended to
3281
allow existing makefiles to add the `.ONESHELL' special target and
3282
still run properly without extensive modifications. Since the special
3283
prefix characters are not legal at the beginning of a line in a POSIX
3284
shell script this is not a loss in functionality. For example, this
3285
works as expected:
3286
3287
.ONESHELL:
3288
foo : bar/lose
3289
@cd $(@D)
3290
@gobble $(@F) > ../$@
3291
3292
Even with this special feature, however, makefiles with `.ONESHELL'
3293
will behave differently in ways that could be noticeable. For example,
3294
normally if any line in the recipe fails, that causes the rule to fail
3295
and no more recipe lines are processed. Under `.ONESHELL' a failure of
3296
any but the final recipe line will not be noticed by `make'. You can
3297
modify `.SHELLFLAGS' to add the `-e' option to the shell which will
3298
cause any failure anywhere in the command line to cause the shell to
3299
fail, but this could itself cause your recipe to behave differently.
3300
Ultimately you may need to harden your recipe lines to allow them to
3301
work with `.ONESHELL'.
3302
3303
3304
File: make.info, Node: Choosing the Shell, Prev: One Shell, Up: Execution
3305
3306
5.3.2 Choosing the Shell
3199
3307
------------------------
3200
3308
3201
3309
The program used as the shell is taken from the variable `SHELL'. If
3202
3310
this variable is not set in your makefile, the program `/bin/sh' is
3203
used as the shell.
3311
used as the shell. The argument(s) passed to the shell are taken from
3312
the variable `.SHELLFLAGS'. The default value of `.SHELLFLAGS' is `-c'
3313
normally, or `-ec' in POSIX-conforming mode.
3204
3314
3205
3315
Unlike most variables, the variable `SHELL' is never set from the
3206
3316
environment. This is because the `SHELL' environment variable is used
3210
3320
Environment.
3211
3321
3212
3322
Furthermore, when you do set `SHELL' in your makefile that value is
3213
_not_ exported in the environment to commands that `make' invokes.
3323
_not_ exported in the environment to recipe lines that `make' invokes.
3214
3324
Instead, the value inherited from the user's environment, if any, is
3215
3325
exported. You can override this behavior by explicitly exporting
3216
3326
`SHELL' (*note Communicating Variables to a Sub-`make':
3217
3327
Variables/Recursion.), forcing it to be passed in the environment to
3218
commands.
3328
recipe lines.
3219
3329
3220
3330
However, on MS-DOS and MS-Windows the value of `SHELL' in the
3221
3331
environment *is* used, since on those systems most users do not set
3280
3390
directory along your `PATH'.
3281
3391
3282
3392
3283
File: make.info, Node: Parallel, Next: Errors, Prev: Execution, Up: Commands
3393
File: make.info, Node: Parallel, Next: Errors, Prev: Execution, Up: Recipes
3284
3394
3285
3395
5.4 Parallel Execution
3286
3396
======================
3287
3397
3288
GNU `make' knows how to execute several commands at once. Normally,
3289
`make' will execute only one command at a time, waiting for it to
3290
finish before executing the next. However, the `-j' or `--jobs' option
3291
tells `make' to execute many commands simultaneously.
3398
GNU `make' knows how to execute several recipes at once. Normally,
3399
`make' will execute only one recipe at a time, waiting for it to finish
3400
before executing the next. However, the `-j' or `--jobs' option tells
3401
`make' to execute many recipes simultaneously. You can inhibit
3402
parallelism in a particular makefile with the `.NOTPARALLEL'
3403
pseudo-target (*note Special Built-in Target Names: Special Targets.).
3292
3404
3293
3405
On MS-DOS, the `-j' option has no effect, since that system doesn't
3294
3406
support multi-processing.
3295
3407
3296
3408
If the `-j' option is followed by an integer, this is the number of
3297
commands to execute at once; this is called the number of "job slots".
3409
recipes to execute at once; this is called the number of "job slots".
3298
3410
If there is nothing looking like an integer after the `-j' option,
3299
3411
there is no limit on the number of job slots. The default number of job
3300
3412
slots is one, which means serial execution (one thing at a time).
3301
3413
3302
One unpleasant consequence of running several commands
3303
simultaneously is that output generated by the commands appears
3304
whenever each command sends it, so messages from different commands may
3305
be interspersed.
3306
3307
Another problem is that two processes cannot both take input from the
3308
same device; so to make sure that only one command tries to take input
3309
from the terminal at once, `make' will invalidate the standard input
3310
streams of all but one running command. This means that attempting to
3311
read from standard input will usually be a fatal error (a `Broken pipe'
3312
signal) for most child processes if there are several.
3313
3314
It is unpredictable which command will have a valid standard input
3315
stream (which will come from the terminal, or wherever you redirect the
3316
standard input of `make'). The first command run will always get it
3317
first, and the first command started after that one finishes will get
3318
it next, and so on.
3319
3320
We will change how this aspect of `make' works if we find a better
3321
alternative. In the mean time, you should not rely on any command using
3322
standard input at all if you are using the parallel execution feature;
3323
but if you are not using this feature, then standard input works
3324
normally in all commands.
3325
3326
Finally, handling recursive `make' invocations raises issues. For
3327
more information on this, see *Note Communicating Options to a
3328
Sub-`make': Options/Recursion.
3329
3330
If a command fails (is killed by a signal or exits with a nonzero
3331
status), and errors are not ignored for that command (*note Errors in
3332
Commands: Errors.), the remaining command lines to remake the same
3333
target will not be run. If a command fails and the `-k' or
3334
`--keep-going' option was not given (*note Summary of Options: Options
3335
Summary.), `make' aborts execution. If make terminates for any reason
3336
(including a signal) with child processes running, it waits for them to
3337
finish before actually exiting.
3414
Handling recursive `make' invocations raises issues for parallel
3415
execution. For more information on this, see *note Communicating
3416
Options to a Sub-`make': Options/Recursion.
3417
3418
If a recipe fails (is killed by a signal or exits with a nonzero
3419
status), and errors are not ignored for that recipe (*note Errors in
3420
Recipes: Errors.), the remaining recipe lines to remake the same target
3421
will not be run. If a recipe fails and the `-k' or `--keep-going'
3422
option was not given (*note Summary of Options: Options Summary.),
3423
`make' aborts execution. If make terminates for any reason (including
3424
a signal) with child processes running, it waits for them to finish
3425
before actually exiting.
3338
3426
3339
3427
When the system is heavily loaded, you will probably want to run
3340
3428
fewer jobs than when it is lightly loaded. You can use the `-l' option
3355
3443
3356
3444
By default, there is no load limit.
3357
3445
3358
3359
File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Commands
3360
3361
5.5 Errors in Commands
3362
======================
3363
3364
After each shell command returns, `make' looks at its exit status. If
3365
the command completed successfully, the next command line is executed
3366
in a new shell; after the last command line is finished, the rule is
3367
finished.
3446
* Menu:
3447
3448
* Parallel Output:: Handling output during parallel execution
3449
* Parallel Input:: Handling input during parallel execution
3450
3451
3452
File: make.info, Node: Parallel Output, Next: Parallel Input, Prev: Parallel, Up: Parallel
3453
3454
5.4.1 Output During Parallel Execution
3455
--------------------------------------
3456
3457
When running several recipes in parallel the output from each recipe
3458
appears as soon as it is generated, with the result that messages from
3459
different recipes may be interspersed, sometimes even appearing on the
3460
same line. This can make reading the output very difficult.
3461
3462
To avoid this you can use the `--output-sync' (`-O') option. This
3463
option instructs `make' to save the output from the commands it invokes
3464
and print it all once the commands are completed. Additionally, if
3465
there are multiple recursive `make' invocations running in parallel,
3466
they will communicate so that only one of them is generating output at
3467
a time.
3468
3469
If working directory printing is enabled (*note The
3470
`--print-directory' Option: -w Option.), the enter/leave messages are
3471
printed around each output grouping. If you prefer not to see these
3472
messages add the `--no-print-directory' option to `MAKEFLAGS'.
3473
3474
There are four levels of granularity when synchronizing output,
3475
specified by giving an argument to the option (e.g., `-Oline' or
3476
`--output-sync=recurse').
3477
3478
`none'
3479
This is the default: all output is sent directly as it is
3480
generated and no synchronization is performed.
3481
3482
`line'
3483
Output from each individual line of the recipe is grouped and
3484
printed as soon as that line is complete. If a recipe consists of
3485
multiple lines, they may be interspersed with lines from other
3486
recipes.
3487
3488
`target'
3489
Output from the entire recipe for each target is grouped and
3490
printed once the target is complete. This is the default if the
3491
`--output-sync' or `-O' option is given with no argument.
3492
3493
`recurse'
3494
Output from each recursive invocation of `make' is grouped and
3495
printed once the recursive invocation is complete.
3496
3497
3498
Regardless of the mode chosen, the total build time will be the same.
3499
The only difference is in how the output appears.
3500
3501
The `target' and `recurse' modes both collect the output of the
3502
entire recipe of a target and display it uninterrupted when the recipe
3503
completes. The difference between them is in how recipes that contain
3504
recursive invocations of `make' are treated (*note Recursive Use of
3505
`make': Recursion.). For all recipes which have no recursive lines,
3506
the `target' and `recurse' modes behave identically.
3507
3508
If the `recurse' mode is chosen, recipes that contain recursive
3509
`make' invocations are treated the same as other targets: the output
3510
from the recipe, including the output from the recursive `make', is
3511
saved and printed after the entire recipe is complete. This ensures
3512
output from all the targets built by a given recursive `make' instance
3513
are grouped together, which may make the output easier to understand.
3514
However it also leads to long periods of time during the build where no
3515
output is seen, followed by large bursts of output. If you are not
3516
watching the build as it proceeds, but instead viewing a log of the
3517
build after the fact, this may be the best option for you.
3518
3519
If you are watching the output, the long gaps of quiet during the
3520
build can be frustrating. The `target' output synchronization mode
3521
detects when `make' is going to be invoked recursively, using the
3522
standard methods, and it will not synchronize the output of those
3523
lines. The recursive `make' will perform the synchronization for its
3524
targets and the output from each will be displayed immediately when it
3525
completes. Be aware that output from recursive lines of the recipe are
3526
not synchronized (for example if the recursive line prints a message
3527
before running `make', that message will not be synchronized).
3528
3529
The `line' mode can be useful for front-ends that are watching the
3530
output of `make' to track when recipes are started and completed.
3531
3532
Some programs invoked by `make' may behave differently if they
3533
determine they're writing output to a terminal versus a file (often
3534
described as "interactive" vs. "non-interactive" modes). For example,
3535
many programs that can display colorized output will not do so if they
3536
determine they are not writing to a terminal. If your makefile invokes
3537
a program like this then using the output synchronization options will
3538
cause the program to believe it's running in "non-interactive" mode
3539
even though the output will ultimately go to the terminal.
3540
3541
3542
File: make.info, Node: Parallel Input, Prev: Parallel Output, Up: Parallel
3543
3544
5.4.2 Input During Parallel Execution
3545
-------------------------------------
3546
3547
Two processes cannot both take input from the same device at the same
3548
time. To make sure that only one recipe tries to take input from the
3549
terminal at once, `make' will invalidate the standard input streams of
3550
all but one running recipe. If another recipe attempts to read from
3551
standard input it will usually incur a fatal error (a `Broken pipe'
3552
signal).
3553
3554
It is unpredictable which recipe will have a valid standard input
3555
stream (which will come from the terminal, or wherever you redirect the
3556
standard input of `make'). The first recipe run will always get it
3557
first, and the first recipe started after that one finishes will get it
3558
next, and so on.
3559
3560
We will change how this aspect of `make' works if we find a better
3561
alternative. In the mean time, you should not rely on any recipe using
3562
standard input at all if you are using the parallel execution feature;
3563
but if you are not using this feature, then standard input works
3564
normally in all recipes.
3565
3566
3567
File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Recipes
3568
3569
5.5 Errors in Recipes
3570
=====================
3571
3572
After each shell invocation returns, `make' looks at its exit status.
3573
If the shell completed successfully (the exit status is zero), the next
3574
line in the recipe is executed in a new shell; after the last line is
3575
finished, the rule is finished.
3368
3576
3369
3577
If there is an error (the exit status is nonzero), `make' gives up on
3370
3578
the current rule, and perhaps on all rules.
3371
3579
3372
Sometimes the failure of a certain command does not indicate a
3580
Sometimes the failure of a certain recipe line does not indicate a
3373
3581
problem. For example, you may use the `mkdir' command to ensure that a
3374
3582
directory exists. If the directory already exists, `mkdir' will report
3375
3583
an error, but you probably want `make' to continue regardless.
3376
3584
3377
To ignore errors in a command line, write a `-' at the beginning of
3585
To ignore errors in a recipe line, write a `-' at the beginning of
3378
3586
the line's text (after the initial tab). The `-' is discarded before
3379
the command is passed to the shell for execution.
3587
the line is passed to the shell for execution.
3380
3588
3381
3589
For example,
3382
3590
3383
3591
clean:
3384
3592
-rm -f *.o
3385
3593
3386
This causes `rm' to continue even if it is unable to remove a file.
3594
This causes `make' to continue even if `rm' is unable to remove a file.
3387
3595
3388
3596
When you run `make' with the `-i' or `--ignore-errors' flag, errors
3389
are ignored in all commands of all rules. A rule in the makefile for
3597
are ignored in all recipes of all rules. A rule in the makefile for
3390
3598
the special target `.IGNORE' has the same effect, if there are no
3391
3599
prerequisites. These ways of ignoring errors are obsolete because `-'
3392
3600
is more flexible.
3393
3601
3394
3602
When errors are to be ignored, because of either a `-' or the `-i'
3395
3603
flag, `make' treats an error return just like success, except that it
3396
prints out a message that tells you the status code the command exited
3604
prints out a message that tells you the status code the shell exited
3397
3605
with, and says that the error has been ignored.
3398
3606
3399
3607
When an error happens that `make' has not been told to ignore, it
3400
3608
implies that the current target cannot be correctly remade, and neither
3401
3609
can any other that depends on it either directly or indirectly. No
3402
further commands will be executed for these targets, since their
3610
further recipes will be executed for these targets, since their
3403
3611
preconditions have not been achieved.
3404
3612
3405
3613
Normally `make' gives up immediately in this circumstance, returning
3419
3627
that you can correct them all before the next attempt to compile. This
3420
3628
is why Emacs' `compile' command passes the `-k' flag by default.
3421
3629
3422
Usually when a command fails, if it has changed the target file at
3423
all, the file is corrupted and cannot be used--or at least it is not
3630
Usually when a recipe line fails, if it has changed the target file
3631
at all, the file is corrupted and cannot be used--or at least it is not
3424
3632
completely updated. Yet the file's time stamp says that it is now up to
3425
3633
date, so the next time `make' runs, it will not try to update that
3426
file. The situation is just the same as when the command is killed by a
3634
file. The situation is just the same as when the shell is killed by a
3427
3635
signal; *note Interrupts::. So generally the right thing to do is to
3428
delete the target file if the command fails after beginning to change
3636
delete the target file if the recipe fails after beginning to change
3429
3637
the file. `make' will do this if `.DELETE_ON_ERROR' appears as a
3430
3638
target. This is almost always what you want `make' to do, but it is
3431
3639
not historical practice; so for compatibility, you must explicitly
3432
3640
request it.
3433
3641
3434
3642
3435
File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Commands
3643
File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Recipes
3436
3644
3437
3645
5.6 Interrupting or Killing `make'
3438
3646
==================================
3439
3647
3440
If `make' gets a fatal signal while a command is executing, it may
3441
delete the target file that the command was supposed to update. This is
3442
done if the target file's last-modification time has changed since
3443
`make' first checked it.
3648
If `make' gets a fatal signal while a shell is executing, it may delete
3649
the target file that the recipe was supposed to update. This is done
3650
if the target file's last-modification time has changed since `make'
3651
first checked it.
3444
3652
3445
3653
The purpose of deleting the target is to make sure that it is remade
3446
3654
from scratch when `make' is next run. Why is this? Suppose you type
3463
3671
times to prevent other sorts of trouble.
3464
3672
3465
3673
3466
File: make.info, Node: Recursion, Next: Sequences, Prev: Interrupts, Up: Commands
3674
File: make.info, Node: Recursion, Next: Canned Recipes, Prev: Interrupts, Up: Recipes
3467
3675
3468
3676
5.7 Recursive Use of `make'
3469
3677
===========================
3471
3679
Recursive use of `make' means using `make' as a command in a makefile.
3472
3680
This technique is useful when you want separate makefiles for various
3473
3681
subsystems that compose a larger system. For example, suppose you have
3474
a subdirectory `subdir' which has its own makefile, and you would like
3475
the containing directory's makefile to run `make' on the subdirectory.
3682
a sub-directory `subdir' which has its own makefile, and you would like
3683
the containing directory's makefile to run `make' on the sub-directory.
3476
3684
You can do it by writing this:
3477
3685
3478
3686
subsystem:
3487
3695
but there are many things to know about how they work and why, and about
3488
3696
how the sub-`make' relates to the top-level `make'. You may also find
3489
3697
it useful to declare targets that invoke recursive `make' commands as
3490
`.PHONY' (for more discussion on when this is useful, see *Note Phony
3698
`.PHONY' (for more discussion on when this is useful, see *note Phony
3491
3699
Targets::).
3492
3700
3493
3701
For your convenience, when GNU `make' starts (after it has processed
3522
3730
cd subdir && $(MAKE)
3523
3731
3524
3732
The value of this variable is the file name with which `make' was
3525
invoked. If this file name was `/bin/make', then the command executed
3733
invoked. If this file name was `/bin/make', then the recipe executed
3526
3734
is `cd subdir && /bin/make'. If you use a special version of `make' to
3527
3735
run the top-level makefile, the same special version will be executed
3528
3736
for recursive invocations.
3529
3737
3530
As a special feature, using the variable `MAKE' in the commands of a
3738
As a special feature, using the variable `MAKE' in the recipe of a
3531
3739
rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'),
3532
3740
or `-q' (`--question') option. Using the `MAKE' variable has the same
3533
effect as using a `+' character at the beginning of the command line.
3534
*Note Instead of Executing the Commands: Instead of Execution. This
3741
effect as using a `+' character at the beginning of the recipe line.
3742
*Note Instead of Executing the Recipes: Instead of Execution. This
3535
3743
special feature is only enabled if the `MAKE' variable appears directly
3536
in the command script: it does not apply if the `MAKE' variable is
3537
referenced through expansion of another variable. In the latter case
3538
you must use the `+' token to get these special effects.
3744
in the recipe: it does not apply if the `MAKE' variable is referenced
3745
through expansion of another variable. In the latter case you must use
3746
the `+' token to get these special effects.
3539
3747
3540
3748
Consider the command `make -t' in the above example. (The `-t'
3541
3749
option marks targets as up to date without actually running any
3542
commands; see *Note Instead of Execution::.) Following the usual
3750
recipes; see *note Instead of Execution::.) Following the usual
3543
3751
definition of `-t', a `make -t' command in the example would create a
3544
3752
file named `subsystem' and do nothing else. What you really want it to
3545
3753
do is run `cd subdir && make -t'; but that would require executing the
3546
command, and `-t' says not to execute commands.
3754
recipe, and `-t' says not to execute recipes.
3547
3755
3548
The special feature makes this do what you want: whenever a command
3756
The special feature makes this do what you want: whenever a recipe
3549
3757
line of a rule contains the variable `MAKE', the flags `-t', `-n' and
3550
`-q' do not apply to that line. Command lines containing `MAKE' are
3758
`-q' do not apply to that line. Recipe lines containing `MAKE' are
3551
3759
executed normally despite the presence of a flag that causes most
3552
commands not to be run. The usual `MAKEFLAGS' mechanism passes the
3760
recipes not to be run. The usual `MAKEFLAGS' mechanism passes the
3553
3761
flags to the sub-`make' (*note Communicating Options to a Sub-`make':
3554
3762
Options/Recursion.), so your request to touch the files, or print the
3555
commands, is propagated to the subsystem.
3763
recipes, is propagated to the subsystem.
3556
3764
3557
3765
3558
3766
File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MAKE Variable, Up: Recursion
3562
3770
3563
3771
Variable values of the top-level `make' can be passed to the sub-`make'
3564
3772
through the environment by explicit request. These variables are
3565
defined in the sub-`make' as defaults, but do not override what is
3566
specified in the makefile used by the sub-`make' makefile unless you
3567
use the `-e' switch (*note Summary of Options: Options Summary.).
3773
defined in the sub-`make' as defaults, but they do not override
3774
variables defined in the makefile used by the sub-`make' unless you use
3775
the `-e' switch (*note Summary of Options: Options Summary.).
3568
3776
3569
3777
To pass down, or "export", a variable, `make' adds the variable and
3570
its value to the environment for running each command. The sub-`make',
3571
in turn, uses the environment to initialize its table of variable
3572
values. *Note Variables from the Environment: Environment.
3778
its value to the environment for running each line of the recipe. The
3779
sub-`make', in turn, uses the environment to initialize its table of
3780
variable values. *Note Variables from the Environment: Environment.
3573
3781
3574
3782
Except by explicit request, `make' exports a variable only if it is
3575
3783
either defined in the environment initially or set on the command line,
3665
3873
export variables by default. Since this is the default behavior, you
3666
3874
would only need to do this if `export' had been used by itself earlier
3667
3875
(in an included makefile, perhaps). You *cannot* use `export' and
3668
`unexport' by themselves to have variables exported for some commands
3876
`unexport' by themselves to have variables exported for some recipes
3669
3877
and not for others. The last `export' or `unexport' directive that
3670
3878
appears by itself determines the behavior for the entire run of `make'.
3671
3879
3674
3882
which is the depth of the level as a decimal number. The value is `0'
3675
3883
for the top-level `make'; `1' for a sub-`make', `2' for a
3676
3884
sub-sub-`make', and so on. The incrementation happens when `make' sets
3677
up the environment for a command.
3885
up the environment for a recipe.
3678
3886
3679
3887
The main use of `MAKELEVEL' is to test it in a conditional directive
3680
3888
(*note Conditional Parts of Makefiles: Conditionals.); this way you can
3720
3928
the parent `make' and all the sub-`make's will communicate to ensure
3721
3929
that there are only `N' jobs running at the same time between them all.
3722
3930
Note that any job that is marked recursive (*note Instead of Executing
3723
the Commands: Instead of Execution.) doesn't count against the total
3724
jobs (otherwise we could get `N' sub-`make's running and have no slots
3725
left over for any real work!)
3931
Recipes: Instead of Execution.) doesn't count against the total jobs
3932
(otherwise we could get `N' sub-`make's running and have no slots left
3933
over for any real work!)
3726
3934
3727
3935
If your operating system doesn't support the above communication,
3728
3936
then `-j 1' is always put into `MAKEFLAGS' instead of the value you
3740
3948
3741
3949
The command line variable definitions really appear in the variable
3742
3950
`MAKEOVERRIDES', and `MAKEFLAGS' contains a reference to this variable.
3743
If you do want to pass flags down normally, but don't want to pass
3744
down the command line variable definitions, you can reset
3745
`MAKEOVERRIDES' to empty, like this:
3951
If you do want to pass flags down normally, but don't want to pass down
3952
the command line variable definitions, you can reset `MAKEOVERRIDES' to
3953
empty, like this:
3746
3954
3747
3955
MAKEOVERRIDES =
3748
3956
3794
4002
variables, could have disastrous consequences and would certainly have
3795
4003
at least surprising and probably annoying effects.
3796
4004
4005
If you'd like to run other implementations of `make' in addition to
4006
GNU `make', and hence do not want to add GNU `make'-specific flags to
4007
the `MAKEFLAGS' variable, you can add them to the `GNUMAKEFLAGS'
4008
variable instead. This variable is parsed just before `MAKEFLAGS', in
4009
the same way as `MAKEFLAGS'. When `make' constructs `MAKEFLAGS' to
4010
pass to a recursive `make' it will include all flags, even those taken
4011
from `GNUMAKEFLAGS'. As a result, after parsing `GNUMAKEFLAGS' GNU
4012
`make' sets this variable to the empty string to avoid duplicating
4013
flags during recursion.
4014
4015
It's best to use `GNUMAKEFLAGS' only with flags which won't
4016
materially change the behavior of your makefiles. If your makefiles
4017
require GNU make anyway then simply use `MAKEFLAGS'. Flags such as
4018
`--no-print-directory' or `--output-sync' may be appropriate for
4019
`GNUMAKEFLAGS'.
4020
3797
4021
3798
4022
File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion
3799
4023
3821
4045
`--no-print-directory' to explicitly disable it.
3822
4046
3823
4047
3824
File: make.info, Node: Sequences, Next: Empty Commands, Prev: Recursion, Up: Commands
4048
File: make.info, Node: Canned Recipes, Next: Empty Recipes, Prev: Recursion, Up: Recipes
3825
4049
3826
5.8 Defining Canned Command Sequences
3827
=====================================
4050
5.8 Defining Canned Recipes
4051
===========================
3828
4052
3829
4053
When the same sequence of commands is useful in making various targets,
3830
4054
you can define it as a canned sequence with the `define' directive, and
3831
refer to the canned sequence from the rules for those targets. The
4055
refer to the canned sequence from the recipes for those targets. The
3832
4056
canned sequence is actually a variable, so the name must not conflict
3833
4057
with other variable names.
3834
4058
3835
Here is an example of defining a canned sequence of commands:
4059
Here is an example of defining a canned recipe:
3836
4060
3837
define run-yacc
4061
define run-yacc =
3838
4062
yacc $(firstword $^)
3839
4063
mv y.tab.c $@
3840
4064
endef
3841
4065
3842
4066
Here `run-yacc' is the name of the variable being defined; `endef'
3843
4067
marks the end of the definition; the lines in between are the commands.
3844
The `define' directive does not expand variable references and
3845
function calls in the canned sequence; the `$' characters, parentheses,
3846
variable names, and so on, all become part of the value of the variable
3847
you are defining. *Note Defining Variables Verbatim: Defining, for a
4068
The `define' directive does not expand variable references and function
4069
calls in the canned sequence; the `$' characters, parentheses, variable
4070
names, and so on, all become part of the value of the variable you are
4071
defining. *Note Defining Multi-Line Variables: Multi-Line, for a
3848
4072
complete explanation of `define'.
3849
4073
3850
4074
The first command in this example runs Yacc on the first
3852
4076
file from Yacc is always named `y.tab.c'. The second command moves the
3853
4077
output to the rule's target file name.
3854
4078
3855
To use the canned sequence, substitute the variable into the
3856
commands of a rule. You can substitute it like any other variable
3857
(*note Basics of Variable References: Reference.). Because variables
3858
defined by `define' are recursively expanded variables, all the
3859
variable references you wrote inside the `define' are expanded now.
3860
For example:
4079
To use the canned sequence, substitute the variable into the recipe
4080
of a rule. You can substitute it like any other variable (*note Basics
4081
of Variable References: Reference.). Because variables defined by
4082
`define' are recursively expanded variables, all the variable
4083
references you wrote inside the `define' are expanded now. For example:
3861
4084
3862
4085
foo.c : foo.y
3863
4086
$(run-yacc)
3870
4093
commands based on the file names involved (*note Using Implicit Rules:
3871
4094
Implicit Rules.).
3872
4095
3873
In command execution, each line of a canned sequence is treated just
4096
In recipe execution, each line of a canned sequence is treated just
3874
4097
as if the line appeared on its own in the rule, preceded by a tab. In
3875
particular, `make' invokes a separate subshell for each line. You can
4098
particular, `make' invokes a separate sub-shell for each line. You can
3876
4099
use the special prefix characters that affect command lines (`@', `-',
3877
and `+') on each line of a canned sequence. *Note Writing the Commands
3878
in Rules: Commands. For example, using this canned sequence:
4100
and `+') on each line of a canned sequence. *Note Writing Recipes in
4101
Rules: Recipes. For example, using this canned sequence:
3879
4102
3880
define frobnicate
4103
define frobnicate =
3881
4104
@echo "frobnicating target $@"
3882
4105
frob-step-1 $< -o $@-step-1
3883
4106
frob-step-2 $@-step-1 -o $@
3884
4107
endef
3885
4108
3886
4109
`make' will not echo the first line, the `echo' command. But it _will_
3887
echo the following two command lines.
4110
echo the following two recipe lines.
3888
4111
3889
On the other hand, prefix characters on the command line that refers
4112
On the other hand, prefix characters on the recipe line that refers
3890
4113
to a canned sequence apply to every line in the sequence. So the rule:
3891
4114
3892
4115
frob.out: frob.in
3893
4116
@$(frobnicate)
3894
4117
3895
does not echo _any_ commands. (*Note Command Echoing: Echoing, for a
3896
full explanation of `@'.)
4118
does not echo _any_ recipe lines. (*Note Recipe Echoing: Echoing, for
4119
a full explanation of `@'.)
3897
4120
3898
4121
3899
File: make.info, Node: Empty Commands, Prev: Sequences, Up: Commands
3900
3901
5.9 Using Empty Commands
3902
========================
3903
3904
It is sometimes useful to define commands which do nothing. This is
3905
done simply by giving a command that consists of nothing but
3906
whitespace. For example:
4122
File: make.info, Node: Empty Recipes, Prev: Canned Recipes, Up: Recipes
4123
4124
5.9 Using Empty Recipes
4125
=======================
4126
4127
It is sometimes useful to define recipes which do nothing. This is done
4128
simply by giving a recipe that consists of nothing but whitespace. For
4129
example:
3907
4130
3908
4131
target: ;
3909
4132
3910
defines an empty command string for `target'. You could also use a
3911
line beginning with a tab character to define an empty command string,
3912
but this would be confusing because such a line looks empty.
3913
3914
You may be wondering why you would want to define a command string
3915
that does nothing. The only reason this is useful is to prevent a
3916
target from getting implicit commands (from implicit rules or the
3917
`.DEFAULT' special target; *note Implicit Rules:: and *note Defining
3918
Last-Resort Default Rules: Last Resort.).
3919
3920
You may be inclined to define empty command strings for targets that
3921
are not actual files, but only exist so that their prerequisites can be
3922
remade. However, this is not the best way to do that, because the
3923
prerequisites may not be remade properly if the target file actually
3924
does exist. *Note Phony Targets: Phony Targets, for a better way to do
3925
this.
4133
defines an empty recipe for `target'. You could also use a line
4134
beginning with a recipe prefix character to define an empty recipe, but
4135
this would be confusing because such a line looks empty.
4136
4137
You may be wondering why you would want to define a recipe that does
4138
nothing. The only reason this is useful is to prevent a target from
4139
getting implicit recipes (from implicit rules or the `.DEFAULT' special
4140
target; *note Implicit Rules:: and *note Defining Last-Resort Default
4141
Rules: Last Resort.).
4142
4143
You may be inclined to define empty recipes for targets that are not
4144
actual files, but only exist so that their prerequisites can be remade.
4145
However, this is not the best way to do that, because the prerequisites
4146
may not be remade properly if the target file actually does exist.
4147
*Note Phony Targets: Phony Targets, for a better way to do this.
3926
4148
3927
4149
3928
File: make.info, Node: Using Variables, Next: Conditionals, Prev: Commands, Up: Top
4150
File: make.info, Node: Using Variables, Next: Conditionals, Prev: Recipes, Up: Top
3929
4151
3930
4152
6 How to Use Variables
3931
4153
**********************
3932
4154
3933
4155
A "variable" is a name defined in a makefile to represent a string of
3934
4156
text, called the variable's "value". These values are substituted by
3935
explicit request into targets, prerequisites, commands, and other parts
4157
explicit request into targets, prerequisites, recipes, and other parts
3936
4158
of the makefile. (In some other versions of `make', variables are
3937
4159
called "macros".)
3938
4160
3939
4161
Variables and functions in all parts of a makefile are expanded when
3940
read, except for the shell commands in rules, the right-hand sides of
3941
variable definitions using `=', and the bodies of variable definitions
3942
using the `define' directive.
4162
read, except for in recipes, the right-hand sides of variable
4163
definitions using `=', and the bodies of variable definitions using the
4164
`define' directive.
3943
4165
3944
4166
Variables can represent lists of file names, options to pass to
3945
4167
compilers, programs to run, directories to look in for source files,
3946
4168
directories to write output in, or anything else you can imagine.
3947
4169
3948
A variable name may be any sequence of characters not containing `:',
3949
`#', `=', or leading or trailing whitespace. However, variable names
3950
containing characters other than letters, numbers, and underscores
3951
should be avoided, as they may be given special meanings in the future,
3952
and with some shells they cannot be passed through the environment to a
3953
sub-`make' (*note Communicating Variables to a Sub-`make':
3954
Variables/Recursion.).
4170
A variable name may be any sequence of characters not containing
4171
`:', `#', `=', or whitespace. However, variable names containing
4172
characters other than letters, numbers, and underscores should be
4173
considered carefully, as in some shells they cannot be passed through
4174
the environment to a sub-`make' (*note Communicating Variables to a
4175
Sub-`make': Variables/Recursion.). Variable names beginning with `.'
4176
and an uppercase letter may be given special meaning in future versions
4177
of `make'.
3955
4178
3956
4179
Variable names are case-sensitive. The names `foo', `FOO', and
3957
4180
`Foo' all refer to different variables.
3978
4201
of a variable.
3979
4202
* Override Directive:: How to set a variable in the makefile even if
3980
4203
the user has set it with a command argument.
3981
* Defining:: An alternate way to set a variable
3982
to a verbatim string.
4204
* Multi-Line:: An alternate way to set a variable
4205
to a multi-line string.
4206
* Undefine Directive:: How to undefine a variable so that it appears
4207
as if it was never set.
3983
4208
* Environment:: Variable values can come from the environment.
3984
4209
* Target-specific:: Variable values can be defined on a per-target
3985
4210
basis.
3986
4211
* Pattern-specific:: Target-specific variable values can be applied
3987
4212
to a group of targets that match a pattern.
4213
* Suppressing Inheritance:: Suppress inheritance of variables.
4214
* Special Variables:: Variables with special meaning or behavior.
3988
4215
3989
4216
3990
4217
File: make.info, Node: Reference, Next: Flavors, Prev: Using Variables, Up: Using Variables
3996
4223
name of the variable in parentheses or braces: either `$(foo)' or
3997
4224
`${foo}' is a valid reference to the variable `foo'. This special
3998
4225
significance of `$' is why you must write `$$' to have the effect of a
3999
single dollar sign in a file name or command.
4226
single dollar sign in a file name or recipe.
4000
4227
4001
4228
Variable references can be used in any context: targets,
4002
prerequisites, commands, most directives, and new variable values.
4003
Here is an example of a common case, where a variable holds the names
4004
of all the object files in a program:
4229
prerequisites, recipes, most directives, and new variable values. Here
4230
is an example of a common case, where a variable holds the names of all
4231
the object files in a program:
4005
4232
4006
4233
objects = program.o foo.o utils.o
4007
4234
program : $(objects)
4039
4266
The first flavor of variable is a "recursively expanded" variable.
4040
4267
Variables of this sort are defined by lines using `=' (*note Setting
4041
4268
Variables: Setting.) or by the `define' directive (*note Defining
4042
Variables Verbatim: Defining.). The value you specify is installed
4269
Multi-Line Variables: Multi-Line.). The value you specify is installed
4043
4270
verbatim; if it contains references to other variables, these
4044
4271
references are expanded whenever this variable is substituted (in the
4045
4272
course of expanding some other string). When this happens, it is
4056
4283
will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to
4057
4284
`$(ugh)' which finally expands to `Huh?'.
4058
4285
4059
This flavor of variable is the only sort supported by other versions
4060
of `make'. It has its advantages and its disadvantages. An advantage
4061
(most would say) is that:
4286
This flavor of variable is the only sort supported by most other
4287
versions of `make'. It has its advantages and its disadvantages. An
4288
advantage (most would say) is that:
4062
4289
4063
4290
CFLAGS = $(include_dirs) -O
4064
4291
include_dirs = -Ifoo -Ibar
4065
4292
4066
will do what was intended: when `CFLAGS' is expanded in a command, it
4293
will do what was intended: when `CFLAGS' is expanded in a recipe, it
4067
4294
will expand to `-Ifoo -Ibar -O'. A major disadvantage is that you
4068
4295
cannot append something on the end of a variable, as in
4069
4296
4082
4309
To avoid all the problems and inconveniences of recursively expanded
4083
4310
variables, there is another flavor: simply expanded variables.
4084
4311
4085
"Simply expanded variables" are defined by lines using `:=' (*note
4086
Setting Variables: Setting.). The value of a simply expanded variable
4087
is scanned once and for all, expanding any references to other
4088
variables and functions, when the variable is defined. The actual
4089
value of the simply expanded variable is the result of expanding the
4090
text that you write. It does not contain any references to other
4091
variables; it contains their values _as of the time this variable was
4092
defined_. Therefore,
4312
"Simply expanded variables" are defined by lines using `:=' or `::='
4313
(*note Setting Variables: Setting.). Both forms are equivalent in GNU
4314
`make'; however only the `::=' form is described by the POSIX standard
4315
(support for `::=' was added to the POSIX standard in 2012, so older
4316
versions of `make' won't accept this form either).
4317
4318
The value of a simply expanded variable is scanned once and for all,
4319
expanding any references to other variables and functions, when the
4320
variable is defined. The actual value of the simply expanded variable
4321
is the result of expanding the text that you write. It does not
4322
contain any references to other variables; it contains their values _as
4323
of the time this variable was defined_. Therefore,
4093
4324
4094
4325
x := foo
4095
4326
y := $(x) bar
4117
4348
endif
4118
4349
4119
4350
An advantage of this use of `:=' is that a typical `descend into a
4120
directory' command then looks like this:
4351
directory' recipe then looks like this:
4121
4352
4122
4353
${subdirs}:
4123
4354
${MAKE} -C $@ all
4268
4499
`u'.
4269
4500
4270
4501
References to recursively-expanded variables within a variable name
4271
are reexpanded in the usual fashion. For example:
4502
are re-expanded in the usual fashion. For example:
4272
4503
4273
4504
x = $(y)
4274
4505
y = z
4359
4590
4360
4591
dir = foo
4361
4592
$(dir)_sources := $(wildcard $(dir)/*.c)
4362
define $(dir)_print
4593
define $(dir)_print =
4363
4594
lpr $($(dir)_sources)
4364
4595
endef
4365
4596
4384
4615
4385
4616
* You can specify a value in the makefile, either with an assignment
4386
4617
(*note Setting Variables: Setting.) or with a verbatim definition
4387
(*note Defining Variables Verbatim: Defining.).
4618
(*note Defining Multi-Line Variables: Multi-Line.).
4388
4619
4389
4620
* Variables in the environment become `make' variables. *Note
4390
4621
Variables from the Environment: Environment.
4403
4634
=====================
4404
4635
4405
4636
To set a variable from the makefile, write a line starting with the
4406
variable name followed by `=' or `:='. Whatever follows the `=' or
4407
`:=' on the line becomes the value. For example,
4637
variable name followed by `=' `:=', or `::='. Whatever follows the
4638
`=', `:=', or `::=' on the line becomes the value. For example,
4408
4639
4409
4640
objects = main.o foo.o bar.o utils.o
4410
4641
4412
4643
name and immediately after the `=' is ignored.
4413
4644
4414
4645
Variables defined with `=' are "recursively expanded" variables.
4415
Variables defined with `:=' are "simply expanded" variables; these
4416
definitions can contain variable references which will be expanded
4417
before the definition is made. *Note The Two Flavors of Variables:
4418
Flavors.
4646
Variables defined with `:=' or `::=' are "simply expanded" variables;
4647
these definitions can contain variable references which will be
4648
expanded before the definition is made. *Note The Two Flavors of
4649
Variables: Flavors.
4419
4650
4420
4651
The variable name may contain function and variable references, which
4421
4652
are expanded when the line is read to find the actual variable name to
4422
4653
use.
4423
4654
4424
4655
There is no limit on the length of the value of a variable except the
4425
amount of swapping space on the computer. When a variable definition is
4426
long, it is a good idea to break it into several lines by inserting
4427
backslash-newline at convenient places in the definition. This will not
4428
affect the functioning of `make', but it will make the makefile easier
4429
to read.
4656
amount of memory on the computer. You can split the value of a
4657
variable into multiple physical lines for readability (*note Splitting
4658
Long Lines: Splitting Lines.).
4430
4659
4431
4660
Most variable names are considered to have the empty string as a
4432
4661
value if you have never set them. Several variables have built-in
4449
4678
FOO = bar
4450
4679
endif
4451
4680
4681
The shell assignment operator `!=' can be used to execute a program
4682
and set a variable to its output. This operator first evaluates the
4683
right-hand side, then passes that result to the shell for execution.
4684
If the result of the execution ends in a newline, that one newline is
4685
removed; all other newlines are replaced by spaces. The resulting
4686
string is then placed into the named recursively-expanded variable.
4687
For example:
4688
4689
hash != printf '\043'
4690
file_list != find . -name '*.c'
4691
4692
If the result of the execution could produce a `$', and you don't
4693
intend what follows that to be interpreted as a make variable or
4694
function reference, then you must replace every `$' with `$$' as part
4695
of the execution. Alternatively, you can set a simply expanded
4696
variable to the result of running a program using the `shell' function
4697
call. *Note The `shell' Function: Shell Function. For example:
4698
4699
hash := $(shell printf '\043')
4700
var := $(shell find . -name "*.c")
4701
4452
4702
4453
4703
File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables
4454
4704
4485
4735
4486
4736
When you add to a variable's value with `+=', `make' acts
4487
4737
essentially as if you had included the extra text in the initial
4488
definition of the variable. If you defined it first with `:=', making
4489
it a simply-expanded variable, `+=' adds to that simply-expanded
4490
definition, and expands the new text before appending it to the old
4491
value just as `:=' does (see *Note Setting Variables: Setting, for a
4492
full explanation of `:='). In fact,
4738
definition of the variable. If you defined it first with `:=' or
4739
`::=', making it a simply-expanded variable, `+=' adds to that
4740
simply-expanded definition, and expands the new text before appending
4741
it to the old value just as `:=' does (see *note Setting Variables:
4742
Setting, for a full explanation of `:=' or `::='). In fact,
4493
4743
4494
4744
variable := value
4495
4745
variable += more
4548
4798
point, a reference like `$(CFLAGS)' still uses its value.
4549
4799
4550
4800
4551
File: make.info, Node: Override Directive, Next: Defining, Prev: Appending, Up: Using Variables
4801
File: make.info, Node: Override Directive, Next: Multi-Line, Prev: Appending, Up: Using Variables
4552
4802
4553
4803
6.7 The `override' Directive
4554
4804
============================
4571
4821
4572
4822
*Note Appending More Text to Variables: Appending.
4573
4823
4824
Variable assignments marked with the `override' flag have a higher
4825
priority than all other assignments, except another `override'.
4826
Subsequent assignments or appends to this variable which are not marked
4827
`override' will be ignored.
4828
4574
4829
The `override' directive was not invented for escalation in the war
4575
4830
between makefiles and command arguments. It was invented so you can
4576
4831
alter and add to values that the user specifies with command arguments.
4585
4840
You can also use `override' directives with `define' directives.
4586
4841
This is done as you might expect:
4587
4842
4588
override define foo
4843
override define foo =
4589
4844
bar
4590
4845
endef
4591
4846
4592
*Note Defining Variables Verbatim: Defining.
4847
*Note Defining Multi-Line Variables: Multi-Line.
4593
4848
4594
4849
4595
File: make.info, Node: Defining, Next: Environment, Prev: Override Directive, Up: Using Variables
4850
File: make.info, Node: Multi-Line, Next: Undefine Directive, Prev: Override Directive, Up: Using Variables
4596
4851
4597
6.8 Defining Variables Verbatim
4598
===============================
4852
6.8 Defining Multi-Line Variables
4853
=================================
4599
4854
4600
4855
Another way to set the value of a variable is to use the `define'
4601
4856
directive. This directive has an unusual syntax which allows newline
4602
characters to be included in the value, which is convenient for defining
4603
both canned sequences of commands (*note Defining Canned Command
4604
Sequences: Sequences.), and also sections of makefile syntax to use
4857
characters to be included in the value, which is convenient for
4858
defining both canned sequences of commands (*note Defining Canned
4859
Recipes: Canned Recipes.), and also sections of makefile syntax to use
4605
4860
with `eval' (*note Eval Function::).
4606
4861
4607
4862
The `define' directive is followed on the same line by the name of
4608
the variable and nothing more. The value to give the variable appears
4609
on the following lines. The end of the value is marked by a line
4610
containing just the word `endef'. Aside from this difference in
4611
syntax, `define' works just like `=': it creates a recursively-expanded
4612
variable (*note The Two Flavors of Variables: Flavors.). The variable
4613
name may contain function and variable references, which are expanded
4614
when the directive is read to find the actual variable name to use.
4863
the variable being defined and an (optional) assignment operator, and
4864
nothing more. The value to give the variable appears on the following
4865
lines. The end of the value is marked by a line containing just the
4866
word `endef'. Aside from this difference in syntax, `define' works
4867
just like any other variable definition. The variable name may contain
4868
function and variable references, which are expanded when the directive
4869
is read to find the actual variable name to use.
4870
4871
You may omit the variable assignment operator if you prefer. If
4872
omitted, `make' assumes it to be `=' and creates a recursively-expanded
4873
variable (*note The Two Flavors of Variables: Flavors.). When using a
4874
`+=' operator, the value is appended to the previous value as with any
4875
other append operation: with a single space separating the old and new
4876
values.
4615
4877
4616
4878
You may nest `define' directives: `make' will keep track of nested
4617
4879
directives and report an error if they are not all properly closed with
4618
`endef'. Note that lines beginning with tab characters are considered
4619
part of a command script, so any `define' or `endef' strings appearing
4620
on such a line will not be considered `make' operators.
4880
`endef'. Note that lines beginning with the recipe prefix character
4881
are considered part of a recipe, so any `define' or `endef' strings
4882
appearing on such a line will not be considered `make' directives.
4621
4883
4622
define two-lines
4884
define two-lines =
4623
4885
echo foo
4624
4886
echo $(bar)
4625
4887
endef
4629
4891
of the variable's value (except for the final newline which precedes
4630
4892
the `endef' and is not considered part of the value).
4631
4893
4632
When used in a command script, the previous example is functionally
4894
When used in a recipe, the previous example is functionally
4633
4895
equivalent to this:
4634
4896
4635
4897
two-lines = echo foo; echo $(bar)
4636
4898
4637
4899
since two commands separated by semicolon behave much like two separate
4638
4900
shell commands. However, note that using two separate lines means
4639
`make' will invoke the shell twice, running an independent subshell for
4640
each line. *Note Command Execution: Execution.
4901
`make' will invoke the shell twice, running an independent sub-shell
4902
for each line. *Note Recipe Execution: Execution.
4641
4903
4642
4904
If you want variable definitions made with `define' to take
4643
4905
precedence over command-line variable definitions, you can use the
4644
4906
`override' directive together with `define':
4645
4907
4646
override define two-lines
4908
override define two-lines =
4647
4909
foo
4648
4910
$(bar)
4649
4911
endef
4651
4913
*Note The `override' Directive: Override Directive.
4652
4914
4653
4915
4654
File: make.info, Node: Environment, Next: Target-specific, Prev: Defining, Up: Using Variables
4655
4656
6.9 Variables from the Environment
4657
==================================
4916
File: make.info, Node: Undefine Directive, Next: Environment, Prev: Multi-Line, Up: Using Variables
4917
4918
6.9 Undefining Variables
4919
========================
4920
4921
If you want to clear a variable, setting its value to empty is usually
4922
sufficient. Expanding such a variable will yield the same result (empty
4923
string) regardless of whether it was set or not. However, if you are
4924
using the `flavor' (*note Flavor Function::) and `origin' (*note Origin
4925
Function::) functions, there is a difference between a variable that
4926
was never set and a variable with an empty value. In such situations
4927
you may want to use the `undefine' directive to make a variable appear
4928
as if it was never set. For example:
4929
4930
foo := foo
4931
bar = bar
4932
4933
undefine foo
4934
undefine bar
4935
4936
$(info $(origin foo))
4937
$(info $(flavor bar))
4938
4939
This example will print "undefined" for both variables.
4940
4941
If you want to undefine a command-line variable definition, you can
4942
use the `override' directive together with `undefine', similar to how
4943
this is done for variable definitions:
4944
4945
override undefine CFLAGS
4946
4947
4948
File: make.info, Node: Environment, Next: Target-specific, Prev: Undefine Directive, Up: Using Variables
4949
4950
6.10 Variables from the Environment
4951
===================================
4658
4952
4659
4953
Variables in `make' can come from the environment in which `make' is
4660
4954
run. Every environment variable that `make' sees when it starts up is
4673
4967
`CFLAGS' explicitly and therefore are not affected by the value in the
4674
4968
environment.)
4675
4969
4676
When `make' runs a command script, variables defined in the makefile
4677
are placed into the environment of that command. This allows you to
4678
pass values to sub-`make' invocations (*note Recursive Use of `make':
4970
When `make' runs a recipe, variables defined in the makefile are
4971
placed into the environment of each shell. This allows you to pass
4972
values to sub-`make' invocations (*note Recursive Use of `make':
4679
4973
Recursion.). By default, only variables that came from the environment
4680
4974
or the command line are passed to recursive invocations. You can use
4681
4975
the `export' directive to pass other variables. *Note Communicating
4691
4985
which is normally present in the environment to specify the user's
4692
4986
choice of interactive shell. It would be very undesirable for this
4693
4987
choice to affect `make'; so, `make' handles the `SHELL' environment
4694
variable in a special way; see *Note Choosing the Shell::.
4988
variable in a special way; see *note Choosing the Shell::.
4695
4989
4696
4990
4697
4991
File: make.info, Node: Target-specific, Next: Pattern-specific, Prev: Environment, Up: Using Variables
4698
4992
4699
6.10 Target-specific Variable Values
4993
6.11 Target-specific Variable Values
4700
4994
====================================
4701
4995
4702
4996
Variable values in `make' are usually global; that is, they are the
4708
5002
feature allows you to define different values for the same variable,
4709
5003
based on the target that `make' is currently building. As with
4710
5004
automatic variables, these values are only available within the context
4711
of a target's command script (and in other target-specific assignments).
5005
of a target's recipe (and in other target-specific assignments).
4712
5006
4713
5007
Set a target-specific variable value like this:
4714
5008
4715
5009
TARGET ... : VARIABLE-ASSIGNMENT
4716
5010
4717
or like this:
4718
4719
TARGET ... : override VARIABLE-ASSIGNMENT
4720
4721
or like this:
4722
4723
TARGET ... : export VARIABLE-ASSIGNMENT
5011
Target-specific variable assignments can be prefixed with any or all
5012
of the special keywords `export', `override', or `private'; these apply
5013
their normal behavior to this instance of the variable only.
4724
5014
4725
5015
Multiple TARGET values create a target-specific variable value for
4726
5016
each member of the target list individually.
4727
5017
4728
5018
The VARIABLE-ASSIGNMENT can be any valid form of assignment;
4729
recursive (`='), static (`:='), appending (`+='), or conditional
4730
(`?='). All variables that appear within the VARIABLE-ASSIGNMENT are
4731
evaluated within the context of the target: thus, any
4732
previously-defined target-specific variable values will be in effect.
4733
Note that this variable is actually distinct from any "global" value:
4734
the two variables do not have to have the same flavor (recursive vs.
4735
static).
5019
recursive (`='), simple (`:=' or `::='), appending (`+='), or
5020
conditional (`?='). All variables that appear within the
5021
VARIABLE-ASSIGNMENT are evaluated within the context of the target:
5022
thus, any previously-defined target-specific variable values will be in
5023
effect. Note that this variable is actually distinct from any "global"
5024
value: the two variables do not have to have the same flavor (recursive
5025
vs. simple).
4736
5026
4737
5027
Target-specific variables have the same priority as any other
4738
makefile variable. Variables provided on the command-line (and in the
5028
makefile variable. Variables provided on the command line (and in the
4739
5029
environment if the `-e' option is in force) will take precedence.
4740
5030
Specifying the `override' directive will allow the target-specific
4741
5031
variable value to be preferred.
4750
5040
prog : CFLAGS = -g
4751
5041
prog : prog.o foo.o bar.o
4752
5042
4753
will set `CFLAGS' to `-g' in the command script for `prog', but it will
4754
also set `CFLAGS' to `-g' in the command scripts that create `prog.o',
4755
`foo.o', and `bar.o', and any command scripts which create their
4756
prerequisites.
5043
will set `CFLAGS' to `-g' in the recipe for `prog', but it will also
5044
set `CFLAGS' to `-g' in the recipes that create `prog.o', `foo.o', and
5045
`bar.o', and any recipes which create their prerequisites.
4757
5046
4758
5047
Be aware that a given prerequisite will only be built once per
4759
5048
invocation of make, at most. If the same file is a prerequisite of
4764
5053
ignore the target-specific values from any other targets.
4765
5054
4766
5055
4767
File: make.info, Node: Pattern-specific, Prev: Target-specific, Up: Using Variables
5056
File: make.info, Node: Pattern-specific, Next: Suppressing Inheritance, Prev: Target-specific, Up: Using Variables
4768
5057
4769
6.11 Pattern-specific Variable Values
5058
6.12 Pattern-specific Variable Values
4770
5059
=====================================
4771
5060
4772
5061
In addition to target-specific variable values (*note Target-specific
4773
5062
Variable Values: Target-specific.), GNU `make' supports
4774
5063
pattern-specific variable values. In this form, the variable is
4775
defined for any target that matches the pattern specified. If a target
4776
matches more than one pattern, all the matching pattern-specific
4777
variables are interpreted in the order in which they were defined in
4778
the makefile, and collected together into one set. Variables defined
4779
in this way are searched after any target-specific variables defined
4780
explicitly for that target, and before target-specific variables
4781
defined for the parent target.
5064
defined for any target that matches the pattern specified.
4782
5065
4783
5066
Set a pattern-specific variable value like this:
4784
5067
4785
5068
PATTERN ... : VARIABLE-ASSIGNMENT
4786
4787
or like this:
4788
4789
PATTERN ... : override VARIABLE-ASSIGNMENT
4790
4791
where PATTERN is a %-pattern. As with target-specific variable values,
4792
multiple PATTERN values create a pattern-specific variable value for
4793
each pattern individually. The VARIABLE-ASSIGNMENT can be any valid
4794
form of assignment. Any command-line variable setting will take
4795
precedence, unless `override' is specified.
5069
where PATTERN is a %-pattern. As with target-specific variable
5070
values, multiple PATTERN values create a pattern-specific variable
5071
value for each pattern individually. The VARIABLE-ASSIGNMENT can be
5072
any valid form of assignment. Any command line variable setting will
5073
take precedence, unless `override' is specified.
4796
5074
4797
5075
For example:
4798
5076
4801
5079
will assign `CFLAGS' the value of `-O' for all targets matching the
4802
5080
pattern `%.o'.
4803
5081
5082
If a target matches more than one pattern, the matching
5083
pattern-specific variables with longer stems are interpreted first.
5084
This results in more specific variables taking precedence over the more
5085
generic ones, for example:
5086
5087
%.o: %.c
5088
$(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
5089
5090
lib/%.o: CFLAGS := -fPIC -g
5091
%.o: CFLAGS := -g
5092
5093
all: foo.o lib/bar.o
5094
5095
In this example the first definition of the `CFLAGS' variable will
5096
be used to update `lib/bar.o' even though the second one also applies
5097
to this target. Pattern-specific variables which result in the same
5098
stem length are considered in the order in which they were defined in
5099
the makefile.
5100
5101
Pattern-specific variables are searched after any target-specific
5102
variables defined explicitly for that target, and before target-specific
5103
variables defined for the parent target.
5104
5105
5106
File: make.info, Node: Suppressing Inheritance, Next: Special Variables, Prev: Pattern-specific, Up: Using Variables
5107
5108
6.13 Suppressing Inheritance
5109
============================
5110
5111
As described in previous sections, `make' variables are inherited by
5112
prerequisites. This capability allows you to modify the behavior of a
5113
prerequisite based on which targets caused it to be rebuilt. For
5114
example, you might set a target-specific variable on a `debug' target,
5115
then running `make debug' will cause that variable to be inherited by
5116
all prerequisites of `debug', while just running `make all' (for
5117
example) would not have that assignment.
5118
5119
Sometimes, however, you may not want a variable to be inherited. For
5120
these situations, `make' provides the `private' modifier. Although
5121
this modifier can be used with any variable assignment, it makes the
5122
most sense with target- and pattern-specific variables. Any variable
5123
marked `private' will be visible to its local target but will not be
5124
inherited by prerequisites of that target. A global variable marked
5125
`private' will be visible in the global scope but will not be inherited
5126
by any target, and hence will not be visible in any recipe.
5127
5128
As an example, consider this makefile:
5129
EXTRA_CFLAGS =
5130
5131
prog: private EXTRA_CFLAGS = -L/usr/local/lib
5132
prog: a.o b.o
5133
5134
Due to the `private' modifier, `a.o' and `b.o' will not inherit the
5135
`EXTRA_CFLAGS' variable assignment from the `prog' target.
5136
5137
5138
File: make.info, Node: Special Variables, Prev: Suppressing Inheritance, Up: Using Variables
5139
5140
6.14 Other Special Variables
5141
============================
5142
5143
GNU `make' supports some variables that have special properties.
5144
5145
`MAKEFILE_LIST'
5146
Contains the name of each makefile that is parsed by `make', in
5147
the order in which it was parsed. The name is appended just
5148
before `make' begins to parse the makefile. Thus, if the first
5149
thing a makefile does is examine the last word in this variable, it
5150
will be the name of the current makefile. Once the current
5151
makefile has used `include', however, the last word will be the
5152
just-included makefile.
5153
5154
If a makefile named `Makefile' has this content:
5155
5156
name1 := $(lastword $(MAKEFILE_LIST))
5157
5158
include inc.mk
5159
5160
name2 := $(lastword $(MAKEFILE_LIST))
5161
5162
all:
5163
@echo name1 = $(name1)
5164
@echo name2 = $(name2)
5165
5166
then you would expect to see this output:
5167
5168
name1 = Makefile
5169
name2 = inc.mk
5170
5171
`.DEFAULT_GOAL'
5172
Sets the default goal to be used if no targets were specified on
5173
the command line (*note Arguments to Specify the Goals: Goals.).
5174
The `.DEFAULT_GOAL' variable allows you to discover the current
5175
default goal, restart the default goal selection algorithm by
5176
clearing its value, or to explicitly set the default goal. The
5177
following example illustrates these cases:
5178
5179
# Query the default goal.
5180
ifeq ($(.DEFAULT_GOAL),)
5181
$(warning no default goal is set)
5182
endif
5183
5184
.PHONY: foo
5185
foo: ; @echo $@
5186
5187
$(warning default goal is $(.DEFAULT_GOAL))
5188
5189
# Reset the default goal.
5190
.DEFAULT_GOAL :=
5191
5192
.PHONY: bar
5193
bar: ; @echo $@
5194
5195
$(warning default goal is $(.DEFAULT_GOAL))
5196
5197
# Set our own.
5198
.DEFAULT_GOAL := foo
5199
5200
This makefile prints:
5201
5202
no default goal is set
5203
default goal is foo
5204
default goal is bar
5205
foo
5206
5207
Note that assigning more than one target name to `.DEFAULT_GOAL' is
5208
invalid and will result in an error.
5209
5210
`MAKE_RESTARTS'
5211
This variable is set only if this instance of `make' has restarted
5212
(*note How Makefiles Are Remade: Remaking Makefiles.): it will
5213
contain the number of times this instance has restarted. Note
5214
this is not the same as recursion (counted by the `MAKELEVEL'
5215
variable). You should not set, modify, or export this variable.
5216
5217
`.RECIPEPREFIX'
5218
The first character of the value of this variable is used as the
5219
character make assumes is introducing a recipe line. If the
5220
variable is empty (as it is by default) that character is the
5221
standard tab character. For example, this is a valid makefile:
5222
5223
.RECIPEPREFIX = >
5224
all:
5225
> @echo Hello, world
5226
5227
The value of `.RECIPEPREFIX' can be changed multiple times; once
5228
set it stays in effect for all rules parsed until it is modified.
5229
5230
`.VARIABLES'
5231
Expands to a list of the _names_ of all global variables defined
5232
so far. This includes variables which have empty values, as well
5233
as built-in variables (*note Variables Used by Implicit Rules:
5234
Implicit Variables.), but does not include any variables which are
5235
only defined in a target-specific context. Note that any value
5236
you assign to this variable will be ignored; it will always return
5237
its special value.
5238
5239
`.FEATURES'
5240
Expands to a list of special features supported by this version of
5241
`make'. Possible values include, but are not limited to:
5242
5243
`archives'
5244
Supports `ar' (archive) files using special file name syntax.
5245
*Note Using `make' to Update Archive Files: Archives.
5246
5247
`check-symlink'
5248
Supports the `-L' (`--check-symlink-times') flag. *Note
5249
Summary of Options: Options Summary.
5250
5251
`else-if'
5252
Supports "else if" non-nested conditionals. *Note Syntax of
5253
Conditionals: Conditional Syntax.
5254
5255
`jobserver'
5256
Supports "job server" enhanced parallel builds. *Note
5257
Parallel Execution: Parallel.
5258
5259
`oneshell'
5260
Supports the `.ONESHELL' special target. *Note Using One
5261
Shell: One Shell.
5262
5263
`order-only'
5264
Supports order-only prerequisites. *Note Types of
5265
Prerequisites: Prerequisite Types.
5266
5267
`second-expansion'
5268
Supports secondary expansion of prerequisite lists.
5269
5270
`shortest-stem'
5271
Uses the "shortest stem" method of choosing which pattern, of
5272
multiple applicable options, will be used. *Note How
5273
Patterns Match: Pattern Match.
5274
5275
`target-specific'
5276
Supports target-specific and pattern-specific variable
5277
assignments. *Note Target-specific Variable Values:
5278
Target-specific.
5279
5280
`undefine'
5281
Supports the `undefine' directive. *Note Undefine
5282
Directive::.
5283
5284
`guile'
5285
Has GNU Guile available as an embedded extension language.
5286
*Note GNU Guile Integration: Guile Integration.
5287
5288
`load'
5289
Supports dynamically loadable objects for creating custom
5290
extensions. *Note Loading Dynamic Objects: Loading Objects.
5291
5292
`.INCLUDE_DIRS'
5293
Expands to a list of directories that `make' searches for included
5294
makefiles (*note Including Other Makefiles: Include.).
5295
5296
4804
5297
4805
5298
File: make.info, Node: Conditionals, Next: Functions, Prev: Using Variables, Up: Top
4806
5299
4807
5300
7 Conditional Parts of Makefiles
4808
5301
********************************
4809
5302
4810
A "conditional" causes part of a makefile to be obeyed or ignored
4811
depending on the values of variables. Conditionals can compare the
4812
value of one variable to another, or the value of a variable to a
5303
A "conditional" directive causes part of a makefile to be obeyed or
5304
ignored depending on the values of variables. Conditionals can compare
5305
the value of one variable to another, or the value of a variable to a
4813
5306
constant string. Conditionals control what `make' actually "sees" in
4814
the makefile, so they _cannot_ be used to control shell commands at the
4815
time of execution.
5307
the makefile, so they _cannot_ be used to control recipes at the time
5308
of execution.
4816
5309
4817
5310
* Menu:
4818
5311
4828
5321
4829
5322
The following example of a conditional tells `make' to use one set of
4830
5323
libraries if the `CC' variable is `gcc', and a different set of
4831
libraries otherwise. It works by controlling which of two command
4832
lines will be used as the command for a rule. The result is that
4833
`CC=gcc' as an argument to `make' changes not only which compiler is
4834
used but also which libraries are linked.
5324
libraries otherwise. It works by controlling which of two recipe lines
5325
will be used for the rule. The result is that `CC=gcc' as an argument
5326
to `make' changes not only which compiler is used but also which
5327
libraries are linked.
4835
5328
4836
5329
libs_for_gcc = -lgnu
4837
5330
normal_libs =
4921
5414
4922
5415
or:
4923
5416
4924
CONDITIONAL-DIRECTIVE
5417
CONDITIONAL-DIRECTIVE-ONE
4925
5418
TEXT-IF-ONE-IS-TRUE
4926
else CONDITIONAL-DIRECTIVE
4927
TEXT-IF-TRUE
5419
else CONDITIONAL-DIRECTIVE-TWO
5420
TEXT-IF-TWO-IS-TRUE
4928
5421
else
4929
TEXT-IF-FALSE
5422
TEXT-IF-ONE-AND-TWO-ARE-FALSE
4930
5423
endif
4931
5424
4932
5425
There can be as many "`else' CONDITIONAL-DIRECTIVE" clauses as
5026
5519
5027
5520
Extra spaces are allowed and ignored at the beginning of the
5028
5521
conditional directive line, but a tab is not allowed. (If the line
5029
begins with a tab, it will be considered a command for a rule.) Aside
5030
from this, extra spaces or tabs may be inserted with no effect anywhere
5031
except within the directive name or within an argument. A comment
5032
starting with `#' may appear at the end of the line.
5522
begins with a tab, it will be considered part of a recipe for a rule.)
5523
Aside from this, extra spaces or tabs may be inserted with no effect
5524
anywhere except within the directive name or within an argument. A
5525
comment starting with `#' may appear at the end of the line.
5033
5526
5034
5527
The other two directives that play a part in a conditional are `else'
5035
5528
and `endif'. Each of these directives is written as one word, with no
5046
5539
5047
5540
`make' evaluates conditionals when it reads a makefile.
5048
5541
Consequently, you cannot use automatic variables in the tests of
5049
conditionals because they are not defined until commands are run (*note
5542
conditionals because they are not defined until recipes are run (*note
5050
5543
Automatic Variables::).
5051
5544
5052
5545
To prevent intolerable confusion, it is not permitted to start a
5081
5574
ranlib archive.a
5082
5575
endif
5083
5576
5084
The `+' prefix marks those command lines as "recursive" so that they
5577
The `+' prefix marks those recipe lines as "recursive" so that they
5085
5578
will be executed despite use of the `-t' flag. *Note Recursive Use of
5086
5579
`make': Recursion.
5087
5580
5092
5585
*********************************
5093
5586
5094
5587
"Functions" allow you to do text processing in the makefile to compute
5095
the files to operate on or the commands to use. You use a function in a
5096
"function call", where you give the name of the function and some text
5097
(the "arguments") for the function to operate on. The result of the
5098
function's processing is substituted into the makefile at the point of
5099
the call, just as a variable might be substituted.
5588
the files to operate on or the commands to use in recipes. You use a
5589
function in a "function call", where you give the name of the function
5590
and some text (the "arguments") for the function to operate on. The
5591
result of the function's processing is substituted into the makefile at
5592
the point of the call, just as a variable might be substituted.
5100
5593
5101
5594
* Menu:
5102
5595
5105
5598
* File Name Functions:: Functions for manipulating file names.
5106
5599
* Conditional Functions:: Functions that implement conditions.
5107
5600
* Foreach Function:: Repeat some text with controlled variation.
5601
* File Function:: Write text to a file.
5108
5602
* Call Function:: Expand a user-defined function.
5109
5603
* Value Function:: Return the un-expanded value of a variable.
5110
5604
* Eval Function:: Evaluate the arguments as makefile syntax.
5111
5605
* Origin Function:: Find where a variable got its value.
5112
5606
* Flavor Function:: Find out the flavor of a variable.
5607
* Make Control Functions:: Functions that control how make runs.
5113
5608
* Shell Function:: Substitute the output of a shell command.
5114
* Make Control Functions:: Functions that control how make runs.
5609
* Guile Function:: Use GNU Guile embedded scripting language.
5115
5610
5116
5611
5117
5612
File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Functions, Up: Functions
5119
5614
8.1 Function Call Syntax
5120
5615
========================
5121
5616
5122
A function call resembles a variable reference. It looks like this:
5617
A function call resembles a variable reference. It can appear anywhere
5618
a variable reference can appear, and it is expanded using the same
5619
rules as variable references. A function call looks like this:
5123
5620
5124
5621
$(FUNCTION ARGUMENTS)
5125
5622
5129
5626
5130
5627
Here FUNCTION is a function name; one of a short list of names that
5131
5628
are part of `make'. You can also essentially create your own functions
5132
by using the `call' builtin function.
5629
by using the `call' built-in function.
5133
5630
5134
5631
The ARGUMENTS are the arguments of the function. They are separated
5135
5632
from the function name by one or more spaces or tabs, and if there is
5583
6080
5584
6081
5585
6082
5586
File: make.info, Node: Foreach Function, Next: Call Function, Prev: Conditional Functions, Up: Functions
6083
File: make.info, Node: Foreach Function, Next: File Function, Prev: Conditional Functions, Up: Functions
5587
6084
5588
6085
8.5 The `foreach' Function
5589
6086
==========================
5634
6131
5635
6132
Here we use the variable `find_files' this way. We use plain `=' to
5636
6133
define a recursively-expanding variable, so that its value contains an
5637
actual function call to be reexpanded under the control of `foreach'; a
5638
simply-expanded variable would not do, since `wildcard' would be called
5639
only once at the time of defining `find_files'.
6134
actual function call to be re-expanded under the control of `foreach';
6135
a simply-expanded variable would not do, since `wildcard' would be
6136
called only once at the time of defining `find_files'.
5640
6137
5641
6138
The `foreach' function has no permanent effect on the variable VAR;
5642
6139
its value and flavor after the `foreach' function call are the same as
5651
6148
result in variable names because many strange things are valid variable
5652
6149
names, but are probably not what you intended. For example,
5653
6150
5654
files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
6151
files := $(foreach Esta-escrito-en-espanol!,b c ch,$(find_files))
5655
6152
5656
6153
might be useful if the value of `find_files' references the variable
5657
whose name is `Esta escrito en espanol!' (es un nombre bastante largo,
6154
whose name is `Esta-escrito-en-espanol!' (es un nombre bastante largo,
5658
6155
no?), but it is more likely to be a mistake.
5659
6156
5660
6157
5661
File: make.info, Node: Call Function, Next: Value Function, Prev: Foreach Function, Up: Functions
5662
5663
8.6 The `call' Function
6158
File: make.info, Node: File Function, Next: Call Function, Prev: Foreach Function, Up: Functions
6159
6160
8.6 The `file' Function
6161
=======================
6162
6163
The `file' function allows the makefile to write to a file. Two modes
6164
of writing are supported: overwrite, where the text is written to the
6165
beginning of the file and any existing content is lost, and append,
6166
where the text is written to the end of the file, preserving the
6167
existing content. In all cases the file is created if it does not
6168
exist.
6169
6170
The syntax of the `file' function is:
6171
6172
$(file OP FILENAME,TEXT)
6173
6174
The operator OP can be either `>' which indicates overwrite mode, or
6175
`>>' which indicates append mode. The FILENAME indicates the file to
6176
be written to. There may optionally be whitespace between the operator
6177
and the file name.
6178
6179
When the `file' function is expanded all its arguments are expanded
6180
first, then the file indicated by FILENAME will be opened in the mode
6181
described by OP. Finally TEXT will be written to the file. If TEXT
6182
does not already end in a newline, a final newline will be written.
6183
The result of evaluating the `file' function is always the empty string.
6184
6185
It is a fatal error if the file cannot be opened for writing, or if
6186
the write operation fails.
6187
6188
For example, the `file' function can be useful if your build system
6189
has a limited command line size and your recipe runs a command that can
6190
accept arguments from a file as well. Many commands use the convention
6191
that an argument prefixed with an `@' specifies a file containing more
6192
arguments. Then you might write your recipe in this way:
6193
6194
program: $(OBJECTS)
6195
$(file >$@.in,$^)
6196
$(CMD) $(CMDFLAGS) @$@.in
6197
@rm $@.in
6198
6199
If the command required each argument to be on a separate line of the
6200
input file, you might write your recipe like this:
6201
6202
program: $(OBJECTS)
6203
$(file >$@.in,) $(foreach O,$^,$(file >>$@.in,$O))
6204
$(CMD) $(CMDFLAGS) @$@.in
6205
@rm $@.in
6206
6207
6208
File: make.info, Node: Call Function, Next: Value Function, Prev: File Function, Up: Functions
6209
6210
8.7 The `call' Function
5664
6211
=======================
5665
6212
5666
6213
The `call' function is unique in that it can be used to create new
5687
6234
parentheses when writing it. (You can, however, use a variable
5688
6235
reference in the name if you want the name not to be a constant.)
5689
6236
5690
If VARIABLE is the name of a builtin function, the builtin function
6237
If VARIABLE is the name of a built-in function, the built-in function
5691
6238
is always invoked (even if a `make' variable by that name also exists).
5692
6239
5693
6240
The `call' function expands the PARAM arguments before assigning
5694
6241
them to temporary variables. This means that VARIABLE values
5695
containing references to builtin functions that have special expansion
6242
containing references to built-in functions that have special expansion
5696
6243
rules, like `foreach' or `if', may not work as you expect.
5697
6244
5698
6245
Some examples may make this clearer.
5737
6284
5738
6285
File: make.info, Node: Value Function, Next: Eval Function, Prev: Call Function, Up: Functions
5739
6286
5740
8.7 The `value' Function
6287
8.8 The `value' Function
5741
6288
========================
5742
6289
5743
6290
The `value' function provides a way for you to use the value of a
5751
6298
5752
6299
$(value VARIABLE)
5753
6300
5754
Note that VARIABLE is the _name_ of a variable; not a _reference_ to
6301
Note that VARIABLE is the _name_ of a variable, not a _reference_ to
5755
6302
that variable. Therefore you would not normally use a `$' or
5756
6303
parentheses when writing it. (You can, however, use a variable
5757
6304
reference in the name if you want the name not to be a constant.)
5777
6324
5778
6325
File: make.info, Node: Eval Function, Next: Origin Function, Prev: Value Function, Up: Functions
5779
6326
5780
8.8 The `eval' Function
6327
8.9 The `eval' Function
5781
6328
=======================
5782
6329
5783
6330
The `eval' function is very special: it allows you to define new
5821
6368
.PHONY: all
5822
6369
all: $(PROGRAMS)
5823
6370
5824
define PROGRAM_template
6371
define PROGRAM_template =
5825
6372
$(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
5826
6373
ALL_OBJS += $$($(1)_OBJS)
5827
6374
endef
5837
6384
5838
6385
File: make.info, Node: Origin Function, Next: Flavor Function, Prev: Eval Function, Up: Functions
5839
6386
5840
8.9 The `origin' Function
5841
=========================
6387
8.10 The `origin' Function
6388
==========================
5842
6389
5843
6390
The `origin' function is unlike most other functions in that it does
5844
6391
not operate on the values of variables; it tells you something _about_
5848
6395
5849
6396
$(origin VARIABLE)
5850
6397
5851
Note that VARIABLE is the _name_ of a variable to inquire about; not
6398
Note that VARIABLE is the _name_ of a variable to inquire about, not
5852
6399
a _reference_ to that variable. Therefore you would not normally use a
5853
6400
`$' or parentheses when writing it. (You can, however, use a variable
5854
6401
reference in the name if you want the name not to be a constant.)
5866
6413
function will return the origin of the later definition.
5867
6414
5868
6415
`environment'
5869
if VARIABLE was defined as an environment variable and the `-e'
5870
option is _not_ turned on (*note Summary of Options: Options
6416
if VARIABLE was inherited from the environment provided to `make'.
6417
6418
`environment override'
6419
if VARIABLE was inherited from the environment provided to `make',
6420
and is overriding a setting for VARIABLE in the makefile as a
6421
result of the `-e' option (*note Summary of Options: Options
5871
6422
Summary.).
5872
6423
5873
`environment override'
5874
if VARIABLE was defined as an environment variable and the `-e'
5875
option _is_ turned on (*note Summary of Options: Options Summary.).
5876
5877
6424
`file'
5878
6425
if VARIABLE was defined in a makefile.
5879
6426
5886
6433
5887
6434
`automatic'
5888
6435
if VARIABLE is an automatic variable defined for the execution of
5889
the commands for each rule (*note Automatic Variables::).
6436
the recipe for each rule (*note Automatic Variables::).
5890
6437
5891
6438
This information is primarily useful (other than for your curiosity)
5892
6439
to determine if you want to believe the value of a variable. For
5921
6468
String Substitution and Analysis: Text Functions.
5922
6469
5923
6470
5924
File: make.info, Node: Flavor Function, Next: Shell Function, Prev: Origin Function, Up: Functions
6471
File: make.info, Node: Flavor Function, Next: Make Control Functions, Prev: Origin Function, Up: Functions
5925
6472
5926
8.10 The `flavor' Function
6473
8.11 The `flavor' Function
5927
6474
==========================
5928
6475
5929
The `flavor' function is unlike most other functions (and like `origin'
5930
function) in that it does not operate on the values of variables; it
5931
tells you something _about_ a variable. Specifically, it tells you the
5932
flavor of a variable (*note The Two Flavors of Variables: Flavors.).
6476
The `flavor' function, like the `origin' function, does not operate on
6477
the values of variables but rather it tells you something _about_ a
6478
variable. Specifically, it tells you the flavor of a variable (*note
6479
The Two Flavors of Variables: Flavors.).
5933
6480
5934
6481
The syntax of the `flavor' function is:
5935
6482
5936
6483
$(flavor VARIABLE)
5937
6484
5938
Note that VARIABLE is the _name_ of a variable to inquire about; not
6485
Note that VARIABLE is the _name_ of a variable to inquire about, not
5939
6486
a _reference_ to that variable. Therefore you would not normally use a
5940
6487
`$' or parentheses when writing it. (You can, however, use a variable
5941
6488
reference in the name if you want the name not to be a constant.)
5954
6501
5955
6502
5956
6503
5957
File: make.info, Node: Shell Function, Next: Make Control Functions, Prev: Flavor Function, Up: Functions
5958
5959
8.11 The `shell' Function
5960
=========================
5961
5962
The `shell' function is unlike any other function other than the
5963
`wildcard' function (*note The Function `wildcard': Wildcard Function.)
5964
in that it communicates with the world outside of `make'.
5965
5966
The `shell' function performs the same function that backquotes
5967
(``') perform in most shells: it does "command expansion". This means
5968
that it takes as an argument a shell command and evaluates to the
5969
output of the command. The only processing `make' does on the result
5970
is to convert each newline (or carriage-return / newline pair) to a
5971
single space. If there is a trailing (carriage-return and) newline it
5972
will simply be removed.
5973
5974
The commands run by calls to the `shell' function are run when the
5975
function calls are expanded (*note How `make' Reads a Makefile: Reading
5976
Makefiles.). Because this function involves spawning a new shell, you
5977
should carefully consider the performance implications of using the
5978
`shell' function within recursively expanded variables vs. simply
5979
expanded variables (*note The Two Flavors of Variables: Flavors.).
5980
5981
Here are some examples of the use of the `shell' function:
5982
5983
contents := $(shell cat foo)
5984
5985
sets `contents' to the contents of the file `foo', with a space (rather
5986
than a newline) separating each line.
5987
5988
files := $(shell echo *.c)
5989
5990
sets `files' to the expansion of `*.c'. Unless `make' is using a very
5991
strange shell, this has the same result as `$(wildcard *.c)' (as long
5992
as at least one `.c' file exists).
5993
5994
5995
File: make.info, Node: Make Control Functions, Prev: Shell Function, Up: Functions
6504
File: make.info, Node: Make Control Functions, Next: Shell Function, Prev: Flavor Function, Up: Functions
5996
6505
5997
6506
8.12 Functions That Control Make
5998
6507
================================
6004
6513
`$(error TEXT...)'
6005
6514
Generates a fatal error where the message is TEXT. Note that the
6006
6515
error is generated whenever this function is evaluated. So, if
6007
you put it inside a command script or on the right side of a
6008
recursive variable assignment, it won't be evaluated until later.
6009
The TEXT will be expanded before the error is generated.
6516
you put it inside a recipe or on the right side of a recursive
6517
variable assignment, it won't be evaluated until later. The TEXT
6518
will be expanded before the error is generated.
6010
6519
6011
6520
For example,
6012
6521
6040
6549
empty string.
6041
6550
6042
6551
6552
File: make.info, Node: Shell Function, Next: Guile Function, Prev: Make Control Functions, Up: Functions
6553
6554
8.13 The `shell' Function
6555
=========================
6556
6557
The `shell' function is unlike any other function other than the
6558
`wildcard' function (*note The Function `wildcard': Wildcard Function.)
6559
in that it communicates with the world outside of `make'.
6560
6561
The `shell' function performs the same function that backquotes
6562
(``') perform in most shells: it does "command expansion". This means
6563
that it takes as an argument a shell command and evaluates to the
6564
output of the command. The only processing `make' does on the result
6565
is to convert each newline (or carriage-return / newline pair) to a
6566
single space. If there is a trailing (carriage-return and) newline it
6567
will simply be removed.
6568
6569
The commands run by calls to the `shell' function are run when the
6570
function calls are expanded (*note How `make' Reads a Makefile: Reading
6571
Makefiles.). Because this function involves spawning a new shell, you
6572
should carefully consider the performance implications of using the
6573
`shell' function within recursively expanded variables vs. simply
6574
expanded variables (*note The Two Flavors of Variables: Flavors.).
6575
6576
Here are some examples of the use of the `shell' function:
6577
6578
contents := $(shell cat foo)
6579
6580
sets `contents' to the contents of the file `foo', with a space (rather
6581
than a newline) separating each line.
6582
6583
files := $(shell echo *.c)
6584
6585
sets `files' to the expansion of `*.c'. Unless `make' is using a very
6586
strange shell, this has the same result as `$(wildcard *.c)' (as long
6587
as at least one `.c' file exists).
6588
6589
6590
File: make.info, Node: Guile Function, Prev: Shell Function, Up: Functions
6591
6592
8.14 The `guile' Function
6593
=========================
6594
6595
If GNU `make' is built with support for GNU Guile as an embedded
6596
extension language then the `guile' function will be available. The
6597
`guile' function takes one argument which is first expanded by `make'
6598
in the normal fashion, then passed to the GNU Guile evaluator. The
6599
result of the evaluator is converted into a string and used as the
6600
expansion of the `guile' function in the makefile. See *note GNU Guile
6601
Integration: Guile Integration. for details on writing extensions to
6602
`make' in Guile.
6603
6604
You can determine whether GNU Guile support is available by checking
6605
the `.FEATURES' variable for the word GUILE.
6606
6607
6043
6608
File: make.info, Node: Running, Next: Implicit Rules, Prev: Functions, Up: Top
6044
6609
6045
6610
9 How to Run `make'
6068
6633
`1'
6069
6634
The exit status is one if you use the `-q' flag and `make'
6070
6635
determines that some target is not already up to date. *Note
6071
Instead of Executing the Commands: Instead of Execution.
6636
Instead of Executing Recipes: Instead of Execution.
6072
6637
6073
6638
* Menu:
6074
6639
6076
6641
* Goals:: How to use goal arguments to specify which
6077
6642
parts of the makefile to use.
6078
6643
* Instead of Execution:: How to use mode flags to specify what
6079
kind of thing to do with the commands
6644
kind of thing to do with the recipes
6080
6645
in the makefile other than simply
6081
6646
execute them.
6082
6647
* Avoiding Compilation:: How to avoid recompiling certain files.
6123
6688
default goal from within your makefile using the `.DEFAULT_GOAL'
6124
6689
variable (*note Other Special Variables: Special Variables.).
6125
6690
6126
You can also specify a different goal or goals with command-line
6691
You can also specify a different goal or goals with command line
6127
6692
arguments to `make'. Use the name of the goal as an argument. If you
6128
6693
specify several goals, `make' processes each of them in turn, in the
6129
6694
order you name them.
6166
6731
which has a rule in the makefile but is not a prerequisite of the
6167
6732
default goal.
6168
6733
6169
Another use of specifying a goal is to run the commands associated
6170
with a phony target (*note Phony Targets::) or empty target (*note
6171
Empty Target Files to Record Events: Empty Targets.). Many makefiles
6172
contain a phony target named `clean' which deletes everything except
6173
source files. Naturally, this is done only if you request it
6174
explicitly with `make clean'. Following is a list of typical phony and
6175
empty target names. *Note Standard Targets::, for a detailed list of
6176
all the standard target names which GNU software packages use.
6734
Another use of specifying a goal is to run the recipe associated with
6735
a phony target (*note Phony Targets::) or empty target (*note Empty
6736
Target Files to Record Events: Empty Targets.). Many makefiles contain
6737
a phony target named `clean' which deletes everything except source
6738
files. Naturally, this is done only if you request it explicitly with
6739
`make clean'. Following is a list of typical phony and empty target
6740
names. *Note Standard Targets::, for a detailed list of all the
6741
standard target names which GNU software packages use.
6177
6742
6178
6743
`all'
6179
6744
Make all the top-level targets the makefile knows about.
6224
6789
6225
6790
File: make.info, Node: Instead of Execution, Next: Avoiding Compilation, Prev: Goals, Up: Running
6226
6791
6227
9.3 Instead of Executing the Commands
6228
=====================================
6792
9.3 Instead of Executing Recipes
6793
================================
6229
6794
6230
6795
The makefile tells `make' how to tell whether a target is up to date,
6231
6796
and how to update each target. But updating the targets is not always
6235
6800
`--just-print'
6236
6801
`--dry-run'
6237
6802
`--recon'
6238
"No-op". The activity is to print what commands would be used to
6239
make the targets up to date, but not actually execute them.
6803
"No-op". Causes `make' to print the recipes that are needed to
6804
make the targets up to date, but not actually execute them. Note
6805
that some recipes are still executed, even with this flag (*note
6806
How the `MAKE' Variable Works: MAKE Variable.). Also any recipes
6807
needed to update included makefiles are still executed (*note How
6808
Makefiles Are Remade: Remaking Makefiles.).
6240
6809
6241
6810
`-t'
6242
6811
`--touch'
6243
"Touch". The activity is to mark the targets as up to date without
6244
actually changing them. In other words, `make' pretends to compile
6245
the targets but does not really change their contents.
6812
"Touch". Marks targets as up to date without actually changing
6813
them. In other words, `make' pretends to update the targets but
6814
does not really change their contents; instead only their modified
6815
times are updated.
6246
6816
6247
6817
`-q'
6248
6818
`--question'
6249
"Question". The activity is to find out silently whether the
6250
targets are up to date already; but execute no commands in either
6251
case. In other words, neither compilation nor output will occur.
6819
"Question". Silently check whether the targets are up to date, but
6820
do not execute recipes; the exit code shows whether any updates are
6821
needed.
6252
6822
6253
6823
`-W FILE'
6254
6824
`--what-if=FILE'
6260
6830
same. You can use the `-W' flag in conjunction with the `-n' flag
6261
6831
to see what would happen if you were to modify specific files.
6262
6832
6263
With the `-n' flag, `make' prints the commands that it would
6264
normally execute but does not execute them.
6833
With the `-n' flag, `make' prints the recipe that it would normally
6834
execute but usually does not execute it.
6265
6835
6266
With the `-t' flag, `make' ignores the commands in the rules and
6267
uses (in effect) the command `touch' for each target that needs to be
6836
With the `-t' flag, `make' ignores the recipes in the rules and uses
6837
(in effect) the command `touch' for each target that needs to be
6268
6838
remade. The `touch' command is also printed, unless `-s' or `.SILENT'
6269
6839
is used. For speed, `make' does not actually invoke the program
6270
6840
`touch'. It does the work directly.
6271
6841
6272
With the `-q' flag, `make' prints nothing and executes no commands,
6842
With the `-q' flag, `make' prints nothing and executes no recipes,
6273
6843
but the exit status code it returns is zero if and only if the targets
6274
6844
to be considered are already up to date. If the exit status is one,
6275
6845
then some updating needs to be done. If `make' encounters an error,
6279
6849
It is an error to use more than one of these three flags in the same
6280
6850
invocation of `make'.
6281
6851
6282
The `-n', `-t', and `-q' options do not affect command lines that
6852
The `-n', `-t', and `-q' options do not affect recipe lines that
6283
6853
begin with `+' characters or contain the strings `$(MAKE)' or
6284
6854
`${MAKE}'. Note that only the line containing the `+' character or the
6285
6855
strings `$(MAKE)' or `${MAKE}' is run regardless of these options.
6287
6857
or contain `$(MAKE)' or `${MAKE}' (*Note How the `MAKE' Variable Works:
6288
6858
MAKE Variable.)
6289
6859
6860
The `-t' flag prevents phony targets (*note Phony Targets::) from
6861
being updated, unless there are recipe lines beginning with `+' or
6862
containing `$(MAKE)' or `${MAKE}'.
6863
6290
6864
The `-W' flag provides two features:
6291
6865
6292
6866
* If you also use the `-n' or `-q' flag, you can see what `make'
6293
6867
would do if you were to modify some files.
6294
6868
6295
6869
* Without the `-n' or `-q' flag, when `make' is actually executing
6296
commands, the `-W' flag can direct `make' to act as if some files
6297
had been modified, without actually modifying the files.
6870
recipes, the `-W' flag can direct `make' to act as if some files
6871
had been modified, without actually running the recipes for those
6872
files.
6298
6873
6299
6874
Note that the options `-p' and `-v' allow you to obtain other
6300
6875
information about `make' or about the makefiles in use (*note Summary
6315
6890
time waiting for them to compile.
6316
6891
6317
6892
If you anticipate the problem before changing the header file, you
6318
can use the `-t' flag. This flag tells `make' not to run the commands
6893
can use the `-t' flag. This flag tells `make' not to run the recipes
6319
6894
in the rules, but rather to mark the target up to date by changing its
6320
6895
last-modification date. You would follow this procedure:
6321
6896
6357
6932
6358
6933
The most common way to use this facility is to pass extra flags to
6359
6934
compilers. For example, in a properly written makefile, the variable
6360
`CFLAGS' is included in each command that runs the C compiler, so a
6361
file `foo.c' would be compiled something like this:
6935
`CFLAGS' is included in each recipe that runs the C compiler, so a file
6936
`foo.c' would be compiled something like this:
6362
6937
6363
6938
cc -c $(CFLAGS) foo.c
6364
6939
6382
6957
your own, giving the user the ability to control other aspects of how
6383
6958
the makefile works by changing the variables.
6384
6959
6385
When you override a variable with a command argument, you can define
6386
either a recursively-expanded variable or a simply-expanded variable.
6387
The examples shown above make a recursively-expanded variable; to make a
6388
simply-expanded variable, write `:=' instead of `='. But, unless you
6389
want to include a variable reference or function call in the _value_
6390
that you specify, it makes no difference which kind of variable you
6391
create.
6960
When you override a variable with a command line argument, you can
6961
define either a recursively-expanded variable or a simply-expanded
6962
variable. The examples shown above make a recursively-expanded
6963
variable; to make a simply-expanded variable, write `:=' or `::='
6964
instead of `='. But, unless you want to include a variable reference
6965
or function call in the _value_ that you specify, it makes no
6966
difference which kind of variable you create.
6392
6967
6393
6968
There is one way that the makefile can change a variable that you
6394
6969
have overridden. This is to use the `override' directive, which is a
6402
6977
========================================
6403
6978
6404
6979
Normally, when an error happens in executing a shell command, `make'
6405
gives up immediately, returning a nonzero status. No further commands
6980
gives up immediately, returning a nonzero status. No further recipes
6406
6981
are executed for any target. The error implies that the goal cannot be
6407
6982
correctly remade, and `make' reports this as soon as it knows.
6408
6983
6431
7006
correct them all before the next attempt to compile. This is why Emacs'
6432
7007
`M-x compile' command passes the `-k' flag by default.
6433
7008
6434
6435
File: make.info, Node: Options Summary, Prev: Testing, Up: Running
6436
6437
9.7 Summary of Options
6438
======================
6439
6440
Here is a table of all the options `make' understands:
6441
6442
`-b'
6443
`-m'
6444
These options are ignored for compatibility with other versions of
6445
`make'.
6446
6447
`-B'
6448
`--always-make'
6449
Consider all targets out-of-date. GNU `make' proceeds to consider
6450
targets and their prerequisites using the normal algorithms;
6451
however, all targets so considered are always remade regardless of
6452
the status of their prerequisites. To avoid infinite recursion, if
6453
`MAKE_RESTARTS' (*note Other Special Variables: Special
6454
Variables.) is set to a number greater than 0 this option is
6455
disabled when considering whether to remake makefiles (*note How
6456
Makefiles Are Remade: Remaking Makefiles.).
6457
6458
`-C DIR'
6459
`--directory=DIR'
6460
Change to directory DIR before reading the makefiles. If multiple
6461
`-C' options are specified, each is interpreted relative to the
6462
previous one: `-C / -C etc' is equivalent to `-C /etc'. This is
6463
typically used with recursive invocations of `make' (*note
6464
Recursive Use of `make': Recursion.).
6465
6466
`-d'
6467
Print debugging information in addition to normal processing. The
6468
debugging information says which files are being considered for
6469
remaking, which file-times are being compared and with what
6470
results, which files actually need to be remade, which implicit
6471
rules are considered and which are applied--everything interesting
6472
about how `make' decides what to do. The `-d' option is
6473
equivalent to `--debug=a' (see below).
6474
6475
`--debug[=OPTIONS]'
6476
Print debugging information in addition to normal processing.
6477
Various levels and types of output can be chosen. With no
6478
arguments, print the "basic" level of debugging. Possible
6479
arguments are below; only the first character is considered, and
6480
values must be comma- or space-separated.
6481
6482
`a (all)'
6483
All types of debugging output are enabled. This is
6484
equivalent to using `-d'.
6485
6486
`b (basic)'
6487
Basic debugging prints each target that was found to be
6488
out-of-date, and whether the build was successful or not.
6489
6490
`v (verbose)'
6491
A level above `basic'; includes messages about which
6492
makefiles were parsed, prerequisites that did not need to be
6493
rebuilt, etc. This option also enables `basic' messages.
6494
6495
`i (implicit)'
6496
Prints messages describing the implicit rule searches for
6497
each target. This option also enables `basic' messages.
6498
6499
`j (jobs)'
6500
Prints messages giving details on the invocation of specific
6501
subcommands.
6502
6503
`m (makefile)'
6504
By default, the above messages are not enabled while trying
6505
to remake the makefiles. This option enables messages while
6506
rebuilding makefiles, too. Note that the `all' option does
6507
enable this option. This option also enables `basic'
6508
messages.
6509
6510
`-e'
6511
`--environment-overrides'
6512
Give variables taken from the environment precedence over
6513
variables from makefiles. *Note Variables from the Environment:
6514
Environment.
6515
6516
`-f FILE'
6517
`--file=FILE'
6518
`--makefile=FILE'
6519
Read the file named FILE as a makefile. *Note Writing Makefiles:
6520
Makefiles.
6521
6522
`-h'
6523
`--help'
6524
Remind you of the options that `make' understands and then exit.
6525
6526
`-i'
6527
`--ignore-errors'
6528
Ignore all errors in commands executed to remake files. *Note
6529
Errors in Commands: Errors.
6530
6531
`-I DIR'
6532
`--include-dir=DIR'
6533
Specifies a directory DIR to search for included makefiles. *Note
6534
Including Other Makefiles: Include. If several `-I' options are
6535
used to specify several directories, the directories are searched
6536
in the order specified.
6537
6538
`-j [JOBS]'
6539
`--jobs[=JOBS]'
6540
Specifies the number of jobs (commands) to run simultaneously.
6541
With no argument, `make' runs as many jobs simultaneously as
6542
possible. If there is more than one `-j' option, the last one is
6543
effective. *Note Parallel Execution: Parallel, for more
6544
information on how commands are run. Note that this option is
6545
ignored on MS-DOS.
6546
6547
`-k'
6548
`--keep-going'
6549
Continue as much as possible after an error. While the target that
6550
failed, and those that depend on it, cannot be remade, the other
6551
prerequisites of these targets can be processed all the same.
6552
*Note Testing the Compilation of a Program: Testing.
6553
6554
`-l [LOAD]'
6555
`--load-average[=LOAD]'
6556
`--max-load[=LOAD]'
6557
Specifies that no new jobs (commands) should be started if there
6558
are other jobs running and the load average is at least LOAD (a
6559
floating-point number). With no argument, removes a previous load
6560
limit. *Note Parallel Execution: Parallel.
6561
6562
`-L'
6563
`--check-symlink-times'
6564
On systems that support symbolic links, this option causes `make'
6565
to consider the timestamps on any symbolic links in addition to the
6566
timestamp on the file referenced by those links. When this option
6567
is provided, the most recent timestamp among the file and the
6568
symbolic links is taken as the modification time for this target
6569
file.
6570
6571
`-n'
6572
`--just-print'
6573
`--dry-run'
6574
`--recon'
6575
Print the commands that would be executed, but do not execute them.
6576
*Note Instead of Executing the Commands: Instead of Execution.
6577
6578
`-o FILE'
6579
`--old-file=FILE'
6580
`--assume-old=FILE'
6581
Do not remake the file FILE even if it is older than its
6582
prerequisites, and do not remake anything on account of changes in
6583
FILE. Essentially the file is treated as very old and its rules
6584
are ignored. *Note Avoiding Recompilation of Some Files: Avoiding
6585
Compilation.
6586
6587
`-p'
6588
`--print-data-base'
6589
Print the data base (rules and variable values) that results from
6590
reading the makefiles; then execute as usual or as otherwise
6591
specified. This also prints the version information given by the
6592
`-v' switch (see below). To print the data base without trying to
6593
remake any files, use `make -qp'. To print the data base of
6594
predefined rules and variables, use `make -p -f /dev/null'. The
6595
data base output contains filename and linenumber information for
6596
command and variable definitions, so it can be a useful debugging
6597
tool in complex environments.
6598
6599
`-q'
6600
`--question'
6601
"Question mode". Do not run any commands, or print anything; just
6602
return an exit status that is zero if the specified targets are
6603
already up to date, one if any remaking is required, or two if an
6604
error is encountered. *Note Instead of Executing the Commands:
6605
Instead of Execution.
6606
6607
`-r'
6608
`--no-builtin-rules'
6609
Eliminate use of the built-in implicit rules (*note Using Implicit
6610
Rules: Implicit Rules.). You can still define your own by writing
6611
pattern rules (*note Defining and Redefining Pattern Rules:
6612
Pattern Rules.). The `-r' option also clears out the default list
6613
of suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
6614
Suffix Rules.). But you can still define your own suffixes with a
6615
rule for `.SUFFIXES', and then define your own suffix rules. Note
6616
that only _rules_ are affected by the `-r' option; default
6617
variables remain in effect (*note Variables Used by Implicit
6618
Rules: Implicit Variables.); see the `-R' option below.
6619
6620
`-R'
6621
`--no-builtin-variables'
6622
Eliminate use of the built-in rule-specific variables (*note
6623
Variables Used by Implicit Rules: Implicit Variables.). You can
6624
still define your own, of course. The `-R' option also
6625
automatically enables the `-r' option (see above), since it
6626
doesn't make sense to have implicit rules without any definitions
6627
for the variables that they use.
6628
6629
`-s'
6630
`--silent'
6631
`--quiet'
6632
Silent operation; do not print the commands as they are executed.
6633
*Note Command Echoing: Echoing.
6634
6635
`-S'
6636
`--no-keep-going'
6637
`--stop'
6638
Cancel the effect of the `-k' option. This is never necessary
6639
except in a recursive `make' where `-k' might be inherited from
6640
the top-level `make' via `MAKEFLAGS' (*note Recursive Use of
6641
`make': Recursion.) or if you set `-k' in `MAKEFLAGS' in your
6642
environment.
6643
6644
`-t'
6645
`--touch'
6646
Touch files (mark them up to date without really changing them)
6647
instead of running their commands. This is used to pretend that
6648
the commands were done, in order to fool future invocations of
6649
`make'. *Note Instead of Executing the Commands: Instead of
6650
Execution.
6651
6652
`-v'
6653
`--version'
6654
Print the version of the `make' program plus a copyright, a list
6655
of authors, and a notice that there is no warranty; then exit.
6656
6657
`-w'
6658
`--print-directory'
6659
Print a message containing the working directory both before and
6660
after executing the makefile. This may be useful for tracking
6661
down errors from complicated nests of recursive `make' commands.
6662
*Note Recursive Use of `make': Recursion. (In practice, you
6663
rarely need to specify this option since `make' does it for you;
6664
see *Note The `--print-directory' Option: -w Option.)
6665
6666
`--no-print-directory'
6667
Disable printing of the working directory under `-w'. This option
6668
is useful when `-w' is turned on automatically, but you do not
6669
want to see the extra messages. *Note The `--print-directory'
6670
Option: -w Option.
6671
6672
`-W FILE'
6673
`--what-if=FILE'
6674
`--new-file=FILE'
6675
`--assume-new=FILE'
6676
Pretend that the target FILE has just been modified. When used
6677
with the `-n' flag, this shows you what would happen if you were
6678
to modify that file. Without `-n', it is almost the same as
6679
running a `touch' command on the given file before running `make',
6680
except that the modification time is changed only in the
6681
imagination of `make'. *Note Instead of Executing the Commands:
6682
Instead of Execution.
6683
6684
`--warn-undefined-variables'
6685
Issue a warning message whenever `make' sees a reference to an
6686
undefined variable. This can be helpful when you are trying to
6687
debug makefiles which use variables in complex ways.
6688
6689
6690
File: make.info, Node: Implicit Rules, Next: Archives, Prev: Running, Up: Top
6691
6692
10 Using Implicit Rules
6693
***********************
6694
6695
Certain standard ways of remaking target files are used very often. For
6696
example, one customary way to make an object file is from a C source
6697
file using the C compiler, `cc'.
6698
6699
"Implicit rules" tell `make' how to use customary techniques so that
6700
you do not have to specify them in detail when you want to use them.
6701
For example, there is an implicit rule for C compilation. File names
6702
determine which implicit rules are run. For example, C compilation
6703
typically takes a `.c' file and makes a `.o' file. So `make' applies
6704
the implicit rule for C compilation when it sees this combination of
6705
file name endings.
6706
6707
A chain of implicit rules can apply in sequence; for example, `make'
6708
will remake a `.o' file from a `.y' file by way of a `.c' file.
6709
6710
The built-in implicit rules use several variables in their commands
6711
so that, by changing the values of the variables, you can change the
6712
way the implicit rule works. For example, the variable `CFLAGS'
6713
controls the flags given to the C compiler by the implicit rule for C
6714
compilation.
6715
6716
You can define your own implicit rules by writing "pattern rules".
6717
6718
"Suffix rules" are a more limited way to define implicit rules.
6719
Pattern rules are more general and clearer, but suffix rules are
6720
retained for compatibility.
6721
6722
* Menu:
6723
6724
* Using Implicit:: How to use an existing implicit rule
6725
to get the commands for updating a file.
6726
* Catalogue of Rules:: A list of built-in implicit rules.
6727
* Implicit Variables:: How to change what predefined rules do.
6728
* Chained Rules:: How to use a chain of implicit rules.
6729
* Pattern Rules:: How to define new implicit rules.
6730
* Last Resort:: How to define commands for rules which
6731
cannot find any.
6732
* Suffix Rules:: The old-fashioned style of implicit rule.
6733
* Implicit Rule Search:: The precise algorithm for applying
6734
implicit rules.
6735
6736
6737
File: make.info, Node: Using Implicit, Next: Catalogue of Rules, Prev: Implicit Rules, Up: Implicit Rules
6738
6739
10.1 Using Implicit Rules
6740
=========================
6741
6742
To allow `make' to find a customary method for updating a target file,
6743
all you have to do is refrain from specifying commands yourself. Either
6744
write a rule with no command lines, or don't write a rule at all. Then
6745
`make' will figure out which implicit rule to use based on which kind
6746
of source file exists or can be made.
6747
6748
For example, suppose the makefile looks like this:
6749
6750
foo : foo.o bar.o
6751
cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
6752
6753
Because you mention `foo.o' but do not give a rule for it, `make' will
6754
automatically look for an implicit rule that tells how to update it.
6755
This happens whether or not the file `foo.o' currently exists.
6756
6757
If an implicit rule is found, it can supply both commands and one or
6758
more prerequisites (the source files). You would want to write a rule
6759
for `foo.o' with no command lines if you need to specify additional
6760
prerequisites, such as header files, that the implicit rule cannot
6761
supply.
6762
6763
Each implicit rule has a target pattern and prerequisite patterns.
6764
There may be many implicit rules with the same target pattern. For
6765
example, numerous rules make `.o' files: one, from a `.c' file with the
6766
C compiler; another, from a `.p' file with the Pascal compiler; and so
6767
on. The rule that actually applies is the one whose prerequisites
6768
exist or can be made. So, if you have a file `foo.c', `make' will run
6769
the C compiler; otherwise, if you have a file `foo.p', `make' will run
6770
the Pascal compiler; and so on.
6771
6772
Of course, when you write the makefile, you know which implicit rule
6773
you want `make' to use, and you know it will choose that one because you
6774
know which possible prerequisite files are supposed to exist. *Note
6775
Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all
6776
the predefined implicit rules.
6777
6778
Above, we said an implicit rule applies if the required
6779
prerequisites "exist or can be made". A file "can be made" if it is
6780
mentioned explicitly in the makefile as a target or a prerequisite, or
6781
if an implicit rule can be recursively found for how to make it. When
6782
an implicit prerequisite is the result of another implicit rule, we say
6783
that "chaining" is occurring. *Note Chains of Implicit Rules: Chained
6784
Rules.
6785
6786
In general, `make' searches for an implicit rule for each target, and
6787
for each double-colon rule, that has no commands. A file that is
6788
mentioned only as a prerequisite is considered a target whose rule
6789
specifies nothing, so implicit rule search happens for it. *Note
6790
Implicit Rule Search Algorithm: Implicit Rule Search, for the details
6791
of how the search is done.
6792
6793
Note that explicit prerequisites do not influence implicit rule
6794
search. For example, consider this explicit rule:
6795
6796
foo.o: foo.p
6797
6798
The prerequisite on `foo.p' does not necessarily mean that `make' will
6799
remake `foo.o' according to the implicit rule to make an object file, a
6800
`.o' file, from a Pascal source file, a `.p' file. For example, if
6801
`foo.c' also exists, the implicit rule to make an object file from a C
6802
source file is used instead, because it appears before the Pascal rule
6803
in the list of predefined implicit rules (*note Catalogue of Implicit
6804
Rules: Catalogue of Rules.).
6805
6806
If you do not want an implicit rule to be used for a target that has
6807
no commands, you can give that target empty commands by writing a
6808
semicolon (*note Defining Empty Commands: Empty Commands.).
6809
6810
6811
File: make.info, Node: Catalogue of Rules, Next: Implicit Variables, Prev: Using Implicit, Up: Implicit Rules
6812
6813
10.2 Catalogue of Implicit Rules
6814
================================
6815
6816
Here is a catalogue of predefined implicit rules which are always
6817
available unless the makefile explicitly overrides or cancels them.
6818
*Note Canceling Implicit Rules: Canceling Rules, for information on
6819
canceling or overriding an implicit rule. The `-r' or
6820
`--no-builtin-rules' option cancels all predefined rules.
6821
6822
This manual only documents the default rules available on POSIX-based
6823
operating systems. Other operating systems, such as VMS, Windows,
6824
OS/2, etc. may have different sets of default rules. To see the full
6825
list of default rules and variables available in your version of GNU
6826
`make', run `make -p' in a directory with no makefile.
6827
6828
Not all of these rules will always be defined, even when the `-r'
6829
option is not given. Many of the predefined implicit rules are
6830
implemented in `make' as suffix rules, so which ones will be defined
6831
depends on the "suffix list" (the list of prerequisites of the special
6832
target `.SUFFIXES'). The default suffix list is: `.out', `.a', `.ln',
6833
`.o', `.c', `.cc', `.C', `.cpp', `.p', `.f', `.F', `.r', `.y', `.l',
6834
`.s', `.S', `.mod', `.sym', `.def', `.h', `.info', `.dvi', `.tex',
6835
`.texinfo', `.texi', `.txinfo', `.w', `.ch' `.web', `.sh', `.elc',
6836
`.el'. All of the implicit rules described below whose prerequisites
6837
have one of these suffixes are actually suffix rules. If you modify
6838
the suffix list, the only predefined suffix rules in effect will be
6839
those named by one or two of the suffixes that are on the list you
6840
specify; rules whose suffixes fail to be on the list are disabled.
6841
*Note Old-Fashioned Suffix Rules: Suffix Rules, for full details on
6842
suffix rules.
6843
6844
Compiling C programs
6845
`N.o' is made automatically from `N.c' with a command of the form
6846
`$(CC) -c $(CPPFLAGS) $(CFLAGS)'.
6847
6848
Compiling C++ programs
6849
`N.o' is made automatically from `N.cc', `N.cpp', or `N.C' with a
6850
command of the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'. We
6851
encourage you to use the suffix `.cc' for C++ source files instead
6852
of `.C'.
6853
6854
Compiling Pascal programs
6855
`N.o' is made automatically from `N.p' with the command `$(PC) -c
6856
$(PFLAGS)'.
6857
6858
Compiling Fortran and Ratfor programs
6859
`N.o' is made automatically from `N.r', `N.F' or `N.f' by running
6860
the Fortran compiler. The precise command used is as follows:
6861
6862
`.f'
6863
`$(FC) -c $(FFLAGS)'.
6864
6865
`.F'
6866
`$(FC) -c $(FFLAGS) $(CPPFLAGS)'.
6867
6868
`.r'
6869
`$(FC) -c $(FFLAGS) $(RFLAGS)'.
6870
6871
Preprocessing Fortran and Ratfor programs
6872
`N.f' is made automatically from `N.r' or `N.F'. This rule runs
6873
just the preprocessor to convert a Ratfor or preprocessable
6874
Fortran program into a strict Fortran program. The precise
6875
command used is as follows:
6876
6877
`.F'
6878
`$(FC) -F $(CPPFLAGS) $(FFLAGS)'.
6879
6880
`.r'
6881
`$(FC) -F $(FFLAGS) $(RFLAGS)'.
6882
6883
Compiling Modula-2 programs
6884
`N.sym' is made from `N.def' with a command of the form `$(M2C)
6885
$(M2FLAGS) $(DEFFLAGS)'. `N.o' is made from `N.mod'; the form is:
6886
`$(M2C) $(M2FLAGS) $(MODFLAGS)'.
6887
6888
Assembling and preprocessing assembler programs
6889
`N.o' is made automatically from `N.s' by running the assembler,
6890
`as'. The precise command is `$(AS) $(ASFLAGS)'.
6891
6892
`N.s' is made automatically from `N.S' by running the C
6893
preprocessor, `cpp'. The precise command is `$(CPP) $(CPPFLAGS)'.
6894
6895
Linking a single object file
6896
`N' is made automatically from `N.o' by running the linker
6897
(usually called `ld') via the C compiler. The precise command
6898
used is `$(CC) $(LDFLAGS) N.o $(LOADLIBES) $(LDLIBS)'.
6899
6900
This rule does the right thing for a simple program with only one
6901
source file. It will also do the right thing if there are multiple
6902
object files (presumably coming from various other source files),
6903
one of which has a name matching that of the executable file.
6904
Thus,
6905
6906
x: y.o z.o
6907
6908
when `x.c', `y.c' and `z.c' all exist will execute:
6909
6910
cc -c x.c -o x.o
6911
cc -c y.c -o y.o
6912
cc -c z.c -o z.o
6913
cc x.o y.o z.o -o x
6914
rm -f x.o
6915
rm -f y.o
6916
rm -f z.o
6917
6918
In more complicated cases, such as when there is no object file
6919
whose name derives from the executable file name, you must write
6920
an explicit command for linking.
6921
6922
Each kind of file automatically made into `.o' object files will
6923
be automatically linked by using the compiler (`$(CC)', `$(FC)' or
6924
`$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files)
6925
without the `-c' option. This could be done by using the `.o'
6926
object files as intermediates, but it is faster to do the
6927
compiling and linking in one step, so that's how it's done.
6928
6929
Yacc for C programs
6930
`N.c' is made automatically from `N.y' by running Yacc with the
6931
command `$(YACC) $(YFLAGS)'.
6932
6933
Lex for C programs
6934
`N.c' is made automatically from `N.l' by running Lex. The actual
6935
command is `$(LEX) $(LFLAGS)'.
6936
6937
Lex for Ratfor programs
6938
`N.r' is made automatically from `N.l' by running Lex. The actual
6939
command is `$(LEX) $(LFLAGS)'.
6940
6941
The convention of using the same suffix `.l' for all Lex files
6942
regardless of whether they produce C code or Ratfor code makes it
6943
impossible for `make' to determine automatically which of the two
6944
languages you are using in any particular case. If `make' is
6945
called upon to remake an object file from a `.l' file, it must
6946
guess which compiler to use. It will guess the C compiler, because
6947
that is more common. If you are using Ratfor, make sure `make'
6948
knows this by mentioning `N.r' in the makefile. Or, if you are
6949
using Ratfor exclusively, with no C files, remove `.c' from the
6950
list of implicit rule suffixes with:
6951
6952
.SUFFIXES:
6953
.SUFFIXES: .o .r .f .l ...
6954
6955
Making Lint Libraries from C, Yacc, or Lex programs
6956
`N.ln' is made from `N.c' by running `lint'. The precise command
6957
is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'. The same command is
6958
used on the C code produced from `N.y' or `N.l'.
6959
6960
TeX and Web
6961
`N.dvi' is made from `N.tex' with the command `$(TEX)'. `N.tex'
6962
is made from `N.web' with `$(WEAVE)', or from `N.w' (and from
6963
`N.ch' if it exists or can be made) with `$(CWEAVE)'. `N.p' is
6964
made from `N.web' with `$(TANGLE)' and `N.c' is made from `N.w'
6965
(and from `N.ch' if it exists or can be made) with `$(CTANGLE)'.
6966
6967
Texinfo and Info
6968
`N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with
6969
the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'. `N.info' is made from
6970
`N.texinfo', `N.texi', or `N.txinfo', with the command
6971
`$(MAKEINFO) $(MAKEINFO_FLAGS)'.
6972
6973
RCS
6974
Any file `N' is extracted if necessary from an RCS file named
6975
either `N,v' or `RCS/N,v'. The precise command used is
6976
`$(CO) $(COFLAGS)'. `N' will not be extracted from RCS if it
6977
already exists, even if the RCS file is newer. The rules for RCS
6978
are terminal (*note Match-Anything Pattern Rules: Match-Anything
6979
Rules.), so RCS files cannot be generated from another source;
6980
they must actually exist.
6981
6982
SCCS
6983
Any file `N' is extracted if necessary from an SCCS file named
6984
either `s.N' or `SCCS/s.N'. The precise command used is
6985
`$(GET) $(GFLAGS)'. The rules for SCCS are terminal (*note
6986
Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS
6987
files cannot be generated from another source; they must actually
6988
exist.
6989
6990
For the benefit of SCCS, a file `N' is copied from `N.sh' and made
6991
executable (by everyone). This is for shell scripts that are
6992
checked into SCCS. Since RCS preserves the execution permission
6993
of a file, you do not need to use this feature with RCS.
6994
6995
We recommend that you avoid using of SCCS. RCS is widely held to
6996
be superior, and is also free. By choosing free software in place
6997
of comparable (or inferior) proprietary software, you support the
6998
free software movement.
6999
7000
Usually, you want to change only the variables listed in the table
7001
above, which are documented in the following section.
7002
7003
However, the commands in built-in implicit rules actually use
7004
variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose
7005
values contain the commands listed above.
7006
7007
`make' follows the convention that the rule to compile a `.X' source
7008
file uses the variable `COMPILE.X'. Similarly, the rule to produce an
7009
executable from a `.X' file uses `LINK.X'; and the rule to preprocess a
7010
`.X' file uses `PREPROCESS.X'.
7011
7012
Every rule that produces an object file uses the variable
7013
`OUTPUT_OPTION'. `make' defines this variable either to contain `-o
7014
$@', or to be empty, depending on a compile-time option. You need the
7015
`-o' option to ensure that the output goes into the right file when the
7016
source file is in a different directory, as when using `VPATH' (*note
7017
Directory Search::). However, compilers on some systems do not accept
7018
a `-o' switch for object files. If you use such a system, and use
7019
`VPATH', some compilations will put their output in the wrong place. A
7020
possible workaround for this problem is to give `OUTPUT_OPTION' the
7021
value `; mv $*.o $@'.
7022
7023
7024
File: make.info, Node: Implicit Variables, Next: Chained Rules, Prev: Catalogue of Rules, Up: Implicit Rules
7025
7026
10.3 Variables Used by Implicit Rules
7027
=====================================
7028
7029
The commands in built-in implicit rules make liberal use of certain
7030
predefined variables. You can alter the values of these variables in
7031
the makefile, with arguments to `make', or in the environment to alter
7032
how the implicit rules work without redefining the rules themselves.
7033
You can cancel all variables used by implicit rules with the `-R' or
7034
`--no-builtin-variables' option.
7035
7036
For example, the command used to compile a C source file actually
7037
says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'. The default values of the
7038
variables used are `cc' and nothing, resulting in the command `cc -c'.
7039
By redefining `CC' to `ncc', you could cause `ncc' to be used for all C
7040
compilations performed by the implicit rule. By redefining `CFLAGS' to
7041
be `-g', you could pass the `-g' option to each compilation. _All_
7042
implicit rules that do C compilation use `$(CC)' to get the program
7043
name for the compiler and _all_ include `$(CFLAGS)' among the arguments
7044
given to the compiler.
7045
7046
The variables used in implicit rules fall into two classes: those
7047
that are names of programs (like `CC') and those that contain arguments
7048
for the programs (like `CFLAGS'). (The "name of a program" may also
7049
contain some command arguments, but it must start with an actual
7050
executable program name.) If a variable value contains more than one
7051
argument, separate them with spaces.
7052
7053
The following tables describe of some of the more commonly-used
7054
predefined variables. This list is not exhaustive, and the default
7055
values shown here may not be what are selected by `make' for your
7056
environment. To see the complete list of predefined variables for your
7057
instance of GNU `make' you can run `make -p' in a directory with no
7058
makefiles.
7059
7060
Here is a table of some of the more common variables used as names of
7061
programs in built-in rules: makefiles.
7062
7063
`AR'
7064
Archive-maintaining program; default `ar'.
7065
7066
`AS'
7067
Program for compiling assembly files; default `as'.
7068
7069
`CC'
7070
Program for compiling C programs; default `cc'.
7071
7072
`CO'
7073
Program for checking out files from RCS; default `co'.
7074
7075
`CXX'
7076
Program for compiling C++ programs; default `g++'.
7077
7078
`CO'
7079
Program for extracting a file from RCS; default `co'.
7080
7081
`CPP'
7082
Program for running the C preprocessor, with results to standard
7083
output; default `$(CC) -E'.
7084
7085
`FC'
7086
Program for compiling or preprocessing Fortran and Ratfor programs;
7087
default `f77'.
7088
7089
`GET'
7090
Program for extracting a file from SCCS; default `get'.
7091
7092
`LEX'
7093
Program to use to turn Lex grammars into source code; default
7094
`lex'.
7095
7096
`YACC'
7097
Program to use to turn Yacc grammars into source code; default
7098
`yacc'.
7099
7100
`LINT'
7101
Program to use to run lint on source code; default `lint'.
7102
7103
`M2C'
7104
Program to use to compile Modula-2 source code; default `m2c'.
7105
7106
`PC'
7107
Program for compiling Pascal programs; default `pc'.
7108
7109
`MAKEINFO'
7110
Program to convert a Texinfo source file into an Info file; default
7111
`makeinfo'.
7112
7113
`TEX'
7114
Program to make TeX DVI files from TeX source; default `tex'.
7115
7116
`TEXI2DVI'
7117
Program to make TeX DVI files from Texinfo source; default
7118
`texi2dvi'.
7119
7120
`WEAVE'
7121
Program to translate Web into TeX; default `weave'.
7122
7123
`CWEAVE'
7124
Program to translate C Web into TeX; default `cweave'.
7125
7126
`TANGLE'
7127
Program to translate Web into Pascal; default `tangle'.
7128
7129
`CTANGLE'
7130
Program to translate C Web into C; default `ctangle'.
7131
7132
`RM'
7133
Command to remove a file; default `rm -f'.
7134
7135
Here is a table of variables whose values are additional arguments
7136
for the programs above. The default values for all of these is the
7137
empty string, unless otherwise noted.
7138
7139
`ARFLAGS'
7140
Flags to give the archive-maintaining program; default `rv'.
7141
7142
`ASFLAGS'
7143
Extra flags to give to the assembler (when explicitly invoked on a
7144
`.s' or `.S' file).
7145
7146
`CFLAGS'
7147
Extra flags to give to the C compiler.
7148
7149
`CXXFLAGS'
7150
Extra flags to give to the C++ compiler.
7151
7152
`COFLAGS'
7153
Extra flags to give to the RCS `co' program.
7154
7155
`CPPFLAGS'
7156
Extra flags to give to the C preprocessor and programs that use it
7157
(the C and Fortran compilers).
7158
7159
`FFLAGS'
7160
Extra flags to give to the Fortran compiler.
7161
7162
`GFLAGS'
7163
Extra flags to give to the SCCS `get' program.
7164
7165
`LDFLAGS'
7166
Extra flags to give to compilers when they are supposed to invoke
7167
the linker, `ld'.
7168
7169
`LFLAGS'
7170
Extra flags to give to Lex.
7171
7172
`YFLAGS'
7173
Extra flags to give to Yacc.
7174
7175
`PFLAGS'
7176
Extra flags to give to the Pascal compiler.
7177
7178
`RFLAGS'
7179
Extra flags to give to the Fortran compiler for Ratfor programs.
7180
7181
`LINTFLAGS'
7182
Extra flags to give to lint.
7183
7184
7185
File: make.info, Node: Chained Rules, Next: Pattern Rules, Prev: Implicit Variables, Up: Implicit Rules
7186
7187
10.4 Chains of Implicit Rules
7188
=============================
7189
7190
Sometimes a file can be made by a sequence of implicit rules. For
7191
example, a file `N.o' could be made from `N.y' by running first Yacc
7192
and then `cc'. Such a sequence is called a "chain".
7193
7194
If the file `N.c' exists, or is mentioned in the makefile, no
7195
special searching is required: `make' finds that the object file can be
7196
made by C compilation from `N.c'; later on, when considering how to
7197
make `N.c', the rule for running Yacc is used. Ultimately both `N.c'
7198
and `N.o' are updated.
7199
7200
However, even if `N.c' does not exist and is not mentioned, `make'
7201
knows how to envision it as the missing link between `N.o' and `N.y'!
7202
In this case, `N.c' is called an "intermediate file". Once `make' has
7203
decided to use the intermediate file, it is entered in the data base as
7204
if it had been mentioned in the makefile, along with the implicit rule
7205
that says how to create it.
7206
7207
Intermediate files are remade using their rules just like all other
7208
files. But intermediate files are treated differently in two ways.
7209
7210
The first difference is what happens if the intermediate file does
7211
not exist. If an ordinary file B does not exist, and `make' considers
7212
a target that depends on B, it invariably creates B and then updates
7213
the target from B. But if B is an intermediate file, then `make' can
7214
leave well enough alone. It won't bother updating B, or the ultimate
7215
target, unless some prerequisite of B is newer than that target or
7216
there is some other reason to update that target.
7217
7218
The second difference is that if `make' _does_ create B in order to
7219
update something else, it deletes B later on after it is no longer
7220
needed. Therefore, an intermediate file which did not exist before
7221
`make' also does not exist after `make'. `make' reports the deletion
7222
to you by printing a `rm -f' command showing which file it is deleting.
7223
7224
Ordinarily, a file cannot be intermediate if it is mentioned in the
7225
makefile as a target or prerequisite. However, you can explicitly mark
7226
a file as intermediate by listing it as a prerequisite of the special
7227
target `.INTERMEDIATE'. This takes effect even if the file is mentioned
7228
explicitly in some other way.
7229
7230
You can prevent automatic deletion of an intermediate file by
7231
marking it as a "secondary" file. To do this, list it as a
7232
prerequisite of the special target `.SECONDARY'. When a file is
7233
secondary, `make' will not create the file merely because it does not
7234
already exist, but `make' does not automatically delete the file.
7235
Marking a file as secondary also marks it as intermediate.
7236
7237
You can list the target pattern of an implicit rule (such as `%.o')
7238
as a prerequisite of the special target `.PRECIOUS' to preserve
7239
intermediate files made by implicit rules whose target patterns match
7240
that file's name; see *Note Interrupts::.
7241
7242
A chain can involve more than two implicit rules. For example, it is
7243
possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc
7244
and `cc'. Then both `foo.y' and `foo.c' are intermediate files that
7245
are deleted at the end.
7246
7247
No single implicit rule can appear more than once in a chain. This
7248
means that `make' will not even consider such a ridiculous thing as
7249
making `foo' from `foo.o.o' by running the linker twice. This
7250
constraint has the added benefit of preventing any infinite loop in the
7251
search for an implicit rule chain.
7252
7253
There are some special implicit rules to optimize certain cases that
7254
would otherwise be handled by rule chains. For example, making `foo'
7255
from `foo.c' could be handled by compiling and linking with separate
7256
chained rules, using `foo.o' as an intermediate file. But what
7257
actually happens is that a special rule for this case does the
7258
compilation and linking with a single `cc' command. The optimized rule
7259
is used in preference to the step-by-step chain because it comes
7260
earlier in the ordering of rules.
7261
Loggerhead is a web-based interface for Breezy
Version: 2.0.1