1 |
\input texinfo @c -*- Texinfo -*- |
2 |
@c %**start of header |
3 |
@setfilename make.info |
4 |
@settitle GNU @code{make} |
5 |
@setchapternewpage odd |
6 |
@c %**end of header |
7 |
|
8 |
@c FSF publishers: format makebook.texi instead of using this file directly. |
9 |
|
10 |
@set RCSID $Id: make.texi,v 1.14 2003/07/31 13:04:33 psmith Exp $ |
11 |
@set EDITION 0.61 |
12 |
@set VERSION 3.81 |
13 |
@set UPDATED 02 May 2003 |
14 |
@set UPDATE-MONTH May 2003 |
15 |
@comment The ISBN number might need to change on next publication. |
16 |
@set ISBN 1-882114-81-7 @c From Brian Youmans <3diff@gnu.org>, 25 Apr 2000 |
17 |
|
18 |
@c finalout |
19 |
|
20 |
@c ISPELL CHECK: done, 10 June 1993 --roland |
21 |
@c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz |
22 |
|
23 |
@c Combine the variable and function indices: |
24 |
@syncodeindex vr fn |
25 |
@c Combine the program and concept indices: |
26 |
@syncodeindex pg cp |
27 |
|
28 |
@dircategory GNU Packages |
29 |
@direntry |
30 |
* Make: (make). Remake files automatically. |
31 |
@end direntry |
32 |
|
33 |
@ifinfo |
34 |
This file documents the GNU Make utility, which determines |
35 |
automatically which pieces of a large program need to be recompiled, |
36 |
and issues the commands to recompile them. |
37 |
|
38 |
This is Edition @value{EDITION}, last updated @value{UPDATED}, |
39 |
of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}. |
40 |
|
41 |
Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003 |
42 |
Free Software Foundation, Inc. |
43 |
|
44 |
Permission is granted to copy, distribute and/or modify this document |
45 |
under the terms of the GNU Free Documentation License, Version 1.1 or |
46 |
any later version published by the Free Software Foundation; with no |
47 |
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
48 |
Texts. A copy of the license is included in the section entitled |
49 |
``GNU Free Documentation License''. |
50 |
@end ifinfo |
51 |
|
52 |
@iftex |
53 |
@shorttitlepage GNU Make |
54 |
@end iftex |
55 |
@titlepage |
56 |
@title GNU Make |
57 |
@subtitle A Program for Directing Recompilation |
58 |
@subtitle GNU @code{make} Version @value{VERSION} |
59 |
@subtitle @value{UPDATE-MONTH} |
60 |
@author Richard M. Stallman, Roland McGrath, Paul Smith |
61 |
@page |
62 |
@vskip 0pt plus 1filll |
63 |
Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, |
64 |
1996, 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc. |
65 |
@sp 2 |
66 |
Published by the Free Software Foundation @* |
67 |
59 Temple Place -- Suite 330, @* |
68 |
Boston, MA 02111-1307 USA @* |
69 |
ISBN @value{ISBN} @* |
70 |
|
71 |
Permission is granted to copy, distribute and/or modify this document |
72 |
under the terms of the GNU Free Documentation License, Version 1.1 or |
73 |
any later version published by the Free Software Foundation; with the |
74 |
Invariant Sections being ``GNU General Public License'', the Front-Cover |
75 |
Texts being ``A GNU Manual'', and with the Back-Cover Texts being as in |
76 |
(a) below. A copy of the license is included in the section entitled |
77 |
``GNU Free Documentation License''. |
78 |
|
79 |
(a) The FSF's Back-Cover Text is: |
80 |
|
81 |
@quotation |
82 |
You have freedom to copy and modify this GNU Manual, like GNU |
83 |
software. Copies published by the Free Software Foundation raise |
84 |
funds for GNU development. |
85 |
@end quotation |
86 |
@sp 2 |
87 |
Cover art by Etienne Suvasa. |
88 |
@end titlepage |
89 |
@page |
90 |
|
91 |
@ifinfo |
92 |
@node Top, Overview, (dir), (dir) |
93 |
@top Make |
94 |
|
95 |
The GNU @code{make} utility automatically determines which pieces of a |
96 |
large program need to be recompiled, and issues the commands to |
97 |
recompile them.@refill |
98 |
|
99 |
This edition of the @cite{GNU Make Manual}, |
100 |
last updated @value{UPDATED}, |
101 |
documents GNU @code{make} Version @value{VERSION}.@refill |
102 |
|
103 |
This manual describes @code{make} and contains the following chapters:@refill |
104 |
@end ifinfo |
105 |
|
106 |
@menu |
107 |
* Overview:: Overview of @code{make}. |
108 |
* Introduction:: An introduction to @code{make}. |
109 |
* Makefiles:: Makefiles tell @code{make} what to do. |
110 |
* Rules:: Rules describe when a file must be remade. |
111 |
* Commands:: Commands say how to remake a file. |
112 |
* Using Variables:: You can use variables to avoid repetition. |
113 |
* Conditionals:: Use or ignore parts of the makefile based |
114 |
on the values of variables. |
115 |
* Functions:: Many powerful ways to manipulate text. |
116 |
* Invoking make: Running. How to invoke @code{make} on the command line. |
117 |
* Implicit Rules:: Use implicit rules to treat many files alike, |
118 |
based on their file names. |
119 |
* Archives:: How @code{make} can update library archives. |
120 |
* Features:: Features GNU @code{make} has over other @code{make}s. |
121 |
* Missing:: What GNU @code{make} lacks from other @code{make}s. |
122 |
* Makefile Conventions:: Conventions for writing makefiles for |
123 |
GNU programs. |
124 |
* Quick Reference:: A quick reference for experienced users. |
125 |
* Error Messages:: A list of common errors generated by @code{make}. |
126 |
* Complex Makefile:: A real example of a straightforward, |
127 |
but nontrivial, makefile. |
128 |
|
129 |
* GNU Free Documentation License:: License for copying this manual |
130 |
* Concept Index:: Index of Concepts |
131 |
* Name Index:: Index of Functions, Variables, & Directives |
132 |
|
133 |
@detailmenu |
134 |
--- The Detailed Node Listing --- |
135 |
|
136 |
Overview of @code{make} |
137 |
|
138 |
* Preparing:: Preparing and Running Make |
139 |
* Reading:: On Reading this Text |
140 |
* Bugs:: Problems and Bugs |
141 |
|
142 |
An Introduction to Makefiles |
143 |
|
144 |
* Rule Introduction:: What a rule looks like. |
145 |
* Simple Makefile:: A Simple Makefile |
146 |
* How Make Works:: How @code{make} Processes This Makefile |
147 |
* Variables Simplify:: Variables Make Makefiles Simpler |
148 |
* make Deduces:: Letting @code{make} Deduce the Commands |
149 |
* Combine By Prerequisite:: Another Style of Makefile |
150 |
* Cleanup:: Rules for Cleaning the Directory |
151 |
|
152 |
Writing Makefiles |
153 |
|
154 |
* Makefile Contents:: What makefiles contain. |
155 |
* Makefile Names:: How to name your makefile. |
156 |
* Include:: How one makefile can use another makefile. |
157 |
* MAKEFILES Variable:: The environment can specify extra makefiles. |
158 |
* MAKEFILE_LIST Variable:: Discover which makefiles have been read. |
159 |
* Special Variables:: Other special variables. |
160 |
* Remaking Makefiles:: How makefiles get remade. |
161 |
* Overriding Makefiles:: How to override part of one makefile |
162 |
with another makefile. |
163 |
* Reading Makefiles:: How makefiles are parsed. |
164 |
|
165 |
Writing Rules |
166 |
|
167 |
* Rule Example:: An example explained. |
168 |
* Rule Syntax:: General syntax explained. |
169 |
* Prerequisite Types:: There are two types of prerequisites. |
170 |
* Wildcards:: Using wildcard characters such as `*'. |
171 |
* Directory Search:: Searching other directories for source files. |
172 |
* Phony Targets:: Using a target that is not a real file's name. |
173 |
* Force Targets:: You can use a target without commands |
174 |
or prerequisites to mark other |
175 |
targets as phony. |
176 |
* Empty Targets:: When only the date matters and the |
177 |
files are empty. |
178 |
* Special Targets:: Targets with special built-in meanings. |
179 |
* Multiple Targets:: When to make use of several targets in a rule. |
180 |
* Multiple Rules:: How to use several rules with the same target. |
181 |
* Static Pattern:: Static pattern rules apply to multiple targets |
182 |
and can vary the prerequisites according to |
183 |
the target name. |
184 |
* Double-Colon:: How to use a special kind of rule to allow |
185 |
several independent rules for one target. |
186 |
* Automatic Prerequisites:: How to automatically generate rules giving |
187 |
prerequisites from source files themselves. |
188 |
|
189 |
Using Wildcard Characters in File Names |
190 |
|
191 |
* Wildcard Examples:: Several examples |
192 |
* Wildcard Pitfall:: Problems to avoid. |
193 |
* Wildcard Function:: How to cause wildcard expansion where |
194 |
it does not normally take place. |
195 |
|
196 |
Searching Directories for Prerequisites |
197 |
|
198 |
* General Search:: Specifying a search path that applies |
199 |
to every prerequisite. |
200 |
* Selective Search:: Specifying a search path |
201 |
for a specified class of names. |
202 |
* Search Algorithm:: When and how search paths are applied. |
203 |
* Commands/Search:: How to write shell commands that work together |
204 |
with search paths. |
205 |
* Implicit/Search:: How search paths affect implicit rules. |
206 |
* Libraries/Search:: Directory search for link libraries. |
207 |
|
208 |
Static Pattern Rules |
209 |
|
210 |
* Static Usage:: The syntax of static pattern rules. |
211 |
* Static versus Implicit:: When are they better than implicit rules? |
212 |
|
213 |
Writing the Commands in Rules |
214 |
|
215 |
* Echoing:: How to control when commands are echoed. |
216 |
* Execution:: How commands are executed. |
217 |
* Parallel:: How commands can be executed in parallel. |
218 |
* Errors:: What happens after a command execution error. |
219 |
* Interrupts:: What happens when a command is interrupted. |
220 |
* Recursion:: Invoking @code{make} from makefiles. |
221 |
* Sequences:: Defining canned sequences of commands. |
222 |
* Empty Commands:: Defining useful, do-nothing commands. |
223 |
|
224 |
Recursive Use of @code{make} |
225 |
|
226 |
* MAKE Variable:: The special effects of using @samp{$(MAKE)}. |
227 |
* Variables/Recursion:: How to communicate variables to a sub-@code{make}. |
228 |
* Options/Recursion:: How to communicate options to a sub-@code{make}. |
229 |
* -w Option:: How the @samp{-w} or @samp{--print-directory} option |
230 |
helps debug use of recursive @code{make} commands. |
231 |
|
232 |
How to Use Variables |
233 |
|
234 |
* Reference:: How to use the value of a variable. |
235 |
* Flavors:: Variables come in two flavors. |
236 |
* Advanced:: Advanced features for referencing a variable. |
237 |
* Values:: All the ways variables get their values. |
238 |
* Setting:: How to set a variable in the makefile. |
239 |
* Appending:: How to append more text to the old value |
240 |
of a variable. |
241 |
* Override Directive:: How to set a variable in the makefile even if |
242 |
the user has set it with a command argument. |
243 |
* Defining:: An alternate way to set a variable |
244 |
to a verbatim string. |
245 |
* Environment:: Variable values can come from the environment. |
246 |
* Target-specific:: Variable values can be defined on a per-target |
247 |
basis. |
248 |
* Pattern-specific:: Target-specific variable values can be applied |
249 |
to a group of targets that match a pattern. |
250 |
|
251 |
Advanced Features for Reference to Variables |
252 |
|
253 |
* Substitution Refs:: Referencing a variable with |
254 |
substitutions on the value. |
255 |
* Computed Names:: Computing the name of the variable to refer to. |
256 |
|
257 |
Conditional Parts of Makefiles |
258 |
|
259 |
* Conditional Example:: Example of a conditional |
260 |
* Conditional Syntax:: The syntax of conditionals. |
261 |
* Testing Flags:: Conditionals that test flags. |
262 |
|
263 |
Functions for Transforming Text |
264 |
|
265 |
* Syntax of Functions:: How to write a function call. |
266 |
* Text Functions:: General-purpose text manipulation functions. |
267 |
* File Name Functions:: Functions for manipulating file names. |
268 |
* Foreach Function:: Repeat some text with controlled variation. |
269 |
* If Function:: Conditionally expand a value. |
270 |
* Call Function:: Expand a user-defined function. |
271 |
* Value Function:: Return the un-expanded value of a variable. |
272 |
* Eval Function:: Evaluate the arguments as makefile syntax. |
273 |
* Origin Function:: Find where a variable got its value. |
274 |
* Shell Function:: Substitute the output of a shell command. |
275 |
* Make Control Functions:: Functions that control how make runs. |
276 |
|
277 |
How to Run @code{make} |
278 |
|
279 |
* Makefile Arguments:: How to specify which makefile to use. |
280 |
* Goals:: How to use goal arguments to specify which |
281 |
parts of the makefile to use. |
282 |
* Instead of Execution:: How to use mode flags to specify what |
283 |
kind of thing to do with the commands |
284 |
in the makefile other than simply |
285 |
execute them. |
286 |
* Avoiding Compilation:: How to avoid recompiling certain files. |
287 |
* Overriding:: How to override a variable to specify |
288 |
an alternate compiler and other things. |
289 |
* Testing:: How to proceed past some errors, to |
290 |
test compilation. |
291 |
* Options Summary:: Summary of Options |
292 |
|
293 |
Using Implicit Rules |
294 |
|
295 |
* Using Implicit:: How to use an existing implicit rule |
296 |
to get the commands for updating a file. |
297 |
* Catalogue of Rules:: A list of built-in implicit rules. |
298 |
* Implicit Variables:: How to change what predefined rules do. |
299 |
* Chained Rules:: How to use a chain of implicit rules. |
300 |
* Pattern Rules:: How to define new implicit rules. |
301 |
* Last Resort:: How to defining commands for rules |
302 |
which cannot find any. |
303 |
* Suffix Rules:: The old-fashioned style of implicit rule. |
304 |
* Implicit Rule Search:: The precise algorithm for applying |
305 |
implicit rules. |
306 |
|
307 |
Defining and Redefining Pattern Rules |
308 |
|
309 |
* Pattern Intro:: An introduction to pattern rules. |
310 |
* Pattern Examples:: Examples of pattern rules. |
311 |
* Automatic Variables:: How to use automatic variables in the |
312 |
commands of implicit rules. |
313 |
* Pattern Match:: How patterns match. |
314 |
* Match-Anything Rules:: Precautions you should take prior to |
315 |
defining rules that can match any |
316 |
target file whatever. |
317 |
* Canceling Rules:: How to override or cancel built-in rules. |
318 |
|
319 |
Using @code{make} to Update Archive Files |
320 |
|
321 |
* Archive Members:: Archive members as targets. |
322 |
* Archive Update:: The implicit rule for archive member targets. |
323 |
* Archive Pitfalls:: Dangers to watch out for when using archives. |
324 |
* Archive Suffix Rules:: You can write a special kind of suffix rule |
325 |
for updating archives. |
326 |
|
327 |
Implicit Rule for Archive Member Targets |
328 |
|
329 |
* Archive Symbols:: How to update archive symbol directories. |
330 |
|
331 |
Makefile Conventions |
332 |
|
333 |
* Makefile Basics:: General Conventions for Makefiles |
334 |
* Utilities in Makefiles:: Utilities in Makefiles |
335 |
* Command Variables:: Variables for Specifying Commands |
336 |
* Directory Variables:: Variables for Installation Directories |
337 |
* Standard Targets:: Standard Targets for Users |
338 |
* Install Command Categories:: Three categories of commands in the `install' |
339 |
|
340 |
Copying This Manual |
341 |
|
342 |
@end detailmenu |
343 |
@end menu |
344 |
|
345 |
@node Overview, Introduction, Top, Top |
346 |
@comment node-name, next, previous, up |
347 |
@chapter Overview of @code{make} |
348 |
|
349 |
The @code{make} utility automatically determines which pieces of a large |
350 |
program need to be recompiled, and issues commands to recompile them. |
351 |
This manual describes GNU @code{make}, which was implemented by Richard |
352 |
Stallman and Roland McGrath. Development since Version 3.76 has been |
353 |
handled by Paul Smith. |
354 |
|
355 |
GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard |
356 |
1003.2-1992} (POSIX.2). |
357 |
@cindex POSIX |
358 |
@cindex IEEE Standard 1003.2 |
359 |
@cindex standards conformance |
360 |
|
361 |
Our examples show C programs, since they are most common, but you can use |
362 |
@code{make} with any programming language whose compiler can be run with a |
363 |
shell command. Indeed, @code{make} is not limited to programs. You can |
364 |
use it to describe any task where some files must be updated automatically |
365 |
from others whenever the others change. |
366 |
|
367 |
@menu |
368 |
* Preparing:: Preparing and Running Make |
369 |
* Reading:: On Reading this Text |
370 |
* Bugs:: Problems and Bugs |
371 |
@end menu |
372 |
|
373 |
@node Preparing, Reading, Overview, Overview |
374 |
@ifinfo |
375 |
@heading Preparing and Running Make |
376 |
@end ifinfo |
377 |
|
378 |
To prepare to use @code{make}, you must write a file called |
379 |
the @dfn{makefile} that describes the relationships among files |
380 |
in your program and provides commands for updating each file. |
381 |
In a program, typically, the executable file is updated from object |
382 |
files, which are in turn made by compiling source files.@refill |
383 |
|
384 |
Once a suitable makefile exists, each time you change some source files, |
385 |
this simple shell command: |
386 |
|
387 |
@example |
388 |
make |
389 |
@end example |
390 |
|
391 |
@noindent |
392 |
suffices to perform all necessary recompilations. The @code{make} program |
393 |
uses the makefile data base and the last-modification times of the files to |
394 |
decide which of the files need to be updated. For each of those files, it |
395 |
issues the commands recorded in the data base. |
396 |
|
397 |
You can provide command line arguments to @code{make} to control which |
398 |
files should be recompiled, or how. @xref{Running, ,How to Run |
399 |
@code{make}}. |
400 |
|
401 |
@node Reading, Bugs, Preparing, Overview |
402 |
@section How to Read This Manual |
403 |
|
404 |
If you are new to @code{make}, or are looking for a general |
405 |
introduction, read the first few sections of each chapter, skipping the |
406 |
later sections. In each chapter, the first few sections contain |
407 |
introductory or general information and the later sections contain |
408 |
specialized or technical information. |
409 |
@ifinfo |
410 |
The exception is the second chapter, @ref{Introduction, ,An |
411 |
Introduction to Makefiles}, all of which is introductory. |
412 |
@end ifinfo |
413 |
@iftex |
414 |
The exception is @ref{Introduction, ,An Introduction to Makefiles}, |
415 |
all of which is introductory. |
416 |
@end iftex |
417 |
|
418 |
If you are familiar with other @code{make} programs, see @ref{Features, |
419 |
,Features of GNU @code{make}}, which lists the enhancements GNU |
420 |
@code{make} has, and @ref{Missing, ,Incompatibilities and Missing |
421 |
Features}, which explains the few things GNU @code{make} lacks that |
422 |
others have. |
423 |
|
424 |
For a quick summary, see @ref{Options Summary}, @ref{Quick Reference}, |
425 |
and @ref{Special Targets}. |
426 |
|
427 |
@node Bugs, , Reading, Overview |
428 |
@section Problems and Bugs |
429 |
@cindex reporting bugs |
430 |
@cindex bugs, reporting |
431 |
@cindex problems and bugs, reporting |
432 |
|
433 |
If you have problems with GNU @code{make} or think you've found a bug, |
434 |
please report it to the developers; we cannot promise to do anything but |
435 |
we might well want to fix it. |
436 |
|
437 |
Before reporting a bug, make sure you've actually found a real bug. |
438 |
Carefully reread the documentation and see if it really says you can do |
439 |
what you're trying to do. If it's not clear whether you should be able |
440 |
to do something or not, report that too; it's a bug in the |
441 |
documentation! |
442 |
|
443 |
Before reporting a bug or trying to fix it yourself, try to isolate it |
444 |
to the smallest possible makefile that reproduces the problem. Then |
445 |
send us the makefile and the exact results @code{make} gave you, |
446 |
including any error or warning messages. Please don't paraphrase |
447 |
these messages: it's best to cut and paste them into your report. |
448 |
When generating this small makefile, be sure to not use any non-free |
449 |
or unusual tools in your commands: you can almost always emulate what |
450 |
such a tool would do with simple shell commands. Finally, be sure to |
451 |
explain what you expected to occur; this will help us decide whether |
452 |
the problem was really in the documentation. |
453 |
|
454 |
Once you have a precise problem you can report it in one of two ways. |
455 |
Either send electronic mail to: |
456 |
|
457 |
@example |
458 |
bug-make@@gnu.org |
459 |
@end example |
460 |
|
461 |
@noindent |
462 |
or use our Web-based project management tool, at: |
463 |
|
464 |
@example |
465 |
http://savannah.gnu.org/projects/make/ |
466 |
@end example |
467 |
|
468 |
@noindent |
469 |
In addition to the information above, please be careful to include the |
470 |
version number of @code{make} you are using. You can get this |
471 |
information with the command @samp{make --version}. Be sure also to |
472 |
include the type of machine and operating system you are using. One |
473 |
way to obtain this information is by looking at the final lines of |
474 |
output from the command @samp{make --help}. |
475 |
|
476 |
@node Introduction, Makefiles, Overview, Top |
477 |
@comment node-name, next, previous, up |
478 |
@chapter An Introduction to Makefiles |
479 |
|
480 |
You need a file called a @dfn{makefile} to tell @code{make} what to do. |
481 |
Most often, the makefile tells @code{make} how to compile and link a |
482 |
program. |
483 |
@cindex makefile |
484 |
|
485 |
In this chapter, we will discuss a simple makefile that describes how to |
486 |
compile and link a text editor which consists of eight C source files |
487 |
and three header files. The makefile can also tell @code{make} how to |
488 |
run miscellaneous commands when explicitly asked (for example, to remove |
489 |
certain files as a clean-up operation). To see a more complex example |
490 |
of a makefile, see @ref{Complex Makefile}. |
491 |
|
492 |
When @code{make} recompiles the editor, each changed C source file |
493 |
must be recompiled. If a header file has changed, each C source file |
494 |
that includes the header file must be recompiled to be safe. Each |
495 |
compilation produces an object file corresponding to the source file. |
496 |
Finally, if any source file has been recompiled, all the object files, |
497 |
whether newly made or saved from previous compilations, must be linked |
498 |
together to produce the new executable editor. |
499 |
@cindex recompilation |
500 |
@cindex editor |
501 |
|
502 |
@menu |
503 |
* Rule Introduction:: What a rule looks like. |
504 |
* Simple Makefile:: A Simple Makefile |
505 |
* How Make Works:: How @code{make} Processes This Makefile |
506 |
* Variables Simplify:: Variables Make Makefiles Simpler |
507 |
* make Deduces:: Letting @code{make} Deduce the Commands |
508 |
* Combine By Prerequisite:: Another Style of Makefile |
509 |
* Cleanup:: Rules for Cleaning the Directory |
510 |
@end menu |
511 |
|
512 |
@node Rule Introduction, Simple Makefile, Introduction, Introduction |
513 |
@comment node-name, next, previous, up |
514 |
@section What a Rule Looks Like |
515 |
@cindex rule, introduction to |
516 |
@cindex makefile rule parts |
517 |
@cindex parts of makefile rule |
518 |
|
519 |
A simple makefile consists of ``rules'' with the following shape: |
520 |
|
521 |
@cindex targets, introduction to |
522 |
@cindex prerequisites, introduction to |
523 |
@cindex commands, introduction to |
524 |
@example |
525 |
@group |
526 |
@var{target} @dots{} : @var{prerequisites} @dots{} |
527 |
@var{command} |
528 |
@dots{} |
529 |
@dots{} |
530 |
@end group |
531 |
@end example |
532 |
|
533 |
A @dfn{target} is usually the name of a file that is generated by a |
534 |
program; examples of targets are executable or object files. A target |
535 |
can also be the name of an action to carry out, such as @samp{clean} |
536 |
(@pxref{Phony Targets}). |
537 |
|
538 |
A @dfn{prerequisite} is a file that is used as input to create the |
539 |
target. A target often depends on several files. |
540 |
|
541 |
@cindex tabs in rules |
542 |
A @dfn{command} is an action that @code{make} carries out. |
543 |
A rule may have more than one command, each on its own line. |
544 |
@strong{Please note:} you need to put a tab character at the beginning of |
545 |
every command line! This is an obscurity that catches the unwary. |
546 |
|
547 |
Usually a command is in a rule with prerequisites and serves to create a |
548 |
target file if any of the prerequisites change. However, the rule that |
549 |
specifies commands for the target need not have prerequisites. For |
550 |
example, the rule containing the delete command associated with the |
551 |
target @samp{clean} does not have prerequisites. |
552 |
|
553 |
A @dfn{rule}, then, explains how and when to remake certain files |
554 |
which are the targets of the particular rule. @code{make} carries out |
555 |
the commands on the prerequisites to create or update the target. A |
556 |
rule can also explain how and when to carry out an action. |
557 |
@xref{Rules, , Writing Rules}. |
558 |
|
559 |
A makefile may contain other text besides rules, but a simple makefile |
560 |
need only contain rules. Rules may look somewhat more complicated |
561 |
than shown in this template, but all fit the pattern more or less. |
562 |
|
563 |
@node Simple Makefile, How Make Works, Rule Introduction, Introduction |
564 |
@section A Simple Makefile |
565 |
@cindex simple makefile |
566 |
@cindex makefile, simple |
567 |
|
568 |
Here is a straightforward makefile that describes the way an |
569 |
executable file called @code{edit} depends on eight object files |
570 |
which, in turn, depend on eight C source and three header files. |
571 |
|
572 |
In this example, all the C files include @file{defs.h}, but only those |
573 |
defining editing commands include @file{command.h}, and only low |
574 |
level files that change the editor buffer include @file{buffer.h}. |
575 |
|
576 |
@example |
577 |
@group |
578 |
edit : main.o kbd.o command.o display.o \ |
579 |
insert.o search.o files.o utils.o |
580 |
cc -o edit main.o kbd.o command.o display.o \ |
581 |
insert.o search.o files.o utils.o |
582 |
|
583 |
main.o : main.c defs.h |
584 |
cc -c main.c |
585 |
kbd.o : kbd.c defs.h command.h |
586 |
cc -c kbd.c |
587 |
command.o : command.c defs.h command.h |
588 |
cc -c command.c |
589 |
display.o : display.c defs.h buffer.h |
590 |
cc -c display.c |
591 |
insert.o : insert.c defs.h buffer.h |
592 |
cc -c insert.c |
593 |
search.o : search.c defs.h buffer.h |
594 |
cc -c search.c |
595 |
files.o : files.c defs.h buffer.h command.h |
596 |
cc -c files.c |
597 |
utils.o : utils.c defs.h |
598 |
cc -c utils.c |
599 |
clean : |
600 |
rm edit main.o kbd.o command.o display.o \ |
601 |
insert.o search.o files.o utils.o |
602 |
@end group |
603 |
@end example |
604 |
|
605 |
@noindent |
606 |
We split each long line into two lines using backslash-newline; this is |
607 |
like using one long line, but is easier to read. |
608 |
@cindex continuation lines |
609 |
@cindex @code{\} (backslash), for continuation lines |
610 |
@cindex backslash (@code{\}), for continuation lines |
611 |
@cindex quoting newline, in makefile |
612 |
@cindex newline, quoting, in makefile |
613 |
|
614 |
To use this makefile to create the executable file called @file{edit}, |
615 |
type: |
616 |
|
617 |
@example |
618 |
make |
619 |
@end example |
620 |
|
621 |
To use this makefile to delete the executable file and all the object |
622 |
files from the directory, type: |
623 |
|
624 |
@example |
625 |
make clean |
626 |
@end example |
627 |
|
628 |
In the example makefile, the targets include the executable file |
629 |
@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The |
630 |
prerequisites are files such as @samp{main.c} and @samp{defs.h}. |
631 |
In fact, each @samp{.o} file is both a target and a prerequisite. |
632 |
Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. |
633 |
|
634 |
When a target is a file, it needs to be recompiled or relinked if any |
635 |
of its prerequisites change. In addition, any prerequisites that are |
636 |
themselves automatically generated should be updated first. In this |
637 |
example, @file{edit} depends on each of the eight object files; the |
638 |
object file @file{main.o} depends on the source file @file{main.c} and |
639 |
on the header file @file{defs.h}. |
640 |
|
641 |
A shell command follows each line that contains a target and |
642 |
prerequisites. These shell commands say how to update the target file. |
643 |
A tab character must come at the beginning of every command line to |
644 |
distinguish commands lines from other lines in the makefile. (Bear in |
645 |
mind that @code{make} does not know anything about how the commands |
646 |
work. It is up to you to supply commands that will update the target |
647 |
file properly. All @code{make} does is execute the commands in the rule |
648 |
you have specified when the target file needs to be updated.) |
649 |
@cindex shell command |
650 |
|
651 |
The target @samp{clean} is not a file, but merely the name of an |
652 |
action. Since you |
653 |
normally |
654 |
do not want to carry out the actions in this rule, @samp{clean} is not a prerequisite of any other rule. |
655 |
Consequently, @code{make} never does anything with it unless you tell |
656 |
it specifically. Note that this rule not only is not a prerequisite, it |
657 |
also does not have any prerequisites, so the only purpose of the rule |
658 |
is to run the specified commands. Targets that do not refer to files |
659 |
but are just actions are called @dfn{phony targets}. @xref{Phony |
660 |
Targets}, for information about this kind of target. @xref{Errors, , |
661 |
Errors in Commands}, to see how to cause @code{make} to ignore errors |
662 |
from @code{rm} or any other command. |
663 |
@cindex @code{clean} target |
664 |
@cindex @code{rm} (shell command) |
665 |
|
666 |
@node How Make Works, Variables Simplify, Simple Makefile, Introduction |
667 |
@comment node-name, next, previous, up |
668 |
@section How @code{make} Processes a Makefile |
669 |
@cindex processing a makefile |
670 |
@cindex makefile, how @code{make} processes |
671 |
|
672 |
By default, @code{make} starts with the first target (not targets whose |
673 |
names start with @samp{.}). This is called the @dfn{default goal}. |
674 |
(@dfn{Goals} are the targets that @code{make} strives ultimately to |
675 |
update. @xref{Goals, , Arguments to Specify the Goals}.) |
676 |
@cindex default goal |
677 |
@cindex goal, default |
678 |
@cindex goal |
679 |
|
680 |
In the simple example of the previous section, the default goal is to |
681 |
update the executable program @file{edit}; therefore, we put that rule |
682 |
first. |
683 |
|
684 |
Thus, when you give the command: |
685 |
|
686 |
@example |
687 |
make |
688 |
@end example |
689 |
|
690 |
@noindent |
691 |
@code{make} reads the makefile in the current directory and begins by |
692 |
processing the first rule. In the example, this rule is for relinking |
693 |
@file{edit}; but before @code{make} can fully process this rule, it |
694 |
must process the rules for the files that @file{edit} depends on, |
695 |
which in this case are the object files. Each of these files is |
696 |
processed according to its own rule. These rules say to update each |
697 |
@samp{.o} file by compiling its source file. The recompilation must |
698 |
be done if the source file, or any of the header files named as |
699 |
prerequisites, is more recent than the object file, or if the object |
700 |
file does not exist. |
701 |
|
702 |
The other rules are processed because their targets appear as |
703 |
prerequisites of the goal. If some other rule is not depended on by the |
704 |
goal (or anything it depends on, etc.), that rule is not processed, |
705 |
unless you tell @code{make} to do so (with a command such as |
706 |
@w{@code{make clean}}). |
707 |
|
708 |
Before recompiling an object file, @code{make} considers updating its |
709 |
prerequisites, the source file and header files. This makefile does not |
710 |
specify anything to be done for them---the @samp{.c} and @samp{.h} files |
711 |
are not the targets of any rules---so @code{make} does nothing for these |
712 |
files. But @code{make} would update automatically generated C programs, |
713 |
such as those made by Bison or Yacc, by their own rules at this time. |
714 |
|
715 |
After recompiling whichever object files need it, @code{make} decides |
716 |
whether to relink @file{edit}. This must be done if the file |
717 |
@file{edit} does not exist, or if any of the object files are newer than |
718 |
it. If an object file was just recompiled, it is now newer than |
719 |
@file{edit}, so @file{edit} is relinked. |
720 |
@cindex relinking |
721 |
|
722 |
Thus, if we change the file @file{insert.c} and run @code{make}, |
723 |
@code{make} will compile that file to update @file{insert.o}, and then |
724 |
link @file{edit}. If we change the file @file{command.h} and run |
725 |
@code{make}, @code{make} will recompile the object files @file{kbd.o}, |
726 |
@file{command.o} and @file{files.o} and then link the file @file{edit}. |
727 |
|
728 |
@node Variables Simplify, make Deduces, How Make Works, Introduction |
729 |
@section Variables Make Makefiles Simpler |
730 |
@cindex variables |
731 |
@cindex simplifying with variables |
732 |
|
733 |
In our example, we had to list all the object files twice in the rule for |
734 |
@file{edit} (repeated here): |
735 |
|
736 |
@example |
737 |
@group |
738 |
edit : main.o kbd.o command.o display.o \ |
739 |
insert.o search.o files.o utils.o |
740 |
cc -o edit main.o kbd.o command.o display.o \ |
741 |
insert.o search.o files.o utils.o |
742 |
@end group |
743 |
@end example |
744 |
|
745 |
@cindex @code{objects} |
746 |
Such duplication is error-prone; if a new object file is added to the |
747 |
system, we might add it to one list and forget the other. We can eliminate |
748 |
the risk and simplify the makefile by using a variable. @dfn{Variables} |
749 |
allow a text string to be defined once and substituted in multiple places |
750 |
later (@pxref{Using Variables, ,How to Use Variables}). |
751 |
|
752 |
@cindex @code{OBJECTS} |
753 |
@cindex @code{objs} |
754 |
@cindex @code{OBJS} |
755 |
@cindex @code{obj} |
756 |
@cindex @code{OBJ} |
757 |
It is standard practice for every makefile to have a variable named |
758 |
@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj}, |
759 |
or @code{OBJ} which is a list of all object file names. We would |
760 |
define such a variable @code{objects} with a line like this in the |
761 |
makefile:@refill |
762 |
|
763 |
@example |
764 |
@group |
765 |
objects = main.o kbd.o command.o display.o \ |
766 |
insert.o search.o files.o utils.o |
767 |
@end group |
768 |
@end example |
769 |
|
770 |
@noindent |
771 |
Then, each place we want to put a list of the object file names, we can |
772 |
substitute the variable's value by writing @samp{$(objects)} |
773 |
(@pxref{Using Variables, ,How to Use Variables}). |
774 |
|
775 |
Here is how the complete simple makefile looks when you use a variable |
776 |
for the object files: |
777 |
|
778 |
@example |
779 |
@group |
780 |
objects = main.o kbd.o command.o display.o \ |
781 |
insert.o search.o files.o utils.o |
782 |
|
783 |
edit : $(objects) |
784 |
cc -o edit $(objects) |
785 |
main.o : main.c defs.h |
786 |
cc -c main.c |
787 |
kbd.o : kbd.c defs.h command.h |
788 |
cc -c kbd.c |
789 |
command.o : command.c defs.h command.h |
790 |
cc -c command.c |
791 |
display.o : display.c defs.h buffer.h |
792 |
cc -c display.c |
793 |
insert.o : insert.c defs.h buffer.h |
794 |
cc -c insert.c |
795 |
search.o : search.c defs.h buffer.h |
796 |
cc -c search.c |
797 |
files.o : files.c defs.h buffer.h command.h |
798 |
cc -c files.c |
799 |
utils.o : utils.c defs.h |
800 |
cc -c utils.c |
801 |
clean : |
802 |
rm edit $(objects) |
803 |
@end group |
804 |
@end example |
805 |
|
806 |
@node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction |
807 |
@section Letting @code{make} Deduce the Commands |
808 |
@cindex deducing commands (implicit rules) |
809 |
@cindex implicit rule, introduction to |
810 |
@cindex rule, implicit, introduction to |
811 |
|
812 |
It is not necessary to spell out the commands for compiling the individual |
813 |
C source files, because @code{make} can figure them out: it has an |
814 |
@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly |
815 |
named @samp{.c} file using a @samp{cc -c} command. For example, it will |
816 |
use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into |
817 |
@file{main.o}. We can therefore omit the commands from the rules for the |
818 |
object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill |
819 |
|
820 |
When a @samp{.c} file is used automatically in this way, it is also |
821 |
automatically added to the list of prerequisites. We can therefore omit |
822 |
the @samp{.c} files from the prerequisites, provided we omit the commands. |
823 |
|
824 |
Here is the entire example, with both of these changes, and a variable |
825 |
@code{objects} as suggested above: |
826 |
|
827 |
@example |
828 |
@group |
829 |
objects = main.o kbd.o command.o display.o \ |
830 |
insert.o search.o files.o utils.o |
831 |
|
832 |
edit : $(objects) |
833 |
cc -o edit $(objects) |
834 |
|
835 |
main.o : defs.h |
836 |
kbd.o : defs.h command.h |
837 |
command.o : defs.h command.h |
838 |
display.o : defs.h buffer.h |
839 |
insert.o : defs.h buffer.h |
840 |
search.o : defs.h buffer.h |
841 |
files.o : defs.h buffer.h command.h |
842 |
utils.o : defs.h |
843 |
|
844 |
.PHONY : clean |
845 |
clean : |
846 |
rm edit $(objects) |
847 |
@end group |
848 |
@end example |
849 |
|
850 |
@noindent |
851 |
This is how we would write the makefile in actual practice. (The |
852 |
complications associated with @samp{clean} are described elsewhere. |
853 |
See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.) |
854 |
|
855 |
Because implicit rules are so convenient, they are important. You |
856 |
will see them used frequently.@refill |
857 |
|
858 |
@node Combine By Prerequisite, Cleanup, make Deduces, Introduction |
859 |
@section Another Style of Makefile |
860 |
@cindex combining rules by prerequisite |
861 |
|
862 |
When the objects of a makefile are created only by implicit rules, an |
863 |
alternative style of makefile is possible. In this style of makefile, |
864 |
you group entries by their prerequisites instead of by their targets. |
865 |
Here is what one looks like: |
866 |
|
867 |
@example |
868 |
@group |
869 |
objects = main.o kbd.o command.o display.o \ |
870 |
insert.o search.o files.o utils.o |
871 |
|
872 |
edit : $(objects) |
873 |
cc -o edit $(objects) |
874 |
|
875 |
$(objects) : defs.h |
876 |
kbd.o command.o files.o : command.h |
877 |
display.o insert.o search.o files.o : buffer.h |
878 |
@end group |
879 |
@end example |
880 |
|
881 |
@noindent |
882 |
Here @file{defs.h} is given as a prerequisite of all the object files; |
883 |
@file{command.h} and @file{buffer.h} are prerequisites of the specific |
884 |
object files listed for them. |
885 |
|
886 |
Whether this is better is a matter of taste: it is more compact, but some |
887 |
people dislike it because they find it clearer to put all the information |
888 |
about each target in one place. |
889 |
|
890 |
@node Cleanup, , Combine By Prerequisite, Introduction |
891 |
@section Rules for Cleaning the Directory |
892 |
@cindex cleaning up |
893 |
@cindex removing, to clean up |
894 |
|
895 |
Compiling a program is not the only thing you might want to write rules |
896 |
for. Makefiles commonly tell how to do a few other things besides |
897 |
compiling a program: for example, how to delete all the object files |
898 |
and executables so that the directory is @samp{clean}. |
899 |
|
900 |
@cindex @code{clean} target |
901 |
Here is how we |
902 |
could write a @code{make} rule for cleaning our example editor: |
903 |
|
904 |
@example |
905 |
@group |
906 |
clean: |
907 |
rm edit $(objects) |
908 |
@end group |
909 |
@end example |
910 |
|
911 |
In practice, we might want to write the rule in a somewhat more |
912 |
complicated manner to handle unanticipated situations. We would do this: |
913 |
|
914 |
@example |
915 |
@group |
916 |
.PHONY : clean |
917 |
clean : |
918 |
-rm edit $(objects) |
919 |
@end group |
920 |
@end example |
921 |
|
922 |
@noindent |
923 |
This prevents @code{make} from getting confused by an actual file |
924 |
called @file{clean} and causes it to continue in spite of errors from |
925 |
@code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in |
926 |
Commands}.) |
927 |
|
928 |
@noindent |
929 |
A rule such as this should not be placed at the beginning of the |
930 |
makefile, because we do not want it to run by default! Thus, in the |
931 |
example makefile, we want the rule for @code{edit}, which recompiles |
932 |
the editor, to remain the default goal. |
933 |
|
934 |
Since @code{clean} is not a prerequisite of @code{edit}, this rule will not |
935 |
run at all if we give the command @samp{make} with no arguments. In |
936 |
order to make the rule run, we have to type @samp{make clean}. |
937 |
@xref{Running, ,How to Run @code{make}}. |
938 |
|
939 |
@node Makefiles, Rules, Introduction, Top |
940 |
@chapter Writing Makefiles |
941 |
|
942 |
@cindex makefile, how to write |
943 |
The information that tells @code{make} how to recompile a system comes from |
944 |
reading a data base called the @dfn{makefile}. |
945 |
|
946 |
@menu |
947 |
* Makefile Contents:: What makefiles contain. |
948 |
* Makefile Names:: How to name your makefile. |
949 |
* Include:: How one makefile can use another makefile. |
950 |
* MAKEFILES Variable:: The environment can specify extra makefiles. |
951 |
* MAKEFILE_LIST Variable:: Discover which makefiles have been read. |
952 |
* Special Variables:: Other special variables. |
953 |
* Remaking Makefiles:: How makefiles get remade. |
954 |
* Overriding Makefiles:: How to override part of one makefile |
955 |
with another makefile. |
956 |
* Reading Makefiles:: How makefiles are parsed. |
957 |
@end menu |
958 |
|
959 |
@node Makefile Contents, Makefile Names, Makefiles, Makefiles |
960 |
@section What Makefiles Contain |
961 |
|
962 |
Makefiles contain five kinds of things: @dfn{explicit rules}, |
963 |
@dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives}, |
964 |
and @dfn{comments}. Rules, variables, and directives are described at |
965 |
length in later chapters.@refill |
966 |
|
967 |
@itemize @bullet |
968 |
@cindex rule, explicit, definition of |
969 |
@cindex explicit rule, definition of |
970 |
@item |
971 |
An @dfn{explicit rule} says when and how to remake one or more files, |
972 |
called the rule's @dfn{targets}. It lists the other files that the |
973 |
targets depend on, called the @dfn{prerequisites} of the target, and |
974 |
may also give commands to use to create or update the targets. |
975 |
@xref{Rules, ,Writing Rules}. |
976 |
|
977 |
@cindex rule, implicit, definition of |
978 |
@cindex implicit rule, definition of |
979 |
@item |
980 |
An @dfn{implicit rule} says when and how to remake a class of files |
981 |
based on their names. It describes how a target may depend on a file |
982 |
with a name similar to the target and gives commands to create or |
983 |
update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. |
984 |
|
985 |
@cindex variable definition |
986 |
@item |
987 |
A @dfn{variable definition} is a line that specifies a text string |
988 |
value for a variable that can be substituted into the text later. The |
989 |
simple makefile example shows a variable definition for @code{objects} |
990 |
as a list of all object files (@pxref{Variables Simplify, , Variables |
991 |
Make Makefiles Simpler}). |
992 |
|
993 |
@cindex directive |
994 |
@item |
995 |
A @dfn{directive} is a command for @code{make} to do something special while |
996 |
reading the makefile. These include: |
997 |
|
998 |
@itemize @bullet |
999 |
@item |
1000 |
Reading another makefile (@pxref{Include, ,Including Other Makefiles}). |
1001 |
|
1002 |
@item |
1003 |
Deciding (based on the values of variables) whether to use or |
1004 |
ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}). |
1005 |
|
1006 |
@item |
1007 |
Defining a variable from a verbatim string containing multiple lines |
1008 |
(@pxref{Defining, ,Defining Variables Verbatim}). |
1009 |
@end itemize |
1010 |
|
1011 |
@cindex comments, in makefile |
1012 |
@cindex @code{#} (comments), in makefile |
1013 |
@item |
1014 |
@samp{#} in a line of a makefile starts a @dfn{comment}. It and the |
1015 |
rest of the line are ignored, except that a trailing backslash not |
1016 |
escaped by another backslash will continue the comment across multiple |
1017 |
lines. A line containing just a comment (with perhaps spaces before |
1018 |
it) is effectively blank, and is ignored. If you want a literal |
1019 |
@code{#}, escape it with a backslash (e.g., @code{\#}). Comments may |
1020 |
appear on any line in the makefile, although they are treated |
1021 |
specially in certain situations. |
1022 |
|
1023 |
Within a command script (if the line begins with a TAB character) the |
1024 |
entire line is passed to the shell, just as with any other line that |
1025 |
begins with a TAB. The shell decides how to interpret the text: |
1026 |
whether or not this is a comment is up to the shell. |
1027 |
|
1028 |
Within a @code{define} directive, comments are not ignored during the |
1029 |
definition of the variable, but rather kept intact in the value of the |
1030 |
variable. When the variable is expanded they will either be treated |
1031 |
as @code{make} comments or as command script text, depending on the |
1032 |
context in which the variable is evaluated. |
1033 |
@end itemize |
1034 |
|
1035 |
@node Makefile Names, Include, Makefile Contents, Makefiles |
1036 |
@section What Name to Give Your Makefile |
1037 |
@cindex makefile name |
1038 |
@cindex name of makefile |
1039 |
@cindex default makefile name |
1040 |
@cindex file name of makefile |
1041 |
|
1042 |
@c following paragraph rewritten to avoid overfull hbox |
1043 |
By default, when @code{make} looks for the makefile, it tries the |
1044 |
following names, in order: @file{GNUmakefile}, @file{makefile} |
1045 |
and @file{Makefile}.@refill |
1046 |
@findex Makefile |
1047 |
@findex GNUmakefile |
1048 |
@findex makefile |
1049 |
|
1050 |
@cindex @code{README} |
1051 |
Normally you should call your makefile either @file{makefile} or |
1052 |
@file{Makefile}. (We recommend @file{Makefile} because it appears |
1053 |
prominently near the beginning of a directory listing, right near other |
1054 |
important files such as @file{README}.) The first name checked, |
1055 |
@file{GNUmakefile}, is not recommended for most makefiles. You should |
1056 |
use this name if you have a makefile that is specific to GNU |
1057 |
@code{make}, and will not be understood by other versions of |
1058 |
@code{make}. Other @code{make} programs look for @file{makefile} and |
1059 |
@file{Makefile}, but not @file{GNUmakefile}. |
1060 |
|
1061 |
If @code{make} finds none of these names, it does not use any makefile. |
1062 |
Then you must specify a goal with a command argument, and @code{make} |
1063 |
will attempt to figure out how to remake it using only its built-in |
1064 |
implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}. |
1065 |
|
1066 |
@cindex @code{-f} |
1067 |
@cindex @code{--file} |
1068 |
@cindex @code{--makefile} |
1069 |
If you want to use a nonstandard name for your makefile, you can specify |
1070 |
the makefile name with the @samp{-f} or @samp{--file} option. The |
1071 |
arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell |
1072 |
@code{make} to read the file @var{name} as the makefile. If you use |
1073 |
more than one @samp{-f} or @samp{--file} option, you can specify several |
1074 |
makefiles. All the makefiles are effectively concatenated in the order |
1075 |
specified. The default makefile names @file{GNUmakefile}, |
1076 |
@file{makefile} and @file{Makefile} are not checked automatically if you |
1077 |
specify @samp{-f} or @samp{--file}.@refill |
1078 |
@cindex specifying makefile name |
1079 |
@cindex makefile name, how to specify |
1080 |
@cindex name of makefile, how to specify |
1081 |
@cindex file name of makefile, how to specify |
1082 |
|
1083 |
@node Include, MAKEFILES Variable, Makefile Names, Makefiles |
1084 |
@section Including Other Makefiles |
1085 |
@cindex including other makefiles |
1086 |
@cindex makefile, including |
1087 |
|
1088 |
@findex include |
1089 |
The @code{include} directive tells @code{make} to suspend reading the |
1090 |
current makefile and read one or more other makefiles before continuing. |
1091 |
The directive is a line in the makefile that looks like this: |
1092 |
|
1093 |
@example |
1094 |
include @var{filenames}@dots{} |
1095 |
@end example |
1096 |
|
1097 |
@noindent |
1098 |
@var{filenames} can contain shell file name patterns. |
1099 |
@cindex shell file name pattern (in @code{include}) |
1100 |
@cindex shell wildcards (in @code{include}) |
1101 |
@cindex wildcard, in @code{include} |
1102 |
|
1103 |
Extra spaces are allowed and ignored at the beginning of the line, but |
1104 |
a tab is not allowed. (If the line begins with a tab, it will be |
1105 |
considered a command line.) Whitespace is required between |
1106 |
@code{include} and the file names, and between file names; extra |
1107 |
whitespace is ignored there and at the end of the directive. A |
1108 |
comment starting with @samp{#} is allowed at the end of the line. If |
1109 |
the file names contain any variable or function references, they are |
1110 |
expanded. @xref{Using Variables, ,How to Use Variables}. |
1111 |
|
1112 |
For example, if you have three @file{.mk} files, @file{a.mk}, |
1113 |
@file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to |
1114 |
@code{bish bash}, then the following expression |
1115 |
|
1116 |
@example |
1117 |
include foo *.mk $(bar) |
1118 |
@end example |
1119 |
|
1120 |
is equivalent to |
1121 |
|
1122 |
@example |
1123 |
include foo a.mk b.mk c.mk bish bash |
1124 |
@end example |
1125 |
|
1126 |
When @code{make} processes an @code{include} directive, it suspends |
1127 |
reading of the containing makefile and reads from each listed file in |
1128 |
turn. When that is finished, @code{make} resumes reading the |
1129 |
makefile in which the directive appears. |
1130 |
|
1131 |
One occasion for using @code{include} directives is when several programs, |
1132 |
handled by individual makefiles in various directories, need to use a |
1133 |
common set of variable definitions |
1134 |
(@pxref{Setting, ,Setting Variables}) or pattern rules |
1135 |
(@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). |
1136 |
|
1137 |
Another such occasion is when you want to generate prerequisites from |
1138 |
source files automatically; the prerequisites can be put in a file that |
1139 |
is included by the main makefile. This practice is generally cleaner |
1140 |
than that of somehow appending the prerequisites to the end of the main |
1141 |
makefile as has been traditionally done with other versions of |
1142 |
@code{make}. @xref{Automatic Prerequisites}. |
1143 |
@cindex prerequisites, automatic generation |
1144 |
@cindex automatic generation of prerequisites |
1145 |
@cindex generating prerequisites automatically |
1146 |
|
1147 |
@cindex @code{-I} |
1148 |
@cindex @code{--include-dir} |
1149 |
@cindex included makefiles, default directories |
1150 |
@cindex default directories for included makefiles |
1151 |
@findex /usr/gnu/include |
1152 |
@findex /usr/local/include |
1153 |
@findex /usr/include |
1154 |
If the specified name does not start with a slash, and the file is not |
1155 |
found in the current directory, several other directories are searched. |
1156 |
First, any directories you have specified with the @samp{-I} or |
1157 |
@samp{--include-dir} option are searched |
1158 |
(@pxref{Options Summary, ,Summary of Options}). |
1159 |
Then the following directories (if they exist) |
1160 |
are searched, in this order: |
1161 |
@file{@var{prefix}/include} (normally @file{/usr/local/include} |
1162 |
@footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if |
1163 |
@var{prefix} has been defined to be the root of the DJGPP tree |
1164 |
hierarchy.}) |
1165 |
@file{/usr/gnu/include}, |
1166 |
@file{/usr/local/include}, @file{/usr/include}. |
1167 |
|
1168 |
If an included makefile cannot be found in any of these directories, a |
1169 |
warning message is generated, but it is not an immediately fatal error; |
1170 |
processing of the makefile containing the @code{include} continues. |
1171 |
Once it has finished reading makefiles, @code{make} will try to remake |
1172 |
any that are out of date or don't exist. |
1173 |
@xref{Remaking Makefiles, ,How Makefiles Are Remade}. |
1174 |
Only after it has tried to find a way to remake a makefile and failed, |
1175 |
will @code{make} diagnose the missing makefile as a fatal error. |
1176 |
|
1177 |
If you want @code{make} to simply ignore a makefile which does not exist |
1178 |
and cannot be remade, with no error message, use the @w{@code{-include}} |
1179 |
directive instead of @code{include}, like this: |
1180 |
|
1181 |
@example |
1182 |
-include @var{filenames}@dots{} |
1183 |
@end example |
1184 |
|
1185 |
This acts like @code{include} in every way except that there is no |
1186 |
error (not even a warning) if any of the @var{filenames} do not exist. |
1187 |
For compatibility with some other @code{make} implementations, |
1188 |
@code{sinclude} is another name for @w{@code{-include}}. |
1189 |
|
1190 |
@node MAKEFILES Variable, MAKEFILE_LIST Variable, Include, Makefiles |
1191 |
@section The Variable @code{MAKEFILES} |
1192 |
@cindex makefile, and @code{MAKEFILES} variable |
1193 |
@cindex including (@code{MAKEFILES} variable) |
1194 |
|
1195 |
@vindex MAKEFILES |
1196 |
If the environment variable @code{MAKEFILES} is defined, @code{make} |
1197 |
considers its value as a list of names (separated by whitespace) of |
1198 |
additional makefiles to be read before the others. This works much like |
1199 |
the @code{include} directive: various directories are searched for those |
1200 |
files (@pxref{Include, ,Including Other Makefiles}). In addition, the |
1201 |
default goal is never taken from one of these makefiles and it is not an |
1202 |
error if the files listed in @code{MAKEFILES} are not found.@refill |
1203 |
|
1204 |
@cindex recursion, and @code{MAKEFILES} variable |
1205 |
The main use of @code{MAKEFILES} is in communication between recursive |
1206 |
invocations of @code{make} (@pxref{Recursion, ,Recursive Use of |
1207 |
@code{make}}). It usually is not desirable to set the environment |
1208 |
variable before a top-level invocation of @code{make}, because it is |
1209 |
usually better not to mess with a makefile from outside. However, if |
1210 |
you are running @code{make} without a specific makefile, a makefile in |
1211 |
@code{MAKEFILES} can do useful things to help the built-in implicit |
1212 |
rules work better, such as defining search paths (@pxref{Directory Search}). |
1213 |
|
1214 |
Some users are tempted to set @code{MAKEFILES} in the environment |
1215 |
automatically on login, and program makefiles to expect this to be done. |
1216 |
This is a very bad idea, because such makefiles will fail to work if run by |
1217 |
anyone else. It is much better to write explicit @code{include} directives |
1218 |
in the makefiles. @xref{Include, , Including Other Makefiles}. |
1219 |
|
1220 |
@node MAKEFILE_LIST Variable, Special Variables, MAKEFILES Variable, Makefiles |
1221 |
@comment node-name, next, previous, up |
1222 |
@section The Variable @code{MAKEFILE_LIST} |
1223 |
@cindex makefiles, and @code{MAKEFILE_LIST} variable |
1224 |
@cindex including (@code{MAKEFILE_LIST} variable) |
1225 |
|
1226 |
As @code{make} reads various makefiles, including any obtained from the |
1227 |
@code{MAKEFILES} variable, the command line, the default files, or |
1228 |
from @code{include} directives, their names will be automatically |
1229 |
appended to the @code{MAKEFILE_LIST} variable. They are added right |
1230 |
before @code{make} begins to parse them. |
1231 |
|
1232 |
This means that if the first thing a makefile does is examine the last |
1233 |
word in this variable, it will be the name of the current makefile. |
1234 |
Once the current makefile has used @code{include}, however, the last |
1235 |
word will be the just-included makefile. |
1236 |
|
1237 |
If a makefile named @code{Makefile} has this content: |
1238 |
|
1239 |
@example |
1240 |
@group |
1241 |
name1 := $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)) |
1242 |
|
1243 |
include inc.mk |
1244 |
|
1245 |
name2 := $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST)) |
1246 |
|
1247 |
all: |
1248 |
@@echo name1 = $(name1) |
1249 |
@@echo name2 = $(name2) |
1250 |
@end group |
1251 |
@end example |
1252 |
|
1253 |
@noindent |
1254 |
then you would expect to see this output: |
1255 |
|
1256 |
@example |
1257 |
@group |
1258 |
name1 = Makefile |
1259 |
name2 = inc.mk |
1260 |
@end group |
1261 |
@end example |
1262 |
|
1263 |
@xref{Text Functions}, for more information on the @code{word} and |
1264 |
@code{words} functions used above. @xref{Flavors, The Two Flavors of |
1265 |
Variables}, for more information on simply-expanded (@code{:=}) |
1266 |
variable definitions. |
1267 |
|
1268 |
@node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles |
1269 |
@comment node-name, next, previous, up |
1270 |
@section Other Special Variables |
1271 |
@cindex makefiles, and special variables |
1272 |
@cindex special variables |
1273 |
|
1274 |
GNU @code{make} also supports a special variable. Note that any value |
1275 |
you assign to this variable will be ignored; it will always return its |
1276 |
special value. |
1277 |
|
1278 |
@vindex $(.VARIABLES) |
1279 |
@vindex .VARIABLES @r{(list of variables)} |
1280 |
The first special variable is @code{.VARIABLES}. When expanded, the |
1281 |
value consists of a list of the @emph{names} of all global variables |
1282 |
defined in all makefiles read up until that point. This includes |
1283 |
variables which have empty values, as well as built-in variables |
1284 |
(@pxref{Implicit Variables, , Variables Used by Implicit Rules}), but |
1285 |
does not include any variables which are only defined in a |
1286 |
target-specific context. |
1287 |
|
1288 |
@c @vindex $(.TARGETS) |
1289 |
@c @vindex .TARGETS @r{(list of targets)} |
1290 |
@c The second special variable is @code{.TARGETS}. When expanded, the |
1291 |
@c value consists of a list of all targets defined in all makefiles read |
1292 |
@c up until that point. Note it's not enough for a file to be simply |
1293 |
@c mentioned in the makefile to be listed in this variable, even if it |
1294 |
@c would match an implicit rule and become an ``implicit target''. The |
1295 |
@c file must appear as a target, on the left-hand side of a ``:'', to be |
1296 |
@c considered a target for the purposes of this variable. |
1297 |
|
1298 |
@node Remaking Makefiles, Overriding Makefiles, Special Variables, Makefiles |
1299 |
@section How Makefiles Are Remade |
1300 |
|
1301 |
@cindex updating makefiles |
1302 |
@cindex remaking makefiles |
1303 |
@cindex makefile, remaking of |
1304 |
Sometimes makefiles can be remade from other files, such as RCS or SCCS |
1305 |
files. If a makefile can be remade from other files, you probably want |
1306 |
@code{make} to get an up-to-date version of the makefile to read in. |
1307 |
|
1308 |
To this end, after reading in all makefiles, @code{make} will consider |
1309 |
each as a goal target and attempt to update it. If a makefile has a |
1310 |
rule which says how to update it (found either in that very makefile or |
1311 |
in another one) or if an implicit rule applies to it (@pxref{Implicit |
1312 |
Rules, ,Using Implicit Rules}), it will be updated if necessary. After |
1313 |
all makefiles have been checked, if any have actually been changed, |
1314 |
@code{make} starts with a clean slate and reads all the makefiles over |
1315 |
again. (It will also attempt to update each of them over again, but |
1316 |
normally this will not change them again, since they are already up to |
1317 |
date.)@refill |
1318 |
|
1319 |
If you know that one or more of your makefiles cannot be remade and you |
1320 |
want to keep @code{make} from performing an implicit rule search on |
1321 |
them, perhaps for efficiency reasons, you can use any normal method of |
1322 |
preventing implicit rule lookup to do so. For example, you can write an |
1323 |
explicit rule with the makefile as the target, and an empty command |
1324 |
string (@pxref{Empty Commands, ,Using Empty Commands}). |
1325 |
|
1326 |
If the makefiles specify a double-colon rule to remake a file with |
1327 |
commands but no prerequisites, that file will always be remade |
1328 |
(@pxref{Double-Colon}). In the case of makefiles, a makefile that has a |
1329 |
double-colon rule with commands but no prerequisites will be remade every |
1330 |
time @code{make} is run, and then again after @code{make} starts over |
1331 |
and reads the makefiles in again. This would cause an infinite loop: |
1332 |
@code{make} would constantly remake the makefile, and never do anything |
1333 |
else. So, to avoid this, @code{make} will @strong{not} attempt to |
1334 |
remake makefiles which are specified as targets of a double-colon rule |
1335 |
with commands but no prerequisites.@refill |
1336 |
|
1337 |
If you do not specify any makefiles to be read with @samp{-f} or |
1338 |
@samp{--file} options, @code{make} will try the default makefile names; |
1339 |
@pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike |
1340 |
makefiles explicitly requested with @samp{-f} or @samp{--file} options, |
1341 |
@code{make} is not certain that these makefiles should exist. However, |
1342 |
if a default makefile does not exist but can be created by running |
1343 |
@code{make} rules, you probably want the rules to be run so that the |
1344 |
makefile can be used. |
1345 |
|
1346 |
Therefore, if none of the default makefiles exists, @code{make} will try |
1347 |
to make each of them in the same order in which they are searched for |
1348 |
(@pxref{Makefile Names, ,What Name to Give Your Makefile}) |
1349 |
until it succeeds in making one, or it runs out of names to try. Note |
1350 |
that it is not an error if @code{make} cannot find or make any makefile; |
1351 |
a makefile is not always necessary.@refill |
1352 |
|
1353 |
When you use the @samp{-t} or @samp{--touch} option |
1354 |
(@pxref{Instead of Execution, ,Instead of Executing the Commands}), |
1355 |
you would not want to use an out-of-date makefile to decide which |
1356 |
targets to touch. So the @samp{-t} option has no effect on updating |
1357 |
makefiles; they are really updated even if @samp{-t} is specified. |
1358 |
Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or |
1359 |
@samp{--just-print}) do not prevent updating of makefiles, because an |
1360 |
out-of-date makefile would result in the wrong output for other targets. |
1361 |
Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in, |
1362 |
and then print the commands to update @file{foo} and its prerequisites |
1363 |
without running them. The commands printed for @file{foo} will be those |
1364 |
specified in the updated contents of @file{mfile}. |
1365 |
|
1366 |
However, on occasion you might actually wish to prevent updating of even |
1367 |
the makefiles. You can do this by specifying the makefiles as goals in |
1368 |
the command line as well as specifying them as makefiles. When the |
1369 |
makefile name is specified explicitly as a goal, the options @samp{-t} |
1370 |
and so on do apply to them. |
1371 |
|
1372 |
Thus, @samp{make -f mfile -n mfile foo} would read the makefile |
1373 |
@file{mfile}, print the commands needed to update it without actually |
1374 |
running them, and then print the commands needed to update @file{foo} |
1375 |
without running them. The commands for @file{foo} will be those |
1376 |
specified by the existing contents of @file{mfile}. |
1377 |
|
1378 |
@node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles |
1379 |
@section Overriding Part of Another Makefile |
1380 |
|
1381 |
@cindex overriding makefiles |
1382 |
@cindex makefile, overriding |
1383 |
Sometimes it is useful to have a makefile that is mostly just like |
1384 |
another makefile. You can often use the @samp{include} directive to |
1385 |
include one in the other, and add more targets or variable definitions. |
1386 |
However, if the two makefiles give different commands for the same |
1387 |
target, @code{make} will not let you just do this. But there is another way. |
1388 |
|
1389 |
@cindex match-anything rule, used to override |
1390 |
In the containing makefile (the one that wants to include the other), |
1391 |
you can use a match-anything pattern rule to say that to remake any |
1392 |
target that cannot be made from the information in the containing |
1393 |
makefile, @code{make} should look in another makefile. |
1394 |
@xref{Pattern Rules}, for more information on pattern rules. |
1395 |
|
1396 |
For example, if you have a makefile called @file{Makefile} that says how |
1397 |
to make the target @samp{foo} (and other targets), you can write a |
1398 |
makefile called @file{GNUmakefile} that contains: |
1399 |
|
1400 |
@example |
1401 |
foo: |
1402 |
frobnicate > foo |
1403 |
|
1404 |
%: force |
1405 |
@@$(MAKE) -f Makefile $@@ |
1406 |
force: ; |
1407 |
@end example |
1408 |
|
1409 |
If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, |
1410 |
read it, and see that to make @file{foo}, it needs to run the command |
1411 |
@samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will |
1412 |
find no way to make @file{bar} in @file{GNUmakefile}, so it will use the |
1413 |
commands from the pattern rule: @samp{make -f Makefile bar}. If |
1414 |
@file{Makefile} provides a rule for updating @file{bar}, @code{make} |
1415 |
will apply the rule. And likewise for any other target that |
1416 |
@file{GNUmakefile} does not say how to make. |
1417 |
|
1418 |
The way this works is that the pattern rule has a pattern of just |
1419 |
@samp{%}, so it matches any target whatever. The rule specifies a |
1420 |
prerequisite @file{force}, to guarantee that the commands will be run even |
1421 |
if the target file already exists. We give @file{force} target empty |
1422 |
commands to prevent @code{make} from searching for an implicit rule to |
1423 |
build it---otherwise it would apply the same match-anything rule to |
1424 |
@file{force} itself and create a prerequisite loop! |
1425 |
|
1426 |
@node Reading Makefiles, , Overriding Makefiles, Makefiles |
1427 |
@section How @code{make} Reads a Makefile |
1428 |
@cindex reading makefiles |
1429 |
@cindex makefile, parsing |
1430 |
|
1431 |
GNU @code{make} does its work in two distinct phases. During the first |
1432 |
phase it reads all the makefiles, included makefiles, etc. and |
1433 |
internalizes all the variables and their values, implicit and explicit |
1434 |
rules, and constructs a dependency graph of all the targets and their |
1435 |
prerequisites. During the second phase, @code{make} uses these internal |
1436 |
structures to determine what targets will need to be rebuilt and to |
1437 |
invoke the rules necessary to do so. |
1438 |
|
1439 |
It's important to understand this two-phase approach because it has a |
1440 |
direct impact on how variable and function expansion happens; this is |
1441 |
often a source of some confusion when writing makefiles. Here we will |
1442 |
present a summary of the phases in which expansion happens for different |
1443 |
constructs within the makefile. We say that expansion is |
1444 |
@dfn{immediate} if it happens during the first phase: in this case |
1445 |
@code{make} will expand any variables or functions in that section of a |
1446 |
construct as the makefile is parsed. We say that expansion is |
1447 |
@dfn{deferred} if expansion is not performed immediately. Expansion of |
1448 |
deferred construct is not performed until either the construct appears |
1449 |
later in an immediate context, or until the second phase. |
1450 |
|
1451 |
You may not be familiar with some of these constructs yet. You can |
1452 |
reference this section as you become familiar with them, in later |
1453 |
chapters. |
1454 |
|
1455 |
@subheading Variable Assignment |
1456 |
@cindex +=, expansion |
1457 |
@cindex =, expansion |
1458 |
@cindex ?=, expansion |
1459 |
@cindex +=, expansion |
1460 |
@cindex define, expansion |
1461 |
|
1462 |
Variable definitions are parsed as follows: |
1463 |
|
1464 |
@example |
1465 |
@var{immediate} = @var{deferred} |
1466 |
@var{immediate} ?= @var{deferred} |
1467 |
@var{immediate} := @var{immediate} |
1468 |
@var{immediate} += @var{deferred} or @var{immediate} |
1469 |
|
1470 |
define @var{immediate} |
1471 |
@var{deferred} |
1472 |
endef |
1473 |
@end example |
1474 |
|
1475 |
For the append operator, @samp{+=}, the right-hand side is considered |
1476 |
immediate if the variable was previously set as a simple variable |
1477 |
(@samp{:=}), and deferred otherwise. |
1478 |
|
1479 |
@subheading Conditional Statements |
1480 |
@cindex ifdef, expansion |
1481 |
@cindex ifeq, expansion |
1482 |
@cindex ifndef, expansion |
1483 |
@cindex ifneq, expansion |
1484 |
|
1485 |
All instances of conditional syntax are parsed immediately, in their |
1486 |
entirety; this includes the @code{ifdef}, @code{ifeq}, @code{ifndef}, |
1487 |
and @code{ifneq} forms. |
1488 |
|
1489 |
@subheading Rule Definition |
1490 |
@cindex target, expansion |
1491 |
@cindex prerequisite, expansion |
1492 |
@cindex implicit rule, expansion |
1493 |
@cindex pattern rule, expansion |
1494 |
@cindex explicit rule, expansion |
1495 |
|
1496 |
A rule is always expanded the same way, regardless of the form: |
1497 |
|
1498 |
@example |
1499 |
@var{immediate} : @var{immediate} ; @var{deferred} |
1500 |
@var{deferred} |
1501 |
@end example |
1502 |
|
1503 |
That is, the target and prerequisite sections are expanded immediately, |
1504 |
and the commands used to construct the target are always deferred. This |
1505 |
general rule is true for explicit rules, pattern rules, suffix rules, |
1506 |
static pattern rules, and simple prerequisite definitions. |
1507 |
|
1508 |
@node Rules, Commands, Makefiles, Top |
1509 |
@chapter Writing Rules |
1510 |
@cindex writing rules |
1511 |
@cindex rule, how to write |
1512 |
@cindex target |
1513 |
@cindex prerequisite |
1514 |
|
1515 |
A @dfn{rule} appears in the makefile and says when and how to remake |
1516 |
certain files, called the rule's @dfn{targets} (most often only one per rule). |
1517 |
It lists the other files that are the @dfn{prerequisites} of the target, and |
1518 |
@dfn{commands} to use to create or update the target. |
1519 |
|
1520 |
@cindex default goal |
1521 |
@cindex goal, default |
1522 |
The order of rules is not significant, except for determining the |
1523 |
@dfn{default goal}: the target for @code{make} to consider, if you do |
1524 |
not otherwise specify one. The default goal is the target of the first |
1525 |
rule in the first makefile. If the first rule has multiple targets, |
1526 |
only the first target is taken as the default. There are two |
1527 |
exceptions: a target starting with a period is not a default unless it |
1528 |
contains one or more slashes, @samp{/}, as well; and, a target that |
1529 |
defines a pattern rule has no effect on the default goal. |
1530 |
(@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.) |
1531 |
|
1532 |
Therefore, we usually write the makefile so that the first rule is the |
1533 |
one for compiling the entire program or all the programs described by |
1534 |
the makefile (often with a target called @samp{all}). |
1535 |
@xref{Goals, ,Arguments to Specify the Goals}. |
1536 |
|
1537 |
@menu |
1538 |
* Rule Example:: An example explained. |
1539 |
* Rule Syntax:: General syntax explained. |
1540 |
* Prerequisite Types:: There are two types of prerequisites. |
1541 |
* Wildcards:: Using wildcard characters such as `*'. |
1542 |
* Directory Search:: Searching other directories for source files. |
1543 |
* Phony Targets:: Using a target that is not a real file's name. |
1544 |
* Force Targets:: You can use a target without commands |
1545 |
or prerequisites to mark other |
1546 |
targets as phony. |
1547 |
* Empty Targets:: When only the date matters and the |
1548 |
files are empty. |
1549 |
* Special Targets:: Targets with special built-in meanings. |
1550 |
* Multiple Targets:: When to make use of several targets in a rule. |
1551 |
* Multiple Rules:: How to use several rules with the same target. |
1552 |
* Static Pattern:: Static pattern rules apply to multiple targets |
1553 |
and can vary the prerequisites according to |
1554 |
the target name. |
1555 |
* Double-Colon:: How to use a special kind of rule to allow |
1556 |
several independent rules for one target. |
1557 |
* Automatic Prerequisites:: How to automatically generate rules giving |
1558 |
prerequisites from source files themselves. |
1559 |
@end menu |
1560 |
|
1561 |
@ifinfo |
1562 |
@node Rule Example, Rule Syntax, Rules, Rules |
1563 |
@section Rule Example |
1564 |
|
1565 |
Here is an example of a rule: |
1566 |
|
1567 |
@example |
1568 |
foo.o : foo.c defs.h # module for twiddling the frobs |
1569 |
cc -c -g foo.c |
1570 |
@end example |
1571 |
|
1572 |
Its target is @file{foo.o} and its prerequisites are @file{foo.c} and |
1573 |
@file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}. |
1574 |
The command line starts with a tab to identify it as a command. |
1575 |
|
1576 |
This rule says two things: |
1577 |
|
1578 |
@itemize @bullet |
1579 |
@item |
1580 |
How to decide whether @file{foo.o} is out of date: it is out of date |
1581 |
if it does not exist, or if either @file{foo.c} or @file{defs.h} is |
1582 |
more recent than it. |
1583 |
|
1584 |
@item |
1585 |
How to update the file @file{foo.o}: by running @code{cc} as stated. |
1586 |
The command does not explicitly mention @file{defs.h}, but we presume |
1587 |
that @file{foo.c} includes it, and that that is why @file{defs.h} was |
1588 |
added to the prerequisites. |
1589 |
@end itemize |
1590 |
@end ifinfo |
1591 |
|
1592 |
@node Rule Syntax, Prerequisite Types, Rule Example, Rules |
1593 |
@section Rule Syntax |
1594 |
|
1595 |
@cindex rule syntax |
1596 |
@cindex syntax of rules |
1597 |
In general, a rule looks like this: |
1598 |
|
1599 |
@example |
1600 |
@var{targets} : @var{prerequisites} |
1601 |
@var{command} |
1602 |
@dots{} |
1603 |
@end example |
1604 |
|
1605 |
@noindent |
1606 |
or like this: |
1607 |
|
1608 |
@example |
1609 |
@var{targets} : @var{prerequisites} ; @var{command} |
1610 |
@var{command} |
1611 |
@dots{} |
1612 |
@end example |
1613 |
|
1614 |
@cindex targets |
1615 |
@cindex rule targets |
1616 |
The @var{targets} are file names, separated by spaces. Wildcard |
1617 |
characters may be used (@pxref{Wildcards, ,Using Wildcard Characters |
1618 |
in File Names}) and a name of the form @file{@var{a}(@var{m})} |
1619 |
represents member @var{m} in archive file @var{a} |
1620 |
(@pxref{Archive Members, ,Archive Members as Targets}). |
1621 |
Usually there is only one |
1622 |
target per rule, but occasionally there is a reason to have more |
1623 |
(@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill |
1624 |
|
1625 |
@cindex commands |
1626 |
@cindex tab character (in commands) |
1627 |
The @var{command} lines start with a tab character. The first command may |
1628 |
appear on the line after the prerequisites, with a tab character, or may |
1629 |
appear on the same line, with a semicolon. Either way, the effect is the |
1630 |
same. @xref{Commands, ,Writing the Commands in Rules}. |
1631 |
|
1632 |
@cindex dollar sign (@code{$}), in rules |
1633 |
@cindex @code{$}, in rules |
1634 |
@cindex rule, and @code{$} |
1635 |
Because dollar signs are used to start variable references, if you really |
1636 |
want a dollar sign in a rule you must write two of them, @samp{$$} |
1637 |
(@pxref{Using Variables, ,How to Use Variables}). |
1638 |
You may split a long line by inserting a backslash |
1639 |
followed by a newline, but this is not required, as @code{make} places no |
1640 |
limit on the length of a line in a makefile. |
1641 |
|
1642 |
A rule tells @code{make} two things: when the targets are out of date, |
1643 |
and how to update them when necessary. |
1644 |
|
1645 |
@cindex prerequisites |
1646 |
@cindex rule prerequisites |
1647 |
The criterion for being out of date is specified in terms of the |
1648 |
@var{prerequisites}, which consist of file names separated by spaces. |
1649 |
(Wildcards and archive members (@pxref{Archives}) are allowed here too.) |
1650 |
A target is out of date if it does not exist or if it is older than any |
1651 |
of the prerequisites (by comparison of last-modification times). The |
1652 |
idea is that the contents of the target file are computed based on |
1653 |
information in the prerequisites, so if any of the prerequisites changes, |
1654 |
the contents of the existing target file are no longer necessarily |
1655 |
valid. |
1656 |
|
1657 |
How to update is specified by @var{commands}. These are lines to be |
1658 |
executed by the shell (normally @samp{sh}), but with some extra features |
1659 |
(@pxref{Commands, ,Writing the Commands in Rules}). |
1660 |
|
1661 |
@node Prerequisite Types, Wildcards, Rule Syntax, Rules |
1662 |
@comment node-name, next, previous, up |
1663 |
@section Types of Prerequisites |
1664 |
@cindex prerequisite types |
1665 |
@cindex types of prerequisites |
1666 |
|
1667 |
@cindex prerequisites, normal |
1668 |
@cindex normal prerequisites |
1669 |
@cindex prerequisites, order-only |
1670 |
@cindex order-only prerequisites |
1671 |
There are actually two different types of prerequisites understood by |
1672 |
GNU @code{make}: normal prerequisites such as described in the |
1673 |
previous section, and @dfn{order-only} prerequisites. A normal |
1674 |
prerequisite makes two statements: first, it imposes an order of |
1675 |
execution of build commands: any commands necessary to build any of a |
1676 |
target's prerequisites will be fully executed before any commands |
1677 |
necessary to build the target. Second, it imposes a dependency |
1678 |
relationship: if any prerequisite is newer than the target, then the |
1679 |
target is considered out-of-date and must be rebuilt. |
1680 |
|
1681 |
Normally, this is exactly what you want: if a target's prerequisite is |
1682 |
updated, then the target should also be updated. |
1683 |
|
1684 |
Occasionally, however, you have a situation where you want to impose a |
1685 |
specific ordering on the rules to be invoked @emph{without} forcing |
1686 |
the target to be updated if one of those rules is executed. In that |
1687 |
case, you want to define @dfn{order-only} prerequisites. Order-only |
1688 |
prerequisites can be specified by placing a pipe symbol (@code{|}) |
1689 |
in the prerequisites list: any prerequisites to the left of the pipe |
1690 |
symbol are normal; any prerequisites to the right are order-only: |
1691 |
|
1692 |
@example |
1693 |
@var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites} |
1694 |
@end example |
1695 |
|
1696 |
The normal prerequisites section may of course be empty. Also, you |
1697 |
may still declare multiple lines of prerequisites for the same target: |
1698 |
they are appended appropriately. Note that if you declare the same |
1699 |
file to be both a normal and an order-only prerequisite, the normal |
1700 |
prerequisite takes precedence (since they are a strict superset of the |
1701 |
behavior of an order-only prerequisite). |
1702 |
|
1703 |
@node Wildcards, Directory Search, Prerequisite Types, Rules |
1704 |
@section Using Wildcard Characters in File Names |
1705 |
@cindex wildcard |
1706 |
@cindex file name with wildcards |
1707 |
@cindex globbing (wildcards) |
1708 |
|
1709 |
@cindex @code{*} (wildcard character) |
1710 |
@cindex @code{?} (wildcard character) |
1711 |
@cindex @code{[@dots{}]} (wildcard characters) |
1712 |
A single file name can specify many files using @dfn{wildcard characters}. |
1713 |
The wildcard characters in @code{make} are @samp{*}, @samp{?} and |
1714 |
@samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} |
1715 |
specifies a list of all the files (in the working directory) whose names |
1716 |
end in @samp{.c}.@refill |
1717 |
|
1718 |
@cindex @code{~} (tilde) |
1719 |
@cindex tilde (@code{~}) |
1720 |
@cindex home directory |
1721 |
The character @samp{~} at the beginning of a file name also has special |
1722 |
significance. If alone, or followed by a slash, it represents your home |
1723 |
directory. For example @file{~/bin} expands to @file{/home/you/bin}. |
1724 |
If the @samp{~} is followed by a word, the string represents the home |
1725 |
directory of the user named by that word. For example @file{~john/bin} |
1726 |
expands to @file{/home/john/bin}. On systems which don't have a home |
1727 |
directory for each user (such as MS-DOS or MS-Windows), this |
1728 |
functionality can be simulated by setting the environment variable |
1729 |
@var{HOME}.@refill |
1730 |
|
1731 |
Wildcard expansion happens automatically in targets, in prerequisites, |
1732 |
and in commands (where the shell does the expansion). In other |
1733 |
contexts, wildcard expansion happens only if you request it explicitly |
1734 |
with the @code{wildcard} function. |
1735 |
|
1736 |
The special significance of a wildcard character can be turned off by |
1737 |
preceding it with a backslash. Thus, @file{foo\*bar} would refer to a |
1738 |
specific file whose name consists of @samp{foo}, an asterisk, and |
1739 |
@samp{bar}.@refill |
1740 |
|
1741 |
@menu |
1742 |
* Wildcard Examples:: Several examples |
1743 |
* Wildcard Pitfall:: Problems to avoid. |
1744 |
* Wildcard Function:: How to cause wildcard expansion where |
1745 |
it does not normally take place. |
1746 |
@end menu |
1747 |
|
1748 |
@node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards |
1749 |
@subsection Wildcard Examples |
1750 |
|
1751 |
Wildcards can be used in the commands of a rule, where they are expanded |
1752 |
by the shell. For example, here is a rule to delete all the object files: |
1753 |
|
1754 |
@example |
1755 |
@group |
1756 |
clean: |
1757 |
rm -f *.o |
1758 |
@end group |
1759 |
@end example |
1760 |
@cindex @code{rm} (shell command) |
1761 |
|
1762 |
Wildcards are also useful in the prerequisites of a rule. With the |
1763 |
following rule in the makefile, @samp{make print} will print all the |
1764 |
@samp{.c} files that have changed since the last time you printed them: |
1765 |
|
1766 |
@example |
1767 |
print: *.c |
1768 |
lpr -p $? |
1769 |
touch print |
1770 |
@end example |
1771 |
|
1772 |
@cindex @code{print} target |
1773 |
@cindex @code{lpr} (shell command) |
1774 |
@cindex @code{touch} (shell command) |
1775 |
@noindent |
1776 |
This rule uses @file{print} as an empty target file; see @ref{Empty |
1777 |
Targets, ,Empty Target Files to Record Events}. (The automatic variable |
1778 |
@samp{$?} is used to print only those files that have changed; see |
1779 |
@ref{Automatic Variables}.)@refill |
1780 |
|
1781 |
Wildcard expansion does not happen when you define a variable. Thus, if |
1782 |
you write this: |
1783 |
|
1784 |
@example |
1785 |
objects = *.o |
1786 |
@end example |
1787 |
|
1788 |
@noindent |
1789 |
then the value of the variable @code{objects} is the actual string |
1790 |
@samp{*.o}. However, if you use the value of @code{objects} in a target, |
1791 |
prerequisite or command, wildcard expansion will take place at that time. |
1792 |
To set @code{objects} to the expansion, instead use: |
1793 |
|
1794 |
@example |
1795 |
objects := $(wildcard *.o) |
1796 |
@end example |
1797 |
|
1798 |
@noindent |
1799 |
@xref{Wildcard Function}. |
1800 |
|
1801 |
@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards |
1802 |
@subsection Pitfalls of Using Wildcards |
1803 |
@cindex wildcard pitfalls |
1804 |
@cindex pitfalls of wildcards |
1805 |
@cindex mistakes with wildcards |
1806 |
@cindex errors with wildcards |
1807 |
@cindex problems with wildcards |
1808 |
|
1809 |
Now here is an example of a naive way of using wildcard expansion, that |
1810 |
does not do what you would intend. Suppose you would like to say that the |
1811 |
executable file @file{foo} is made from all the object files in the |
1812 |
directory, and you write this: |
1813 |
|
1814 |
@example |
1815 |
objects = *.o |
1816 |
|
1817 |
foo : $(objects) |
1818 |
cc -o foo $(CFLAGS) $(objects) |
1819 |
@end example |
1820 |
|
1821 |
@noindent |
1822 |
The value of @code{objects} is the actual string @samp{*.o}. Wildcard |
1823 |
expansion happens in the rule for @file{foo}, so that each @emph{existing} |
1824 |
@samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if |
1825 |
necessary. |
1826 |
|
1827 |
But what if you delete all the @samp{.o} files? When a wildcard matches |
1828 |
no files, it is left as it is, so then @file{foo} will depend on the |
1829 |
oddly-named file @file{*.o}. Since no such file is likely to exist, |
1830 |
@code{make} will give you an error saying it cannot figure out how to |
1831 |
make @file{*.o}. This is not what you want! |
1832 |
|
1833 |
Actually it is possible to obtain the desired result with wildcard |
1834 |
expansion, but you need more sophisticated techniques, including the |
1835 |
@code{wildcard} function and string substitution. |
1836 |
@ifinfo |
1837 |
@xref{Wildcard Function, ,The Function @code{wildcard}}. |
1838 |
@end ifinfo |
1839 |
@iftex |
1840 |
These are described in the following section. |
1841 |
@end iftex |
1842 |
|
1843 |
@cindex wildcards and MS-DOS/MS-Windows backslashes |
1844 |
@cindex backslashes in pathnames and wildcard expansion |
1845 |
|
1846 |
Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to |
1847 |
separate directories in pathnames, like so: |
1848 |
|
1849 |
@example |
1850 |
c:\foo\bar\baz.c |
1851 |
@end example |
1852 |
|
1853 |
This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the |
1854 |
@file{c:} part is the so-called drive letter). When @code{make} runs on |
1855 |
these systems, it supports backslashes as well as the Unix-style forward |
1856 |
slashes in pathnames. However, this support does @emph{not} include the |
1857 |
wildcard expansion, where backslash is a quote character. Therefore, |
1858 |
you @emph{must} use Unix-style slashes in these cases. |
1859 |
|
1860 |
|
1861 |
@node Wildcard Function, , Wildcard Pitfall, Wildcards |
1862 |
@subsection The Function @code{wildcard} |
1863 |
@findex wildcard |
1864 |
|
1865 |
Wildcard expansion happens automatically in rules. But wildcard expansion |
1866 |
does not normally take place when a variable is set, or inside the |
1867 |
arguments of a function. If you want to do wildcard expansion in such |
1868 |
places, you need to use the @code{wildcard} function, like this: |
1869 |
|
1870 |
@example |
1871 |
$(wildcard @var{pattern}@dots{}) |
1872 |
@end example |
1873 |
|
1874 |
@noindent |
1875 |
This string, used anywhere in a makefile, is replaced by a |
1876 |
space-separated list of names of existing files that match one of the |
1877 |
given file name patterns. If no existing file name matches a pattern, |
1878 |
then that pattern is omitted from the output of the @code{wildcard} |
1879 |
function. Note that this is different from how unmatched wildcards |
1880 |
behave in rules, where they are used verbatim rather than ignored |
1881 |
(@pxref{Wildcard Pitfall}). |
1882 |
|
1883 |
One use of the @code{wildcard} function is to get a list of all the C source |
1884 |
files in a directory, like this: |
1885 |
|
1886 |
@example |
1887 |
$(wildcard *.c) |
1888 |
@end example |
1889 |
|
1890 |
We can change the list of C source files into a list of object files by |
1891 |
replacing the @samp{.c} suffix with @samp{.o} in the result, like this: |
1892 |
|
1893 |
@example |
1894 |
$(patsubst %.c,%.o,$(wildcard *.c)) |
1895 |
@end example |
1896 |
|
1897 |
@noindent |
1898 |
(Here we have used another function, @code{patsubst}. |
1899 |
@xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill |
1900 |
|
1901 |
Thus, a makefile to compile all C source files in the directory and then |
1902 |
link them together could be written as follows: |
1903 |
|
1904 |
@example |
1905 |
objects := $(patsubst %.c,%.o,$(wildcard *.c)) |
1906 |
|
1907 |
foo : $(objects) |
1908 |
cc -o foo $(objects) |
1909 |
@end example |
1910 |
|
1911 |
@noindent |
1912 |
(This takes advantage of the implicit rule for compiling C programs, so |
1913 |
there is no need to write explicit rules for compiling the files. |
1914 |
@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of |
1915 |
@samp{:=}, which is a variant of @samp{=}.) |
1916 |
|
1917 |
@node Directory Search, Phony Targets, Wildcards, Rules |
1918 |
@section Searching Directories for Prerequisites |
1919 |
@vindex VPATH |
1920 |
@findex vpath |
1921 |
@cindex vpath |
1922 |
@cindex search path for prerequisites (@code{VPATH}) |
1923 |
@cindex directory search (@code{VPATH}) |
1924 |
|
1925 |
For large systems, it is often desirable to put sources in a separate |
1926 |
directory from the binaries. The @dfn{directory search} features of |
1927 |
@code{make} facilitate this by searching several directories |
1928 |
automatically to find a prerequisite. When you redistribute the files |
1929 |
among directories, you do not need to change the individual rules, |
1930 |
just the search paths. |
1931 |
|
1932 |
@menu |
1933 |
* General Search:: Specifying a search path that applies |
1934 |
to every prerequisite. |
1935 |
* Selective Search:: Specifying a search path |
1936 |
for a specified class of names. |
1937 |
* Search Algorithm:: When and how search paths are applied. |
1938 |
* Commands/Search:: How to write shell commands that work together |
1939 |
with search paths. |
1940 |
* Implicit/Search:: How search paths affect implicit rules. |
1941 |
* Libraries/Search:: Directory search for link libraries. |
1942 |
@end menu |
1943 |
|
1944 |
@node General Search, Selective Search, Directory Search, Directory Search |
1945 |
@subsection @code{VPATH}: Search Path for All Prerequisites |
1946 |
@vindex VPATH |
1947 |
|
1948 |
The value of the @code{make} variable @code{VPATH} specifies a list of |
1949 |
directories that @code{make} should search. Most often, the |
1950 |
directories are expected to contain prerequisite files that are not in the |
1951 |
current directory; however, @code{VPATH} specifies a search list that |
1952 |
@code{make} applies for all files, including files which are targets of |
1953 |
rules. |
1954 |
|
1955 |
Thus, if a file that is listed as a target or prerequisite does not exist |
1956 |
in the current directory, @code{make} searches the directories listed in |
1957 |
@code{VPATH} for a file with that name. If a file is found in one of |
1958 |
them, that file may become the prerequisite (see below). Rules may then |
1959 |
specify the names of files in the prerequisite list as if they all |
1960 |
existed in the current directory. @xref{Commands/Search, ,Writing Shell |
1961 |
Commands with Directory Search}. |
1962 |
|
1963 |
In the @code{VPATH} variable, directory names are separated by colons or |
1964 |
blanks. The order in which directories are listed is the order followed |
1965 |
by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons |
1966 |
are used as separators of directory names in @code{VPATH}, since the |
1967 |
colon can be used in the pathname itself, after the drive letter.) |
1968 |
|
1969 |
For example, |
1970 |
|
1971 |
@example |
1972 |
VPATH = src:../headers |
1973 |
@end example |
1974 |
|
1975 |
@noindent |
1976 |
specifies a path containing two directories, @file{src} and |
1977 |
@file{../headers}, which @code{make} searches in that order. |
1978 |
|
1979 |
With this value of @code{VPATH}, the following rule, |
1980 |
|
1981 |
@example |
1982 |
foo.o : foo.c |
1983 |
@end example |
1984 |
|
1985 |
@noindent |
1986 |
is interpreted as if it were written like this: |
1987 |
|
1988 |
@example |
1989 |
foo.o : src/foo.c |
1990 |
@end example |
1991 |
|
1992 |
@noindent |
1993 |
assuming the file @file{foo.c} does not exist in the current directory but |
1994 |
is found in the directory @file{src}. |
1995 |
|
1996 |
@node Selective Search, Search Algorithm, General Search, Directory Search |
1997 |
@subsection The @code{vpath} Directive |
1998 |
@findex vpath |
1999 |
|
2000 |
Similar to the @code{VPATH} variable, but more selective, is the |
2001 |
@code{vpath} directive (note lower case), which allows you to specify a |
2002 |
search path for a particular class of file names: those that match a |
2003 |
particular pattern. Thus you can supply certain search directories for |
2004 |
one class of file names and other directories (or none) for other file |
2005 |
names. |
2006 |
|
2007 |
There are three forms of the @code{vpath} directive: |
2008 |
|
2009 |
@table @code |
2010 |
@item vpath @var{pattern} @var{directories} |
2011 |
Specify the search path @var{directories} for file names that match |
2012 |
@var{pattern}. |
2013 |
|
2014 |
The search path, @var{directories}, is a list of directories to be |
2015 |
searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or |
2016 |
blanks, just like the search path used in the @code{VPATH} variable. |
2017 |
|
2018 |
@item vpath @var{pattern} |
2019 |
Clear out the search path associated with @var{pattern}. |
2020 |
|
2021 |
@c Extra blank line makes sure this gets two lines. |
2022 |
@item vpath |
2023 |
|
2024 |
Clear all search paths previously specified with @code{vpath} directives. |
2025 |
@end table |
2026 |
|
2027 |
A @code{vpath} pattern is a string containing a @samp{%} character. The |
2028 |
string must match the file name of a prerequisite that is being searched |
2029 |
for, the @samp{%} character matching any sequence of zero or more |
2030 |
characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and |
2031 |
Redefining Pattern Rules}). For example, @code{%.h} matches files that |
2032 |
end in @code{.h}. (If there is no @samp{%}, the pattern must match the |
2033 |
prerequisite exactly, which is not useful very often.) |
2034 |
|
2035 |
@cindex @code{%}, quoting in @code{vpath} |
2036 |
@cindex @code{%}, quoting with @code{\} (backslash) |
2037 |
@cindex @code{\} (backslash), to quote @code{%} |
2038 |
@cindex backslash (@code{\}), to quote @code{%} |
2039 |
@cindex quoting @code{%}, in @code{vpath} |
2040 |
@samp{%} characters in a @code{vpath} directive's pattern can be quoted |
2041 |
with preceding backslashes (@samp{\}). Backslashes that would otherwise |
2042 |
quote @samp{%} characters can be quoted with more backslashes. |
2043 |
Backslashes that quote @samp{%} characters or other backslashes are |
2044 |
removed from the pattern before it is compared to file names. Backslashes |
2045 |
that are not in danger of quoting @samp{%} characters go unmolested.@refill |
2046 |
|
2047 |
When a prerequisite fails to exist in the current directory, if the |
2048 |
@var{pattern} in a @code{vpath} directive matches the name of the |
2049 |
prerequisite file, then the @var{directories} in that directive are searched |
2050 |
just like (and before) the directories in the @code{VPATH} variable. |
2051 |
|
2052 |
For example, |
2053 |
|
2054 |
@example |
2055 |
vpath %.h ../headers |
2056 |
@end example |
2057 |
|
2058 |
@noindent |
2059 |
tells @code{make} to look for any prerequisite whose name ends in @file{.h} |
2060 |
in the directory @file{../headers} if the file is not found in the current |
2061 |
directory. |
2062 |
|
2063 |
If several @code{vpath} patterns match the prerequisite file's name, then |
2064 |
@code{make} processes each matching @code{vpath} directive one by one, |
2065 |
searching all the directories mentioned in each directive. @code{make} |
2066 |
handles multiple @code{vpath} directives in the order in which they |
2067 |
appear in the makefile; multiple directives with the same pattern are |
2068 |
independent of each other. |
2069 |
|
2070 |
@need 750 |
2071 |
Thus, |
2072 |
|
2073 |
@example |
2074 |
@group |
2075 |
vpath %.c foo |
2076 |
vpath % blish |
2077 |
vpath %.c bar |
2078 |
@end group |
2079 |
@end example |
2080 |
|
2081 |
@noindent |
2082 |
will look for a file ending in @samp{.c} in @file{foo}, then |
2083 |
@file{blish}, then @file{bar}, while |
2084 |
|
2085 |
@example |
2086 |
@group |
2087 |
vpath %.c foo:bar |
2088 |
vpath % blish |
2089 |
@end group |
2090 |
@end example |
2091 |
|
2092 |
@noindent |
2093 |
will look for a file ending in @samp{.c} in @file{foo}, then |
2094 |
@file{bar}, then @file{blish}. |
2095 |
|
2096 |
@node Search Algorithm, Commands/Search, Selective Search, Directory Search |
2097 |
@subsection How Directory Searches are Performed |
2098 |
@cindex algorithm for directory search |
2099 |
@cindex directory search algorithm |
2100 |
|
2101 |
When a prerequisite is found through directory search, regardless of type |
2102 |
(general or selective), the pathname located may not be the one that |
2103 |
@code{make} actually provides you in the prerequisite list. Sometimes |
2104 |
the path discovered through directory search is thrown away. |
2105 |
|
2106 |
The algorithm @code{make} uses to decide whether to keep or abandon a |
2107 |
path found via directory search is as follows: |
2108 |
|
2109 |
@enumerate |
2110 |
@item |
2111 |
If a target file does not exist at the path specified in the makefile, |
2112 |
directory search is performed. |
2113 |
|
2114 |
@item |
2115 |
If the directory search is successful, that path is kept and this file |
2116 |
is tentatively stored as the target. |
2117 |
|
2118 |
@item |
2119 |
All prerequisites of this target are examined using this same method. |
2120 |
|
2121 |
@item |
2122 |
After processing the prerequisites, the target may or may not need to be |
2123 |
rebuilt: |
2124 |
|
2125 |
@enumerate a |
2126 |
@item |
2127 |
If the target does @emph{not} need to be rebuilt, the path to the file |
2128 |
found during directory search is used for any prerequisite lists which |
2129 |
contain this target. In short, if @code{make} doesn't need to rebuild |
2130 |
the target then you use the path found via directory search. |
2131 |
|
2132 |
@item |
2133 |
If the target @emph{does} need to be rebuilt (is out-of-date), the |
2134 |
pathname found during directory search is @emph{thrown away}, and the |
2135 |
target is rebuilt using the file name specified in the makefile. In |
2136 |
short, if @code{make} must rebuild, then the target is rebuilt locally, |
2137 |
not in the directory found via directory search. |
2138 |
@end enumerate |
2139 |
@end enumerate |
2140 |
|
2141 |
This algorithm may seem complex, but in practice it is quite often |
2142 |
exactly what you want. |
2143 |
|
2144 |
@cindex traditional directory search (GPATH) |
2145 |
@cindex directory search, traditional (GPATH) |
2146 |
Other versions of @code{make} use a simpler algorithm: if the file does |
2147 |
not exist, and it is found via directory search, then that pathname is |
2148 |
always used whether or not the target needs to be built. Thus, if the |
2149 |
target is rebuilt it is created at the pathname discovered during |
2150 |
directory search. |
2151 |
|
2152 |
@vindex GPATH |
2153 |
If, in fact, this is the behavior you want for some or all of your |
2154 |
directories, you can use the @code{GPATH} variable to indicate this to |
2155 |
@code{make}. |
2156 |
|
2157 |
@code{GPATH} has the same syntax and format as @code{VPATH} (that is, a |
2158 |
space- or colon-delimited list of pathnames). If an out-of-date target |
2159 |
is found by directory search in a directory that also appears in |
2160 |
@code{GPATH}, then that pathname is not thrown away. The target is |
2161 |
rebuilt using the expanded path. |
2162 |
|
2163 |
@node Commands/Search, Implicit/Search, Search Algorithm, Directory Search |
2164 |
@subsection Writing Shell Commands with Directory Search |
2165 |
@cindex shell command, and directory search |
2166 |
@cindex directory search (@code{VPATH}), and shell commands |
2167 |
|
2168 |
When a prerequisite is found in another directory through directory search, |
2169 |
this cannot change the commands of the rule; they will execute as written. |
2170 |
Therefore, you must write the commands with care so that they will look for |
2171 |
the prerequisite in the directory where @code{make} finds it. |
2172 |
|
2173 |
This is done with the @dfn{automatic variables} such as @samp{$^} |
2174 |
(@pxref{Automatic Variables}). |
2175 |
For instance, the value of @samp{$^} is a |
2176 |
list of all the prerequisites of the rule, including the names of |
2177 |
the directories in which they were found, and the value of |
2178 |
@samp{$@@} is the target. Thus:@refill |
2179 |
|
2180 |
@example |
2181 |
foo.o : foo.c |
2182 |
cc -c $(CFLAGS) $^ -o $@@ |
2183 |
@end example |
2184 |
|
2185 |
@noindent |
2186 |
(The variable @code{CFLAGS} exists so you can specify flags for C |
2187 |
compilation by implicit rules; we use it here for consistency so it will |
2188 |
affect all C compilations uniformly; |
2189 |
@pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) |
2190 |
|
2191 |
Often the prerequisites include header files as well, which you do not |
2192 |
want to mention in the commands. The automatic variable @samp{$<} is |
2193 |
just the first prerequisite: |
2194 |
|
2195 |
@example |
2196 |
VPATH = src:../headers |
2197 |
foo.o : foo.c defs.h hack.h |
2198 |
cc -c $(CFLAGS) $< -o $@@ |
2199 |
@end example |
2200 |
|
2201 |
@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search |
2202 |
@subsection Directory Search and Implicit Rules |
2203 |
@cindex @code{VPATH}, and implicit rules |
2204 |
@cindex directory search (@code{VPATH}), and implicit rules |
2205 |
@cindex search path for prerequisites (@code{VPATH}), and implicit rules |
2206 |
@cindex implicit rule, and directory search |
2207 |
@cindex implicit rule, and @code{VPATH} |
2208 |
@cindex rule, implicit, and directory search |
2209 |
@cindex rule, implicit, and @code{VPATH} |
2210 |
|
2211 |
The search through the directories specified in @code{VPATH} or with |
2212 |
@code{vpath} also happens during consideration of implicit rules |
2213 |
(@pxref{Implicit Rules, ,Using Implicit Rules}). |
2214 |
|
2215 |
For example, when a file @file{foo.o} has no explicit rule, @code{make} |
2216 |
considers implicit rules, such as the built-in rule to compile |
2217 |
@file{foo.c} if that file exists. If such a file is lacking in the |
2218 |
current directory, the appropriate directories are searched for it. If |
2219 |
@file{foo.c} exists (or is mentioned in the makefile) in any of the |
2220 |
directories, the implicit rule for C compilation is applied. |
2221 |
|
2222 |
The commands of implicit rules normally use automatic variables as a |
2223 |
matter of necessity; consequently they will use the file names found by |
2224 |
directory search with no extra effort. |
2225 |
|
2226 |
@node Libraries/Search, , Implicit/Search, Directory Search |
2227 |
@subsection Directory Search for Link Libraries |
2228 |
@cindex link libraries, and directory search |
2229 |
@cindex libraries for linking, directory search |
2230 |
@cindex directory search (@code{VPATH}), and link libraries |
2231 |
@cindex @code{VPATH}, and link libraries |
2232 |
@cindex search path for prerequisites (@code{VPATH}), and link libraries |
2233 |
@cindex @code{-l} (library search) |
2234 |
@cindex link libraries, patterns matching |
2235 |
@cindex @code{.LIBPATTERNS}, and link libraries |
2236 |
@vindex .LIBPATTERNS |
2237 |
|
2238 |
Directory search applies in a special way to libraries used with the |
2239 |
linker. This special feature comes into play when you write a prerequisite |
2240 |
whose name is of the form @samp{-l@var{name}}. (You can tell something |
2241 |
strange is going on here because the prerequisite is normally the name of a |
2242 |
file, and the @emph{file name} of a library generally looks like |
2243 |
@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill |
2244 |
|
2245 |
When a prerequisite's name has the form @samp{-l@var{name}}, @code{make} |
2246 |
handles it specially by searching for the file @file{lib@var{name}.so} in |
2247 |
the current directory, in directories specified by matching @code{vpath} |
2248 |
search paths and the @code{VPATH} search path, and then in the |
2249 |
directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} |
2250 |
(normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of |
2251 |
@code{make} behave as if @var{prefix} is defined to be the root of the |
2252 |
DJGPP installation tree). |
2253 |
|
2254 |
If that file is not found, then the file @file{lib@var{name}.a} is |
2255 |
searched for, in the same directories as above. |
2256 |
|
2257 |
For example, if there is a @file{/usr/lib/libcurses.a} library on your |
2258 |
system (and no @file{/usr/lib/libcurses.so} file), then |
2259 |
|
2260 |
@example |
2261 |
@group |
2262 |
foo : foo.c -lcurses |
2263 |
cc $^ -o $@@ |
2264 |
@end group |
2265 |
@end example |
2266 |
|
2267 |
@noindent |
2268 |
would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to |
2269 |
be executed when @file{foo} is older than @file{foo.c} or than |
2270 |
@file{/usr/lib/libcurses.a}.@refill |
2271 |
|
2272 |
Although the default set of files to be searched for is |
2273 |
@file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable |
2274 |
via the @code{.LIBPATTERNS} variable. Each word in the value of this |
2275 |
variable is a pattern string. When a prerequisite like |
2276 |
@samp{-l@var{name}} is seen, @code{make} will replace the percent in |
2277 |
each pattern in the list with @var{name} and perform the above directory |
2278 |
searches using that library filename. If no library is found, the next |
2279 |
word in the list will be used. |
2280 |
|
2281 |
The default value for @code{.LIBPATTERNS} is ``@samp{lib%.so lib%.a}'', |
2282 |
which provides the default behavior described above. |
2283 |
|
2284 |
You can turn off link library expansion completely by setting this |
2285 |
variable to an empty value. |
2286 |
|
2287 |
@node Phony Targets, Force Targets, Directory Search, Rules |
2288 |
@section Phony Targets |
2289 |
@cindex phony targets |
2290 |
@cindex targets, phony |
2291 |
@cindex targets without a file |
2292 |
|
2293 |
A phony target is one that is not really the name of a file. It is just a |
2294 |
name for some commands to be executed when you make an explicit request. |
2295 |
There are two reasons to use a phony target: to avoid a conflict with |
2296 |
a file of the same name, and to improve performance. |
2297 |
|
2298 |
If you write a rule whose commands will not create the target file, the |
2299 |
commands will be executed every time the target comes up for remaking. |
2300 |
Here is an example: |
2301 |
|
2302 |
@example |
2303 |
@group |
2304 |
clean: |
2305 |
rm *.o temp |
2306 |
@end group |
2307 |
@end example |
2308 |
|
2309 |
@noindent |
2310 |
Because the @code{rm} command does not create a file named @file{clean}, |
2311 |
probably no such file will ever exist. Therefore, the @code{rm} command |
2312 |
will be executed every time you say @samp{make clean}. |
2313 |
@cindex @code{rm} (shell command) |
2314 |
|
2315 |
@findex .PHONY |
2316 |
The phony target will cease to work if anything ever does create a file |
2317 |
named @file{clean} in this directory. Since it has no prerequisites, the |
2318 |
file @file{clean} would inevitably be considered up to date, and its |
2319 |
commands would not be executed. To avoid this problem, you can explicitly |
2320 |
declare the target to be phony, using the special target @code{.PHONY} |
2321 |
(@pxref{Special Targets, ,Special Built-in Target Names}) as follows: |
2322 |
|
2323 |
@example |
2324 |
.PHONY : clean |
2325 |
@end example |
2326 |
|
2327 |
@noindent |
2328 |
Once this is done, @samp{make clean} will run the commands regardless of |
2329 |
whether there is a file named @file{clean}. |
2330 |
|
2331 |
Since it knows that phony targets do not name actual files that could be |
2332 |
remade from other files, @code{make} skips the implicit rule search for |
2333 |
phony targets (@pxref{Implicit Rules}). This is why declaring a target |
2334 |
phony is good for performance, even if you are not worried about the |
2335 |
actual file existing. |
2336 |
|
2337 |
Thus, you first write the line that states that @code{clean} is a |
2338 |
phony target, then you write the rule, like this: |
2339 |
|
2340 |
@example |
2341 |
@group |
2342 |
.PHONY: clean |
2343 |
clean: |
2344 |
rm *.o temp |
2345 |
@end group |
2346 |
@end example |
2347 |
|
2348 |
Another example of the usefulness of phony targets is in conjunction |
2349 |
with recursive invocations of @code{make} (for more information, see |
2350 |
@ref{Recursion, ,Recursive Use of @code{make}}). In this case the |
2351 |
makefile will often contain a variable which lists a number of |
2352 |
subdirectories to be built. One way to handle this is with one rule |
2353 |
whose command is a shell loop over the subdirectories, like this: |
2354 |
|
2355 |
@example |
2356 |
@group |
2357 |
SUBDIRS = foo bar baz |
2358 |
|
2359 |
subdirs: |
2360 |
for dir in $(SUBDIRS); do \ |
2361 |
$(MAKE) -C $$dir; \ |
2362 |
done |
2363 |
@end group |
2364 |
@end example |
2365 |
|
2366 |
There are a few problems with this method, however. First, any error |
2367 |
detected in a submake is not noted by this rule, so it will continue to |
2368 |
build the rest of the directories even when one fails. This can be |
2369 |
overcome by adding shell commands to note the error and exit, but then |
2370 |
it will do so even if @code{make} is invoked with the @code{-k} option, |
2371 |
which is unfortunate. Second, and perhaps more importantly, you cannot |
2372 |
take advantage of the parallel build capabilities of make using this |
2373 |
method, since there is only one rule. |
2374 |
|
2375 |
By declaring the subdirectories as phony targets (you must do this as |
2376 |
the subdirectory obviously always exists; otherwise it won't be built) |
2377 |
you can remove these problems: |
2378 |
|
2379 |
@example |
2380 |
@group |
2381 |
SUBDIRS = foo bar baz |
2382 |
|
2383 |
.PHONY: subdirs $(SUBDIRS) |
2384 |
|
2385 |
subdirs: $(SUBDIRS) |
2386 |
|
2387 |
$(SUBDIRS): |
2388 |
$(MAKE) -C $@@ |
2389 |
|
2390 |
foo: baz |
2391 |
@end group |
2392 |
@end example |
2393 |
|
2394 |
Here we've also declared that the @file{foo} subdirectory cannot be |
2395 |
built until after the @file{baz} subdirectory is complete; this kind of |
2396 |
relationship declaration is particularly important when attempting |
2397 |
parallel builds. |
2398 |
|
2399 |
A phony target should not be a prerequisite of a real target file; if it |
2400 |
is, its commands are run every time @code{make} goes to update that |
2401 |
file. As long as a phony target is never a prerequisite of a real |
2402 |
target, the phony target commands will be executed only when the phony |
2403 |
target is a specified goal (@pxref{Goals, ,Arguments to Specify the |
2404 |
Goals}). |
2405 |
|
2406 |
Phony targets can have prerequisites. When one directory contains multiple |
2407 |
programs, it is most convenient to describe all of the programs in one |
2408 |
makefile @file{./Makefile}. Since the target remade by default will be the |
2409 |
first one in the makefile, it is common to make this a phony target named |
2410 |
@samp{all} and give it, as prerequisites, all the individual programs. For |
2411 |
example: |
2412 |
|
2413 |
@example |
2414 |
all : prog1 prog2 prog3 |
2415 |
.PHONY : all |
2416 |
|
2417 |
prog1 : prog1.o utils.o |
2418 |
cc -o prog1 prog1.o utils.o |
2419 |
|
2420 |
prog2 : prog2.o |
2421 |
cc -o prog2 prog2.o |
2422 |
|
2423 |
prog3 : prog3.o sort.o utils.o |
2424 |
cc -o prog3 prog3.o sort.o utils.o |
2425 |
@end example |
2426 |
|
2427 |
@noindent |
2428 |
Now you can say just @samp{make} to remake all three programs, or specify |
2429 |
as arguments the ones to remake (as in @samp{make prog1 prog3}). |
2430 |
|
2431 |
When one phony target is a prerequisite of another, it serves as a subroutine |
2432 |
of the other. For example, here @samp{make cleanall} will delete the |
2433 |
object files, the difference files, and the file @file{program}: |
2434 |
|
2435 |
@example |
2436 |
.PHONY: cleanall cleanobj cleandiff |
2437 |
|
2438 |
cleanall : cleanobj cleandiff |
2439 |
rm program |
2440 |
|
2441 |
cleanobj : |
2442 |
rm *.o |
2443 |
|
2444 |
cleandiff : |
2445 |
rm *.diff |
2446 |
@end example |
2447 |
|
2448 |
@node Force Targets, Empty Targets, Phony Targets, Rules |
2449 |
@section Rules without Commands or Prerequisites |
2450 |
@cindex force targets |
2451 |
@cindex targets, force |
2452 |
@cindex @code{FORCE} |
2453 |
@cindex rule, no commands or prerequisites |
2454 |
|
2455 |
If a rule has no prerequisites or commands, and the target of the rule |
2456 |
is a nonexistent file, then @code{make} imagines this target to have |
2457 |
been updated whenever its rule is run. This implies that all targets |
2458 |
depending on this one will always have their commands run. |
2459 |
|
2460 |
An example will illustrate this: |
2461 |
|
2462 |
@example |
2463 |
@group |
2464 |
clean: FORCE |
2465 |
rm $(objects) |
2466 |
FORCE: |
2467 |
@end group |
2468 |
@end example |
2469 |
|
2470 |
Here the target @samp{FORCE} satisfies the special conditions, so the |
2471 |
target @file{clean} that depends on it is forced to run its commands. |
2472 |
There is nothing special about the name @samp{FORCE}, but that is one name |
2473 |
commonly used this way. |
2474 |
|
2475 |
As you can see, using @samp{FORCE} this way has the same results as using |
2476 |
@samp{.PHONY: clean}. |
2477 |
|
2478 |
Using @samp{.PHONY} is more explicit and more efficient. However, |
2479 |
other versions of @code{make} do not support @samp{.PHONY}; thus |
2480 |
@samp{FORCE} appears in many makefiles. @xref{Phony Targets}. |
2481 |
|
2482 |
@node Empty Targets, Special Targets, Force Targets, Rules |
2483 |
@section Empty Target Files to Record Events |
2484 |
@cindex empty targets |
2485 |
@cindex targets, empty |
2486 |
@cindex recording events with empty targets |
2487 |
|
2488 |
The @dfn{empty target} is a variant of the phony target; it is used to hold |
2489 |
commands for an action that you request explicitly from time to time. |
2490 |
Unlike a phony target, this target file can really exist; but the file's |
2491 |
contents do not matter, and usually are empty. |
2492 |
|
2493 |
The purpose of the empty target file is to record, with its |
2494 |
last-modification time, when the rule's commands were last executed. It |
2495 |
does so because one of the commands is a @code{touch} command to update the |
2496 |
target file. |
2497 |
|
2498 |
The empty target file should have some prerequisites (otherwise it |
2499 |
doesn't make sense). When you ask to remake the empty target, the |
2500 |
commands are executed if any prerequisite is more recent than the target; |
2501 |
in other words, if a prerequisite has changed since the last time you |
2502 |
remade the target. Here is an example: |
2503 |
|
2504 |
@example |
2505 |
print: foo.c bar.c |
2506 |
lpr -p $? |
2507 |
touch print |
2508 |
@end example |
2509 |
@cindex @code{print} target |
2510 |
@cindex @code{lpr} (shell command) |
2511 |
@cindex @code{touch} (shell command) |
2512 |
|
2513 |
@noindent |
2514 |
With this rule, @samp{make print} will execute the @code{lpr} command if |
2515 |
either source file has changed since the last @samp{make print}. The |
2516 |
automatic variable @samp{$?} is used to print only those files that have |
2517 |
changed (@pxref{Automatic Variables}). |
2518 |
|
2519 |
@node Special Targets, Multiple Targets, Empty Targets, Rules |
2520 |
@section Special Built-in Target Names |
2521 |
@cindex special targets |
2522 |
@cindex built-in special targets |
2523 |
@cindex targets, built-in special |
2524 |
|
2525 |
Certain names have special meanings if they appear as targets. |
2526 |
|
2527 |
@table @code |
2528 |
@findex .PHONY |
2529 |
@item .PHONY |
2530 |
|
2531 |
The prerequisites of the special target @code{.PHONY} are considered to |
2532 |
be phony targets. When it is time to consider such a target, |
2533 |
@code{make} will run its commands unconditionally, regardless of |
2534 |
whether a file with that name exists or what its last-modification |
2535 |
time is. @xref{Phony Targets, ,Phony Targets}. |
2536 |
|
2537 |
@findex .SUFFIXES |
2538 |
@item .SUFFIXES |
2539 |
|
2540 |
The prerequisites of the special target @code{.SUFFIXES} are the list |
2541 |
of suffixes to be used in checking for suffix rules. |
2542 |
@xref{Suffix Rules, , Old-Fashioned Suffix Rules}. |
2543 |
|
2544 |
@findex .DEFAULT |
2545 |
@item .DEFAULT |
2546 |
|
2547 |
The commands specified for @code{.DEFAULT} are used for any target for |
2548 |
which no rules are found (either explicit rules or implicit rules). |
2549 |
@xref{Last Resort}. If @code{.DEFAULT} commands are specified, every |
2550 |
file mentioned as a prerequisite, but not as a target in a rule, will have |
2551 |
these commands executed on its behalf. @xref{Implicit Rule Search, |
2552 |
,Implicit Rule Search Algorithm}. |
2553 |
|
2554 |
@findex .PRECIOUS |
2555 |
@item .PRECIOUS |
2556 |
@cindex precious targets |
2557 |
@cindex preserving with @code{.PRECIOUS} |
2558 |
|
2559 |
The targets which @code{.PRECIOUS} depends on are given the following |
2560 |
special treatment: if @code{make} is killed or interrupted during the |
2561 |
execution of their commands, the target is not deleted. |
2562 |
@xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the |
2563 |
target is an intermediate file, it will not be deleted after it is no |
2564 |
longer needed, as is normally done. @xref{Chained Rules, ,Chains of |
2565 |
Implicit Rules}. In this latter respect it overlaps with the |
2566 |
@code{.SECONDARY} special target. |
2567 |
|
2568 |
You can also list the target pattern of an implicit rule (such as |
2569 |
@samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS} |
2570 |
to preserve intermediate files created by rules whose target patterns |
2571 |
match that file's name. |
2572 |
|
2573 |
@findex .INTERMEDIATE |
2574 |
@item .INTERMEDIATE |
2575 |
@cindex intermediate targets, explicit |
2576 |
|
2577 |
The targets which @code{.INTERMEDIATE} depends on are treated as |
2578 |
intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}. |
2579 |
@code{.INTERMEDIATE} with no prerequisites has no effect. |
2580 |
|
2581 |
@findex .SECONDARY |
2582 |
@item .SECONDARY |
2583 |
@cindex secondary targets |
2584 |
@cindex preserving with @code{.SECONDARY} |
2585 |
|
2586 |
The targets which @code{.SECONDARY} depends on are treated as |
2587 |
intermediate files, except that they are never automatically deleted. |
2588 |
@xref{Chained Rules, ,Chains of Implicit Rules}. |
2589 |
|
2590 |
@code{.SECONDARY} with no prerequisites causes all targets to be treated |
2591 |
as secondary (i.e., no target is removed because it is considered |
2592 |
intermediate). |
2593 |
|
2594 |
@findex .DELETE_ON_ERROR |
2595 |
@item .DELETE_ON_ERROR |
2596 |
@cindex removing targets on failure |
2597 |
|
2598 |
If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the |
2599 |
makefile, then @code{make} will delete the target of a rule if it has |
2600 |
changed and its commands exit with a nonzero exit status, just as it |
2601 |
does when it receives a signal. @xref{Errors, ,Errors in Commands}. |
2602 |
|
2603 |
@findex .IGNORE |
2604 |
@item .IGNORE |
2605 |
|
2606 |
If you specify prerequisites for @code{.IGNORE}, then @code{make} will |
2607 |
ignore errors in execution of the commands run for those particular |
2608 |
files. The commands for @code{.IGNORE} are not meaningful. |
2609 |
|
2610 |
If mentioned as a target with no prerequisites, @code{.IGNORE} says to |
2611 |
ignore errors in execution of commands for all files. This usage of |
2612 |
@samp{.IGNORE} is supported only for historical compatibility. Since |
2613 |
this affects every command in the makefile, it is not very useful; we |
2614 |
recommend you use the more selective ways to ignore errors in specific |
2615 |
commands. @xref{Errors, ,Errors in Commands}. |
2616 |
|
2617 |
@findex .LOW_RESOLUTION_TIME |
2618 |
@item .LOW_RESOLUTION_TIME |
2619 |
|
2620 |
If you specify prerequisites for @code{.LOW_RESOLUTION_TIME}, |
2621 |
@command{make} assumes that these files are created by commands that |
2622 |
generate low resolution time stamps. The commands for |
2623 |
@code{.LOW_RESOLUTION_TIME} are not meaningful. |
2624 |
|
2625 |
The high resolution file time stamps of many modern hosts lessen the |
2626 |
chance of @command{make} incorrectly concluding that a file is up to |
2627 |
date. Unfortunately, these hosts provide no way to set a high |
2628 |
resolution file time stamp, so commands like @samp{cp -p} that |
2629 |
explicitly set a file's time stamp must discard its subsecond part. If |
2630 |
a file is created by such a command, you should list it as a |
2631 |
prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} does |
2632 |
not mistakenly conclude that the file is out of date. For example: |
2633 |
|
2634 |
@example |
2635 |
@group |
2636 |
.LOW_RESOLUTION_TIME: dst |
2637 |
dst: src |
2638 |
cp -p src dst |
2639 |
@end group |
2640 |
@end example |
2641 |
|
2642 |
Since @samp{cp -p} discards the subsecond part of @file{src}'s time |
2643 |
stamp, @file{dst} is typically slightly older than @file{src} even when |
2644 |
it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes |
2645 |
@command{make} to consider @file{dst} to be up to date if its time stamp |
2646 |
is at the start of the same second that @file{src}'s time stamp is in. |
2647 |
|
2648 |
Due to a limitation of the archive format, archive member time stamps |
2649 |
are always low resolution. You need not list archive members as |
2650 |
prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this |
2651 |
automatically. |
2652 |
|
2653 |
@findex .SILENT |
2654 |
@item .SILENT |
2655 |
|
2656 |
If you specify prerequisites for @code{.SILENT}, then @code{make} will |
2657 |
not print the commands to remake those particular files before executing |
2658 |
them. The commands for @code{.SILENT} are not meaningful. |
2659 |
|
2660 |
If mentioned as a target with no prerequisites, @code{.SILENT} says not |
2661 |
to print any commands before executing them. This usage of |
2662 |
@samp{.SILENT} is supported only for historical compatibility. We |
2663 |
recommend you use the more selective ways to silence specific commands. |
2664 |
@xref{Echoing, ,Command Echoing}. If you want to silence all commands |
2665 |
for a particular run of @code{make}, use the @samp{-s} or |
2666 |
@w{@samp{--silent}} option (@pxref{Options Summary}). |
2667 |
|
2668 |
@findex .EXPORT_ALL_VARIABLES |
2669 |
@item .EXPORT_ALL_VARIABLES |
2670 |
|
2671 |
Simply by being mentioned as a target, this tells @code{make} to |
2672 |
export all variables to child processes by default. |
2673 |
@xref{Variables/Recursion, ,Communicating Variables to a |
2674 |
Sub-@code{make}}. |
2675 |
|
2676 |
@findex .NOTPARALLEL |
2677 |
@item .NOTPARALLEL |
2678 |
@cindex parallel execution, overriding |
2679 |
|
2680 |
If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of |
2681 |
@code{make} will be run serially, even if the @samp{-j} option is |
2682 |
given. Any recursively invoked @code{make} command will still be run in |
2683 |
parallel (unless its makefile contains this target). Any prerequisites |
2684 |
on this target are ignored. |
2685 |
@end table |
2686 |
|
2687 |
Any defined implicit rule suffix also counts as a special target if it |
2688 |
appears as a target, and so does the concatenation of two suffixes, such |
2689 |
as @samp{.c.o}. These targets are suffix rules, an obsolete way of |
2690 |
defining implicit rules (but a way still widely used). In principle, any |
2691 |
target name could be special in this way if you break it in two and add |
2692 |
both pieces to the suffix list. In practice, suffixes normally begin with |
2693 |
@samp{.}, so these special target names also begin with @samp{.}. |
2694 |
@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. |
2695 |
|
2696 |
@node Multiple Targets, Multiple Rules, Special Targets, Rules |
2697 |
@section Multiple Targets in a Rule |
2698 |
@cindex multiple targets |
2699 |
@cindex several targets in a rule |
2700 |
@cindex targets, multiple |
2701 |
@cindex rule, with multiple targets |
2702 |
|
2703 |
A rule with multiple targets is equivalent to writing many rules, each with |
2704 |
one target, and all identical aside from that. The same commands apply to |
2705 |
all the targets, but their effects may vary because you can substitute the |
2706 |
actual target name into the command using @samp{$@@}. The rule contributes |
2707 |
the same prerequisites to all the targets also. |
2708 |
|
2709 |
This is useful in two cases. |
2710 |
|
2711 |
@itemize @bullet |
2712 |
@item |
2713 |
You want just prerequisites, no commands. For example: |
2714 |
|
2715 |
@example |
2716 |
kbd.o command.o files.o: command.h |
2717 |
@end example |
2718 |
|
2719 |
@noindent |
2720 |
gives an additional prerequisite to each of the three object files |
2721 |
mentioned. |
2722 |
|
2723 |
@item |
2724 |
Similar commands work for all the targets. The commands do not need |
2725 |
to be absolutely identical, since the automatic variable @samp{$@@} |
2726 |
can be used to substitute the particular target to be remade into the |
2727 |
commands (@pxref{Automatic Variables}). For example: |
2728 |
|
2729 |
@example |
2730 |
@group |
2731 |
bigoutput littleoutput : text.g |
2732 |
generate text.g -$(subst output,,$@@) > $@@ |
2733 |
@end group |
2734 |
@end example |
2735 |
@findex subst |
2736 |
|
2737 |
@noindent |
2738 |
is equivalent to |
2739 |
|
2740 |
@example |
2741 |
bigoutput : text.g |
2742 |
generate text.g -big > bigoutput |
2743 |
littleoutput : text.g |
2744 |
generate text.g -little > littleoutput |
2745 |
@end example |
2746 |
|
2747 |
@noindent |
2748 |
Here we assume the hypothetical program @code{generate} makes two |
2749 |
types of output, one if given @samp{-big} and one if given |
2750 |
@samp{-little}. |
2751 |
@xref{Text Functions, ,Functions for String Substitution and Analysis}, |
2752 |
for an explanation of the @code{subst} function. |
2753 |
@end itemize |
2754 |
|
2755 |
Suppose you would like to vary the prerequisites according to the target, |
2756 |
much as the variable @samp{$@@} allows you to vary the commands. |
2757 |
You cannot do this with multiple targets in an ordinary rule, but you can |
2758 |
do it with a @dfn{static pattern rule}. |
2759 |
@xref{Static Pattern, ,Static Pattern Rules}. |
2760 |
|
2761 |
@node Multiple Rules, Static Pattern, Multiple Targets, Rules |
2762 |
@section Multiple Rules for One Target |
2763 |
@cindex multiple rules for one target |
2764 |
@cindex several rules for one target |
2765 |
@cindex rule, multiple for one target |
2766 |
@cindex target, multiple rules for one |
2767 |
|
2768 |
One file can be the target of several rules. All the prerequisites |
2769 |
mentioned in all the rules are merged into one list of prerequisites for |
2770 |
the target. If the target is older than any prerequisite from any rule, |
2771 |
the commands are executed. |
2772 |
|
2773 |
There can only be one set of commands to be executed for a file. If |
2774 |
more than one rule gives commands for the same file, @code{make} uses |
2775 |
the last set given and prints an error message. (As a special case, |
2776 |
if the file's name begins with a dot, no error message is printed. |
2777 |
This odd behavior is only for compatibility with other implementations |
2778 |
of @code{make}... you should avoid using it). Occasionally it is |
2779 |
useful to have the same target invoke multiple commands which are |
2780 |
defined in different parts of your makefile; you can use |
2781 |
@dfn{double-colon rules} (@pxref{Double-Colon}) for this. |
2782 |
|
2783 |
An extra rule with just prerequisites can be used to give a few extra |
2784 |
prerequisites to many files at once. For example, makefiles often |
2785 |
have a variable, such as @code{objects}, containing a list of all the |
2786 |
compiler output files in the system being made. An easy way to say |
2787 |
that all of them must be recompiled if @file{config.h} changes is to |
2788 |
write the following: |
2789 |
|
2790 |
@example |
2791 |
objects = foo.o bar.o |
2792 |
foo.o : defs.h |
2793 |
bar.o : defs.h test.h |
2794 |
$(objects) : config.h |
2795 |
@end example |
2796 |
|
2797 |
This could be inserted or taken out without changing the rules that really |
2798 |
specify how to make the object files, making it a convenient form to use if |
2799 |
you wish to add the additional prerequisite intermittently. |
2800 |
|
2801 |
Another wrinkle is that the additional prerequisites could be specified with |
2802 |
a variable that you set with a command argument to @code{make} |
2803 |
(@pxref{Overriding, ,Overriding Variables}). For example, |
2804 |
|
2805 |
@example |
2806 |
@group |
2807 |
extradeps= |
2808 |
$(objects) : $(extradeps) |
2809 |
@end group |
2810 |
@end example |
2811 |
|
2812 |
@noindent |
2813 |
means that the command @samp{make extradeps=foo.h} will consider |
2814 |
@file{foo.h} as a prerequisite of each object file, but plain @samp{make} |
2815 |
will not. |
2816 |
|
2817 |
If none of the explicit rules for a target has commands, then @code{make} |
2818 |
searches for an applicable implicit rule to find some commands |
2819 |
@pxref{Implicit Rules, ,Using Implicit Rules}). |
2820 |
|
2821 |
@node Static Pattern, Double-Colon, Multiple Rules, Rules |
2822 |
@section Static Pattern Rules |
2823 |
@cindex static pattern rule |
2824 |
@cindex rule, static pattern |
2825 |
@cindex pattern rules, static (not implicit) |
2826 |
@cindex varying prerequisites |
2827 |
@cindex prerequisites, varying (static pattern) |
2828 |
|
2829 |
@dfn{Static pattern rules} are rules which specify multiple targets and |
2830 |
construct the prerequisite names for each target based on the target name. |
2831 |
They are more general than ordinary rules with multiple targets because the |
2832 |
targets do not have to have identical prerequisites. Their prerequisites must |
2833 |
be @emph{analogous}, but not necessarily @emph{identical}. |
2834 |
|
2835 |
@menu |
2836 |
* Static Usage:: The syntax of static pattern rules. |
2837 |
* Static versus Implicit:: When are they better than implicit rules? |
2838 |
@end menu |
2839 |
|
2840 |
@node Static Usage, Static versus Implicit, Static Pattern, Static Pattern |
2841 |
@subsection Syntax of Static Pattern Rules |
2842 |
@cindex static pattern rule, syntax of |
2843 |
@cindex pattern rules, static, syntax of |
2844 |
|
2845 |
Here is the syntax of a static pattern rule: |
2846 |
|
2847 |
@example |
2848 |
@var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{} |
2849 |
@var{commands} |
2850 |
@dots{} |
2851 |
@end example |
2852 |
|
2853 |
@noindent |
2854 |
The @var{targets} list specifies the targets that the rule applies to. |
2855 |
The targets can contain wildcard characters, just like the targets of |
2856 |
ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File |
2857 |
Names}). |
2858 |
|
2859 |
@cindex target pattern, static (not implicit) |
2860 |
@cindex stem |
2861 |
The @var{target-pattern} and @var{prereq-patterns} say how to compute the |
2862 |
prerequisites of each target. Each target is matched against the |
2863 |
@var{target-pattern} to extract a part of the target name, called the |
2864 |
@dfn{stem}. This stem is substituted into each of the @var{prereq-patterns} |
2865 |
to make the prerequisite names (one from each @var{prereq-pattern}). |
2866 |
|
2867 |
Each pattern normally contains the character @samp{%} just once. When the |
2868 |
@var{target-pattern} matches a target, the @samp{%} can match any part of |
2869 |
the target name; this part is called the @dfn{stem}. The rest of the |
2870 |
pattern must match exactly. For example, the target @file{foo.o} matches |
2871 |
the pattern @samp{%.o}, with @samp{foo} as the stem. The targets |
2872 |
@file{foo.c} and @file{foo.out} do not match that pattern.@refill |
2873 |
|
2874 |
@cindex prerequisite pattern, static (not implicit) |
2875 |
The prerequisite names for each target are made by substituting the stem |
2876 |
for the @samp{%} in each prerequisite pattern. For example, if one |
2877 |
prerequisite pattern is @file{%.c}, then substitution of the stem |
2878 |
@samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate |
2879 |
to write a prerequisite pattern that does not contain @samp{%}; then this |
2880 |
prerequisite is the same for all targets. |
2881 |
|
2882 |
@cindex @code{%}, quoting in static pattern |
2883 |
@cindex @code{%}, quoting with @code{\} (backslash) |
2884 |
@cindex @code{\} (backslash), to quote @code{%} |
2885 |
@cindex backslash (@code{\}), to quote @code{%} |
2886 |
@cindex quoting @code{%}, in static pattern |
2887 |
@samp{%} characters in pattern rules can be quoted with preceding |
2888 |
backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} |
2889 |
characters can be quoted with more backslashes. Backslashes that quote |
2890 |
@samp{%} characters or other backslashes are removed from the pattern |
2891 |
before it is compared to file names or has a stem substituted into it. |
2892 |
Backslashes that are not in danger of quoting @samp{%} characters go |
2893 |
unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has |
2894 |
@samp{the%weird\} preceding the operative @samp{%} character, and |
2895 |
@samp{pattern\\} following it. The final two backslashes are left alone |
2896 |
because they cannot affect any @samp{%} character.@refill |
2897 |
|
2898 |
Here is an example, which compiles each of @file{foo.o} and @file{bar.o} |
2899 |
from the corresponding @file{.c} file: |
2900 |
|
2901 |
@example |
2902 |
@group |
2903 |
objects = foo.o bar.o |
2904 |
|
2905 |
all: $(objects) |
2906 |
|
2907 |
$(objects): %.o: %.c |
2908 |
$(CC) -c $(CFLAGS) $< -o $@@ |
2909 |
@end group |
2910 |
@end example |
2911 |
|
2912 |
@noindent |
2913 |
Here @samp{$<} is the automatic variable that holds the name of the |
2914 |
prerequisite and @samp{$@@} is the automatic variable that holds the name |
2915 |
of the target; see @ref{Automatic Variables}. |
2916 |
|
2917 |
Each target specified must match the target pattern; a warning is issued |
2918 |
for each target that does not. If you have a list of files, only some of |
2919 |
which will match the pattern, you can use the @code{filter} function to |
2920 |
remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): |
2921 |
|
2922 |
@example |
2923 |
files = foo.elc bar.o lose.o |
2924 |
|
2925 |
$(filter %.o,$(files)): %.o: %.c |
2926 |
$(CC) -c $(CFLAGS) $< -o $@@ |
2927 |
$(filter %.elc,$(files)): %.elc: %.el |
2928 |
emacs -f batch-byte-compile $< |
2929 |
@end example |
2930 |
|
2931 |
@noindent |
2932 |
In this example the result of @samp{$(filter %.o,$(files))} is |
2933 |
@file{bar.o lose.o}, and the first static pattern rule causes each of |
2934 |
these object files to be updated by compiling the corresponding C source |
2935 |
file. The result of @w{@samp{$(filter %.elc,$(files))}} is |
2936 |
@file{foo.elc}, so that file is made from @file{foo.el}.@refill |
2937 |
|
2938 |
Another example shows how to use @code{$*} in static pattern rules: |
2939 |
@vindex $*@r{, and static pattern} |
2940 |
|
2941 |
@example |
2942 |
@group |
2943 |
bigoutput littleoutput : %output : text.g |
2944 |
generate text.g -$* > $@@ |
2945 |
@end group |
2946 |
@end example |
2947 |
|
2948 |
@noindent |
2949 |
When the @code{generate} command is run, @code{$*} will expand to the |
2950 |
stem, either @samp{big} or @samp{little}. |
2951 |
|
2952 |
@node Static versus Implicit, , Static Usage, Static Pattern |
2953 |
@subsection Static Pattern Rules versus Implicit Rules |
2954 |
@cindex rule, static pattern versus implicit |
2955 |
@cindex static pattern rule, versus implicit |
2956 |
|
2957 |
A static pattern rule has much in common with an implicit rule defined as a |
2958 |
pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). |
2959 |
Both have a pattern for the target and patterns for constructing the |
2960 |
names of prerequisites. The difference is in how @code{make} decides |
2961 |
@emph{when} the rule applies. |
2962 |
|
2963 |
An implicit rule @emph{can} apply to any target that matches its pattern, |
2964 |
but it @emph{does} apply only when the target has no commands otherwise |
2965 |
specified, and only when the prerequisites can be found. If more than one |
2966 |
implicit rule appears applicable, only one applies; the choice depends on |
2967 |
the order of rules. |
2968 |
|
2969 |
By contrast, a static pattern rule applies to the precise list of targets |
2970 |
that you specify in the rule. It cannot apply to any other target and it |
2971 |
invariably does apply to each of the targets specified. If two conflicting |
2972 |
rules apply, and both have commands, that's an error. |
2973 |
|
2974 |
The static pattern rule can be better than an implicit rule for these |
2975 |
reasons: |
2976 |
|
2977 |
@itemize @bullet |
2978 |
@item |
2979 |
You may wish to override the usual implicit rule for a few |
2980 |
files whose names cannot be categorized syntactically but |
2981 |
can be given in an explicit list. |
2982 |
|
2983 |
@item |
2984 |
If you cannot be sure of the precise contents of the directories |
2985 |
you are using, you may not be sure which other irrelevant files |
2986 |
might lead @code{make} to use the wrong implicit rule. The choice |
2987 |
might depend on the order in which the implicit rule search is done. |
2988 |
With static pattern rules, there is no uncertainty: each rule applies |
2989 |
to precisely the targets specified. |
2990 |
@end itemize |
2991 |
|
2992 |
@node Double-Colon, Automatic Prerequisites, Static Pattern, Rules |
2993 |
@section Double-Colon Rules |
2994 |
@cindex double-colon rules |
2995 |
@cindex rule, double-colon (@code{::}) |
2996 |
@cindex multiple rules for one target (@code{::}) |
2997 |
@cindex @code{::} rules (double-colon) |
2998 |
|
2999 |
@dfn{Double-colon} rules are rules written with @samp{::} instead of |
3000 |
@samp{:} after the target names. They are handled differently from |
3001 |
ordinary rules when the same target appears in more than one rule. |
3002 |
|
3003 |
When a target appears in multiple rules, all the rules must be the same |
3004 |
type: all ordinary, or all double-colon. If they are double-colon, each |
3005 |
of them is independent of the others. Each double-colon rule's commands |
3006 |
are executed if the target is older than any prerequisites of that rule. |
3007 |
If there are no prerequisites for that rule, its commands are always |
3008 |
executed (even if the target already exists). This can result in |
3009 |
executing none, any, or all of the double-colon rules. |
3010 |
|
3011 |
Double-colon rules with the same target are in fact completely separate |
3012 |
from one another. Each double-colon rule is processed individually, just |
3013 |
as rules with different targets are processed. |
3014 |
|
3015 |
The double-colon rules for a target are executed in the order they appear |
3016 |
in the makefile. However, the cases where double-colon rules really make |
3017 |
sense are those where the order of executing the commands would not matter. |
3018 |
|
3019 |
Double-colon rules are somewhat obscure and not often very useful; they |
3020 |
provide a mechanism for cases in which the method used to update a target |
3021 |
differs depending on which prerequisite files caused the update, and such |
3022 |
cases are rare. |
3023 |
|
3024 |
Each double-colon rule should specify commands; if it does not, an |
3025 |
implicit rule will be used if one applies. |
3026 |
@xref{Implicit Rules, ,Using Implicit Rules}. |
3027 |
|
3028 |
@node Automatic Prerequisites, , Double-Colon, Rules |
3029 |
@section Generating Prerequisites Automatically |
3030 |
@cindex prerequisites, automatic generation |
3031 |
@cindex automatic generation of prerequisites |
3032 |
@cindex generating prerequisites automatically |
3033 |
|
3034 |
In the makefile for a program, many of the rules you need to write often |
3035 |
say only that some object file depends on some header |
3036 |
file. For example, if @file{main.c} uses @file{defs.h} via an |
3037 |
@code{#include}, you would write: |
3038 |
|
3039 |
@example |
3040 |
main.o: defs.h |
3041 |
@end example |
3042 |
|
3043 |
@noindent |
3044 |
You need this rule so that @code{make} knows that it must remake |
3045 |
@file{main.o} whenever @file{defs.h} changes. You can see that for a |
3046 |
large program you would have to write dozens of such rules in your |
3047 |
makefile. And, you must always be very careful to update the makefile |
3048 |
every time you add or remove an @code{#include}. |
3049 |
@cindex @code{#include} |
3050 |
|
3051 |
@cindex @code{-M} (to compiler) |
3052 |
To avoid this hassle, most modern C compilers can write these rules for |
3053 |
you, by looking at the @code{#include} lines in the source files. |
3054 |
Usually this is done with the @samp{-M} option to the compiler. |
3055 |
For example, the command: |
3056 |
|
3057 |
@example |
3058 |
cc -M main.c |
3059 |
@end example |
3060 |
|
3061 |
@noindent |
3062 |
generates the output: |
3063 |
|
3064 |
@example |
3065 |
main.o : main.c defs.h |
3066 |
@end example |
3067 |
|
3068 |
@noindent |
3069 |
Thus you no longer have to write all those rules yourself. |
3070 |
The compiler will do it for you. |
3071 |
|
3072 |
Note that such a prerequisite constitutes mentioning @file{main.o} in a |
3073 |
makefile, so it can never be considered an intermediate file by implicit |
3074 |
rule search. This means that @code{make} won't ever remove the file |
3075 |
after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}. |
3076 |
|
3077 |
@cindex @code{make depend} |
3078 |
With old @code{make} programs, it was traditional practice to use this |
3079 |
compiler feature to generate prerequisites on demand with a command like |
3080 |
@samp{make depend}. That command would create a file @file{depend} |
3081 |
containing all the automatically-generated prerequisites; then the |
3082 |
makefile could use @code{include} to read them in (@pxref{Include}). |
3083 |
|
3084 |
In GNU @code{make}, the feature of remaking makefiles makes this |
3085 |
practice obsolete---you need never tell @code{make} explicitly to |
3086 |
regenerate the prerequisites, because it always regenerates any makefile |
3087 |
that is out of date. @xref{Remaking Makefiles}. |
3088 |
|
3089 |
The practice we recommend for automatic prerequisite generation is to have |
3090 |
one makefile corresponding to each source file. For each source file |
3091 |
@file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists |
3092 |
what files the object file @file{@var{name}.o} depends on. That way |
3093 |
only the source files that have changed need to be rescanned to produce |
3094 |
the new prerequisites. |
3095 |
|
3096 |
Here is the pattern rule to generate a file of prerequisites (i.e., a makefile) |
3097 |
called @file{@var{name}.d} from a C source file called @file{@var{name}.c}: |
3098 |
|
3099 |
@smallexample |
3100 |
@group |
3101 |
%.d: %.c |
3102 |
@set -e; rm -f $@@; \ |
3103 |
$(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \ |
3104 |
sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \ |
3105 |
rm -f $@@.$$$$ |
3106 |
@end group |
3107 |
@end smallexample |
3108 |
|
3109 |
@noindent |
3110 |
@xref{Pattern Rules}, for information on defining pattern rules. The |
3111 |
@samp{-e} flag to the shell causes it to exit immediately if the |
3112 |
@code{$(CC)} command (or any other command) fails (exits with a |
3113 |
nonzero status). |
3114 |
@cindex @code{-e} (shell flag) |
3115 |
|
3116 |
@cindex @code{-MM} (to GNU compiler) |
3117 |
With the GNU C compiler, you may wish to use the @samp{-MM} flag instead |
3118 |
of @samp{-M}. This omits prerequisites on system header files. |
3119 |
@xref{Preprocessor Options, , Options Controlling the Preprocessor, |
3120 |
gcc.info, Using GNU CC}, for details. |
3121 |
|
3122 |
@cindex @code{sed} (shell command) |
3123 |
The purpose of the @code{sed} command is to translate (for example): |
3124 |
|
3125 |
@example |
3126 |
main.o : main.c defs.h |
3127 |
@end example |
3128 |
|
3129 |
@noindent |
3130 |
into: |
3131 |
|
3132 |
@example |
3133 |
main.o main.d : main.c defs.h |
3134 |
@end example |
3135 |
|
3136 |
@noindent |
3137 |
@cindex @code{.d} |
3138 |
This makes each @samp{.d} file depend on all the source and header files |
3139 |
that the corresponding @samp{.o} file depends on. @code{make} then |
3140 |
knows it must regenerate the prerequisites whenever any of the source or |
3141 |
header files changes. |
3142 |
|
3143 |
Once you've defined the rule to remake the @samp{.d} files, |
3144 |
you then use the @code{include} directive to read them all in. |
3145 |
@xref{Include}. For example: |
3146 |
|
3147 |
@example |
3148 |
@group |
3149 |
sources = foo.c bar.c |
3150 |
|
3151 |
include $(sources:.c=.d) |
3152 |
@end group |
3153 |
@end example |
3154 |
|
3155 |
@noindent |
3156 |
(This example uses a substitution variable reference to translate the |
3157 |
list of source files @samp{foo.c bar.c} into a list of prerequisite |
3158 |
makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full |
3159 |
information on substitution references.) Since the @samp{.d} files are |
3160 |
makefiles like any others, @code{make} will remake them as necessary |
3161 |
with no further work from you. @xref{Remaking Makefiles}. |
3162 |
|
3163 |
Note that the @samp{.d} files contain target definitions; you should |
3164 |
be sure to place the @code{include} directive @emph{after} the first, |
3165 |
default target in your makefiles or run the risk of having a random |
3166 |
object file become the default target. |
3167 |
@xref{How Make Works}. |
3168 |
|
3169 |
@node Commands, Using Variables, Rules, Top |
3170 |
@chapter Writing the Commands in Rules |
3171 |
@cindex commands, how to write |
3172 |
@cindex rule commands |
3173 |
@cindex writing rule commands |
3174 |
|
3175 |
The commands of a rule consist of shell command lines to be executed one |
3176 |
by one. Each command line must start with a tab, except that the first |
3177 |
command line may be attached to the target-and-prerequisites line with a |
3178 |
semicolon in between. Blank lines and lines of just comments may appear |
3179 |
among the command lines; they are ignored. (But beware, an apparently |
3180 |
``blank'' line that begins with a tab is @emph{not} blank! It is an |
3181 |
empty command; @pxref{Empty Commands}.) |
3182 |
|
3183 |
Users use many different shell programs, but commands in makefiles are |
3184 |
always interpreted by @file{/bin/sh} unless the makefile specifies |
3185 |
otherwise. @xref{Execution, ,Command Execution}. |
3186 |
|
3187 |
@cindex comments, in commands |
3188 |
@cindex commands, comments in |
3189 |
@cindex @code{#} (comments), in commands |
3190 |
The shell that is in use determines whether comments can be written on |
3191 |
command lines, and what syntax they use. When the shell is |
3192 |
@file{/bin/sh}, a @samp{#} starts a comment that extends to the end of |
3193 |
the line. The @samp{#} does not have to be at the beginning of a line. |
3194 |
Text on a line before a @samp{#} is not part of the comment. |
3195 |
|
3196 |
@menu |
3197 |
* Echoing:: How to control when commands are echoed. |
3198 |
* Execution:: How commands are executed. |
3199 |
* Parallel:: How commands can be executed in parallel. |
3200 |
* Errors:: What happens after a command execution error. |
3201 |
* Interrupts:: What happens when a command is interrupted. |
3202 |
* Recursion:: Invoking @code{make} from makefiles. |
3203 |
* Sequences:: Defining canned sequences of commands. |
3204 |
* Empty Commands:: Defining useful, do-nothing commands. |
3205 |
@end menu |
3206 |
|
3207 |
@node Echoing, Execution, Commands, Commands |
3208 |
@section Command Echoing |
3209 |
@cindex echoing of commands |
3210 |
@cindex silent operation |
3211 |
@cindex @code{@@} (in commands) |
3212 |
@cindex commands, echoing |
3213 |
@cindex printing of commands |
3214 |
|
3215 |
Normally @code{make} prints each command line before it is executed. |
3216 |
We call this @dfn{echoing} because it gives the appearance that you |
3217 |
are typing the commands yourself. |
3218 |
|
3219 |
When a line starts with @samp{@@}, the echoing of that line is suppressed. |
3220 |
The @samp{@@} is discarded before the command is passed to the shell. |
3221 |
Typically you would use this for a command whose only effect is to print |
3222 |
something, such as an @code{echo} command to indicate progress through |
3223 |
the makefile: |
3224 |
|
3225 |
@example |
3226 |
@@echo About to make distribution files |
3227 |
@end example |
3228 |
|
3229 |
@cindex @code{-n} |
3230 |
@cindex @code{--just-print} |
3231 |
@cindex @code{--dry-run} |
3232 |
@cindex @code{--recon} |
3233 |
When @code{make} is given the flag @samp{-n} or @samp{--just-print} |
3234 |
it only echoes commands, it won't execute them. @xref{Options Summary, |
3235 |
,Summary of Options}. In this case and only this case, even the |
3236 |
commands starting with @samp{@@} are printed. This flag is useful for |
3237 |
finding out which commands @code{make} thinks are necessary without |
3238 |
actually doing them. |
3239 |
|
3240 |
@cindex @code{-s} |
3241 |
@cindex @code{--silent} |
3242 |
@cindex @code{--quiet} |
3243 |
@findex .SILENT |
3244 |
The @samp{-s} or @samp{--silent} |
3245 |
flag to @code{make} prevents all echoing, as if all commands |
3246 |
started with @samp{@@}. A rule in the makefile for the special target |
3247 |
@code{.SILENT} without prerequisites has the same effect |
3248 |
(@pxref{Special Targets, ,Special Built-in Target Names}). |
3249 |
@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill |
3250 |
|
3251 |
@node Execution, Parallel, Echoing, Commands |
3252 |
@section Command Execution |
3253 |
@cindex commands, execution |
3254 |
@cindex execution, of commands |
3255 |
@cindex shell command, execution |
3256 |
@vindex SHELL @r{(command execution)} |
3257 |
|
3258 |
When it is time to execute commands to update a target, they are executed |
3259 |
by making a new subshell for each line. (In practice, @code{make} may |
3260 |
take shortcuts that do not affect the results.) |
3261 |
|
3262 |
@cindex @code{cd} (shell command) |
3263 |
@strong{Please note:} this implies that shell commands such as @code{cd} |
3264 |
that set variables local to each process will not affect the following |
3265 |
command lines. @footnote{On MS-DOS, the value of current working |
3266 |
directory is @strong{global}, so changing it @emph{will} affect the |
3267 |
following command lines on those systems.} If you want to use @code{cd} |
3268 |
to affect the next command, put the two on a single line with a |
3269 |
semicolon between them. Then @code{make} will consider them a single |
3270 |
command and pass them, together, to a shell which will execute them in |
3271 |
sequence. For example: |
3272 |
|
3273 |
@example |
3274 |
foo : bar/lose |
3275 |
cd bar; gobble lose > ../foo |
3276 |
@end example |
3277 |
|
3278 |
@cindex commands, backslash (@code{\}) in |
3279 |
@cindex commands, quoting newlines in |
3280 |
@cindex backslash (@code{\}), in commands |
3281 |
@cindex @code{\} (backslash), in commands |
3282 |
@cindex quoting newline, in commands |
3283 |
@cindex newline, quoting, in commands |
3284 |
If you would like to split a single shell command into multiple lines of |
3285 |
text, you must use a backslash at the end of all but the last subline. |
3286 |
Such a sequence of lines is combined into a single line, by deleting the |
3287 |
backslash-newline sequences, before passing it to the shell. Thus, the |
3288 |
following is equivalent to the preceding example: |
3289 |
|
3290 |
@example |
3291 |
@group |
3292 |
foo : bar/lose |
3293 |
cd bar; \ |
3294 |
gobble lose > ../foo |
3295 |
@end group |
3296 |
@end example |
3297 |
|
3298 |
@vindex SHELL |
3299 |
The program used as the shell is taken from the variable @code{SHELL}. |
3300 |
By default, the program @file{/bin/sh} is used. |
3301 |
|
3302 |
@vindex COMSPEC |
3303 |
On MS-DOS, if @code{SHELL} is not set, the value of the variable |
3304 |
@code{COMSPEC} (which is always set) is used instead. |
3305 |
|
3306 |
@cindex @code{SHELL}, MS-DOS specifics |
3307 |
The processing of lines that set the variable @code{SHELL} in Makefiles |
3308 |
is different on MS-DOS. The stock shell, @file{command.com}, is |
3309 |
ridiculously limited in its functionality and many users of @code{make} |
3310 |
tend to install a replacement shell. Therefore, on MS-DOS, @code{make} |
3311 |
examines the value of @code{SHELL}, and changes its behavior based on |
3312 |
whether it points to a Unix-style or DOS-style shell. This allows |
3313 |
reasonable functionality even if @code{SHELL} points to |
3314 |
@file{command.com}. |
3315 |
|
3316 |
If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS |
3317 |
additionally checks whether that shell can indeed be found; if not, it |
3318 |
ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make} |
3319 |
searches for the shell in the following places: |
3320 |
|
3321 |
@enumerate |
3322 |
@item |
3323 |
In the precise place pointed to by the value of @code{SHELL}. For |
3324 |
example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make} |
3325 |
will look in the directory @file{/bin} on the current drive. |
3326 |
|
3327 |
@item |
3328 |
In the current directory. |
3329 |
|
3330 |
@item |
3331 |
In each of the directories in the @code{PATH} variable, in order. |
3332 |
|
3333 |
@end enumerate |
3334 |
|
3335 |
In every directory it examines, @code{make} will first look for the |
3336 |
specific file (@file{sh} in the example above). If this is not found, |
3337 |
it will also look in that directory for that file with one of the known |
3338 |
extensions which identify executable files. For example @file{.exe}, |
3339 |
@file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others. |
3340 |
|
3341 |
If any of these attempts is successful, the value of @code{SHELL} will |
3342 |
be set to the full pathname of the shell as found. However, if none of |
3343 |
these is found, the value of @code{SHELL} will not be changed, and thus |
3344 |
the line that sets it will be effectively ignored. This is so |
3345 |
@code{make} will only support features specific to a Unix-style shell if |
3346 |
such a shell is actually installed on the system where @code{make} runs. |
3347 |
|
3348 |
Note that this extended search for the shell is limited to the cases |
3349 |
where @code{SHELL} is set from the Makefile; if it is set in the |
3350 |
environment or command line, you are expected to set it to the full |
3351 |
pathname of the shell, exactly as things are on Unix. |
3352 |
|
3353 |
The effect of the above DOS-specific processing is that a Makefile that |
3354 |
says @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work |
3355 |
on MS-DOS unaltered if you have e.g. @file{sh.exe} installed in some |
3356 |
directory along your @code{PATH}. |
3357 |
|
3358 |
@cindex environment, @code{SHELL} in |
3359 |
Unlike most variables, the variable @code{SHELL} is never set from the |
3360 |
environment. This is because the @code{SHELL} environment variable is |
3361 |
used to specify your personal choice of shell program for interactive |
3362 |
use. It would be very bad for personal choices like this to affect the |
3363 |
functioning of makefiles. @xref{Environment, ,Variables from the |
3364 |
Environment}. However, on MS-DOS and MS-Windows the value of |
3365 |
@code{SHELL} in the environment @strong{is} used, since on those systems |
3366 |
most users do not set this variable, and therefore it is most likely set |
3367 |
specifically to be used by @code{make}. On MS-DOS, if the setting of |
3368 |
@code{SHELL} is not suitable for @code{make}, you can set the variable |
3369 |
@code{MAKESHELL} to the shell that @code{make} should use; this will |
3370 |
override the value of @code{SHELL}. |
3371 |
|
3372 |
@node Parallel, Errors, Execution, Commands |
3373 |
@section Parallel Execution |
3374 |
@cindex commands, execution in parallel |
3375 |
@cindex parallel execution |
3376 |
@cindex execution, in parallel |
3377 |
@cindex job slots |
3378 |
@cindex @code{-j} |
3379 |
@cindex @code{--jobs} |
3380 |
|
3381 |
GNU @code{make} knows how to execute several commands at once. |
3382 |
Normally, @code{make} will execute only one command at a time, waiting |
3383 |
for it to finish before executing the next. However, the @samp{-j} or |
3384 |
@samp{--jobs} option tells @code{make} to execute many commands |
3385 |
simultaneously.@refill |
3386 |
|
3387 |
On MS-DOS, the @samp{-j} option has no effect, since that system doesn't |
3388 |
support multi-processing. |
3389 |
|
3390 |
If the @samp{-j} option is followed by an integer, this is the number of |
3391 |
commands to execute at once; this is called the number of @dfn{job slots}. |
3392 |
If there is nothing looking like an integer after the @samp{-j} option, |
3393 |
there is no limit on the number of job slots. The default number of job |
3394 |
slots is one, which means serial execution (one thing at a time). |
3395 |
|
3396 |
One unpleasant consequence of running several commands simultaneously is |
3397 |
that output generated by the commands appears whenever each command |
3398 |
sends it, so messages from different commands may be interspersed. |
3399 |
|
3400 |
Another problem is that two processes cannot both take input from the |
3401 |
same device; so to make sure that only one command tries to take input |
3402 |
from the terminal at once, @code{make} will invalidate the standard |
3403 |
input streams of all but one running command. This means that |
3404 |
attempting to read from standard input will usually be a fatal error (a |
3405 |
@samp{Broken pipe} signal) for most child processes if there are |
3406 |
several. |
3407 |
@cindex broken pipe |
3408 |
@cindex standard input |
3409 |
|
3410 |
It is unpredictable which command will have a valid standard input stream |
3411 |
(which will come from the terminal, or wherever you redirect the standard |
3412 |
input of @code{make}). The first command run will always get it first, and |
3413 |
the first command started after that one finishes will get it next, and so |
3414 |
on. |
3415 |
|
3416 |
We will change how this aspect of @code{make} works if we find a better |
3417 |
alternative. In the mean time, you should not rely on any command using |
3418 |
standard input at all if you are using the parallel execution feature; but |
3419 |
if you are not using this feature, then standard input works normally in |
3420 |
all commands. |
3421 |
|
3422 |
Finally, handling recursive @code{make} invocations raises issues. For |
3423 |
more information on this, see |
3424 |
@ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. |
3425 |
|
3426 |
If a command fails (is killed by a signal or exits with a nonzero |
3427 |
status), and errors are not ignored for that command |
3428 |
(@pxref{Errors, ,Errors in Commands}), |
3429 |
the remaining command lines to remake the same target will not be run. |
3430 |
If a command fails and the @samp{-k} or @samp{--keep-going} |
3431 |
option was not given |
3432 |
(@pxref{Options Summary, ,Summary of Options}), |
3433 |
@code{make} aborts execution. If make |
3434 |
terminates for any reason (including a signal) with child processes |
3435 |
running, it waits for them to finish before actually exiting.@refill |
3436 |
|
3437 |
@cindex load average |
3438 |
@cindex limiting jobs based on load |
3439 |
@cindex jobs, limiting based on load |
3440 |
@cindex @code{-l} (load average) |
3441 |
@cindex @code{--max-load} |
3442 |
@cindex @code{--load-average} |
3443 |
When the system is heavily loaded, you will probably want to run fewer jobs |
3444 |
than when it is lightly loaded. You can use the @samp{-l} option to tell |
3445 |
@code{make} to limit the number of jobs to run at once, based on the load |
3446 |
average. The @samp{-l} or @samp{--max-load} |
3447 |
option is followed by a floating-point number. For |
3448 |
example, |
3449 |
|
3450 |
@example |
3451 |
-l 2.5 |
3452 |
@end example |
3453 |
|
3454 |
@noindent |
3455 |
will not let @code{make} start more than one job if the load average is |
3456 |
above 2.5. The @samp{-l} option with no following number removes the |
3457 |
load limit, if one was given with a previous @samp{-l} option.@refill |
3458 |
|
3459 |
More precisely, when @code{make} goes to start up a job, and it already has |
3460 |
at least one job running, it checks the current load average; if it is not |
3461 |
lower than the limit given with @samp{-l}, @code{make} waits until the load |
3462 |
average goes below that limit, or until all the other jobs finish. |
3463 |
|
3464 |
By default, there is no load limit. |
3465 |
|
3466 |
@node Errors, Interrupts, Parallel, Commands |
3467 |
@section Errors in Commands |
3468 |
@cindex errors (in commands) |
3469 |
@cindex commands, errors in |
3470 |
@cindex exit status (errors) |
3471 |
|
3472 |
After each shell command returns, @code{make} looks at its exit status. |
3473 |
If the command completed successfully, the next command line is executed |
3474 |
in a new shell; after the last command line is finished, the rule is |
3475 |
finished. |
3476 |
|
3477 |
If there is an error (the exit status is nonzero), @code{make} gives up on |
3478 |
the current rule, and perhaps on all rules. |
3479 |
|
3480 |
Sometimes the failure of a certain command does not indicate a problem. |
3481 |
For example, you may use the @code{mkdir} command to ensure that a |
3482 |
directory exists. If the directory already exists, @code{mkdir} will |
3483 |
report an error, but you probably want @code{make} to continue regardless. |
3484 |
|
3485 |
@cindex @code{-} (in commands) |
3486 |
To ignore errors in a command line, write a @samp{-} at the beginning of |
3487 |
the line's text (after the initial tab). The @samp{-} is discarded before |
3488 |
the command is passed to the shell for execution. |
3489 |
|
3490 |
For example, |
3491 |
|
3492 |
@example |
3493 |
@group |
3494 |
clean: |
3495 |
-rm -f *.o |
3496 |
@end group |
3497 |
@end example |
3498 |
@cindex @code{rm} (shell command) |
3499 |
|
3500 |
@noindent |
3501 |
This causes @code{rm} to continue even if it is unable to remove a file. |
3502 |
|
3503 |
@cindex @code{-i} |
3504 |
@cindex @code{--ignore-errors} |
3505 |
@findex .IGNORE |
3506 |
When you run @code{make} with the @samp{-i} or @samp{--ignore-errors} |
3507 |
flag, errors are ignored in all commands of all rules. A rule in the |
3508 |
makefile for the special target @code{.IGNORE} has the same effect, if |
3509 |
there are no prerequisites. These ways of ignoring errors are obsolete |
3510 |
because @samp{-} is more flexible. |
3511 |
|
3512 |
When errors are to be ignored, because of either a @samp{-} or the |
3513 |
@samp{-i} flag, @code{make} treats an error return just like success, |
3514 |
except that it prints out a message that tells you the status code |
3515 |
the command exited with, and says that the error has been ignored. |
3516 |
|
3517 |
When an error happens that @code{make} has not been told to ignore, |
3518 |
it implies that the current target cannot be correctly remade, and neither |
3519 |
can any other that depends on it either directly or indirectly. No further |
3520 |
commands will be executed for these targets, since their preconditions |
3521 |
have not been achieved. |
3522 |
|
3523 |
|
3524 |
@cindex @code{-k} |
3525 |
@cindex @code{--keep-going} |
3526 |
Normally @code{make} gives up immediately in this circumstance, returning a |
3527 |
nonzero status. However, if the @samp{-k} or @samp{--keep-going} |
3528 |
flag is specified, @code{make} |
3529 |
continues to consider the other prerequisites of the pending targets, |
3530 |
remaking them if necessary, before it gives up and returns nonzero status. |
3531 |
For example, after an error in compiling one object file, @samp{make -k} |
3532 |
will continue compiling other object files even though it already knows |
3533 |
that linking them will be impossible. @xref{Options Summary, ,Summary of Options}. |
3534 |
|
3535 |
The usual behavior assumes that your purpose is to get the specified |
3536 |
targets up to date; once @code{make} learns that this is impossible, it |
3537 |
might as well report the failure immediately. The @samp{-k} option says |
3538 |
that the real purpose is to test as many of the changes made in the |
3539 |
program as possible, perhaps to find several independent problems so |
3540 |
that you can correct them all before the next attempt to compile. This |
3541 |
is why Emacs' @code{compile} command passes the @samp{-k} flag by |
3542 |
default. |
3543 |
@cindex Emacs (@code{M-x compile}) |
3544 |
|
3545 |
@findex .DELETE_ON_ERROR |
3546 |
@cindex deletion of target files |
3547 |
@cindex removal of target files |
3548 |
@cindex target, deleting on error |
3549 |
Usually when a command fails, if it has changed the target file at all, |
3550 |
the file is corrupted and cannot be used---or at least it is not |
3551 |
completely updated. Yet the file's time stamp says that it is now up to |
3552 |
date, so the next time @code{make} runs, it will not try to update that |
3553 |
file. The situation is just the same as when the command is killed by a |
3554 |
signal; @pxref{Interrupts}. So generally the right thing to do is to |
3555 |
delete the target file if the command fails after beginning to change |
3556 |
the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears |
3557 |
as a target. This is almost always what you want @code{make} to do, but |
3558 |
it is not historical practice; so for compatibility, you must explicitly |
3559 |
request it. |
3560 |
|
3561 |
@node Interrupts, Recursion, Errors, Commands |
3562 |
@section Interrupting or Killing @code{make} |
3563 |
@cindex interrupt |
3564 |
@cindex signal |
3565 |
@cindex deletion of target files |
3566 |
@cindex removal of target files |
3567 |
@cindex target, deleting on interrupt |
3568 |
@cindex killing (interruption) |
3569 |
|
3570 |
If @code{make} gets a fatal signal while a command is executing, it may |
3571 |
delete the target file that the command was supposed to update. This is |
3572 |
done if the target file's last-modification time has changed since |
3573 |
@code{make} first checked it. |
3574 |
|
3575 |
The purpose of deleting the target is to make sure that it is remade from |
3576 |
scratch when @code{make} is next run. Why is this? Suppose you type |
3577 |
@kbd{Ctrl-c} while a compiler is running, and it has begun to write an |
3578 |
object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting |
3579 |
in an incomplete file whose last-modification time is newer than the source |
3580 |
file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal |
3581 |
and deletes this incomplete file. If @code{make} did not do this, the next |
3582 |
invocation of @code{make} would think that @file{foo.o} did not require |
3583 |
updating---resulting in a strange error message from the linker when it |
3584 |
tries to link an object file half of which is missing. |
3585 |
|
3586 |
@findex .PRECIOUS |
3587 |
You can prevent the deletion of a target file in this way by making the |
3588 |
special target @code{.PRECIOUS} depend on it. Before remaking a target, |
3589 |
@code{make} checks to see whether it appears on the prerequisites of |
3590 |
@code{.PRECIOUS}, and thereby decides whether the target should be deleted |
3591 |
if a signal happens. Some reasons why you might do this are that the |
3592 |
target is updated in some atomic fashion, or exists only to record a |
3593 |
modification-time (its contents do not matter), or must exist at all |
3594 |
times to prevent other sorts of trouble. |
3595 |
|
3596 |
@node Recursion, Sequences, Interrupts, Commands |
3597 |
@section Recursive Use of @code{make} |
3598 |
@cindex recursion |
3599 |
@cindex subdirectories, recursion for |
3600 |
|
3601 |
Recursive use of @code{make} means using @code{make} as a command in a |
3602 |
makefile. This technique is useful when you want separate makefiles for |
3603 |
various subsystems that compose a larger system. For example, suppose you |
3604 |
have a subdirectory @file{subdir} which has its own makefile, and you would |
3605 |
like the containing directory's makefile to run @code{make} on the |
3606 |
subdirectory. You can do it by writing this: |
3607 |
|
3608 |
@example |
3609 |
subsystem: |
3610 |
cd subdir && $(MAKE) |
3611 |
@end example |
3612 |
|
3613 |
@noindent |
3614 |
or, equivalently, this (@pxref{Options Summary, ,Summary of Options}): |
3615 |
|
3616 |
@example |
3617 |
subsystem: |
3618 |
$(MAKE) -C subdir |
3619 |
@end example |
3620 |
@cindex @code{-C} |
3621 |
@cindex @code{--directory} |
3622 |
|
3623 |
You can write recursive @code{make} commands just by copying this example, |
3624 |
but there are many things to know about how they work and why, and about |
3625 |
how the sub-@code{make} relates to the top-level @code{make}. You may |
3626 |
also find it useful to declare targets that invoke recursive |
3627 |
@code{make} commands as @samp{.PHONY} (for more discussion on when |
3628 |
this is useful, see @ref{Phony Targets}). |
3629 |
|
3630 |
@vindex @code{CURDIR} |
3631 |
For your convenience, when GNU @code{make} starts (after it has |
3632 |
processed any @code{-C} options) it sets the variable @code{CURDIR} to |
3633 |
the pathname of the current working directory. This value is never |
3634 |
touched by @code{make} again: in particular note that if you include |
3635 |
files from other directories the value of @code{CURDIR} does not |
3636 |
change. The value has the same precedence it would have if it were |
3637 |
set in the makefile (by default, an environment variable @code{CURDIR} |
3638 |
will not override this value). Note that setting this variable has no |
3639 |
impact on the operation of @code{make} (it does not cause @code{make} |
3640 |
to change its working directory, for example). |
3641 |
|
3642 |
@menu |
3643 |
* MAKE Variable:: The special effects of using @samp{$(MAKE)}. |
3644 |
* Variables/Recursion:: How to communicate variables to a sub-@code{make}. |
3645 |
* Options/Recursion:: How to communicate options to a sub-@code{make}. |
3646 |
* -w Option:: How the @samp{-w} or @samp{--print-directory} option |
3647 |
helps debug use of recursive @code{make} commands. |
3648 |
@end menu |
3649 |
|
3650 |
@node MAKE Variable, Variables/Recursion, Recursion, Recursion |
3651 |
@subsection How the @code{MAKE} Variable Works |
3652 |
@vindex MAKE |
3653 |
@cindex recursion, and @code{MAKE} variable |
3654 |
|
3655 |
Recursive @code{make} commands should always use the variable @code{MAKE}, |
3656 |
not the explicit command name @samp{make}, as shown here: |
3657 |
|
3658 |
@example |
3659 |
@group |
3660 |
subsystem: |
3661 |
cd subdir && $(MAKE) |
3662 |
@end group |
3663 |
@end example |
3664 |
|
3665 |
The value of this variable is the file name with which @code{make} was |
3666 |
invoked. If this file name was @file{/bin/make}, then the command executed |
3667 |
is @samp{cd subdir && /bin/make}. If you use a special version of |
3668 |
@code{make} to run the top-level makefile, the same special version will be |
3669 |
executed for recursive invocations. |
3670 |
@cindex @code{cd} (shell command) |
3671 |
|
3672 |
@cindex +, and commands |
3673 |
As a special feature, using the variable @code{MAKE} in the commands of |
3674 |
a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n} |
3675 |
(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option. |
3676 |
Using the @code{MAKE} variable has the same effect as using a @samp{+} |
3677 |
character at the beginning of the command line. @xref{Instead of |
3678 |
Execution, ,Instead of Executing the Commands}.@refill |
3679 |
|
3680 |
Consider the command @samp{make -t} in the above example. (The |
3681 |
@samp{-t} option marks targets as up to date without actually running |
3682 |
any commands; see @ref{Instead of Execution}.) Following the usual |
3683 |
definition of @samp{-t}, a @samp{make -t} command in the example would |
3684 |
create a file named @file{subsystem} and do nothing else. What you |
3685 |
really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would |
3686 |
require executing the command, and @samp{-t} says not to execute |
3687 |
commands.@refill |
3688 |
@cindex @code{-t}, and recursion |
3689 |
@cindex recursion, and @code{-t} |
3690 |
@cindex @code{--touch}, and recursion |
3691 |
|
3692 |
The special feature makes this do what you want: whenever a command |
3693 |
line of a rule contains the variable @code{MAKE}, the flags @samp{-t}, |
3694 |
@samp{-n} and @samp{-q} do not apply to that line. Command lines |
3695 |
containing @code{MAKE} are executed normally despite the presence of a |
3696 |
flag that causes most commands not to be run. The usual |
3697 |
@code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make} |
3698 |
(@pxref{Options/Recursion, ,Communicating Options to a |
3699 |
Sub-@code{make}}), so your request to touch the files, or print the |
3700 |
commands, is propagated to the subsystem.@refill |
3701 |
|
3702 |
@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion |
3703 |
@subsection Communicating Variables to a Sub-@code{make} |
3704 |
@cindex sub-@code{make} |
3705 |
@cindex environment, and recursion |
3706 |
@cindex exporting variables |
3707 |
@cindex variables, environment |
3708 |
@cindex variables, exporting |
3709 |
@cindex recursion, and environment |
3710 |
@cindex recursion, and variables |
3711 |
|
3712 |
Variable values of the top-level @code{make} can be passed to the |
3713 |
sub-@code{make} through the environment by explicit request. These |
3714 |
variables are defined in the sub-@code{make} as defaults, but do not |
3715 |
override what is specified in the makefile used by the sub-@code{make} |
3716 |
makefile unless you use the @samp{-e} switch (@pxref{Options Summary, |
3717 |
,Summary of Options}).@refill |
3718 |
|
3719 |
To pass down, or @dfn{export}, a variable, @code{make} adds the variable |
3720 |
and its value to the environment for running each command. The |
3721 |
sub-@code{make}, in turn, uses the environment to initialize its table |
3722 |
of variable values. @xref{Environment, ,Variables from the |
3723 |
Environment}. |
3724 |
|
3725 |
Except by explicit request, @code{make} exports a variable only if it |
3726 |
is either defined in the environment initially or set on the command |
3727 |
line, and if its name consists only of letters, numbers, and underscores. |
3728 |
Some shells cannot cope with environment variable names consisting of |
3729 |
characters other than letters, numbers, and underscores. |
3730 |
|
3731 |
The special variables @code{SHELL} and @code{MAKEFLAGS} are always |
3732 |
exported (unless you unexport them). |
3733 |
@code{MAKEFILES} is exported if you set it to anything. |
3734 |
|
3735 |
@code{make} automatically passes down variable values that were defined |
3736 |
on the command line, by putting them in the @code{MAKEFLAGS} variable. |
3737 |
@iftex |
3738 |
See the next section. |
3739 |
@end iftex |
3740 |
@ifinfo |
3741 |
@xref{Options/Recursion}. |
3742 |
@end ifinfo |
3743 |
|
3744 |
Variables are @emph{not} normally passed down if they were created by |
3745 |
default by @code{make} (@pxref{Implicit Variables, ,Variables Used by |
3746 |
Implicit Rules}). The sub-@code{make} will define these for |
3747 |
itself.@refill |
3748 |
|
3749 |
@findex export |
3750 |
If you want to export specific variables to a sub-@code{make}, use the |
3751 |
@code{export} directive, like this: |
3752 |
|
3753 |
@example |
3754 |
export @var{variable} @dots{} |
3755 |
@end example |
3756 |
|
3757 |
@noindent |
3758 |
@findex unexport |
3759 |
If you want to @emph{prevent} a variable from being exported, use the |
3760 |
@code{unexport} directive, like this: |
3761 |
|
3762 |
@example |
3763 |
unexport @var{variable} @dots{} |
3764 |
@end example |
3765 |
|
3766 |
@noindent |
3767 |
In both of these forms, the arguments to @code{export} and |
3768 |
@code{unexport} are expanded, and so could be variables or functions |
3769 |
which expand to a (list of) variable names to be (un)exported. |
3770 |
|
3771 |
As a convenience, you can define a variable and export it at the same |
3772 |
time by doing: |
3773 |
|
3774 |
@example |
3775 |
export @var{variable} = value |
3776 |
@end example |
3777 |
|
3778 |
@noindent |
3779 |
has the same result as: |
3780 |
|
3781 |
@example |
3782 |
@var{variable} = value |
3783 |
export @var{variable} |
3784 |
@end example |
3785 |
|
3786 |
@noindent |
3787 |
and |
3788 |
|
3789 |
@example |
3790 |
export @var{variable} := value |
3791 |
@end example |
3792 |
|
3793 |
@noindent |
3794 |
has the same result as: |
3795 |
|
3796 |
@example |
3797 |
@var{variable} := value |
3798 |
export @var{variable} |
3799 |
@end example |
3800 |
|
3801 |
Likewise, |
3802 |
|
3803 |
@example |
3804 |
export @var{variable} += value |
3805 |
@end example |
3806 |
|
3807 |
@noindent |
3808 |
is just like: |
3809 |
|
3810 |
@example |
3811 |
@var{variable} += value |
3812 |
export @var{variable} |
3813 |
@end example |
3814 |
|
3815 |
@noindent |
3816 |
@xref{Appending, ,Appending More Text to Variables}. |
3817 |
|
3818 |
You may notice that the @code{export} and @code{unexport} directives |
3819 |
work in @code{make} in the same way they work in the shell, @code{sh}. |
3820 |
|
3821 |
If you want all variables to be exported by default, you can use |
3822 |
@code{export} by itself: |
3823 |
|
3824 |
@example |
3825 |
export |
3826 |
@end example |
3827 |
|
3828 |
@noindent |
3829 |
This tells @code{make} that variables which are not explicitly mentioned |
3830 |
in an @code{export} or @code{unexport} directive should be exported. |
3831 |
Any variable given in an @code{unexport} directive will still @emph{not} |
3832 |
be exported. If you use @code{export} by itself to export variables by |
3833 |
default, variables whose names contain characters other than |
3834 |
alphanumerics and underscores will not be exported unless specifically |
3835 |
mentioned in an @code{export} directive.@refill |
3836 |
|
3837 |
@findex .EXPORT_ALL_VARIABLES |
3838 |
The behavior elicited by an @code{export} directive by itself was the |
3839 |
default in older versions of GNU @code{make}. If your makefiles depend |
3840 |
on this behavior and you want to be compatible with old versions of |
3841 |
@code{make}, you can write a rule for the special target |
3842 |
@code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive. |
3843 |
This will be ignored by old @code{make}s, while the @code{export} |
3844 |
directive will cause a syntax error.@refill |
3845 |
@cindex compatibility in exporting |
3846 |
|
3847 |
Likewise, you can use @code{unexport} by itself to tell @code{make} |
3848 |
@emph{not} to export variables by default. Since this is the default |
3849 |
behavior, you would only need to do this if @code{export} had been used |
3850 |
by itself earlier (in an included makefile, perhaps). You |
3851 |
@strong{cannot} use @code{export} and @code{unexport} by themselves to |
3852 |
have variables exported for some commands and not for others. The last |
3853 |
@code{export} or @code{unexport} directive that appears by itself |
3854 |
determines the behavior for the entire run of @code{make}.@refill |
3855 |
|
3856 |
@vindex MAKELEVEL |
3857 |
@cindex recursion, level of |
3858 |
As a special feature, the variable @code{MAKELEVEL} is changed when it |
3859 |
is passed down from level to level. This variable's value is a string |
3860 |
which is the depth of the level as a decimal number. The value is |
3861 |
@samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make}, |
3862 |
@samp{2} for a sub-sub-@code{make}, and so on. The incrementation |
3863 |
happens when @code{make} sets up the environment for a command.@refill |
3864 |
|
3865 |
The main use of @code{MAKELEVEL} is to test it in a conditional |
3866 |
directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this |
3867 |
way you can write a makefile that behaves one way if run recursively and |
3868 |
another way if run directly by you.@refill |
3869 |
|
3870 |
@vindex MAKEFILES |
3871 |
You can use the variable @code{MAKEFILES} to cause all sub-@code{make} |
3872 |
commands to use additional makefiles. The value of @code{MAKEFILES} is |
3873 |
a whitespace-separated list of file names. This variable, if defined in |
3874 |
the outer-level makefile, is passed down through the environment; then |
3875 |
it serves as a list of extra makefiles for the sub-@code{make} to read |
3876 |
before the usual or specified ones. @xref{MAKEFILES Variable, ,The |
3877 |
Variable @code{MAKEFILES}}.@refill |
3878 |
|
3879 |
@node Options/Recursion, -w Option, Variables/Recursion, Recursion |
3880 |
@subsection Communicating Options to a Sub-@code{make} |
3881 |
@cindex options, and recursion |
3882 |
@cindex recursion, and options |
3883 |
|
3884 |
@vindex MAKEFLAGS |
3885 |
Flags such as @samp{-s} and @samp{-k} are passed automatically to the |
3886 |
sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is |
3887 |
set up automatically by @code{make} to contain the flag letters that |
3888 |
@code{make} received. Thus, if you do @w{@samp{make -ks}} then |
3889 |
@code{MAKEFLAGS} gets the value @samp{ks}.@refill |
3890 |
|
3891 |
As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS} |
3892 |
in its environment. In response, it takes the flags from that value and |
3893 |
processes them as if they had been given as arguments. |
3894 |
@xref{Options Summary, ,Summary of Options}. |
3895 |
|
3896 |
@cindex command line variable definitions, and recursion |
3897 |
@cindex variables, command line, and recursion |
3898 |
@cindex recursion, and command line variable definitions |
3899 |
Likewise variables defined on the command line are passed to the |
3900 |
sub-@code{make} through @code{MAKEFLAGS}. Words in the value of |
3901 |
@code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable |
3902 |
definitions just as if they appeared on the command line. |
3903 |
@xref{Overriding, ,Overriding Variables}. |
3904 |
|
3905 |
@cindex @code{-C}, and recursion |
3906 |
@cindex @code{-f}, and recursion |
3907 |
@cindex @code{-o}, and recursion |
3908 |
@cindex @code{-W}, and recursion |
3909 |
@cindex @code{--directory}, and recursion |
3910 |
@cindex @code{--file}, and recursion |
3911 |
@cindex @code{--old-file}, and recursion |
3912 |
@cindex @code{--assume-old}, and recursion |
3913 |
@cindex @code{--assume-new}, and recursion |
3914 |
@cindex @code{--new-file}, and recursion |
3915 |
@cindex recursion, and @code{-C} |
3916 |
@cindex recursion, and @code{-f} |
3917 |
@cindex recursion, and @code{-o} |
3918 |
@cindex recursion, and @code{-W} |
3919 |
The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put |
3920 |
into @code{MAKEFLAGS}; these options are not passed down.@refill |
3921 |
|
3922 |
@cindex @code{-j}, and recursion |
3923 |
@cindex @code{--jobs}, and recursion |
3924 |
@cindex recursion, and @code{-j} |
3925 |
@cindex job slots, and recursion |
3926 |
The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}). |
3927 |
If you set it to some numeric value @samp{N} and your operating system |
3928 |
supports it (most any UNIX system will; others typically won't), the |
3929 |
parent @code{make} and all the sub-@code{make}s will communicate to |
3930 |
ensure that there are only @samp{N} jobs running at the same time |
3931 |
between them all. Note that any job that is marked recursive |
3932 |
(@pxref{Instead of Execution, ,Instead of Executing the Commands}) |
3933 |
doesn't count against the total jobs (otherwise we could get @samp{N} |
3934 |
sub-@code{make}s running and have no slots left over for any real work!) |
3935 |
|
3936 |
If your operating system doesn't support the above communication, then |
3937 |
@samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you |
3938 |
specified. This is because if the @w{@samp{-j}} option were passed down |
3939 |
to sub-@code{make}s, you would get many more jobs running in parallel |
3940 |
than you asked for. If you give @samp{-j} with no numeric argument, |
3941 |
meaning to run as many jobs as possible in parallel, this is passed |
3942 |
down, since multiple infinities are no more than one.@refill |
3943 |
|
3944 |
If you do not want to pass the other flags down, you must change the |
3945 |
value of @code{MAKEFLAGS}, like this: |
3946 |
|
3947 |
@example |
3948 |
subsystem: |
3949 |
cd subdir && $(MAKE) MAKEFLAGS= |
3950 |
@end example |
3951 |
|
3952 |
@vindex MAKEOVERRIDES |
3953 |
The command line variable definitions really appear in the variable |
3954 |
@code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this |
3955 |
variable. If you do want to pass flags down normally, but don't want to |
3956 |
pass down the command line variable definitions, you can reset |
3957 |
@code{MAKEOVERRIDES} to empty, like this: |
3958 |
|
3959 |
@example |
3960 |
MAKEOVERRIDES = |
3961 |
@end example |
3962 |
|
3963 |
@noindent |
3964 |
@cindex Arg list too long |
3965 |
@cindex E2BIG |
3966 |
This is not usually useful to do. However, some systems have a small |
3967 |
fixed limit on the size of the environment, and putting so much |
3968 |
information into the value of @code{MAKEFLAGS} can exceed it. If you |
3969 |
see the error message @samp{Arg list too long}, this may be the problem. |
3970 |
@findex .POSIX |
3971 |
@cindex POSIX.2 |
3972 |
(For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does |
3973 |
not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears |
3974 |
in the makefile. You probably do not care about this.) |
3975 |
|
3976 |
@vindex MFLAGS |
3977 |
A similar variable @code{MFLAGS} exists also, for historical |
3978 |
compatibility. It has the same value as @code{MAKEFLAGS} except that it |
3979 |
does not contain the command line variable definitions, and it always |
3980 |
begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a |
3981 |
hyphen only when it begins with an option that has no single-letter |
3982 |
version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was |
3983 |
traditionally used explicitly in the recursive @code{make} command, like |
3984 |
this: |
3985 |
|
3986 |
@example |
3987 |
subsystem: |
3988 |
cd subdir && $(MAKE) $(MFLAGS) |
3989 |
@end example |
3990 |
|
3991 |
@noindent |
3992 |
but now @code{MAKEFLAGS} makes this usage redundant. If you want your |
3993 |
makefiles to be compatible with old @code{make} programs, use this |
3994 |
technique; it will work fine with more modern @code{make} versions too. |
3995 |
|
3996 |
@cindex setting options from environment |
3997 |
@cindex options, setting from environment |
3998 |
@cindex setting options in makefiles |
3999 |
@cindex options, setting in makefiles |
4000 |
The @code{MAKEFLAGS} variable can also be useful if you want to have |
4001 |
certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of |
4002 |
Options}), set each time you run @code{make}. You simply put a value for |
4003 |
@code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in |
4004 |
a makefile, to specify additional flags that should also be in effect for |
4005 |
that makefile. (Note that you cannot use @code{MFLAGS} this way. That |
4006 |
variable is set only for compatibility; @code{make} does not interpret a |
4007 |
value you set for it in any way.) |
4008 |
|
4009 |
When @code{make} interprets the value of @code{MAKEFLAGS} (either from the |
4010 |
environment or from a makefile), it first prepends a hyphen if the value |
4011 |
does not already begin with one. Then it chops the value into words |
4012 |
separated by blanks, and parses these words as if they were options given |
4013 |
on the command line (except that @samp{-C}, @samp{-f}, @samp{-h}, |
4014 |
@samp{-o}, @samp{-W}, and their long-named versions are ignored; and there |
4015 |
is no error for an invalid option). |
4016 |
|
4017 |
If you do put @code{MAKEFLAGS} in your environment, you should be sure not |
4018 |
to include any options that will drastically affect the actions of |
4019 |
@code{make} and undermine the purpose of makefiles and of @code{make} |
4020 |
itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if |
4021 |
put in one of these variables, could have disastrous consequences and would |
4022 |
certainly have at least surprising and probably annoying effects.@refill |
4023 |
|
4024 |
@node -w Option, , Options/Recursion, Recursion |
4025 |
@subsection The @samp{--print-directory} Option |
4026 |
@cindex directories, printing them |
4027 |
@cindex printing directories |
4028 |
@cindex recursion, and printing directories |
4029 |
|
4030 |
If you use several levels of recursive @code{make} invocations, the |
4031 |
@samp{-w} or @w{@samp{--print-directory}} option can make the output a |
4032 |
lot easier to understand by showing each directory as @code{make} |
4033 |
starts processing it and as @code{make} finishes processing it. For |
4034 |
example, if @samp{make -w} is run in the directory @file{/u/gnu/make}, |
4035 |
@code{make} will print a line of the form:@refill |
4036 |
|
4037 |
@example |
4038 |
make: Entering directory `/u/gnu/make'. |
4039 |
@end example |
4040 |
|
4041 |
@noindent |
4042 |
before doing anything else, and a line of the form: |
4043 |
|
4044 |
@example |
4045 |
make: Leaving directory `/u/gnu/make'. |
4046 |
@end example |
4047 |
|
4048 |
@noindent |
4049 |
when processing is completed. |
4050 |
|
4051 |
@cindex @code{-C}, and @code{-w} |
4052 |
@cindex @code{--directory}, and @code{--print-directory} |
4053 |
@cindex recursion, and @code{-w} |
4054 |
@cindex @code{-w}, and @code{-C} |
4055 |
@cindex @code{-w}, and recursion |
4056 |
@cindex @code{--print-directory}, and @code{--directory} |
4057 |
@cindex @code{--print-directory}, and recursion |
4058 |
@cindex @code{--no-print-directory} |
4059 |
@cindex @code{--print-directory}, disabling |
4060 |
@cindex @code{-w}, disabling |
4061 |
Normally, you do not need to specify this option because @samp{make} |
4062 |
does it for you: @samp{-w} is turned on automatically when you use the |
4063 |
@samp{-C} option, and in sub-@code{make}s. @code{make} will not |
4064 |
automatically turn on @samp{-w} if you also use @samp{-s}, which says to |
4065 |
be silent, or if you use @samp{--no-print-directory} to explicitly |
4066 |
disable it. |
4067 |
|
4068 |
@node Sequences, Empty Commands, Recursion, Commands |
4069 |
@section Defining Canned Command Sequences |
4070 |
@cindex sequences of commands |
4071 |
@cindex commands, sequences of |
4072 |
|
4073 |
When the same sequence of commands is useful in making various targets, you |
4074 |
can define it as a canned sequence with the @code{define} directive, and |
4075 |
refer to the canned sequence from the rules for those targets. The canned |
4076 |
sequence is actually a variable, so the name must not conflict with other |
4077 |
variable names. |
4078 |
|
4079 |
Here is an example of defining a canned sequence of commands: |
4080 |
|
4081 |
@example |
4082 |
define run-yacc |
4083 |
yacc $(firstword $^) |
4084 |
mv y.tab.c $@@ |
4085 |
endef |
4086 |
@end example |
4087 |
@cindex @code{yacc} |
4088 |
|
4089 |
@noindent |
4090 |
Here @code{run-yacc} is the name of the variable being defined; |
4091 |
@code{endef} marks the end of the definition; the lines in between are the |
4092 |
commands. The @code{define} directive does not expand variable references |
4093 |
and function calls in the canned sequence; the @samp{$} characters, |
4094 |
parentheses, variable names, and so on, all become part of the value of the |
4095 |
variable you are defining. |
4096 |
@xref{Defining, ,Defining Variables Verbatim}, |
4097 |
for a complete explanation of @code{define}. |
4098 |
|
4099 |
The first command in this example runs Yacc on the first prerequisite of |
4100 |
whichever rule uses the canned sequence. The output file from Yacc is |
4101 |
always named @file{y.tab.c}. The second command moves the output to the |
4102 |
rule's target file name. |
4103 |
|
4104 |
To use the canned sequence, substitute the variable into the commands of a |
4105 |
rule. You can substitute it like any other variable |
4106 |
(@pxref{Reference, ,Basics of Variable References}). |
4107 |
Because variables defined by @code{define} are recursively expanded |
4108 |
variables, all the variable references you wrote inside the @code{define} |
4109 |
are expanded now. For example: |
4110 |
|
4111 |
@example |
4112 |
foo.c : foo.y |
4113 |
$(run-yacc) |
4114 |
@end example |
4115 |
|
4116 |
@noindent |
4117 |
@samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in |
4118 |
@code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill |
4119 |
|
4120 |
This is a realistic example, but this particular one is not needed in |
4121 |
practice because @code{make} has an implicit rule to figure out these |
4122 |
commands based on the file names involved |
4123 |
(@pxref{Implicit Rules, ,Using Implicit Rules}). |
4124 |
|
4125 |
@cindex @@, and @code{define} |
4126 |
@cindex -, and @code{define} |
4127 |
@cindex +, and @code{define} |
4128 |
In command execution, each line of a canned sequence is treated just as |
4129 |
if the line appeared on its own in the rule, preceded by a tab. In |
4130 |
particular, @code{make} invokes a separate subshell for each line. You |
4131 |
can use the special prefix characters that affect command lines |
4132 |
(@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence. |
4133 |
@xref{Commands, ,Writing the Commands in Rules}. |
4134 |
For example, using this canned sequence: |
4135 |
|
4136 |
@example |
4137 |
define frobnicate |
4138 |
@@echo "frobnicating target $@@" |
4139 |
frob-step-1 $< -o $@@-step-1 |
4140 |
frob-step-2 $@@-step-1 -o $@@ |
4141 |
endef |
4142 |
@end example |
4143 |
|
4144 |
@noindent |
4145 |
@code{make} will not echo the first line, the @code{echo} command. |
4146 |
But it @emph{will} echo the following two command lines. |
4147 |
|
4148 |
On the other hand, prefix characters on the command line that refers to |
4149 |
a canned sequence apply to every line in the sequence. So the rule: |
4150 |
|
4151 |
@example |
4152 |
frob.out: frob.in |
4153 |
@@$(frobnicate) |
4154 |
@end example |
4155 |
|
4156 |
@noindent |
4157 |
does not echo @emph{any} commands. |
4158 |
(@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.) |
4159 |
|
4160 |
@node Empty Commands, , Sequences, Commands |
4161 |
@section Using Empty Commands |
4162 |
@cindex empty commands |
4163 |
@cindex commands, empty |
4164 |
|
4165 |
It is sometimes useful to define commands which do nothing. This is done |
4166 |
simply by giving a command that consists of nothing but whitespace. For |
4167 |
example: |
4168 |
|
4169 |
@example |
4170 |
target: ; |
4171 |
@end example |
4172 |
|
4173 |
@noindent |
4174 |
defines an empty command string for @file{target}. You could also use a |
4175 |
line beginning with a tab character to define an empty command string, |
4176 |
but this would be confusing because such a line looks empty. |
4177 |
|
4178 |
@findex .DEFAULT@r{, and empty commands} |
4179 |
You may be wondering why you would want to define a command string that |
4180 |
does nothing. The only reason this is useful is to prevent a target |
4181 |
from getting implicit commands (from implicit rules or the |
4182 |
@code{.DEFAULT} special target; @pxref{Implicit Rules} and |
4183 |
@pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill |
4184 |
|
4185 |
@c !!! another reason is for canonical stamp files: |
4186 |
@ignore |
4187 |
@example |
4188 |
foo: stamp-foo ; |
4189 |
stamp-foo: foo.in |
4190 |
create foo frm foo.in |
4191 |
touch $@ |
4192 |
@end example |
4193 |
@end ignore |
4194 |
|
4195 |
You may be inclined to define empty command strings for targets that are |
4196 |
not actual files, but only exist so that their prerequisites can be |
4197 |
remade. However, this is not the best way to do that, because the |
4198 |
prerequisites may not be remade properly if the target file actually does exist. |
4199 |
@xref{Phony Targets, ,Phony Targets}, for a better way to do this. |
4200 |
|
4201 |
@node Using Variables, Conditionals, Commands, Top |
4202 |
@chapter How to Use Variables |
4203 |
@cindex variable |
4204 |
@cindex value |
4205 |
@cindex recursive variable expansion |
4206 |
@cindex simple variable expansion |
4207 |
|
4208 |
A @dfn{variable} is a name defined in a makefile to represent a string |
4209 |
of text, called the variable's @dfn{value}. These values are |
4210 |
substituted by explicit request into targets, prerequisites, commands, |
4211 |
and other parts of the makefile. (In some other versions of @code{make}, |
4212 |
variables are called @dfn{macros}.) |
4213 |
@cindex macro |
4214 |
|
4215 |
Variables and functions in all parts of a makefile are expanded when |
4216 |
read, except for the shell commands in rules, the right-hand sides of |
4217 |
variable definitions using @samp{=}, and the bodies of variable |
4218 |
definitions using the @code{define} directive.@refill |
4219 |
|
4220 |
Variables can represent lists of file names, options to pass to compilers, |
4221 |
programs to run, directories to look in for source files, directories to |
4222 |
write output in, or anything else you can imagine. |
4223 |
|
4224 |
A variable name may be any sequence of characters not containing @samp{:}, |
4225 |
@samp{#}, @samp{=}, or leading or trailing whitespace. However, |
4226 |
variable names containing characters other than letters, numbers, and |
4227 |
underscores should be avoided, as they may be given special meanings in the |
4228 |
future, and with some shells they cannot be passed through the environment to a |
4229 |
sub-@code{make} |
4230 |
(@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}). |
4231 |
|
4232 |
Variable names are case-sensitive. The names @samp{foo}, @samp{FOO}, |
4233 |
and @samp{Foo} all refer to different variables. |
4234 |
|
4235 |
It is traditional to use upper case letters in variable names, but we |
4236 |
recommend using lower case letters for variable names that serve internal |
4237 |
purposes in the makefile, and reserving upper case for parameters that |
4238 |
control implicit rules or for parameters that the user should override with |
4239 |
command options (@pxref{Overriding, ,Overriding Variables}). |
4240 |
|
4241 |
A few variables have names that are a single punctuation character or |
4242 |
just a few characters. These are the @dfn{automatic variables}, and |
4243 |
they have particular specialized uses. @xref{Automatic Variables}. |
4244 |
|
4245 |
@menu |
4246 |
* Reference:: How to use the value of a variable. |
4247 |
* Flavors:: Variables come in two flavors. |
4248 |
* Advanced:: Advanced features for referencing a variable. |
4249 |
* Values:: All the ways variables get their values. |
4250 |
* Setting:: How to set a variable in the makefile. |
4251 |
* Appending:: How to append more text to the old value |
4252 |
of a variable. |
4253 |
* Override Directive:: How to set a variable in the makefile even if |
4254 |
the user has set it with a command argument. |
4255 |
* Defining:: An alternate way to set a variable |
4256 |
to a verbatim string. |
4257 |
* Environment:: Variable values can come from the environment. |
4258 |
* Target-specific:: Variable values can be defined on a per-target |
4259 |
basis. |
4260 |
* Pattern-specific:: Target-specific variable values can be applied |
4261 |
to a group of targets that match a pattern. |
4262 |
@end menu |
4263 |
|
4264 |
@node Reference, Flavors, Using Variables, Using Variables |
4265 |
@section Basics of Variable References |
4266 |
@cindex variables, how to reference |
4267 |
@cindex reference to variables |
4268 |
@cindex @code{$}, in variable reference |
4269 |
@cindex dollar sign (@code{$}), in variable reference |
4270 |
|
4271 |
To substitute a variable's value, write a dollar sign followed by the name |
4272 |
of the variable in parentheses or braces: either @samp{$(foo)} or |
4273 |
@samp{$@{foo@}} is a valid reference to the variable @code{foo}. This |
4274 |
special significance of @samp{$} is why you must write @samp{$$} to have |
4275 |
the effect of a single dollar sign in a file name or command. |
4276 |
|
4277 |
Variable references can be used in any context: targets, prerequisites, |
4278 |
commands, most directives, and new variable values. Here is an |
4279 |
example of a common case, where a variable holds the names of all the |
4280 |
object files in a program: |
4281 |
|
4282 |
@example |
4283 |
@group |
4284 |
objects = program.o foo.o utils.o |
4285 |
program : $(objects) |
4286 |
cc -o program $(objects) |
4287 |
|
4288 |
$(objects) : defs.h |
4289 |
@end group |
4290 |
@end example |
4291 |
|
4292 |
Variable references work by strict textual substitution. Thus, the rule |
4293 |
|
4294 |
@example |
4295 |
@group |
4296 |
foo = c |
4297 |
prog.o : prog.$(foo) |
4298 |
$(foo)$(foo) -$(foo) prog.$(foo) |
4299 |
@end group |
4300 |
@end example |
4301 |
|
4302 |
@noindent |
4303 |
could be used to compile a C program @file{prog.c}. Since spaces before |
4304 |
the variable value are ignored in variable assignments, the value of |
4305 |
@code{foo} is precisely @samp{c}. (Don't actually write your makefiles |
4306 |
this way!) |
4307 |
|
4308 |
A dollar sign followed by a character other than a dollar sign, |
4309 |
open-parenthesis or open-brace treats that single character as the |
4310 |
variable name. Thus, you could reference the variable @code{x} with |
4311 |
@samp{$x}. However, this practice is strongly discouraged, except in |
4312 |
the case of the automatic variables (@pxref{Automatic Variables}). |
4313 |
|
4314 |
@node Flavors, Advanced, Reference, Using Variables |
4315 |
@section The Two Flavors of Variables |
4316 |
@cindex flavors of variables |
4317 |
@cindex recursive variable expansion |
4318 |
@cindex variables, flavors |
4319 |
@cindex recursively expanded variables |
4320 |
@cindex variables, recursively expanded |
4321 |
|
4322 |
There are two ways that a variable in GNU @code{make} can have a value; |
4323 |
we call them the two @dfn{flavors} of variables. The two flavors are |
4324 |
distinguished in how they are defined and in what they do when expanded. |
4325 |
|
4326 |
@cindex = |
4327 |
The first flavor of variable is a @dfn{recursively expanded} variable. |
4328 |
Variables of this sort are defined by lines using @samp{=} |
4329 |
(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive |
4330 |
(@pxref{Defining, ,Defining Variables Verbatim}). The value you specify |
4331 |
is installed verbatim; if it contains references to other variables, |
4332 |
these references are expanded whenever this variable is substituted (in |
4333 |
the course of expanding some other string). When this happens, it is |
4334 |
called @dfn{recursive expansion}.@refill |
4335 |
|
4336 |
For example, |
4337 |
|
4338 |
@example |
4339 |
foo = $(bar) |
4340 |
bar = $(ugh) |
4341 |
ugh = Huh? |
4342 |
|
4343 |
all:;echo $(foo) |
4344 |
@end example |
4345 |
|
4346 |
@noindent |
4347 |
will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which |
4348 |
expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill |
4349 |
|
4350 |
This flavor of variable is the only sort supported by other versions of |
4351 |
@code{make}. It has its advantages and its disadvantages. An advantage |
4352 |
(most would say) is that: |
4353 |
|
4354 |
@example |
4355 |
CFLAGS = $(include_dirs) -O |
4356 |
include_dirs = -Ifoo -Ibar |
4357 |
@end example |
4358 |
|
4359 |
@noindent |
4360 |
will do what was intended: when @samp{CFLAGS} is expanded in a command, |
4361 |
it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you |
4362 |
cannot append something on the end of a variable, as in |
4363 |
|
4364 |
@example |
4365 |
CFLAGS = $(CFLAGS) -O |
4366 |
@end example |
4367 |
|
4368 |
@noindent |
4369 |
because it will cause an infinite loop in the variable expansion. |
4370 |
(Actually @code{make} detects the infinite loop and reports an error.) |
4371 |
@cindex loops in variable expansion |
4372 |
@cindex variables, loops in expansion |
4373 |
|
4374 |
Another disadvantage is that any functions |
4375 |
(@pxref{Functions, ,Functions for Transforming Text}) |
4376 |
referenced in the definition will be executed every time the variable is |
4377 |
expanded. This makes @code{make} run slower; worse, it causes the |
4378 |
@code{wildcard} and @code{shell} functions to give unpredictable results |
4379 |
because you cannot easily control when they are called, or even how many |
4380 |
times. |
4381 |
|
4382 |
To avoid all the problems and inconveniences of recursively expanded |
4383 |
variables, there is another flavor: simply expanded variables. |
4384 |
|
4385 |
@cindex simply expanded variables |
4386 |
@cindex variables, simply expanded |
4387 |
@cindex := |
4388 |
@dfn{Simply expanded variables} are defined by lines using @samp{:=} |
4389 |
(@pxref{Setting, ,Setting Variables}). |
4390 |
The value of a simply expanded variable is scanned |
4391 |
once and for all, expanding any references to other variables and |
4392 |
functions, when the variable is defined. The actual value of the simply |
4393 |
expanded variable is the result of expanding the text that you write. |
4394 |
It does not contain any references to other variables; it contains their |
4395 |
values @emph{as of the time this variable was defined}. Therefore, |
4396 |
|
4397 |
@example |
4398 |
x := foo |
4399 |
y := $(x) bar |
4400 |
x := later |
4401 |
@end example |
4402 |
|
4403 |
@noindent |
4404 |
is equivalent to |
4405 |
|
4406 |
@example |
4407 |
y := foo bar |
4408 |
x := later |
4409 |
@end example |
4410 |
|
4411 |
When a simply expanded variable is referenced, its value is substituted |
4412 |
verbatim. |
4413 |
|
4414 |
Here is a somewhat more complicated example, illustrating the use of |
4415 |
@samp{:=} in conjunction with the @code{shell} function. |
4416 |
(@xref{Shell Function, , The @code{shell} Function}.) This example |
4417 |
also shows use of the variable @code{MAKELEVEL}, which is changed |
4418 |
when it is passed down from level to level. |
4419 |
(@xref{Variables/Recursion, , Communicating Variables to a |
4420 |
Sub-@code{make}}, for information about @code{MAKELEVEL}.) |
4421 |
|
4422 |
@vindex MAKELEVEL |
4423 |
@vindex MAKE |
4424 |
@example |
4425 |
@group |
4426 |
ifeq (0,$@{MAKELEVEL@}) |
4427 |
cur-dir := $(shell pwd) |
4428 |
whoami := $(shell whoami) |
4429 |
host-type := $(shell arch) |
4430 |
MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@} |
4431 |
endif |
4432 |
@end group |
4433 |
@end example |
4434 |
|
4435 |
@noindent |
4436 |
An advantage of this use of @samp{:=} is that a typical |
4437 |
`descend into a directory' command then looks like this: |
4438 |
|
4439 |
@example |
4440 |
@group |
4441 |
$@{subdirs@}: |
4442 |
$@{MAKE@} cur-dir=$@{cur-dir@}/$@@ -C $@@ all |
4443 |
@end group |
4444 |
@end example |
4445 |
|
4446 |
Simply expanded variables generally make complicated makefile programming |
4447 |
more predictable because they work like variables in most programming |
4448 |
languages. They allow you to redefine a variable using its own value (or |
4449 |
its value processed in some way by one of the expansion functions) and to |
4450 |
use the expansion functions much more efficiently |
4451 |
(@pxref{Functions, ,Functions for Transforming Text}). |
4452 |
|
4453 |
@cindex spaces, in variable values |
4454 |
@cindex whitespace, in variable values |
4455 |
@cindex variables, spaces in values |
4456 |
You can also use them to introduce controlled leading whitespace into |
4457 |
variable values. Leading whitespace characters are discarded from your |
4458 |
input before substitution of variable references and function calls; |
4459 |
this means you can include leading spaces in a variable value by |
4460 |
protecting them with variable references, like this: |
4461 |
|
4462 |
@example |
4463 |
nullstring := |
4464 |
space := $(nullstring) # end of the line |
4465 |
@end example |
4466 |
|
4467 |
@noindent |
4468 |
Here the value of the variable @code{space} is precisely one space. The |
4469 |
comment @w{@samp{# end of the line}} is included here just for clarity. |
4470 |
Since trailing space characters are @emph{not} stripped from variable |
4471 |
values, just a space at the end of the line would have the same effect |
4472 |
(but be rather hard to read). If you put whitespace at the end of a |
4473 |
variable value, it is a good idea to put a comment like that at the end |
4474 |
of the line to make your intent clear. Conversely, if you do @emph{not} |
4475 |
want any whitespace characters at the end of your variable value, you |
4476 |
must remember not to put a random comment on the end of the line after |
4477 |
some whitespace, such as this: |
4478 |
|
4479 |
@example |
4480 |
dir := /foo/bar # directory to put the frobs in |
4481 |
@end example |
4482 |
|
4483 |
@noindent |
4484 |
Here the value of the variable @code{dir} is @w{@samp{/foo/bar }} |
4485 |
(with four trailing spaces), which was probably not the intention. |
4486 |
(Imagine something like @w{@samp{$(dir)/file}} with this definition!) |
4487 |
|
4488 |
@cindex conditional variable assignment |
4489 |
@cindex variables, conditional assignment |
4490 |
@cindex ?= |
4491 |
There is another assignment operator for variables, @samp{?=}. This |
4492 |
is called a conditional variable assignment operator, because it only |
4493 |
has an effect if the variable is not yet defined. This statement: |
4494 |
|
4495 |
@example |
4496 |
FOO ?= bar |
4497 |
@end example |
4498 |
|
4499 |
@noindent |
4500 |
is exactly equivalent to this |
4501 |
(@pxref{Origin Function, ,The @code{origin} Function}): |
4502 |
|
4503 |
@example |
4504 |
ifeq ($(origin FOO), undefined) |
4505 |
FOO = bar |
4506 |
endif |
4507 |
@end example |
4508 |
|
4509 |
Note that a variable set to an empty value is still defined, so |
4510 |
@samp{?=} will not set that variable. |
4511 |
|
4512 |
@node Advanced, Values, Flavors, Using Variables |
4513 |
@section Advanced Features for Reference to Variables |
4514 |
@cindex reference to variables |
4515 |
|
4516 |
This section describes some advanced features you can use to reference |
4517 |
variables in more flexible ways. |
4518 |
|
4519 |
@menu |
4520 |
* Substitution Refs:: Referencing a variable with |
4521 |
substitutions on the value. |
4522 |
* Computed Names:: Computing the name of the variable to refer to. |
4523 |
@end menu |
4524 |
|
4525 |
@node Substitution Refs, Computed Names, Advanced, Advanced |
4526 |
@subsection Substitution References |
4527 |
@cindex modified variable reference |
4528 |
@cindex substitution variable reference |
4529 |
@cindex variables, modified reference |
4530 |
@cindex variables, substitution reference |
4531 |
|
4532 |
@cindex variables, substituting suffix in |
4533 |
@cindex suffix, substituting in variables |
4534 |
A @dfn{substitution reference} substitutes the value of a variable with |
4535 |
alterations that you specify. It has the form |
4536 |
@samp{$(@var{var}:@var{a}=@var{b})} (or |
4537 |
@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value |
4538 |
of the variable @var{var}, replace every @var{a} at the end of a word with |
4539 |
@var{b} in that value, and substitute the resulting string. |
4540 |
|
4541 |
When we say ``at the end of a word'', we mean that @var{a} must appear |
4542 |
either followed by whitespace or at the end of the value in order to be |
4543 |
replaced; other occurrences of @var{a} in the value are unaltered. For |
4544 |
example:@refill |
4545 |
|
4546 |
@example |
4547 |
foo := a.o b.o c.o |
4548 |
bar := $(foo:.o=.c) |
4549 |
@end example |
4550 |
|
4551 |
@noindent |
4552 |
sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}. |
4553 |
|
4554 |
A substitution reference is actually an abbreviation for use of the |
4555 |
@code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide |
4556 |
substitution references as well as @code{patsubst} for compatibility with |
4557 |
other implementations of @code{make}. |
4558 |
|
4559 |
@findex patsubst |
4560 |
Another type of substitution reference lets you use the full power of |
4561 |
the @code{patsubst} function. It has the same form |
4562 |
@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now |
4563 |
@var{a} must contain a single @samp{%} character. This case is |
4564 |
equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. |
4565 |
@xref{Text Functions, ,Functions for String Substitution and Analysis}, |
4566 |
for a description of the @code{patsubst} function.@refill |
4567 |
|
4568 |
@example |
4569 |
@group |
4570 |
@exdent For example: |
4571 |
|
4572 |
foo := a.o b.o c.o |
4573 |
bar := $(foo:%.o=%.c) |
4574 |
@end group |
4575 |
@end example |
4576 |
|
4577 |
@noindent |
4578 |
sets @samp{bar} to @samp{a.c b.c c.c}. |
4579 |
|
4580 |
@node Computed Names, , Substitution Refs, Advanced |
4581 |
@subsection Computed Variable Names |
4582 |
@cindex nested variable reference |
4583 |
@cindex computed variable name |
4584 |
@cindex variables, computed names |
4585 |
@cindex variables, nested references |
4586 |
@cindex variables, @samp{$} in name |
4587 |
@cindex @code{$}, in variable name |
4588 |
@cindex dollar sign (@code{$}), in variable name |
4589 |
|
4590 |
Computed variable names are a complicated concept needed only for |
4591 |
sophisticated makefile programming. For most purposes you need not |
4592 |
consider them, except to know that making a variable with a dollar sign |
4593 |
in its name might have strange results. However, if you are the type |
4594 |
that wants to understand everything, or you are actually interested in |
4595 |
what they do, read on. |
4596 |
|
4597 |
Variables may be referenced inside the name of a variable. This is |
4598 |
called a @dfn{computed variable name} or a @dfn{nested variable |
4599 |
reference}. For example, |
4600 |
|
4601 |
@example |
4602 |
x = y |
4603 |
y = z |
4604 |
a := $($(x)) |
4605 |
@end example |
4606 |
|
4607 |
@noindent |
4608 |
defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands |
4609 |
to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands |
4610 |
to @samp{z}. Here the name of the variable to reference is not stated |
4611 |
explicitly; it is computed by expansion of @samp{$(x)}. The reference |
4612 |
@samp{$(x)} here is nested within the outer variable reference. |
4613 |
|
4614 |
The previous example shows two levels of nesting, but any number of levels |
4615 |
is possible. For example, here are three levels: |
4616 |
|
4617 |
@example |
4618 |
x = y |
4619 |
y = z |
4620 |
z = u |
4621 |
a := $($($(x))) |
4622 |
@end example |
4623 |
|
4624 |
@noindent |
4625 |
Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))} |
4626 |
expands to @samp{$(y)} which in turn expands to @samp{z}; now we have |
4627 |
@samp{$(z)}, which becomes @samp{u}. |
4628 |
|
4629 |
References to recursively-expanded variables within a variable name are |
4630 |
reexpanded in the usual fashion. For example: |
4631 |
|
4632 |
@example |
4633 |
x = $(y) |
4634 |
y = z |
4635 |
z = Hello |
4636 |
a := $($(x)) |
4637 |
@end example |
4638 |
|
4639 |
@noindent |
4640 |
defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} |
4641 |
which becomes @samp{$(z)} which becomes @samp{Hello}. |
4642 |
|
4643 |
Nested variable references can also contain modified references and |
4644 |
function invocations (@pxref{Functions, ,Functions for Transforming Text}), |
4645 |
just like any other reference. |
4646 |
For example, using the @code{subst} function |
4647 |
(@pxref{Text Functions, ,Functions for String Substitution and Analysis}): |
4648 |
|
4649 |
@example |
4650 |
@group |
4651 |
x = variable1 |
4652 |
variable2 := Hello |
4653 |
y = $(subst 1,2,$(x)) |
4654 |
z = y |
4655 |
a := $($($(z))) |
4656 |
@end group |
4657 |
@end example |
4658 |
|
4659 |
@noindent |
4660 |
eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone |
4661 |
would ever want to write a nested reference as convoluted as this one, but |
4662 |
it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes |
4663 |
@samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from |
4664 |
@code{x} and changes it by substitution to @samp{variable2}, so that the |
4665 |
entire string becomes @samp{$(variable2)}, a simple variable reference |
4666 |
whose value is @samp{Hello}.@refill |
4667 |
|
4668 |
A computed variable name need not consist entirely of a single variable |
4669 |
reference. It can contain several variable references, as well as some |
4670 |
invariant text. For example, |
4671 |
|
4672 |
@example |
4673 |
@group |
4674 |
a_dirs := dira dirb |
4675 |
1_dirs := dir1 dir2 |
4676 |
@end group |
4677 |
|
4678 |
@group |
4679 |
a_files := filea fileb |
4680 |
1_files := file1 file2 |
4681 |
@end group |
4682 |
|
4683 |
@group |
4684 |
ifeq "$(use_a)" "yes" |
4685 |
a1 := a |
4686 |
else |
4687 |
a1 := 1 |
4688 |
endif |
4689 |
@end group |
4690 |
|
4691 |
@group |
4692 |
ifeq "$(use_dirs)" "yes" |
4693 |
df := dirs |
4694 |
else |
4695 |
df := files |
4696 |
endif |
4697 |
|
4698 |
dirs := $($(a1)_$(df)) |
4699 |
@end group |
4700 |
@end example |
4701 |
|
4702 |
@noindent |
4703 |
will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs}, |
4704 |
@code{a_files} or @code{1_files} depending on the settings of @code{use_a} |
4705 |
and @code{use_dirs}.@refill |
4706 |
|
4707 |
Computed variable names can also be used in substitution references: |
4708 |
|
4709 |
@example |
4710 |
@group |
4711 |
a_objects := a.o b.o c.o |
4712 |
1_objects := 1.o 2.o 3.o |
4713 |
|
4714 |
sources := $($(a1)_objects:.o=.c) |
4715 |
@end group |
4716 |
@end example |
4717 |
|
4718 |
@noindent |
4719 |
defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c}, |
4720 |
depending on the value of @code{a1}. |
4721 |
|
4722 |
The only restriction on this sort of use of nested variable references |
4723 |
is that they cannot specify part of the name of a function to be called. |
4724 |
This is because the test for a recognized function name is done before |
4725 |
the expansion of nested references. For example, |
4726 |
|
4727 |
@example |
4728 |
@group |
4729 |
ifdef do_sort |
4730 |
func := sort |
4731 |
else |
4732 |
func := strip |
4733 |
endif |
4734 |
@end group |
4735 |
|
4736 |
@group |
4737 |
bar := a d b g q c |
4738 |
@end group |
4739 |
|
4740 |
@group |
4741 |
foo := $($(func) $(bar)) |
4742 |
@end group |
4743 |
@end example |
4744 |
|
4745 |
@noindent |
4746 |
attempts to give @samp{foo} the value of the variable @samp{sort a d b g |
4747 |
q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c} |
4748 |
as the argument to either the @code{sort} or the @code{strip} function. |
4749 |
This restriction could be removed in the future if that change is shown |
4750 |
to be a good idea. |
4751 |
|
4752 |
You can also use computed variable names in the left-hand side of a |
4753 |
variable assignment, or in a @code{define} directive, as in: |
4754 |
|
4755 |
@example |
4756 |
dir = foo |
4757 |
$(dir)_sources := $(wildcard $(dir)/*.c) |
4758 |
define $(dir)_print |
4759 |
lpr $($(dir)_sources) |
4760 |
endef |
4761 |
@end example |
4762 |
|
4763 |
@noindent |
4764 |
This example defines the variables @samp{dir}, @samp{foo_sources}, and |
4765 |
@samp{foo_print}. |
4766 |
|
4767 |
Note that @dfn{nested variable references} are quite different from |
4768 |
@dfn{recursively expanded variables} |
4769 |
(@pxref{Flavors, ,The Two Flavors of Variables}), though both are |
4770 |
used together in complex ways when doing makefile programming.@refill |
4771 |
|
4772 |
@node Values, Setting, Advanced, Using Variables |
4773 |
@section How Variables Get Their Values |
4774 |
@cindex variables, how they get their values |
4775 |
@cindex value, how a variable gets it |
4776 |
|
4777 |
Variables can get values in several different ways: |
4778 |
|
4779 |
@itemize @bullet |
4780 |
@item |
4781 |
You can specify an overriding value when you run @code{make}. |
4782 |
@xref{Overriding, ,Overriding Variables}. |
4783 |
|
4784 |
@item |
4785 |
You can specify a value in the makefile, either |
4786 |
with an assignment (@pxref{Setting, ,Setting Variables}) or with a |
4787 |
verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill |
4788 |
|
4789 |
@item |
4790 |
Variables in the environment become @code{make} variables. |
4791 |
@xref{Environment, ,Variables from the Environment}. |
4792 |
|
4793 |
@item |
4794 |
Several @dfn{automatic} variables are given new values for each rule. |
4795 |
Each of these has a single conventional use. |
4796 |
@xref{Automatic Variables}. |
4797 |
|
4798 |
@item |
4799 |
Several variables have constant initial values. |
4800 |
@xref{Implicit Variables, ,Variables Used by Implicit Rules}. |
4801 |
@end itemize |
4802 |
|
4803 |
@node Setting, Appending, Values, Using Variables |
4804 |
@section Setting Variables |
4805 |
@cindex setting variables |
4806 |
@cindex variables, setting |
4807 |
@cindex = |
4808 |
@cindex := |
4809 |
@cindex ?= |
4810 |
|
4811 |
To set a variable from the makefile, write a line starting with the |
4812 |
variable name followed by @samp{=} or @samp{:=}. Whatever follows the |
4813 |
@samp{=} or @samp{:=} on the line becomes the value. For example, |
4814 |
|
4815 |
@example |
4816 |
objects = main.o foo.o bar.o utils.o |
4817 |
@end example |
4818 |
|
4819 |
@noindent |
4820 |
defines a variable named @code{objects}. Whitespace around the variable |
4821 |
name and immediately after the @samp{=} is ignored. |
4822 |
|
4823 |
Variables defined with @samp{=} are @dfn{recursively expanded} variables. |
4824 |
Variables defined with @samp{:=} are @dfn{simply expanded} variables; these |
4825 |
definitions can contain variable references which will be expanded before |
4826 |
the definition is made. @xref{Flavors, ,The Two Flavors of Variables}. |
4827 |
|
4828 |
The variable name may contain function and variable references, which |
4829 |
are expanded when the line is read to find the actual variable name to use. |
4830 |
|
4831 |
There is no limit on the length of the value of a variable except the |
4832 |
amount of swapping space on the computer. When a variable definition is |
4833 |
long, it is a good idea to break it into several lines by inserting |
4834 |
backslash-newline at convenient places in the definition. This will not |
4835 |
affect the functioning of @code{make}, but it will make the makefile easier |
4836 |
to read. |
4837 |
|
4838 |
Most variable names are considered to have the empty string as a value if |
4839 |
you have never set them. Several variables have built-in initial values |
4840 |
that are not empty, but you can set them in the usual ways |
4841 |
(@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). |
4842 |
Several special variables are set |
4843 |
automatically to a new value for each rule; these are called the |
4844 |
@dfn{automatic} variables (@pxref{Automatic Variables}). |
4845 |
|
4846 |
If you'd like a variable to be set to a value only if it's not already |
4847 |
set, then you can use the shorthand operator @samp{?=} instead of |
4848 |
@samp{=}. These two settings of the variable @samp{FOO} are identical |
4849 |
(@pxref{Origin Function, ,The @code{origin} Function}): |
4850 |
|
4851 |
@example |
4852 |
FOO ?= bar |
4853 |
@end example |
4854 |
|
4855 |
@noindent |
4856 |
and |
4857 |
|
4858 |
@example |
4859 |
ifeq ($(origin FOO), undefined) |
4860 |
FOO = bar |
4861 |
endif |
4862 |
@end example |
4863 |
|
4864 |
@node Appending, Override Directive, Setting, Using Variables |
4865 |
@section Appending More Text to Variables |
4866 |
@cindex += |
4867 |
@cindex appending to variables |
4868 |
@cindex variables, appending to |
4869 |
|
4870 |
Often it is useful to add more text to the value of a variable already defined. |
4871 |
You do this with a line containing @samp{+=}, like this: |
4872 |
|
4873 |
@example |
4874 |
objects += another.o |
4875 |
@end example |
4876 |
|
4877 |
@noindent |
4878 |
This takes the value of the variable @code{objects}, and adds the text |
4879 |
@samp{another.o} to it (preceded by a single space). Thus: |
4880 |
|
4881 |
@example |
4882 |
objects = main.o foo.o bar.o utils.o |
4883 |
objects += another.o |
4884 |
@end example |
4885 |
|
4886 |
@noindent |
4887 |
sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}. |
4888 |
|
4889 |
Using @samp{+=} is similar to: |
4890 |
|
4891 |
@example |
4892 |
objects = main.o foo.o bar.o utils.o |
4893 |
objects := $(objects) another.o |
4894 |
@end example |
4895 |
|
4896 |
@noindent |
4897 |
but differs in ways that become important when you use more complex values. |
4898 |
|
4899 |
When the variable in question has not been defined before, @samp{+=} |
4900 |
acts just like normal @samp{=}: it defines a recursively-expanded |
4901 |
variable. However, when there @emph{is} a previous definition, exactly |
4902 |
what @samp{+=} does depends on what flavor of variable you defined |
4903 |
originally. @xref{Flavors, ,The Two Flavors of Variables}, for an |
4904 |
explanation of the two flavors of variables. |
4905 |
|
4906 |
When you add to a variable's value with @samp{+=}, @code{make} acts |
4907 |
essentially as if you had included the extra text in the initial |
4908 |
definition of the variable. If you defined it first with @samp{:=}, |
4909 |
making it a simply-expanded variable, @samp{+=} adds to that |
4910 |
simply-expanded definition, and expands the new text before appending it |
4911 |
to the old value just as @samp{:=} does |
4912 |
(@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}). |
4913 |
In fact, |
4914 |
|
4915 |
@example |
4916 |
variable := value |
4917 |
variable += more |
4918 |
@end example |
4919 |
|
4920 |
@noindent |
4921 |
is exactly equivalent to: |
4922 |
|
4923 |
@noindent |
4924 |
@example |
4925 |
variable := value |
4926 |
variable := $(variable) more |
4927 |
@end example |
4928 |
|
4929 |
On the other hand, when you use @samp{+=} with a variable that you defined |
4930 |
first to be recursively-expanded using plain @samp{=}, @code{make} does |
4931 |
something a bit different. Recall that when you define a |
4932 |
recursively-expanded variable, @code{make} does not expand the value you set |
4933 |
for variable and function references immediately. Instead it stores the text |
4934 |
verbatim, and saves these variable and function references to be expanded |
4935 |
later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors |
4936 |
of Variables}). When you use @samp{+=} on a recursively-expanded variable, |
4937 |
it is this unexpanded text to which @code{make} appends the new text you |
4938 |
specify. |
4939 |
|
4940 |
@example |
4941 |
@group |
4942 |
variable = value |
4943 |
variable += more |
4944 |
@end group |
4945 |
@end example |
4946 |
|
4947 |
@noindent |
4948 |
is roughly equivalent to: |
4949 |
|
4950 |
@example |
4951 |
@group |
4952 |
temp = value |
4953 |
variable = $(temp) more |
4954 |
@end group |
4955 |
@end example |
4956 |
|
4957 |
@noindent |
4958 |
except that of course it never defines a variable called @code{temp}. |
4959 |
The importance of this comes when the variable's old value contains |
4960 |
variable references. Take this common example: |
4961 |
|
4962 |
@example |
4963 |
CFLAGS = $(includes) -O |
4964 |
@dots{} |
4965 |
CFLAGS += -pg # enable profiling |
4966 |
@end example |
4967 |
|
4968 |
@noindent |
4969 |
The first line defines the @code{CFLAGS} variable with a reference to another |
4970 |
variable, @code{includes}. (@code{CFLAGS} is used by the rules for C |
4971 |
compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.) |
4972 |
Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded |
4973 |
variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when |
4974 |
@code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes} |
4975 |
need not be defined yet for its value to take effect. It only has to be |
4976 |
defined before any reference to @code{CFLAGS}. If we tried to append to the |
4977 |
value of @code{CFLAGS} without using @samp{+=}, we might do it like this: |
4978 |
|
4979 |
@example |
4980 |
CFLAGS := $(CFLAGS) -pg # enable profiling |
4981 |
@end example |
4982 |
|
4983 |
@noindent |
4984 |
This is pretty close, but not quite what we want. Using @samp{:=} |
4985 |
redefines @code{CFLAGS} as a simply-expanded variable; this means |
4986 |
@code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the |
4987 |
variable. If @code{includes} is not yet defined, we get @w{@samp{ -O |
4988 |
-pg}}, and a later definition of @code{includes} will have no effect. |
4989 |
Conversely, by using @samp{+=} we set @code{CFLAGS} to the |
4990 |
@emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve |
4991 |
the reference to @code{includes}, so if that variable gets defined at |
4992 |
any later point, a reference like @samp{$(CFLAGS)} still uses its |
4993 |
value. |
4994 |
|
4995 |
@node Override Directive, Defining, Appending, Using Variables |
4996 |
@section The @code{override} Directive |
4997 |
@findex override |
4998 |
@cindex overriding with @code{override} |
4999 |
@cindex variables, overriding |
5000 |
|
5001 |
If a variable has been set with a command argument |
5002 |
(@pxref{Overriding, ,Overriding Variables}), |
5003 |
then ordinary assignments in the makefile are ignored. If you want to set |
5004 |
the variable in the makefile even though it was set with a command |
5005 |
argument, you can use an @code{override} directive, which is a line that |
5006 |
looks like this:@refill |
5007 |
|
5008 |
@example |
5009 |
override @var{variable} = @var{value} |
5010 |
@end example |
5011 |
|
5012 |
@noindent |
5013 |
or |
5014 |
|
5015 |
@example |
5016 |
override @var{variable} := @var{value} |
5017 |
@end example |
5018 |
|
5019 |
To append more text to a variable defined on the command line, use: |
5020 |
|
5021 |
@example |
5022 |
override @var{variable} += @var{more text} |
5023 |
@end example |
5024 |
|
5025 |
@noindent |
5026 |
@xref{Appending, ,Appending More Text to Variables}. |
5027 |
|
5028 |
The @code{override} directive was not invented for escalation in the war |
5029 |
between makefiles and command arguments. It was invented so you can alter |
5030 |
and add to values that the user specifies with command arguments. |
5031 |
|
5032 |
For example, suppose you always want the @samp{-g} switch when you run the |
5033 |
C compiler, but you would like to allow the user to specify the other |
5034 |
switches with a command argument just as usual. You could use this |
5035 |
@code{override} directive: |
5036 |
|
5037 |
@example |
5038 |
override CFLAGS += -g |
5039 |
@end example |
5040 |
|
5041 |
You can also use @code{override} directives with @code{define} directives. |
5042 |
This is done as you might expect: |
5043 |
|
5044 |
@example |
5045 |
override define foo |
5046 |
bar |
5047 |
endef |
5048 |
@end example |
5049 |
|
5050 |
@noindent |
5051 |
@iftex |
5052 |
See the next section for information about @code{define}. |
5053 |
@end iftex |
5054 |
@ifinfo |
5055 |
@xref{Defining, ,Defining Variables Verbatim}. |
5056 |
@end ifinfo |
5057 |
|
5058 |
@node Defining, Environment, Override Directive, Using Variables |
5059 |
@section Defining Variables Verbatim |
5060 |
@findex define |
5061 |
@findex endef |
5062 |
@cindex verbatim variable definition |
5063 |
@cindex defining variables verbatim |
5064 |
@cindex variables, defining verbatim |
5065 |
|
5066 |
Another way to set the value of a variable is to use the @code{define} |
5067 |
directive. This directive has an unusual syntax which allows newline |
5068 |
characters to be included in the value, which is convenient for defining |
5069 |
both canned sequences of commands |
5070 |
(@pxref{Sequences, ,Defining Canned Command Sequences}), and also |
5071 |
sections of makefile syntax to use with @code{eval} (@pxref{Eval Function}). |
5072 |
|
5073 |
The @code{define} directive is followed on the same line by the name of the |
5074 |
variable and nothing more. The value to give the variable appears on the |
5075 |
following lines. The end of the value is marked by a line containing just |
5076 |
the word @code{endef}. Aside from this difference in syntax, @code{define} |
5077 |
works just like @samp{=}: it creates a recursively-expanded variable |
5078 |
(@pxref{Flavors, ,The Two Flavors of Variables}). |
5079 |
The variable name may contain function and variable references, which |
5080 |
are expanded when the directive is read to find the actual variable name |
5081 |
to use. |
5082 |
|
5083 |
You may nest @code{define} directives: @code{make} will keep track of |
5084 |
nested directives and report an error if they are not all properly |
5085 |
closed with @code{endef}. Note that lines beginning with tab |
5086 |
characters are considered part of a command script, so any |
5087 |
@code{define} or @code{endef} strings appearing on such a line will |
5088 |
not be considered @code{make} operators. |
5089 |
|
5090 |
@example |
5091 |
define two-lines |
5092 |
echo foo |
5093 |
echo $(bar) |
5094 |
endef |
5095 |
@end example |
5096 |
|
5097 |
The value in an ordinary assignment cannot contain a newline; but the |
5098 |
newlines that separate the lines of the value in a @code{define} become |
5099 |
part of the variable's value (except for the final newline which precedes |
5100 |
the @code{endef} and is not considered part of the value).@refill |
5101 |
|
5102 |
@need 800 |
5103 |
When used in a command script, the previous example is functionally |
5104 |
equivalent to this: |
5105 |
|
5106 |
@example |
5107 |
two-lines = echo foo; echo $(bar) |
5108 |
@end example |
5109 |
|
5110 |
@noindent |
5111 |
since two commands separated by semicolon behave much like two separate |
5112 |
shell commands. However, note that using two separate lines means |
5113 |
@code{make} will invoke the shell twice, running an independent subshell |
5114 |
for each line. @xref{Execution, ,Command Execution}. |
5115 |
|
5116 |
If you want variable definitions made with @code{define} to take |
5117 |
precedence over command-line variable definitions, you can use the |
5118 |
@code{override} directive together with @code{define}: |
5119 |
|
5120 |
@example |
5121 |
override define two-lines |
5122 |
foo |
5123 |
$(bar) |
5124 |
endef |
5125 |
@end example |
5126 |
|
5127 |
@noindent |
5128 |
@xref{Override Directive, ,The @code{override} Directive}. |
5129 |
|
5130 |
@node Environment, Target-specific, Defining, Using Variables |
5131 |
@section Variables from the Environment |
5132 |
|
5133 |
@cindex variables, environment |
5134 |
@cindex environment |
5135 |
Variables in @code{make} can come from the environment in which |
5136 |
@code{make} is run. Every environment variable that @code{make} sees when |
5137 |
it starts up is transformed into a @code{make} variable with the same name |
5138 |
and value. But an explicit assignment in the makefile, or with a command |
5139 |
argument, overrides the environment. (If the @samp{-e} flag is specified, |
5140 |
then values from the environment override assignments in the makefile. |
5141 |
@xref{Options Summary, ,Summary of Options}. |
5142 |
But this is not recommended practice.) |
5143 |
|
5144 |
Thus, by setting the variable @code{CFLAGS} in your environment, you can |
5145 |
cause all C compilations in most makefiles to use the compiler switches you |
5146 |
prefer. This is safe for variables with standard or conventional meanings |
5147 |
because you know that no makefile will use them for other things. (But |
5148 |
this is not totally reliable; some makefiles set @code{CFLAGS} explicitly |
5149 |
and therefore are not affected by the value in the environment.) |
5150 |
|
5151 |
When @code{make} is invoked recursively, variables defined in the |
5152 |
outer invocation can be passed to inner invocations through the |
5153 |
environment (@pxref{Recursion, ,Recursive Use of @code{make}}). By |
5154 |
default, only variables that came from the environment or the command |
5155 |
line are passed to recursive invocations. You can use the |
5156 |
@code{export} directive to pass other variables. |
5157 |
@xref{Variables/Recursion, , Communicating Variables to a |
5158 |
Sub-@code{make}}, for full details. |
5159 |
|
5160 |
Other use of variables from the environment is not recommended. It is not |
5161 |
wise for makefiles to depend for their functioning on environment variables |
5162 |
set up outside their control, since this would cause different users to get |
5163 |
different results from the same makefile. This is against the whole |
5164 |
purpose of most makefiles. |
5165 |
|
5166 |
Such problems would be especially likely with the variable @code{SHELL}, |
5167 |
which is normally present in the environment to specify the user's choice |
5168 |
of interactive shell. It would be very undesirable for this choice to |
5169 |
affect @code{make}. So @code{make} ignores the environment value of |
5170 |
@code{SHELL} (except on MS-DOS and MS-Windows, where @code{SHELL} is |
5171 |
usually not set. @xref{Execution, ,Special handling of SHELL on |
5172 |
MS-DOS}.)@refill |
5173 |
|
5174 |
@node Target-specific, Pattern-specific, Environment, Using Variables |
5175 |
@section Target-specific Variable Values |
5176 |
@cindex target-specific variables |
5177 |
@cindex variables, target-specific |
5178 |
|
5179 |
Variable values in @code{make} are usually global; that is, they are the |
5180 |
same regardless of where they are evaluated (unless they're reset, of |
5181 |
course). One exception to that is automatic variables |
5182 |
(@pxref{Automatic Variables}). |
5183 |
|
5184 |
The other exception is @dfn{target-specific variable values}. This |
5185 |
feature allows you to define different values for the same variable, |
5186 |
based on the target that @code{make} is currently building. As with |
5187 |
automatic variables, these values are only available within the context |
5188 |
of a target's command script (and in other target-specific assignments). |
5189 |
|
5190 |
Set a target-specific variable value like this: |
5191 |
|
5192 |
@example |
5193 |
@var{target} @dots{} : @var{variable-assignment} |
5194 |
@end example |
5195 |
|
5196 |
@noindent |
5197 |
or like this: |
5198 |
|
5199 |
@example |
5200 |
@var{target} @dots{} : override @var{variable-assignment} |
5201 |
@end example |
5202 |
|
5203 |
@noindent |
5204 |
or like this: |
5205 |
|
5206 |
@example |
5207 |
@var{target} @dots{} : export @var{variable-assignment} |
5208 |
@end example |
5209 |
|
5210 |
Multiple @var{target} values create a target-specific variable value for |
5211 |
each member of the target list individually. |
5212 |
|
5213 |
The @var{variable-assignment} can be any valid form of assignment; |
5214 |
recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or |
5215 |
conditional (@samp{?=}). All variables that appear within the |
5216 |
@var{variable-assignment} are evaluated within the context of the |
5217 |
target: thus, any previously-defined target-specific variable values |
5218 |
will be in effect. Note that this variable is actually distinct from |
5219 |
any ``global'' value: the two variables do not have to have the same |
5220 |
flavor (recursive vs. static). |
5221 |
|
5222 |
Target-specific variables have the same priority as any other makefile |
5223 |
variable. Variables provided on the command-line (and in the |
5224 |
environment if the @samp{-e} option is in force) will take precedence. |
5225 |
Specifying the @code{override} directive will allow the target-specific |
5226 |
variable value to be preferred. |
5227 |
|
5228 |
There is one more special feature of target-specific variables: when you |
5229 |
define a target-specific variable, that variable value is also in effect |
5230 |
for all prerequisites of this target (unless those prerequisites override |
5231 |
it with their own target-specific variable value). So, for example, a |
5232 |
statement like this: |
5233 |
|
5234 |
@example |
5235 |
prog : CFLAGS = -g |
5236 |
prog : prog.o foo.o bar.o |
5237 |
@end example |
5238 |
|
5239 |
@noindent |
5240 |
will set @code{CFLAGS} to @samp{-g} in the command script for |
5241 |
@file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the |
5242 |
command scripts that create @file{prog.o}, @file{foo.o}, and |
5243 |
@file{bar.o}, and any command scripts which create their prerequisites. |
5244 |
|
5245 |
@node Pattern-specific, , Target-specific, Using Variables |
5246 |
@section Pattern-specific Variable Values |
5247 |
@cindex pattern-specific variables |
5248 |
@cindex variables, pattern-specific |
5249 |
|
5250 |
In addition to target-specific variable values |
5251 |
(@pxref{Target-specific, ,Target-specific Variable Values}), GNU |
5252 |
@code{make} supports pattern-specific variable values. In this form, |
5253 |
the variable is defined for any target that matches the pattern |
5254 |
specified. If a target matches more than one pattern, all the |
5255 |
matching pattern-specific variables are interpreted in the order in |
5256 |
which they were defined in the makefile, and collected together into |
5257 |
one set. Variables defined in this way are searched after any |
5258 |
target-specific variables defined explicitly for that target, and |
5259 |
before target-specific variables defined for the parent target. |
5260 |
|
5261 |
Set a pattern-specific variable value like this: |
5262 |
|
5263 |
@example |
5264 |
@var{pattern} @dots{} : @var{variable-assignment} |
5265 |
@end example |
5266 |
|
5267 |
@noindent |
5268 |
or like this: |
5269 |
|
5270 |
@example |
5271 |
@var{pattern} @dots{} : override @var{variable-assignment} |
5272 |
@end example |
5273 |
|
5274 |
@noindent |
5275 |
where @var{pattern} is a %-pattern. As with target-specific variable |
5276 |
values, multiple @var{pattern} values create a pattern-specific variable |
5277 |
value for each pattern individually. The @var{variable-assignment} can |
5278 |
be any valid form of assignment. Any command-line variable setting will |
5279 |
take precedence, unless @code{override} is specified. |
5280 |
|
5281 |
For example: |
5282 |
|
5283 |
@example |
5284 |
%.o : CFLAGS = -O |
5285 |
@end example |
5286 |
|
5287 |
@noindent |
5288 |
will assign @code{CFLAGS} the value of @samp{-O} for all targets |
5289 |
matching the pattern @code{%.o}. |
5290 |
|
5291 |
@node Conditionals, Functions, Using Variables, Top |
5292 |
@chapter Conditional Parts of Makefiles |
5293 |
|
5294 |
@cindex conditionals |
5295 |
A @dfn{conditional} causes part of a makefile to be obeyed or ignored |
5296 |
depending on the values of variables. Conditionals can compare the |
5297 |
value of one variable to another, or the value of a variable to |
5298 |
a constant string. Conditionals control what @code{make} actually |
5299 |
``sees'' in the makefile, so they @emph{cannot} be used to control shell |
5300 |
commands at the time of execution.@refill |
5301 |
|
5302 |
@menu |
5303 |
* Conditional Example:: Example of a conditional |
5304 |
* Conditional Syntax:: The syntax of conditionals. |
5305 |
* Testing Flags:: Conditionals that test flags. |
5306 |
@end menu |
5307 |
|
5308 |
@node Conditional Example, Conditional Syntax, Conditionals, Conditionals |
5309 |
@section Example of a Conditional |
5310 |
|
5311 |
The following example of a conditional tells @code{make} to use one set |
5312 |
of libraries if the @code{CC} variable is @samp{gcc}, and a different |
5313 |
set of libraries otherwise. It works by controlling which of two |
5314 |
command lines will be used as the command for a rule. The result is |
5315 |
that @samp{CC=gcc} as an argument to @code{make} changes not only which |
5316 |
compiler is used but also which libraries are linked. |
5317 |
|
5318 |
@example |
5319 |
libs_for_gcc = -lgnu |
5320 |
normal_libs = |
5321 |
|
5322 |
foo: $(objects) |
5323 |
ifeq ($(CC),gcc) |
5324 |
$(CC) -o foo $(objects) $(libs_for_gcc) |
5325 |
else |
5326 |
$(CC) -o foo $(objects) $(normal_libs) |
5327 |
endif |
5328 |
@end example |
5329 |
|
5330 |
This conditional uses three directives: one @code{ifeq}, one @code{else} |
5331 |
and one @code{endif}. |
5332 |
|
5333 |
The @code{ifeq} directive begins the conditional, and specifies the |
5334 |
condition. It contains two arguments, separated by a comma and surrounded |
5335 |
by parentheses. Variable substitution is performed on both arguments and |
5336 |
then they are compared. The lines of the makefile following the |
5337 |
@code{ifeq} are obeyed if the two arguments match; otherwise they are |
5338 |
ignored. |
5339 |
|
5340 |
The @code{else} directive causes the following lines to be obeyed if the |
5341 |
previous conditional failed. In the example above, this means that the |
5342 |
second alternative linking command is used whenever the first alternative |
5343 |
is not used. It is optional to have an @code{else} in a conditional. |
5344 |
|
5345 |
The @code{endif} directive ends the conditional. Every conditional must |
5346 |
end with an @code{endif}. Unconditional makefile text follows. |
5347 |
|
5348 |
As this example illustrates, conditionals work at the textual level: |
5349 |
the lines of the conditional are treated as part of the makefile, or |
5350 |
ignored, according to the condition. This is why the larger syntactic |
5351 |
units of the makefile, such as rules, may cross the beginning or the |
5352 |
end of the conditional. |
5353 |
|
5354 |
When the variable @code{CC} has the value @samp{gcc}, the above example has |
5355 |
this effect: |
5356 |
|
5357 |
@example |
5358 |
foo: $(objects) |
5359 |
$(CC) -o foo $(objects) $(libs_for_gcc) |
5360 |
@end example |
5361 |
|
5362 |
@noindent |
5363 |
When the variable @code{CC} has any other value, the effect is this: |
5364 |
|
5365 |
@example |
5366 |
foo: $(objects) |
5367 |
$(CC) -o foo $(objects) $(normal_libs) |
5368 |
@end example |
5369 |
|
5370 |
Equivalent results can be obtained in another way by conditionalizing a |
5371 |
variable assignment and then using the variable unconditionally: |
5372 |
|
5373 |
@example |
5374 |
libs_for_gcc = -lgnu |
5375 |
normal_libs = |
5376 |
|
5377 |
ifeq ($(CC),gcc) |
5378 |
libs=$(libs_for_gcc) |
5379 |
else |
5380 |
libs=$(normal_libs) |
5381 |
endif |
5382 |
|
5383 |
foo: $(objects) |
5384 |
$(CC) -o foo $(objects) $(libs) |
5385 |
@end example |
5386 |
|
5387 |
@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals |
5388 |
@section Syntax of Conditionals |
5389 |
@findex ifdef |
5390 |
@findex ifeq |
5391 |
@findex ifndef |
5392 |
@findex ifneq |
5393 |
@findex else |
5394 |
@findex endif |
5395 |
|
5396 |
The syntax of a simple conditional with no @code{else} is as follows: |
5397 |
|
5398 |
@example |
5399 |
@var{conditional-directive} |
5400 |
@var{text-if-true} |
5401 |
endif |
5402 |
@end example |
5403 |
|
5404 |
@noindent |
5405 |
The @var{text-if-true} may be any lines of text, to be considered as part |
5406 |
of the makefile if the condition is true. If the condition is false, no |
5407 |
text is used instead. |
5408 |
|
5409 |
The syntax of a complex conditional is as follows: |
5410 |
|
5411 |
@example |
5412 |
@var{conditional-directive} |
5413 |
@var{text-if-true} |
5414 |
else |
5415 |
@var{text-if-false} |
5416 |
endif |
5417 |
@end example |
5418 |
|
5419 |
@noindent |
5420 |
If the condition is true, @var{text-if-true} is used; otherwise, |
5421 |
@var{text-if-false} is used instead. The @var{text-if-false} can be any |
5422 |
number of lines of text. |
5423 |
|
5424 |
The syntax of the @var{conditional-directive} is the same whether the |
5425 |
conditional is simple or complex. There are four different directives that |
5426 |
test different conditions. Here is a table of them: |
5427 |
|
5428 |
@table @code |
5429 |
@item ifeq (@var{arg1}, @var{arg2}) |
5430 |
@itemx ifeq '@var{arg1}' '@var{arg2}' |
5431 |
@itemx ifeq "@var{arg1}" "@var{arg2}" |
5432 |
@itemx ifeq "@var{arg1}" '@var{arg2}' |
5433 |
@itemx ifeq '@var{arg1}' "@var{arg2}" |
5434 |
Expand all variable references in @var{arg1} and @var{arg2} and |
5435 |
compare them. If they are identical, the @var{text-if-true} is |
5436 |
effective; otherwise, the @var{text-if-false}, if any, is effective. |
5437 |
|
5438 |
Often you want to test if a variable has a non-empty value. When the |
5439 |
value results from complex expansions of variables and functions, |
5440 |
expansions you would consider empty may actually contain whitespace |
5441 |
characters and thus are not seen as empty. However, you can use the |
5442 |
@code{strip} function (@pxref{Text Functions}) to avoid interpreting |
5443 |
whitespace as a non-empty value. For example: |
5444 |
|
5445 |
@example |
5446 |
@group |
5447 |
ifeq ($(strip $(foo)),) |
5448 |
@var{text-if-empty} |
5449 |
endif |
5450 |
@end group |
5451 |
@end example |
5452 |
|
5453 |
@noindent |
5454 |
will evaluate @var{text-if-empty} even if the expansion of |
5455 |
@code{$(foo)} contains whitespace characters. |
5456 |
|
5457 |
@item ifneq (@var{arg1}, @var{arg2}) |
5458 |
@itemx ifneq '@var{arg1}' '@var{arg2}' |
5459 |
@itemx ifneq "@var{arg1}" "@var{arg2}" |
5460 |
@itemx ifneq "@var{arg1}" '@var{arg2}' |
5461 |
@itemx ifneq '@var{arg1}' "@var{arg2}" |
5462 |
Expand all variable references in @var{arg1} and @var{arg2} and |
5463 |
compare them. If they are different, the @var{text-if-true} is |
5464 |
effective; otherwise, the @var{text-if-false}, if any, is effective. |
5465 |
|
5466 |
@item ifdef @var{variable-name} |
5467 |
If the variable @var{variable-name} has a non-empty value, the |
5468 |
@var{text-if-true} is effective; otherwise, the @var{text-if-false}, |
5469 |
if any, is effective. Variables that have never been defined have an |
5470 |
empty value. The variable @var{variable-name} is itself expanded, so |
5471 |
it could be a variable or function that expands to the name of a |
5472 |
variable. |
5473 |
|
5474 |
Note that @code{ifdef} only tests whether a variable has a value. It |
5475 |
does not expand the variable to see if that value is nonempty. |
5476 |
Consequently, tests using @code{ifdef} return true for all definitions |
5477 |
except those like @code{foo =}. To test for an empty value, use |
5478 |
@w{@code{ifeq ($(foo),)}}. For example, |
5479 |
|
5480 |
@example |
5481 |
bar = |
5482 |
foo = $(bar) |
5483 |
ifdef foo |
5484 |
frobozz = yes |
5485 |
else |
5486 |
frobozz = no |
5487 |
endif |
5488 |
@end example |
5489 |
|
5490 |
@noindent |
5491 |
sets @samp{frobozz} to @samp{yes}, while: |
5492 |
|
5493 |
@example |
5494 |
foo = |
5495 |
ifdef foo |
5496 |
frobozz = yes |
5497 |
else |
5498 |
frobozz = no |
5499 |
endif |
5500 |
@end example |
5501 |
|
5502 |
@noindent |
5503 |
sets @samp{frobozz} to @samp{no}. |
5504 |
|
5505 |
@item ifndef @var{variable-name} |
5506 |
If the variable @var{variable-name} has an empty value, the |
5507 |
@var{text-if-true} is effective; otherwise, the @var{text-if-false}, |
5508 |
if any, is effective. |
5509 |
@end table |
5510 |
|
5511 |
Extra spaces are allowed and ignored at the beginning of the conditional |
5512 |
directive line, but a tab is not allowed. (If the line begins with a tab, |
5513 |
it will be considered a command for a rule.) Aside from this, extra spaces |
5514 |
or tabs may be inserted with no effect anywhere except within the directive |
5515 |
name or within an argument. A comment starting with @samp{#} may appear at |
5516 |
the end of the line. |
5517 |
|
5518 |
The other two directives that play a part in a conditional are @code{else} |
5519 |
and @code{endif}. Each of these directives is written as one word, with no |
5520 |
arguments. Extra spaces are allowed and ignored at the beginning of the |
5521 |
line, and spaces or tabs at the end. A comment starting with @samp{#} may |
5522 |
appear at the end of the line. |
5523 |
|
5524 |
Conditionals affect which lines of the makefile @code{make} uses. If |
5525 |
the condition is true, @code{make} reads the lines of the |
5526 |
@var{text-if-true} as part of the makefile; if the condition is false, |
5527 |
@code{make} ignores those lines completely. It follows that syntactic |
5528 |
units of the makefile, such as rules, may safely be split across the |
5529 |
beginning or the end of the conditional.@refill |
5530 |
|
5531 |
@code{make} evaluates conditionals when it reads a makefile. |
5532 |
Consequently, you cannot use automatic variables in the tests of |
5533 |
conditionals because they are not defined until commands are run |
5534 |
(@pxref{Automatic Variables}). |
5535 |
|
5536 |
To prevent intolerable confusion, it is not permitted to start a |
5537 |
conditional in one makefile and end it in another. However, you may |
5538 |
write an @code{include} directive within a conditional, provided you do |
5539 |
not attempt to terminate the conditional inside the included file. |
5540 |
|
5541 |
@node Testing Flags, , Conditional Syntax, Conditionals |
5542 |
@section Conditionals that Test Flags |
5543 |
|
5544 |
You can write a conditional that tests @code{make} command flags such as |
5545 |
@samp{-t} by using the variable @code{MAKEFLAGS} together with the |
5546 |
@code{findstring} function |
5547 |
(@pxref{Text Functions, , Functions for String Substitution and Analysis}). |
5548 |
This is useful when @code{touch} is not enough to make a file appear up |
5549 |
to date. |
5550 |
|
5551 |
The @code{findstring} function determines whether one string appears as a |
5552 |
substring of another. If you want to test for the @samp{-t} flag, |
5553 |
use @samp{t} as the first string and the value of @code{MAKEFLAGS} as |
5554 |
the other. |
5555 |
|
5556 |
For example, here is how to arrange to use @samp{ranlib -t} to finish |
5557 |
marking an archive file up to date: |
5558 |
|
5559 |
@example |
5560 |
archive.a: @dots{} |
5561 |
ifneq (,$(findstring t,$(MAKEFLAGS))) |
5562 |
+touch archive.a |
5563 |
+ranlib -t archive.a |
5564 |
else |
5565 |
ranlib archive.a |
5566 |
endif |
5567 |
@end example |
5568 |
|
5569 |
@noindent |
5570 |
The @samp{+} prefix marks those command lines as ``recursive'' so |
5571 |
that they will be executed despite use of the @samp{-t} flag. |
5572 |
@xref{Recursion, ,Recursive Use of @code{make}}. |
5573 |
|
5574 |
@node Functions, Running, Conditionals, Top |
5575 |
@chapter Functions for Transforming Text |
5576 |
@cindex functions |
5577 |
|
5578 |
@dfn{Functions} allow you to do text processing in the makefile to compute |
5579 |
the files to operate on or the commands to use. You use a function in a |
5580 |
@dfn{function call}, where you give the name of the function and some text |
5581 |
(the @dfn{arguments}) for the function to operate on. The result of the |
5582 |
function's processing is substituted into the makefile at the point of the |
5583 |
call, just as a variable might be substituted. |
5584 |
|
5585 |
@menu |
5586 |
* Syntax of Functions:: How to write a function call. |
5587 |
* Text Functions:: General-purpose text manipulation functions. |
5588 |
* File Name Functions:: Functions for manipulating file names. |
5589 |
* Foreach Function:: Repeat some text with controlled variation. |
5590 |
* If Function:: Conditionally expand a value. |
5591 |
* Call Function:: Expand a user-defined function. |
5592 |
* Value Function:: Return the un-expanded value of a variable. |
5593 |
* Eval Function:: Evaluate the arguments as makefile syntax. |
5594 |
* Origin Function:: Find where a variable got its value. |
5595 |
* Shell Function:: Substitute the output of a shell command. |
5596 |
* Make Control Functions:: Functions that control how make runs. |
5597 |
@end menu |
5598 |
|
5599 |
@node Syntax of Functions, Text Functions, Functions, Functions |
5600 |
@section Function Call Syntax |
5601 |
@cindex @code{$}, in function call |
5602 |
@cindex dollar sign (@code{$}), in function call |
5603 |
@cindex arguments of functions |
5604 |
@cindex functions, syntax of |
5605 |
|
5606 |
A function call resembles a variable reference. It looks like this: |
5607 |
|
5608 |
@example |
5609 |
$(@var{function} @var{arguments}) |
5610 |
@end example |
5611 |
|
5612 |
@noindent |
5613 |
or like this: |
5614 |
|
5615 |
@example |
5616 |
$@{@var{function} @var{arguments}@} |
5617 |
@end example |
5618 |
|
5619 |
Here @var{function} is a function name; one of a short list of names |
5620 |
that are part of @code{make}. You can also essentially create your own |
5621 |
functions by using the @code{call} builtin function. |
5622 |
|
5623 |
The @var{arguments} are the arguments of the function. They are |
5624 |
separated from the function name by one or more spaces or tabs, and if |
5625 |
there is more than one argument, then they are separated by commas. |
5626 |
Such whitespace and commas are not part of an argument's value. The |
5627 |
delimiters which you use to surround the function call, whether |
5628 |
parentheses or braces, can appear in an argument only in matching pairs; |
5629 |
the other kind of delimiters may appear singly. If the arguments |
5630 |
themselves contain other function calls or variable references, it is |
5631 |
wisest to use the same kind of delimiters for all the references; write |
5632 |
@w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This |
5633 |
is because it is clearer, and because only one type of delimiter is |
5634 |
matched to find the end of the reference. |
5635 |
|
5636 |
The text written for each argument is processed by substitution of |
5637 |
variables and function calls to produce the argument value, which |
5638 |
is the text on which the function acts. The substitution is done in the |
5639 |
order in which the arguments appear. |
5640 |
|
5641 |
Commas and unmatched parentheses or braces cannot appear in the text of an |
5642 |
argument as written; leading spaces cannot appear in the text of the first |
5643 |
argument as written. These characters can be put into the argument value |
5644 |
by variable substitution. First define variables @code{comma} and |
5645 |
@code{space} whose values are isolated comma and space characters, then |
5646 |
substitute these variables where such characters are wanted, like this: |
5647 |
|
5648 |
@example |
5649 |
@group |
5650 |
comma:= , |
5651 |
empty:= |
5652 |
space:= $(empty) $(empty) |
5653 |
foo:= a b c |
5654 |
bar:= $(subst $(space),$(comma),$(foo)) |
5655 |
# @r{bar is now `a,b,c'.} |
5656 |
@end group |
5657 |
@end example |
5658 |
|
5659 |
@noindent |
5660 |
Here the @code{subst} function replaces each space with a comma, through |
5661 |
the value of @code{foo}, and substitutes the result. |
5662 |
|
5663 |
@node Text Functions, File Name Functions, Syntax of Functions, Functions |
5664 |
@section Functions for String Substitution and Analysis |
5665 |
@cindex functions, for text |
5666 |
|
5667 |
Here are some functions that operate on strings: |
5668 |
|
5669 |
@table @code |
5670 |
@item $(subst @var{from},@var{to},@var{text}) |
5671 |
@findex subst |
5672 |
Performs a textual replacement on the text @var{text}: each occurrence |
5673 |
of @var{from} is replaced by @var{to}. The result is substituted for |
5674 |
the function call. For example, |
5675 |
|
5676 |
@example |
5677 |
$(subst ee,EE,feet on the street) |
5678 |
@end example |
5679 |
|
5680 |
substitutes the string @samp{fEEt on the strEEt}. |
5681 |
|
5682 |
@item $(patsubst @var{pattern},@var{replacement},@var{text}) |
5683 |
@findex patsubst |
5684 |
Finds whitespace-separated words in @var{text} that match |
5685 |
@var{pattern} and replaces them with @var{replacement}. Here |
5686 |
@var{pattern} may contain a @samp{%} which acts as a wildcard, |
5687 |
matching any number of any characters within a word. If |
5688 |
@var{replacement} also contains a @samp{%}, the @samp{%} is replaced |
5689 |
by the text that matched the @samp{%} in @var{pattern}. Only the first |
5690 |
@samp{%} in the @var{pattern} and @var{replacement} is treated this |
5691 |
way; any subsequent @samp{%} is unchanged.@refill |
5692 |
|
5693 |
@cindex @code{%}, quoting in @code{patsubst} |
5694 |
@cindex @code{%}, quoting with @code{\} (backslash) |
5695 |
@cindex @code{\} (backslash), to quote @code{%} |
5696 |
@cindex backslash (@code{\}), to quote @code{%} |
5697 |
@cindex quoting @code{%}, in @code{patsubst} |
5698 |
@samp{%} characters in @code{patsubst} function invocations can be |
5699 |
quoted with preceding backslashes (@samp{\}). Backslashes that would |
5700 |
otherwise quote @samp{%} characters can be quoted with more backslashes. |
5701 |
Backslashes that quote @samp{%} characters or other backslashes are |
5702 |
removed from the pattern before it is compared file names or has a stem |
5703 |
substituted into it. Backslashes that are not in danger of quoting |
5704 |
@samp{%} characters go unmolested. For example, the pattern |
5705 |
@file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the |
5706 |
operative @samp{%} character, and @samp{pattern\\} following it. The |
5707 |
final two backslashes are left alone because they cannot affect any |
5708 |
@samp{%} character.@refill |
5709 |
|
5710 |
Whitespace between words is folded into single space characters; |
5711 |
leading and trailing whitespace is discarded. |
5712 |
|
5713 |
For example, |
5714 |
|
5715 |
@example |
5716 |
$(patsubst %.c,%.o,x.c.c bar.c) |
5717 |
@end example |
5718 |
|
5719 |
@noindent |
5720 |
produces the value @samp{x.c.o bar.o}. |
5721 |
|
5722 |
Substitution references (@pxref{Substitution Refs, ,Substitution |
5723 |
References}) are a simpler way to get the effect of the @code{patsubst} |
5724 |
function: |
5725 |
|
5726 |
@example |
5727 |
$(@var{var}:@var{pattern}=@var{replacement}) |
5728 |
@end example |
5729 |
|
5730 |
@noindent |
5731 |
is equivalent to |
5732 |
|
5733 |
@example |
5734 |
$(patsubst @var{pattern},@var{replacement},$(@var{var})) |
5735 |
@end example |
5736 |
|
5737 |
The second shorthand simplifies one of the most common uses of |
5738 |
@code{patsubst}: replacing the suffix at the end of file names. |
5739 |
|
5740 |
@example |
5741 |
$(@var{var}:@var{suffix}=@var{replacement}) |
5742 |
@end example |
5743 |
|
5744 |
@noindent |
5745 |
is equivalent to |
5746 |
|
5747 |
@example |
5748 |
$(patsubst %@var{suffix},%@var{replacement},$(@var{var})) |
5749 |
@end example |
5750 |
|
5751 |
@noindent |
5752 |
For example, you might have a list of object files: |
5753 |
|
5754 |
@example |
5755 |
objects = foo.o bar.o baz.o |
5756 |
@end example |
5757 |
|
5758 |
@noindent |
5759 |
To get the list of corresponding source files, you could simply write: |
5760 |
|
5761 |
@example |
5762 |
$(objects:.o=.c) |
5763 |
@end example |
5764 |
|
5765 |
@noindent |
5766 |
instead of using the general form: |
5767 |
|
5768 |
@example |
5769 |
$(patsubst %.o,%.c,$(objects)) |
5770 |
@end example |
5771 |
|
5772 |
@item $(strip @var{string}) |
5773 |
@cindex stripping whitespace |
5774 |
@cindex whitespace, stripping |
5775 |
@cindex spaces, stripping |
5776 |
@findex strip |
5777 |
Removes leading and trailing whitespace from @var{string} and replaces |
5778 |
each internal sequence of one or more whitespace characters with a |
5779 |
single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}. |
5780 |
|
5781 |
The function @code{strip} can be very useful when used in conjunction |
5782 |
with conditionals. When comparing something with the empty string |
5783 |
@samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of |
5784 |
just whitespace to match the empty string (@pxref{Conditionals}). |
5785 |
|
5786 |
Thus, the following may fail to have the desired results: |
5787 |
|
5788 |
@example |
5789 |
.PHONY: all |
5790 |
ifneq "$(needs_made)" "" |
5791 |
all: $(needs_made) |
5792 |
else |
5793 |
all:;@@echo 'Nothing to make!' |
5794 |
endif |
5795 |
@end example |
5796 |
|
5797 |
@noindent |
5798 |
Replacing the variable reference @w{@samp{$(needs_made)}} with the |
5799 |
function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq} |
5800 |
directive would make it more robust.@refill |
5801 |
|
5802 |
@item $(findstring @var{find},@var{in}) |
5803 |
@findex findstring |
5804 |
@cindex searching for strings |
5805 |
@cindex finding strings |
5806 |
@cindex strings, searching for |
5807 |
Searches @var{in} for an occurrence of @var{find}. If it occurs, the |
5808 |
value is @var{find}; otherwise, the value is empty. You can use this |
5809 |
function in a conditional to test for the presence of a specific |
5810 |
substring in a given string. Thus, the two examples, |
5811 |
|
5812 |
@example |
5813 |
$(findstring a,a b c) |
5814 |
$(findstring a,b c) |
5815 |
@end example |
5816 |
|
5817 |
@noindent |
5818 |
produce the values @samp{a} and @samp{} (the empty string), |
5819 |
respectively. @xref{Testing Flags}, for a practical application of |
5820 |
@code{findstring}.@refill |
5821 |
|
5822 |
@need 750 |
5823 |
@findex filter |
5824 |
@cindex filtering words |
5825 |
@cindex words, filtering |
5826 |
@item $(filter @var{pattern}@dots{},@var{text}) |
5827 |
Returns all whitespace-separated words in @var{text} that @emph{do} match |
5828 |
any of the @var{pattern} words, removing any words that @emph{do not} |
5829 |
match. The patterns are written using @samp{%}, just like the patterns |
5830 |
used in the @code{patsubst} function above.@refill |
5831 |
|
5832 |
The @code{filter} function can be used to separate out different types |
5833 |
of strings (such as file names) in a variable. For example: |
5834 |
|
5835 |
@example |
5836 |
sources := foo.c bar.c baz.s ugh.h |
5837 |
foo: $(sources) |
5838 |
cc $(filter %.c %.s,$(sources)) -o foo |
5839 |
@end example |
5840 |
|
5841 |
@noindent |
5842 |
says that @file{foo} depends of @file{foo.c}, @file{bar.c}, |
5843 |
@file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and |
5844 |
@file{baz.s} should be specified in the command to the |
5845 |
compiler.@refill |
5846 |
|
5847 |
@item $(filter-out @var{pattern}@dots{},@var{text}) |
5848 |
@findex filter-out |
5849 |
@cindex filtering out words |
5850 |
@cindex words, filtering out |
5851 |
Returns all whitespace-separated words in @var{text} that @emph{do not} |
5852 |
match any of the @var{pattern} words, removing the words that @emph{do} |
5853 |
match one or more. This is the exact opposite of the @code{filter} |
5854 |
function.@refill |
5855 |
|
5856 |
For example, given: |
5857 |
|
5858 |
@example |
5859 |
@group |
5860 |
objects=main1.o foo.o main2.o bar.o |
5861 |
mains=main1.o main2.o |
5862 |
@end group |
5863 |
@end example |
5864 |
|
5865 |
@noindent |
5866 |
the following generates a list which contains all the object files not |
5867 |
in @samp{mains}: |
5868 |
|
5869 |
@example |
5870 |
$(filter-out $(mains),$(objects)) |
5871 |
@end example |
5872 |
|
5873 |
@need 1500 |
5874 |
@findex sort |
5875 |
@cindex sorting words |
5876 |
@item $(sort @var{list}) |
5877 |
Sorts the words of @var{list} in lexical order, removing duplicate |
5878 |
words. The output is a list of words separated by single spaces. |
5879 |
Thus, |
5880 |
|
5881 |
@example |
5882 |
$(sort foo bar lose) |
5883 |
@end example |
5884 |
|
5885 |
@noindent |
5886 |
returns the value @samp{bar foo lose}. |
5887 |
|
5888 |
@cindex removing duplicate words |
5889 |
@cindex duplicate words, removing |
5890 |
@cindex words, removing duplicates |
5891 |
Incidentally, since @code{sort} removes duplicate words, you can use |
5892 |
it for this purpose even if you don't care about the sort order. |
5893 |
|
5894 |
@item $(word @var{n},@var{text}) |
5895 |
@findex word |
5896 |
@cindex word, selecting a |
5897 |
@cindex selecting a word |
5898 |
Returns the @var{n}th word of @var{text}. The legitimate values of |
5899 |
@var{n} start from 1. If @var{n} is bigger than the number of words |
5900 |
in @var{text}, the value is empty. For example, |
5901 |
|
5902 |
@example |
5903 |
$(word 2, foo bar baz) |
5904 |
@end example |
5905 |
|
5906 |
@noindent |
5907 |
returns @samp{bar}. |
5908 |
|
5909 |
@item $(wordlist @var{s},@var{e},@var{text}) |
5910 |
@findex wordlist |
5911 |
@cindex words, selecting lists of |
5912 |
@cindex selecting word lists |
5913 |
Returns the list of words in @var{text} starting with word @var{s} and |
5914 |
ending with word @var{e} (inclusive). The legitimate values of @var{s} |
5915 |
and @var{e} start from 1. If @var{s} is bigger than the number of words |
5916 |
in @var{text}, the value is empty. If @var{e} is bigger than the number |
5917 |
of words in @var{text}, words up to the end of @var{text} are returned. |
5918 |
If @var{s} is greater than @var{e}, nothing is returned. For example, |
5919 |
|
5920 |
@example |
5921 |
$(wordlist 2, 3, foo bar baz) |
5922 |
@end example |
5923 |
|
5924 |
@noindent |
5925 |
returns @samp{bar baz}. |
5926 |
|
5927 |
@c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92 |
5928 |
@item $(words @var{text}) |
5929 |
@findex words |
5930 |
@cindex words, finding number |
5931 |
Returns the number of words in @var{text}. |
5932 |
Thus, the last word of @var{text} is |
5933 |
@w{@code{$(word $(words @var{text}),@var{text})}}.@refill |
5934 |
|
5935 |
@item $(firstword @var{names}@dots{}) |
5936 |
@findex firstword |
5937 |
@cindex words, extracting first |
5938 |
The argument @var{names} is regarded as a series of names, separated |
5939 |
by whitespace. The value is the first name in the series. The rest |
5940 |
of the names are ignored. |
5941 |
|
5942 |
For example, |
5943 |
|
5944 |
@example |
5945 |
$(firstword foo bar) |
5946 |
@end example |
5947 |
|
5948 |
@noindent |
5949 |
produces the result @samp{foo}. Although @code{$(firstword |
5950 |
@var{text})} is the same as @code{$(word 1,@var{text})}, the |
5951 |
@code{firstword} function is retained for its simplicity.@refill |
5952 |
@end table |
5953 |
|
5954 |
Here is a realistic example of the use of @code{subst} and |
5955 |
@code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable |
5956 |
to specify a list of directories that @code{make} should search for |
5957 |
prerequisite files |
5958 |
(@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}). |
5959 |
This example shows how to |
5960 |
tell the C compiler to search for header files in the same list of |
5961 |
directories.@refill |
5962 |
|
5963 |
The value of @code{VPATH} is a list of directories separated by colons, |
5964 |
such as @samp{src:../headers}. First, the @code{subst} function is used to |
5965 |
change the colons to spaces: |
5966 |
|
5967 |
@example |
5968 |
$(subst :, ,$(VPATH)) |
5969 |
@end example |
5970 |
|
5971 |
@noindent |
5972 |
This produces @samp{src ../headers}. Then @code{patsubst} is used to turn |
5973 |
each directory name into a @samp{-I} flag. These can be added to the |
5974 |
value of the variable @code{CFLAGS}, which is passed automatically to the C |
5975 |
compiler, like this: |
5976 |
|
5977 |
@example |
5978 |
override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH))) |
5979 |
@end example |
5980 |
|
5981 |
@noindent |
5982 |
The effect is to append the text @samp{-Isrc -I../headers} to the |
5983 |
previously given value of @code{CFLAGS}. The @code{override} directive is |
5984 |
used so that the new value is assigned even if the previous value of |
5985 |
@code{CFLAGS} was specified with a command argument (@pxref{Override |
5986 |
Directive, , The @code{override} Directive}). |
5987 |
|
5988 |
@node File Name Functions, Foreach Function, Text Functions, Functions |
5989 |
@section Functions for File Names |
5990 |
@cindex functions, for file names |
5991 |
@cindex file name functions |
5992 |
|
5993 |
Several of the built-in expansion functions relate specifically to |
5994 |
taking apart file names or lists of file names. |
5995 |
|
5996 |
Each of the following functions performs a specific transformation on a |
5997 |
file name. The argument of the function is regarded as a series of file |
5998 |
names, separated by whitespace. (Leading and trailing whitespace is |
5999 |
ignored.) Each file name in the series is transformed in the same way and |
6000 |
the results are concatenated with single spaces between them. |
6001 |
|
6002 |
@table @code |
6003 |
@item $(dir @var{names}@dots{}) |
6004 |
@findex dir |
6005 |
@cindex directory part |
6006 |
@cindex file name, directory part |
6007 |
Extracts the directory-part of each file name in @var{names}. The |
6008 |
directory-part of the file name is everything up through (and |
6009 |
including) the last slash in it. If the file name contains no slash, |
6010 |
the directory part is the string @samp{./}. For example, |
6011 |
|
6012 |
@example |
6013 |
$(dir src/foo.c hacks) |
6014 |
@end example |
6015 |
|
6016 |
@noindent |
6017 |
produces the result @samp{src/ ./}. |
6018 |
|
6019 |
@item $(notdir @var{names}@dots{}) |
6020 |
@findex notdir |
6021 |
@cindex file name, nondirectory part |
6022 |
@cindex nondirectory part |
6023 |
Extracts all but the directory-part of each file name in @var{names}. |
6024 |
If the file name contains no slash, it is left unchanged. Otherwise, |
6025 |
everything through the last slash is removed from it. |
6026 |
|
6027 |
A file name that ends with a slash becomes an empty string. This is |
6028 |
unfortunate, because it means that the result does not always have the |
6029 |
same number of whitespace-separated file names as the argument had; |
6030 |
but we do not see any other valid alternative. |
6031 |
|
6032 |
For example, |
6033 |
|
6034 |
@example |
6035 |
$(notdir src/foo.c hacks) |
6036 |
@end example |
6037 |
|
6038 |
@noindent |
6039 |
produces the result @samp{foo.c hacks}. |
6040 |
|
6041 |
@item $(suffix @var{names}@dots{}) |
6042 |
@findex suffix |
6043 |
@cindex suffix, function to find |
6044 |
@cindex file name suffix |
6045 |
Extracts the suffix of each file name in @var{names}. If the file name |
6046 |
contains a period, the suffix is everything starting with the last |
6047 |
period. Otherwise, the suffix is the empty string. This frequently |
6048 |
means that the result will be empty when @var{names} is not, and if |
6049 |
@var{names} contains multiple file names, the result may contain fewer |
6050 |
file names. |
6051 |
|
6052 |
For example, |
6053 |
|
6054 |
@example |
6055 |
$(suffix src/foo.c src-1.0/bar.c hacks) |
6056 |
@end example |
6057 |
|
6058 |
@noindent |
6059 |
produces the result @samp{.c .c}. |
6060 |
|
6061 |
@item $(basename @var{names}@dots{}) |
6062 |
@findex basename |
6063 |
@cindex basename |
6064 |
@cindex file name, basename of |
6065 |
Extracts all but the suffix of each file name in @var{names}. If the |
6066 |
file name contains a period, the basename is everything starting up to |
6067 |
(and not including) the last period. Periods in the directory part are |
6068 |
ignored. If there is no period, the basename is the entire file name. |
6069 |
For example, |
6070 |
|
6071 |
@example |
6072 |
$(basename src/foo.c src-1.0/bar hacks) |
6073 |
@end example |
6074 |
|
6075 |
@noindent |
6076 |
produces the result @samp{src/foo src-1.0/bar hacks}. |
6077 |
|
6078 |
@c plural convention with dots (be consistent) |
6079 |
@item $(addsuffix @var{suffix},@var{names}@dots{}) |
6080 |
@findex addsuffix |
6081 |
@cindex suffix, adding |
6082 |
@cindex file name suffix, adding |
6083 |
The argument @var{names} is regarded as a series of names, separated |
6084 |
by whitespace; @var{suffix} is used as a unit. The value of |
6085 |
@var{suffix} is appended to the end of each individual name and the |
6086 |
resulting larger names are concatenated with single spaces between |
6087 |
them. For example, |
6088 |
|
6089 |
@example |
6090 |
$(addsuffix .c,foo bar) |
6091 |
@end example |
6092 |
|
6093 |
@noindent |
6094 |
produces the result @samp{foo.c bar.c}. |
6095 |
|
6096 |
@item $(addprefix @var{prefix},@var{names}@dots{}) |
6097 |
@findex addprefix |
6098 |
@cindex prefix, adding |
6099 |
@cindex file name prefix, adding |
6100 |
The argument @var{names} is regarded as a series of names, separated |
6101 |
by whitespace; @var{prefix} is used as a unit. The value of |
6102 |
@var{prefix} is prepended to the front of each individual name and the |
6103 |
resulting larger names are concatenated with single spaces between |
6104 |
them. For example, |
6105 |
|
6106 |
@example |
6107 |
$(addprefix src/,foo bar) |
6108 |
@end example |
6109 |
|
6110 |
@noindent |
6111 |
produces the result @samp{src/foo src/bar}. |
6112 |
|
6113 |
@item $(join @var{list1},@var{list2}) |
6114 |
@findex join |
6115 |
@cindex joining lists of words |
6116 |
@cindex words, joining lists |
6117 |
Concatenates the two arguments word by word: the two first words (one |
6118 |
from each argument) concatenated form the first word of the result, the |
6119 |
two second words form the second word of the result, and so on. So the |
6120 |
@var{n}th word of the result comes from the @var{n}th word of each |
6121 |
argument. If one argument has more words that the other, the extra |
6122 |
words are copied unchanged into the result. |
6123 |
|
6124 |
For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}. |
6125 |
|
6126 |
Whitespace between the words in the lists is not preserved; it is |
6127 |
replaced with a single space. |
6128 |
|
6129 |
This function can merge the results of the @code{dir} and |
6130 |
@code{notdir} functions, to produce the original list of files which |
6131 |
was given to those two functions.@refill |
6132 |
|
6133 |
@item $(wildcard @var{pattern}) |
6134 |
@findex wildcard |
6135 |
@cindex wildcard, function |
6136 |
The argument @var{pattern} is a file name pattern, typically containing |
6137 |
wildcard characters (as in shell file name patterns). The result of |
6138 |
@code{wildcard} is a space-separated list of the names of existing files |
6139 |
that match the pattern. |
6140 |
@xref{Wildcards, ,Using Wildcard Characters in File Names}. |
6141 |
@end table |
6142 |
|
6143 |
@node Foreach Function, If Function, File Name Functions, Functions |
6144 |
@section The @code{foreach} Function |
6145 |
@findex foreach |
6146 |
@cindex words, iterating over |
6147 |
|
6148 |
The @code{foreach} function is very different from other functions. It |
6149 |
causes one piece of text to be used repeatedly, each time with a different |
6150 |
substitution performed on it. It resembles the @code{for} command in the |
6151 |
shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}. |
6152 |
|
6153 |
The syntax of the @code{foreach} function is: |
6154 |
|
6155 |
@example |
6156 |
$(foreach @var{var},@var{list},@var{text}) |
6157 |
@end example |
6158 |
|
6159 |
@noindent |
6160 |
The first two arguments, @var{var} and @var{list}, are expanded before |
6161 |
anything else is done; note that the last argument, @var{text}, is |
6162 |
@strong{not} expanded at the same time. Then for each word of the expanded |
6163 |
value of @var{list}, the variable named by the expanded value of @var{var} |
6164 |
is set to that word, and @var{text} is expanded. Presumably @var{text} |
6165 |
contains references to that variable, so its expansion will be different |
6166 |
each time. |
6167 |
|
6168 |
The result is that @var{text} is expanded as many times as there are |
6169 |
whitespace-separated words in @var{list}. The multiple expansions of |
6170 |
@var{text} are concatenated, with spaces between them, to make the result |
6171 |
of @code{foreach}. |
6172 |
|
6173 |
This simple example sets the variable @samp{files} to the list of all files |
6174 |
in the directories in the list @samp{dirs}: |
6175 |
|
6176 |
@example |
6177 |
dirs := a b c d |
6178 |
files := $(foreach dir,$(dirs),$(wildcard $(dir)/*)) |
6179 |
@end example |
6180 |
|
6181 |
Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition |
6182 |
finds the value @samp{a} for @code{dir}, so it produces the same result |
6183 |
as @samp{$(wildcard a/*)}; the second repetition produces the result |
6184 |
of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}. |
6185 |
|
6186 |
This example has the same result (except for setting @samp{dirs}) as |
6187 |
the following example: |
6188 |
|
6189 |
@example |
6190 |
files := $(wildcard a/* b/* c/* d/*) |
6191 |
@end example |
6192 |
|
6193 |
When @var{text} is complicated, you can improve readability by giving it |
6194 |
a name, with an additional variable: |
6195 |
|
6196 |
@example |
6197 |
find_files = $(wildcard $(dir)/*) |
6198 |
dirs := a b c d |
6199 |
files := $(foreach dir,$(dirs),$(find_files)) |
6200 |
@end example |
6201 |
|
6202 |
@noindent |
6203 |
Here we use the variable @code{find_files} this way. We use plain @samp{=} |
6204 |
to define a recursively-expanding variable, so that its value contains an |
6205 |
actual function call to be reexpanded under the control of @code{foreach}; |
6206 |
a simply-expanded variable would not do, since @code{wildcard} would be |
6207 |
called only once at the time of defining @code{find_files}. |
6208 |
|
6209 |
The @code{foreach} function has no permanent effect on the variable |
6210 |
@var{var}; its value and flavor after the @code{foreach} function call are |
6211 |
the same as they were beforehand. The other values which are taken from |
6212 |
@var{list} are in effect only temporarily, during the execution of |
6213 |
@code{foreach}. The variable @var{var} is a simply-expanded variable |
6214 |
during the execution of @code{foreach}. If @var{var} was undefined |
6215 |
before the @code{foreach} function call, it is undefined after the call. |
6216 |
@xref{Flavors, ,The Two Flavors of Variables}.@refill |
6217 |
|
6218 |
You must take care when using complex variable expressions that result in |
6219 |
variable names because many strange things are valid variable names, but |
6220 |
are probably not what you intended. For example, |
6221 |
|
6222 |
@smallexample |
6223 |
files := $(foreach Esta escrito en espanol!,b c ch,$(find_files)) |
6224 |
@end smallexample |
6225 |
|
6226 |
@noindent |
6227 |
might be useful if the value of @code{find_files} references the variable |
6228 |
whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo, |
6229 |
no?), but it is more likely to be a mistake. |
6230 |
|
6231 |
@node If Function, Call Function, Foreach Function, Functions |
6232 |
@section The @code{if} Function |
6233 |
@findex if |
6234 |
@cindex conditional expansion |
6235 |
|
6236 |
The @code{if} function provides support for conditional expansion in a |
6237 |
functional context (as opposed to the GNU @code{make} makefile |
6238 |
conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of |
6239 |
Conditionals}). |
6240 |
|
6241 |
An @code{if} function call can contain either two or three arguments: |
6242 |
|
6243 |
@example |
6244 |
$(if @var{condition},@var{then-part}[,@var{else-part}]) |
6245 |
@end example |
6246 |
|
6247 |
The first argument, @var{condition}, first has all preceding and |
6248 |
trailing whitespace stripped, then is expanded. If it expands to any |
6249 |
non-empty string, then the condition is considered to be true. If it |
6250 |
expands to an empty string, the condition is considered to be false. |
6251 |
|
6252 |
If the condition is true then the second argument, @var{then-part}, is |
6253 |
evaluated and this is used as the result of the evaluation of the entire |
6254 |
@code{if} function. |
6255 |
|
6256 |
If the condition is false then the third argument, @var{else-part}, is |
6257 |
evaluated and this is the result of the @code{if} function. If there is |
6258 |
no third argument, the @code{if} function evaluates to nothing (the |
6259 |
empty string). |
6260 |
|
6261 |
Note that only one of the @var{then-part} or the @var{else-part} will be |
6262 |
evaluated, never both. Thus, either can contain side-effects (such as |
6263 |
@code{shell} function calls, etc.) |
6264 |
|
6265 |
@node Call Function, Value Function, If Function, Functions |
6266 |
@section The @code{call} Function |
6267 |
@findex call |
6268 |
@cindex functions, user defined |
6269 |
@cindex user defined functions |
6270 |
|
6271 |
The @code{call} function is unique in that it can be used to create new |
6272 |
parameterized functions. You can write a complex expression as the |
6273 |
value of a variable, then use @code{call} to expand it with different |
6274 |
values. |
6275 |
|
6276 |
The syntax of the @code{call} function is: |
6277 |
|
6278 |
@example |
6279 |
$(call @var{variable},@var{param},@var{param},@dots{}) |
6280 |
@end example |
6281 |
|
6282 |
When @code{make} expands this function, it assigns each @var{param} to |
6283 |
temporary variables @code{$(1)}, @code{$(2)}, etc. The variable |
6284 |
@code{$(0)} will contain @var{variable}. There is no maximum number of |
6285 |
parameter arguments. There is no minimum, either, but it doesn't make |
6286 |
sense to use @code{call} with no parameters. |
6287 |
|
6288 |
Then @var{variable} is expanded as a @code{make} variable in the context |
6289 |
of these temporary assignments. Thus, any reference to @code{$(1)} in |
6290 |
the value of @var{variable} will resolve to the first @var{param} in the |
6291 |
invocation of @code{call}. |
6292 |
|
6293 |
Note that @var{variable} is the @emph{name} of a variable, not a |
6294 |
@emph{reference} to that variable. Therefore you would not normally use |
6295 |
a @samp{$} or parentheses when writing it. (You can, however, use a |
6296 |
variable reference in the name if you want the name not to be a |
6297 |
constant.) |
6298 |
|
6299 |
If @var{variable} is the name of a builtin function, the builtin function |
6300 |
is always invoked (even if a @code{make} variable by that name also |
6301 |
exists). |
6302 |
|
6303 |
The @code{call} function expands the @var{param} arguments before |
6304 |
assigning them to temporary variables. This means that @var{variable} |
6305 |
values containing references to builtin functions that have special |
6306 |
expansion rules, like @code{foreach} or @code{if}, may not work as you |
6307 |
expect. |
6308 |
|
6309 |
Some examples may make this clearer. |
6310 |
|
6311 |
This macro simply reverses its arguments: |
6312 |
|
6313 |
@smallexample |
6314 |
reverse = $(2) $(1) |
6315 |
|
6316 |
foo = $(call reverse,a,b) |
6317 |
@end smallexample |
6318 |
|
6319 |
@noindent |
6320 |
Here @var{foo} will contain @samp{b a}. |
6321 |
|
6322 |
This one is slightly more interesting: it defines a macro to search for |
6323 |
the first instance of a program in @code{PATH}: |
6324 |
|
6325 |
@smallexample |
6326 |
pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH))))) |
6327 |
|
6328 |
LS := $(call pathsearch,ls) |
6329 |
@end smallexample |
6330 |
|
6331 |
@noindent |
6332 |
Now the variable LS contains @code{/bin/ls} or similar. |
6333 |
|
6334 |
The @code{call} function can be nested. Each recursive invocation gets |
6335 |
its own local values for @code{$(1)}, etc. that mask the values of |
6336 |
higher-level @code{call}. For example, here is an implementation of a |
6337 |
@dfn{map} function: |
6338 |
|
6339 |
@smallexample |
6340 |
map = $(foreach a,$(2),$(call $(1),$(a))) |
6341 |
@end smallexample |
6342 |
|
6343 |
Now you can @var{map} a function that normally takes only one argument, |
6344 |
such as @code{origin}, to multiple values in one step: |
6345 |
|
6346 |
@smallexample |
6347 |
o = $(call map,origin,o map MAKE) |
6348 |
@end smallexample |
6349 |
|
6350 |
and end up with @var{o} containing something like @samp{file file default}. |
6351 |
|
6352 |
A final caution: be careful when adding whitespace to the arguments to |
6353 |
@code{call}. As with other functions, any whitespace contained in the |
6354 |
second and subsequent arguments is kept; this can cause strange |
6355 |
effects. It's generally safest to remove all extraneous whitespace when |
6356 |
providing parameters to @code{call}. |
6357 |
|
6358 |
@node Value Function, Eval Function, Call Function, Functions |
6359 |
@comment node-name, next, previous, up |
6360 |
@section The @code{value} Function |
6361 |
@findex value |
6362 |
@cindex variables, unexpanded value |
6363 |
|
6364 |
The @code{value} function provides a way for you to use the value of a |
6365 |
variable @emph{without} having it expanded. Please note that this |
6366 |
does not undo expansions which have already occurred; for example if |
6367 |
you create a simply expanded variable its value is expanded during the |
6368 |
definition; in that case the @code{value} function will return the |
6369 |
same result as using the variable directly. |
6370 |
|
6371 |
The syntax of the @code{value} function is: |
6372 |
|
6373 |
@example |
6374 |
$(value @var{variable}) |
6375 |
@end example |
6376 |
|
6377 |
Note that @var{variable} is the @emph{name} of a variable; not a |
6378 |
@emph{reference} to that variable. Therefore you would not normally |
6379 |
use a @samp{$} or parentheses when writing it. (You can, however, use |
6380 |
a variable reference in the name if you want the name not to be a |
6381 |
constant.) |
6382 |
|
6383 |
The result of this function is a string containing the value of |
6384 |
@var{variable}, without any expansion occurring. For example, in this |
6385 |
makefile: |
6386 |
|
6387 |
@example |
6388 |
@group |
6389 |
FOO = $PATH |
6390 |
|
6391 |
all: |
6392 |
@@echo $(FOO) |
6393 |
@@echo $(value FOO) |
6394 |
@end group |
6395 |
@end example |
6396 |
|
6397 |
@noindent |
6398 |
The first output line would be @code{ATH}, since the ``$P'' would be |
6399 |
expanded as a @code{make} variable, while the second output line would |
6400 |
be the current value of your @code{$PATH} environment variable, since |
6401 |
the @code{value} function avoided the expansion. |
6402 |
|
6403 |
The @code{value} function is most often used in conjunction with the |
6404 |
@code{eval} function (@pxref{Eval Function}). |
6405 |
|
6406 |
@node Eval Function, Origin Function, Value Function, Functions |
6407 |
@comment node-name, next, previous, up |
6408 |
@section The @code{eval} Function |
6409 |
@findex eval |
6410 |
@cindex evaluating makefile syntax |
6411 |
@cindex makefile syntax, evaluating |
6412 |
|
6413 |
The @code{eval} function is very special: it allows you to define new |
6414 |
makefile constructs that are not constant; which are the result of |
6415 |
evaluating other variables and functions. The argument to the |
6416 |
@code{eval} function is expanded, then the results of that expansion |
6417 |
are parsed as makefile syntax. The expanded results can define new |
6418 |
@code{make} variables, targets, implicit or explicit rules, etc. |
6419 |
|
6420 |
The result of the @code{eval} function is always the empty string; |
6421 |
thus, it can be placed virtually anywhere in a makefile without |
6422 |
causing syntax errors. |
6423 |
|
6424 |
It's important to realize that the @code{eval} argument is expanded |
6425 |
@emph{twice}; first by the @code{eval} function, then the results of |
6426 |
that expansion are expanded again when they are parsed as makefile |
6427 |
syntax. This means you may need to provide extra levels of escaping |
6428 |
for ``$'' characters when using @code{eval}. The @code{value} |
6429 |
function (@pxref{Value Function}) can sometimes be useful in these |
6430 |
situations, to circumvent unwanted expansions. |
6431 |
|
6432 |
Here is an example of how @code{eval} can be used; this example |
6433 |
combines a number of concepts and other functions. Although it might |
6434 |
seem overly complex to use @code{eval} in this example, rather than |
6435 |
just writing out the rules, consider two things: first, the template |
6436 |
definition (in @code{PROGRAM_template}) could need to be much more |
6437 |
complex than it is here; and second, you might put the complex, |
6438 |
``generic'' part of this example into another makefile, then include |
6439 |
it in all the individual makefiles. Now your individual makefiles are |
6440 |
quite straightforward. |
6441 |
|
6442 |
@example |
6443 |
@group |
6444 |
PROGRAMS = server client |
6445 |
|
6446 |
server_OBJS = server.o server_priv.o server_access.o |
6447 |
server_LIBS = priv protocol |
6448 |
|
6449 |
client_OBJS = client.o client_api.o client_mem.o |
6450 |
client_LIBS = protocol |
6451 |
|
6452 |
# Everything after this is generic |
6453 |
|
6454 |
.PHONY: all |
6455 |
all: $(PROGRAMS) |
6456 |
|
6457 |
define PROGRAM_template |
6458 |
$(1): $$($(1)_OBJ) $$($(1)_LIBS:%=-l%) |
6459 |
ALL_OBJS += $$($(1)_OBJS) |
6460 |
endef |
6461 |
|
6462 |
$(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog)))) |
6463 |
|
6464 |
$(PROGRAMS): |
6465 |
$(LINK.o) $^ $(LDLIBS) -o $@@ |
6466 |
|
6467 |
clean: |
6468 |
rm -f $(ALL_OBJS) $(PROGRAMS) |
6469 |
@end group |
6470 |
@end example |
6471 |
|
6472 |
@node Origin Function, Shell Function, Eval Function, Functions |
6473 |
@section The @code{origin} Function |
6474 |
@findex origin |
6475 |
@cindex variables, origin of |
6476 |
@cindex origin of variable |
6477 |
|
6478 |
The @code{origin} function is unlike most other functions in that it does |
6479 |
not operate on the values of variables; it tells you something @emph{about} |
6480 |
a variable. Specifically, it tells you where it came from. |
6481 |
|
6482 |
The syntax of the @code{origin} function is: |
6483 |
|
6484 |
@example |
6485 |
$(origin @var{variable}) |
6486 |
@end example |
6487 |
|
6488 |
Note that @var{variable} is the @emph{name} of a variable to inquire about; |
6489 |
not a @emph{reference} to that variable. Therefore you would not normally |
6490 |
use a @samp{$} or parentheses when writing it. (You can, however, use a |
6491 |
variable reference in the name if you want the name not to be a constant.) |
6492 |
|
6493 |
The result of this function is a string telling you how the variable |
6494 |
@var{variable} was defined: |
6495 |
|
6496 |
@table @samp |
6497 |
@item undefined |
6498 |
|
6499 |
if @var{variable} was never defined. |
6500 |
|
6501 |
@item default |
6502 |
|
6503 |
if @var{variable} has a default definition, as is usual with @code{CC} |
6504 |
and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. |
6505 |
Note that if you have redefined a default variable, the @code{origin} |
6506 |
function will return the origin of the later definition. |
6507 |
|
6508 |
@item environment |
6509 |
|
6510 |
if @var{variable} was defined as an environment variable and the |
6511 |
@samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}). |
6512 |
|
6513 |
@item environment override |
6514 |
|
6515 |
if @var{variable} was defined as an environment variable and the |
6516 |
@w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary, |
6517 |
,Summary of Options}).@refill |
6518 |
|
6519 |
@item file |
6520 |
|
6521 |
if @var{variable} was defined in a makefile. |
6522 |
|
6523 |
@item command line |
6524 |
|
6525 |
if @var{variable} was defined on the command line. |
6526 |
|
6527 |
@item override |
6528 |
|
6529 |
if @var{variable} was defined with an @code{override} directive in a |
6530 |
makefile (@pxref{Override Directive, ,The @code{override} Directive}). |
6531 |
|
6532 |
@item automatic |
6533 |
|
6534 |
if @var{variable} is an automatic variable defined for the |
6535 |
execution of the commands for each rule |
6536 |
(@pxref{Automatic Variables}). |
6537 |
@end table |
6538 |
|
6539 |
This information is primarily useful (other than for your curiosity) to |
6540 |
determine if you want to believe the value of a variable. For example, |
6541 |
suppose you have a makefile @file{foo} that includes another makefile |
6542 |
@file{bar}. You want a variable @code{bletch} to be defined in @file{bar} |
6543 |
if you run the command @w{@samp{make -f bar}}, even if the environment contains |
6544 |
a definition of @code{bletch}. However, if @file{foo} defined |
6545 |
@code{bletch} before including @file{bar}, you do not want to override that |
6546 |
definition. This could be done by using an @code{override} directive in |
6547 |
@file{foo}, giving that definition precedence over the later definition in |
6548 |
@file{bar}; unfortunately, the @code{override} directive would also |
6549 |
override any command line definitions. So, @file{bar} could |
6550 |
include:@refill |
6551 |
|
6552 |
@example |
6553 |
@group |
6554 |
ifdef bletch |
6555 |
ifeq "$(origin bletch)" "environment" |
6556 |
bletch = barf, gag, etc. |
6557 |
endif |
6558 |
endif |
6559 |
@end group |
6560 |
@end example |
6561 |
|
6562 |
@noindent |
6563 |
If @code{bletch} has been defined from the environment, this will redefine |
6564 |
it. |
6565 |
|
6566 |
If you want to override a previous definition of @code{bletch} if it came |
6567 |
from the environment, even under @samp{-e}, you could instead write: |
6568 |
|
6569 |
@example |
6570 |
@group |
6571 |
ifneq "$(findstring environment,$(origin bletch))" "" |
6572 |
bletch = barf, gag, etc. |
6573 |
endif |
6574 |
@end group |
6575 |
@end example |
6576 |
|
6577 |
Here the redefinition takes place if @samp{$(origin bletch)} returns either |
6578 |
@samp{environment} or @samp{environment override}. |
6579 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
6580 |
|
6581 |
@node Shell Function, Make Control Functions, Origin Function, Functions |
6582 |
@section The @code{shell} Function |
6583 |
@findex shell |
6584 |
@cindex commands, expansion |
6585 |
@cindex backquotes |
6586 |
@cindex shell command, function for |
6587 |
|
6588 |
The @code{shell} function is unlike any other function except the |
6589 |
@code{wildcard} function |
6590 |
(@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it |
6591 |
communicates with the world outside of @code{make}. |
6592 |
|
6593 |
The @code{shell} function performs the same function that backquotes |
6594 |
(@samp{`}) perform in most shells: it does @dfn{command expansion}. This |
6595 |
means that it takes an argument that is a shell command and returns the |
6596 |
output of the command. The only processing @code{make} does on the result, |
6597 |
before substituting it into the surrounding text, is to convert each |
6598 |
newline or carriage-return / newline pair to a single space. It also |
6599 |
removes the trailing (carriage-return and) newline, if it's the last |
6600 |
thing in the result.@refill |
6601 |
|
6602 |
The commands run by calls to the @code{shell} function are run when the |
6603 |
function calls are expanded (@pxref{Reading Makefiles, , How |
6604 |
@code{make} Reads a Makefile}). Because this function involves |
6605 |
spawning a new shell, you should carefully consider the performance |
6606 |
implications of using the @code{shell} function within recursively |
6607 |
expanded variables vs. simply expanded variables (@pxref{Flavors, ,The |
6608 |
Two Flavors of Variables}). |
6609 |
|
6610 |
Here are some examples of the use of the @code{shell} function: |
6611 |
|
6612 |
@example |
6613 |
contents := $(shell cat foo) |
6614 |
@end example |
6615 |
|
6616 |
@noindent |
6617 |
sets @code{contents} to the contents of the file @file{foo}, with a space |
6618 |
(rather than a newline) separating each line. |
6619 |
|
6620 |
@example |
6621 |
files := $(shell echo *.c) |
6622 |
@end example |
6623 |
|
6624 |
@noindent |
6625 |
sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is |
6626 |
using a very strange shell, this has the same result as |
6627 |
@w{@samp{$(wildcard *.c)}}.@refill |
6628 |
|
6629 |
@node Make Control Functions, , Shell Function, Functions |
6630 |
@section Functions That Control Make |
6631 |
@cindex functions, for controlling make |
6632 |
@cindex controlling make |
6633 |
|
6634 |
These functions control the way make runs. Generally, they are used to |
6635 |
provide information to the user of the makefile or to cause make to stop |
6636 |
if some sort of environmental error is detected. |
6637 |
|
6638 |
@table @code |
6639 |
@item $(error @var{text}@dots{}) |
6640 |
@findex error |
6641 |
@cindex error, stopping on |
6642 |
@cindex stopping make |
6643 |
Generates a fatal error where the message is @var{text}. Note that the |
6644 |
error is generated whenever this function is evaluated. So, if you put |
6645 |
it inside a command script or on the right side of a recursive variable |
6646 |
assignment, it won't be evaluated until later. The @var{text} will be |
6647 |
expanded before the error is generated. |
6648 |
|
6649 |
For example, |
6650 |
|
6651 |
@example |
6652 |
ifdef ERROR1 |
6653 |
$(error error is $(ERROR1)) |
6654 |
endif |
6655 |
@end example |
6656 |
|
6657 |
@noindent |
6658 |
will generate a fatal error during the read of the makefile if the |
6659 |
@code{make} variable @code{ERROR1} is defined. Or, |
6660 |
|
6661 |
@example |
6662 |
ERR = $(error found an error!) |
6663 |
|
6664 |
.PHONY: err |
6665 |
err: ; $(ERR) |
6666 |
@end example |
6667 |
|
6668 |
@noindent |
6669 |
will generate a fatal error while @code{make} is running, if the |
6670 |
@code{err} target is invoked. |
6671 |
|
6672 |
@item $(warning @var{text}@dots{}) |
6673 |
@findex warning |
6674 |
@cindex warnings, printing |
6675 |
@cindex printing user warnings |
6676 |
This function works similarly to the @code{error} function, above, |
6677 |
except that @code{make} doesn't exit. Instead, @var{text} is expanded |
6678 |
and the resulting message is displayed, but processing of the makefile |
6679 |
continues. |
6680 |
|
6681 |
The result of the expansion of this function is the empty string. |
6682 |
@end table |
6683 |
|
6684 |
@node Running, Implicit Rules, Functions, Top |
6685 |
@chapter How to Run @code{make} |
6686 |
|
6687 |
A makefile that says how to recompile a program can be used in more |
6688 |
than one way. The simplest use is to recompile every file that is out |
6689 |
of date. Usually, makefiles are written so that if you run |
6690 |
@code{make} with no arguments, it does just that. |
6691 |
|
6692 |
But you might want to update only some of the files; you might want to use |
6693 |
a different compiler or different compiler options; you might want just to |
6694 |
find out which files are out of date without changing them. |
6695 |
|
6696 |
By giving arguments when you run @code{make}, you can do any of these |
6697 |
things and many others. |
6698 |
|
6699 |
The exit status of @code{make} is always one of three values: |
6700 |
@table @code |
6701 |
@item 0 |
6702 |
The exit status is zero if @code{make} is successful. |
6703 |
@item 2 |
6704 |
The exit status is two if @code{make} encounters any errors. |
6705 |
It will print messages describing the particular errors. |
6706 |
@item 1 |
6707 |
The exit status is one if you use the @samp{-q} flag and @code{make} |
6708 |
determines that some target is not already up to date. |
6709 |
@xref{Instead of Execution, ,Instead of Executing the Commands}. |
6710 |
@end table |
6711 |
|
6712 |
@menu |
6713 |
* Makefile Arguments:: How to specify which makefile to use. |
6714 |
* Goals:: How to use goal arguments to specify which |
6715 |
parts of the makefile to use. |
6716 |
* Instead of Execution:: How to use mode flags to specify what |
6717 |
kind of thing to do with the commands |
6718 |
in the makefile other than simply |
6719 |
execute them. |
6720 |
* Avoiding Compilation:: How to avoid recompiling certain files. |
6721 |
* Overriding:: How to override a variable to specify |
6722 |
an alternate compiler and other things. |
6723 |
* Testing:: How to proceed past some errors, to |
6724 |
test compilation. |
6725 |
* Options Summary:: Summary of Options |
6726 |
@end menu |
6727 |
|
6728 |
@node Makefile Arguments, Goals, Running, Running |
6729 |
@section Arguments to Specify the Makefile |
6730 |
@cindex @code{--file} |
6731 |
@cindex @code{--makefile} |
6732 |
@cindex @code{-f} |
6733 |
|
6734 |
The way to specify the name of the makefile is with the @samp{-f} or |
6735 |
@samp{--file} option (@samp{--makefile} also works). For example, |
6736 |
@samp{-f altmake} says to use the file @file{altmake} as the makefile. |
6737 |
|
6738 |
If you use the @samp{-f} flag several times and follow each @samp{-f} |
6739 |
with an argument, all the specified files are used jointly as |
6740 |
makefiles. |
6741 |
|
6742 |
If you do not use the @samp{-f} or @samp{--file} flag, the default is |
6743 |
to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in |
6744 |
that order, and use the first of these three which exists or can be made |
6745 |
(@pxref{Makefiles, ,Writing Makefiles}).@refill |
6746 |
|
6747 |
@node Goals, Instead of Execution, Makefile Arguments, Running |
6748 |
@section Arguments to Specify the Goals |
6749 |
@cindex goal, how to specify |
6750 |
|
6751 |
The @dfn{goals} are the targets that @code{make} should strive ultimately |
6752 |
to update. Other targets are updated as well if they appear as |
6753 |
prerequisites of goals, or prerequisites of prerequisites of goals, etc. |
6754 |
|
6755 |
By default, the goal is the first target in the makefile (not counting |
6756 |
targets that start with a period). Therefore, makefiles are usually |
6757 |
written so that the first target is for compiling the entire program or |
6758 |
programs they describe. If the first rule in the makefile has several |
6759 |
targets, only the first target in the rule becomes the default goal, not |
6760 |
the whole list. |
6761 |
|
6762 |
You can specify a different goal or goals with arguments to @code{make}. |
6763 |
Use the name of the goal as an argument. If you specify several goals, |
6764 |
@code{make} processes each of them in turn, in the order you name them. |
6765 |
|
6766 |
Any target in the makefile may be specified as a goal (unless it |
6767 |
starts with @samp{-} or contains an @samp{=}, in which case it will be |
6768 |
parsed as a switch or variable definition, respectively). Even |
6769 |
targets not in the makefile may be specified, if @code{make} can find |
6770 |
implicit rules that say how to make them. |
6771 |
|
6772 |
@cindex @code{MAKECMDGOALS} |
6773 |
@vindex MAKECMDGOALS |
6774 |
@code{Make} will set the special variable @code{MAKECMDGOALS} to the |
6775 |
list of goals you specified on the command line. If no goals were given |
6776 |
on the command line, this variable is empty. Note that this variable |
6777 |
should be used only in special circumstances. |
6778 |
|
6779 |
An example of appropriate use is to avoid including @file{.d} files |
6780 |
during @code{clean} rules (@pxref{Automatic Prerequisites}), so |
6781 |
@code{make} won't create them only to immediately remove them |
6782 |
again:@refill |
6783 |
|
6784 |
@example |
6785 |
@group |
6786 |
sources = foo.c bar.c |
6787 |
|
6788 |
ifneq ($(MAKECMDGOALS),clean) |
6789 |
include $(sources:.c=.d) |
6790 |
endif |
6791 |
@end group |
6792 |
@end example |
6793 |
|
6794 |
One use of specifying a goal is if you want to compile only a part of |
6795 |
the program, or only one of several programs. Specify as a goal each |
6796 |
file that you wish to remake. For example, consider a directory containing |
6797 |
several programs, with a makefile that starts like this: |
6798 |
|
6799 |
@example |
6800 |
.PHONY: all |
6801 |
all: size nm ld ar as |
6802 |
@end example |
6803 |
|
6804 |
If you are working on the program @code{size}, you might want to say |
6805 |
@w{@samp{make size}} so that only the files of that program are recompiled. |
6806 |
|
6807 |
Another use of specifying a goal is to make files that are not normally |
6808 |
made. For example, there may be a file of debugging output, or a |
6809 |
version of the program that is compiled specially for testing, which has |
6810 |
a rule in the makefile but is not a prerequisite of the default goal. |
6811 |
|
6812 |
Another use of specifying a goal is to run the commands associated with |
6813 |
a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty |
6814 |
Targets, ,Empty Target Files to Record Events}). Many makefiles contain |
6815 |
a phony target named @file{clean} which deletes everything except source |
6816 |
files. Naturally, this is done only if you request it explicitly with |
6817 |
@w{@samp{make clean}}. Following is a list of typical phony and empty |
6818 |
target names. @xref{Standard Targets}, for a detailed list of all the |
6819 |
standard target names which GNU software packages use. |
6820 |
|
6821 |
@table @file |
6822 |
@item all |
6823 |
@cindex @code{all} @r{(standard target)} |
6824 |
Make all the top-level targets the makefile knows about. |
6825 |
|
6826 |
@item clean |
6827 |
@cindex @code{clean} @r{(standard target)} |
6828 |
Delete all files that are normally created by running @code{make}. |
6829 |
|
6830 |
@item mostlyclean |
6831 |
@cindex @code{mostlyclean} @r{(standard target)} |
6832 |
Like @samp{clean}, but may refrain from deleting a few files that people |
6833 |
normally don't want to recompile. For example, the @samp{mostlyclean} |
6834 |
target for GCC does not delete @file{libgcc.a}, because recompiling it |
6835 |
is rarely necessary and takes a lot of time. |
6836 |
|
6837 |
@item distclean |
6838 |
@cindex @code{distclean} @r{(standard target)} |
6839 |
@itemx realclean |
6840 |
@cindex @code{realclean} @r{(standard target)} |
6841 |
@itemx clobber |
6842 |
@cindex @code{clobber} @r{(standard target)} |
6843 |
Any of these targets might be defined to delete @emph{more} files than |
6844 |
@samp{clean} does. For example, this would delete configuration files |
6845 |
or links that you would normally create as preparation for compilation, |
6846 |
even if the makefile itself cannot create these files. |
6847 |
|
6848 |
@item install |
6849 |
@cindex @code{install} @r{(standard target)} |
6850 |
Copy the executable file into a directory that users typically search |
6851 |
for commands; copy any auxiliary files that the executable uses into |
6852 |
the directories where it will look for them. |
6853 |
|
6854 |
@item print |
6855 |
@cindex @code{print} @r{(standard target)} |
6856 |
Print listings of the source files that have changed. |
6857 |
|
6858 |
@item tar |
6859 |
@cindex @code{tar} @r{(standard target)} |
6860 |
Create a tar file of the source files. |
6861 |
|
6862 |
@item shar |
6863 |
@cindex @code{shar} @r{(standard target)} |
6864 |
Create a shell archive (shar file) of the source files. |
6865 |
|
6866 |
@item dist |
6867 |
@cindex @code{dist} @r{(standard target)} |
6868 |
Create a distribution file of the source files. This might |
6869 |
be a tar file, or a shar file, or a compressed version of one of the |
6870 |
above, or even more than one of the above. |
6871 |
|
6872 |
@item TAGS |
6873 |
@cindex @code{TAGS} @r{(standard target)} |
6874 |
Update a tags table for this program. |
6875 |
|
6876 |
@item check |
6877 |
@cindex @code{check} @r{(standard target)} |
6878 |
@itemx test |
6879 |
@cindex @code{test} @r{(standard target)} |
6880 |
Perform self tests on the program this makefile builds. |
6881 |
@end table |
6882 |
|
6883 |
@node Instead of Execution, Avoiding Compilation, Goals, Running |
6884 |
@section Instead of Executing the Commands |
6885 |
@cindex execution, instead of |
6886 |
@cindex commands, instead of executing |
6887 |
|
6888 |
The makefile tells @code{make} how to tell whether a target is up to date, |
6889 |
and how to update each target. But updating the targets is not always |
6890 |
what you want. Certain options specify other activities for @code{make}. |
6891 |
|
6892 |
@comment Extra blank lines make it print better. |
6893 |
@table @samp |
6894 |
@item -n |
6895 |
@itemx --just-print |
6896 |
@itemx --dry-run |
6897 |
@itemx --recon |
6898 |
@cindex @code{--just-print} |
6899 |
@cindex @code{--dry-run} |
6900 |
@cindex @code{--recon} |
6901 |
@cindex @code{-n} |
6902 |
|
6903 |
``No-op''. The activity is to print what commands would be used to make |
6904 |
the targets up to date, but not actually execute them. |
6905 |
|
6906 |
@item -t |
6907 |
@itemx --touch |
6908 |
@cindex @code{--touch} |
6909 |
@cindex touching files |
6910 |
@cindex target, touching |
6911 |
@cindex @code{-t} |
6912 |
|
6913 |
``Touch''. The activity is to mark the targets as up to date without |
6914 |
actually changing them. In other words, @code{make} pretends to compile |
6915 |
the targets but does not really change their contents. |
6916 |
|
6917 |
@item -q |
6918 |
@itemx --question |
6919 |
@cindex @code{--question} |
6920 |
@cindex @code{-q} |
6921 |
@cindex question mode |
6922 |
|
6923 |
``Question''. The activity is to find out silently whether the targets |
6924 |
are up to date already; but execute no commands in either case. In other |
6925 |
words, neither compilation nor output will occur. |
6926 |
|
6927 |
@item -W @var{file} |
6928 |
@itemx --what-if=@var{file} |
6929 |
@itemx --assume-new=@var{file} |
6930 |
@itemx --new-file=@var{file} |
6931 |
@cindex @code{--what-if} |
6932 |
@cindex @code{-W} |
6933 |
@cindex @code{--assume-new} |
6934 |
@cindex @code{--new-file} |
6935 |
@cindex what if |
6936 |
@cindex files, assuming new |
6937 |
|
6938 |
``What if''. Each @samp{-W} flag is followed by a file name. The given |
6939 |
files' modification times are recorded by @code{make} as being the present |
6940 |
time, although the actual modification times remain the same. |
6941 |
You can use the @samp{-W} flag in conjunction with the @samp{-n} flag |
6942 |
to see what would happen if you were to modify specific files.@refill |
6943 |
@end table |
6944 |
|
6945 |
With the @samp{-n} flag, @code{make} prints the commands that it would |
6946 |
normally execute but does not execute them. |
6947 |
|
6948 |
With the @samp{-t} flag, @code{make} ignores the commands in the rules |
6949 |
and uses (in effect) the command @code{touch} for each target that needs to |
6950 |
be remade. The @code{touch} command is also printed, unless @samp{-s} or |
6951 |
@code{.SILENT} is used. For speed, @code{make} does not actually invoke |
6952 |
the program @code{touch}. It does the work directly. |
6953 |
|
6954 |
With the @samp{-q} flag, @code{make} prints nothing and executes no |
6955 |
commands, but the exit status code it returns is zero if and only if the |
6956 |
targets to be considered are already up to date. If the exit status is |
6957 |
one, then some updating needs to be done. If @code{make} encounters an |
6958 |
error, the exit status is two, so you can distinguish an error from a |
6959 |
target that is not up to date. |
6960 |
|
6961 |
It is an error to use more than one of these three flags in the same |
6962 |
invocation of @code{make}. |
6963 |
|
6964 |
@cindex +, and command execution |
6965 |
The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command |
6966 |
lines that begin with @samp{+} characters or contain the strings |
6967 |
@samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing |
6968 |
the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} |
6969 |
is run regardless of these options. Other lines in the same rule are |
6970 |
not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or |
6971 |
@samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.) |
6972 |
|
6973 |
The @samp{-W} flag provides two features: |
6974 |
|
6975 |
@itemize @bullet |
6976 |
@item |
6977 |
If you also use the @samp{-n} or @samp{-q} flag, you can see what |
6978 |
@code{make} would do if you were to modify some files. |
6979 |
|
6980 |
@item |
6981 |
Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually |
6982 |
executing commands, the @samp{-W} flag can direct @code{make} to act |
6983 |
as if some files had been modified, without actually modifying the |
6984 |
files.@refill |
6985 |
@end itemize |
6986 |
|
6987 |
Note that the options @samp{-p} and @samp{-v} allow you to obtain other |
6988 |
information about @code{make} or about the makefiles in use |
6989 |
(@pxref{Options Summary, ,Summary of Options}).@refill |
6990 |
|
6991 |
@node Avoiding Compilation, Overriding, Instead of Execution, Running |
6992 |
@section Avoiding Recompilation of Some Files |
6993 |
@cindex @code{-o} |
6994 |
@cindex @code{--old-file} |
6995 |
@cindex @code{--assume-old} |
6996 |
@cindex files, assuming old |
6997 |
@cindex files, avoiding recompilation of |
6998 |
@cindex recompilation, avoiding |
6999 |
|
7000 |
Sometimes you may have changed a source file but you do not want to |
7001 |
recompile all the files that depend on it. For example, suppose you add |
7002 |
a macro or a declaration to a header file that many other files depend |
7003 |
on. Being conservative, @code{make} assumes that any change in the |
7004 |
header file requires recompilation of all dependent files, but you know |
7005 |
that they do not need to be recompiled and you would rather not waste |
7006 |
the time waiting for them to compile. |
7007 |
|
7008 |
If you anticipate the problem before changing the header file, you can |
7009 |
use the @samp{-t} flag. This flag tells @code{make} not to run the |
7010 |
commands in the rules, but rather to mark the target up to date by |
7011 |
changing its last-modification date. You would follow this procedure: |
7012 |
|
7013 |
@enumerate |
7014 |
@item |
7015 |
Use the command @samp{make} to recompile the source files that really |
7016 |
need recompilation, ensuring that the object files are up-to-date |
7017 |
before you begin. |
7018 |
|
7019 |
@item |
7020 |
Make the changes in the header files. |
7021 |
|
7022 |
@item |
7023 |
Use the command @samp{make -t} to mark all the object files as |
7024 |
up to date. The next time you run @code{make}, the changes in the |
7025 |
header files will not cause any recompilation. |
7026 |
@end enumerate |
7027 |
|
7028 |
If you have already changed the header file at a time when some files |
7029 |
do need recompilation, it is too late to do this. Instead, you can |
7030 |
use the @w{@samp{-o @var{file}}} flag, which marks a specified file as |
7031 |
``old'' (@pxref{Options Summary, ,Summary of Options}). This means |
7032 |
that the file itself will not be remade, and nothing else will be |
7033 |
remade on its account. Follow this procedure: |
7034 |
|
7035 |
@enumerate |
7036 |
@item |
7037 |
Recompile the source files that need compilation for reasons independent |
7038 |
of the particular header file, with @samp{make -o @var{headerfile}}. |
7039 |
If several header files are involved, use a separate @samp{-o} option |
7040 |
for each header file. |
7041 |
|
7042 |
@item |
7043 |
Touch all the object files with @samp{make -t}. |
7044 |
@end enumerate |
7045 |
|
7046 |
@node Overriding, Testing, Avoiding Compilation, Running |
7047 |
@section Overriding Variables |
7048 |
@cindex overriding variables with arguments |
7049 |
@cindex variables, overriding with arguments |
7050 |
@cindex command line variables |
7051 |
@cindex variables, command line |
7052 |
|
7053 |
An argument that contains @samp{=} specifies the value of a variable: |
7054 |
@samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}. |
7055 |
If you specify a value in this way, all ordinary assignments of the same |
7056 |
variable in the makefile are ignored; we say they have been |
7057 |
@dfn{overridden} by the command line argument. |
7058 |
|
7059 |
The most common way to use this facility is to pass extra flags to |
7060 |
compilers. For example, in a properly written makefile, the variable |
7061 |
@code{CFLAGS} is included in each command that runs the C compiler, so a |
7062 |
file @file{foo.c} would be compiled something like this: |
7063 |
|
7064 |
@example |
7065 |
cc -c $(CFLAGS) foo.c |
7066 |
@end example |
7067 |
|
7068 |
Thus, whatever value you set for @code{CFLAGS} affects each compilation |
7069 |
that occurs. The makefile probably specifies the usual value for |
7070 |
@code{CFLAGS}, like this: |
7071 |
|
7072 |
@example |
7073 |
CFLAGS=-g |
7074 |
@end example |
7075 |
|
7076 |
Each time you run @code{make}, you can override this value if you |
7077 |
wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C |
7078 |
compilation will be done with @samp{cc -c -g -O}. (This also |
7079 |
illustrates how you can use quoting in the shell to enclose spaces and |
7080 |
other special characters in the value of a variable when you override |
7081 |
it.) |
7082 |
|
7083 |
The variable @code{CFLAGS} is only one of many standard variables that |
7084 |
exist just so that you can change them this way. @xref{Implicit |
7085 |
Variables, , Variables Used by Implicit Rules}, for a complete list. |
7086 |
|
7087 |
You can also program the makefile to look at additional variables of your |
7088 |
own, giving the user the ability to control other aspects of how the |
7089 |
makefile works by changing the variables. |
7090 |
|
7091 |
When you override a variable with a command argument, you can define either |
7092 |
a recursively-expanded variable or a simply-expanded variable. The |
7093 |
examples shown above make a recursively-expanded variable; to make a |
7094 |
simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless |
7095 |
you want to include a variable reference or function call in the |
7096 |
@emph{value} that you specify, it makes no difference which kind of |
7097 |
variable you create. |
7098 |
|
7099 |
There is one way that the makefile can change a variable that you have |
7100 |
overridden. This is to use the @code{override} directive, which is a line |
7101 |
that looks like this: @samp{override @var{variable} = @var{value}} |
7102 |
(@pxref{Override Directive, ,The @code{override} Directive}). |
7103 |
|
7104 |
@node Testing, Options Summary, Overriding, Running |
7105 |
@section Testing the Compilation of a Program |
7106 |
@cindex testing compilation |
7107 |
@cindex compilation, testing |
7108 |
|
7109 |
Normally, when an error happens in executing a shell command, @code{make} |
7110 |
gives up immediately, returning a nonzero status. No further commands are |
7111 |
executed for any target. The error implies that the goal cannot be |
7112 |
correctly remade, and @code{make} reports this as soon as it knows. |
7113 |
|
7114 |
When you are compiling a program that you have just changed, this is not |
7115 |
what you want. Instead, you would rather that @code{make} try compiling |
7116 |
every file that can be tried, to show you as many compilation errors |
7117 |
as possible. |
7118 |
|
7119 |
@cindex @code{-k} |
7120 |
@cindex @code{--keep-going} |
7121 |
On these occasions, you should use the @samp{-k} or |
7122 |
@samp{--keep-going} flag. This tells @code{make} to continue to |
7123 |
consider the other prerequisites of the pending targets, remaking them |
7124 |
if necessary, before it gives up and returns nonzero status. For |
7125 |
example, after an error in compiling one object file, @samp{make -k} |
7126 |
will continue compiling other object files even though it already |
7127 |
knows that linking them will be impossible. In addition to continuing |
7128 |
after failed shell commands, @samp{make -k} will continue as much as |
7129 |
possible after discovering that it does not know how to make a target |
7130 |
or prerequisite file. This will always cause an error message, but |
7131 |
without @samp{-k}, it is a fatal error (@pxref{Options Summary, |
7132 |
,Summary of Options}).@refill |
7133 |
|
7134 |
The usual behavior of @code{make} assumes that your purpose is to get the |
7135 |
goals up to date; once @code{make} learns that this is impossible, it might |
7136 |
as well report the failure immediately. The @samp{-k} flag says that the |
7137 |
real purpose is to test as much as possible of the changes made in the |
7138 |
program, perhaps to find several independent problems so that you can |
7139 |
correct them all before the next attempt to compile. This is why Emacs' |
7140 |
@kbd{M-x compile} command passes the @samp{-k} flag by default. |
7141 |
|
7142 |
@node Options Summary, , Testing, Running |
7143 |
@section Summary of Options |
7144 |
@cindex options |
7145 |
@cindex flags |
7146 |
@cindex switches |
7147 |
|
7148 |
Here is a table of all the options @code{make} understands: |
7149 |
|
7150 |
@table @samp |
7151 |
@item -b |
7152 |
@cindex @code{-b} |
7153 |
@itemx -m |
7154 |
@cindex @code{-m} |
7155 |
These options are ignored for compatibility with other versions of @code{make}. |
7156 |
|
7157 |
@item -B |
7158 |
@cindex @code{-B} |
7159 |
@itemx --always-make |
7160 |
@cindex @code{--always-make} |
7161 |
Consider all targets out-of-date. GNU @code{make} proceeds to |
7162 |
consider targets and their prerequisites using the normal algorithms; |
7163 |
however, all these targets are remade, regardless of the status of |
7164 |
their prerequisites. |
7165 |
|
7166 |
@item -C @var{dir} |
7167 |
@cindex @code{-C} |
7168 |
@itemx --directory=@var{dir} |
7169 |
@cindex @code{--directory} |
7170 |
Change to directory @var{dir} before reading the makefiles. If multiple |
7171 |
@samp{-C} options are specified, each is interpreted relative to the |
7172 |
previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}. |
7173 |
This is typically used with recursive invocations of @code{make} |
7174 |
(@pxref{Recursion, ,Recursive Use of @code{make}}). |
7175 |
|
7176 |
@item -d |
7177 |
@cindex @code{-d} |
7178 |
@c Extra blank line here makes the table look better. |
7179 |
|
7180 |
Print debugging information in addition to normal processing. The |
7181 |
debugging information says which files are being considered for |
7182 |
remaking, which file-times are being compared and with what results, |
7183 |
which files actually need to be remade, which implicit rules are |
7184 |
considered and which are applied---everything interesting about how |
7185 |
@code{make} decides what to do. The @code{-d} option is equivalent to |
7186 |
@samp{--debug=a} (see below). |
7187 |
|
7188 |
@item --debug[=@var{options}] |
7189 |
@cindex @code{--debug} |
7190 |
@c Extra blank line here makes the table look better. |
7191 |
|
7192 |
Print debugging information in addition to normal processing. Various |
7193 |
levels and types of output can be chosen. With no arguments, print the |
7194 |
``basic'' level of debugging. Possible arguments are below; only the |
7195 |
first character is considered, and values must be comma- or |
7196 |
space-separated. |
7197 |
|
7198 |
@table @code |
7199 |
@item a (@i{all}) |
7200 |
All types of debugging output are enabled. This is equivalent to using |
7201 |
@samp{-d}. |
7202 |
|
7203 |
@item b (@i{basic}) |
7204 |
Basic debugging prints each target that was found to be out-of-date, and |
7205 |
whether the build was successful or not. |
7206 |
|
7207 |
@item v (@i{verbose}) |
7208 |
A level above @samp{basic}; includes messages about which makefiles were |
7209 |
parsed, prerequisites that did not need to be rebuilt, etc. This option |
7210 |
also enables @samp{basic} messages. |
7211 |
|
7212 |
@item i (@i{implicit}) |
7213 |
Prints messages describing the implicit rule searches for each target. |
7214 |
This option also enables @samp{basic} messages. |
7215 |
|
7216 |
@item j (@i{jobs}) |
7217 |
Prints messages giving details on the invocation of specific subcommands. |
7218 |
|
7219 |
@item m (@i{makefile}) |
7220 |
By default, the above messages are not enabled while trying to remake |
7221 |
the makefiles. This option enables messages while rebuilding makefiles, |
7222 |
too. Note that the @samp{all} option does enable this option. This |
7223 |
option also enables @samp{basic} messages. |
7224 |
@end table |
7225 |
|
7226 |
@item -e |
7227 |
@cindex @code{-e} |
7228 |
@itemx --environment-overrides |
7229 |
@cindex @code{--environment-overrides} |
7230 |
Give variables taken from the environment precedence |
7231 |
over variables from makefiles. |
7232 |
@xref{Environment, ,Variables from the Environment}. |
7233 |
|
7234 |
@item -f @var{file} |
7235 |
@cindex @code{-f} |
7236 |
@itemx --file=@var{file} |
7237 |
@cindex @code{--file} |
7238 |
@itemx --makefile=@var{file} |
7239 |
@cindex @code{--makefile} |
7240 |
Read the file named @var{file} as a makefile. |
7241 |
@xref{Makefiles, ,Writing Makefiles}. |
7242 |
|
7243 |
@item -h |
7244 |
@cindex @code{-h} |
7245 |
@itemx --help |
7246 |
@cindex @code{--help} |
7247 |
@c Extra blank line here makes the table look better. |
7248 |
|
7249 |
Remind you of the options that @code{make} understands and then exit. |
7250 |
|
7251 |
@item -i |
7252 |
@cindex @code{-i} |
7253 |
@itemx --ignore-errors |
7254 |
@cindex @code{--ignore-errors} |
7255 |
Ignore all errors in commands executed to remake files. |
7256 |
@xref{Errors, ,Errors in Commands}. |
7257 |
|
7258 |
@item -I @var{dir} |
7259 |
@cindex @code{-I} |
7260 |
@itemx --include-dir=@var{dir} |
7261 |
@cindex @code{--include-dir} |
7262 |
Specifies a directory @var{dir} to search for included makefiles. |
7263 |
@xref{Include, ,Including Other Makefiles}. If several @samp{-I} |
7264 |
options are used to specify several directories, the directories are |
7265 |
searched in the order specified. |
7266 |
|
7267 |
@item -j [@var{jobs}] |
7268 |
@cindex @code{-j} |
7269 |
@itemx --jobs[=@var{jobs}] |
7270 |
@cindex @code{--jobs} |
7271 |
Specifies the number of jobs (commands) to run simultaneously. With no |
7272 |
argument, @code{make} runs as many jobs simultaneously as possible. If |
7273 |
there is more than one @samp{-j} option, the last one is effective. |
7274 |
@xref{Parallel, ,Parallel Execution}, |
7275 |
for more information on how commands are run. |
7276 |
Note that this option is ignored on MS-DOS. |
7277 |
|
7278 |
@item -k |
7279 |
@cindex @code{-k} |
7280 |
@itemx --keep-going |
7281 |
@cindex @code{--keep-going} |
7282 |
Continue as much as possible after an error. While the target that |
7283 |
failed, and those that depend on it, cannot be remade, the other |
7284 |
prerequisites of these targets can be processed all the same. |
7285 |
@xref{Testing, ,Testing the Compilation of a Program}. |
7286 |
|
7287 |
@item -l [@var{load}] |
7288 |
@cindex @code{-l} |
7289 |
@itemx --load-average[=@var{load}] |
7290 |
@cindex @code{--load-average} |
7291 |
@itemx --max-load[=@var{load}] |
7292 |
@cindex @code{--max-load} |
7293 |
Specifies that no new jobs (commands) should be started if there are |
7294 |
other jobs running and the load average is at least @var{load} (a |
7295 |
floating-point number). With no argument, removes a previous load |
7296 |
limit. @xref{Parallel, ,Parallel Execution}. |
7297 |
|
7298 |
@item -n |
7299 |
@cindex @code{-n} |
7300 |
@itemx --just-print |
7301 |
@cindex @code{--just-print} |
7302 |
@itemx --dry-run |
7303 |
@cindex @code{--dry-run} |
7304 |
@itemx --recon |
7305 |
@cindex @code{--recon} |
7306 |
@c Extra blank line here makes the table look better. |
7307 |
|
7308 |
Print the commands that would be executed, but do not execute them. |
7309 |
@xref{Instead of Execution, ,Instead of Executing the Commands}. |
7310 |
|
7311 |
@item -o @var{file} |
7312 |
@cindex @code{-o} |
7313 |
@itemx --old-file=@var{file} |
7314 |
@cindex @code{--old-file} |
7315 |
@itemx --assume-old=@var{file} |
7316 |
@cindex @code{--assume-old} |
7317 |
Do not remake the file @var{file} even if it is older than its |
7318 |
prerequisites, and do not remake anything on account of changes in |
7319 |
@var{file}. Essentially the file is treated as very old and its rules |
7320 |
are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of |
7321 |
Some Files}.@refill |
7322 |
|
7323 |
@item -p |
7324 |
@cindex @code{-p} |
7325 |
@itemx --print-data-base |
7326 |
@cindex @code{--print-data-base} |
7327 |
@cindex data base of @code{make} rules |
7328 |
@cindex predefined rules and variables, printing |
7329 |
Print the data base (rules and variable values) that results from |
7330 |
reading the makefiles; then execute as usual or as otherwise specified. |
7331 |
This also prints the version information given by the @samp{-v} switch |
7332 |
(see below). To print the data base without trying to remake any files, |
7333 |
use @w{@samp{make -qp}}. To print the data base of predefined rules and |
7334 |
variables, use @w{@samp{make -p -f /dev/null}}. The data base output |
7335 |
contains filename and linenumber information for command and variable |
7336 |
definitions, so it can be a useful debugging tool in complex environments. |
7337 |
|
7338 |
@item -q |
7339 |
@cindex @code{-q} |
7340 |
@itemx --question |
7341 |
@cindex @code{--question} |
7342 |
``Question mode''. Do not run any commands, or print anything; just |
7343 |
return an exit status that is zero if the specified targets are already |
7344 |
up to date, one if any remaking is required, or two if an error is |
7345 |
encountered. @xref{Instead of Execution, ,Instead of Executing the |
7346 |
Commands}.@refill |
7347 |
|
7348 |
@item -r |
7349 |
@cindex @code{-r} |
7350 |
@itemx --no-builtin-rules |
7351 |
@cindex @code{--no-builtin-rules} |
7352 |
Eliminate use of the built-in implicit rules (@pxref{Implicit Rules, |
7353 |
,Using Implicit Rules}). You can still define your own by writing |
7354 |
pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern |
7355 |
Rules}). The @samp{-r} option also clears out the default list of |
7356 |
suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix |
7357 |
Rules}). But you can still define your own suffixes with a rule for |
7358 |
@code{.SUFFIXES}, and then define your own suffix rules. Note that only |
7359 |
@emph{rules} are affected by the @code{-r} option; default variables |
7360 |
remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit |
7361 |
Rules}); see the @samp{-R} option below. |
7362 |
|
7363 |
@item -R |
7364 |
@cindex @code{-R} |
7365 |
@itemx --no-builtin-variables |
7366 |
@cindex @code{--no-builtin-variables} |
7367 |
Eliminate use of the built-in rule-specific variables (@pxref{Implicit |
7368 |
Variables, ,Variables Used by Implicit Rules}). You can still define |
7369 |
your own, of course. The @samp{-R} option also automatically enables |
7370 |
the @samp{-r} option (see above), since it doesn't make sense to have |
7371 |
implicit rules without any definitions for the variables that they use. |
7372 |
|
7373 |
@item -s |
7374 |
@cindex @code{-s} |
7375 |
@itemx --silent |
7376 |
@cindex @code{--silent} |
7377 |
@itemx --quiet |
7378 |
@cindex @code{--quiet} |
7379 |
@c Extra blank line here makes the table look better. |
7380 |
|
7381 |
Silent operation; do not print the commands as they are executed. |
7382 |
@xref{Echoing, ,Command Echoing}. |
7383 |
|
7384 |
@item -S |
7385 |
@cindex @code{-S} |
7386 |
@itemx --no-keep-going |
7387 |
@cindex @code{--no-keep-going} |
7388 |
@itemx --stop |
7389 |
@cindex @code{--stop} |
7390 |
@c Extra blank line here makes the table look better. |
7391 |
|
7392 |
Cancel the effect of the @samp{-k} option. This is never necessary |
7393 |
except in a recursive @code{make} where @samp{-k} might be inherited |
7394 |
from the top-level @code{make} via @code{MAKEFLAGS} |
7395 |
(@pxref{Recursion, ,Recursive Use of @code{make}}) |
7396 |
or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill |
7397 |
|
7398 |
@item -t |
7399 |
@cindex @code{-t} |
7400 |
@itemx --touch |
7401 |
@cindex @code{--touch} |
7402 |
@c Extra blank line here makes the table look better. |
7403 |
|
7404 |
Touch files (mark them up to date without really changing them) |
7405 |
instead of running their commands. This is used to pretend that the |
7406 |
commands were done, in order to fool future invocations of |
7407 |
@code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}. |
7408 |
|
7409 |
@item -v |
7410 |
@cindex @code{-v} |
7411 |
@itemx --version |
7412 |
@cindex @code{--version} |
7413 |
Print the version of the @code{make} program plus a copyright, a list |
7414 |
of authors, and a notice that there is no warranty; then exit. |
7415 |
|
7416 |
@item -w |
7417 |
@cindex @code{-w} |
7418 |
@itemx --print-directory |
7419 |
@cindex @code{--print-directory} |
7420 |
Print a message containing the working directory both before and after |
7421 |
executing the makefile. This may be useful for tracking down errors |
7422 |
from complicated nests of recursive @code{make} commands. |
7423 |
@xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you |
7424 |
rarely need to specify this option since @samp{make} does it for you; |
7425 |
see @ref{-w Option, ,The @samp{--print-directory} Option}.) |
7426 |
|
7427 |
@itemx --no-print-directory |
7428 |
@cindex @code{--no-print-directory} |
7429 |
Disable printing of the working directory under @code{-w}. |
7430 |
This option is useful when @code{-w} is turned on automatically, |
7431 |
but you do not want to see the extra messages. |
7432 |
@xref{-w Option, ,The @samp{--print-directory} Option}. |
7433 |
|
7434 |
@item -W @var{file} |
7435 |
@cindex @code{-W} |
7436 |
@itemx --what-if=@var{file} |
7437 |
@cindex @code{--what-if} |
7438 |
@itemx --new-file=@var{file} |
7439 |
@cindex @code{--new-file} |
7440 |
@itemx --assume-new=@var{file} |
7441 |
@cindex @code{--assume-new} |
7442 |
Pretend that the target @var{file} has just been modified. When used |
7443 |
with the @samp{-n} flag, this shows you what would happen if you were |
7444 |
to modify that file. Without @samp{-n}, it is almost the same as |
7445 |
running a @code{touch} command on the given file before running |
7446 |
@code{make}, except that the modification time is changed only in the |
7447 |
imagination of @code{make}. |
7448 |
@xref{Instead of Execution, ,Instead of Executing the Commands}. |
7449 |
|
7450 |
@item --warn-undefined-variables |
7451 |
@cindex @code{--warn-undefined-variables} |
7452 |
@cindex variables, warning for undefined |
7453 |
@cindex undefined variables, warning message |
7454 |
Issue a warning message whenever @code{make} sees a reference to an |
7455 |
undefined variable. This can be helpful when you are trying to debug |
7456 |
makefiles which use variables in complex ways. |
7457 |
@end table |
7458 |
|
7459 |
@node Implicit Rules, Archives, Running, Top |
7460 |
@chapter Using Implicit Rules |
7461 |
@cindex implicit rule |
7462 |
@cindex rule, implicit |
7463 |
|
7464 |
Certain standard ways of remaking target files are used very often. For |
7465 |
example, one customary way to make an object file is from a C source file |
7466 |
using the C compiler, @code{cc}. |
7467 |
|
7468 |
@dfn{Implicit rules} tell @code{make} how to use customary techniques so |
7469 |
that you do not have to specify them in detail when you want to use |
7470 |
them. For example, there is an implicit rule for C compilation. File |
7471 |
names determine which implicit rules are run. For example, C |
7472 |
compilation typically takes a @file{.c} file and makes a @file{.o} file. |
7473 |
So @code{make} applies the implicit rule for C compilation when it sees |
7474 |
this combination of file name endings.@refill |
7475 |
|
7476 |
A chain of implicit rules can apply in sequence; for example, @code{make} |
7477 |
will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. |
7478 |
@iftex |
7479 |
@xref{Chained Rules, ,Chains of Implicit Rules}. |
7480 |
@end iftex |
7481 |
|
7482 |
The built-in implicit rules use several variables in their commands so |
7483 |
that, by changing the values of the variables, you can change the way the |
7484 |
implicit rule works. For example, the variable @code{CFLAGS} controls the |
7485 |
flags given to the C compiler by the implicit rule for C compilation. |
7486 |
@iftex |
7487 |
@xref{Implicit Variables, ,Variables Used by Implicit Rules}. |
7488 |
@end iftex |
7489 |
|
7490 |
You can define your own implicit rules by writing @dfn{pattern rules}. |
7491 |
@iftex |
7492 |
@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}. |
7493 |
@end iftex |
7494 |
|
7495 |
@dfn{Suffix rules} are a more limited way to define implicit rules. |
7496 |
Pattern rules are more general and clearer, but suffix rules are |
7497 |
retained for compatibility. |
7498 |
@iftex |
7499 |
@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. |
7500 |
@end iftex |
7501 |
|
7502 |
@menu |
7503 |
* Using Implicit:: How to use an existing implicit rule |
7504 |
to get the commands for updating a file. |
7505 |
* Catalogue of Rules:: A list of built-in implicit rules. |
7506 |
* Implicit Variables:: How to change what predefined rules do. |
7507 |
* Chained Rules:: How to use a chain of implicit rules. |
7508 |
* Pattern Rules:: How to define new implicit rules. |
7509 |
* Last Resort:: How to defining commands for rules |
7510 |
which cannot find any. |
7511 |
* Suffix Rules:: The old-fashioned style of implicit rule. |
7512 |
* Implicit Rule Search:: The precise algorithm for applying |
7513 |
implicit rules. |
7514 |
@end menu |
7515 |
|
7516 |
@node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules |
7517 |
@section Using Implicit Rules |
7518 |
@cindex implicit rule, how to use |
7519 |
@cindex rule, implicit, how to use |
7520 |
|
7521 |
To allow @code{make} to find a customary method for updating a target file, |
7522 |
all you have to do is refrain from specifying commands yourself. Either |
7523 |
write a rule with no command lines, or don't write a rule at all. Then |
7524 |
@code{make} will figure out which implicit rule to use based on which |
7525 |
kind of source file exists or can be made. |
7526 |
|
7527 |
For example, suppose the makefile looks like this: |
7528 |
|
7529 |
@example |
7530 |
foo : foo.o bar.o |
7531 |
cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) |
7532 |
@end example |
7533 |
|
7534 |
@noindent |
7535 |
Because you mention @file{foo.o} but do not give a rule for it, @code{make} |
7536 |
will automatically look for an implicit rule that tells how to update it. |
7537 |
This happens whether or not the file @file{foo.o} currently exists. |
7538 |
|
7539 |
If an implicit rule is found, it can supply both commands and one or |
7540 |
more prerequisites (the source files). You would want to write a rule |
7541 |
for @file{foo.o} with no command lines if you need to specify additional |
7542 |
prerequisites, such as header files, that the implicit rule cannot |
7543 |
supply. |
7544 |
|
7545 |
Each implicit rule has a target pattern and prerequisite patterns. There may |
7546 |
be many implicit rules with the same target pattern. For example, numerous |
7547 |
rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler; |
7548 |
another, from a @samp{.p} file with the Pascal compiler; and so on. The rule |
7549 |
that actually applies is the one whose prerequisites exist or can be made. |
7550 |
So, if you have a file @file{foo.c}, @code{make} will run the C compiler; |
7551 |
otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal |
7552 |
compiler; and so on. |
7553 |
|
7554 |
Of course, when you write the makefile, you know which implicit rule you |
7555 |
want @code{make} to use, and you know it will choose that one because you |
7556 |
know which possible prerequisite files are supposed to exist. |
7557 |
@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, |
7558 |
for a catalogue of all the predefined implicit rules. |
7559 |
|
7560 |
Above, we said an implicit rule applies if the required prerequisites ``exist |
7561 |
or can be made''. A file ``can be made'' if it is mentioned explicitly in |
7562 |
the makefile as a target or a prerequisite, or if an implicit rule can be |
7563 |
recursively found for how to make it. When an implicit prerequisite is the |
7564 |
result of another implicit rule, we say that @dfn{chaining} is occurring. |
7565 |
@xref{Chained Rules, ,Chains of Implicit Rules}. |
7566 |
|
7567 |
In general, @code{make} searches for an implicit rule for each target, and |
7568 |
for each double-colon rule, that has no commands. A file that is mentioned |
7569 |
only as a prerequisite is considered a target whose rule specifies nothing, |
7570 |
so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the |
7571 |
details of how the search is done. |
7572 |
|
7573 |
Note that explicit prerequisites do not influence implicit rule search. |
7574 |
For example, consider this explicit rule: |
7575 |
|
7576 |
@example |
7577 |
foo.o: foo.p |
7578 |
@end example |
7579 |
|
7580 |
@noindent |
7581 |
The prerequisite on @file{foo.p} does not necessarily mean that |
7582 |
@code{make} will remake @file{foo.o} according to the implicit rule to |
7583 |
make an object file, a @file{.o} file, from a Pascal source file, a |
7584 |
@file{.p} file. For example, if @file{foo.c} also exists, the implicit |
7585 |
rule to make an object file from a C source file is used instead, |
7586 |
because it appears before the Pascal rule in the list of predefined |
7587 |
implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit |
7588 |
Rules}). |
7589 |
|
7590 |
If you do not want an implicit rule to be used for a target that has no |
7591 |
commands, you can give that target empty commands by writing a semicolon |
7592 |
(@pxref{Empty Commands, ,Defining Empty Commands}). |
7593 |
|
7594 |
@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules |
7595 |
@section Catalogue of Implicit Rules |
7596 |
@cindex implicit rule, predefined |
7597 |
@cindex rule, implicit, predefined |
7598 |
|
7599 |
Here is a catalogue of predefined implicit rules which are always |
7600 |
available unless the makefile explicitly overrides or cancels them. |
7601 |
@xref{Canceling Rules, ,Canceling Implicit Rules}, for information on |
7602 |
canceling or overriding an implicit rule. The @samp{-r} or |
7603 |
@samp{--no-builtin-rules} option cancels all predefined rules. |
7604 |
|
7605 |
Not all of these rules will always be defined, even when the @samp{-r} |
7606 |
option is not given. Many of the predefined implicit rules are |
7607 |
implemented in @code{make} as suffix rules, so which ones will be |
7608 |
defined depends on the @dfn{suffix list} (the list of prerequisites of |
7609 |
the special target @code{.SUFFIXES}). The default suffix list is: |
7610 |
@code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc}, |
7611 |
@code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y}, |
7612 |
@code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def}, |
7613 |
@code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo}, |
7614 |
@code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web}, |
7615 |
@code{.sh}, @code{.elc}, @code{.el}. All of the implicit rules |
7616 |
described below whose prerequisites have one of these suffixes are |
7617 |
actually suffix rules. If you modify the suffix list, the only |
7618 |
predefined suffix rules in effect will be those named by one or two of |
7619 |
the suffixes that are on the list you specify; rules whose suffixes fail |
7620 |
to be on the list are disabled. @xref{Suffix Rules, ,Old-Fashioned |
7621 |
Suffix Rules}, for full details on suffix rules. |
7622 |
|
7623 |
@table @asis |
7624 |
@item Compiling C programs |
7625 |
@cindex C, rule to compile |
7626 |
@pindex cc |
7627 |
@pindex gcc |
7628 |
@pindex .o |
7629 |
@pindex .c |
7630 |
@file{@var{n}.o} is made automatically from @file{@var{n}.c} with |
7631 |
a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill |
7632 |
|
7633 |
@item Compiling C++ programs |
7634 |
@cindex C++, rule to compile |
7635 |
@pindex g++ |
7636 |
@pindex .C |
7637 |
@pindex .cc |
7638 |
@file{@var{n}.o} is made automatically from @file{@var{n}.cc} or |
7639 |
@file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS) |
7640 |
$(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++ |
7641 |
source files instead of @samp{.C}.@refill |
7642 |
|
7643 |
@item Compiling Pascal programs |
7644 |
@cindex Pascal, rule to compile |
7645 |
@pindex pc |
7646 |
@pindex .p |
7647 |
@file{@var{n}.o} is made automatically from @file{@var{n}.p} |
7648 |
with the command @samp{$(PC) -c $(PFLAGS)}.@refill |
7649 |
|
7650 |
@item Compiling Fortran and Ratfor programs |
7651 |
@cindex Fortran, rule to compile |
7652 |
@cindex Ratfor, rule to compile |
7653 |
@pindex f77 |
7654 |
@pindex .f |
7655 |
@pindex .r |
7656 |
@pindex .F |
7657 |
@file{@var{n}.o} is made automatically from @file{@var{n}.r}, |
7658 |
@file{@var{n}.F} or @file{@var{n}.f} by running the |
7659 |
Fortran compiler. The precise command used is as follows:@refill |
7660 |
|
7661 |
@table @samp |
7662 |
@item .f |
7663 |
@samp{$(FC) -c $(FFLAGS)}. |
7664 |
@item .F |
7665 |
@samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}. |
7666 |
@item .r |
7667 |
@samp{$(FC) -c $(FFLAGS) $(RFLAGS)}. |
7668 |
@end table |
7669 |
|
7670 |
@item Preprocessing Fortran and Ratfor programs |
7671 |
@file{@var{n}.f} is made automatically from @file{@var{n}.r} or |
7672 |
@file{@var{n}.F}. This rule runs just the preprocessor to convert a |
7673 |
Ratfor or preprocessable Fortran program into a strict Fortran |
7674 |
program. The precise command used is as follows:@refill |
7675 |
|
7676 |
@table @samp |
7677 |
@item .F |
7678 |
@samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}. |
7679 |
@item .r |
7680 |
@samp{$(FC) -F $(FFLAGS) $(RFLAGS)}. |
7681 |
@end table |
7682 |
|
7683 |
@item Compiling Modula-2 programs |
7684 |
@cindex Modula-2, rule to compile |
7685 |
@pindex m2c |
7686 |
@pindex .sym |
7687 |
@pindex .def |
7688 |
@pindex .mod |
7689 |
@file{@var{n}.sym} is made from @file{@var{n}.def} with a command |
7690 |
of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o} |
7691 |
is made from @file{@var{n}.mod}; the form is: |
7692 |
@w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill |
7693 |
|
7694 |
@need 1200 |
7695 |
@item Assembling and preprocessing assembler programs |
7696 |
@cindex assembly, rule to compile |
7697 |
@pindex as |
7698 |
@pindex .s |
7699 |
@file{@var{n}.o} is made automatically from @file{@var{n}.s} by |
7700 |
running the assembler, @code{as}. The precise command is |
7701 |
@samp{$(AS) $(ASFLAGS)}.@refill |
7702 |
|
7703 |
@pindex .S |
7704 |
@file{@var{n}.s} is made automatically from @file{@var{n}.S} by |
7705 |
running the C preprocessor, @code{cpp}. The precise command is |
7706 |
@w{@samp{$(CPP) $(CPPFLAGS)}}. |
7707 |
|
7708 |
@item Linking a single object file |
7709 |
@cindex linking, predefined rule for |
7710 |
@pindex ld |
7711 |
@pindex .o |
7712 |
@file{@var{n}} is made automatically from @file{@var{n}.o} by running |
7713 |
the linker (usually called @code{ld}) via the C compiler. The precise |
7714 |
command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}. |
7715 |
|
7716 |
This rule does the right thing for a simple program with only one |
7717 |
source file. It will also do the right thing if there are multiple |
7718 |
object files (presumably coming from various other source files), one |
7719 |
of which has a name matching that of the executable file. Thus, |
7720 |
|
7721 |
@example |
7722 |
x: y.o z.o |
7723 |
@end example |
7724 |
|
7725 |
@noindent |
7726 |
when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute: |
7727 |
|
7728 |
@example |
7729 |
@group |
7730 |
cc -c x.c -o x.o |
7731 |
cc -c y.c -o y.o |
7732 |
cc -c z.c -o z.o |
7733 |
cc x.o y.o z.o -o x |
7734 |
rm -f x.o |
7735 |
rm -f y.o |
7736 |
rm -f z.o |
7737 |
@end group |
7738 |
@end example |
7739 |
|
7740 |
@noindent |
7741 |
In more complicated cases, such as when there is no object file whose |
7742 |
name derives from the executable file name, you must write an explicit |
7743 |
command for linking. |
7744 |
|
7745 |
Each kind of file automatically made into @samp{.o} object files will |
7746 |
be automatically linked by using the compiler (@samp{$(CC)}, |
7747 |
@samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to |
7748 |
assemble @samp{.s} files) without the @samp{-c} option. This could be |
7749 |
done by using the @samp{.o} object files as intermediates, but it is |
7750 |
faster to do the compiling and linking in one step, so that's how it's |
7751 |
done.@refill |
7752 |
|
7753 |
@item Yacc for C programs |
7754 |
@pindex yacc |
7755 |
@cindex Yacc, rule to run |
7756 |
@pindex .y |
7757 |
@file{@var{n}.c} is made automatically from @file{@var{n}.y} by |
7758 |
running Yacc with the command @samp{$(YACC) $(YFLAGS)}. |
7759 |
|
7760 |
@item Lex for C programs |
7761 |
@pindex lex |
7762 |
@cindex Lex, rule to run |
7763 |
@pindex .l |
7764 |
@file{@var{n}.c} is made automatically from @file{@var{n}.l} by |
7765 |
running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. |
7766 |
|
7767 |
@item Lex for Ratfor programs |
7768 |
@file{@var{n}.r} is made automatically from @file{@var{n}.l} by |
7769 |
running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. |
7770 |
|
7771 |
The convention of using the same suffix @samp{.l} for all Lex files |
7772 |
regardless of whether they produce C code or Ratfor code makes it |
7773 |
impossible for @code{make} to determine automatically which of the two |
7774 |
languages you are using in any particular case. If @code{make} is |
7775 |
called upon to remake an object file from a @samp{.l} file, it must |
7776 |
guess which compiler to use. It will guess the C compiler, because |
7777 |
that is more common. If you are using Ratfor, make sure @code{make} |
7778 |
knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you |
7779 |
are using Ratfor exclusively, with no C files, remove @samp{.c} from |
7780 |
the list of implicit rule suffixes with:@refill |
7781 |
|
7782 |
@example |
7783 |
@group |
7784 |
.SUFFIXES: |
7785 |
.SUFFIXES: .o .r .f .l @dots{} |
7786 |
@end group |
7787 |
@end example |
7788 |
|
7789 |
@item Making Lint Libraries from C, Yacc, or Lex programs |
7790 |
@pindex lint |
7791 |
@cindex @code{lint}, rule to run |
7792 |
@pindex .ln |
7793 |
@file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}. |
7794 |
The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. |
7795 |
The same command is used on the C code produced from |
7796 |
@file{@var{n}.y} or @file{@var{n}.l}.@refill |
7797 |
|
7798 |
@item @TeX{} and Web |
7799 |
@cindex @TeX{}, rule to run |
7800 |
@cindex Web, rule to run |
7801 |
@pindex tex |
7802 |
@pindex cweave |
7803 |
@pindex weave |
7804 |
@pindex tangle |
7805 |
@pindex ctangle |
7806 |
@pindex .dvi |
7807 |
@pindex .tex |
7808 |
@pindex .web |
7809 |
@pindex .w |
7810 |
@pindex .ch |
7811 |
@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command |
7812 |
@samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with |
7813 |
@samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if |
7814 |
it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is |
7815 |
made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c} |
7816 |
is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists |
7817 |
or can be made) with @samp{$(CTANGLE)}.@refill |
7818 |
|
7819 |
@item Texinfo and Info |
7820 |
@cindex Texinfo, rule to format |
7821 |
@cindex Info, rule to format |
7822 |
@pindex texi2dvi |
7823 |
@pindex makeinfo |
7824 |
@pindex .texinfo |
7825 |
@pindex .info |
7826 |
@pindex .texi |
7827 |
@pindex .txinfo |
7828 |
@file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, |
7829 |
@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command |
7830 |
@w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from |
7831 |
@file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with |
7832 |
the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. |
7833 |
|
7834 |
@item RCS |
7835 |
@cindex RCS, rule to extract from |
7836 |
@pindex co |
7837 |
@pindex ,v @r{(RCS file extension)} |
7838 |
Any file @file{@var{n}} is extracted if necessary from an RCS file |
7839 |
named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise |
7840 |
command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be |
7841 |
extracted from RCS if it already exists, even if the RCS file is |
7842 |
newer. The rules for RCS are terminal |
7843 |
(@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), |
7844 |
so RCS files cannot be generated from another source; they must |
7845 |
actually exist.@refill |
7846 |
|
7847 |
@item SCCS |
7848 |
@cindex SCCS, rule to extract from |
7849 |
@pindex get |
7850 |
@pindex s. @r{(SCCS file prefix)} |
7851 |
Any file @file{@var{n}} is extracted if necessary from an SCCS file |
7852 |
named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise |
7853 |
command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are |
7854 |
terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), |
7855 |
so SCCS files cannot be generated from another source; they must |
7856 |
actually exist.@refill |
7857 |
|
7858 |
@pindex .sh |
7859 |
For the benefit of SCCS, a file @file{@var{n}} is copied from |
7860 |
@file{@var{n}.sh} and made executable (by everyone). This is for |
7861 |
shell scripts that are checked into SCCS. Since RCS preserves the |
7862 |
execution permission of a file, you do not need to use this feature |
7863 |
with RCS.@refill |
7864 |
|
7865 |
We recommend that you avoid using of SCCS. RCS is widely held to be |
7866 |
superior, and is also free. By choosing free software in place of |
7867 |
comparable (or inferior) proprietary software, you support the free |
7868 |
software movement. |
7869 |
@end table |
7870 |
|
7871 |
Usually, you want to change only the variables listed in the table |
7872 |
above, which are documented in the following section. |
7873 |
|
7874 |
However, the commands in built-in implicit rules actually use |
7875 |
variables such as @code{COMPILE.c}, @code{LINK.p}, and |
7876 |
@code{PREPROCESS.S}, whose values contain the commands listed above. |
7877 |
|
7878 |
@code{make} follows the convention that the rule to compile a |
7879 |
@file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}. |
7880 |
Similarly, the rule to produce an executable from a @file{.@var{x}} |
7881 |
file uses @code{LINK.@var{x}}; and the rule to preprocess a |
7882 |
@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}. |
7883 |
|
7884 |
@vindex OUTPUT_OPTION |
7885 |
Every rule that produces an object file uses the variable |
7886 |
@code{OUTPUT_OPTION}. @code{make} defines this variable either to |
7887 |
contain @samp{-o $@@}, or to be empty, depending on a compile-time |
7888 |
option. You need the @samp{-o} option to ensure that the output goes |
7889 |
into the right file when the source file is in a different directory, |
7890 |
as when using @code{VPATH} (@pxref{Directory Search}). However, |
7891 |
compilers on some systems do not accept a @samp{-o} switch for object |
7892 |
files. If you use such a system, and use @code{VPATH}, some |
7893 |
compilations will put their output in the wrong place. |
7894 |
A possible workaround for this problem is to give @code{OUTPUT_OPTION} |
7895 |
the value @w{@samp{; mv $*.o $@@}}. |
7896 |
|
7897 |
@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules |
7898 |
@section Variables Used by Implicit Rules |
7899 |
@cindex flags for compilers |
7900 |
|
7901 |
The commands in built-in implicit rules make liberal use of certain |
7902 |
predefined variables. You can alter these variables in the makefile, |
7903 |
with arguments to @code{make}, or in the environment to alter how the |
7904 |
implicit rules work without redefining the rules themselves. You can |
7905 |
cancel all variables used by implicit rules with the @samp{-R} or |
7906 |
@samp{--no-builtin-variables} option. |
7907 |
|
7908 |
For example, the command used to compile a C source file actually says |
7909 |
@samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables |
7910 |
used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By |
7911 |
redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be |
7912 |
used for all C compilations performed by the implicit rule. By redefining |
7913 |
@samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to |
7914 |
each compilation. @emph{All} implicit rules that do C compilation use |
7915 |
@samp{$(CC)} to get the program name for the compiler and @emph{all} |
7916 |
include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill |
7917 |
|
7918 |
The variables used in implicit rules fall into two classes: those that are |
7919 |
names of programs (like @code{CC}) and those that contain arguments for the |
7920 |
programs (like @code{CFLAGS}). (The ``name of a program'' may also contain |
7921 |
some command arguments, but it must start with an actual executable program |
7922 |
name.) If a variable value contains more than one argument, separate them |
7923 |
with spaces. |
7924 |
|
7925 |
Here is a table of variables used as names of programs in built-in rules: |
7926 |
|
7927 |
@table @code |
7928 |
@item AR |
7929 |
@vindex AR |
7930 |
Archive-maintaining program; default @samp{ar}. |
7931 |
@pindex ar |
7932 |
|
7933 |
@item AS |
7934 |
@vindex AS |
7935 |
Program for doing assembly; default @samp{as}. |
7936 |
@pindex as |
7937 |
|
7938 |
@item CC |
7939 |
@vindex CC |
7940 |
Program for compiling C programs; default @samp{cc}. |
7941 |
@pindex cc |
7942 |
|
7943 |
@item CXX |
7944 |
@vindex CXX |
7945 |
Program for compiling C++ programs; default @samp{g++}. |
7946 |
@pindex g++ |
7947 |
|
7948 |
@item CO |
7949 |
@vindex CO |
7950 |
Program for extracting a file from RCS; default @samp{co}. |
7951 |
@pindex co |
7952 |
|
7953 |
@item CPP |
7954 |
@vindex CPP |
7955 |
Program for running the C preprocessor, with results to standard output; |
7956 |
default @samp{$(CC) -E}. |
7957 |
|
7958 |
@item FC |
7959 |
@vindex FC |
7960 |
Program for compiling or preprocessing Fortran and Ratfor programs; |
7961 |
default @samp{f77}. |
7962 |
@pindex f77 |
7963 |
|
7964 |
@item GET |
7965 |
@vindex GET |
7966 |
Program for extracting a file from SCCS; default @samp{get}. |
7967 |
@pindex get |
7968 |
|
7969 |
@item LEX |
7970 |
@vindex LEX |
7971 |
Program to use to turn Lex grammars into C programs or Ratfor programs; |
7972 |
default @samp{lex}. |
7973 |
@pindex lex |
7974 |
|
7975 |
@item PC |
7976 |
@vindex PC |
7977 |
Program for compiling Pascal programs; default @samp{pc}. |
7978 |
@pindex pc |
7979 |
|
7980 |
@item YACC |
7981 |
@vindex YACC |
7982 |
Program to use to turn Yacc grammars into C programs; default @samp{yacc}. |
7983 |
@pindex yacc |
7984 |
|
7985 |
@item YACCR |
7986 |
@vindex YACCR |
7987 |
Program to use to turn Yacc grammars into Ratfor |
7988 |
programs; default @samp{yacc -r}. |
7989 |
|
7990 |
@item MAKEINFO |
7991 |
@vindex MAKEINFO |
7992 |
Program to convert a Texinfo source file into an Info file; default |
7993 |
@samp{makeinfo}. |
7994 |
@pindex makeinfo |
7995 |
|
7996 |
@item TEX |
7997 |
@vindex TEX |
7998 |
Program to make @TeX{} @sc{dvi} files from @TeX{} source; |
7999 |
default @samp{tex}. |
8000 |
@pindex tex |
8001 |
|
8002 |
@item TEXI2DVI |
8003 |
@vindex TEXI2DVI |
8004 |
Program to make @TeX{} @sc{dvi} files from Texinfo source; |
8005 |
default @samp{texi2dvi}. |
8006 |
@pindex texi2dvi |
8007 |
|
8008 |
@item WEAVE |
8009 |
@vindex WEAVE |
8010 |
Program to translate Web into @TeX{}; default @samp{weave}. |
8011 |
@pindex weave |
8012 |
|
8013 |
@item CWEAVE |
8014 |
@vindex CWEAVE |
8015 |
Program to translate C Web into @TeX{}; default @samp{cweave}. |
8016 |
@pindex cweave |
8017 |
|
8018 |
@item TANGLE |
8019 |
@vindex TANGLE |
8020 |
Program to translate Web into Pascal; default @samp{tangle}. |
8021 |
@pindex tangle |
8022 |
|
8023 |
@item CTANGLE |
8024 |
@vindex CTANGLE |
8025 |
Program to translate C Web into C; default @samp{ctangle}. |
8026 |
@pindex ctangle |
8027 |
|
8028 |
@item RM |
8029 |
@vindex RM |
8030 |
Command to remove a file; default @samp{rm -f}. |
8031 |
@pindex rm |
8032 |
@end table |
8033 |
|
8034 |
Here is a table of variables whose values are additional arguments for the |
8035 |
programs above. The default values for all of these is the empty |
8036 |
string, unless otherwise noted. |
8037 |
|
8038 |
@table @code |
8039 |
@item ARFLAGS |
8040 |
@vindex ARFLAGS |
8041 |
Flags to give the archive-maintaining program; default @samp{rv}. |
8042 |
|
8043 |
@item ASFLAGS |
8044 |
@vindex ASFLAGS |
8045 |
Extra flags to give to the assembler (when explicitly |
8046 |
invoked on a @samp{.s} or @samp{.S} file). |
8047 |
|
8048 |
@item CFLAGS |
8049 |
@vindex CFLAGS |
8050 |
Extra flags to give to the C compiler. |
8051 |
|
8052 |
@item CXXFLAGS |
8053 |
@vindex CXXFLAGS |
8054 |
Extra flags to give to the C++ compiler. |
8055 |
|
8056 |
@item COFLAGS |
8057 |
@vindex COFLAGS |
8058 |
Extra flags to give to the RCS @code{co} program. |
8059 |
|
8060 |
@item CPPFLAGS |
8061 |
@vindex CPPFLAGS |
8062 |
Extra flags to give to the C preprocessor and programs |
8063 |
that use it (the C and Fortran compilers). |
8064 |
|
8065 |
@item FFLAGS |
8066 |
@vindex FFLAGS |
8067 |
Extra flags to give to the Fortran compiler. |
8068 |
|
8069 |
@item GFLAGS |
8070 |
@vindex GFLAGS |
8071 |
Extra flags to give to the SCCS @code{get} program. |
8072 |
|
8073 |
@item LDFLAGS |
8074 |
@vindex LDFLAGS |
8075 |
Extra flags to give to compilers when they are |
8076 |
supposed to invoke the linker, @samp{ld}. |
8077 |
|
8078 |
@item LFLAGS |
8079 |
@vindex LFLAGS |
8080 |
Extra flags to give to Lex. |
8081 |
|
8082 |
@item PFLAGS |
8083 |
@vindex PFLAGS |
8084 |
Extra flags to give to the Pascal compiler. |
8085 |
|
8086 |
@item RFLAGS |
8087 |
@vindex RFLAGS |
8088 |
Extra flags to give to the Fortran compiler for Ratfor programs. |
8089 |
|
8090 |
@item YFLAGS |
8091 |
@vindex YFLAGS |
8092 |
Extra flags to give to Yacc. |
8093 |
@end table |
8094 |
|
8095 |
@node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules |
8096 |
@section Chains of Implicit Rules |
8097 |
|
8098 |
@cindex chains of rules |
8099 |
@cindex rule, implicit, chains of |
8100 |
Sometimes a file can be made by a sequence of implicit rules. For example, |
8101 |
a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running |
8102 |
first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. |
8103 |
|
8104 |
If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no |
8105 |
special searching is required: @code{make} finds that the object file can |
8106 |
be made by C compilation from @file{@var{n}.c}; later on, when considering |
8107 |
how to make @file{@var{n}.c}, the rule for running Yacc is |
8108 |
used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are |
8109 |
updated.@refill |
8110 |
|
8111 |
@cindex intermediate files |
8112 |
@cindex files, intermediate |
8113 |
However, even if @file{@var{n}.c} does not exist and is not mentioned, |
8114 |
@code{make} knows how to envision it as the missing link between |
8115 |
@file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is |
8116 |
called an @dfn{intermediate file}. Once @code{make} has decided to use the |
8117 |
intermediate file, it is entered in the data base as if it had been |
8118 |
mentioned in the makefile, along with the implicit rule that says how to |
8119 |
create it.@refill |
8120 |
|
8121 |
Intermediate files are remade using their rules just like all other |
8122 |
files. But intermediate files are treated differently in two ways. |
8123 |
|
8124 |
The first difference is what happens if the intermediate file does not |
8125 |
exist. If an ordinary file @var{b} does not exist, and @code{make} |
8126 |
considers a target that depends on @var{b}, it invariably creates |
8127 |
@var{b} and then updates the target from @var{b}. But if @var{b} is an |
8128 |
intermediate file, then @code{make} can leave well enough alone. It |
8129 |
won't bother updating @var{b}, or the ultimate target, unless some |
8130 |
prerequisite of @var{b} is newer than that target or there is some other |
8131 |
reason to update that target. |
8132 |
|
8133 |
The second difference is that if @code{make} @emph{does} create @var{b} |
8134 |
in order to update something else, it deletes @var{b} later on after it |
8135 |
is no longer needed. Therefore, an intermediate file which did not |
8136 |
exist before @code{make} also does not exist after @code{make}. |
8137 |
@code{make} reports the deletion to you by printing a @samp{rm -f} |
8138 |
command showing which file it is deleting. |
8139 |
|
8140 |
Ordinarily, a file cannot be intermediate if it is mentioned in the |
8141 |
makefile as a target or prerequisite. However, you can explicitly mark a |
8142 |
file as intermediate by listing it as a prerequisite of the special target |
8143 |
@code{.INTERMEDIATE}. This takes effect even if the file is mentioned |
8144 |
explicitly in some other way. |
8145 |
|
8146 |
@cindex intermediate files, preserving |
8147 |
@cindex preserving intermediate files |
8148 |
@cindex secondary files |
8149 |
You can prevent automatic deletion of an intermediate file by marking it |
8150 |
as a @dfn{secondary} file. To do this, list it as a prerequisite of the |
8151 |
special target @code{.SECONDARY}. When a file is secondary, @code{make} |
8152 |
will not create the file merely because it does not already exist, but |
8153 |
@code{make} does not automatically delete the file. Marking a file as |
8154 |
secondary also marks it as intermediate. |
8155 |
|
8156 |
You can list the target pattern of an implicit rule (such as @samp{%.o}) |
8157 |
as a prerequisite of the special target @code{.PRECIOUS} to preserve |
8158 |
intermediate files made by implicit rules whose target patterns match |
8159 |
that file's name; see @ref{Interrupts}.@refill |
8160 |
@cindex preserving with @code{.PRECIOUS} |
8161 |
@cindex @code{.PRECIOUS} intermediate files |
8162 |
|
8163 |
A chain can involve more than two implicit rules. For example, it is |
8164 |
possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, |
8165 |
Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are |
8166 |
intermediate files that are deleted at the end.@refill |
8167 |
|
8168 |
No single implicit rule can appear more than once in a chain. This means |
8169 |
that @code{make} will not even consider such a ridiculous thing as making |
8170 |
@file{foo} from @file{foo.o.o} by running the linker twice. This |
8171 |
constraint has the added benefit of preventing any infinite loop in the |
8172 |
search for an implicit rule chain. |
8173 |
|
8174 |
There are some special implicit rules to optimize certain cases that would |
8175 |
otherwise be handled by rule chains. For example, making @file{foo} from |
8176 |
@file{foo.c} could be handled by compiling and linking with separate |
8177 |
chained rules, using @file{foo.o} as an intermediate file. But what |
8178 |
actually happens is that a special rule for this case does the compilation |
8179 |
and linking with a single @code{cc} command. The optimized rule is used in |
8180 |
preference to the step-by-step chain because it comes earlier in the |
8181 |
ordering of rules. |
8182 |
|
8183 |
@node Pattern Rules, Last Resort, Chained Rules, Implicit Rules |
8184 |
@section Defining and Redefining Pattern Rules |
8185 |
|
8186 |
You define an implicit rule by writing a @dfn{pattern rule}. A pattern |
8187 |
rule looks like an ordinary rule, except that its target contains the |
8188 |
character @samp{%} (exactly one of them). The target is considered a |
8189 |
pattern for matching file names; the @samp{%} can match any nonempty |
8190 |
substring, while other characters match only themselves. The prerequisites |
8191 |
likewise use @samp{%} to show how their names relate to the target name. |
8192 |
|
8193 |
Thus, a pattern rule @samp{%.o : %.c} says how to make any file |
8194 |
@file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill |
8195 |
|
8196 |
Note that expansion using @samp{%} in pattern rules occurs |
8197 |
@strong{after} any variable or function expansions, which take place |
8198 |
when the makefile is read. @xref{Using Variables, , How to Use |
8199 |
Variables}, and @ref{Functions, ,Functions for Transforming Text}. |
8200 |
|
8201 |
@menu |
8202 |
* Pattern Intro:: An introduction to pattern rules. |
8203 |
* Pattern Examples:: Examples of pattern rules. |
8204 |
* Automatic Variables:: How to use automatic variables in the |
8205 |
commands of implicit rules. |
8206 |
* Pattern Match:: How patterns match. |
8207 |
* Match-Anything Rules:: Precautions you should take prior to |
8208 |
defining rules that can match any |
8209 |
target file whatever. |
8210 |
* Canceling Rules:: How to override or cancel built-in rules. |
8211 |
@end menu |
8212 |
|
8213 |
@node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules |
8214 |
@subsection Introduction to Pattern Rules |
8215 |
@cindex pattern rule |
8216 |
@cindex rule, pattern |
8217 |
|
8218 |
A pattern rule contains the character @samp{%} (exactly one of them) |
8219 |
in the target; otherwise, it looks exactly like an ordinary rule. The |
8220 |
target is a pattern for matching file names; the @samp{%} matches any |
8221 |
nonempty substring, while other characters match only themselves. |
8222 |
@cindex target pattern, implicit |
8223 |
@cindex @code{%}, in pattern rules |
8224 |
|
8225 |
For example, @samp{%.c} as a pattern matches any file name that ends in |
8226 |
@samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts |
8227 |
with @samp{s.}, ends in @samp{.c} and is at least five characters long. |
8228 |
(There must be at least one character to match the @samp{%}.) The substring |
8229 |
that the @samp{%} matches is called the @dfn{stem}.@refill |
8230 |
|
8231 |
@samp{%} in a prerequisite of a pattern rule stands for the same stem |
8232 |
that was matched by the @samp{%} in the target. In order for |
8233 |
the pattern rule to apply, its target pattern must match the file name |
8234 |
under consideration, and its prerequisite patterns must name files that |
8235 |
exist or can be made. These files become prerequisites of the target. |
8236 |
@cindex prerequisite pattern, implicit |
8237 |
|
8238 |
Thus, a rule of the form |
8239 |
|
8240 |
@example |
8241 |
%.o : %.c ; @var{command}@dots{} |
8242 |
@end example |
8243 |
|
8244 |
@noindent |
8245 |
specifies how to make a file @file{@var{n}.o}, with another file |
8246 |
@file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c} |
8247 |
exists or can be made. |
8248 |
|
8249 |
There may also be prerequisites that do not use @samp{%}; such a prerequisite |
8250 |
attaches to every file made by this pattern rule. These unvarying |
8251 |
prerequisites are useful occasionally. |
8252 |
|
8253 |
A pattern rule need not have any prerequisites that contain @samp{%}, or |
8254 |
in fact any prerequisites at all. Such a rule is effectively a general |
8255 |
wildcard. It provides a way to make any file that matches the target |
8256 |
pattern. @xref{Last Resort}. |
8257 |
|
8258 |
@c !!! The end of of this paragraph should be rewritten. --bob |
8259 |
Pattern rules may have more than one target. Unlike normal rules, this |
8260 |
does not act as many different rules with the same prerequisites and |
8261 |
commands. If a pattern rule has multiple targets, @code{make} knows that |
8262 |
the rule's commands are responsible for making all of the targets. The |
8263 |
commands are executed only once to make all the targets. When searching |
8264 |
for a pattern rule to match a target, the target patterns of a rule other |
8265 |
than the one that matches the target in need of a rule are incidental: |
8266 |
@code{make} worries only about giving commands and prerequisites to the file |
8267 |
presently in question. However, when this file's commands are run, the |
8268 |
other targets are marked as having been updated themselves. |
8269 |
@cindex multiple targets, in pattern rule |
8270 |
@cindex target, multiple in pattern rule |
8271 |
|
8272 |
The order in which pattern rules appear in the makefile is important |
8273 |
since this is the order in which they are considered. |
8274 |
Of equally applicable |
8275 |
rules, only the first one found is used. The rules you write take precedence |
8276 |
over those that are built in. Note however, that a rule whose |
8277 |
prerequisites actually exist or are mentioned always takes priority over a |
8278 |
rule with prerequisites that must be made by chaining other implicit rules. |
8279 |
@cindex pattern rules, order of |
8280 |
@cindex order of pattern rules |
8281 |
|
8282 |
@node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules |
8283 |
@subsection Pattern Rule Examples |
8284 |
|
8285 |
Here are some examples of pattern rules actually predefined in |
8286 |
@code{make}. First, the rule that compiles @samp{.c} files into @samp{.o} |
8287 |
files:@refill |
8288 |
|
8289 |
@example |
8290 |
%.o : %.c |
8291 |
$(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@ |
8292 |
@end example |
8293 |
|
8294 |
@noindent |
8295 |
defines a rule that can make any file @file{@var{x}.o} from |
8296 |
@file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and |
8297 |
@samp{$<} to substitute the names of the target file and the source file |
8298 |
in each case where the rule applies (@pxref{Automatic Variables}).@refill |
8299 |
|
8300 |
Here is a second built-in rule: |
8301 |
|
8302 |
@example |
8303 |
% :: RCS/%,v |
8304 |
$(CO) $(COFLAGS) $< |
8305 |
@end example |
8306 |
|
8307 |
@noindent |
8308 |
defines a rule that can make any file @file{@var{x}} whatsoever from a |
8309 |
corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since |
8310 |
the target is @samp{%}, this rule will apply to any file whatever, provided |
8311 |
the appropriate prerequisite file exists. The double colon makes the rule |
8312 |
@dfn{terminal}, which means that its prerequisite may not be an intermediate |
8313 |
file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill |
8314 |
|
8315 |
@need 500 |
8316 |
This pattern rule has two targets: |
8317 |
|
8318 |
@example |
8319 |
@group |
8320 |
%.tab.c %.tab.h: %.y |
8321 |
bison -d $< |
8322 |
@end group |
8323 |
@end example |
8324 |
|
8325 |
@noindent |
8326 |
@c The following paragraph is rewritten to avoid overfull hboxes |
8327 |
This tells @code{make} that the command @samp{bison -d @var{x}.y} will |
8328 |
make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file |
8329 |
@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} |
8330 |
and the file @file{scan.o} depends on the file @file{parse.tab.h}, |
8331 |
when @file{parse.y} is changed, the command @samp{bison -d parse.y} |
8332 |
will be executed only once, and the prerequisites of both |
8333 |
@file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably |
8334 |
the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c} |
8335 |
and the file @file{scan.o} from @file{scan.c}, while @file{foo} is |
8336 |
linked from @file{parse.tab.o}, @file{scan.o}, and its other |
8337 |
prerequisites, and it will execute happily ever after.)@refill |
8338 |
|
8339 |
@node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules |
8340 |
@subsection Automatic Variables |
8341 |
@cindex automatic variables |
8342 |
@cindex variables, automatic |
8343 |
@cindex variables, and implicit rule |
8344 |
|
8345 |
Suppose you are writing a pattern rule to compile a @samp{.c} file into a |
8346 |
@samp{.o} file: how do you write the @samp{cc} command so that it operates |
8347 |
on the right source file name? You cannot write the name in the command, |
8348 |
because the name is different each time the implicit rule is applied. |
8349 |
|
8350 |
What you do is use a special feature of @code{make}, the @dfn{automatic |
8351 |
variables}. These variables have values computed afresh for each rule that |
8352 |
is executed, based on the target and prerequisites of the rule. In this |
8353 |
example, you would use @samp{$@@} for the object file name and @samp{$<} |
8354 |
for the source file name. |
8355 |
|
8356 |
@cindex automatic variables in prerequisites |
8357 |
@cindex prerequisites, and automatic variables |
8358 |
It's very important that you recognize the limited scope in which |
8359 |
automatic variable values are available: they only have values within |
8360 |
the command script. In particular, you cannot use them anywhere |
8361 |
within the target or prerequisite lists of a rule; they have no value |
8362 |
there and will expand to the empty string. A common mistake is |
8363 |
attempting to use @code{$@@} within the prerequisites list in a rule; |
8364 |
this will not work. However, see below for information on the |
8365 |
SysV-style @code{$$@@} variables. |
8366 |
|
8367 |
Here is a table of automatic variables: |
8368 |
|
8369 |
@table @code |
8370 |
@vindex $@@ |
8371 |
@vindex @@ @r{(automatic variable)} |
8372 |
@item $@@ |
8373 |
The file name of the target of the rule. If the target is an archive |
8374 |
member, then @samp{$@@} is the name of the archive file. In a pattern |
8375 |
rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to |
8376 |
Pattern Rules}), @samp{$@@} is the name of whichever target caused the |
8377 |
rule's commands to be run. |
8378 |
|
8379 |
@vindex $% |
8380 |
@vindex % @r{(automatic variable)} |
8381 |
@item $% |
8382 |
The target member name, when the target is an archive member. |
8383 |
@xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then |
8384 |
@samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is |
8385 |
empty when the target is not an archive member. |
8386 |
|
8387 |
@vindex $< |
8388 |
@vindex < @r{(automatic variable)} |
8389 |
@item $< |
8390 |
The name of the first prerequisite. If the target got its commands from |
8391 |
an implicit rule, this will be the first prerequisite added by the |
8392 |
implicit rule (@pxref{Implicit Rules}). |
8393 |
|
8394 |
@vindex $? |
8395 |
@vindex ? @r{(automatic variable)} |
8396 |
@item $? |
8397 |
The names of all the prerequisites that are newer than the target, with |
8398 |
spaces between them. For prerequisites which are archive members, only |
8399 |
the member named is used (@pxref{Archives}). |
8400 |
@cindex prerequisites, list of changed |
8401 |
@cindex list of changed prerequisites |
8402 |
|
8403 |
@vindex $^ |
8404 |
@vindex ^ @r{(automatic variable)} |
8405 |
@item $^ |
8406 |
The names of all the prerequisites, with spaces between them. For |
8407 |
prerequisites which are archive members, only the member named is used |
8408 |
(@pxref{Archives}). A target has only one prerequisite on each other file |
8409 |
it depends on, no matter how many times each file is listed as a |
8410 |
prerequisite. So if you list a prerequisite more than once for a target, |
8411 |
the value of @code{$^} contains just one copy of the name. |
8412 |
@cindex prerequisites, list of all |
8413 |
@cindex list of all prerequisites |
8414 |
|
8415 |
@vindex $+ |
8416 |
@vindex + @r{(automatic variable)} |
8417 |
@item $+ |
8418 |
This is like @samp{$^}, but prerequisites listed more than once are |
8419 |
duplicated in the order they were listed in the makefile. This is |
8420 |
primarily useful for use in linking commands where it is meaningful to |
8421 |
repeat library file names in a particular order. |
8422 |
|
8423 |
@vindex $* |
8424 |
@vindex * @r{(automatic variable)} |
8425 |
@item $* |
8426 |
The stem with which an implicit rule matches (@pxref{Pattern Match, ,How |
8427 |
Patterns Match}). If the target is @file{dir/a.foo.b} and the target |
8428 |
pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is |
8429 |
useful for constructing names of related files.@refill |
8430 |
@cindex stem, variable for |
8431 |
|
8432 |
In a static pattern rule, the stem is part of the file name that matched |
8433 |
the @samp{%} in the target pattern. |
8434 |
|
8435 |
In an explicit rule, there is no stem; so @samp{$*} cannot be determined |
8436 |
in that way. Instead, if the target name ends with a recognized suffix |
8437 |
(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to |
8438 |
the target name minus the suffix. For example, if the target name is |
8439 |
@samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a |
8440 |
suffix. GNU @code{make} does this bizarre thing only for compatibility |
8441 |
with other implementations of @code{make}. You should generally avoid |
8442 |
using @samp{$*} except in implicit rules or static pattern rules.@refill |
8443 |
|
8444 |
If the target name in an explicit rule does not end with a recognized |
8445 |
suffix, @samp{$*} is set to the empty string for that rule. |
8446 |
@end table |
8447 |
|
8448 |
@samp{$?} is useful even in explicit rules when you wish to operate on only |
8449 |
the prerequisites that have changed. For example, suppose that an archive |
8450 |
named @file{lib} is supposed to contain copies of several object files. |
8451 |
This rule copies just the changed object files into the archive: |
8452 |
|
8453 |
@example |
8454 |
@group |
8455 |
lib: foo.o bar.o lose.o win.o |
8456 |
ar r lib $? |
8457 |
@end group |
8458 |
@end example |
8459 |
|
8460 |
Of the variables listed above, four have values that are single file |
8461 |
names, and three have values that are lists of file names. These seven |
8462 |
have variants that get just the file's directory name or just the file |
8463 |
name within the directory. The variant variables' names are formed by |
8464 |
appending @samp{D} or @samp{F}, respectively. These variants are |
8465 |
semi-obsolete in GNU @code{make} since the functions @code{dir} and |
8466 |
@code{notdir} can be used to get a similar effect (@pxref{File Name |
8467 |
Functions, , Functions for File Names}). Note, however, that the |
8468 |
@samp{D} variants all omit the trailing slash which always appears in |
8469 |
the output of the @code{dir} function. Here is a table of the variants: |
8470 |
|
8471 |
@table @samp |
8472 |
@vindex $(@@D) |
8473 |
@vindex @@D @r{(automatic variable)} |
8474 |
@item $(@@D) |
8475 |
The directory part of the file name of the target, with the trailing |
8476 |
slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then |
8477 |
@samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does |
8478 |
not contain a slash. |
8479 |
|
8480 |
@vindex $(@@F) |
8481 |
@vindex @@F @r{(automatic variable)} |
8482 |
@item $(@@F) |
8483 |
The file-within-directory part of the file name of the target. If the |
8484 |
value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is |
8485 |
@file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}. |
8486 |
|
8487 |
@vindex $(*D) |
8488 |
@vindex *D @r{(automatic variable)} |
8489 |
@item $(*D) |
8490 |
@vindex $(*F) |
8491 |
@vindex *F @r{(automatic variable)} |
8492 |
@itemx $(*F) |
8493 |
The directory part and the file-within-directory |
8494 |
part of the stem; @file{dir} and @file{foo} in this example. |
8495 |
|
8496 |
@vindex $(%D) |
8497 |
@vindex %D @r{(automatic variable)} |
8498 |
@item $(%D) |
8499 |
@vindex $(%F) |
8500 |
@vindex %F @r{(automatic variable)} |
8501 |
@itemx $(%F) |
8502 |
The directory part and the file-within-directory part of the target |
8503 |
archive member name. This makes sense only for archive member targets |
8504 |
of the form @file{@var{archive}(@var{member})} and is useful only when |
8505 |
@var{member} may contain a directory name. (@xref{Archive Members, |
8506 |
,Archive Members as Targets}.) |
8507 |
|
8508 |
@vindex $(<D) |
8509 |
@vindex <D @r{(automatic variable)} |
8510 |
@item $(<D) |
8511 |
@vindex $(<F) |
8512 |
@vindex <F @r{(automatic variable)} |
8513 |
@itemx $(<F) |
8514 |
The directory part and the file-within-directory |
8515 |
part of the first prerequisite. |
8516 |
|
8517 |
@vindex $(^D) |
8518 |
@vindex ^D @r{(automatic variable)} |
8519 |
@item $(^D) |
8520 |
@vindex $(^F) |
8521 |
@vindex ^F @r{(automatic variable)} |
8522 |
@itemx $(^F) |
8523 |
Lists of the directory parts and the file-within-directory |
8524 |
parts of all prerequisites. |
8525 |
|
8526 |
@vindex $(+D) |
8527 |
@vindex +D @r{(automatic variable)} |
8528 |
@item $(+D) |
8529 |
@vindex $(+F) |
8530 |
@vindex +F @r{(automatic variable)} |
8531 |
@itemx $(+F) |
8532 |
Lists of the directory parts and the file-within-directory |
8533 |
parts of all prerequisites, including multiple instances of duplicated |
8534 |
prerequisites. |
8535 |
|
8536 |
@vindex $(?D) |
8537 |
@vindex ?D @r{(automatic variable)} |
8538 |
@item $(?D) |
8539 |
@vindex $(?F) |
8540 |
@vindex ?F @r{(automatic variable)} |
8541 |
@itemx $(?F) |
8542 |
Lists of the directory parts and the file-within-directory parts of |
8543 |
all prerequisites that are newer than the target. |
8544 |
@end table |
8545 |
|
8546 |
Note that we use a special stylistic convention when we talk about these |
8547 |
automatic variables; we write ``the value of @samp{$<}'', rather than |
8548 |
@w{``the variable @code{<}''} as we would write for ordinary variables |
8549 |
such as @code{objects} and @code{CFLAGS}. We think this convention |
8550 |
looks more natural in this special case. Please do not assume it has a |
8551 |
deep significance; @samp{$<} refers to the variable named @code{<} just |
8552 |
as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}. |
8553 |
You could just as well use @samp{$(<)} in place of @samp{$<}. |
8554 |
|
8555 |
@vindex $$@@ |
8556 |
@vindex $$(@@D) |
8557 |
@vindex $$(@@F) |
8558 |
@cindex $$@@, support for |
8559 |
GNU @code{make} provides support for the SysV @code{make} feature that |
8560 |
allows special variable references @code{$$@@}, @code{$$(@@D)}, and |
8561 |
@code{$$(@@F)} (note the required double-''$''!) to appear with the |
8562 |
@emph{prerequisites list} (normal automatic variables are available |
8563 |
only within a command script). When appearing in a prerequisites |
8564 |
list, these variables are expanded to the name of the target, the |
8565 |
directory component of the target, and the file component of the |
8566 |
target, respectively. |
8567 |
|
8568 |
Note that these variables are available only within explicit and |
8569 |
static pattern (@pxref{Static Pattern, ,Static Pattern Rules}) rules; |
8570 |
they have no special significance within implicit (suffix or pattern) |
8571 |
rules. Also note that while SysV @code{make} actually expands its |
8572 |
entire prerequisite list @emph{twice}, GNU @code{make} does not behave |
8573 |
this way: instead it simply expands these special variables without |
8574 |
re-expanding any other part of the prerequisites list. |
8575 |
|
8576 |
This somewhat bizarre feature is included only to provide some |
8577 |
compatibility with SysV makefiles. In a native GNU @code{make} file |
8578 |
there are other ways to accomplish the same results. This feature is |
8579 |
disabled if the special pseudo target @code{.POSIX} is defined. |
8580 |
|
8581 |
@node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules |
8582 |
@subsection How Patterns Match |
8583 |
|
8584 |
@cindex stem |
8585 |
A target pattern is composed of a @samp{%} between a prefix and a suffix, |
8586 |
either or both of which may be empty. The pattern matches a file name only |
8587 |
if the file name starts with the prefix and ends with the suffix, without |
8588 |
overlap. The text between the prefix and the suffix is called the |
8589 |
@dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name |
8590 |
@file{test.o}, the stem is @samp{test}. The pattern rule prerequisites are |
8591 |
turned into actual file names by substituting the stem for the character |
8592 |
@samp{%}. Thus, if in the same example one of the prerequisites is written |
8593 |
as @samp{%.c}, it expands to @samp{test.c}.@refill |
8594 |
|
8595 |
When the target pattern does not contain a slash (and it usually does |
8596 |
not), directory names in the file names are removed from the file name |
8597 |
before it is compared with the target prefix and suffix. After the |
8598 |
comparison of the file name to the target pattern, the directory |
8599 |
names, along with the slash that ends them, are added on to the |
8600 |
prerequisite file names generated from the pattern rule's prerequisite |
8601 |
patterns and the file name. The directories are ignored only for the |
8602 |
purpose of finding an implicit rule to use, not in the application of |
8603 |
that rule. Thus, @samp{e%t} matches the file name @file{src/eat}, |
8604 |
with @samp{src/a} as the stem. When prerequisites are turned into file |
8605 |
names, the directories from the stem are added at the front, while the |
8606 |
rest of the stem is substituted for the @samp{%}. The stem |
8607 |
@samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name |
8608 |
@file{src/car}.@refill |
8609 |
|
8610 |
@node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules |
8611 |
@subsection Match-Anything Pattern Rules |
8612 |
|
8613 |
@cindex match-anything rule |
8614 |
@cindex terminal rule |
8615 |
When a pattern rule's target is just @samp{%}, it matches any file name |
8616 |
whatever. We call these rules @dfn{match-anything} rules. They are very |
8617 |
useful, but it can take a lot of time for @code{make} to think about them, |
8618 |
because it must consider every such rule for each file name listed either |
8619 |
as a target or as a prerequisite. |
8620 |
|
8621 |
Suppose the makefile mentions @file{foo.c}. For this target, @code{make} |
8622 |
would have to consider making it by linking an object file @file{foo.c.o}, |
8623 |
or by C compilation-and-linking in one step from @file{foo.c.c}, or by |
8624 |
Pascal compilation-and-linking from @file{foo.c.p}, and many other |
8625 |
possibilities. |
8626 |
|
8627 |
We know these possibilities are ridiculous since @file{foo.c} is a C source |
8628 |
file, not an executable. If @code{make} did consider these possibilities, |
8629 |
it would ultimately reject them, because files such as @file{foo.c.o} and |
8630 |
@file{foo.c.p} would not exist. But these possibilities are so |
8631 |
numerous that @code{make} would run very slowly if it had to consider |
8632 |
them.@refill |
8633 |
|
8634 |
To gain speed, we have put various constraints on the way @code{make} |
8635 |
considers match-anything rules. There are two different constraints that |
8636 |
can be applied, and each time you define a match-anything rule you must |
8637 |
choose one or the other for that rule. |
8638 |
|
8639 |
One choice is to mark the match-anything rule as @dfn{terminal} by defining |
8640 |
it with a double colon. When a rule is terminal, it does not apply unless |
8641 |
its prerequisites actually exist. Prerequisites that could be made with |
8642 |
other implicit rules are not good enough. In other words, no further |
8643 |
chaining is allowed beyond a terminal rule. |
8644 |
|
8645 |
For example, the built-in implicit rules for extracting sources from RCS |
8646 |
and SCCS files are terminal; as a result, if the file @file{foo.c,v} does |
8647 |
not exist, @code{make} will not even consider trying to make it as an |
8648 |
intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}. |
8649 |
RCS and SCCS files are generally ultimate source files, which should not be |
8650 |
remade from any other files; therefore, @code{make} can save time by not |
8651 |
looking for ways to remake them.@refill |
8652 |
|
8653 |
If you do not mark the match-anything rule as terminal, then it is |
8654 |
nonterminal. A nonterminal match-anything rule cannot apply to a file name |
8655 |
that indicates a specific type of data. A file name indicates a specific |
8656 |
type of data if some non-match-anything implicit rule target matches it. |
8657 |
|
8658 |
For example, the file name @file{foo.c} matches the target for the pattern |
8659 |
rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this |
8660 |
rule is actually applicable (which happens only if there is a file |
8661 |
@file{foo.y}), the fact that its target matches is enough to prevent |
8662 |
consideration of any nonterminal match-anything rules for the file |
8663 |
@file{foo.c}. Thus, @code{make} will not even consider trying to make |
8664 |
@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c}, |
8665 |
@file{foo.c.p}, etc.@refill |
8666 |
|
8667 |
The motivation for this constraint is that nonterminal match-anything |
8668 |
rules are used for making files containing specific types of data (such as |
8669 |
executable files) and a file name with a recognized suffix indicates some |
8670 |
other specific type of data (such as a C source file). |
8671 |
|
8672 |
Special built-in dummy pattern rules are provided solely to recognize |
8673 |
certain file names so that nonterminal match-anything rules will not be |
8674 |
considered. These dummy rules have no prerequisites and no commands, and |
8675 |
they are ignored for all other purposes. For example, the built-in |
8676 |
implicit rule |
8677 |
|
8678 |
@example |
8679 |
%.p : |
8680 |
@end example |
8681 |
|
8682 |
@noindent |
8683 |
exists to make sure that Pascal source files such as @file{foo.p} match a |
8684 |
specific target pattern and thereby prevent time from being wasted looking |
8685 |
for @file{foo.p.o} or @file{foo.p.c}. |
8686 |
|
8687 |
Dummy pattern rules such as the one for @samp{%.p} are made for every |
8688 |
suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}). |
8689 |
|
8690 |
@node Canceling Rules, , Match-Anything Rules, Pattern Rules |
8691 |
@subsection Canceling Implicit Rules |
8692 |
|
8693 |
You can override a built-in implicit rule (or one you have defined |
8694 |
yourself) by defining a new pattern rule with the same target and |
8695 |
prerequisites, but different commands. When the new rule is defined, the |
8696 |
built-in one is replaced. The new rule's position in the sequence of |
8697 |
implicit rules is determined by where you write the new rule. |
8698 |
|
8699 |
You can cancel a built-in implicit rule by defining a pattern rule with the |
8700 |
same target and prerequisites, but no commands. For example, the following |
8701 |
would cancel the rule that runs the assembler: |
8702 |
|
8703 |
@example |
8704 |
%.o : %.s |
8705 |
@end example |
8706 |
|
8707 |
@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules |
8708 |
@section Defining Last-Resort Default Rules |
8709 |
@cindex last-resort default rules |
8710 |
@cindex default rules, last-resort |
8711 |
|
8712 |
You can define a last-resort implicit rule by writing a terminal |
8713 |
match-anything pattern rule with no prerequisites (@pxref{Match-Anything |
8714 |
Rules}). This is just like any other pattern rule; the only thing |
8715 |
special about it is that it will match any target. So such a rule's |
8716 |
commands are used for all targets and prerequisites that have no commands |
8717 |
of their own and for which no other implicit rule applies. |
8718 |
|
8719 |
For example, when testing a makefile, you might not care if the source |
8720 |
files contain real data, only that they exist. Then you might do this: |
8721 |
|
8722 |
@example |
8723 |
%:: |
8724 |
touch $@@ |
8725 |
@end example |
8726 |
|
8727 |
@noindent |
8728 |
to cause all the source files needed (as prerequisites) to be created |
8729 |
automatically. |
8730 |
|
8731 |
@findex .DEFAULT |
8732 |
You can instead define commands to be used for targets for which there |
8733 |
are no rules at all, even ones which don't specify commands. You do |
8734 |
this by writing a rule for the target @code{.DEFAULT}. Such a rule's |
8735 |
commands are used for all prerequisites which do not appear as targets in |
8736 |
any explicit rule, and for which no implicit rule applies. Naturally, |
8737 |
there is no @code{.DEFAULT} rule unless you write one. |
8738 |
|
8739 |
If you use @code{.DEFAULT} with no commands or prerequisites: |
8740 |
|
8741 |
@example |
8742 |
.DEFAULT: |
8743 |
@end example |
8744 |
|
8745 |
@noindent |
8746 |
the commands previously stored for @code{.DEFAULT} are cleared. |
8747 |
Then @code{make} acts as if you had never defined @code{.DEFAULT} at all. |
8748 |
|
8749 |
If you do not want a target to get the commands from a match-anything |
8750 |
pattern rule or @code{.DEFAULT}, but you also do not want any commands |
8751 |
to be run for the target, you can give it empty commands (@pxref{Empty |
8752 |
Commands, ,Defining Empty Commands}).@refill |
8753 |
|
8754 |
You can use a last-resort rule to override part of another makefile. |
8755 |
@xref{Overriding Makefiles, , Overriding Part of Another Makefile}. |
8756 |
|
8757 |
@node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules |
8758 |
@section Old-Fashioned Suffix Rules |
8759 |
@cindex old-fashioned suffix rules |
8760 |
@cindex suffix rule |
8761 |
|
8762 |
@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for |
8763 |
@code{make}. Suffix rules are obsolete because pattern rules are more |
8764 |
general and clearer. They are supported in GNU @code{make} for |
8765 |
compatibility with old makefiles. They come in two kinds: |
8766 |
@dfn{double-suffix} and @dfn{single-suffix}.@refill |
8767 |
|
8768 |
A double-suffix rule is defined by a pair of suffixes: the target suffix |
8769 |
and the source suffix. It matches any file whose name ends with the |
8770 |
target suffix. The corresponding implicit prerequisite is made by |
8771 |
replacing the target suffix with the source suffix in the file name. A |
8772 |
two-suffix rule whose target and source suffixes are @samp{.o} and |
8773 |
@samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}. |
8774 |
|
8775 |
A single-suffix rule is defined by a single suffix, which is the source |
8776 |
suffix. It matches any file name, and the corresponding implicit |
8777 |
prerequisite name is made by appending the source suffix. A single-suffix |
8778 |
rule whose source suffix is @samp{.c} is equivalent to the pattern rule |
8779 |
@samp{% : %.c}. |
8780 |
|
8781 |
Suffix rule definitions are recognized by comparing each rule's target |
8782 |
against a defined list of known suffixes. When @code{make} sees a rule |
8783 |
whose target is a known suffix, this rule is considered a single-suffix |
8784 |
rule. When @code{make} sees a rule whose target is two known suffixes |
8785 |
concatenated, this rule is taken as a double-suffix rule. |
8786 |
|
8787 |
For example, @samp{.c} and @samp{.o} are both on the default list of |
8788 |
known suffixes. Therefore, if you define a rule whose target is |
8789 |
@samp{.c.o}, @code{make} takes it to be a double-suffix rule with source |
8790 |
suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned |
8791 |
way to define the rule for compiling a C source file:@refill |
8792 |
|
8793 |
@example |
8794 |
.c.o: |
8795 |
$(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< |
8796 |
@end example |
8797 |
|
8798 |
Suffix rules cannot have any prerequisites of their own. If they have any, |
8799 |
they are treated as normal files with funny names, not as suffix rules. |
8800 |
Thus, the rule: |
8801 |
|
8802 |
@example |
8803 |
.c.o: foo.h |
8804 |
$(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< |
8805 |
@end example |
8806 |
|
8807 |
@noindent |
8808 |
tells how to make the file @file{.c.o} from the prerequisite file |
8809 |
@file{foo.h}, and is not at all like the pattern rule: |
8810 |
|
8811 |
@example |
8812 |
%.o: %.c foo.h |
8813 |
$(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $< |
8814 |
@end example |
8815 |
|
8816 |
@noindent |
8817 |
which tells how to make @samp{.o} files from @samp{.c} files, and makes all |
8818 |
@samp{.o} files using this pattern rule also depend on @file{foo.h}. |
8819 |
|
8820 |
Suffix rules with no commands are also meaningless. They do not remove |
8821 |
previous rules as do pattern rules with no commands (@pxref{Canceling |
8822 |
Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as |
8823 |
a target in the data base.@refill |
8824 |
|
8825 |
@findex .SUFFIXES |
8826 |
The known suffixes are simply the names of the prerequisites of the special |
8827 |
target @code{.SUFFIXES}. You can add your own suffixes by writing a rule |
8828 |
for @code{.SUFFIXES} that adds more prerequisites, as in: |
8829 |
|
8830 |
@example |
8831 |
.SUFFIXES: .hack .win |
8832 |
@end example |
8833 |
|
8834 |
@noindent |
8835 |
which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes. |
8836 |
|
8837 |
If you wish to eliminate the default known suffixes instead of just adding |
8838 |
to them, write a rule for @code{.SUFFIXES} with no prerequisites. By |
8839 |
special dispensation, this eliminates all existing prerequisites of |
8840 |
@code{.SUFFIXES}. You can then write another rule to add the suffixes you |
8841 |
want. For example, |
8842 |
|
8843 |
@example |
8844 |
@group |
8845 |
.SUFFIXES: # @r{Delete the default suffixes} |
8846 |
.SUFFIXES: .c .o .h # @r{Define our suffix list} |
8847 |
@end group |
8848 |
@end example |
8849 |
|
8850 |
The @samp{-r} or @samp{--no-builtin-rules} flag causes the default |
8851 |
list of suffixes to be empty. |
8852 |
|
8853 |
@vindex SUFFIXES |
8854 |
The variable @code{SUFFIXES} is defined to the default list of suffixes |
8855 |
before @code{make} reads any makefiles. You can change the list of suffixes |
8856 |
with a rule for the special target @code{.SUFFIXES}, but that does not alter |
8857 |
this variable. |
8858 |
|
8859 |
@node Implicit Rule Search, , Suffix Rules, Implicit Rules |
8860 |
@section Implicit Rule Search Algorithm |
8861 |
@cindex implicit rule, search algorithm |
8862 |
@cindex search algorithm, implicit rule |
8863 |
|
8864 |
Here is the procedure @code{make} uses for searching for an implicit rule |
8865 |
for a target @var{t}. This procedure is followed for each double-colon |
8866 |
rule with no commands, for each target of ordinary rules none of which have |
8867 |
commands, and for each prerequisite that is not the target of any rule. It |
8868 |
is also followed recursively for prerequisites that come from implicit |
8869 |
rules, in the search for a chain of rules. |
8870 |
|
8871 |
Suffix rules are not mentioned in this algorithm because suffix rules are |
8872 |
converted to equivalent pattern rules once the makefiles have been read in. |
8873 |
|
8874 |
For an archive member target of the form |
8875 |
@samp{@var{archive}(@var{member})}, the following algorithm is run |
8876 |
twice, first using the entire target name @var{t}, and second using |
8877 |
@samp{(@var{member})} as the target @var{t} if the first run found no |
8878 |
rule.@refill |
8879 |
|
8880 |
@enumerate |
8881 |
@item |
8882 |
Split @var{t} into a directory part, called @var{d}, and the rest, |
8883 |
called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then |
8884 |
@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill |
8885 |
|
8886 |
@item |
8887 |
Make a list of all the pattern rules one of whose targets matches |
8888 |
@var{t} or @var{n}. If the target pattern contains a slash, it is |
8889 |
matched against @var{t}; otherwise, against @var{n}. |
8890 |
|
8891 |
@item |
8892 |
If any rule in that list is @emph{not} a match-anything rule, then |
8893 |
remove all nonterminal match-anything rules from the list. |
8894 |
|
8895 |
@item |
8896 |
Remove from the list all rules with no commands. |
8897 |
|
8898 |
@item |
8899 |
For each pattern rule in the list: |
8900 |
|
8901 |
@enumerate a |
8902 |
@item |
8903 |
Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n} |
8904 |
matched by the @samp{%} in the target pattern.@refill |
8905 |
|
8906 |
@item |
8907 |
Compute the prerequisite names by substituting @var{s} for @samp{%}; if |
8908 |
the target pattern does not contain a slash, append @var{d} to |
8909 |
the front of each prerequisite name.@refill |
8910 |
|
8911 |
@item |
8912 |
Test whether all the prerequisites exist or ought to exist. (If a |
8913 |
file name is mentioned in the makefile as a target or as an explicit |
8914 |
prerequisite, then we say it ought to exist.) |
8915 |
|
8916 |
If all prerequisites exist or ought to exist, or there are no prerequisites, |
8917 |
then this rule applies. |
8918 |
@end enumerate |
8919 |
|
8920 |
@item |
8921 |
If no pattern rule has been found so far, try harder. |
8922 |
For each pattern rule in the list: |
8923 |
|
8924 |
@enumerate a |
8925 |
@item |
8926 |
If the rule is terminal, ignore it and go on to the next rule. |
8927 |
|
8928 |
@item |
8929 |
Compute the prerequisite names as before. |
8930 |
|
8931 |
@item |
8932 |
Test whether all the prerequisites exist or ought to exist. |
8933 |
|
8934 |
@item |
8935 |
For each prerequisite that does not exist, follow this algorithm |
8936 |
recursively to see if the prerequisite can be made by an implicit |
8937 |
rule. |
8938 |
|
8939 |
@item |
8940 |
If all prerequisites exist, ought to exist, or can be |
8941 |
made by implicit rules, then this rule applies. |
8942 |
@end enumerate |
8943 |
|
8944 |
@item |
8945 |
If no implicit rule applies, the rule for @code{.DEFAULT}, if any, |
8946 |
applies. In that case, give @var{t} the same commands that |
8947 |
@code{.DEFAULT} has. Otherwise, there are no commands for @var{t}. |
8948 |
@end enumerate |
8949 |
|
8950 |
Once a rule that applies has been found, for each target pattern of the |
8951 |
rule other than the one that matched @var{t} or @var{n}, the @samp{%} in |
8952 |
the pattern is replaced with @var{s} and the resultant file name is stored |
8953 |
until the commands to remake the target file @var{t} are executed. After |
8954 |
these commands are executed, each of these stored file names are entered |
8955 |
into the data base and marked as having been updated and having the same |
8956 |
update status as the file @var{t}. |
8957 |
|
8958 |
When the commands of a pattern rule are executed for @var{t}, the automatic |
8959 |
variables are set corresponding to the target and prerequisites. |
8960 |
@xref{Automatic Variables}. |
8961 |
|
8962 |
@node Archives, Features, Implicit Rules, Top |
8963 |
@chapter Using @code{make} to Update Archive Files |
8964 |
@cindex archive |
8965 |
|
8966 |
@dfn{Archive files} are files containing named subfiles called |
8967 |
@dfn{members}; they are maintained with the program @code{ar} and their |
8968 |
main use is as subroutine libraries for linking. |
8969 |
|
8970 |
@menu |
8971 |
* Archive Members:: Archive members as targets. |
8972 |
* Archive Update:: The implicit rule for archive member targets. |
8973 |
* Archive Pitfalls:: Dangers to watch out for when using archives. |
8974 |
* Archive Suffix Rules:: You can write a special kind of suffix rule |
8975 |
for updating archives. |
8976 |
@end menu |
8977 |
|
8978 |
@node Archive Members, Archive Update, Archives, Archives |
8979 |
@section Archive Members as Targets |
8980 |
@cindex archive member targets |
8981 |
|
8982 |
An individual member of an archive file can be used as a target or |
8983 |
prerequisite in @code{make}. You specify the member named @var{member} in |
8984 |
archive file @var{archive} as follows: |
8985 |
|
8986 |
@example |
8987 |
@var{archive}(@var{member}) |
8988 |
@end example |
8989 |
|
8990 |
@noindent |
8991 |
This construct is available only in targets and prerequisites, not in |
8992 |
commands! Most programs that you might use in commands do not support this |
8993 |
syntax and cannot act directly on archive members. Only @code{ar} and |
8994 |
other programs specifically designed to operate on archives can do so. |
8995 |
Therefore, valid commands to update an archive member target probably must |
8996 |
use @code{ar}. For example, this rule says to create a member |
8997 |
@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}: |
8998 |
|
8999 |
@example |
9000 |
foolib(hack.o) : hack.o |
9001 |
ar cr foolib hack.o |
9002 |
@end example |
9003 |
|
9004 |
In fact, nearly all archive member targets are updated in just this way |
9005 |
and there is an implicit rule to do it for you. @strong{Note:} The |
9006 |
@samp{c} flag to @code{ar} is required if the archive file does not |
9007 |
already exist. |
9008 |
|
9009 |
To specify several members in the same archive, you can write all the |
9010 |
member names together between the parentheses. For example: |
9011 |
|
9012 |
@example |
9013 |
foolib(hack.o kludge.o) |
9014 |
@end example |
9015 |
|
9016 |
@noindent |
9017 |
is equivalent to: |
9018 |
|
9019 |
@example |
9020 |
foolib(hack.o) foolib(kludge.o) |
9021 |
@end example |
9022 |
|
9023 |
@cindex wildcard, in archive member |
9024 |
You can also use shell-style wildcards in an archive member reference. |
9025 |
@xref{Wildcards, ,Using Wildcard Characters in File Names}. For |
9026 |
example, @w{@samp{foolib(*.o)}} expands to all existing members of the |
9027 |
@file{foolib} archive whose names end in @samp{.o}; perhaps |
9028 |
@samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}. |
9029 |
|
9030 |
@node Archive Update, Archive Pitfalls, Archive Members, Archives |
9031 |
@section Implicit Rule for Archive Member Targets |
9032 |
|
9033 |
Recall that a target that looks like @file{@var{a}(@var{m})} stands for the |
9034 |
member named @var{m} in the archive file @var{a}. |
9035 |
|
9036 |
When @code{make} looks for an implicit rule for such a target, as a special |
9037 |
feature it considers implicit rules that match @file{(@var{m})}, as well as |
9038 |
those that match the actual target @file{@var{a}(@var{m})}. |
9039 |
|
9040 |
This causes one special rule whose target is @file{(%)} to match. This |
9041 |
rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m} |
9042 |
into the archive. For example, it will update the archive member target |
9043 |
@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the |
9044 |
archive @file{foo.a} as a @emph{member} named @file{bar.o}. |
9045 |
|
9046 |
When this rule is chained with others, the result is very powerful. |
9047 |
Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the |
9048 |
@samp{(} and @samp{)} from being interpreted specially by the shell) in |
9049 |
the presence of a file @file{bar.c} is enough to cause the following |
9050 |
commands to be run, even without a makefile: |
9051 |
|
9052 |
@example |
9053 |
cc -c bar.c -o bar.o |
9054 |
ar r foo.a bar.o |
9055 |
rm -f bar.o |
9056 |
@end example |
9057 |
|
9058 |
@noindent |
9059 |
Here @code{make} has envisioned the file @file{bar.o} as an intermediate |
9060 |
file. @xref{Chained Rules, ,Chains of Implicit Rules}. |
9061 |
|
9062 |
Implicit rules such as this one are written using the automatic variable |
9063 |
@samp{$%}. @xref{Automatic Variables}. |
9064 |
|
9065 |
An archive member name in an archive cannot contain a directory name, but |
9066 |
it may be useful in a makefile to pretend that it does. If you write an |
9067 |
archive member target @file{foo.a(dir/file.o)}, @code{make} will perform |
9068 |
automatic updating with this command: |
9069 |
|
9070 |
@example |
9071 |
ar r foo.a dir/file.o |
9072 |
@end example |
9073 |
|
9074 |
@noindent |
9075 |
which has the effect of copying the file @file{dir/file.o} into a member |
9076 |
named @file{file.o}. In connection with such usage, the automatic variables |
9077 |
@code{%D} and @code{%F} may be useful. |
9078 |
|
9079 |
@menu |
9080 |
* Archive Symbols:: How to update archive symbol directories. |
9081 |
@end menu |
9082 |
|
9083 |
@node Archive Symbols, , Archive Update, Archive Update |
9084 |
@subsection Updating Archive Symbol Directories |
9085 |
@cindex @code{__.SYMDEF} |
9086 |
@cindex updating archive symbol directories |
9087 |
@cindex archive symbol directory updating |
9088 |
@cindex symbol directories, updating archive |
9089 |
@cindex directories, updating archive symbol |
9090 |
|
9091 |
An archive file that is used as a library usually contains a special member |
9092 |
named @file{__.SYMDEF} that contains a directory of the external symbol |
9093 |
names defined by all the other members. After you update any other |
9094 |
members, you need to update @file{__.SYMDEF} so that it will summarize the |
9095 |
other members properly. This is done by running the @code{ranlib} program: |
9096 |
|
9097 |
@example |
9098 |
ranlib @var{archivefile} |
9099 |
@end example |
9100 |
|
9101 |
Normally you would put this command in the rule for the archive file, |
9102 |
and make all the members of the archive file prerequisites of that rule. |
9103 |
For example, |
9104 |
|
9105 |
@example |
9106 |
libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{} |
9107 |
ranlib libfoo.a |
9108 |
@end example |
9109 |
|
9110 |
@noindent |
9111 |
The effect of this is to update archive members @file{x.o}, @file{y.o}, |
9112 |
etc., and then update the symbol directory member @file{__.SYMDEF} by |
9113 |
running @code{ranlib}. The rules for updating the members are not shown |
9114 |
here; most likely you can omit them and use the implicit rule which copies |
9115 |
files into the archive, as described in the preceding section. |
9116 |
|
9117 |
This is not necessary when using the GNU @code{ar} program, which |
9118 |
updates the @file{__.SYMDEF} member automatically. |
9119 |
|
9120 |
@node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives |
9121 |
@section Dangers When Using Archives |
9122 |
@cindex archive, and parallel execution |
9123 |
@cindex parallel execution, and archive update |
9124 |
@cindex archive, and @code{-j} |
9125 |
@cindex @code{-j}, and archive update |
9126 |
|
9127 |
It is important to be careful when using parallel execution (the |
9128 |
@code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives. |
9129 |
If multiple @code{ar} commands run at the same time on the same archive |
9130 |
file, they will not know about each other and can corrupt the file. |
9131 |
|
9132 |
Possibly a future version of @code{make} will provide a mechanism to |
9133 |
circumvent this problem by serializing all commands that operate on the |
9134 |
same archive file. But for the time being, you must either write your |
9135 |
makefiles to avoid this problem in some other way, or not use @code{-j}. |
9136 |
|
9137 |
@node Archive Suffix Rules, , Archive Pitfalls, Archives |
9138 |
@section Suffix Rules for Archive Files |
9139 |
@cindex suffix rule, for archive |
9140 |
@cindex archive, suffix rule for |
9141 |
@cindex library archive, suffix rule for |
9142 |
@cindex @code{.a} (archives) |
9143 |
|
9144 |
You can write a special kind of suffix rule for dealing with archive |
9145 |
files. @xref{Suffix Rules}, for a full explanation of suffix rules. |
9146 |
Archive suffix rules are obsolete in GNU @code{make}, because pattern |
9147 |
rules for archives are a more general mechanism (@pxref{Archive |
9148 |
Update}). But they are retained for compatibility with other |
9149 |
@code{make}s. |
9150 |
|
9151 |
To write a suffix rule for archives, you simply write a suffix rule |
9152 |
using the target suffix @samp{.a} (the usual suffix for archive files). |
9153 |
For example, here is the old-fashioned suffix rule to update a library |
9154 |
archive from C source files: |
9155 |
|
9156 |
@example |
9157 |
@group |
9158 |
.c.a: |
9159 |
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o |
9160 |
$(AR) r $@@ $*.o |
9161 |
$(RM) $*.o |
9162 |
@end group |
9163 |
@end example |
9164 |
|
9165 |
@noindent |
9166 |
This works just as if you had written the pattern rule: |
9167 |
|
9168 |
@example |
9169 |
@group |
9170 |
(%.o): %.c |
9171 |
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o |
9172 |
$(AR) r $@@ $*.o |
9173 |
$(RM) $*.o |
9174 |
@end group |
9175 |
@end example |
9176 |
|
9177 |
In fact, this is just what @code{make} does when it sees a suffix rule |
9178 |
with @samp{.a} as the target suffix. Any double-suffix rule |
9179 |
@w{@samp{.@var{x}.a}} is converted to a pattern rule with the target |
9180 |
pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}. |
9181 |
|
9182 |
Since you might want to use @samp{.a} as the suffix for some other kind |
9183 |
of file, @code{make} also converts archive suffix rules to pattern rules |
9184 |
in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule |
9185 |
@w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):} |
9186 |
@w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill |
9187 |
|
9188 |
@node Features, Missing, Archives, Top |
9189 |
@chapter Features of GNU @code{make} |
9190 |
@cindex features of GNU @code{make} |
9191 |
@cindex portability |
9192 |
@cindex compatibility |
9193 |
|
9194 |
Here is a summary of the features of GNU @code{make}, for comparison |
9195 |
with and credit to other versions of @code{make}. We consider the |
9196 |
features of @code{make} in 4.2 BSD systems as a baseline. If you are |
9197 |
concerned with writing portable makefiles, you should not use the |
9198 |
features of @code{make} listed here, nor the ones in @ref{Missing}. |
9199 |
|
9200 |
Many features come from the version of @code{make} in System V. |
9201 |
|
9202 |
@itemize @bullet |
9203 |
@item |
9204 |
The @code{VPATH} variable and its special meaning. |
9205 |
@xref{Directory Search, , Searching Directories for Prerequisites}. |
9206 |
This feature exists in System V @code{make}, but is undocumented. |
9207 |
It is documented in 4.3 BSD @code{make} (which says it mimics System V's |
9208 |
@code{VPATH} feature).@refill |
9209 |
|
9210 |
@item |
9211 |
Included makefiles. @xref{Include, ,Including Other Makefiles}. |
9212 |
Allowing multiple files to be included with a single directive is a GNU |
9213 |
extension. |
9214 |
|
9215 |
@item |
9216 |
Variables are read from and communicated via the environment. |
9217 |
@xref{Environment, ,Variables from the Environment}. |
9218 |
|
9219 |
@item |
9220 |
Options passed through the variable @code{MAKEFLAGS} to recursive |
9221 |
invocations of @code{make}. |
9222 |
@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. |
9223 |
|
9224 |
@item |
9225 |
The automatic variable @code{$%} is set to the member name |
9226 |
in an archive reference. @xref{Automatic Variables}. |
9227 |
|
9228 |
@item |
9229 |
The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%}, |
9230 |
and @code{$?} have corresponding forms like @code{$(@@F)} and |
9231 |
@code{$(@@D)}. We have generalized this to @code{$^} as an obvious |
9232 |
extension. @xref{Automatic Variables}.@refill |
9233 |
|
9234 |
@item |
9235 |
Substitution variable references. |
9236 |
@xref{Reference, ,Basics of Variable References}. |
9237 |
|
9238 |
@item |
9239 |
The command-line options @samp{-b} and @samp{-m}, accepted and |
9240 |
ignored. In System V @code{make}, these options actually do something. |
9241 |
|
9242 |
@item |
9243 |
Execution of recursive commands to run @code{make} via the variable |
9244 |
@code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified. |
9245 |
@xref{Recursion, ,Recursive Use of @code{make}}. |
9246 |
|
9247 |
@item |
9248 |
Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix |
9249 |
Rules}. This feature is obsolete in GNU @code{make}, because the |
9250 |
general feature of rule chaining (@pxref{Chained Rules, ,Chains of |
9251 |
Implicit Rules}) allows one pattern rule for installing members in an |
9252 |
archive (@pxref{Archive Update}) to be sufficient. |
9253 |
|
9254 |
@item |
9255 |
The arrangement of lines and backslash-newline combinations in |
9256 |
commands is retained when the commands are printed, so they appear as |
9257 |
they do in the makefile, except for the stripping of initial |
9258 |
whitespace. |
9259 |
@end itemize |
9260 |
|
9261 |
The following features were inspired by various other versions of |
9262 |
@code{make}. In some cases it is unclear exactly which versions inspired |
9263 |
which others. |
9264 |
|
9265 |
@itemize @bullet |
9266 |
@item |
9267 |
Pattern rules using @samp{%}. |
9268 |
This has been implemented in several versions of @code{make}. |
9269 |
We're not sure who invented it first, but it's been spread around a bit. |
9270 |
@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill |
9271 |
|
9272 |
@item |
9273 |
Rule chaining and implicit intermediate files. |
9274 |
This was implemented by Stu Feldman in his version of @code{make} |
9275 |
for AT&T Eighth Edition Research Unix, and later by Andrew Hume of |
9276 |
AT&T Bell Labs in his @code{mk} program (where he terms it |
9277 |
``transitive closure''). We do not really know if |
9278 |
we got this from either of them or thought it up ourselves at the |
9279 |
same time. @xref{Chained Rules, ,Chains of Implicit Rules}. |
9280 |
|
9281 |
@item |
9282 |
The automatic variable @code{$^} containing a list of all prerequisites |
9283 |
of the current target. We did not invent this, but we have no idea who |
9284 |
did. @xref{Automatic Variables}. The automatic variable |
9285 |
@code{$+} is a simple extension of @code{$^}. |
9286 |
|
9287 |
@item |
9288 |
The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know) |
9289 |
invented by Andrew Hume in @code{mk}. |
9290 |
@xref{Instead of Execution, ,Instead of Executing the Commands}. |
9291 |
|
9292 |
@item |
9293 |
The concept of doing several things at once (parallelism) exists in |
9294 |
many incarnations of @code{make} and similar programs, though not in the |
9295 |
System V or BSD implementations. @xref{Execution, ,Command Execution}. |
9296 |
|
9297 |
@item |
9298 |
Modified variable references using pattern substitution come from |
9299 |
SunOS 4. @xref{Reference, ,Basics of Variable References}. |
9300 |
This functionality was provided in GNU @code{make} by the |
9301 |
@code{patsubst} function before the alternate syntax was implemented |
9302 |
for compatibility with SunOS 4. It is not altogether clear who |
9303 |
inspired whom, since GNU @code{make} had @code{patsubst} before SunOS |
9304 |
4 was released.@refill |
9305 |
|
9306 |
@item |
9307 |
The special significance of @samp{+} characters preceding command lines |
9308 |
(@pxref{Instead of Execution, ,Instead of Executing the Commands}) is |
9309 |
mandated by |
9310 |
@cite{IEEE Standard 1003.2-1992} (POSIX.2). |
9311 |
|
9312 |
@item |
9313 |
The @samp{+=} syntax to append to the value of a variable comes from SunOS |
9314 |
4 @code{make}. @xref{Appending, , Appending More Text to Variables}. |
9315 |
|
9316 |
@item |
9317 |
The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list |
9318 |
multiple members in a single archive file comes from SunOS 4 @code{make}. |
9319 |
@xref{Archive Members}. |
9320 |
|
9321 |
@item |
9322 |
The @code{-include} directive to include makefiles with no error for a |
9323 |
nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4 |
9324 |
@code{make} does not allow multiple makefiles to be specified in one |
9325 |
@code{-include} directive.) The same feature appears with the name |
9326 |
@code{sinclude} in SGI @code{make} and perhaps others. |
9327 |
@end itemize |
9328 |
|
9329 |
The remaining features are inventions new in GNU @code{make}: |
9330 |
|
9331 |
@itemize @bullet |
9332 |
@item |
9333 |
Use the @samp{-v} or @samp{--version} option to print version and |
9334 |
copyright information. |
9335 |
|
9336 |
@item |
9337 |
Use the @samp{-h} or @samp{--help} option to summarize the options to |
9338 |
@code{make}. |
9339 |
|
9340 |
@item |
9341 |
Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}. |
9342 |
|
9343 |
@item |
9344 |
Pass command-line variable assignments automatically through the |
9345 |
variable @code{MAKE} to recursive @code{make} invocations. |
9346 |
@xref{Recursion, ,Recursive Use of @code{make}}. |
9347 |
|
9348 |
@item |
9349 |
Use the @samp{-C} or @samp{--directory} command option to change |
9350 |
directory. @xref{Options Summary, ,Summary of Options}. |
9351 |
|
9352 |
@item |
9353 |
Make verbatim variable definitions with @code{define}. |
9354 |
@xref{Defining, ,Defining Variables Verbatim}. |
9355 |
|
9356 |
@item |
9357 |
Declare phony targets with the special target @code{.PHONY}. |
9358 |
|
9359 |
Andrew Hume of AT&T Bell Labs implemented a similar feature with a |
9360 |
different syntax in his @code{mk} program. This seems to be a case of |
9361 |
parallel discovery. @xref{Phony Targets, ,Phony Targets}. |
9362 |
|
9363 |
@item |
9364 |
Manipulate text by calling functions. |
9365 |
@xref{Functions, ,Functions for Transforming Text}. |
9366 |
|
9367 |
@item |
9368 |
Use the @samp{-o} or @samp{--old-file} |
9369 |
option to pretend a file's modification-time is old. |
9370 |
@xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}. |
9371 |
|
9372 |
@item |
9373 |
Conditional execution. |
9374 |
|
9375 |
This feature has been implemented numerous times in various versions |
9376 |
of @code{make}; it seems a natural extension derived from the features |
9377 |
of the C preprocessor and similar macro languages and is not a |
9378 |
revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}. |
9379 |
|
9380 |
@item |
9381 |
Specify a search path for included makefiles. |
9382 |
@xref{Include, ,Including Other Makefiles}. |
9383 |
|
9384 |
@item |
9385 |
Specify extra makefiles to read with an environment variable. |
9386 |
@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. |
9387 |
|
9388 |
@item |
9389 |
Strip leading sequences of @samp{./} from file names, so that |
9390 |
@file{./@var{file}} and @file{@var{file}} are considered to be the |
9391 |
same file.@refill |
9392 |
|
9393 |
@item |
9394 |
Use a special search method for library prerequisites written in the |
9395 |
form @samp{-l@var{name}}. |
9396 |
@xref{Libraries/Search, ,Directory Search for Link Libraries}. |
9397 |
|
9398 |
@item |
9399 |
Allow suffixes for suffix rules |
9400 |
(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any |
9401 |
characters. In other versions of @code{make}, they must begin with |
9402 |
@samp{.} and not contain any @samp{/} characters. |
9403 |
|
9404 |
@item |
9405 |
Keep track of the current level of @code{make} recursion using the |
9406 |
variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}. |
9407 |
|
9408 |
@item |
9409 |
Provide any goals given on the command line in the variable |
9410 |
@code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}. |
9411 |
|
9412 |
@item |
9413 |
Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}. |
9414 |
|
9415 |
@item |
9416 |
Provide selective @code{vpath} search. |
9417 |
@xref{Directory Search, ,Searching Directories for Prerequisites}. |
9418 |
|
9419 |
@item |
9420 |
Provide computed variable references. |
9421 |
@xref{Reference, ,Basics of Variable References}. |
9422 |
|
9423 |
@item |
9424 |
Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}. |
9425 |
System V @code{make} has a very, very limited form of this |
9426 |
functionality in that it will check out SCCS files for makefiles. |
9427 |
|
9428 |
@item |
9429 |
Various new built-in implicit rules. |
9430 |
@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}. |
9431 |
|
9432 |
@item |
9433 |
The built-in variable @samp{MAKE_VERSION} gives the version number of |
9434 |
@code{make}. |
9435 |
@end itemize |
9436 |
|
9437 |
@node Missing, Makefile Conventions, Features, Top |
9438 |
@chapter Incompatibilities and Missing Features |
9439 |
@cindex incompatibilities |
9440 |
@cindex missing features |
9441 |
@cindex features, missing |
9442 |
|
9443 |
The @code{make} programs in various other systems support a few features |
9444 |
that are not implemented in GNU @code{make}. The POSIX.2 standard |
9445 |
(@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not |
9446 |
require any of these features.@refill |
9447 |
|
9448 |
@itemize @bullet |
9449 |
@item |
9450 |
A target of the form @samp{@var{file}((@var{entry}))} stands for a member |
9451 |
of archive file @var{file}. The member is chosen, not by name, but by |
9452 |
being an object file which defines the linker symbol @var{entry}.@refill |
9453 |
|
9454 |
This feature was not put into GNU @code{make} because of the |
9455 |
nonmodularity of putting knowledge into @code{make} of the internal |
9456 |
format of archive file symbol tables. |
9457 |
@xref{Archive Symbols, ,Updating Archive Symbol Directories}. |
9458 |
|
9459 |
@item |
9460 |
Suffixes (used in suffix rules) that end with the character @samp{~} |
9461 |
have a special meaning to System V @code{make}; |
9462 |
they refer to the SCCS file that corresponds |
9463 |
to the file one would get without the @samp{~}. For example, the |
9464 |
suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from |
9465 |
the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole |
9466 |
series of such suffix rules is required. |
9467 |
@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. |
9468 |
|
9469 |
In GNU @code{make}, this entire series of cases is handled by two |
9470 |
pattern rules for extraction from SCCS, in combination with the |
9471 |
general feature of rule chaining. |
9472 |
@xref{Chained Rules, ,Chains of Implicit Rules}. |
9473 |
|
9474 |
@item |
9475 |
In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search |
9476 |
(@pxref{Directory Search, ,Searching Directories for Prerequisites}) have their names changed inside command |
9477 |
strings. We feel it is much cleaner to always use automatic variables |
9478 |
and thus make this feature obsolete.@refill |
9479 |
|
9480 |
@item |
9481 |
In some Unix @code{make}s, the automatic variable @code{$*} appearing in |
9482 |
the prerequisites of a rule has the amazingly strange ``feature'' of |
9483 |
expanding to the full name of the @emph{target of that rule}. We cannot |
9484 |
imagine what went on in the minds of Unix @code{make} developers to do |
9485 |
this; it is utterly inconsistent with the normal definition of @code{$*}. |
9486 |
@vindex * @r{(automatic variable), unsupported bizarre usage} |
9487 |
|
9488 |
@item |
9489 |
In some Unix @code{make}s, implicit rule search |
9490 |
(@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for |
9491 |
@emph{all} targets, not just those without commands. This means you can |
9492 |
do:@refill |
9493 |
|
9494 |
@example |
9495 |
@group |
9496 |
foo.o: |
9497 |
cc -c foo.c |
9498 |
@end group |
9499 |
@end example |
9500 |
|
9501 |
@noindent |
9502 |
and Unix @code{make} will intuit that @file{foo.o} depends on |
9503 |
@file{foo.c}.@refill |
9504 |
|
9505 |
We feel that such usage is broken. The prerequisite properties of |
9506 |
@code{make} are well-defined (for GNU @code{make}, at least), |
9507 |
and doing such a thing simply does not fit the model.@refill |
9508 |
|
9509 |
@item |
9510 |
GNU @code{make} does not include any built-in implicit rules for |
9511 |
compiling or preprocessing EFL programs. If we hear of anyone who is |
9512 |
using EFL, we will gladly add them. |
9513 |
|
9514 |
@item |
9515 |
It appears that in SVR4 @code{make}, a suffix rule can be specified with |
9516 |
no commands, and it is treated as if it had empty commands |
9517 |
(@pxref{Empty Commands}). For example: |
9518 |
|
9519 |
@example |
9520 |
.c.a: |
9521 |
@end example |
9522 |
|
9523 |
@noindent |
9524 |
will override the built-in @file{.c.a} suffix rule. |
9525 |
|
9526 |
We feel that it is cleaner for a rule without commands to always simply |
9527 |
add to the prerequisite list for the target. The above example can be |
9528 |
easily rewritten to get the desired behavior in GNU @code{make}: |
9529 |
|
9530 |
@example |
9531 |
.c.a: ; |
9532 |
@end example |
9533 |
|
9534 |
@item |
9535 |
Some versions of @code{make} invoke the shell with the @samp{-e} flag, |
9536 |
except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a |
9537 |
Program}). The @samp{-e} flag tells the shell to exit as soon as any |
9538 |
program it runs returns a nonzero status. We feel it is cleaner to |
9539 |
write each shell command line to stand on its own and not require this |
9540 |
special treatment. |
9541 |
@end itemize |
9542 |
|
9543 |
@comment The makefile standards are in a separate file that is also |
9544 |
@comment included by standards.texi. |
9545 |
@include make-stds.texi |
9546 |
|
9547 |
@node Quick Reference, Error Messages, Makefile Conventions, Top |
9548 |
@appendix Quick Reference |
9549 |
|
9550 |
This appendix summarizes the directives, text manipulation functions, |
9551 |
and special variables which GNU @code{make} understands. |
9552 |
@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules}, |
9553 |
and @ref{Options Summary, ,Summary of Options}, |
9554 |
for other summaries. |
9555 |
|
9556 |
Here is a summary of the directives GNU @code{make} recognizes: |
9557 |
|
9558 |
@table @code |
9559 |
@item define @var{variable} |
9560 |
@itemx endef |
9561 |
|
9562 |
Define a multi-line, recursively-expanded variable.@* |
9563 |
@xref{Sequences}. |
9564 |
|
9565 |
@item ifdef @var{variable} |
9566 |
@itemx ifndef @var{variable} |
9567 |
@itemx ifeq (@var{a},@var{b}) |
9568 |
@itemx ifeq "@var{a}" "@var{b}" |
9569 |
@itemx ifeq '@var{a}' '@var{b}' |
9570 |
@itemx ifneq (@var{a},@var{b}) |
9571 |
@itemx ifneq "@var{a}" "@var{b}" |
9572 |
@itemx ifneq '@var{a}' '@var{b}' |
9573 |
@itemx else |
9574 |
@itemx endif |
9575 |
|
9576 |
Conditionally evaluate part of the makefile.@* |
9577 |
@xref{Conditionals}. |
9578 |
|
9579 |
@item include @var{file} |
9580 |
@itemx -include @var{file} |
9581 |
@itemx sinclude @var{file} |
9582 |
|
9583 |
Include another makefile.@* |
9584 |
@xref{Include, ,Including Other Makefiles}. |
9585 |
|
9586 |
@item override @var{variable} = @var{value} |
9587 |
@itemx override @var{variable} := @var{value} |
9588 |
@itemx override @var{variable} += @var{value} |
9589 |
@itemx override @var{variable} ?= @var{value} |
9590 |
@itemx override define @var{variable} |
9591 |
@itemx endef |
9592 |
|
9593 |
Define a variable, overriding any previous definition, even one from |
9594 |
the command line.@* |
9595 |
@xref{Override Directive, ,The @code{override} Directive}. |
9596 |
|
9597 |
@item export |
9598 |
|
9599 |
Tell @code{make} to export all variables to child processes by default.@* |
9600 |
@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. |
9601 |
|
9602 |
@item export @var{variable} |
9603 |
@itemx export @var{variable} = @var{value} |
9604 |
@itemx export @var{variable} := @var{value} |
9605 |
@itemx export @var{variable} += @var{value} |
9606 |
@itemx export @var{variable} ?= @var{value} |
9607 |
@itemx unexport @var{variable} |
9608 |
Tell @code{make} whether or not to export a particular variable to child |
9609 |
processes.@* |
9610 |
@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}. |
9611 |
|
9612 |
@item vpath @var{pattern} @var{path} |
9613 |
Specify a search path for files matching a @samp{%} pattern.@* |
9614 |
@xref{Selective Search, , The @code{vpath} Directive}. |
9615 |
|
9616 |
@item vpath @var{pattern} |
9617 |
Remove all search paths previously specified for @var{pattern}. |
9618 |
|
9619 |
@item vpath |
9620 |
Remove all search paths previously specified in any @code{vpath} |
9621 |
directive. |
9622 |
@end table |
9623 |
|
9624 |
Here is a summary of the text manipulation functions (@pxref{Functions}): |
9625 |
|
9626 |
@table @code |
9627 |
@item $(subst @var{from},@var{to},@var{text}) |
9628 |
Replace @var{from} with @var{to} in @var{text}.@* |
9629 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9630 |
|
9631 |
@item $(patsubst @var{pattern},@var{replacement},@var{text}) |
9632 |
Replace words matching @var{pattern} with @var{replacement} in @var{text}.@* |
9633 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9634 |
|
9635 |
@item $(strip @var{string}) |
9636 |
Remove excess whitespace characters from @var{string}.@* |
9637 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9638 |
|
9639 |
@item $(findstring @var{find},@var{text}) |
9640 |
Locate @var{find} in @var{text}.@* |
9641 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9642 |
|
9643 |
@item $(filter @var{pattern}@dots{},@var{text}) |
9644 |
Select words in @var{text} that match one of the @var{pattern} words.@* |
9645 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9646 |
|
9647 |
@item $(filter-out @var{pattern}@dots{},@var{text}) |
9648 |
Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@* |
9649 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9650 |
|
9651 |
@item $(sort @var{list}) |
9652 |
Sort the words in @var{list} lexicographically, removing duplicates.@* |
9653 |
@xref{Text Functions, , Functions for String Substitution and Analysis}. |
9654 |
|
9655 |
@item $(dir @var{names}@dots{}) |
9656 |
Extract the directory part of each file name.@* |
9657 |
@xref{File Name Functions, ,Functions for File Names}. |
9658 |
|
9659 |
@item $(notdir @var{names}@dots{}) |
9660 |
Extract the non-directory part of each file name.@* |
9661 |
@xref{File Name Functions, ,Functions for File Names}. |
9662 |
|
9663 |
@item $(suffix @var{names}@dots{}) |
9664 |
Extract the suffix (the last @samp{.} and following characters) of each file name.@* |
9665 |
@xref{File Name Functions, ,Functions for File Names}. |
9666 |
|
9667 |
@item $(basename @var{names}@dots{}) |
9668 |
Extract the base name (name without suffix) of each file name.@* |
9669 |
@xref{File Name Functions, ,Functions for File Names}. |
9670 |
|
9671 |
@item $(addsuffix @var{suffix},@var{names}@dots{}) |
9672 |
Append @var{suffix} to each word in @var{names}.@* |
9673 |
@xref{File Name Functions, ,Functions for File Names}. |
9674 |
|
9675 |
@item $(addprefix @var{prefix},@var{names}@dots{}) |
9676 |
Prepend @var{prefix} to each word in @var{names}.@* |
9677 |
@xref{File Name Functions, ,Functions for File Names}. |
9678 |
|
9679 |
@item $(join @var{list1},@var{list2}) |
9680 |
Join two parallel lists of words.@* |
9681 |
@xref{File Name Functions, ,Functions for File Names}. |
9682 |
|
9683 |
@item $(word @var{n},@var{text}) |
9684 |
Extract the @var{n}th word (one-origin) of @var{text}.@* |
9685 |
@xref{File Name Functions, ,Functions for File Names}. |
9686 |
|
9687 |
@item $(words @var{text}) |
9688 |
Count the number of words in @var{text}.@* |
9689 |
@xref{File Name Functions, ,Functions for File Names}. |
9690 |
|
9691 |
@item $(wordlist @var{s},@var{e},@var{text}) |
9692 |
Returns the list of words in @var{text} from @var{s} to @var{e}.@* |
9693 |
@xref{File Name Functions, ,Functions for File Names}. |
9694 |
|
9695 |
@item $(firstword @var{names}@dots{}) |
9696 |
Extract the first word of @var{names}.@* |
9697 |
@xref{File Name Functions, ,Functions for File Names}. |
9698 |
|
9699 |
@item $(wildcard @var{pattern}@dots{}) |
9700 |
Find file names matching a shell file name pattern (@emph{not} a |
9701 |
@samp{%} pattern).@* |
9702 |
@xref{Wildcard Function, ,The Function @code{wildcard}}. |
9703 |
|
9704 |
@item $(error @var{text}@dots{}) |
9705 |
|
9706 |
When this function is evaluated, @code{make} generates a fatal error |
9707 |
with the message @var{text}.@* |
9708 |
@xref{Make Control Functions, ,Functions That Control Make}. |
9709 |
|
9710 |
@item $(warning @var{text}@dots{}) |
9711 |
|
9712 |
When this function is evaluated, @code{make} generates a warning with |
9713 |
the message @var{text}.@* |
9714 |
@xref{Make Control Functions, ,Functions That Control Make}. |
9715 |
|
9716 |
@item $(shell @var{command}) |
9717 |
|
9718 |
Execute a shell command and return its output.@* |
9719 |
@xref{Shell Function, , The @code{shell} Function}. |
9720 |
|
9721 |
@item $(origin @var{variable}) |
9722 |
|
9723 |
Return a string describing how the @code{make} variable @var{variable} was |
9724 |
defined.@* |
9725 |
@xref{Origin Function, , The @code{origin} Function}. |
9726 |
|
9727 |
@item $(foreach @var{var},@var{words},@var{text}) |
9728 |
|
9729 |
Evaluate @var{text} with @var{var} bound to each word in @var{words}, |
9730 |
and concatenate the results.@* |
9731 |
@xref{Foreach Function, ,The @code{foreach} Function}. |
9732 |
|
9733 |
@item $(call @var{var},@var{param},@dots{}) |
9734 |
|
9735 |
Evaluate the variable @var{var} replacing any references to @code{$(1)}, |
9736 |
@code{$(2)} with the first, second, etc. @var{param} values.@* |
9737 |
@xref{Call Function, ,The @code{call} Function}. |
9738 |
|
9739 |
@item $(eval @var{text}) |
9740 |
|
9741 |
Evaluate @var{text} then read the results as makefile commands. |
9742 |
Expands to the empty string.@* |
9743 |
@xref{Eval Function, ,The @code{eval} Function}. |
9744 |
|
9745 |
@item $(value @var{var}) |
9746 |
|
9747 |
Evaluates to the contents of the variable @var{var}, with no expansion |
9748 |
performed on it.@* |
9749 |
@xref{Value Function, ,The @code{value} Function}. |
9750 |
@end table |
9751 |
|
9752 |
Here is a summary of the automatic variables. |
9753 |
@xref{Automatic Variables}, |
9754 |
for full information. |
9755 |
|
9756 |
@table @code |
9757 |
@item $@@ |
9758 |
The file name of the target. |
9759 |
|
9760 |
@item $% |
9761 |
The target member name, when the target is an archive member. |
9762 |
|
9763 |
@item $< |
9764 |
The name of the first prerequisite. |
9765 |
|
9766 |
@item $? |
9767 |
The names of all the prerequisites that are |
9768 |
newer than the target, with spaces between them. |
9769 |
For prerequisites which are archive members, only |
9770 |
the member named is used (@pxref{Archives}). |
9771 |
|
9772 |
@item $^ |
9773 |
@itemx $+ |
9774 |
The names of all the prerequisites, with spaces between them. For |
9775 |
prerequisites which are archive members, only the member named is used |
9776 |
(@pxref{Archives}). The value of @code{$^} omits duplicate |
9777 |
prerequisites, while @code{$+} retains them and preserves their order. |
9778 |
|
9779 |
@item $* |
9780 |
The stem with which an implicit rule matches |
9781 |
(@pxref{Pattern Match, ,How Patterns Match}). |
9782 |
|
9783 |
@item $(@@D) |
9784 |
@itemx $(@@F) |
9785 |
The directory part and the file-within-directory part of @code{$@@}. |
9786 |
|
9787 |
@item $(*D) |
9788 |
@itemx $(*F) |
9789 |
The directory part and the file-within-directory part of @code{$*}. |
9790 |
|
9791 |
@item $(%D) |
9792 |
@itemx $(%F) |
9793 |
The directory part and the file-within-directory part of @code{$%}. |
9794 |
|
9795 |
@item $(<D) |
9796 |
@itemx $(<F) |
9797 |
The directory part and the file-within-directory part of @code{$<}. |
9798 |
|
9799 |
@item $(^D) |
9800 |
@itemx $(^F) |
9801 |
The directory part and the file-within-directory part of @code{$^}. |
9802 |
|
9803 |
@item $(+D) |
9804 |
@itemx $(+F) |
9805 |
The directory part and the file-within-directory part of @code{$+}. |
9806 |
|
9807 |
@item $(?D) |
9808 |
@itemx $(?F) |
9809 |
The directory part and the file-within-directory part of @code{$?}. |
9810 |
@end table |
9811 |
|
9812 |
These variables are used specially by GNU @code{make}: |
9813 |
|
9814 |
@table @code |
9815 |
@item MAKEFILES |
9816 |
|
9817 |
Makefiles to be read on every invocation of @code{make}.@* |
9818 |
@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. |
9819 |
|
9820 |
@item VPATH |
9821 |
|
9822 |
Directory search path for files not found in the current directory.@* |
9823 |
@xref{General Search, , @code{VPATH} Search Path for All Prerequisites}. |
9824 |
|
9825 |
@item SHELL |
9826 |
|
9827 |
The name of the system default command interpreter, usually @file{/bin/sh}. |
9828 |
You can set @code{SHELL} in the makefile to change the shell used to run |
9829 |
commands. @xref{Execution, ,Command Execution}. |
9830 |
|
9831 |
@item MAKESHELL |
9832 |
|
9833 |
On MS-DOS only, the name of the command interpreter that is to be used |
9834 |
by @code{make}. This value takes precedence over the value of |
9835 |
@code{SHELL}. @xref{Execution, ,MAKESHELL variable}. |
9836 |
|
9837 |
@item MAKE |
9838 |
|
9839 |
The name with which @code{make} was invoked. |
9840 |
Using this variable in commands has special meaning. |
9841 |
@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}. |
9842 |
|
9843 |
@item MAKELEVEL |
9844 |
|
9845 |
The number of levels of recursion (sub-@code{make}s).@* |
9846 |
@xref{Variables/Recursion}. |
9847 |
|
9848 |
@item MAKEFLAGS |
9849 |
|
9850 |
The flags given to @code{make}. You can set this in the environment or |
9851 |
a makefile to set flags.@* |
9852 |
@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. |
9853 |
|
9854 |
It is @emph{never} appropriate to use @code{MAKEFLAGS} directly on a |
9855 |
command line: its contents may not be quoted correctly for use in the |
9856 |
shell. Always allow recursive @code{make}'s to obtain these values |
9857 |
through the environment from its parent. |
9858 |
|
9859 |
@item MAKECMDGOALS |
9860 |
|
9861 |
The targets given to @code{make} on the command line. Setting this |
9862 |
variable has no effect on the operation of @code{make}.@* |
9863 |
@xref{Goals, ,Arguments to Specify the Goals}. |
9864 |
|
9865 |
@item CURDIR |
9866 |
|
9867 |
Set to the pathname of the current working directory (after all |
9868 |
@code{-C} options are processed, if any). Setting this variable has no |
9869 |
effect on the operation of @code{make}.@* |
9870 |
@xref{Recursion, ,Recursive Use of @code{make}}. |
9871 |
|
9872 |
@item SUFFIXES |
9873 |
|
9874 |
The default list of suffixes before @code{make} reads any makefiles. |
9875 |
|
9876 |
@item .LIBPATTERNS |
9877 |
Defines the naming of the libraries @code{make} searches for, and their |
9878 |
order.@* |
9879 |
@xref{Libraries/Search, ,Directory Search for Link Libraries}. |
9880 |
@end table |
9881 |
|
9882 |
@node Error Messages, Complex Makefile, Quick Reference, Top |
9883 |
@comment node-name, next, previous, up |
9884 |
@appendix Errors Generated by Make |
9885 |
|
9886 |
Here is a list of the more common errors you might see generated by |
9887 |
@code{make}, and some information about what they mean and how to fix |
9888 |
them. |
9889 |
|
9890 |
Sometimes @code{make} errors are not fatal, especially in the presence |
9891 |
of a @code{-} prefix on a command script line, or the @code{-k} command |
9892 |
line option. Errors that are fatal are prefixed with the string |
9893 |
@code{***}. |
9894 |
|
9895 |
Error messages are all either prefixed with the name of the program |
9896 |
(usually @samp{make}), or, if the error is found in a makefile, the name |
9897 |
of the file and linenumber containing the problem. |
9898 |
|
9899 |
In the table below, these common prefixes are left off. |
9900 |
|
9901 |
@table @samp |
9902 |
|
9903 |
@item [@var{foo}] Error @var{NN} |
9904 |
@itemx [@var{foo}] @var{signal description} |
9905 |
These errors are not really @code{make} errors at all. They mean that a |
9906 |
program that @code{make} invoked as part of a command script returned a |
9907 |
non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets |
9908 |
as failure, or it exited in some other abnormal fashion (with a |
9909 |
signal of some type). @xref{Errors, ,Errors in Commands}. |
9910 |
|
9911 |
If no @code{***} is attached to the message, then the subprocess failed |
9912 |
but the rule in the makefile was prefixed with the @code{-} special |
9913 |
character, so @code{make} ignored the error. |
9914 |
|
9915 |
@item missing separator. Stop. |
9916 |
@itemx missing separator (did you mean TAB instead of 8 spaces?). Stop. |
9917 |
This means that @code{make} could not understand much of anything about |
9918 |
the command line it just read. GNU @code{make} looks for various kinds |
9919 |
of separators (@code{:}, @code{=}, TAB characters, etc.) to help it |
9920 |
decide what kind of commandline it's seeing. This means it couldn't |
9921 |
find a valid one. |
9922 |
|
9923 |
One of the most common reasons for this message is that you (or perhaps |
9924 |
your oh-so-helpful editor, as is the case with many MS-Windows editors) |
9925 |
have attempted to indent your command scripts with spaces instead of a |
9926 |
TAB character. In this case, @code{make} will use the second form of |
9927 |
the error above. Remember that every line in the command script must |
9928 |
begin with a TAB character. Eight spaces do not count. @xref{Rule |
9929 |
Syntax}. |
9930 |
|
9931 |
@item commands commence before first target. Stop. |
9932 |
@itemx missing rule before commands. Stop. |
9933 |
This means the first thing in the makefile seems to be part of a command |
9934 |
script: it begins with a TAB character and doesn't appear to be a legal |
9935 |
@code{make} command (such as a variable assignment). Command scripts |
9936 |
must always be associated with a target. |
9937 |
|
9938 |
The second form is generated if the line has a semicolon as the first |
9939 |
non-whitespace character; @code{make} interprets this to mean you left |
9940 |
out the "target: prerequisite" section of a rule. @xref{Rule Syntax}. |
9941 |
|
9942 |
@item No rule to make target `@var{xxx}'. |
9943 |
@itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'. |
9944 |
This means that @code{make} decided it needed to build a target, but |
9945 |
then couldn't find any instructions in the makefile on how to do that, |
9946 |
either explicit or implicit (including in the default rules database). |
9947 |
|
9948 |
If you want that file to be built, you will need to add a rule to your |
9949 |
makefile describing how that target can be built. Other possible |
9950 |
sources of this problem are typos in the makefile (if that filename is |
9951 |
wrong) or a corrupted source tree (if that file is not supposed to be |
9952 |
built, but rather only a prerequisite). |
9953 |
|
9954 |
@item No targets specified and no makefile found. Stop. |
9955 |
@itemx No targets. Stop. |
9956 |
The former means that you didn't provide any targets to be built on the |
9957 |
command line, and @code{make} couldn't find any makefiles to read in. |
9958 |
The latter means that some makefile was found, but it didn't contain any |
9959 |
default target and none was given on the command line. GNU @code{make} |
9960 |
has nothing to do in these situations. |
9961 |
@xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill |
9962 |
|
9963 |
@item Makefile `@var{xxx}' was not found. |
9964 |
@itemx Included makefile `@var{xxx}' was not found. |
9965 |
A makefile specified on the command line (first form) or included |
9966 |
(second form) was not found. |
9967 |
|
9968 |
@item warning: overriding commands for target `@var{xxx}' |
9969 |
@itemx warning: ignoring old commands for target `@var{xxx}' |
9970 |
GNU @code{make} allows commands to be specified only once per target |
9971 |
(except for double-colon rules). If you give commands for a target |
9972 |
which already has been defined to have commands, this warning is issued |
9973 |
and the second set of commands will overwrite the first set. |
9974 |
@xref{Multiple Rules, ,Multiple Rules for One Target}. |
9975 |
|
9976 |
@item Circular @var{xxx} <- @var{yyy} dependency dropped. |
9977 |
This means that @code{make} detected a loop in the dependency graph: |
9978 |
after tracing the prerequisite @var{yyy} of target @var{xxx}, and its |
9979 |
prerequisites, etc., one of them depended on @var{xxx} again. |
9980 |
|
9981 |
@item Recursive variable `@var{xxx}' references itself (eventually). Stop. |
9982 |
This means you've defined a normal (recursive) @code{make} variable |
9983 |
@var{xxx} that, when it's expanded, will refer to itself (@var{xxx}). |
9984 |
This is not allowed; either use simply-expanded variables (@code{:=}) or |
9985 |
use the append operator (@code{+=}). @xref{Using Variables, ,How to Use |
9986 |
Variables}. |
9987 |
|
9988 |
@item Unterminated variable reference. Stop. |
9989 |
This means you forgot to provide the proper closing parenthesis |
9990 |
or brace in your variable or function reference. |
9991 |
|
9992 |
@item insufficient arguments to function `@var{xxx}'. Stop. |
9993 |
This means you haven't provided the requisite number of arguments for |
9994 |
this function. See the documentation of the function for a description |
9995 |
of its arguments. @xref{Functions, ,Functions for Transforming Text}. |
9996 |
|
9997 |
@item missing target pattern. Stop. |
9998 |
@itemx multiple target patterns. Stop. |
9999 |
@itemx target pattern contains no `%'. Stop. |
10000 |
@itemx mixed implicit and static pattern rules. Stop. |
10001 |
These are generated for malformed static pattern rules. The first means |
10002 |
there's no pattern in the target section of the rule; the second means |
10003 |
there are multiple patterns in the target section; the third means |
10004 |
the target doesn't contain a pattern character (@code{%}); and the |
10005 |
fourth means that all three parts of the static pattern rule contain |
10006 |
pattern characters (@code{%})--only the first two parts should. |
10007 |
@xref{Static Usage, ,Syntax of Static Pattern Rules}. |
10008 |
|
10009 |
@item warning: -jN forced in submake: disabling jobserver mode. |
10010 |
This warning and the next are generated if @code{make} detects error |
10011 |
conditions related to parallel processing on systems where |
10012 |
sub-@code{make}s can communicate (@pxref{Options/Recursion, |
10013 |
,Communicating Options to a Sub-@code{make}}). This warning is |
10014 |
generated if a recursive invocation of a @code{make} process is forced |
10015 |
to have @samp{-j@var{N}} in its argument list (where @var{N} is greater |
10016 |
than one). This could happen, for example, if you set the @code{MAKE} |
10017 |
environment variable to @samp{make -j2}. In this case, the |
10018 |
sub-@code{make} doesn't communicate with other @code{make} processes and |
10019 |
will simply pretend it has two jobs of its own. |
10020 |
|
10021 |
@item warning: jobserver unavailable: using -j1. Add `+' to parent make rule. |
10022 |
In order for @code{make} processes to communicate, the parent will pass |
10023 |
information to the child. Since this could result in problems if the |
10024 |
child process isn't actually a @code{make}, the parent will only do this |
10025 |
if it thinks the child is a @code{make}. The parent uses the normal |
10026 |
algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE} |
10027 |
Variable Works}). If the makefile is constructed such that the parent |
10028 |
doesn't know the child is a @code{make} process, then the child will |
10029 |
receive only part of the information necessary. In this case, the child |
10030 |
will generate this warning message and proceed with its build in a |
10031 |
sequential manner. |
10032 |
|
10033 |
@end table |
10034 |
|
10035 |
@node Complex Makefile, GNU Free Documentation License, Error Messages, Top |
10036 |
@appendix Complex Makefile Example |
10037 |
|
10038 |
Here is the makefile for the GNU @code{tar} program. This is a |
10039 |
moderately complex makefile. |
10040 |
|
10041 |
Because it is the first target, the default goal is @samp{all}. An |
10042 |
interesting feature of this makefile is that @file{testpad.h} is a |
10043 |
source file automatically created by the @code{testpad} program, |
10044 |
itself compiled from @file{testpad.c}. |
10045 |
|
10046 |
If you type @samp{make} or @samp{make all}, then @code{make} creates |
10047 |
the @file{tar} executable, the @file{rmt} daemon that provides |
10048 |
remote tape access, and the @file{tar.info} Info file. |
10049 |
|
10050 |
If you type @samp{make install}, then @code{make} not only creates |
10051 |
@file{tar}, @file{rmt}, and @file{tar.info}, but also installs |
10052 |
them. |
10053 |
|
10054 |
If you type @samp{make clean}, then @code{make} removes the @samp{.o} |
10055 |
files, and the @file{tar}, @file{rmt}, @file{testpad}, |
10056 |
@file{testpad.h}, and @file{core} files. |
10057 |
|
10058 |
If you type @samp{make distclean}, then @code{make} not only removes |
10059 |
the same files as does @samp{make clean} but also the |
10060 |
@file{TAGS}, @file{Makefile}, and @file{config.status} files. |
10061 |
(Although it is not evident, this makefile (and |
10062 |
@file{config.status}) is generated by the user with the |
10063 |
@code{configure} program, which is provided in the @code{tar} |
10064 |
distribution, but is not shown here.) |
10065 |
|
10066 |
If you type @samp{make realclean}, then @code{make} removes the same |
10067 |
files as does @samp{make distclean} and also removes the Info files |
10068 |
generated from @file{tar.texinfo}. |
10069 |
|
10070 |
In addition, there are targets @code{shar} and @code{dist} that create |
10071 |
distribution kits. |
10072 |
|
10073 |
@example |
10074 |
@group |
10075 |
# Generated automatically from Makefile.in by configure. |
10076 |
# Un*x Makefile for GNU tar program. |
10077 |
# Copyright (C) 1991 Free Software Foundation, Inc. |
10078 |
@end group |
10079 |
|
10080 |
@group |
10081 |
# This program is free software; you can redistribute |
10082 |
# it and/or modify it under the terms of the GNU |
10083 |
# General Public License @dots{} |
10084 |
@dots{} |
10085 |
@dots{} |
10086 |
@end group |
10087 |
|
10088 |
SHELL = /bin/sh |
10089 |
|
10090 |
#### Start of system configuration section. #### |
10091 |
|
10092 |
srcdir = . |
10093 |
|
10094 |
@group |
10095 |
# If you use gcc, you should either run the |
10096 |
# fixincludes script that comes with it or else use |
10097 |
# gcc with the -traditional option. Otherwise ioctl |
10098 |
# calls will be compiled incorrectly on some systems. |
10099 |
CC = gcc -O |
10100 |
YACC = bison -y |
10101 |
INSTALL = /usr/local/bin/install -c |
10102 |
INSTALLDATA = /usr/local/bin/install -c -m 644 |
10103 |
@end group |
10104 |
|
10105 |
# Things you might add to DEFS: |
10106 |
# -DSTDC_HEADERS If you have ANSI C headers and |
10107 |
# libraries. |
10108 |
# -DPOSIX If you have POSIX.1 headers and |
10109 |
# libraries. |
10110 |
# -DBSD42 If you have sys/dir.h (unless |
10111 |
# you use -DPOSIX), sys/file.h, |
10112 |
# and st_blocks in `struct stat'. |
10113 |
# -DUSG If you have System V/ANSI C |
10114 |
# string and memory functions |
10115 |
# and headers, sys/sysmacros.h, |
10116 |
# fcntl.h, getcwd, no valloc, |
10117 |
# and ndir.h (unless |
10118 |
# you use -DDIRENT). |
10119 |
# -DNO_MEMORY_H If USG or STDC_HEADERS but do not |
10120 |
# include memory.h. |
10121 |
# -DDIRENT If USG and you have dirent.h |
10122 |
# instead of ndir.h. |
10123 |
# -DSIGTYPE=int If your signal handlers |
10124 |
# return int, not void. |
10125 |
# -DNO_MTIO If you lack sys/mtio.h |
10126 |
# (magtape ioctls). |
10127 |
# -DNO_REMOTE If you do not have a remote shell |
10128 |
# or rexec. |
10129 |
# -DUSE_REXEC To use rexec for remote tape |
10130 |
# operations instead of |
10131 |
# forking rsh or remsh. |
10132 |
# -DVPRINTF_MISSING If you lack vprintf function |
10133 |
# (but have _doprnt). |
10134 |
# -DDOPRNT_MISSING If you lack _doprnt function. |
10135 |
# Also need to define |
10136 |
# -DVPRINTF_MISSING. |
10137 |
# -DFTIME_MISSING If you lack ftime system call. |
10138 |
# -DSTRSTR_MISSING If you lack strstr function. |
10139 |
# -DVALLOC_MISSING If you lack valloc function. |
10140 |
# -DMKDIR_MISSING If you lack mkdir and |
10141 |
# rmdir system calls. |
10142 |
# -DRENAME_MISSING If you lack rename system call. |
10143 |
# -DFTRUNCATE_MISSING If you lack ftruncate |
10144 |
# system call. |
10145 |
# -DV7 On Version 7 Unix (not |
10146 |
# tested in a long time). |
10147 |
# -DEMUL_OPEN3 If you lack a 3-argument version |
10148 |
# of open, and want to emulate it |
10149 |
# with system calls you do have. |
10150 |
# -DNO_OPEN3 If you lack the 3-argument open |
10151 |
# and want to disable the tar -k |
10152 |
# option instead of emulating open. |
10153 |
# -DXENIX If you have sys/inode.h |
10154 |
# and need it 94 to be included. |
10155 |
|
10156 |
DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \ |
10157 |
-DVPRINTF_MISSING -DBSD42 |
10158 |
# Set this to rtapelib.o unless you defined NO_REMOTE, |
10159 |
# in which case make it empty. |
10160 |
RTAPELIB = rtapelib.o |
10161 |
LIBS = |
10162 |
DEF_AR_FILE = /dev/rmt8 |
10163 |
DEFBLOCKING = 20 |
10164 |
|
10165 |
@group |
10166 |
CDEBUG = -g |
10167 |
CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \ |
10168 |
-DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \ |
10169 |
-DDEFBLOCKING=$(DEFBLOCKING) |
10170 |
LDFLAGS = -g |
10171 |
@end group |
10172 |
|
10173 |
@group |
10174 |
prefix = /usr/local |
10175 |
# Prefix for each installed program, |
10176 |
# normally empty or `g'. |
10177 |
binprefix = |
10178 |
|
10179 |
# The directory to install tar in. |
10180 |
bindir = $(prefix)/bin |
10181 |
|
10182 |
# The directory to install the info files in. |
10183 |
infodir = $(prefix)/info |
10184 |
@end group |
10185 |
|
10186 |
#### End of system configuration section. #### |
10187 |
|
10188 |
SRC1 = tar.c create.c extract.c buffer.c \ |
10189 |
getoldopt.c update.c gnu.c mangle.c |
10190 |
SRC2 = version.c list.c names.c diffarch.c \ |
10191 |
port.c wildmat.c getopt.c |
10192 |
SRC3 = getopt1.c regex.c getdate.y |
10193 |
SRCS = $(SRC1) $(SRC2) $(SRC3) |
10194 |
OBJ1 = tar.o create.o extract.o buffer.o \ |
10195 |
getoldopt.o update.o gnu.o mangle.o |
10196 |
OBJ2 = version.o list.o names.o diffarch.o \ |
10197 |
port.o wildmat.o getopt.o |
10198 |
OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB) |
10199 |
OBJS = $(OBJ1) $(OBJ2) $(OBJ3) |
10200 |
@group |
10201 |
AUX = README COPYING ChangeLog Makefile.in \ |
10202 |
makefile.pc configure configure.in \ |
10203 |
tar.texinfo tar.info* texinfo.tex \ |
10204 |
tar.h port.h open3.h getopt.h regex.h \ |
10205 |
rmt.h rmt.c rtapelib.c alloca.c \ |
10206 |
msd_dir.h msd_dir.c tcexparg.c \ |
10207 |
level-0 level-1 backup-specs testpad.c |
10208 |
@end group |
10209 |
|
10210 |
all: tar rmt tar.info |
10211 |
|
10212 |
@group |
10213 |
tar: $(OBJS) |
10214 |
$(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) |
10215 |
@end group |
10216 |
|
10217 |
@group |
10218 |
rmt: rmt.c |
10219 |
$(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c |
10220 |
@end group |
10221 |
|
10222 |
@group |
10223 |
tar.info: tar.texinfo |
10224 |
makeinfo tar.texinfo |
10225 |
@end group |
10226 |
|
10227 |
@group |
10228 |
install: all |
10229 |
$(INSTALL) tar $(bindir)/$(binprefix)tar |
10230 |
-test ! -f rmt || $(INSTALL) rmt /etc/rmt |
10231 |
$(INSTALLDATA) $(srcdir)/tar.info* $(infodir) |
10232 |
@end group |
10233 |
|
10234 |
@group |
10235 |
$(OBJS): tar.h port.h testpad.h |
10236 |
regex.o buffer.o tar.o: regex.h |
10237 |
# getdate.y has 8 shift/reduce conflicts. |
10238 |
@end group |
10239 |
|
10240 |
@group |
10241 |
testpad.h: testpad |
10242 |
./testpad |
10243 |
@end group |
10244 |
|
10245 |
@group |
10246 |
testpad: testpad.o |
10247 |
$(CC) -o $@@ testpad.o |
10248 |
@end group |
10249 |
|
10250 |
@group |
10251 |
TAGS: $(SRCS) |
10252 |
etags $(SRCS) |
10253 |
@end group |
10254 |
|
10255 |
@group |
10256 |
clean: |
10257 |
rm -f *.o tar rmt testpad testpad.h core |
10258 |
@end group |
10259 |
|
10260 |
@group |
10261 |
distclean: clean |
10262 |
rm -f TAGS Makefile config.status |
10263 |
@end group |
10264 |
|
10265 |
@group |
10266 |
realclean: distclean |
10267 |
rm -f tar.info* |
10268 |
@end group |
10269 |
|
10270 |
@group |
10271 |
shar: $(SRCS) $(AUX) |
10272 |
shar $(SRCS) $(AUX) | compress \ |
10273 |
> tar-`sed -e '/version_string/!d' \ |
10274 |
-e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ |
10275 |
-e q |
10276 |
version.c`.shar.Z |
10277 |
@end group |
10278 |
|
10279 |
@group |
10280 |
dist: $(SRCS) $(AUX) |
10281 |
echo tar-`sed \ |
10282 |
-e '/version_string/!d' \ |
10283 |
-e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ |
10284 |
-e q |
10285 |
version.c` > .fname |
10286 |
-rm -rf `cat .fname` |
10287 |
mkdir `cat .fname` |
10288 |
ln $(SRCS) $(AUX) `cat .fname` |
10289 |
tar chZf `cat .fname`.tar.Z `cat .fname` |
10290 |
-rm -rf `cat .fname` .fname |
10291 |
@end group |
10292 |
|
10293 |
@group |
10294 |
tar.zoo: $(SRCS) $(AUX) |
10295 |
-rm -rf tmp.dir |
10296 |
-mkdir tmp.dir |
10297 |
-rm tar.zoo |
10298 |
for X in $(SRCS) $(AUX) ; do \ |
10299 |
echo $$X ; \ |
10300 |
sed 's/$$/^M/' $$X \ |
10301 |
> tmp.dir/$$X ; done |
10302 |
cd tmp.dir ; zoo aM ../tar.zoo * |
10303 |
-rm -rf tmp.dir |
10304 |
@end group |
10305 |
@end example |
10306 |
|
10307 |
@raisesections |
10308 |
@include fdl.texi |
10309 |
@lowersections |
10310 |
|
10311 |
@node Concept Index, Name Index, GNU Free Documentation License, Top |
10312 |
@unnumbered Index of Concepts |
10313 |
|
10314 |
@printindex cp |
10315 |
|
10316 |
@node Name Index, , Concept Index, Top |
10317 |
@unnumbered Index of Functions, Variables, & Directives |
10318 |
|
10319 |
@printindex fn |
10320 |
|
10321 |
@summarycontents |
10322 |
@contents |
10323 |
@bye |